@laitszkin/apollo-toolkit 3.10.0 → 3.11.0

package/spec-to-project-html/SKILL.md

@@ -1,46 +1,44 @@
 ---
 name: spec-to-project-html
 description: >-
-  Sync HTML architecture pages to active planning specs. **MUST** preserve the two-layer rule: macro `index.html` stays ONE SVG showing both feature-module and sub-module interactions (multi-edge, producer/consumer loops, cross-feature data-row); each sub-module page stays self-only (function I/O + variables-with-business-purpose + internal data flow + local errors). Feature `index.html` stays lightweight (story + submodule-nav). Read strategy mirrors `init-project-html`: list affected feature modules first; with subagents, dispatch one read-only subagent per affected feature to return summaries before patching; without subagents, patch one feature's pages plus its macro slice before moving to the next — never load every affected feature's code into the main context at once. Ground in repo evidence; mark `TBD` when code is missing.
+  Sync the project HTML architecture atlas to active planning specs by driving `apltk architecture --spec <spec_dir>`. The CLI writes overlay YAML under `<spec_dir>/architecture_diff/atlas/` and re-renders only the affected proposed-after HTML pages, so `apltk architecture diff` can pair before/after by path. Preserve the two-layer rule: macro `index.html` keeps feature clusters with every sub-module visible together; each sub-module page stays self-only (function I/O + variables-with-business-purpose + internal data flow + local errors); feature pages stay lightweight. Read strategy mirrors `init-project-html`: list affected features first, then either dispatch one read-only subagent per affected feature or process them sequentially — never load every affected feature's source into the main agent context at once. Ground every declaration in repo evidence; mark `TBD` when code is missing.
 ---
 
 # Spec To Project HTML
 
 ## Dependencies
 
-- Required: **`init-project-html`** — its `SKILL.md` is the binding rulebook for page contracts (Rules 1–7), and its `references/architecture.css` is the shared asset to copy. Local cheat sheet (same vocabulary + class hooks + DOM snippets) lives in this skill's own `references/TEMPLATE_SPEC.md`.
+- Required: **`init-project-html`** — its `SKILL.md` is the rulebook for what each component declaration means and which verbs to call. Reuse the same CLI here with `--spec`.
 - Conditional: **`recover-missing-plan`** if a spec pointer is missing.
 - Conditional: **`generate-spec`** / **`implement-specs*`** terminology for requirement IDs.
 - Optional: **`review-spec-related-changes`** when verifying diagram updates against specs.
-- Fallback: spec demands components that are absent from code → label **planned / gap** in macro summary and on affected nodes; **MUST NOT** mark them as implemented.
+- Fallback: spec demands components that are absent from code → declare them but use `TBD` strings or a `gap` token in the role/purpose/dataflow fields; **MUST NOT** mark them as implemented.
 
 ## Non-negotiables
 
 - **MUST** read specs in order unless the user directs otherwise: `spec.md` → `design.md` → `contract.md` → coordination notes.
-- **MUST** open and parse the existing macro `index.html`, every `features/<slug>/index.html`, **and every sub-module HTML** before editing — preserve `data-feature-id` / `data-submodule-id` / `data-edge-id` unless a rename is explicit and propagated everywhere (including the macro SVG nav and the macro manifest).
-- **MUST** obey `init-project-html/SKILL.md` Rules 1–7 (page contracts, naming, assets, accessibility, forbidden shortcuts). Two reminders that this skill violates most often:
-  - **Rule 1** — cross-submodule interactions live only in the macro SVG (multi-edge, producer/consumer, cross-feature data-row); the macro **MUST** index every sub-module page.
-  - **Rule 2** — sub-module pages contain only `sub-io` + `sub-vars` (variables-with-business-purpose) + `sub-dataflow` + `sub-errors`; no cross-boundary narrative.
-- **MUST** reconcile new requirements and design deltas:
-  - In the macro SVG, add/remove/relabel sub-module nodes and edges; every new node also gets a sub-module HTML and a manifest row.
-  - On sub-module pages, add/remove/update function I/O and internal data flow; **never** describe cross-boundary interactions here — update the macro edges instead.
-- **MUST** migrate any leftover legacy structure during the same edit pass:
-  - feature index `flow-chart--submodules` / `flow-edge-manifest` / `flow-return-row` → move to the macro; feature index reverts to lightweight.
-  - sub-module page `submodule-role` cross-boundary prose or cross-boundary manifests → delete or compress into a single "see macro" link.
-  - legacy single-file `features/<slug>.html` → migrate to the directory layout.
-- **MUST NOT** shrink the macro into prose-only or feature-only diagrams: the multi-edge + sub-module layer must remain visible in the SVG.
-- **MUST NOT** drop modules that are still present in code just because the spec omits them — keep them, or annotate as "out of spec scope" with a reason.
+- **MUST** declare every change through the CLI with `--spec <spec_dir>`. The CLI writes overlay YAML to `<spec_dir>/architecture_diff/atlas/` and re-renders only the affected proposed-after HTML pages there. **MUST NOT** hand-edit `architecture_diff/**/*.html` — the renderer owns those files.
+- **MUST** obey the semantic rules from `init-project-html/SKILL.md`:
+  - Sub-module pages stay self-only — express cross-boundary interactions via `edge add` (cross-feature) or intra-feature `edge add`, never as sub-module page prose.
+  - Feature pages stay lightweight — declare cross-submodule choreography through edges, not through sub-module-internal `dataflow` steps that wander outside the sub-module.
+- **MUST** reconcile new requirements and design deltas through CLI verbs:
+  - Add a sub-module → `submodule add --spec ...`. Removing → `submodule remove --spec ...` (the CLI lists the removed page in `_removed.txt` automatically).
+  - Rename a sub-module → `submodule remove` then `submodule add` with the new slug; the CLI emits both the removal entry and the new HTML page so `apltk architecture diff` classifies it as remove + add.
+  - Function / variable / dataflow / error deltas → corresponding `add` or `remove` verbs scoped to the sub-module.
+  - Edge changes → `edge add` or `edge remove` (use the stable `--id` when available to make the remove unambiguous).
+- **MUST NOT** drop modules that are still present in code just because the spec omits them — keep them, or rewrite their role/purpose strings to flag "out of spec scope".
 - **MUST** scope reads to the **affected feature modules** identified from the spec/design diff (plus any feature owning a cross-feature edge into an affected one). Apply the same context-safe read strategy as `init-project-html` Rule 3:
-  - **With subagents** — main agent lists affected features first, then dispatches **one read-only subagent per affected feature** to deep-read and return a structured change summary (affected sub-modules, variable / I/O / boundary deltas). Main agent **only** receives summaries, and only after every subagent reports does it patch the macro and pages in one pass.
-  - **Without subagents** — process features one at a time: read one affected feature, **immediately** patch its `features/<slug>/` tree plus the macro cluster/nodes/edges (mark edges pointing at unread affected features with `data-edge-target-pending`). Drop function-level details from memory before reading the next feature. After all features are patched, resolve every pending edge in a final pass.
-  - **Forbidden**: loading every affected feature's source into the main agent's context before patching — early details get pushed out and macro/sub-module pages contradict each other.
+  - **With subagents** — main agent lists affected features first, then dispatches **one read-only subagent per affected feature** to deep-read and return a structured change summary (affected sub-modules, variable / I/O / boundary deltas, edges added/removed). Main agent **only** receives summaries, and only after every subagent reports does it run the CLI verbs in one batched pass (use `--no-render` per verb and a single `apltk architecture render --spec ...` at the end).
+  - **Without subagents** — process features one at a time: read one affected feature, **immediately** drive the CLI verbs for that feature (with `--spec ...`). Drop function-level details from memory before reading the next feature.
+  - **Forbidden**: loading every affected feature's source into the main agent's context before declaring — early details get pushed out and overlay declarations contradict each other.
+- **MUST** run `apltk architecture validate --spec <spec_dir>` after the final mutation. Resolve every reported error before reporting completion.
 
 ## Standards (summary)
 
-- **Evidence**: cite the spec passage (design subsystem entry) alongside the code path.
-- **Execution**: locate the plan set → read the existing HTML tree → list affected feature modules → branch by environment (subagent fan-out OR sequential read-patch-write; resolve macro pending edges last) → link check.
-- **Quality**: the macro SVG keeps "≥2 edges on one node pair", "at least one producer/consumer loop", and "at least one cross-feature data-row" (when the spec still requires it); sub-module pages stay self-only; CSS paths correct; no pending edges left.
-- **Output**: touches only `resources/project-architecture/**`. If files are missing, scaffold via `init-project-html` first, then merge spec deltas.
+- **Evidence**: cite the spec passage (design subsystem entry) alongside the code path; record the citation in `meta.summary` or in sub-module purposes when relevant.
+- **Execution**: locate the plan set → list affected feature modules → branch by environment (subagent fan-out OR sequential read-declare) → `apltk architecture validate --spec ...` → handover.
+- **Quality**: macro overlay still shows every cross-feature data-row the spec requires; sub-module declarations stay self-only; `apltk architecture diff` opens cleanly with no orphan pages; no dangling edges.
+- **Output**: touches only `<spec_dir>/architecture_diff/atlas/**` (overlay state) and `<spec_dir>/architecture_diff/**/*.html` (renderer output). Base `resources/project-architecture/` is **NEVER** mutated.
 
 ## Workflow
 
@@ -50,67 +48,67 @@ User-pointed path wins; otherwise use the batch `coordination.md` or `recover-mi
 
 ### 2) List the affected feature modules (no function bodies yet)
 
-Derive from the spec/design diff which feature modules change: new nodes, edge changes, variable changes, error changes, retired sub-modules… **Also** include any feature that owns the other end of a cross-feature edge that is being changed (even if that feature's own spec is untouched). Record only `slug + change-kind`; do not enter function bodies yet.
+Derive from the spec/design diff which feature modules change: new sub-modules, edge changes, variable changes, error changes, retired sub-modules… **Also** include any feature owning the other end of a cross-feature edge that is being changed (even if that feature's own spec is untouched). Record only `slug + change-kind`; do not enter function bodies yet.
 
-### 3) Read the current HTML atlas (scoped to affected features)
+### 3) Branch the deep-read + declare by environment (mirrors `init-project-html` Rule 3)
 
-Load the macro `index.html` + every affected feature directory + that directory's sub-module pages; list existing node/edge IDs; lock the IDs to preserve (so steps 4/5 do not silently rename).
-
-### 4) Branch the deep-read + patch by environment (mirrors `init-project-html` Rule 3)
-
-#### 4A) With subagents (preferred)
+#### 3A) With subagents (preferred)
 
 Dispatch one **read-only subagent per affected feature**, requiring this summary:
 
 > **Feature `<slug>` change summary**
 > - Matching spec passages / requirement IDs.
-> - Affected sub-modules (added / renamed / retired / I/O changed).
-> - Per sub-module: function I/O, variables-with-business-purpose (additions / removals / renames), internal flow, errors raised.
-> - Boundary changes: new / changed / removed call edges and data-row edges (name the other-end feature / sub-module).
-> - Spec items the code does not yet scaffold: mark as `planned` / `gap`.
+> - Affected sub-modules (added / renamed / retired / I/O changed; new kind/role if changed).
+> - Per sub-module: function I/O deltas, variables-with-business-purpose deltas (added/removed/renamed), internal dataflow deltas, errors raised.
+> - Boundary changes: new / changed / removed `edge`s (call / return / data-row / failure) with the other-end feature/sub-module slugs.
+> - Spec items the code does not yet scaffold: mark as `planned` / `gap` and propose how to surface them (e.g. `--role "planned: ..."`).
 
-Main agent collects summaries and patches in one pass:
+Main agent collects summaries and runs the CLI in one batched pass:
 
-1. Patch the macro `index.html`: add/change/remove `<a><g class="m-sub">` nodes; add/change/remove `<path class="m-edge ...">`; mirror in `flow-edge-manifest--macro`; preserve multi-edge, call/return pairs, cross-feature data-row.
-2. Patch each affected `features/<slug>/index.html` (still lightweight) and each affected sub-module page (self-only: `sub-io`, `sub-vars`, `sub-dataflow`, `sub-errors` all in sync).
-3. Update `<nav class="atlas-submodule-index">`: link new pages; remove retired pages.
+```bash
+# add --no-render to every mutation, then render once at the end
+apltk architecture submodule add --spec <spec_dir> --feature X --slug Y --kind ... --role "..." --no-render
+apltk architecture function add --spec <spec_dir> ... --no-render
+apltk architecture edge add --spec <spec_dir> --from X/sub --to Y/sub --kind data-row --label "..." --no-render
+apltk architecture render --spec <spec_dir>
+apltk architecture validate --spec <spec_dir>
+```
 
-- **Pause →** Do `planned` / `gap` nodes appear consistently in both the macro and `atlas-summary` as "not yet implemented"? Inconsistency would mislead readers.
+- **Pause →** Do every `planned` / `gap` declaration appear consistently across affected sub-modules (e.g. role text + variable purpose strings)? Inconsistency would mislead reviewers.
 
-#### 4B) Without subagents — feature-by-feature read-patch-write
+#### 3B) Without subagents — feature-by-feature read-declare loop
 
-Process the step-2 list one feature at a time. Per feature, run the full inner loop:
+Process the step-2 list one feature at a time. Per feature:
 
-1. **Deep-read** this feature's affected sub-modules (functions, variables, boundaries).
-2. **Patch immediately**:
-   - `features/<slug>/index.html` (refresh user story; add/remove rows in `submodule-nav`; do NOT re-introduce a cross-submodule flowchart).
-   - Each affected sub-module page:
-     - Function I/O table updated (additions / renames / signature changes).
-     - `sub-vars`: add, remove, or rename variables (including DB columns, config knobs, counters, time anchors) introduced by the spec/design; rewrite the business-purpose column to match the new branches.
-     - `sub-dataflow` steps + small SVG refreshed.
-     - `sub-errors` updated with any new error types.
-     - Any leftover "who I talk to" text → move into a macro edge, or delete.
-3. **Incremental macro patch**: sync this feature's nodes/edges/manifest rows; mark edges pointing at **unread** affected features as `data-edge-target-pending="<future-slug>"`.
-4. **Drop function-level memory** of this feature; keep only cluster id and pending-edge notes.
-5. Return to step 1 for the next feature.
+1. **Deep-read** this feature's affected sub-modules.
+2. **Run CLI verbs immediately** with `--spec ...`: `submodule add|set|remove`, `function add|remove`, `variable add|remove`, `dataflow add|remove|reorder`, `error add|remove`, intra-feature `edge add|remove`.
+3. **Cross-feature edges**: if the target feature has not been overlaid yet, add the edge anyway — the CLI accepts edges into features that exist in the base atlas without re-declaring them in the overlay.
+4. **Drop function-level memory** of this feature; keep only cluster id + edge notes.
+5. Move to the next feature.
 
 Final pass after every feature is patched:
 
-- Resolve every macro `pending` edge; none may remain.
-- Verify `<nav class="atlas-submodule-index">` matches the final set of sub-module pages.
+- `apltk architecture render --spec <spec_dir>` (if you used `--no-render`).
+- `apltk architecture validate --spec <spec_dir>`.
 
-- **Pause →** Pending edges left? Step 2 missed an affected feature — re-read and patch.
+- **Pause →** Did `apltk architecture diff` pair every changed page correctly? If a page shows up as add + remove instead of modified, you renamed a slug somewhere. Re-check.
 
-### 5) Traceability (suggested)
+### 4) Traceability (suggested)
 
-Use `feature-trace` to map spec IDs to implementation status: `met` / `partial` / `planned` / `gap`.
+Use `feature-trace` (or in `meta.summary` for spec-only changes) to map spec IDs to implementation status: `met` / `partial` / `planned` / `gap`.
 
-### 6) Report
+### 5) Report
 
-List touched files, new edges / nodes, the read strategy used (4A or 4B), unresolved spec-vs-code gaps, and any follow-ups.
+List touched verbs (or the generated YAML files), the resulting diff counts (modified / added / removed) from `apltk architecture diff`, the read strategy used (3A or 3B), unresolved spec-vs-code gaps, and any follow-ups.
 
 ## Sample hints
 
-- **Batch merge**: when one domain has multiple specs, decide first whether sub-modules merge; keep node IDs unique.
-- **Spec shrinks scope**: soften or remove nodes, but keep a `figcaption` footnote in the macro explaining the retired requirement.
-- **Design-only change**: still re-review macro edges — interaction order shifts even when no module is added.
+- **Batch merge**: when one domain has multiple specs, each member's `--spec <member_dir>` writes its own overlay; `apltk architecture diff` shows them as separate sections in the paginated viewer.
+- **Spec shrinks scope**: prefer `submodule set --role "deprecated: ..."` so reviewers see the planned retirement before issuing `submodule remove`.
+- **Design-only change**: still review edges — interaction order shifts even when no sub-module is added; verify with `apltk architecture validate` to surface dangling references.
+
+## References
+
+- `init-project-html/SKILL.md` — authoritative verb-by-verb rulebook.
+- `init-project-html/references/TEMPLATE_SPEC.md` — component schema cheat sheet (also linked from this skill's `references/TEMPLATE_SPEC.md`).
+- `apltk architecture --help` — live CLI reference.

package/spec-to-project-html/agents/openai.yaml

@@ -1,12 +1,18 @@
 interface:
   display_name: "spec-to-project-html"
-  short_description: "Sync HTML architecture pages with active planning specs"
+  short_description: "Sync the project HTML architecture atlas with active planning specs via `apltk architecture --spec`"
   default_prompt: >-
-    Use $spec-to-project-html to read docs/plans (spec.md → design.md → contract.md), diff against `resources/project-architecture/` produced by $init-project-html, and patch HTML per `init-project-html/SKILL.md` Rules 1–7 (the authoritative rulebook). Local vocabulary + class-hook + DOM cheat sheet lives in this skill's own `references/TEMPLATE_SPEC.md`. Preserve the two-layer rule throughout.
-    The macro `index.html` stays ONE SVG with feature-module clusters AND every sub-module node drawn together, including many-to-many edges, producer/consumer loops, and cross-feature `m-edge--cross` data-row edges; the macro `flow-edge-manifest--macro` mirrors every SVG edge.
-    Read strategy (mirrors $init-project-html Rule 3 to avoid context loss). STEP 1: list AFFECTED feature modules from the spec/design diff, plus any feature owning a cross-feature edge into an affected one — without diving into function bodies.
+    Use $spec-to-project-html to read `docs/plans` (spec.md → design.md → contract.md), translate the spec/design delta into `apltk architecture --spec <spec_dir>` CLI verbs, and let the CLI write the overlay YAML under `<spec_dir>/architecture_diff/atlas/` plus the affected proposed-after HTML under `<spec_dir>/architecture_diff/`. NEVER hand-edit files under `architecture_diff/**` — the renderer (owned by $init-project-html) is the only writer. The base atlas under `resources/project-architecture/` is read-only in spec mode.
+    Read strategy (mirrors $init-project-html Rule 3 to avoid context loss). STEP 1: list AFFECTED feature modules from the spec/design diff (plus any feature owning a cross-feature edge into an affected one) — without diving into function bodies.
     STEP 2: branch by environment.
-    (4A, preferred) with subagents, dispatch ONE read-only subagent per affected feature; each returns a structured CHANGE summary (added/renamed/retired sub-modules, function I/O deltas, variables-with-business-purpose deltas, error deltas, outbound edge changes, `planned` / `gap` markers). The main agent collects every summary first, then patches the macro and pages in one pass.
-    (4B, no subagents) handle affected features ONE AT A TIME — deep-read feature A, IMMEDIATELY patch `features/A/index.html` + affected sub-module pages, incrementally patch the macro for A's cluster / nodes / edges (mark edges pointing at unread affected features with `data-edge-target-pending="<future-slug>"`), drop A's function-level details from memory, then move on. After every affected feature is patched, resolve every pending placeholder in a final macro pass. NEVER load every affected feature's source into the main agent context at once.
-    Each `features/<slug>/<sub-module>.html` stays self-only: update `sub-io` function table + `sub-vars` variables-with-business-purpose table (sync every renamed / added / removed parameter, local state, struct field, DB column, config knob, counter, or time anchor that influences a business branch, using scope chips `sub-vars__scope--call|tx|persist|instance|loop`) + `sub-dataflow` internal value flow + `sub-errors`. FORBIDDEN on sub-module pages: cross-submodule narrative, `flow-return-row`, or cross-boundary `flow-edge-manifest`.
-    Feature `index.html` stays lightweight (story + submodule-nav). Migrate legacy `arch-diagram` or feature-level cross-submodule flowcharts onto the macro when you touch them; keep CSS paths (`assets/` for root, `../../assets/` under features); scaffold via $init-project-html if files are missing. Report which read strategy (4A or 4B) was actually used.
+    (3A, preferred) with subagents, dispatch ONE read-only subagent per affected feature; each returns a structured CHANGE summary (added / renamed / retired sub-modules, function I/O deltas, variables-with-business-purpose deltas, error deltas, outbound edge changes, `planned` / `gap` markers). The main agent collects every summary first, then runs the CLI in one batched pass (`--no-render` per verb plus a single `apltk architecture render --spec <spec_dir>` at the end).
+    (3B, no subagents) handle affected features ONE AT A TIME — deep-read feature A, IMMEDIATELY drive the CLI verbs for A with `--spec ...`, drop A's function-level details from memory before moving on.
+    CLI verbs (always pass `--spec <spec_dir>`; kebab-case slugs):
+    `submodule add|set|remove --feature X --slug Y --kind ui|api|service|db|pure-fn|queue|external --role "..."`,
+    `function add|remove --feature X --submodule Y --name fn --in "..." --out "..." --side pure|io|write|tx|lock|network --purpose "..."`,
+    `variable add|remove --feature X --submodule Y --name v --type T --scope call|tx|persist|instance|loop --purpose "..."`,
+    `dataflow add|remove|reorder --feature X --submodule Y --step "..." [--at N]` (or `--from i --to j` for reorder),
+    `error add|remove --feature X --submodule Y --name ErrCode --when "..." --means "..."`,
+    `edge add|remove --from <feature>[/sub] --to <feature>[/sub] --kind call|return|data-row|failure --label "..." [--id <stable>]`.
+    Removals: `submodule remove` / `feature remove` writes `_removed.yaml`; the renderer emits `_removed.txt` and `apltk architecture diff` classifies the missing pages as `removed`. Rename = remove old slug + add new slug. After the final mutation run `apltk architecture validate --spec <spec_dir>` (must return OK) and `apltk architecture diff` to verify pairing.
+    Each sub-module page stays self-only — express any cross-boundary interaction as a macro edge via `edge add`, NEVER as sub-module page prose. For `planned` / `gap` items the spec mandates but code does not yet implement, surface the marker in the relevant field (e.g. `--role "planned: TOTP service"`, `--purpose "gap: not wired"`). Anchor every declaration to a concrete spec passage + code path. Report the read strategy used (3A or 3B), the resulting diff counts (`modified` / `added` / `removed`), and any unresolved spec-vs-code gaps.

package/spec-to-project-html/references/TEMPLATE_SPEC.md

@@ -1,98 +1,111 @@
-# HTML architecture atlas — reference cheat sheet (spec-to-project-html copy)
+# Atlas component schema — reference cheat sheet (spec-to-project-html copy)
 
-> Reference material only. The **binding rules** (page contracts, naming, assets, accessibility, forbidden shortcuts) live in `init-project-html/SKILL.md` (the atlas authority). `spec-to-project-html/SKILL.md` follows those same Rules 1–7 when patching pages to match active specs. This file is a local glossary + class-hook table + DOM snippets so this skill can stay self-contained when installed alone.
+> Reference material only. The binding rules (read strategy, evidence requirements, what each verb means) live in `init-project-html/SKILL.md` (atlas authority) and this skill's `SKILL.md` (spec-overlay variant). This file lists the exact fields and enum values that `apltk architecture --spec <spec_dir>` accepts; the renderer produces consistent DOM/CSS/ARIA hooks under `<spec_dir>/architecture_diff/` so agents never need to touch HTML.
 
-## Vocabulary
+## State files on disk
 
-- **Feature module** — one **user-visible end-to-end capability** (e.g. "invite-code registration", "get-invite-codes"). One directory `features/<feature-slug>/`. It is **not** a single web layer or a single database.
-- **Sub-module** — an implementation boundary inside that capability (front-end page, public API, domain service, PostgreSQL, pure helpers, message queues…). One HTML page per sub-module, sibling to the feature's `index.html`.
+Base atlas (read-only from this skill's perspective):
 
-## Directory layout (target output)
-
-```text
-resources/project-architecture/
-  index.html                           # macro: feature × sub-module in one SVG with multi-edge + data-row flow
-  assets/
-    architecture.css
-  features/
-    <feature-slug>/                    # one feature module = one directory
-      index.html                       # lightweight overview (story + submodule nav)
-      <sub-module-slug>.html           # one HTML per sub-module (own I/O + internal flow)
 ```
-
-## Macro SVG — CSS class hooks
-
-| Element | class |
-|---|---|
-| Actor block | `m-actor` |
-| Feature cluster frame | `m-cluster` / `m-cluster__rect` / `m-cluster__title` |
-| Sub-module node | `m-sub` (add `m-sub--db` for databases) |
-| Edge | `m-edge` + modifier `m-edge--call` / `m-edge--return` / `m-edge--cross` |
-| Edge label | `m-edge__label` (cross-feature labels add `m-edge__label--cross`) |
-
-## DOM snippets
-
-### `sub-io` function I/O table
-
-```html
-<section class="sub-io">
-  <h2>Function I/O</h2>
-  <table>
-    <thead><tr><th>Function</th><th>Signature</th><th>Side effects</th><th>Purpose</th></tr></thead>
-    <tbody>
-      <tr>
-        <td><code>FunctionName</code></td>
-        <td class="sub-io__signature">
-          <strong>in:</strong> <code>T1</code>, <code>T2</code><br>
-          <strong>out:</strong> <code>R</code> | <code>ErrX</code>
-        </td>
-        <td><span class="sub-io__side sub-io__side--pure">pure</span></td>
-        <td>One-line purpose.</td>
-      </tr>
-    </tbody>
-  </table>
-</section>
+<project>/resources/project-architecture/atlas/
+├── atlas.index.yaml
+├── features/<slug>.yaml
+├── atlas.history.log
+└── atlas.history.undo.json
 ```
 
-### `sub-vars` variables-with-business-purpose table
-
-```html
-<section class="sub-vars">
-  <h2>Variables &amp; business purpose</h2>
-  <p class="sub-vars__intro">Identifiers this sub-module holds or threads through. Types align readers; business purpose comes first.</p>
-  <table>
-    <thead>
-      <tr><th>Variable</th><th>Type</th><th>Scope</th><th>Business purpose</th></tr>
-    </thead>
-    <tbody>
-      <tr>
-        <td class="sub-vars__name">someVar</td>
-        <td class="sub-vars__type">SomeType</td>
-        <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
-        <td>One line: this value decides branch X; without it Y breaks.</td>
-      </tr>
-    </tbody>
-  </table>
-</section>
+Overlay (where this skill writes via `--spec`):
+
 ```
+<spec_dir>/architecture_diff/
+├── atlas/
+│   ├── atlas.index.yaml          # optional partial override (meta / actors / cross-feature edges / feature order)
+│   ├── features/<slug>.yaml      # full proposed state of any changed feature
+│   ├── _removed.yaml             # {features: [...], submodules: [{feature, submodule}]}
+│   ├── atlas.history.log
+│   └── atlas.history.undo.json
+├── index.html                    # rendered (re-emit only when macro visibly changes)
+├── features/<slug>/index.html    # rendered (re-emit when the feature page would visibly change)
+├── features/<slug>/<sub>.html    # rendered (re-emit when the sub-module's tables/dataflow change)
+├── _removed.txt                  # auto-written by the renderer; lists removed HTML paths
+└── assets/                       # architecture.css + viewer.client.js (copied by the renderer)
+```
+
+## Components (mirrors `init-project-html/references/TEMPLATE_SPEC.md`)
+
+### `meta`
+
+| Field   | Type   | Required | Notes |
+| ------- | ------ | -------- | ----- |
+| title   | string | yes      | Macro page H1; the spec overlay typically keeps the base title. |
+| summary | string | no       | Update if the spec changes scanned roots or known omissions. |
+
+CLI: `apltk architecture meta set --spec <spec_dir> --title "..." --summary "..."`
+
+### `actor`
+
+| Field | Type | Required | Notes |
+| ----- | ---- | -------- | ----- |
+| id    | kebab-case | yes | Stable identity. |
+| label | string | yes | Display name. |
+
+CLI: `apltk architecture actor add --spec <spec_dir> --id ... --label "..."`
+
+### `feature`
 
-Scope chip vocabulary: `sub-vars__scope--call` (single call), `--tx` (transaction-bound), `--persist` (persisted), `--instance` (fixed at construction; lifetime-shared), `--loop` (retry/loop).
+Same shape as base mode (`slug`, `title`, `story`, `dependsOn`, `submodules`, `edges`). `submodule add|remove`, `function add|remove`, etc. mutate the feature's full overlay snapshot under the hood — declare what you would have declared in base mode, but pass `--spec <spec_dir>`.
 
-### `sub-dataflow` small SVG sizing
+CLI: `apltk architecture feature add --spec <spec_dir> --slug <kebab> --title "..." --story "..."`
 
-- Node class: `d-node`; edge class: `d-edge` (side-effect edges use `d-edge--side`).
-- Recommended viewBox: height ≤ 240, width ≤ 720.
-- Nodes are this sub-module's internal variables/functions only.
+### `submodule`
 
-## Edge-kind vocabulary (for macro `flow-edge-manifest`)
+| Field | Type | Required | Notes |
+| ----- | ---- | -------- | ----- |
+| slug  | kebab-case | yes | The HTML filename. |
+| kind  | enum `ui` `api` `service` `db` `pure-fn` `queue` `external` | yes | Drives node colour + chip. |
+| role  | string | no | Own responsibility in one sentence. Use `planned: ...` or `gap: ...` to mark spec items the code does not yet implement. |
+| functions / variables / dataflow / errors | arrays | no | Edited through their own CLI verbs. |
 
-| `data-edge-kind` | meaning | typical visual |
-|---|---|---|
-| `call` | function call / HTTP request | solid arrow |
-| `return` | return value / response | thin dashed arrow |
-| `data-row` | cross-feature hand-off via data rows (not a function call) | warm-tone heavy dashed |
-| `failure` | failure branch | red solid arrow with `failure` chip in the manifest row |
+CLI: `apltk architecture submodule add|set|remove --spec <spec_dir> --feature X --slug Y --kind ... --role "..."`
 
-## Typography hint
+### `function`, `variable`, `dataflow`, `error`
+
+Each row uses the same fields documented in `init-project-html/references/TEMPLATE_SPEC.md`. Always pass `--spec <spec_dir>` so the write lands in the overlay.
+
+### `edge`
+
+| Field | Type | Required | Notes |
+| ----- | ---- | -------- | ----- |
+| id    | kebab-case | recommended | Pass `--id <stable>` when adding or removing so the CLI matches unambiguously. |
+| from  | `feature/submodule` or (intra-feature) `submodule` | yes | |
+| to    | same shape | yes | |
+| kind  | enum `call` `return` `data-row` `failure` | yes | |
+| label | string | no | |
+
+CLI: `apltk architecture edge add|remove --spec <spec_dir> --from <feature>[/sub] --to <feature>[/sub] --kind ... --label "..."`
+
+## Diff classification (how `apltk architecture diff` pairs pages)
+
+`apltk architecture diff` scans every `docs/plans/**/architecture_diff/**/*.html` (skipping `assets/` and `atlas/`) and pairs by path against `resources/project-architecture/`:
+
+| Base exists? | Overlay HTML exists? | Listed in `_removed.txt`? | Classification |
+| ------------ | -------------------- | ------------------------- | -------------- |
+| yes          | yes                  | no                        | **modified** (split before/after view) |
+| no           | yes                  | no                        | **added** (single after view) |
+| yes          | no                   | yes                       | **removed** (single before view) |
+
+The renderer writes `_removed.txt` automatically from `_removed.yaml`; agents only set the YAML through `feature remove` / `submodule remove`.
+
+## Quick example: add a 2FA sub-module to an existing feature
+
+```bash
+apltk architecture --spec docs/plans/2026-05-11/add-2fa \
+  submodule add --feature register --slug 2fa --kind service \
+  --role "TOTP verification (planned: not yet implemented)"
+apltk architecture --spec docs/plans/2026-05-11/add-2fa \
+  edge add --from register/api --to register/2fa --kind call --label "verify TOTP" --id e-api-2fa
+apltk architecture --spec docs/plans/2026-05-11/add-2fa validate
+apltk architecture diff
+```
 
-Pair a recognisable display face (e.g. `Fraunces`) with `Plus Jakarta Sans`. Avoid the "AI-default purple gradient" and Inter look-alike. Detailed rules live in `init-project-html/SKILL.md` § Rule 6.
+The CLI writes only the affected HTML pages (`features/register/2fa.html` plus any page whose visible state changed) into `architecture_diff/`, and the diff viewer pairs them with the base atlas.