How-to Guides

Task-oriented. Each guide solves one concrete task. Prerequisites from the Quickstart assumed.

H1 — Verify the freshness of any page

Find the page’s provenance block (owner · repo@SHA).

Compare the pinned SHA to live remote HEAD:

gh api repos/Aftergraph/<repo>/commits/main --jq '.sha'

If they differ, check /status.json for the semantic verdict: SOURCE_MOVED_CONTENT_UNCHANGED (dependabot churn, artifacts identical — harmless) vs SOURCE_MOVED_CONTENT_CHANGED (semantic drift, adoption pending). See ADR-004.

H2 — Adopt a moved source (explicit, reviewable)

Pins are never auto-updated. After review:

node scripts/adopt-source.mjs Aftergraph/<repo> <new-full-40-sha>

The script updates pins, provenance, catalog and artifact fingerprints, then runs all validation gates. Commit + push; the scheduled verifier (6h cadence) picks up the new state.

H3 — Wire the Docs MCP into your client

Hermes:

hermes config set mcp_servers.aftergraph-docs.command node
hermes config set mcp_servers.aftergraph-docs.args '["/path/to/docs/scripts/docs-mcp-server.mjs"]'

Generic stdio client: run node scripts/docs-mcp-server.mjs and speak newline-delimited JSON-RPC (initialize → tools/list → tools/call). The server is read-only and bounded to the built dist/ — run npm run build first. Boundary details: Docs MCP.

H4 — Consume context packs in your agent

Fetch the index, then per-page packs:

curl -s https://docs.aftergraph.org/context/index.json
curl -s https://docs.aftergraph.org/context/platform.system-map.json

Each pack carries source_repository@source_commit, dependency contracts, related claims, next_reading and freshness constraints. Treat the pack as never fresher than its site_commit. Schema invariants: ADR-005.

H5 — Add a new canonical source

Add the repo to PUBLIC_ALLOWLIST and SOURCES in src/data/sources.ts (full SHA, owner, kind, visibility).
Add a provenance entry for any page that renders from it.
npm run build — validation fails on non-allowlisted references, so private leakage is structurally impossible.

Was this page helpful?