@laitszkin/apollo-toolkit 3.9.7 → 3.11.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,43 @@ All notable changes to this repository are documented in this file.
 
 ### Fixed
 
+## [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
+
+- `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 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`…
 ---
 
 # Generate Spec
@@ -26,6 +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 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.
 
@@ -79,6 +81,26 @@ 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, declare the proposed-after state through the CLI scoped to this spec directory:
+
+```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
+```
+
+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 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
 
 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 / 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

@@ -0,0 +1,117 @@
+# Atlas component schema — reference cheat sheet (generate-spec copy)
+
+> 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.
+
+## Where the overlay lands
+
+When you run any `apltk architecture --spec <spec_dir> <verb> ...`, the CLI writes:
+
+```
+<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)
+```
+
+`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
+```
+
+## Important constraints (binding)
+
+- **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.
+
+## Worked example: end-to-end overlay for a new "add 2FA" spec
+
+The CLI invocation above produces this overlay tree (rendered HTML omitted for brevity):
+
+```
+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
+```
+
+Running `apltk architecture diff` then pairs `register/2fa.html` (added) and `register/api.html` + `register/index.html` + `index.html` (modified) with their base counterparts.

package/init-project-html/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: init-project-html
+description: >-
+  Declare the project HTML architecture atlas through `apltk architecture` CLI verbs instead of hand-writing SVG/HTML. The tool owns layout, no-overlap, DOM, CSS, and pan/zoom; the agent only declares features, sub-modules, functions, variables, dataflow steps, errors, and edges. Macro `index.html` always shows feature clusters with their sub-modules and every cross/intra-feature edge; each sub-module page describes only itself (function I/O + variables-with-business-purpose + internal dataflow + local errors); feature index pages stay lightweight. Read strategy avoids context loss: list feature modules first, then either dispatch one read-only subagent per feature and aggregate summaries before declaring, or process one feature at a time end-to-end. Anchor every declaration to repo evidence.
+---
+
+# Init Project HTML
+
+## Dependencies
+
+- Required: none (the CLI ships its own layout engine, CSS, and pan/zoom client; `apltk architecture` is installed with this toolkit).
+- Conditional: `spec-to-project-html` when the same atlas needs spec-driven refresh — that skill uses the same CLI with `--spec`.
+- Optional: `align-project-documents` when `docs/features` already names the user-visible capabilities.
+- Fallback: codebase too large for one pass → use the subagent strategy below, document scanned roots and explicit omissions in `meta.summary`. **MUST NOT** declare components for code paths that were never read.
+
+## Non-negotiables
+
+### Rule 1 — Use the CLI; never hand-author atlas HTML
+
+The atlas state lives in `resources/project-architecture/atlas/` (`atlas.index.yaml` + per-feature YAMLs). Every change goes through `apltk architecture <verb> ...`. After any mutation, the CLI re-renders `resources/project-architecture/**/*.html` with the correct layout, CSS, pan/zoom, and ARIA — agents **MUST NOT** edit those HTML files by hand or invent additional ones.
+
+### Rule 2 — Sub-module pages describe only themselves
+
+What the CLI emits on each sub-module page is fixed:
+
+- function I/O table (`function add --feature X --submodule Y --name fn --in ... --out ... --side ... --purpose ...`),
+- variables-with-business-purpose table (`variable add --name v --type T --scope call|tx|persist|instance|loop --purpose ...`),
+- internal dataflow steps (`dataflow add --step "..."`),
+- local errors (`error add --name ErrX --when ... --means ...`).
+
+Cross-boundary narratives ("I call X", "Y calls me") **MUST** be expressed as macro edges (`edge add --from X/sub --to Y/sub --kind call|return|data-row|failure --label ...`), never as sub-module page prose. The CLI enforces this by design — there is no verb to add cross-boundary text to a sub-module page.
+
+### 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 declaring pushes early details out by the end, making macro edges and sub-module declarations contradict each other. **MUST** follow one of:
+
+- **With subagents (preferred):** first enumerate the **feature-module list** (slug + entry + boundary resources only). Then dispatch **one read-only subagent per feature**. Each subagent deep-reads and returns ONLY a structured summary (sub-module list with kind/role; per sub-module: function I/O, variables-with-business-purpose, internal dataflow steps, errors; outbound edges to other features). The main agent collects every summary first, then drives the CLI in one pass to declare every component.
+- **Without subagents:** process features **one at a time** — read feature A end-to-end, then declare it via the CLI (`feature add`, `submodule add`, `function add`, `variable add`, `dataflow add`, `error add`, intra-feature `edge add`). For cross-feature edges that point at not-yet-declared features, declare the placeholder feature with `feature add --slug <future> --title <future>` first, then add the edge; subsequent passes set the real title/story. Drop A's function-level details from working memory before reading feature B.
+
+Both paths share one invariant: at any moment the main agent only holds *current-feature details + cross-feature boundary notes*. Run `apltk architecture validate` after the last feature to catch dangling edges, unknown endpoints, or missing required fields.
+
+### Rule 4 — Evidence over invention
+
+- **MUST** anchor every declared feature, sub-module, function, variable, dataflow step, and edge to a concrete path / symbol / SQL / config; record scanned roots and any deliberate omissions in `meta.summary` via `apltk architecture meta set --summary "..."`.
+- **MUST NOT** invent modules, integrations, or sub-modules just because the diagram "looks balanced". Empty rows are valid; lies are not.
+
+## Standards (summary)
+
+- **Evidence**: every CLI declaration traces to a path/symbol/SQL/config; uncertain areas surface as `TBD` strings or are omitted with a recorded reason.
+- **Execution**: feature-module list (shallow) → branch by environment (subagent fan-out or sequential read-declare) → `apltk architecture validate` → handover report.
+- **Quality**: macro SVG carries every cross-feature data-row edge that exists in the system; sub-module declarations are self-only; pan/zoom + Fit work in the rendered HTML; `apltk architecture validate` returns OK.
+- **Output**: `resources/project-architecture/atlas/` (YAML state) + `resources/project-architecture/**/*.html` (renderer output) — both managed by the CLI.
+
+## How to use `apltk architecture`
+
+Each verb is a single mutation; the CLI auto-renders after every change. Pass `--no-render` when batching mutations. Global flags: `--project <root>`, `--spec <spec_dir>` (writes to overlay; see `spec-to-project-html`), `--no-render`, `--no-open`.
+
+| Verb | Use it to… |
+| --- | --- |
+| `apltk architecture meta set --title ... --summary ...` | Set the macro title + atlas summary (read order, scanned roots, deliberate omissions). |
+| `apltk architecture actor add --id end-user --label "End user"` | Add a top-level actor (optional; appears in macro context). |
+| `apltk architecture feature add --slug <kebab> --title "..." --story "..." [--depends-on a,b]` | Declare a feature module (user-visible capability). |
+| `apltk architecture submodule add --feature <slug> --slug <kebab> --kind ui\|api\|service\|db\|pure-fn\|queue\|external --role "..."` | Declare a sub-module under a feature. |
+| `apltk architecture function add --feature X --submodule Y --name fn --in "T1, T2" --out "R \| ErrX" --side pure\|io\|write\|tx\|lock\|network --purpose "..."` | Add a function I/O row. |
+| `apltk architecture variable add --feature X --submodule Y --name v --type T --scope call\|tx\|persist\|instance\|loop --purpose "..."` | Add a variable-with-business-purpose row. |
+| `apltk architecture dataflow add --feature X --submodule Y --step "..." [--at N]` | Append (or insert at index `N`) an internal dataflow step. |
+| `apltk architecture dataflow reorder --feature X --submodule Y --from i --to j` | Move a step within the same sub-module. |
+| `apltk architecture error add --feature X --submodule Y --name ErrCode --when "..." --means "..."` | Add a local error row. |
+| `apltk architecture edge add --from <feature>[/sub] --to <feature>[/sub] --kind call\|return\|data-row\|failure --label "..." [--id <stable>]` | Add an edge. Intra-feature edges (both endpoints in the same feature with sub-modules) land in the feature YAML; cross-feature edges land in `atlas.index.yaml`. |
+| `apltk architecture feature\|submodule\|function\|variable\|error\|edge remove ...` | Remove a previously declared component. Removing a feature drops every sub-module and edge that referenced it. |
+| `apltk architecture feature\|submodule set ...` | Update fields (e.g. retitle a feature, change a sub-module's role) without re-adding. |
+| `apltk architecture render` | Force-regenerate HTML from current YAML state (useful after editing YAML directly, though hand-editing is discouraged). |
+| `apltk architecture validate` | Schema + referential integrity check; fails on dangling edges, unknown enums, duplicate slugs. |
+| `apltk architecture undo` | Revert the most recent mutation (single-level snapshot). |
+| `apltk architecture open` | Open the rendered macro `index.html` in a browser. |
+| `apltk architecture diff` | Render the paginated before/after viewer for every active spec under `docs/plans/**/architecture_diff/`. |
+
+## 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. Record only kebab-case slug + one-line user story + boundary points (entry symbol, outbound DB tables / queue topics / external services).
+
+- **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; one-line role).
+> - Per sub-module: function signatures (in / out / side / purpose), variables-with-business-purpose, internal dataflow steps, errors raised.
+> - **Outbound boundaries**: call edges to other features' sub-modules; data-row edges through shared DB tables / topics / cache keys with another feature; mark direction.
+
+Main agent collects every summary, then drives the CLI in one pass:
+
+```bash
+apltk architecture meta set --title "..." --summary "..." --no-render
+apltk architecture feature add --slug <slug> --title "..." --story "..." --no-render
+# repeat submodule / function / variable / dataflow / error / edge add for the whole atlas
+apltk architecture render
+apltk architecture validate
+```
+
+#### 2B) Without subagents — feature-by-feature read-declare 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:
+
+1. **Deep-read** every sub-module of this feature.
+2. **Declare immediately** via the CLI (`feature add`, then `submodule add` × N, then `function`/`variable`/`dataflow`/`error` rows, then intra-feature `edge add`).
+3. **Cross-feature edges**: if the target feature has not been declared yet, declare a placeholder with `feature add --slug <future> --title <future>`, add the edge, then refine the placeholder on a later pass.
+4. **Drop function-level details from working memory** before moving to the next feature.
+
+After the last feature:
+
+- Refine any placeholder features that were used to carry cross-feature edges.
+- Run `apltk architecture validate` — must return OK.
+
+### 3) Handover report
+
+Report: feature count, sub-module count, macro edge counts (call / return / data-row / failure), uncovered paths + reasons, the read strategy actually used (2A or 2B), and the location of the rendered atlas (`resources/project-architecture/index.html`).
+
+## Sample hints
+
+- Multiple SQL paths on `service ↔ db` → call `edge add` once per SQL path so the macro shows them as separate edges.
+- Retry loops between `service ↔ generator(pure)` → call/return pair in the macro plus a dataflow step in the service describing the retry budget.
+- Cross-feature DB hand-off (A writes, B reads) → declare both sides' `INSERT_*` / `SELECT_*` functions on the `db` sub-module, then `edge add --kind data-row` from producer feature/submodule to consumer feature/submodule.
+- Third-party systems → declare as `--kind external` sub-modules; the trust boundary becomes visible because the renderer styles them differently.
+
+## References
+
+- `lib/atlas/schema.js` — single source of truth for component fields, enums, and validation. `references/TEMPLATE_SPEC.md` mirrors that schema as a quick-reference cheat sheet.
+- `lib/atlas/cli.js` — full verb dispatch (run `apltk architecture --help` for the live usage).
+- `init-project-html/sample-demo/` — end-to-end YAML + rendered HTML for two features.

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

@@ -0,0 +1,22 @@
+interface:
+  display_name: "init-project-html"
+  short_description: "Declare the project HTML architecture atlas through `apltk architecture` CLI verbs"
+  default_prompt: >-
+    Use $init-project-html. Its `SKILL.md` is the authoritative rulebook; `references/TEMPLATE_SPEC.md` is a component-schema cheat sheet.
+    NEVER hand-author files under `resources/project-architecture/**/*.html`. The atlas state lives in YAML under `resources/project-architecture/atlas/` and every mutation goes through `apltk architecture <verb> ...`; the CLI owns layout, no-overlap, DOM, CSS, ARIA, and pan/zoom.
+    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 with kind/role; per sub-module: function I/O, variables-with-business-purpose, internal dataflow steps, errors raised; outbound edges to other features). The main agent collects every summary first, then runs the CLI in one batched pass.
+    (2B, no subagents) process features ONE AT A TIME — deep-read feature A, IMMEDIATELY drive the CLI (`feature add`, `submodule add` x N, `function add` / `variable add` / `dataflow add` / `error add` rows, intra-feature `edge add`), drop A's function-level details from working memory, then move to feature B. For cross-feature edges pointing at a not-yet-declared feature, declare a placeholder with `feature add --slug <future> --title <future>` first and refine its title/story on a later pass.
+    CLI verbs to declare components (always kebab-case slugs; pass `--no-render` to batch then call `apltk architecture render` once at the end):
+    `apltk architecture meta set --title "..." --summary "..."`,
+    `apltk architecture actor add --id <kebab> --label "..."`,
+    `apltk architecture feature add --slug <kebab> --title "..." --story "..." [--depends-on a,b]`,
+    `apltk architecture submodule add --feature X --slug Y --kind ui|api|service|db|pure-fn|queue|external --role "..."`,
+    `apltk architecture function add --feature X --submodule Y --name fn --in "T1, T2" --out "R | ErrX" --side pure|io|write|tx|lock|network --purpose "..."`,
+    `apltk architecture variable add --feature X --submodule Y --name v --type T --scope call|tx|persist|instance|loop --purpose "..."`,
+    `apltk architecture dataflow add --feature X --submodule Y --step "..." [--at N]`,
+    `apltk architecture error add --feature X --submodule Y --name ErrCode --when "..." --means "..."`,
+    `apltk architecture edge add --from <feature>[/sub] --to <feature>[/sub] --kind call|return|data-row|failure --label "..." [--id <stable>]`.
+    Intra-feature edges (both endpoints in the same feature with sub-modules) land in the feature YAML; cross-feature edges land in `atlas.index.yaml`. After the last mutation run `apltk architecture validate` — must return OK; resolve every reported error before reporting completion.
+    Each sub-module page describes ONLY itself (`sub-io` function I/O + `sub-vars` variables-with-business-purpose + `sub-dataflow` internal flow + `sub-errors` local errors) — express any cross-boundary interaction as a macro edge, never as sub-module page prose. Anchor every declaration to a concrete path / symbol / SQL / config; mark TBD when evidence is missing; record scanned roots and deliberate omissions in `meta.summary`. Report which read strategy (2A or 2B) was actually used and the location of the rendered atlas (`resources/project-architecture/index.html`).

package/init-project-html/lib/atlas/assets/architecture.css

@@ -0,0 +1,140 @@
+/* architecture.css — styling for the declarative atlas. The CLI copies
+ * this file into <outDir>/assets/. Style hooks (class names) are owned
+ * by render.js so agents never need to touch HTML by hand. */
+
+:root {
+  color-scheme: light dark;
+  --bg: #0f172a;
+  --panel: #111827;
+  --panel-soft: #1f2937;
+  --text: #e5e7eb;
+  --muted: #9ca3af;
+  --border: #334155;
+  --accent: #38bdf8;
+  --kind-ui: #38bdf8;
+  --kind-api: #818cf8;
+  --kind-service: #34d399;
+  --kind-db: #fbbf24;
+  --kind-pure-fn: #cbd5e1;
+  --kind-queue: #a78bfa;
+  --kind-external: #fb7185;
+  --edge-call: #60a5fa;
+  --edge-return: #94a3b8;
+  --edge-data-row: #fbbf24;
+  --edge-failure: #fb7185;
+}
+
+* { box-sizing: border-box; }
+html, body { margin: 0; padding: 0; background: var(--bg); color: var(--text); font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; }
+
+a { color: var(--accent); text-decoration: none; }
+a:hover { text-decoration: underline; }
+
+h1, h2 { margin: 0 0 12px; font-weight: 600; letter-spacing: -0.01em; }
+h1 { font-size: 28px; }
+h2 { font-size: 18px; color: var(--muted); text-transform: uppercase; letter-spacing: 0.08em; font-size: 13px; }
+
+p { line-height: 1.55; color: var(--text); }
+
+/* ---- atlas (macro) ---- */
+.atlas-header { padding: 28px 40px 16px; border-bottom: 1px solid var(--border); background: var(--panel); }
+.atlas-summary { color: var(--muted); max-width: 80ch; margin: 8px 0 0; }
+
+.atlas-main { display: grid; grid-template-columns: minmax(0, 3fr) minmax(280px, 1fr); gap: 24px; padding: 24px 40px 48px; }
+
+.atlas-canvas { background: var(--panel); border: 1px solid var(--border); border-radius: 12px; padding: 16px; position: relative; }
+.atlas-canvas__toolbar { position: absolute; top: 16px; right: 16px; display: flex; gap: 4px; z-index: 2; }
+.atlas-canvas__toolbar button { background: var(--panel-soft); color: var(--text); border: 1px solid var(--border); padding: 4px 12px; border-radius: 6px; cursor: pointer; font-size: 13px; }
+.atlas-canvas__toolbar button:hover { border-color: var(--accent); color: var(--accent); }
+
+.atlas-canvas__viewport { width: 100%; max-height: 72vh; overflow: hidden; border-radius: 8px; background: #0b1220; }
+.atlas-canvas__viewport.is-grabbing { cursor: grabbing; }
+.atlas-canvas__viewport:not(.is-grabbing) { cursor: grab; }
+
+.atlas-svg { width: 100%; height: auto; max-height: 72vh; display: block; user-select: none; touch-action: none; }
+
+.atlas-legend { list-style: none; padding: 12px 4px 0; margin: 0; display: flex; gap: 18px; flex-wrap: wrap; font-size: 12px; color: var(--muted); }
+.atlas-legend li { display: inline-flex; align-items: center; gap: 6px; }
+.legend-swatch { display: inline-block; width: 18px; height: 4px; border-radius: 2px; }
+.legend-swatch--call { background: var(--edge-call); }
+.legend-swatch--return { background: var(--edge-return); }
+.legend-swatch--data-row { background: var(--edge-data-row); }
+.legend-swatch--failure { background: var(--edge-failure); }
+
+.atlas-index { background: var(--panel); border: 1px solid var(--border); border-radius: 12px; padding: 16px; max-height: 80vh; overflow: auto; }
+
+.atlas-submodule-index { list-style: none; padding: 0; margin: 0; display: flex; flex-direction: column; gap: 10px; }
+.atlas-submodule-index__item a { display: grid; grid-template-columns: minmax(0, 1fr) auto; align-items: center; gap: 4px 8px; padding: 8px 10px; background: var(--panel-soft); border: 1px solid var(--border); border-radius: 8px; color: inherit; }
+.atlas-submodule-index__item a:hover { border-color: var(--accent); }
+.atlas-submodule-index__feature { font-size: 11px; color: var(--muted); text-transform: uppercase; letter-spacing: 0.06em; grid-column: 1 / 3; }
+.atlas-submodule-index__sub { font-weight: 600; }
+.atlas-submodule-index__kind { font-size: 11px; padding: 1px 8px; border-radius: 999px; background: var(--panel); border: 1px solid var(--border); color: var(--muted); }
+.atlas-submodule-index__role { margin: 4px 10px 0; font-size: 12px; color: var(--muted); }
+
+/* ---- SVG macro ---- */
+.m-cluster__bg { fill: rgba(15, 23, 42, 0.55); stroke: var(--border); stroke-width: 1; }
+.m-cluster__title { font-family: ui-sans-serif, system-ui, sans-serif; font-size: 14px; fill: var(--text); font-weight: 600; letter-spacing: 0.04em; text-transform: uppercase; }
+.m-node rect { fill: var(--panel-soft); stroke: var(--border); stroke-width: 1; transition: stroke 120ms ease; }
+.m-node:hover rect { stroke: var(--accent); }
+.m-node__title { font-size: 13px; font-weight: 600; fill: var(--text); }
+.m-node__kind { font-size: 11px; fill: var(--muted); }
+.m-node__role { font-size: 11px; fill: var(--muted); }
+
+.m-node--ui rect { stroke: var(--kind-ui); }
+.m-node--api rect { stroke: var(--kind-api); }
+.m-node--service rect { stroke: var(--kind-service); }
+.m-node--db rect { stroke: var(--kind-db); }
+.m-node--pure-fn rect { stroke: var(--kind-pure-fn); }
+.m-node--queue rect { stroke: var(--kind-queue); }
+.m-node--external rect { stroke: var(--kind-external); }
+
+.m-edge path { stroke-width: 1.6; }
+.m-edge--call path { stroke: var(--edge-call); }
+.m-edge--return path { stroke: var(--edge-return); stroke-dasharray: 6 4; }
+.m-edge--data-row path { stroke: var(--edge-data-row); }
+.m-edge--failure path { stroke: var(--edge-failure); }
+
+.m-arrow path { fill: currentColor; }
+.m-arrow--call { color: var(--edge-call); }
+.m-arrow--return { color: var(--edge-return); }
+.m-arrow--data-row { color: var(--edge-data-row); }
+.m-arrow--failure { color: var(--edge-failure); }
+
+.m-edge__label { fill: var(--muted); font-size: 11px; }
+
+/* ---- feature page ---- */
+.feature-header, .submodule-header { padding: 24px 40px 12px; border-bottom: 1px solid var(--border); background: var(--panel); }
+.feature-breadcrumb, .submodule-breadcrumb { font-size: 13px; color: var(--muted); margin-bottom: 8px; }
+.feature-depends { font-size: 13px; color: var(--muted); margin: 8px 0 0; }
+.feature-main, .submodule-main { padding: 24px 40px 48px; display: flex; flex-direction: column; gap: 32px; }
+.feature-story p { max-width: 80ch; }
+
+.submodule-nav { list-style: none; padding: 0; margin: 0; display: grid; gap: 12px; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); }
+.submodule-card { background: var(--panel); border: 1px solid var(--border); border-radius: 10px; padding: 12px 14px; }
+.submodule-card__link { display: flex; align-items: center; justify-content: space-between; color: inherit; font-weight: 600; }
+.submodule-card__kind { font-size: 11px; padding: 2px 8px; border-radius: 999px; border: 1px solid var(--border); color: var(--muted); }
+.submodule-card__role { margin: 8px 0 0; font-size: 13px; color: var(--muted); }
+
+.feature-edges__list { list-style: none; padding: 0; margin: 0; display: flex; flex-direction: column; gap: 8px; }
+.feature-edges__item { display: grid; grid-template-columns: minmax(0, 1fr) auto minmax(0, 2fr); gap: 8px; padding: 8px 12px; background: var(--panel); border: 1px solid var(--border); border-radius: 8px; font-size: 13px; }
+.feature-edges__kind { font-size: 11px; color: var(--muted); text-transform: uppercase; letter-spacing: 0.06em; align-self: center; }
+.feature-edges__item--call { border-left: 4px solid var(--edge-call); }
+.feature-edges__item--return { border-left: 4px solid var(--edge-return); }
+.feature-edges__item--data-row { border-left: 4px solid var(--edge-data-row); }
+.feature-edges__item--failure { border-left: 4px solid var(--edge-failure); }
+
+/* ---- submodule page ---- */
+.submodule-kind { display: inline-block; font-size: 12px; padding: 2px 10px; border-radius: 999px; border: 1px solid var(--border); color: var(--muted); margin-left: 8px; vertical-align: middle; text-transform: uppercase; letter-spacing: 0.06em; }
+.submodule-role { color: var(--muted); margin: 8px 0 0; max-width: 80ch; }
+
+.sub-table { width: 100%; border-collapse: collapse; font-size: 13px; }
+.sub-table th, .sub-table td { padding: 8px 12px; border-bottom: 1px solid var(--border); text-align: left; vertical-align: top; }
+.sub-table th { font-size: 11px; color: var(--muted); text-transform: uppercase; letter-spacing: 0.06em; background: var(--panel); }
+
+.sub-section__empty { color: var(--muted); font-style: italic; font-size: 13px; }
+
+.sub-dataflow__svg { width: 100%; max-width: 480px; }
+.sub-dataflow__step rect { fill: var(--panel); stroke: var(--border); }
+.sub-dataflow__step text { fill: var(--text); font-size: 13px; }
+.sub-dataflow__arrow { stroke: var(--muted); stroke-width: 1.4; }
+.sub-dataflow__empty { color: var(--muted); font-style: italic; }