Overview
How authored templates become runtime document programs across app and local venues
Goldie Blocks templates are both structural source of truth and executable document programs. Authors write module source files using the DSL syntax. The source declares structure, logic, metadata, workflow behavior, and renderable content.
The compiler/import boundary validates authored source and emits deterministic machine-readable artifacts for runtime records. The compiler contract is not yet published as an authoritative reference; until it is, docs should treat it as the boundary between authored source and app runtime state.
Authoring Time
At authoring time, a template source declares:
- modules and blocks
- data fields and computed values
flow.conditiongates; sequencing is position in the YAML sequence, not a declared field- interpolation references and block-level iteration
- display metadata
App/library workflows may add access, classification, and signal metadata for sharing, search, review, ranking, and reuse. Local skills do not need those fields to interview or render a document.
Selection helpers such as performs and consumes are derived from this source when the app needs filtering, compatibility checks, or insertion diagnostics. They are not authored fields. See Derived Selection Facets.
Authors program the document. The authored source is the source of truth for both shape and behavior.
Runtime
At runtime, the same template is interpreted against an instance's collected data, computed values, active workflow mode, and generation state.
Authoring-time logic is evaluated lazily on read against current state:
flow.conditionexpressions- computed field expressions
- template interpolation
repeatForandjoinForblock iteration
Authors do not write separate runtime code. The template is the execution script.
Evaluation Venues
Two evaluation venues run the same template against the same instance data shape. Choice of venue is an implementation detail; the language, data shape, and produced output are intended to be identical.
| Venue | Storage | Evaluation | Agent role |
|---|---|---|---|
| In-app | Convex documents and tables | Convex resolves reactive views where it can; an agent tool surface handles the remainder. | Agent calls tools to ask questions, write data, and request renders. |
| IDE / local | Markdown/YAML files on disk | Claude Code reads template and instance files, interprets the DSL, and writes resolved output back to disk. | Claude Code is both agent and interpreter. |
The in-app venue persists authored and runtime state through the unified content-object schema: Documents, Modules, embedded Blocks, and exact-snapshot Document Generations. Superseded template/instance pages remain available only for historical context.
Implications
- The DSL must be venue-agnostic.
- Expressions must evaluate consistently in Convex-backed app flows and local interpreter flows.
- Computed fields are stored as expression text and evaluated lazily on read. No persisted derived results and no dependency-graph maintenance are required for MVP.
- Tooling and tests should target the compiled JSON contract, not handwritten source.
- Agent behavior has the same shape across venues; only the tool or file surface differs.
- Roles, capabilities, surfaces, and agent posture are defined in Permissions and Surfaces.
Reference Pages
- DSL Agent Spec — short-form runtime reference; the canonical source for
document_guide/dsl_spec.mdin each skill - DSL Syntax — full narrative reference with examples and edge cases
- DSL Expressions
- Documents, Modules, and Blocks
- Derived Selection Facets
- Access Metadata
- Corpus Seeding
- Local Skills