docs/canonical_thin_shell_v0.md

# Canonical Thin Shell v0

Clean product one-liner: keep one authored system file, compile the operator-facing contracts, and let the existing kernel/runtime keep doing the work.

## Why

The fast build path is not a rewrite.

It is:

`canon/system.yml -> compile -> current shell kernel`

That reduces duplicate authority without throwing away the working harness.

## Authored Surfaces

| Surface | Role |
| --- | --- |
| `canon/system.yml` | canonical source for API, runtime, control, and inference state |
| `scripts/compile_system.sh` | deterministic compiler from canon into live surfaces |
| `api/run_turn.sh` | current executable shell kernel |
| `benchmarks/run_standalone_control_bench.sh` | current proof surface |

## Generated Surfaces

| Surface | Generated from canon |
| --- | --- |
| `api/conversational_api_v0.json` | yes |
| `runtime/work_manifest_v0.json` | yes |
| `policy/control_language_v0.json` | yes |
| `inference.yaml` | yes |
| `build/system/compiled_system.json` | yes |
| `build/system/user_governance.json` | yes, from `data_prep_stage` reduction surfaces |
| `build/system/continuity_provider.json` | yes |

## Operator Path

```bash
./bin/bvtctl compile
./bin/bvtctl governance
./bin/bvtctl benchmark
```

Why in plain English: edit one file, compile, then measure the result through the same harness you already trust.

## User-Governed Next Moves

The compile path also pulls reduced user-data doctrine from `data_prep_stage`:

- operator brain stable rules
- motif-family reduction
- primitive trigger map
- interaction primitive status

Why: the next moves should come from repeated user patterns, not only from local repo taste.