<!-- Generated by scripts/build-llms-full.mjs; do not edit by hand. -->

# Topogram

> Topogram is a living app map that helps humans and agents change software from bounded context, contracts, and proof.

Topogram uses these public command verbs:

- `init` starts an empty app map for maintained, greenfield, existing-app, or spec-only work.
- `copy` copies templates or pure Topogram packages into a project.
- `extract` emits reviewable brownfield candidates without mutating source apps.
- `adopt` promotes reviewed candidates into canonical `topo/` source.
- `generate` writes app/runtime outputs from the app map.
- `emit` prints or writes contracts, reports, snapshots, context, and plans.
- `query` gives agents focused slices, plans, proof gaps, and review packets.

## Start

- [Docs Map](docs/README.md): Audience-oriented entrypoint for current Topogram docs.
- [Beta Launch](docs/beta-launch.md): Public beta story, first commands, proof paths, current limits, and feedback asks.
- [Beta Readiness](docs/beta-readiness.md): What must be true before a beta release and what remains preview-only.
- [What Topogram Is](docs/concepts/what-is-topogram.md): Short evaluator explanation of Topogram, its value, and what it is not.
- [Init Workspace](docs/start/init-workspace.md): Create an empty Topogram workspace.
- [Greenfield Generate](docs/start/greenfield-generate.md): Start from a template or authored spec and generate app outputs.
- [Brownfield Extract/Adopt](docs/start/brownfield-import.md): Extract candidates from an existing app and adopt reviewed specs.
- [Workflow Extraction](docs/start/workflow-extraction.md): Extract workflow-native state machines or process definitions into reviewable candidates.
- [Database Migrations](docs/start/database-migrations.md): Use Topogram with generated or maintained database migrations.
- [Agent First Run](docs/agent-first-run.md): First commands and context packets for coding agents.

## Concepts

- [Topogram Model](docs/concepts/topogram-model.md): Core model and ownership boundaries.
- [Topo Workspace](docs/concepts/topo-workspace.md): Workspace folder, project config, and ownership conventions.
- [Generate vs Emit](docs/concepts/generate-vs-emit.md): Difference between app generation and artifact emission.
- [Templates and Catalog](docs/concepts/templates-catalog.md): Template, catalog, and pure Topogram package concepts.
- [Generators](docs/concepts/generators.md): Package-backed generators and stack realization.
- [Extractors](docs/concepts/extractors.md): Package-backed extractors and brownfield discovery.
- [Widgets and Design](docs/widgets.md): Semantic UI widgets, display fields, and design intent.
- [Map A Design System](docs/design/map-design-system.md): Widget-first mapping from semantic widgets to platform component refs.
- [SDLC](docs/concepts/sdlc.md): Topogram SDLC records and command-owned workflow state.
- [Glossary](docs/concepts/glossary.md): Current project vocabulary for humans and agents.

## Reference

- [CLI Reference](docs/reference/cli.md): Public commands and options.
- [DSL Reference](docs/reference/dsl.md): Topogram DSL statement kinds and fields.
- [Project Config](docs/reference/project-config.md): `topogram.project.json` shape and ownership settings.
- [Extract/Adopt JSON](docs/reference/import-json.md): Extraction, candidate, plan, and adoption JSON shapes.

## Authoring

- [Templates](docs/authoring/templates.md): Template package authoring and trust expectations.
- [Generator Packs](docs/authoring/generator-packs.md): Generator package manifest and adapter authoring.
- [Extractor Packs](docs/authoring/extractor-packs.md): Extractor package manifest and adapter authoring.

## Proofs

- [Proof Walkthrough](docs/proof-walkthrough.md): Runnable proof/demo program and branch/tag convention.
- [Generated/Maintained Proof Repo](https://github.com/attebury/topogram-proof-content-approval-v3): Current beta-story generated-to-maintained proof repository.
- [Brownfield Proof Repo](https://github.com/attebury/topogram-proof-content-approval-brownfield-v3): Current beta-story brownfield extract/adopt and cross-stack proof repository.
- [Widget Design Realization Proof Repo](https://github.com/attebury/topogram-proof-widget-design-realization): Focused proof for widget-first design realization sets, including the Markdown design matrix from `ui-design-coverage --format markdown`.
- [Storybook Design Realization Proof Repo](https://github.com/attebury/topogram-proof-storybook-design-realization): Focused proof for static Storybook CSF metadata as review-only `design_realizations` evidence.
- [XState Workflow Proof Repo](https://github.com/attebury/topogram-proof-xstate-workflow): Focused workflow-native proof for package-backed XState extraction.
- [Step Functions Workflow Proof Repo](https://github.com/attebury/topogram-proof-step-functions-workflow): Focused workflow-native proof for package-backed Step Functions ASL extraction.

## Optional

- [Maintainer Docs](docs/maintainers/engine-development.md): Engine maintainer workflow.
- [Testing](docs/maintainers/testing.md): Maintainer testing guidance.
- [Releasing](docs/maintainers/releasing.md): Release process for maintainers.
- [Release Matrix](docs/release-matrix.md): Current package and consumer release status.
- [ARIA Accessibility Contract](docs/design/aria-accessibility-contract.md): Design note for accessibility obligations, ARIA evidence, focus, keyboard behavior, and proof.
- [Generated/Maintained Proof V2](https://github.com/attebury/topogram-proof-content-approval-v2): Historical generated-to-maintained proof repository.
- [Brownfield Proof V2](https://github.com/attebury/topogram-proof-content-approval-brownfield-v2): Historical brownfield proof repository.
- [I18n Message Contract](docs/design/i18n-message-contract.md): Design note for glossary terms, translatable messages, message keys, and locale policy.
- [SvelteKit Realization Shape](docs/design/sveltekit-realization-shape.md): Design note for maintained SvelteKit realization.

---

# Source: docs/README.md

# Topogram Docs

> These docs are the current audience map for Topogram users, agents, package authors, and maintainers.

Status: current
Audience: people and agents choosing where to start
Use when: you need the current documentation map by audience or workflow.

These docs are organized by audience. Historical docs were archived to
`topogram-project` on 2026-05-11 and are not the current source of truth.

For agent and retrieval use, start from [`../llms.txt`](../llms.txt). The
generated [`../llms-full.txt`](../llms-full.txt) file bundles the high-priority
docs listed there.

## I Want To...

| Goal | Start Here |
| --- | --- |
| Initialize an empty Topogram workspace | [Init Workspace](./start/init-workspace.md) |
| Make an app safe for agents to change | [Brownfield Extract/Adopt](./start/brownfield-import.md), then [Agent First Run](./agent-first-run.md) |
| Understand the beta story | [Beta Launch](./beta-launch.md) |
| Evaluate beta readiness | [Beta Readiness](./beta-readiness.md) for the one-command smoke, then [Proof Walkthrough](./proof-walkthrough.md) |
| Understand what Topogram is and is not | [What Topogram Is](./concepts/what-is-topogram.md) |
| Extract an existing app | [Brownfield Extract/Adopt](./start/brownfield-import.md) |
| Extract workflow state machines | [Workflow Extraction](./start/workflow-extraction.md) |
| Generate a new app | [Greenfield Generate](./start/greenfield-generate.md) |
| Maintain database migrations | [Database Migrations](./start/database-migrations.md) |
| Work as an agent | [Agent First Run](./agent-first-run.md) |
| Understand the model | [Topogram Model](./concepts/topogram-model.md) |
| Look up project vocabulary | [Glossary](./concepts/glossary.md) |
| Map a design system to Topogram widgets | [Map A Design System](./design/map-design-system.md), then inspect the [Widget Design Realization Proof](https://github.com/attebury/topogram-proof-widget-design-realization) |
| Understand `topo/` ownership | [Topo Workspace](./concepts/topo-workspace.md) |
| Choose between `generate` and `emit` | [Generate vs Emit](./concepts/generate-vs-emit.md) |
| Author templates | [Template Authoring](./authoring/templates.md) |
| Author generator packages | [Generator Packs](./authoring/generator-packs.md) |
| Use or author extractor packages | [Extractor Packs](./authoring/extractor-packs.md) |
| Inspect runnable proof stories | [Proof Walkthrough](./proof-walkthrough.md) |
| Maintain this repo | [Engine Development](./maintainers/engine-development.md) |
| Maintain docs | [Documentation Maintenance](./maintainers/docs.md) |

## Proof Repositories

Use the public proof repos when you want to inspect complete, runnable workflow
stories instead of isolated command examples. They are the fastest way to see
how an app map, extraction/adoption, generation, SDLC, agent packets, and
maintained ownership fit together.

- [Proof Walkthrough](./proof-walkthrough.md)
- [Beta Launch](./beta-launch.md)
- [Beta Readiness](./beta-readiness.md)
- [Generated To Maintained Proof](https://github.com/attebury/topogram-proof-content-approval-v3)
- [Brownfield Extract/Adopt Proof](https://github.com/attebury/topogram-proof-content-approval-brownfield-v3)
- [Widget Design Realization Proof](https://github.com/attebury/topogram-proof-widget-design-realization)
- [XState Workflow Extraction Proof](https://github.com/attebury/topogram-proof-xstate-workflow)
- [Step Functions Workflow Extraction Proof](https://github.com/attebury/topogram-proof-step-functions-workflow)

Each v3 proof repo uses branch and tag checkpoints named `step/NN-*` and
`proof-NN-*`. Run `npm run verify` at any checkpoint to execute the hardened
proof audit for that step.

## Reference

- [SvelteKit / maintained UI realization (design reference)](./design/sveltekit-realization-shape.md)
- [ARIA Accessibility Contract](./design/aria-accessibility-contract.md)
- [I18n Message Contract](./design/i18n-message-contract.md)
- [Map A Design System](./design/map-design-system.md)
- [What Topogram Is](./concepts/what-is-topogram.md)
- [CLI Reference](./reference/cli.md)
- [DSL Reference](./reference/dsl.md)
- [Project Config](./reference/project-config.md)
- [Extract/Adopt JSON](./reference/import-json.md)
- [Widgets](./widgets.md)
- [SDLC](./concepts/sdlc.md)

## Current Terms

- Workspace folder: `topo/`
- Project config: `topogram.project.json`
- Reusable UI contract: `widget`
- App output command: `topogram generate`
- Artifact command: `topogram emit`
- Brownfield discovery command: `topogram extract`
- Topology entries: `topology.runtimes`
- Runtime kinds: `web_surface`, `api_service`, `database`, `ios_surface`,
  `android_surface`

---

# Source: docs/beta-launch.md

# Topogram Beta Launch

> Topogram beta is for teams that want a living app map agents can safely work from.

Status: current
Audience: evaluators, engineering leads, maintainers, agents, and package authors
Use when: you need the public beta story, first commands, proof paths, limits, and useful feedback asks.

## What Topogram Is

Topogram keeps app intent, contracts, ownership, and proof in a `topo/`
workspace. Humans and agents use that map to understand what exists, what is
owned by generators, what is maintained by people, and what proof should run
before a change is trusted.

The beta product wedge is brownfield plus agents:

1. extract reviewable candidates from existing code;
2. adopt only the candidates a human reviewed;
3. query a focused slice for one task or surface;
4. change maintained code or generate owned output;
5. verify with the commands named by the map.

Generation is still important, but it is one realization path for the app map,
not the whole product.

## Who Should Try It

- Teams experimenting with coding agents on existing apps.
- Maintainers who want contracts and proof around brownfield code.
- Product engineers who want generated starts but expect to graduate parts of
  the app to maintained ownership.
- Package authors building generator or extractor packs for a stack.
- Release owners who want consumer proof, public smoke, and package rollup
  checks before shipping.

## Five-Minute Evaluation

From this repo, run the published CLI smoke:

```bash
TOPOGRAM_CLI_PACKAGE_SPEC=@topogram/cli@latest npm run smoke:beta-evaluator
```

That command installs the public CLI and first-party extractor packages in a
clean temp project. It creates a small brownfield app, extracts review-only
candidates, adopts a reviewed bundle, emits agent packets, validates the
adopted `topo/`, and writes a portable report.

For your own app, use the same shape manually:

```bash
npx topogram extract ./existing-app --out ./imported-topogram
cd ./imported-topogram
npx topogram extract plan
npx topogram adopt --list
npx topogram query extract-plan ./topo --json
npx topogram query single-agent-plan ./topo --mode extract-adopt --json
npx topogram check
```

Start with package-backed extractors when the stack is known:

```bash
npm install --save-dev @topogram/cli @topogram/extractor-express-api @topogram/extractor-prisma-db
npx topogram extractor recommend ./existing-app --from db,api
npx topogram extractor policy init
npx topogram extractor policy pin @topogram/extractor-express-api@1
npx topogram extractor policy pin @topogram/extractor-prisma-db@1
npx topogram extract ./existing-app --out ./imported-topogram --from db,api --extractor @topogram/extractor-express-api --extractor @topogram/extractor-prisma-db
```

## Proof Paths

Use the proof repos when you want a complete story with branches, tags, SDLC
records, agent packets, artifacts, and `npm run verify` at every checkpoint.

- [Brownfield proof](https://github.com/attebury/topogram-proof-content-approval-brownfield-v3):
  best first demo for extract/adopt, maintained feature work, drift refresh,
  and cross-stack recreation.
- [Generated to maintained proof](https://github.com/attebury/topogram-proof-content-approval-v3):
  best demo for generated output, graduation to maintained ownership, and DB
  migration guidance.
- [XState workflow proof](https://github.com/attebury/topogram-proof-xstate-workflow):
  focused workflow-native extraction from an app state-machine library.
- [Step Functions workflow proof](https://github.com/attebury/topogram-proof-step-functions-workflow):
  focused workflow-native extraction from local Amazon States Language source.
- [Widget design realization proof](https://github.com/attebury/topogram-proof-widget-design-realization):
  focused semantic-design proof for mapping one widget to web, iOS, and Android
  component refs. It is current on `@topogram/cli@0.3.110` and includes the
  designer-readable `ui-design-coverage --format markdown` matrix.

## What Is Beta-Ready

- `init`, `copy`, `extract`, `adopt`, `generate`, `emit`, and `query` command
  vocabulary.
- `topo/` workspace ownership and project config.
- Brownfield extraction with bundled and first-party package-backed extractors.
- Review-only adoption plans and explicit `adopt --write`.
- Agent briefs, focused context slices, SDLC readiness, and proof-gap queries.
- Web UI semantic contracts, widget realization reports, and i18n/ARIA
  obligation markers for generated web output.
- Widget-first design realization matrices that show component refs, platform
  coverage, variant/state coverage, token/a11y/i18n gaps, and review work.
- Release preflight, strict release status, first-party consumer rollup, proof
  consumer tracking, and secret scanning.

## Current Limits

Topogram beta does not promise:

- pixel-perfect UI parity;
- complete runtime translation catalog management;
- full automated accessibility audit coverage;
- production deployment orchestration;
- automatic source mutation during extraction;
- silent adoption of brownfield candidates;
- enterprise audit exports, signed history, or external issue tracker sync.

Native generation and some workflow extractor families are preview/future work.

## Feedback That Helps

Useful beta feedback is concrete:

- Which command or artifact was unclear?
- Which candidate was noisy, missing, or unsafe to adopt?
- Which slice gave an agent too much or too little context?
- Which proof command failed to build trust?
- Which stack needs a generator or extractor pack?
- Which beta limit blocks real evaluation?

Attach the command, the relevant `topo/` file or candidate artifact, and the
expected next action when possible.

## Related Docs

- [Beta Readiness](./beta-readiness.md)
- [Brownfield Extract/Adopt](./start/brownfield-import.md)
- [Agent First Run](./agent-first-run.md)
- [Proof Walkthrough](./proof-walkthrough.md)
- [Extractor Packs](./authoring/extractor-packs.md)

---

# Source: docs/beta-readiness.md

# Beta Readiness

> Topogram beta is ready when the app-map workflow is understandable, demonstrable, and safe enough for real evaluator use.

Status: current
Audience: evaluators, maintainers, agents, package authors, and release owners
Use when: you need to know what is beta-ready, what is preview-only, and what proof to run before a beta release.

Topogram's beta wedge is not "a DSL that generates apps." It is an
agent-safe app map: extract or author a `topo/`, review ownership and contracts,
query bounded context, then generate or maintain software with proof.

For the public evaluator narrative, see [Beta Launch](./beta-launch.md).

## Beta Bar

Before a beta release, these workflows should be true from a fresh install:

- `topogram init` creates an empty maintained or greenfield workspace and
  explains what it scaffolded.
- `topogram copy` creates a starter from the public catalog.
- `topogram extract` plus package-backed extractors creates review-only
  brownfield candidates without mutating source code.
- `topogram adopt` promotes reviewed candidates and leaves receipts.
- `topogram query` gives agents focused context, proof gaps, and next commands.
- `topogram generate` writes app/runtime output only for generated-owned paths.
- `topogram emit` prints or writes contracts, reports, snapshots, and plans.
- `topogram check`, SDLC checks, docs checks, package smoke, and release status
  verify the claimed contract.

## UI Beta Proof

UI beta readiness is web-first and semantic. Topogram must preserve the same
screens, routes, regions, widget usages, display fields, behavior coverage, and
design-token intent from one `ui_contract` across React and SvelteKit proof
surfaces.

Run these commands when UI contracts, widgets, or web generators change:

```bash
topogram emit ui-surface-contract ./topo --projection <web_surface> --json
topogram emit ui-realization-report ./topo --projection <web_surface> --json
topogram query ui-design-coverage ./topo --projection <web_surface> --json
topogram emit widget-conformance-report ./topo --projection <web_surface> --json
topogram query slice ./topo --projection <web_surface> --screen <screen-id> --json
```

For beta review, the important artifact is the realization report: it should
show whether each screen, widget usage, message key, accessibility obligation,
design token, design-contract mapping, and behavior is `rendered`,
`contract_only`, `implementation_owned`, `unsupported`, or `failed`.
The design-coverage query is the companion authoring view: it highlights missing
platform mappings, unmapped widgets, and behavior that still needs
developer/agent review before parity claims.

For design-system mapping, use widget-first `design_realization_set` records.
`design_contract` owns the design-system/platform header and token scope;
realization sets map semantic widgets to platform component refs and behavior
support. See [Map A Design System](./design/map-design-system.md).
The focused [Widget Design Realization Proof](https://github.com/attebury/topogram-proof-widget-design-realization)
is current on `@topogram/cli@0.3.110` and includes the Markdown design matrix
that designers and front-end leads should read first.

The beta bar is compile plus deterministic contract and marker coverage. It is
not screenshot comparison, pixel parity, runtime translation completeness, or a
full automated accessibility audit. Semantic i18n message contracts and
accessibility obligations are beta scope for generated web output; locale
catalogs, runtime i18n libraries, axe/Playwright audits, and manual review
evidence are later proof layers.

## Extractor Beta Proof

Extractor packs are execution packages, not templates. A beta-quality extractor
path must prove:

- package discovery is explicit;
- package code is not loaded during list/show/recommend/policy commands;
- package execution happens only during `extractor check` or `extract`;
- source apps are not mutated;
- candidates are review-only;
- `extract plan`, `adopt --list`, and focused query packets show provenance and
  safety notes before adoption.

For private extractor packages, use local paths or already-installed private
packages. Topogram does not install extractor packages during extraction and
does not require packages to be public unless you intend to publish them.

## Proof Repos

The v3 proof repositories are the current full beta demos, not per-patch
release consumers:

- [Brownfield proof](https://github.com/attebury/topogram-proof-content-approval-brownfield-v3):
  shortest story for extracting, adopting, querying, implementing, refreshing
  drift, and recreating another stack.
- [Generated-to-maintained proof](https://github.com/attebury/topogram-proof-content-approval-v3):
  best story for starting generated, graduating to maintained ownership, and
  using Topogram for maintained feature and DB migration guidance.
- [XState workflow proof](https://github.com/attebury/topogram-proof-xstate-workflow)
  and [Step Functions workflow proof](https://github.com/attebury/topogram-proof-step-functions-workflow):
  focused stories for package-backed workflow extraction, adoption, compact
  workflow slices, and drift refresh.

Each proof checkpoint should pass `npm run verify`. Refresh proof repos when
command meaning changes, a breaking workflow lands, or the proof artifacts teach
stale behavior. Do not repin every proof repo for every patch release.

## One-Command Evaluator Smoke

Before beta, run the clean brownfield evaluator smoke from this repo:

```bash
npm run smoke:beta-evaluator
```

The repo script installs the current local CLI package plus first-party
extractor packages, creates a small Express/Prisma source app, extracts
review-only candidates, reviews and adopts the submission bundle, emits agent
context packets, validates the adopted `topo/`, and writes a portable report
under `<tmp>/topogram-beta-evaluator.*/artifacts`.

After publishing, run the same smoke against npm:

```bash
TOPOGRAM_CLI_PACKAGE_SPEC=@topogram/cli@latest npm run smoke:beta-evaluator
```

That one command is the preferred evaluator proof because it removes local repo
state from the app under test. The manual commands below are the same shape to
use when testing a real app.

These are the command surfaces it proves:

```bash
npm install --save-dev @topogram/cli @topogram/extractor-express-api @topogram/extractor-prisma-db
npx topogram doctor
npx topogram extractor recommend ./existing-app --from db,api
npx topogram extractor policy init .
npx topogram extractor policy pin @topogram/extractor-express-api@1 .
npx topogram extractor policy pin @topogram/extractor-prisma-db@1 .
npx topogram extractor check @topogram/extractor-express-api --json
npx topogram extractor check @topogram/extractor-prisma-db --json
npx topogram extract ./existing-app --out ./extracted-topogram --from db,api --extractor @topogram/extractor-express-api --extractor @topogram/extractor-prisma-db --extractor-policy ./topogram.extractor-policy.json --json
npx topogram extract plan ./extracted-topogram --json
npx topogram adopt --list ./extracted-topogram --json
npx topogram adopt bundle:submission ./extracted-topogram --dry-run --json
npx topogram adopt bundle:submission ./extracted-topogram --write --json
npx topogram query extract-plan ./extracted-topogram/topo --json
npx topogram query single-agent-plan ./extracted-topogram/topo --mode extract-adopt --json
npx topogram query slice ./extracted-topogram/topo --entity entity_submission --json
npx topogram check ./extracted-topogram --json
```

That dry run is the release manager's smoke for the core beta story: public CLI,
package-backed extraction, review-only candidates, agent context, and validation.

## Preview Or Deferred

These are important, but should not block beta unless the beta promise changes:

- native SwiftUI generation beyond package-first preview;
- screenshot or visual-diff UI proof;
- locale-specific translation catalogs and runtime i18n adapters;
- automated accessibility audits and manual review evidence;
- enterprise/audit SDLC profiles and immutable history;
- external issue tracker sync;
- package-backed workflow extractors for BPMN, Temporal, XState, Step
  Functions, Camunda, Rails state machines, or Django FSM.

## Release Decision

Call a beta release ready only when:

- the fresh-user dry run passes from npm;
- first-party consumers are green in strict release status;
- proof repos pass their baseline verification;
- docs/RAG checks pass;
- the release page names preview-only areas plainly;
- no open P1/P2 security, path, package-execution, or generated-output boundary
  defects remain.

---

# Source: docs/concepts/what-is-topogram.md

# What Topogram Is

> Topogram is a living app map that gives humans and agents bounded context, contracts, ownership, and proof before they change software.

Status: current
Audience: evaluators, developers, agents, and technical decision makers
Use when: you need the shortest explanation of what Topogram is, what it is not, and why it is useful.

Topogram helps a team answer: what does this app do, who owns each output,
which contracts matter, what can be generated, what must be maintained, and
which proof commands show the change is safe?

## What It Does

- Creates a `topo/` app map with data, API, UI, CLI, runtime, rule, and SDLC
  records.
- Extracts reviewable candidates from brownfield code without mutating the
  source app.
- Promotes only reviewed candidates into canonical `topo/` source.
- Gives agents focused slices, write scope, rules, and verification commands.
- Emits contracts, migration plans, reports, and proof artifacts.
- Generates app/runtime output when ownership is generated.
- Guides maintained app edits when humans or agents own the source.

## What It Is Not

- Not just a code generator. Generation is one output of the app map.
- Not a no-code tool. Humans still review, adopt, and maintain source.
- Not a framework replacement. Generators and maintained apps still use normal
  framework code.
- Not a project manager. SDLC records exist to connect work to requirements,
  proof, and agent context.
- Not a promise of pixel-perfect UI parity. UI beta proof is semantic: contracts,
  display fields, markers, compile checks, and realization reports.

## Best First Demo

Use the brownfield proof when you want to see the main differentiator quickly:

```bash
git clone https://github.com/attebury/topogram-proof-content-approval-brownfield-v3.git
cd topogram-proof-content-approval-brownfield-v3
git checkout proof-03-adopt-app-map
npm install
npm run verify
```

That checkpoint shows existing React/Express/Prisma code becoming reviewed
`topo/` source. Extraction evidence stays separate, the original app remains
maintained, and agents get focused packets before feature work.

## When To Use It

Use Topogram when agents or humans need to make app changes from a smaller,
verified operating surface than the full repository. It is especially useful for
brownfield discovery, generated-to-maintained workflows, database migration
planning, UI contract proof, and teams that want change work tied to explicit
requirements and verification.

---

# Source: docs/start/init-workspace.md

# Init Workspace

> Create an empty Topogram workspace for a greenfield, maintained, existing-app, or spec-only project.

Status: current
Audience: humans and agents starting a Topogram workspace
Use when: you want to model a project yourself instead of copying a template or extracting candidates from brownfield code.

Use this workflow when a repository already exists, when you want to dogfood
Topogram inside a maintained codebase, when you are starting a greenfield app
from your own spec, or when you want a spec-only `topo/` workspace.

`topogram init` is intentionally small. It creates Topogram source and guidance
files, but it does not copy template content, install generator packages, or
write generated app code.

## 1. Initialize

```bash
npm install --save-dev @topogram/cli
npx topogram init . --adopt-sdlc
```

This writes:

- `topo/`
- `topogram.project.json`
- `README.md`, if missing
- `AGENTS.md`, if missing
- `topogram.sdlc-policy.json` and `topo/sdlc/**`, when `--adopt-sdlc` is used
- starter engineering-law records, when `--adopt-sdlc` is used:
  `topo/capabilities/engineering-workflow.tg`,
  `topo/rules/engineering-laws.tg`, and
  `topo/sdlc/decisions/repo-local-laws-are-enforceable.tg`

The command also explains the scaffold in its output:

- human output prints a `Scaffolded:` section with each path, create/reuse
  status, and purpose;
- `--json` output returns `scaffold[]` entries with `path`, `kind`, `status`,
  and `purpose`.

The generated project config marks `.` as maintained ownership. That means
Topogram will not overwrite source files in the repo.

For greenfield generated work, keep the initialized `topo/` as the contract
source, add topology/generator bindings, then use `topogram generate` only after
you explicitly configure generated-owned outputs.

The generated `AGENTS.md` always includes the basic engineering laws: maintain
for long-lived intermittent ownership, keep code testable and security-focused,
prove consumer-visible behavior, start agents from focused context, and use
commands for workflow state. With `--adopt-sdlc`, those laws are also seeded as
queryable `.tg` records.

## 2. Inspect

```bash
topogram agent brief --json
topogram sdlc policy explain --json
topogram check --json
topogram query list --json
```

Agents should start from the brief, then use focused query packets instead of
reading the whole graph.

## 3. Add Topogram source

Edit `topo/**` to describe the project. For small projects, flat folders are
fine. For larger projects, use domain folders under `topo/` as a human and
agent convention; the parser still flattens all statements into one graph.

Use `topogram emit` to inspect contracts, reports, snapshots, and plans:

```bash
topogram emit <target> ./topo --json
```

Use `topogram generate` only after you deliberately configure generated-owned
outputs in `topogram.project.json`.

## 4. Before committing

```bash
topogram check . --json
topogram sdlc check --strict
topogram sdlc prep commit . --json
```

If SDLC is enforced, protected changes need an SDLC item, a `topo/sdlc/**`
record update, or an explicit allowed exemption.

---

# Source: docs/start/greenfield-generate.md

# Greenfield Generate

> Use this workflow when Topogram should realize an app map as generated app or runtime output.

Status: current
Audience: developers and agents creating generated apps
Use when: you want to start from a template or authored Topogram source and generate app/runtime outputs.

Use this workflow when Topogram should realize an app map as generated app or
runtime output. Generation is one Topogram workflow: the same `topo/` map can
also guide maintained code, emit contracts, and give agents focused context.

Start with [Init Workspace](./init-workspace.md) instead when you
want an empty maintained Topogram workspace in an existing repo and do not want
to copy a starter template.

## 1. Create a project

```bash
npm install --save-dev @topogram/cli
npx topogram doctor
npx topogram template list
npx topogram copy hello-web ./my-app
cd ./my-app
npm install
```

`hello-web` is the default small web starter. Other catalog aliases can include
API, database, or native runtimes.

For a blank maintained workspace:

```bash
npx topogram init ./existing-or-empty-repo --adopt-sdlc
cd ./existing-or-empty-repo
topogram check --json
```

`init` writes `topo/` and `topogram.project.json` only. It does not copy a
template, install generators, or generate app code. `--adopt-sdlc` also writes
`topogram.sdlc-policy.json` with adopted/enforced defaults.

## 2. Inspect the project

```bash
npm run agent:brief
npm run explain
npm run doctor
npm run source:status
npm run template:explain
npm run generator:policy:status
npm run generator:policy:check
npm run query:list
```

`source:status` may report no pure Topogram source provenance for projects
created from templates. For template-created projects, `template:explain`,
`template:status`, and trust commands are the relevant template lifecycle
surfaces.

Read:

1. `AGENTS.md`
2. `README.md`
3. `topogram.project.json`
4. `topo/**`

## 3. Edit the source

Edit `topo/**` for the model and `topogram.project.json` for topology,
ownership, ports, and generator bindings.

Do not treat `app/**` as durable source unless its output ownership is
maintained. Generated-owned outputs are replaceable.

## 4. Validate and generate

```bash
npm run check
npm run generate
npm run verify
```

`npm run verify` is the generated project's strongest standard verification
script. If a generated app exposes lower-level app scripts, they remain useful
for focused debugging:

```bash
npm run app:compile
npm run app:runtime
```

## 5. Inspect contracts when needed

```bash
topogram emit ui-widget-contract ./topo --json
topogram emit widget-conformance-report ./topo --projection proj_web_surface --json
topogram emit db-schema-snapshot ./topo --projection proj_db --json
```

`emit` is read-only by default. Add `--write --out-dir <dir>` when you want
artifact files.

## Loop

1. Edit `topo/**` or `topogram.project.json`.
2. Run `topogram check`.
3. Run focused widget/query/SDLC checks when relevant.
4. Run `topogram generate`.
5. Compile or run the generated output.

---

# Source: docs/start/brownfield-import.md

# Brownfield Extract/Adopt

> Extract reviewable Topogram candidates from an existing app, then adopt only what has been reviewed.

Status: current
Audience: developers and agents extracting specs from existing apps
Use when: you want to discover candidates from brownfield code and adopt reviewed Topogram source.

Use this workflow when an app already exists and you want a reviewable app map
before humans or agents change it.

Extract does not mutate the source app.

## Shortest useful path

```bash
topogram extract ./existing-app --out ./imported-topogram
cd ./imported-topogram
topogram extract plan
topogram adopt --list
topogram query extract-plan ./topo --json
topogram query single-agent-plan ./topo --mode extract-adopt --json
topogram check
```

That path gives you candidates, an adoption review surface, agent context, and a
validation gate before any canonical `topo/**` writes beyond extraction output.
For a beta readiness smoke, run the same path from a fresh npm-installed CLI
with at least one package-backed DB/API extractor.

## 1. Extract to a separate workspace

```bash
topogram extract ./existing-app --out ./imported-topogram
cd ./imported-topogram
```

Limit tracks when useful:

```bash
topogram extract ./existing-app --out ./imported-topogram --from db,api,ui
topogram extract ./existing-cli --out ./imported-topogram --from cli
```

Supported tracks are `db`, `api`, `ui`, `cli`, `workflows`, and
`verification`.

Use `workflows` for two cases. First, use it when the source has workflow-owned
evidence such as BPMN, Temporal, XState, Step Functions, Camunda, Rails state
machines, Django FSM, or similar state/orchestration definitions. Second,
ordinary DB/API extraction can produce conservative review-only workflow
candidates when API capabilities map to a DB entity with a `status` or `state`
enum. For broader ordinary app stacks, run the DB, API, UI, CLI, and
verification tracks first; do not expect per-stack extractors to guess workflow
semantics. For the focused workflow-native path, see
[Workflow Extraction](./workflow-extraction.md).

## Choose extractor packs before extraction

Topogram has two extractor sources:

- bundled extractors ship inside `@topogram/cli` and are always available;
- package-backed extractors are npm packages you install and opt into for a
  specific brownfield source.

Use bundled extractors for a first broad pass. Use `topogram extractor
recommend <source>` when you want Topogram to inspect local evidence and suggest
which first-party packages are worth installing before extraction:

```bash
topogram extractor recommend ./existing-app --from db,api,ui,cli,workflows
```

Recommendation is read-only: it does not load extractor adapter code, install
packages, write candidates, or mutate the source app. It only reports likely
bundled and package-backed extractors, evidence, and the next install, pin,
check, and extract commands.

Use package-backed extractor packs when you deliberately want extra
framework-specific discovery beyond the bundled pass. Package-backed extractors
are execution dependencies, not templates: they run only during `topogram
extract`, return review-only candidates, and do not own adoption.

Current first-party package-backed extractors:

| Source evidence | Extractor package | npm version on the current CLI line | Track | Use it for |
| --- | --- | --- | --- | --- |
| Node package CLI code | `@topogram/extractor-node-cli` | `0.1.0` | `cli` | Commands, options, effects, and `cli_surface` candidates |
| React Router route trees | `@topogram/extractor-react-router` | `0.1.1` | `ui` | Screens, routes, non-resource flows, widgets, and UI stack evidence |
| Prisma schema and migrations | `@topogram/extractor-prisma-db` | `0.1.0` | `db` | Entity, enum, relation, index, and maintained DB seam candidates |
| Express routers and route modules | `@topogram/extractor-express-api` | `0.1.0` | `api` | Route, capability, parameter, auth, and stack evidence |
| Drizzle config, schema modules, migrations | `@topogram/extractor-drizzle-db` | `0.1.0` | `db` | Table, relation, index, and maintained DB seam candidates |
| XState state machines | `@topogram/extractor-xstate-workflows` | `0.1.0` | `workflows` | Workflow definition, state, and transition candidates |
| Step Functions ASL definitions | `@topogram/extractor-step-functions-workflows` | `0.1.0` | `workflows` | Workflow definition, state, and transition candidates |

The policy pin uses the extractor manifest version, currently `@1`, not the npm
package version. Install the npm package version you want, then pin the manifest
identity that Topogram is allowed to execute.

`topogram extractor list`, `show`, `check`, and `policy status` report the
version split explicitly:

- manifest version: the adapter contract version pinned by policy, for example `1`;
- package version: the npm package version installed in your project, for example `0.1.1`;
- compatible CLI range: the `@topogram/cli` range declared by the package or inferred for first-party packages;
- policy pin state: whether the reviewed manifest version is pinned, unpinned, mismatched, blocked, or missing.

```bash
topogram extractor list
topogram extractor recommend ./existing-app --from db,api,ui,cli,workflows
topogram extractor show @topogram/extractor-prisma-db
topogram extractor check @topogram/extractor-prisma-db
topogram extractor policy init
topogram extractor policy pin @topogram/extractor-node-cli@1
topogram extractor policy pin @topogram/extractor-react-router@1
topogram extractor policy pin @topogram/extractor-prisma-db@1
topogram extractor policy pin @topogram/extractor-express-api@1
topogram extractor policy pin @topogram/extractor-drizzle-db@1
topogram extractor policy pin @topogram/extractor-xstate-workflows@1
```

Install the packages you plan to execute. Topogram never installs extractor
packages during extraction:

```bash
npm install -D @topogram/extractor-node-cli
npm install -D @topogram/extractor-react-router
npm install -D @topogram/extractor-prisma-db
npm install -D @topogram/extractor-express-api
npm install -D @topogram/extractor-drizzle-db
npm install -D @topogram/extractor-xstate-workflows
```

`topogram extractor check <package>` loads the manifest and adapter, validates
the package shape, and runs a minimal smoke extraction against a synthetic
fixture. It proves the package boundary is executable; it does not prove that
the package understands your application. The real proof is the extract/adopt
review loop below.

Extractor command safety is intentionally staged:

| Command | Loads package code? | Purpose |
| --- | --- | --- |
| `topogram extractor list` | No | Discover bundled and first-party package extractors by track. |
| `topogram extractor show <package>` | No | Read purpose, install command, policy pin, and extract command. |
| `topogram extractor recommend <source>` | No | Inspect source evidence and suggest extractor packages plus next commands. |
| `topogram extractor policy ...` | No | Allow and pin reviewed extractor manifest versions. |
| `topogram extractor check <package>` | Yes | Smoke-test the adapter boundary against a synthetic fixture. |
| `topogram extract ... --extractor <package>` | Yes | Read brownfield source and write review-only candidates. |
| `topogram extract plan` / `topogram adopt --list` | No | Review package provenance, candidate counts, bundles, selectors, and safety notes. |
| `topogram adopt <selector> --dry-run` | No | Preview canonical `topo/**` writes. |
| `topogram adopt <selector> --write` | No | Write only reviewed canonical records. |

Then run extraction with the selected pack:

```bash
topogram extract ./existing-cli --out ./imported-topogram --from cli --extractor @topogram/extractor-node-cli
topogram extract ./react-router-app --out ./imported-topogram --from ui --extractor @topogram/extractor-react-router
topogram extract ./prisma-app --out ./imported-topogram --from db --extractor @topogram/extractor-prisma-db
topogram extract ./express-api --out ./imported-topogram --from api --extractor @topogram/extractor-express-api
topogram extract ./drizzle-app --out ./imported-topogram --from db --extractor @topogram/extractor-drizzle-db
topogram extract ./xstate-app --out ./imported-topogram --from workflows --extractor @topogram/extractor-xstate-workflows
```

Extractor packs return review-only candidates, findings, diagnostics, and
evidence. Topogram core still owns candidate persistence, provenance,
reconcile, adoption, and canonical `topo/**` writes. Extractors must not mutate
the source app, install packages, or perform network access. `topogram
extractor list` shows first-party packages even when they are not installed so
agents can select the right package, install it, pin it in policy, then run
extraction deliberately.

Private extractor packages work the same way. Keep the repo private, install it
explicitly in the consumer project, then pass the installed package name or a
local path:

```bash
npm install -D git+ssh://git@github.com/your-org/topogram-extractor-custom-api.git
topogram extractor check @your-org/topogram-extractor-custom-api
topogram extract ./existing-app --out ./imported-topogram --from api --extractor @your-org/topogram-extractor-custom-api
```

If you do not want package installation yet, use a local path:

```bash
topogram extractor check ../topogram-extractor-custom-api
topogram extract ./existing-app --out ./imported-topogram --from api --extractor ../topogram-extractor-custom-api
```

Policy still controls which manifest versions are allowed to execute. Public
npm publication is optional; deliberate installation and policy review are not.

## 2. Review extraction health

```bash
topogram extract check
topogram extract diff
topogram extract plan
topogram adopt --list
topogram query extract-plan ./topo --json
topogram query single-agent-plan ./topo --mode extract-adopt --json
topogram query multi-agent-plan ./topo --mode extract-adopt --json
topogram query work-packet ./topo --mode extract-adopt --lane adoption_operator --json
```

Agent rule: use the query packets before reading raw candidate JSON. The raw
files are useful when you need evidence details, but `extract-plan`,
`single-agent-plan`, and `work-packet` summarize extractor provenance, safety
notes, candidate counts, and the next review command in a smaller context.

Extract writes:

- `topo/candidates/app/**` for raw candidates;
- `topo/candidates/reconcile/**` for proposal bundles;
- `topogram.project.json` with maintained ownership;
- `.topogram-extract.json` with source hashes from extraction time.

Important JSON fields:

- `workspaceRoot`: the project-owned workspace folder, normally `topo/`;
- `candidateCounts`: counts by extracted surface such as `apiCapabilities`,
  `dbMaintainedSeams`, `uiFlows`, `uiWidgets`, `cliCommands`, and
  `cliSurfaces`;
- `extraction_context`: agent query packet context with extraction provenance,
  package-backed extractor summaries, candidate counts, safety notes, and next
  review commands;
- `nextCommands`: the next review commands Topogram recommends.

Extracted Topogram files are project-owned after creation. Edit candidates and
canonical files freely, but do not hand-edit extraction provenance or adoption
receipts.

DB extraction may also emit maintained migration seam candidates under
`topo/candidates/app/db/candidates.json` as `maintained_seams`. These are
review-only proposals inferred from Prisma, Drizzle, or SQL schema/migration
evidence. They are carried into `topogram extract plan` as a `database` review
bundle, but extraction does not edit `topogram.project.json`, schema files, or
migration files for you.

UI extraction may emit non-resource flow candidates under
`topo/candidates/app/ui/candidates.json` as `flows`. These are conservative,
review-only hints for auth, onboarding/wizard, settings/preferences,
dashboard/reporting, search/filter, and bulk-review routes. They include route
evidence, confidence, missing decisions, and proposed `ui_contract` additions.
Extract plan carries them as UI review packets; adoption writes only reviewed
reports/docs when you explicitly adopt the related selector.

Extract classifies evidence by source type. Runtime source and parser/config
files can create primary candidates. Docs, tests, fixtures, and generated
output can support review evidence, but they should not create high-confidence
API/UI/CLI candidates by themselves.

## 3. Adopt deliberately

Preview first:

```bash
topogram adopt bundle:task --dry-run
topogram adopt widgets --dry-run
topogram adopt bundle:cli --dry-run
topogram adopt cli --dry-run
```

Write only after review:

```bash
topogram adopt bundle:task --write
topogram adopt widgets --write
topogram adopt bundle:cli --write
topogram adopt cli --write
```

`bundle:task` is common for API/UI extraction. `widgets` promotes only widget
candidate files and their related event shapes. `bundle:cli` and `cli` are
common for CLI imports.

For DB seam candidates, review `bundle:database` and manually copy the proposed
runtime migration block into `topogram.project.json` only after confirming the
tool, schema path, migration path, snapshot path, and `apply: "never"` policy.
The DB seam packet includes the proposed `topology.runtimes[...].migration`
target and manual next steps; treat those as instructions, not automation.

Adoption appends receipts to `.topogram-adoptions.jsonl`. Use history to
audit them:

```bash
topogram extract status
topogram extract history --verify
```

## 4. Refresh when source changes

```bash
topogram extract diff
topogram extract refresh . --from ../existing-app --dry-run
topogram extract refresh . --from ../existing-app
topogram extract check
```

Refresh rewrites only candidate/reconcile artifacts and source provenance. It
does not overwrite adopted canonical `topo/**` files.

## 5. Choose the next operating mode

- Generate a new stack from the adopted Topogram.
- Treat the app as maintained and use Topogram to emit contracts, reports, and
  migration proposals while humans or agents edit app code directly.

## Existing app plus an existing Topogram

If you already have a Topogram you want to use inside an existing app, do not
use brownfield extract/adopt first. Initialize the app as maintained, then copy or
merge the reviewed `topo/` files:

```bash
cd ./existing-app
topogram init . --adopt-sdlc
topogram check --json
```

`topogram init` creates maintained ownership for `.`. After that, copy the pure
Topogram workspace into `topo/`, review `topogram.project.json`, run
`topogram check`, and use `topogram emit` for contracts, reports, and migration
proposals. `--adopt-sdlc` opts the repo into enforced SDLC linkage and scaffolds `topo/sdlc/`. Topogram
should not overwrite maintained app source.

---

# Source: docs/start/workflow-extraction.md

# Workflow Extraction

> Extract workflow-native source into reviewable Topogram workflow candidates, then adopt only the reviewed map.

Status: current
Audience: developers and agents extracting workflow state machines or process definitions
Use when: an existing app has source that directly owns workflow states, transitions, orchestration, or process definitions.

Use this path when workflow behavior is encoded in a workflow-native source such
as XState, BPMN, Temporal, Step Functions, Camunda, Rails state machines,
Django FSM, SCXML, or a similar state-machine/process tool.

Do not use ordinary DB, API, UI, or CLI extractors to invent workflow intent.
Those extractors should emit their own track evidence. Topogram can synthesize
some conservative cross-track workflow candidates, but workflow-native
extractor packs are the clearer path when the source already owns the workflow.

## Shortest Useful Path

```bash
npm install -D @topogram/extractor-xstate-workflows
topogram extractor recommend ./xstate-app --from workflows
topogram extractor show @topogram/extractor-xstate-workflows
topogram extractor policy init
topogram extractor policy pin @topogram/extractor-xstate-workflows@1
topogram extractor check @topogram/extractor-xstate-workflows
topogram extract ./xstate-app --out ./extracted-workflows --from workflows --extractor @topogram/extractor-xstate-workflows
cd ./extracted-workflows
topogram extract plan
topogram adopt --list
```

That sequence does four separate things:

- chooses the workflow extractor without executing package code;
- pins the reviewed extractor manifest version;
- runs a package boundary smoke check;
- writes review-only candidates and then shows adoption selectors.

Extractor packages are never installed by `topogram extract`. Install them
deliberately, pin the manifest version deliberately, then run extraction.

## What Gets Extracted

Workflow extractors emit review-only candidate buckets:

- `workflow_definitions`: workflow names, source evidence, and identity hints;
- `workflow_states`: state IDs, labels, types, and source evidence;
- `workflow_transitions`: event names, source state, target state, guards, and evidence.

Topogram core owns persistence, reports, extract plans, adoption, and canonical
`topo/**` writes. Extractor packages return candidates; they do not write the
canonical app map.

## Step Functions V1 Shape

The first-party Step Functions extractor starts with local Amazon States
Language files, not AWS account discovery. V1 reads checked-in JSON or YAML
definitions such as `.asl.json`, `.asl.yaml`, `states.json`, or `states.yaml`.

The extractor should map statically visible state-machine structure into normal
workflow candidate buckets:

- workflow definition from the state-machine `Comment`, file name, or logical id;
- states from `States` keys, including `StartAt`, `Succeed`, `Fail`, `Wait`,
  `Task`, `Choice`, `Map`, `Parallel`, and `Pass`;
- transitions from `Next`, `Default`, `Choices`, `Catch`, `Retry`, branch
  starts, and terminal `End` states where available;
- evidence with project-relative source paths and JSON/YAML pointers.

V1 should not call AWS APIs, read credentials, inspect deployed execution
history, or infer IAM semantics. CloudFormation, CDK, SAM, Serverless, and
Terraform discovery can become separate extractor or preprocessor work after
the local ASL path is useful.

When using a local checkout before an npm release, pass the package directory
as the extractor:

```bash
topogram extractor check ../topogram-extractor-step-functions-workflows
topogram extract ./service --out ./extracted-workflows --from workflows --extractor ../topogram-extractor-step-functions-workflows
```

## Review And Adoption

After extraction, review the candidate plan before adopting:

```bash
topogram extract plan --json
topogram adopt --list --json
topogram adopt workflows --dry-run --json
topogram adopt workflows --write
topogram check --json
```

Use `--dry-run` first. Adoption is the first step that can promote reviewed
workflow candidates into canonical `topo/**` files.

## Agent Context

After adoption, start with the normal agent workflow:

```bash
topogram agent brief --json
topogram query list --json
topogram query single-agent-plan ./topo --mode extract-adopt --json
topogram emit context-slice ./topo --workflow workflow_review --detail compact --json
```

Adopted workflow candidates become graph-native `workflow` records. A workflow
slice includes states, transitions, related context, write-scope guidance, and
proof commands without requiring an agent to infer behavior from Markdown docs.

## Proof Repo

Use the focused proof repo to see the path end to end:

- [XState Workflow Proof](https://github.com/attebury/topogram-proof-xstate-workflow)
- [Step Functions Workflow Proof](https://github.com/attebury/topogram-proof-step-functions-workflow)

The proof starts with an XState app, extracts workflow candidates through
`@topogram/extractor-xstate-workflows`, adopts reviewed workflow records,
uses compact agent context for a maintained source change, and refreshes drift.
The Step Functions proof follows the same path with local Amazon States
Language and `@topogram/extractor-step-functions-workflows`.

## Failure Modes

- The extractor package is not installed: install it explicitly with npm or use
  a local package path.
- The policy pin is missing or mismatched: run `topogram extractor policy pin
  <package>@<manifest-version>`.
- The workflow source is not workflow-native: run DB/API/UI/CLI extraction first
  and treat cross-track workflow candidates as conservative review hints.
- Adoption selectors are unclear: inspect `topogram extract plan --json` and
  `topogram adopt --list --json` before writing.

## Related Docs

- [Brownfield Extract/Adopt](./brownfield-import.md)
- [Extractors](../concepts/extractors.md)
- [Extractor Packs](../authoring/extractor-packs.md)
- [Extract/Adopt JSON](../reference/import-json.md)
- [Proof Walkthrough](../proof-walkthrough.md)

---

# Source: docs/start/database-migrations.md

# Database Migrations

> Use Topogram to plan and verify generated-owned or maintained database migration workflows.

Status: current
Audience: developers maintaining generated or maintained database schemas
Use when: you need database snapshot, migration plan, or SQL migration guidance.

Topogram treats database migration ownership as a runtime decision in
`topogram.project.json`. The `db_contract` describes desired tables, columns,
relations, indexes, and lifecycle intent. The database runtime decides whether
Topogram owns generated migration output or only emits proposals for a
maintained app.

## Generated Runtimes

Use generated ownership when the database lifecycle belongs to the generated app
bundle.

```json
{
  "id": "main_db",
  "kind": "database",
  "projection": "proj_db",
  "migration": {
    "ownership": "generated",
    "tool": "sql",
    "statePath": "app/db/main_db/state",
    "apply": "script"
  }
}
```

In generated mode:

- `topogram generate` can write DB lifecycle files into the generated app.
- lifecycle scripts may apply supported additive SQL migrations.
- destructive or ambiguous migration plans stop for manual review.
- generated state snapshots record what the generated database is expected to
  match.

## Maintained Runtimes

Use maintained ownership when a brownfield or hand-maintained app owns its
schema files, migrations, and migration runner.

```json
{
  "id": "main_db",
  "kind": "database",
  "projection": "proj_db",
  "migration": {
    "ownership": "maintained",
    "tool": "prisma",
    "schemaPath": "apps/api/prisma/schema.prisma",
    "migrationsPath": "apps/api/prisma/migrations",
    "snapshotPath": "topo/state/db/main_db/current.snapshot.json",
    "apply": "never"
  }
}
```

In maintained mode, Topogram emits proposal artifacts only. It does not write to
the configured `schemaPath` or `migrationsPath`, and generated lifecycle scripts
do not apply migrations.

Typical commands:

```bash
topogram emit db-lifecycle-plan --projection proj_db --json
topogram emit db-schema-snapshot --projection proj_db --json
topogram emit db-migration-plan --projection proj_db --from-snapshot ./topo/state/db/main_db/current.snapshot.json --json
topogram emit sql-migration --projection proj_db --from-snapshot ./topo/state/db/main_db/current.snapshot.json --write --out-dir ./db-proposals/sql
topogram emit prisma-schema --projection proj_db --write --out-dir ./db-proposals/prisma
topogram emit drizzle-schema --projection proj_db --write --out-dir ./db-proposals/drizzle
topogram emit db-lifecycle-bundle --projection proj_db --write --out-dir ./db-proposals/lifecycle
```

`db-lifecycle-plan` includes `reviewWorkflow`. For maintained databases, that
section is the handoff checklist: migration tool, trusted current snapshot,
proposal commands, apply boundary, and manual steps for adapting the proposal
into Prisma, Drizzle, or SQL migrations.

Snapshot files passed to `--from-snapshot` are treated as untrusted filesystem
input. Topogram rejects unsafe JSON keys and malformed DB snapshot shapes before
building migration plans or SQL proposals.

The review loop is:

1. Edit `topo/` and run `topogram check`.
2. Emit the desired snapshot, migration plan, and tool-specific proposal.
3. Review the proposal against the maintained app's current schema and
   migrations.
4. Adapt accepted changes into the app's Prisma, Drizzle, or SQL migration
   workflow.
5. Update the trusted snapshot after the app migration has been reviewed and
   applied.

## Imported Maintained DB Seams

Brownfield extract/adopt can infer review-only migration seam candidates for Prisma,
Drizzle, and SQL projects:

```bash
topogram extract ./existing-app --out ./imported-topogram --from db
cd ./imported-topogram
topogram extract plan --json
```

Review:

- `candidateCounts.dbMaintainedSeams` in the import JSON output;
- `topo/candidates/app/db/candidates.json` under `maintained_seams`;
- `topo/candidates/app/db/report.md`;
- the `database` bundle in `topo/candidates/reconcile/**`.

Each candidate includes the inferred tool, schema path, migrations path,
snapshot path, confidence, evidence, missing decisions, and a
`proposed_runtime_migration` block plus manual next steps. Treat that block as
a proposal only. Extraction never patches `topogram.project.json` and never writes
to maintained Prisma, Drizzle, or SQL migration files.

When the candidate is correct, manually add a database runtime migration block
to `topogram.project.json` with `ownership: "maintained"` and `apply: "never"`.
If the candidate reports `missing_decisions`, resolve those first; for example,
a Prisma schema without a migrations directory should not be treated as a
complete migration seam.

The reviewed config target is the matching database runtime under
`topology.runtimes[].migration`, for example:

```json
{
  "id": "app_db",
  "kind": "database",
  "projection": "proj_db",
  "migration": {
    "ownership": "maintained",
    "tool": "prisma",
    "schemaPath": "prisma/schema.prisma",
    "migrationsPath": "prisma/migrations",
    "snapshotPath": "topo/state/db/app_db/current.snapshot.json",
    "apply": "never"
  }
}
```

## Tool Notes

SQL:

- Generated mode can apply supported SQL through generated lifecycle scripts.
- Maintained mode emits SQL proposals for the app's own runner.

Prisma:

- Topogram can emit a proposed `schema.prisma`.
- Maintained apps own `prisma/schema.prisma` and `prisma/migrations/**`.

Drizzle:

- Topogram can emit a proposed Drizzle schema module.
- Maintained apps own the Drizzle schema and Drizzle Kit migration directory.

See [Project Config](../reference/project-config.md#database-migrations) for
the validation rules.

---

# Source: docs/agent-first-run.md

# Agent First Run

> Start agents from the app map, focused query packets, write scope, and proof commands instead of broad repository reads.

Status: current
Audience: coding agents and humans supervising agents
Use when: an agent is entering a Topogram project and needs safe read order, commands, and edit boundaries.

Agents should start from the project briefing and focused query packets. The
goal is to understand the smallest useful part of the app map, the allowed
write scope, and the proof commands before reading broad repository context or
editing code.

## First command

```bash
topogram agent brief --json
```

Generated projects expose the same command as:

```bash
npm run --silent agent:brief
```

`agent brief` is read-only. It validates the Topogram and project config but
does not generate apps, write files, load generator adapters, or execute
template implementation code.

## Read order

1. `AGENTS.md`
2. `README.md`
3. `topogram.project.json`
4. `topogram.sdlc-policy.json`, when present
5. `topogram.template-policy.json`, when present
6. `topogram.generator-policy.json`, when present
7. `.topogram-template-trust.json`, when executable implementation exists
8. `.topogram-extract.json`, when the project came from brownfield extract/adopt
9. Focused `topogram query ... --json` output

## First command sequence

```bash
topogram agent brief --json
topogram query list --json
topogram query show <name> --json
topogram check --json
```

If the project has adopted SDLC and the work is tied to a task or bug, add:

```bash
topogram query sdlc-grooming ./topo --json
topogram query sdlc-backlog ./topo --json
topogram query sdlc-available ./topo --json
topogram query sdlc-ready ./topo --json
topogram sdlc explain <task-id> --json
topogram sdlc start <task-id> . --actor <actor-id> --json
topogram sdlc start <task-id> . --actor <actor-id> --write --json
topogram query slice ./topo --task <task-id> --json
topogram query sdlc-proof-gaps ./topo --task <task-id> --json
topogram query verification-runs ./topo --task <task-id> --json
```

The first `sdlc start` command is read-only and returns the task-start packet.
Use `--write` only after reviewing blockers, ownership, decisions, rules,
plans, and verification targets in that packet.

For journey-oriented workflow context:

```bash
topogram query slice ./topo --journey journey_greenfield_start_from_template --json
```

For implementation planning:

```bash
topogram query single-agent-plan . --mode modeling --capability <capability-id> --json
```

Before commit in an SDLC-adopted project:

```bash
topogram query sdlc-proof-gaps ./topo --task <task-id> --json
topogram sdlc prep commit . --base origin/main --head HEAD --json
topogram sdlc gate . --base origin/main --head HEAD --require-adopted --json
```

## Edit boundaries

Safe default source edits:

- `topo/**`
- `topogram.project.json`
- policy files after review
- `implementation/**` only after reviewing trust state

Generated-owned outputs such as `app/**` are replaceable. Do not make durable
edits there unless the output ownership is maintained.

## Generated project first-run commands

Generated projects usually expose these local scripts:

```bash
npm run agent:brief
npm run doctor
npm run source:status
npm run template:explain
npm run generator:policy:check
npm run check
npm run generate
npm run verify
```

## UI and widgets

For UI work, inspect widget and surface packets:

```bash
topogram widget check ./topo --projection proj_web_surface
topogram widget behavior ./topo --projection proj_web_surface --json
topogram emit ui-widget-contract ./topo --json
```

`ui_contract` owns semantic UI. Concrete web/native surfaces inherit it and own
routes and surface hints.

## Slices and vocabulary

Context slices are intended to be cold-start safe without copying the full
agent brief into every packet. Slices include focused dependencies, standing
rule references, mode-specific next commands, and glossary terms explicitly
linked through `related_terms` or entity `uses_terms`.

Each slice includes a `slice_manifest` that tells an agent what is must-read,
reference-only, proof context, or diagnostic context. Use `--detail compact`
when you need the shortest safe packet, `standard` for normal work, and `full`
when reviewing or debugging the slice itself.

```bash
topogram query slice ./topo --mode implementation --task <task-id> --json
topogram query slice ./topo --mode implementation --task <task-id> --detail compact --format markdown
topogram emit glossary ./topo --json
```

## Brownfield extract/adopt

Before running a package-backed extractor, identify and check the package:

```bash
topogram extractor list
topogram extractor show @topogram/extractor-react-router
npm install -D @topogram/extractor-react-router
topogram extractor policy init
topogram extractor policy pin @topogram/extractor-react-router@1
topogram extractor check @topogram/extractor-react-router
```

The policy pin uses the extractor manifest version, not the npm package
version. `topogram extractor list`, `show`, `check`, and `policy status` report
manifest version, installed package version, compatible CLI range, and policy
pin state before package-backed execution. `topogram extractor check` proves the
package boundary can load and run a minimal smoke extraction; it does not prove
that the package understood the target app. That proof comes from extract/adopt
review packets.

When `.topogram-extract.json` exists:

```bash
topogram extract check . --json
topogram extract diff . --json
topogram extract plan . --json
topogram adopt --list . --json
topogram query extract-plan ./topo --json
topogram query single-agent-plan ./topo --mode extract-adopt --json
topogram query multi-agent-plan ./topo --mode extract-adopt --json
topogram query work-packet ./topo --mode extract-adopt --lane adoption_operator --json
topogram extract status . --json
topogram extract history . --verify --json
```

Use `workspaceRoot` from import JSON as the canonical project-owned workspace
path.

In extract/adopt mode, query packets include `extraction_context` when
`.topogram-extract.json` is present. That context tells an agent which
package-backed extractors ran, how many candidates they produced, where the
trusted extraction record lives, and which review/adoption commands are safe to
run next. Treat extractor output as evidence until `topogram adopt ... --write`
promotes reviewed candidates.

Use query packets before raw `topo/candidates/**` files unless you need the
evidence details for a specific candidate.

## Command-owned state

Use commands for stateful workflow mutations:

- `topogram sdlc transition`
- `topogram sdlc plan step ... --write`
- `topogram sdlc archive`
- `topogram trust ...`
- `topogram extract ...`
- `topogram generate`
- `topogram emit --write`
- `topogram release ...`

Declarative `.tg` source may be edited directly. Status history, provenance,
trust hashes, generated sentinels, archives, and release evidence should not be
hand-edited to make checks pass.

---

# Source: docs/concepts/topogram-model.md

# Topogram Model

> Topogram is a living app map that separates durable intent from stack realization.

Status: current
Audience: humans and agents learning Topogram concepts
Use when: you need the core model before editing specs, generators, extractors, or docs.

Topogram is a living app map. It keeps app intent, contracts, ownership,
runtime topology, rules, and proof in one validated workspace so humans and
agents can reason from bounded context before changing code.

The map can be authored directly, copied from a template, or extracted from a
brownfield app as reviewable candidates. Once validated, it can drive generated
outputs, maintained-app guidance, contracts, migration proposals, and agent
query packets.

## Source

`topo/` contains `.tg` statements and markdown documents. The parser flattens
the folder tree into one graph, so folders are a human and agent convention.
Start with `topogram init` when you want a maintained repo or empty `topo/`
workspace. `topogram init --adopt-sdlc` also adopts enforced SDLC. Use
`topogram copy` when you want to copy a starter template into a generated
project.

Common statement kinds:

- `actor`, `role`, `term`, `domain`
- `entity`, `shape`, `enum`
- `rule`, `capability`, `orchestration`, `verification`
- `widget`, `region_contract`, `layout_contract`, `design_contract`,
  `design_realization_set`
- `journey`, `workflow`
- `projection`
- `decision`
- SDLC kinds: `pitch`, `requirement`, `acceptance_criterion`, `task`, `plan`,
  `bug`

## Project Config

`topogram.project.json` declares:

- workspace path, usually `./topo`;
- output ownership, generated or maintained;
- topology runtimes;
- generator bindings;
- runtime relationships such as `uses_api` and `uses_database`;
- ports and stack-specific runtime settings.

## Contracts And Surfaces

Projection `type` describes the contract or surface:

- `ui_contract` owns semantic UI: screens, layout usage, screen region
  overrides, widget bindings, behavior, visibility, navigation, and design
  tokens.
- `region_contract` and `layout_contract` define reusable semantic work areas
  and templates. They are not DOM, SwiftUI, Android, or CSS layout trees.
- `web_surface`, `ios_surface`, and `android_surface` realize a UI contract for
  a concrete platform.
- `design_contract` owns design-system scope, supported platforms, package
  identity, surfaces, and token names.
- `design_realization_set` maps shared semantic widgets to platform component
  refs and behavior support. The graph is a work map, not a framework render
  tree.
- `api_contract` owns API endpoints and wire contracts.
- `db_contract` owns database tables, columns, relations, indexes, and lifecycle
  intent.
- `cli_surface` owns command-line commands, options, effects, and examples.

## Journeys

`journey` records describe ordered workflows for users, maintainers, and agents.
They use repeated `step { ... }` and `alternate { ... }` blocks so the graph can
preserve sequence, branch points, commands, expected outcomes, and related
capabilities or surfaces.

Canonical journeys are graph-native `.tg` statements. Markdown journey text is
supporting material or an import/reconcile draft until it is reviewed and
promoted into a `journey` record.

## Workflows

`workflow` records describe app-owned state machines and process flows. They use
ordered `state { ... }` and `transition { ... }` blocks so agents can inspect
states, events, guards, linked capabilities, and verification targets without
reading source code or Markdown prose first.

Workflow-native extractors emit reviewable workflow candidates. Adoption turns
reviewed candidates into canonical `workflow` records under `topo/`; subsequent
`query slice --workflow ...` packets provide focused context for maintained
workflow changes and drift review.

## Runtimes

Topology runtimes are deployable or generated units:

- `web_surface`
- `api_service`
- `database`
- `ios_surface`
- `android_surface`

Runtimes bind projections to generators. Generators receive normalized
contracts and write stack-specific output.

## Ownership

Generated outputs can be replaced only when their generated sentinel is present.
Maintained outputs are never overwritten; Topogram can still emit contracts,
reports, checks, and migration proposals for maintained apps.

---

# Source: docs/concepts/topo-workspace.md

# Topo Workspace

> topo/ is the default Topogram workspace folder.

Status: current
Audience: developers and agents working with topo/ source
Use when: you need workspace folder, ownership, and project layout rules.

`topo/` is the default Topogram workspace folder.

```text
my-app/
  topo/
  topogram.project.json
  package.json
  app/
```

`topo/` is source. `app/` is generated output unless
`topogram.project.json` marks that output as maintained.

## Resolution

Commands default to `./topo`. If a command starts from another path, Topogram
looks for `topogram.project.json` and uses its `workspace` field.

Valid project config:

```json
{
  "version": "1",
  "workspace": "./topo",
  "outputs": [],
  "topology": {
    "runtimes": []
  }
}
```

`workspace` must be relative and must not escape the project root. Some package
fixtures use `"workspace": "."`.

## Suggested folders

Small projects can stay flat. Larger projects should group files for humans and
agents:

```text
topo/
  domains/
  shared/
  sdlc/
    pitches/
    requirements/
    acceptance_criteria/
    tasks/
    plans/
    bugs/
    decisions/
  widgets/
  projections/
  verifications/
  docs/
```

Folder layout is not semantic by itself. References inside statements are the
source of truth.

---

# Source: docs/concepts/generate-vs-emit.md

# Generate vs Emit

> Topogram uses two verbs for two different jobs.

Status: current
Audience: developers and agents choosing command verbs
Use when: you need to know whether to write app outputs or inspect contracts/reports.

Topogram uses two verbs for two different jobs.

## Generate

`generate` writes app or runtime output.

```bash
topogram generate
topogram generate ./topo --out ./app
topogram generate app ./topo --out ./app
```

Default input is `./topo`. Default output is `./app`.

Use this when you want generator packages to write web, API, database, or native
runtime files.

## Emit

`emit` prints or writes named artifacts.

```bash
topogram emit ui-widget-contract ./topo --json
topogram emit widget-conformance-report ./topo --projection proj_web_surface --json
topogram emit db-schema-snapshot ./topo --projection proj_db --json
topogram emit sql-migration ./topo --projection proj_db --from-snapshot ./state/current.json
```

`emit` prints to stdout by default. It writes files only with `--write`:

```bash
topogram emit ui-widget-contract ./topo --write --out-dir ./contracts
```

Use this for contracts, reports, snapshots, migration plans, and agent packets.

---

# Source: docs/concepts/templates-catalog.md

# Templates And Catalog

> Templates create starter projects, while the catalog maps stable names to versioned packages.

Status: current
Audience: template users, catalog curators, and agents
Use when: you need to understand templates, catalogs, package provenance, or copy behavior.

Templates create starter projects. The catalog maps stable names to versioned
packages.

## Discover

```bash
topogram template list
topogram copy --list
topogram catalog list
topogram catalog show hello-web
```

## Create from a template

```bash
topogram copy hello-web ./my-app
topogram copy todo ./todo-app
topogram copy @scope/template-package ./my-app
topogram copy ../local-template ./my-app
```

`topogram copy` copies template files, writes project metadata, and installs no
package lifecycle scripts. If a template includes executable `implementation/`
code, the generated project records trust metadata. Generation can be blocked
until that implementation is reviewed and trusted.

Template-created projects use template metadata, not pure Topogram source
provenance. Use:

```bash
topogram template explain
topogram template status
topogram trust status
```

Generated projects may contain `.topogram-template-files.json` as the reviewed
template baseline. They normally do not contain `.topogram-source.json`; that
file belongs to pure Topogram catalog copies.

## Copy a pure Topogram

```bash
topogram copy hello ./hello-topogram
cd ./hello-topogram
topogram source status --local
topogram check
```

Pure Topogram packages contain source for editing. They do not contain
executable `implementation/` code. `catalog copy` records `.topogram-source.json`
so `topogram source status --local` can compare the copied files against their
catalog package source.

## Health

```bash
topogram doctor
topogram catalog doctor
topogram source status --local
topogram source status --remote
```

Public `@topogram/*` packages install from npmjs. Private package consumers use
their registry's normal npm auth.

---

# Source: docs/concepts/generators.md

# Generators

> Generators realize the app map into stack-specific generated output.

Status: current
Audience: generator users and package authors
Use when: you need to understand how generators turn contracts into app/runtime outputs.

Topogram core owns contracts. Generator packages own stack realization.

Before generation, Topogram validates topology, resolves the graph, builds
normalized contracts, and selects the generator bound to each runtime in
`topogram.project.json`.

## Runtime to generator

```json
{
  "id": "app_web",
  "kind": "web_surface",
  "projection": "proj_web_surface",
  "generator": {
    "id": "@topogram/generator-react-web",
    "version": "1",
    "package": "@topogram/generator-react-web"
  },
  "uses_api": "app_api",
  "port": 5173
}
```

The project must install package-backed generators before `check` or
`generate` can load them.

Bundled generators are available with the CLI. Package-backed generators are
normal npm packages that must already be installed. Local generator package
paths are useful for authoring and smoke tests, but production projects should
pin installed packages through generator policy.

## Inspect

```bash
topogram generator list
topogram generator show @topogram/generator-react-web
topogram generator check ./generator-package
topogram generator policy check
```

`generator list` and `generator show` read manifests only. `generator check`
loads package code and runs smoke generation. `topogram generate` loads the
generator selected by `topogram.project.json` runtime bindings.

Generator policy controls which package-backed generators may execute:

```bash
topogram generator policy init
topogram generator policy pin @scope/topogram-generator-web@1
topogram generator policy check --json
```

Topogram does not install generator packages. Install them with npm, pin the
generator manifest version, run `topogram check`, then generate and verify the
resulting app with the stack's own commands.

## Contracts by surface

- Web generators receive `ui-surface-contract` and related API contracts.
- API generators receive server/API contracts and optional database runtime
  context.
- Database generators receive DB contract and lifecycle plan.
- Native generators receive routed UI contracts and related API contracts.

## Authoring Loop

Generator authors should prove both sides of the package:

```bash
topogram generator check ./generator-package
npm pack --dry-run
```

Then test from a clean consumer project:

```bash
npm install --save-dev ./generator-package.tgz
topogram generator policy pin @scope/topogram-generator-web@1
topogram check . --json
topogram generate
npm run verify
```

See [Generator Packs](../authoring/generator-packs.md) for manifest, adapter,
policy, and publish guidance.

---

# Source: docs/concepts/extractors.md

# Extractors

> Extractors read brownfield source and emit review-only candidates for Topogram adoption.

Status: current
Audience: developers, agents, and extractor package authors
Use when: you need to understand what extractors do before selecting, authoring, or trusting an extractor package.

Extractors are execution dependencies for `topogram extract`. They inspect an
existing app and return findings, evidence, and candidates. Topogram core owns
normalization, persistence, reports, reconcile/adoption plans, and canonical
`topo/**` writes.

Extractor packages do not mutate source apps, write canonical Topogram records,
install packages, or perform adoption. They are lower-level discovery
dependencies, while templates are user-facing starting points.

## Workflow Evidence

Ordinary stack extractors should not guess workflows. Prisma, Express, React
Router, and similar packages should emit precise DB, API, UI, CLI, or
verification evidence for their own track. Topogram core performs the
conservative cross-track v1 synthesis: it emits review-only workflow candidates
only when API capabilities map to a DB entity with a `status` or `state` enum.
Broader synthesis across UI, CLI, and verification evidence remains future
work.

Package-backed `workflows` extractors are for workflow-native sources: BPMN,
Temporal, XState, Step Functions, Camunda, Rails state machines, Django FSM,
and similar systems that directly encode states, transitions, orchestration, or
process definitions. Those packages may emit `workflow_definitions`,
`workflow_states`, and `workflow_transitions`, but adoption still remains an
explicit Topogram review step. See [Workflow Extraction](../start/workflow-extraction.md)
for the focused command path.

Step Functions belongs in that workflow-native group when the source includes
local Amazon States Language JSON or YAML. Treat AWS account discovery,
execution history, and credential-backed inspection as later work; extractor v1
should be deterministic and local.

## Design Evidence

Design-system extractors should propose review-only design realization
candidates, not canonical design decisions. Storybook support starts with the
first-party `@topogram/extractor-storybook-design` package. It reads static CSF
story files and only emits `design_realizations` when `parameters.topogram`
explicitly names the widget, design contract, component ref, platform, pattern,
and status. Missing or unsupported story metadata becomes findings for review.

Use it when a component library already documents stable component identities in
Storybook and you want Topogram to carry those mappings into `adopt
design-realizations` review.

Extractor package repos can have their own `llms.txt` and `llms-full.txt`.
Those files describe the package-local authoring and safety surface; they are
separate from the root Topogram repo `llms.txt`. Scaffolded extractor packages
generate package-local docs checks that refuse links or writes outside the
package root.

## Commands

```bash
topogram extractor list
topogram extractor recommend ./existing-app --from db,api,ui,cli,workflows
topogram extractor show @topogram/extractor-prisma-db
topogram extractor policy pin @topogram/extractor-prisma-db@1
topogram extract ./existing-app --out ./extracted-topogram --from db --extractor @topogram/extractor-prisma-db
topogram extractor show @topogram/extractor-xstate-workflows
topogram extractor policy pin @topogram/extractor-xstate-workflows@1
topogram extract ./xstate-app --out ./extracted-topogram --from workflows --extractor @topogram/extractor-xstate-workflows
topogram extractor show @topogram/extractor-storybook-design
topogram extractor policy pin @topogram/extractor-storybook-design@1
topogram extract ./storybook-library --out ./storybook-topogram --from ui --extractor @topogram/extractor-storybook-design
```

## Related Docs

- [Brownfield Extract/Adopt](../start/brownfield-import.md)
- [Workflow Extraction](../start/workflow-extraction.md)
- [Extractor Packs](../authoring/extractor-packs.md)
- [Extract/Adopt JSON](../reference/import-json.md)

---

# Source: docs/widgets.md

# Widgets

> Widgets are Topogram reusable semantic UI contracts, not framework component trees.

Status: current
Audience: UI authors, generator authors, and agents
Use when: you need semantic widget, display-field, behavior, or design-token guidance.

`widget` is Topogram's reusable semantic UI contract. It is not a React,
Svelte, SwiftUI, or Android component. Generators map widget contracts to their
stack.

## Authoring

```text
widget widget_data_grid {
  name "Data Grid"
  description "Reusable tabular display"
  category collection
  props {
    rows array required
    selected_ids array optional default []
  }
  events {
    row_select shape_output_item_card
  }
  patterns [resource_table data_grid_view]
  regions [results toolbar]
  status active
}
```

Place widgets through `widget_bindings` on a `ui_contract` projection. Prefer a
reusable `layout_contract` for screen structure, then bind widgets to inherited
layout regions:

```text
region_contract region_collection_results {
  name "Collection Results"
  description "Primary result area for collection screens."
  kind results
  pattern resource_table
  placement primary
  status active
}

layout_contract layout_collection_list {
  name "Collection List Layout"
  description "Collection screen with result content."
  region {
    id results
    uses region_collection_results
  }
  status active
}

projection proj_ui_contract {
  type ui_contract
  screens {
    screen item_list title "Items" kind list layout layout_collection_list
  }
  widget_bindings {
    screen item_list region results widget widget_data_grid data rows from cap_list_items event row_select navigate item_detail
  }
  status active
}
```

Concrete `web_surface`, `ios_surface`, and `android_surface` projections realize
the shared UI contract. They own routes and surface hints, not widget placement.

`screen_regions` remains available for one-off regions and screen-specific
overrides. It should not be the default way to repeat the same toolbar, filters,
results, content, or footer regions on every screen.

## Display Fields

Topogram beta UI proof uses derived display fields instead of a new display DSL.
`ui-surface-contract` derives fields from screen shapes, capability output
shapes, and widget data bindings. A widget usage includes the data prop, source
capability/shape, source shape, field names, human labels, roles, type, and
requiredness.

Generators must render supported collection widgets from those fields. A table
or board should not guess columns at runtime with `Object.keys(...)`. If
Topogram cannot derive display intent, reports emit diagnostics instead of
silently inventing UI.

## Behavior

Widgets can declare only the canonical behavior vocabulary: `selection`,
`sorting`, `filtering`, `search`, `pagination`, `grouping`, `drag_drop`,
`inline_edit`, `bulk_action`, `optimistic_update`, `realtime_update`, and
`keyboard_navigation`. Projection bindings realize those behaviors by
connecting data, events, navigation, and capabilities.

## Design Contracts

`ui_contract` records define the semantic UI. `design_contract` records own
design-system scope, platforms, package identity, and token mappings.
`design_realization_set` records map semantic widgets to platform component
refs and behavior support.

The graph is not a render tree. It is a work map: layouts compose semantic
regions, screens choose a layout, widgets bind into those regions, and
realization sets show how those widgets are rendered, contract-only,
implementation-owned, or unsupported on each platform.

```text
design_contract design_company_web {
  name "Company Web Design Contract"
  description "Defines company web design-system scope and token names."
  platforms [web]
  surfaces [proj_web_surface]
  library company_web
  package "@company/ui"

  token_mappings {
    color_role danger token "company.color.danger"
    typography_role body token "company.typography.body"
  }

  status active
}

design_realization_set realization_set_company_web_widgets {
  name "Company Web Widget Realizations"
  description "Maps shared widgets to company web component refs."
  design_contract design_company_web
  status active

  widget_realization {
    id review_queue_grid_wide
    widget widget_review_queue
    platform web
    viewport wide
    component_ref "company.reviewQueueGrid"
    pattern resource_table
    density compact
    state_coverage [loading empty error]
    role_contexts [reviewer]
    theme_contexts [light dark]
    locale_contexts [default_locale]
    status rendered
    behaviors_rendered [selection]
    behaviors_contract_only [sorting]
  }

  widget_realization {
    id review_queue_cards_narrow
    widget widget_review_queue
    platform web
    viewport narrow
    component_ref "company.reviewQueueCards"
    pattern card_list
    status contract_only
  }
}
```

Use stable component refs, not local source import paths. A source path may be
evidence in a report or maintained app, but it is not canonical contract
identity. If a widget has no mapping, or if a behavior is `contract_only` or
`unsupported`, `ui-realization-report` and focused UI slices show that as
developer/agent review work.

Use `ui-design-coverage` before claiming design parity. It groups coverage by
platform, surface, and widget, then emits a design matrix for designers and
agents. The matrix includes component refs, viewport, density, state coverage,
token status, accessibility status, i18n status, and review rows for unmapped
widgets, missing platforms, missing states, and `contract_only` or
`unsupported` behavior.
For the end-to-end mapping workflow, see [Map A Design System](./design/map-design-system.md).

## Required checks

These command shapes are covered by regression tests:

```bash
topogram emit ui-widget-contract ./topo --widget widget_data_grid
topogram emit widget-conformance-report ./topo --projection proj_web_surface --json
topogram emit ui-realization-report ./topo --projection proj_web_surface --json
topogram query ui-design-coverage ./topo --projection proj_web_surface --json
topogram query ui-design-coverage ./topo --projection proj_web_surface --format markdown
topogram widget check ./topo --projection proj_web_surface
topogram widget behavior ./topo --projection proj_web_surface --widget widget_data_grid --json
topogram query widget-behavior ./topo --projection proj_web_surface --widget widget_data_grid --json
topogram query slice ./topo --widget widget_data_grid
topogram query slice ./topo --projection proj_web_surface --screen item_list --json
```

Use `--json` for agent packets and `--write --out-dir <dir>` when a report or
contract should be written to disk.

## Migration review

When a widget contract changes against a baseline, use `context-diff` to review
the migration plan:

```bash
topogram emit context-diff ./topo --from-topogram ./baseline/topo --json
```

The `widget_contract_migration_plan` section lists changed widget contract
sections, affected projections, and the exact widget contract, conformance,
behavior, and surface-contract commands to run before regenerating or updating
maintained UI code.

## Generator rule

If a generator accepts a widget pattern, tests should prove it appears in the
normalized contract, `ui-realization-report`, generated coverage, or generated
app output. Generated web wrappers preserve `data-topogram-widget`,
`data-topogram-region`, `data-topogram-screen`, and `data-topogram-display-field`
markers. Generated web output also preserves message and accessibility intent
with `data-topogram-message-key`, `data-topogram-accessibility-target`,
keyboard/focus markers, and locale policy coverage.

Unsupported widget, component, or platform realization is developer/agent review
work. It must be shown as `contract_only`, `unsupported`, or explicit
implementation work in reports and focused slices; it must not silently
disappear or be replaced by an unmarked generic fallback.

## Web UI beta proof

Topogram's beta UI proof is web-first and semantic. React and SvelteKit
generation must preserve the same screens, routes, regions, widget usages,
display fields, behavior coverage, and design-token intent from one
`ui_contract`.

Use these proof commands when UI contracts or generator support change:

```bash
topogram emit ui-surface-contract ./topo --projection proj_web_surface --json
topogram emit ui-realization-report ./topo --projection proj_web_surface --json
topogram query ui-design-coverage ./topo --projection proj_web_surface --json
topogram emit widget-conformance-report ./topo --projection proj_web_surface --json
topogram query slice ./topo --projection proj_web_surface --screen <screen-id> --json
```

The current beta bar is compile plus deterministic contract/coverage assertions.
Semantic i18n and accessibility obligations are part of that contract now.
Screenshot comparison, visual diffing, locale catalog completeness, and
automated accessibility audits are future proof layers.

See [Beta Readiness](./beta-readiness.md) for the release-level UI proof bar and
what remains preview-only.

---

# Source: docs/design/map-design-system.md

# Map A Design System

> Map one semantic UI contract to platform components without turning the graph into a render tree.

Status: current
Audience: designers, front-end leads, design-system maintainers, and agents
Use when: you need to connect Topogram widgets to web, iOS, Android, or desktop component libraries.

Topogram keeps three UI layers separate:

- `ui_contract` owns screens, layout usage, screen region overrides, widget
  placement, actions, messages, and accessibility obligations.
- `region_contract` and `layout_contract` describe reusable semantic work areas
  such as header, nav, content, toolbar, filters, results, and footer actions.
- `design_contract` owns the design-system scope: supported platforms, design
  package identity, and token mappings.
- `design_realization_set` maps semantic widgets to stable platform component
  refs and behavior support.

The graph is not a render tree. It is a work map. Layouts say where work
belongs; widgets say what reusable semantic UI is needed; realization sets say
which design-system components implement those widgets on each platform. A
widget such as `widget_review_queue` should be authored once, then mapped to
the platform components that realize it.

## Five-Minute Review

If you only want to see the practical shape, inspect the focused proof:

```bash
git clone https://github.com/attebury/topogram-proof-widget-design-realization.git
cd topogram-proof-widget-design-realization
npm install
npm run verify
```

Then open:

- `topo/widgets/widget-data-grid.tg`: the semantic widget.
- `topo/design-contracts/design-company-web.tg`: platform and token scope.
- `topo/design-contracts/realization-set-company-web-widgets.tg`: widget-to-platform component mappings.
- `proof/artifacts/ui-design-coverage.md`: the designer-readable matrix.
- `proof/artifacts/widget-slice.json`: the agent packet for changing the widget.

The matrix is the first artifact to read. It groups the widget by platform,
viewport, density, component ref, behavior support, and review state, so design
review starts from a component matrix instead of raw graph records.

## Authoring Pattern

Start with reusable structure and the shared widget:

```text
region_contract region_collection_results {
  name "Collection Results"
  description "Primary collection result area."
  kind results
  pattern resource_table
  placement primary
  states [loading empty error]
  allowed_widget_patterns [resource_table card_list]
  status active
}

layout_contract layout_collection_list {
  name "Collection List Layout"
  description "Collection screen layout with result content."
  region {
    id results
    uses region_collection_results
  }
  status active
}

widget widget_review_queue {
  name "Review Queue"
  description "Reusable queue for reviewing submitted items."
  category collection
  patterns [resource_table card_list]
  regions [results toolbar]
  status active
}

projection proj_ui_contract {
  type ui_contract
  screens {
    screen review_queue title "Review Queue" kind list layout layout_collection_list
  }
  widget_bindings {
    screen review_queue region results widget widget_review_queue data rows from cap_list_items
  }
  status active
}
```

Define the design contract as the platform and token header:

```text
design_contract design_acme_product_ui {
  name "Acme Product UI"
  description "Acme product design-system scope."
  platforms [web ios android]
  library acme_product_ui
  package "@acme/product-ui"

  token_mappings {
    color_role danger token "acme.color.danger"
    typography_role body token "acme.type.body"
    action_role destructive token "acme.action.destructive"
  }

  status active
}
```

Map widgets with a widget-first realization set:

```text
design_realization_set realization_set_review_queue {
  name "Review Queue Realizations"
  description "Maps the Review Queue widget to Acme platform components."
  design_contract design_acme_product_ui
  status active

  widget_realization {
    id review_queue_web_grid
    widget widget_review_queue
    platform web
    viewport wide
    component_ref "acme.reviewQueue.grid"
    pattern resource_table
    density compact
    state_coverage [loading empty error]
    role_contexts [reviewer manager]
    theme_contexts [light dark]
    locale_contexts [default_locale]
    review_notes "Bulk action is contract-only until the grid adapter proves it."
    status rendered
    behaviors_rendered [selection sorting]
    behaviors_contract_only [bulk_action]
  }

  widget_realization {
    id review_queue_ios_list
    widget widget_review_queue
    platform ios
    viewport any
    component_ref "acme.reviewQueue.list"
    pattern card_list
    density comfortable
    state_coverage [loading empty error]
    role_contexts [reviewer]
    theme_contexts [system]
    locale_contexts [default_locale]
    status implementation_owned
    behaviors_rendered [selection]
    behaviors_implementation_owned [bulk_action]
  }

  widget_realization {
    id review_queue_android_cards
    widget widget_review_queue
    platform android
    viewport any
    component_ref "acme.reviewQueue.cards"
    pattern card_list
    density comfortable
    state_coverage [loading]
    role_contexts [reviewer]
    theme_contexts [system]
    locale_contexts [default_locale]
    status unsupported
    behaviors_unsupported [bulk_action]
  }
}
```

Use `component_ref` as a stable design-system identity. Do not use source import
paths such as `src/components/ReviewQueueGrid`. Import paths move when code is
refactored; component refs describe the design-system contract.

## Review Workflow

Run coverage before claiming parity:

```bash
topogram query ui-design-coverage ./topo --projection proj_web_surface --json
topogram emit ui-realization-report ./topo --projection proj_web_surface --json
topogram query slice ./topo --widget widget_review_queue --json
```

Review these states:

- `rendered`: the generator or maintained implementation proves the mapping.
- `contract_only`: the semantic mapping exists, but behavior needs
  implementation or stronger proof.
- `implementation_owned`: maintained/native code owns the realization.
- `unsupported`: the platform does not support that widget or behavior yet.
- missing platform: the design contract declares a platform with no matching
  widget realization.
- missing state: a realization has not declared required loading, empty, or
  error state coverage.
- missing token, accessibility, or i18n: the widget has no mapped design token,
  authored accessibility obligation, or message key evidence.

Unsupported and contract-only entries are developer/agent review work. They
should appear in reports and slices, not disappear behind generic fallback UI.

For designer review, use Markdown:

```bash
topogram query ui-design-coverage ./topo --projection proj_web_surface --format markdown
```

That output is a widget-first matrix. It is easier to read at scale than raw
`.tg` records because each row shows the widget, platform, viewport, density,
component ref, state coverage, and review status.

Use that matrix as the shared review surface:

- designers confirm component refs, states, density, and platform expectations;
- front-end leads confirm whether each component ref is implemented or owned by
  maintained code;
- agents use the review rows to find unsupported, contract-only, missing-state,
  missing-token, missing-i18n, and missing-accessibility work.

## Brownfield Extraction

Extractor packages may propose `design_realizations` candidates when they see a
custom data grid, native list, or bespoke component that appears to implement a
known widget. These candidates are review-only:

```js
return {
  findings: [],
  candidates: {
    design_realizations: [{
      id_hint: "review_queue_web_grid",
      realization_set_id_hint: "realization_set_review_queue",
      design_contract_id_hint: "design_acme_product_ui",
      widget_id: "widget_review_queue",
      platform: "web",
      viewport: "wide",
      component_ref: "acme.reviewQueue.grid",
      pattern: "resource_table",
      status: "rendered",
      behaviors_rendered: ["selection"],
      behaviors_contract_only: ["bulk_action"],
      confidence: "medium",
      evidence: [{ file: "src/review/ReviewQueue.tsx", reason: "Uses Acme ReviewQueueGrid." }],
      missing_decisions: ["Confirm bulk action behavior support."]
    }]
  },
  diagnostics: []
};
```

`topogram adopt design-realizations --write` only writes canonical
`design_realization_set` records after the referenced widget and design contract
exist or are selected in the same adoption plan.

Figma and Storybook are evidence sources, not the design source of truth. The
first Storybook bridge is package-backed and intentionally narrow:
`@topogram/extractor-storybook-design` reads static CSF story files with
explicit `parameters.topogram` metadata and emits review-only
`design_realizations` candidates. It does not run Storybook, parse MDX, use
screenshots, or replace `design_contract` and `design_realization_set`.

A future Figma bridge should also propose component refs and variants from
design component identity, but those proposals should stay review-only until a
human or agent adopts them.

## Proof Commands

For the built-in proof fixture:

```bash
topogram query ui-design-coverage engine/tests/fixtures/workspaces/app-basic --projection proj_web_surface --json
topogram query ui-design-coverage engine/tests/fixtures/workspaces/app-basic --projection proj_web_surface --format markdown
topogram emit ui-realization-report engine/tests/fixtures/workspaces/app-basic --projection proj_web_surface --json
topogram query slice engine/tests/fixtures/workspaces/app-basic --widget widget_data_grid --detail compact --json
```

For project work, replace the fixture path with `./topo`.

---

# Source: docs/concepts/sdlc.md

# SDLC

> Topogram can make project work traceable inside topo/.

Status: current
Audience: maintainers, product owners, and agents using Topogram SDLC
Use when: you need SDLC record meanings, transitions, or proof expectations.

Topogram can make project work traceable inside `topo/`.

Projects opt in with `topogram.sdlc-policy.json`. Missing policy means SDLC
commands still work, but `topogram sdlc gate` reports `not_adopted` unless
`--require-adopted` is passed.

## Adoption Profiles

Topogram's default SDLC profile is `standard`: lightweight, enforced repo
discipline for maintainers and agents. It uses `topogram.sdlc-policy.json`, task
start packets, proof links, `sdlc prep commit`, and `sdlc gate` to keep
non-trivial work traceable without enterprise audit metadata.

The optional `audit` profile is stricter. For protected changes, it requires
task-backed work to declare `risk_class` and `change_type`, have at least one
passing verification run receipt, and keep exemptions tied to a valid SDLC item
with a specific reason. It also surfaces future audit obligations such as
explicit approval/reviewer metadata, release audit-trail exports, and regulated
or signed history profiles. Those obligations should not become the default for
small teams.

Use `mode: "advisory"` when a project wants reports without failures. Regulated
profiles are intentionally deferred until the standard and audit profiles are
coherent.

```json
{
  "version": "1",
  "status": "adopted",
  "mode": "enforced",
  "profile": "standard"
}
```

## Records

Recommended layout:

```text
topo/sdlc/
  pitches/
  requirements/
  acceptance_criteria/
  tasks/
  plans/
  bugs/
  decisions/
  _archive/
```

Use one record per file for SDLC kinds. Plans may contain multiple nested step
definitions.

## Normal loop

```bash
topogram sdlc policy explain --json
topogram query sdlc-backlog ./topo --json
topogram query sdlc-available ./topo --json
topogram query sdlc-ready ./topo --json
topogram sdlc start <task-id> . --actor actor_coding_agent --json
topogram sdlc start <task-id> . --actor actor_coding_agent --write --json
topogram query sdlc-proof-gaps ./topo --task <task-id> --json
topogram query verification-runs ./topo --task <task-id> --json
topogram query sdlc-metrics ./topo --json
topogram query sdlc-stale-work ./topo --json
topogram sdlc prep commit . --base origin/main --head HEAD --json
topogram sdlc gate . --base origin/main --head HEAD --require-adopted --json
```

The default `sdlc start` call is read-only. It returns the task, linked
requirement, acceptance criteria, decisions, rules, blockers, plans, query
commands, write-scope hints, and verification targets. Add `--write` only after
reviewing that packet; the command then owns the legal transition from
`unclaimed` or same-actor `claimed` work to `in-progress`.

## Chain Of Proof

Use the smallest SDLC record that tells the truth:

- `pitch`: why a backlog theme matters.
- `requirement`: durable behavior the project commits to.
- `acceptance_criterion`: observable proof. Approved criteria use
  `Given ... when ... then ...` wording.
- `task`: one implementation-sized slice.
- `verification`: proof command, test, check, or CI gate.
- `decision`: durable choice.
- `bug`: violation of an accepted rule, requirement, or verified expectation.
- `plan`: optional nested execution notes for a task.

Done tasks require valid `satisfies` refs to requirements, approved
`acceptance_refs`, and valid `verification_refs`.

Finite requirements stay `approved` until done tasks prove them, then they can
transition to `satisfied`. Durable operating commitments can transition to
`ongoing`; ongoing requirements must link to at least one rule or verification
and are intentionally omitted from available-work and closeout queues.

Use `topogram query sdlc-grooming ./topo --json` for lifecycle cleanup after
work lands. It shows requirements ready to become `satisfied` or `ongoing`,
pitches ready to become `covered`, plans ready to complete or supersede, and
stale pitches that still need review.

Use `topogram query sdlc-backlog ./topo --json` for unresolved backlog shaping.
It shows draft/shaped/submitted pitches, draft or in-review requirements, draft
journeys, and draft plans. Covered pitches, satisfied requirements, ongoing
requirements, and completed work are intentionally omitted.

Use `topogram query sdlc-ready ./topo --json` before claiming work. It combines
startable tasks, blocked tasks, claimed tasks, proof gaps, latest verification
receipts, risk classification, change type, and next commands.

Before completing work:

```bash
topogram query sdlc-proof-gaps ./topo --task <task-id> --json
topogram sdlc verify record <verification-id> . --task <task-id> --actor actor_coding_agent --command "<command you ran>" --status pass --write --json
topogram sdlc complete <task-id> . --verification <verification-id> --actor actor_coding_agent --write
```

`sdlc verify record` records evidence only; it does not execute commands. It
writes portable JSONL receipts under `topo/sdlc/.topogram-verification-runs.jsonl`.
Use task `risk_class` and `change_type` when the work needs a stronger proof
posture, for example `risk_class high` and `change_type security`.

Use `topogram query sdlc-claimed ./topo --actor <actor-id> --json` to see work
already claimed by an actor. Use `topogram query sdlc-blockers ./topo --task
<task-id> --json` when a task cannot start or complete.

Use `topogram query sdlc-metrics ./topo --json` for counts, WIP, stale work,
closeout candidates, proof gaps, ongoing requirements, and transition-duration
statistics derived from `.topogram-sdlc-history.json`. Use
`topogram query sdlc-stale-work ./topo --json` for the focused stale/WIP policy
view. Projects can optionally add `wipLimits` and `staleWork` thresholds to
`topogram.sdlc-policy.json`; advisory policies warn, enforced policies can fail
protected-change gates unless an allowed exemption is supplied.

## Command-owned state

Humans and agents may edit declarative `.tg` text directly. Use commands for
stateful mutations:

| State | Command path |
| --- | --- |
| `topo/sdlc/.topogram-sdlc-history.json` | `topogram sdlc transition` and `topogram sdlc plan step ... --write` |
| `topo/sdlc/_archive/*.jsonl` | `topogram sdlc archive`, `topogram sdlc unarchive`, and `topogram sdlc compact` |
| `.topogram-template-trust.json` | `topogram trust status`, `topogram trust diff`, and `topogram trust template` |
| `.topogram-template-files.json` | `topogram trust template` and reviewed `topogram template update ...` commands |
| `.topogram-source.json` | `topogram copy` and `topogram source status` |
| `.topogram-extract.json` and `.topogram-adoptions.jsonl` | `topogram extract status` and `topogram extract history --verify` |
| `app/.topogram-generated.json` | `topogram generate` |
| Written emitted artifacts | `topogram emit --write` |
| Release status reports and rollout evidence | `topogram release status` and `topogram release roll-consumers` |

---

# Source: docs/concepts/glossary.md

# Glossary

> Generated from term records in the Topogram workspace. Use this glossary to align humans and agents on current Topogram vocabulary.

Status: current
Audience: humans and agents aligning vocabulary
Use when: you need definitions for Topogram terms used in slices, docs, and SDLC records.

Generated from `term` records in the Topogram workspace. Use `topogram emit glossary ./topo --write --out-dir docs/concepts` to refresh this file.

## Accessibility

### Accessibility Obligation

A semantic promise that a screen, widget, or behavior must be usable by assistive technology and keyboard or alternative input users.

- ID: `term_accessibility_obligation`
- Domain: `dom_generator_runtime`
- Aliases: `a11y_obligation`
- Related terms: `term_ui_contract`, `term_widget`

### Accessible Name

The label or naming source that assistive technologies use to identify an interactive control, region, or widget.

- ID: `term_accessible_name`
- Domain: `dom_generator_runtime`
- Aliases: `aria_label`, `label_source`
- Related terms: `term_accessibility_obligation`, `term_translatable_message`

### Keyboard Interaction

The expected keyboard behavior for a screen or widget, including tab order, arrow-key navigation, escape behavior, activation keys, and shortcuts.

- ID: `term_keyboard_interaction`
- Domain: `dom_generator_runtime`
- Aliases: `keyboard_model`
- Related terms: `term_accessibility_obligation`

### Live Region

A UI area whose changes should be announced to assistive technologies, such as status, validation, loading, or error updates.

- ID: `term_live_region`
- Domain: `dom_generator_runtime`
- Aliases: `announcement_region`, `aria_live`
- Related terms: `term_accessibility_obligation`, `term_translatable_message`

### Semantic Role

The user-facing purpose of a UI element or region, such as button, grid, dialog, form, navigation, status, or alert.

- ID: `term_semantic_role`
- Domain: `dom_generator_runtime`
- Aliases: `aria_role`, `role_intent`
- Related terms: `term_accessibility_obligation`

## Agent Workflow

### Agent Brief

A read-only onboarding packet that tells an agent what to read, which commands to run first, and which project boundaries matter.

- ID: `term_agent_brief`
- Domain: `dom_sdlc_query_agent_context`
- Aliases: `brief`, `first_run_packet`

### Agent Mode

A declared work posture such as modeling, implementation, review, verification, extract-adopt, maintained-app, generated-app, or release.

- ID: `term_agent_mode`
- Domain: `dom_sdlc_query_agent_context`
- Aliases: `task_mode`, `work_mode`
- Related terms: `term_context_slice`

### Agent-Safe Change

A code or Topogram change made from bounded context, explicit write scope, and known verification commands.

- ID: `term_agent_safe_change`
- Domain: `dom_sdlc_query_agent_context`
- Aliases: `safe_agent_change`
- Related terms: `term_context_slice`, `term_verification`

### App Map

The validated Topogram view of an app's intent, contracts, ownership, runtime topology, rules, and proof.

- ID: `term_app_map`
- Domain: `dom_sdlc_query_agent_context`
- Aliases: `living_app_map`
- Related terms: `term_agent_brief`, `term_context_slice`

### Context Slice

A focused app-map packet for one capability, widget, projection, SDLC item, or related target, intended to be small enough for agent work.

- ID: `term_context_slice`
- Domain: `dom_sdlc_query_agent_context`
- Aliases: `focused_packet`, `slice`
- Related terms: `term_agent_brief`, `term_app_map`

### Proof Section

A context-slice section containing verification targets, proof gaps, receipt summaries, or commands needed before work is complete.

- ID: `term_proof_section`
- Domain: `dom_sdlc_query_agent_context`
- Aliases: `proof_context`
- Related terms: `term_context_slice`, `term_slice_manifest`, `term_verification`

### Slice Detail Level

The query slice depth setting that lets agents choose compact, standard, or full context without changing the selected graph focus.

- ID: `term_slice_detail_level`
- Domain: `dom_sdlc_query_agent_context`
- Aliases: `detail_level`, `slice_depth`
- Related terms: `term_context_slice`, `term_slice_manifest`

### Slice Manifest

The read-order map inside a context slice that labels sections as must-read, reference, proof, or diagnostic.

- ID: `term_slice_manifest`
- Domain: `dom_sdlc_query_agent_context`
- Aliases: `read_order`, `section_manifest`
- Related terms: `term_agent_mode`, `term_context_slice`

### Work Map

A graph organized around where product work belongs and how it is proven, not a framework render tree.

- ID: `term_work_map`
- Domain: `dom_generator_runtime`
- Related terms: `term_design_realization_set`, `term_layout_contract`, `term_region_contract`, `term_ui_contract`, `term_widget`

## Extract/Adopt

### Adopted Contract

A reviewed candidate promoted into canonical topo source and treated as project-owned app-map truth.

- ID: `term_adopted_contract`
- Domain: `dom_import_adoption`
- Aliases: `canonical_contract`
- Related terms: `term_adoption`, `term_reviewable_candidate`

### Adoption

The explicit promotion of reviewed extraction candidates into canonical topo source.

- ID: `term_adoption`
- Domain: `dom_import_adoption`
- Related terms: `term_candidate`

### Candidate

A review-only inferred record produced by extraction before it becomes canonical Topogram source.

- ID: `term_candidate`
- Domain: `dom_import_adoption`
- Aliases: `draft_candidate`, `reviewable_candidate`
- Related terms: `term_adoption`, `term_extractor`

### Extractor

A read-only package or built-in adapter that inspects brownfield source and emits candidates, findings, and evidence.

- ID: `term_extractor`
- Domain: `dom_import_adoption`
- Aliases: `extractor_pack`

### Reviewable Candidate

An extraction candidate with evidence that must be reviewed before it becomes canonical Topogram source.

- ID: `term_reviewable_candidate`
- Domain: `dom_import_adoption`
- Aliases: `candidate`
- Related terms: `term_adoption`, `term_candidate`

## Generation

### Emit

The command verb for printing or writing contracts, reports, snapshots, migration plans, and other named artifacts.

- ID: `term_emit`
- Domain: `dom_cli`
- Related terms: `term_generator`

### Generator

A package or bundled adapter that realizes Topogram contracts into app, runtime, API, database, or native output.

- ID: `term_generator`
- Domain: `dom_generator_runtime`
- Aliases: `generator_pack`

### Runtime

A topology unit such as a web surface, API service, database, or native surface that binds a projection to a generator.

- ID: `term_runtime`
- Domain: `dom_generator_runtime`
- Aliases: `topology_runtime`
- Related terms: `term_generator`

## I18n

### Glossary Term

A canonical definition of domain or Topogram vocabulary used to preserve meaning across humans, agents, contracts, and generated or maintained code.

- ID: `term_glossary_term`
- Domain: `dom_sdlc_query_agent_context`
- Aliases: `term`
- Related terms: `term_context_slice`

### Locale Policy

The app-level internationalization expectations for default locale, supported locales, fallback locale, text direction, and date, number, currency, and pluralization behavior.

- ID: `term_locale_policy`
- Domain: `dom_generator_runtime`
- Aliases: `i18n_policy`, `localization_policy`
- Related terms: `term_translatable_message`

### Message Key

A stable identifier for a translatable message that lets generated or maintained app code bind UI copy to localization catalogs without losing semantic context.

- ID: `term_message_key`
- Domain: `dom_generator_runtime`
- Aliases: `i18n_key`, `translation_key`
- Related terms: `term_translatable_message`

### Translatable Message

A user-visible copy contract with a stable key, default source text, usage context, variables, and optional term references.

- ID: `term_translatable_message`
- Domain: `dom_generator_runtime`
- Aliases: `copy_contract`, `message`
- Related terms: `term_glossary_term`, `term_locale_policy`, `term_message_key`

## Ownership

### Enforced Rule

A rule whose obligation currently applies to the project.

- ID: `term_enforced_rule`
- Domain: `dom_engine_quality`
- Aliases: `active_rule`

### Generated-Owned Output

Output that Topogram is allowed to replace from canonical contracts and generator bindings.

- ID: `term_generated_owned_output`
- Domain: `dom_workspace_project_config`
- Aliases: `generated_output`

### Maintained Output

Project source that humans or agents edit directly; Topogram can emit guidance but must not overwrite it.

- ID: `term_maintained_output`
- Domain: `dom_workspace_project_config`
- Aliases: `maintained_source`
- Related terms: `term_generated_owned_output`

### Proof Command

A command that validates an app-map expectation, generated output, maintained change, or SDLC state.

- ID: `term_proof_command`
- Domain: `dom_engine_quality`
- Aliases: `proof_gate`, `verification_command`
- Related terms: `term_agent_safe_change`, `term_verification`

## SDLC

### Acceptance Criterion

An observable Given/when/then proof condition attached to a requirement.

- ID: `term_acceptance_criterion`
- Domain: `dom_sdlc_query_agent_context`
- Aliases: `ac`, `acceptance`
- Related terms: `term_requirement`, `term_verification`

### Ongoing Requirement

A durable operating commitment that stays enforced through linked rules or verification rather than closing as satisfied.

- ID: `term_ongoing_requirement`
- Domain: `dom_sdlc_query_agent_context`
- Related terms: `term_enforced_rule`, `term_requirement`

### Pitch

An SDLC record that explains why a problem matters, the appetite for solving it, and traps to avoid.

- ID: `term_pitch`
- Domain: `dom_sdlc_query_agent_context`
- Aliases: `problem_framing`

### Requirement

An SDLC commitment that describes behavior or policy Topogram should satisfy until it is satisfied, superseded, or marked ongoing.

- ID: `term_requirement`
- Domain: `dom_sdlc_query_agent_context`
- Related terms: `term_acceptance_criterion`

### Task

A small implementation slice that satisfies requirements, references approved acceptance criteria, and closes with verification proof.

- ID: `term_task`
- Domain: `dom_sdlc_query_agent_context`
- Related terms: `term_acceptance_criterion`, `term_requirement`, `term_verification`

### Verification

A proof target or check that demonstrates an accepted expectation holds.

- ID: `term_verification`
- Domain: `dom_sdlc_query_agent_context`
- Aliases: `proof_gate`

## UI Widgets

### Component Ref

A stable design-contract identity for a platform component, independent of local source import paths.

- ID: `term_component_ref`
- Domain: `dom_generator_runtime`
- Related terms: `term_design_contract`, `term_design_matrix`

### Design Contract

A Topogram record that owns design-system scope, platforms, surfaces, package identity, and design-token mappings for semantic UI realization.

- ID: `term_design_contract`
- Domain: `dom_generator_runtime`
- Related terms: `term_design_realization_set`, `term_platform_realization`, `term_ui_contract`, `term_widget`

### Design Matrix

A widget-first coverage view that groups component refs, platforms, viewports, density, state coverage, token status, accessibility status, i18n status, and review gaps for design work.

- ID: `term_design_matrix`
- Domain: `dom_generator_runtime`
- Related terms: `term_component_ref`, `term_design_contract`, `term_design_realization_set`, `term_widget`

### Design Realization Set

A widget-first group of platform component refs and behavior support for one design contract.

- ID: `term_design_realization_set`
- Domain: `dom_generator_runtime`
- Related terms: `term_component_ref`, `term_design_contract`, `term_design_matrix`, `term_platform_realization`, `term_widget`

### Design Review Gap

A missing or incomplete design realization signal, such as unsupported behavior, contract-only behavior, missing platform, missing state, missing token mapping, missing accessibility obligation, or missing i18n message.

- ID: `term_design_review_gap`
- Domain: `dom_generator_runtime`
- Related terms: `term_accessibility_obligation`, `term_design_matrix`, `term_platform_realization`, `term_translatable_message`

### Layout Contract

A reusable semantic template that composes region contracts for screens without defining a framework render tree.

- ID: `term_layout_contract`
- Domain: `dom_generator_runtime`
- Aliases: `screen_template`, `semantic_layout`
- Related terms: `term_region_contract`, `term_ui_contract`, `term_widget`, `term_work_map`

### Platform Realization

The way a semantic UI widget, behavior, or design-token role is rendered, carried as contract-only, owned by implementation code, or left unsupported for a specific platform.

- ID: `term_platform_realization`
- Domain: `dom_generator_runtime`
- Related terms: `term_design_contract`, `term_surface`

### Region Contract

A reusable semantic work area, such as content, toolbar, filters, results, navigation, or footer actions, with design, accessibility, i18n, state, and allowed-widget expectations.

- ID: `term_region_contract`
- Domain: `dom_generator_runtime`
- Aliases: `semantic_region`, `work_area`
- Related terms: `term_layout_contract`, `term_ui_contract`, `term_widget`, `term_work_map`

### Surface

A concrete projection such as web_surface or ios_surface that realizes a platform-neutral contract for a target platform.

- ID: `term_surface`
- Domain: `dom_generator_runtime`
- Related terms: `term_ui_contract`

### UI Contract

The platform-neutral UI projection that owns screens, layout usage, screen region overrides, widget bindings, navigation, behavior, and semantic design intent.

- ID: `term_ui_contract`
- Domain: `dom_generator_runtime`
- Related terms: `term_layout_contract`, `term_region_contract`, `term_widget`

### Widget

A reusable semantic UI contract that can bind to screens and regions without naming a framework component tree. Unsupported widget realization must be visible as contract-only, unsupported, or explicit implementation work for developer and agent review.

- ID: `term_widget`
- Domain: `dom_generator_runtime`
- Aliases: `semantic_component`

---

# Source: docs/reference/cli.md

# CLI Reference

> Public Topogram commands are organized around init, copy, extract, adopt, generate, emit, query, and policy workflows.

Status: current
Audience: CLI users and agents executing Topogram commands
Use when: you need public command syntax, options, or examples.

Run `topogram help <command>` for command-specific help. This page gives the
current command map.

## Setup and health

```bash
topogram version
topogram doctor
topogram setup package-auth
topogram setup catalog-auth
```

## Project creation

```bash
topogram init
topogram init . --adopt-sdlc
topogram init ./existing-app --json
topogram template list
topogram copy --list
topogram copy hello-web ./my-app
topogram catalog list
topogram catalog show <id>
topogram copy <id> <target>
```

Use `topogram init` first for existing or maintained repos. Use `topogram copy`
when you want to copy a starter template and generate an app/runtime bundle.
Successful `init` output includes a `Scaffolded:` summary; JSON output includes
`scaffold[]` entries with each path, kind, status, and purpose.

Remote catalog and GitHub reads are size-limited before parsing. Override the
default only when you have reviewed the source. These can be set in the
environment or in `topogram.config.json` under `limits`.

- `TOPOGRAM_REMOTE_FETCH_MAX_BYTES`
- `TOPOGRAM_CATALOG_FETCH_MAX_BYTES`
- `TOPOGRAM_GITHUB_FETCH_MAX_BYTES`

## Validation and output

```bash
topogram check
topogram generate
topogram generate ./topo --out ./app
topogram emit <target> ./topo --json
topogram emit <target> ./topo --write --out-dir ./artifacts
topogram emit glossary ./topo --write --out-dir docs/concepts
topogram emit glossary ./topo --check docs/concepts/glossary.md
```

## Agent and query

```bash
topogram agent brief --json
topogram query list --json
topogram query show <name> --json
topogram query slice ./topo --task <task-id> --json
topogram query slice ./topo --task <task-id> --detail compact --format markdown
topogram query slice ./topo --journey journey_greenfield_start_from_template --json
topogram query sdlc-grooming ./topo --json
topogram query sdlc-backlog ./topo --json
topogram query sdlc-available ./topo --json
topogram query sdlc-ready ./topo --json
topogram query sdlc-claimed ./topo --actor actor_coding_agent --json
topogram query sdlc-blockers ./topo --task <task-id> --json
topogram query sdlc-proof-gaps ./topo --task <task-id> --json
topogram query verification-runs ./topo --task <task-id> --json
topogram query sdlc-metrics ./topo --json
topogram query sdlc-stale-work ./topo --json
```

## SDLC

```bash
topogram sdlc policy explain --json
topogram sdlc start <task-id> . --actor actor_coding_agent --json
topogram sdlc start <task-id> . --actor actor_coding_agent --write --json
topogram sdlc verify record <verification-id> . --task <task-id> --actor actor_coding_agent --command "<command you ran>" --status pass --write --json
topogram sdlc complete <task-id> . --verification <verification-id> --actor actor_coding_agent --write
topogram sdlc prep commit . --base origin/main --head HEAD --json
topogram sdlc gate . --base origin/main --head HEAD --require-adopted --json
```

`sdlc start` is read-only by default. It returns the implementation packet for a
task; `--write` claims and starts the task through command-owned history.

## Widgets

```bash
topogram widget check ./topo --projection proj_web_surface
topogram widget behavior ./topo --projection proj_web_surface --json
topogram emit ui-widget-contract ./topo --widget widget_data_grid --json
topogram emit glossary ./topo --json
```

## Brownfield extract/adopt

```bash
topogram extract ./existing-app --out ./imported-topogram
topogram extract ./existing-cli --out ./imported-topogram --from cli --extractor @topogram/extractor-node-cli
topogram extract ./react-router-app --out ./imported-topogram --from ui --extractor @topogram/extractor-react-router
topogram extract ./prisma-app --out ./imported-topogram --from db --extractor @topogram/extractor-prisma-db
topogram extract ./express-api --out ./imported-topogram --from api --extractor @topogram/extractor-express-api
topogram extract ./drizzle-app --out ./imported-topogram --from db --extractor @topogram/extractor-drizzle-db
topogram extract ./xstate-app --out ./imported-topogram --from workflows --extractor @topogram/extractor-xstate-workflows
topogram extractor list
topogram extractor recommend ./existing-app --from db,api,ui,cli,workflows
topogram extractor show @topogram/extractor-prisma-db
topogram extractor show @topogram/extractor-xstate-workflows
topogram extractor show topogram/ui-extractors
topogram extractor check @topogram/extractor-prisma-db
topogram extractor check ./extractor-package
topogram extractor init ./extractor-package --track cli --package @scope/extractor-package
topogram extractor policy init
topogram extractor policy pin @topogram/extractor-prisma-db@1
topogram extractor policy pin @topogram/extractor-xstate-workflows@1
topogram extractor policy check
topogram extract check ./imported-topogram
topogram extract plan ./imported-topogram
topogram adopt --list ./imported-topogram
topogram query extract-plan ./imported-topogram/topo --json
topogram query single-agent-plan ./imported-topogram/topo --mode extract-adopt --json
topogram query multi-agent-plan ./imported-topogram/topo --mode extract-adopt --json
topogram query work-packet ./imported-topogram/topo --mode extract-adopt --lane adoption_operator --json
topogram adopt <selector> ./imported-topogram --dry-run
topogram adopt <selector> ./imported-topogram --write
topogram extract status ./imported-topogram
topogram extract history ./imported-topogram --verify
```

`topogram extractor init` also reports a `Scaffolded:` summary and returns
`scaffold[]` in JSON mode so extractor authors can see the generated package
shape and why each file exists.

Extractor command safety: `extractor list`, `extractor show`, and
`extractor recommend`, and `extractor policy` do not load package adapter code.
`extractor recommend <source>` only reads local source evidence and reports
likely bundled/package-backed extractors plus install, pin, check, and extract
commands. `extractor check` and `extract --extractor` do load package adapter
code. Extractor packages write review-only candidates; `adopt --dry-run` should
precede any canonical `--write`. Extractor package output distinguishes manifest
version, npm package version, compatible CLI range, and policy pin state so
humans and agents can choose the exact install or pin command before execution.

## Policies and trust

```bash
topogram trust status
topogram trust diff
topogram trust template
topogram template policy check
topogram generator list
topogram generator show @topogram/generator-react-web
topogram generator check ./generator-package
topogram generator policy check
topogram generator policy pin @scope/topogram-generator-web@1
topogram extractor list
topogram extractor policy check
topogram sdlc policy explain
```

Generator command safety: `generator list` and `generator show` read manifests
only. `generator check` and `topogram generate` load generator package code.
Topogram does not install generator packages; install them with npm, pin their
manifest version through `topogram.generator-policy.json`, run `topogram check`,
then verify generated output with the stack's own commands.

## Maintainers

```bash
topogram release status
topogram release status --strict
topogram release roll-consumers --latest
topogram package update-cli --latest
```

`topogram release roll-consumers --latest --watch` is the maintainer command for
rolling first-party consumers after a CLI publish. Human output includes a
recovery summary, and progress is printed to stderr so JSON output stays
machine-readable. Use `--no-watch` to push consumer commits without waiting for
CI, then run `topogram release status --strict`.

`topogram release status --strict` requires the current checkout to match the
current package version's remote release tag. If new commits have landed after
the latest `topogram-v*` tag, strict mode fails until a new patch release is
cut or the checkout is moved back to the released commit.

`topogram release status --strict` also checks public proof repositories in a
separate proof-consumer section. Those repos are not rolled by
`roll-consumers`; they are tutorial/product proof repos, so release status
checks their configured proof baseline, `proof:audit` and `verify` scripts, and
Proof Verification workflow state separately from package rollout consumers.
Proof repos do not need to move on every patch release; refresh them when a
workflow meaning changes, a breaking change lands, or a proof would teach stale
behavior.

---

# Source: docs/reference/dsl.md

# DSL Reference

> Topogram files use .tg statements:

Status: current
Audience: Topogram authors and tooling implementers
Use when: you need DSL statement and field reference material.

Topogram files use `.tg` statements:

```text
kind identifier {
  field value
  block_field {
    entry values
  }
}
```

The parser accepts generic statement syntax. The validator defines the public
grammar.

## Statement kinds

- `term`
- `actor`
- `role`
- `enum`
- `entity`
- `shape`
- `rule`
- `capability`
- `widget`
- `region_contract`
- `layout_contract`
- `design_contract`
- `design_realization_set`
- `journey`
- `workflow`
- `decision`
- `projection`
- `orchestration`
- `verification`
- `operation`
- `domain`
- `pitch`
- `requirement`
- `acceptance_criterion`
- `task`
- `plan`
- `bug`

Documents are markdown files with frontmatter under `topo/docs/**`.

## Rule status

Rules use a rule-specific lifecycle: `draft`, `proposed`, `enforced`, and
`deprecated`. Use `status enforced` for rules that currently apply. Other graph
kinds may still use `status active` where their lifecycle allows it.

## Terms and Glossary

`term` records define project vocabulary. They are graph-native, can be grouped
with `category`, and can be tied to a domain with `domain`. Other records can
reference slice-relevant vocabulary through `related_terms`; entities also keep
`uses_terms` for business/domain language.

```tg
term term_context_slice {
  name "Context Slice"
  description "A focused graph packet for one implementation target."
  category agent_workflow
  domain dom_sdlc_query_agent_context
  aliases [slice focused_packet]
  status active
}

capability cap_query_context {
  name "Query Focused Context"
  description "List and show focused query packets."
  related_terms [term_context_slice]
  status active
}
```

Emit the human glossary from term records:

```bash
topogram emit glossary ./topo --write --out-dir docs/concepts
topogram emit glossary ./topo --check docs/concepts/glossary.md
```

## Projection types

- `ui_contract`
- `web_surface`
- `ios_surface`
- `android_surface`
- `api_contract`
- `db_contract`
- `cli_surface`

## UI ownership

`ui_contract` owns semantic UI blocks:

- `screens`
- `screen_regions`
- `navigation`
- `app_shell`
- `collection_views`
- `screen_actions`
- `visibility_rules`
- `field_lookups`
- `widget_bindings`
- `design_tokens`
- `messages`
- `accessibility`

Screens may reference reusable semantic layouts with `layout <layout_contract>`.
Those layouts inherit reusable regions from `region_contract` records.
`screen_regions` remains available for one-off regions and per-screen
overrides.

Concrete surfaces own routes and hints:

- `screen_routes`
- `web_hints`
- `ios_hints`

`messages` models translation intent, not locale catalogs:

```tg
messages {
  locale default "en-US" fallback "en-US" direction ltr supported ["en-US"]
  message msg_item_list_title key "items.list.title" default "Items" context screen_title screen item_list
  message msg_items_table_label key "items.table.label" default "Items table" context widget_label widget widget_data_grid
}
```

`accessibility` models obligations, not raw `aria-*` attributes:

```tg
accessibility {
  screen item_list role main name_from message msg_item_list_title keyboard standard focus visible live off
  widget widget_data_grid role grid name_from message msg_items_table_label keyboard data_grid focus roving_tabindex live off
}
```

`region_contract` defines a reusable semantic work area. It is not a DOM node,
component, or CSS class.

```tg
region_contract region_collection_results {
  name "Collection Results"
  description "Primary result collection area for list, board, and calendar screens."
  kind results
  pattern resource_table
  placement primary
  states [loading empty error]
  density comfortable
  style_intent [surface scannable]
  accessibility_obligations [region_label keyboard_reachable]
  i18n_obligations [empty_state_copy]
  allowed_widget_patterns [resource_table card_list calendar]
  status active
}
```

`layout_contract` composes region contracts into a reusable semantic template.
Layouts are semantic templates, not framework templates.

```tg
layout_contract layout_collection_list {
  name "Collection List Layout"
  description "Standard collection screen with toolbar, filters, and results."
  parent layout_standard_app_shell
  fills content

  region {
    id toolbar
    uses region_action_toolbar
    placement top
  }

  region {
    id filters
    uses region_filter_panel
    placement secondary
  }

  region {
    id results
    uses region_collection_results
    placement primary
  }

  status active
}
```

`ui_contract` screens reference the layout. Widget bindings may target inherited
layout regions or explicit `screen_regions` overrides:

```tg
screens {
  screen item_list title "Items" kind list layout layout_collection_list
}

widget_bindings {
  screen item_list region results widget widget_data_grid data rows from cap_list_items event row_select navigate item_detail
}
```

`design_contract` owns design-system scope, supported platforms, optional
surface bindings, package identity, and design-token mappings. Real projects
should keep widget/component mappings in `design_realization_set` records so the
contract header stays small at scale.

```tg
design_contract design_company_web {
  name "Company Web Design Contract"
  description "Defines company web design-system scope and token names."
  platforms [web]
  surfaces [proj_web_surface]
  library company_web
  package "@company/ui"

  token_mappings {
    color_role danger token "company.color.danger"
    typography_role body token "company.typography.body"
  }

  status active
}
```

`design_realization_set` maps semantic widgets to platform component refs and
behavior support. The graph is not a render tree; it is a work map that shows
where design/platform realization work belongs and what still needs review.

```tg
design_realization_set realization_set_company_web_widgets {
  name "Company Web Widget Realizations"
  description "Maps shared widgets to company web component refs."
  design_contract design_company_web
  status active

  widget_realization {
    id data_grid_wide
    widget widget_data_grid
    platform web
    viewport wide
    component_ref "company.dataGrid"
    pattern data_grid_view
    density compact
    state_coverage [loading empty error]
    role_contexts [reviewer]
    theme_contexts [light dark]
    locale_contexts [default_locale]
    review_notes "Sorting is still contract-only until the adapter proves it."
    status rendered
    behaviors_rendered [selection]
    behaviors_contract_only [sorting]
  }
}
```

Supported design-contract platforms are `web`, `ios`, and `android`.
Widget realization statuses are `rendered`, `contract_only`,
`implementation_owned`, and `unsupported`. Realization entries may also carry
review metadata: `density`, `state_coverage`, `role_contexts`,
`theme_contexts`, `locale_contexts`, and `review_notes`. Realization entries
must use `component_ref`; `import_path`, `source_path`, and `path` are rejected
as canonical identity. Component and behavior mappings belong in
`design_realization_set`, not in `design_contract`.

Use `topogram query ui-design-coverage ./topo --projection <surface> --json` to
review the JSON design matrix, or `--format markdown` for a designer-readable
table. The matrix surfaces unmapped widgets, missing platforms, missing states,
missing token mappings, missing accessibility obligations, missing i18n
messages, and contract-only or unsupported behavior from authored design
contracts and realization sets.

## API blocks

`api_contract` projections use blocks such as `endpoints`, `wire_fields`,
`responses`, `error_responses`, `preconditions`, `idempotency`, `cache`,
`delete_semantics`, `async_jobs`, `async_status`, `downloads`,
`authorization`, and `callbacks`.

## DB blocks

`db_contract` projections use `tables`, `columns`, `keys`, `indexes`,
`relations`, and `lifecycle`.

## CLI surface blocks

`cli_surface` projections use `commands`, `command_options`, `command_outputs`,
`command_effects`, and `command_examples`.

Allowed command effects are `read_only`, `writes_workspace`, `writes_app`,
`network`, `package_install`, `git`, and `filesystem`.

## Journeys

`journey` statements model ordered user, maintainer, or agent workflows as graph
source. Canonical journeys live in `.tg` files, usually under `topo/journeys/`.
Markdown journey documents are transitional/supporting drafts produced by import
or reconcile workflows; promote durable journeys into graph-native `journey`
records.

Required fields:

- `name`
- `description`
- `status`
- `actors`
- `goal`
- at least one `step { ... }`

Allowed statuses are `draft`, `canonical`, `active`, and `deprecated`.

Relationship fields may include `domain`, `roles`, `related_capabilities`,
`related_rules`, `related_projections`, `related_widgets`,
`related_verifications`, `related_decisions`, and `related_docs`.

Journey steps and alternates use repeated ordered record blocks. The parser
syntax is the normal block syntax; validators preserve source order and enforce
known record fields.

```tg
journey journey_greenfield_start_from_template {
  name "Greenfield Start From Template"
  description "A developer starts a new app from a template."
  status canonical
  domain dom_catalog_templates
  actors [actor_consumer_developer]
  goal "Create a valid generated app from a copied Topogram starter."

  step {
    id inspect_templates
    intent "Find available templates."
    commands ["topogram template list --json"]
    expects ["Template aliases and package-backed entries are visible."]
  }

  step {
    id create_project
    intent "Copy the selected template into a project."
    after [inspect_templates]
    commands ["topogram copy hello-web ./my-app"]
    expects ["Project contains topo/, topogram.project.json, README.md, and AGENTS.md."]
  }

  alternate {
    id use_package_spec
    from inspect_templates
    condition "The desired template is not in the catalog."
    commands ["topogram copy @topogram/template-hello-web ./my-app"]
  }
}
```

`step` records support `id`, `intent`, `after`, `commands`, `expects`, and
`notes`. `alternate` records support `id`, `from`, `condition`, `commands`,
`expects`, and `notes`. Step IDs must be unique, `after` must reference existing
steps, and `alternate.from` must reference an existing step.

## Workflows

`workflow` statements model application state machines or process flows as graph
source. Use them when the app itself has states and transitions, such as review
lifecycles, approval flows, XState machines, BPMN processes, or other
workflow-native sources.

Required fields:

- `name`
- `description`
- `status`
- at least one `state { ... }`

Allowed statuses use the normal graph lifecycle: `draft`, `proposed`, `active`,
and `deprecated`.

Relationship fields may include `domain`, `actors`, `roles`,
`related_capabilities`, `related_rules`, `related_entities`,
`related_journeys`, `related_verifications`, `related_decisions`, and
`related_docs`.

Workflow states and transitions use repeated ordered record blocks. Validators
preserve source order, require unique IDs, and check transition state and
capability references.

```tg
workflow workflow_review {
  name "Review Workflow"
  description "Tracks an item from draft through review and approval."
  status active
  actors [actor_reviewer]
  related_capabilities [cap_submit_item cap_approve_item]

  state {
    id draft
    name "Draft"
    type initial
  }

  state {
    id submitted
    name "Submitted"
  }

  state {
    id approved
    name "Approved"
    type terminal
  }

  transition {
    id submit
    from draft
    to submitted
    event "SUBMIT"
    capability cap_submit_item
  }

  transition {
    id approve
    from submitted
    to approved
    event "APPROVE"
    capability cap_approve_item
  }
}
```

`state` records support `id`, `name`, `description`, and `type`. State types are
`normal`, `initial`, `terminal`, `final`, and `error`. `transition` records
support `id`, `from`, `to`, `event`, `capability`, `guard`, `actors`, `roles`,
and `description`. `to` is required; `from` may be omitted for entry or start
transitions.

Workflow slices are available through:

```bash
topogram query slice ./topo --workflow workflow_review --detail compact --json
topogram emit context-slice ./topo --workflow workflow_review --detail compact --json
```

---

# Source: docs/reference/project-config.md

# Project Config

> topogram.project.json declares how a project uses a topo/ workspace.

Status: current
Audience: project maintainers and agents editing topogram.project.json
Use when: you need project config, topology, workspace, or ownership reference.

`topogram.project.json` declares how a project uses a `topo/` workspace.

Minimal shape:

```json
{
  "version": "1",
  "workspace": "./topo",
  "outputs": [
    {
      "id": "app",
      "path": "./app",
      "ownership": "generated"
    }
  ],
  "topology": {
    "runtimes": []
  }
}
```

## Workspace

`workspace` defaults to `./topo`. It must be relative and cannot escape the
project root. Package fixtures may use `"."`.

## Outputs

Outputs are either:

- `generated`: Topogram may replace the output when the generated sentinel is
  present.
- `maintained`: Topogram never overwrites it; emit contracts/reports instead.

## Runtimes

Runtime kinds:

- `web_surface`
- `api_service`
- `database`
- `ios_surface`
- `android_surface`

References:

- `uses_api` links web/native surfaces to an API runtime.
- `uses_database` links API services to a database runtime.

Each runtime can bind a package-backed or bundled generator.

## Database Migrations

Database runtimes can declare an optional `migration` strategy. This makes the
database ownership boundary explicit without changing the stack-neutral
`db_contract`.

Generated database runtime:

```json
{
  "id": "main_db",
  "kind": "database",
  "projection": "proj_db",
  "generator": {
    "id": "@topogram/generator-postgres-db",
    "version": "1",
    "package": "@topogram/generator-postgres-db"
  },
  "migration": {
    "ownership": "generated",
    "tool": "sql",
    "statePath": "app/db/main_db/state",
    "apply": "script"
  }
}
```

Maintained Prisma runtime:

```json
{
  "id": "main_db",
  "kind": "database",
  "projection": "proj_db",
  "generator": {
    "id": "@topogram/generator-postgres-db",
    "version": "1",
    "package": "@topogram/generator-postgres-db"
  },
  "migration": {
    "ownership": "maintained",
    "tool": "prisma",
    "schemaPath": "apps/api/prisma/schema.prisma",
    "migrationsPath": "apps/api/prisma/migrations",
    "snapshotPath": "topo/state/db/main_db/current.snapshot.json",
    "apply": "never"
  }
}
```

Rules:

- `ownership` is `generated` or `maintained`.
- `tool` is `sql`, `prisma`, or `drizzle`.
- generated migrations require `statePath` and `apply: "script"`.
- maintained migrations require `snapshotPath` and `apply: "never"`.
- maintained Prisma and Drizzle workflows require `schemaPath` and
  `migrationsPath`.
- maintained SQL workflows require `migrationsPath`.
- paths are project-relative and cannot escape the project root.

In maintained mode, Topogram emits snapshots, plans, SQL proposals, and
Prisma/Drizzle schema proposals. The maintained app owns its schema files,
migration directory, and migration runner.

Generated DB lifecycle bundles use the strategy when rendering their plan and
scripts:

- `ownership: "generated"` keeps apply-capable lifecycle scripts. Supported
  SQL migrations may be applied by generated scripts; unsupported plans stop for
  manual review.
- `ownership: "maintained"` renders proposal-only lifecycle scripts. They emit
  desired snapshots, migration plans, and SQL proposals, but never apply
  migrations or seed generated demo data into the maintained database.

---

# Source: docs/reference/import-json.md

# Extract/Adopt JSON

> Use --json for agent and script automation.

Status: current
Audience: brownfield extraction/adoption tooling users
Use when: you need extraction, candidate, plan, or adoption JSON shapes.

Use `--json` for agent and script automation.

Important fields:

- `workspaceRoot`: canonical path to the project-owned workspace folder. Public
  JSON uses portable placeholders such as `<repo>/topo` or `<workspace>`, not
  machine-local absolute paths.
- `projectRoot`: target project root, serialized as a portable placeholder such
  as `<repo>`.
- `candidateCounts`: number of extracted candidate artifacts by surface,
  including fields such as `apiCapabilities`, `apiRoutes`,
  `dbMaintainedSeams`, `uiFlows`, `uiWidgets`, `cliCommands`, and
  `cliSurfaces`.
- `writtenFiles`: files written by extraction or adoption.
- `nextCommands`: recommended follow-up commands.
- `receipt`: adoption receipt when an adoption command writes.
- `extraction_context`: focused query context for `.topogram-extract.json`,
  package-backed extractor provenance, candidate counts, safety notes, and next
  review commands.

Package-backed extractor provenance is recorded in the extraction receipt and
then summarized through `extraction_context`. Use it to answer which package ran,
which extractor IDs produced evidence, and whether package-backed execution was
part of the review. Provenance does not mean adoption happened; candidates stay
review-only until an explicit `topogram adopt ... --write` command records a
receipt.

Current command payloads:

- `topogram extract <source> --out <target> --json`
- `topogram extract check --json`
- `topogram extract diff --json`
- `topogram extract refresh --json`
- `topogram extract plan --json`
- `topogram adopt --list --json`
- `topogram adopt <selector> --json`
- `topogram extract status --json`
- `topogram extract history --json`

Review payloads:

- `topogram extract plan --json` returns `bundles`, `summary`,
  `workspaceRoot`, and a `nextCommand`.
- Maintained DB migration seam proposals appear as `dbMaintainedSeams` in
  extract counts, `candidates.db.maintained_seams` in raw candidate files, and a
  review-only `database` bundle in plan output.
- Non-resource UI flow proposals appear as `uiFlows` in extract counts,
  `candidates.ui.flows` in raw candidate files, and review-only UI items in
  plan/adoption output. They are proposals for shared `ui_contract` additions,
  not automatic canonical writes.
- Evidence records can include source type context. Runtime source and
  parser/config files are primary; docs, tests, fixtures, and generated output
  should not create high-confidence primary candidates by themselves.
- `topogram adopt --list --json` returns exact `selectors` such as
  `bundle:task` or `bundle:cli` and broad selectors such as `widgets`, `ui`,
  `cli`, `capabilities`, and `from-plan`.
- `topogram adopt <selector> --dry-run --json` returns
  `promotedCanonicalItems`, `promotedCanonicalItemCount`, `writtenFiles`, and
  `write: false`.
- `topogram extract history --verify --json` returns `verification` in
  audit-only mode. Adopted Topogram files are project-owned, so local edits do
  not invalidate extraction evidence.

Focused agent review:

```bash
topogram query extract-plan ./topo --json
topogram query single-agent-plan ./topo --mode extract-adopt --json
topogram query multi-agent-plan ./topo --mode extract-adopt --json
topogram query work-packet ./topo --mode extract-adopt --lane adoption_operator --json
```

These queries are read-only and give agents staged items, extractor provenance,
maintained-boundary risk, write scope, review requirements, lane ownership, and
verification targets.

Agents should use `workspaceRoot`, not older compatibility fields, when deciding
where project-owned Topogram files live.

Public JSON, reports, and proof artifacts are safe to commit by default: paths
under the project are emitted as repo-relative values or placeholders, and
external local paths are redacted as `<external>/...`. Internal engine file IO
may still use absolute paths before values cross a public output boundary.

---

# Source: docs/authoring/templates.md

# Template Authoring

> Template packages are starter projects for topogram copy.

Status: current
Audience: template authors and maintainers
Use when: you need package layout, trust, and template authoring rules.

Template packages are starter projects for `topogram copy`.

## Required layout

```text
topogram-template.json
topo/
topogram.project.json
implementation/        # optional executable customization
package.json           # required for npm packages
```

`topogram-template.json`:

```json
{
  "id": "@scope/template-name",
  "version": "0.1.0",
  "kind": "starter",
  "topogramVersion": "0.1",
  "includesExecutableImplementation": false
}
```

Use `includesExecutableImplementation: true` when the template copies
`implementation/` code that may run later during `topogram generate`.

## Package payload

Keep package files narrow:

```json
{
  "files": [
    "topogram-template.json",
    "topo",
    "topogram.project.json",
    "implementation",
    "README.md"
  ]
}
```

Do not publish consumer metadata such as `.topogram-template-trust.json` or
`.topogram-template-files.json`; those files are command-owned state in copied
projects.

## Trust

`topogram copy` copies implementation code but does not execute it. Generated
projects record implementation hashes. Review code before running
`topogram trust template`.

Template packs must not contain symlinks under `topo/`,
`topogram.project.json`, or `implementation/`.

## Verify

```bash
topogram template check ./my-template
topogram copy ./my-template ./scratch
cd ./scratch
npm install
npm run check
npm run generate
npm run verify
```

Template tests should run the generated project's meaningful verification
surface, not only check that files exist.

---

# Source: docs/authoring/generator-packs.md

# Generator Packs

> Generator packs are package-backed realization extensions that turn Topogram contracts into stack-specific files.

Status: current
Audience: generator package authors
Use when: you need generator manifest, adapter, verification, or publish guidance.

Generator packs are execution packages. They do not copy starter content and
they do not own the Topogram model. Topogram core validates the workspace,
builds normalized contracts, loads the selected generator, and writes generated
output under the configured output root.

Use a generator pack when a stack-specific renderer must be shared across
projects. Keep one-off maintained-app code in the app instead.

## Authoring Path

There is no `topogram generator init` command yet. Create a normal package repo
with the files below, then use the same preflight loop every time:

```bash
npm install
npm test
npm run docs:rag:check
topogram generator check .
npm pack --dry-run
npm run release:preflight
```

`topogram generator check .` loads the adapter and runs smoke generation against
a minimal contract fixture. It is intentionally different from `generator list`
and `generator show`, which read manifests only.

For package consumers, the safe loop is:

```bash
npm install --save-dev @scope/topogram-generator-web
topogram generator policy pin @scope/topogram-generator-web@1
topogram generator check @scope/topogram-generator-web
topogram check . --json
topogram generate
npm run verify
```

Topogram does not install generator packages. A project or package author must
install them with npm, pin them through `topogram.generator-policy.json`, and
verify the generated output with the target stack's own checks.

## Manifest

`topogram-generator.json`:

```json
{
  "id": "@topogram/generator-react-web",
  "version": "1",
  "surface": "web",
  "projectionTypes": ["web_surface"],
  "inputs": ["ui-surface-contract", "api-contracts"],
  "outputs": ["web-app", "generation-coverage"],
  "stack": {
    "runtime": "browser",
    "framework": "react",
    "language": "typescript"
  },
  "capabilities": {
    "routes": true,
    "widgets": true,
    "coverage": true
  },
  "widgetSupport": {
    "patterns": ["resource_table", "data_grid_view"],
    "behaviors": ["selection", "sorting"],
    "unsupported": "warning"
  },
  "source": "package",
  "package": "@topogram/generator-react-web"
}
```

`id` and `version` identify the generator contract. The npm package version is
separate. Policy pins use the generator manifest version, so a package can patch
implementation code without changing the contract version.

## Adapter export

Publish a CommonJS-compatible entry:

```js
exports.manifest = require("./topogram-generator.json");

exports.generate = function generate(context) {
  return {
    files: {},
    artifacts: {},
    diagnostics: []
  };
};
```

Use `context.runtime` and `context.contracts` as the primary API. Raw projection
internals are compatibility fallback, not the preferred contract.

The returned file map must stay inside the generated output root. Topogram
validates returned paths as a backstop, but generators should also keep paths
relative, portable, and deterministic.

## Widget support vocabulary

`widgetSupport.patterns` must use the canonical UI pattern vocabulary from the
DSL, such as `resource_table`, `data_grid_view`, `board_view`, `calendar_view`,
and `summary_stats`.

`widgetSupport.behaviors` must use the canonical widget behavior vocabulary:
`selection`, `sorting`, `filtering`, `search`, `pagination`, `grouping`,
`drag_drop`, `inline_edit`, `bulk_action`, `optimistic_update`,
`realtime_update`, and `keyboard_navigation`.

Unknown pattern or behavior values are manifest errors. A generator that cannot
render a supported widget contract should use `unsupported` to report `error`,
`warning`, or `contract-only`; it should not invent stack-local behavior names.

## Verify

```bash
topogram generator check .
npm run check
npm run release:preflight
```

`npm run check` should prove the adapter export, manifest, docs, and local
generator smoke. `npm run release:preflight` is the package-local publish gate:
it should run `npm run check`, `npm pack --dry-run`, a Gitleaks secret scan, and
consumer smoke for the supported stack.

Generator CI should pack/install the generator into a clean consumer project,
run `topogram generator check`, run `topogram check`, run `topogram generate`,
and compile or check the generated output when the stack supports it. Publish
workflows should run Gitleaks first, then `npm run release:preflight` before
`npm publish`.

## Local Paths Vs Installed Packages

Use local paths while developing:

```bash
topogram generator check ./generator-package
```

Use installed package names when testing as a consumer:

```bash
topogram generator check @scope/topogram-generator-web
```

`generator show` accepts either form when the manifest can be resolved, but it
does not execute package code. `generator check` executes package code. Treat
local package paths as trusted source code.

## What To Publish

A shareable generator package should include:

- `package.json`;
- `topogram-generator.json`;
- a CommonJS-compatible adapter export;
- focused unit tests for contract-to-file rendering;
- package-local docs and retrieval files;
- `npm pack --dry-run` and consumer smoke in CI;
- Gitleaks or equivalent secret scanning before publish.

Do not publish generated app output, local temp files, source app credentials,
or project-specific Topogram workspaces as part of a generator package.

---

# Source: docs/authoring/extractor-packs.md

# Extractor Packs

> Extractor packs are package-backed brownfield discovery extensions for review-only candidates.

Status: current
Audience: extractor users and package authors
Use when: you need to understand package-backed extractors or brownfield discovery dependencies.

Extractor packs are package-backed brownfield discovery extensions. They are
the extraction counterpart to generator packs, but their contract is narrower:
they read source evidence and emit review-only findings, candidates,
diagnostics, and provenance. Topogram core owns persistence, reconcile,
adoption, and canonical `topo/**` writes.

Use an extractor pack when bundled extraction is too generic for a framework,
language, CLI, database, or UI evidence family. Do not use an extractor pack as
a content template, generator, or adoption plugin. Templates copy starting
Topogram source; generators create runtime/app files from contracts; extractors
read brownfield source and emit review candidates only.

First-party examples include:

- `@topogram/extractor-node-cli` for CLI surfaces;
- `@topogram/extractor-react-router` for React Router UI surfaces;
- `@topogram/extractor-prisma-db` for Prisma schema/migration evidence;
- `@topogram/extractor-express-api` for Express route surfaces;
- `@topogram/extractor-drizzle-db` for Drizzle schema/migration evidence;
- `@topogram/extractor-xstate-workflows` for XState state machines.

## Package Shape

Start with `extractor init` when authoring a new pack:

```bash
topogram extractor init ./topogram-extractor-node-cli --track cli --package @scope/topogram-extractor-node-cli
cd ./topogram-extractor-node-cli
npm install
npm test
npm run docs:rag:check
npm run check
npm run release:preflight
```

The initializer writes the package shape below plus a small fixture, unit test,
agent guide, retrieval docs, and check script.
Use it as disposable starter code; replace the adapter with precise framework
evidence before publishing.

The command output includes a `Scaffolded:` section. In `--json` mode, the
same information is available as `scaffold[]`, with each path marked as
`created` or `reused` and labeled with its purpose. Use that output as the
first authoring checklist before editing the adapter.

```text
package.json
topogram-extractor.json
index.cjs
AGENTS.md
README.md
llms.txt
llms-full.txt
scripts/build-llms-full.mjs
scripts/verify-docs-rag.mjs
scripts/run-secret-scan.mjs
scripts/check-extractor.mjs
test/adapter.test.mjs
fixtures/basic-source/
```

The generated `AGENTS.md` is part of the contract for humans and coding agents:
extractors are read-only, do not write canonical `topo/**`, do not install
packages or use the network, and return only review candidates. Shared or
published extractor packs should adopt SDLC in their package repo so those rules,
tasks, and verification proof are queryable. Private one-off extractors may stay
lighter, but they should still follow the generated rules and checks.

Use SDLC for shared, published, or safety-sensitive extractor packs. The SDLC
records do not make the package heavier for consumers; they give maintainers and
agents queryable rules, tasks, proof gaps, and verification commands while the
adapter evolves.

The generated package also has its own retrieval surface. Package-local
`llms.txt` is the curated map for humans, agents, and RAG systems reading the
extractor repo; `llms-full.txt` is generated from that map. These files live at
the extractor package root, not in the parent Topogram repo. The generated docs
scripts resolve the package root from their own script path, require
`package.json`, `topogram-extractor.json`, and `llms.txt`, and refuse local
links or writes that escape the package root.

```bash
npm run docs:rag:build
npm run docs:rag:check
```

`npm run release:preflight` is the package-local publish gate. It runs
`npm run check`, `npm pack --dry-run`, and the package-local Gitleaks secret
scan. CI may set `TOPOGRAM_SECRET_SCAN_ALREADY_RAN=1` only after a Gitleaks
workflow step has already passed; local release prep should run the scanner.

`topogram-extractor.json` declares the pack:

```json
{
  "id": "@topogram/extractor-node-cli",
  "version": "1",
  "tracks": ["cli"],
  "source": "package",
  "package": "@topogram/extractor-node-cli",
  "compatibleCliRange": "^0.3.89",
  "stack": { "runtime": "node", "framework": "generic-cli" },
  "capabilities": { "commands": true, "options": true, "effects": true },
  "candidateKinds": ["command", "capability", "cli_surface"],
  "evidenceTypes": ["runtime_source", "parser_config"],
  "extractors": [
    { "id": "cli.node-package", "track": "cli" }
  ]
}
```

The package export returns `{ manifest, extractors }`:

```js
module.exports = {
  manifest,
  extractors: [
    {
      id: "cli.node-package",
      track: "cli",
      detect(context) {
        return { score: 1, reasons: ["Found Node package CLI metadata."] };
      },
      extract(context) {
        return {
          findings: [],
          candidates: {
            commands: [],
            capabilities: [],
            surfaces: []
          },
          diagnostics: []
        };
      }
    }
  ]
};
```

## Adapter Contract

Each extractor adapter is intentionally small. It detects whether it should run,
then returns review-only output:

| Method | Purpose | Must Not |
| --- | --- | --- |
| `detect(context)` | Score whether the extractor has enough source evidence to run. | Mutate source files, install packages, or write `topo/**`. |
| `extract(context)` | Return findings, candidates, diagnostics, and evidence. | Adopt candidates, edit `topogram.project.json`, or define custom adoption semantics. |

The context is read-oriented. Treat source paths, helper reads, source
classification, and configured tracks as evidence inputs. Keep any framework
parsing local to the package and return plain candidate data for Topogram core
to normalize.

Extractor candidate buckets are track-specific:

| Track | Common buckets |
| --- | --- |
| `db` | `entities`, `enums`, `relations`, `indexes`, `maintained_seams` |
| `api` | `capabilities`, `routes`, `stacks` |
| `ui` | `screens`, `routes`, `actions`, `flows`, `widgets`, `shapes`, `design_realizations`, `stacks` |
| `cli` | `commands`, `capabilities`, `surfaces` |
| `workflows` | `workflow_definitions`, `workflow_states`, `workflow_transitions` |
| `verification` | `verifications`, `scenarios`, `frameworks`, `scripts` |

Only use the `workflows` track when the source directly owns workflow
semantics. Good workflow-pack sources include BPMN, Temporal, XState, Step
Functions, Camunda, Rails state machines, Django FSM, and similar systems that
encode states, transitions, orchestration, or process definitions. Do not add
workflow guesses to ordinary DB/API/UI/CLI extractors. Those extractors should
return their own track evidence. Topogram core already handles the conservative
DB/API v1 synthesis for entities with `status` or `state` enums; broader
cross-track synthesis should be added deliberately where the synthesizer can see
corroborated evidence across tracks.

For Step Functions, prefer a local Amazon States Language v1. Read checked-in
JSON or YAML state-machine definitions and emit workflow candidates from
`StartAt`, `States`, `Next`, `Default`, `Choices`, `Catch`, `Retry`, `Map`,
`Parallel`, `Succeed`, and `Fail` structure. Do not call AWS APIs, load
credentials, inspect execution history, or infer IAM behavior from an extractor
package. Infrastructure wrappers such as CloudFormation, CDK, SAM, Serverless,
and Terraform should be explicit future scope unless the package can recover
the embedded ASL definition deterministically.

Workflow extractor packages should emit the canonical workflow buckets, not a
generic `workflows` bucket:

```js
return {
  findings: [],
  candidates: {
    workflow_definitions: [{
      id_hint: "workflow_review",
      label: "Review",
      source_kind: "workflow_native",
      source_system: "xstate",
      evidence: [{ file: "src/review-machine.js", reason: "machine id review" }]
    }],
    workflow_states: [{
      id_hint: "workflow_review_draft",
      workflow_id: "workflow_review",
      state_id: "draft",
      label: "Draft"
    }],
    workflow_transitions: [{
      id_hint: "workflow_review_submit",
      workflow_id: "workflow_review",
      from_state: "draft",
      to_state: "review",
      event: "SUBMIT"
    }]
  },
  diagnostics: []
};
```

`topogram extract plan` and `topogram adopt --list` expose these candidates as
review-only workflow adoption selectors. The package still does not define
canonical `workflow` files or adoption semantics; Topogram core owns the
reviewed graph record and any supporting decision/doc output.

Extractor output is validated before Topogram persists extraction artifacts.
`findings` and `diagnostics` must be arrays when present, and `candidates` must
be an object of track-owned array buckets. Candidate records must have a stable
identity such as `id_hint`, `id`, `name`, or `command_id`; route candidates may
use `method` plus `path`. File evidence must use safe project-relative paths,
not absolute paths or `..` escapes. Candidate output must not include canonical
files, patches, adoption plans, write instructions, or direct `topo/**` writes.
Those are core responsibilities handled only after explicit `topogram adopt`.

`stacks` and `frameworks` are scalar metadata buckets, not adoptable graph
records. Return strings:

```js
return {
  findings: [],
  candidates: {
    capabilities: [{
      id_hint: "cap_get_invoice",
      label: "Get invoice",
      endpoint: { method: "GET", path: "/invoices/{id}" },
      path_params: ["id"],
      query_params: ["includeLines"],
      header_params: ["authorization"],
      input_fields: [],
      output_fields: ["id", "status"],
      provenance: ["src/routes/invoices.ts"]
    }],
    routes: [{ method: "GET", path: "/invoices/{id}", source_kind: "route_code" }],
    stacks: ["express"]
  },
  diagnostics: []
};
```

Common shorthand is accepted at the package boundary. String parameter names are
normalized to parameter records, so `path_params: ["id"]` becomes
`[{ name: "id", required: true, type: null }]`; query and header params default
to `required: false`. `input_fields` and `output_fields` may stay as string field
names. Older stack objects are tolerated temporarily and normalized to strings,
but new extractor packages should emit `stacks: ["express"]`.

UI extractors may propose `design_realizations` when source evidence maps a
semantic widget to a design-system component. These are review-only candidates,
not canonical design decisions:

```js
return {
  findings: [],
  candidates: {
    design_realizations: [{
      id_hint: "review_queue_web_grid",
      realization_set_id_hint: "realization_set_review_queue",
      design_contract_id_hint: "design_acme_product_ui",
      widget_id: "widget_review_queue",
      platform: "web",
      viewport: "wide",
      component_ref: "acme.reviewQueue.grid",
      pattern: "resource_table",
      status: "rendered",
      behaviors_rendered: ["selection"],
      behaviors_contract_only: ["bulk_action"],
      confidence: "medium",
      evidence: [{ file: "src/review/ReviewQueue.tsx", reason: "Uses Acme ReviewQueueGrid." }],
      missing_decisions: ["Confirm bulk action support."]
    }]
  },
  diagnostics: []
};
```

`component_ref` must be a stable design-system identity, not a source import
path. `topogram adopt design-realizations --write` stays blocked until the
referenced widget and design contract exist or are selected in the same plan.

Storybook is a good source for these candidates when the component library uses
static CSF stories. The first-party `@topogram/extractor-storybook-design`
package reads `*.stories.js`, `*.stories.jsx`, `*.stories.ts`, and
`*.stories.tsx` files and looks for explicit metadata on the default story meta:

```ts
parameters: {
  topogram: {
    widget: "widget_review_queue",
    designContract: "design_acme_product_ui",
    realizationSet: "realization_set_review_queue",
    componentRef: "acme.reviewQueue.grid",
    platform: "web",
    viewport: "wide",
    pattern: "resource_table",
    status: "rendered",
    behaviorsRendered: ["selection"],
    behaviorsContractOnly: ["bulk_action"]
  }
}
```

The Storybook extractor does not run Storybook, execute components, parse MDX,
read screenshots, or use generated `storybook-static` output in v1. Stories
without enough explicit metadata become findings and missing decisions, not
low-confidence mappings.

## Safety Boundary

- Extractors are read-only.
- Extractors do not write `topo/**`.
- Extractors do not mutate source app files.
- Extractors do not install packages.
- Extractors do not perform network access.
- Extractors do not define adoption semantics.

Core normalizes candidates and writes extraction artifacts. Adoption happens only
through `topogram adopt`.

## Policy And Execution

Bundled `topogram/*` extractors and first-party `@topogram/extractor-*`
packages are allowed by default. Other packages require an explicit
`topogram.extractor-policy.json`.

```bash
topogram extractor policy init
topogram extractor policy pin @topogram/extractor-node-cli@1
topogram extractor policy pin @topogram/extractor-react-router@1
topogram extractor policy pin @topogram/extractor-prisma-db@1
topogram extractor policy pin @topogram/extractor-express-api@1
topogram extractor policy pin @topogram/extractor-drizzle-db@1
topogram extractor policy pin @topogram/extractor-storybook-design@1
topogram extractor policy pin @topogram/extractor-xstate-workflows@1
topogram extractor policy check
```

No dynamic installation is performed. A package-backed extractor must already be
installed, or you must pass a local package path. Policy pins use the extractor
manifest version, not the npm package version. For example,
`@topogram/extractor-react-router@1` pins manifest version `1`; npm may install
package version `0.1.1` or later.

Private repositories are fine. They are often the right place to develop a
domain-specific extractor before deciding whether it belongs on npm. Consumers
can use either an installed private package or a local path:

```bash
npm install -D git+ssh://git@github.com/your-org/topogram-extractor-custom-api.git
topogram extractor check @your-org/topogram-extractor-custom-api
topogram extract ./existing-app --out ./imported-topogram --from api --extractor @your-org/topogram-extractor-custom-api
```

```bash
topogram extractor check ../topogram-extractor-custom-api
topogram extract ./existing-app --out ./imported-topogram --from api --extractor ../topogram-extractor-custom-api
```

Public packages are easier for broad sharing and release tracking. Private or
local packages are better while the evidence model is still specific to one
organization or application family. In both cases, the adapter contract stays
the same: read source evidence, return review-only candidates, and let core own
normalization, persistence, reconcile, and adoption.

Use `topogram extractor list` to see bundled packs and first-party package
recommendations grouped by track. Use `topogram extractor recommend <source>`
to inspect a local brownfield source tree and get suggested first-party package
extractors before installing or loading any package code. Use `topogram
extractor show <package>` before installing when you need the package purpose,
install command, policy pin command, npm package version, compatible CLI range,
and a concrete extract command. `topogram extractor check <package>` reports the
same version split: manifest version is what policy pins, package version is
what npm installed, and compatible CLI range is the CLI line the package
declares or inherits.

The consumer command loop is part of the contract:

1. `topogram extractor list` discovers candidates without loading package code.
2. `topogram extractor recommend <source> --from <tracks>` suggests packages from local evidence without loading package code.
3. `topogram extractor show <package>` explains why to use one package, how to install it, how to pin it, what package version is installed, what CLI range is compatible, and how to run extraction.
4. `npm install -D <package>` is explicit; Topogram does not install extractor packages during extraction.
5. `topogram extractor policy pin <package>@<manifest-version>` records the reviewed manifest version.
6. `topogram extractor check <package>` loads package code only for a minimal smoke extraction.
7. `topogram extract ... --extractor <package>` writes candidates and provenance, not canonical records.
8. `topogram extract plan`, `topogram adopt --list`, and `topogram query extract-plan` show package provenance and selectors.
9. `topogram adopt <selector> --dry-run` precedes any `--write`.

Consumer loop:

```bash
npm install -D @topogram/extractor-react-router
topogram extractor policy init
topogram extractor recommend ./react-router-app --from ui
topogram extractor recommend ./storybook-library --from ui
topogram extractor policy pin @topogram/extractor-react-router@1
topogram extractor policy pin @topogram/extractor-storybook-design@1
topogram extractor check @topogram/extractor-react-router
topogram extractor check @topogram/extractor-storybook-design
topogram extract ./react-router-app --out ./imported-topogram --from ui --extractor @topogram/extractor-react-router
topogram extract ./storybook-library --out ./storybook-topogram --from ui --extractor @topogram/extractor-storybook-design
topogram query extract-plan ./imported-topogram/topo --json
topogram adopt --list ./imported-topogram --json
topogram adopt <selector> ./imported-topogram --dry-run
```

`topogram extractor check` proves the package manifest, export shape, adapter
load, and minimal smoke extraction. It does not prove domain correctness for a
real app. A useful package test must run extraction against a representative
fixture, inspect candidate counts and provenance, run `extract plan`, and dry-run
adoption.

## Author Checks

```bash
topogram extractor init ./my-extractor-pack --track cli --package @scope/my-extractor-pack
npm --prefix ./my-extractor-pack test
npm --prefix ./my-extractor-pack run check
topogram extractor check ./my-extractor-pack
topogram extract ./fixture-app --out /private/tmp/extracted --extractor ./my-extractor-pack
topogram extract plan /private/tmp/extracted --json
topogram adopt --list /private/tmp/extracted --json
topogram query extract-plan /private/tmp/extracted/topo --json
```

Use `TOPOGRAM_CLI` when developing an extractor against a local Topogram checkout:

```bash
TOPOGRAM_CLI=/path/to/topogram/engine/src/cli.js npm --prefix ./my-extractor-pack run check
```

Passing `topogram extractor check` proves the manifest, adapter export, and
minimal smoke shape, including track-aware candidate validation. It does not
replace fixture-based extraction tests.

Package CI should also run a real fixture extraction and inspect the generated
review packet. At minimum, prove:

- `topogram extractor check ./` passes;
- `topogram extract ./fixture-app --out <tmp> --extractor ./` writes candidates;
- `topogram extract plan <tmp> --json` includes the expected candidate groups;
- `topogram query extract-plan <tmp>/topo --json` includes extractor provenance;
- `topogram adopt <selector> <tmp> --dry-run --json` previews canonical writes;
- source fixture files are unchanged.

## Publication Readiness Checklist

Before publishing an extractor package, prove the package boundary from the
outside. The package should be usable by a consumer without reading Topogram
engine internals.

- Scaffold or maintain the standard package shape:
  `topogram-extractor.json`, `index.cjs`, `fixtures/`, `scripts/check-extractor.mjs`,
  package exports, and `files`.
- Run `npm run release:preflight` from the extractor package root.
- Pack and install the extractor into a temporary consumer project.
- Run `topogram extractor check <package-or-path>`.
- Run `topogram extract <fixture> --out <tmp> --from <track> --extractor <package-or-path>`.
- Inspect `topogram extract plan <tmp> --json`, `topogram adopt --list <tmp> --json`,
  and `topogram query extract-plan <tmp>/topo --json`.
- Assert expected candidates, candidate counts, extractor provenance, and safety
  notes. Do not accept string-existence-only tests.
- Assert source fixture files are unchanged after extraction.
- Publish only after package CI runs the package smoke against the CLI version in
  `topogram-cli.version`.
- After publish, run the `Package Access` workflow to set public npm access and
  verify `npm view <package> version --registry=https://registry.npmjs.org/`.

Recommended workflows for public first-party-style packages:

```text
.github/workflows/extractor-verification.yml
.github/workflows/publish-package.yml
.github/workflows/package-access.yml
```

Publish workflows should run a Gitleaks action first, then `npm run
release:preflight` before `npm publish`. If the workflow already passed the
Gitleaks action, it may set `TOPOGRAM_SECRET_SCAN_ALREADY_RAN=1` for the
preflight script so CI does not need a second scanner binary.

## First-Party Examples

Current public first-party extractor packages on the current `@topogram/cli`
release line:

| Package | Version | Track |
| --- | --- | --- |
| `@topogram/extractor-node-cli` | `0.1.0` | `cli` |
| `@topogram/extractor-react-router` | `0.1.1` | `ui` |
| `@topogram/extractor-prisma-db` | `0.1.0` | `db` |
| `@topogram/extractor-express-api` | `0.1.0` | `api` |
| `@topogram/extractor-drizzle-db` | `0.1.0` | `db` |
| `@topogram/extractor-xstate-workflows` | `0.1.0` | `workflows` |
| `@topogram/extractor-step-functions-workflows` | `0.1.0` | `workflows` |

```bash
topogram extract ./existing-cli --out ./extracted-cli --from cli --extractor @topogram/extractor-node-cli
topogram extract ./react-router-app --out ./extracted-ui --from ui --extractor @topogram/extractor-react-router
topogram extract ./prisma-app --out ./extracted-db --from db --extractor @topogram/extractor-prisma-db
topogram extract ./express-api --out ./extracted-api --from api --extractor @topogram/extractor-express-api
topogram extract ./drizzle-app --out ./extracted-db --from db --extractor @topogram/extractor-drizzle-db
topogram extract ./xstate-app --out ./extracted-workflows --from workflows --extractor @topogram/extractor-xstate-workflows
topogram extract ./step-functions-app --out ./extracted-workflows --from workflows --extractor @topogram/extractor-step-functions-workflows
```

These packages emit review-only candidates. React Router can add screen, route,
non-resource flow, and widget evidence. Prisma and Drizzle can add maintained DB
seam proposals. Express can add route, capability, parameter, auth, and stack
evidence. XState can add workflow definition, state, and transition candidates.
Step Functions can add workflow definition, state, and transition candidates from
local Amazon States Language JSON or YAML.
Adoption is still explicit through `topogram adopt`.

---

# Source: docs/proof-walkthrough.md

# Proof Walkthrough

> The proof repositories show runnable step-by-step stories for generated, maintained, brownfield, recreated, and workflow-native app maps.

Status: current
Audience: evaluators and maintainers inspecting proof repositories
Use when: you need runnable proof/demo steps and what each checkpoint proves.

Topogram has current public proof repositories organized into focused product
stories. They are tutorial-style demos, not fixtures. Use them when you
want to see how the app map supports real work: branches, tags, README notes,
SDLC records, agent packets, emitted contracts, and verification commands.

## Five-Minute Demo Path

Use the brownfield proof when you want the shortest product demo:

```bash
git clone https://github.com/attebury/topogram-proof-content-approval-brownfield-v3.git
cd topogram-proof-content-approval-brownfield-v3
git checkout proof-03-adopt-app-map
npm install
npm run verify
```

Then inspect:

- `proof/STEP.md` for what the checkpoint proves;
- `proof/artifacts/` for the extract/adopt plan, receipts, agent packets, and
  validation output;
- `topo/` for the adopted app map.

That checkpoint shows the core Topogram move: existing React/Express/Prisma
code becomes reviewed `topo/` source, extraction evidence stays separate, and
agents get focused packets before maintained-code changes.

If you have only a few minutes, do not read every file. Read `proof/STEP.md`,
open the latest agent packet under `proof/artifacts/`, then compare the current
tag with the previous proof tag. The useful question is: what did Topogram know
before the code changed?

## Beta Evaluation Path

For beta evaluation, read the proof repos as product demos:

1. Run the five-minute brownfield path above.
2. Open `proof/artifacts/` and inspect the extract plan, adoption list, agent
   brief, and focused query packets.
3. Compare `proof-03-adopt-app-map` to `proof-04-feature-from-slice` to see how a
   maintained feature is planned from `topo/` instead of rediscovering source.
4. Compare `proof-06-recreate-other-stack` and `proof-07-parity-proof` to see
   where Topogram can recreate a stack and where parity is only reported.
5. Use the focused XState or Step Functions proof when you want to inspect
   workflow-native extraction without the larger UI/API/DB proof story.
6. Use the focused widget design proof when you want to inspect semantic design
   mappings, component refs, and designer/developer review rows.
7. Use the Storybook design proof when you want to see Storybook metadata become
   review-only design realization candidates before explicit adoption.
8. Use the generated-to-maintained proof second to see how `generate` fits the
   same app-map model.

The demo claim is intentionally narrow: Topogram provides a reviewable map,
focused agent context, contracts, and proof commands. It does not promise full
runtime equivalence or pixel-perfect UI parity.

## Proof Repos

| Story | Repository | What It Proves |
| --- | --- | --- |
| Brownfield extract/adopt | [topogram-proof-content-approval-brownfield-v3](https://github.com/attebury/topogram-proof-content-approval-brownfield-v3) | Start with a maintained app, extract candidates, adopt curated specs, implement a maintained feature from agent context, refresh drift, recreate another stack, and compare parity. |
| Generated to maintained | [topogram-proof-content-approval-v3](https://github.com/attebury/topogram-proof-content-approval-v3) | Start from an initialized Topogram, generate an app, graduate output to maintained ownership, then use Topogram for maintained feature and DB migration guidance. |
| Widget design realization | [topogram-proof-widget-design-realization](https://github.com/attebury/topogram-proof-widget-design-realization) | Map one semantic widget to web, iOS, and Android component refs; prove rendered, contract-only, implementation-owned, unsupported, and review states through JSON coverage, a designer-readable Markdown matrix, `ui-realization-report`, and a widget slice. See [Map A Design System](./design/map-design-system.md). |
| Storybook design extraction | [topogram-proof-storybook-design-realization](https://github.com/attebury/topogram-proof-storybook-design-realization) | Start with static CSF Storybook stories, extract explicit `parameters.topogram` metadata as review-only `design_realizations`, adopt the mapping into a canonical `design_realization_set`, then prove coverage, realization report, and widget slice output. |
| Workflow-native extraction | [topogram-proof-xstate-workflow](https://github.com/attebury/topogram-proof-xstate-workflow) | Start with an XState app, extract workflow candidates through a package-backed extractor, adopt a workflow map, use compact slices for a maintained source change, then refresh and adopt workflow drift. |
| Workflow-native extraction | [topogram-proof-step-functions-workflow](https://github.com/attebury/topogram-proof-step-functions-workflow) | Start with a local Step Functions ASL definition, extract workflow candidates through a package-backed extractor, adopt a workflow map, use compact slices for a maintained source change, then refresh and adopt workflow drift. |

The brownfield proof is the fastest way to understand Topogram’s main
differentiator: it turns existing code into reviewable app-map evidence, then
uses that map to guide agent-safe maintained changes. The generated-to-maintained
proof shows the same map starting from a template instead of an existing app.

The proof repos expose a `Proof Verification` workflow, `npm run proof:audit`, and
`npm run verify`. They also use SDLC to show the recommended habit, but SDLC is
not required for ordinary Topogram users.

`topogram release status --strict` tracks these repos as `proofConsumers`, not
as normal package rollout consumers. A release is considered current when proof
repos meet the configured proof baseline, expose the audit/verify scripts, and
have green Proof Verification workflows. The current v3 content-approval proof
baseline is `@topogram/cli@0.3.99`; the focused XState proof is pinned to
`@topogram/cli@0.3.104` and `@topogram/extractor-xstate-workflows@0.1.0`.
The focused Step Functions proof is pinned to `@topogram/cli@0.3.106` and
`@topogram/extractor-step-functions-workflows@0.1.0`. The widget design proof is
current on `@topogram/cli@0.3.110` because the designer-readable design matrix
changed the demo story. The Storybook design proof is pinned to
`@topogram/cli@0.3.110` and uses the package-backed Storybook extractor from
its GitHub repo until the npm package is published. Proof repos do not need to
be repinned for every CLI patch; refresh them when the product demo story
changes. The v2 repos remain public historical demos.

When a proof repo is created or materially refreshed, close the work with a
learning review. Promote what the proof taught into current docs, `llms.txt`,
journeys, glossary, agent guidance, release/proof tracking, or backlog records.
If the proof revealed no product-facing gaps, record that explicitly in the
linked plan before marking the proof task done.

## How To Read A Proof

1. Open the repo and confirm the `Proof Verification` badge is green.
2. Read `proof/README.md` for the step map.
3. Check out a proof tag:

   ```bash
   git fetch --tags
   git checkout proof-03-ui-i18n-aria-proof
   cat proof/STEP.md
   npm install
   npm run verify
   ```

4. Inspect `proof/artifacts/` for the machine-readable proof.
5. Compare the current tag with the previous tag when you want to see exactly
   what changed.

`npm run verify` is intentionally the only command a reader needs to trust at a
checkpoint. In the v3 repos it runs the proof audit, path-hygiene audit,
Topogram validation when `topo/` exists, SDLC validation when adopted, app
verification, recreated-stack compilation when present, and a final clean
worktree check.

## What Agents Should Read

The proof repos intentionally commit agent-facing artifacts. These are the files
an implementation agent would normally read instead of loading the whole repo:

- `agent-brief.json`: read order, edit boundaries, workflow commands, and trust
  or policy state.
- `*-task-slice.json`: focused SDLC/task context for one implementation slice.
- `*-single-agent-plan.json`: implementation plan for maintained app edits.
- `ui-surface-contract.json`, `ui-widget-contract.json`, and widget reports:
  UI contracts and conformance checks.
- DB snapshots, migration plans, and SQL migration artifacts: generated or
  maintained migration evidence.
- extract/adopt plans and receipts: brownfield candidate review and adoption
  proof.

For current engine UI work, also inspect `ui-realization-report` and generated
`generation-coverage.json` outputs. For design-system work, inspect
`ui-design-coverage --format markdown` first; it is the widget-first matrix a
designer or front-end lead can read without parsing JSON. The v3 proof repos are
pinned baseline stories; they do not move for every patch-level generator
improvement.

## Story 1: Generated To Maintained

The generated proof walks through:

| Step | Checkpoint | What To Notice |
| --- | --- | --- |
| 01 init SDLC baseline | [`proof-01-init-sdlc-baseline`](https://github.com/attebury/topogram-proof-content-approval-v3/tree/proof-01-init-sdlc-baseline) | `topogram init --adopt-sdlc` creates an empty app map with enforced SDLC guidance. |
| 02 generated content approval | [`proof-02-generated-content-approval`](https://github.com/attebury/topogram-proof-content-approval-v3/tree/proof-02-generated-content-approval) | The app map generates a content approval app and verifies compile. |
| 03 UI i18n/ARIA proof | [`proof-03-ui-i18n-aria-proof`](https://github.com/attebury/topogram-proof-content-approval-v3/tree/proof-03-ui-i18n-aria-proof) | Widgets, screen bindings, behavior, i18n/ARIA contracts, and UI realization reports become the development guide. |
| 04 generated DB migration | [`proof-04-generated-db-migration`](https://github.com/attebury/topogram-proof-content-approval-v3/tree/proof-04-generated-db-migration) | DB snapshots and SQL migration output are generated while app output is still generated-owned. |
| 05 graduate maintained | [`proof-05-graduate-maintained`](https://github.com/attebury/topogram-proof-content-approval-v3/tree/proof-05-graduate-maintained) | `topogram generate` refuses to overwrite maintained output. |
| 06 maintained feature from slice | [`proof-06-maintained-feature-from-slice`](https://github.com/attebury/topogram-proof-content-approval-v3/tree/proof-06-maintained-feature-from-slice) | Agent/query packets guide direct maintained app edits. |
| 07 maintained DB migration | [`proof-07-maintained-db-migration`](https://github.com/attebury/topogram-proof-content-approval-v3/tree/proof-07-maintained-db-migration) | Topogram emits migration proposals; humans/agents adapt maintained DB files directly. |

Use this story when you want to understand the greenfield path: start with a
generated project, keep the generated loop while it is useful, then graduate the
app to maintained ownership without throwing away the `topo/` contract.

## Story 2: Brownfield Extract/Adopt

The brownfield proof walks through:

| Step | Checkpoint | What To Notice |
| --- | --- | --- |
| 01 brownfield baseline | [`proof-01-brownfield-baseline`](https://github.com/attebury/topogram-proof-content-approval-brownfield-v3/tree/proof-01-brownfield-baseline) | A working React/Express/Prisma app exists with no `topo/`. |
| 02 extract with packages | [`proof-02-extract-with-packages`](https://github.com/attebury/topogram-proof-content-approval-brownfield-v3/tree/proof-02-extract-with-packages) | Package-backed extractors create review-only candidates and provenance. |
| 03 adopt app map | [`proof-03-adopt-app-map`](https://github.com/attebury/topogram-proof-content-approval-brownfield-v3/tree/proof-03-adopt-app-map) | Curated candidates become canonical `topo/`; extraction output remains evidence. |
| 04 feature from slice | [`proof-04-feature-from-slice`](https://github.com/attebury/topogram-proof-content-approval-brownfield-v3/tree/proof-04-feature-from-slice) | A maintained feature is implemented from Topogram context packets. |
| 05 refresh drift | [`proof-05-refresh-drift`](https://github.com/attebury/topogram-proof-content-approval-brownfield-v3/tree/proof-05-refresh-drift) | Source/spec drift is detected and reviewed without silent adoption. |
| 06 recreate other stack | [`proof-06-recreate-other-stack`](https://github.com/attebury/topogram-proof-content-approval-brownfield-v3/tree/proof-06-recreate-other-stack) | The adopted Topogram generates a SvelteKit/Hono/Postgres recreation beside maintained source. |
| 07 parity proof | [`proof-07-parity-proof`](https://github.com/attebury/topogram-proof-content-approval-brownfield-v3/tree/proof-07-parity-proof) | Contracts and verification reports compare maintained and generated stacks. |

Use this story when you want to understand the brownfield path: extract
candidates from existing source, review and adopt only the useful contracts,
keep the original app maintained, then use the adopted `topo/` to guide features
or recreate another stack.

## Story 3: Workflow-Native Extraction

The XState proof walks through:

| Step | Checkpoint | What To Notice |
| --- | --- | --- |
| 01 XState baseline | [`proof-01-xstate-baseline`](https://github.com/attebury/topogram-proof-xstate-workflow/tree/proof-01-xstate-baseline) | A working XState review workflow exists with no `topo/`. |
| 02 extract workflow candidates | [`proof-02-extract-workflow-candidates`](https://github.com/attebury/topogram-proof-xstate-workflow/tree/proof-02-extract-workflow-candidates) | The package-backed XState extractor emits review-only workflow candidates and provenance. |
| 03 adopt workflow map | [`proof-03-adopt-workflow-map`](https://github.com/attebury/topogram-proof-xstate-workflow/tree/proof-03-adopt-workflow-map) | Curated workflow evidence becomes canonical `topo/`, SDLC is enabled, and agent packets are emitted. |
| 04 workflow slice guides change | [`proof-04-workflow-slice-guides-change`](https://github.com/attebury/topogram-proof-xstate-workflow/tree/proof-04-workflow-slice-guides-change) | A compact workflow slice guides a maintained source change without manually editing canonical workflow records. |
| 05 refresh and review drift | [`proof-05-refresh-and-review-drift`](https://github.com/attebury/topogram-proof-xstate-workflow/tree/proof-05-refresh-and-review-drift) | Extraction refresh surfaces workflow drift, then selected updates are reviewed and adopted. |

Use this story when you want the smallest proof of package-backed workflow
extraction. It isolates the workflow-native path from broader brownfield
DB/API/UI concerns.

The Step Functions proof walks through the same shape with local Amazon States
Language source:

| Step | Checkpoint | What To Notice |
| --- | --- | --- |
| 01 Step Functions baseline | [`proof-01-step-functions-baseline`](https://github.com/attebury/topogram-proof-step-functions-workflow/tree/proof-01-step-functions-baseline) | A working local ASL review workflow exists with no `topo/`. |
| 02 extract workflow candidates | [`proof-02-extract-workflow-candidates`](https://github.com/attebury/topogram-proof-step-functions-workflow/tree/proof-02-extract-workflow-candidates) | The package-backed Step Functions extractor emits review-only workflow candidates and provenance. |
| 03 adopt workflow map | [`proof-03-adopt-workflow-map`](https://github.com/attebury/topogram-proof-step-functions-workflow/tree/proof-03-adopt-workflow-map) | Curated workflow evidence becomes canonical `topo/`, SDLC is enabled, and agent packets are emitted. |
| 04 workflow slice guides change | [`proof-04-workflow-slice-guides-change`](https://github.com/attebury/topogram-proof-step-functions-workflow/tree/proof-04-workflow-slice-guides-change) | A compact workflow slice guides a maintained ASL source change without manually editing canonical workflow records. |
| 05 refresh and review drift | [`proof-05-refresh-and-review-drift`](https://github.com/attebury/topogram-proof-step-functions-workflow/tree/proof-05-refresh-and-review-drift) | Extraction refresh surfaces workflow drift, then selected updates are reviewed and adopted. |

Use this story when you want the same workflow-native proof against an
infrastructure/orchestration format instead of an application state-machine
library.

## Story 4: Storybook Design Extraction

The Storybook proof walks through:

| Step | Checkpoint | What To Notice |
| --- | --- | --- |
| 01 Storybook baseline | [`proof-01-storybook-baseline`](https://github.com/attebury/topogram-proof-storybook-design-realization/tree/proof-01-storybook-baseline) | A component library has static CSF stories with explicit `parameters.topogram` metadata and no adopted `topo/`. |
| 02 extract candidates | [`proof-02-extract-candidates`](https://github.com/attebury/topogram-proof-storybook-design-realization/tree/proof-02-extract-candidates) | The package-backed Storybook extractor emits review-only `design_realizations` candidates plus provenance and adoption plan output. |
| 03 adopt realization | [`proof-03-adopt-realization`](https://github.com/attebury/topogram-proof-storybook-design-realization/tree/proof-03-adopt-realization) | Curated Storybook evidence becomes a canonical `design_realization_set`. |
| 04 report and slice | [`proof-04-report-and-slice`](https://github.com/attebury/topogram-proof-storybook-design-realization/tree/proof-04-report-and-slice) | `ui-design-coverage`, `ui-realization-report`, and a widget slice expose the adopted component ref and remaining design review work. |

Use this story when you want to see how a design/component registry can propose
widget-to-component mappings without becoming the source of truth.

## What The Proofs Are Not

The proof repos are not release consumers that must move on every patch and they
are not a promise that every stack has identical runtime behavior. They are
known-good product stories pinned to a CLI baseline. Refresh them when a command
workflow changes, a breaking change lands, or the committed artifacts would
teach stale behavior.

## Current Limits

The proofs show contract, compile, and workflow parity. They do not claim pixel
parity, full production deployment readiness, or exhaustive runtime equivalence.
When a proof cannot establish something, it should say so in the step result or
parity report.