Skip to content

docs: align agent and user documentation with runtime behavior - #88

Merged
codeasier merged 3 commits into
mainfrom
docs/add-agent-guidance
Aug 8, 2026
Merged

codeasier merged 3 commits into
mainfrom
docs/add-agent-guidance

Conversation

@codeasier

@codeasier codeasier commented Aug 7, 2026 •

Copy link
Copy Markdown
Owner

📝 Description

This PR now covers both repository-local agent guidance and a repository-wide user documentation governance pass.

Agent guidance

  • Add directory-local AGENTS.md guidance for .github/, docs/, src/, and tests/ subtrees.
  • Keep the consolidated root AGENTS.md as the repository-wide navigation and invariant layer.
  • Update documentation inventories for snapshot splitting, legal evidence, and the high-level Python API.
  • Add focused snapshot runtime/test guidance and complete service, template, CI, and test navigation after review.

User documentation

  • Fix onboarding commands that referenced a missing example database or unsupported query parameters.
  • Align SnapshotDB DDL, event relationships, dictionary encoding, metadata, focus, split, and raw query output descriptions with implementation and tests.
  • Add mirrored English and Chinese SnapshotAnalyzer API guides covering focus, device selection, template discovery, query execution, metadata, and errors.
  • Clarify optional ResultMapper behavior and the pass-through datetime declaration.
  • Streamline both root READMEs and connect the documentation index, API guides, language navigation, and governance evidence.

🔗 Related Issues

Closes #91

Related: #90 tracks the no-op leak_detection.device_id runtime template parameter; this documentation PR does not change query-template behavior.

🧪 Testing

  • pytest tests/test_api.py tests/test_governance.py (27 passed)
  • Follow-up pytest tests/test_governance.py (14 passed)
  • AGENTS validator in strict mode (24 files, 0 errors, 0 warnings)
  • git diff --check
  • Repository-relative link and English/Chinese parity review

✅ Checklist

  • Documentation claims were checked against current source and focused tests
  • English and Chinese user-visible behavior remains aligned
  • No product runtime or query template behavior changed
  • No generated, specs, superpowers, or local scratch files were added

Snapshot Runtime Provenance

  • Snapshot provenance evaluation completed when snapshot runtime files change

Snapshot provenance decision: no-update

Snapshot provenance no-update reason: This PR changes documentation and AGENTS.md guidance only; it does not modify files under src/pt_snap_cli/snapshot/ other than the local AGENTS.md instruction file.

📋 Additional Notes

The runtime metadata defect discovered during the documentation audit is intentionally tracked separately in #90 so it can be fixed with the query-template and CLI/MCP contract tests in scope.

@codeasier codeasier changed the title docs: add AGENTS.md guidance across repo subtrees docs: align agent and user documentation with runtime behavior Aug 8, 2026

@codeasier codeasier left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

跨模型 review 结果(DeepSeek / GLM / Kimi 独立审查 + 父会话复核)

用户文档中与运行时行为不符的事实性错误未通过复核。但新增 AGENTS.md 导航存在不完整/冲突问题。以下为经验证的行内发现,按严重度排序。

  • 无用户文档事实性错误成立;git diff --check 与 AGENTS 严格校验(22 文件, 0 错误, 0 警告)均通过。
  • 残余风险:尚无自动检查保障 EN/ZH 一致性及 AGENTS 导航完整性。

并行审查会增加 token 用量与成本。

Comment thread tests/AGENTS.md Resolved
Comment thread src/pt_snap_cli/core/AGENTS.md Resolved
Comment thread src/pt_snap_cli/AGENTS.md Resolved
Comment thread tests/core/AGENTS.md Resolved
@codeasier
codeasier merged commit f111db5 into main Aug 8, 2026
7 of 12 checks passed
@codeasier
codeasier deleted the docs/add-agent-guidance branch August 8, 2026 06:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[DOCS] Align user guides with implemented CLI, SnapshotDB, and Python API behavior

1 participant