Paqad project profile and .config settings files

What the project profile is

The project profile is the file .paqad/project-profile.yaml. It records facts about your project: its name, which rule sets are active, the stack Paqad detected, and the commands used to install, test, lint and build it. Onboarding writes it, you commit it, and Paqad's commands and hooks read it.

The profile no longer holds framework settings such as strictness, feature switches, model names or search-index options. Those moved to separate settings files, described below. If an older profile still contains them, Paqad ignores those keys when it reads the file and removes them the next time it writes it.

What is in the file

An abridged profile for a React project looks like this. Your values come from detection.

project:
  name: paqad project
  id: paqad-project
  description: Generated by paqad-ai
active_capabilities:
  - content
  - coding
  - security
stack_profile:
  frameworks:
    - react
  traits: []
  toolchains:
    - ecosystem: node
      package_manager: pnpm
      lockfile: pnpm-lock.yaml
  version_bands:
    - name: react:^18
      package_name: react
      range: ^18
      locked_version: 18.3.1
      source: lockfile
  sources: []
commands:
  install: pnpm install
  dev: pnpm dev
  test: pnpm test -- --reporter=tap
  test_single: pnpm test -- <pattern> --reporter=tap
  lint: pnpm lint
  format: pnpm format
  migrate: echo "configure migrate command"
  build: pnpm build
compliance_packs: []
mcp:
  servers: []
custom:
  classification_dimensions: []
  verification_plugins: []
  escalation_rules: []

Section	What it holds
`project`	Name, ID and description. Onboarding fills in placeholders; change them to your own. They are kept when you onboard again.
`active_capabilities`	Which rule sets apply (see below).
`stack_profile`	What detection found: frameworks, traits such as `tailwind` or `docker`, package managers and lock files, major-version bands for key packages, and the files used as evidence. Present only for code projects.
`commands`	The commands Paqad's checks run. Onboarding fills them from your stack's defaults and may add reporter options so test results can be read (see Structured test output).
`testing`	Optional. Which test runner is used and whether it can run tests in parallel. Written by onboarding or by `paqad-ai checks run`.
`mcp.servers`	MCP servers you switch on or off by name, on top of the stack's defaults.
`compliance_packs`, `custom`	Optional project-specific additions. Empty by default.

Check the commands block after onboarding. For Node-based stacks the defaults use pnpm, even if your project uses npm or yarn, and migrate is a placeholder for stacks without a standard migration command. Edit the commands to match how your project really runs, because paqad-ai checks run uses exactly these. paqad-ai doctor fails the "Stack commands configured" check if any command is empty.

Capabilities: which rule sets apply

active_capabilities decides which groups of rules Paqad copies and applies:

content: writing and documentation rules. Always on; it cannot be removed.
coding: code-quality, testing and architecture rules plus your stack's rules. On for code projects.
security: security review rules and the security reviewer role. Always switched on together with coding.

You can list and change them with paqad-ai capabilities list, available, add <name> and remove <name> (see the capabilities reference). Two things to know: removing coding also removes the stored stack_profile (and with it security); and paqad-ai refresh --stack resets active_capabilities to what detection recommends, so a manual change can be undone by the next stack refresh.

Where framework settings live now

Settings that change how Paqad behaves are read from four places. A higher layer overrides a lower one:

PAQAD_* environment variables, for one run or one machine (for example PAQAD_AUTO_UPDATE=false).
.paqad/.config: your personal overrides. Git-ignored, so it is safe for things like API keys.
.paqad/configs/.config.app, .config.rag, .config.models and .config.policy: the team's shared settings, committed to git.
The built-in defaults.

Onboarding writes the four team files with every setting listed as a comment at its default value, plus .paqad/.config.example as a full reference. To change a setting, remove the # in front of it and set the value:

# Pull newer framework versions in the background on session start. (env: PAQAD_AUTO_UPDATE)
auto_update=false

Some settings, the "mode" settings such as stages_mode and rule_compliance, act as a floor: the team's value is the minimum, and a personal override can only make it stricter.

See which settings actually take effect

paqad-ai config effective

This prints each setting's current value, which layer it came from, and which part of Paqad reads it. It changes nothing. A setting shown as consumed by: NOTHING is read by no running code, so changing it has no effect. In 1.91.1 this includes the strictness and escalation settings (full_lane_default, require_adversarial_review, block_on_stale_docs, require_db_review_for_migrations, the escalate_* settings), the decisions_* tuning settings and research_depth. Add --json for machine-readable output.

Editing the profile safely

Edit project facts, such as the name and commands, directly in the YAML and commit the change.
Put behaviour changes in .paqad/configs/ (team) or .paqad/.config (just you), not in the profile.
Run paqad-ai doctor afterwards. The "Profile is valid" check validates the file against Paqad's schema, the formal description of which fields and values are allowed.

The project profile and where settings live