@laitszkin/apollo-toolkit 4.0.11 → 4.1.1

package/scripts/test.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Split test runner — isolates mock.module tests from the rest to avoid
+# a Node.js 24.x test runner IPC deserialization issue that can make
+# tests flaky when --experimental-test-module-mocks is active globally.
+# See: https://github.com/nodejs/node/issues (test_runner IPC clone)
+
+EXIT=0
+
+run_test_group() {
+  local label="$1"
+  shift
+  echo ""
+  echo "==> $label"
+  if "$@"; then
+    echo "    PASS"
+  else
+    echo "    FAIL"
+    EXIT=1
+  fi
+}
+
+# Group 1: stable non-mock tests (test/)
+run_test_group "Stable tests (test/)" \
+  node --test 'test/**/*.test.js'
+
+# Group 2: package .test.js files that do NOT need mock.module
+EXCLUDE='(cmd-init|cmd-list-apis|cmd-survey)'
+PACKAGE_TEST_FILES=$(find packages -name '*.test.js' -not -path '*/node_modules/*' | grep -v -E "$EXCLUDE" | sort | tr '\n' ' ')
+run_test_group "Package tests (no mock.module)" \
+  node --test $PACKAGE_TEST_FILES
+
+# Group 3: mock-dependent tests — isolated with --experimental-test-module-mocks
+run_test_group "Package tests (mock.module)" \
+  node --experimental-test-module-mocks --test \
+    'packages/tools/codegraph/dist/lib/cmd-init.test.js' \
+    'packages/tools/codegraph/dist/lib/cmd-list-apis.test.js' \
+    'packages/tools/codegraph/dist/lib/cmd-survey.test.js'
+
+exit $EXIT

package/skills/design/SKILL.md

@@ -167,6 +167,10 @@ Each component should link to:
 
 #### 5e. Generate the Diff and Validate
 
+Two alternative workflows — use the **Classic flow** when `codegraph` is not installed, or the **CodeGraph-integrated flow** when it is available.
+
+**Classic flow** (manual):
+
 ```bash
 apltk architecture --spec <spec_dir> render
 apltk architecture --spec <spec_dir> validate
@@ -178,6 +182,35 @@ Confirm validation passes, then use the diff command to produce a visual compari
 apltk architecture diff
 ```
 
+**New flow (CodeGraph-integrated):**
+
+1. **Survey the existing API landscape**:
+   ```bash
+   apltk codegraph list-apis --all
+   ```
+   This returns the full project API directory (function names, file paths, callers) as a reference for integration points. Use this data to understand what existing modules, services, and functions your new feature will interact with.
+
+2. **Fill the proposal skeleton**: Based on your design decisions from steps 5a-5d,
+   fill in the `proposal.yaml` file generated by `apltk architecture template`.
+   Define the feature, its submodules, their functions, and cross-feature edges.
+
+3. **Apply batch mutations**:
+   ```bash
+   apltk architecture apply <spec_dir>/architecture_diff/atlas/proposal.yaml --spec <spec_dir>
+   ```
+   This processes all mutations in one call with undo protection.
+
+4. **Verify correctness**:
+   ```bash
+   apltk codegraph verify --spec <spec_dir>
+   ```
+   This confirms every symbol and edge reference in the spec overlay exists in the actual code.
+
+5. **Render and validate** (optional, for visual confirmation):
+   ```bash
+   apltk architecture diff --spec <spec_dir>
+   ```
+
 **Single spec**: Produce one Architecture Diff for one SPEC.md.
 **Batch spec**: Produce **one** unified Architecture Diff covering all SPEC.md files in the batch.
 

package/skills/init-project-html/SKILL.md

@@ -1,31 +1,30 @@
 ---
 name: init-project-html
-description: 為項目初始化架構圖。透過 apltk CLI 將功能模塊與子模塊的關係轉化為可渲染的 HTML 架構圖，採用 C4 模型層級（Context → Container → Component → Code）。
+description: Initialize the project architecture atlas. Use the apltk CLI to map feature and submodule relationships into a renderable HTML architecture diagram following the C4 model (Context → Container → Component → Code).
 ---
 
-## 技能目標
+## Goal
 
-透過 `apltk` CLI 製作項目架構圖。
-幫助用戶理解專案的軟體架構。
+Produce a project architecture diagram via the `apltk` CLI.
+Help users understand the project's software architecture.
 
-## 驗收條件
+## Acceptance Criteria
 
-- 所有子模塊之間的 edge 被完整定義
-- 所有子模塊內部的 edge 被完整定義
-- 架構圖完整展示整個系統之中子模塊之間的關係以及功能模塊之間的關係
-- 每個宣告的 component 皆附有來源程式碼證據；無法確定的標記為 inferred
-- 架構圖層級對應 C4 model：功能模塊（Container 層級）→ 子模塊（Component 層級）
+- The diagram covers all four C4 levels: System Context → Container (feature) → Component (submodule) → Code (function row)
+- All cross-module and intra-module edges are fully defined
+- Every declared component is backed by source code evidence (`evidence.sourceFile:sourceLine`); unresolved ones are tagged `inferred`
+- Every submodule must declare its `functions` and `variables` arrays (mandatory, may not be left empty)
 
-## C4 模型對照
+## C4 Mapping
 
-本技能的「功能模塊」與「子模塊」對應到 C4 model 的以下層級：
+This skill's "feature" and "submodule" map to the C4 model as follows:
 
-| C4 層級 | 本技能對應 | 說明 | 使用時機 |
-|---------|-----------|------|---------|
-| System Context | 整體系統 | 系統與外部 actor、外部系統的關係 | 步驟 1 建立基線認知 |
-| Container | 功能模塊 | 高階功能邊界（如登入功能、支付功能） | 主要抽象層級 |
-| Component | 子模塊 | 功能內部的實作單元（如 controller、service、repository） | 主要詳細層級 |
-| Code | function 行 | 函式層級細節 | 只在特定關鍵路徑需要 |
+| C4 Level | Skill Equivalent | Description | When to Use |
+|----------|-----------------|-------------|-------------|
+| System Context | Whole system | System boundaries, external actors, and external systems | Step 1 — establish baseline awareness |
+| Container | Feature | High-level functional boundary (e.g. Login, Payment) | Primary abstraction level |
+| Component | Submodule | Implementation unit inside a feature (controller, service, repository) | Primary detail level |
+| Code | Function row | Function-level detail with source file and line evidence | Mandatory — every submodule must declare its functions with `evidence.sourceFile:sourceLine` |
 
 ## Mode Detection
 
@@ -48,58 +47,69 @@ At load time, check the project state to select the correct mode:
   directory already exists and is non-empty, pause and ask the user whether to:
   (a) overwrite the existing atlas, (b) switch to update mode, or (c) abort.
 
-## 工作流程
+## Workflow
 
-適用模式：design（完整初始化）、record（快速記錄）
+Applicable modes: design (full initialization), record (quick recording)
 
-### 1. 閱讀並理解代碼庫 — 先建立 System Context
+### 1. Survey the project with `apltk codegraph survey`
 
-在深入程式碼前，先建立系統的宏觀認知：
-- 系統與哪些外部 actor 互動（使用者、第三方服務、其他系統）
-- 系統提供哪些高階能力
+Before diving into the code, establish a high-level understanding:
+- Which external actors interact with the system (users, third-party services, other systems)
+- What high-level capabilities the system provides
 
-然後閱讀 `sample-demo/` 了解預期的輸出格式與抽象層級。
+Then read `sample-demo/` to understand the expected output format and abstraction level.
 
-按照功能模塊定義，全面檢索代碼庫。
-將其拆分為單個或多個功能模塊（對應 C4 Container 層級）。
-接著，識別功能模塊下的子模塊（對應 C4 Component 層級），並進行深度閱讀。
+Next, run `apltk codegraph survey` to get a structured survey report:
+- List of all files in the project directory with function counts
+- Entry points (public functions called from external files)
+- Suggested submodule groupings and cross-boundary edges
+- Supports `--json` output for programmatic consumption by the LLM
 
-並行調度 subagents，並為每一個功能模塊分配一個 subagent 進行深度閱讀，要求 subagents 完整列出：
-- 該功能模塊與其他功能模塊之間是否存在交互；如有，如何交互。
-- 該功能模塊內部存在哪些子模塊，這些子模塊之間如何交互並實現功能模塊的功能。
-- 該功能模塊及下屬子模塊的資料流、錯誤處理。
+Based on the survey report, decide how to partition features (C4 Container level):
+- Group closely interconnected function clusters into the same feature's submodules
+- Identify feature boundaries and cross-feature call relationships
+- Record the directory path and entry points for each feature
 
-> 每個 subagent 回報的每個宣告都應附上對應的程式碼檔案路徑與行號，作為證據追溯的基礎。
+### 2. Write the atlas with `apltk architecture apply`
 
-### 2. 使用 `apltk` cli 工具協助生成架構圖
+Generate the atlas incrementally by C4 level:
+Consult `references/architecture.md` for CLI flag details when needed (parameter reference, mutation series).
 
-依照 C4 層級逐步產生：
-在操作 CLI 前先閱讀 `references/architecture.md` 了解所有參數與 mutation 系列的使用方式。
+1. **System Context**: Define external actors, system boundaries, and cross-system edges
+2. **Container level**: Define features and their inter-feature edges
+3. **Component level**: Define submodules with their internal elements (function, variable, dataflow, error)
+4. **Code level**: Declare `functions` and `variables` for every submodule, attaching `evidence` (source file and line number via `--evidence observed:path/file.ts:42`)
 
-1. **System Context**：定義外部 actor、系統邊界、跨系統 edge
-2. **Container 層級**：定義功能模塊（feature）及其之間的 edge
-3. **Component 層級**：定義子模塊（submodule）及其內部元素（function、variable、dataflow、error）
-4. **Code 層級**（選擇性）：對關鍵路徑補充函式層級細節
+Use `apltk architecture apply <proposal.yaml>` for batch atlas writes (replaces manual per-mutation CLI calls).
+Transform the codebase knowledge gathered in the previous step into a clear architecture diagram.
+After completion, verify the atlas format is valid and renders correctly.
 
-將前一步獲取的代碼庫知識透過 CLI 工具轉化為清晰的架構圖。
-完成後驗證架構圖格式正確且可渲染。
+### 3. Self-review
 
-## 證據追溯
+Confirm the following before finishing:
 
-每個透過 CLI 宣告的 component 應附上對應的來源證據：
+- [ ] All four C4 levels are populated (Context → Container → Component → Code)
+- [ ] Every submodule has at least one function declared with source evidence
+- [ ] All cross-feature and intra-feature edges are defined
+- [ ] Evidence level is correctly set (`observed` for source-confirmed, `inferred` otherwise)
+- [ ] Atlas passes `apltk architecture validate`
 
-- 功能模塊（feature）→ 對應的目錄路徑或 entry point 檔案
-- 子模塊（submodule）→ 實作該模組的檔案列表
-- function 行 → 函式定義的檔案與行號
-- edge → 觸發該呼叫關係的程式碼位置
+## Evidence Traceability
 
-若因時間或上下文限制無法完整追溯，在 `meta.summary` 中記錄已掃描範圍與已知遺漏。
+Every component declared via the CLI must carry source evidence:
 
-## 參考資料
+- Feature → corresponding directory path or entry point file
+- Submodule → list of files implementing the module
+- Function row → source file and line number (`evidence.sourceFile` + `evidence.sourceLine`)
+- Edge → code location triggering the call relationship
 
-- `references/architecture.md` — apltk architecture 工具的完整參數說明。在步驟 2 產生架構圖前閱讀。
-- `references/TEMPLATE_SPEC.md`：atlas 欄位、列舉和 CLI 寫入形狀速查表。
-- `references/definition.md`: 功能模塊和子模塊的詳細定義。
-- `assets/architecture-page.template.html`: 模板 html。
-- `references/architecture.css`: 風格模板。
-- `sample-demo/`：完整示例輸出，用於理解基礎 atlas 的最終形態與 C4 層級對應。
+If time or context constraints prevent full traceability, record the scanned scope and known gaps in `meta.summary`.
+
+## References
+
+- `references/architecture.md` — Full parameter reference for the apltk architecture tool (consult when CLI flag details are needed).
+- `references/TEMPLATE_SPEC.md` — Atlas field reference, enum values, and CLI shape cheat sheet.
+- `references/definition.md` — Detailed definitions of feature and submodule.
+- `assets/architecture-page.template.html` — HTML template.
+- `references/architecture.css` — Style template.
+- `sample-demo/` — Complete example output for understanding the final atlas shape and C4 level mapping.

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

@@ -759,7 +759,8 @@ p { line-height: 1.6; color: var(--vellum-soft); }
 /* =================================================================
    evidence badges
    ================================================================= */
-.evi { display: inline-block; padding: 0 6px; border-radius: 3px; font-size: 11px; font-weight: 600; line-height: 18px; cursor: help; }
+.evi { display: inline-block; padding: 0 6px; border-radius: 3px; font-size: 11px; font-weight: 600; line-height: 18px; cursor: help; white-space: nowrap; }
+.evi__source { font-size: 10px; font-weight: 400; margin-left: 4px; padding: 1px 5px; border-radius: 3px; background: rgba(0,0,0,0.15); color: inherit; }
 .evi--observed { background: #d4edda; color: #155724; border: 1px solid #c3e6cb; }
 .evi--inferred { background: #fff3cd; color: #856404; border: 1px solid #ffeeba; }
 .evi--assumed { background: #f8d7da; color: #721c24; border: 1px solid #f5c6cb; }

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

@@ -309,7 +309,17 @@ function renderEvidenceBadge(ev) {
   const label = EVI_LABEL[ev.level] || ev.level;
   const title = ev.source ? htmlEscape(ev.source) : '';
   const titleAttr = title ? ` title="${title}"` : '';
-  return `<span class="evi evi--${ev.level}"${titleAttr}>${label}</span>`;
+
+  // Append source location when structured file:line data is available
+  let locHtml = '';
+  if (ev.sourceFile && ev.sourceFile !== ev.source && /[/\\]|\.[a-zA-Z0-9]+$/.test(ev.sourceFile)) {
+    const loc = ev.sourceLine
+      ? `${htmlEscape(ev.sourceFile)}:${ev.sourceLine}`
+      : htmlEscape(ev.sourceFile);
+    locHtml = ` <code class="evi__source">${loc}</code>`;
+  }
+
+  return `<span class="evi evi--${ev.level}"${titleAttr}>${label}${locHtml}</span>`;
 }
 
 function renderSubmoduleTable(headers, rows, evidences) {

package/skills/init-project-html/lib/atlas/schema.js

@@ -69,17 +69,54 @@ function parseEvidence(value) {
   const str = String(value);
   const colon = str.indexOf(':');
   let level, source;
+
   if (colon === -1) {
-    level = 'inferred';
-    source = str;
+    if (EVIDENCE_LEVELS.includes(str)) {
+      level = str;
+      source = '';
+    } else {
+      level = 'inferred';
+      source = str;
+    }
   } else {
-    level = str.slice(0, colon);
-    source = str.slice(colon + 1);
-    if (!EVIDENCE_LEVELS.includes(level)) {
-      throw new Error(`Invalid evidence level: "${level}". Must be one of: ${EVIDENCE_LEVELS.join(', ')}`);
+    const candidateLevel = str.slice(0, colon);
+    if (EVIDENCE_LEVELS.includes(candidateLevel)) {
+      level = candidateLevel;
+      source = str.slice(colon + 1);
+    } else {
+      level = 'inferred';
+      source = str;
+    }
+  }
+
+  // Extract structured sourceFile & sourceLine from the source string.
+  // Heuristic: source ends with ":<number>" and the part before the last
+  // colon resembles a file path (contains '/' or '.'), so parse it as
+  // "path/to/file.ext:lineNumber".
+  let sourceFile = null;
+  let sourceLine = null;
+  if (source) {
+    const lastColon = source.lastIndexOf(':');
+    if (lastColon !== -1) {
+      const afterColon = source.slice(lastColon + 1).trim();
+      const lineNum = parseInt(afterColon, 10);
+      const filePart = source.slice(0, lastColon);
+      if (
+        !isNaN(lineNum) && lineNum > 0 &&
+        String(lineNum) === afterColon &&
+        (/[/\\]/.test(filePart) || /\.[a-zA-Z0-9]+$/.test(filePart))
+      ) {
+        sourceFile = filePart;
+        sourceLine = lineNum;
+      } else {
+        sourceFile = source;
+      }
+    } else {
+      sourceFile = source;
     }
   }
-  return { level, source };
+
+  return { level, source, sourceFile, sourceLine };
 }
 
 function noFix(message) {

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

@@ -129,6 +129,26 @@ CLI: `apltk architecture error add --feature X --submodule Y --name ErrCode --wh
 
 CLI: `apltk architecture edge add --from <feature>[/sub] --to <feature>[/sub] --kind call --label "..."`
 
+### `evidence` (shared, optional on every entity above)
+
+| Field      | Type | Required | Notes |
+| ---------- | ---- | -------- | ----- |
+| level      | enum `observed` `inferred` `assumed` | yes | Quality tier — drives badge colour (green/amber/red). |
+| source     | string | no | Free-text evidence description. |
+| sourceFile | string | no | Extracted file path (e.g. `src/auth/controller.ts`). Auto-parsed from `--evidence observed:path/file.ts:42`. |
+| sourceLine | number | no | Extracted line number. Auto-parsed from `--evidence observed:path/file.ts:42`. |
+
+CLI: `--evidence observed:path/to/file.ts:42` (line number parsed automatically when source ends with `:N` and the preceding segment resembles a file path).
+
+In YAML:
+```yaml
+evidence:
+  level: observed
+  sourceFile: src/auth/controller.ts
+  sourceLine: 42
+  source: src/auth/controller.ts:42
+```
+
 ## Class hooks on rendered HTML
 
 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.

package/skills/init-project-html/references/architecture.md

@@ -1,40 +1,40 @@
-# apltk architecture — 宣告式架構圖 CLI
+# apltk architecture — Declarative Architecture Diagram CLI
 
-## 用途
-透過 YAML 狀態檔案管理 `resources/project-architecture/` 下的架構圖，支援基礎架構圖與 spec 覆蓋層的差異比對與合併。
+## Purpose
+Manage architecture diagrams under `resources/project-architecture/` via YAML state files. Supports base atlas and spec overlay diff/merge comparison.
 
-## 用法
+## Usage
 ```
 apltk architecture [verb] [options]
 ```
 
-## 全局旗標
-| 旗標 | 效果 |
-|------|------|
-| `--project <root>` | 指定專案根目錄（預設從 cwd 向上搜尋） |
-| `--spec <spec_dir>` | 寫入 spec overlay 而非基礎架構圖 |
-| `--no-render` | 變更後略過自動重新渲染，可批次多條指令 |
-| `--no-open` | `open` 和 `diff` 時不開啟瀏覽器 |
-| `--dry-run` | 預覽變更為 JSON diff，不實際寫入 |
-| `--out <dir>` | `diff` 的輸出目錄 |
-| `--clean` | `merge` 成功後移除 spec overlay 目錄 |
-| `--all` | `merge` 時選取所有 pending spec overlay |
-| `--json` | `status` 時輸出 JSON |
-| `--evidence <level[:source]>` | 為組件標記 observed/inferred/assumed 品質等級 |
-
-## 頂層動詞
-- **`open`** — 開啟基礎架構圖 HTML，若未渲染則先 bootstrap
-- **`diff`** — 收集 `docs/plans/` 下所有 overlay，產生 before/after 檢視器
-- **`render`** — 從當前 YAML 狀態重新產生 HTML
-- **`validate`** — 驗證架構圖結構完整性（schema + referential integrity）
-- **`status`** — 顯示摘要（feature/submodule/edge/actor 數量、時間戳、驗證狀態）
-- **`scan --src <dir>`** — 掃描目錄結構，輸出 JSON 候選 feature 列表
-- **`undo [--steps <n>]`** — 還原最近一次 mutation
-- **`merge --spec <dir> | --all`** — 將 spec overlay 合併回基礎架構圖
-
-## Mutation 系列
-
-所有 mutation 共用 `--project`、`--spec`、`--no-render`、`--dry-run`、`--evidence` 旗標。
+## Global Flags
+| Flag | Effect |
+|------|--------|
+| `--project <root>` | Specify project root (defaults to upward search from cwd) |
+| `--spec <spec_dir>` | Write to spec overlay instead of base atlas |
+| `--no-render` | Skip auto-render after mutations for batch operations |
+| `--no-open` | Skip browser launch for `open` and `diff` |
+| `--dry-run` | Preview changes as JSON diff without writing |
+| `--out <dir>` | Output directory for `diff` |
+| `--clean` | Remove spec overlay directory after successful `merge` |
+| `--all` | Select all pending spec overlays for `merge` |
+| `--json` | JSON output for `status` |
+| `--evidence <level[:source]>` | Mark component quality tier (observed/inferred/assumed); source supports auto-parsed `file:line` (e.g. `observed:src/foo.ts:42`) |
+
+## Top-Level Verbs
+- **`open`** — Open base atlas HTML in browser; bootstrap if not rendered
+- **`diff`** — Collect all overlays under `docs/plans/`, generate before/after viewer
+- **`render`** — Regenerate HTML from current YAML state
+- **`validate`** — Validate atlas structural integrity (schema + referential integrity)
+- **`status`** — Show summary (feature/submodule/edge/actor counts, timestamp, validation status)
+- **`scan --src <dir>`** — Scan directory structure, output JSON candidate feature list
+- **`undo [--steps <n>]`** — Revert the most recent mutation(s)
+- **`merge --spec <dir> | --all`** — Merge spec overlay(s) into base atlas
+
+## Mutation Series
+
+All mutations share `--project`, `--spec`, `--no-render`, `--dry-run`, `--evidence` flags.
 
 ### feature
 ```
@@ -92,7 +92,7 @@ apltk architecture actor add --id <actor-id> [--label "..."]
 apltk architecture actor remove --id <actor-id>
 ```
 
-## 注意事項
-- 執行 mutation 後自動重新渲染（除非 `--no-render`）
-- 每個 mutation 建立 undo snapshot，可行 `undo` 還原
-- 驗證通過後才算架構圖工作完成
+## Notes
+- Auto-render after every mutation (unless `--no-render`)
+- Each mutation creates an undo snapshot — revert with `undo`
+- Atlas work is not complete until validation passes

package/skills/init-project-html/references/definition.md

@@ -1,25 +1,20 @@
-## 功能模塊
+## Feature
 
-功能模塊是直接面向用戶的功能，如：
-- 登陸功能
-- 註冊功能
-- 邀請碼功能
+A feature is a user-facing capability, such as:
+- Login
+- Registration
+- Invite code management
 
-功能模塊由子模塊的合作、交互實現
+Features are realized through collaboration and interaction of their submodules.
 
-功能模塊對應 C4 model 的 **Container** 層級：高階功能邊界，可獨立部署或辨識的系統能力單元。
+A feature maps to the C4 model's **Container** level: a high-level functional boundary, deployable or identifiable as a distinct system capability unit.
 
-## 子模塊
+## Submodule
 
-子模塊是功能模塊的關鍵組成部分。具體定義依照代碼的實作邊界得出。
+A submodule is a key building block of a feature. Its exact definition follows the implementation boundaries in the code.
 
-子模塊對應 C4 model 的 **Component** 層級：功能內部的實作單元（如 controller、service、repository）。
+A submodule maps to the C4 model's **Component** level: an implementation unit inside a feature (e.g., controller, service, repository).
 
-## C4 模型層級對照
+## C4 Level Mapping
 
-| C4 層級 | 對應概念 | 用途 |
-|---------|---------|------|
-| System Context | 整體系統 + 外部 actor | 定義系統邊界與外部依賴 |
-| Container | 功能模塊（feature） | 高階功能邊界 |
-| Component | 子模塊（submodule） | 功能內部的實作單元 |
-| Code | function 行 | 函式層級細節（選擇性） |
+Refer to the C4 mapping table in `SKILL.md` — it is not duplicated here.

package/skills/update-project-html/README.md

@@ -1,42 +1,31 @@
 # update-project-html
 
-`update-project-html` refreshes the project HTML architecture atlas (`resources/project-architecture/`) so it reflects the latest code changes.
-
-## What this skill does
-
-1. Reads the current atlas (`atlas.index.yaml` + per-feature YAML) — only affected features (context economy).
-2. Measures architecture drift: compares atlas entries against actual codebase structure.
-3. Resolves the diff scope (`git diff --stat` + `git diff --cached --stat` by default, or `git diff --stat <base>..HEAD` when the user names a ref).
-4. Filters out non-architecture changes (formatting, config-only, test-only, comments).
-5. Maps filtered diff hunks to existing or new features.
-6. Dispatches one write-capable subagent per affected feature to deep-read only its own changed files and apply every intra-feature mutation through `apltk architecture` (no `--spec`).
-7. Waits until every subagent finishes, then declares cross-feature edges, runs `apltk architecture render`, and validates.
-8. Re-measures drift to confirm it is within acceptable range.
+Refreshes the project HTML architecture atlas (`resources/project-architecture/`) to reflect the latest code changes.
 
 ## When to use
 
-Use this skill when the task asks you to:
-
-- update or refresh the existing project architecture diagram after code changes,
-- bring `resources/project-architecture/` back in sync with the current branch or a specific commit range,
-- reflect a recent PR or batch of commits in the canonical atlas before merging or releasing.
+- The existing atlas is out of sync with the current branch or working tree
+- Code has changed (new routes, modules, service logic) and the atlas needs updating before a release
+- You need to bring `resources/project-architecture/` back in sync after a PR or batch of commits
 
-If no atlas exists yet, use `init-project-html` to bootstrap one. For planned but unshipped work scoped to a `docs/plans/...` spec, use `spec-to-project-html` to write under `<spec_dir>/architecture_diff/` instead of the base atlas.
+If no atlas exists yet, use [`init-project-html`](../init-project-html/SKILL.md) to bootstrap one first.
 
 ## Core principles
 
-- The CLI owns atlas state and renderer output; agents never hand-edit `resources/project-architecture/**/*.html`.
-- Every mutation traces to a specific file + diff hunk; absent code never produces atlas entries.
-- Subagent fan-out is the only safe read pattern: one feature per subagent, no shared source loading.
-- Cross-feature wiring happens **after** every subagent finishes — never from partial summaries.
-- Measure drift before and after: confirm the atlas stays within an acceptable drift threshold.
-- Filter diff noise: formatting, config-only, test-only, and comment-only changes never drive atlas mutations.
+- The CLI owns atlas state and rendered output; never hand-edit `resources/project-architecture/**/*.html`
+- Every mutation traces to a specific file + diff hunk; absent code never produces atlas entries
+- Measure drift **before and after**: confirm the atlas stays within acceptable thresholds
+- Filter diff noise: formatting, config-only, test-only, and comment-only changes never drive atlas mutations
+
+## Workflow
+
+See [`SKILL.md`](./SKILL.md) for the full 6-step workflow.
 
 ## References
 
-- [`SKILL.md`](./SKILL.md) — full workflow and execution rules.
-- [`../init-project-html/SKILL.md`](../init-project-html/SKILL.md) — semantic rulebook.
-- [`../spec-to-project-html/SKILL.md`](../spec-to-project-html/SKILL.md) — spec overlay flow.
+- [`SKILL.md`](./SKILL.md) — Full workflow and execution rules
+- [`../init-project-html/SKILL.md`](../init-project-html/SKILL.md) — C4 semantic rulebook
+- [`../init-project-html/references/TEMPLATE_SPEC.md`](../init-project-html/references/TEMPLATE_SPEC.md) — Atlas field reference and schema
 
 ## License