---
name: archal-setup
description: Connect a coding agent to Archal, guide browser signup or approval, install and verify the canonical Archal skills, or repair an incomplete coding-agent setup. Use for first-time setup, Archal pairing codes, device connection, skill installation, authentication readiness, target selection, and setup verification.
---

# Set up Archal

Connect the user's coding agent to Archal without changing their application.
Skill installation is intentionally repository-local: write to the selected
agent's standard skill directory under the current working directory. Codex
and the portable/shared target both use `.agents/skills`; Codex does not load
repository skills from `.codex/skills`. Do not silently substitute a
user-level/global location or install the shared destination twice.

## Guardrails

- Treat a pairing code as a short-lived secret. Pass it only to `archal connect`; never echo it into logs, source, shell history examples, or chat after use.
- Use the target the human selected. If no target was selected, use the single detected Claude Code, Codex, Cursor, or Windsurf target. Ask when detection is ambiguous; use the portable target when none can be detected. Never default to a vendor.
- Setup may write only the selected coding-agent skill directory, its `.archal-manifest.json`, and the protected Archal credential store.
- Do not change application source, tests, application configuration, or CI. Do not start an environment or call a provider during setup.
- Do not expose the returned control-plane credential to an agent under test. Let the CLI store it in its protected credential store.

## Connect

1. Inspect `archal connect --help` from the installed CLI.
2. Use exactly one connection path:
   - If a dashboard prompt supplied a pairing code, exchange it with `archal connect --code <code> --target <agent>`.
   - Otherwise, run `archal connect --device --target <agent>` and wait while the human signs up or approves access in the browser. Never automate identity verification or ask the human to paste a password into chat.
3. Let the connect command install exactly these skills:
   - `archal-setup`
   - `archal-state`
   - `archal-session`
   - `archal-ci`
   - `archal-diagnose`
4. Require checksum verification and no skipped or missing skills.
5. Verify authenticated control-plane access with the CLI's non-mutating status or usage command.
6. Report readiness to Archal only after all five installed checksums match.

## Finish

Stop after setup. If authentication and the canonical skill manifest both pass, reply exactly:

`Archal is connected and ready`

Otherwise report the failed boundary and one safe next action. Never claim readiness after a partial install.