A canonical_id is a 26-character ULID. It is assigned when the page is
first saved (the structural-spine save filter auto-injects it, controlled by
wikantik.structural_spine.enforcement.enabled, default true) and stays
with the page across every rename. Slugs are routes; canonical_ids are
identity.
Whenever you write a wiki citation that another process or another session might read.
The structural index maintains a page_canonical_ids table that maps
canonical_id → current_slug, plus a page_slug_history audit trail of
every previous slug. This is why /api/pages/by-id/{canonical_id} (and
get_page_by_id on /knowledge-mcp) keep working after a rename — the
index resolves through the mapping table. Both treat a page the caller may
not view as nonexistent. The slug history is a record only: nothing resolves
an old slug to the new page, so a stale slug is simply a dead name.
For human-facing links in prose, a page name is fine as long as it is
current: rename_page rewrites in-wiki referrers when updateLinks is true
(the default), but a name stored outside the wiki, or in another session's
memory, keeps the old spelling. For machine-readable identity, only
canonical_ids will do. The frontmatter steps are the lookup procedure.
To cite a specific passage rather than a whole page, use a cite:// link: a
Markdown link whose address is cite:// plus the target's canonical_id, an
optional heading path and an optional quoted span of the exact words you rely
on. The shape is below, written with a space after the closing bracket so that
this page does not itself record a citation; write it without the space:
[claim text] (cite://<canonical_id>/<Heading>/<Subheading> "exact words you rely on")
When a page is saved the wiki records each citation with the version of the
target it saw and grades it current, stale (the heading is gone or the span
no longer appears) or target_missing, and it re-grades whenever the target is
saved. Readers see an ordinary link; curators find stale ones with
list_stale_citations on /knowledge-mcp and GET /admin/drift/citations.
Tracking is on by default (wikantik.citations.enabled) and needs the database.
The parser is a plain pattern match over the page body, so an example written
as a real link, even inside a code block, is still recorded as a citation.
Sections returned by assemble_bundle carry a similar handle: the page's
canonicalId, its version, the headingPath and a span hash. Cite the page
together with that version (for example AuthenticationArchitecture @ 4).
The frontmatter pitfalls are the recurring failure modes. The most
expensive is caching slug→canonical_id mappings in long-lived agent
memory: when a page renames, the cached slug is wrong forever.
Cluster Hub: Agent Cookbook (agent-cookbook)