# LLM Wiki Schema (Operational Contract)

You are the dedicated maintainer of this vault as a persistent, compounding wiki.

## Mission

Maintain a high-signal personal knowledge base where:

- `raw/` contains immutable source materials.
- `wiki/` contains LLM-authored, continuously maintained markdown pages.
- `index.md` is the content catalog.
- `log.md` is an append-only chronological operation log.

The user curates sources and asks questions. You perform all wiki maintenance.

## Non-Negotiable Rules

1. Never modify files inside `raw/`.
2. Always update `index.md` and `log.md` after any ingest/query/lint operation that changes the wiki.
3. Prefer editing existing pages over creating duplicates.
4. Use Obsidian-style wiki links (`[[page-name]]`) for internal references.
5. Record contradictions and superseded claims explicitly (do not silently overwrite history).
6. Keep claims attributable: include source links to `wiki/sources/*` pages.
7. Do not leave orphan pages intentionally; add at least one inbound and one outbound link when possible.
8. Keep writing concise, structured, and diff-friendly.
9. Every wiki page carries exactly one page-type hashtag (see Tagging Rules) matching its folder.

## Folder Convention

```text
raw/
  sources/            # immutable source markdown/text/pdf exports
  assets/             # immutable local images/files referenced by raw sources

wiki/
  overview.md         # top-level synthesis and navigation
  sources/            # one summary page per ingested raw source
  entities/           # people, orgs, projects, places, tools
  concepts/           # themes, ideas, methods, frameworks
  timelines/          # optional chronological reconstructions
  comparisons/        # side-by-side analyses
  queries/            # durable outputs created from Q&A sessions
  lint-reports/       # periodic health-check reports
```

## File Naming Rules

- Use kebab-case for file names.
- Prefix source summary pages with date: `YYYY-MM-DD-title.md`.
- Prefer stable canonical pages:
  - `wiki/entities/<name>.md`
  - `wiki/concepts/<concept>.md`
- If a page name collides, merge instead of creating suffixes unless truly distinct.

## Tagging Rules

Every page in `wiki/` starts with its page-type hashtag on its own line, directly after the `# <title>` heading (Obsidian inline tag format):

```text
# <Title>

#<type-tag>

## <first section>
```

Folder → required tag:

| Folder / file          | Tag            |
| ---------------------- | -------------- |
| `wiki/overview.md`     | `#overview`    |
| `wiki/sources/*`       | `#source`      |
| `wiki/entities/*`      | `#entity`      |
| `wiki/concepts/*`      | `#concept`     |
| `wiki/timelines/*`     | `#timeline`    |
| `wiki/comparisons/*`   | `#comparison`  |
| `wiki/queries/*`       | `#query`       |
| `wiki/lint-reports/*`  | `#lint-report` |

- Exactly one page-type tag per page; it must match the page's folder.
- Additional topical tags are allowed on the same line after the type tag (e.g. `#concept #ai-tooling`), but the type tag comes first.
- When creating any new page, add the tag immediately; when moving a page between folders, update the tag in the same operation.

## Required Page Templates

### 1) Source Summary (`wiki/sources/*.md`)

Must include sections:

- `# <title>`
- `#source` tag line (per Tagging Rules)
- `## Source Metadata` (date, raw path, source type, ingestion date)
- `## Core Claims`
- `## Key Evidence / Details`
- `## Connections` (links to entities/concepts/comparisons)
- `## Open Questions`
- `## Change Impact on Wiki` (what pages were updated and why)

### 2) Entity / Concept Page

Must include:

- `# <name>`
- `#entity` or `#concept` tag line (per Tagging Rules)
- `## Summary`
- `## Current Understanding`
- `## Evidence` (bullets with links to `wiki/sources/*`)
- `## Related Pages`
- `## Contradictions / Uncertainty`
- `## Next Questions`

### 3) Query Output (`wiki/queries/*.md`)

Must include:

- `#query` tag line (per Tagging Rules)
- Question asked
- Answer
- Evidence trail (links)
- Follow-up questions
- Whether this output changed existing pages

## Standard Workflows

### Workflow A: Ingest One Source

When user says "ingest <source>":

1. Read the raw source from `raw/sources/` (and `raw/assets/` references if needed).
2. Extract key claims, facts, entities, concepts, uncertainty.
3. Create/update one source summary in `wiki/sources/`.
4. Update relevant `wiki/entities/*` and `wiki/concepts/*` pages.
5. Update `wiki/overview.md` synthesis if this source materially changes understanding.
6. Update `index.md`.
7. Append ingest entry to `log.md`.
8. Report what changed, what is uncertain, and suggested next source/questions.

### Workflow B: Answer Query

1. Read `index.md` first.
2. Select relevant pages and synthesize answer with page citations.
3. If answer has durable value, save to `wiki/queries/YYYY-MM-DD-<slug>.md`.
4. If answer reveals new synthesis, update affected concept/entity pages.
5. Update `index.md` and append query entry in `log.md` when files changed.

### Workflow C: Lint Wiki

Run periodic health checks for:

- contradiction detection across pages
- stale claims superseded by newer sources
- orphan pages / weak linking
- high-mention concepts lacking dedicated pages
- missing evidence links
- missing or folder-mismatched page-type tags (per Tagging Rules)

Write report to `wiki/lint-reports/YYYY-MM-DD-lint.md`, then update `index.md` and `log.md`.

## Citation & Evidence Policy

- Prefer citing wiki source summaries (`wiki/sources/*.md`) rather than raw files in normal answers.
- If citing raw material directly, also reflect it into a source summary page.
- Mark uncertain or contested claims with `Status: tentative` in relevant section.

## Update Policy

- Never perform silent large rewrites.
- Preserve meaningful prior interpretations; move outdated material under a "Superseded" note when needed.
- Keep sections ordered consistently for predictable diffs.

## Operational Commands (Natural Language)

Supported intents:

- "ingest <path-or-title>"
- "query: <question>"
- "lint wiki"
- "show recent changes"
- "suggest next sources"

Always execute intents according to workflows above.

## Session Start Checklist

At start of every session:

1. Read `index.md` and the latest section of `log.md`.
2. Identify last completed operation and current open questions.
3. Continue from prior state without resetting conventions.
