v1 to v2

4 added, 4 removed. Audit A to A.

---

type: "skill"

name: "wiki-generate"

status: "stable"

description: "Drafts wiki structure from the codebase: hub/spoke index rows, doc skeletons, and a linked catalog. Use when bootstrapping docs for new code, refreshing index rows after new files land, or ingesting an OpenWiki/OKF bundle. Drafts only — the wiki-bootstrap verification pass confirms accuracy before docs go stable. Native generation for structure; OpenWiki interop for prose."

- references: "references/ — optional per-domain scaffolds. scripts/wiki_okf.py — OKF v0.2 export projection."

- version: 1

+ references: "references/ — optional per-domain scaffolds. scripts/wiki_okf.py — OKF v0.2 import/export bridge."

+ version: 2

updated: 2026-09-11

---

# wiki-generate

Generate wiki structure from reality, then hand it to `@wiki-bootstrap` to verify.

> **This skill drafts. It does not bless.** Every doc it writes stays `status: in-progress` until `@wiki-bootstrap` verifies it against the codebase and a human promotes it.

---

## 1. When This Skill Runs

| Situation | Action |

|---|---|

| New source files landed with no wiki docs | Draft doc skeletons + index rows |

| Index rows are missing for existing docs | Draft the rows; hand to `@wiki-lint` to confirm `[UNINDEXED]` clears |

| A satellite brings an `openwiki/` bundle | Ingest the bundle as draft docs (interop path) |

| A doc needs prose written/rewritten | **Not this skill** — use `@wiki-writer` |

| A doc needs its content verified | **Not this skill** — use `@wiki-bootstrap` |

---

## 2. Native Generation (structure)

Inputs: `.wiki/*-index.md` (the authoritative catalogs) and the source tree.

1. **Read the taxonomy.** Open `.wiki/core/17-docs-blueprint.md` for the doc naming and folder rules, and the relevant `.wiki/*-index.md` for the current rows.

2. **Inventory the gap.** For a domain with sources but no docs, list the source files and group them the way the index groups its siblings.

3. **Draft index rows.** One row per new doc, matching the index's existing column shape. Use the source file name for `[Title](path)` and a one-line `description`. Never invent a description that the code does not support.

4. **Draft doc skeletons.** Frontmatter uses the unified schema (`.wiki/rules/frontmatter.md`) with `status: in-progress` and `format-version: 1`. Body: H1, a 2-3 sentence overview, Technical Context (paths, data shapes), Relationships (cross-links), Rules & Constraints (if any). Follow `.wiki/core/17-docs-blueprint.md` and `@wiki-writer` discipline.

5. **Ground what you assert.** Where a draft states a material fact, add a `claims:` entry pointing at the real source (`path#symbol`) and run `python scripts/wiki_claims.py update`.

6. **Hand off.** Run `python scripts/wiki_lint.py`; then invoke `@wiki-bootstrap` to verify the drafts one doc at a time.

> **Never mark generated docs `stable`.** Generation produces a claim; verification produces truth.

---

## 3. OpenWiki / OKF Interop (prose)

A satellite may bring its own generator. When an `openwiki/` bundle is present:

- 1. Ingest the bundle's concept docs (`type:`-bearing Markdown files) as **drafts** under the matching `.wiki/` domain.

- 2. Preserve the bundle's `description`/`tags` when they map cleanly; otherwise fall back to the unified schema and record the gap.

+ 1. Run the bridge: `python scripts/wiki_okf.py import [--from openwiki] [--out .wiki]`. It translates each `type:`-bearing concept doc to the local `format-version: 1` schema as a `status: in-progress` draft, records provenance (`okf_version: "0.2"`), and registers the doc in its area spoke index. An existing target path is **skipped**, never overwritten.

+ 2. Preserve the bundle's `description`/`tags` when they map cleanly; otherwise fall back to the unified schema and record the gap. (The bridge preserves both.)

3. Treat the bundle as a claim source, not as truth — run `@wiki-bootstrap` verification before promoting anything.

4. To go the other way, use `python scripts/wiki_okf.py export` to project this wiki into an OKF v0.2 bundle for an OKF-aware consumer.

The local schema stays authoritative. OKF is a projection; it is never the source of truth.

---

## 4. Boundaries

- **No content invention.** If the code does not tell you what a doc should say, write `[PLACEHOLDER: <reason>]` and flag it — never guess.

- **No prose rewriting.** Drafting only. Prose polish belongs to `@wiki-writer`.

- **No promotion.** `stable` is a human decision, recorded at wrap-up.

- **Structure only, by default.** Native generation drafts indexes and skeletons; it does not author deep prose from source.

---

> **The rule:** generate from reality, ground every claim, verify before you stable.