--- name: karpathy-wiki-capture description: | Capture-authoring protocol for the main agent. Read on demand when a TRIGGER fires (per `using-karpathy-wiki/SKILL.md`). Defines how to format a capture, how to invoke `bin/wiki capture`, body-size floors, and the subagent-report workflow. ---

# karpathy-wiki capture

You loaded this skill because a TRIGGER fired (per the loader). Your job is to write a capture file (or move a file into `inbox/` for raw-direct ingest), then return to the user's task.

## Single capture entry point

All chat-driven captures go through ONE command:

```bash echo "$BODY" | bin/wiki capture \ --title "<one-line title>" \ --kind chat-only \ --suggested-action create|update|augment ```

For chat-attached (a real file accompanies the conversation), pass the absolute path of that file via `--evidence-path`:

```bash echo "$BODY" | bin/wiki capture \ --title "<one-line title>" \ --kind chat-attached \ --suggested-action create|update|augment \ --evidence-path /absolute/path/to/source/file.ext ```

Or for long bodies:

```bash bin/wiki capture \ --title "<one-line title>" \ --kind chat-only \ --suggested-action create \ --body-file /tmp/body.md ```

`--evidence-path` is REQUIRED for `--kind chat-attached` and `--kind raw-direct`, REJECTED for `--kind chat-only`. The path lands verbatim in the capture's `evidence:` frontmatter and propagates to the manifest's `origin` field — the iron-rule contract that lets the ingester trace every wiki page back to its source.

`bin/wiki capture` handles wiki resolution (which wiki the capture goes to), prompts the user for setup if needed, writes every capture file, and asks the bounded dispatcher to drain the target queue. You do NOT write to `.wiki-pending/` directly or launch a provider yourself.

## Trigger

Triggers are listed in the loader (`using-karpathy-wiki/SKILL.md`). This skill assumes a trigger has fired and you're now writing.

## Capture file format

See `references/capture-schema.md` for the canonical frontmatter schema. Key fields you set when invoking `bin/wiki capture`:

- `--title`: one-line title (becomes filename slug + capture title). - `--kind`: `chat-only` (no file evidence) | `chat-attached` (file + conversation delta) | `raw-direct` (you do NOT write this; it's for drop-zone ingestion). - `--suggested-action`: `create` (new page) | `update` (replace existing) | `augment` (add to existing).

The body is read from stdin OR `--body-file <path>`.

## Body sufficiency

Per `references/capture-schema.md`:

| Kind | Floor | What goes in the body | |---|---|---| | `chat-only` | 1500 b | Every durable claim, exact details (URLs, version numbers, error messages), every decision-with-rationale, every gotcha, sources cited. | | `chat-attached` | 1000 b | The conversation-delta — what the conversation added that the file doesn't cover. The file is the bulk; you owe the delta in full. | | `raw-direct` | none | You don't write raw-direct bodies. The SessionStart hook or `wiki ingest-now` auto-generates them when a file appears in `inbox/`. |

A `chat-only` body must clear 1500 bytes with content, not filler. Required:

- Every durable CLAIM — fact, number, version, commit, percentage, decision. - Every CONCRETE DETAIL the ingester cannot guess — exact URLs, package names, error messages, command snippets, code examples (5-15 lines), numeric thresholds, version ranges. - Every DECISION made WITH its rationale — *"we chose X because Y failed on Z"* is a complete unit. *"we chose X"* alone is not. - Every CONTRADICTION, GOTCHA, OR CAVEAT observed. - SOURCES — doc URLs, arxiv IDs, GitHub repos with star counts as-of the session.

NOT in the body:

- Pleasantries, meta-commentary, "let me check", "good question". - Process over output: wrong turns, reasoning trail, "I thought X but then Y". Keep the resolution; drop the detour. - The user's questions verbatim — they're context, not content. Capture the ANSWER, not the question.

If the ingester rejects your capture (`needs_more_detail: true`), expand the re-queued body in place, remove both `needs_more_detail` and `needs_more_detail_reason` from frontmatter, and run `wiki tick <wiki> --source manual`. Marked captures remain durable but are not automatically retried. Do NOT ignore the rejection.

## Subagent reports — DO NOT write a capture body

When a research subagent returns a file with durable findings, the report IS the capture. Move the file to `<wiki>/inbox/`:

```bash mv <subagent-report-path> <wiki>/inbox/<basename> wiki ingest-now <wiki> # or wait for next SessionStart ```

`wiki ingest-now` triggers the same drift-scan + drain that SessionStart runs, but on demand. Use this when the user is still in the active session and wants the report ingested before they close the terminal.

Subagent-report bodies frequently exceed several KB; rewriting them as a `chat-only` capture body wastes tokens AND produces an inferior wiki page (the body summarizes what the file already says).

## Mode change

If the user asks to change the wiki mode for this directory:

```bash wiki use project # captures go to ./wiki/ only wiki use main # captures go to ~/wiki/ only wiki use both # capture locally; selectively promote reusable knowledge ```

Confirm in one line. The mode is persisted in `<cwd>/.wiki-config` (project or both) or `<cwd>/.wiki-mode` (main-only). See `references/capture-schema.md` and the v2.4 spec for details.

`both` is project-first. The original capture is written only to `./wiki/`. During ingest, the project ingester keeps project-specific knowledge local and uses the deterministic promotion helper only for reusable cross-project knowledge. The original capture is never copied verbatim to both queues.

## Cwd unconfigured (0.2.9)

If `bin/wiki capture` aborts with stderr containing `cwd unconfigured` + a `wiki use project|main|both` nudge, the cwd has no `.wiki-config` or `.wiki-mode`. The body is preserved at the orphan path printed in the same stderr. Do NOT silently re-route or auto-pick — surface the choice to the user verbatim:

> "This directory isn't configured for the wiki yet. Should this > capture go to: (a) a project wiki at `./wiki/` (scoped to this > repo), (b) the main wiki at `~/wiki/` (cross-project), or (c) both?"

After the user picks, run `wiki use project|main|both` and re-capture either by re-piping the body or by passing the orphan path:

```bash bin/wiki capture --title "..." --kind chat-only \ --suggested-action create --body-file <orphan-path> ```

Pre-0.2.9 the CLI silently auto-selected `main-only` and wrote `<cwd>/.wiki-mode`, stealing the choice from the user. The new abort makes the choice explicit.

## Order matters: reply first, then capture

Reply to the user FIRST. The user is waiting; capture mechanics are not. After your reply emits, write any captures whose triggers fired (via `bin/wiki capture`), then run a turn-closure check.

## Turn closure — before you stop

Before emitting your final assistant message, check:

```bash ls "<wiki_root>/.wiki-pending/" 2>/dev/null | grep -v '^archive$\|^schema-proposals$' | head -20 ```

If the output lists any `.md` file OR any `.md.processing` file older than 10 minutes, the turn is NOT done. Handle the pending captures first (rejection-handling, stalled-recovery, missed-capture from earlier turns), then re-check, then close the turn.

This is a self-discipline rule until a Stop-hook gate is wired.

## What's NOT in this skill

- The ingester's behavior (orientation, page format, manifest protocol). That lives in `karpathy-wiki-ingest/SKILL.md` and is loaded by the detached runtime ingester only. The main agent never reads it. - Iron laws and announce-line contract. Those live in the loader (`using-karpathy-wiki/SKILL.md`) — single source of truth.