docs: reconcile spec with actual implementation (drift sync)

[jrosskopf]

Summary

Part 2 of the spec↔implementation drift remediation (Part 1 = #245 code fixes). A doc↔implementation audit (6 scoped subagent passes + a Codex pass) found the specs had drifted from the code across the agent surface, admin surface, storage, DX, and platform docs. This syncs the docs to what the code actually does. Where the spec described an unbuilt feature, it is now clearly marked Not yet implemented rather than presented as current. No code changed.

docs/spec/protocol.md (the wire contract — biggest change)

• Read tools: expand / neighbours / list_instances / resolve request args + response fields corrected to the real handlers; documented the shared scenario / full / as_of params; removed never-emitted fields (snapshot_version, resolve.error, session content/conflicts/issues) as not-yet-implemented. Documented fetch_blob (was undocumented); added Hit.similarity, search.queries/page_id; validate → {ok, issues}.
• Admin: real tool names (admin_audit / admin_quota / admin_delete_chat_history); removed the non-existent health MCP tool; fixed tenant/attach_external arg+output shapes; added the ~11 previously-undocumented admin tools (admin_index_query, lane introspection, group members, run_stored_query, create_remote_instance, …); documented tenant_delete confirm + tenant_export {format_version, sha256} + markdown-only tarball (matches fix: align runtime with documented contract (spec-drift code fixes) #245).
• Framing/versioning: tools/list is not role-gated (admin tools always listed, dispatch-gated); added the plain-HTTP endpoints incl. /openapi.json; versioning corrected to the crate semver (no escurel-ws/1); backend_ref is {kind, endpoint}.

Other docs

• storage.md — removed the phantom frontmatter_index table (filtering is a direct json_extract over pages); open_writer not-implemented; url() -> Result<Url>; links PK includes dst_anchor; FTS ignore regex; put_blob signature; compact_db → compact_lanes.
• dx.md — Role::User → Role::Agent (the canonical example didn't compile); added AuthMode::ExternalMulti; TestIssuer is RSA-2048.
• platform.md / README.md / deploy — the multi-tenant TenantManager model, the sizing knobs, log_format=text, and the /readyz OTel check are marked not-implemented; OTLP env is the convention name (bare ESCUREL_OTLP_ENDPOINT a deprecated alias).
• Dockerfile — base rust:1.88 → 1.91 (matches rust-toolchain.toml); bundled-DuckDB comments rewritten to describe download mode. (Image build verified by CI, not locally.)
• CLAUDE.md — CI is live (re-enabled at v1.0.0); flipped the three stale "CI is paused" claims.
• ADR-0002 — appended a note that gRPC was retired (surface is MCP-only).

Verification

Docs-only — no code changed, so fmt/clippy/test/build are unaffected (sanity cargo build + fmt --check pass locally; CI runs the full gate). Every claim was verified against the cited source file during the sync. Two larger feature gaps found in the audit are filed as #246 (update_page optimistic concurrency) and #247 (tenant_update status/quotas).

Depends on #245 for the tenant_delete / tenant_export / OTLP field names it documents — merge #245 first.

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag /codesmith with what you need. Autofix is disabled.}