# Component Wiki Capture (channels.md Wiki adapter)

> **TLDR**  -  Component tasks can auto-generate wiki docs + Figma screenshots. The Wiki adapter is invoked from `/multi-agent:channels` (Phase 7 delegates, or user invokes post-hoc). Four layouts supported (`submodule`, `in-repo`, `github-wiki`, `separate-repo`)  -  adapter picked from `figmaConfig.wiki.mode`. Non-blocking: failures log a warning and channels continues to other adapters. The Wiki adapter supports scope multi-select (Case A) and a precondition-failure menu (Case B)  -  see below.

This doc is referenced from `commands/multi-agent/channels/SKILL.md` (Wiki adapter) and indirectly from `$HOME/.claude/multi-agent-refs/phases/phase-7-report.md` (which delegates all external delivery to channels). Keeping it separate keeps both files under their token budgets and gives the contract a stable location for Claude-side + Copilot-side implementations.

## Applicability

Step 2 runs only when **both** are true:

1. `state.taskType === "component"`  -  set by Phase 0 Step 7 when the task originates from a Figma URL or figma-driven instruction.
2. `figmaConfig.wiki.enabled === true`  -  enables the capture globally for the project.

Any other taskType skips silently (no prompt, no log)  -  wiki docs only make sense for UI components.

## Case A  -  preconditions met (scope multi-select)

When both applicability checks pass, channels opens a scope multi-select BEFORE dispatching:

```
What should I update in the wiki? (space = toggle, enter = confirm)
  [x] Main component page      ({Name}.md  -  variants, overview, testing IDs,
                                  localization, a11y, analytics, sub-components)
  [x] iOS sub-page             ({Name}-iOS.md  -  initializer, usage, iOS patterns,
                                  Code Connect, snapshot tests, changelog)
  [x] Screenshots              (assets/  -  Figma LTR+RTL+light+dark + iOS snapshot)
  [x] Index updates            (_Sidebar.md + ComponentImplementationStatus.md)
  [ ] Other                    (skip adapter dispatch; log "manual wiki override"
                                  to agent-log, channels.wiki returns skipped)
```

Pre-ticks from `prefs.global.wikiScope` (array of scope IDs). Saved after selection for next run.

- Selecting a subset (e.g. only Screenshots) → adapter runs with `scope=["screenshots"]`, skipping main/iOS/index writes.
- Selecting "Other" alone → adapter dispatch is skipped entirely. Phase 7 / channels logs `Wiki: manual override  -  skipped by user`. No git push, no file changes.
- Selecting nothing and confirming → same as "Other" alone (explicit skip).

The adapter receives `scope: string[]` alongside `{componentName, componentPath, figmaConfig, agentState}` and writes only the requested artifacts.

## Case B  -  preconditions missing (actionable menu)

When preconditions fail, the gap is surfaced with a fix menu instead of a silent no-op:

```
Phase 7 · Wiki  -  preconditions not met

  taskType:          {current}     ({component expected} ✗)
  figma-config.json: {found/missing}
  wiki.enabled:      {true/false/undefined}

  What should I do?
    [1] Add Figma token + config      (Token Save Flow + figma-config bootstrap)
    [2] Skip for this run only         (skipped, asked again)
    [3] Disable wiki for this project  (writes wiki.enabled=false)
    [4] Other  -  manual note          (logs "user manual wiki path" to agent-log)
```

- **[1]** dispatches to `setup.md` Token Save Flow for Figma, then bootstraps `figma-config.json` from `preferences-template.json` `_figmaConfigTemplate`. After success, re-check preconditions  -  if met, fall into Case A. If user cancels the setup, fall back to [2].
- **[2]** `phase-tracker.sh sub 7 1 "Channels/Wiki" skipped`, log line: `Wiki skipped  -  preconditions not met (this run only)`. Next run re-prompts.
- **[3]** write `figmaConfig.wiki.enabled = false` to the project config. Subsequent runs silently skip Wiki (no menu, no prompt)  -  exactly the pre-v5.7 behavior for projects that don't want wiki.
- **[4]** free-text prompt, user's note appended to agent-log under `### Wiki Manual Override`. No adapter action.

Autopilot in Phase 7 pauses at the channels menu (per modes.md contract)  -  if user selects Wiki and preconditions fail, Case B opens, user picks. Post-hoc `/multi-agent:channels` with `--channels wiki` + failed preconditions: Case B opens non-negotiably (autopilot rules don't apply to post-hoc invocations).

## Legacy prompt + preference flow (pre-v5.7, still supported for backward compat)

Interactive path (any interactive run, Full or Short), ONLY when the schema lacks `wikiScope`  -  ask with a native `AskUserQuestion` picker (never a typed y/n):

- `question`: "Generate component wiki docs?" (rendered in `outputLanguage`)
- `header`: "Wiki" (English, <=12 chars)
- `options`:
  - `{ label: "Generate", description: "Write component wiki docs for this run" }`
  - `{ label: "Skip", description: "Do not generate wiki docs" }`
- Surface the previous default (`prefs.global.wikiDefault`) as the recommended option: when it is `true`, present **Generate** first (recommended); when `false`, present **Skip** first.

Save the answer to `prefs.global.wikiDefault` for next run. Migration script (`migrate-prefs.mjs`) promotes `wikiDefault=true` → `wikiScope=["main","ios","screenshots","index"]` on first v5.7 run, then removes `wikiDefault`.

## Dispatch

1. Resolve wiki mode from `figmaConfig.wiki.mode`  -  one of `submodule`, `in-repo`, `github-wiki`, `separate-repo`. Each has a dedicated adapter inside the `figma-component-wiki` skill; see the `ai-ios-toolkit:figma-component-wiki` plugin skill for per-mode path layout and push semantics.
2. Emit progress line: `→ writing wiki {componentName} (mode: {mode})`.
3. Dispatch to the plugin skill `ai-ios-toolkit:figma-component-wiki` (iOS) or `ai-android-toolkit:figma-component-wiki` (Android), passing `{componentName, componentPath, figmaConfig}`.
4. Skill returns `{ writtenPaths[], committedSha?, pushedRemote? }`. Write `writtenPaths` to Phase 7 summary's "Files written" section and push metadata (if any) to "External publishes".
5. On adapter failure  -  log the adapter + mode + error, continue Phase 7. Wiki is a non-blocking augmentation; the Jira comment in Step 3 already carries the component summary, so the developer is never left in the dark if wiki misfires.

## Skip conditions (explicit log lines)

Explicit logs help the developer understand why wiki did or did not run:

- `state.taskType !== "component"` → skip silently (no log).
- `figmaConfig.wiki.enabled === false` → log `Phase 7: wiki disabled in figma-config.json`.
- `figmaConfig` missing entirely → log `Phase 7: wiki skipped (no figma-config for this project)`.
- User declined at prompt → log `Phase 7: wiki skipped by user`.
- Autopilot with `wikiDefault=false` → log `Phase 7: wiki skipped (autopilot + wikiDefault=false)`.
- Short run: DO prompt  -  wiki is cheap and keeps docs fresh on the fast path; skip only if the user says no.

## Success log

`Phase 7: Component wiki generated  -  {componentName} via {mode} ({paths.length} files)`

## Cross-CLI parity

Claude Code and Copilot CLI MUST:

- Resolve the adapter the same way (mode enum → adapter module).
- Emit byte-identical progress lines.
- Render byte-identical Case A / Case B menus (spacing, brackets, numbering).
- Respect `prefs.global.wikiScope` array. Legacy `wikiDefault` boolean is migrated on first v5.7 load.
- Treat adapter failures as non-blocking with the same log shape.
- Pause the Case A / Case B menu in autopilot  -  per Phase 7 autopilot exception (`$HOME/.claude/multi-agent-refs/phases/modes.md`). 30-min timeout ends session cleanly; resume re-opens menu.

`smoke-wiki-integration.sh` asserts every contract item documented above.