docs: permission-grant ceremony — the mobile-OS app-permission analog

[hanwencheng]

Summary

Encodes the mobile-OS app-permission model as AgentKeys' core product mental model. You install an app → it asks for permissions at first launch → you grant/deny each → the OS enforces at the syscall boundary → you revoke in Settings. AgentKeys is the same, one layer up, for AI agents. Pure docs PR — additive only (78 insertions, 0 deletions).

The analogy isn't decorative — it crisply explains why hooks (not just MCP tools) are non-negotiable: an app politely calling a "may I use the camera?" function it can skip = IAM tool; the OS intercepting the camera syscall = IAM guarantee = the PreToolUse hook. That's exactly the §3.6 / §22d distinction, now with a mental model everyone already owns.

What changed

docs/agent-iam-strategy.md — new §2.7 (expansive; it's the product spine)

• Full mobile-OS → AgentKeys mapping table (install=onboard, first-launch prompt=K11 grant ceremony, syscall enforcement=PreToolUse hook, Settings revoke=cap.revoke)
• Three reasons it's the spine: consumer pitch without saying "IAM" (§3.4 dual narrative), the IAM-tool-vs-guarantee distinction made tangible (§3.6), the onboarding ceremony as the product trust moment (§3.7)
• Consumer permission-category vocabulary: 出行/健康/关系/工作记忆, 支付 ≤¥50, 家居控制, 凭证访问

docs/arch.md — new §10.7 (conservative; additive only)

• Maps the UX onto existing primitives (§10.2 bootstrap, §16.1 AgentKeysScope, §19 cap shape, §22d hooks). No contract / key / wire change.
• Documents the one-step-vs-two-step UX nuance: agent create + scope grant unified into one K11-captured onboarding moment = CLI/UX composition of two existing chain calls, not a protocol change.
• Identifies the real gap the analogy exposes: the current flat Scope (services[] + one global read_only + payment-only bounds) can't express per-category grants ("read-only travel memory AND no health memory AND payment ≤¥50 AND these two IoT devices"). Records the additive future Scope.grants field as a known, bounded extension, explicitly deferred to Phase 4. No v0 contract change.
• Inline compatibility check: 5 ✅ no-contradiction assertions against §10.2 / §16.1 / §22d / §6.3 / §5 canonical names.

Contradictions checked

Per CLAUDE.md architecture-as-source-of-truth policy. The new §10.7 carries its own verified no-contradiction table; the analogy reinforces the existing hooks-first §22d (the hook is the syscall-interception layer) rather than competing with it. Every cross-reference anchor verified to resolve (§10.2, §16.1, §19, §22c.4, §22d, strategy §3.4/§3.6/§3.7).

Test plan

• grep confirms both new sections present + every referenced anchor (§10.2 / §16.1 / §19 / §22d / §3.7) exists
• additive only — git diff --stat = 78 insertions, 0 deletions
• no contract / struct / wire changes; Scope.grants is documented as deferred-and-additive
• pure markdown; no code / test impact

🤖 Generated with Claude Code