@laitszkin/apollo-toolkit 3.10.0 → 3.11.1

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

@@ -0,0 +1,402 @@
+'use strict';
+
+// state.js — YAML persistence for the declarative atlas.
+//
+// On-disk layout (base mode):
+//   <project>/resources/project-architecture/atlas/
+//     ├── atlas.index.yaml          # meta, actors, ordered feature slug list, cross-feature edges
+//     ├── features/<slug>.yaml      # one file per feature (submodules + intra-feature edges)
+//     ├── atlas.history.log         # append-only audit JSONL
+//     └── atlas.history.undo.json   # single-step undo snapshot
+//
+// Overlay layout (spec mode mirrors base, plus _removed.yaml):
+//   <spec_dir>/architecture_diff/atlas/
+//     ├── atlas.index.yaml          # optional partial override of meta/actors/edges/feature ordering
+//     ├── features/<slug>.yaml      # full proposed state of any changed feature
+//     └── _removed.yaml             # {features: [...], submodules: [{feature, submodule}]}
+
+const fs = require('node:fs');
+const path = require('node:path');
+const yaml = require('js-yaml');
+
+const { emptyState } = require('./schema');
+
+const INDEX_FILE = 'atlas.index.yaml';
+const REMOVED_FILE = '_removed.yaml';
+const FEATURES_DIR = 'features';
+const HISTORY_FILE = 'atlas.history.log';
+const UNDO_FILE = 'atlas.history.undo.json';
+const ATLAS_DIRNAME = 'atlas';
+
+function readYaml(file) {
+  if (!fs.existsSync(file)) return null;
+  const text = fs.readFileSync(file, 'utf8');
+  if (text.trim().length === 0) return null;
+  return yaml.load(text);
+}
+
+function writeYaml(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const text = yaml.dump(data, { sortKeys: false, lineWidth: 100, noRefs: true });
+  fs.writeFileSync(file, text, 'utf8');
+}
+
+// load(atlasDir) reads the full base state. Missing directories are
+// treated as empty (returns emptyState()). Each referenced feature
+// file is loaded eagerly; missing feature files are surfaced as empty
+// stubs so validation can flag them.
+function load(atlasDir) {
+  const state = emptyState();
+  const indexFile = path.join(atlasDir, INDEX_FILE);
+  const index = readYaml(indexFile);
+  if (!index) return state;
+
+  if (index.meta) state.meta = { ...state.meta, ...index.meta };
+  if (Array.isArray(index.actors)) state.actors = index.actors;
+  if (Array.isArray(index.edges)) state.edges = index.edges;
+
+  const featureList = Array.isArray(index.features) ? index.features : [];
+  state.features = featureList
+    .map((entry) => {
+      const slug = typeof entry === 'string' ? entry : entry && entry.slug;
+      if (!slug) return null;
+      const featureFile = path.join(atlasDir, FEATURES_DIR, `${slug}.yaml`);
+      const feature = readYaml(featureFile);
+      if (!feature) {
+        return { slug, title: slug, story: '', dependsOn: [], submodules: [], edges: [] };
+      }
+      return normalizeFeature({ ...feature, slug: feature.slug || slug });
+    })
+    .filter(Boolean);
+
+  return state;
+}
+
+function normalizeFeature(feature) {
+  return {
+    slug: feature.slug,
+    title: feature.title || feature.slug,
+    story: feature.story || '',
+    dependsOn: Array.isArray(feature.dependsOn) ? feature.dependsOn : [],
+    submodules: Array.isArray(feature.submodules) ? feature.submodules.map(normalizeSubmodule) : [],
+    edges: Array.isArray(feature.edges) ? feature.edges : [],
+  };
+}
+
+function normalizeSubmodule(sub) {
+  return {
+    slug: sub.slug,
+    kind: sub.kind || 'service',
+    role: sub.role || '',
+    functions: Array.isArray(sub.functions) ? sub.functions : [],
+    variables: Array.isArray(sub.variables) ? sub.variables : [],
+    dataflow: Array.isArray(sub.dataflow) ? sub.dataflow : [],
+    errors: Array.isArray(sub.errors) ? sub.errors : [],
+  };
+}
+
+// save(atlasDir, state, {touch=true}) writes the index + every feature
+// YAML, dropping orphan feature files. When touch is true, meta.updatedAt
+// is refreshed.
+function save(atlasDir, state, options = {}) {
+  const { touch = true } = options;
+  const next = JSON.parse(JSON.stringify(state));
+  next.meta = next.meta || {};
+  if (touch) next.meta.updatedAt = new Date().toISOString();
+
+  const indexFile = path.join(atlasDir, INDEX_FILE);
+  const index = {
+    meta: next.meta,
+    actors: next.actors || [],
+    features: (next.features || []).map((f) => f.slug),
+    edges: next.edges || [],
+  };
+  writeYaml(indexFile, index);
+
+  const featuresDir = path.join(atlasDir, FEATURES_DIR);
+  fs.mkdirSync(featuresDir, { recursive: true });
+  const wanted = new Set((next.features || []).map((f) => `${f.slug}.yaml`));
+  for (const entry of fs.readdirSync(featuresDir)) {
+    if (entry.endsWith('.yaml') && !wanted.has(entry)) {
+      fs.rmSync(path.join(featuresDir, entry));
+    }
+  }
+  for (const feature of next.features || []) {
+    writeYaml(path.join(featuresDir, `${feature.slug}.yaml`), feature);
+  }
+}
+
+// loadOverlay reads the spec-mode overlay. Every field is optional.
+// Returns a structured overlay object even when the overlay directory
+// is missing (all-empty overlay, which merges to base unchanged).
+function loadOverlay(overlayDir) {
+  const overlay = {
+    meta: null,
+    actors: null,
+    edges: null,
+    featureOrder: null,
+    features: {},
+    removed: { features: [], submodules: [] },
+  };
+  if (!fs.existsSync(overlayDir)) return overlay;
+
+  const index = readYaml(path.join(overlayDir, INDEX_FILE));
+  if (index) {
+    if (index.meta !== undefined) overlay.meta = index.meta;
+    if (index.actors !== undefined) overlay.actors = index.actors;
+    if (index.edges !== undefined) overlay.edges = index.edges;
+    if (Array.isArray(index.features) && index.features.length > 0) {
+      overlay.featureOrder = index.features.map((entry) => (typeof entry === 'string' ? entry : entry && entry.slug)).filter(Boolean);
+    }
+  }
+
+  const featuresDir = path.join(overlayDir, FEATURES_DIR);
+  if (fs.existsSync(featuresDir)) {
+    for (const entry of fs.readdirSync(featuresDir)) {
+      if (!entry.endsWith('.yaml')) continue;
+      const data = readYaml(path.join(featuresDir, entry));
+      if (data && data.slug) overlay.features[data.slug] = normalizeFeature(data);
+    }
+  }
+
+  const removed = readYaml(path.join(overlayDir, REMOVED_FILE));
+  if (removed) {
+    if (Array.isArray(removed.features)) overlay.removed.features = removed.features;
+    if (Array.isArray(removed.submodules)) overlay.removed.submodules = removed.submodules;
+  }
+
+  return overlay;
+}
+
+// saveOverlay writes only the components the caller provided. Unlike
+// save(), this does not touch base files. Untouched features keep their
+// base definition; explicitly written features land in
+// overlayDir/features/<slug>.yaml; removed features/submodules land in
+// _removed.yaml.
+function saveOverlay(overlayDir, overlay) {
+  fs.mkdirSync(overlayDir, { recursive: true });
+
+  const indexPayload = {};
+  if (overlay.meta !== null && overlay.meta !== undefined) indexPayload.meta = overlay.meta;
+  if (overlay.actors !== null && overlay.actors !== undefined) indexPayload.actors = overlay.actors;
+  if (overlay.edges !== null && overlay.edges !== undefined) indexPayload.edges = overlay.edges;
+  if (overlay.featureOrder) indexPayload.features = overlay.featureOrder;
+  if (Object.keys(indexPayload).length > 0) {
+    writeYaml(path.join(overlayDir, INDEX_FILE), indexPayload);
+  } else if (fs.existsSync(path.join(overlayDir, INDEX_FILE))) {
+    fs.rmSync(path.join(overlayDir, INDEX_FILE));
+  }
+
+  const featuresDir = path.join(overlayDir, FEATURES_DIR);
+  fs.mkdirSync(featuresDir, { recursive: true });
+  const wanted = new Set(Object.keys(overlay.features || {}).map((slug) => `${slug}.yaml`));
+  for (const entry of fs.readdirSync(featuresDir)) {
+    if (entry.endsWith('.yaml') && !wanted.has(entry)) {
+      fs.rmSync(path.join(featuresDir, entry));
+    }
+  }
+  for (const [slug, feature] of Object.entries(overlay.features || {})) {
+    writeYaml(path.join(featuresDir, `${slug}.yaml`), feature);
+  }
+
+  const removedFile = path.join(overlayDir, REMOVED_FILE);
+  const hasRemoved = (overlay.removed.features && overlay.removed.features.length > 0)
+    || (overlay.removed.submodules && overlay.removed.submodules.length > 0);
+  if (hasRemoved) {
+    writeYaml(removedFile, overlay.removed);
+  } else if (fs.existsSync(removedFile)) {
+    fs.rmSync(removedFile);
+  }
+}
+
+// mergeOverlay produces the after-state given a base state and an
+// overlay. Overlay features fully replace base features of the same
+// slug; removed features/submodules drop from the merged result.
+// When overlay.featureOrder is provided it controls the order of
+// features in the merged output (unlisted features keep base ordering
+// at the tail).
+function mergeOverlay(base, overlay) {
+  const merged = JSON.parse(JSON.stringify(base));
+  if (overlay.meta) merged.meta = { ...merged.meta, ...overlay.meta };
+  if (overlay.actors !== null && overlay.actors !== undefined) merged.actors = overlay.actors || [];
+  if (overlay.edges !== null && overlay.edges !== undefined) merged.edges = overlay.edges || [];
+
+  const featureMap = new Map((merged.features || []).map((f) => [f.slug, f]));
+  for (const [slug, feature] of Object.entries(overlay.features || {})) {
+    featureMap.set(slug, feature);
+  }
+
+  if (overlay.removed && Array.isArray(overlay.removed.features)) {
+    for (const slug of overlay.removed.features) featureMap.delete(slug);
+  }
+  if (overlay.removed && Array.isArray(overlay.removed.submodules)) {
+    for (const { feature: fslug, submodule: sslug } of overlay.removed.submodules) {
+      const f = featureMap.get(fslug);
+      if (f) f.submodules = (f.submodules || []).filter((s) => s.slug !== sslug);
+    }
+  }
+
+  let orderedSlugs;
+  if (overlay.featureOrder) {
+    const seen = new Set();
+    orderedSlugs = [];
+    for (const slug of overlay.featureOrder) {
+      if (featureMap.has(slug) && !seen.has(slug)) {
+        orderedSlugs.push(slug);
+        seen.add(slug);
+      }
+    }
+    for (const slug of featureMap.keys()) {
+      if (!seen.has(slug)) orderedSlugs.push(slug);
+    }
+  } else {
+    orderedSlugs = [...featureMap.keys()];
+  }
+  merged.features = orderedSlugs.map((slug) => featureMap.get(slug));
+
+  return merged;
+}
+
+// diffPages compares the merged after-state against the base and
+// classifies which HTML pages must be regenerated (modified) versus
+// emitted fresh (added) versus listed in _removed.txt (removed).
+function diffPages(base, merged) {
+  const baseFeatures = new Map((base.features || []).map((f) => [f.slug, f]));
+  const mergedFeatures = new Map((merged.features || []).map((f) => [f.slug, f]));
+
+  const addedFeatures = new Set();
+  const modifiedFeatures = new Set();
+  const removedFeatures = new Set();
+  const addedSubmodules = []; // {feature, submodule}
+  const modifiedSubmodules = [];
+  const removedSubmodules = [];
+
+  for (const [slug, mergedFeat] of mergedFeatures) {
+    const baseFeat = baseFeatures.get(slug);
+    if (!baseFeat) {
+      addedFeatures.add(slug);
+      for (const sub of mergedFeat.submodules || []) {
+        addedSubmodules.push({ feature: slug, submodule: sub.slug });
+      }
+      continue;
+    }
+    if (JSON.stringify(featureVisualOf(baseFeat)) !== JSON.stringify(featureVisualOf(mergedFeat))) {
+      modifiedFeatures.add(slug);
+    }
+    const baseSubMap = new Map((baseFeat.submodules || []).map((s) => [s.slug, s]));
+    const mergedSubMap = new Map((mergedFeat.submodules || []).map((s) => [s.slug, s]));
+    for (const [subSlug, mergedSub] of mergedSubMap) {
+      const baseSub = baseSubMap.get(subSlug);
+      if (!baseSub) addedSubmodules.push({ feature: slug, submodule: subSlug });
+      else if (JSON.stringify(baseSub) !== JSON.stringify(mergedSub)) {
+        modifiedSubmodules.push({ feature: slug, submodule: subSlug });
+      }
+    }
+    for (const subSlug of baseSubMap.keys()) {
+      if (!mergedSubMap.has(subSlug)) removedSubmodules.push({ feature: slug, submodule: subSlug });
+    }
+  }
+  for (const slug of baseFeatures.keys()) {
+    if (!mergedFeatures.has(slug)) {
+      removedFeatures.add(slug);
+      for (const sub of baseFeatures.get(slug).submodules || []) {
+        removedSubmodules.push({ feature: slug, submodule: sub.slug });
+      }
+    }
+  }
+
+  const macroChanged = (
+    JSON.stringify(macroVisualOf(base)) !== JSON.stringify(macroVisualOf(merged))
+  );
+
+  return {
+    addedFeatures,
+    modifiedFeatures,
+    removedFeatures,
+    addedSubmodules,
+    modifiedSubmodules,
+    removedSubmodules,
+    macroChanged,
+  };
+}
+
+// featureVisualOf returns the projection of a feature that drives its
+// own page (title, story, dependsOn, submodule navigation cards, and
+// intra-feature edge list). Sub-module internals are compared
+// separately in diffPages.
+function featureVisualOf(feature) {
+  return {
+    title: feature.title,
+    story: feature.story,
+    dependsOn: feature.dependsOn || [],
+    submodules: (feature.submodules || []).map((s) => ({ slug: s.slug, kind: s.kind, role: s.role })),
+    edges: feature.edges || [],
+  };
+}
+
+// macroVisualOf returns the projection of state that drives the macro
+// SVG (cluster titles, submodule nodes + their kind/role badges, every
+// edge label/kind). Sub-module-internal fields (functions, variables,
+// dataflow, errors) are excluded so editing those alone does not force
+// a macro re-render.
+function macroVisualOf(state) {
+  return {
+    meta: state.meta || {},
+    actors: state.actors || [],
+    edges: state.edges || [],
+    features: (state.features || []).map((f) => ({
+      slug: f.slug,
+      title: f.title,
+      dependsOn: f.dependsOn || [],
+      submodules: (f.submodules || []).map((s) => ({ slug: s.slug, kind: s.kind, role: s.role })),
+      edges: f.edges || [],
+    })),
+  };
+}
+
+function appendHistory(atlasDir, entry) {
+  fs.mkdirSync(atlasDir, { recursive: true });
+  const file = path.join(atlasDir, HISTORY_FILE);
+  fs.appendFileSync(file, `${JSON.stringify({ ts: new Date().toISOString(), ...entry })}\n`, 'utf8');
+}
+
+function writeUndoSnapshot(atlasDir, state) {
+  fs.mkdirSync(atlasDir, { recursive: true });
+  fs.writeFileSync(path.join(atlasDir, UNDO_FILE), JSON.stringify(state, null, 2), 'utf8');
+}
+
+function readUndoSnapshot(atlasDir) {
+  const file = path.join(atlasDir, UNDO_FILE);
+  if (!fs.existsSync(file)) return null;
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function clearUndoSnapshot(atlasDir) {
+  const file = path.join(atlasDir, UNDO_FILE);
+  if (fs.existsSync(file)) fs.rmSync(file);
+}
+
+module.exports = {
+  ATLAS_DIRNAME,
+  INDEX_FILE,
+  REMOVED_FILE,
+  FEATURES_DIR,
+  HISTORY_FILE,
+  UNDO_FILE,
+  readYaml,
+  writeYaml,
+  load,
+  save,
+  loadOverlay,
+  saveOverlay,
+  mergeOverlay,
+  diffPages,
+  normalizeFeature,
+  normalizeSubmodule,
+  appendHistory,
+  writeUndoSnapshot,
+  readUndoSnapshot,
+  clearUndoSnapshot,
+  macroVisualOf,
+  featureVisualOf,
+};

package/init-project-html/references/TEMPLATE_SPEC.md

@@ -1,98 +1,155 @@
-# HTML architecture atlas — reference cheat sheet
+# Atlas component schema — reference cheat sheet
 
-> Reference material only. The **binding rules** (page contracts, naming, assets, accessibility, forbidden shortcuts) live in `init-project-html/SKILL.md`. This file is a glossary + class-hook table + ready-to-copy DOM snippets so an agent does not have to re-derive the markup. `spec-to-project-html` reuses the same vocabulary when refreshing diagrams.
+> Reference material only. The binding rules (read strategy, evidence requirements, what each verb means) live in `SKILL.md`. This file lists the exact fields and enum values that `apltk architecture` accepts; the renderer applies them to consistent DOM/CSS/ARIA hooks 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`.
-
-## 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)
+├── atlas/
+│   ├── atlas.index.yaml          # meta + actors + feature slug order + cross-feature edges
+│   ├── features/<slug>.yaml      # one file per feature (submodules + intra-feature edges)
+│   ├── atlas.history.log         # append-only audit log (JSONL)
+│   └── atlas.history.undo.json   # single-step undo snapshot
+├── index.html                    # rendered (do not hand-edit)
+├── features/<slug>/index.html    # rendered
+├── features/<slug>/<sub>.html    # rendered
+└── assets/                       # architecture.css + viewer.client.js (copied by the renderer)
 ```
 
-## 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>
-```
+## Components
+
+### `meta`
+
+| Field   | Type   | Required | Notes |
+| ------- | ------ | -------- | ----- |
+| title   | string | yes      | Macro page H1 + diff viewer title. |
+| summary | string | no       | Renders below the title; record scanned roots and deliberate omissions here. |
+| updatedAt | string (ISO) | auto | Touched on every save; do not set manually. |
+
+CLI: `apltk architecture meta set --title "..." --summary "..."`
+
+### `actors`
+
+| Field | Type | Required | Notes |
+| ----- | ---- | -------- | ----- |
+| id    | kebab-case slug | yes | Stable identity. |
+| label | string | yes | Display name. |
+
+CLI: `apltk architecture actor add --id end-user --label "End user"`
+
+### `feature`
+
+| Field      | Type | Required | Notes |
+| ---------- | ---- | -------- | ----- |
+| slug       | kebab-case | yes | Matches the directory name `features/<slug>/`. |
+| title      | string | yes | User-language capability name. |
+| story      | string | no  | 1–3 sentence user story shown on the feature page. |
+| dependsOn  | array of feature slugs | no | Shown as "Depends on:" links on the feature page. |
+| submodules | array of submodule | yes | Render-order matches list order. |
+| edges      | array of edge | no | Intra-feature edges (see below). |
+
+CLI: `apltk architecture feature add --slug <kebab> --title "..." --story "..." [--depends-on a,b]`
+
+### `submodule`
+
+| Field      | Type | Required | Notes |
+| ---------- | ---- | -------- | ----- |
+| slug       | kebab-case | yes | Matches the HTML filename `features/<feature>/<slug>.html`. |
+| kind       | enum `ui` `api` `service` `db` `pure-fn` `queue` `external` | yes | Drives node colour + label. |
+| role       | string | no | Own responsibility in one sentence. Renders as macro node footnote + feature card subtitle. |
+| functions  | array of function row | no | Renders the `sub-io` table. |
+| variables  | array of variable row | no | Renders the `sub-vars` table. |
+| dataflow   | array of dataflow step (string OR object — see below) | no | Renders the `sub-dataflow` internal flow SVG. |
+| errors     | array of error row | no | Renders the `sub-errors` table. |
+
+CLI: `apltk architecture submodule add --feature X --slug Y --kind api --role "..."`
+
+### `function` row
+
+| Field   | Type | Required | Notes |
+| ------- | ---- | -------- | ----- |
+| name    | string | yes | Function or method name. |
+| in      | string | no  | Comma-separated signature parts; rendered verbatim. |
+| out     | string | no  | May include `\|` to denote error returns. |
+| side    | enum `pure` `io` `write` `tx` `lock` `network` | no | Side-effect chip. |
+| purpose | string | no | One-line business purpose. |
+
+CLI: `apltk architecture function add --feature X --submodule Y --name fn --in "..." --out "..." --side tx --purpose "..."`
+
+### `variable` row
+
+| Field   | Type | Required | Notes |
+| ------- | ---- | -------- | ----- |
+| name    | string | yes | Parameter / field / column / counter name. |
+| type    | string | no  | Free-form. |
+| scope   | enum `call` `tx` `persist` `instance` `loop` | no | Lifetime/scope chip. |
+| purpose | string | no  | **Business** purpose — why this identifier exists, which branch it gates, what breaks without it. |
+
+CLI: `apltk architecture variable add --feature X --submodule Y --name v --type T --scope call --purpose "..."`
+
+### `dataflow` step
+
+Each step is either a plain string OR an object with one required and three optional fields. The renderer arranges them top-to-bottom inside a pan/zoom viewport; `--fn` becomes a function pill at the top of the step box, `--reads` becomes a green chip on the bottom-left, `--writes` becomes an orange chip on the bottom-right.
+
+| Field   | Type | Required | Notes |
+| ------- | ---- | -------- | ----- |
+| step    | string | yes | The action / observation in one short sentence. |
+| fn      | string | no  | Name of a `function` already declared in the SAME sub-module. `validate` fails otherwise. Use it to surface function-to-function transitions inside the sub-module. |
+| reads   | array of variable names | no | Each name must be a `variable` declared in the SAME sub-module. Shows up as `← reads: …` chip. |
+| writes  | array of variable names | no | Same constraint as `reads`. Shows up as `→ writes: …` chip. |
+
+Appended at the tail by default; pass `--at N` to insert at index N. Reorder with `apltk architecture dataflow reorder --feature X --submodule Y --from i --to j`. `--reads` / `--writes` accept comma-separated lists (`--reads "a, b"`).
+
+CLI:
 
-### `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 dataflow add --feature X --submodule Y --step "..." [--fn <declared-fn>] [--reads "v1,v2"] [--writes "v3,v4"]
+```
+
+### `error` row
+
+| Field | Type | Required | Notes |
+| ----- | ---- | -------- | ----- |
+| name  | string | yes | Symbolic name (e.g. `ErrInvalidCode`). |
+| when  | string | no | Condition that raises this error. |
+| means | string | no | Observable outcome (HTTP status, user feedback). |
+
+CLI: `apltk architecture error add --feature X --submodule Y --name ErrCode --when "..." --means "..."`
+
+### `edge`
+
+| Field | Type | Required | Notes |
+| ----- | ---- | -------- | ----- |
+| id    | kebab-case | no (auto if omitted) | Stable so cross-references survive renames. |
+| from  | `feature/submodule` (cross-feature) or `submodule` (intra-feature, when `--from` and `--to` share a feature) | yes | |
+| to    | same shape | yes | |
+| kind  | enum `call` `return` `data-row` `failure` | yes | Drives stroke/dash/colour and arrow head. |
+| label | string | no | Rendered at the middle of the edge path. |
+
+CLI: `apltk architecture edge add --from <feature>[/sub] --to <feature>[/sub] --kind call --label "..."`
+
+## Class hooks on rendered HTML
 
-Scope chip vocabulary: `sub-vars__scope--call` (single call), `--tx` (transaction-bound), `--persist` (persisted), `--instance` (fixed at construction; lifetime-shared), `--loop` (retry/loop).
+These are emitted automatically by `lib/atlas/render.js`. Agents do **not** write them by hand — they are listed here only so reviewers know which selectors are stable.
 
-### `sub-dataflow` small SVG sizing
+| Hook | Page |
+| --- | --- |
+| `.atlas-header`, `.atlas-summary`, `.atlas-canvas`, `.atlas-submodule-index`, `.atlas-legend` | macro |
+| `.m-cluster`, `.m-cluster__title`, `.m-node`, `.m-node--<kind>`, `.m-node__title/__kind/__role`, `.m-edge`, `.m-edge--<kind>`, `.m-edge__label` | macro SVG |
+| `.feature-header`, `.feature-story`, `.submodule-nav`, `.submodule-card`, `.feature-edges` | feature page |
+| `.submodule-header`, `.submodule-role`, `.sub-io`, `.sub-vars`, `.sub-dataflow`, `.sub-dataflow__canvas`, `.sub-dataflow__toolbar`, `.sub-dataflow__viewport`, `.sub-dataflow__step`, `.sub-dataflow__badge`, `.sub-dataflow__fn-text`, `.sub-dataflow__chip--reads`, `.sub-dataflow__chip--writes`, `.sub-errors`, `.submodule-kind--<kind>` | sub-module page |
 
-- 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.
+## Pan/zoom
 
-## Edge-kind vocabulary (for macro `flow-edge-manifest`)
+The CLI copies `assets/viewer.client.js` into the atlas. Two viewports exist:
 
-| `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 |
+- macro `index.html` — one `[data-pan-zoom-viewport]` wrapping the atlas SVG.
+- each sub-module page — one `[data-pan-zoom-viewport]` wrapping the sub-dataflow SVG (when the sub-module has any `dataflow` step).
 
-## Typography hint
+For every viewport the script wires:
 
-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.
+- mouse wheel zoom around the cursor,
+- click + drag to pan,
+- `+` / `−` / `Fit` buttons on the toolbar (scoped to the surrounding `[data-pan-zoom-container]`),
+- keyboard `←` `→` `↑` `↓` (pan), `+` `=` (zoom in), `−` `_` (zoom out), `0` (reset) — applied to the page's primary viewport.