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)

---
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]]. If the wiki can't answer it, say so (and offer to ingest a source that would).
4. If the answer is reusable, file it as a type: query page under pages/ and add it to the index + log.

4. Lint (audit integrity) — run after every ingest, and on demand

skill_run({ skill: "knowledge-base", script: "lint", args: { root: "wiki" } })

It returns JSON: clean, totalIssues, counts, and per-check arrays. clean / totalIssues count only the blocking checks below; fix every blocking issue with file_write / file_patch and re-run until clean is true.

Blocking (gate clean):

• brokenLinks → create the missing page, or fix/remove the link.
• orphans → link the page from a related page (not just the index).
• duplicateSlugs → two files share a slug; rename one (a slug must be unique).
• missingFromIndex / indexEntriesWithoutPage → reconcile index.md.
• frontmatter → add the missing/invalid keys; ensure ≥2 resolved outbound links.
• oversized → split the page into focused sub-pages and link them.
• unknownTagsUsed → add the tag to SCHEMA.md's taxonomy first, or retag the page.
• nonSlugFilenames → rename to a lowercase-hyphen slug (rewrite the file at the new path and update links/index).

Advisory (reported but do NOT gate clean — act on them with judgment):

• backlinkAsymmetry → add the reciprocal link where the relationship is real; many one-directional links are legitimate, so don't force every pair.
• stale → re-check the page against its sources and bump updated if it still holds.

Conflict handling

When a new source contradicts an existing page, do NOT silently overwrite: check the dates, keep both positions with their sources if the contradiction is real, set contested: true and contradictions: [other-slug] in frontmatter, and call it out to the user for review.

Rules

• Orient before you write. Always read SCHEMA + index + log tail first.
• Never edit raw/. It is the immutable source layer.
• Always update index.md and log.md — they are the wiki's navigation and history.
• Frontmatter is mandatory on every page; every tag must be in the taxonomy.
• Lint after every ingest and fix until clean.
• Keep pages scannable (< ~200 lines); handle contradictions explicitly.