llm-wiki/schema/AGENTS.md

AGENTS.md — LLM Wiki Schema

This file tells the LLM agent how to maintain the wiki. Share this with your LLM agent (Hermes, Codex, Claude Code, etc.) so it knows the conventions, structure, and workflows.

Wiki Structure

docs/
├── index.md              # Welcome page + quick-start guide
├── mkdocs.yml            # MkDocs configuration (theme, nav, plugins)
├── wiki/                 # LLM-generated content pages
│   ├── index.md          # Wiki index / category listing
│   ├── entities/         # Entity pages (people, places, systems)
│   ├── concepts/         # Concept pages (ideas, theories, patterns)
│   ├── comparisons/      # Comparison / analysis pages
│   └── syntheses/        # Integrated overviews across sources
├── sources/              # Ingested source summaries
│   └── index.md          # Source catalog (table)
├── raw/                  # Raw source files (immutable)
│   └── index.md          # Raw directory index
└── log.md                # Append-only changelog

Conventions

Page format

---
tags: [tag1, tag2]
created: YYYY-MM-DD
updated: YYYY-MM-DD
sources: [source-filename-1, source-filename-2]
---

# Page Title

Summary paragraph.

## Section

Content with [[wiki/entities/related-page]] internal links.

## Sources
- [Source Title](../sources/source-summary.md)

Internal links

Use relative markdown links: [[wiki/concepts/some-topic]] or [text](../wiki/entities/page.md). Always link to wiki pages, never to raw sources, from within wiki content.

Tags

Use lowercase, hyphenated tags in frontmatter. Add or update tags as the wiki grows.

Dates

Use YYYY-MM-DD format consistently.

Workflows

Ingest a new source

1. Read the source file from raw/
2. If images are referenced, also examine them with the vision tool for additional context
3. Discuss key takeaways with the user
4. Write a summary page in sources/ (with link to the raw file)
5. Create or update relevant entity/concept pages in wiki/
6. Update wiki/index.md and sources/index.md
7. Append an entry to log.md with the ## [YYYY-MM-DD] ingest | Title format
8. Update mkdocs.yml nav: section if new top-level pages were added

Answer a query

1. Read sources/index.md and/or wiki/index.md to find relevant pages
2. Read the relevant pages
3. Synthesize an answer with citations to wiki pages
4. Offer to save the answer as a new wiki page: "Shall I file this as a comparison/synthesis page?"

Lint the wiki

Periodically check for:

• Contradictions between pages
• Stale claims that newer sources have superseded
• Orphan pages with no inbound links
• Important concepts mentioned but lacking their own page
• Missing cross-references
• Data gaps that could be filled with a web search

Write a page

Pages should be informative, well-structured, and cross-linked. Use admonitions for notes, warnings, or open questions:

[!note] Open question The relationship between X and Y is not yet clear from available sources.

[!warning] Conflicting claims Source A claims Z, but source B says ¬Z. This needs further investigation.

Tools available

• raw/ directory: read-only source files
• wiki/ directory: create, update, or reorganize wiki pages
• sources/ directory: write source summaries
• log.md: append entries (never edit existing entries)
• mkdocs.yml: update nav section as the wiki grows
• Web search: fill data gaps identified during lint
• Terminal: git operations for version control

Git workflow

The wiki is a git repository. After each ingest or significant update:

cd /docs && git add -A && git commit -m "ingest: [title] — YYYY-MM-DD"

This schema was initialized from Karpathy's LLM Wiki pattern: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f