Skip to content

Documentation Source of Truth

Jump to bottom
Jm Rohmer edited this page Jul 18, 2026 · 4 revisions

Documentation Source of Truth

Use this page to decide which file should be updated when behavior changes. The goal is to avoid stale README, wiki, and auth.md references.

Repository Docs

Topic Source of truth
Public project overview README.md
Contribution workflow and review expectations CONTRIBUTING.md
Community behavior rules CODE_OF_CONDUCT.md
Tool IDs, titles, and scope mapping docs/tools.md
Operator config and service behavior docs/operator-guide.md
Release gates docs/release-checklist.md
AgentReady 100% recovery notes docs/agent-ready-howto.md
Client compatibility status docs/client-compatibility.md
Standards mapping docs/rfc-compliance.md
OAuth client registry example docs/oauth-clients.example.yaml
OpenResty/Nginx/Hugo static examples docs/examples/agent-ready/
Live public recovery notes for www / mcp discovery docs/agent-ready-howto.md

Wiki Docs

Topic Wiki page
Operator overview Home
AgentReady breakages and fixes AgentReady Pitfalls
OAuth scope pitfalls Pitfall invalid scope disguised as 302
Live topology and deploy verification Live Deployment Runbook
OAuth clients and aliases OAuth Clients and Scopes
Quick tool scope matrix Scope and Tool Matrix
Client behavior notes Client Compatibility
Smoke commands Smoke Tests and Live Verification
Secret handling Security Redaction Checklist

Current Scope Model

Since #450, canonical advertised scopes:

read
write

write implies read, plus every tool that used to require a separate site.admin tier. read is fully ungated — no client secret needed, and it includes tools that used to require content.read (e.g. validate_site, build_agent_context) — see Pitfall Anonymous vs Authenticated Server.

Compatibility aliases (all older scope strings normalize to one of the two above):

content.read, reader, mcp                                  -> read
content.write, site.admin, system.admin, admin, and others  -> write

See docs/mcp-contract.md §6.12 for the exact alias table. Do not reintroduce a third canonical scope (e.g. a restricted "reader" tier, or a separate admin tier) unless the code, tests, discovery metadata, README, wiki, and release notes are all updated intentionally.

Update Checklist

When a public behavior changes, check:

rg -n "old_name|old_scope|old_url" README.md docs
rg -n "old_name|old_scope|old_url" /tmp/mcp-hugo-server-go.wiki

Then update only the relevant docs. Historical notes can mention old behavior, but they must clearly say it is historical or compatibility-only.

Avoiding Drift

  • Do not hard-code a tool list in new docs unless it is copied from docs/tools.md.
  • Do not document a discovery field unless it is generated by the server or served by the Hugo static files.
  • Do not say a client is fully working unless it has been tested live after the latest deploy.
  • Do not document host-local secrets, bearer tokens, cookies, or OAuth authorization codes.
  • Do not let repository policy drift between README.md, CONTRIBUTING.md, issue templates, and PR template.

Clone this wiki locally