factory/skills/setup-wiki/SKILL.md

---
name: setup-wiki
version: 1.1.0
description: Creates or migrates a project's `.wiki/` to the canonical Karpathy LLM Wiki layout — `CLAUDE.md` schema, `index.md`, `log.md`, `overview.md`, `raw/README.md`, plus empty `entities/`, `concepts/`, `packages/`, `sources/`, `contradictions/`, `open-questions/`. Use when the user says "set up wiki", "init wiki", "настрой вики", "инициализируй вики", "create wiki", "migrate wiki to canon", "wiki сломана", "wiki layout broken", or whenever `using-wiki` detects a missing or non-canonical `.wiki/`. Two modes — greenfield (no wiki) and migrate (existing non-canonical layout). Confirmation gate before writing. Cross-platform.
---

# setup-wiki

> Creates or migrates a `.wiki/` to canon. The canonical layout is documented at https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f and enforced by `using-wiki`. This skill is the *only* place that creates or rearranges those files.

## When to use

- User explicitly asks: set up / init / migrate / create wiki.
- `using-wiki` runs and detects a missing or non-canonical `.wiki/` — its Prerequisites delegate here.
- `project-bootstrap` Step 3 delegates here when initializing a new project.

## Out of scope

- Editing existing wiki *content* (that's `using-wiki`'s job).
- Anything outside `.wiki/`.

## Hard rule: don't auto-mutate

The procedure mutates the project's `.wiki/`. **Pause for explicit confirmation between Phase 1 (discovery) and Phase 2 (plan).** A trigger phrase is permission to inspect, not to write.

## Procedure

### Phase 0 — Environment sanity

- Confirm current working directory is a project root (has `.git/` ideally, or at minimum is a place the user wants a wiki).
- Detect platform; pick file paths accordingly. Wiki paths are POSIX-style (`.wiki/...`) on every OS.

### Phase 1 — Discovery

Inspect `.wiki/`:

- **No `.wiki/`** → mode = `greenfield`.
- **`.wiki/` exists AND has all of:** `CLAUDE.md`, `index.md`, `log.md`, `overview.md`, `raw/README.md`, plus directories `entities/`, `concepts/`, `packages/`, `sources/`, `contradictions/`, `open-questions/` → mode = `noop` (already canon; report and exit).
- **`.wiki/` exists but missing some canon files OR has non-canon files** (`SUMMARY.md`, `WORKFLOW.md`, `source/`) → mode = `migrate`.

Report findings to the user as a short summary:

```
Mode:  greenfield | noop | migrate
Has:   <list of canon files present>
Missing: <list>
Non-canon: <list>
```

### Phase 2 — Plan + confirm

Show the plan in one block:

**Greenfield:**
```
Will create .wiki/ with canonical layout:
  CLAUDE.md (schema), index.md, log.md, overview.md
  raw/README.md
  entities/, concepts/, packages/, sources/, contradictions/, open-questions/ (with .gitkeep)
```

**Migrate:**
```
Will rename:
  source/*.md → concepts/*.md  (via git mv when in a git repo, plain mv otherwise)
Will create:
  CLAUDE.md, index.md, log.md, overview.md, raw/README.md
  entities/, packages/, sources/, contradictions/, open-questions/ (with .gitkeep)
Will delete:
  SUMMARY.md, WORKFLOW.md, raw/.gitkeep, source/ (after moves)
Will not touch existing files in raw/ — they're immutable sources.
```

Wait for explicit confirmation ("ok", "go", "поехали"). Anything else → stop.

### Phase 3 — Backup (migrate only)

In migrate mode only, copy each file we will rename/delete to `.wiki/.backup-YYYYMMDD-HHMMSS/`. (Greenfield has nothing to back up.)

If git is available, the rename history is also recoverable via `git reflog`, but a filesystem backup is belt-and-suspenders.

### Phase 4a — Greenfield create

Create the canonical layout. Each file gets the content shown below; the project name comes from the parent directory's basename.

**`.wiki/CLAUDE.md`** (schema):

```markdown
# Wiki Schema — <project>

Project-specific wiki conventions. Read this before any wiki operation.

This wiki follows Karpathy's LLM Wiki pattern:
**https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f**

The `using-wiki` skill enforces the workflow and file formats. This file overrides the skill where they conflict.

## Page types

- `entities/` — discrete things this project tracks (people, services, modules).
- `concepts/` — recurring ideas, design decisions, gotchas.
- `packages/` — code packages this project produces or consumes.
- `sources/` — one summary page per ingested external doc; carries `ingested:` and `raw_path:`.
- `contradictions/` — surfaced tensions between sources or pages worth tracking long-term; each page cross-links the affected entities/concepts/sources and carries a status (`open` / `resolved` / `accepted-divergence`).
- `open-questions/` — unresolved questions raised during ingest or query that the wiki cannot answer yet; each page cross-links the pages/sources that touch the question and carries a status (`open` / `answered` / `obsolete`).
- `overview.md` — single project-wide overview.

## Naming

- `kebab-case.md`, **Latin only**. Transliterate Cyrillic in filenames; keep the original title in the H1 + frontmatter.

## Domain conventions

<!-- Fill in as the project takes shape — what counts as an entity here, which packages exist, naming idioms specific to this codebase. -->
```

**`.wiki/index.md`** (catalog):

```markdown
# Wiki Index

Catalog of all wiki pages. One line per page, organized by type. Updated on every ingest / new page.

## Overview

- [overview.md](overview.md) — project overview

## Entities

<!-- (none yet) -->

## Concepts

<!-- (none yet) -->

## Packages

<!-- (none yet) -->

## Sources

<!-- (none yet) -->

## Contradictions

<!-- (none yet) -->

## Open Questions

<!-- (none yet) -->
```

**`.wiki/log.md`** (op log; backfill an `init` line dated today):

```markdown
# Wiki Log

Append-only operation log. Format:

\`\`\`
## [YYYY-MM-DD] <op> | <one-line description>
\`\`\`

Operations: `init`, `ingest`, `query`, `lint`, `refactor`, `decision`.

Parseable: `grep "^## \[" .wiki/log.md | tail -20`.

---

## [<today>] init | wiki bootstrapped via setup-wiki@<version>
```

**`.wiki/overview.md`**:

```markdown
---
title: <project> overview
type: overview
updated: <today>
---

# <project> — overview

<!-- Replace with a high-level description: what this project does, who it's for, the main components. -->
```

**`.wiki/raw/README.md`**:

```markdown
# Raw Sources

**Immutable.** Read, never edit. The only allowed modification is appending a `> Status:` blockquote when the user explicitly asks for a status audit.

Place raw inputs here — articles, transcripts, PDFs, screenshots — exactly as they came in. The agent reads from `raw/`, writes summaries into `../sources/`, and never modifies raw files.

For large or path-sensitive sources outside the repo, register them here:

\`\`\`
- short-name → /absolute/path/to/source
\`\`\`
```

**Empty `.gitkeep`** in each of `entities/`, `concepts/`, `packages/`, `sources/`, `contradictions/`, `open-questions/` so git tracks the dirs.

### Phase 4b — Migrate

If migrate mode: combine creation (for missing canon files) with file moves (for non-canon).

```bash
# 1. Create missing directories
mkdir -p .wiki/concepts .wiki/entities .wiki/packages .wiki/sources .wiki/contradictions .wiki/open-questions

# 2. Move source/* → concepts/* (use git mv if in a git repo)
if git rev-parse --git-dir >/dev/null 2>&1; then
  for f in .wiki/source/*.md; do
    [ -e "$f" ] && git mv "$f" ".wiki/concepts/$(basename "$f")"
  done
  git rm -f .wiki/SUMMARY.md .wiki/WORKFLOW.md .wiki/source/.gitkeep .wiki/raw/.gitkeep 2>/dev/null
else
  mv .wiki/source/*.md .wiki/concepts/ 2>/dev/null
  rm -f .wiki/SUMMARY.md .wiki/WORKFLOW.md .wiki/source/.gitkeep .wiki/raw/.gitkeep
fi
rmdir .wiki/source 2>/dev/null

# 3. Create missing canon files (CLAUDE.md, index.md, log.md, overview.md, raw/README.md)
#    using the templates from Phase 4a, but skip files that already exist.

# 4. Add .gitkeep to entities/, packages/, sources/, contradictions/, open-questions/
touch .wiki/entities/.gitkeep .wiki/packages/.gitkeep .wiki/sources/.gitkeep .wiki/contradictions/.gitkeep .wiki/open-questions/.gitkeep
```

For migrated `concepts/*.md` pages, **do not rewrite their content** — just prepend a minimal frontmatter if missing:

```yaml
---
title: <derived from existing H1>
type: concept
updated: <today>
---
```

Build `index.md` with one entry per migrated `concepts/<file>.md`, derived from the file's H1 and any one-liner the agent can extract.

Append a line to `log.md`:

```
## [<today>] refactor | wiki migrated to canon via setup-wiki@<version>
```

### Phase 5 — Verify

After writes, confirm:

- All canon files exist: `CLAUDE.md`, `index.md`, `log.md`, `overview.md`, `raw/README.md`.
- Six content directories exist (`entities/`, `concepts/`, `packages/`, `sources/`, `contradictions/`, `open-questions/`) — with at least `.gitkeep` or content.
- No leftover non-canon files (`SUMMARY.md`, `WORKFLOW.md`, `source/`).
- For migrate mode: every migrated page has frontmatter with `type: concept`.

If anything's off — restore from `.wiki/.backup-*` and report.

### Phase 6 — Report

Print final state:

```
✅ Wiki ready at .wiki/.
   Mode: greenfield | migrate
   Files: 5 canon + 6 dirs + N migrated concept pages
   Backup (if migrate): .wiki/.backup-<ts>/

Next steps for the user:
  • Edit .wiki/overview.md to describe the project
  • Edit .wiki/CLAUDE.md "Domain conventions" with project-specific rules
  • Read using-wiki SKILL.md if unfamiliar with the workflow
```

If invoked from `project-bootstrap`, return control silently — bootstrap continues with its remaining steps.

## Rollback

1. `rm -rf .wiki/` (greenfield rollback) OR `cp -r .wiki/.backup-<ts>/* .wiki/` (migrate rollback).
2. If a git repo, `git reset HEAD .wiki/` to unstage moves.
3. Tell user what failed.

## Common mistakes

- **Touching `raw/` content during migration.** `raw/` is immutable — only the `.gitkeep` placeholder may be removed (and that only because `raw/README.md` replaces it).
- **Skipping confirmation on greenfield.** Yes, even greenfield needs the gate — the user might be running this skill in the wrong directory.
- **Re-running on already-canon wiki and rewriting files.** Phase 1 detection guards this; bail out at `noop` mode.
- **Inventing project-specific Domain conventions in `CLAUDE.md`.** The schema's "Domain conventions" section is intentionally a stub — let the user fill it as they accumulate domain knowledge.

## Cross-platform notes

The procedure is platform-agnostic. `mkdir -p`, `mv`, `git mv`, `cp -r`, `rm -rf`, `touch` work in git-bash on Windows the same as on Linux/macOS. Wiki paths use forward slashes throughout.