@laitszkin/apollo-toolkit 4.1.0 → 4.1.1

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
 

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

@@ -1,70 +1,83 @@
 ---
 name: update-project-html
-description: 當項目架構圖與實際程式碼脫節時，增量刷新架構圖資源。包括基礎 atlas 與渲染 HTML。更新前先測量 drift 程度決定更新範圍。
+description: Incrementally refresh the architecture atlas when the project diagram drifts from actual code. Measures drift before updating to determine scope, then updates the base atlas and re-renders HTML.
 ---
 
-## 目標
+## Goal
 
-根據目前分支、工作區或指定提交範圍內的程式碼變更，增量刷新基礎 atlas 與渲染 HTML。
-使架構圖持續和實際程式碼保持一致。
+Incrementally refresh the base atlas and rendered HTML based on code changes in the current branch, working tree, or a specified commit range.
+Keep the architecture diagram continuously aligned with the actual codebase.
 
-## 驗收條件
+## Acceptance Criteria
 
-- 所有子模塊之間的 edge 的定義被更新到貼合最新代碼實踐
-- 所有子模塊內部的 edge 的定義被更新到貼合最新代碼實踐
-- 架構圖完整展示整個系統之中子模塊之間的關係以及功能模塊之間的關係
-- 已測量架構圖與程式碼的 drift 程度，確認更新範圍合理
-- diff 中不影響架構的變更（formatting、config-only、test-only）已被過濾
+- Architecture drift has been measured before and after the update; the update scope is justified
+- All cross-module and intra-module edges reflect the latest code
+- Every declared component is backed by source code evidence (`evidence.sourceFile:sourceLine`); unresolved ones are tagged `inferred`
+- Non-architectural changes (formatting, config-only, test-only) have been filtered from the diff
 
-## 工作流程
+## Workflow
 
-### 1. 查看現有架構圖
+### 1. Review the current atlas
 
-閱讀現有架構圖。
-整理功能模塊之間、子模塊之間的關係等重要資訊。
+Read the existing architecture diagram.
+Capture the relationship between features and submodules.
 
-> 只讀取 `atlas.index.yaml` + 受影響 feature 的 YAML 檔案。不讀取無關的 feature 或未變更的模組，以維持 context economy。
+> Read only `atlas.index.yaml` + the YAML files of affected features. Do not read unrelated features or unchanged modules to preserve context economy.
 
-### 2. 測量架構 drift
+### 2. Measure architecture drift
 
-在決定更新範圍前，先比對架構圖與當前程式碼的偏離程度：
+Before deciding the update scope, compare the atlas against the current code:
 
-- 比較 `atlas.index.yaml` 與當前目錄結構：是否有新增 / 移除的目錄或模組？
-- 比較各 feature YAML 中的檔案路徑與實際程式碼：是否有檔案已不存在或搬移？
-- 量化 drift：新增 + 移除 + 修改的 entries 數量 / 總 entries 數量
+- Compare `atlas.index.yaml` with the current directory structure: are there added / removed directories or modules?
+- Compare file paths in each feature YAML against the actual codebase: are any files missing or moved?
+- Quantify drift: count of added + removed + modified entries / total entries
 
-根據 drift 程度決定更新策略：
-- **低 drift（< 20%）**：只更新受 diff 影響的 feature
-- **高 drift（≥ 20%）**：建議標記為重大偏離，通知用戶後考慮全面重新初始化（使用 `init-project-html`）
+Determine the update strategy based on drift severity:
+- **Low drift (< 20%)**: Update only the features affected by the diff
+- **High drift (≥ 20%)**: Flag as significant divergence, notify the user and recommend a full re-initialization via `init-project-html`
 
-### 3. 過濾 diff 噪聲
+### 3. Filter diff noise
 
-分析 diff 範圍，過濾不影響架構的變更類型：
-- **保留**：新增或修改的 API route、service 邏輯、資料庫操作、模組邊界變更
-- **過濾**：formatting 調整、config 值變更（非結構變更）、純測試檔案、型別定義調整（非邊界影響）、註解或文檔變更
+Analyze the diff scope and filter non-architectural changes:
 
-將過濾後的 diff hunk 對應到受影響的 feature。
+- **Keep**: New or modified API routes, service logic, database operations, module boundary changes
+- **Filter**: Formatting adjustments, config value changes (non-structural), test-only files, type definition adjustments (no boundary impact), comment or documentation changes
 
-### 4. 對照代碼庫及當前架構圖
+Map the filtered diff hunks to the affected features.
 
-並行調度 subagents 完成代碼與架構圖的對照任務，驗證架構圖是否存在錯誤或遺漏。
+### 4. Cross-reference code with the current atlas
 
-### 5. 通過 `apltk` cli 工具更新當前架構圖
+Dispatch subagents in parallel to cross-reference the code against the architecture diagram and verify whether the atlas has errors or omissions.
 
-使用 `apltk` cli 工具，按照以下流程完成架構圖的更新：
+### 5. Update the atlas via `apltk` CLI
 
-在操作前先閱讀 `references/architecture.md` 了解所有參數細節。
-1. 定義功能模塊及其下屬子模塊。
-2. 定義子模塊之間的關係、呼叫、錯誤處理、資料流、回滾等架構關係
-3. 定義子模塊內部的函數、變數、資料流及錯誤處理。
+Use `apltk architecture` commands to update the architecture diagram:
 
-當從 diff 推斷 component 時，使用 `--evidence inferred` 標記品質等級。例如：
+Consult `references/architecture.md` for CLI flag details (parameter reference, mutation series).
+
+1. Define features and their submodules.
+2. Define inter-submodule relationships: calls, error handling, data flow, rollback, and other architectural connections.
+3. Define intra-submodule functions, variables, data flows, and error handling.
+
+When inferring components from a diff hunk, use `--evidence inferred` with a `file:line` source. For example:
 ```
-apltk architecture function add --feature <slug> --submodule <slug> --name <fn> --evidence "inferred:<source-path>"
+apltk architecture function add --feature <slug> --submodule <slug> --name <fn> \
+  --evidence inferred:src/auth/controller.ts:42
 ```
 
-更新完成後再次測量 drift，確認已降低至可接受範圍。
+After completing the update, re-measure drift to confirm it has been reduced to an acceptable range.
+
+### 6. Self-review
+
+Confirm the following before finishing:
+
+- [ ] Drift is now within acceptable range (< 20%)
+- [ ] Filtered diff noise (formatting, config-only, test-only) did not drive any atlas mutations
+- [ ] Every new or modified component carries evidence (`observed` for source-confirmed, `inferred` otherwise)
+- [ ] All edges affected by changed code have been reviewed and updated
+- [ ] Atlas passes `apltk architecture validate`
 
-## 參考資料
+## References
 
-- `references/architecture.md` — apltk architecture 工具的完整參數說明。在步驟 5 更新架構圖前閱讀，了解 mutation 指令與 --evidence 旗標的行為。
+- `references/architecture.md` — Full parameter reference for the apltk architecture tool (consult when CLI flag details are needed).
+- `references/definition.md` — Detailed definitions of feature and submodule.

package/skills/update-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/update-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.