OVERVIEW

Introduction

RECALL is a declarative web interface language with COBOL-inspired syntax. It compiles .rcl source files to self-contained, zero-dependency HTML. Every page embeds its source in an HTML comment — view source, see origin.

NOTE

RECALL is not a framework, runtime, or templating engine. It is a compiler. Source in. HTML out.

OVERVIEW

Quick Start

bash 
npm install -g @semanticintent/recall-compiler
RECALL 
IDENTIFICATION DIVISION.
   PROGRAM-ID.   MY-SITE.
   PAGE-TITLE.   Hello World.
   AUTHOR.       Your Name.
   DATE-WRITTEN. 2026-04-06.

DATA DIVISION.
   WORKING-STORAGE SECTION.
      01 HERO-HEAD PIC X(20) VALUE Hello World.

PROCEDURE DIVISION.
   RENDER.
      DISPLAY HEADING-1 HERO-HEAD.
   STOP RUN.
TIP

No config file. No build pipeline. Open the .html output directly in any browser.

LANGUAGE

Divisions

Every RECALL program has exactly five divisions, declared in order. Borrowed directly from COBOL — explicit, readable, non-negotiable. COMPONENT DIVISION is optional; all others are required.

DIVISIONREQUIREDDESCRIPTION
IDENTIFICATION DIVISIONREQUIREDProgram metadata — PROGRAM-ID, PAGE-TITLE, AUTHOR, DATE-WRITTEN, DESCRIPTION, FAVICON.
ENVIRONMENT DIVISIONREQUIREDTheme and config — VIEWPORT, COLOR-MODE, PALETTE, FONT, STYLE-BLOCK. Supports COPY FROM for theme inheritance.
DATA DIVISIONREQUIREDFields and groups — WORKING-STORAGE for scalars, ITEMS for groups. COPY FROM inlines shared fields. LOAD FROM ingests JSON or CSV at compile time.
COMPONENT DIVISIONOPTIONALComponent definitions — DEFINE, ACCEPTS, END DEFINE. COPY FROM imports .rcpy libraries. WITH DATA binds fields at invocation.
PROCEDURE DIVISIONREQUIREDRender logic — named sections with DISPLAY statements. Must end with STOP RUN.
WARNING

Divisions must appear in order: IDENTIFICATION, ENVIRONMENT, DATA, COMPONENT, PROCEDURE. Omitting COMPONENT DIVISION is valid. Omitting any other aborts compilation.

LANGUAGE

PIC Types

Every DATA DIVISION field carries a PIC type. The compiler validates every DISPLAY statement against the element's type contract — wrong type, wrong format, no output. Run recall schema to query the live registry.

DECLARATIONKINDUSAGE
PIC X(n)stringText up to n characters. Used by HEADING-1, PARAGRAPH, LABEL, BUTTON, and most elements.
PIC XstringSingle character. Shorthand for PIC X(1). Also used with VALUE BLOCK for auto-sized strings.
PIC 9(n)numericInteger up to n digits. Use LABEL or STAT-GRID for display. Non-numeric VALUE triggers RCL-012.
PIC 9boolean-numeric0 or 1. Boolean flag. Single-digit numeric.
PIC DATEdateISO 8601 date string (YYYY-MM-DD). Malformed values trigger RCL-009.
PIC URLurlMust begin with http, https, or /. Malformed values trigger RCL-010.
PIC PCTpercentInteger 0-100. Out-of-range values trigger RCL-011.
GROUPgroupNamed group declared in ITEMS SECTION. Referenced by USING clause in TABLE, STAT-GRID, CARD-LIST, NAVIGATION.
RECALL 
DATA DIVISION.
   WORKING-STORAGE SECTION.
      01 PAGE-TITLE  PIC X(60)  VALUE My Site.
      01 VISIT-COUNT PIC 9(6)   VALUE 142398.
      01 PUBLISHED   PIC DATE   VALUE 2026-04-06.
      01 LOGO-SRC    PIC URL    VALUE https://example.com/logo.svg.
      01 ACCURACY    PIC PCT    VALUE 94.
TIP

Run `recall schema --json` to see the live element type contracts — which PIC types each element accepts.

LANGUAGE

Elements

RECALL provides 20 built-in elements invoked with DISPLAY. Run recall schema to query the live element registry from the installed compiler.

ELEMENTARGUMENTSDESCRIPTION
HEADING-1/2/3value WITH STYLE MONO/SANSHeading at level 1, 2 or 3. Expects PIC X.
PARAGRAPHvalue WITH COLOR MUTED/TEXT/ACCENTBody paragraph. Expects PIC X. Accepts `citations YES` for inline footnote links.
LABELvalueUppercase eyebrow label. Use before headings to add section context. Accepts PIC X or PIC 9.
CODE-BLOCKvalue WITH LANGUAGE bash/cobol/jsonMonospace code block with optional language hint for syntax display.
BUTTONvalue ON-CLICK GOTO hrefLink styled as a button. WITH STYLE PRIMARY, GHOST, or OUTLINE.
LINKvalue WITH HREF urlInline anchor. WITH TARGET BLANK opens in a new tab.
IMAGEWITH SRC url WITH ALT textImage element. WITH SIZE FULL or HALF sets display width. SRC must be PIC URL.
DIVIDERWITH STYLE DASHEDHorizontal rule. WITH SPACING SMALL or LARGE controls vertical margin.
BANNERvalueFull-width accent-coloured banner bar.
CALLOUTvalue WITH TYPE NOTE/TIP/WARNING/DANGERHighlighted callout block with typed accent colour. Expects PIC X.
INPUTvalue WITH TYPE text/email/searchText input field. The value sets the placeholder label.
CARD-LISTUSING group WITH COLUMNS 2/3Card grid from an ITEMS group. WITH HOVER-LIFT YES adds card lift on hover.
TABLEUSING group WITH COLUMNS col1, col2Data table from an ITEMS group. COLUMNS sets header labels; cells map to level-10 fields by position.
STAT-GRIDUSING group WITH COLUMNS 3/4/6Metric display grid. Detects -VALUE and -LABEL field pairs per row automatically.
TIMELINEUSING groupChronological timeline rendered from an ITEMS group.
TABSUSING groupInteractive tabbed panels. Each item in the group becomes one tab with a label and content.
NAVIGATIONUSING group WITH LOGO textTop navigation bar with logo and links. WITH STICKY YES fixes it while scrolling.
SIDEBAR-NAVUSING group WITH LOGO textSidebar navigation panel. Only valid inside LAYOUT SIDEBAR. WITH STICKY YES keeps it fixed.
FOOTERWITH TEXT value WITH ALIGN CENTERPage footer with centred or left-aligned text.
SECTIONID id WITH LAYOUT type WITH PADDING sizeLayout container. LAYOUT: CENTERED, STACK, GRID, SIDEBAR, SPLIT. Supports nesting. Closed with STOP SECTION.
NOTE

SECTION elements close with STOP SECTION. All other elements are single-line DISPLAY statements.

LANGUAGE

Copybooks

Copybooks use the .rcpy extension — a reference to COBOL's .cpy format. They are never compiled standalone; only COPY FROM'd into .rcl programs at compile time. recall build skips .rcpy files automatically.

RECALL 
COPY FROM components/nav.rcpy.
NOTE

A copybook can contain any RECALL division content. COPY FROM is resolved at compile time — the result is one self-contained HTML file.

TIP

Use `recall check --inspect` to see what DATA symbols are generated after all COPY FROM and LOAD FROM statements are resolved.

LANGUAGE

Components

Components are reusable layout fragments defined in COMPONENT DIVISION. Each declares an ACCEPTS list — the DATA DIVISION field names it expects. Callers bind fields with WITH DATA at invocation.

Defining a component

RECALL 
COMPONENT DIVISION.
   DEFINE PAGE-HERO.
      ACCEPTS HERO-TITLE REQUIRED, HERO-SUBTITLE, CTA-LABEL.
      DISPLAY SECTION WITH LAYOUT STACK WITH PADDING LARGE.
         DISPLAY HEADING-1 HERO-TITLE.
         DISPLAY PARAGRAPH HERO-SUBTITLE.
         DISPLAY BUTTON CTA-LABEL WITH STYLE PRIMARY.
      STOP SECTION.
   END DEFINE.

Invoking with WITH DATA

RECALL 
DATA DIVISION.
   WORKING-STORAGE SECTION.
      01 SITE-TITLE PIC X(60) VALUE Launch Day.
      01 SITE-BODY  PIC X(200) VALUE Ready when you are.
      01 BTN-LABEL  PIC X(20) VALUE Get Started.

PROCEDURE DIVISION.
   RENDER.
      DISPLAY PAGE-HERO WITH DATA HERO-TITLE, HERO-SUBTITLE, CTA-LABEL
         WITH HERO-TITLE SITE-TITLE
         WITH HERO-SUBTITLE SITE-BODY
         WITH CTA-LABEL BTN-LABEL.
   STOP RUN.

REQUIRED parameters

RECALL 
ACCEPTS PAGE-TITLE REQUIRED, SUBTITLE, BADGE.
* RCL-017 fires when PAGE-TITLE is not provided at the call site.
* SUBTITLE and BADGE are optional — no error if omitted.
WARNING

REQUIRED on an ACCEPTS parameter makes it a compile-time contract. Calling the component without that parameter fires RCL-017 — no output is written.

COMMENT clause

RECALL 
01 FETCH-SCORE PIC X(10) VALUE 2978
   COMMENT CAL fetch score — higher is better.

01 REVIEW-DATE PIC DATE VALUE 2027-09-30
   COMMENT Scheduled review window for prognostic case.
NOTE

COMMENT clauses surface in `recall check --inspect` output and `--format json` under fieldIntent. They have no effect on compiled HTML — intent only.

LANGUAGE

Value Language

Four features modernise the data layer. VALUE BLOCK supports multi-line prose strings. VALUE HEREDOC preserves raw content — code examples, RECALL syntax, embedded quotes. RECORD types define reusable group shapes expanded at compile time. COMMENT clauses attach intent metadata for AI tooling.

VALUE BLOCK — multi-line prose strings

RECALL 
01 BODY-TEXT PIC X VALUE BLOCK.   First paragraph of content here.   Second paragraph continues here. END VALUE.
NOTE

PIC X declared without a size (PIC X VALUE BLOCK.) is auto-sized by the compiler to fit the block content exactly.

VALUE HEREDOC — opaque raw content

RECALL 
01 BODY-TEXT PIC X VALUE HEREDOC.
   This is multi-line content.
   It can contain 'quoted strings' and RECALL syntax:
      PROCEDURE DIVISION.
      DISPLAY HEADING-1 BODY-TEXT.
   Everything between the delimiters is preserved exactly.
NOTE

HEREDOC closes only on END HEREDOC. — not on any heuristic. Use it for content that contains RECALL syntax, quoted strings, or JSON fragments. PIC X is auto-sized.

RECORD types — reusable group shapes

RECALL 
RECORD CARD-SHAPE WITH FIELDS   CARD-TITLE  PIC X(60)   CARD-BODY   PIC X(200).   01 CARDS RECORD CARD-SHAPE ROWS 4.
NOTE

RECORD types are expanded at compile time. Use LIKE to stamp a defined shape onto a group field. All field names are generated deterministically.

LANGUAGE

Data Loading

LOAD FROM reads a JSON or CSV file at compile time and injects its contents into the DATA DIVISION. Scalars become WORKING-STORAGE fields. Arrays become ITEMS groups. No runtime — values are baked into the compiled HTML.

Load from JSON

RECALL 
DATA DIVISION.
   LOAD FROM brief.json.

* brief.json keys map to field names:
{
  HERO-TITLE: Streaming Consolidation,
  STATS: [ { VALUE: 2451, LABEL: FETCH Score } ]
}

Load from CSV

RECALL 
DATA DIVISION.
   LOAD FROM metrics.csv.

* header row becomes column names:
NAME,SCORE,LAYER
Revenue (D3),75,origin
Quality (D5),62,momentum

* Auto-generates METRICS group.
NOTE

LOAD FROM runs at compile time. No data files are bundled into the HTML — only the resolved field values are embedded.

TIP

Multiple LOAD FROM statements in one DATA DIVISION are supported. Data from all files is merged into a single symbol table.

LANGUAGE

DATA COPY

DATA COPY brings shared field definitions from .rcpy copybooks into the DATA DIVISION at compile time. COPY FROM appears before WORKING-STORAGE SECTION. Fields are inlined as if declared locally — fully typed, validated, and visible to all diagnostic passes. Circular dependencies and field name collisions are compile errors.

RECALL 
DATA DIVISION.
   COPY FROM shared/nav-fields.rcpy.
   WORKING-STORAGE SECTION.
      01 PAGE-TITLE PIC X(60) VALUE Home.
NOTE

Fields from a DATA COPY copybook are visible to the type checker, `recall check --inspect`, and `recall check --format json`. They appear in the compositor payload alongside locally declared fields.

WARNING

Field name collisions (RCL-025) and circular COPY chains (RCL-026) are compile errors. RCL-024 fires when the referenced file cannot be found.

LANGUAGE

WITH INTENT

WITH INTENT annotates a DISPLAY statement with natural language intent for an AI compositor. Before expansion it compiles as a placeholder HTML comment (RCL-W09). Run recall expand to call the compositor — output is validated by the full compiler pipeline before writing. The compositor receives live schema, DATA DIVISION fields, COMMENT annotations, and palette.

RECALL 
PROCEDURE DIVISION.
   RENDER.
      DISPLAY HERO
         WITH INTENT 'dramatic opening, single product, urgency without hype'
         WITH DATA PRODUCT-NAME, PRODUCT-TAGLINE, CTA-PRIMARY.
   STOP RUN.
NOTE

A WITH INTENT statement compiles before expansion. The page is always in a valid, deployable state — the placeholder comment is the safe default.

TIP

Run `recall expand --dry-run` to inspect the JSON payload the compositor will receive without making an API call.

DIAGNOSTICS

Error Codes

RECALL enforces 29 structured diagnostic codes. Each code is stable, searchable, and documentable. If a program compiles, it is valid. If not, the compiler tells you exactly what is wrong, where, and how to fix it.

NOTE

Every diagnostic has a stable code. RCL-001 means the same thing forever. Use `recall explain RCL-001` for the full reference on any code.

Errors — abort compilation, no output written

CODECATEGORYDESCRIPTION
RCL-001type-mismatchElement received a field of the wrong PIC type.
RCL-002value-constraintVALUE string exceeds declared PIC X(n) length.
RCL-003unknown-elementDISPLAY references an unregistered element name.
RCL-004unknown-identifierVariable or group not declared in DATA DIVISION.
RCL-005missing-requiredPROCEDURE DIVISION is empty or absent.
RCL-006missing-requiredPROGRAM-ID or PAGE-TITLE absent from IDENTIFICATION DIVISION.
RCL-007group-shapeUSING references a scalar field — a group is required.
RCL-008group-shapeGroup used where scalar expected, or LAYOUT SPLIT structure invalid.
RCL-009formatPIC DATE value does not match ISO 8601 (YYYY-MM-DD).
RCL-010formatPIC URL value does not begin with http, https, or /.
RCL-011formatPIC PCT value is outside the 0-100 range.
RCL-012value-constraintPIC 9 field VALUE contains non-numeric characters.
RCL-013structuralSTOP RUN. is absent from PROCEDURE DIVISION.
RCL-014structuralComponent used in PROCEDURE before its DEFINE block appears.
RCL-015unknown-identifierCOPY FROM path cannot be resolved on disk or in node_modules.
RCL-016type-mismatchWITH DATA passes a name not declared in the component ACCEPTS list.
RCL-017missing-requiredComponent called without a REQUIRED ACCEPTS parameter.
RCL-018structuralCircular COPY detected — file includes itself directly or transitively.
RCL-019structuralRECORD type referenced but never defined in DATA DIVISION.
RCL-020value-constraintVALUE BLOCK encoding error.
RCL-021unknown-identifierLOAD FROM file not found or parse failed.
RCL-022formatPalette key has a trailing period — colour lookup fails silently.
RCL-023syntaxStatement has no terminator — every DISPLAY must end with a period.
RCL-024unknown-identifierDATA COPY file not found — COPY FROM in DATA DIVISION cannot be resolved.
RCL-025structuralDATA COPY field name collision — copybook field duplicates a local field.
RCL-026structuralCircular DATA COPY dependency — COPY FROM chain creates a cycle.
RCL-027structuralWITH INTENT expansion failed — compositor returned invalid RECALL.

Warnings — shown but compilation continues

CODECATEGORYDESCRIPTION
RCL-W01group-shapeGroup declared but has no items — element will render empty.
RCL-W02value-constraintVALUE string uses over 90% of declared PIC X(n) length.
RCL-W03missing-requiredAUTHOR or DATE-WRITTEN absent from IDENTIFICATION DIVISION.
RCL-W04structuralProcedure section defined but contains no DISPLAY statements.
RCL-W05type-mismatchNumeric PIC 9 field used in a string-accepting element — implicit coercion.
RCL-W06dataField referenced in PROCEDURE but declared without VALUE — renders empty.
RCL-W07syntaxUnknown PIC type — field defaulted to PIC X, compilation continues.
RCL-W08syntaxMalformed VALUE clause — treated as empty string, compilation continues.
RCL-W09structuralWITH INTENT clause not yet expanded — renders as HTML placeholder comment.
TIP

All 29 codes are actively enforced. Silent failures are errors. If a program compiles, it is valid.

DIAGNOSTICS

Strict Mode

Strict mode promotes all warnings to errors — zero tolerance for CI pipelines. Machine-readable JSON output includes source lines and caret strings so editor integrations and AI tools can render diagnostics without parsing ANSI sequences.

Terminal output

bash 
ERROR [RCL-001] type-mismatch — my-site.rcl:14:8
  DISPLAY HEADING-1 HERO-STAT
                    ^^^^^^^^^
  Type mismatch
  HEADING-1 expects PIC X — HERO-STAT is PIC 9(4)
  Hint: use DISPLAY LABEL HERO-STAT for numeric display

JSON output

json 
recall check my-site.rcl --format json

{
  errors: 1, warnings: 0,
  diagnostics: [{
    code: RCL-001, severity: error,
    category: type-mismatch,
    line: 14, col: 8,
    message: Type mismatch,
    source: DISPLAY HEADING-1 HERO-STAT,
    caret:                     ^^^^^^^^^
  }]
}

Exit codes

bash 
0 — clean, no errors or warnings
1 — errors present, no output written
2 — warnings present, compiled unless --strict
TIP

Use `--quiet` in CI for exit-code-only validation with no terminal output. Use `--strict` to promote all warnings to errors.

CLI

Command Reference

The RECALL CLI provides commands for compilation, validation, scaffolding, auto-fix, history diffing, and introspection. All commands accept .rcl files. Copybooks (.rcpy) are resolved automatically during compilation.

recall compile — single file

bash 
recall compile my-site.rcl
recall compile my-site.rcl --out dist/

recall build — directory

bash 
recall build src/ --out public/
recall build src/

recall check — validate without compiling

bash 
recall check my-site.rcl
recall check my-site.rcl --strict
recall check my-site.rcl --format json
recall check my-site.rcl --quiet
recall check my-site.rcl --inspect
NOTE

recall check is the primary quality gate. --strict for CI. --format json for editor integrations. --inspect to see LOAD FROM symbols before type-checking.

recall fix — auto-apply safe fixes

bash 
recall fix my-site.rcl --dry-run   * show what would change
recall fix my-site.rcl --yes       * apply all fixes without prompt
recall fix my-site.rcl             * interactive — confirm each fix
TIP

Safe fixes include: PIC resize when VALUE exceeds declared length (RCL-002), AUTHOR insertion (RCL-W03), and empty section removal (RCL-W04).

recall history — git-aware DATA field diff

bash 
recall history my-site.rcl
recall history my-site.rcl --commits 5

recall stats — orientation snapshot

bash 
recall stats my-site.rcl

recall schema — live element registry

bash 
recall schema             * list all elements and PIC types
recall schema --json       * machine-readable output
NOTE

recall schema queries the installed compiler directly. The output reflects the actual compiler state — drift between docs and implementation is structurally impossible.

recall explain — per-code reference

bash 
recall explain RCL-001
recall explain RCL-W05

recall scaffold — generate .rcl from component manifest

bash 
recall scaffold --list --plugin @semanticintent/recall-ui
recall scaffold PAGE-HERO --plugin @semanticintent/recall-ui
recall scaffold PAGE-HERO --plugin @semanticintent/recall-ui --out ./my-page.rcl
TIP

recall scaffold reads the component manifest from any installed plugin package and generates a complete, compilable .rcl pre-populated with the correct DATA DIVISION fields, PIC types, COMMENT annotations, and PROCEDURE DIVISION usage. Fill in the placeholder values and recall compile.

recall expand — expand WITH INTENT via AI compositor

bash 
recall expand page.rcl
recall expand page.rcl --dry-run
recall expand page.rcl --out ./expanded/
NOTE

recall expand calls the Anthropic API with a structured payload — intent, DATA DIVISION fields, COMMENT annotations, palette, and component registry. The expanded source is validated by the full compiler pipeline before writing. Requires ANTHROPIC_API_KEY.

ECOSYSTEM

Component Library

@semanticintent/recall-ui is the standard component library. Install once and use recall scaffold to generate a working .rcl from any component — or COPY FROM its .rcpy files directly. Includes the dark theme, nav, hero, stat-section, card-section, and footer.

bash 
npm install @semanticintent/recall-ui
RECALL 
ENVIRONMENT DIVISION.
   COPY FROM @semanticintent/recall-ui/themes/dark.rcpy.

COMPONENT DIVISION.
   COPY FROM @semanticintent/recall-ui/components/nav.rcpy.
   COPY FROM @semanticintent/recall-ui/components/hero.rcpy.
   COPY FROM @semanticintent/recall-ui/components/stat-section.rcpy.
   COPY FROM @semanticintent/recall-ui/components/footer.rcpy.

PROCEDURE DIVISION.
   RENDER.
      DISPLAY SITE-NAV     WITH DATA SITE-LOGO, NAV-ITEMS.
      DISPLAY PAGE-HERO    WITH DATA HERO-TITLE, HERO-SUBTITLE, CTA-LABEL, CTA-HREF.
      DISPLAY STAT-SECTION WITH DATA SECTION-TITLE, STATS, STAT-COLUMNS.
      DISPLAY SITE-FOOTER  WITH DATA FOOTER-TEXT.
   STOP RUN.
WARNING

recall-ui components declare strict ACCEPTS contracts. Your DATA DIVISION field names must match exactly. Run `recall check` after adding components.

NOTE

Themes (dark.rcpy) go in ENVIRONMENT DIVISION via COPY FROM. Components go in COMPONENT DIVISION. The separation is enforced by the compiler.