Agent-grade content: one source, two readers

Two readers, one source

Most wikis are optimised exclusively for human reading: flowing prose, headers for navigation, images and tables for comprehension. That is fine for humans. But AI agents need something different: explicit metadata to assess source confidence, a token-budgeted representation that fits within an LLM context window, structured hints about which tools and related pages are relevant, and verification timestamps to know whether a fact is still current.

Wikantik's answer is not "write a separate machine-readable version". It is a set of conventions, metadata fields, and server-side projection logic that transforms a single well-structured page into the right form for each reader automatically.

For the full design, see Agent-Grade Content Design in the live wiki.

Page projections for agents: /api/pages/for-agent/{id}

The /api/pages/for-agent/{id} endpoint delivers a token-budgeted projection of a page specifically shaped for agent consumption. Rather than the rendered HTML a browser receives, the agent projection includes:

• Structured YAML frontmatter fields (type, cluster, status, summary, tags)
• The canonical ID for rename-stable cross-referencing
• Verification metadata (see below)
• Derived agent_hints computed at projection time

The agent_hints field has two sub-fields computed by AgentHintsDeriver at request time with zero author burden:

• prefer_tools — ranked list of MCP tools relevant to this page and its cluster, from McpToolHintsResolver
• prefer_pages — ranked list of cluster pages by intra-cluster wikilink centrality, with a 1.5× bonus for verified-authoritative pages

An agent that calls /for-agent on a page gets not just the content but also a curated reading list and a ranked tool recommendation — without any author having to maintain those lists manually.

Runbooks and page types

Wikantik pages are typed. The type: frontmatter field declares what kind of content a page contains:

• article — explanatory content on a topic
• design — architectural or design documentation
• reference — reference material (config keys, API docs, etc.)
• runbook — a specialised type for procedural content

Runbook pages include a runbook: frontmatter block with structured fields:

• when_to_use — specific triggers for the procedure
• steps — an ordered list of atomic actions
• pitfalls — common failure modes and mitigations

An agent retrieving a runbook page knows it is procedural, what triggers it, and can walk the steps — without having to parse prose to figure out "is this a how-to or an explanation?"

For live examples of typed, retrieval-tuned content built this way, browse the wiki's practice clusters: data science practice, operations research (from open-source solvers to production optimization), and software engineering practices (e.g. property-based testing).

Verification metadata

Agents need to know how much to trust a citation. Is this page current? Has a human reviewed it recently? Wikantik's confidence protocol answers these questions with three frontmatter fields:

• verified_at — ISO-8601 timestamp of the last manual audit
• verified_by — the verifier (readers see their display name, not the stored login)
• confidence — one of authoritative (verified within the last 90 days by a trusted author), provisional (verified within 90 days but not by a trusted author), or stale (never verified, or over 90 days since the last verification)

The auto-generated frontmatter flag acts as a technical debt marker: pages marked true are treated as low-confidence stubs. Setting it to false is a declaration that the content has been overhauled to meet the high-density, machine-readable standard.

Retrieval-quality CI and the agent-grade audit

Wikantik ships an operator-facing audit report at /admin/agent-grade-audit that surfaces pages with weak agent-grade signals: no cluster, no inbound cluster links (for non-hub pages), generic hub summaries, or missing or stale verification. Pages are sorted by flag count so operators can focus their improvement effort where it matters most.

This is the compensating control for a content standard that does not impose mandatory frontmatter on every page: the audit tells you where the gaps are, without blocking authors who are still writing drafts.

Frequently asked questions

What is the /api/pages/for-agent/{id} endpoint?

It is a token-budgeted projection of a page tailored for agent consumption. It includes the page content, structured frontmatter metadata, verification status, and derived agent_hints — prefer_tools (which MCP tools are relevant) and prefer_pages (which cluster pages are highest-centrality). Agents get all of this in one call rather than assembling it from multiple endpoints.

What is the auto-generated flag?

Pages with auto-generated: true in their frontmatter are treated as low-confidence stubs. Setting it to false is a declaration that a human has reviewed and overhauled the content to meet the high-density standards required for authoritative agent citations.

How does verification metadata work?

Pages carry verified_at (ISO-8601 timestamp), verified_by (the reviewer, shown to readers as a display name), and confidence (authoritative, provisional, or stale). Agents can check these fields to assess how much to trust a citation. The agent-grade audit at /admin/agent-grade-audit flags pages with missing or stale verification.