docs: add ADR 0001 (agentd-mcp stdio transport) and wire into nav

[geoffjay]

Summary

• Commits ADR 0001 from the architect agent's untracked file at docs/planning/decisions/0001-agentd-mcp-stdio-transport.md
• Creates the docs/planning/decisions/ directory structure for future ADRs
• Adds an Architecture Decisions section to mkdocs.yml nav under Development

Context

The architect agent drafted ADR 0001 covering the decision to build agentd-mcp as a stdio/rmcp pass-through service (vs. HTTP server or CLI embedding). The file existed in the local main checkout as an untracked file. This PR commits it and makes it discoverable in the docs site.

ADR status is Proposed — it should be reviewed and accepted alongside or before the #249 scaffold PR lands, per the architect's recommendation.

Nav change

- Development:
    - Error Handling & Logging: public/error-handling.md
    - Storage Patterns: storage.md
    + Architecture Decisions:
    +     - 0001 — agentd-mcp stdio Transport: planning/decisions/0001-agentd-mcp-stdio-transport.md

Test plan

• Verify MkDocs builds without errors (mkdocs build)
• Confirm ADR renders correctly at Development → Architecture Decisions → 0001
• Review ADR content against architect's stated intent (stdio/rmcp, pass-through, no storage)
• Accept ADR status (Proposed → Accepted) before or alongside Scaffold agentd-mcp crate with rmcp server framework #249

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 55.66%. Comparing base (a5867f0) to head (9da77ba).
⚠️ Report is 12 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #736   +/-   ##
=======================================
  Coverage   55.66%   55.66%           
=======================================
  Files         126      126           
  Lines       13759    13760    +1     
=======================================
+ Hits         7659     7660    +1     
  Misses       6100     6100           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[geoffjay]

👀 Conductor: Awaiting reviewer — 30 minutes with no review activity.

CI: PASSED — this PR is ready for review. No reviewer has commented or approved yet.

Nudge posted by conductor pipeline sync at 2026-03-23 17:01 UTC. Communicate service offline; using PR comment as fallback.

[geoffjay]

Review: docs — ADR 0001 (agentd-mcp stdio transport)

Stack position: docs/adr-0001-agentd-mcp is directly on main, no
parent PR dependency. git-spice reports (needs restack) — the branch is
behind main and must be rebased before the conductor can merge it.

This is the correct branch for this content. PRs #740 and #744 both
accidentally included this same ADR file in unrelated branches; both have
needs-rework and will remove their duplicate copies. This PR is the
authoritative home.

---

ADR content: approved

The document addresses all four concerns the architect raised for issue #248:

Architect requirement	ADR coverage
stdio vs HTTP decision rationale	✅ Options A/B/C with full pros/cons
rmcp choice documented	✅ Decision Drivers + Implementation Notes
Pass-through architecture documented	✅ Context + Consequences
Standard service template deviation justified	✅ Context + Consequences ("New contributors must understand...")
rmcp pin strategy	✅ "Pin to 0.16.x... track changelog... fallback if unstable"
Self-healing tool risk annotations	✅ Neutral consequences item
Use agentd-common types, not redefine	✅ Implementation Notes
install.md update referenced	✅ Implementation Notes → #259

The three-option structure (stdio/rmcp, HTTP server, embed in CLI) gives
future readers the necessary context for why the chosen approach wasn't
simply the path of least resistance. The Consequences section is balanced —
the "cannot be monitored via agent status" trade-off is called out
honestly.

**Status**: Proposed is correct for this commit. The PR description
calls out that it should advance to Accepted before or alongside #249 —
that update can land as a one-line amendment on the same PR or as a
follow-up commit to main once the project owner signs off. Not a blocker
here.

mkdocs nav: approved

• docs_dir is not overridden; it defaults to docs/. The nav path
  planning/decisions/0001-agentd-mcp-stdio-transport.md resolves to
  docs/planning/decisions/0001-agentd-mcp-stdio-transport.md — matches
  the new file location.
• docs/planning/decisions/ does not yet exist on main; this PR creates
  it. No stale directory entries to worry about.
• Placement under Development → Architecture Decisions is appropriate.

Scope: clean

Two files, both directly relevant:

• docs/planning/decisions/0001-agentd-mcp-stdio-transport.md — the ADR
• mkdocs.yml — nav wiring for it

No unrelated changes.

---

Action required before merge

Rebase onto main:

git-spice branch restack
git-spice branch submit

Once restacked, add merge-queue. After merge, PRs #740 and #744 can
complete their needs-rework by removing their duplicate copies of this
file, which unblocks them.