@laitszkin/apollo-toolkit 3.9.7 → 3.10.0

package/AGENTS.md

@@ -77,6 +77,8 @@ This repository enables users to install and run a curated set of reusable agent
 - `node bin/apollo-toolkit.js codex openclaw trae` - 以非互動方式將技能安裝到指定目標。
 - `node bin/apollo-toolkit.js tools` - 列出 Apollo Toolkit 內建 CLI 工具。
 - `node bin/apollo-toolkit.js filter-logs app.log --start 2026-03-24T10:00:00Z` - 透過內建工具包裝器執行技能腳本。
+- `node bin/apollo-toolkit.js architecture` - 開啟專案 `resources/project-architecture/index.html` 架構圖。
+- `node bin/apollo-toolkit.js architecture diff` - 將 `docs/plans/**/architecture_diff/` 與目前架構圖配對成分頁式 before/after viewer（輸出至 `.apollo-toolkit/architecture-diff/`）。
 - `python3 scripts/validate_skill_frontmatter.py` - 驗證所有頂層技能 `SKILL.md` 的 frontmatter。
 - `python3 scripts/validate_openai_agent_config.py` - 驗證所有技能 `agents/openai.yaml` 設定。
 - `./scripts/install_skills.sh codex` - 用本地安裝腳本把技能安裝到 Codex 目錄。

package/CHANGELOG.md

@@ -10,6 +10,23 @@ All notable changes to this repository are documented in this file.
 
 ### Fixed
 
+## [v3.10.0] - 2026-05-11
+
+### Added
+
+- `init-project-html` skill: HTML architecture atlas (macro × sub-module SVG contract, sample demo, `references/TEMPLATE_SPEC.md` cheat sheet, `apltk architecture` helper script).
+- `spec-to-project-html` skill: refresh `resources/project-architecture/**` from active `docs/plans/**` specs using the same atlas rules.
+- `apltk architecture` and `apltk architecture diff`: open the project atlas or render a paginated before/after viewer from every `docs/plans/**/architecture_diff/` tree (pairs paths with `resources/project-architecture/`).
+- `generate-spec/references/TEMPLATE_SPEC.md` and `spec-to-project-html/references/TEMPLATE_SPEC.md`: local copies of the atlas vocabulary + DOM cheat sheet so each skill is self-contained when installed.
+- `cjk-pdf/agents/openai.yaml` and `merge-conflict-resolver/agents/openai.yaml` OpenAI agent interface stubs.
+- `test/architecture-script.test.js` covering registration, diff classification, and viewer output paths.
+
+### Changed
+
+- `generate-spec`: when a spec touches the atlas surface, emit `architecture_diff/` next to `spec.md` with path-aligned after-HTML (`_removed.txt` for deletions); keep rules in SKILL.md (reference file is non-authoritative).
+- Root `README.md` and `AGENTS.md`: document `apltk architecture` / `architecture diff` examples.
+- `.gitignore`: ignore `.apollo-toolkit/` (default output for the diff viewer).
+
 ## [v3.9.7] - 2026-05-09
 
 ### Changed

package/README.md

@@ -25,6 +25,7 @@ A curated skill catalog for Codex, OpenClaw, Trae, Agents, and Claude Code with
 - implement-specs
 - implement-specs-with-subagents
 - implement-specs-with-worktree
+- init-project-html
 - improve-observability
 - iterative-code-performance
 - iterative-code-quality
@@ -49,6 +50,7 @@ A curated skill catalog for Codex, OpenClaw, Trae, Agents, and Claude Code with
 - scheduled-runtime-health-check
 - shadow-api-model-research
 - solana-development
+- spec-to-project-html
 - solve-issues-found-during-review
 - submission-readiness-check
 - systematic-debug
@@ -112,6 +114,10 @@ apltk tools
 apltk filter-logs app.log --start "2026-03-24T10:00:00Z"
 apltk create-specs "Membership upgrade flow" --change-name membership-upgrade-flow
 apltk open-github-issue --help
+
+# Browse architecture HTML atlas and active-spec diffs
+apltk architecture          # opens resources/project-architecture/index.html
+apltk architecture diff     # paginates docs/plans/**/architecture_diff/ vs atlas
 ```
 
 ### Non-interactive install

package/cjk-pdf/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "cjk-pdf"
+  short_description: "CJK-safe PDF rendering, font selection, and screenshot visual QA"
+  default_prompt: >-
+    Use $cjk-pdf when producing PDFs that include Chinese or mixed CJK text: verify macOS font paths, enforce content safety, delegate rendering to the external `pdf` skill, then run screenshot-based visual QA before returning the final artifact.

package/generate-spec/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: generate-spec
 description: >-
-  Author planning trees under docs/plans: run `apltk create-specs`, hydrate templates (`spec/tasks/checklist/contract/design`; add `coordination.md`/`preparation.md` when parallel/prep dictates), cite official docs for every material external dependency, plan tests with **`test-case-strategy`**, and block product code changes until explicit user approval completes.
-  Use when drafting or refreshing specs before coding, restructuring multi-member batches, or recording clarifications—not when simply executing tasks from an approved plan (**`implement-specs*`** family instead).
-  Reject ALWAYS vague `tasks.md` lines missing file target + mutation + verifier; SPLIT work when scope exceeds three modules; never overwrite a neighboring `{change}` directory for a different issue.
-  Example bad: `- [ ] Add tests`… Example ok: `- [ ] src/auth/scope.rs — deny unknown scopes — Verify: cargo test scope::defaults`…
+  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).
+  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`…
 ---
 
 # Generate Spec
@@ -26,6 +27,12 @@ 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.
 - 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.
 
@@ -79,6 +86,19 @@ Always materialize: `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `desig
    - **Pause →** Do **`design.md` / `contract.md`** stay **coarser than `tasks.md`** (no mirrored checkbox choreography / file paths)—yet still constrain ordering and forbidden hallucinations?
    - **Pause →** For parallel batches, does `design.md` **avoid** duplicating batch ownership grids already locked in **`coordination.md`**?
 
+### 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:
+
+- 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.
+
+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.
+
+- **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.
+
 ### 4) Clarifications and approval
 
 On answers: update clarification/approval section in `checklist.md` first, then any of `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md`; **MUST** obtain approval again after material edits. **MUST NOT** touch product code pre-approval.

package/generate-spec/agents/openai.yaml

@@ -4,3 +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.

package/generate-spec/references/TEMPLATE_SPEC.md

@@ -0,0 +1,98 @@
+# HTML architecture atlas — 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.
+
+## Vocabulary
+
+- **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)
+```
+
+## 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>
+```
+
+### `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>
+```
+
+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
+
+- 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.
+
+## Edge-kind vocabulary (for macro `flow-edge-manifest`)
+
+| `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 |
+
+## Typography hint
+
+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.

package/init-project-html/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: init-project-html
+description: >-
+  Build the HTML architecture atlas. Macro `index.html` is ONE SVG showing feature-modules (clusters) AND every sub-module (nodes inside) together, with many-to-many edges, producer/consumer loops, and at least one cross-feature `m-edge--cross` data-row when applicable; macro MUST index every sub-module page in `atlas-submodule-index`. Each `features/<slug>/<sub-module>.html` describes ONLY itself: `sub-io` (function I/O) + `sub-vars` (variables-with-business-purpose) + `sub-dataflow` (internal flow) + `sub-errors`. Feature `index.html` stays lightweight (story + submodule-nav). Read strategy avoids context loss: list feature modules first; with subagents, dispatch one read-only subagent per feature and aggregate summaries before drawing; without subagents, read one feature, emit its pages, update macro incrementally, drop details, then move on — never read the whole codebase before writing. Distinctive typography; no purple-gradient/Inter defaults.
+---
+
+# Init Project HTML
+
+## Dependencies
+
+- Required: none (the template asset `references/architecture.css` ships with this skill and is copied at runtime).
+- Conditional: `spec-to-project-html` when the same atlas needs spec-driven refresh — that skill obeys the rules below.
+- Optional: `align-project-documents` when `docs/features` already names capabilities.
+- Optional: local `frontend-design` skill for bolder, non-generic visual direction.
+- Fallback: codebase too large for one pass → document scanned roots, explicit omissions, phased plan. **MUST NOT** pretend untread paths were verified.
+
+## Non-negotiables
+
+### Rule 1 — Cross-submodule interactions live only on the macro page
+
+- **MUST** render `resources/project-architecture/index.html` as **one SVG figure** showing both layers together:
+  - Layer A: **feature ↔ feature** user-visible journeys.
+  - Layer B: **sub-module ↔ sub-module** concrete calls / returns / data-row hand-offs that realise Layer A.
+- **MUST** draw each feature as an `m-cluster` (dashed frame); sub-modules are clickable nodes inside their cluster.
+- **MUST** include at least one node-pair carrying **≥2 edges** (e.g. service → db with SELECT / INSERT / UPDATE) to prove multi-edge support.
+- **MUST** include at least one **producer ↔ consumer** loop (call/return pair, or cyclic data-row).
+- **MUST** use **`m-edge--cross`** dashed-heavy edges for cross-feature data-row hand-offs whenever the system has them.
+- **MUST** include `<nav class="atlas-submodule-index">` linking every sub-module page in the atlas.
+
+### Rule 2 — Sub-module pages describe **only themselves**
+
+Each `features/<slug>/<sub-module>.html` contains exactly:
+
+1. `sub-io` — function I/O table (signature + side-effect chip + one-line purpose).
+2. `sub-vars` — **variables-with-business-purpose** table: every identifier this sub-module holds or threads between its functions (params, local state, struct fields, DB columns, config knobs, counters, time anchors) with type, scope chip (`sub-vars__scope--call|tx|persist|instance|loop`), and **business purpose** in business language (why it exists / which branch it decides / what breaks without it).
+3. `sub-dataflow` — internal value flow between this sub-module's own functions (optional small SVG; **never** draw external sub-modules here).
+4. `sub-errors` — errors this sub-module raises/returns (condition + meaning; HTTP mapping may be one line).
+
+**Forbidden** on sub-module pages: "I call X / Y calls me" narrative, cross-boundary `flow-edge-manifest`, cross-boundary `flow-return-row`, or any structure describing inter-submodule choreography. If unavoidable, end with one sentence + link "see macro atlas for cross-boundary interactions".
+
+### Rule 3 — Read order: never let the codebase wipe the context window
+
+Real production codebases dwarf the main agent's context. Reading the whole repo before writing pushes early details out by the end, making macro edges and sub-module pages contradict each other. **MUST** follow one of these two strategies:
+
+- **With subagents (preferred):** main agent first builds the **feature-module list** (slug + entry + boundary resources only), then dispatches **one read-only subagent per feature**. Each subagent deep-reads and returns ONLY a structured summary (sub-module list; per sub-module: function I/O, variables-with-business-purpose, internal flow steps, errors raised; outbound edges to other features). Main agent collects every summary and **only then** emits the macro SVG and all pages in one pass.
+- **Without subagents:** process features **one at a time** — read feature A end-to-end, **immediately** emit `features/A/` (overview + every sub-module page) and incrementally add A's cluster, nodes, and known edges to the macro. Mark edges pointing at unread features with `data-edge-target-pending="<future-slug>"`. **Drop A's function-level details from working memory**, then read feature B. After every feature is written, resolve all pending placeholders in the macro. **Never** read everything before writing.
+
+Both paths share one invariant: at any moment the main agent only holds *current-feature details + cross-feature boundary notes*.
+
+### Rule 4 — Per-page section contracts
+
+Each page type has a fixed required set of sections. Violating the contract is a Rule 1 or Rule 2 violation by definition.
+
+**A) Macro `resources/project-architecture/index.html`** (the only page that draws interactions):
+
+1. `<header class="atlas-header">` — title + generation timestamp.
+2. `<section class="atlas-summary">` — prose explaining why feature modules and sub-modules sit in one diagram; cite a real producer+consumer / multi-edge case.
+3. `<section class="atlas-legend">` — explains the four edge types: solid arrow = **call**, thin dashed = **return**, warm-tone heavy dashed = **data-row**, plus a note that multiple edges between the same node pair are allowed.
+4. `<section class="flow-section flow-section--macro">` with **one** `<figure class="flow-chart flow-chart--macro flow-chart--svg">` honouring every MUST in Rule 1, plus a mirrored `<ol class="flow-edge-manifest flow-edge-manifest--macro">` (one row per edge, with `data-edge-id` + `data-edge-kind`).
+5. `<nav class="atlas-submodule-index">` — links to every sub-module page across all features.
+6. `<nav class="atlas-features">` (optional) — middle-tier nav to each feature index.
+
+**B) Feature overview `features/<feature-slug>/index.html`** (intentionally lightweight; no cross-submodule flowchart):
+
+1. `<nav class="breadcrumb">` (`../../index.html` → macro).
+2. `<header>` — user-visible capability name.
+3. `<section class="feature-story">` — 1–3 paragraphs of user story; close with one sentence + link back to the macro.
+4. `<section class="submodule-nav">` — table of every sub-module page (link + one-line own responsibility).
+5. Optional `<section class="feature-trace">` for spec-ID traceability.
+
+**Forbidden on feature index**: `flow-chart--submodules`, `flow-chart--end-to-end`, `flow-edge-manifest`, or any other cross-submodule structure — those belong on the macro.
+
+**C) Sub-module `features/<feature-slug>/<sub-module-slug>.html`** (self-only; matches Rule 2):
+
+1. `<nav class="breadcrumb">`: `../../index.html` · `./index.html` · current sub-module.
+2. `<header>` — sub-module name + **own** responsibility (one paragraph; no "who I talk to").
+3. `<section class="sub-io">` — columns `function | signature (in / out) | side effects | purpose`; side-effect chips `pure` / `io` / `write` / `tx` / `lock` / `network` / …
+4. `<section class="sub-vars">` — columns `variable | type | lifecycle / scope | business purpose`; cover **every** business-branch-affecting identifier; scope chip values listed in Rule 2; business purpose in business language (no bland "stores some value").
+5. `<section class="sub-dataflow">` — numbered steps; optional small `<svg class="sub-dataflow__svg">` (nodes = internal variables/functions only; height ≤ 240, width ≤ 720).
+6. `<section class="sub-errors">` — errors raised/returned (condition + meaning).
+7. footer: one-sentence links back to `../../index.html` and `./index.html`.
+
+If a sub-module truly holds no business-branch-affecting variables (rare; usually pure pass-through), `sub-vars` MUST still appear as a single-row table that says so with a one-line justification.
+
+### Rule 5 — Naming, IDs, and shared assets
+
+- **`feature-slug`**: kebab-case, matching the **user-language capability** (e.g. `invite-code-registration`).
+- **`sub-module-slug`**: kebab-case, identifying the implementation boundary (e.g. `web-register-ui`, `public-api`, `registration-service`, `postgresql`).
+- **`data-feature-id` / `data-submodule-id`**: optional node attributes; **MUST** match directory/file names.
+- **`data-edge-id`**: stable id per macro edge (mirrored in the manifest row).
+- **`data-edge-kind`**: one of `call` | `return` | `data-row` | `failure`.
+- **Shared CSS**: on first run, copy `references/architecture.css` to `resources/project-architecture/assets/architecture.css`. Root `index.html` → `href="assets/architecture.css"`; everything under `features/<feature-slug>/` → `href="../../assets/architecture.css"`.
+
+### Rule 6 — Accessibility and styling minima
+
+- The macro SVG `<figure>` **MUST** carry an `aria-label` plus the mirrored `<ol class="flow-edge-manifest">` so screen-reader users get the full edge list without chasing pixels.
+- Cluster and node links **MUST** wrap their `<g>` in `<a>` and provide readable `<text>` (browsers expose `<text>` as the accessible name).
+- Sub-module `sub-io` and `sub-vars` tables **MUST** use semantic `<thead>` / `<tbody>`.
+- Colour MUST NOT be the sole semantic carrier: edge differences encode via line style (solid / dashed / heavy-dashed) AND colour.
+- Every diagram is static SVG — respect `prefers-reduced-motion` by not adding animation.
+- Quality bar: high contrast, print-friendly, restrained palette; avoid the "AI-default purple gradient" and Inter look-alike. Pair a recognisable display face (e.g. `Fraunces`) with `Plus Jakarta Sans`. Edges use `currentColor` so light/dark adapt; pages stay readable across widths via SVG `viewBox`.
+
+### Rule 7 — Other binding rules
+
+- **MUST** read the entire production codebase along language boundaries; record skipped roots and the reason in `atlas-summary`.
+- **MUST** anchor every user-visible capability to a concrete entry; **never** invent modules or integrations.
+- **MUST** migrate legacy single-file `features/<slug>.html` or feature-level cross-submodule flowcharts to the new layering on first touch.
+
+> Reference cheat sheets (DOM examples, the macro SVG class-hook table, vocabulary glossary) live in `references/TEMPLATE_SPEC.md`. That file is reference material only — every binding rule already lives here.
+
+## Standards (summary)
+
+- **Evidence**: every node and edge traces to a path/symbol/SQL/config.
+- **Execution**: feature-module list (shallow) → branch by environment (subagent fan-out or sequential read-write) → pending-edge resolution + cross-link check.
+- **Quality**: macro SVG carries at least one multi-edge case, one loop, and one cross-feature edge (when applicable); sub-module pages stay self-only; print-friendly contrast; zero `pending` edges remaining.
+- **Output**: `resources/project-architecture/` tree obeying Rules 1–7 — anything else counts as a violation.
+
+## Workflow
+
+### 1) Whole-repo inventory — list feature modules, not function bodies
+
+Scan the shipped source for **user-visible capabilities** (each one = one feature module): entry routes, CLI commands, UI pages, cron jobs, runners, event handlers, CDC streams. For each entry record only:
+
+- kebab-case `slug` + one-line user story.
+- **Boundary points**: entry symbol/file, outbound resources (DB tables, queue topics, external services, shared cache keys).
+- Candidate cross-feature edges (mark as candidates; do not verify yet).
+
+- **Pause →** Is the list actually complete? Note skipped roots with reason; no silent skips.
+- **Pause →** Did I dive into function bodies here? Roll back — keep only structural notes.
+
+### 2) Branch the deep-read by environment (Rule 3)
+
+#### 2A) With subagents (preferred)
+
+Dispatch one **read-only** subagent per feature. Require this summary template (no source-code excerpts):
+
+> **Feature `<slug>` summary**
+> - Sub-module list: one row per `<sub-module-slug>` (kind: ui / api / service / db / pure-fn / queue / external).
+> - Per sub-module: function signatures (in / out / errors), side-effect chip, variables-with-business-purpose, internal flow steps, errors raised.
+> - **Outbound boundaries**: which other features' sub-modules this one calls (call edges); which DB tables / topics / cache keys it touches that **another feature also reads or writes** (data-row / data-topic edges; mark direction).
+
+Main agent collects every summary, does **not** re-read source, then emits in one pass:
+
+1. Macro `index.html` (single SVG: clusters + multi-edge + call/return loop + cross-feature `m-edge--cross` + `atlas-submodule-index` + `flow-edge-manifest--macro`).
+2. `features/<slug>/index.html` per feature (lightweight: user story + `submodule-nav`).
+3. Per sub-module: self-only page with `sub-io` + `sub-vars` + `sub-dataflow` (small SVG if useful) + `sub-errors`.
+4. Copy `references/architecture.css` to `resources/project-architecture/assets/`.
+
+- **Pause →** Every cross-feature edge in the summaries has both source and target sub-module nodes actually drawn in the SVG? If not, add the node or split one out.
+
+#### 2B) Without subagents — feature-by-feature read-write loop
+
+Process the list from step 1 one feature at a time (topological hint: read-from data sources and pure helpers first, user-facing entries last). Per feature, run the full inner loop:
+
+1. **Deep-read** every sub-module of this feature (functions, variables, errors, cross-feature edges).
+2. **Write to disk immediately**:
+   - `features/<slug>/index.html` (lightweight).
+   - One page per sub-module (self-only: `sub-io` + `sub-vars` + `sub-dataflow` + `sub-errors`).
+   - For `sub-vars`, sweep every identifier (params, local state, struct fields, DB columns, config, counters, `now`) — anything that influences a business branch or external promise **must** appear.
+3. **Patch the macro `index.html` incrementally**: add this feature's cluster + sub-module nodes + intra-feature edges; mark edges pointing at unread features as `data-edge-target-pending="<future-slug>"` and note them in `figcaption`; mirror new edges in `flow-edge-manifest--macro`.
+4. **Drop function-level details from working memory**; keep only lightweight notes (cluster id, pending-edge list); do not re-read this feature's bodies when handling the next one.
+5. Return to step 1 for the next feature.
+
+After the last feature, do a final pass:
+
+- Resolve every pending placeholder in the macro (no `pending` residue allowed).
+- Verify `atlas-submodule-index` lists every sub-module page.
+- Confirm `architecture.css` is copied into `assets/`.
+
+- **Pause →** Pending edges remaining after the last feature? Either step 1's list missed a feature or step 3 dropped an edge — re-read and patch. Silent deletion is forbidden.
+
+### 3) Handover report
+
+Report: feature count, macro edge counts (call/return/cross), sub-module page count, uncovered paths + reasons, the read strategy actually used (2A or 2B), and stable IDs to hand off to `spec-to-project-html`.
+
+## Sample hints
+
+- Multiple SQL paths on `service ↔ db` → draw **separate edges**; do not merge.
+- Retry loops between `service ↔ generator(pure)` → call/return pair in the macro plus a `retry` side note; sub-module pages still describe only their own function I/O.
+- Cross-feature DB hand-off (A writes, B reads) → macro uses `m-edge--cross`; sub-module pages each describe only their own INSERT / SELECT functions.
+- Third-party systems → render as `m-sub--ext` (when extended) or cluster-external nodes; the trust boundary must be visible.

package/init-project-html/agents/openai.yaml

@@ -0,0 +1,13 @@
+interface:
+  display_name: "init-project-html"
+  short_description: "Bootstrap an HTML architecture atlas with a single macro feature × sub-module SVG"
+  default_prompt: >-
+    Use $init-project-html. Its `SKILL.md` is the authoritative rulebook (Rules 1–7); `references/TEMPLATE_SPEC.md` is a reference cheat sheet (vocabulary, class hooks, DOM snippets).
+    Read strategy to avoid context loss on large codebases. STEP 1: enumerate the feature-module list (slug + entry + boundary resources) WITHOUT diving into function bodies.
+    STEP 2: branch by environment.
+    (2A, preferred) if subagents are available, dispatch ONE read-only subagent per feature; each returns ONLY a structured summary (sub-modules; per sub-module: function I/O, variables-with-business-purpose, internal data flow, errors raised; outbound edges to other features). The main agent collects every summary first, then emits the whole atlas in one pass.
+    (2B, no subagents) process features ONE AT A TIME — deep-read feature A, IMMEDIATELY emit `features/A/index.html` + every sub-module page, incrementally patch the macro `index.html` to add A's cluster and known edges (mark edges pointing at unread features with `data-edge-target-pending="<future-slug>"`), drop A's function-level details from working memory, then move to feature B. After every feature is written, resolve every pending placeholder in the macro. NEVER read the whole codebase before writing.
+    Macro `index.html` MUST be a SINGLE SVG covering BOTH layers in one diagram: feature-modules as `m-cluster` frames AND every sub-module as a clickable node inside its cluster, with many-to-many edges (same node pair may carry multiple edges, e.g. SELECT/INSERT/UPDATE), producer ↔ consumer call/return loops, and cross-feature `m-edge--cross` data-row edges where applicable. The macro MUST also include `<nav class="atlas-submodule-index">` linking every sub-module page.
+    Each `features/<slug>/<sub-module>.html` describes ONLY itself: `sub-io` function I/O table + `sub-vars` variables-with-business-purpose table (every parameter / local state / struct field / DB column / config / counter / time anchor that influences a business branch, with type, scope chip `sub-vars__scope--call|tx|persist|instance|loop`, and a business-language purpose explaining why it exists and which branch it decides) + `sub-dataflow` internal flow + `sub-errors`. FORBIDDEN on sub-module pages: cross-boundary `flow-edge-manifest`, `flow-return-row`, or any "who I call / who calls me" narrative.
+    Feature `index.html` stays lightweight: user story + `submodule-nav` table only — no cross-submodule flowchart.
+    Copy `references/architecture.css` into `resources/project-architecture/assets/`. Mark TBD when evidence is missing. Keep IDs stable for $spec-to-project-html. Report which read strategy (2A or 2B) was actually used.

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

@@ -0,0 +1,98 @@
+# HTML architecture atlas — 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.
+
+## Vocabulary
+
+- **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)
+```
+
+## 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>
+```
+
+### `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>
+```
+
+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
+
+- 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.
+
+## Edge-kind vocabulary (for macro `flow-edge-manifest`)
+
+| `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 |
+
+## Typography hint
+
+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.

package/init-project-html/references/architecture-page.template.html

@@ -0,0 +1,35 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="generator" content="apollo-toolkit:init-project-html|spec-to-project-html" />
+    <!-- ARCHITECTURE_ROOT: default resources/project-architecture -->
+    <title>{{PAGE_TITLE}}</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,500;600&family=Plus+Jakarta+Sans:wght@400;500;600&display=swap"
+      rel="stylesheet"
+    />
+    <link rel="stylesheet" href="{{CSS_PATH}}" />
+  </head>
+  <body>
+    <main class="atlas-page atlas-page--{{PAGE_KIND}}">
+      <header class="atlas-header">
+        <p class="atlas-kicker">Architecture atlas</p>
+        <h1 class="atlas-title">{{HEADLINE}}</h1>
+        <p class="atlas-meta">
+          Updated <time datetime="{{UPDATED_ISO}}">{{UPDATED_DISPLAY}}</time>
+          · {{VERSION_OR_REF}}
+        </p>
+      </header>
+
+      {{BODY_SECTIONS}}
+
+      <footer class="atlas-meta" style="margin-top: 2rem">
+        <p>{{FOOTER_NOTE}}</p>
+      </footer>
+    </main>
+  </body>
+</html>