# CASAN Adoption Guide

CASAN separates machine installation from project adoption. Install the DevKit
once so the `casan` command is available, then enroll each repository with a
version/hash lock. Application teams never edit gate logic (H1→H7).

## Option A — Managed Core (recommended)

Install from an approved checkout or release:

```bash
sh install.sh --level devkit
cd /path/to/my-project
casan init --project ticketing --client claude,codex
casan doctor
casan verify-harness
```

The project defaults to Level 1/Core with runtime mode `managed`. Core remains
under `$CASAN_HOME`; the repository receives `.casan` config/lock/bootstrap and
the selected client hooks. The CLI output states the resolved runtime path.

Use this for developer workstations and managed CI runners. CI must install the
same release recorded by `.casan/version.lock` before running gates.

## Option B — Vendored Core (offline/self-contained)

```bash
cd /path/to/my-project
casan init --runtime vendored --project ticketing --client claude,codex
casan doctor
casan verify-harness
```

This installs the production-only Core at
`.casan/runtime/casan-core/`, including a local `bin/casan`. It excludes tests,
legacy `level5`, internal runners and Platform helpers. Choose this for
air-gapped customers or repositories that must execute without a machine-level
runtime. Re-running init preserves the selected mode; switching mode requires
an explicit `--runtime managed|vendored`.

## Option C — New production project shell

```bash
packages/casan-devkit/install.sh \
  --target ../my-project \
  --project ticketing \
  --domain "Ticketing" \
  --template nestjs-react
```

This creates a strict-TypeScript NestJS/React monorepo, health bootstrap, tests, Docker multi-stage
images, GitHub CI, a complete Domain Pack, versioned quality profile, project manifest, CASAN CLI,
harness, and manifest-driven pipeline. Existing different files are never overwritten.

The legacy direct installer is reserved for generating a new application shell;
do not use it merely to enroll an existing repository.

## Option D — Docker (no install into repo)
```bash
docker run --rm -v "$PWD":/workspace -w /workspace casan-harness:1.0.0 casan gate
```
See `DOCKER_GUIDE.md`.
This runtime-only option also does not enforce repository-agent entrypoints.

## After install
1. Requirement → `apps/<project>/domain/input/requirement.md` (keep the `| FR-xx |` table).
2. Golden baseline → `apps/<project>/domain/golden-runs/<artifact>.golden.txt`.
3. Corpus → `apps/<project>/domain/corpus/` (redteam + benign) for H4 scoring.
4. Requirement→code→test map → `apps/<project>/domain/traceability-map.json`.
5. Run:
   ```bash
   CASAN_DOMAIN_ROOT=apps/<project>/domain bin/casan gate     # full governance gate
   bin/casan run in.txt out.txt my_step -- <command>          # one governed step
   bin/casan reuse                                            # HARNESS_REUSE_VALID
   ```

For a manifest-enabled project prefer:

```bash
bin/casan project validate --manifest apps/<project>/domain/project.manifest.json
bin/casan pipeline --manifest apps/<project>/domain/project.manifest.json
```

## Path model (what lives where)
- **Managed Core** → `$CASAN_HOME/current/packages/casan-harness/`.
- **Vendored Core** → `.casan/runtime/casan-core/packages/casan-harness/`.
- **Project lock/config** → `.casan/config.json` and `.casan/version.lock`.
- **Your domain data** → `apps/<project>/domain/` (via `CASAN_DOMAIN_ROOT`).
- **Runtime state** → `.specify/` (logs, audit, governance — created on first run).
The bootstrap resolves the mode/path from the project lock and verifies the live
Core hash before dispatch.

## Proving reuse
Two+ projects sharing the same harness package/version → `bin/casan reuse` prints
`HARNESS_REUSE_VALID ... project_count=N`. This is the evidence that the harness is genuinely
reusable, not copy-pasted. See `docs/plans/CASAN_PLAN_06_ONBOARD.md`.

## Upgrading
Re-run `install.sh` from a newer DevKit (or re-extract a newer core tarball). Your
`apps/<project>/domain/` and `.specify/` state are untouched — only `packages/casan-harness/`
+ `bin/casan` are replaced. Keep `harness_version` aligned across projects for reuse to count.