@laitszkin/apollo-toolkit 3.10.0 → 3.11.1

package/CHANGELOG.md

@@ -10,6 +10,43 @@ All notable changes to this repository are documented in this file.
 
 ### Fixed
 
+## [v3.11.1] - 2026-05-11
+
+### Added
+
+- `dataflow add` optional `--fn`, `--reads`, and `--writes` (comma-separated variable names): each internal step can reference a declared function and read/write declared variables in the same sub-module; `validate` rejects unknown names. The renderer draws a function pill plus reads/writes chips on sub-module internal flow diagrams.
+- `init-project-html` / `spec-to-project-html`: **Acceptance criteria** for macro edges (call/return/data-row/failure) and for sub-module diagrams (function flow + variable state); Rule 2 and CLI verb table updated; `TEMPLATE_SPEC.md` documents object-shaped `dataflow` steps and new CSS hooks.
+- Macro atlas UX: each sub-module rectangle is an `<a href="features/<feature>/<sub>.html">` with `aria-label`, nested SVG `<title>` tooltip, `cursor: pointer`, and clearer hover/focus styles.
+
+### Changed
+
+- `layout.js`: `measureSubmodule()` computes per-node width/height from slug, kind label, and `role` so elkjs lays out boxes that fit wrapped role text (replaces fixed 240×92 and the old single-line truncation).
+- `render.js`: macro SVG draws slug, kind, and multi-line role using the same `measureSubmodule()` output as layout; sub-dataflow SVG renders enriched steps with fn pill and reads/writes chips (from prior work in this release train, now validated and documented).
+
+### Fixed
+
+- `viewer.client.js`: defer pointer capture until the pointer moves past a small drag threshold so clicks on macro sub-module links navigate; swallow the synthetic click after an actual drag so pan does not accidentally open a page.
+
+## [v3.11.0] - 2026-05-11
+
+### Added
+
+- Declarative atlas CLI: every component (feature, sub-module, function, variable, dataflow step, error, edge, actor, meta) is now declared through `apltk architecture <verb> ...`. The CLI persists per-feature YAML under `resources/project-architecture/atlas/`, runs deterministic layout via `elkjs`, and re-renders HTML/SVG (with built-in pan/zoom) on every mutation.
+- `--spec <spec_dir>` flag: spec-mode mutations write the overlay snapshot under `<spec_dir>/architecture_diff/atlas/` and render only the affected proposed-after HTML pages there; `apltk architecture diff` continues to pair pages by relative path.
+- `apltk architecture` new verbs: `render`, `validate`, `undo`, plus per-component `add` / `set` / `remove` actions for features, sub-modules, functions, variables, dataflow steps, errors, and edges.
+- Built-in pan/zoom client for the macro atlas (mouse wheel, drag, +/-/Fit toolbar, keyboard arrows) shipped as `lib/atlas/assets/viewer.client.js`.
+- New test suites: `test/atlas-state.test.js`, `test/atlas-render.test.js`, `test/atlas-cli.test.js` covering YAML round-trip, overlay merge, layout no-overlap, rendering scope, and every CLI verb.
+- New runtime dependencies: `elkjs` (layered layout) and `js-yaml` (YAML state).
+
+### Changed
+
+- `init-project-html`, `spec-to-project-html`, and `generate-spec` SKILL.md / agents/openai.yaml / `references/TEMPLATE_SPEC.md`: rewritten around CLI verbs and the declarative atlas; binding rules now forbid hand-authoring HTML under `resources/project-architecture/**` or `architecture_diff/**` (the renderer owns layout, no-overlap, DOM, CSS, ARIA, pan/zoom).
+- `init-project-html/sample-demo/`: converted to YAML source (`atlas/atlas.index.yaml` + `atlas/features/*.yaml`) and regenerated via the new CLI.
+- `init-project-html/scripts/architecture.js`: now a thin shim — the legacy `open` / `diff` verbs stay sync for backward-compatible tests, while new declarative verbs (`feature add`, `submodule add`, etc.) route through `lib/atlas/cli.js`.
+- `.gitignore`: ignore `node_modules/` for local development; document that `package-lock.json` must remain committed so `npm ci` installs and published installs resolve the same dependency tree (`elkjs`, `js-yaml`).
+
+### Fixed
+
 ## [v3.10.0] - 2026-05-11
 
 ### Added

package/generate-spec/SKILL.md

@@ -2,8 +2,8 @@
 name: generate-spec
 description: >-
   Author docs/plans trees: run `apltk create-specs`, hydrate `spec/tasks/checklist/contract/design` (+ `coordination.md`/`preparation.md` when parallel/prep dictates), cite official docs for external deps, plan tests via **`test-case-strategy`**, block code edits until explicit user approval.
-  Architecture-touching specs also emit `architecture_diff/` next to `spec.md` (after-HTML for affected pages only): module-internal edits reuse the SAME path as `resources/project-architecture/<rel>.html` so `apltk architecture diff` aligns by path, additions use a new path, removals go in `_removed.txt`.
-  Use when drafting/refreshing specs or restructuring batches—not when executing approved plans (use **`implement-specs*`** instead).
+  Architecture-touching specs declare the proposed-after atlas via `apltk architecture --spec <spec_dir> <verb> ...`; the CLI writes overlay YAML to `<spec_dir>/architecture_diff/atlas/` and re-renders only the affected proposed-after HTML pages — never hand-author files under `architecture_diff/`.
+  Use when drafting/refreshing specs or restructuring batches — not when executing approved plans (use **`implement-specs*`** instead).
   Reject vague `tasks.md` missing file/mutation/verifier; SPLIT >3-module scope; never overwrite a neighbor `{change}`.
   Bad: `- [ ] Add tests`… OK: `- [ ] src/auth/scope.rs — deny unknown scopes — Verify: cargo test scope::defaults`…
 ---
@@ -27,12 +27,7 @@ description: >-
 - **`tasks.md` checklist items**: **every** `- [ ]` **MUST** specify (a) concrete file/function target, (b) specific modification and expected outcome, (c) a verification hook—**no** vague rows (`Implement integration`, `Add tests`). Forbidden vague items **MUST** be rewritten before approval.
 - **MUST** use `test-case-strategy` when planning non-trivial logic tests and checklist mapping (test IDs, drift checks). Every **non-trivial** `tasks.md` implementation item **MUST** name a focused unit drift check, another concrete verification hook, or **`N/A`** with a concrete reason.
 - **MUST NOT** modify implementation code before **explicit user approval** of the spec set. Clarifications **MUST** sync across affected files and **MUST** re-trigger approval. If scope becomes a **different issue**, **MUST** stop editing the old set and create a **new** `change_name`.
-- **MUST** when the proposed change touches the architecture surface (feature/sub-module add/rename/remove, edge add/remove, `sub-vars` or `sub-io` deltas), generate an `architecture_diff/` directory **next to `spec.md`** containing the proposed **after** HTML for **only the affected pages**, mirroring `resources/project-architecture/` paths produced by `init-project-html`. Use this skill's own `references/TEMPLATE_SPEC.md` for the vocabulary, macro SVG class hooks, and ready-to-copy `sub-io` / `sub-vars` / `sub-dataflow` DOM snippets — page-contract rules still come from `init-project-html/SKILL.md`. The CLI `apltk architecture diff` identifies diffs **by path alone**, so deviating from the three alignment rules below breaks the viewer:
-  - **Module-internal change** (same sub-module: function I/O, variables, internal flow, errors; or small in-place edits on `macro` / feature index pages): write the proposed-after HTML at the **SAME path** as `resources/project-architecture/<rel>.html`. This is the common case — never invent a new filename for an in-place edit, or the CLI mis-classifies it as add + remove.
-  - **Addition**: write at a new `architecture_diff/<new-rel>.html` whose mirror under `resources/project-architecture/` does not yet exist.
-  - **Removal**: list the removed `<rel>` in `architecture_diff/_removed.txt` (one relative path per line). Do not create an empty placeholder HTML for removals.
-  - **Rename = removal + addition**: list the old path in `_removed.txt` AND write proposed-after HTML at the new path.
-  Always copy `architecture.css` into `architecture_diff/assets/` so every page renders standalone via relative paths (`../../assets/architecture.css`). For batch specs the diff lives inside each member spec's directory only — **MUST NOT** duplicate at batch root. **MUST** keep all paths relative for portability.
+- **MUST** when the proposed change touches the architecture surface (feature / sub-module add / rename / remove, edge add / remove, `sub-vars` or function I/O deltas, internal dataflow / error deltas), declare the proposed-after state through `apltk architecture --spec <spec_dir> <verb> ...`. The CLI writes overlay YAML to `<spec_dir>/architecture_diff/atlas/` and renders only the affected proposed-after HTML pages under `<spec_dir>/architecture_diff/`; `apltk architecture diff` then pairs them with the base atlas by path. **MUST NOT** hand-author files under `architecture_diff/**` — the renderer owns layout, no-overlap, DOM, CSS, ARIA, and pan/zoom. For batch specs the overlay lives in each member spec's own directory only — **MUST NOT** duplicate at batch root. See this skill's own `references/TEMPLATE_SPEC.md` for the component schema cheat sheet and a quick worked example; the binding verbs and semantic rules live in `init-project-html/SKILL.md`.
 - Write prose in the **user’s language** by default; keep requirement/task/test IDs traceable across `spec.md`, `tasks.md`, and `checklist.md`.
 - **MUST** use **kebab-case** `change_name`; **MUST NOT** use spaces or arbitrary special characters in names.
 
@@ -88,16 +83,23 @@ Always materialize: `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `desig
 
 ### 3.5) Architecture diff (only when the proposal touches the architecture surface)
 
-When the spec changes a feature module, sub-module, edge, variable, or function I/O, create `architecture_diff/` **inside the spec directory** and write proposed-after HTML following the three alignment rules:
+When the spec changes a feature module, sub-module, edge, variable, or function I/O, declare the proposed-after state through the CLI scoped to this spec directory:
 
-- Module-internal change → write at the **SAME path** as `resources/project-architecture/<rel>.html`.
-- Addition → write at a new path.
-- Removal → list the `<rel>` in `architecture_diff/_removed.txt`; do not write an HTML placeholder.
+```bash
+SPEC_DIR=docs/plans/<date>/<change_name>
+apltk architecture --spec "$SPEC_DIR" feature add --slug ... --title "..." --story "..." --no-render
+apltk architecture --spec "$SPEC_DIR" submodule add|set|remove --feature ... --slug ... --kind ... --role "..." --no-render
+apltk architecture --spec "$SPEC_DIR" function|variable|dataflow|error add|remove ... --no-render
+apltk architecture --spec "$SPEC_DIR" edge add|remove --from <feat>[/sub] --to <feat>[/sub] --kind ... --label "..." --no-render
+apltk architecture --spec "$SPEC_DIR" render
+apltk architecture --spec "$SPEC_DIR" validate
+```
 
-Copy `architecture.css` into `architecture_diff/assets/`; keep every path relative. For batch specs the diff stays inside the member spec's own directory. `apltk architecture diff` pairs `architecture_diff/` with `resources/project-architecture/` for a paginated before/after viewer.
+The CLI writes overlay YAML under `$SPEC_DIR/architecture_diff/atlas/` and re-renders only the affected HTML pages under `$SPEC_DIR/architecture_diff/`. Cross-feature edges into features that are not declared in the overlay still resolve against the base atlas. For batch specs, scope each member spec's overlay to its own directory — never duplicate at the batch root. **Do not hand-edit** any file under `architecture_diff/`.
 
-- **Pause →** Did an in-place sub-module edit get written at a new path? Move it back to the same path — otherwise the CLI registers it as add + remove.
-- **Pause →** Does every `_removed.txt` entry actually exist under `resources/project-architecture/`? Drop entries that do not.
+- **Pause →** Did I touch any file under `architecture_diff/` by hand? Revert and re-run the CLI verb instead.
+- **Pause →** Does `apltk architecture --spec "$SPEC_DIR" validate` return OK? Resolve dangling edges and unknown enums before approval.
+- **Pause →** Does `apltk architecture diff` pair the spec's pages correctly (modified / added / removed)? A page that shows as remove + add means a slug was renamed inadvertently.
 
 ### 4) Clarifications and approval
 

package/generate-spec/agents/openai.yaml

@@ -4,4 +4,4 @@ interface:
   default_prompt: >-
     Use $generate-spec to create or update single-spec plans under docs/plans/<date>/<change_name>/ or parallel batches under docs/plans/<date>/<batch_name>/<change_name>/ with shared coordination.md and, only when specs cannot be parallel-safe without prior shared work, minimal non-business preparation.md; treat references/templates/*.md as binding format; member specs assume preparation finished—do not duplicate preparation tasks; surface collisions early and resolve ownership via coordination.md; fill BDD in spec.md; integrate $test-case-strategy into tasks/checklists.
     **Critical layering:** design.md + contract.md are higher-level guiding context only (architecture + cite-backed external truth; coarse INT-### / EXT-### anchors). tasks.md MUST be the ONLY enumerated runnable queue with path-level edits and verification hooks—derive tasks FROM spec + design + contract WITHOUT mirroring checklist rows into design/contract; optionally cite INT/EXT on task lines for traceability—never duplicate task choreography inside design.md or contract.md.
-    **Architecture diff:** When the spec touches the architecture surface (feature/sub-module add/rename/remove, edge changes, sub-vars / sub-io deltas), generate an `architecture_diff/` directory next to `spec.md` with proposed-after HTML for affected pages only, mirroring `resources/project-architecture/` paths produced by $init-project-html. Use this skill's own `references/TEMPLATE_SPEC.md` for vocabulary, class hooks, and DOM snippets — page-contract rules come from `init-project-html/SKILL.md`. Three hard rules so `apltk architecture diff` can pair before/after by PATH alone — (1) module-internal changes MUST be written at the SAME relative path as `resources/project-architecture/<rel>.html` (never invent a new filename for in-place edits, or the CLI will mis-classify it as add+remove); (2) additions go to a new path; (3) removals are listed in `architecture_diff/_removed.txt` (one relative path per line, no placeholder HTML). Rename = removed + added. Copy `architecture.css` into `architecture_diff/assets/`; keep every path relative; for batch specs the diff folder lives in each member spec's directory only, never duplicated at batch root.
+    **Architecture diff:** When the spec touches the architecture surface (feature/sub-module add/rename/remove, edge changes, sub-vars / sub-io / dataflow / error deltas), declare the proposed-after state through `apltk architecture --spec <spec_dir> <verb> ...`. The CLI writes overlay YAML under `<spec_dir>/architecture_diff/atlas/` and renders only the affected HTML pages under `<spec_dir>/architecture_diff/`; `apltk architecture diff` then pairs them with the base atlas by path. NEVER hand-author files under `architecture_diff/**` — the renderer owns layout, no-overlap, DOM, CSS, ARIA, and pan/zoom. Use $init-project-html `SKILL.md` and `references/TEMPLATE_SPEC.md` for the verb cheat sheet (`feature`, `submodule`, `function`, `variable`, `dataflow`, `error`, `edge` add/remove/set + `meta set`, `actor add`, plus `render`, `validate`, `undo`). For batch specs scope each member's overlay to that member's directory only — never duplicate at the batch root. Always run `apltk architecture --spec <spec_dir> validate` after the final mutation and ensure `apltk architecture diff` pairs every changed page (modified / added / removed) correctly.

package/generate-spec/references/TEMPLATE_SPEC.md

@@ -1,98 +1,117 @@
-# HTML architecture atlas — reference cheat sheet (generate-spec copy)
+# Atlas component schema — reference cheat sheet (generate-spec copy)
 
-> Reference material only. The **binding rules for atlas pages** (page contracts, naming, assets, accessibility, forbidden shortcuts) live in `init-project-html/SKILL.md`. The **binding rules for `architecture_diff/`** (the three-rule path-alignment contract used by `apltk architecture diff`) live in this skill's own `generate-spec/SKILL.md`. This file is a local glossary + class-hook table + DOM snippets so `generate-spec` can author proposed-after pages without re-deriving the markup, and stay self-contained when installed alone.
+> Reference material only. The binding rules for atlas pages (verbs, semantic contracts, evidence) live in `init-project-html/SKILL.md`. The binding rule for spec-time atlas changes (declare via CLI, never hand-author HTML) lives in this skill's own `generate-spec/SKILL.md`. This file lists the exact fields and enum values that `apltk architecture --spec <spec_dir>` accepts.
 
-## Vocabulary
+## Where the overlay lands
 
-- **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`.
+When you run any `apltk architecture --spec <spec_dir> <verb> ...`, the CLI writes:
 
-## 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>
+<spec_dir>/architecture_diff/
+├── atlas/
+│   ├── atlas.index.yaml          # optional partial override of meta / actors / cross-feature edges / feature ordering
+│   ├── 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 when macro visibly changes
+├── features/<slug>/index.html    # rendered when feature page visibly changes
+├── features/<slug>/<sub>.html    # rendered when sub-module visibly changes
+├── _removed.txt                  # auto-written from _removed.yaml; consumed by `apltk architecture diff`
+└── assets/                       # architecture.css + viewer.client.js (copied by the renderer)
 ```
 
-### `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>
+`apltk architecture diff` scans every `docs/plans/**/architecture_diff/**/*.html`, pairs them with `resources/project-architecture/` by relative path, and classifies each as **modified**, **added**, or **removed**. The CLI's overlay path layout guarantees correct pairing — agents do not need to manage paths manually.
+
+## Components (mirrors `init-project-html/references/TEMPLATE_SPEC.md`)
+
+The same component fields and enums apply in spec mode:
+
+| Component | Required fields | Enum values |
+| --------- | --------------- | ----------- |
+| `meta` | `title` | — (`summary` optional) |
+| `actor` | `id` (kebab-case), `label` | — |
+| `feature` | `slug` (kebab-case), `title` | — (`story`, `dependsOn` optional) |
+| `submodule` | `slug` (kebab-case), `kind` | `ui` `api` `service` `db` `pure-fn` `queue` `external` |
+| `function` | `name` | `side`: `pure` `io` `write` `tx` `lock` `network` |
+| `variable` | `name` | `scope`: `call` `tx` `persist` `instance` `loop` |
+| `dataflow` step | string | — |
+| `error` | `name` | — (`when`, `means` optional) |
+| `edge` | `from`, `to`, `kind` | `kind`: `call` `return` `data-row` `failure` |
+
+## Verb cheat sheet (spec mode)
+
+Always pass `--spec <spec_dir>`. Common patterns:
+
+```bash
+# Open the spec directory once as a shell variable for readability:
+SPEC_DIR=docs/plans/2026-05-11/add-2fa
+
+# Add a new sub-module to an existing feature in the base atlas:
+apltk architecture --spec "$SPEC_DIR" submodule add \
+  --feature register --slug 2fa --kind service \
+  --role "TOTP verification (planned: not yet implemented)" --no-render
+
+# Adjust an existing sub-module's role / kind:
+apltk architecture --spec "$SPEC_DIR" submodule set \
+  --feature register --slug api --role "Endpoint with 2FA gate" --no-render
+
+# Add functions / variables / dataflow / errors:
+apltk architecture --spec "$SPEC_DIR" function add \
+  --feature register --submodule 2fa --name VerifyTotp \
+  --in "ctx, code" --out "ok | ErrInvalidTotp" --side network \
+  --purpose "Checks the TOTP code against the user's seed." --no-render
+
+apltk architecture --spec "$SPEC_DIR" variable add \
+  --feature register --submodule 2fa --name totp_seed \
+  --type "bytes[20]" --scope persist \
+  --purpose "Seed material for TOTP verification (per user)." --no-render
+
+apltk architecture --spec "$SPEC_DIR" dataflow add \
+  --feature register --submodule 2fa --step "Load seed for userId" --no-render
+apltk architecture --spec "$SPEC_DIR" dataflow add \
+  --feature register --submodule 2fa --step "Validate TOTP code window" --no-render
+
+apltk architecture --spec "$SPEC_DIR" error add \
+  --feature register --submodule 2fa --name ErrInvalidTotp \
+  --when "Code mismatch within accepted window." \
+  --means "422 response with totp reason." --no-render
+
+# Add intra-feature edge:
+apltk architecture --spec "$SPEC_DIR" edge add \
+  --from register/api --to register/2fa --kind call \
+  --label "verify TOTP" --id e-api-2fa --no-render
+
+# Removals (overlay records them in _removed.yaml; the renderer emits _removed.txt):
+apltk architecture --spec "$SPEC_DIR" feature remove --slug legacy --no-render
+apltk architecture --spec "$SPEC_DIR" submodule remove --feature register --slug v0-shim --no-render
+
+# Render + validate once at the end (sed for batched mutations):
+apltk architecture --spec "$SPEC_DIR" render
+apltk architecture --spec "$SPEC_DIR" validate
 ```
 
-Scope chip vocabulary: `sub-vars__scope--call` (single call), `--tx` (transaction-bound), `--persist` (persisted), `--instance` (fixed at construction; lifetime-shared), `--loop` (retry/loop).
-
-### `sub-dataflow` small SVG sizing
+## Important constraints (binding)
 
-- 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.
+- **Never** hand-edit any file under `architecture_diff/` — the renderer rewrites them on every `apltk architecture --spec ... render` call.
+- The base atlas under `resources/project-architecture/` is **read-only** in spec mode; CLI writes never touch it.
+- Cross-feature edges into features that are not overlaid still resolve against the base atlas without re-declaring those features.
+- For batch specs, scope each member's overlay to its own member directory; never duplicate at the batch root.
 
-## Edge-kind vocabulary (for macro `flow-edge-manifest`)
+## Worked example: end-to-end overlay for a new "add 2FA" spec
 
-| `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 |
+The CLI invocation above produces this overlay tree (rendered HTML omitted for brevity):
 
-## Typography hint
+```
+docs/plans/2026-05-11/add-2fa/architecture_diff/
+├── atlas/
+│   ├── atlas.index.yaml
+│   └── features/register.yaml
+├── index.html
+├── features/register/index.html
+├── features/register/api.html
+├── features/register/2fa.html
+└── assets/architecture.css
+```
 
-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.
+Running `apltk architecture diff` then pairs `register/2fa.html` (added) and `register/api.html` + `register/index.html` + `index.html` (modified) with their base counterparts.