[codeasier]

Summary

Fixes #270.

The first-use path was split across advanced format contracts, focus documentation, and installation edge cases. This change makes the default path explicit without changing runtime behavior.

• Route README and the bilingual documentation index by existing DB/complete dataset, trusted pickle, collection, or agent use.
• Put input preparation → default import (if needed) → overview/device selection → memory_peak → readable peak-memory report before optional sharded/compatible/split contracts.
• Explain Python 3.10+, collection versus offline analysis, byte units and counter meanings, independent peak events, attribution coverage and included-byte denominators.
• Document output placement, default project-focus writes, and --no-focus beside import. Explicitly distinguish standalone cache-miss/force replacement from native/compatible directory protections.
• Lead Agent Skills with install → restart → disk/host verification → natural-language requests. Preserve the existing preflight, trust, read-only, dataset and attribution contracts.
• Add packaged, on-demand full-output recovery instructions: retrieve every retained output chunk or retry only the incomplete read-only probe with an in-memory JSON minifier. Never treat truncation/summaries as complete evidence.
• Point both READMEs at the canonical contributor checklist, including basedpyright.

Verification

• Independent static review completed; its standalone-replacement wording finding was corrected and re-reviewed.
• Static relative-link/heading audit: 210 references checked, no missing targets.
• Authored/bundled parity checked for the four changed skill trees; recovery references are included in both trees.
• Ruff, Black and git diff --check passed for the candidate; new/updated Python test syntax inspected.
• Added regression coverage for bilingual command/output parity, local links, ordering/state boundaries, actual documented commands against a synthetic DB, read-only report behavior, and complete/truncated/failed recovery payloads.
• Updated the custom-install missing-skill fixture to remove its temporary whole skill directory now that references are bundled.
• Unit tests and wheel/build acceptance are intentionally delegated to the existing Test and Platform compatibility CI workflows (not duplicated in the cloud workspace). See this PR's exact-head checks for execution results.

Scope

Documentation, packaged skill instructions and regression tests only. No query/import/cache runtime changes; no real pickle, hardware collection, live-model diagnosis, release or deployment was performed.

Based on main 365771995541cdc4bb5af589ba5ac664da5f7f1c. PR #269 remains separate and unmerged; this PR does not assume its parser-v3 or sharded frame-tree behavior.

Snapshot Runtime Provenance

No files under src/pt_snap_cli/snapshot/ changed.

[codeasier]

Validation complete for head 340c8594d284efa22ec17f5e384a4b14f9aa5973.

• Test: success. Python 3.10–3.13, provenance, Ruff/Black/basedpyright, Chromium interaction regression, wheel build/audit, and clean-wheel offline CLI/Skills acceptance passed. Python 3.13: 3082 passed, 14 skipped, 7 deselected, 9 subtests passed; branch-enabled coverage 92.90%, with all critical-file floors passing.
• Platform compatibility: success. All four Windows partitions passed; macOS: 3066 passed, 14 skipped, 23 deselected, 9 subtests passed.
• All 29 new onboarding/recovery cases passed on Linux and macOS and across the Windows partition union. These include the actual bilingual documented overview/query/report commands against a synthetic database, unchanged source bytes/focus, relative links and anchors, skill-reference parity, and complete/truncated/failed output recovery.
• Exact-head check readback: 12 successful jobs, with only the existing schedule/manual-only installed-wheel dataset-acceptance job skipped for the PR event. That skip is not a claim that the larger scheduled acceptance ran; the ordinary clean-wheel CLI/Skills acceptance did run and pass.

The first CI attempt exposed an existing fault-injection test patching process-wide os.fstat unconditionally. Commit 340c859 limits the failure to the test-owned staging descriptor and restores the patch before pytest handles the exception. Independent static re-review cleared the change; real descriptor-close assertions remain, with no runtime change, new skip, or weakened gate.

All test/build execution used the existing CI workflows and their reviewed fixtures (plus the new synthetic onboarding fixture), not duplicate local UT/build runs. No ad-hoc user-data import, hardware capture, live-model diagnosis, release or deployment was performed.

The PR remains Draft, unmerged.