> ## Documentation Index
> Fetch the complete documentation index at: https://llmwiki.atomicstrata.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Detecting and Repairing Stale and Orphaned Wiki Pages

> llmwiki tracks source freshness and flags stale and orphaned pages. Learn how to detect them with lint and repair them with refresh --stale.

Every wiki page llmwiki generates records the source files - and their content hashes - that produced it. At compile time, those hashes are written to `.llmwiki/state.json`. On any subsequent command, llmwiki compares the recorded hashes against the current state of `sources/` on disk. This comparison is **source freshness tracking**: a lightweight, on-demand signal that tells you whether each page still accurately reflects the sources it was built from, without requiring a full recompile to find out.

When sources drift out of sync with the compiled wiki, llmwiki surfaces the issue clearly so you can repair it deliberately rather than discovering it through stale query results.

## The two freshness states

### Stale

A page is **stale** when at least one of its owning sources still exists on disk but its content has changed since the last compile. The recorded hash in `.llmwiki/state.json` no longer matches the file's current content hash. The page exists and is readable, but it may no longer accurately represent the current state of the source material.

A page with multiple contributing sources is also marked stale when a subset of those sources was deleted - the surviving sources are still present, but the page can no longer be fully regenerated without them.

### Orphaned

A page is **orphaned** when every source that produced it has been deleted from `sources/`. The page exists on disk but has no living source to regenerate it from. Orphaned pages are flagged by `llmwiki lint` and are candidates for cleanup.

<Note>
  Query pages (saved answers written by `llmwiki query --save`) are never marked stale or orphaned - they are generated answers, not source projections. Their freshness status is always `unverified`.
</Note>

## How llmwiki detects freshness

Freshness is derived on demand. There is no background watcher or daemon involved. When you run a command that checks freshness - `llmwiki lint`, `llmwiki status`, or `llmwiki refresh --stale` - llmwiki:

1. Reads `.llmwiki/state.json`, which records the per-source content hashes from the last compile along with each source's ownership map (which concept slugs it produced).
2. For each source in the state file, checks whether the file still exists on disk and hashes its current content if so.
3. Compares the current hash against the recorded hash for each source.
4. Applies the classification algorithm to each page:
   * If state is missing or corrupt → `unverified`
   * If all owning sources were deleted → `orphaned`
   * If any owning source was deleted, or any live owning source has a changed hash → `stale`
   * If all live owning sources match their recorded hashes → `fresh`

This hashing pass happens once per command and is shared by every consumer - lint, export, MCP tools, the viewer - so freshness is never computed redundantly in a single run.

## Where staleness is surfaced

You don't need to run a dedicated freshness check to know about stale pages. The signal propagates across all of llmwiki's output surfaces.

**`llmwiki lint`** lists every stale and orphaned page as named lint results, alongside broken links, missing citations, and other quality issues. Stale and orphaned pages contribute to the health score reported by `llmwiki eval`.

**`llmwiki status`** (and the MCP `wiki_status` tool) returns a structured snapshot that includes stale and orphaned page counts, the full list of affected slugs, and a `stateStatus` field that reports whether `.llmwiki/state.json` is `ok`, `missing`, or `corrupt`.

**Local viewer** (`llmwiki view`): an open page's metadata rail displays a badge for its freshness status - **STALE**, **ORPHANED**, **CONTRADICTED**, or **ARCHIVED**. The **Concepts** screen (`#/concepts`) marks each row with a freshness dot and filters the list by freshness axis; **Health & lint** (`#/health`) shows the aggregate counts, and the header pill reports the whole-wiki verdict. If `.llmwiki/state.json` is missing or corrupt, a corrupt-state banner appears at the top of the viewer and the header reports freshness as unverified rather than fresh.

**MCP `get_context_pack`**: the evidence pack includes a `freshnessStatus` field per page, so agents consuming the pack know which pages may be outdated before reasoning over them.

**JSON export** (`llmwiki export --target json`): each page record in the export envelope includes freshness metadata, making it inspectable downstream or importable into tools like [`@atomicmemory/llmwiki`](https://github.com/atomicstrata/atomicmemory/tree/main/packages/llmwiki).

**`llmwiki next`**: when stale pages exist, `llmwiki next` recommends running `llmwiki refresh --stale` as your next action, so you're guided toward repair naturally.

## Repairing stale pages

### `llmwiki refresh --stale`

`llmwiki refresh --stale` is the targeted repair command. It does three things:

1. **Recompiles the changed owning sources** - only the sources that changed and own stale pages are sent back through the two-phase LLM pipeline. Sources that are new and have never been compiled are deliberately skipped.
2. **Cleans up orphaned pages** - pages whose every source was deleted are removed from `wiki/`. This cleanup requires no LLM calls and no API key.
3. **Leaves unrelated pages untouched** - pages whose sources haven't changed are not reprocessed, even if other pages in the project are stale.

<Warning>
  `llmwiki refresh --stale` does **not** pick up new source files that have never been compiled. If you've added new files to `sources/` since the last compile, run `llmwiki compile` to ingest them. Use `refresh --stale` specifically for repairing pages whose sources changed or were deleted.
</Warning>

### Preview with `--dry-run`

Before committing to a repair, preview exactly what `refresh --stale` would do:

```bash theme={null}
llmwiki refresh --stale --dry-run
```

`--dry-run` prints the repair plan - which sources will be recompiled, which orphaned pages will be cleaned up - without making any LLM calls or writing anything to disk. Use this to verify the scope of the repair before running it for real.

### Cleanup-only refreshes

When all stale pages are orphaned (every affected source was deleted, no sources merely changed), the repair requires no LLM calls - it's a filesystem cleanup only. You can run `llmwiki refresh --stale` in this case **without any provider credentials configured**.

## Review policy and refresh

If your project has a review policy declared in `.llmwiki/config.json`, `llmwiki refresh --stale` honors it the same way `llmwiki compile` does. Pages that trip a hold condition (low confidence, contradicted, schema-violating, or provenance-violating) are queued as candidates in `.llmwiki/candidates/` rather than written directly to `wiki/`. Configuration is fail-closed - a malformed config aborts the refresh rather than silently disabling the policy.

```json theme={null}
{
  "version": 1,
  "review": {
    "hold": ["low-confidence", "contradicted"],
    "lowConfidenceThreshold": 0.5
  }
}
```

## Corrupt state

If `.llmwiki/state.json` is missing or contains invalid JSON, llmwiki surfaces the problem explicitly. It does **not** silently create a `.bak` file or fall back to an empty state. Instead:

* `llmwiki lint` and `llmwiki status` report `stateStatus: "missing"` or `stateStatus: "corrupt"` and list all pages as `unverified`.
* The local viewer shows a corrupt-state banner.
* `llmwiki refresh --stale` will report the corrupt state and cannot proceed.

To recover, rebuild the state file from scratch by running a full compile:

```bash theme={null}
llmwiki compile
```

This regenerates `.llmwiki/state.json` from the current `sources/` directory and produces fresh pages. After compile completes, freshness tracking resumes normally.

## Repair workflow

<Steps>
  <Step title="Check what's stale">
    Run `llmwiki lint` to see which pages are stale or orphaned, along with any other quality issues in the wiki.

    ```bash theme={null}
    llmwiki lint
    ```

    Look for results with rule names `stale-page` and `orphaned-page`. Each result names the affected slug and the source file responsible.
  </Step>

  <Step title="Preview the repair plan">
    Before making any changes, preview what `refresh --stale` will do. No LLM calls are made and nothing is written to disk.

    ```bash theme={null}
    llmwiki refresh --stale --dry-run
    ```

    Review the output to confirm the scope: which sources will be recompiled, which orphaned pages will be deleted.
  </Step>

  <Step title="Run the repair">
    Once you're satisfied with the plan, run the repair for real:

    ```bash theme={null}
    llmwiki refresh --stale
    ```

    Stale pages whose sources changed are recompiled. Orphaned pages are cleaned up. Unrelated pages are not touched.
  </Step>

  <Step title="Verify resolution">
    Run `llmwiki lint` again to confirm that no stale or orphaned pages remain:

    ```bash theme={null}
    llmwiki lint
    ```

    If any stale pages are still present, check whether their source files exist and whether you may have new sources that need a full `llmwiki compile`.
  </Step>
</Steps>

<Tip>
  The best way to avoid accumulating stale pages is to keep `llmwiki watch` running during active editing sessions. It monitors `sources/` for changes and triggers an incremental recompile automatically whenever a file is saved - so pages stay fresh as you work rather than drifting until you notice.

  ```bash theme={null}
  llmwiki watch
  ```
</Tip>

## Related reference pages

* [CLI reference: lint and eval](/cli/lint-eval) - full documentation for `llmwiki lint` rules and `llmwiki eval` thresholds
* [CLI reference: compile and refresh](/cli/compile) - incremental compilation and the `--review` flag


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.