# Local story authoring

The `topo-story-authoring` skill gives a coding agent a local workflow for
creating and evolving a source-grounded story. The agent reads the branch
source, diff, and existing stories; edits the authored `stories/**/*.topo.json`
document; and uses Topocode's objective validation and preview commands. No
hosted model service is required, and `topo scan` never invokes an agent or
model.

Start with `topo init <repo>` and `topo serve <repo>` for the empty Home.
After validating and committing a story, `topo story preview` populates the
same Home inventory with every supported committed story. `topo scan` is
optional for generated Repository exploration; it is not a preview prerequisite.

For parser-backed Rust/Tauri anchors, hash-bound technical branches, independent
Graphviz receipts and cache regeneration, use the [supported technical workflow](./rust-tauri.md).

Source-grounded stories may select any native diagram family and must keep
evidence on every section. Use `classification: "capability-demo"` only for an
explicitly conceptual, anchor-free renderer demonstration; it is labelled as
non-source-grounded and separated from factual catalogue entries. See
[source-grounded story preview](./story-preview.md) for the complete family,
classification, relationship-label, preview, and export contract.

## Executable before/after walkthrough

The regression fixture under `examples/story-authoring/` represents a real Git
repository at two points on a `payment-boundary` branch:

- `initial/` contains the first source and authored checkout story.
- `changed/` moves payment authorization to `src/payment.ts` and updates only
  the two affected anchors. The story ID, unrelated audit anchor and section,
  narrative, and connections remain unchanged.

`packages/cli/src/story-authoring.test.ts` creates the repository, commits the
initial source, authors the first story as an uncommitted draft, and runs:

```text
topo story validate <repo> <repo>/stories/checkout.topo.json
Validated stories/checkout.topo.json (checkout) against <revision> with working tree changes
  submit-checkout: src/checkout.ts:7-7
  charge-order: src/checkout.ts:10-12
  audit-order: src/checkout.ts:14-16
```

After committing and previewing that story, the test applies the changed source
while retaining the old story. Validation fails objectively with
`missing-pattern`. The test then applies the changed authored document, compares
the before/after identity and unrelated content, and validates the repaired
evidence:

```text
Validated stories/checkout.topo.json (checkout) against <revision> with working tree changes
  submit-checkout: src/checkout.ts:9-9
  charge-order: src/payment.ts:3-5
  audit-order: src/checkout.ts:12-14
```

Finally it commits the branch change, runs `topo scan` and
`topo story preview`, and verifies the locally viewable generated artifact at
`.topo/cache/site/stories/checkout/viewer.html` cites
`authorizePayment`. The authored story remains in `stories/`; generated
renderer and cache output remains in `.topo/cache/site/`.

Run the walkthrough with:

```sh
corepack yarn workspace @topo/cli build
corepack yarn workspace @topo/cli test -- story-authoring.test.ts
```

Successful schema and anchor resolution proves structure and source evidence
exist at that working-tree state. It does not prove that the explanation is
semantically accurate or complete; human review remains required.

---
name: topo-story-authoring
description: "Create or update source-grounded Topocode stories locally, validate anchors, and preview committed results without invoking a hosted model."
user-invocable: true
disable-model-invocation: false
---

# Topocode story authoring

Use this workflow when a branch needs a focused architecture explanation.
The coding agent is the author: read the relevant source, branch diff, and
existing `stories/**/*.topo.json` documents before changing a story. Do not
invoke a hosted model service, and do not add model execution to `topo scan`.

## Create or update the authored story

Write the durable document under `stories/**/*.topo.json` using
`node_modules/@jdylanmc/topo-code/story.schema.json` (or the same exported
`@jdylanmc/topo-code/story.schema.json` from a global installation).
Keep authored documents outside `.topo/cache/`;
that directory contains generated output and is never the editing surface.

For a new story, choose one stable lowercase `id`, a focused title and summary,
small sections, and repository-relative source anchors. For an update, retain
the document `id`, section and anchor IDs, and unrelated narrative or
connections. Change only evidence and explanation affected by the branch.
Never store derived line ranges, excerpts, renderer IDs, or renderer JSON in the
authored document.

## Run the objective repair loop

Validate the uncommitted draft against the current working tree:

```sh
npm exec --no -- topo story validate . stories/example.topo.json
```

Repair each reported `invalid-document`, `missing-file`, `missing-symbol`, or
`missing-pattern` or `stale-source` failure by rereading the cited source and updating the
smallest affected authored fields. Repeat until validation succeeds. A success
lists every resolved source location but does **not** establish semantic
accuracy or complete explanation coverage; the author and human reviewer remain
responsible for those judgments.

Commit the source and authored story together. Build or refresh the generated
site, preview the committed story, and inspect it locally:

```sh
npm exec --no -- topo init .
npm exec --no -- topo story preview . stories/example.topo.json
npm exec --no -- topo serve .
```

Home inventories all committed supported stories, not only the preview target.
Scanning is optional for generated Repository exploration.
Open `/stories/<story-id>/`. If source changes later, rerun validation before
previewing and preserve identity plus unrelated authored intent during repairs.
Humans review the authored explanation and generated view; they do not edit the
renderer output in `.topo/cache/site`.

Commit only when authorized by the repository owner. For a globally installed
CLI, use `topo` directly instead of `npm exec --no -- topo`.
Source-grounded native rendering requires the repository's Git `origin` remote
for evidence validation. Do not invent a remote. Initialization and anchor-free
capability demos do not require one; demos must never replace factual evidence.

## Minimal source-grounded document

Read the actual source before adapting this example. `symbol` names a compiler
declaration; `pattern` is an exact text match within the file. Anchors store
neither derived line numbers nor renderer-specific data.

```json
{
  "schemaVersion": "1.0",
  "id": "request",
  "title": "Request handling",
  "summary": "A focused explanation verified against the source.",
  "anchors": [{"id": "handler", "path": "src/handler.ts", "symbol": "handle"}],
  "sections": [{"id": "handle", "title": "Handle request", "body": "Describe the observed behavior.", "anchorIds": ["handler"]}],
  "connections": []
}
```

Architecture is the default; `diagramFamily` also accepts `workflow`, `sequence`,
`dataflow` and `lifecycle`. Every source-grounded section needs evidence. Use
`classification: "capability-demo"` only for explicitly conceptual, anchor-free
renderer demonstrations, never to bypass missing factual evidence. Prefer
small focused stories and short labels. For source moves, reread both sides,
repair only affected anchors and explanation, and retain IDs/unrelated intent.
The package includes executable before/after fixtures under
`node_modules/@jdylanmc/topo-code/examples/story-authoring/`.

## Rust/Tauri technical workflows

Read installed `node_modules/@jdylanmc/topo-code/docs/rust-tauri.md` and
`examples/rust-tauri/stories/` before using the extended contract.
Rust anchors support `language: "rust"`, an unambiguous lexical `symbol` and
exact `pattern`. Use `renderer: "graphviz", diagramFamily: "workflow"` explicitly
for decisions (`kind: "decision"`) or values (`kind: "data"`); native families
remain the default. Every technical anchor pins the complete file's SHA-256.
Every connection declares `classification: "source-traced"` or `"inferred"`,
`rationale` and `anchorIds`; source-traced connections require verified evidence.
Do not label an authored arrow source-derived or compiler control flow.

Hash changes require rereading and reconciling the explanation, not blindly
refreshing digests. Retain IDs when meaning is unchanged. Check exact node and
edge excerpts, cross-story/return links, Home inventory, shared app theme and
actual exports. Graphviz has its own layout receipt, not borrowed Archify
certification. A generic fixture is not evidence for another application's
behavior; disposable consumer diagrams/caches must not enter Topocode source.

Impl/trait methods are first-class source nodes. Repeated method names require
their structural qualified symbol, for example
`src/lib.rs::impl Engine#0::snapshot`, not an owner line/column. Comments and
blank lines change freshness/evidence but not these identities; preserve the
qualified symbol during comment-only hash repair. Tauri rest values and
spread-shifted argument positions remain unresolved, as do overwritten helpers
after dot or computed-member writes. Never promote those unresolved cases to
specific source-derived calls in a narrative.

# Local story authoring

The `topo-story-authoring` skill gives a coding agent a local workflow for
creating and evolving a source-grounded story. The agent reads the branch
source, diff, and existing stories; edits the authored `stories/**/*.topo.json`
document; and uses Topocode's objective validation and preview commands. No
hosted model service is required, and `topo scan` never invokes an agent or
model.

Start with `topo init <repo>` and `topo serve <repo>` for the empty Home.
After validating and committing a story, `topo story preview` populates the
same Home inventory with every supported committed story. `topo scan` is
optional for generated Repository exploration; it is not a preview prerequisite.

For parser-backed Rust/Tauri anchors, hash-bound technical branches, independent
Graphviz receipts and cache regeneration, use the [supported technical workflow](./rust-tauri.md).

Source-grounded stories may select any native diagram family and must keep
evidence on every section. Use `classification: "capability-demo"` only for an
explicitly conceptual, anchor-free renderer demonstration; it is labelled as
non-source-grounded and separated from factual catalogue entries. See
[source-grounded story preview](./story-preview.md) for the complete family,
classification, relationship-label, preview, and export contract.

## Executable before/after walkthrough

The regression fixture under `examples/story-authoring/` represents a real Git
repository at two points on a `payment-boundary` branch:

- `initial/` contains the first source and authored checkout story.
- `changed/` moves payment authorization to `src/payment.ts` and updates only
  the two affected anchors. The story ID, unrelated audit anchor and section,
  narrative, and connections remain unchanged.

`packages/cli/src/story-authoring.test.ts` creates the repository, commits the
initial source, authors the first story as an uncommitted draft, and runs:

```text
topo story validate <repo> <repo>/stories/checkout.topo.json
Validated stories/checkout.topo.json (checkout) against <revision> with working tree changes
  submit-checkout: src/checkout.ts:7-7
  charge-order: src/checkout.ts:10-12
  audit-order: src/checkout.ts:14-16
```

After committing and previewing that story, the test applies the changed source
while retaining the old story. Validation fails objectively with
`missing-pattern`. The test then applies the changed authored document, compares
the before/after identity and unrelated content, and validates the repaired
evidence:

```text
Validated stories/checkout.topo.json (checkout) against <revision> with working tree changes
  submit-checkout: src/checkout.ts:9-9
  charge-order: src/payment.ts:3-5
  audit-order: src/checkout.ts:12-14
```

Finally it commits the branch change, runs `topo scan` and
`topo story preview`, and verifies the locally viewable generated artifact at
`.topo/cache/site/stories/checkout/viewer.html` cites
`authorizePayment`. The authored story remains in `stories/`; generated
renderer and cache output remains in `.topo/cache/site/`.

Run the walkthrough with:

```sh
corepack yarn workspace @topo/cli build
corepack yarn workspace @topo/cli test -- story-authoring.test.ts
```

Successful schema and anchor resolution proves structure and source evidence
exist at that working-tree state. It does not prove that the explanation is
semantically accurate or complete; human review remains required.

---
name: topo-story-authoring
description: "Create or update source-grounded Topocode stories locally, validate anchors, and preview committed results without invoking a hosted model."
user-invocable: true
disable-model-invocation: false
---

# Topocode story authoring

Use this workflow when a branch needs a focused architecture explanation.
The coding agent is the author: read the relevant source, branch diff, and
existing `stories/**/*.topo.json` documents before changing a story. Do not
invoke a hosted model service, and do not add model execution to `topo scan`.

## Create or update the authored story

Write the durable document under `stories/**/*.topo.json` using
`node_modules/@jdylanmc/topo-code/story.schema.json` (or the same exported
`@jdylanmc/topo-code/story.schema.json` from a global installation).
Keep authored documents outside `.topo/cache/`;
that directory contains generated output and is never the editing surface.

For a new story, choose one stable lowercase `id`, a focused title and summary,
small sections, and repository-relative source anchors. For an update, retain
the document `id`, section and anchor IDs, and unrelated narrative or
connections. Change only evidence and explanation affected by the branch.
Never store derived line ranges, excerpts, renderer IDs, or renderer JSON in the
authored document.

## Run the objective repair loop

Validate the uncommitted draft against the current working tree:

```sh
npm exec --no -- topo story validate . stories/example.topo.json
```

Repair each reported `invalid-document`, `missing-file`, `missing-symbol`, or
`missing-pattern` or `stale-source` failure by rereading the cited source and updating the
smallest affected authored fields. Repeat until validation succeeds. A success
lists every resolved source location but does **not** establish semantic
accuracy or complete explanation coverage; the author and human reviewer remain
responsible for those judgments.

Commit the source and authored story together. Build or refresh the generated
site, preview the committed story, and inspect it locally:

```sh
npm exec --no -- topo init .
npm exec --no -- topo story preview . stories/example.topo.json
npm exec --no -- topo serve .
```

Home inventories all committed supported stories, not only the preview target.
Scanning is optional for generated Repository exploration.
Open `/stories/<story-id>/`. If source changes later, rerun validation before
previewing and preserve identity plus unrelated authored intent during repairs.
Humans review the authored explanation and generated view; they do not edit the
renderer output in `.topo/cache/site`.

Commit only when authorized by the repository owner. For a globally installed
CLI, use `topo` directly instead of `npm exec --no -- topo`.
Source-grounded native rendering requires the repository's Git `origin` remote
for evidence validation. Do not invent a remote. Initialization and anchor-free
capability demos do not require one; demos must never replace factual evidence.

## Minimal source-grounded document

Read the actual source before adapting this example. `symbol` names a compiler
declaration; `pattern` is an exact text match within the file. Anchors store
neither derived line numbers nor renderer-specific data.

```json
{
  "schemaVersion": "1.0",
  "id": "request",
  "title": "Request handling",
  "summary": "A focused explanation verified against the source.",
  "anchors": [{"id": "handler", "path": "src/handler.ts", "symbol": "handle"}],
  "sections": [{"id": "handle", "title": "Handle request", "body": "Describe the observed behavior.", "anchorIds": ["handler"]}],
  "connections": []
}
```

Architecture is the default; `diagramFamily` also accepts `workflow`, `sequence`,
`dataflow` and `lifecycle`. Every source-grounded section needs evidence. Use
`classification: "capability-demo"` only for explicitly conceptual, anchor-free
renderer demonstrations, never to bypass missing factual evidence. Prefer
small focused stories and short labels. For source moves, reread both sides,
repair only affected anchors and explanation, and retain IDs/unrelated intent.
The package includes executable before/after fixtures under
`node_modules/@jdylanmc/topo-code/examples/story-authoring/`.

## Rust/Tauri technical workflows

Read installed `node_modules/@jdylanmc/topo-code/docs/rust-tauri.md` and
`examples/rust-tauri/stories/` before using the extended contract.
Rust anchors support `language: "rust"`, an unambiguous lexical `symbol` and
exact `pattern`. Use `renderer: "graphviz", diagramFamily: "workflow"` explicitly
for decisions (`kind: "decision"`) or values (`kind: "data"`); native families
remain the default. Every technical anchor pins the complete file's SHA-256.
Every connection declares `classification: "source-traced"` or `"inferred"`,
`rationale` and `anchorIds`; source-traced connections require verified evidence.
Do not label an authored arrow source-derived or compiler control flow.

Hash changes require rereading and reconciling the explanation, not blindly
refreshing digests. Retain IDs when meaning is unchanged. Check exact node and
edge excerpts, cross-story/return links, Home inventory, shared app theme and
actual exports. Graphviz has its own layout receipt, not borrowed Archify
certification. A generic fixture is not evidence for another application's
behavior; disposable consumer diagrams/caches must not enter Topocode source.

Impl/trait methods are first-class source nodes. Repeated method names require
their structural qualified symbol, for example
`src/lib.rs::impl Engine#0::snapshot`, not an owner line/column. Comments and
blank lines change freshness/evidence but not these identities; preserve the
qualified symbol during comment-only hash repair. Tauri rest values and
spread-shifted argument positions remain unresolved, as do overwritten helpers
after dot or computed-member writes. Never promote those unresolved cases to
specific source-derived calls in a narrative.

# Enrichment runner

`topo enrich [repository]` explicitly runs the repository's configured enrichment command against the latest generated Topocode analysis. Invocation is consent to run that command. The command is trusted repository code; Topocode does not add a trust store, provider permission manager, sandbox, model adapter, or review workflow.

Run `topo scan` first whenever source changes. Enrichment is never invoked by `scan`, `ingest`, `init`, or `serve`.

## Configuration

Add an optional `enrichment` object to `.topo/config.json`:

```json
{
  "schemaVersion": "1.0",
  "repositoryId": "example",
  "modules": [],
  "enrichment": {
    "command": ["copilot", "-p", "{prompt}"],
    "promptFile": "docs/topo-enrichment-prompt.md",
    "timeoutMs": 600000
  }
}
```

- `command` is a nonempty argv array. The first item is the executable. Topocode uses `shell: false`; no shell interpolation occurs.
- `{prompt}` is replaced literally with the complete built-in and repository prompt text. `{input}` and `{output}` are replaced with absolute staged file paths.
- `promptFile` is an optional repository-relative UTF-8 file appended to Topocode's built-in instructions.
- `timeoutMs` is optional and defaults to 10 minutes. It must be a positive safe timer integer.
- The process runs in the repository directory with `TOPO_INPUT_PATH`, `TOPO_OUTPUT_PATH`, `TOPO_PROMPT_PATH`, and `TOPO_ANALYSIS_HASH` set. `TOPO_PROMPT_PATH` points to a file containing the same assembled text supplied through `{prompt}` and is intended for wrapper scripts.

The complete canonical graph and dashboard are written to the staged input. The prompt describes Topocode interpretation, partial-scan caution, inferred provenance, the exact output schema, valid graph references, the analysis hash, and the absolute staged paths.

The command must write JSON to the designated output file. Standard output is not parsed, so chatty provider output is harmless within the bounded log limit. The output document has this shape:

```json
{
  "schemaVersion": "1.0",
  "analysisHash": "64 lowercase hexadecimal characters",
  "provenance": "inferred",
  "comments": [
    {
      "text": "Secondary commentary",
      "nodeIds": ["node-id-from-input-graph"],
      "evidenceIds": []
    }
  ]
}
```

Each comment must reference at least one node or evidence identifier from the staged graph. An empty `comments` array is valid abstention.

## Publication and failures

Topocode holds the workspace lock only while staging and publishing. The provider does not block scans or authored view saves. Before publication, Topocode re-reads the current graph and dashboard and rejects the result if their analysis hash changed.

Successful output is written to `.topo/reports/outputs/enrichment.json` and included as the optional top-level `enrichment` field in `.topo/cache/site/data.json`. Static graph, dashboard, layout, architecture, curated views, and authored files are preserved.

Static regeneration keeps enrichment only when its analysis hash still matches. A changed graph or dashboard removes old commentary from the site. Stale references are not validated because stale output is expected after source changes. Malformed matching output is warned about and omitted without blocking valid static publication; the generated file remains available for diagnosis.

Missing configuration or generated input, missing executables or output, nonzero exits, timeouts, oversized output/logs, malformed JSON, invalid references, and stale publication are explicit errors. A failed run does not replace the last good static site or enrichment output.

# Local story authoring

The `topo-story-authoring` skill gives a coding agent a local workflow for
creating and evolving a source-grounded story. The agent reads the branch
source, diff, and existing stories; edits the authored `stories/**/*.topo.json`
document; and uses Topocode's objective validation and preview commands. No
hosted model service is required, and `topo scan` never invokes an agent or
model.

Start with `topo init <repo>` and `topo serve <repo>` for the empty Home.
After validating and committing a story, `topo story preview` populates the
same Home inventory with every supported committed story. `topo scan` is
optional for generated Repository exploration; it is not a preview prerequisite.

For parser-backed Rust/Tauri anchors, hash-bound technical branches, independent
Graphviz receipts and cache regeneration, use the [supported technical workflow](./rust-tauri.md).

Source-grounded stories may select any native diagram family and must keep
evidence on every section. Use `classification: "capability-demo"` only for an
explicitly conceptual, anchor-free renderer demonstration; it is labelled as
non-source-grounded and separated from factual catalogue entries. See
[source-grounded story preview](./story-preview.md) for the complete family,
classification, relationship-label, preview, and export contract.

## Executable before/after walkthrough

The regression fixture under `examples/story-authoring/` represents a real Git
repository at two points on a `payment-boundary` branch:

- `initial/` contains the first source and authored checkout story.
- `changed/` moves payment authorization to `src/payment.ts` and updates only
  the two affected anchors. The story ID, unrelated audit anchor and section,
  narrative, and connections remain unchanged.

`packages/cli/src/story-authoring.test.ts` creates the repository, commits the
initial source, authors the first story as an uncommitted draft, and runs:

```text
topo story validate <repo> <repo>/stories/checkout.topo.json
Validated stories/checkout.topo.json (checkout) against <revision> with working tree changes
  submit-checkout: src/checkout.ts:7-7
  charge-order: src/checkout.ts:10-12
  audit-order: src/checkout.ts:14-16
```

After committing and previewing that story, the test applies the changed source
while retaining the old story. Validation fails objectively with
`missing-pattern`. The test then applies the changed authored document, compares
the before/after identity and unrelated content, and validates the repaired
evidence:

```text
Validated stories/checkout.topo.json (checkout) against <revision> with working tree changes
  submit-checkout: src/checkout.ts:9-9
  charge-order: src/payment.ts:3-5
  audit-order: src/checkout.ts:12-14
```

Finally it commits the branch change, runs `topo scan` and
`topo story preview`, and verifies the locally viewable generated artifact at
`.topo/cache/site/stories/checkout/viewer.html` cites
`authorizePayment`. The authored story remains in `stories/`; generated
renderer and cache output remains in `.topo/cache/site/`.

Run the walkthrough with:

```sh
corepack yarn workspace @topo/cli build
corepack yarn workspace @topo/cli test -- story-authoring.test.ts
```

Successful schema and anchor resolution proves structure and source evidence
exist at that working-tree state. It does not prove that the explanation is
semantically accurate or complete; human review remains required.

# CLI reference

Run commands inside your project using `npm exec --no -- topo`, or use `topo`
directly after a global installation. Node.js 22+ and a Git repository are
required. Repository arguments default to the current directory where shown.

```text
topo init [repository] [--skills]
topo scan [repository] [--allow-partial] [--responsibilities path]
topo ingest <repository> <report.json> [more.json ...]
topo enrich [repository]
topo preview <repository> <story>
topo story validate <repository> <story>
topo story preview <repository> <story>
topo serve [repository] [--port 4173]
topo bundle [repository] [--output directory] [--base-path /path/]
```

| Command | Purpose |
| --- | --- |
| `init` | Create configuration and a ready-to-serve Home without scanning. `--skills` opts into local agent guidance. |
| `scan` | Generate structural evidence and repository exploration; render committed stories. Strict by default. |
| `ingest` | Ingest normalized report evidence against a clean scanned revision. |
| `enrich` | Explicitly run the repository-configured external command for inferred commentary. Never runs as part of scan. |
| `story validate` | Validate an authored draft and resolve its source anchors. |
| `story preview` | Render committed stories and refresh Home without requiring a scan. |
| `preview` | Legacy shorthand for story preview. |
| `serve` | Serve locally on `127.0.0.1`; default port is 4173. |
| `bundle` | Emit static files with all required runtime assets and notices. |

`--help` (or `-h`) prints the installed CLI contract. Unknown commands, arguments,
and unsupported option combinations fail explicitly.

## Important options

`scan --allow-partial` publishes a visibly incomplete preview and returns exit
code **2**. It is not a success override. Explicit Rust/Tauri analysis currently
requires this acknowledgement.

`scan --responsibilities <path>` accepts an explicit responsibility-grouping
proposal. See [logical architecture](./logical-architecture.md).

`bundle --base-path` must be `/` or an absolute URL path ending in `/`. It creates
that path beneath the output directory. Default output is `.topo/bundle`.

`serve --port 0` requests an available port; use the printed URL.

## Related contracts

- [Configuration and workspace lifecycle](./workspace.md)
- [Story authoring](./story-authoring.md)
- [Report ingestion](./reports.md)
- [Explicit enrichment](./enrichment.md)
- [Rust/Tauri support and limits](./rust-tauri.md)

{
  "name": "@topo/cli",
  "version": "0.0.0",
  "private": true,
  "type": "module",
  "bin": {
    "topo": "./dist/main.js"
  },
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc -b && node ../../scripts/package-skills.mjs",
    "typecheck": "tsc -b --pretty false",
    "test": "vitest run --no-file-parallelism"
  },
  "dependencies": {
    "@topo/diagram-core": "workspace:*",
    "@topo/enrichment": "workspace:*",
    "@topo/graph": "workspace:*",
    "@topo/languages": "workspace:*",
    "@topo/modules": "workspace:*",
    "@topo/reports": "workspace:*",
    "@topo/scanner": "workspace:*",
    "@topo/schema": "workspace:*",
    "@topo/site": "workspace:*",
    "@topo/story": "workspace:*",
    "@topo/views": "workspace:*",
    "@topo/workspace": "workspace:*"
  },
  "devDependencies": {
    "@types/node": "^22.20.1",
    "typescript": "^7.0.2",
    "vite": "8.2.2",
    "vitest": "^5.0.0"
  }
}

---
name: topo-story-authoring
description: "Create or update source-grounded Topocode stories locally, validate anchors, and preview committed results without invoking a hosted model."
user-invocable: true
disable-model-invocation: false
---

# Topocode story authoring

Use this workflow when a branch needs a focused architecture explanation.
The coding agent is the author: read the relevant source, branch diff, and
existing `stories/**/*.topo.json` documents before changing a story. Do not
invoke a hosted model service, and do not add model execution to `topo scan`.

## Create or update the authored story

Write the durable document under `stories/**/*.topo.json` using
`node_modules/@jdylanmc/topo-code/story.schema.json` (or the same exported
`@jdylanmc/topo-code/story.schema.json` from a global installation).
Keep authored documents outside `.topo/cache/`;
that directory contains generated output and is never the editing surface.

For a new story, choose one stable lowercase `id`, a focused title and summary,
small sections, and repository-relative source anchors. For an update, retain
the document `id`, section and anchor IDs, and unrelated narrative or
connections. Change only evidence and explanation affected by the branch.
Never store derived line ranges, excerpts, renderer IDs, or renderer JSON in the
authored document.

## Run the objective repair loop

Validate the uncommitted draft against the current working tree:

```sh
npm exec --no -- topo story validate . stories/example.topo.json
```

Repair each reported `invalid-document`, `missing-file`, `missing-symbol`, or
`missing-pattern` or `stale-source` failure by rereading the cited source and updating the
smallest affected authored fields. Repeat until validation succeeds. A success
lists every resolved source location but does **not** establish semantic
accuracy or complete explanation coverage; the author and human reviewer remain
responsible for those judgments.

Commit the source and authored story together. Build or refresh the generated
site, preview the committed story, and inspect it locally:

```sh
npm exec --no -- topo init .
npm exec --no -- topo story preview . stories/example.topo.json
npm exec --no -- topo serve .
```

Home inventories all committed supported stories, not only the preview target.
Scanning is optional for generated Repository exploration.
Open `/stories/<story-id>/`. If source changes later, rerun validation before
previewing and preserve identity plus unrelated authored intent during repairs.
Humans review the authored explanation and generated view; they do not edit the
renderer output in `.topo/cache/site`.

Commit only when authorized by the repository owner. For a globally installed
CLI, use `topo` directly instead of `npm exec --no -- topo`.
Source-grounded native rendering requires the repository's Git `origin` remote
for evidence validation. Do not invent a remote. Initialization and anchor-free
capability demos do not require one; demos must never replace factual evidence.

## Minimal source-grounded document

Read the actual source before adapting this example. `symbol` names a compiler
declaration; `pattern` is an exact text match within the file. Anchors store
neither derived line numbers nor renderer-specific data.

```json
{
  "schemaVersion": "1.0",
  "id": "request",
  "title": "Request handling",
  "summary": "A focused explanation verified against the source.",
  "anchors": [{"id": "handler", "path": "src/handler.ts", "symbol": "handle"}],
  "sections": [{"id": "handle", "title": "Handle request", "body": "Describe the observed behavior.", "anchorIds": ["handler"]}],
  "connections": []
}
```

Architecture is the default; `diagramFamily` also accepts `workflow`, `sequence`,
`dataflow` and `lifecycle`. Every source-grounded section needs evidence. Use
`classification: "capability-demo"` only for explicitly conceptual, anchor-free
renderer demonstrations, never to bypass missing factual evidence. Prefer
small focused stories and short labels. For source moves, reread both sides,
repair only affected anchors and explanation, and retain IDs/unrelated intent.
The package includes executable before/after fixtures under
`node_modules/@jdylanmc/topo-code/examples/story-authoring/`.

## Rust/Tauri technical workflows

Read installed `node_modules/@jdylanmc/topo-code/docs/rust-tauri.md` and
`examples/rust-tauri/stories/` before using the extended contract.
Rust anchors support `language: "rust"`, an unambiguous lexical `symbol` and
exact `pattern`. Use `renderer: "graphviz", diagramFamily: "workflow"` explicitly
for decisions (`kind: "decision"`) or values (`kind: "data"`); native families
remain the default. Every technical anchor pins the complete file's SHA-256.
Every connection declares `classification: "source-traced"` or `"inferred"`,
`rationale` and `anchorIds`; source-traced connections require verified evidence.
Do not label an authored arrow source-derived or compiler control flow.

Hash changes require rereading and reconciling the explanation, not blindly
refreshing digests. Retain IDs when meaning is unchanged. Check exact node and
edge excerpts, cross-story/return links, Home inventory, shared app theme and
actual exports. Graphviz has its own layout receipt, not borrowed Archify
certification. A generic fixture is not evidence for another application's
behavior; disposable consumer diagrams/caches must not enter Topocode source.

Impl/trait methods are first-class source nodes. Repeated method names require
their structural qualified symbol, for example
`src/lib.rs::impl Engine#0::snapshot`, not an owner line/column. Comments and
blank lines change freshness/evidence but not these identities; preserve the
qualified symbol during comment-only hash repair. Tauri rest values and
spread-shifted argument positions remain unresolved, as do overwritten helpers
after dot or computed-member writes. Never promote those unresolved cases to
specific source-derived calls in a narrative.

# The `.topo/` workspace

`topo init <repository>` initializes a ready-to-serve diagram home without
analysis, a model, native rendering, or a Git commit. `--skills` adds optional
authoring guidance; neither form launches a server/browser. Repeated init
preserves the current generated site, diagrams and authored context.
`topo scan <repository>` also initializes the workspace without replacing existing
configuration or human-authored metadata. Unknown config versions, malformed
JSON and unsupported options are errors, not invitations to reset a workspace.

| Path | Lifecycle | Source control / review |
| --- | --- | --- |
| `config.json` | Authored; created once | Commit and review |
| `graph/graph.json` | Generated canonical graph | Optional; review architectural changes |
| `graph/layout.json` | Generated, persisted positions | Optional; commit when sharing spatial context |
| `graph/architecture.json` | Derived directories, cycles and scaling | Optional; reproducible from the graph |
| `reports/inputs/*.json` | Normalized evidence inputs, content-addressed | Independently commit and review |
| `reports/outputs/dashboard.json` | Generated normalized dashboard | Optional; reproducible from graph and inputs |
| `reports/outputs/layout-delta.json` | Comparison against the previous layout | Optional; inspect removed subjects and orphaned pins |
| `reports/outputs/curated-views.json` | Generated authored-view snapshot | Optional; regenerate from metadata |
| `reports/outputs/curated-view-deltas.json` | Comparison against explicitly reviewed membership | Optional; pending changes persist across scans |
| `reports/outputs/enrichment.json` | Generated, inferred commentary tied to graph/report inputs | Optional; not authored metadata or verified facts |
| `metadata/` | Human-authored notes and pins | Commit and review; never overwritten by generation |
| `metadata/views/<id>.json` | Named path view, overrides, pins, review baseline | Commit and review; explicit local saves only |
| `cache/site/` | Compiled site assets and atomic data snapshot | Ignore; regenerate |
| `cache/site/site-state.json` | Explicit `unscanned` state, bound to repository ID; no graph/revision claim | Ignore; removed after scanned data is written |
| `cache/site/repository.json` | Generated repository hierarchy, source evidence and page index | Ignore; regenerate with scan |
| `cache/site/repository/<view-id>/viewer.html` | Pinned Archify views for bounded repository scopes | Ignore; included in static bundles |
| `cache/enrichment-runs/` | Temporary command input, prompt and staged output | Ignore; owned run directories are cleaned after execution |
| `cache/write.lock` | Ephemeral single-writer lock | Ignore |

The tool-generated `.topo/.gitignore` default ignores **only `/cache/`**. Do not
blanket-ignore `.topo/`: doing so hides authored config, report evidence and
architecture review. Existing workspace ignore files are preserved so each
repository can choose a stricter policy without changing the initializer default.

This repository checks in a project-specific policy that also ignores `/graph/`
and `/reports/outputs/`. Generated maps, local layout state and output reports
remain local here, while configuration, authored metadata and normalized report
inputs remain source-controllable.

## Configuration

```json
{
  "schemaVersion": "1.0",
  "repositoryId": "my-repository",
  "modules": []
}
```

The repository ID is initialized from the directory name. Set it explicitly
before sharing a workspace between differently named clones. `modules` selects
statically registered optional producers: `@topo/module-degree` and
`@topo/module-cycles`. Either can run independently; an empty list keeps the
core-only workflow. Scan and ingest compose the same enabled set before
generating artifacts. Unknown IDs fail rather than loading arbitrary packages.
See [module composition](./modules.md) for build-time versus generate-time support.
Public package-scope ownership and third-party module loading are not established
by the private local `@topo/*` workspace names.

Optional `enrichment` configuration selects an argv command and repository
prompt file for explicit `topo enrich`. It is not run by scanning or ingestion,
and there is no extra trust/approval store. See the [runner guide](./enrichment.md)
and [commentary contract](./enrichment-contract.md). A repository command can use
its provider's network/account and its normal user permissions; it is not
sandboxed by Topocode.

Optional `catalogue` configuration changes the generated shell's title,
description, accent color, category order, and per-story category overrides.
It cannot add executable extensions or replace the pinned Archify renderer.
See the [story catalogue walkthrough](./story-catalogue.md).
The repository title defaults to `repositoryId`; Topocode product branding
remains separate. Init does not refresh an existing site; use preview or scan.

An initialized-only site (including an unborn Git repository) is bundleable.
It has shell assets and all legal notices, but no `data.json` or fake graph.
After story preview, it remains unscanned while carrying the full authored
inventory. Bundling refreshes committed stories when HEAD exists. Missing
scanned data cannot be bypassed with an unscanned marker; scanned bundles still
validate graph identity, revision, repository fingerprints and runtime assets.
Without HEAD, bundling requires the cached Home to match the current empty
initialized Home and no rendered stories to remain. A preview retained across
an orphan-branch switch is rejected without changing the cache or existing
bundle; restore the intended committed source before bundling.

## Layout and authored pins

Generated positions live in `graph/layout.json`; the global default view is
regenerated using the previous layout. Unchanged subjects retain their positions.
The layout delta reports additions/removals and orphaned pins. It depends on the
previous snapshot, so its first-run result intentionally differs from subsequent
unchanged runs. See [graph layout](./graph-layout.md) for projection and grid rules.

Optional `metadata/pins.json` is an array of the graph engine's `LayoutPin` records:
an explicit subject, stable pin ID, `anchor` with a repository-relative path and
optional symbol-scoped pattern, and integer `position`. The CLI validates and
passes these records to the graph engine; it does not rewrite them. Line numbers
are diagnostics only, never anchor identity. Orphaned pins remain authored data
and produce warnings rather than disappearing.

Named [human-authored views](./curated-views.md) have independent path-based
membership and anchored pins. Their reviewed baselines change only through
explicit review, unlike the default layout delta's previous-snapshot comparison.
The local server can save view definitions with optimistic graph/file revisions;
regeneration and ingestion validate but never rewrite them.

## Concurrency, invalidation and recovery

Generation and ingestion acquire an exclusive per-workspace lock. A second
writer fails explicitly. A lock left by an interrupted process must be removed
manually **only after checking that the recorded process is no longer running**.
Enrichment holds this lock only while capturing inputs and publishing output,
not during the provider command. Publication rechecks the current analysis
hash, so a concurrent scan cannot be overwritten by an old enrichment result.
Changed graph/report analysis omits old commentary from the site; unchanged
analysis preserves it. View and layout edits alone do not invalidate it.

Generated files use temporary siblings followed by rename. The website reads
one atomically replaced `cache/site/data.json`, not graph and layout files
independently, so it cannot combine snapshots from two different regenerations.
Reviewable files are replaced individually: after interruption, rerun generation
to reconstruct them; no multi-file filesystem transaction is claimed.
When the tool's compiled assets change, retired files are pruned from the cached
site. Reload open browser tabs after upgrading the tool; the asset set itself is
not an atomic multi-file deployment.

Scanner output is recomputed, not restored from a hidden cross-machine cache.
The workspace's `cacheKey` helper hashes canonical evidence/configuration; any
future scanner cache must include adapter version, schema version, configuration
and source fingerprints. Do not share `cache/` between machines. Stable graph
and report artifacts contain no local absolute paths or live generation times.

The static pipeline refuses symlinked `.topo` paths and path traversal. It does not modify
source files, install dependencies in scanned repositories, stage files, or
resolve Git merge conflicts. If two branches change the same generated graph,
merge the authored configuration and report inputs first, then regenerate.
Those guarantees do not sandbox a repository command explicitly invoked through
`topo enrich`; its behavior remains the operator's responsibility.