refresh and update: keep generated files current

Two commands keep the files Paqad generated in line with your project and with the installed version of Paqad:

• paqad-ai refresh rebuilds specific generated files after something in your project changed, such as a new framework dependency. You choose exactly what to rebuild.
• paqad-ai update brings a project's framework-managed files up to date with the version of Paqad installed on your machine, typically right after you upgrade the package.

Both are scripts. Neither asks an AI model to write content.

refresh rebuilds only what you name

paqad-ai refresh [--stack] [--context] [--providers] [--rules [--force]] [--reconcile-module-map] [--project-root <path>]

Every target is opt-in. Running paqad-ai refresh with no flags changes nothing; it prints the list of targets and exits. You can combine several flags in one run.

Flag	What it rebuilds
--stack	Detects the stack again, rewrites the cached stack snapshot and the stack notes in docs/instructions/stack/, updates the stack and capabilities in .paqad/project-profile.yaml, and records what changed in .paqad/stack-drift.json.
--context	Brings the chunk and vector indexes used by RAG (the optional code search index) up to date with your files. See rag.
--providers	Re-renders the entry file of every AI tool that is already set up (for example CLAUDE.md or AGENTS.md). Tools without an entry file are left alone, so this never adds a new tool.
--rules	Regenerates docs/instructions/rules/ from Paqad's rule packs for your saved stack and capabilities. On its own it only reports what it would delete and write. Add --force to apply.
--reconcile-module-map	Compares docs/instructions/rules/module-map.yml with your source folders. It exits with 1 when they have drifted apart and writes the details to .paqad/module-map/drift.json. It is skipped with a message when your stack pack does not declare source folders.
--force	Only has an effect together with --rules.

Take care with --rules --force

A stack refresh resets capabilities

refresh --stack replaces the project's active capabilities with what detection recommends. If you changed them by hand with paqad-ai capabilities, check them again afterwards with paqad-ai capabilities list.

What refresh leaves alone

Refresh never touches the design system notes in docs/instructions/design-system/. Those belong to the documentation workflow, which your AI tool runs when you prompt create documentation.

update syncs files with the installed version

paqad-ai update [--project-root <path>] [--silent]

update does not download or install anything. It works with the version of paqad-ai already on your machine and needs an onboarded project (it stops if .paqad/project-profile.yaml is missing). In order, it:

1. Moves the .paqad/ folder layout forward if this version expects a newer layout. If the project was set up by a newer Paqad than the one installed, it stops and asks you to upgrade.
2. Rebuilds the framework-managed files in a temporary folder from your saved profile, then copies them into the project. Files marked as yours to keep, such as the rules in docs/instructions/rules/, are skipped when they already exist, and the report shows their old and new content so you can merge by hand. Files marked as auto-updating, including the AI tools' entry files such as CLAUDE.md and AGENTS.md, are overwritten with the current version.
3. Refreshes the team settings in .paqad/configs/: new options appear commented out, options this version no longer knows are removed, and every value your team set is kept.
4. Records the new version in .paqad/framework-version.txt and adds a line to .paqad/audit.log.

It prints a JSON report with previous_version, target_version, regenerated, skipped, new_scripts and config_keys_pruned, among other fields. With --silent it prints nothing and writes the outcome to .paqad/audit.log only, exiting with 1 on failure.

Upgrading Paqad itself

To move to a newer release, upgrade the package and then sync the project:

npm install -g paqad-ai@latest
paqad-ai update

In Claude Code and Codex CLI sessions where Paqad's hooks are active, a session-start hook can do this for you in the background: it checks for a newer version (every 12 hours by default), runs the same two steps silently, and never blocks the session. This is controlled by the auto_update setting (on by default), version_check_interval_hours and minimum_version in .paqad/configs/.config.app. Other AI tools do not run this hook, so upgrade by hand there.