@laitszkin/apollo-toolkit 3.10.0 → 3.11.0

package/init-project-html/SKILL.md

@@ -1,129 +1,85 @@
 ---
 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. The tool owns layout, no-overlap, DOM, CSS, and pan/zoom; the agent only declares features, sub-modules, functions, variables, dataflow steps, errors, and edges. Macro `index.html` always shows feature clusters with their sub-modules and every cross/intra-feature edge; each sub-module page describes only itself (function I/O + variables-with-business-purpose + internal dataflow + local errors); feature index pages stay lightweight. Read strategy avoids context loss: list feature modules first, then either dispatch one read-only subagent per feature and aggregate summaries before declaring, or process one feature at a time end-to-end. 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
 
-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 steps (`dataflow add --step "..."`),
+- 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".
+Cross-boundary narratives ("I call X", "Y calls me") **MUST** be expressed as macro 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.
 
 ### Rule 3 — Read order: never let the codebase wipe the context window
 
-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:
+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. **MUST** follow one of:
 
-- **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.
+- **With subagents (preferred):** first enumerate the **feature-module list** (slug + entry + boundary resources only). Then dispatch **one read-only subagent per feature**. Each subagent deep-reads and returns ONLY a structured summary (sub-module list with kind/role; per sub-module: function I/O, variables-with-business-purpose, internal dataflow steps, errors; outbound edges to other features). The main agent collects every summary first, then drives the CLI in one pass to declare every component.
+- **Without subagents:** process features **one at a time** — read feature A end-to-end, then declare it via the CLI (`feature add`, `submodule add`, `function add`, `variable add`, `dataflow add`, `error add`, intra-feature `edge add`). 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.
 
-Both paths share one invariant: at any moment the main agent only holds *current-feature details + cross-feature boundary notes*.
+Both paths share one invariant: at any moment the main agent only holds *current-feature details + cross-feature boundary notes*. Run `apltk architecture validate` after the last feature to catch dangling edges, unknown endpoints, or missing required fields.
 
-### Rule 4 — Per-page section contracts
+### Rule 4 — Evidence over invention
 
-Each page type has a fixed required set of sections. Violating the contract is a Rule 1 or Rule 2 violation by definition.
-
-**A) Macro `resources/project-architecture/index.html`** (the only page that draws interactions):
-
-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.
-
-**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.
+
+## 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 "..." [--at N]` | Append (or insert at index `N`) an internal dataflow step. |
+| `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.
@@ -132,50 +88,50 @@ Scan the shipped source for **user-visible capabilities** (each one = one featur
 
 #### 2A) With subagents (preferred)
 
-Dispatch one **read-only** subagent per feature. Require this summary template (no source-code excerpts):
+Dispatch one read-only subagent per feature. Require this summary template (no source-code excerpts):
 
 > **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).
-
-Main agent collects every summary, does **not** re-read source, then emits in one pass:
-
-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/`.
+> - Sub-module list: one row per `<sub-module-slug>` (kind: ui / api / service / db / pure-fn / queue / external; one-line role).
+> - Per sub-module: function signatures (in / out / side / purpose), variables-with-business-purpose, internal dataflow steps, errors raised.
+> - **Outbound boundaries**: call edges to other features' sub-modules; data-row edges through shared DB tables / topics / cache keys with another feature; mark direction.
 
-- **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.
+Main agent collects every summary, then drives the CLI in one pass:
 
-#### 2B) Without subagents — feature-by-feature read-write loop
+```bash
+apltk architecture meta set --title "..." --summary "..." --no-render
+apltk architecture feature add --slug <slug> --title "..." --story "..." --no-render
+# repeat submodule / function / variable / dataflow / error / edge add for the whole atlas
+apltk architecture render
+apltk architecture validate
+```
 
-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 step in the service describing the retry budget.
+- 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.
+- 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).
+    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.
     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.
     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 read-only subagent per feature; each returns ONLY a structured summary (sub-modules with kind/role; per sub-module: function I/O, variables-with-business-purpose, internal dataflow steps, errors raised; outbound edges to other features). The main agent collects every summary first, then runs the CLI in one batched pass.
+    (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`), 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 "..." [--at N]`,
+    `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` internal flow + `sub-errors` local errors) — express any cross-boundary interaction as a macro edge, never as sub-module page prose. 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,140 @@
+/* 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 rect { fill: var(--panel-soft); stroke: var(--border); stroke-width: 1; transition: stroke 120ms ease; }
+.m-node:hover rect { stroke: var(--accent); }
+.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--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__svg { width: 100%; max-width: 480px; }
+.sub-dataflow__step rect { fill: var(--panel); stroke: var(--border); }
+.sub-dataflow__step text { fill: var(--text); font-size: 13px; }
+.sub-dataflow__arrow { stroke: var(--muted); stroke-width: 1.4; }
+.sub-dataflow__empty { color: var(--muted); font-style: italic; }

package/init-project-html/lib/atlas/assets/viewer.client.js

@@ -0,0 +1,93 @@
+/* viewer.client.js — pan/zoom for the macro atlas SVG. No deps; wires
+ * onto any element marked [data-pan-zoom-viewport] containing one
+ * [data-atlas-svg] SVG. Mouse wheel zooms around the cursor; drag pans;
+ * toolbar buttons handle +/-/Fit; keyboard arrows pan. */
+
+(function () {
+  'use strict';
+
+  const viewport = document.querySelector('[data-pan-zoom-viewport]');
+  if (!viewport) return;
+  const svg = viewport.querySelector('[data-atlas-svg]');
+  if (!svg) return;
+
+  const initial = svg.getAttribute('viewBox');
+  if (!initial) return;
+  const [ix, iy, iw, ih] = initial.split(/\s+/).map(Number);
+  const state = { x: ix, y: iy, w: iw, h: ih };
+
+  function apply() {
+    svg.setAttribute('viewBox', `${state.x} ${state.y} ${state.w} ${state.h}`);
+  }
+
+  function zoom(factor, cx, cy) {
+    const newW = Math.max(40, Math.min(state.w * factor, iw * 8));
+    const newH = newW * (state.h / state.w);
+    if (cx == null) { cx = state.x + state.w / 2; cy = state.y + state.h / 2; }
+    state.x = cx - (cx - state.x) * (newW / state.w);
+    state.y = cy - (cy - state.y) * (newH / state.h);
+    state.w = newW;
+    state.h = newH;
+    apply();
+  }
+
+  function clientToSvg(evt) {
+    const rect = svg.getBoundingClientRect();
+    const xRatio = (evt.clientX - rect.left) / rect.width;
+    const yRatio = (evt.clientY - rect.top) / rect.height;
+    return { x: state.x + xRatio * state.w, y: state.y + yRatio * state.h };
+  }
+
+  viewport.addEventListener('wheel', function (evt) {
+    if (!evt.ctrlKey && !evt.metaKey && Math.abs(evt.deltaY) < 4 && Math.abs(evt.deltaX) < 4) return;
+    evt.preventDefault();
+    const factor = evt.deltaY > 0 ? 1.1 : 1 / 1.1;
+    const pt = clientToSvg(evt);
+    zoom(factor, pt.x, pt.y);
+  }, { passive: false });
+
+  let dragging = null;
+  viewport.addEventListener('pointerdown', function (evt) {
+    if (evt.button !== 0) return;
+    dragging = { x: evt.clientX, y: evt.clientY };
+    viewport.classList.add('is-grabbing');
+    viewport.setPointerCapture(evt.pointerId);
+  });
+  viewport.addEventListener('pointermove', function (evt) {
+    if (!dragging) return;
+    const rect = svg.getBoundingClientRect();
+    const dx = ((evt.clientX - dragging.x) / rect.width) * state.w;
+    const dy = ((evt.clientY - dragging.y) / rect.height) * state.h;
+    state.x -= dx;
+    state.y -= dy;
+    dragging = { x: evt.clientX, y: evt.clientY };
+    apply();
+  });
+  function endDrag(evt) {
+    if (!dragging) return;
+    dragging = null;
+    viewport.classList.remove('is-grabbing');
+    try { viewport.releasePointerCapture(evt.pointerId); } catch (e) { /* ignore */ }
+  }
+  viewport.addEventListener('pointerup', endDrag);
+  viewport.addEventListener('pointercancel', endDrag);
+  viewport.addEventListener('pointerleave', endDrag);
+
+  document.addEventListener('keydown', function (evt) {
+    if (evt.target && (evt.target.tagName === 'INPUT' || evt.target.tagName === 'TEXTAREA')) return;
+    const step = state.w * 0.08;
+    if (evt.key === 'ArrowLeft') { state.x -= step; apply(); }
+    else if (evt.key === 'ArrowRight') { state.x += step; apply(); }
+    else if (evt.key === 'ArrowUp') { state.y -= step; apply(); }
+    else if (evt.key === 'ArrowDown') { state.y += step; apply(); }
+    else if (evt.key === '+' || evt.key === '=') { zoom(1 / 1.2); }
+    else if (evt.key === '-' || evt.key === '_') { zoom(1.2); }
+    else if (evt.key === '0') { state.x = ix; state.y = iy; state.w = iw; state.h = ih; apply(); }
+  });
+
+  document.querySelectorAll('[data-pan-zoom="zoom-in"]').forEach((btn) => btn.addEventListener('click', () => zoom(1 / 1.2)));
+  document.querySelectorAll('[data-pan-zoom="zoom-out"]').forEach((btn) => btn.addEventListener('click', () => zoom(1.2)));
+  document.querySelectorAll('[data-pan-zoom="fit"]').forEach((btn) => btn.addEventListener('click', () => {
+    state.x = ix; state.y = iy; state.w = iw; state.h = ih; apply();
+  }));
+})();