docs/CLAUDE.md

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:

---
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:

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.