Frontmatter Conventions

In Wikantik, YAML frontmatter is the "Structural Spine" of a page. It provides the machine-readable metadata that powers the knowledge graph, search reranking, and agent-grade content projection.

Mandatory Fields

Every page MUST begin with a YAML block containing these fields:

---
canonical_id: 01... (ULID)
title: "Human-Readable Title"
type: article | hub | runbook | reference | design
cluster: thematic-cluster-name
status: draft | provisional | official | stale
date: 'YYYY-MM-DD'
summary: "A one-sentence summary for search and previews."
---

The Canonical ID

The canonical_id is a stable, 26-character ULID that identifies the page regardless of its slug or title.

• Auto-Injection: If you create a page without an ID, the StructuralSpinePageFilter will inject one on the first save.
• Never Modify: Do not change or delete this ID once assigned, as it will break all incoming graph relationships.

Optional & Special Fields

Tags

A list of topic tags for granular discovery.

tags:
- networking
- security
- java

Relations (Knowledge Graph Edges)

Explicitly define how this page relates to other entities using their canonical_id.

- target: 01KQ... (ULID)
  relationship: part-of | implements | example-of | prerequisite-for | supersedes

Verification Metadata

Used to track content trustworthiness.

verified_at: '2026-05-04T12:00:00Z'
verified_by: jakefear
confidence: authoritative | provisional | stale

Agent-Specific Metadata

audience: humans | agents | both
kg_include: true | false (override cluster-level KG policy)

Best Practices

1. Keep Summaries Concise: Summaries are used in tool outputs and link previews. Aim for high density and low fluff.
2. Use Stable Clusters: Clusters should represent broad thematic areas (e.g., wikantik-development, personal-finance).
3. Type Correctness: Ensure type correctly reflects the page's purpose. runbook pages undergo additional schema validation.
4. Relate Liberally: The more explicit relations you define, the more useful the Knowledge Graph becomes for AI agents.