docs: align docs with code on MCP tool exposure, scheme discovery, and build variants

[V3RON]

Fixes nine doc/code inconsistencies. Each was verified against packages/ (the source of truth) before editing; no behavior changes, only documentation and two CLI help strings.

What was wrong, and what the code says

1. README.md claimed app tools "show up next to the agent's own" over MCP. packages/appduct/src/mcp/app-tools.ts:3 is explicit that they are never registered as MCP tools — an agent reaches them through appduct_list_tools / appduct_describe_tool / appduct_call_tool. (packages/appduct/README.md:215 already said this correctly.)

2. Scheme discovery also reads Android app/build.gradle(.kts) / app/src/main/AndroidManifest.xml and iOS Info.plist / project.yml (native-scheme.ts), and init reaches those probes too via discoverStaticProjectScheme. Only app.json was documented. Updated the init --scheme and link --scheme help text, docs/ARCHITECTURE.md §10 (item 5 is now the full a/b/c probe order), and the appduct skill (SKILL.md, references/setup.md), including the rule that two probes resolving different schemes is an error rather than a guess. Also corrected §10's two init --force / divergence sentences, which still named app.json alone.

3. docs/TOOLS.md documented a createAppductClient defaultToolTimeoutMs option. CreateAppductClientOptions is Record<string, never>; the app-side fallback is native-owned (APPDUCT_DEFAULT_TOOL_TIMEOUT_MS) with no TurboModule channel for JS to override it.

4. docs/ARCHITECTURE.md §11 said sessionChange carries only { sessionId, alias } and no longer distinguishes a claim from a resume from a loss. AppductSessionChangeEvent is { type, sessionId, alias, reason? }.

5. packages/react-native/metro.d.ts documented include as defaulting to true and mirroring the config plugin's include option. metro.js:96 falls back to isAppductAutolinkEnabled() (APPDUCT_ENABLED), and app.plugin.js:94 throws on include as removed.

6. playground/README.md told readers to run pnpm exec expo run:ios from the monorepo root; expo is a dependency of the playground app.

7. docs/TOOLS.md intro referred to "the shape MCP requires"; app schemas no longer travel as MCP inputSchema. The file's other MCP mentions (tool groups, appduct_describe_tool, timeout_ms) are accurate and untouched.

8. docs/SECURITY.md vs docs/BUILD-VARIANTS.md disagreed about Android. BUILD-VARIANTS is correct: packages/react-native/android/build.gradle:75-79 swaps java.srcDirs between the vendored core and core-noop, and AppductPackage.kt lives in src/main/java and compiles for every variant. SECURITY.md's "swaps in a no-op AppductPackage" was fixed.

9. skills/appduct/references/setup.md numbered two steps 6.; the getAppductState() item is now 8., matching the surrounding 7/9/10.

website/src/content/docs does not exist in this repository, so there was nothing to keep in sync there.

Verification

• pnpm check:links — clean, 38 Markdown files, no broken relative links or anchors
• pnpm -w typecheck — passes
• pnpm -w test — 739 passed, 1 skipped

🤖 Generated with Claude Code

https://claude.ai/code/session_01GmJYxaqiwgZqLooLjYQXBt

---

Generated by Claude Code