@laitszkin/apollo-toolkit 3.11.2 → 3.11.3

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

@@ -69,10 +69,18 @@
       return { x: state.x + xRatio * state.w, y: state.y + yRatio * state.h };
     }
 
+    // The diagram viewport owns the wheel gesture entirely: ANY wheel
+    // event that lands inside the viewport is consumed so the host page
+    // never scrolls underneath the user. The wheel zooms the SVG around
+    // the cursor; trackpad pinch-zoom (which arrives as ctrlKey wheel
+    // on macOS) is treated the same way for a single predictable model.
     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;
+      evt.stopPropagation();
+      const absX = Math.abs(evt.deltaX);
+      const absY = Math.abs(evt.deltaY);
+      if (absX < 0.5 && absY < 0.5) return;
+      const factor = evt.deltaY > 0 ? 1.08 : 1 / 1.08;
       const pt = clientToSvg(evt);
       zoom(factor, pt.x, pt.y);
     }, { passive: false });

package/init-project-html/lib/atlas/render.js

@@ -55,6 +55,10 @@ function head({ title, assetRel, pageKind }) {
     '  <meta charset="utf-8">',
     `  <title>${htmlEscape(title)}</title>`,
     '  <meta name="viewport" content="width=device-width, initial-scale=1">',
+    '  <meta name="color-scheme" content="dark">',
+    '  <link rel="preconnect" href="https://fonts.googleapis.com">',
+    '  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>',
+    '  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@0,9..144,300..600;1,9..144,300..500&family=Geist:wght@300..700&family=JetBrains+Mono:wght@400..600&display=swap">',
     `  <link rel="stylesheet" href="${assetRel}/architecture.css">`,
     '</head>',
   ].join('\n');
@@ -88,13 +92,13 @@ function findEdgeMeta(state, edgeId) {
 
 function renderMacroSvg(layout, state) {
   if (layout.empty) {
-    return '<svg class="atlas-svg" viewBox="0 0 320 160" role="img" aria-label="Atlas is empty"><text x="160" y="80" text-anchor="middle" fill="currentColor">Atlas has no features yet</text></svg>';
+    return '<svg class="atlas-svg" viewBox="0 0 320 160" preserveAspectRatio="xMidYMid meet" role="img" aria-label="Atlas is empty"><text x="160" y="80" text-anchor="middle" fill="currentColor">Atlas has no features yet</text></svg>';
   }
   const pad = 24;
   const vbW = Math.max(320, Math.ceil(layout.width + pad * 2));
   const vbH = Math.max(160, Math.ceil(layout.height + pad * 2));
   const parts = [];
-  parts.push(`<svg class="atlas-svg" viewBox="0 0 ${vbW} ${vbH}" role="img" aria-label="Project architecture atlas" data-atlas-svg="macro">`);
+  parts.push(`<svg class="atlas-svg" viewBox="0 0 ${vbW} ${vbH}" preserveAspectRatio="xMidYMid meet" role="img" aria-label="Project architecture atlas" data-atlas-svg="macro">`);
   parts.push('  <defs>');
   for (const kind of ['call', 'return', 'data-row', 'failure']) {
     parts.push(`    <marker id="arrow-${kind}" class="m-arrow m-arrow--${kind}" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" /></marker>`);
@@ -339,7 +343,7 @@ function renderInternalDataflowSvg(steps) {
   const totalW = padLeft + boxW + padRight;
 
   const parts = [];
-  parts.push(`<svg class="sub-dataflow__svg" data-atlas-svg="sub-dataflow" viewBox="0 0 ${totalW} ${totalH}" role="img" aria-label="Internal dataflow">`);
+  parts.push(`<svg class="sub-dataflow__svg" data-atlas-svg="sub-dataflow" viewBox="0 0 ${totalW} ${totalH}" preserveAspectRatio="xMidYMid meet" role="img" aria-label="Internal dataflow">`);
   parts.push('  <defs>');
   parts.push('    <marker id="sub-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" /></marker>');
   parts.push('  </defs>');
@@ -539,9 +543,46 @@ async function renderAll({ outDir, state, scope = null, removedPaths = [] }) {
     if (fs.existsSync(file)) fs.rmSync(file);
   }
 
+  // Full base render (no scope): sweep stale HTML so `apltk architecture
+  // render` is a true refresh — old feature folders or renamed sub-modules
+  // do not linger with the previous (broken) markup or styling.
+  if (!scope) {
+    sweepOrphanFeaturePages(outDir, state);
+  }
+
   return { written, layout };
 }
 
+function sweepOrphanFeaturePages(outDir, state) {
+  const featuresRoot = path.join(outDir, 'features');
+  if (!fs.existsSync(featuresRoot)) return;
+  const validFeatures = new Map();
+  for (const f of state.features || []) {
+    validFeatures.set(f.slug, new Set((f.submodules || []).map((s) => s.slug)));
+  }
+  let entries;
+  try { entries = fs.readdirSync(featuresRoot, { withFileTypes: true }); } catch (_e) { return; }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const featDir = path.join(featuresRoot, entry.name);
+    if (!validFeatures.has(entry.name)) {
+      fs.rmSync(featDir, { recursive: true, force: true });
+      continue;
+    }
+    const wantedSubs = validFeatures.get(entry.name);
+    let files;
+    try { files = fs.readdirSync(featDir); } catch (_e) { continue; }
+    for (const file of files) {
+      if (!file.toLowerCase().endsWith('.html')) continue;
+      if (file === 'index.html') continue;
+      const slug = file.slice(0, -5);
+      if (!wantedSubs.has(slug)) {
+        fs.rmSync(path.join(featDir, file), { force: true });
+      }
+    }
+  }
+}
+
 function scopeFromDiff(diff) {
   const submodules = [];
   for (const item of diff.modifiedSubmodules || []) submodules.push(item);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "3.11.2",
+  "version": "3.11.3",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",

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

@@ -1,14 +1,14 @@
 ---
 name: spec-to-project-html
 description: >-
-  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 — macro SVG and per-sub-module internal-dataflow diagrams stay zoomable just like the base atlas — so `apltk architecture diff` can pair before/after by path. Preserve the two-layer rule and the responsibility split: when subagents are available, each subagent reads ONE affected feature and declares EVERY intra-feature change itself (sub-modules, function / variable / dataflow / error rows, intra-feature edges including error and rollback flows); the main agent only aggregates outbound-boundary summaries and declares cross-feature edges. Without subagents, process features sequentially with the same split. Ground every declaration 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 — macro SVG and per-sub-module internal-dataflow diagrams stay zoomable like the base atlas — so `apltk architecture diff` pairs before/after by path under `docs/plans/**/architecture_diff/`. Preserve the two-layer rule and the responsibility split: **subagents only** — each subagent reads ONE affected feature and declares EVERY intra-feature overlay change; the main agent **waits until all subagents finish**, then aggregates outbound summaries and declares **only** cross-feature edges. **Exact CLI spelling:** always `apltk architecture --help`. 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 rulebook for what each component declaration means and which verbs to call. Reuse the same CLI here with `--spec`.
+- Required: **`init-project-html`** — its `SKILL.md` is the semantic rulebook; **`apltk architecture --help`** is the verb/flag source of truth. 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.
@@ -17,26 +17,26 @@ description: >-
 ## Non-negotiables
 
 - **MUST** read specs in order unless the user directs otherwise: `spec.md` → `design.md` → `contract.md` → coordination notes.
-- **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** declare every change through the CLI with `--spec <spec_dir>` (exact verbs/flags: **`apltk architecture --help`**). 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 — **subagents own intra-feature overlay changes; the main agent owns cross-feature seams**:
-  - **With subagents (preferred)** — main agent lists affected features first, then dispatches **one write-capable subagent per affected feature**. Each subagent deep-reads its feature and applies every intra-feature overlay mutation itself via `apltk architecture ... --spec <spec_dir> --feature <slug>` (add/remove sub-modules, function / variable / dataflow / error deltas, intra-feature edges — including error / rollback edges and ordered dataflow steps that capture variable state transitions). It returns ONLY a structured change summary of outbound boundaries (cross-feature edges added / changed / removed, with direction and proposed labels) plus its sub-module change list. The main agent never re-reads the feature source; it batches **only cross-feature** `edge add|remove` verbs from the aggregated summaries, then runs `apltk architecture render --spec ...` and `apltk architecture validate --spec ...`.
-  - **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.
+  - Sub-module pages stay self-only — express cross-boundary interactions via **edges** (cross-feature or intra-feature), never as sub-module page prose.
+  - Feature pages stay lightweight — cross-sub-module choreography belongs in **edges**, not in `dataflow` prose that pretends to cross features.
+- **MUST** reconcile deltas through the CLI families described in **`--help`**:
+  - Structural changes → `feature` / `submodule` (**add** / **set** / **remove** as appropriate).
+  - Per-sub-module rows → `function`, `variable`, `dataflow`, `error` (**add** / **remove** / **reorder** for dataflow where supported).
+  - Seams → `edge` **add** / **remove** (prefer stable **`--id`** when you may remove the same edge later).
+  - **`submodule remove`** / **`feature remove`** in spec mode populate removal manifests so `diff` can show **removed** pages; renames are usually **remove old slug + add new slug** so the viewer shows remove + add rather than a silent overwrite.
+- **MUST NOT** drop modules that are still present in code just because the spec omits them — keep them, or rewrite role/purpose to flag “out of spec scope”.
+- **MUST** scope reads to the **affected feature modules** from the spec/design diff (plus any feature owning the other end of a cross-feature edge into an affected one). **Subagents own intra-feature overlay writes; the main agent owns cross-feature seams — after all subagents finish:**
+  - Dispatch **one write-capable subagent per affected feature**. Each applies every intra-feature overlay mutation via `apltk architecture ... --spec <spec_dir>` (exact flags: **`--help`**). Each returns **ONLY** a structured summary: sub-module change list, outbound boundary changes (cross-feature edges to add/change/remove), and any `planned` / `gap` markers.
+  - **MUST** wait until **every** dispatched subagent has completed before running any cross-feature **`edge`** mutation, overlay-wide **`meta`** that stitches multiple features, or shared **`actor`** that exists only for cross-feature context.
+  - **Forbidden:** loading every affected feature’s source into the main agent before delegating — that explodes context and produces contradictory overlays.
 - **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; 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.
+- **Execution**: locate the plan set → list affected feature modules → subagent fan-out → **all complete** → cross-feature edges → `render --spec` if batched → `validate --spec` → `diff` check → 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.
 
@@ -44,8 +44,8 @@ description: >-
 
 Open the proposed-after viewer (`apltk architecture diff`) and verify both criteria on the overlay pages before reporting completion:
 
-1. **The macro overlay clearly shows the proposed-after feature × sub-module relationships**, including data flow (`--kind data-row`), interaction logic (`--kind call` + `--kind return`), error handling and rollback (`--kind failure`). Any new / changed / removed cross-boundary path the spec implies MUST exist as an edge mutation in the overlay — not as sub-module prose.
-2. **Each touched sub-module's internal overlay diagram clearly shows the function-level interactions inside it**, including function-to-function flow (`dataflow add --fn <declared-fn>`), variable state transitions (`--reads` / `--writes` referencing declared variables), and the resulting local data flow. If the spec introduces a new function or variable that participates in the flow, declare it via `function add` / `variable add` first, then reference it from the new `dataflow` step so `validate --spec` passes.
+1. **The macro overlay clearly shows the proposed-after feature × sub-module relationships**, including data flow (**`data-row`**), interaction logic (**`call`** + **`return`**), error handling and rollback (**`failure`**). Any new / changed / removed cross-boundary path the spec implies **MUST** exist as an edge mutation in the overlay — not as sub-module prose.
+2. **Each touched sub-module’s internal overlay diagram clearly shows the function-level interactions inside it**, including function references and variable reads/writes on `dataflow` steps. Declare `function` / `variable` before referencing them so `validate --spec` passes.
 
 ## Workflow
 
@@ -55,69 +55,49 @@ 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 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.
+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) Branch the deep-read + declare by environment (mirrors `init-project-html` Rule 3)
+### 3) Subagents patch features; orchestrator patches cross-feature seams **after** all workers finish
 
-#### 3A) With subagents (preferred) — workers patch their feature; main agent patches only cross-feature edges
-
-Dispatch one **write-capable subagent per affected feature**, plus the main agent for the macro seams. Each subagent owns every intra-feature overlay write and reports outbound boundaries upward:
+Dispatch one **write-capable subagent per affected feature**. Each subagent owns every intra-feature overlay write and reports outbound boundaries upward. Use **`apltk architecture --help`** for exact `add|set|remove|reorder` spelling.
 
 > **Feature `<slug>` subagent contract (overlay)**
-> - Read this feature's affected sub-modules and the cited spec passages / requirement IDs.
-> - Apply every intra-feature overlay mutation via `apltk architecture ... --spec <spec_dir>`:
->   - `submodule add|set|remove` for added / renamed / retired / kind-or-role-changed sub-modules.
->   - `function add|remove`, `variable add|remove`, `dataflow add|remove|reorder`, `error add|remove` for per-sub-module deltas. Order `dataflow` steps so the **variable state transitions** through the new path are visible end-to-end.
->   - Intra-feature `edge add|remove` for every changed function-call / return / data-row / failure / rollback edge between the feature's own sub-modules.
-> - Run `apltk architecture validate --spec <spec_dir>` (scoped check) before returning.
-> - **Return ONLY**: (i) the sub-module change list (slug + change-kind + new kind/role when relevant), (ii) outbound boundary changes (cross-feature edges added / changed / removed, with the other-end `feature/sub` and the suggested `--kind` / `--label`), (iii) any `planned` / `gap` flags so the main agent can mirror them in `meta.summary` if needed.
+> - Read this feature’s affected sub-modules and the cited spec passages / requirement IDs.
+> - Apply every intra-feature overlay mutation with `--spec <spec_dir>`: structural (`feature` / `submodule`), rows (`function`, `variable`, `dataflow`, `error`), and intra-feature **`edge`** changes (including failure / rollback between this feature’s own sub-modules). Order `dataflow` so **variable state** reads end-to-end.
+> - Run `apltk architecture validate --spec <spec_dir>` before returning.
+> - **Return ONLY**: (i) sub-module change list, (ii) outbound boundary changes (cross-feature edges add/change/remove with endpoints and suggested kind/label), (iii) any `planned` / `gap` flags for `meta.summary`.
 
-Main agent — after every subagent returns — declares **only** the cross-feature seams and renders once:
+**After every subagent has completed**, the main agent declares **only** cross-feature seams, then renders and validates:
 
 ```bash
-# one verb per cross-feature edge reported by the subagents
+# exact flags per edge: see --help
 apltk architecture edge add --spec <spec_dir> --from <featA>/<subA> --to <featB>/<subB> --kind call|return|data-row|failure --label "..." --no-render
 apltk architecture edge remove --spec <spec_dir> --id <stable_id> --no-render
 apltk architecture render --spec <spec_dir>
 apltk architecture validate --spec <spec_dir>
 ```
 
-- **Pause →** Do every `planned` / `gap` declaration appear consistently across affected sub-modules (e.g. role text + variable purpose strings)? Inconsistency would mislead reviewers.
-- The main agent **MUST NOT** re-declare a subagent's intra-feature components, and **MUST NOT** open source files for any feature it delegated.
-
-#### 3B) Without subagents — feature-by-feature read-declare loop
-
-Process the step-2 list one feature at a time. Per 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:
-
-- `apltk architecture render --spec <spec_dir>` (if you used `--no-render`).
-- `apltk architecture validate --spec <spec_dir>`.
+- **Pause →** Do `planned` / `gap` markers read consistently across affected sub-modules?
+- The main agent **MUST NOT** re-declare a subagent’s intra-feature components, and **MUST NOT** open source files for any feature it delegated.
 
-- **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.
+- **Pause →** Does `apltk architecture diff` pair every changed page correctly? If a page shows as add + remove instead of modified, you renamed a slug somewhere — re-check.
 
 ### 4) Traceability (suggested)
 
-Use `feature-trace` (or in `meta.summary` for spec-only changes) to map spec IDs to implementation status: `met` / `partial` / `planned` / `gap`.
+Use `feature-trace` (or `meta.summary` for spec-only changes) to map spec IDs to implementation status: `met` / `partial` / `planned` / `gap`.
 
 ### 5) Report
 
-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.
+List overlay files touched (or verb families used), the diff counts (`modified` / `added` / `removed`) from `apltk architecture diff`, confirmation that **all subagents finished before cross-feature wiring**, unresolved spec-vs-code gaps, and any follow-ups.
 
 ## Sample hints
 
-- **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.
+- **Batch merge**: each member spec’s `--spec <member_dir>` writes its own overlay; `diff` lists each spec’s section in the paginated viewer.
+- **Spec shrinks scope**: prefer `submodule set --role "deprecated: ..."` before `submodule remove` so reviewers see intent.
+- **Design-only change**: still review edges — order shifts surface as edge mutations; `validate --spec` catches 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.
+- `init-project-html/SKILL.md` — semantic contracts and acceptance criteria.
+- `init-project-html/references/TEMPLATE_SPEC.md` — schema cheat sheet (fields/enums), not a command list.
+- **`apltk architecture --help`** — live CLI reference.

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

@@ -2,17 +2,10 @@ interface:
   display_name: "spec-to-project-html"
   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), 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/`. The macro SVG and every sub-module's internal-dataflow diagram in the overlay output stay zoomable, just like the base atlas. 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 AND to enforce a hard responsibility split). 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.
-    (3A, preferred) with subagents, dispatch ONE write-capable subagent per affected feature. Each subagent deep-reads its own feature and applies every intra-feature overlay mutation itself via `apltk architecture ... --spec <spec_dir> --feature <slug>`: `submodule add|set|remove`, `function add|remove`, `variable add|remove`, `dataflow add|remove|reorder` (order the steps so the variable state transitions through the new path are visible end-to-end), `error add|remove`, and EVERY intra-feature `edge add|remove` (including failure / rollback edges between the feature's own sub-modules). The subagent returns ONLY a structured CHANGE summary of (i) sub-module changes (slug + change-kind + new kind/role when relevant), (ii) outbound boundary changes (cross-feature edges added / changed / removed with the other-end `feature/sub` and suggested `--kind` / `--label`), and (iii) any `planned` / `gap` flags. The main agent never re-reads source for a delegated feature and never re-declares its intra-feature components — it batches ONLY cross-feature `edge add|remove` from the aggregated summaries, then runs a single `apltk architecture render --spec <spec_dir>` and `apltk architecture validate --spec <spec_dir>`.
-    (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 "..." [--fn <declared-fn>] [--reads "v1,v2"] [--writes "v3,v4"] [--at N]` (or `--from i --to j` for reorder; every `--fn` / `--reads` / `--writes` value MUST reference a function/variable declared in the merged state for the same sub-module or `validate --spec` fails),
-    `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 an 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.
+    Use $spec-to-project-html. Read docs/plans (spec → design → contract). Every overlay mutation: `apltk architecture --spec <spec_dir> …`. **Exact commands: `apltk architecture --help`** — do not trust long command lists in docs.
+    CLI writes `<spec_dir>/architecture_diff/atlas/*.yaml` + affected HTML under `<spec_dir>/architecture_diff/`. Base `resources/project-architecture/` is read-only here. NEVER hand-edit `architecture_diff/**`.
+    **`apltk architecture diff`** builds a paginated viewer: scans all `docs/plans/**/architecture_diff/`, pairs overlay paths with base atlas HTML by relative path, labels modified/added/removed — use it to verify the architecture delta before hand-off.
+    **Subagents only:** dispatch ONE write-capable subagent per AFFECTED feature; each applies ALL intra-feature overlay mutations (`submodule`/`function`/`variable`/`dataflow`/`error`/`edge` within that feature). Each returns ONLY change summary + outbound boundary deltas for OTHER features.
+    **HARD GATE:** main agent MUST wait until ALL subagents finish before ANY cross-feature `edge add|remove`, overlay `meta` that stitches multiple features, or shared `actor` for cross-feature context. Then `render --spec`, `validate --spec`.
+    Sub-module pages stay self-only — cross-boundary = `edge`. For removals/renames in overlay, follow SKILL.md (`submodule remove` / remove+add pattern) so `diff` classifies correctly.
+    After work: `validate --spec` MUST be OK; run `diff` and report modified/added/removed counts. Semantic rules: $init-project-html SKILL.md.