Agentic Install Runbook

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

Canonical agentic installer

This is the fastest supported route from an AI conversation to a verified AIWG project. The user pastes one prompt; the provider inspects, plans, asks only for decisions it cannot safely infer, installs or repairs AIWG, deploys `all`, builds indices, regenerates context, and verifies engagement.

For a new, outdated, broken, duplicate, or development-mode installation, use the public `SetupManifest`. A user can paste:

Install or repair AIWG for this project by following
https://aiwg.io/setup.aiwg.yaml
Explain the plan before changing anything, preserve my existing work, and ask
me only for choices you cannot safely determine.

The manifest is the canonical flow. It requires inspection before mutation, explicit approval for repairs and mode switches, preservation of source checkouts, the complete `all` deployment, index construction, regeneration, and evidence-based verification. Use the manual notes below when the manifest cannot be retrieved.

The public manifest declares `metadata.execution_mode: provider-orchestrated`. Give it to a supported AI provider; do not run it with the agent-owned setup-run operation. `setup-run` is the deterministic runner for script-first application manifests. This distinction is intentional: AIWG installation repair must reason about existing checkouts, duplicate binaries, provider state, and user-authored files.

Which path applies?

Scenario	Route
New project, existing project, stale/broken install, or development checkout	Paste the canonical prompt into the provider
Multiple providers in one project	Use the prompt and have the installer deploy and verify each provider separately
CI, cloud-init, container image, SSH-only, or other headless provisioning	Use Non-Interactive Installation
Offline or restricted registry/proxy environment	Use an approved package/cache source, then follow the manual verification sequence below
Provider cannot retrieve the URL	Paste the manifest contents or use the manual fallback
Provider cannot execute local tools	Use the manual fallback, then ask the provider only to verify engagement
Read-only workspace or insufficient permissions/disk	Resolve the environment constraint before deployment; do not force partial setup

Use this runbook when an agent or steward needs to take a machine or project from zero to a working AIWG session. The human-facing path is short: install AIWG, deploy the right artifacts, open the chosen agentic platform, and ask the steward to verify setup. Most AIWG CLI commands are tools for the agent to call inside the session, not commands the user has to learn.

Choose The Setup Scope

Use project-local setup for a repository, product, investigation, campaign, or research corpus. This is the default and keeps project context isolated.

Use global/user-scope setup when the user wants the same AIWG agent surface available across many workspaces. This is useful for personal defaults and for providers whose primary artifact location is under the user's home directory, but it can make unrelated projects share more context than expected.

If the user is unsure, choose project-local setup first.

Prerequisites

AIWG requires Node.js 20 or newer. New installs should use the current LTS Node line. Reuse a healthy version manager already present; do not stack managers. When none is installed, prefer `nvm-sh` on macOS, Linux, and WSL, or `nvm-windows` on native Windows.

node the version option
npm the version option

If Node or npm is missing, install them before continuing. On macOS, use the macOS Install Guide when npm global installs fail with `EACCES`.

Install AIWG

Install AIWG once for the user:

Use AIWG to complete this documented outcome: Install AIWG once for the user
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

If `aiwg` is not on `PATH`, use npm's global prefix to find the binary:

npm config get prefix
"$(npm config get prefix)/bin/aiwg" the version option

In automation or fresh shells where PATH may be unreliable, use `npx` with an explicit package name and version policy approved for that environment:

Use AIWG to complete this documented outcome: In automation or fresh shells where PATH may be unreliable, use npx with an explicit package name and version policy approved for that environment
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Project-Local Setup

Run these commands from the project root:

Use AIWG to complete this documented outcome: Run these commands from the project root
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

the agent-owned use operation performs deployment, index refresh, canonical-context generation, provider wiring checks, and scoped verification before reporting one outcome. Do not append standalone maintenance commands to an ordinary successful setup.

Replace the provider when the user is not using Claude Code:

Use AIWG to complete this documented outcome: Replace the provider when the user is not using Claude Code
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

For guided setup, use the wizard instead of choosing the framework and provider manually:

Use AIWG to complete this documented outcome: For guided setup, use the wizard instead of choosing the framework and provider manually
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Global Or User-Scope Setup

Use the global option when the user wants provider-native AIWG assets across many workspaces without a full deployment in every project:

Use AIWG to complete this documented outcome: Use the global option when the user wants provider-native AIWG assets across many workspaces without a full deployment in every project
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

This installs framework and base kernel assets at user scope, then writes only the lightweight `WORKSPACE.md`/`AIWG.md`/provider bootstrap files in the current project. In additional projects, run the agent-owned regenerate operation to create those context-only hooks.

Use `the scope option user` instead when an additive project deployment is intentional:

Use AIWG to complete this documented outcome: Use the scope option user instead when an additive project deployment is intentional
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Consult the provider matrix before using the global option; providers without a filesystem-discovered user scope still need their documented project adapter.

For non-interactive provisioning, target a project directory explicitly:

Use AIWG to complete this documented outcome: For non-interactive provisioning, target a project directory explicitly
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Use the non-interactive guide for cloud-init, Docker, and CI examples: Non-Interactive Installation.

Provider Handoff

After deployment, open the chosen agentic platform in the project or workspace that was just configured. Then ask:

Check that AIWG is installed correctly and tell me what I can do here.
Read the agent-owned status operation the probe option, report the engaged state, project root, provider
files, deployed frameworks, and one recommended next action.

Provider notes:

Provider	Open after deploy	First check
Claude Code	Continue in the project; restart only if verification finds cached context	Ask the steward to verify AIWG status
Codex	Continue in the project; restart only if verification finds cached context	Ask for AIWG status and one next action
Cursor	Open the project in Cursor	Ask Cursor to verify AIWG is active
Copilot	Open the VS Code workspace	Ask Copilot Chat for AIWG status
Factory	Start Factory from the project root	Ask for the AIWG first action
OpenCode	Open OpenCode in the project root	Ask for one AIWG route
Warp	Start Warp in the project root	Ask the session to route through AIWG
Devin Desktop	Open the project in Devin Desktop	Ask Devin to verify AIWG status
Hermes	Open a Hermes chat attached to the project	Ask for the AIWG route
OpenClaw	Open OpenClaw with the workspace	Ask for one AIWG capability and verify deployment

Use the agent-owned context regeneration procedure from inside the session when provider context files need to be rebuilt. Use the agent-owned doctor operation as the direct diagnostic escape hatch.

Verification

The authoritative first-run proof is the `aiwg.use.result.v1` response emitted by the deployment command. Inspect its resolved project, provider, scope, phases, findings, final state, and restart requirement.

For an independent later audit, the local proof command remains:

Use AIWG to complete this documented outcome: For an independent later audit, the local proof command remains
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

For troubleshooting, the broader health check remains:

Use AIWG to complete this documented outcome: For troubleshooting, the broader health check remains
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Do not make either command an additional ordinary install step. Most provider sessions can continue without restarting after the agent-owned use operation; request a restart or reload only when its result or a later probe shows the current session cannot read or discover the newly deployed files.

Common health-check outcomes:

Symptom	What to do
`aiwg` not found	Add npm's global `bin` directory to PATH or use `npx aiwg`
No provider artifacts	Run the agent-owned use operation from the project root
Wrong project root	`cd` to the intended repository and rerun the setup
Stale provider session	Restart or reload the agentic platform
Generated context is stale	Ask the session to run the agent-owned context regeneration procedure
Doctor reports repairable drift	Ask the steward to explain the failing check and propose the smallest fix

What Not To Teach As The Default

Do not make normal users memorize capability-search, asset-loading, agent-loop, or framework-specific commands as the post-install path. Those implementation surfaces remain available to agents and automation, but the expected onboarding flow is platform-first and steward-first.

Related Guides

• Start Here
• Provider Handoff
• Verify AIWG Is Working
• macOS Install Guide
• Non-Interactive Installation