> ## 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.

# Troubleshooting

> Common issues and how to resolve them

<Note>
  Your source files are never modified by the wiki compiler. The wiki writes only to the configured `output` directory, and the entire wiki can be deleted and regenerated at any time from your source files. Nothing is permanent.
</Note>

Run `/wiki-lint` at any time for a health check on your compiled wiki. It surfaces stale articles, orphan pages, missing cross-references, contradictions, and schema drift in one pass.

## Common issues

<AccordionGroup>
  <Accordion title="Wiki not found or INDEX.md missing">
    You haven't compiled yet, or the output directory was deleted.

    Run `/wiki-compile` to generate the wiki for the first time. On a large knowledge base (hundreds of files) the first compile can take 5–10 minutes — this is expected. Subsequent incremental compiles are much faster.
  </Accordion>

  <Accordion title="Configuration not found">
    The plugin can't find `.wiki-compiler.json` in your project root or any parent directory.

    Run `/wiki-init` to create the configuration file. `/wiki-init` auto-detects your markdown directories, samples your files, and proposes a topic structure for your approval before writing anything.
  </Accordion>

  <Accordion title="Articles look stale">
    Your source files changed after the last compile, so the wiki no longer reflects the current state.

    Run `/wiki-compile` to pick up the changes. The incremental compile checks modification dates and only reprocesses topics whose sources changed. You can also run `/wiki-lint` first to see exactly which topics are stale before compiling.
  </Accordion>

  <Accordion title="First compile is taking a long time">
    This is expected behavior. The first compile reads every source file and generates every topic article from scratch. On a project with hundreds of files this typically takes 5–10 minutes.

    After the first compile, incremental runs are significantly faster because only changed topics are reprocessed.
  </Accordion>

  <Accordion title="Topics don't match what I expected">
    The auto-detected topics don't align with how you think about your knowledge base.

    You have two options:

    * **Add `topic_hints`** to `.wiki-compiler.json` to seed the topic classifier with names you want:
      ```json theme={null}
      {
        "topic_hints": ["retention", "onboarding", "pricing"]
      }
      ```
    * **Edit `schema.md`** in your wiki output directory to rename or merge topics. The compiler reads `schema.md` before each run and respects your changes. After editing, run `/wiki-compile --full` to regenerate all articles with the updated structure.
  </Accordion>

  <Accordion title="Plugin commands not available after install">
    Claude Code needs to restart to register the plugin's hooks and commands.

    Quit Claude Code completely and reopen it. If the commands are still missing, verify the plugin installed correctly:

    ```bash theme={null}
    claude plugin list
    ```

    If `llm-wiki-compiler` is not listed, re-run the install steps from the [installation guide](/installation).
  </Accordion>

  <Accordion title="Rolling back or disabling the plugin">
    To stop the plugin from injecting wiki context without uninstalling it, change `mode` in `.wiki-compiler.json` back to `staging`:

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

    In `staging` mode the plugin only mentions that the wiki is available — it does not instruct Claude to read it. To disable entirely, delete `.wiki-compiler.json`. Your source files and the compiled wiki are left untouched.
  </Accordion>
</AccordionGroup>