wiki

name	wiki
description	Maintains a project knowledge wiki at wiki/ as the agent's long-term memory, dynamically structured around the mission in wiki/_meta/mission.md. Use whenever the user shares a fact, decision, preference, requirement, or finding worth remembering; whenever the user says "remember this", "add to wiki", "we decided", "save", "note that", or "for the record"; whenever the user asks "what do we know about X", "have we considered Y", "what did we decide", "summarize what we have"; whenever a file in the project codebase contains information relevant to the mission and should be ingested; at the end of a session to consolidate findings; and at session start to load relevant context. Reads index first, deduplicates before writing, tracks provenance, appends history rather than overwriting, and creates stubs for mentioned-but-unresearched topics. Pure markdown, no embeddings, no external network.
allowed-tools	Read Write Edit Bash(tsx:*) Bash(cat:*) Bash(ls:*) Grep Glob
license	MIT
metadata	{"version":"1.1.0","author":"etienne"}

Wiki — long-term memory as a markdown knowledge base

You maintain wiki/ — a structured, mission-driven, pure-markdown knowledge base that is the project's persistent memory. The mission lives at wiki/_meta/mission.md and was written by the host application before this session started; you do not invent or modify it.

Operating principles

1. Mission first. Before any wiki operation in a session, read wiki/_meta/mission.md and wiki/_meta/taxonomy.md. Everything you write must serve the mission. Information unrelated to the mission does not belong in the wiki, no matter how interesting.
2. Read before write, every time. Before writing or updating any page, run wiki-search with the candidate title plus two to three salient terms. Decide between update existing, cross-link, or create new based on the results. Skipping this step creates duplicates that are expensive to clean up.
3. Index before drill. When answering a question from the wiki, read wiki/index.md first, then drill into the two to five most relevant pages. Do not regrep the whole tree. index.md is the entry page of the wiki — it is fully auto-generated by wiki-index.ts and contains a mission excerpt, headline stats, recently updated pages, top topics by mission relevance, meta navigation, and the full category listing. Treat it as read-only: never hand-edit it; instead, regenerate it after any batch of writes so the entry page stays current.
4. History, not overwrite. When new information conflicts with what is on a page, append the prior claim to the page's ## History section with its date and source. Never silently rewrite. Conflicts must remain visible.
5. Provenance is mandatory. Every claim's sources frontmatter entry is either {kind: conversation, turn, note} or {kind: file, path, lines}. A page with no provenance must be marked confidence: low and status: draft.
6. Stubs over silence. When a topic is mentioned but not yet researched, create a stub page rather than dropping the reference. Stubs cost almost nothing and prevent forgetting.
7. Slugs are immutable. Once a page is published, its slug never changes. Renames create a redirect in wiki/_meta/redirects.md and an aliases entry on the page.
8. No network, no embeddings. All knowledge comes from this conversation or from text files already in the project. Do not browse the web.

When to invoke wiki operations

Invoke proactively, without waiting for an explicit "save this" request, in these situations:

• The user shares a preference, decision, requirement, fact, or finding ("I want X", "we decided Y", "we should avoid Z").
• The user asks a question that the wiki could answer ("what do we know about…", "have we considered…", "what did we decide about…").
• The user uploads or points to a project file that plausibly contains mission-relevant information.
• The user uses an explicit memory phrase ("remember", "save", "add to wiki", "note", "for the record").
• The session is wrapping up and there are uncommitted findings.

When uncertain whether something is wiki-worthy, apply this rule: if the next session would be poorer without it, save it; if it is transient chat noise, do not.

Wiki layout you maintain

wiki/
├── _meta/
│   ├── mission.md            # READ-ONLY for you
│   ├── taxonomy.md           # categories + tag axes; you evolve this
│   ├── changelog.md          # append-only event log
│   ├── graph.md              # auto-generated by wiki-index
│   └── redirects.md          # old-slug → new-slug
├── index.md                  # ENTRY PAGE — auto-generated by wiki-index. Mission excerpt, stats,
│                             #   recently updated, top topics, meta nav, then all pages by category.
│                             #   Never hand-edit; regenerate after any batch of writes.
├── topics/<slug>.md          # the substantive pages
├── sources/<slug>.md         # one summary per ingested codebase file
└── queries/<yyyy-mm-dd>-<slug>.md   # filed answers worth keeping

Page frontmatter — the canonical schema

Every page under topics/, sources/, queries/ carries this header. Required fields are bold.

---
title: <Human readable>
slug: <kebab-case>
status: stub | draft | stable | deleted
confidence: high | medium | low
tags: [t1, t2, axis:value]
mission_relevance: 0..1
sources:
  - kind: conversation
    turn: <ISO-8601 timestamp>
    note: <short>
  - kind: file
    path: <relative to project root>
    lines: <"start-end" or "all">
created: <ISO-8601>
last_updated: <ISO-8601>
supersedes: []
aliases: []

# Optional — set by Adaptive Memory when active. Absent fields default to
# classification='private' and a synthesised Provenance at the service boundary.
classification: public | private | secret
provenance:
  sourceSessions: [<session-id>, ...]
  sourceEntries: [<upstream-entry-id>, ...]
  createdBy: agent | ponderer | user
  createdAt: <ISO-8601>
  updatedAt: <ISO-8601>
  inferenceTag: <ponderer-pattern-id>      # ponderer-only
---

title, slug, status, confidence, mission_relevance, created, last_updated, and at least one sources entry are required. classification and provenance are optional but should be supplied whenever the page is written through Adaptive Memory; status: deleted is reserved for wiki-delete.ts tombstones and is excluded from index.md regeneration.

Cross-linking convention

Use relative markdown links: [Walnut wood](../topics/walnut-wood.md). Every page ends with a ## Backlinks section maintained by wiki-add — never edit it by hand.

Diagrams — when to embed mermaid

Wiki pages render in the project frontend, which displays ```mermaid fenced blocks as inline SVG. You may embed mermaid diagrams in any topics/, sources/, or queries/ page when a diagram conveys structure that prose obscures.

Reach for a diagram in exactly these three situations:

• Sequences — interactions over time across multiple actors or components (request flows, ingest pipelines, auth handshakes, lifecycle of an event). Use sequenceDiagram.
• Dependencies — directed relationships between modules, services, packages, or concepts ("X depends on Y", call graphs, build order, blocker chains). Use graph LR or graph TD.
• Data models — entity shapes and relationships (tables, records, domain objects, message schemas). Use erDiagram or classDiagram.

Discipline — diagrams must earn their place:

1. Prose first. A diagram is justified only when it makes a relationship clearer than three sentences of prose would. If you can write the relationship out cleanly, do that and skip the diagram.
2. One diagram per concept, not per page. A page with five diagrams is doing prose's job badly.
3. Keep diagrams small — aim for under ~12 nodes. Split into multiple focused diagrams rather than one mega-graph.
4. Supplement, don't replace. A reader who can't render mermaid (terminal, plain-text export, grep) must still get the full story from the surrounding text. The diagram is a visual aid, not the source of truth.
5. No diagrams on status: stub or confidence: low pages. Diagram-worthy structure implies you've actually researched it.

Minimal worked snippet for a sequenceDiagram inside a page body:

The upload handler validates the file, persists it to the workspace, then notifies the ingest worker:

```mermaid
sequenceDiagram
    Client->>API: POST /upload
    API->>Workspace: write file
    API->>Ingest: enqueue(file)
    Ingest-->>API: ack
```

The six scripts

All scripts live at .claude/skills/wiki/scripts/ and run with tsx. Their stdout is structured (single JSON object per call). Always parse the JSON; do not rely on prose output.

Script	Purpose	Typical call
wiki-search.ts	Ranked search across body and frontmatter. Run before every write.	tsx <skill>/scripts/wiki-search.ts --query "mid-century sofa" --limit 10
wiki-add.ts	Add a new page or update an existing one. Handles frontmatter merge (including classification + provenance), history append, backlink maintenance.	tsx <skill>/scripts/wiki-add.ts --input /tmp/page.json
wiki-delete.ts	Soft-delete a page (sets status: deleted, appends a tombstone to _meta/redirects.md). Idempotent. Preserves the file on disk per the history-append-only principle.	tsx <skill>/scripts/wiki-delete.ts --slug brand-x --bucket topics --reason "merged into brand-y"
wiki-index.ts	Rebuilds the wiki entry page index.md (mission excerpt, stats, recently updated, top topics, meta nav, full category listing) and _meta/graph.md. Skips pages with status: deleted. Run after any batch of writes. Flags: --recent-limit N, --top-limit N, --report-orphans.	tsx <skill>/scripts/wiki-index.ts
wiki-taxonomy.ts	Diffs current pages against _meta/taxonomy.md and the mission. Reports orphan tags, missing pages, oversized categories. Use --bootstrap on first run.	tsx <skill>/scripts/wiki-taxonomy.ts --diff
wiki-ingest-file.ts	Heuristic extraction of mission-relevant chunks from a codebase file. Produces a draft JSON you review and pass to wiki-add.	tsx <skill>/scripts/wiki-ingest-file.ts --path src/foo.ts

Invocation contract. The scripts assume the current working directory is the project root (the directory containing wiki/). In the examples below, <skill> resolves to .claude/skills/wiki (relative to the project root). The wiki root is always <cwd>/wiki/.

Always invoke as tsx <skill>/scripts/<script>.ts ... — i.e. tsx .claude/skills/wiki/scripts/<script>.ts .... Never write tsx scripts/<script>.ts ...; there is no top-level scripts/ directory in a project. The backend sets cwd correctly when it spawns these scripts; when invoking them yourself from a terminal or Bash tool, cd to the project root first.

Standard workflows

Bootstrap (first activation)

1. cat wiki/_meta/mission.md — confirm it exists and has content. If missing or empty, ask the user/host to populate it; do nothing else.
2. tsx <skill>/scripts/wiki-taxonomy.ts --bootstrap — get a proposal.
3. Review semantically, edit, write the final taxonomy.md.
4. Create stub pages for each proposed topic via wiki-add (status: stub).
5. tsx <skill>/scripts/wiki-index.ts.
6. Append a bootstrap entry to _meta/changelog.md.

Conversation-fact ingest

1. Run tsx <skill>/scripts/wiki-search.ts --query "<terms>" with the fact's key terms.
2. Decide: update / cross-link / create / stub.
3. Build the page JSON (title, slug, body, tags, mission_relevance, sources entry of kind conversation).
4. tsx <skill>/scripts/wiki-add.ts --input <page.json> with mode: "update" or mode: "create" set in the JSON.
5. tsx <skill>/scripts/wiki-index.ts and changelog entry.

File ingest

1. tsx <skill>/scripts/wiki-ingest-file.ts --path <file> — get the heuristic draft.
2. Review the chunks; discard noise; keep mission-relevant facts.
3. For each kept chunk: run tsx <skill>/scripts/wiki-search.ts --query "<terms>" (deduplication), then tsx <skill>/scripts/wiki-add.ts --input <page.json>.
4. Create one summary page in wiki/sources/ linking back to all topic pages it touched.
5. tsx <skill>/scripts/wiki-index.ts and changelog.

Question answering

1. Read wiki/index.md.
2. Pick the two to five most relevant pages and cat them.
3. Answer the user citing the page paths.
4. If the answer was non-trivial and reusable, file it as a new wiki/queries/<date>-<slug>.md (Karpathy's "explorations compound" rule).
5. Changelog entry of kind query.

Lint / health-check

Run tsx <skill>/scripts/wiki-taxonomy.ts --diff plus tsx <skill>/scripts/wiki-index.ts --report-orphans. Investigate stubs older than the configured threshold, oversized categories, contradictions visible in ## History sections, and pages with no inbound links. File a lint report at wiki/queries/<date>-lint.md.

Conflict resolution

When the conversation contradicts a file, or when two files contradict each other, both claims must remain visible on the page. Place the more recent claim in the body, the older claim in ## History, and add a ## Open question section if the disagreement is unresolved. Mark the page confidence: medium until resolved.

Confidence rules

• high — multiple independent sources or an explicit user decision.
• medium — a single source, or inferred from heuristics.
• low — speculation, mention without detail, or missing provenance. Stubs default to low.

Worked example

User says: "We decided on a mid-century modern sofa from Brand X."

1. tsx <skill>/scripts/wiki-search.ts --query "sofa Brand X mid-century" — returns no exact match, one related page mid-century-style-direction.md.
2. Build the new page JSON. Title: Brand X mid-century sofa (selected). Slug: brand-x-mid-century-sofa. Status: stable. Confidence: high (explicit user decision). Tags: [furniture, sofa, brand:brand-x, style:mid-century, decision]. Source: conversation, current turn. Body explains the decision and links to mid-century-style-direction.md and the to-be-created brand-x.md (stub).
3. tsx <skill>/scripts/wiki-add.ts --input /tmp/sofa.json --create — creates the page; auto-creates the brand-x stub because the body links to it; updates backlinks on mid-century-style-direction.md.
4. tsx <skill>/scripts/wiki-index.ts.
5. cat >> wiki/_meta/changelog.md with a decision entry.

What does not go in the wiki

Transient chitchat, unverified speculation marked clearly as such, the user's typos and self-corrections, anything outside the mission, anything the user asks not to record, anything that would be obsolete in a week, and decorative diagrams that restate the surrounding prose without adding structural clarity.

For more depth on any step, read references/conventions.md, references/workflows.md, or references/pitfalls.md.