atlas-setup

---
name: atlas-setup
description: "One-shot ATLAS installer + healer for new users (esp. G Mining external devs on Mac/Linux). Bootstraps Claude Code CLI, status line, plugin install, Forgejo NPM auth, settings.json patches. Use when 'atlas setup', 'install atlas', 'first time install', 'onboarding install', 'fresh setup', '/atlas setup', '/atlas install', 'g-mining onboarding', 'install plugin from scratch'. Pendant of atlas-doctor — doctor diagnoses, setup installs/heals."
mode: [personal, all]
effort: medium
---

# ATLAS Setup — One-shot Installer & Healer

Bootstrap a fresh ATLAS environment from zero, OR heal a partially-installed one. Companion to `atlas-doctor`:

| Skill | Role |
|-------|------|
| `atlas-doctor` | **diagnoses** — reads state, reports drift |
| `atlas-setup` (this) | **installs/heals** — applies fixes |

## Subcommands

| Command | Action |
|---------|--------|
| `/atlas setup` | Interactive guided install (default — prompts at each step) |
| `/atlas setup --auto` | Idempotent autonomous install (no HITL — for CI/scripts) |
| `/atlas setup --dry-run` | Show plan without applying |
| `/atlas setup --persona=gmining-external` | G Mining external dev flow (Forgejo PAT + plugin install) |
| `/atlas setup --upgrade` | Upgrade existing install (v7.x → v8.x with migration helpers) |
| `/atlas setup --uninstall` | Remove ATLAS (keeps user data per `preuninstall.js`) |
| `/atlas setup --fix` | Detect drift via doctor + propose fixes (interactive) |

## When to use

- **First-time install** on a fresh Mac/Linux box (G Mining dev day-one)
- **CI bootstrap** — non-interactive (`--auto`) for automation
- **After Claude Code update** — verify ATLAS still wired
- **After laptop reset** — restore ATLAS from npm install
- **Partial install drift** — atlas-doctor reports issues, this fixes them

## Persona flows

### `--persona=gmining-external` (default for non-AXOIQ users)

```
Step 1/7 — Detect OS              → Linux x86_64 / Darwin ARM64 / Darwin Intel
Step 2/7 — Verify deps            → bash, python3, node 18+, bun, docker (optional)
Step 3/7 — Install Claude Code    → brew install --cask claude-code (Mac) | curl install.sh (Linux)
Step 4/7 — Authenticate CC        → opens browser → Anthropic OAuth flow
Step 5/7 — Forgejo PAT setup      → prompt user to paste PAT (read:repository scope)
                                    → write ~/.npmrc with @axoiq registry + token
                                    → chmod 600 ~/.npmrc
                                    → test: git ls-remote forgejo.axoiq.com/axoiq/atlas-plugin
Step 6/7 — Install ATLAS plugin   → /plugin marketplace add https://plugins.axoiq.com
                                    → /plugin install atlas-core@atlas-marketplace
                                    → /plugin install atlas-dev-addon@atlas-marketplace
                                    → (admin tier: prompt confirm)
Step 7/7 — Verify install         → runs atlas-doctor with --fix-all
                                    → final report: ✅ READY / ⚠️ DRIFT / ❌ BLOCKED
```

### `--persona=internal-axoiq` (Seb + AXOIQ contributors)

```
Step 1/5 — Detect existing install  → check ~/.atlas/, ~/.claude/plugins/cache/atlas-marketplace/
Step 2/5 — git clone source repo    → ~/workspace_atlas/projects/atlas-plugin/
Step 3/5 — make dev                 → builds + installs dist/ to CC + npm pack to ~/.atlas/
Step 4/5 — Configure dev mode       → ATLAS_AUTO_DETECT_PROFILE=true + ATLAS_SOURCE_REPO
Step 5/5 — Verify                   → atlas-doctor --fix
```

### `--persona=ci` (automation, headless)

```
Step 1/4 — Validate env             → CI=1, ATLAS_FORGEJO_TOKEN, ATLAS_NO_INTERACTIVE
Step 2/4 — npm install -g           → @axoiq/atlas-cli (with .npmrc from secret)
Step 3/4 — Plugin install (silent)  → /plugin install --no-prompt
Step 4/4 — Smoke verify             → atlas --version + atlas doctor --json | jq '.overall'
                                      Exit 0 only if overall ≥80%
```

## Installation matrix

| Step | Mac M1/M2 (Darwin ARM64) | Mac Intel (Darwin x86_64) | Linux Ubuntu/Debian |
|------|--------------------------|---------------------------|---------------------|
| **bash 5.x** | system 3.2 OK + `brew install bash` recommended | same | system 5.x OK |
| **python3** | system 3.11+ OK | same | `apt install python3 python3-pip` |
| **node 18+** | `brew install node` | same | `apt install nodejs npm` |
| **bun** | `curl -fsSL https://bun.sh/install \| bash` | same | same |
| **docker** | Docker Desktop (optional) | Docker Desktop | `apt install docker.io && usermod -aG docker $USER` |
| **claude-code** | `brew install --cask claude-code` | same | `curl -fsSL https://claude.ai/install.sh \| bash` |
| **gnu-coreutils** | `brew install gnu-sed coreutils` (recommended for portable scripts) | same | already installed |
| **portable-shell.sh** | bundled in plugin (handles BSD/GNU dispatch automatically) | same | same |

## Mandatory inputs (interactive prompts)

| Prompt | Validates | Saved to | Required for |
|--------|-----------|----------|--------------|
| **Forgejo PAT** | `read:repository` scope on `axoiq/atlas-plugin` | `~/.npmrc` + `git config --global url.X.insteadOf` | npm install + git clone |
| **Anthropic plan** | Pro/Max/Team subscription | OAuth flow → `~/.config/claude-code/` | All Claude Code use |
| **Confirm admin tier** | (only if `--persona=axoiq` and admin requested) | n/a | atlas-admin-addon install |

**No password / API key prompts**. ATLAS never stores secrets in plaintext per `feedback_no_plaintext_secrets`. PAT only stored via standard tools (`.npmrc`, git config).

## Heal mode (`--fix`)

When run with `--fix`, atlas-setup invokes `atlas-doctor` first to identify drift, then proposes fixes per category:

| Drift detected | Auto-fix |
|----------------|----------|
| `~/.atlas/shell/atlas.sh` missing | `npm install -g @axoiq/atlas-cli` (re-run postinstall) |
| `~/.zshrc` not sourcing atlas.sh | append source line + reload |
| `settings.json` missing skillListingBudgetFraction | jq merge with `{"skillListingBudgetFraction":0.03}` |
| Status line not configured | install statusline-wrapper.sh + write settings.local.json |
| Plugin cache stale (>14 versions) | invoke `atlas-doctor --prune-plugin-cache --confirm` |
| Forgejo PAT expired | prompt re-paste + validate |
| Hooks not registered | re-run plugin postinstall + validate `~/.claude/plugins/cache/atlas-marketplace/atlas-core/<v>/hooks/hooks.json` |
| MCPs missing | suggest `claude mcp add <name> <url>` interactively |

Each proposed fix has:
- **What** — one-line description
- **Why** — rationale (link to memory if relevant)
- **Command** — exact bash to run
- **Reversal** — how to undo

User can : `Y` apply | `n` skip | `a` apply all remaining | `q` quit.

## Cross-platform safety

This skill ships only the **plan + interactive flow**. The actual commands invoked are wrapped in `lib/portable-shell.sh` (W1+W2 G Mining Federation) to handle BSD vs GNU coreutils on Mac vs Linux.

Specifically :
- `sed -i` writes use `psed_i` (handles `sed -i ''` on Darwin)
- Timestamps use `pdate_ms` / `pdate_ns` (BSD `date` lacks `%N`)
- Path resolution uses `prealpath_m` (BSD `realpath` lacks `-m`)
- File copies use `\cp -f` to escape any user `cp -i` alias

Validated by:
- `tests/cross-platform/test_portable_shell.sh` (8/8 PASS Linux baseline)
- `tests/cross-platform/test_force_darwin_mode.sh` (9/9 PASS BSD branch logic)
- `scripts/lint-cross-platform.sh` (CI gate, 0 regressions)

## Output format

```
🏛️ ATLAS │ 🚀 SETUP │ G Mining External Dev Onboarding
─────────────────────────────────────────────────────

Persona: gmining-external
OS detected: Darwin ARM64 (macOS 14.5, M2)
Mode: interactive (use --auto for non-interactive)

[Step 1/7] Detect OS              ✅ Darwin ARM64 — supported
[Step 2/7] Verify deps            ✅ bash 5.2.21, python3 3.13, node 22.7, bun 1.1.30
[Step 3/7] Install Claude Code    ⏳ Running: brew install --cask claude-code
                                   ✅ Installed v2.1.132
[Step 4/7] Authenticate CC        ⏳ Open browser? [Y/n] Y
                                   ✅ Logged in as you@gmining.com (Pro plan)
[Step 5/7] Forgejo PAT setup      📝 Paste PAT: ********
                                   ✅ Validated (scope: read:repository, expires 2026-08-05)
                                   ✅ Saved to ~/.npmrc
[Step 6/7] Install ATLAS plugin   ⏳ Adding marketplace https://plugins.axoiq.com
                                   ✅ atlas-core@7.17.1 installed
                                   ✅ atlas-dev-addon@7.17.1 installed
                                   ⏭️  atlas-admin-addon skipped (not requested)
[Step 7/7] Verify install         ⏳ Running atlas-doctor...
                                   ✅ 12/14 ✅, 2/14 ⚠️ (warnings non-blocking)
                                   📊 OVERALL: 92% — READY

─────────────────────────────────────────────────
✅ ATLAS ready. Try: /atlas-help or atlas synapse <project>
   Documentation: https://forgejo.axoiq.com/axoiq/atlas-plugin/src/branch/main/README.md
```

## Companion files (NEW in W3 — to ship in follow-up commits)

- **Helper script**: `scripts/atlas-setup/install.sh` (bootstrap CLI + deps + plugin)
- **Helper script**: `scripts/atlas-setup/forgejo-auth.sh` (PAT wizard)
- **Helper script**: `scripts/atlas-setup/heal.sh` (per-check fixers)
- **Test fixture**: `tests/skills/atlas-setup/test_atlas_setup_install_dryrun.sh`
- **Test fixture**: `tests/skills/atlas-setup/test_atlas_setup_heal_idempotent.py`

## Related skills

- `atlas-doctor` — diagnostic-only sibling (14-category dashboard)
- `atlas-onboarding` — guided walkthrough (uses atlas-setup under the hood)
- `atlas-workspace-setup` — first-run workspace init (different scope)
- `onboarding-check` — admin-tier readiness audit (different scope)

## References

- Plan SSoT : `.blueprint/plans/MEGA-PLAN-G-MINING-FEDERATION-V8.md` Section J Wave 3
- Sub-plan : `.blueprint/plans/sub/sp-mp03-doctor-setup-skills.md`
- Cross-platform : `lib/portable-shell.sh` + W1+W2 SHIPPED v7.17.0
- Memory : `feedback_no_plaintext_secrets`, `feedback_3layer_zombie_defense_pattern`
- ONBOARDING-EXTERNAL.md (G Mining specific guide — read this AFTER setup completes)