knowledge-base

# Knowledge Base (Wiki)

You maintain a **compounding knowledge base**: a wiki of interlinked markdown
notes that lives in the workspace. Unlike a chat that forgets, the wiki is
written once and kept correct — every new source is folded into existing
pages and cross-referenced, so the knowledge graph gets denser over time. The
files are plain markdown with `[[wikilinks]]`, so the user can also open them
in Obsidian or any editor.

## When to use

- "Set up a knowledge base / wiki", "start a company wiki", "organize my notes".
- "Add this to the wiki", "ingest this article/doc/page", "remember this for the team".
- A question that the wiki should answer ("what do we know about X?").
- "Audit / lint / health-check the wiki", "find broken links / orphans".

## When NOT to use

- One-off facts about the user or your own behavior → that's **memory** (retain), not the wiki.
- Throwaway scratch work, or content the user doesn't want kept.

## Layout

The wiki lives under `wiki/` in the workspace (use an existing root such as
`knowledge-base/` if one is already there). Structure:

```
wiki/
├── SCHEMA.md     # the domain, conventions, and tag taxonomy — defined once
├── index.md      # catalog of every page, grouped by type, each with a one-line summary
├── log.md        # append-only action log (newest entries at the bottom)
├── raw/          # captured sources, IMMUTABLE — you read these, never edit them
│   ├── articles/
│   ├── docs/
│   └── transcripts/
└── pages/        # the wiki pages (one entity/concept/comparison/query each)
```

Page filenames are **lowercase, hyphenated slugs, no spaces**: `acme-robotics.md`,
`atlas-robot.md`. A `[[Display Name]]` link resolves to the page whose slug
equals the slugified display name, so `[[Acme Robotics]]` and `[[acme-robotics]]`
both point at `pages/acme-robotics.md`.

## Reading the wiki

When the user asks how to read or browse what you've built, tell them: it's
plain markdown they can open in any editor, and the pages are **Obsidian-native
by design** — they can open the `wiki/` folder as an Obsidian vault to get graph
view, backlinks, and clickable `[[wikilinks]]` for free. (The files live in the
workspace, so point the vault at the workspace `wiki/` folder.)

## Frontmatter contract (mandatory on every page)

```yaml
---
title: Acme Robotics
created: 2026-06-05      # YYYY-MM-DD
updated: 2026-06-05      # YYYY-MM-DD — bump on every edit
type: entity             # entity | concept | comparison | query | summary
tags: [companies, robotics]   # every tag MUST appear in SCHEMA.md's taxonomy
sources: [raw/articles/acme-launch.md]   # the raw/ files this page draws on
# optional:
confidence: high         # high | medium | low
contested: true          # set when the page records a genuine contradiction
contradictions: [other-slug]
---
```

## Linking rules

- Use `[[slug]]` (or `[[slug|alias]]`) for every cross-reference. Link the
  first mention of any entity/concept that has (or should have) its own page.
- **Minimum 2 outbound links per page**, including a link back to a hub page
  or `[[index]]` where it helps navigation.
- **Bidirectional**: when page A links to B, make sure B links back to A when
  the relationship is real (e.g. a company links its CEO and the CEO links the
  company). The lint reports one-directional links so you can reciprocate them.
- **Provenance**: list every `raw/` file the page draws on in `sources:`.

## Page thresholds

- Create a page when an entity/concept appears in **2+ sources**, or is
  **central to one** source. Don't create pages for passing mentions.
- Split a page that grows past ~200 lines into focused sub-pages and link them.

## Operations

### 0. Orient (ALWAYS do this first)

Before creating or editing anything, read the lay of the land so you don't
duplicate pages or drift from the schema:

1. `file_read wiki/SCHEMA.md` — the domain + conventions + tag taxonomy.
2. `file_read wiki/index.md` — what pages already exist.
3. `file_read wiki/log.md` — recent activity (skim the tail).

If `wiki/` does not exist yet, go to **Init**.

### 1. Init (no wiki yet)

1. Create `wiki/` with `raw/` and `pages/` subfolders.
2. Write `SCHEMA.md`: a one-paragraph description of the domain, the naming +
   linking conventions (summarize this skill), and a **tag taxonomy** of
   10–20 lowercase tags under a `## Tag taxonomy` heading, one per `- ` bullet.
   If the domain is unclear, ask the user one question to scope it.
3. Write an empty-ish `index.md` (an `# Index` heading) and `log.md` (`# Log`).

### 2. Ingest a source

A source is anything worth remembering. The wiki is source-agnostic — use
whatever surface fits: a **URL** (fetch it with `web_fetch`), a **chat-attached
file** (PDFs, Word, and spreadsheets are extracted to text), **pasted notes**,
or something you found with `web_search`. The steps are the same regardless.

1. **Orient** (step 0).
2. **Capture the source** verbatim into `raw/` (e.g. `raw/articles/<slug>.md`)
   with a tiny header (`source_url` when there is one, `ingested` date). Fetch a
   URL with `web_fetch` first. Never edit a file in `raw/` afterward —
   corrections go on the wiki pages, not the source.
3. **Extract** the entities/concepts worth pages (apply the threshold above).
4. For each, **check for an existing page**: `file_search` the name and scan
   `index.md`. Update the existing page rather than creating a duplicate.
5. **Create or update** pages with full frontmatter, `[[links]]`, and the new
   `raw/` path appended to `sources:`. Bump `updated:`.
6. **Reciprocate links** on the pages you touched (bidirectional rule).
7. **Update `index.md`** (add new pages under their type, with a one-line
   summary) and **append to `log.md`** (`- 2026-06-05 — ingested <source>; added/updated <pages>`).
8. **Lint and fix** (step 4).

### 3. Query the wiki

1. **Orient** (step 0).
2. `file_search` for relevant pages; `file_read` the best matches.
3. Synthesize an answer, citing pages with `[[links]]