onboard: set up Paqad in a project

paqad-ai onboard sets Paqad up in one project. You run it once, from the project's root folder. It looks at your code to work out which stack you use (for example Laravel or Next.js), asks which AI coding tools your team uses, and then writes the files those tools read: a short entry file for each tool, the project's rules, and Paqad's own settings.

The command itself is a script: stack detection and file writing are deterministic, and no AI assistant makes decisions during onboarding. The same answers on the same code produce the same set of files.

When to run onboard

• First setup of a project. One person, usually the lead, runs onboard and commits the result.
• A teammate cloning a project that is already onboarded should run paqad-ai join instead. It sets up their machine without changing the files the team has committed.
• Running it again later is treated as a refresh, not a reset. Your saved settings are kept, and entry files that already exist (such as CLAUDE.md) are not overwritten.

Synopsis and options

paqad-ai onboard [--project-root <path>] [--providers <provider...>] [--stack <stack>] [--capability <capability...>]

Option	What it does
--project-root <path>	The folder to onboard. Defaults to the current folder.
--providers <provider...>	The AI tools to set up, separated by spaces. Accepted values: codex-cli, antigravity, claude-code, gemini-cli, junie, cursor, github-copilot, windsurf, continue, aider, aiassistant. The singular --provider also works and prints a notice.
--stack <stack>	Use this stack instead of the detected one, for example laravel, nextjs, django, rails, spring-boot or node-cli.
--capability <capability...>	Add stack traits that detection may miss, such as docker, compose, tailwind, inertia or pest.

What the interactive flow asks

In a normal terminal, onboard asks a few questions:

1. Which AI tools you use. A checklist appears with Codex, Claude Code, Gemini and Junie ticked by default. Pick at least one.
2. Which stack the project uses. If detection is confident, you see the detected stack and move on. If not, you pick the stack from a list and answer a few follow-up questions (for example whether you use Tailwind CSS or Docker).
3. Whether the summary is right. You can continue, revise your answers, or abort. Nothing is written before you continue.
4. Whether to turn on RAG (coding projects only). RAG, short for retrieval-augmented generation, is an optional search index that helps the AI find relevant code. You choose a local model on your machine or an OpenAI or Voyage AI key. If this step fails, onboarding still completes with RAG switched off. See rag.

A panel headed ONBOARDING COMPLETE appears as soon as the project files are written, before the optional RAG step.

Running onboard without prompts

When there is no interactive terminal (for example in a script or CI job), onboard asks nothing. It uses your flags plus detection. If you pass no --providers, it sets up Claude Code only, and it skips the RAG step. If it finds code but cannot settle on a stack, it stops with a message asking you to pass --stack (and any needed --capability values).

paqad-ai onboard --providers claude-code codex-cli --stack nextjs

Files onboard writes

Inside the project:

• .paqad/project-profile.yaml: the project's facts, such as stack, capabilities and build commands.
• .paqad/configs/: team settings files (.config.app, .config.rag, .config.models, .config.policy) with every option listed and commented out at its default, plus .paqad/.config.example as a reference copy.
• Detection and bookkeeping records, including .paqad/detection-report.json, .paqad/stack-snapshot.json, .paqad/stack-drift.json, .paqad/onboarding-manifest.json and the .paqad/decisions/ folder.
• docs/instructions/rules/: the rules for your stack, copied from Paqad's built-in rule packs, plus reference guides under docs/instructions/tools/<stack>/.
• docs/instructions/workflows/feature-development.yaml and delivery-policy.yaml: your project's settings for the delivery workflow.
• For each selected tool: its entry file (table below) and, where the tool supports it, MCP configuration. MCP (Model Context Protocol) is the standard way AI tools connect to extra services.
• Hook configuration for Claude Code, Codex CLI and Gemini CLI. Hooks are small scripts the AI tool runs at set moments, such as before a file edit or at the end of a turn. What they can enforce depends on the tool; see adapters.
• Git post-commit and post-merge hooks that link commits to Paqad's feature records. Existing git hooks are kept and chained. Nothing is installed if the folder is not a git repository.

Outside the project, onboard creates ~/.paqad-ai/current (a link to the installed framework) and helper agent files in your home folder, for example under ~/.claude/agents and ~/.codex/agents.

Tool	Provider value	Entry file
Claude Code	claude-code	CLAUDE.md
Codex CLI	codex-cli	AGENTS.md
Gemini CLI	gemini-cli	GEMINI.md
Antigravity	antigravity	ANTIGRAVITY.md
Junie	junie	.junie/AGENTS.md
Cursor	cursor	.cursor/rules/paqad.mdc
GitHub Copilot	github-copilot	.github/copilot-instructions.md
Windsurf	windsurf	.windsurfrules
Continue	continue	.continue/rules/paqad.md
Aider	aider	CONVENTIONS.md
JetBrains AI Assistant	aiassistant	.aiassistant/rules/guidelines.md

If an entry file already exists with your own content, onboard keeps that content and adds Paqad's short section inside a clearly marked block.

What onboard does not do

Onboard does not write your project documentation. The full docs/instructions/ set, including the design system notes and the module map (a reviewable list of your project's main areas), is produced afterwards by your AI tool when you ask for it. That step is model work, so review what it produces.

Next steps after onboarding

1. In your AI tool, send the prompt create documentation. Review the module map it proposes, then send create module documentation.
2. Optionally send analyze rules and then generate rule scripts, which turns suitable rules into scripted checks.
3. If you use Codex, open Codex in the project, run /hooks and approve Paqad's hooks. Codex only loads project hooks after you trust them, and onboard prints a reminder when Codex is selected.
4. Run paqad-ai doctor to check the setup, then commit the new files.