knowledge-setup

---
name: knowledge-setup
description: "Bootstrap a cogni-knowledge knowledge base — a wiki base + a binding manifest that records every research project deposited into it. Scaffolds the wiki skeleton natively (the wiki engine is vendored; no separate plugin required) if it does not exist, then writes .cogni-knowledge/binding.json. Use this skill whenever the user says 'set up a knowledge base', 'start a knowledge base on X', 'bootstrap a wiki-first research base', 'new knowledge base for X', 'create a knowledge base', or 'wiki-first research setup'. After setup, run the inverted pipeline (knowledge-plan → knowledge-curate → knowledge-fetch → knowledge-ingest → knowledge-compose → knowledge-verify → knowledge-finalize) to deposit research syntheses into the base."
allowed-tools: Read, Bash, Glob, WebSearch, AskUserQuestion, Skill
---

# Knowledge Setup

Bootstrap a cogni-knowledge knowledge base. A knowledge base is one directory that holds both a cogni-wiki (`.cogni-wiki/config.json`) and a cogni-knowledge binding manifest (`.cogni-knowledge/binding.json`). The wiki is the substrate; the binding records which research projects have contributed to it.

This skill is a **thin orchestrator**. It scaffolds the wiki skeleton natively — the wiki engine is vendored under `scripts/vendor/cogni-wiki/`, so setup dispatches no `cogni-wiki:wiki-setup` skill. The cogni-knowledge value-add is the binding manifest plus the one-command workflow.

Read `${CLAUDE_PLUGIN_ROOT}/references/differentiation-thesis.md` once at the start of a session to anchor on why wiki-first matters; read `${CLAUDE_PLUGIN_ROOT}/references/delegation-contract.md` to remember what cogni-knowledge owns vs. delegates.

## When to run

- User asks to bootstrap, set up, initialize, or start a knowledge base
- User wants to begin a long-running research area (multiple projects, accumulating findings)
- User explicitly invokes `/cogni-knowledge:knowledge-setup`
- User wants to **re-steer an existing base** — the domain sharpened, the audience shifted, a new seed theme appeared — via `--reframe` (re-runs the charter interview against the existing binding; no hand-editing `binding.json`)

## Never run when

- The target directory already has `.cogni-knowledge/binding.json` — report the existing binding and stop. Re-initialisation is destructive; surface the existing slug and let the user decide.
- The user wants a one-off research report — point them at `cogni-research:research-setup` directly. cogni-knowledge is opinionated about accumulation; cogni-research stays available as a sibling plugin for one-shot reports.

## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--knowledge-slug` | Yes (prompted) | Kebab-case identifier for the knowledge base, e.g. `eu-ai-act`. Used for the directory name (`cogni-knowledge/<slug>/`) and the `knowledge_slug` field in the binding. |
| `--knowledge-title` | Yes (prompted) | Human-readable title, e.g. `"EU AI Act knowledge base"`. Used as the wiki's `name` in `.cogni-wiki/config.json`. |
| `--knowledge-root` | No | Override the default knowledge-base directory. Defaults to `cogni-knowledge/<knowledge-slug>/` (relative to the current working directory). Both the wiki and the binding live inside this directory. |
| `--description` | No | One-sentence description written into `.cogni-wiki/config.json`. |
| `--publisher-base-url` | No | Written into `.cogni-wiki/config.json` as `publisher_base_url`. Used as last-resort fallback URL when wiki pages have no per-page publisher URL. |
| `--market` | No | Default market for this knowledge base. One of: `dach`, `de`, `fr`, `it`, `pl`, `nl`, `es`, `us`, `uk`, `eu`. Persisted to `binding.json::research_defaults.market`; inherited by every `knowledge-plan` run. Resolved interactively in Step 2.5 when omitted (default `dach`). |
| `--output-language` | No | Default output language (two-letter code) for this knowledge base. Persisted to `binding.json::research_defaults.output_language`; inherited by every `knowledge-plan` run. Resolved interactively in Step 2.5 when omitted — defaults to the chosen market's registry `default_output_language` (e.g. `dach`→`de`, `fr`→`fr`, `eu`→`en`). |
| `--prose-density` | No | Default prose density (`standard`/`executive`) persisted to `binding.json::research_defaults.prose_density`. **Flag-or-default** — not prompted in Step 2.5 (safe default `executive`). |
| `--tone` | No | Default writing tone persisted to `binding.json::research_defaults.tone` (see `${CLAUDE_PLUGIN_ROOT}/references/writing-tones.md`). **Flag-or-default** — not prompted (safe default `objective`). |
| `--citation-format` | No | Default citation format persisted to `binding.json::research_defaults.citation_format` (`ieee`/`chicago` numbered; `apa`/`mla`/`harvard` author-date — all five render as requested). **Flag-or-default** — not prompted (safe default `ieee`). |
| `--target-words` | No | Default soft target word count persisted to `binding.json::research_defaults.target_words`. **Flag-or-default** — not prompted (safe default `2000`). |
| `--charter-domain` | No | One sentence: what this knowledge base is about. Persisted to `binding.json::charter.domain` (schema 0.1.4). Resolved interactively in Step 2.5 when omitted (engages the charter interview). |
| `--charter-audience` | No | Primary reader of the syntheses this base produces. Persisted to `binding.json::charter.audience`. Resolved interactively in Step 2.5 when omitted. |
| `--charter-scope` | No | In/out boundaries — geography / segment / horizon, one line. Persisted to `binding.json::charter.scope`. Resolved interactively in Step 2.5 when omitted. |
| `--open-themes` | No | Pipe-separated seed-theme backlog (e.g. `"high-risk systems\|conformity assessment\|GPAI"`). Persisted to `binding.json::topic_lineage.open_themes[]`; surfaces as the candidate menu for the first research question. Resolved interactively in Step 2.5 when omitted. |
| `--no-charter` | No | Skip the Step 2.5 charter interview AND the Step 5 first-question on-ramp. Use for automation / a flag-only init. The charter fields fall through to `""` and `open_themes[]` to `[]` (a complete, schema-valid 0.1.4 binding either way). |
| `--no-prelim-search` | No | Keep the Step 2.5 charter interview but skip its optional preliminary scoping scan (stays offline). Same semantics as `knowledge-plan --no-prelim-search`. |
| `--reframe` | No | **Re-steer an existing base** instead of bootstrapping a new one. Re-runs the Step 2.5 charter interview against the **existing** binding and writes the updated charter in place via `knowledge-binding.py set-charter` (a **partial** update — only the fields you change). Inverts Step 1's pre-flight: requires an existing binding and aborts when none is found. Skips wiki setup (Steps 2/3), the `init` call (Step 4), and the Step 5 first-question on-ramp. The charter's data shape (schema 0.1.4) is unchanged. |

If `--knowledge-slug` or `--knowledge-title` is missing, ask the user once with AskUserQuestion (call `ToolSearch(query="select:AskUserQuestion")` to load the schema if needed). Do not invent slugs or titles silently.

## Workflow

### 0. Pre-flight: self-contained (no external wiki plugin)

cogni-knowledge bundles its wiki engine: the vendored copy under `scripts/vendor/cogni-wiki/` is resolved vendored-first by every wiki-touching step, and this skill scaffolds the wiki skeleton natively (Step 3). There is no `cogni-wiki` plugin install to probe and no hard dependency to abort on — setup runs end-to-end with nothing else installed. Proceed directly to Step 1.

### 1. Resolve the knowledge root

1. If `--knowledge-root` was passed, use it as-is.
2. Otherwise, `knowledge_root = cogni-knowledge/<knowledge-slug>/` relative to the current working directory — the standard cogni-plugin convention (`cogni-{plugin}/{project-slug}/`), matching `cogni-wiki/{slug}/`.
3. **Binding pre-flight — direction depends on the mode:**
   - **Normal (bootstrap) mode** (no `--reframe`): if `<knowledge_root>/.cogni-knowledge/binding.json` already exists, read it, report the existing knowledge_slug/title/wiki_path, and stop. Do not overwrite.
   - **`--reframe` mode** (re-steer): the inverse. The binding **must** exist. If `<knowledge_root>/.cogni-knowledge/binding.json` is **missing**, abort cleanly: *"nothing to re-frame — run `knowledge-setup` (without `--reframe`) to bootstrap this base first."* When it exists, read it, validate its `knowledge_slug` matches `--knowledge-slug` (mismatch → abort), then **jump straight to Step 2.5** — skip the wiki pre-flight / dispatch (Steps 2/3) and the `init` call (Step 4); the wiki and binding already exist, so re-frame only rewrites the charter via `set-charter`.

### 2. Pre-flight: wiki vs no wiki

Check `<knowledge_root>/.cogni-wiki/config.json`:

- **Exists** → a wiki is already set up at this path. Skip Step 3 (the wiki already exists; no native scaffold needed). Treat the existing wiki as the binding's target.
- **Does not exist** → Step 3 will scaffold the wiki skeleton natively.

If `<knowledge_root>` exists but contains foreign files (no `.cogni-wiki/`, but non-empty subdirs that are not the standard cogni-wiki layout — `raw/`, `wiki/`, `assets/`), abort: "path exists but is not a wiki — choose a different `--knowledge-root` or move the existing files."

### 2.5. Charter framing + language defaults (the single setup interview)

This step steers the base: it captures a coarse **charter** (what the base is about, who reads it, where its boundaries are, which themes to cover first) **and** the default `market` + `output_language`, in **one coherent interview** rather than two disjoint prompts. The charter is the base-level analog of `knowledge-plan`'s per-question topic-framing (`references/topic-framing.md`); the full base-scoped playbook + question bank lives in `${CLAUDE_PLUGIN_ROOT}/references/charter-framing.md`. Read it once here.

Why a charter: in cogni-knowledge one base accumulates *many* topics over time, so the base needs a coarser charter while each `knowledge-plan` run keeps the finer per-question framing that already exists. The charter is persisted to `binding.json::charter` (schema 0.1.4) and seed themes to `topic_lineage.open_themes[]`; `knowledge-plan` Step 0.4 then inherits the charter as grounding so every future run is anchored to the base's domain.

**Engage / skip** (mirror topic-framing's contract — *this base must be steered*, so default-on with an explicit opt-out):

- **Skip** the charter interview when `--no-charter` is passed, **or** the run is non-interactive (all of `--charter-domain`/`--charter-audience`/`--charter-scope` supplied via flags). In the skip case, charter fields fall through to their flags (else `""`) and `open_themes[]` to `--open-themes` (else `[]`) — still a complete schema-0.1.4 binding.
- **Engage** otherwise (the default on an interactive run). Say so in one sentence before asking: *"Let me frame this knowledge base before we set it up — a few quick questions so every future research run is anchored to it."*

**`--reframe` mode — re-steer an existing charter.** When invoked with `--reframe`, this same interview runs against the **existing** binding instead of a fresh one:

- First **read the current charter** so the user sees what is set today and only changes what shifted:
  ```
  python3 ${CLAUDE_PLUGIN_ROOT}/scripts/knowledge-binding.py read --knowledge-root <knowledge_root>
  ```
  Pull `binding.charter.{domain,audience,scope}` and `binding.topic_lineage.open_themes[]`.
- **Pre-populate the AskUserQuestion defaults** from those current values (the sharpen turn shows "currently: `<domain>`" so an unchanged field is one keystroke to keep).
- Frame the seed-themes question as *"Any **additional** seed themes to add?"* — `set-charter` **union-merges** `--open-themes` into the existing backlog (it appends; it never clobbers or removes). Dropping a seed theme stays a hand-edit for now.
- Say so in one sentence first: *"Let me re-frame this knowledge base — I'll show you what's set today, change only what shifted."*
- The market / language resolution below is **not** re-run in `--reframe` mode (those live in `research_defaults`, not the charter; re-framing steers domain/audience/scope/themes only). Skip straight to writing the charter in Step 4's `--reframe` branch.

When engaged, run the four framing moves (port the **shape** from `references/charter-framing.md`):

1. **Ground** (optional, ≤50 KB, no writes outside the base). Ask for any grounding material: *"Any grounding material for this knowledge base? (a path / pasted text / a URL / 'no context')"*. When the user supplies a path, read conservatively (`Glob` the top-level shape, `Read` the manifest/README, sample 2–3 files; cap ~50 KB). No network here; no writes.
2. **Scan** (optional, fail-soft). Unless `--no-prelim-search` was passed, issue **2–3 broad `WebSearch` queries** on the domain to ground the seed-theme suggestions; review the top snippets for the dominant themes/organizations/terminology. **Any error → skip silently** and fall through to pure reasoning. The scan never blocks framing.
3. **Sharpen** — one `AskUserQuestion` turn (call `ToolSearch(query="select:AskUserQuestion")` to load the schema if needed), ≤4 skippable, **base-scoped** questions. Fold the market/language questions into this same turn (or a single immediate follow-up turn if the four-question budget is full):
   - **Domain** — *"In one sentence, what is this knowledge base about?"* (free text → `charter.domain`)
   - **Audience** — *"Who reads the syntheses this base produces?"* (offer the audience option list from `charter-framing.md` → `charter.audience`)
   - **Scope** — *"What's in and out of scope? (geography / segment / horizon)"* (free text → `charter.scope`)
   - **Seed themes** — *"Which 3–6 themes should this base cover first?"* (multiSelect over scan-derived suggestions + Other → `open_themes[]`)
   - **Market** (only if `--market` not passed): the supported codes; default `dach` *(Recommended)*.
   - **Output language** (only if `--output-language` not passed): option 1 is the market's `default_output_language` *(Recommended)*, option 2 `en`, plus 1–2 common others; "Other" takes a two-letter code.
   Every question is skippable — "I'll decide later" drops to the safe default (charter field → `""`, market → `dach`, language → the market's `default_output_language`, no seed themes).

Resolve the **market / language** default exactly as before (the precedence and helper are unchanged):

1. If **both** `--market` and `--output-language` were passed, use them as-is.
2. Otherwise derive the suggested language default from the market via the canonical workspace helper (the same path `knowledge-plan` uses for `candidate_domains`):
   ```
   python3 "${WORKSPACE_PLUGIN_ROOT:-$(ls -td "$HOME"/.claude/plugins/cache/insight-wave/cogni-workspace/*/ | head -1)}/scripts/get-market-config.py" --plugin research --market <market-or-default-dach>
   ```
   Read `data.default_output_language` from the envelope (e.g. `dach`→`de`, `fr`→`fr`, `eu`→`en`).
3. Surface market + language inside the sharpen turn above (skippable → market `dach`, language = market's `default_output_language`).

Carry the resolved `charter.{domain,audience,scope}`, `open_themes[]`, `market`, and `output_language` into Step 4.

**Writer-quality knobs (`prose_density`, `tone`, `citation_format`, `target_words`) are flag-or-default — NOT prompted here.** Each has a safe default and is primarily a per-run choice on `knowledge-plan`, so the interview stays scoped to charter + market/language; the four knobs persist from their flags when passed, else the script-side defaults (`executive`/`objective`/`ieee`/`2000`). Overridable per run via `knowledge-plan --prose-density|--tone|--citation-format|--target-words`. Carry any passed flags into Step 4.

### 3. Scaffold the wiki skeleton (only if no wiki exists)

cogni-knowledge owns the wiki skeleton natively — it does **not** dispatch `cogni-wiki:wiki-setup`. The wiki engine is vendored under `scripts/vendor/cogni-wiki/`; the only residue a fresh wiki needs before Step 3.5's curated re-seeding is the directory skeleton plus an initial `.cogni-wiki/config.json` (Step 3.5 then bumps its `schema_version` 0.0.7 → 0.0.9 via the vendored `config_bump.py`, which requires the file to already exist).

Create the skeleton and write the config natively. Pass the title/description/url as **environment variables** to `python3 -c` so an arbitrary `<knowledge-title>` containing `$`, a backtick, or a quote can never break the JSON or expand in the shell:

```
mkdir -p <knowledge_root>/raw <knowledge_root>/assets <knowledge_root>/.cogni-wiki \
  <knowledge_root>/wiki/concepts <knowledge_root>/wiki/entities <knowledge_root>/wiki/people \
  <knowledge_root>/wiki/sources <knowledge_root>/wiki/questions <knowledge_root>/wiki/syntheses \
  <knowledge_root>/wiki/interviews <knowledge_root>/wiki/audits || abort "wiki skeleton mkdir failed"

WIKI_NAME='<knowledge-title>' WIKI_SLUG='<knowledge-slug>' \
WIKI_DESC='<description, or empty>' WIKI_PUB='<publisher-base-url, or empty>' \
WIKI_ROOT='<knowledge_root>' python3 -c '
import json, os, datetime
cfg = {
    "name": os.environ["WIKI_NAME"],
    "slug": os.environ["WIKI_SLUG"],
    "description": os.environ.get("WIKI_DESC", ""),
    "created": datetime.date.today().isoformat(),
    "entries_count": 0,
    "last_lint": None,
    "schema_version": "0.0.7",
}
pub = os.environ.get("WIKI_PUB", "")
if pub:
    cfg["publisher_base_url"] = pub
with open(os.path.join(os.environ["WIKI_ROOT"], ".cogni-wiki", "config.json"), "w") as fh:
    json.dump(cfg, fh, indent=2)
' || abort "wiki config.json write failed"
```

On a `mkdir` / `config.json` failure, surface the error verbatim and stop. The binding is **not** written if the wiki skeleton was not created.

### 3.5 Seed the curated wiki-output layout (new wikis only)

Run this step **only on the fresh-wiki branch** — when Step 3 just scaffolded
the wiki skeleton. **Skip it** when Step 2 re-used an existing wiki, and in
`--reframe` mode (which already skips Steps 2–3). It turns the
`schema_version 0.0.9` layout the contract below declares into the actual seeded
shape, so a NEW wiki opens with a curated MAP front door (`wiki/index.md`)
over its per-type sub-indexes — with the overview narrative folded into the
`wiki/index.md` intro (where `knowledge-finalize` maintains it via
`overview_update.py narrative-splice --target-file index.md`) and `wiki/overview.md`
reduced to a stub holding the `## Recent syntheses` list — rather than leaving the
wiki root files unstructured. All edits are CK-side; the vendored engine scripts are read-only — this
step *calls* them, never edits them.

**Resolve the wiki-ingest scripts dir** (Step 3 dispatches the skill but resolves
no script dir, so resolve it here, mirroring `knowledge-finalize` Step 0):

```
. "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-wiki-scripts.sh"
WIKI_INGEST_SCRIPTS=$(resolve_wiki_scripts wiki-ingest config_bump.py) \
  || abort "cogni-knowledge's vendored wiki-ingest scripts are missing. Reinstall cogni-knowledge, then retry."
```

**(a) Seed the six per-type sub-index stubs via the canonical renderer.** Call
`sub_index.py render` per type — it writes each `wiki/<type>/index.md` with its
`<!-- MACHINE-OWNED:<TYPE>-INDEX -->` ownership marker under the wiki lock, so the
renderer treats it as a machine-owned upsert target on the first
`knowledge-finalize`. Do **not** hand-author the markers — that would duplicate
`sub_index.py`'s logic, which the no-duplicate-upstream-logic convention forbids:

```
for t in concepts entities people sources questions syntheses; do
  python3 "${CLAUDE_PLUGIN_ROOT}/scripts/sub_index.py" render \
    --type "$t" --wiki-root <knowledge_root> \
    --wiki-scripts-dir "$WIKI_INGEST_SCRIPTS" \
    || abort "sub_index render failed for $t"
done
```

**(b) Seed the curated root files — `wiki/index.md` (curated MAP front door,
overview narrative in its intro), `wiki/overview.md` (stub), and the
knowledge-native `SCHEMA.md`.** Seed all three curated root files via Bash
heredocs (since this skill's `allowed-tools` carries no `Write` tool — the seed
mechanism is `cat > … <<'EOF'`, not a `Write` call). All bodies use a **quoted**
heredoc delimiter (`<<'EOF'`) — they need no shell expansion, and quoting keeps a
`<knowledge-title>` that happens to contain a `$` or backtick from being expanded
or executed. Substitute `<knowledge-title>` and — on the `_Created:` subtitle
line **only** — today's date `YYYY-MM-DD` **textually** before running (the
quoted delimiter means the shell will not expand a `$(date)` here — the log
heredoc in (c) is the one place that stays unquoted precisely because it *does*
rely on `$(date)`). Never replace-all on `YYYY-MM-DD`: the SCHEMA.md seed's
audits/ tree line carries `lint-YYYY-MM-DD.md` / `health-YYYY-MM-DD.md` as
filename **patterns** that must stay literal. The in-body `<knowledge-root>/`
tree root in the SCHEMA.md seed likewise stays **literal** — it is a generic
placeholder in the deposited contract, not a substitution token:

- **`wiki/index.md`** becomes the curated **portal front door** carrying the
  `MACHINE-OWNED:OVERVIEW-NARRATIVE` block **in its intro** (the narrative now
  lives here, not in `wiki/overview.md`) plus the `MACHINE-OWNED:ROOT-INDEX`
  ownership marker and the curated-map intro line. `knowledge-finalize`'s
  `root_index.py render` upserts one `## <theme>` section per theme as research
  lands (each a count-link to its per-type sub-indexes, no per-page bullets), and
  `overview_update.py narrative-splice --target-file index.md` refreshes the
  OVERVIEW-NARRATIVE inner. The seed carries no `## <theme>` sections yet (none
  exist) and no per-page bullet line, so the vendored `strip_seed_placeholder`
  has nothing to strip. The intro line matches `root_index.py`'s so the first
  finalize render is a no-op on the intro.
- **`wiki/overview.md`** is re-seeded as a thin **stub** that points at the
  curated map: it no longer carries the `OVERVIEW-NARRATIVE` block (that moved to
  `index.md`'s intro). It remains the home of the `## Recent syntheses` running
  list that `knowledge-finalize`'s `overview_update.py recent-bullet` appends —
  the only surface still written there.
- **`SCHEMA.md`** (at the wiki ROOT, `<knowledge_root>/SCHEMA.md` — one level
  above the `wiki/` page tree the two seeds above target; that is where
  `wiki-setup` copies its generic template) is replaced with the
  **knowledge-native contract**: the generic template declares directories the
  knowledge pipeline never writes (`decisions/`, `meetings/`, `notes/`) while
  omitting the knowledge-native surfaces (`sources/`, `questions/`, `people/`,
  `interviews/`, `audits/`) — so without this overwrite every new base violates
  its own self-describing contract. The seed's directory set is pinned to the
  `sub_index.py` REGISTRY's six indexed types plus the on-disk
  `interviews/` / `audits/` / `wiki/meta/`, and it documents the
  concept-vs-entity **instance-free test** (the same rule the
  `concept-distiller` agent applies) so the contract is readable from inside
  the base. This seed is also the canonical copy `knowledge-index`'s schema
  truth-up applies to existing bases — change it here, never fork it there.

Seed the three curated root files by running the **verbatim three-heredoc block** in `${CLAUDE_PLUGIN_ROOT}/references/curated-layout-seed.md` §"Seed payload (run verbatim)" — apply the `<knowledge-title>` / date substitutions described above before running. The three `cat > … <<'EOF'` seeds are `wiki/index.md` (curated MAP front door, `MACHINE-OWNED:OVERVIEW-NARRATIVE` + `MACHINE-OWNED:ROOT-INDEX`), `wiki/overview.md` (stub), and `<knowledge_root>/SCHEMA.md` (the knowledge-native contract).

**(c) Move the control log under `wiki/meta/`.** Create the meta dir and seed
`wiki/meta/log.md` **directly** — not via `control-path.py log`: the direct
write keeps the seed self-contained (no resolver round-trip), and the resolver
now defaults a file absent from both layouts to `wiki/meta/` anyway, so the
direct seed and the canonical resolution agree.
`_knowledge_lib.meta_dir(<knowledge_root>)` is definitionally
`<knowledge_root>/wiki/meta`. This heredoc alone uses an **unquoted** delimiter
(`<<EOF`) so the shell expands `$(date +%Y-%m-%d)` into the log line:

```
mkdir -p <knowledge_root>/wiki/meta
cat > <knowledge_root>/wiki/meta/log.md <<EOF
# Log

Append-only record of every wiki + knowledge operation. Never rewritten.

## [$(date +%Y-%m-%d)] setup | wiki initialized
EOF
```

**(d) Drop the folded-away flat control file.** Remove only the flat `wiki/log.md`
`wiki-setup` seeded — its content now lives at `wiki/meta/log.md` (seeded in (c)).
**Keep `wiki/overview.md`** — it is the stub re-seeded in (b) that holds the
`## Recent syntheses` list `knowledge-finalize` appends to via `overview_update.py
recent-bullet`; deleting it would make the first finalize recreate a bare default:

```
rm -f <knowledge_root>/wiki/log.md
```

**(e) Advertise `schema_version 0.0.9`.** The Step 3 scaffold writes `0.0.7`; bump it via
the locked `config_bump.py` (the scaffold has no schema flag of its own):

```
python3 "$WIKI_INGEST_SCRIPTS/config_bump.py" \
  --wiki-root <knowledge_root> --key schema_version --set-string 0.0.9
```

After this step a fresh wiki has exactly `wiki/index.md` (the curated MAP front
door, overview narrative in its intro), `wiki/overview.md` (the seeded stub holding
the `## Recent syntheses` list), `wiki/meta/log.md`, and the six per-type
`wiki/<type>/index.md` stubs — no flat `wiki/log.md`. This invariant holds
**across** the first `knowledge-finalize`: finalize folds the overview narrative
into the `index.md` intro via `overview_update.py narrative-splice --target-file
index.md` and re-renders the curated root MAP (`root_index.py`), never regrowing a
competing root file. `knowledge-health`'s assertions for this shape
are a separate follow-up child of the epic — this step seeds the layout the check
will later assert; it does not add health expectations.

### 4. Write the binding manifest

**`--reframe` mode → `set-charter` (in-place, partial).** Skip the `init` call entirely. Write only the charter fields the user actually changed in Step 2.5, passing **only** those flags (an unchanged field is simply omitted — `set-charter` leaves it untouched; `framed_at` is re-stamped only when domain/audience/scope changes; `--open-themes` union-merges into the existing backlog):

```
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/knowledge-binding.py set-charter \
    --knowledge-root <knowledge_root> --knowledge-slug <knowledge_slug> \
    [--charter-domain "<new domain>"] [--charter-audience "<new audience>"] \
    [--charter-scope "<new scope>"] [--open-themes "<theme1|theme2|...>"]
```

`set-charter` writes the **same** schema-0.1.4 charter shape `init` does (it is a new action, not a new field — `schema_version` is not bumped) and is fail-soft on a pre-0.1.4 binding (it recreates a complete charter block). On `success: false` (e.g. nothing-to-update, or a `--knowledge-slug` mismatch), surface the error and stop. **Then go to Step 5's `--reframe` branch** (print the updated-charter summary; skip the first-question on-ramp).

**Normal (bootstrap) mode → `init`:**

```
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/knowledge-binding.py init \
    --knowledge-root <knowledge_root> \
    --knowledge-slug <knowledge_slug> \
    --knowledge-title "<knowledge_title>" \
    --wiki-path <knowledge_root> \
    --market <resolved market> \
    --output-language <resolved output_language> \
    [--prose-density <flag>] [--tone <flag>] [--citation-format <flag>] [--target-words <flag>] \
    [--charter-domain "<resolved domain>"] [--charter-audience "<resolved audience>"] \
    [--charter-scope "<resolved scope>"] [--open-themes "<theme1|theme2|...>"]
```

`--market` / `--output-language` carry the Step 2.5 resolution into `binding.json::research_defaults` (schema 0.1.2). The four charter args carry the Step 2.5 charter interview into `binding.json::charter` + `topic_lineage.open_themes[]` (schema 0.1.4) — pass each only when resolved (a skipped/blank charter field simply omits the flag and falls through **script-side** to `""`; `framed_at` is stamped only when any charter field is non-empty). The four writer-quality flags are likewise passed only when the user supplied them; **omitted flags fall back script-side** to the `DEFAULT_RESEARCH_DEFAULTS` block (`dach`/`en`/`executive`/`objective`/`ieee`/`2000`), so a plain `init` still writes a complete schema-0.1.4 binding (`research_defaults` complete, `charter` all-`""`, `open_themes` `[]`). The script returns the standard `{success, data, error}` envelope. On failure (e.g. binding already exists), surface the error. The script refuses to overwrite an existing binding — Step 1's pre-flight should have caught that, but the script is the second line of defence.

### 5. Final summary + first-question on-ramp

**`--reframe` mode → updated-charter summary, no on-ramp.** Print a short confirmation of the re-framed charter (domain / audience / scope, and any seed themes added) and **stop**. Do **not** run the first-question on-ramp — a base being re-framed already has projects, so the right next step is `knowledge-resume --knowledge-slug <slug>` (to see where it stands) or `knowledge-plan --knowledge-slug <slug> --topic '...'` (to frame the next research question against the freshened charter), not a first-question chain. Point at those and end the run.

**Normal (bootstrap) mode** — the rest of this step.

First print a short summary, ≤ 8 lines:

- Knowledge base path (absolute)
- Knowledge slug and title
- Wiki path (`<knowledge_root>` — they are the same in the default layout)
- Binding file path (`<knowledge_root>/.cogni-knowledge/binding.json`)
- Charter (when set): domain `<charter.domain>`, audience `<charter.audience>`, scope `<charter.scope>`
- Defaults: market `<resolved market>`, output language `<resolved output_language>`, density `<prose_density>`, tone `<tone>`, citations `<citation_format>`, target `<target_words>`w (all inherited by `knowledge-plan`; overridable per run)

Do not print the full binding JSON in the summary — point at the file path and let the user inspect it if they want.

**Then the first-question on-ramp.** A fresh base is empty — the value of setup is leaving the user with a *framed first research question*, not just a binding. Replace the old static "suggested next action" line with one interactive prompt:

- **Skip the prompt entirely** on a non-interactive / `--no-charter` (flag-only) run — print the static guidance instead (the bullet below) and stop. Automation-safe: setup never blocks waiting for input it can't get.
- **Otherwise** ask once with `AskUserQuestion`: *"Frame your first research question now?"*. When `open_themes[]` is non-empty, surface the seed themes as the selectable options so the user picks **which one** to frame first (single select; default = the first seed theme); always include a "No — pick later" option.
  - **A theme is chosen (Yes)** → chain straight into the existing per-question framing:
    ```
    Skill("cogni-knowledge:knowledge-plan",
          args="--knowledge-slug <slug> --topic '<chosen seed theme>' --frame")
    ```
    `--frame` forces `knowledge-plan`'s Step 0.4 per-question topic-framing (which now inherits this base's charter as grounding), so the user leaves with a sharpened first question + `plan.json` + `.metadata/framing.md`. **The chain stops at `plan`** — `knowledge-curate` → `knowledge-fetch` → … each cost web/tokens, so they stay the user's explicit per-run decision. Do **not** auto-run any phase past `plan`.
  - **No — pick later** → print the static next-action guidance below, listing `open_themes[]` as the candidate menu.

Static next-action guidance (printed on skip / "pick later"):

> Next: `cogni-knowledge:knowledge-plan --knowledge-slug <slug> --topic '<one of your seed themes>'`, then `knowledge-curate` → `knowledge-fetch` → `knowledge-ingest` → `knowledge-compose` → `knowledge-verify` → `knowledge-finalize`. Seed themes for this base: `<open_themes joined by ', '>` (or "none — pick any topic" when empty).

## Edge cases

- **Wiki exists but is for a different domain.** Step 2 detects the existing wiki and re-uses it. This is intentional — a user may want to layer a knowledge base onto an existing wiki. The binding records only `wiki_path`; the wiki's own slug is read live from `<wiki_path>/.cogni-wiki/config.json` whenever a consumer needs it, so a wiki rename never causes the binding to drift.
- **`--knowledge-slug` collides with a sibling directory.** Step 1's binding-existence check protects against double-init; if the sibling is a non-wiki directory, Step 2's foreign-files check fires.
- **The wiki scaffold fails mid-run.** No binding has been written. Surface the scaffold error (the `mkdir` / `config.json` write); the user can re-run after fixing it.

## Out of scope

- Does NOT write wiki pages — that is `cogni-wiki:wiki-ingest`'s job (transitively via `knowledge-ingest`).
- Does NOT pre-fill the wiki with cogni-wiki foundations — that is deliberately left for the user's deposit-driven seeding (or opt-in `cogni-wiki:wiki-prefill`).
- Does NOT configure source mode — that happens during `knowledge-plan`, where the topic is known.
- Records only the knowledge-base **defaults** (`market`/`output_language` + the four writer-quality knobs `prose_density`/`tone`/`citation_format`/`target_words`) in `binding.json::research_defaults` (Step 2.5, schema 0.1.2). The per-run choice still lives in `knowledge-plan` — a single plan can override any base default with its own matching flag (e.g. an English report about a German market, or an `executive`-density draft on a `standard`-default base).
- The **charter** (Step 2.5, schema 0.1.4) is **domain / audience / scope / seed-themes only** — the coarse base steering. It deliberately does NOT carry the writer-quality knobs (those stay per-run on `knowledge-plan`) and is NOT a per-question prompt: the finer per-research-question framing remains `knowledge-plan` Step 0.4's job, which inherits this charter as grounding.
- Does NOT run any pipeline phase past `plan`. The Step 5 on-ramp chains at most into `knowledge-plan --frame` (cheap, no-web decomposition); `knowledge-curate` onward stay the user's cost-bearing per-run decision.
- **`--reframe` re-steers the charter only** (domain / audience / scope / *additional* seed themes), in place via `set-charter`. It does NOT re-run wiki setup, does NOT re-run `init`, does NOT re-resolve `market`/`output_language` (those live in `research_defaults`, untouched), and does NOT run the first-question on-ramp. It only ADDS seed themes (union-merge) — removing or replacing a seed theme stays a hand-edit. The charter's data shape (schema 0.1.4) is unchanged.

## Output

- A directory at `<knowledge_root>/` containing:
  - `.cogni-wiki/config.json` (written natively by Step 3)
  - `.cogni-knowledge/binding.json` (from `knowledge-binding.py init`)
  - `raw/`, `assets/`, and the curated `wiki/` output layout below.

No files are written outside `<knowledge_root>/`.

### Curated wiki-output layout (contract, `schema_version` 0.0.9)

The inverted pipeline deposits its knowledge into `wiki/` as a **curated,
progressively-disclosed** tree — a single front door over per-type sub-indexes,
not a flat dump:

```
wiki/
├── index.md            ← curated MAP front door (root_index.py): the overview
│                          narrative (MACHINE-OWNED:OVERVIEW-NARRATIVE) in its
│                          intro, then one `## <theme>` section per theme, each a
│                          count-link to the sub-indexes below — no per-page bullets.
├── overview.md         ← stub: points at index.md; holds the `## Recent
│                          syntheses` list (overview_update.py recent-bullet).
├── concepts/index.md   ← per-type sub-index (exists today via concepts_index.py)
├── sources/index.md    ┐
├── questions/index.md  │
├── syntheses/index.md  │ per-type machine-owned sub-indexes
├── entities/index.md   │
├── people/index.md     ┘
└── meta/               ← visible control files: log.md, context_brief.md,
                           open_questions.md
```

**`schema_version` 0.0.9 is additive and read-forward.** It adds the
first-class `person` page type (`wiki/people/`, split
out of the catch-all `entity`) to the curated layout the previous bump
declared, on top of the existing per-type-directory contract. As with the 0.0.6 (`sources/`), 0.0.7 (`questions/`), and 0.0.8
(curated layout) bumps, an older-but-post-migration wiki reads forward without
a rewrite — an absent `wiki/people/` directory on a 0.0.8 base is harmless;
**0.0.5 remains the hard-fail boundary** (pre-migration wikis still abort). This is the wiki `schema_version`, distinct
from the cogni-knowledge plugin version.

**Layout seeding for NEW wikis lands here** (Step 3.5 above) — a fresh wiki opens
in this curated shape (`wiki/index.md` curated MAP front door with the overview
narrative in its intro, `wiki/overview.md` stub, `wiki/meta/log.md`, per-type
sub-index stubs, `schema_version 0.0.9`). The **`wiki/meta/` control-file path centralization**
(flipping the canonical write target, with a legacy fallback) and the
**lint/health enforcement** of the exemption below remain follow-up children of
this epic. Until the path centralization lands, the legacy flat paths
`wiki/context_brief.md` and `wiki/open_questions.md` remain valid; `wiki/meta/` is
the seeded home for `log.md` and the **declared target** the rest of the layout
work builds toward.

**Overview ownership (landed).** The overview narrative is folded *into* the
`wiki/index.md` intro (the `MACHINE-OWNED:OVERVIEW-NARRATIVE` block lives there).
`knowledge-finalize` maintains it via `overview_update.py narrative-splice
--target-file index.md` and re-renders the curated root MAP (`root_index.py`), so
the seeded shape survives the first finalize byte-for-byte (the seeded intro line
matches `root_index.py`'s, so the first render is a no-op on the intro). So
**seeding (Step 3.5) seeds the folded shape directly**: `wiki/index.md` carries the
`OVERVIEW-NARRATIVE` block + the `ROOT-INDEX` marker, and `wiki/overview.md` is a
stub holding only the `## Recent syntheses` list. The vendored `wiki_index_update.py`
stays byte-identical — `root_index.py` is a new CK-side script (Option A).

**Per-type `index.md` is a machine-owned sub-index, not a page.** Each
`wiki/<type>/index.md` is generated, not authored, so it is **exempt from the
`entries_count`, `orphan_page`, and `reverse_link_missing` checks** — the same
structural exemption the lint/health tooling already grants `is_audit_slug`
pages (`lint-*` / `health-*`). Declaring the exemption here gives the
lint/health-enforcement follow-up a contract to point at.

## References

- `${CLAUDE_PLUGIN_ROOT}/references/delegation-contract.md` — what this skill owns vs. delegates (incl. §"How `Skill(...)` blocks are written")
- `${CLAUDE_PLUGIN_ROOT}/references/differentiation-thesis.md` — why wiki-first
- `${CLAUDE_PLUGIN_ROOT}/scripts/vendor/cogni-wiki/` — the vendored wiki engine Step 3.5 calls (`config_bump.py`, `sub_index.py`)
- `${CLAUDE_PLUGIN_ROOT}/scripts/knowledge-binding.py --help`