LLM Wiki Agent — Schema & Workflow Instructions

This wiki is maintained entirely by your coding agent. No API key or Python scripts needed — just open this repo in Codex, OpenCode, or any agent that reads this file, and talk to it.

How to Use

Describe what you want in plain English:

"Ingest this file: raw/papers/my-paper.md"
"What does the wiki say about transformer models?"
"Check the wiki for orphan pages and contradictions"
"Build the knowledge graph"

Or use shorthand triggers:

ingest <file> → runs the Ingest Workflow
query: <question> → runs the Query Workflow
health → runs the Health Workflow (fast, every session)
lint → runs the Lint Workflow (expensive, periodic)
build graph → runs the Graph Workflow

Directory Layout

raw/          # Immutable source documents — never modify these
wiki/         # Agent owns this layer entirely
  index.md    # Catalog of all pages — update on every ingest
  log.md      # Append-only chronological record
  overview.md # Living synthesis across all sources
  sources/    # One summary page per source document
  entities/   # People, companies, projects, products
  concepts/   # Ideas, frameworks, methods, theories
  syntheses/  # Saved query answers
graph/        # Auto-generated graph data
tools/        # Standalone Python scripts
  health.py   # Structural checks (deterministic, no LLM calls)
  lint.py     # Content quality checks (uses LLM for semantic analysis)
  build_graph.py  # Knowledge graph generation

Page Format

Every wiki page uses this frontmatter:

---
title: "Page Title"
type: source | entity | concept | synthesis
tags: []
sources: []       # list of source slugs that inform this page
last_updated: YYYY-MM-DD
---

Use [[PageName]] wikilinks to link to other wiki pages.

Ingest Workflow

Triggered by: "ingest "

Supported formats: Markdown (.md) is ingested directly. Non-markdown files (.pdf, .docx, .pptx, .xlsx, .html, .txt, .csv, .json, .xml, .rst, .rtf, .epub, .ipynb, .yaml, .yml, .tsv, .wav, .mp3) are auto-converted to markdown via markitdown before ingestion. Use --no-convert to skip auto-conversion.

Steps (in order):

Read the source document fully (auto-convert if non-markdown)
Read wiki/index.md and wiki/overview.md for current wiki context
Write wiki/sources/<slug>.md — use the source page format below
Update wiki/index.md — add entry under Sources section
Update wiki/overview.md — revise synthesis if warranted
Update/create entity pages for key people, companies, projects mentioned
Update/create concept pages for key ideas and frameworks discussed
Flag any contradictions with existing wiki content
Append to wiki/log.md: ## [YYYY-MM-DD] ingest | <Title>
Post-ingest validation — check for broken [[wikilinks]], verify all new pages are in index.md, print a change summary

Source Page Format

---
title: "Source Title"
type: source
tags: []
date: YYYY-MM-DD
source_file: raw/...
---

## Summary
2–4 sentence summary.

## Key Claims
- Claim 1
- Claim 2

## Key Quotes
> "Quote here" — context

## Connections
- [[EntityName]] — how they relate
- [[ConceptName]] — how it connects

## Contradictions
- Contradicts [[OtherPage]] on: ...

Domain-Specific Templates

If the source falls into a specific domain (e.g., personal diary, meeting notes), the agent should use a specialized template instead of the default generic one above:

Diary / Journal Template

---
title: "YYYY-MM-DD Diary"
type: source
tags: [diary]
date: YYYY-MM-DD
---
## Event Summary
...
## Key Decisions
...
## Energy & Mood
...
## Connections
...
## Shifts & Contradictions
...

Meeting Notes Template

---
title: "Meeting Title"
type: source
tags: [meeting]
date: YYYY-MM-DD
---
## Goal
...
## Key Discussions
...
## Decisions Made
...
## Action Items
...

Query Workflow

Triggered by: "query: "

Steps:

Read wiki/index.md to identify relevant pages
Read those pages
Synthesize an answer with inline citations as [[PageName]] wikilinks
Ask the user if they want the answer filed as wiki/syntheses/<slug>.md

Lint Workflow

Triggered by: "lint"

Check for:

Orphan pages — wiki pages with no inbound [[links]] from other pages
Broken links — [[WikiLinks]] pointing to pages that don't exist
Contradictions — claims that conflict across pages
Stale summaries — pages not updated after newer sources
Missing entity pages — entities mentioned in 3+ pages but lacking their own page
Sparse pages — pages with fewer than 2 outbound [[wikilinks]] (link density budget)
Data gaps — questions the wiki can't answer; suggest new sources

Graph-aware checks (require graph.json from build graph):

Hub stubs — god nodes (degree > μ+2σ) with thin content (< 500 chars)
Fragile bridges — community pairs connected by only 1 edge
Isolated communities — clusters with zero external connections

Output a lint report and ask if the user wants it saved to wiki/lint-report.md.

Health Workflow

Triggered by: "health"

Run: python tools/health.py (or python tools/health.py --json for machine-readable output)

Fast structural integrity checks — zero LLM calls, safe to run every session:

Empty / stub files — pages with no content beyond frontmatter (rate-limit damage)
Index sync — wiki/index.md entries vs actual files on disk
Log coverage — source pages missing a corresponding ingest entry in wiki/log.md

Output a health report. Use --save to write to wiki/health-report.md.

Health vs Lint Boundary

Dimension	`health`	`lint`
Scope	Structural integrity	Content quality
LLM calls	Zero	Yes (semantic analysis)
Cost	Free	Tokens
Frequency	Every session, before other work	Every 10-15 ingests
Checks	Empty files, index sync, log sync	Orphans, broken links, contradictions, gaps
Tool	`tools/health.py`	`tools/lint.py`
Run order	First (pre-flight)	After health passes

Run health first — linting an empty file wastes tokens.

Graph Workflow

Triggered by: "build graph"

First try: python tools/build_graph.py --open

If Python/deps unavailable, build manually:

Search for all [[wikilinks]] across wiki pages
Build nodes (one per page) and edges (one per link)
Infer implicit relationships not captured by wikilinks — tag INFERRED with confidence score; low confidence → AMBIGUOUS
Write graph/graph.json with {nodes, edges, built: date}
Write graph/graph.html as a self-contained vis.js visualization

Naming Conventions

Source slugs: kebab-case matching source filename
Entity pages: TitleCase.md (e.g. OpenAI.md, SamAltman.md)
Concept pages: TitleCase.md (e.g. ReinforcementLearning.md, RAG.md)

Index Format

# Wiki Index

## Overview
- [Overview](overview.md) — living synthesis

## Sources
- [Source Title](sources/slug.md) — one-line summary

## Entities
- [Entity Name](entities/EntityName.md) — one-line description

## Concepts
- [Concept Name](concepts/ConceptName.md) — one-line description

## Syntheses
- [Analysis Title](syntheses/slug.md) — what question it answers

Log Format

## [YYYY-MM-DD] <operation> | <title>

Operations: ingest, query, health, lint, graph, report

Graph Health Report

Triggered by: "graph report" or python tools/build_graph.py --report

The --report flag generates a structured graph health report covering:

Health summary — edges/node ratio, orphan %, community count, link density
Orphan nodes — pages with zero graph connections
God nodes — hub pages with degree > μ+2σ (disproportionate connectivity)
Fragile bridges — community pairs connected by only 1 edge
Phantom hubs — [[wikilinks]] referenced by 2+ existing pages but pointing to non-existent pages (page creation signals)

Use --save to write the report to graph/graph-report.md.

Phase 3 Design Constraints (Auto-Linking — Open)

Phase 3 proposes automatic [[wikilink]] insertion based on graph analysis. The following hard rules apply:

Promotion Gate: `draft → stable`

Auto-linked edges start as DRAFT (visible in graph, not written to page body)
A dedicated promote pass validates source grounding + consistency
Only edges that pass get materialized as [[wikilinks]] in the page
Link density budget: a page must have ≥2 outbound wikilinks before promotion

Hard Rules

ID	Rule	Rationale
HG-WA-01	Graph layer MUST NOT auto-create pages from broken links — report only	LLM ingest produces hallucinated wikilinks; auto-creating amplifies noise
HG-WA-02	New slash commands MUST NOT duplicate existing command coverage	Prevents user confusion; merge into existing commands instead

Navigation Menu

Repository navigation

AGENTS.md

AGENTS.md

LLM Wiki Agent — Schema & Workflow Instructions

How to Use

Directory Layout

Page Format

Ingest Workflow

Source Page Format

Domain-Specific Templates

Diary / Journal Template

Meeting Notes Template

Query Workflow

Lint Workflow

Health Workflow

Health vs Lint Boundary

Graph Workflow

Naming Conventions

Index Format

Log Format

Graph Health Report

Phase 3 Design Constraints (Auto-Linking — Open)

Promotion Gate: `draft → stable`

Hard Rules

FilesExpand file tree

AGENTS.md

Latest commit

History

AGENTS.md

File metadata and controls

LLM Wiki Agent — Schema & Workflow Instructions

How to Use

Directory Layout

Page Format

Ingest Workflow

Source Page Format

Domain-Specific Templates

Diary / Journal Template

Meeting Notes Template

Query Workflow

Lint Workflow

Health Workflow

Health vs Lint Boundary

Graph Workflow

Naming Conventions

Index Format

Log Format

Graph Health Report

Phase 3 Design Constraints (Auto-Linking — Open)

Promotion Gate: draft → stable

Hard Rules

Promotion Gate: `draft → stable`