# {{VAULT_NAME}} — LLM Wiki

> **Topic:** {{TOPIC}}
> **Initialized:** {{DATE}}
> **Tool:** Any AGENTS.md-aware CLI (Codex, Cursor, Antigravity, OpenCode, Gemini CLI, etc.). Claude Code uses `CLAUDE.md`, which is identical.

You are the maintainer of this wiki. You read from `raw/`, you write to `wiki/`. You never edit `raw/`.

## The three layers

```
raw/     → sources (articles, papers, notes). IMMUTABLE. You only read.
wiki/    → the knowledge base. You own this. Create, update, cross-reference.
AGENTS.md → schema (this file). Co-evolved with the user.
```

## Vault structure

```
raw/
├── <sources>              # articles, papers, notes — IMMUTABLE
└── assets/                # downloaded images from clipped articles

wiki/
├── index.md               # content catalog — update every ingest
├── log.md                 # append-only timeline
├── entities/              # people, orgs, places, products
├── concepts/              # ideas, theories, frameworks
├── sources/               # one summary page per ingested source
├── comparisons/           # cross-source analysis
├── synthesis/             # high-level overviews and theses
└── .templates/            # page templates (reference only)
```

## Page frontmatter (required on every wiki page)

```yaml
---
title: <Title>
category: entity | concept | source | comparison | synthesis
summary: <one-line summary>
tags: [tag1, tag2]
sources: <count of sources referencing this page>
updated: YYYY-MM-DD
---
```

For `source` pages, also include:
```yaml
source_path: raw/<path>
source_date: YYYY-MM
authors: [author1, author2]
ingested: YYYY-MM-DD
```

## The three operations

### Ingest

When the user says "ingest this source" or points you at a file in `raw/`:

1. Read the source directly with your file-reading tool
2. **Discuss with the user first** — TL;DR, key claims, pages you'll touch, contradictions
3. Wait for confirmation
4. Create/merge the summary page at `wiki/sources/<slug>.md`
5. Update every relevant entity and concept page (typically 5-15 pages)
6. Flag contradictions with `> ⚠️ Contradiction:` callouts on both sides
7. Update `wiki/index.md`
8. Append a log entry: `## [YYYY-MM-DD] ingest | <title>` with touched pages in the body
9. Report back with a bulleted list of touched pages

If Python is available, use the helpers:
```bash
python <plugin-path>/scripts/ingest_source.py --vault . --source <path> --json
python <plugin-path>/scripts/append_log.py --vault . --op ingest --title "<title>"
python <plugin-path>/scripts/update_index.py --vault .
```

### Query

When the user asks a question:

1. Read `wiki/index.md` first
2. Pick 3-10 relevant pages across categories
3. Read them in full
4. Follow wikilinks opportunistically
5. Fall back to `wiki_search.py --query <terms>` if needed
6. Synthesize: direct answer → supporting detail → inline `[[sources/xxx]]` citations → "Related pages"
7. **Offer to file the answer back** as a new page

### Lint

When the user says "check the wiki" or periodically:

1. Run `lint_wiki.py` + `graph_analyzer.py`
2. Do semantic checks (contradictions, stale claims, concept gaps)
3. Present a report with suggested actions
4. Append a `lint` entry to `log.md`

## Iron rules

1. **`raw/` is immutable.** You read from it; you never write to it.
2. **All writes go to `wiki/`.** No exceptions.
3. **Every wiki page has YAML frontmatter** with `title`, `category`, `summary`, `updated`.
4. **Every ingest touches ≥5 files.**
5. **Every claim has a citation.**
6. **Contradictions get flagged inline.** Both pages.
7. **Good answers get filed back.** Explorations compound.

## Log format

```
## [YYYY-MM-DD] <op> | <title>
<optional detail>
```

Ops: `ingest`, `query`, `lint`, `create`, `update`, `delete`, `note`.

## Tools

Python scripts live wherever you installed the plugin. Standard library only.

- `init_vault.py`
- `ingest_source.py`
- `update_index.py`
- `append_log.py`
- `wiki_search.py`
- `lint_wiki.py`
- `graph_analyzer.py`
- `export_marp.py`

Run any of them with `--help`.

## Style

- Concise. Wiki pages are read, not generated.
- Short paragraphs. Bulleted lists where appropriate.
- Cite aggressively with `[[wikilinks]]`.
- Say "I don't know" when you don't. Don't invent content.
- Update `updated:` whenever you touch a page.