# using-wiki Runtime policy for an LLM Wiki built on the [Karpathy LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). Knowledge is **compiled once and kept current** across three layers, via three named operations, with strict file formats that keep the wiki parseable and grep-friendly. `using-wiki` governs *usage* of an existing `.wiki/`. Initial creation and migration to canon are owned by [`setup-wiki`](../setup-wiki/). > Renamed from `wiki-maintainer` at v1.0.0. ## When it triggers - User says: "use project wiki", "query the wiki", "ingest this", or the Russian equivalents ("обнови вики", "проверь вики", "запроси вики", "заингесть"). - Any time the agent modifies a file under `.wiki/` — the workflow and formats below are mandatory. - If `.wiki/` is missing or non-canonical, this skill delegates to [`setup-wiki`](../setup-wiki/) before doing anything else. ## Three layers (do not blur) 1. **Raw sources** — `.wiki/raw/` (or external paths registered in `raw/README.md`). **Immutable.** Read, never edit. The only exception is appending a `> Status` blockquote when the user explicitly asks for a status audit. 2. **Wiki** — everything else under `.wiki/`. Agent-owned. Entity / concept / package / source summary pages. 3. **Schema** — `.wiki/CLAUDE.md`. Project-specific conventions (what entities, what packages, naming). Always read it first; it overrides this skill on conflict. ## Three operations ### Ingest «заингесть X» — pull a raw source into the wiki. 1. Read the raw source fully. 2. Extract: entities, concepts, packages, cross-cutting patterns. 3. Create `sources/.md` (one summary page per source, ~50–150 lines). 4. For each affected entity / concept / package page: update if exists, create if not. Flag contradictions explicitly with `> **Противоречие:** источник A говорит X, источник B — Y`. **Never silently overwrite.** 5. Update `index.md`. 6. Append one line to `log.md`. 7. Report: what was created, updated, contradicted. One ingest may touch 10–15 pages. That's normal — that's why an LLM does it. ### Query A question answered from the wiki. 1. Read `index.md` first, drill into relevant pages. 2. Answer with citations as markdown links. 3. **Compound the wiki.** If the answer is a real synthesis, ask the user: "Сохранить как страницу wiki?" Good queries become durable pages under `concepts/` or `analyses/`. 4. Append one line to `log.md`. ### Lint «проверь wiki» — health check. Scan for: - Contradictions between pages. - Orphans (pages with no inbound links). - Stale claims (raw source updated after the summary's `ingested:` date — check via `git log -p`). - Concepts mentioned in prose but missing their own page. - Empty / TODO sections. Report as a punch list. Don't delete anything automatically. Append one line to `log.md` with the findings. ## File formats (mandatory) ### Page frontmatter ```yaml --- title: Человекочитаемое имя type: entity | concept | package | source | contradiction | open-question | overview tags: [short, tokens] sources: [../sources/foo.md, ../sources/bar.md] updated: 2026-04-21 --- ``` Source pages also carry `ingested: YYYY-MM-DD` and `raw_path: ../raw/...`. Contradiction pages also carry `status: open | resolved | accepted-divergence` and `affects: [../entities/x.md, ../concepts/y.md]`. Open-question pages also carry `status: open | answered | obsolete` and `touches: [../entities/x.md, ../sources/z.md]`. ### File naming - `kebab-case.md`, **Latin only**. Transliterate Cyrillic / non-Latin in filenames; keep the original title in H1 + frontmatter. - `entities/.md`, `concepts/.md`, `packages/.md` (no `@org/` prefix), `sources/.md`, `contradictions/.md`, `open-questions/.md`. ### `log.md` — append-only, grep-parseable Every entry must start with: ``` ## [YYYY-MM-DD] | ``` Operations: `ingest`, `query`, `lint`, `refactor`, `decision`, `init`. Parse with: `grep "^## \[" .wiki/log.md | tail -20`. ### `index.md` Catalog, not narrative. One line per page: `- [Title](path) — hook.` Sections by type. Update on every ingest. ### Cross-references - Wiki → wiki: relative markdown links — `[Name](../entities/x.md)`. - Wiki → code: relative path from repo root — `[foo.js](../../packages/api/foo.js)`. - Wiki → raw: `../raw/`. - URL-encode spaces (`%20`) and Cyrillic when needed. ## Quick reference | Situation | Files touched | |---|---| | Ingest one doc | `sources/.md` (new) + 3–15 entity/concept/package pages + `index.md` + `log.md` | | Query | (read only) + optionally a new wiki page + `log.md` | | Lint | (read only) + `log.md` | | Bootstrap / migrate | (delegated to [`setup-wiki`](../setup-wiki/)) | ## Common mistakes - **Editing `raw/`.** Don't. Only allowed change: status blockquote on explicit request. - **Dumping raw content into `sources/`.** Summaries are summaries. Link to raw, don't copy. - **Silent overwrites on contradictions.** Flag them with a `> **Противоречие:**` block. - **Narrative `log.md`.** "Today I added…" is wrong. Use `## [YYYY-MM-DD] ingest | `. - **Non-ASCII filenames.** Breaks greppability and cross-platform. Transliterate. - **Forgetting `index.md`.** Pages not listed there are invisible to future queries. - **Improvising layout when canon files are missing.** Hand off to [`setup-wiki`](../setup-wiki/) instead of patching ad-hoc. ## When NOT to use - The project has CLAUDE.md / AGENTS.md docs but no `.wiki/` — that's regular documentation, not an LLM Wiki. - The user wants a single-file README or ADR — this skill is for persistent, interlinked knowledge bases. - One-off questions about code — read files directly, no wiki workflow needed. ## Install From the repo root: ```bash bash scripts/install.sh using-wiki ``` Works on Windows under git-bash, Linux, macOS. ## See also - [`setup-wiki`](../setup-wiki/) — companion, owns `.wiki/` creation and canon migration. - [`project-bootstrap`](../project-bootstrap/) — invokes `setup-wiki` for new projects. - Karpathy's LLM Wiki gist: