The Page Graph: wikilinks, canonical IDs, and cluster membership

What the Page Graph is

The Page Graph is not a metaphor. It is a concrete data structure: a directed graph where nodes are pages and edges are the [OtherPage] wikilinks that authors write in page bodies. That is the only source of edges — no inference, no LLM extraction, no implicit relationships. If an author did not write the link, the edge does not exist.

This strictness is a feature. It means the Page Graph reflects actual editorial intent: which authors judged that one page is relevant enough to another to link it explicitly. That signal is valuable for navigation, authoring aids, and — as it turns out — for computing inbound link centrality to rank pages for agent retrieval.

For an authoritative comparison of the Page Graph and the Knowledge Graph, see Page Graph vs Knowledge Graph in the live wiki.

Wikilinks as first-class edges

Wikilinks in Wikantik are parsed from page bodies at save time by ReferenceManager. The resulting edges are queryable: you can ask "which pages link to this one?" (backlinks) and "which pages does this one link to?" (outbound links). Both are available via the REST API at /api/pages/{slug}/backlinks and via the get_backlinks / get_outbound_links MCP tools on /wikantik-admin-mcp.

The backlink graph powers several visible features:

• Broken-link triage — when a page is deleted or renamed without updating links, affected pages surface in /admin/page-graph/*
• Orphan detection — pages with no inbound links from other pages in the same cluster are flagged by the agent-grade audit
• Inbound link centrality — used by AgentHintsDeriver to rank pages in the prefer_pages hint on agent projections

Canonical IDs: rename-stable page identity

Renaming a page — a perfectly normal editorial act — breaks every external reference to the old slug. Wikantik solves this with canonical_id: a 26-character ULID assigned to each page at first save and immutable thereafter, stored in frontmatter and in the page_canonical_ids database table.

The endpoint GET /api/pages/by-id/{canonical_id} resolves a canonical ID to the current page regardless of any renames that have occurred since the ID was assigned. Slug rename history is tracked in page_slug_history for audit purposes. External systems — integrations, agent memory stores, citation databases — that reference a page by canonical ID instead of slug are rename-proof.

Canonical ID assignment is enforced at save time: if a page lacks a canonical_id in its frontmatter, StructuralSpinePageFilter automatically assigns one and injects it before the page is saved.

Clusters and hubs

Every page declares a cluster: in its frontmatter, assigning it to a logical topic area. Within each cluster, one page is designated the hub — the entry point that links to all cluster articles and provides the overview. The rest are articles.

Cluster membership is the primary navigation structure for agents: list_clusters on the /knowledge-mcp server returns all clusters with their hub page, article count, and last-updated timestamp. list_pages_by_filter lets agents filter by cluster, type, tag, or update time. This is how an agent asks "what does this wiki contain?" without doing a full-text search.

Page Graph vs. Knowledge Graph

These are distinct subsystems and must not be confused. The Page Graph's nodes are pages; its edges are wikilinks authors wrote. The Knowledge Graph's nodes are LLM-extracted entities (concepts, people, technologies); its edges are co-mention or typed-relation predicates. They live in separate code packages (com.wikantik.pagegraph.* vs com.wikantik.knowledge.*), separate database tables (page_canonical_ids vs kg_*), and serve different purposes: navigation vs. semantic retrieval.

Frequently asked questions

What makes Page Graph edges different from Knowledge Graph edges?

Page Graph edges are real wikilinks that an author literally typed in a page body. Knowledge Graph edges are LLM-extracted predicates between entity nodes. They serve different purposes and live in separate subsystems — the Page Graph is for navigation and authoring; the Knowledge Graph is for semantic retrieval and agent reasoning.

What happens to wikilinks when a page is renamed?

Each page has a canonical_id — a 26-character ULID assigned at first save and immutable thereafter. External references can use the canonical ID instead of the slug; GET /api/pages/by-id/{canonical_id} resolves to the current page regardless of renames. The slug history is also tracked in page_slug_history.

How do agents navigate the Page Graph?

The /knowledge-mcp server exposes structural spine tools — list_clusters, list_pages_by_filter, get_page_by_id, and a sitemap endpoint — that let agents navigate by cluster membership, type, and canonical ID. The /api/structure/* REST endpoints serve the same data for non-MCP clients.