Supporting reference · Working design and evidence, not a promise of complete support.

Current product goals

Status: Working inventory. Every item remains revisable.

IDs make discussion and tests easier; they do not make a goal permanent. The assumption register (repository-only) records confidence, and the evidence ledger records what exists.

End-to-end journey

The self-service path we currently want to try is:

A user starts a Project and works with the coding agent they already use.
A First Draft Plugin, CLI, or API helps that agent author one complete target-aware Foundation Plan document.
A conditional import replaces the Project's mutable graph and triggers whole-graph analysis.
First Draft projects the admitted graph into ERD and table-like views, pairs them with diagnostics and, when valid, current gaps, returns the exact submitted JSON, and explains the selected Rails consequences. These are two projections of one current Project review state: the graph views show admitted meaning, while the JSON preserves authored source, including skipped meaning. The user or agent corrects meaning through another complete import.
A valid AnalysisRun returns the complete service- and target-support GapSet for the exact submitted source, graph generation, releases, and selected target. The user or agent reviews it before invoking ordinary Compile.
Starting compilation copies the exact submitted source and canonical admitted-graph snapshot and logically locks authored mutation until compilation finishes or the user cancels it.
A deterministic target Compiler captures the same coherent Project graph, emits output and the reviewed GapSet unchanged, verifies it, and creates a Compilation Record.
The user may inspect a replaceable preview, revise the Project for another compilation, or take the ordinary generated repository and continue with their agent.

Rails is the only current stack. The product may default it rather than present a one-item choice. Every Plan still embeds Rails and its pinned target-profile release.

Authoring and review

A-1 — Existing agent. The user's agent may conduct product conversation, inspect files, perform research, and call First Draft authoring operations.
A-2 — Product language. Authoring should discuss product meaning without requiring the user to know Rails.
A-3 — One review state. ERD, table, and Rails-aware surfaces show the admitted graph with diagnostics and, when valid, current gaps. JSON shows the exact submitted source. They are two projections of one current Project review state, not identical mutable models.
A-4 — Visible uncertainty. Contradictions, missing judgment, and consequential assumptions stay visible in draft state until resolved.
A-5 — Recommendation first. The agent and target profile may recommend supported choices without hiding their meaning or consequences.
A-6 — Dependent review. Revising one answer identifies dependent conclusions that may need review.
A-7 — Vocabulary admission. A concept enters the Plan because it improves recurring design and compilation, not merely because Rails or a gem exposes it.
A-8 — One selected stack. A Project selects one stack. A future cross-stack experiment may fork the Project rather than change the selected target in place.
A-9 — Context ownership. First Draft does not currently need to own the agent's chat, transcript, uploads, or unstructured product understanding.
A-10 — API shape. The initial agent API accepts one self-contained document. Whether a future Designer uses focused CRUD, and how it synchronizes exact source, the admitted graph, and skipped meaning, remains deferred under ADR 0020 (repository-only).

Foundation Plan

P-1 — Mutable authority. One Project owns one mutable admitted semantic graph. Accepted semantic graph changes advance its graph version. The Head owns the latest submitted bytes, including schema-valid meaning the service skips; a representation-only replacement does not create a graph generation but does require a fresh source-bound AnalysisRun.
P-2 — Resource identity. The request route selects the Project and clients treat its Head ETag as opaque. The document omits root Plan, Project, and revision identity. Project-scoped subject UUIDs preserve continuity across complete submissions.
P-3 — Representation boundary. A Foundation Plan document is self-contained for import, export, fixtures, and compilation evidence. Analysis considers the submitted source bytes stored by the Head plus one sealed admitted graph. The Compiler coherently preloads that logically locked graph; it does not import the bytes or construct a second authored or semantic graph.
P-4 — Semantic application definition. The Plan contains application meaning as Entities, Fields, References, Associations, queries, rules, Policies, Scaffolds, and other admitted subjects.
P-5 — Target identity. The Plan embeds the Project-selected stack and automatically pinned target-profile release, and import rejects a mismatch. How or whether a retained Project advances to a future profile is deferred; pre-alpha work may start a new Project or fork an old one.
P-6 — Sparse realization. A material choice among several supported target lowerings appears at the narrowest coherent subject. Fixed profile consequences are not repeated as fake choices.
P-7 — Generation request. Every structured subject requests generation. The Plan has no element-level unique, responsibility, disposition, or opt-out property.
P-8 — Derived consequences. Capabilities and external prerequisites derive from application meaning, realization choices, and the selected profile. They are not parallel editable lists.
P-9 — Human notes. A Field may contain explanatory notes. The Compiler does not infer unstated behavior from that prose.
P-10 — Presence semantics. Ordinary empty collections and optional singleton or variant-specific values are omitted. Required feature maps may be empty. Required application.entities may be empty while the Plan is being authored so an agent does not invent a placeholder Entity. null appears only when it has a distinct documented meaning.
P-11 — Safe data. The Plan contains no secrets, transient provider state, or arbitrary executable code.
P-12 — Structured boundary. Product meaning with no bounded admitted representation remains with the user's agent instead of entering a Continuation or Handoff field.

Changing the Project may use agents, heuristics, target expertise, and user judgment. Deterministic compilation begins only from a valid graph generation and its immutable snapshot evidence.

Compilation

C-1 — One coherent input. A Compiler eagerly preloads one complete Project graph generation and gives every renderer the same rich graph after the read boundary closes.
C-2 — Recompilation. One unchanged graph generation may have several Compilation Records.
C-3 — Reproducibility. Fixed graph snapshot, Compiler, target profile, Core, and toolchain inputs produce the same meaningful output.
C-4 — No new product judgment. The Compiler may calculate forced consequences and begin from the starting material that F-9 describes, but it does not present that material as an authored product decision or select among materially different product realizations.
C-5 — Actionable admission. Malformed, schema-invalid, structurally dangling, relationally unrepresentable, or contradictory authored meaning fails import or produces an issues_found AnalysisRun with no GapSet. Every failure produces typed, location-aware diagnostics. Target incompleteness is not an authored semantic error.
C-6 — No silent claims. Authorization, transitions, ownership, validation, and other stated meaning are generated or reported as a gap. The artifact does not claim that missing behavior was realized. A surface whose guarding Policy the Compiler does not write keeps that Policy as a stub that admits nobody until the Policy is written, and the GapSet lists it. A hard failure is reserved for invalid authored meaning, corrupted review identity, failed verification, or the absence of any deterministic bootable residual application.
C-7 — Coherent gaps. Schema-valid meaning unsupported by the current service, or admitted meaning unsupported by one target or Compiler release, remains in the Plan as a nonblocking support gap. Meaning the service skips before analysis is pruned with its dependents. For admitted behavior it does not realize, the Compiler emits everything that uses the behavior and stubs or leaves out the behavior itself, as F-9 describes. Output may do less than the Plan asks but never gives anyone more access than its Policies allow. A generated-name collision uses a semantics-preserving projection when one exists; otherwise the Compiler omits every participant, without an arbitrary winner, and lists it. A valid AnalysisRun discloses the complete service/target distinction before Compile; the emitted application remains bootable and carries that reviewed GapSet.
C-8 — Cross-feature derivation. The Compiler applies consequences forced by interactions among Plan subjects and profile rules rather than emitting unrelated snippets.
C-9 — Verification. Emitted output installs, prepares its data stores, boots, and passes the checks stated for what was generated. Specs for behavior the Compiler does not write fail, and only through their stub or the missing behavior.
C-10 — Compilation Record. Every accepted compile request records its UUIDv7, exact submitted-source identity, Project graph version, canonical graph-snapshot format and hash, reviewed AnalysisRun/GapSet identity, Compiler, profile, Core release and archive digest, toolchain, diagnostics, output identity, provenance, and verification results. External execution retries are separate Compilation Attempts within that Compilation.

Candidate overall results are succeeded and failed. A Compilation with capability skips is an ordinary success, and the generated .firstdraft/gaps.json discloses each subject's gap status. The exact response schema remains open.

Foundation quality

F-1 — Verified output. Foundation means Compiler output whose emitted behavior passed its stated checks and whose gaps are disclosed. Its only failing specs are the ones F-9 expects for behavior the Compiler did not write.
F-2 — Composition. Core, derived Capabilities, and Domain are provenance labels, not protected directories.
F-3 — Operability. Every Foundation includes reproducible setup, one clear verification command, useful diagnostics, and concise agent guidance. Tests and CI describe the behavior the target actually verifies; they do not turn an incomplete target slice into a claim of complete application coverage. Until the owner writes the behavior F-9 stubs or leaves out, the verification command fails only through that behavior's specs. The generated agent guidance tells the user's agent to preview without waiting for that behavior, naming the pages that deny or raise, and to debug any other failure as its own without weakening a spec; generated tests describe it. The owner's 2026-10-12 decision (repository-only) replaced rule 7 of the 2026-10-10 decision, which had the agent clear those failures before any preview.
F-4 — Baseline quality. Every target defines an appropriate direction for security, accessibility, internationalization, data integrity, error handling, and operations. A Compiler may emit an earlier conventional point on that path. The reviewed GapSet lists authored meaning that the application does not realize, such as an unwritten Predicate or Policy, or an omitted page. The generated application's documents, today DEPLOY.md and the README, disclose the safeguards and app-wide trade-offs that remain; deriving them from the project graph (repository-only) is tracked separately.
F-5 — Triggered safeguards. Plan-triggered surfaces derive related safeguard obligations, such as abuse controls for public input and lifecycle handling for uploads. The Compiler realizes each obligation or discloses it in the generated application's documents rather than the GapSet. A missing safeguard does not by itself require omitting the surface it protects; a Policy the Compiler does not write becomes a stub, as F-9 describes.
F-6 — Replaceable adapters. Hosting, mail, storage, monitoring, and similar vendors remain replaceable operational adapters rather than permanent product dependencies.
F-7 — Inspectable source. Dependencies and emitted source have provenance and redistribution rights appropriate for the owner.
F-8 — Explain the result. The repository contains the exact submitted Plan source and canonical reviewed .firstdraft/gaps.json; the durable Compilation separately retains the canonical admitted-graph snapshot. Clients may render the GapSet for people without persisting a second prose authority. Final artifact identity and publication status remain on the durable record rather than describing their own containing artifact recursively.
F-9 — Code worth keeping. A generated application is an editable head start, not a production-ready application. It may be unfinished, but every emitted line is conventional code that its owner, or a careful Rails developer, would keep. The measure is a useful head start: the Compiler emits everything the Plan asks for, security and authorization included. Behavior it cannot finish keeps everything that uses it, as a stub or, when Rails runs it on every write, left out behind a failing spec. The Compiler emits only what the Plan requests or its realization forces. The one exception is a Policy's relation scope, which the Compiler emits as a head start before any page reads it. Policies (repository-only) records the owner's 2026-10-09 choice and how generated examples check a scope against its rule. Output may do less than the Plan asks but never lets anyone do or see records that the Plan's Policies deny.
- Stubs. Behavior the Compiler does not write, whether a target gap or marked owner-built, keeps everything that uses it. Format 0.24 (repository-only) adds the owner marker; its shape is open. A stubbed Policy rule returns false, with a comment naming its subject and spec, so every page that asks it denies. A stubbed scope, event, or calculation raises NotImplementedError naming its subject wherever a page shows its output. A rule that delegates to a stub, or an alias of one, follows it. A stubbed Policy admits nobody. Behavior Rails runs by itself is left out instead: a Validation and its condition, a callback, a normalization, a default, a counter, or an association scope. Seeds, factories, and spec setup never call a stub. Either way, the spec the Compiler would emit for the behavior fails until it is written.
- Storage. owner never applies to storage. The Compiler generates every table, column, and key the Plan defines; storage it cannot generate yet stays a listed gap until it can.
- Omissions. Analysis rejects a Plan that no implementation could satisfy (repository-only), as C-5 describes, so the owner decides. A surface that a satisfiable Plan allows but current output cannot make succeed is Compiler work. Presentation the renderer cannot serve is omitted and listed. Code that does only part of its job stays when the finished application needs it anyway, such as a page that shows an upload whose file a rule not yet written must allow; the GapSet discloses what is missing.
- Honest output. Output is deterministic and bootable. The submitted Plan stays in the artifact, the GapSet lists unmet authored meaning, the generated documents disclose missing safeguards, and nothing claims missing behavior was realized. Output never contains invalid source, embedded credentials, invented external effects, or defensive machinery that a developer would first remove.
- Starting material. Lines identical to a new Rails application and Core's reusable UI kit count as starting material.
The 2026-10-08 (repository-only), 2026-10-10 (repository-only), and 2026-10-11 (repository-only) decisions record why. Stub emission (repository-only) tracks output that still omits surfaces around unwritten behavior, and the compiled-app audit (repository-only) tracks other output that does not meet this requirement yet.

Ownership and continuation

O-1 — Ordinary source. Every generated file may be edited, moved, or deleted.
O-2 — No required runtime. Continuing the application does not require a First Draft runtime or proprietary generated-source editor.
O-3 — Owner control. The owner can control application data, repository, production credentials, hosting, domains, and native identities, with temporary exceptions disclosed.
O-4 — Agent continuation. The user's agent can orient from the repository, Plan, tests, and Compilation Record and implement work outside the Plan vocabulary.
O-5 — Deferred context transfer. A First Draft-owned transcript or Handoff bundle is added only if observed use shows that the existing artifacts lose material understanding.
O-6 — No regeneration requirement. The first product does not need to regenerate safely into an owner-modified repository.

Native applications

N-1 — Owned projects. The intended product can eventually emit ordinary owner-controlled iOS and Android projects with coherent server integration.
N-2 — Complete push path. Supported push behavior spans server, client registration, preference and token lifecycle, delivery diagnostics, and routed-open behavior.
N-3 — Separate claims. Authoring, building, previewing, signing, installing, distributing, and receiving push are reported as separate capabilities.
N-4 — Real project preview. A managed preview runs the actual generated project through a replaceable adapter rather than substituting a generic shell.
N-5 — Owner identities. Owner release uses owner-controlled application identities and credentials.
N-6 — Evidence boundaries. iOS does not prove Android, Simulator does not prove a physical device, and token registration does not prove end-to-end delivery.

Native behavior is not required for the first web Compiler proof.

Evidence and claims

E-1 — Name the boundary. Documentation and marketing distinguish design, implementation, reference exercises, Compiler exercises, repeated results, and representative-user observations.
E-2 — Reference is not generation. A hand-authored app can support a lowering without proving Compiler output.
E-3 — Record facilitation. Workshop reports include staff intervention, manual repair, delay, and account exceptions.
E-4 — Measure claims. Claims about speed, tokens, completion, native delivery, or continuation follow measurement.
E-5 — Repeat the journey. Isolated feature proofs do not replace repeated end-to-end use.

Current acceptance bars

First document bar: the six application probes expose enough meaning and realization detail for a thin emission spike to diagnose omissions.
First Compiler bar: the spike captures one graph generation and emits the same meaningful development Foundation twice, including its reference-data and development-data setup.
Coverage bar: every support gap is present before Compile in one self-contained machine-readable GapSet that the artifact copies byte-for-byte; human views are projections of that source.
Foundation bar: emitted behavior satisfies its Rails quality checks before the output is called a Foundation.
Design bar: a user finds and corrects a planted consequential misunderstanding before compilation.
Continuation bar: the user's agent makes and deploys a change outside the Plan vocabulary after First Draft loses write access.
Self-service bar: a representative user and external agent complete the journey without staff action.

Non-requirements

The first product does not need to:

own a general-purpose product conversation;
model every future feature;
support more than one target;
regenerate safely into an owner-modified repository;
provide arbitrary visual page composition;
choose every vendor a mature application may eventually need;
remove every future need for refactoring; or
replace the user's coding agent.

References marked “repository-only” name implementation or internal material outside this public guide. They are intentionally not links. Publishing a design does not prove its implementation.