@laitszkin/apollo-toolkit 3.10.0 → 3.11.1

package/init-project-html/SKILL.md

@@ -1,181 +1,173 @@
 ---
 name: init-project-html
 description: >-
-  Build the HTML architecture atlas. Macro `index.html` is ONE SVG showing feature-modules (clusters) AND every sub-module (nodes inside) together, with many-to-many edges, producer/consumer loops, and at least one cross-feature `m-edge--cross` data-row when applicable; macro MUST index every sub-module page in `atlas-submodule-index`. Each `features/<slug>/<sub-module>.html` describes ONLY itself: `sub-io` (function I/O) + `sub-vars` (variables-with-business-purpose) + `sub-dataflow` (internal flow) + `sub-errors`. Feature `index.html` stays lightweight (story + submodule-nav). Read strategy avoids context loss: list feature modules first; with subagents, dispatch one read-only subagent per feature and aggregate summaries before drawing; without subagents, read one feature, emit its pages, update macro incrementally, drop details, then move on — never read the whole codebase before writing. Distinctive typography; no purple-gradient/Inter defaults.
+  Declare the project HTML architecture atlas through `apltk architecture` CLI verbs instead of hand-writing SVG/HTML. Two acceptance criteria gate completion: (1) the macro diagram clearly shows feature × sub-module relationships — data flow, call/return interaction logic, error handling, rollback — all expressed as `--kind call|return|data-row|failure` edges; (2) each sub-module's internal diagram clearly shows function-level interactions inside it — function-to-function flow via `dataflow add --fn <declared-fn>`, variable state transitions via `--reads`/`--writes` referencing declared variables, and the resulting local data flow. The tool owns layout, CSS, and pan/zoom for both diagrams; `validate` rejects any step that references an undeclared function or variable. With subagents, each owns one feature and declares every intra-feature interaction itself; the main agent only declares cross-feature edges. Anchor every declaration to repo evidence.
 ---
 
 # Init Project HTML
 
 ## Dependencies
 
-- Required: none (the template asset `references/architecture.css` ships with this skill and is copied at runtime).
-- Conditional: `spec-to-project-html` when the same atlas needs spec-driven refresh — that skill obeys the rules below.
-- Optional: `align-project-documents` when `docs/features` already names capabilities.
-- Optional: local `frontend-design` skill for bolder, non-generic visual direction.
-- Fallback: codebase too large for one pass → document scanned roots, explicit omissions, phased plan. **MUST NOT** pretend untread paths were verified.
+- Required: none (the CLI ships its own layout engine, CSS, and pan/zoom client; `apltk architecture` is installed with this toolkit).
+- Conditional: `spec-to-project-html` when the same atlas needs spec-driven refresh — that skill uses the same CLI with `--spec`.
+- Optional: `align-project-documents` when `docs/features` already names the user-visible capabilities.
+- Fallback: codebase too large for one pass → use the subagent strategy below, document scanned roots and explicit omissions in `meta.summary`. **MUST NOT** declare components for code paths that were never read.
 
 ## Non-negotiables
 
-### Rule 1 — Cross-submodule interactions live only on the macro page
+### Rule 1 — Use the CLI; never hand-author atlas HTML
 
-- **MUST** render `resources/project-architecture/index.html` as **one SVG figure** showing both layers together:
-  - Layer A: **feature ↔ feature** user-visible journeys.
-  - Layer B: **sub-module ↔ sub-module** concrete calls / returns / data-row hand-offs that realise Layer A.
-- **MUST** draw each feature as an `m-cluster` (dashed frame); sub-modules are clickable nodes inside their cluster.
-- **MUST** include at least one node-pair carrying **≥2 edges** (e.g. service → db with SELECT / INSERT / UPDATE) to prove multi-edge support.
-- **MUST** include at least one **producer ↔ consumer** loop (call/return pair, or cyclic data-row).
-- **MUST** use **`m-edge--cross`** dashed-heavy edges for cross-feature data-row hand-offs whenever the system has them.
-- **MUST** include `<nav class="atlas-submodule-index">` linking every sub-module page in the atlas.
+The atlas state lives in `resources/project-architecture/atlas/` (`atlas.index.yaml` + per-feature YAMLs). Every change goes through `apltk architecture <verb> ...`. After any mutation, the CLI re-renders `resources/project-architecture/**/*.html` with the correct layout, CSS, pan/zoom, and ARIA — agents **MUST NOT** edit those HTML files by hand or invent additional ones.
 
-### Rule 2 — Sub-module pages describe **only themselves**
+### Rule 2 — Sub-module pages describe only themselves; the internal-dataflow diagram is zoomable and structurally typed
 
-Each `features/<slug>/<sub-module>.html` contains exactly:
+What the CLI emits on each sub-module page is fixed:
 
-1. `sub-io` — function I/O table (signature + side-effect chip + one-line purpose).
-2. `sub-vars` — **variables-with-business-purpose** table: every identifier this sub-module holds or threads between its functions (params, local state, struct fields, DB columns, config knobs, counters, time anchors) with type, scope chip (`sub-vars__scope--call|tx|persist|instance|loop`), and **business purpose** in business language (why it exists / which branch it decides / what breaks without it).
-3. `sub-dataflow` — internal value flow between this sub-module's own functions (optional small SVG; **never** draw external sub-modules here).
-4. `sub-errors` — errors this sub-module raises/returns (condition + meaning; HTTP mapping may be one line).
+- function I/O table (`function add --feature X --submodule Y --name fn --in ... --out ... --side ... --purpose ...`),
+- variables-with-business-purpose table (`variable add --name v --type T --scope call|tx|persist|instance|loop --purpose ...`),
+- internal dataflow diagram — ordered steps the renderer lays out as a numbered top-to-bottom flow inside a pan/zoom viewport with +/−/Fit controls, exactly like the macro SVG. Each step is `dataflow add --step "..." [--fn <declared-fn>] [--reads "v1,v2"] [--writes "v3,v4"]`. The renderer surfaces `--fn` as a pill at the top of the step box, `--reads` as a green chip on the bottom-left, and `--writes` as an orange chip on the bottom-right — so a single SVG simultaneously shows the function-to-function flow inside the sub-module AND the variable state transitions across the run,
+- local errors (`error add --name ErrX --when ... --means ...`).
 
-**Forbidden** on sub-module pages: "I call X / Y calls me" narrative, cross-boundary `flow-edge-manifest`, cross-boundary `flow-return-row`, or any structure describing inter-submodule choreography. If unavoidable, end with one sentence + link "see macro atlas for cross-boundary interactions".
+Schema rules the CLI enforces on every `dataflow add` (so the diagram never lies):
 
-### Rule 3 — Read order: never let the codebase wipe the context window
+- `--fn <name>` must match a function declared **in the same sub-module** via `function add`. If it does not, `validate` fails — declare the function first.
+- Every name in `--reads` / `--writes` must match a variable declared **in the same sub-module** via `variable add`. If it does not, `validate` fails — declare the variable first.
+- `--fn` / `--reads` / `--writes` are optional but additive: omitting them is allowed for purely descriptive steps, but for any non-trivial sub-module the function-and-variable structure **MUST** be filled in so the diagram conveys the function-to-function flow and the variable state transitions.
 
-Real production codebases dwarf the main agent's context. Reading the whole repo before writing pushes early details out by the end, making macro edges and sub-module pages contradict each other. **MUST** follow one of these two strategies:
+Cross-boundary narratives ("I call X", "Y calls me") **MUST** be expressed as edges (`edge add --from X/sub --to Y/sub --kind call|return|data-row|failure --label ...`), never as sub-module page prose. The CLI enforces this by design — there is no verb to add cross-boundary text to a sub-module page.
 
-- **With subagents (preferred):** main agent first builds the **feature-module list** (slug + entry + boundary resources only), then dispatches **one read-only subagent per feature**. Each subagent deep-reads and returns ONLY a structured summary (sub-module list; per sub-module: function I/O, variables-with-business-purpose, internal flow steps, errors raised; outbound edges to other features). Main agent collects every summary and **only then** emits the macro SVG and all pages in one pass.
-- **Without subagents:** process features **one at a time** — read feature A end-to-end, **immediately** emit `features/A/` (overview + every sub-module page) and incrementally add A's cluster, nodes, and known edges to the macro. Mark edges pointing at unread features with `data-edge-target-pending="<future-slug>"`. **Drop A's function-level details from working memory**, then read feature B. After every feature is written, resolve all pending placeholders in the macro. **Never** read everything before writing.
+### Rule 3 — Read order: never let the codebase wipe the context window; subagents own their own feature
 
-Both paths share one invariant: at any moment the main agent only holds *current-feature details + cross-feature boundary notes*.
+Real production codebases dwarf the main agent's context. Reading the whole repo before declaring pushes early details out by the end, making macro edges and sub-module declarations contradict each other. The split below also draws a hard responsibility line between the worker and the orchestrator. **MUST** follow one of:
 
-### Rule 4 — Per-page section contracts
+- **With subagents (preferred):** first enumerate the **feature-module list** (slug + entry + boundary resources only). Then dispatch **one (write-capable) subagent per feature**. Each subagent:
+  - deep-reads its own feature,
+  - declares **everything intra-feature** itself via `apltk architecture ... --feature <slug>` (sub-modules; per sub-module functions / variables / internal dataflow / errors; **every intra-feature edge** — function calls between sub-modules, error edges, rollback / compensation edges; variable state transitions are captured as ordered `dataflow add` steps on each sub-module),
+  - returns ONLY a structured summary of (i) the sub-module list and (ii) the **outbound boundaries** the main agent needs to wire (calls / data-rows / failure edges to other features' sub-modules, including direction and the consuming/producing endpoints).
 
-Each page type has a fixed required set of sections. Violating the contract is a Rule 1 or Rule 2 violation by definition.
+  The main agent never re-reads source for that feature. It collects every subagent's outbound-boundary summary and declares **only the cross-feature edges** (and any cross-feature actors / meta) itself, then runs `apltk architecture validate`.
+- **Without subagents:** process features **one at a time** — read feature A end-to-end, declare its sub-modules, functions, variables, internal dataflow, errors, and intra-feature edges via the CLI, then move on. For cross-feature edges that point at not-yet-declared features, declare the placeholder feature with `feature add --slug <future> --title <future>` first, then add the edge; subsequent passes set the real title/story. Drop A's function-level details from working memory before reading feature B.
 
-**A) Macro `resources/project-architecture/index.html`** (the only page that draws interactions):
+Both paths share one invariant: at any moment the agent doing the deep read only holds *that feature's details + cross-feature boundary notes*. The main agent's working set, in subagent mode, is **boundaries only**. Run `apltk architecture validate` after the last feature to catch dangling edges, unknown endpoints, or missing required fields.
 
-1. `<header class="atlas-header">` — title + generation timestamp.
-2. `<section class="atlas-summary">` — prose explaining why feature modules and sub-modules sit in one diagram; cite a real producer+consumer / multi-edge case.
-3. `<section class="atlas-legend">` — explains the four edge types: solid arrow = **call**, thin dashed = **return**, warm-tone heavy dashed = **data-row**, plus a note that multiple edges between the same node pair are allowed.
-4. `<section class="flow-section flow-section--macro">` with **one** `<figure class="flow-chart flow-chart--macro flow-chart--svg">` honouring every MUST in Rule 1, plus a mirrored `<ol class="flow-edge-manifest flow-edge-manifest--macro">` (one row per edge, with `data-edge-id` + `data-edge-kind`).
-5. `<nav class="atlas-submodule-index">` — links to every sub-module page across all features.
-6. `<nav class="atlas-features">` (optional) — middle-tier nav to each feature index.
+### Rule 4 — Evidence over invention
 
-**B) Feature overview `features/<feature-slug>/index.html`** (intentionally lightweight; no cross-submodule flowchart):
-
-1. `<nav class="breadcrumb">` (`../../index.html` → macro).
-2. `<header>` — user-visible capability name.
-3. `<section class="feature-story">` — 1–3 paragraphs of user story; close with one sentence + link back to the macro.
-4. `<section class="submodule-nav">` — table of every sub-module page (link + one-line own responsibility).
-5. Optional `<section class="feature-trace">` for spec-ID traceability.
-
-**Forbidden on feature index**: `flow-chart--submodules`, `flow-chart--end-to-end`, `flow-edge-manifest`, or any other cross-submodule structure — those belong on the macro.
-
-**C) Sub-module `features/<feature-slug>/<sub-module-slug>.html`** (self-only; matches Rule 2):
-
-1. `<nav class="breadcrumb">`: `../../index.html` · `./index.html` · current sub-module.
-2. `<header>` — sub-module name + **own** responsibility (one paragraph; no "who I talk to").
-3. `<section class="sub-io">` — columns `function | signature (in / out) | side effects | purpose`; side-effect chips `pure` / `io` / `write` / `tx` / `lock` / `network` / …
-4. `<section class="sub-vars">` — columns `variable | type | lifecycle / scope | business purpose`; cover **every** business-branch-affecting identifier; scope chip values listed in Rule 2; business purpose in business language (no bland "stores some value").
-5. `<section class="sub-dataflow">` — numbered steps; optional small `<svg class="sub-dataflow__svg">` (nodes = internal variables/functions only; height ≤ 240, width ≤ 720).
-6. `<section class="sub-errors">` — errors raised/returned (condition + meaning).
-7. footer: one-sentence links back to `../../index.html` and `./index.html`.
-
-If a sub-module truly holds no business-branch-affecting variables (rare; usually pure pass-through), `sub-vars` MUST still appear as a single-row table that says so with a one-line justification.
-
-### Rule 5 — Naming, IDs, and shared assets
-
-- **`feature-slug`**: kebab-case, matching the **user-language capability** (e.g. `invite-code-registration`).
-- **`sub-module-slug`**: kebab-case, identifying the implementation boundary (e.g. `web-register-ui`, `public-api`, `registration-service`, `postgresql`).
-- **`data-feature-id` / `data-submodule-id`**: optional node attributes; **MUST** match directory/file names.
-- **`data-edge-id`**: stable id per macro edge (mirrored in the manifest row).
-- **`data-edge-kind`**: one of `call` | `return` | `data-row` | `failure`.
-- **Shared CSS**: on first run, copy `references/architecture.css` to `resources/project-architecture/assets/architecture.css`. Root `index.html` → `href="assets/architecture.css"`; everything under `features/<feature-slug>/` → `href="../../assets/architecture.css"`.
-
-### Rule 6 — Accessibility and styling minima
-
-- The macro SVG `<figure>` **MUST** carry an `aria-label` plus the mirrored `<ol class="flow-edge-manifest">` so screen-reader users get the full edge list without chasing pixels.
-- Cluster and node links **MUST** wrap their `<g>` in `<a>` and provide readable `<text>` (browsers expose `<text>` as the accessible name).
-- Sub-module `sub-io` and `sub-vars` tables **MUST** use semantic `<thead>` / `<tbody>`.
-- Colour MUST NOT be the sole semantic carrier: edge differences encode via line style (solid / dashed / heavy-dashed) AND colour.
-- Every diagram is static SVG — respect `prefers-reduced-motion` by not adding animation.
-- Quality bar: high contrast, print-friendly, restrained palette; avoid the "AI-default purple gradient" and Inter look-alike. Pair a recognisable display face (e.g. `Fraunces`) with `Plus Jakarta Sans`. Edges use `currentColor` so light/dark adapt; pages stay readable across widths via SVG `viewBox`.
-
-### Rule 7 — Other binding rules
-
-- **MUST** read the entire production codebase along language boundaries; record skipped roots and the reason in `atlas-summary`.
-- **MUST** anchor every user-visible capability to a concrete entry; **never** invent modules or integrations.
-- **MUST** migrate legacy single-file `features/<slug>.html` or feature-level cross-submodule flowcharts to the new layering on first touch.
-
-> Reference cheat sheets (DOM examples, the macro SVG class-hook table, vocabulary glossary) live in `references/TEMPLATE_SPEC.md`. That file is reference material only — every binding rule already lives here.
+- **MUST** anchor every declared feature, sub-module, function, variable, dataflow step, and edge to a concrete path / symbol / SQL / config; record scanned roots and any deliberate omissions in `meta.summary` via `apltk architecture meta set --summary "..."`.
+- **MUST NOT** invent modules, integrations, or sub-modules just because the diagram "looks balanced". Empty rows are valid; lies are not.
 
 ## Standards (summary)
 
-- **Evidence**: every node and edge traces to a path/symbol/SQL/config.
-- **Execution**: feature-module list (shallow) → branch by environment (subagent fan-out or sequential read-write) → pending-edge resolution + cross-link check.
-- **Quality**: macro SVG carries at least one multi-edge case, one loop, and one cross-feature edge (when applicable); sub-module pages stay self-only; print-friendly contrast; zero `pending` edges remaining.
-- **Output**: `resources/project-architecture/` tree obeying Rules 1–7 — anything else counts as a violation.
+- **Evidence**: every CLI declaration traces to a path/symbol/SQL/config; uncertain areas surface as `TBD` strings or are omitted with a recorded reason.
+- **Execution**: feature-module list (shallow) → branch by environment (subagent fan-out or sequential read-declare) → `apltk architecture validate` → handover report.
+- **Quality**: macro SVG carries every cross-feature data-row edge that exists in the system; sub-module declarations are self-only; pan/zoom + Fit work in the rendered HTML; `apltk architecture validate` returns OK.
+- **Output**: `resources/project-architecture/atlas/` (YAML state) + `resources/project-architecture/**/*.html` (renderer output) — both managed by the CLI.
+
+## Acceptance criteria
+
+The atlas is only complete when both of the following are demonstrably true on the rendered HTML (open `resources/project-architecture/index.html` and one representative sub-module page to verify):
+
+1. **Macro diagram clearly shows the relationships between features and sub-modules**, including:
+   - **Data flow** — every cross-feature DB row, queue topic, or cache key hand-off is a `--kind data-row` edge between the producing and consuming sub-modules (not free-form prose).
+   - **Interaction logic** — synchronous request/response paths are paired `--kind call` (outbound) and `--kind return` (response) edges with a label that names the call site or response shape.
+   - **Error handling and rollback** — every failure / compensation / retry path that crosses a sub-module boundary is a `--kind failure` edge with a label that names what is being rolled back or compensated.
+   - No interaction is captured *only* in sub-module page prose — if it crosses a sub-module boundary it MUST appear as an edge so the macro SVG carries it.
+2. **Each sub-module's internal diagram clearly shows the function-level interactions inside the sub-module**, including:
+   - **Function-to-function flow** — every step that does non-trivial work carries `--fn <declared-fn>`. The sequence of pills along the steps reveals which function is active at each point in the flow.
+   - **Variable state transitions during the run** — every variable that is read or mutated by a step is declared via `variable add`, and that step lists it in `--reads` (the value flows in) or `--writes` (the value is created/updated). Reading the steps top-to-bottom traces each variable's life cycle.
+   - **Local data flow** — the ordered step boxes (with reads/writes chips) read as a directed flowchart, ending at the sub-module boundary (returning a value, persisting a row, emitting an event).
+
+`apltk architecture validate` MUST return OK before reporting completion — it enforces both criteria's structural pieces (unknown sub-modules on edges, unknown functions/variables referenced by dataflow steps).
+
+## How to use `apltk architecture`
+
+Each verb is a single mutation; the CLI auto-renders after every change. Pass `--no-render` when batching mutations. Global flags: `--project <root>`, `--spec <spec_dir>` (writes to overlay; see `spec-to-project-html`), `--no-render`, `--no-open`.
+
+| Verb | Use it to… |
+| --- | --- |
+| `apltk architecture meta set --title ... --summary ...` | Set the macro title + atlas summary (read order, scanned roots, deliberate omissions). |
+| `apltk architecture actor add --id end-user --label "End user"` | Add a top-level actor (optional; appears in macro context). |
+| `apltk architecture feature add --slug <kebab> --title "..." --story "..." [--depends-on a,b]` | Declare a feature module (user-visible capability). |
+| `apltk architecture submodule add --feature <slug> --slug <kebab> --kind ui\|api\|service\|db\|pure-fn\|queue\|external --role "..."` | Declare a sub-module under a feature. |
+| `apltk architecture function add --feature X --submodule Y --name fn --in "T1, T2" --out "R \| ErrX" --side pure\|io\|write\|tx\|lock\|network --purpose "..."` | Add a function I/O row. |
+| `apltk architecture variable add --feature X --submodule Y --name v --type T --scope call\|tx\|persist\|instance\|loop --purpose "..."` | Add a variable-with-business-purpose row. |
+| `apltk architecture dataflow add --feature X --submodule Y --step "..." [--fn <declared-fn>] [--reads "v1,v2"] [--writes "v3,v4"] [--at N]` | Append (or insert at index `N`) an internal dataflow step. `--fn` must match a previously declared `function`; every name in `--reads` / `--writes` must match a previously declared `variable` in the same sub-module — the renderer surfaces them as a function pill + reads/writes chips so the diagram shows function-to-function flow and variable state transitions. |
+| `apltk architecture dataflow reorder --feature X --submodule Y --from i --to j` | Move a step within the same sub-module. |
+| `apltk architecture error add --feature X --submodule Y --name ErrCode --when "..." --means "..."` | Add a local error row. |
+| `apltk architecture edge add --from <feature>[/sub] --to <feature>[/sub] --kind call\|return\|data-row\|failure --label "..." [--id <stable>]` | Add an edge. Intra-feature edges (both endpoints in the same feature with sub-modules) land in the feature YAML; cross-feature edges land in `atlas.index.yaml`. |
+| `apltk architecture feature\|submodule\|function\|variable\|error\|edge remove ...` | Remove a previously declared component. Removing a feature drops every sub-module and edge that referenced it. |
+| `apltk architecture feature\|submodule set ...` | Update fields (e.g. retitle a feature, change a sub-module's role) without re-adding. |
+| `apltk architecture render` | Force-regenerate HTML from current YAML state (useful after editing YAML directly, though hand-editing is discouraged). |
+| `apltk architecture validate` | Schema + referential integrity check; fails on dangling edges, unknown enums, duplicate slugs. |
+| `apltk architecture undo` | Revert the most recent mutation (single-level snapshot). |
+| `apltk architecture open` | Open the rendered macro `index.html` in a browser. |
+| `apltk architecture diff` | Render the paginated before/after viewer for every active spec under `docs/plans/**/architecture_diff/`. |
 
 ## Workflow
 
 ### 1) Whole-repo inventory — list feature modules, not function bodies
 
-Scan the shipped source for **user-visible capabilities** (each one = one feature module): entry routes, CLI commands, UI pages, cron jobs, runners, event handlers, CDC streams. For each entry record only:
-
-- kebab-case `slug` + one-line user story.
-- **Boundary points**: entry symbol/file, outbound resources (DB tables, queue topics, external services, shared cache keys).
-- Candidate cross-feature edges (mark as candidates; do not verify yet).
+Scan the shipped source for **user-visible capabilities** (each one = one feature module): entry routes, CLI commands, UI pages, cron jobs, runners, event handlers, CDC streams. Record only kebab-case slug + one-line user story + boundary points (entry symbol, outbound DB tables / queue topics / external services).
 
 - **Pause →** Is the list actually complete? Note skipped roots with reason; no silent skips.
 - **Pause →** Did I dive into function bodies here? Roll back — keep only structural notes.
 
 ### 2) Branch the deep-read by environment (Rule 3)
 
-#### 2A) With subagents (preferred)
-
-Dispatch one **read-only** subagent per feature. Require this summary template (no source-code excerpts):
+#### 2A) With subagents (preferred) — workers own their feature; main agent owns the macro seams
 
-> **Feature `<slug>` summary**
-> - Sub-module list: one row per `<sub-module-slug>` (kind: ui / api / service / db / pure-fn / queue / external).
-> - Per sub-module: function signatures (in / out / errors), side-effect chip, variables-with-business-purpose, internal flow steps, errors raised.
-> - **Outbound boundaries**: which other features' sub-modules this one calls (call edges); which DB tables / topics / cache keys it touches that **another feature also reads or writes** (data-row / data-topic edges; mark direction).
+Dispatch one **write-capable** subagent per feature, plus the main agent for the macro layer. Hand each subagent: its feature slug, the feature-module list from step 1 (so it knows other features' slugs for outbound edges), and access to `apltk architecture`. Each subagent **declares its own feature end-to-end** and only reports outbound boundaries upward:
 
-Main agent collects every summary, does **not** re-read source, then emits in one pass:
+> **Feature `<slug>` subagent contract**
+> - Read every sub-module of this feature.
+> - Run `feature add --slug <slug> --title "..." --story "..." --no-render` (or `feature set` if a placeholder already exists).
+> - For every sub-module: `submodule add` with the right `--kind`, then add its `function`, `variable`, `dataflow` (ordered — these steps carry the variable state transitions through the flow), and `error` rows.
+> - For every intra-feature interaction between sub-modules — function calls, returns, error propagation, rollback / compensation — emit `edge add --from <slug>/<a> --to <slug>/<b> --kind call|return|data-row|failure --label "..."`. Failure / rollback flows belong here: model them as additional `--kind failure` edges or as ordered `dataflow add` steps on the affected sub-modules, whichever maps to the real code path.
+> - Run `apltk architecture validate` (scoped to this feature) before returning.
+> - **Return ONLY**: (i) sub-module list (slug + kind + one-line role), (ii) outbound boundaries to *other* features' sub-modules (direction + edge kind + suggested label). No source excerpts, no function bodies.
 
-1. Macro `index.html` (single SVG: clusters + multi-edge + call/return loop + cross-feature `m-edge--cross` + `atlas-submodule-index` + `flow-edge-manifest--macro`).
-2. `features/<slug>/index.html` per feature (lightweight: user story + `submodule-nav`).
-3. Per sub-module: self-only page with `sub-io` + `sub-vars` + `sub-dataflow` (small SVG if useful) + `sub-errors`.
-4. Copy `references/architecture.css` to `resources/project-architecture/assets/`.
+Main agent — after every subagent returns — declares **only** macro-level state from the aggregated outbound boundaries:
 
-- **Pause →** Every cross-feature edge in the summaries has both source and target sub-module nodes actually drawn in the SVG? If not, add the node or split one out.
+```bash
+apltk architecture meta set --title "..." --summary "..." --no-render
+# only when an actor is shared across multiple features:
+apltk architecture actor add --id <id> --label "..." --no-render
+# one edge per cross-feature interaction reported by the subagents:
+apltk architecture edge add --from <featA>/<subA> --to <featB>/<subB> --kind call|return|data-row|failure --label "..." --no-render
+apltk architecture render
+apltk architecture validate
+```
 
-#### 2B) Without subagents — feature-by-feature read-write loop
+The main agent **MUST NOT** re-declare a subagent's intra-feature components, and **MUST NOT** open source files for any feature it delegated.
 
-Process the list from step 1 one feature at a time (topological hint: read-from data sources and pure helpers first, user-facing entries last). Per feature, run the full inner loop:
+#### 2B) Without subagents — feature-by-feature read-declare loop
 
-1. **Deep-read** every sub-module of this feature (functions, variables, errors, cross-feature edges).
-2. **Write to disk immediately**:
-   - `features/<slug>/index.html` (lightweight).
-   - One page per sub-module (self-only: `sub-io` + `sub-vars` + `sub-dataflow` + `sub-errors`).
-   - For `sub-vars`, sweep every identifier (params, local state, struct fields, DB columns, config, counters, `now`) — anything that influences a business branch or external promise **must** appear.
-3. **Patch the macro `index.html` incrementally**: add this feature's cluster + sub-module nodes + intra-feature edges; mark edges pointing at unread features as `data-edge-target-pending="<future-slug>"` and note them in `figcaption`; mirror new edges in `flow-edge-manifest--macro`.
-4. **Drop function-level details from working memory**; keep only lightweight notes (cluster id, pending-edge list); do not re-read this feature's bodies when handling the next one.
-5. Return to step 1 for the next feature.
+Process the list from step 1 one feature at a time (topological hint: read-from data sources and pure helpers first, user-facing entries last). Per feature:
 
-After the last feature, do a final pass:
+1. **Deep-read** every sub-module of this feature.
+2. **Declare immediately** via the CLI (`feature add`, then `submodule add` × N, then `function`/`variable`/`dataflow`/`error` rows, then intra-feature `edge add`).
+3. **Cross-feature edges**: if the target feature has not been declared yet, declare a placeholder with `feature add --slug <future> --title <future>`, add the edge, then refine the placeholder on a later pass.
+4. **Drop function-level details from working memory** before moving to the next feature.
 
-- Resolve every pending placeholder in the macro (no `pending` residue allowed).
-- Verify `atlas-submodule-index` lists every sub-module page.
-- Confirm `architecture.css` is copied into `assets/`.
+After the last feature:
 
-- **Pause →** Pending edges remaining after the last feature? Either step 1's list missed a feature or step 3 dropped an edge — re-read and patch. Silent deletion is forbidden.
+- Refine any placeholder features that were used to carry cross-feature edges.
+- Run `apltk architecture validate` — must return OK.
 
 ### 3) Handover report
 
-Report: feature count, macro edge counts (call/return/cross), sub-module page count, uncovered paths + reasons, the read strategy actually used (2A or 2B), and stable IDs to hand off to `spec-to-project-html`.
+Report: feature count, sub-module count, macro edge counts (call / return / data-row / failure), uncovered paths + reasons, the read strategy actually used (2A or 2B), and the location of the rendered atlas (`resources/project-architecture/index.html`).
 
 ## Sample hints
 
-- Multiple SQL paths on `service ↔ db` → draw **separate edges**; do not merge.
-- Retry loops between `service ↔ generator(pure)` → call/return pair in the macro plus a `retry` side note; sub-module pages still describe only their own function I/O.
-- Cross-feature DB hand-off (A writes, B reads) → macro uses `m-edge--cross`; sub-module pages each describe only their own INSERT / SELECT functions.
-- Third-party systems → render as `m-sub--ext` (when extended) or cluster-external nodes; the trust boundary must be visible.
+- Multiple SQL paths on `service ↔ db` → call `edge add` once per SQL path so the macro shows them as separate edges.
+- Retry loops between `service ↔ generator(pure)` → call/return pair in the macro plus a `dataflow add` step in the service with `--fn issueCode --writes "code"` describing the retry budget; a follow-up step `--fn issueCode --reads "code" --writes "row"` then captures the persistence attempt.
+- Variable state transitions inside one function (e.g. `code` is computed, persisted, then returned) → emit one `dataflow add` per logical mutation, with `--fn` constant and `--reads` / `--writes` listing every variable that changes shape at that point. The sub-module page chips trace each variable's life cycle top-to-bottom.
+- Cross-feature DB hand-off (A writes, B reads) → declare both sides' `INSERT_*` / `SELECT_*` functions on the `db` sub-module, then `edge add --kind data-row` from producer feature/submodule to consumer feature/submodule.
+- Rollback / compensation across sub-modules → `edge add --kind failure --label "rollback on dup"`; rollback *within* a single sub-module belongs in `dataflow add` (with `--fn` set to whichever function owns the cleanup).
+- Third-party systems → declare as `--kind external` sub-modules; the trust boundary becomes visible because the renderer styles them differently.
+
+## References
+
+- `lib/atlas/schema.js` — single source of truth for component fields, enums, and validation. `references/TEMPLATE_SPEC.md` mirrors that schema as a quick-reference cheat sheet.
+- `lib/atlas/cli.js` — full verb dispatch (run `apltk architecture --help` for the live usage).
+- `init-project-html/sample-demo/` — end-to-end YAML + rendered HTML for two features.

package/init-project-html/agents/openai.yaml

@@ -1,13 +1,22 @@
 interface:
   display_name: "init-project-html"
-  short_description: "Bootstrap an HTML architecture atlas with a single macro feature × sub-module SVG"
+  short_description: "Declare the project HTML architecture atlas through `apltk architecture` CLI verbs"
   default_prompt: >-
-    Use $init-project-html. Its `SKILL.md` is the authoritative rulebook (Rules 1–7); `references/TEMPLATE_SPEC.md` is a reference cheat sheet (vocabulary, class hooks, DOM snippets).
-    Read strategy to avoid context loss on large codebases. STEP 1: enumerate the feature-module list (slug + entry + boundary resources) WITHOUT diving into function bodies.
+    Use $init-project-html. Its `SKILL.md` is the authoritative rulebook; `references/TEMPLATE_SPEC.md` is a component-schema cheat sheet.
+    NEVER hand-author files under `resources/project-architecture/**/*.html`. The atlas state lives in YAML under `resources/project-architecture/atlas/` and every mutation goes through `apltk architecture <verb> ...`; the CLI owns layout, no-overlap, DOM, CSS, ARIA, and pan/zoom — both the macro SVG and each sub-module's internal-dataflow diagram are zoomable.
+    Read strategy to avoid context loss AND to enforce a hard responsibility split. STEP 1: enumerate the feature-module list (slug + entry + boundary resources) WITHOUT diving into function bodies.
     STEP 2: branch by environment.
-    (2A, preferred) if subagents are available, dispatch ONE read-only subagent per feature; each returns ONLY a structured summary (sub-modules; per sub-module: function I/O, variables-with-business-purpose, internal data flow, errors raised; outbound edges to other features). The main agent collects every summary first, then emits the whole atlas in one pass.
-    (2B, no subagents) process features ONE AT A TIME — deep-read feature A, IMMEDIATELY emit `features/A/index.html` + every sub-module page, incrementally patch the macro `index.html` to add A's cluster and known edges (mark edges pointing at unread features with `data-edge-target-pending="<future-slug>"`), drop A's function-level details from working memory, then move to feature B. After every feature is written, resolve every pending placeholder in the macro. NEVER read the whole codebase before writing.
-    Macro `index.html` MUST be a SINGLE SVG covering BOTH layers in one diagram: feature-modules as `m-cluster` frames AND every sub-module as a clickable node inside its cluster, with many-to-many edges (same node pair may carry multiple edges, e.g. SELECT/INSERT/UPDATE), producer ↔ consumer call/return loops, and cross-feature `m-edge--cross` data-row edges where applicable. The macro MUST also include `<nav class="atlas-submodule-index">` linking every sub-module page.
-    Each `features/<slug>/<sub-module>.html` describes ONLY itself: `sub-io` function I/O table + `sub-vars` variables-with-business-purpose table (every parameter / local state / struct field / DB column / config / counter / time anchor that influences a business branch, with type, scope chip `sub-vars__scope--call|tx|persist|instance|loop`, and a business-language purpose explaining why it exists and which branch it decides) + `sub-dataflow` internal flow + `sub-errors`. FORBIDDEN on sub-module pages: cross-boundary `flow-edge-manifest`, `flow-return-row`, or any "who I call / who calls me" narrative.
-    Feature `index.html` stays lightweight: user story + `submodule-nav` table only — no cross-submodule flowchart.
-    Copy `references/architecture.css` into `resources/project-architecture/assets/`. Mark TBD when evidence is missing. Keep IDs stable for $spec-to-project-html. Report which read strategy (2A or 2B) was actually used.
+    (2A, preferred) if subagents are available, dispatch ONE write-capable subagent per feature. Each subagent deep-reads ITS OWN feature and declares EVERY intra-feature interaction itself via `apltk architecture ... --feature <slug>`: `submodule add` (with the right `--kind`), `function add` / `variable add` / `dataflow add` (ordered — these steps carry the variable state transitions through the flow) / `error add` rows on every sub-module, and **every intra-feature edge** between its sub-modules (function calls, returns, error propagation, rollback / compensation — model failure / rollback paths as `--kind failure` edges and/or as ordered `dataflow add` steps). The subagent returns ONLY (i) sub-module list (slug + kind + one-line role) and (ii) outbound boundaries to other features' sub-modules (direction + edge kind + suggested label). The main agent never re-reads source for a delegated feature and never re-declares its components — it batches ONLY cross-feature `edge add` (and any shared `actor` / `meta`) from the aggregated outbound summaries, then runs `apltk architecture render` and `apltk architecture validate`.
+    (2B, no subagents) process features ONE AT A TIME — deep-read feature A, IMMEDIATELY drive the CLI (`feature add`, `submodule add` x N, `function add` / `variable add` / `dataflow add` / `error add` rows, intra-feature `edge add` including failure / rollback edges), drop A's function-level details from working memory, then move to feature B. For cross-feature edges pointing at a not-yet-declared feature, declare a placeholder with `feature add --slug <future> --title <future>` first and refine its title/story on a later pass.
+    CLI verbs to declare components (always kebab-case slugs; pass `--no-render` to batch then call `apltk architecture render` once at the end):
+    `apltk architecture meta set --title "..." --summary "..."`,
+    `apltk architecture actor add --id <kebab> --label "..."`,
+    `apltk architecture feature add --slug <kebab> --title "..." --story "..." [--depends-on a,b]`,
+    `apltk architecture submodule add --feature X --slug Y --kind ui|api|service|db|pure-fn|queue|external --role "..."`,
+    `apltk architecture function add --feature X --submodule Y --name fn --in "T1, T2" --out "R | ErrX" --side pure|io|write|tx|lock|network --purpose "..."`,
+    `apltk architecture variable add --feature X --submodule Y --name v --type T --scope call|tx|persist|instance|loop --purpose "..."`,
+    `apltk architecture dataflow add --feature X --submodule Y --step "..." [--fn <declared-fn>] [--reads "v1,v2"] [--writes "v3,v4"] [--at N]` (use `--fn` to surface function-to-function flow inside the sub-module; use `--reads` / `--writes` to surface variable state transitions — every name MUST match a `function`/`variable` already declared in the SAME sub-module or `validate` fails),
+    `apltk architecture error add --feature X --submodule Y --name ErrCode --when "..." --means "..."`,
+    `apltk architecture edge add --from <feature>[/sub] --to <feature>[/sub] --kind call|return|data-row|failure --label "..." [--id <stable>]`.
+    Intra-feature edges (both endpoints in the same feature with sub-modules) land in the feature YAML; cross-feature edges land in `atlas.index.yaml`. After the last mutation run `apltk architecture validate` — must return OK; resolve every reported error before reporting completion.
+    Each sub-module page describes ONLY itself (`sub-io` function I/O + `sub-vars` variables-with-business-purpose + `sub-dataflow` zoomable internal flow with fn pill + reads/writes chips + `sub-errors` local errors) — express any cross-boundary interaction as an edge, never as sub-module page prose. Two acceptance criteria gate completion: (1) the macro diagram clearly shows feature×sub-module relationships — data flow, call/return interaction logic, error handling, rollback — all as `--kind call|return|data-row|failure` edges (no cross-boundary path expressed only as prose); (2) every non-trivial sub-module's internal diagram clearly shows function-level interactions — `dataflow add --fn <declared-fn>` for function-to-function flow + `--reads` / `--writes` for variable state transitions through the run. Anchor every declaration to a concrete path / symbol / SQL / config; mark TBD when evidence is missing; record scanned roots and deliberate omissions in `meta.summary`. Report which read strategy (2A or 2B) was actually used and the location of the rendered atlas (`resources/project-architecture/index.html`).

package/init-project-html/lib/atlas/assets/architecture.css

@@ -0,0 +1,161 @@
+/* architecture.css — styling for the declarative atlas. The CLI copies
+ * this file into <outDir>/assets/. Style hooks (class names) are owned
+ * by render.js so agents never need to touch HTML by hand. */
+
+:root {
+  color-scheme: light dark;
+  --bg: #0f172a;
+  --panel: #111827;
+  --panel-soft: #1f2937;
+  --text: #e5e7eb;
+  --muted: #9ca3af;
+  --border: #334155;
+  --accent: #38bdf8;
+  --kind-ui: #38bdf8;
+  --kind-api: #818cf8;
+  --kind-service: #34d399;
+  --kind-db: #fbbf24;
+  --kind-pure-fn: #cbd5e1;
+  --kind-queue: #a78bfa;
+  --kind-external: #fb7185;
+  --edge-call: #60a5fa;
+  --edge-return: #94a3b8;
+  --edge-data-row: #fbbf24;
+  --edge-failure: #fb7185;
+}
+
+* { box-sizing: border-box; }
+html, body { margin: 0; padding: 0; background: var(--bg); color: var(--text); font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; }
+
+a { color: var(--accent); text-decoration: none; }
+a:hover { text-decoration: underline; }
+
+h1, h2 { margin: 0 0 12px; font-weight: 600; letter-spacing: -0.01em; }
+h1 { font-size: 28px; }
+h2 { font-size: 18px; color: var(--muted); text-transform: uppercase; letter-spacing: 0.08em; font-size: 13px; }
+
+p { line-height: 1.55; color: var(--text); }
+
+/* ---- atlas (macro) ---- */
+.atlas-header { padding: 28px 40px 16px; border-bottom: 1px solid var(--border); background: var(--panel); }
+.atlas-summary { color: var(--muted); max-width: 80ch; margin: 8px 0 0; }
+
+.atlas-main { display: grid; grid-template-columns: minmax(0, 3fr) minmax(280px, 1fr); gap: 24px; padding: 24px 40px 48px; }
+
+.atlas-canvas { background: var(--panel); border: 1px solid var(--border); border-radius: 12px; padding: 16px; position: relative; }
+.atlas-canvas__toolbar { position: absolute; top: 16px; right: 16px; display: flex; gap: 4px; z-index: 2; }
+.atlas-canvas__toolbar button { background: var(--panel-soft); color: var(--text); border: 1px solid var(--border); padding: 4px 12px; border-radius: 6px; cursor: pointer; font-size: 13px; }
+.atlas-canvas__toolbar button:hover { border-color: var(--accent); color: var(--accent); }
+
+.atlas-canvas__viewport { width: 100%; max-height: 72vh; overflow: hidden; border-radius: 8px; background: #0b1220; }
+.atlas-canvas__viewport.is-grabbing { cursor: grabbing; }
+.atlas-canvas__viewport:not(.is-grabbing) { cursor: grab; }
+
+.atlas-svg { width: 100%; height: auto; max-height: 72vh; display: block; user-select: none; touch-action: none; }
+
+.atlas-legend { list-style: none; padding: 12px 4px 0; margin: 0; display: flex; gap: 18px; flex-wrap: wrap; font-size: 12px; color: var(--muted); }
+.atlas-legend li { display: inline-flex; align-items: center; gap: 6px; }
+.legend-swatch { display: inline-block; width: 18px; height: 4px; border-radius: 2px; }
+.legend-swatch--call { background: var(--edge-call); }
+.legend-swatch--return { background: var(--edge-return); }
+.legend-swatch--data-row { background: var(--edge-data-row); }
+.legend-swatch--failure { background: var(--edge-failure); }
+
+.atlas-index { background: var(--panel); border: 1px solid var(--border); border-radius: 12px; padding: 16px; max-height: 80vh; overflow: auto; }
+
+.atlas-submodule-index { list-style: none; padding: 0; margin: 0; display: flex; flex-direction: column; gap: 10px; }
+.atlas-submodule-index__item a { display: grid; grid-template-columns: minmax(0, 1fr) auto; align-items: center; gap: 4px 8px; padding: 8px 10px; background: var(--panel-soft); border: 1px solid var(--border); border-radius: 8px; color: inherit; }
+.atlas-submodule-index__item a:hover { border-color: var(--accent); }
+.atlas-submodule-index__feature { font-size: 11px; color: var(--muted); text-transform: uppercase; letter-spacing: 0.06em; grid-column: 1 / 3; }
+.atlas-submodule-index__sub { font-weight: 600; }
+.atlas-submodule-index__kind { font-size: 11px; padding: 1px 8px; border-radius: 999px; background: var(--panel); border: 1px solid var(--border); color: var(--muted); }
+.atlas-submodule-index__role { margin: 4px 10px 0; font-size: 12px; color: var(--muted); }
+
+/* ---- SVG macro ---- */
+.m-cluster__bg { fill: rgba(15, 23, 42, 0.55); stroke: var(--border); stroke-width: 1; }
+.m-cluster__title { font-family: ui-sans-serif, system-ui, sans-serif; font-size: 14px; fill: var(--text); font-weight: 600; letter-spacing: 0.04em; text-transform: uppercase; }
+.m-node { cursor: pointer; }
+.m-node rect { fill: var(--panel-soft); stroke: var(--border); stroke-width: 1; transition: stroke 120ms ease, fill 120ms ease; }
+.m-node:hover rect,
+.m-node:focus rect,
+.m-node:focus-visible rect { stroke: var(--accent); stroke-width: 1.6; fill: rgba(56, 189, 248, 0.08); }
+.m-node:focus { outline: none; }
+.m-node__title { font-size: 13px; font-weight: 600; fill: var(--text); }
+.m-node__kind { font-size: 11px; fill: var(--muted); }
+.m-node__role { font-size: 11px; fill: var(--muted); }
+.m-node:hover .m-node__title,
+.m-node:focus .m-node__title { fill: var(--accent); }
+
+.m-node--ui rect { stroke: var(--kind-ui); }
+.m-node--api rect { stroke: var(--kind-api); }
+.m-node--service rect { stroke: var(--kind-service); }
+.m-node--db rect { stroke: var(--kind-db); }
+.m-node--pure-fn rect { stroke: var(--kind-pure-fn); }
+.m-node--queue rect { stroke: var(--kind-queue); }
+.m-node--external rect { stroke: var(--kind-external); }
+
+.m-edge path { stroke-width: 1.6; }
+.m-edge--call path { stroke: var(--edge-call); }
+.m-edge--return path { stroke: var(--edge-return); stroke-dasharray: 6 4; }
+.m-edge--data-row path { stroke: var(--edge-data-row); }
+.m-edge--failure path { stroke: var(--edge-failure); }
+
+.m-arrow path { fill: currentColor; }
+.m-arrow--call { color: var(--edge-call); }
+.m-arrow--return { color: var(--edge-return); }
+.m-arrow--data-row { color: var(--edge-data-row); }
+.m-arrow--failure { color: var(--edge-failure); }
+
+.m-edge__label { fill: var(--muted); font-size: 11px; }
+
+/* ---- feature page ---- */
+.feature-header, .submodule-header { padding: 24px 40px 12px; border-bottom: 1px solid var(--border); background: var(--panel); }
+.feature-breadcrumb, .submodule-breadcrumb { font-size: 13px; color: var(--muted); margin-bottom: 8px; }
+.feature-depends { font-size: 13px; color: var(--muted); margin: 8px 0 0; }
+.feature-main, .submodule-main { padding: 24px 40px 48px; display: flex; flex-direction: column; gap: 32px; }
+.feature-story p { max-width: 80ch; }
+
+.submodule-nav { list-style: none; padding: 0; margin: 0; display: grid; gap: 12px; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); }
+.submodule-card { background: var(--panel); border: 1px solid var(--border); border-radius: 10px; padding: 12px 14px; }
+.submodule-card__link { display: flex; align-items: center; justify-content: space-between; color: inherit; font-weight: 600; }
+.submodule-card__kind { font-size: 11px; padding: 2px 8px; border-radius: 999px; border: 1px solid var(--border); color: var(--muted); }
+.submodule-card__role { margin: 8px 0 0; font-size: 13px; color: var(--muted); }
+
+.feature-edges__list { list-style: none; padding: 0; margin: 0; display: flex; flex-direction: column; gap: 8px; }
+.feature-edges__item { display: grid; grid-template-columns: minmax(0, 1fr) auto minmax(0, 2fr); gap: 8px; padding: 8px 12px; background: var(--panel); border: 1px solid var(--border); border-radius: 8px; font-size: 13px; }
+.feature-edges__kind { font-size: 11px; color: var(--muted); text-transform: uppercase; letter-spacing: 0.06em; align-self: center; }
+.feature-edges__item--call { border-left: 4px solid var(--edge-call); }
+.feature-edges__item--return { border-left: 4px solid var(--edge-return); }
+.feature-edges__item--data-row { border-left: 4px solid var(--edge-data-row); }
+.feature-edges__item--failure { border-left: 4px solid var(--edge-failure); }
+
+/* ---- submodule page ---- */
+.submodule-kind { display: inline-block; font-size: 12px; padding: 2px 10px; border-radius: 999px; border: 1px solid var(--border); color: var(--muted); margin-left: 8px; vertical-align: middle; text-transform: uppercase; letter-spacing: 0.06em; }
+.submodule-role { color: var(--muted); margin: 8px 0 0; max-width: 80ch; }
+
+.sub-table { width: 100%; border-collapse: collapse; font-size: 13px; }
+.sub-table th, .sub-table td { padding: 8px 12px; border-bottom: 1px solid var(--border); text-align: left; vertical-align: top; }
+.sub-table th { font-size: 11px; color: var(--muted); text-transform: uppercase; letter-spacing: 0.06em; background: var(--panel); }
+
+.sub-section__empty { color: var(--muted); font-style: italic; font-size: 13px; }
+
+.sub-dataflow__canvas { position: relative; background: var(--panel); border: 1px solid var(--border); border-radius: 12px; padding: 16px; }
+.sub-dataflow__toolbar { position: absolute; top: 16px; right: 16px; display: flex; gap: 4px; z-index: 2; }
+.sub-dataflow__toolbar button { background: var(--panel-soft); color: var(--text); border: 1px solid var(--border); padding: 4px 12px; border-radius: 6px; cursor: pointer; font-size: 13px; }
+.sub-dataflow__toolbar button:hover { border-color: var(--accent); color: var(--accent); }
+.sub-dataflow__viewport { width: 100%; max-height: 60vh; overflow: hidden; border-radius: 8px; background: #0b1220; }
+.sub-dataflow__viewport.is-grabbing { cursor: grabbing; }
+.sub-dataflow__viewport:not(.is-grabbing) { cursor: grab; }
+.sub-dataflow__svg { width: 100%; height: auto; max-height: 60vh; display: block; user-select: none; touch-action: none; }
+.sub-dataflow__badge { fill: var(--panel-soft); stroke: var(--accent); stroke-width: 1.4; }
+.sub-dataflow__badge-text { font-family: ui-sans-serif, system-ui, sans-serif; font-size: 13px; font-weight: 600; fill: var(--accent); }
+.sub-dataflow__step .sub-dataflow__box { fill: var(--panel-soft); stroke: var(--border); stroke-width: 1; }
+.sub-dataflow__step:hover .sub-dataflow__box { stroke: var(--accent); }
+.sub-dataflow__text { font-family: ui-sans-serif, system-ui, sans-serif; font-size: 14px; fill: var(--text); }
+.sub-dataflow__arrow { stroke: var(--muted); stroke-width: 1.6; }
+.sub-dataflow__fn-bg { fill: rgba(56, 189, 248, 0.12); stroke: var(--accent); stroke-width: 1; }
+.sub-dataflow__fn-text { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11px; font-weight: 600; fill: var(--accent); letter-spacing: 0.02em; }
+.sub-dataflow__chip { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11px; font-weight: 500; }
+.sub-dataflow__chip--reads { fill: var(--kind-service); }
+.sub-dataflow__chip--writes { fill: var(--kind-db); }
+.sub-dataflow__empty { color: var(--muted); font-style: italic; }