# 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 readiness --refresh
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.

After any prompt, visual assurance is available from Core itself:

```bash
casan report latest
casan view
```

The viewer is single-project, offline-capable and read-only. It starts lazily on
`127.0.0.1`, so projects do not need Platform, Node/npm or an always-running
service merely to inspect H1–H7 and H6.

The dashboard and CLI expose three independent states:

- Core: installation acceptance and client activation;
- Domain Pipeline: optional project-specific SRS→test configuration;
- Provider Telemetry: optional model/provider token and cost coverage.

`not_configured` Domain Pipeline and `optional_unavailable` Provider Telemetry
do not block Core. `casan report export` is on-demand and must not run after
every prompt.

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).
- **Local viewer state** → `.specify/state/local-viewer.json` (`0600` on POSIX,
  project ACL on Windows; ephemeral loopback port/session token; removed on stop).
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.