Document 2026-08-22 heartbeat integration, openapi.json/health, host-aware oauth-protected-resource fix, and auth.md self-correction
docs: fix stale 2-tier scope claims, Release-Checklist command drift (v1.9.2 freshness pass)
Cross-checked every wiki page against current main (through #1209) and
docs/tools.md, docs/mcp-contract.md, docs/operator-guide.md. Found and
fixed real drift, not just cosmetic staleness:
- Client-Compatibility.md, Smoke-Tests-and-Live-Verification.md: both
claimed "write scope sees the full write/build/admin tool set" — the
admin tier (#1039/#1050) narrowed that; write no longer includes the
four managed Hugo lifecycle tools. Fixed both, matching the model
OAuth-Clients-and-Scopes.md and Pitfall-Anonymous-vs-Authenticated-Server.md
already correctly describe.
- Managed-Hugo-Upgrades.md: said "all five [Hugo upgrade] tools require
a write bearer" — verified against internal/tools/admin/image.go's
Defs(): only get_hugo_update requires write; the other four require
admin. This was a real security-relevant inaccuracy, not just stale
wording.
- Installation-Guide.md: scope table still said "read/write scopes",
missing admin.
- Documentation-Source-of-Truth.md: self-contradicted — described the
current 3-scope model, then immediately said "do not reintroduce a
third canonical scope," leftover text from before #1039/#1050 shipped
the admin tier it was warning against. Reworded to be accurate and
forward-looking (warn against a fourth scope instead).
- Release-Checklist.md: explicitly claims "docs/release-checklist.md
remains the source of truth for the exact command list" and then
presented its own diverged copy (had a standalone `gofmt -w` step the
repo doc doesn't have; missing check-readme-release/check-agent-ready.sh
the repo doc does have). Synced to match, noted gofmt is CI-enforced
rather than a manual step, and added a note about the new v1.9.2
diff-coverage gate (#1207).
- Pitfall-Claude-auth_callback-vs-oauth_callback.md: added a
terminology note on its historical `scope: site.admin` example
(still valid as a compatibility alias, but now resolves to the
narrower `admin` tier, not `write`) — same pattern the sibling
invalid-scope-disguised-as-302 pitfall page already uses.
- Pitfall-openid-configuration-404.md: added a "reconfirmed live
2026-08-20" note — re-observed the same 404-then-success pattern in
production logs today while diagnosing an unrelated ChatGPT connector
issue; still expected, still no fix needed.
Read every other page (Home, AgentReady-Pitfalls, Live-Deployment-Runbook,
Discovery-and-RFC-Map, Webhook-Plugins-Configuration, Security-Redaction-Checklist,
Pitfalls-Index, Scope-and-Tool-Matrix, remaining Pitfall-* pages,
Client-Compatibility, OAuth-Clients-and-Scopes) — all already current
against v1.9.2 main, no changes needed. Config field names
(cloudflare/indexnow/google_indexing) spot-checked directly against
internal/config/config.go and match exactly. docs/tools.md and
docs/mcp-contract.md already document the three chunked-upload tools
from #1204/#1205 — repo docs were already in sync.
Update scope model docs from 2-tier to 3-tier (read/write/admin)
Matches the mcp-hugo-server-go main repo docs fix (PR #1057), landing
after that PR's merge to main so this wiki never describes a state
main didn't yet reflect. #1039/#1050 added a third, strictly-additive
admin scope on top of write, gating the four managed Hugo binary
lifecycle tools. Several pages self-contradicted their own examples
(OAuth-Clients-and-Scopes.md already showed a scopes: ["read", "write",
"admin"] example while its prose said 'exactly two'), and some claimed
legacy site.admin/system.admin resolve to write -- they resolve to
admin as of #1039/#1050.
Pitfall-Anonymous-vs-Authenticated-Server.md needed the largest
rewrite: it described exactly two MCP server instances
(publicServer/writeServer), but internal/server/server.go's New() now
builds three (publicServer/writeServer/adminServer). It also
speculated that a future restricted-reader tier would need a third
instance -- a third instance was added, but for the unrelated reason
of gating admin-only tools, not restricting read.
Add Managed Hugo Upgrades runbook (#980/#990)
Documents the live hugo-vm wiring: the dedicated systemd PATH drop-in,
hugo_upgrade config block, and the verification performed when enabling
the capability (build_site + get_hugo_update + a real stage, no
activation performed). Linked from Home and Documentation-Source-of-Truth.
docs: update wiki to reflect the #450 2-scope model (read/write)
Several pages still described the pre-#450 four-tier scope model
(content.read/content.write/site.admin/system.admin with mcp as the
only alias) as if it were still active. Since #450 the server enforces
exactly two scopes, read and write, with every older scope string
accepted only as a compatibility alias.
Home, Documentation-Source-of-Truth, OAuth-Clients-and-Scopes,
Scope-and-Tool-Matrix, Pitfalls-Index, Client-Compatibility, and
Smoke-Tests-and-Live-Verification updated to describe the current
model as current, with the old model kept only as historical context
where relevant.
Pitfall-Anonymous-vs-Authenticated-Server rewritten more substantially:
it described a four-MCP-server-instance architecture
(anonServer/readServer/writeServer/siteAdminServer) that no longer
exists in the code -- the server now runs two instances
(publicServer/writeServer), and read-only tools that used to require
content.read (validate_site, build_agent_context, etc.) are fully
ungated since #450, not just relabeled.
Security-Proof-Client-Credential-Isolation gets a terminology note
rather than a rewrite -- the security property it demonstrates
(redirect URI isolation blocks cross-client credential reuse) is
scope-model-independent, so the historical scope names are left
in place with a pointer to the current model.
docs: document july 13 agent-ready recovery
docs: align wiki with contribution rules and graph contract
docs: add wiki source-of-truth and smoke runbooks