Skip to content

Documentation Source of Truth

Jump to bottom
jmrGrav edited this page Aug 22, 2026 · 8 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
Which layer serves which public URL (MCP-dynamic / Hugo-static / OpenResty-only), and where its config lives docs/public-url-topology.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
Managed Hugo upgrade runbook (live config) Managed Hugo Upgrades
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 (extended by #1039/#1050), canonical advertised scopes:

read
write
admin

write implies read. admin implies write (and therefore read) and additionally gates the four managed Hugo binary lifecycle tools (stage_hugo_upgrade, activate_hugo, rollback_hugo, bootstrap_hugo) — it is a separately-approved tier layered on top of write, not a restoration of the old 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 (older scope strings normalize to one of the three above; admin is canonical, not a legacy alias, listed here only to show which other strings resolve to it):

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

See docs/mcp-contract.md §6.12 for the exact alias table. admin (#1039/#1050) is the one time this project has deliberately added a canonical scope beyond the #450 read/write pair — narrow and additive (four managed Hugo lifecycle tools only), not a restoration of the old four-tier model. Do not introduce a fourth canonical scope (e.g. a restricted "reader" tier carved out of read) unless the code, tests, discovery metadata, README, wiki, and release notes are all updated intentionally together.

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