workflowindexbacklinksmaintenancestateUpdated 2026-07-01

Build Index Workflow

Regenerate the wiki graph surfaces after source markdown changes: catalog, backlinks, README stats, and index freshness state.

npx tsx scripts/build-index.ts

Source: AGENTS.md Indexing and Logging, 2026-05-31

Side effects

  • Walks all wiki/**/*.md (except _ prefixed)
  • Parses frontmatter, wikilinks, and typed related: relationships
  • Updates _backlinks.json with mention and relationship types
  • Refreshes README Repository stats between <!-- repo-stats:auto:start/end --> markers (never edit that table by hand)
  • Updates state.json timestamps via updateState

This workflow is a generated-surface refresh. The source of truth is the handwritten page graph, not _index.md or _backlinks.json. If a generated row is wrong, fix the source page or generator, then rerun the command. Source: Generated Surface Contract, 2026-07-01

What counts as success

A successful run leaves these files consistent with disk:

  • wiki/_index.md includes every page that should be findable.
  • wiki/_backlinks.json reflects current wikilinks and typed relationships.
  • Root README.md stats match the current repository.
  • state.json records the index refresh.
  • No manual ## Backlinks sections were added to pages.

The index is a compiled artifact, not prose. Edit source pages, not generated index sections.

When to run

After any ingest, new category expansion, page move, merge, delete, or bulk page creation. Always follow with QMD Embed Workflow so search matches disk.

Also run after:

  • renaming or moving wiki pages
  • changing frontmatter fields used by the UI
  • adding or removing wikilinks
  • editing directory READMEs or resolver pages
  • deleting pages during deduplication

Failure handling

If build-index fails, do not continue to qmd embed. Fix the structural issue first. Common causes are malformed frontmatter, invalid relationship shapes, duplicate generated markers in README, or a page path the script cannot parse. After fixing, rerun build-index, then doctor, then qmd.

If the command succeeds but produces unexpected generated diffs, inspect the source pages and generator before hand-editing output. Generated files are allowed to change during broad wiki maintenance; mystery diffs are a prompt to verify ownership, not to delete the evidence.

Run Contract

This workflow follows Workflow Run Contract: name the sources, write output or no-op proof, promote only durable facts, update state only when the run really completed, refresh generated surfaces when durable pages or skills change, and log user-visible work.

Timeline

Related Pages

Index Logging ProtocolBacklink Index ProtocolQMD Embed WorkflowWiki Lint WorkflowWorkflow Run ContractGenerated Surface Contract

9 pages link here

Capture Ingest WorkflowWorkflowsEmail Sync WorkflowWorkflowsGraphify Sidecar WorkflowWorkflowsProject Briefing WorkflowWorkflowsQMD Embed WorkflowWorkflowsSlack Sync WorkflowWorkflowsSub-Daily Ingest WorkflowWorkflowsWiki Lint WorkflowWorkflowsWorkflows FilingFiling Decision Tree