PAiD Setup

Public bootstrapper for PAiD agent skill installation.

Intended customer entrypoint:

npx -y @processai/setup
npx -y @processai/setup all
npx -y @processai/setup claude
npx -y @processai/setup codex
npx -y @processai/setup --version

With no target, setup defaults to all: it installs into every supported client it detects on the user's machine. If only Claude Code or only Codex is present, the missing client is skipped. If neither is present, setup fails closed with a clear message. The old both target remains accepted as an alias for all for older instructions.

On macOS, Codex detection checks both codex on PATH and the standard Codex app binary at /Applications/Codex.app/Contents/Resources/codex.

The installer is deliberately fail-closed. It must not install private PAiD skills unless PAiD has accepted an existing PAiD MCP OAuth/PAT credential for the current principal.

The first private packages are:

• @processai/agent-plugin-core, containing the PAiD router skill.
• @processai/agent-plugin-reporting, containing branded report rendering and accounting review workflow skills.

Runtime data access still depends on PAiD MCP entitlements.

The setup CLI installs whatever safe skill-pack list the PAiD claim endpoint returns. Adding a later generic pack should not require republishing @processai/setup unless the claim protocol, package validation, native client installation behaviour, or supported package scope changes.

The default flow opens PAiD OAuth in a browser, receives a loopback PKCE callback, claims the entitled skill packs from the MCP server, and then installs through the native Claude/Codex plugin command. Private package bytes are downloaded from PAiD after the same MCP credential is re-checked server-side; customers do not need npm or GitHub package credentials.

Before installing, setup reports the current local plugin version for each returned skill pack per detected client and the entitled version returned by PAiD. It prints whether each client is installing for the first time, updating, or already current.

For support and release tracking, --version and -v print the public setup bootstrapper version without opening OAuth, checking clients, or contacting the PAiD setup API.

Development smoke paths:

node ./bin/paid-setup.mjs --dry-run
PAID_ACCESS_TOKEN_FILE=/path/to/token.txt node ./bin/paid-setup.mjs claude --plan-only
PAID_ACCESS_TOKEN_FILE=/path/to/token.txt node ./bin/paid-setup.mjs all \
  --plugin-source ../paid-core-plugin \
  --reporting-plugin-source ../paid-reporting-plugin \
  --plan-only

PAiD support may run private-registry fallback checks in controlled automation. The intended customer path is the PAiD brokered package download advertised by the claim endpoint; customers should not need direct npm credentials.

For production, new generic packs are released by publishing the private plugin package, updating the MCP runtime skill-pack catalogue, restarting the MCP services so that catalogue is loaded, and running the setup/broker smoke checks. Per-pack, database-specific, or staged rollout rules still require control-plane entitlement work rather than catalogue-only distribution.

Skill-pack availability is derived from the same MCP database, organisation, capability, and role entitlements used at runtime. The setup output must not print bearer tokens, refresh tokens, OTPs, registry credentials, tenant names, database slugs, or organisation slugs.