setup

# /do setup — First-Run Experience

Configures the harness for a specific project: installs hooks, detects stack, writes harness.json, and optionally demos the system on real code. Flag: `/do setup --express` skips mode selection and runs Express directly. Reference tables and layouts: docs/SETUP_REFERENCE.md.

## Orientation

**Use when:** first-run configuration of Citadel on a new project -- installs hooks, generates harness.json, scaffolds .planning/.
**Don't use when:** harness is already configured and you want to verify it (use /verify); adding a single skill to an existing project (copy SKILL.md manually).

## Protocol

### Step -1: ARCHIVE DETECTION (all modes, before anything else)

Run `ls docs/citadel/ 2>/dev/null`. If `docs/citadel/` exists and contains `.md` files with `citadel-archive: true` in frontmatter, extract the `exported-at` date and prompt once:

```
Found a Citadel archive from {exported-at date}.
  Campaigns: {N}  Postmortems: {N}  Backlog items: {N}  Research: {N}

Restore history into .planning/ during setup? [Y/n]
```

Y or Enter → set `restoreArchive = true`, restore after Step 1 (below). n → skip silently. No archive found → skip entirely, no output.

**ARCHIVE RESTORE** (runs after Step 1 if `restoreArchive = true`). Splitting: each `## Section Title` becomes one restored file; strip frontmatter before writing.

| File | Restore to |
|---|---|
| `campaigns.md` | Split sections → `.planning/campaigns/completed/{name}.md` |
| `postmortems.md` | Split sections → `.planning/postmortems/{name}.md` |
| `research.md` | Split sections → `.planning/research/{name}.md` |
| `backlog.md` | Split sections → `.planning/intake/{name}.md` |
| `discoveries.md` | Split sections → `.planning/discoveries/{name}.md` |
| `project.md` | Strip frontmatter → `.citadel/project.md` |
| `harness.json.md` | Strip frontmatter → `.claude/harness.json` |

After restore: `  ✓ Archive restored — {N} campaigns, {N} postmortems, {N} backlog items`

### Step 0: MODE SELECTION

```
Welcome to Citadel.

How would you like to get started?

  [1] Recommended  — auto-detect your stack, install hooks, live demo  (~3 min)
  [2] Full Tour    — everything in Recommended + guided skill walkthrough (~8 min)
  [3] Express      — zero questions, auto-detect, hooks installed, done  (~30 sec)

Press Enter for Recommended, or type 1, 2, or 3.
```

If harness.json already exists with full config, add: `  [4] Update — reconfigure existing setup (current: {language}, {skillCount} skills)`. Default: Recommended. If `--express` flag passed: skip mode selection, run Express.

### Step 1: INSTALL HOOKS (all modes, always first)

Hooks must be live before anything else. Run `node {citadel-root}/scripts/install-hooks.js`. Find `{citadel-root}`: read `.citadel/plugin-root.txt`; fallback: directory containing this SKILL.md. The installer reads `hooks/hooks-template.json`, resolves absolute paths, writes into `.claude/settings.json`, preserves non-Citadel settings, is idempotent.

**On success:** `  ✓ {N} hooks installed (protect-files, external-gate, circuit-breaker, quality-gate + more)`
**On failure:** output the error, explain manual install path (`node /path/to/Citadel/scripts/install-hooks.js`), continue — setup must not abort.

### Step 2: STACK DETECTION (all modes)

Auto-detect by scanning the project root. Never ask what can be read. (Readable tables: docs/SETUP_REFERENCE.md#stack-detection-tables.)

- **Language** (check in order): `tsconfig.json` → TypeScript; `package.json` without tsconfig → JavaScript; `requirements.txt` or `pyproject.toml` → Python; `go.mod` → Go; `Cargo.toml` → Rust; `pom.xml` or `build.gradle` → Java
- **Framework** (package.json dependencies): `next` → Next.js; `react` (no next) → React; `vue` → Vue; `svelte` → Svelte; `@angular/core` → Angular; `express` → Express; `fastify` → Fastify
- **Package manager**: `pnpm-lock.yaml` → pnpm; `yarn.lock` → yarn; `bun.lockb` → bun; `package-lock.json` → npm; `requirements.txt` → pip; `Pipfile` → pipenv
- **Test framework**: package.json devDependencies for `jest`, `vitest`, `mocha`, `jasmine`; Python: `pytest` in requirements.txt or pyproject.toml
- **Typecheck by language**: TypeScript `npx tsc --noEmit` (per-file: no, project-scope incremental); Python `mypy {file}` or `pyright {file}` (per-file: yes); Go `go vet ./...`, Rust `cargo check`, JavaScript none (per-file: no)

**Confirmation (Recommended + Full Tour only):** output `Detected: {language}{+ framework if any} · {packageManager} · {testFramework if any}`, then `Correct? [y/n/edit]`. y/Enter → proceed; n/edit → ask for corrections inline. Express: skip confirmation, use detected values.

### Step 3: GENERATE CONFIG (all modes)

Write `.claude/harness.json` using Node (not Write tool — harness.json is protected after first install):

```javascript
node -e "
const fs = require('fs');
const existing = fs.existsSync('.claude/harness.json') ? JSON.parse(fs.readFileSync('.claude/harness.json', 'utf8')) : {};
const skillDirs = fs.readdirSync('{citadelRoot}/skills', { withFileTypes: true }).filter(d => d.isDirectory()).map(d => d.name);
const config = {
  language: '{detected}', framework: '{detected or null}', packageManager: '{detected}',
  typecheck: { command: '{command}', perFile: {bool}, timeoutMs: 25000 },
  test: { command: '{testCommand}', framework: '{testFramework}' },
  qualityRules: { builtIn: ['no-confirm-alert', 'no-transition-all'], custom: [] },
  protectedFiles: ['.claude/harness.json', '.claude/settings.json'],
  features: { intakeScanner: true, telemetry: true },
  registeredSkills: skillDirs, registeredSkillCount: skillDirs.length,
  agentTimeouts: { skill: 600000, research: 900000, build: 1800000 },
  trust: { sessionCount: existing.trust?.sessionCount || 0, campaignCount: existing.trust?.campaignCount || 0, level: existing.trust?.level || 'novice' },
  ...existing  // preserve consent, storage, policy
};
fs.writeFileSync('.claude/harness.json', JSON.stringify(config, nul