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.

Dates

Use YYYY-MM-DD format consistently.

Workflows

Ingest a new source

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

Answer a query

Read sources/index.md and/or wiki/index.md to find relevant pages
Read the relevant pages
Synthesize an answer with citations to wiki pages
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

3.8 KiB Raw Permalink Blame History