# TRM Wiki — Schema & Conventions

This repo is an LLM-maintained wiki. The human curates sources and asks questions. You (the LLM) own all wiki pages: you write them, update them, and keep them consistent.

## Layout

```
docs/
├── CLAUDE.md         # this file — schema and workflows
├── index.md          # content catalog (you maintain)
├── log.md            # chronological activity log (you append to)
├── raw/              # immutable source documents — READ ONLY
└── wiki/             # all LLM-generated pages live here
    ├── sources/      # one page per ingested source
    ├── entities/     # people, orgs, products, places
    ├── concepts/     # ideas, topics, themes
    └── synthesis/    # comparisons, analyses, overview pages
```

Rules:
- **Never modify anything in `raw/`.** Treat it as immutable source of truth.
- **Never edit the wiki by hand is the user's expectation** — but the user may occasionally. If you see human edits, respect them.
- All wiki pages are markdown with YAML frontmatter (see below).
- Use Obsidian-style `[[wikilinks]]` for cross-references between wiki pages. Use standard markdown links for external URLs and for links into `raw/`.

## Page frontmatter

Every page in `wiki/` starts with frontmatter:

```yaml
---
title: <page title>
type: source | entity | concept | synthesis
created: YYYY-MM-DD
updated: YYYY-MM-DD
sources: [<source-page-name>, ...]   # which sources contribute to this page
tags: [<tag>, ...]
---
```

For `type: source` pages, also include:
```yaml
source_path: raw/<filename>
source_date: YYYY-MM-DD   # date of the original document, if known
source_kind: article | paper | transcript | note | image | other
```

## Workflows

### Ingest (when user says "ingest X" or drops a new file in raw/)

1. Read the source from `raw/`.
2. Briefly discuss key takeaways with the user before writing — confirm what to emphasize.
3. Create `wiki/sources/<slug>.md` with:
   - Frontmatter (type: source).
   - One-paragraph TL;DR.
   - Key claims / facts as a bulleted list, each with enough context to stand alone.
   - Notable quotes (verbatim, with location if available).
   - Open questions or things to follow up on.
4. For each entity or concept the source touches:
   - If a page exists in `wiki/entities/` or `wiki/concepts/`, update it: add new facts, link the new source in `sources:` frontmatter, flag contradictions with existing claims explicitly (don't silently overwrite).
   - If no page exists and the entity/concept is substantive, create one.
5. Update `index.md` — add the new source row and any new entity/concept rows.
6. Append an entry to `log.md`.

A single ingest typically touches 5–15 wiki files. That's expected.

### Query (when user asks a question)

1. Read `index.md` first to locate relevant pages.
2. Read those pages (and follow wikilinks as needed).
3. Answer with citations: link `[[page-name]]` for wiki pages, and reference the underlying source pages so the user can trace claims back to `raw/`.
4. If the answer is substantive (a comparison, an analysis, a new connection), offer to file it into `wiki/synthesis/` as a new page. Don't file by default — ask first.
5. If the wiki can't answer the question, say so plainly. Suggest what source would fill the gap.

### Lint (when user says "lint" or "health-check")

Scan the wiki for:
- Contradictions between pages (same claim, different values).
- Stale claims newer sources have superseded.
- Orphan pages (no inbound wikilinks).
- Concepts mentioned in 3+ pages but lacking their own page.
- Missing cross-references (entity X mentioned on page Y but not linked).
- Frontmatter drift (missing fields, wrong types).

Report findings as a checklist. Don't fix automatically — confirm with the user first.

## Log format

`log.md` is append-only. Each entry starts with a header line in this exact format so it's grep-able:

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

Where `<op>` is one of: `ingest`, `query`, `lint`, `synthesis`, `note`. Body underneath is 1–5 lines: what happened, what files changed.

Example:
```
## [2026-04-30] ingest | Acme Q1 earnings call transcript

Created wiki/sources/acme-q1-earnings.md. Updated [[Acme]], [[revenue-recognition]].
Flagged contradiction with [[acme-2025-guidance]] re: margin outlook.
```

## Index format

`index.md` is a content catalog organized by section: Sources, Entities, Concepts, Synthesis. Each row: `- [[page-name]] — one-line summary`. Keep summaries tight. Re-sort alphabetically within each section after edits.

## Style

- Wiki pages should be readable on their own. Don't write "as discussed above" — there's no above for someone landing via search.
- Prefer short, declarative sentences over hedged prose. Where uncertainty matters, say so explicitly with a `> note:` callout.
- Quote sparingly and verbatim. Paraphrase by default.
- When new information conflicts with an existing page, do not silently overwrite. Add the new claim, mark the conflict, and let the user adjudicate.