tt-a1i · Lagom-TA · Aug 31, 2026
diff --git a/PRODUCT.md b/PRODUCT.md
@@ -0,0 +1,56 @@
+# Product
+
+## Register
+
+product
+
+## Users
+
+Engineers using Simplify Codebase in a desktop coding-agent workflow. They need
+to locate accidental complexity, understand confirmed ownership and consumer
+paths, judge a proposed cut, and verify a completed structural change. They
+need a concise analysis entry point before they can interpret the visual; they
+do not need the full proof record duplicated inside it.
+
+## Product Purpose
+
+Turn a proved Simplify Codebase Finding into a direct visual investigation
+surface. Success means the user can see where the problem lives, what reaches
+it, what would disappear, and what survived, while the written proof record
+remains the authoritative detailed report.
+
+## Brand Personality
+
+Direct, evidential, technical. Preserve Archify's crafted engineering-diagram
+identity while making cleanup decisions feel purpose-built rather than added on.
+
+## Anti-references
+
+- explanatory card walls that repeat what the graph already shows;
+- generic SaaS dashboards and decorative metrics;
+- cleanup actions hidden behind general diagram controls;
+- an Archify clone that lacks Simplify Codebase semantics;
+- dense prose permanently occupying the investigation canvas.
+
+## Design Principles
+
+- Let the graph own topology and state; use concise text to orient and
+  interpret it.
+- Make Locate, Trace, Cut, and Decide the visible primary workflow.
+- Keep the Finding summary visible once, then reveal proof, consequence, and
+  uncertainty at the decision point.
+- Keep the graph dominant when evidence opens; decision text belongs beside
+  the graph instead of pushing it below the fold.
+- De-emphasize contextual semantics in readable gray instead of hiding them.
+- Load into a stable graph. Motion may explain an explicit stage change, but
+  never pulse or scan the report decoratively on entry.
+- Keep source loci and stable Finding IDs available throughout the investigation.
+- Make node selection unmistakable and preserve Archify's native focus links.
+- Never imply that authored reachability proves runtime impact or deletion safety.
+
+## Accessibility & Inclusion
+
+Preserve keyboard navigation, visible focus, reduced-motion behavior, and the
+existing Archify semantic labels. Never use color as the only signal for node
+role, cut state, confidence, or risk. The visualization is intentionally designed
+and accepted for desktop viewports only.
diff --git a/README.en.md b/README.en.md
@@ -34,6 +34,7 @@ Static analysis can surface leads, but it cannot prove a deletion safe by itself
 
 Every serious candidate receives a proof record covering:
 
+- the exact ownership boundary, symbol, file, and verified source range where available;
 - the maintenance burden it creates;
 - production, test, dynamic, and external consumers;
 - the complete cut, including candidate-owned members inside shared files;
@@ -71,6 +72,8 @@ git clone https://github.com/tt-a1i/simplify-codebase.git \
 
 Start a new task after installation so the Skill catalog refreshes. For other Agent environments that support `SKILL.md`, place the repository in that environment's Skill directory.
 
+The interactive Cleanup Map is bundled with this Skill; Archify does not need to be installed separately. It vendors a trimmed Architecture renderer and desktop interaction core, then adds cleanup-specific compilation and Survey/Change behavior. The renderer requires Node.js 18 or newer, has no npm package dependency, and produces HTML without external font requests.
+
 ## Use
 
 ### Audit a repository without editing it
@@ -97,32 +100,52 @@ Use $simplify-codebase to remove one high-confidence source of accidental comple
 Use $simplify-codebase to verify and integrate the simplification findings from this PR. Preserve evidence, not finding counts.
 ```
 
+### Add a visual companion
+
+```text
+Use $simplify-codebase to audit this repository. Keep the written proof records authoritative. When several confirmed components and consumers make a finding hard to locate, also deliver a Cleanup Map with deep links for each visualized Finding ID. Do not call authored graph reachability runtime impact.
+```
+
 ## What it returns
 
 A read-only survey returns coverage, ranked proof records, important counterexamples, unresolved questions, and the next fact needed for each uncertainty.
 
 A change task also returns the implemented cut, validation results by layer, remaining risk, an operation receipt, and an executable undo path. A narrow green check is never presented as complete runtime or user acceptance.
 
+When a finding crosses several components, states, or consumers, the Skill can use its bundled renderer to deliver a validated desktop interactive HTML artifact. Survey follows Locate, Trace, Cut, and Decide; Change follows Before, Cut, After, and Verify. The map remains a visual companion to the proof record, never a substitute for consumer evidence, the Change operation receipt, or the undo path. When topology remains unresolved or a map adds no explanatory value, the result falls back to the complete text report with exact source locations.
+
 ## Repository layout
 
 ```text
 .
 ├── SKILL.md                    # Core workflow and decision rules
+├── PRODUCT.md                  # Visualization product and disclosure principles
 ├── agents/openai.yaml          # Agent-facing metadata
 ├── references/
 │   ├── investigation.md        # Broad investigation and discovery
 │   ├── boundaries-and-lifecycle.md
 │   ├── execution-and-recovery.md
 │   ├── decision-records.md
-│   └── integrating-findings.md
+│   ├── integrating-findings.md
+│   └── visual-reporting.md     # Truth and delivery contract for optional visuals
+├── visualization/
+│   ├── cleanup-map.schema.json # Cleanup-specific semantic contract
+│   ├── render-cleanup-map.mjs  # Cleanup Map to Archify Architecture compiler
+│   ├── archify-core/           # Vendored Architecture renderer and desktop viewer
+│   ├── cleanup-extension.*     # Survey and Change interaction extension
+│   ├── examples/               # Survey and Change inputs
+│   └── test/                   # Contract, route, and artifact tests
 ├── docs/validation.md          # Behavioral validation evidence
+├── docs/visual-report-example.md
 └── assets/hero.png             # Original hero artwork
 ```
 
 ## Quality and boundaries
 
 This version has been exercised in Change, Broad, Integration, and Decision-record scenarios, including a full survey of a 973-file Python + TypeScript project. See [docs/validation.md](./docs/validation.md) for the method and known limits.
 
+The visual companion directly vendors Archify's Architecture renderer, Signal Flow visual system, and desktop viewer runtime, then adds Findings, Survey/Change stages, cut boundaries, and an on-demand evidence drawer. The default surface first uses a concise analysis finding to orient the user, then discloses source, route, and decision evidence with the active stage while the graph keeps the primary visual space. Other general diagram renderers, the repository CLI, publishing, and gallery flows are not included. Attribution, adaptation notes, and the MIT license are preserved under [`visualization/`](./visualization/). See [docs/visual-report-example.md](./docs/visual-report-example.md) for the handoff format.
+
 The Skill does not replace product judgment. Removing a reachable capability, supported interface, persisted representation, or compatibility path still requires explicit user authority.
 
 ## Contributing

diff --git a/README.md b/README.md
@@ -34,6 +34,7 @@
 
 每个候选都要形成一份证明记录：
 
+- 它位于哪个所有权边界、符号、文件，以及能够验证时的行号；
 - 它增加了什么维护负担；
 - 生产、测试、动态和外部消费者分别是谁；
 - 完整删除边界在哪里，包括共享文件内部的成员；
@@ -69,6 +70,8 @@ git clone https://github.com/tt-a1i/simplify-codebase.git \
 
 安装后请新建一个任务，让 Skill 目录重新加载。其他支持 `SKILL.md` 的 Agent 环境可将本仓库放入各自的 Skill 目录。
 
+可交互 Cleanup Map 已内置在本 Skill 中，不需要另外安装 Archify。它直接内置精简后的 Architecture 渲染与桌面交互核心，再叠加清理专用编译和 Survey/Change 交互。renderer 需要 Node.js 18 或更高版本，不依赖额外 npm 包；交付的 HTML 不会请求外部字体。
+
 ## 使用
 
 ### 审计整个仓库，不改文件
@@ -95,32 +98,52 @@ git clone https://github.com/tt-a1i/simplify-codebase.git \
 使用 $simplify-codebase 复核并整合这个 PR 中的简化建议。保留证据，不保留候选数量。
 ```
 
+### 生成可视化伴随报告
+
+```text
+使用 $simplify-codebase 审计这个仓库。文字证明记录作为权威结果；如果多个已确认组件和消费者让问题位置难以理解，再额外交付带 Finding 深链接的 Cleanup Map。不要把图上可达关系称为运行时影响范围。
+```
+
 ## 输出是什么样的
 
 只读审计会交付覆盖范围、排序后的证明记录、重要反例、未决问题和下一条所需证据。
 
 修改任务会额外交付实际变更、分层验证结果、剩余风险、操作回执与可执行的撤销路径。一次小范围测试通过，不会被包装成完整的运行时或用户验收。
 
+当问题横跨多个组件、状态或消费者时，Skill 可以使用内置 renderer 额外交付经过校验的桌面端交互 HTML。Survey 按“定位、路径、删除边界、判断”组织，Change 按“变更前、删除边界、变更后、验证”组织。它是 proof record 的视觉伴随物，不替代消费者证明、Change 操作回执或撤销路径。拓扑尚未证明或图没有额外解释价值时，会正常退化为带精确文件定位的文字报告。
+
 ## 仓库结构
 
 ```text
 .
 ├── SKILL.md                    # 主工作流与判断标准
+├── PRODUCT.md                  # 可视化产品定位与渐进披露原则
 ├── agents/openai.yaml          # Agent 展示与调用元数据
 ├── references/
 │   ├── investigation.md        # 全库调查与候选发现
 │   ├── boundaries-and-lifecycle.md
 │   ├── execution-and-recovery.md
 │   ├── decision-records.md
-│   └── integrating-findings.md
+│   ├── integrating-findings.md
+│   └── visual-reporting.md     # 可选视觉伴随层的真实性与交付契约
+├── visualization/
+│   ├── cleanup-map.schema.json # 清理专用语义契约
+│   ├── render-cleanup-map.mjs  # Cleanup Map → Archify Architecture 编译与交付
+│   ├── archify-core/           # 内置的 Architecture renderer 与桌面 viewer 核心
+│   ├── cleanup-extension.*     # Survey / Change 专用交互与视觉扩展
+│   ├── examples/               # Survey 与 Change 输入示例
+│   └── test/                   # 契约、路径与产物测试
 ├── docs/validation.md          # 行为验证与质量证据
+├── docs/visual-report-example.md
 └── assets/hero.png             # 原创 Hero 视觉
 ```
 
 ## 质量与边界
 
 这个版本经过 Change、Broad、Integration 和 Decision-record 场景验证，也在一个 973 文件的 Python + TypeScript 项目上完成过全库审计。测试方法与已知边界记录在 [docs/validation.md](./docs/validation.md)。
 
+视觉伴随层直接内置 Archify 的 Architecture renderer、Signal Flow 视觉系统和桌面 viewer 运行时，并在其上增加 Finding、Survey/Change 阶段、删除边界和按需证据抽屉。默认界面先用一两句话说清问题，再让源码、路径和决策证据随阶段展开；图始终占据主要视觉空间。其他通用图种、仓库 CLI、发布与图库流程没有搬入。来源、修改边界和 MIT 许可保留在 [`visualization/`](./visualization/)；报告格式示例见 [docs/visual-report-example.md](./docs/visual-report-example.md)。
+
 Skill 不能替代产品决策。删除仍然可达的能力、已支持接口、持久化表示或兼容路径时，仍需由使用者明确授权。
 
 ## 贡献

diff --git a/SKILL.md b/SKILL.md
@@ -45,7 +45,10 @@ Use repository-native search, compiler and linter output, dependency metadata, a
 For every in-scope lead that reaches consumer-map evidence or could retire a meaningful contract, record:
 
 ```text
+Finding ID: a stable report-local identifier such as S1 or S2
 Candidate: the exact contract, representation, or layer to remove or merge
+Locus: the ownership boundary, symbols, and exact paths or lines when verified
+Topology: confirmed node and relationship IDs, primary locus, related nodes, route, and cut set when useful; otherwise not applicable
 Burden: the concepts, synchronization, publication, or testing cost it creates
 Reachability: production, non-production, dynamic, external, and persisted consumers
 Rationale: why it exists and whether that reason remains current
@@ -56,6 +59,8 @@ Proof: the smallest check that would expose an incorrect cut
 Net effect: maintenance concepts removed minus replacement or migration machinery added
 ```
 
+Keep Finding IDs stable within the run so the summary, proof record, source links, and any visual companion refer to the same candidate. Do not invent a line number, owner, relationship, or route to fill the location fields. Mark unknown facts as unresolved.
+
 Prove cut boundaries below file granularity when the candidate shares an artifact with surviving consumers. Account for candidate-exclusive selectors, members, fields, keys, registry entries, generated fragments, and fixtures without disturbing the surviving owners.
 
 Keep or downgrade the candidate when a real consumer exists, dynamic reachability remains unresolved, a current decision still owns the design, the change merely relocates complexity, the result is outside scope or retires no meaningful obligation, or the available check cannot distinguish success from accidental breakage.
@@ -74,8 +79,17 @@ If the user requests a simplification proposal, local cleanup annotation, or des
 
 If the user asks to combine findings from another branch, pull request, task, or agent run, read [integrating-findings.md](references/integrating-findings.md). Preserve evidence, not finding counts.
 
+When the user requests a visual report, or when several confirmed components and relationships make a candidate's locus materially clearer, read [visual-reporting.md](references/visual-reporting.md). Use the bundled cleanup-map renderer rather than requiring a general diagram Skill. Treat the map as an optional companion to the proof records, not as evidence by itself. Do not write Survey artifacts into the target repository unless the user requested repository files.
+
 ## Deliver the result
 
-For a survey, report coverage, ranked proof records, rejected or unresolved high-value leads, and the next fact needed for each uncertainty.
+For a survey, report coverage, ranked proof records, rejected or unresolved high-value leads, and the next fact needed for each uncertainty. When a visual companion was requested or justified, report its status and cleanup-map Finding deep links separately.
+
+Keep the handoff scan-friendly. Lead with the result, then include only the
+proof records, decision-relevant uncertainty, visual links, and validation that
+the user needs. Do not narrate the search process, repeat the same evidence
+under several labels, append generic advice, or keep empty sections. Concision
+does not remove required proof fields: write each field once, in the shortest
+form that preserves its subject, evidence strength, consequence, and boundary.
 
-For a change, complete the validation and operation receipt defined in [execution-and-recovery.md](references/execution-and-recovery.md). Report each validation layer separately; a narrow green check does not establish broader runtime, deployment, or user acceptance.
+For a change, complete the validation and operation receipt defined in [execution-and-recovery.md](references/execution-and-recovery.md). A Before/Cut/After/Verify cleanup map may explain a structural change, but it never replaces the operation receipt. Report each validation layer separately; a narrow green check does not establish broader runtime, deployment, or user acceptance.
diff --git a/docs/validation.md b/docs/validation.md
@@ -30,18 +30,29 @@ This document records the behavioral validation completed before the initial ope
 - Expected behavior: prove the cut below file granularity.
 - Result: the focused audit found 14 candidate-exclusive CSS classes, identified removable members inside mixed selectors, retained the shared stylesheet and surviving component, and found two stale documentation references.
 
+### Cleanup Map renderer
+
+- Fixture: one Survey and one Change cleanup-map document covering a confirmed dispatch path and an adapter cut.
+- Expected behavior: reject guessed or dangling topology, unsafe links, and inconsistent Change snapshots; keep Finding IDs stable; trace only confirmed directed relationships; render distinct Survey and Change stages; progressively disclose stage-specific information without duplicate cards; keep first-paint and post-probe page geometry stable; and produce a portable standalone HTML artifact.
+- Result: all 13 renderer tests passed on Node.js 18.20.8 and 26.7.0; both fixtures passed the dependency-free cleanup-map contract validator; and the checked-in Draft 2020-12 schema's authored surface is covered by a parity test. Both delivered artifacts passed all 7 structural checks. The suite also rejects overlong or duplicate unknowns, control-character URL obfuscation, unsafe URL schemes, incomplete or type-wrong cuts, route/cut semantics outside a Finding, retained cuts, dangling snapshot edges, and multi-Finding Change receipts. The vendored Archify clean-flow gate accepted node spacing, relationship-label placement, and the Change bypass route. Browser review passed at 1280×800 and 1440×900 in light and dark themes with no page-level overflow or console warnings/errors; repeated first-load, stage, evidence, focus, zoom, and rapid-switch sampling kept `scrollY`, document height, and the panel/workspace coordinates stable. Cut snapshot isolation, deep links, role labels, shortcut isolation, truth-boundary visibility, and small-text contrast were also checked directly.
+
 ## Mechanical checks / 机械检查
 
 - Skill structure and frontmatter validation;
 - YAML metadata validation;
 - internal Markdown link validation;
 - Markdown lint with line-length enforcement disabled for prose and long commands;
 - upstream-name and attribution scan;
-- clean-worktree checks for read-only scenarios.
+- clean-worktree checks for read-only scenarios;
+- cleanup-map schema-parity, referential-integrity, Change-snapshot, link-scheme, shortest-path, script-injection, and offline portable-artifact tests;
+- standalone artifact checks for the Archify runtime, one semantic SVG, cleanup workbench, passport, route probe, and truth boundary;
 
 ## Known limits / 已知边界
 
 - These tests establish behavior for the exercised scenarios, not every language, build system, or Agent runtime.
 - Dynamic consumers outside the inspected repository can remain unknowable without external evidence.
 - Deployment, production health, and end-user acceptance remain separate gates from repository tests.
 - A user must still authorize product or compatibility changes.
+- The bundled Cleanup Map is desktop-only. It is intentionally bounded to five visualized Findings, 18 nodes, and 32 confirmed relationships per artifact.
+- The renderer's structural checks do not replace visual review, repository evidence, runtime verification, or the canonical text proof records.
+- Cleanup Map vendors Archify's Architecture renderer and desktop viewer core. Other diagram renderers, the generic repository CLI, publishing, gallery, and multi-diagram validator are outside this distribution.