@laitszkin/apollo-toolkit 4.1.0 → 4.1.1

package/packages/tools/codegraph/index.ts

@@ -19,13 +19,21 @@ export async function codegraphHandler(args: string[], context: ToolContext): Pr
   const isJson = jsonIndex >= 0;
   if (jsonIndex >= 0) args.splice(jsonIndex, 1);
 
-  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+  // Main help: no args, --help, -h, or "help" subcommand
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
     printHelp(stdout);
     return 0;
   }
 
   const subcommand = args[0];
+
+  // Per-subcommand help: e.g., "apltk codegraph search --help"
+  // Check for --help/-h at position 1 (after the subcommand name)
   const rest = args.slice(1);
+  if (rest.includes('--help') || rest.includes('-h')) {
+    printSubcommandHelp(subcommand, stdout, stderr);
+    return 0;
+  }
 
   // Parse --spec <dir> for verify
   const specIndex = rest.indexOf('--spec');
@@ -129,42 +137,223 @@ export async function codegraphHandler(args: string[], context: ToolContext): Pr
 function printHelp(stream: NodeJS.WriteStream): void {
   stream.write(`Usage: apltk codegraph <subcommand> [options]
 
+CodeGraph code intelligence — parse source code into a knowledge graph
+of symbols (functions, classes) and relationships (call edges), backed by
+a local SQLite database with FTS5 full-text search.
+
+Powered by @colbymchenry/codegraph (tree-sitter-backed code knowledge graph).
+
 Subcommands:
 
   lifecycle:
     init               Initialize CodeGraph for the project
-                       --index    Run initial indexing after init
+                       --index    Run initial indexing immediately after init
+                       --json     JSON output
 
     sync               Sync the index with current file state
+                       --json     JSON output
 
-    status             Show index statistics (files, nodes, edges)
+    status             Show index statistics (files, nodes, edges, languages)
+                       --json     JSON output
 
   discovery:
-    search <query>     Search the code graph for symbols
-                       --limit N  Max results (default: 20)
-
-    explore <query>    Deep-dive on a symbol (callers, callees, source)
+    search <query>     Search the code graph for symbols via FTS5
+                       --limit N  Max results (default: 20, max: 100)
                        --json     JSON output
 
-    survey [dir]       Scan a directory and suggest submodule groupings
-                       --feature <name>  Feature context
+    explore <query>    Deep-dive on a symbol — show callers, callees, and source
+                       --feature <name>  Only show results within this feature
+                       --json            JSON output
+
+    survey [dir]       Scan a directory, suggest submodule groupings and
+                       cross-boundary edges for atlas modelling
+                       --feature <name>  Feature context for grouping
                        --json            JSON output
 
-    list-apis [path]   List public APIs in the project or a sub-path
-                       --all      Include non-exported symbols
+    list-apis [path]   List public APIs in the project or within a sub-path
+                       --all      Include non-exported (internal) symbols
                        --json     JSON output
 
   validation:
-    verify             Verify a spec overlay against the actual code
-                       --spec <dir>  Spec directory (required)
-                       --json        JSON output
+    verify --spec <dir>
+                       Verify a spec overlay against actual code —
+                       checks that every declared feature, submodule,
+                       function, and edge exists in the code graph
+                       --json     JSON output
 
 Global options:
     --json             Output as JSON instead of human-readable format
-    --help             Show this help message
+    --help, -h         Show this help message
+
+Use "apltk codegraph <subcommand> --help" for per-subcommand details.
+
+Examples:
+  apltk codegraph init
+  apltk codegraph init --index
+  apltk codegraph status --json
+  apltk codegraph search getUser
+  apltk codegraph search getUser --limit 5 --json
+  apltk codegraph explore handleLogin
+  apltk codegraph survey src/
+  apltk codegraph survey src/ --feature auth --json
+  apltk codegraph list-apis --all
+  apltk codegraph verify --spec docs/plans/2026-05-11/add-2fa
 `);
 }
 
+function printSubcommandHelp(subcommand: string, stream: NodeJS.WriteStream, errStream: NodeJS.WriteStream): void {
+  const PAD = '  ';
+
+  const helps: Record<string, string> = {
+    init: `Usage: apltk codegraph init [--index] [--json]
+
+Initialize the CodeGraph knowledge graph for the project.
+Creates the .codegraph/ directory and SQLite database.
+
+Flags:
+  --index    Run initial indexing immediately after init, so the
+             knowledge graph is ready for queries right away.
+             Without this flag, you need to run "apltk codegraph sync"
+             separately before searching or exploring.
+  --json     Output confirmation as JSON.
+
+Examples:
+  apltk codegraph init
+  apltk codegraph init --index
+`,
+    sync: `Usage: apltk codegraph sync [--json]
+
+Sync the code graph index with the current state of files on disk.
+Parses changed files and updates the SQLite database.
+
+This is needed after you modify source files if you want queries
+to reflect the latest code. Runs incrementally — only reprocesses
+files whose mtime has changed.
+
+Flags:
+  --json     Output sync results (files added/removed/updated) as JSON.
+
+Examples:
+  apltk codegraph sync
+  apltk codegraph sync --json
+`,
+    status: `Usage: apltk codegraph status [--json]
+
+Show index statistics: file count, symbol (node) count, edge count,
+languages detected, and last-sync timestamp.
+
+Flags:
+  --json     Output full statistics as a JSON object.
+
+Examples:
+  apltk codegraph status
+  apltk codegraph status --json
+`,
+    search: `Usage: apltk codegraph search <query> [--limit N] [--json]
+
+Full-text search the code graph for symbols (functions, classes, variables).
+Uses FTS5 (SQLite full-text search) under the hood.
+
+Arguments:
+  query      Search term (required). Matches against symbol names and
+             source code content.
+
+Flags:
+  --limit N  Max results to return (default: 20, max: 100).
+  --json     Output results as a JSON array.
+
+Examples:
+  apltk codegraph search getUser
+  apltk codegraph search handleLogin --limit 5
+  apltk codegraph search "class.*Handler" --limit 10 --json
+`,
+    explore: `Usage: apltk codegraph explore <query> [--feature <name>] [--json]
+
+Deep-dive on a symbol — shows who calls it, what it calls, and its
+full source code. Useful for understanding how a function or class
+fits into the broader codebase.
+
+Arguments:
+  query      Symbol name to explore (required).
+
+Flags:
+  --feature <name>
+             Scope results to only show callers/callees within a
+             specific feature directory (e.g. "auth", "billing").
+  --json     Output full exploration data as JSON (callers, callees,
+             source code, file path, line numbers).
+
+Examples:
+  apltk codegraph explore handleLogin
+  apltk codegraph explore authenticate --feature auth
+  apltk codegraph explore sendEmail --json
+`,
+    survey: `Usage: apltk codegraph survey [dir] [--feature <name>] [--json]
+
+Scan a directory and produce a structured survey report with suggested
+submodule groupings, cross-boundary edges, and entry points.
+
+This is the primary input for the "init-project-html" skill's Step 1 —
+it tells the LLM how to model features and submodules for the atlas.
+
+Arguments:
+  dir        Directory to scan (default: current directory ".").
+
+Flags:
+  --feature <name>
+             Feature context: scope the survey to only one feature's
+             boundary. Helps the grouper cluster symbols more accurately.
+  --json     Output survey results as JSON — best for LLM consumption.
+
+Examples:
+  apltk codegraph survey
+  apltk codegraph survey src/
+  apltk codegraph survey src/auth --feature auth --json
+`,
+    'list-apis': `Usage: apltk codegraph list-apis [path] [--all] [--json]
+
+List public (exported) symbols in the project or a specific sub-path.
+Useful for understanding the public surface area of a module.
+
+Arguments:
+  path       Sub-path to scan (e.g. "src/auth"). When omitted, scans
+             the entire project.
+
+Flags:
+  --all      Include non-exported (internal) symbols in the listing.
+  --json     Output API list as JSON.
+
+Examples:
+  apltk codegraph list-apis
+  apltk codegraph list-apis src/auth
+  apltk codegraph list-apis --all --json
+`,
+    verify: `Usage: apltk codegraph verify --spec <spec-dir> [--json]
+
+Verify a spec overlay's architecture proposals against actual code.
+Checks that every feature, submodule, function, and edge referenced
+in the overlay's atlas state actually exists in the code graph.
+
+Flags:
+  --spec <spec-dir>
+             Path to the spec directory containing an architecture_diff/
+             overlay (required). For example, "docs/plans/2026-05-11/add-2fa".
+  --json     Output verification results as JSON (passed/failed checks).
+
+Examples:
+  apltk codegraph verify --spec docs/plans/2026-05-11/add-2fa
+  apltk codegraph verify --spec docs/plans/2026-05-11/add-2fa --json
+`,
+  };
+
+  const text = helps[subcommand];
+  if (text) {
+    stream.write(text);
+  } else {
+    errStream.write(`Unknown subcommand: "${subcommand}". Use "apltk codegraph --help" for the list of available subcommands.\n`);
+  }
+}
+
 export const tool: ToolDefinition = {
   name: 'codegraph',
   category: 'Code analysis',

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/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,59 +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. 使用 codegraph survey 取得專案結構
+### 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.
 
-接著使用 `apltk codegraph survey` 取得專案的結構化調查報告：
-- 專案目錄下的所有檔案清單與函式數量
-- Entry points（被外部檔案呼叫的公開函式）
-- 建議的 submodule 分組與跨邊界 edge
-- 支援 `--json` 輸出供 LLM 程式化消費
+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
 
-根據 survey 報告，決定功能模塊的劃分（對應 C4 Container 層級）：
-- 將高度互相呼叫的函式群歸類為同一功能模塊的子模塊
-- 識別功能模塊之間的邊界與跨模塊呼叫關係
-- 記錄每個功能模塊對應的目錄路徑與 entry point
+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
 
-### 2. 使用 `apltk architecture apply` 批次寫入 atlas
+### 2. Write the atlas with `apltk architecture apply`
 
-依照 C4 層級逐步產生：
-在操作 CLI 前先閱讀 `references/architecture.md` 了解所有參數與 mutation 系列的使用方式。
+Generate the atlas incrementally by C4 level:
+Consult `references/architecture.md` for CLI flag details when needed (parameter reference, mutation series).
 
-1. **System Context**：定義外部 actor、系統邊界、跨系統 edge
-2. **Container 層級**：定義功能模塊（feature）及其之間的 edge
-3. **Component 層級**：定義子模塊（submodule）及其內部元素（function、variable、dataflow、error）
-4. **Code 層級**（選擇性）：對關鍵路徑補充函式層級細節
+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`)
 
-使用 `apltk architecture apply <proposal.yaml>` 進行批次 atlas 寫入（取代逐一手動 mutation）。
-將前一步獲取的代碼庫知識透過 CLI 工具轉化為清晰的架構圖。
-完成後驗證架構圖格式正確且可渲染。
+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.
 
-## 證據追溯
+### 3. Self-review
 
-每個透過 CLI 宣告的 component 應附上對應的來源證據：
+Confirm the following before finishing:
 
-- 功能模塊（feature）→ 對應的目錄路徑或 entry point 檔案
-- 子模塊（submodule）→ 實作該模組的檔案列表
-- function 行 → 函式定義的檔案與行號
-- edge → 觸發該呼叫關係的程式碼位置
+- [ ] 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`
 
-若因時間或上下文限制無法完整追溯，在 `meta.summary` 中記錄已掃描範圍與已知遺漏。
+## Evidence Traceability
 
-## 參考資料
+Every component declared via the CLI must carry source evidence:
 
-- `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 層級對應。
+- 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
+
+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.