codeasier · Oct 31, 2026 · Oct 31, 2026 · Oct 31, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -32,6 +32,10 @@ follow the hierarchy rather than copying local rules into this file.
 
 ## Development and Checks
 
+This is the canonical contributor checklist linked from both READMEs. Keep new
+required checks here and in the owning CI workflow rather than maintaining a
+shorter, divergent checklist in user onboarding docs.
+
 Run from the repository root using the intended Python environment. Installing
 changes that environment and may download dependencies:
 

diff --git a/README.md b/README.md
@@ -4,89 +4,54 @@
 
 A command-line tool for analyzing PyTorch memory snapshots. Set a snapshot database, run built-in queries, and inspect memory usage, leaks, and timelines.
 
+## Start Here
+
+| Your input or goal | Next step |
+| --- | --- |
+| Existing `.db` or complete dataset | [Inspect → query → report](docs/en/quickstart.md#step-2-inspect-the-target-and-choose-a-device); no import required |
+| Trusted pickle | [Default single-DB import](docs/en/quickstart.md#step-1-import-only-if-needed) |
+| No snapshot yet | [Collection prerequisites and entry points](docs/en/quickstart.md#need-to-collect-a-snapshot) |
+| Ask an agent to analyze | [Install → restart → verify → ask](docs/en/skills.md#first-agent-session) |
+
 ## Installation
 
+Requires **Python 3.10+**. Offline import/analysis needs no PyTorch or accelerator;
+collection uses the workload's compatible GPU/NPU environment.
+
 ```bash
-pip install pt-snap-cli
+python -m pip install pt-snap-cli
 ```
 
 For a source checkout and contributor setup, see [Development](#development).
 
 ## Quick Start
 
-To start from a raw PyTorch memory snapshot, import the pickle into a SnapshotDB with pt-snap's built-in snapshot support, then list the available query templates:
-
-> **Security warning:** Import only pickle snapshots from a trusted source. Pickle
-> deserialization can execute arbitrary code. The loader rejects non-`builtins`
-> global objects, but `pt-snap import` is not a sandbox.
+If you already have a DB, skip import. Otherwise use only a **trusted** pickle:
+its deserialization can execute arbitrary code; the `builtins` restriction does
+not make `pt-snap import` a sandbox.
 
 ```bash
 pt-snap import snapshot.pkl
-pt-snap metadata snapshot.pkl.db
-pt-snap query --list
-```
-
-```bash
-# Set the snapshot database and device
-pt-snap focus snapshot.pkl.db --device 0
-
-# List available queries
-pt-snap query --list
-
-# Run a query (automatically uses the focused device)
-pt-snap query --template-use memory_peak
-
-# Detect potential memory leaks
-pt-snap query --template-use leak_detection --params '{"min_size": 1024}'
+pt-snap overview snapshot.pkl.db --json
+# Replace 0 with a device returned by overview.
+pt-snap query snapshot.pkl.db --device 0 --template-use memory_peak --json
+pt-snap report peak-memory snapshot.pkl.db --device 0 --metric active --limit 20
 ```
 
-To divide a large snapshot into independently replayable files before import,
-use exactly one split strategy and an output directory that does not exist:
+Default import writes `snapshot.pkl.db` beside the pickle and updates project
+`.pt-snap/focus.json` in the current directory. Add `--no-focus` to avoid that
+focus change, not to prevent DB replacement: a standalone cache miss/`--force`
+can replace an existing same-named DB; choose another `--output-dir` if needed.
+The explicit-path inspection/query/report commands do not persist
+focus or modify source data. The [walkthrough](docs/en/quickstart.md) explains
+byte units, allocated/active/reserved counters, expected output and partial reports.
 
-```bash
-pt-snap split snapshot.pkl --slices 4 --output snapshot-slices
-```
+### Other Input Formats
 
-See [Splitting Snapshots](docs/en/splitting.md) for device selection, JSON output,
-deterministic names, replay validation, and failure-safe publication.
-
-See the [full quick start guide](docs/en/quickstart.md) for a walkthrough.
-
-Complete compatibility-v1 sharded artifacts can be focused by directory or
-`manifest.json`, without the archived pickle. See [dataset focus and addressing](docs/en/sharded-snapshotdb.md#complete-dataset-focus-and-addressing-p1)
-for read-only overview, event routing, `--slice`, and explicit cross-slice limits.
-
-Opt into a **native, not msinsight-compatible** dataset with
-`pt-snap import snapshot.pkl --events-per-slice 50000 --output-dir captures --json`.
-The output is `captures/snapshot.pkl.pt-snap-native-v2/`; default standalone import
-is unchanged. Reuse validates all shards and content/options/semantic versions.
-Nonmatching recognized targets require `--force`; unknown targets are preserved.
-Publication/focus failures are compensated, with explicit recovery evidence if
-rollback fails (force is not a single crash-atomic swap). See the
-[native import guide](docs/en/quickstart.md#optional-import-a-native-sharded-dataset).
-Dataset `event` addressing and point-event `active_blocks_at_event` /
-`active_memory_callstack_at_event` share batched cross-shard alloc/free sources,
-including original artifacts without extensions. Built-in global peaks, event pages,
-canonical stack statistics, deduplicated lifecycles, terminal leak candidates and
-`report peak-memory` share bounded core semantics; custom SQL/overrides remain unsupported
-on datasets. See the [global support matrix](docs/en/querying.md#dataset-global-built-in-support-p3)
-and [dataset attribution and coverage](docs/en/querying.md#dataset-point-event-attribution).
-Lifecycle queries exceeding SQLite's attachment limit use a private, page-limited
-temporary derived database; source shards stay read-only. See the global support
-matrix for storage limits, cleanup and memory caveats.
-
-Explicit `pt-snap import snapshot.pkl --format msinsight --json` produces
-`snapshot.pkl.msinsight/` for the fixed msinsight revision's **same original
-pickle + adjacent cache** entrance. Inline stacks cost more space than native
-interning. Existing compatible targets are never replaced, even with `--force`;
-only fully validated identical pt-snap caches are reused. GUI acceptance remains
-**pending/not run**; hash equality alone is not acceptance. See
-[compatible export and limits](docs/en/sharded-snapshotdb.md#explicit-msinsight-compatible-export-p2).
-
-See [offline interoperability acceptance and bounded performance](docs/en/interop-acceptance.md)
-for the two fixed-version chains, deterministic reference tools, honest three-mode
-measurements and the explicitly **pending/not-run GUI checklist**. Diagnostic skills
-accept explicitly selected complete validated datasets, not arbitrary directories.
+- [Native sharded import](docs/en/quickstart.md#optional-import-a-native-sharded-dataset): opt in with `--events-per-slice`; not msinsight-compatible.
+- [Explicit msinsight export](docs/en/quickstart.md#optional-export-an-msinsight-compatible-dataset): separate compatibility and no-replace rules, even with `--force`.
+- [Replayable pickle splitting](docs/en/splitting.md): one split strategy and a new output directory; separate from dataset import.
+- [Complete-dataset addressing](docs/en/sharded-snapshotdb.md#complete-dataset-focus-and-addressing-p1), [global built-in support](docs/en/querying.md#dataset-global-built-in-support-p3), and [recorded interoperability acceptance](docs/en/interop-acceptance.md): advanced contracts and evidence, not prerequisites for a first report.
 
 ## Commands
 
@@ -155,12 +120,15 @@ See the [documentation index](docs/README.md) for all English and Chinese guides
 
 ## Development
 
+Use the repository's single [Development and Checks checklist](AGENTS.md#development-and-checks):
+fixture provenance, pytest, Ruff, Black, **basedpyright**, and `git diff --check`.
+It also explains environment isolation, browser tests and coverage gates.
+
 ```bash
-pip install -e ".[dev]"         # Install development dependencies
-pytest                           # Run all tests
-black --check . && ruff check .  # Check formatting and lint
+python -m pip install -e ".[dev]"
 ```
 
+
 For the regular suite use `pytest -m 'not slow'`. Default-capacity scale and
 non-editable installed exporter tests are described in the
 [dataset acceptance guide](docs/en/dataset-acceptance.md).

diff --git a/README_zh.md b/README_zh.md
@@ -4,76 +4,51 @@
 
 用于分析 PyTorch 内存快照的命令行工具。设置快照数据库，运行内置查询，检查内存使用、泄漏和时间线。
 
+## 从这里开始
+
+| 你的输入或目标 | 下一步 |
+| --- | --- |
+| 已有 `.db` 或完整数据集 | [检查 → 查询 → 报告](docs/zh/quickstart.md#第二步检查目标并选择设备)，无需导入 |
+| 可信 pickle | [默认单库导入](docs/zh/quickstart.md#第一步仅在需要时导入) |
+| 尚无快照 | [采集前提与入口](docs/zh/quickstart.md#尚需采集快照) |
+| 让 Agent 帮忙分析 | [安装 → 重启 → 验证 → 提问](docs/zh/skills.md#首次-agent-会话) |
+
 ## 安装
 
+需要 **Python 3.10+**。离线导入/分析无需 PyTorch 或加速器；采集则在工作负载对应的
+兼容 GPU/NPU 环境中进行。
+
 ```bash
-pip install pt-snap-cli
+python -m pip install pt-snap-cli
 ```
 
 源码 checkout 与贡献者安装见[开发](#开发)。
 
 ## 快速开始
 
-> **安全警告：** 只导入来自可信来源的 pickle 快照。反序列化 pickle 可能执行任意代码；
-> 实现会拒绝非 builtins 全局对象，但 `pt-snap import` 不是沙箱。
+已有 DB 就跳过导入；否则只使用**可信** pickle。反序列化可能执行任意代码，
+`builtins` 限制不代表 `pt-snap import` 是沙箱。
 
 ```bash
-# 从原始 pickle 导入；相同内容和配置会自动复用已有 DB
 pt-snap import snapshot.pkl
-pt-snap metadata snapshot.pkl.db
-
-# 设置快照数据库和设备
-pt-snap focus snapshot.pkl.db --device 0
-
-# 列出可用查询
-pt-snap query --list
-
-# 运行查询（自动使用 focus 中设置的设备）
-pt-snap query --template-use memory_peak
-
-# 检测潜在内存泄漏
-pt-snap query --template-use leak_detection --params '{"min_size": 1024}'
+pt-snap overview snapshot.pkl.db --json
+# 将 0 替换为 overview 实际返回的设备。
+pt-snap query snapshot.pkl.db --device 0 --template-use memory_peak --json
+pt-snap report peak-memory snapshot.pkl.db --device 0 --metric active --limit 20
 ```
 
-如需先把大型快照拆成可独立回放的文件，请只选择一种拆分策略，并指定一个尚不存在的
-输出目录：
+默认导入在 pickle 旁写出 `snapshot.pkl.db`，并更新当前目录的项目
+`.pt-snap/focus.json`；加 `--no-focus` 只避免 focus 变化，不防止 DB 替换：单库缓存
+未命中或 `--force` 可能替换同名 DB，必要时选择其他 `--output-dir`。显式路径的检查/查询/报告
+不持久化 focus，也不修改源数据。[完整示例](docs/zh/quickstart.md)解释字节单位、
+allocated/active/reserved 指标、预期输出和报告不完整的情况。
 
-```bash
-pt-snap split snapshot.pkl --slices 4 --output snapshot-slices
-```
+### 其他输入格式
 
-设备选择、JSON 输出、确定性命名、回放验证和失败安全发布见
-[拆分快照](docs/zh/splitting.md)。
-
-完整的入门指南见 [Quick Start](docs/zh/quickstart.md)。
-
-完整兼容 v1 分片产物可以目录或 `manifest.json` 为 focus，无需已归档 pickle。
-只读 overview、事件路由、`--slice` 和跨片限制见
-[完整数据集 focus 与寻址](docs/zh/sharded-snapshotdb.md#完整数据集-focus-与寻址p1)。
-
-用 `pt-snap import snapshot.pkl --events-per-slice 50000 --output-dir captures --json`
-显式生成**原生、非 msinsight 兼容**数据集 `captures/snapshot.pkl.pt-snap-native-v2/`。
-默认单库导入不变；复用校验全部片及内容/选项/语义版本。不匹配的已识别目标须
-`--force`，未知目标保留。发布/focus 失败会补偿，回滚自身失败则保留并报告恢复证据
-（force 不是单次崩溃原子 swap）。详见
-[原生分库导入](docs/zh/quickstart.md#可选导入原生分库数据集)。数据集 `event` 寻址及定点
-`active_blocks_at_event` / `active_memory_callstack_at_event` 共用跨片 alloc/free 批量来源，
-原版无扩展产物也适用。内建全局峰值、事件分页、canonical 栈统计、去重生命周期、
-终片泄漏候选及 `report peak-memory` 共用有界 core 语义；数据集仍不支持自定义 SQL/override。
-详见[全局支持矩阵](docs/zh/querying.md#数据集全局内建支持p3)及
-[数据集定点归因与覆盖](docs/zh/querying.md#数据集定点事件归因)。
-超过 SQLite 附加上限的生命周期查询使用私有、限制主库页数空间的临时派生数据库，源分片
-保持只读；存储限额、清理及内存边界见全局支持矩阵。
-
-显式 `pt-snap import snapshot.pkl --format msinsight --json` 生成
-`snapshot.pkl.msinsight/`，对齐固定 msinsight 版本的**同一原始 pickle + 邻接缓存**入口。
-内联栈比原生去重占更多空间；即使 `--force` 也不替换已有兼容目标，只复用完整校验且
-身份相同的 pt-snap 缓存。GUI **待验收/未运行**，hash 相等不代表验收通过。详见
-[兼容导出及限制](docs/zh/sharded-snapshotdb.md#显式-msinsight-兼容导出p2)。
-
-[离线双向验收与有界性能](docs/zh/interop-acceptance.md) 提供固定版本两条链路、
-确定性独立参考工具、真实三模式测量及明确**待验收/not-run 的 GUI 清单**。
-诊断 skills 接受显式选择的完整已校验数据集，不接受任意目录。
+- [原生分库导入](docs/zh/quickstart.md#可选导入原生分库数据集)：用 `--events-per-slice` 显式启用，不是 msinsight 兼容格式。
+- [显式 msinsight 导出](docs/zh/quickstart.md#可选导出-msinsight-兼容数据集)：独立的兼容合同与 no-replace 规则，`--force` 也不替换。
+- [可回放 pickle 拆分](docs/zh/splitting.md)：只选一种拆分策略并使用新目录，与数据集导入不同。
+- [完整数据集寻址](docs/zh/sharded-snapshotdb.md#完整数据集-focus-与寻址p1)、[全局内建支持](docs/zh/querying.md#数据集全局内建支持p3)和[已记录的互操作验收](docs/zh/interop-acceptance.md)：按需查看高级合同与证据，不是第一份报告的前置条件。
 
 ## 命令
 
@@ -138,12 +113,15 @@ helper 会先路由采集，无需先安装 CLI。分析仍需要 CLI 和 Snapsh
 
 ## 开发
 
+统一使用根 [Development and Checks 检查清单](AGENTS.md#development-and-checks)：
+fixture provenance、pytest、Ruff、Black、**basedpyright** 和 `git diff --check`，
+并在同一入口查看环境隔离、浏览器测试与覆盖率门槛。
+
 ```bash
-pip install -e ".[dev]"         # 安装开发依赖
-pytest                           # 运行所有测试
-black --check . && ruff check .  # 检查格式和 lint
+python -m pip install -e ".[dev]"
 ```
 
+
 常规套件可用 `pytest -m 'not slow'`。默认容量规模及非 editable 安装包导出测试见
 [数据集验收指南](docs/zh/dataset-acceptance.md)。
 

diff --git a/docs/AGENTS.md b/docs/AGENTS.md
@@ -27,6 +27,8 @@ Commands must be checked against group modules too; not all options live in
 
 - Public behavior changes update both language guides and relevant README entry
   points. Topic additions/moves also update `docs/README.md` navigation.
+- First-use walkthroughs route by input, show the default report before advanced
+  formats, and explain output units and import/focus writes next to the commands.
 - Installation walkthroughs lead with PyPI; keep editable developer setup
   separate. Agent integration uses skills plus CLI, and host restart/loading
   must be distinguished from on-disk installation status.

diff --git a/docs/README.md b/docs/README.md
@@ -1,5 +1,17 @@
 # pt-snap-cli Documentation
 
+## Start by Goal / 按目标开始
+
+| Goal / 目标 | English | 中文 |
+| --- | --- | --- |
+| Prepare or collect input / 准备或采集输入 | [Input choices](en/quickstart.md#prepare-your-input) | [输入分流](zh/quickstart.md#准备输入) |
+| First read-only report / 首份只读报告 | [Inspect, query, report](en/quickstart.md#step-2-inspect-the-target-and-choose-a-device) | [检查、查询、报告](zh/quickstart.md#第二步检查目标并选择设备) |
+| First agent session / 首次 Agent 接入 | [Install, restart, verify, ask](en/skills.md#first-agent-session) | [安装、重启、验证、提问](zh/skills.md#首次-agent-会话) |
+| Contributor checks / 贡献者检查 | [Canonical checklist](../AGENTS.md#development-and-checks) | [统一完整清单](../AGENTS.md#development-and-checks) |
+
+Advanced protocols and evidence are indexed below; they are not prerequisites
+for the default single-DB workflow. 高级协议与证据见下表，不是默认单库流程的前置阅读。
+
 ## English
 
 | Topic | File |

diff --git a/docs/en/AGENTS.md b/docs/en/AGENTS.md
@@ -7,7 +7,7 @@ Translation counterpart: [Chinese guides](../zh/AGENTS.md).
 
 | Guide | Required behavior coverage |
 | --- | --- |
-| `quickstart.md` | PyPI/source setup, trusted import, focus and first query |
+| `quickstart.md` | Input/collection routing, PyPI setup, trusted import/focus effects, first report and metric interpretation |
 | `focus-management.md` | Explicit/environment/project/global resolution and persistence |
 | `querying.md` | Template discovery, params, semantics, pagination/completeness and timeout |
 | `splitting.md` | Strategy/device/format, original event IDs, replay validation and absent-destination publication |