# Refresh Docs

> Use when the user asks to refresh local reference docs, rerun `./scripts/refresh-docs.sh`, review the latest `docs/references/CHANGES.md` entry, or produce/update `docs/references/CHANGES-REPORT.md`. Trigger phrases include "refresh docs", "refresh references", "update references", "check what the refresh changed", "write the changes report". Scoped to repos that ship this specific Axon/Repomix reference-docs pipeline — requires the host project to provide `./scripts/refresh-docs.sh` and a `docs/references/` tree. Does not apply to generic documentation, README, or doc-generator refreshes in other repos.

- Skill: `dinglebear-ai/refresh-docs` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add dinglebear-ai/refresh-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dinglebear-ai/refresh-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: dinglebear-ai (https://skillmd.com/u/dinglebear-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dinglebear-ai/refresh-docs

---


# Refresh Docs Impact Review

Run the reference refresh first, then review the exact changed reference files and produce an implementation impact report. Do not make application code changes as part of this skill.

Upstream reference checks for this skill:

- `docs/references/INDEX.md`
- `./scripts/refresh-docs.sh`
- `docs/references/CHANGES.md`
- `docs/references/CHANGES-REPORT.md`
- the changed files under `docs/references/` named by the latest `CHANGES.md` entry

## Refresh Run

```!
./scripts/refresh-docs.sh
```

Use the script's options when the user asks for a narrower or non-writing run:

```!
./scripts/refresh-docs.sh --dry-run
./scripts/refresh-docs.sh --skip-crawl
./scripts/refresh-docs.sh --skip-repomix
```

`--dry-run` prints planned work and does not update `docs/references/CHANGES.md`. `--skip-crawl` refreshes Repomix XML packs and sparse-cloned FastMCP/mcporter docs only. `--skip-repomix` refreshes only Axon-crawled ACP, MCP, and Claude Code docs; it also skips FastMCP and mcporter sparse docs because those are refreshed in the Repomix phase. The script rejects using both skip flags together.

## Reference Change Log

```!
if [ -f docs/references/CHANGES.md ]; then
  awk '
    /^## / {
      if (entry != "") {
        latest = entry
      }
      entry = $0 ORS
      next
    }
    entry != "" {
      entry = entry $0 ORS
    }
    END {
      printf "%s", entry != "" ? entry : latest
    }
  ' docs/references/CHANGES.md
else
  echo "docs/references/CHANGES.md does not exist"
fi
```

## Reference Summary

```!
printf 'reference files: '
find docs/references -type f | wc -l
find docs/references -maxdepth 3 -type f \
  | sed 's#^docs/references/##' \
  | awk -F/ '{ print $1 "/" ($2 ? $2 : "") }' \
  | sort \
  | uniq -c
```

## Workflow

1. Read the latest entry in `docs/references/CHANGES.md`.
2. Normalize changed paths from the latest entry by removing list markers, surrounding backticks, and any leading whitespace inside the backticks before resolving under `docs/references/`.
3. Review every file listed as added, modified, or removed in that latest entry. For removed files, compare by slug/path intent against added or current files when possible. For large XML packs, search within the pack for relevant changed areas instead of loading the whole file at once.
4. Cross-reference the changed reference material against the implementation using `rg`, `find`, and focused file reads. Check Rust crates, scripts, skills, docs, configs, and generated contract surfaces.
5. Cross-check against `docs/references/INDEX.md` so the report uses the current reference layout and source names.
6. Identify any code, docs, config, tests, schemas, skills, scripts, or workflows that should change because of the refreshed references.
7. Identify new capabilities, commands, protocol features, examples, or workflows that the project could add because of the refreshed references.
8. Before writing a new report, run `<skill-dir>/scripts/archive-changes-report.sh`.
9. Write the new report to `docs/references/CHANGES-REPORT.md` using `references/CHANGES-REPORT-template.md` as the structure.

`./scripts/refresh-docs.sh` excludes `docs/references/CHANGES.md`, `docs/references/CHANGES-REPORT.md`, and `docs/references/archive/changes-reports/*` from the detected file-change set. Do not treat those generated report/log files as upstream reference changes.

The full refresh currently covers:

- Axon crawls copied from `AXON_OUTPUT_DIR` for `agentclientprotocol.com`, `modelcontextprotocol.io`, and `code.claude.com`.
- Repomix XML packs for ACP, MCP, FastMCP, `jmagar/aurora-design-system`, `jmagar/lab` with `docs/references/**` ignored, and mcporter.
- Sparse checkouts for `PrefectHQ/fastmcp/docs/cli` as flat top-level `.mdx` files and `openclaw/mcporter/docs` recursively.

## Bundled Resources

- `references/CHANGES-REPORT-template.md`: use this as the required report structure.
- `references/CHANGES-template.md`: documents the append-only `docs/references/CHANGES.md` entry format generated by `./scripts/refresh-docs.sh`.
- `scripts/archive-changes-report.sh`: run this before creating a new `CHANGES-REPORT.md`.

## Report Requirements

The report must include frontmatter with at least:

- `title`
- `generated_at`
- `source_changes_log`
- `reviewed_change_entry`
- `reviewer`

The report body must include:

- Latest refresh summary.
- Every changed reference file reviewed, with status.
- Upstream reference paths used for the review.
- Affected implementation areas and exact file paths.
- Required changes, if any.
- New additions or opportunities enabled by the refreshed references.
- Tests or verification that should be run before implementing any follow-up work.
- Unknowns or areas needing human/product judgment.

If no local code changes are needed, say that explicitly and explain why.