# 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
```markdown
---
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:
```bash
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*