112 lines
3.8 KiB
Markdown
112 lines
3.8 KiB
Markdown
# 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*
|