> ## Documentation Index
> Fetch the complete documentation index at: https://saydo-5cd0e3d7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Adoption Modes

> Control how aggressively Claude uses your wiki versus raw source files.

Adoption modes let you roll out the wiki gradually. Start with light integration, validate the output, then increase Claude's reliance on the wiki as you gain confidence in it.

The mode is set in `.wiki-compiler.json` and takes effect at the start of the next Claude session.

## The three modes

| Mode                | Claude's instruction                            | Your CLAUDE.md / AGENTS.md                |
| ------------------- | ----------------------------------------------- | ----------------------------------------- |
| `staging` (default) | "Wiki available — check it when you need depth" | Unchanged                                 |
| `recommended`       | "Check wiki articles before raw files"          | Unchanged                                 |
| `primary`           | "Wiki is your primary knowledge source"         | You can optionally simplify startup reads |

### staging

The default mode. Claude is told the wiki exists and can consult it for depth, but it is not instructed to prefer it over raw files. Your existing AGENTS.md and CLAUDE.md are completely untouched.

Use `staging` while you're validating that the compiled articles are accurate and well-structured.

### recommended

Claude is instructed to check wiki articles before reading raw source files. This is the main efficiency win — Claude reads a single synthesized article instead of scanning many raw files for each question.

Your CLAUDE.md and AGENTS.md remain unchanged. The prioritization instruction is injected by the SessionStart hook.

### primary

Claude treats the wiki as its primary knowledge source. At this level, you can optionally simplify your AGENTS.md startup reads, since Claude will default to the wiki rather than raw files.

Use `primary` once you've run `/wiki-compile` regularly, validated topic articles across several sessions, and trust the coverage indicators.

## How mode injection works

The plugin never modifies your CLAUDE.md or AGENTS.md. Instead, it uses a **SessionStart hook** to inject context at the beginning of each session. The hook reads the current `mode` from `.wiki-compiler.json` and adds the appropriate instruction to Claude's context.

This means:

* Changing the mode takes effect at your next session start — no restart required
* Rolling back is instant: change `mode` back to `staging` and the stronger instructions disappear
* Your existing project files are never touched

<Note>The SessionStart hook runs automatically once the plugin is installed. You don't need to configure it — it reads `.wiki-compiler.json` on its own.</Note>

## Changing mode

Edit the `mode` field in `.wiki-compiler.json` directly:

```json theme={null}
{ "mode": "staging" }
```

```json theme={null}
{ "mode": "recommended" }
```

```json theme={null}
{ "mode": "primary" }
```

## Recommended progression

<Steps>
  <Step title="Start with staging">
    Run `/wiki-init` and `/wiki-compile`, then leave the mode at `staging`. Use Claude normally and let it consult the wiki organically. Check a few topic articles manually to see if they accurately reflect your knowledge.
  </Step>

  <Step title="Move to recommended">
    Once you're satisfied that the compiled articles are accurate and cover your main topics, change to `recommended`. Claude will start preferring wiki articles over raw files for research. Watch for cases where it returns wrong or outdated information — those point to articles that need a recompile or a section with low coverage.
  </Step>

  <Step title="Move to primary">
    After several sessions in `recommended` mode without quality issues, switch to `primary`. At this point you can also simplify your AGENTS.md startup reads, since Claude will default to `INDEX.md` and relevant topic articles instead of scanning raw directories.
  </Step>
</Steps>

<Tip>You can move backwards at any time. If you add a large batch of new source files and want Claude to fall back to raw files while you recompile, switching to `staging` takes effect immediately at the next session.</Tip>

## Safety guarantees

* Your CLAUDE.md and AGENTS.md are **never modified** by the plugin
* The wiki output directory can be **deleted and regenerated** at any time
* Changing `mode` back to `staging` immediately reduces Claude's wiki reliance
* Deleting `.wiki-compiler.json` disables the SessionStart hook entirely