docs(claude-code): onboarding overhaul + fix verify drift detection

[imran-siddique]

Summary

Make the Claude Code integration easy for any Claude Code user to understand, add, and use, and fix a correctness bug the docs work exposed.

Docs / experience

• Rewrite the plugin README to lead with why it matters: the agent's composition (skills, permissions, MCP servers, instruction layer) is what decides what it can do to your machine, and it drifts silently. Concrete threat list up top.
• Add a ~60-second quickstart showing the real first-session baseline message, and the everyday warning -> /manifest verify -> /manifest approve loop with real engine output.
• Keep the honest "known limits" section (software-only Level 0, instruction-layer proxy, policy_language composite, hook-vs-command visibility).
• Polish both command docs for plain-English reporting and to reflect the verify fix. Removed em dashes throughout per house style.

Fix (verify drift detection)

• cmd_verify used _load(LATEST) or snapshot(...), so it trusted a cached session-latest.json and ignored the --live-context the /manifest command passes. Drift introduced after session start (a rogue skill, a widened permission) was reported as "nothing added, nothing subtracted" against stale data, defeating the plugin's whole point.
• verify now always re-snapshots (merging live context) and saves the result, falling back to LATEST only when no snapshot is possible.
• Reproduced before the fix and confirmed fixed after: with a rogue exfil skill + a widened Bash(curl:*) permission on disk, verify now reports both changes without a manual re-snapshot.

Validation

• python -m pytest claude-code/tests/test_capture.py -q -> 7 passed (adds an end-to-end regression test driving cmd_verify against post-baseline drift).
• ruff check claude-code/engine claude-code/tests --select E,F,W --ignore E501 -> clean.
• Manually exercised snapshot / approve / verify end-to-end against a synthetic ~/.claude.

Notes

• integration.yaml claims tested_against: agent-manifest 0.2.0; PyPI now has 0.3.0 for both agent-manifest and agentrust-trace. Left version numbers untouched (no maintainer test matrix re-run in scope); flagging for a follow-up.

🤖 Generated with Claude Code