docs: make the prose match the shipped behaviour, and pin the version copies

[Faisal-Fayaz]

Two of these would have led a user to write something that silently does nothing

docs/plugins.md was still a design document

It said "Status: design — no implementation here; #49 implements against this doc." The feature shipped long ago. Worse, its example manifest was wrong in a way that fails silently:

params:                          # ← a YAML mapping
  city: {type: string, required: true}

plugins.py only handles params when the value is a string, so a mapping leaves the parameter set empty, {city} is never substituted, and the tool still appears in the schema with no required arguments. Nothing warns.

Rewritten as shipped, showing the working inline form (params: city: string required) and adding a Deliberate differences table recording each divergence from the original design and why.

The documented shell fallback does not exist

"Anything outside the allowlist falls back to the shell tool, which keeps its approval gate + hard-refusal patterns."

There is no fallback and no escalation — tool_exec returns its own Blocked: … string and the command does not run. The code is right and the doc was wrong: implicit escalation to a more powerful tool is a worse default than refusing.

docs/mcp-client.md omitted the key that refuses your tools

Default trust is untrusted, a tool needs a literal readOnlyHint: true, and the refusal message tells you to set trust = "full" — a key that appeared nowhere in the file. inherit_env was absent entirely. Both are now documented, with the three gates (trust / readOnlyHint / approval) spelled out, including that an unrecognised trust value silently normalises to untrusted.

Two web_search claims were false

README and docs/egress.md both said the allowlist covers "every hit it follows". tool_web_search requests only html.duckduckgo.com and returns result URLs as text — it never fetches a hit.

SIDEKICK_TRUST_REPO was undocumented

A security gate: a repo's .sidekick/commands/*.md expands !`cmd` into sh -c with no approval prompt, and is silently ignored without it. A user had no way to discover why their repo's commands did nothing.

Version copies — all five had drifted

	was	now
AUR pkgver	0.26.0 + sdist hash for 0.26.0	0.29.0, URL + sha256 verified against the real artifact
AUR publish flow	"tag vX.Y.Z" by hand	the workflow tags; on.push filters on branches, so a tag push runs nothing
ROADMAP.md Next	v0.28.0 (already shipped)	v0.30.0, with 0.28/0.29 recorded
website roadmap	8 releases stale	matches ROADMAP.md
CONTRIBUTING.md checklist	demanded a test-count badge gate removed in #319	names the real required checks

Tests (+14)

Mechanical agreements only: version copies agree, documented keys exist, the params form shown is the form the parser accepts, the docs/examples/ manifests don't use the broken mapping form, and no removed gate is still referenced.

Deliberately not asserting that prose is true — a doc can be confidently wrong in a way no test can see, which is why the high-severity ones were verified against the code first.

sabotage	caught
revert plugins.md to design-doc framing	✅
remove the trust key documentation	✅

1381 passed (+14), ruff clean, mypy clean, coverage 79.92%.