[qingyun-wu]

Summary

• Creates docs/host-cli-bindings.md with the abstract surface taxonomy + per-surface re-bind cost + the canonical claudeHomePath() helper.
• Trims docs/workspace-design.md's "Host CLI dependency surface" section from ~15 lines to a 2-line pointer at the new doc.
• No specific host-CLI paths published. Those stay in the workspace-private engineering note — publishing them invites bit-rot when the host CLI's directory conventions change.

Why

Follow-up from PR #858 review (Susan / Mac Studio non-blocking observation): the high-cost re-bind list and the interop-loss list are information contributors will want, and gating it behind "ask the maintainer for the workspace-private engineering note" creates friction for the contributors most likely to be useful — the host-CLI-aware ones.

This PR promotes the public version of the taxonomy to its own doc while keeping the specific-path inventory private. Same shape as docs/workspace-design.md's relationship to docs/workspace-contract.md.

Acceptance (per #875)

• docs/host-cli-bindings.md created with the surface taxonomy + the claudeHomePath() reference
• No specific host-CLI paths in the doc — references to those stay in the workspace-private note
• docs/workspace-design.md "Host CLI dependency surface" section points at the new doc instead of carrying its content inline

Test plan

• Render the doc on GitHub and confirm the surface table reads cleanly + the no-paths rule is visible
• Confirm the link from docs/workspace-design.md to the new doc resolves
• (No code change, no tests added)

Closes #875

🤖 Generated with Claude Code

[liususan091219]

Reviewed feat/host-cli-bindings-doc HEAD — 51 LoC new public doc + 12 LoC trim of docs/workspace-design.md's "Host CLI dependency surface" section to a 2-line pointer. Docs-only PR.

Like:

• The policy is preserved: surface taxonomy goes public, specific paths stay in the workspace-private engineering note. That's exactly the right cut — the contributor who needs to estimate a host-CLI swap cost gets enough; the bit-rot-prone path inventory stays where it can be updated without a PR cycle.
• Per-surface re-bind cost table is the value. "Agent memory + skill discovery = high (need equivalent loader contract)" / "Bridge tokens = low (data movement)" / "Slash commands = interop loss (partial re-implementation)" is the right granularity for someone planning the swap. The "interop loss" framing for slash commands is sharper than "partial re-bind" — captures the user-facing regression that data-movement alone can't fix.
• Greppable-helper rationale is stated clearly: one resolver = one grep target = 1-day swap vs. quarter-long re-architecture. That's the load-bearing structural insurance, and the doc names it explicitly so a future code reviewer can reject ~/.claude/-relative paths with confidence.
• Relationship section properly cross-links workspace-design.md (the RFC) + workspace-contract.md (impl reference). Makes the doc graph navigable.

Asks (small, docs-grade):

1. "What binds it" column for the Bridge tokens row reads slightly off: "The host CLI doesn't actually need these — Sutando picked the host CLI's per-user directory as a stable, gitignored home for cross-bridge config." If nothing on the host-CLI side binds this surface, the "What binds it" cell is conceptually a no-op — worth either (a) renaming the cell to "Sutando's reason for choosing this location" or (b) calling it out inline as "(no host-CLI behavior binds this — co-located by convention, not constraint)." Today's wording requires the reader to detect the column-meaning mismatch themselves.

2. Acceptance checked, test plan unchecked. Three test items: render-on-GitHub, link resolution, "no code change, no tests added." First two are 30-second eyeballs — worth running before un-WIP'ing so the reviewer (and you) can see the table renders cleanly on github.com and the workspace-design.md → host-cli-bindings.md link resolves. The "no code change" item is informational and can stay unchecked permanently or just be removed.

3. #860 provenance for claudeHomePath() got dropped in the workspace-design.md trim. Today's diff says "the canonical helper (claude_home_path() / claudeHomePath()) you should call" — fine. But the original line (added in #860) is the kind of breadcrumb that helps a future archaeologist trace when the helper landed. Not a blocker; git log -p docs/host-cli-bindings.md recovers it, just slightly less convenient.

4. "Today: Claude Code" appears in both the new doc and the trimmed workspace-design.md after this PR. Single point of truth would be the new doc; workspace-design.md could just say "the host CLI" and link out. Trivial.

Ship it.

[vidhuUC]

APPROVE. Clean docs promotion — extracts the host-CLI surface taxonomy from workspace-design.md into its own doc. The decision to NOT publish specific host-CLI paths (to avoid bit-rot) is sound. The claudeHomePath() helper reference gives contributors the canonical lookup point without hardcoding paths in a doc that will drift. CI green.