Keeping Paqad's files current

This page explains when to bring Paqad's files back in line with your project, and which command does it. For every option of the commands, see the refresh and update reference.

Which command to run after which change

What changed	Run
You added or removed a framework, upgraded a major version, or added Docker or Compose files	paqad-ai refresh --stack
A newer version of paqad-ai is installed	paqad-ai update (Claude Code and Codex CLI run this for you by default)
You want the latest framework rules, or your capabilities or stack changed	paqad-ai refresh --rules, then --rules --force
An entry file such as CLAUDE.md is outdated, or doctor flags the entry files	paqad-ai refresh --providers
You want to add another AI tool	paqad-ai onboard and tick the new tool (refresh never adds tools)
You edited rules in docs/instructions/rules/ and doctor reports "Compiled rules are current" as failed	paqad-ai rag refresh-context
RAG is on and much of the code changed	paqad-ai refresh --context
You want to check the module map against the source folders	paqad-ai refresh --reconcile-module-map
The written documentation (stack overview, architecture, design system, module docs) is out of date	Prompt your AI tool with create documentation or create module documentation
A teammate is setting up a cloned project	paqad-ai join

Not sure what changed? Run paqad-ai doctor; its suggested fixes usually name the command. See Diagnosing problems with doctor.

A plain refresh does nothing on purpose

Running paqad-ai refresh with no option changes nothing. It prints the list of targets and exits, so that it never creates files you did not ask for. You always choose what to refresh, and you can combine targets, for example paqad-ai refresh --stack --providers.

What each refresh target changes

Refreshing the stack with --stack

Runs stack detection again and compares the result with the last snapshot. It then:

• rewrites .paqad/stack-snapshot.json and records changes in .paqad/stack-drift.json (see Drift detection);
• rewrites the stack documents in docs/instructions/stack/: overview.md, frameworks.md, dependencies.md, tooling.md, version-rules.md, sources.md and drift-report.md;
• updates stack_profile and active_capabilities in the project profile to match what detection recommends.

It does not re-copy rules. If the stack change means you need different rules, follow up with --rules.

Refreshing the rules with --rules

Works out which rule files your saved capabilities and stack should have. On its own it only reports how many files it would delete and write. Add --force to apply it: every file in docs/instructions/rules/ is deleted except module-map.yml and rule-script-map.yml, and fresh copies are written.

Refreshing entry files with --providers

Rewrites the entry file, and for Claude Code, Codex CLI and Gemini CLI the hook settings, for each tool that already has an entry file. Tools without an entry file are left alone. The entry file is rewritten from Paqad's template, so if you keep your own notes in CLAUDE.md or AGENTS.md, check the diff before you commit.

Refreshing the search index with --context

Brings the RAG search index up to date with changed, added and deleted files. It only matters when RAG is switched on.

Checking the module map with --reconcile-module-map

Compares module-map.yml (the list of your project's modules, created by the documentation workflow) with your source folders and module docs, writes the findings to .paqad/module-map/drift.json, and exits with an error code if it finds differences. It reports only; it never edits the map.

What refresh never touches

The design system in docs/instructions/design-system/ belongs to the documentation workflow; refresh never creates or changes it.

Choosing between refresh and update

• paqad-ai refresh reacts to changes in your project, one target at a time.
• paqad-ai update reacts to a new Paqad version. It migrates the .paqad/ layout if needed, regenerates the files Paqad manages, skips files your project owns such as the copied rules, and adds any new settings to your .paqad/configs/ files as comments while keeping the values you set. It prints a JSON report of what it regenerated and skipped.

Because update skips the copied rules, new rule content from a newer version only reaches your project through paqad-ai refresh --rules --force.

A safe routine for any refresh

1. Commit or stash your work, so every change Paqad makes shows up on its own in git diff.
2. Run the command for what changed, using the table above.
3. Read the diff. Put back any hand edits that were overwritten.
4. Run paqad-ai doctor and deal with any failures.
5. Commit.