# Spectra Scope — folder structure canon (LAW, 2026-08-14)

Ring discipline applies: every folder and file has a designated place.
Nothing "lands where it lands." Before creating ANY file in this project,
find its home here; if it has none, add its home HERE first, then create it.

Folder name is `SpectraScope` (no space — paths stay tool-friendly); the
product's display name is "Spectra Scope". SPECTRA = State & Parameter
Examination via Captured Traces; the Scope is the instrument.

## Repository (the repo root)

```
SpectraScope/
  README.md                 project charter: what Spectra Scope is, how to
                            run the app, the hooks env, and co-op sharing
  PUNCHLIST.md              harmless-but-fix-later items (build first,
                            sweep later)
  requirements.txt          Python dependencies for the hooks/dev
                            environment (single source; setup.sh consumes it)
  .gitignore                venv, build dirs, caches, trace data
  venv/                     the project venv — created ONLY by
                            scripts/setup.sh, never committed. VISIBLE by
                            owner ruling 2026-08-15 (dev and official
                            installs alike): users must be able to find
                            what was installed on their machine

  docs/                     the paper trail
    STRUCTURE.md            THIS file — the law
    INSTRUMENTS.md          instrument registry + the CORE/SIDEBAR two-tier
                            law the app's side rail mirrors
    COLLAB_SPEC.md          co-op protocol (authoritative for server+client)
    build-report-*/         dated build/verify evidence (screenshots, logs)

  app/                      the Spectra Scope application (LIVE 2026-08-14 —
                            built, E2E-verified 26/26, renamed in place;
                            app/STRUCTURE.md holds its per-file inventory)
    face/                   nine-tab UI — vanilla HTML/CSS/classic-script JS
                            (window.RS_* registries; runs from file:// and
                            any static server; no frameworks, no build step)
    src-tauri/              Rust desktop shell (Tauri 2)
    collab-server/          Rust co-op crate: static face serve + ws
                            sessions (control/observe links, cursors)
    package.json            tauri CLI dev-dependency
    node_modules/           installed CLI (not committed)

  hooks/                    the dev environment that hooks models (two-tier
                            law: docs/INSTRUMENTS.md — CORE = pure-pip
                            python; SIDEBAR = optional system tools, never
                            dependencies)
    harness/                model residency + hook capture (MIGRATES IN from
                            the research harness: resident, router/residual/dense
                            taps, interventions, prefetch, probes)
    server/                 capture/replay server lanes (fastapi + ws;
                            migrates from the research harness)
    instruments/            analysis + capture instruments (LIVE: meta
                            anatomy, attention summaries, KV readout,
                            system lane; lens/censuses migrate in)
    attach/                 SIDEBAR attach scripts (nsys, ncu, dcgm,
                            jupyter): detect-and-wrap, honest "not
                            installed" exits, never claimed as downloads
    drafter/                the Scrabble-head drafter lane (owner-authorized
                            2026-08-15): capture_rack.py (rack corpus from
                            the serving artifact via logprobs) +
                            train_scrabble.py (tiny selector, hash-bucket
                            embeddings, γ=1 + confidence gate)
    prompts/                probe prompt sets (yaml)

  drafter-shim/             pip package `spectra-drafter` (AGPL): the
                            custom_class vLLM shim + compat gauntlet +
                            trained-head loader; RESULT.md carries both
                            A/B verdicts (shim 0.70x, fork 0.976x);
                            tests/ = port-equivalence gate + A/B serve.
                            SIBLING ARTIFACT (lives outside this repo):
                            the vLLM fork at ~/src/vllm-spectra
                            (branch spectra-drafter, venv
                            ~/venvs/vllm-spectra) — first-class "spectra"
                            method, async-preserving, GPU-resident;
                            original ~/src/vllm-026 untouched.

  traces/                   captured trace artifacts (DATA, not code —
                            gitignored above a size floor; the app's traces
                            tab reads from here)

  scripts/
    setup.sh                creates venv/ from requirements.txt (the ONE
                            bootstrap; idempotent; torch platform note in
                            header). Owner ruling 2026-08-15: the venv
                            folder is VISIBLE (no leading dot) everywhere
                            — dev and official installs — so users can
                            always find what was installed.
```

## Rules carried from the ring approach

1. Structure-first: new lanes get a home in this file before code exists.
2. No machine-specific constants in shipped code — defaults are app-owned,
   paths are relative or configured, ports are knobs (default 8937 for the
   collab server).
3. Data (traces, screenshots, reports) never mixes with source folders
   except the dated `docs/build-report-*/` evidence dirs.
4. Retire/move = breadcrumb at the old home + this file updated in the
   same sitting.

## Migration status (2026-08-14, updated same day)

- app/: **DONE** — built by workflow wf_35ad9e17, desktop launch verified,
  co-op E2E 26/26 after the nav same-page fix, migrated in and renamed
  Spectra Scope (an earlier prototype, now dissolved).
- docs/COLLAB_SPEC.md + docs/build-report-2026-08-14/: **DONE** — moved in
  with the app.
- hooks/: PENDING — sources live in the research harness (harness/,
  server/, analysis/); selective migration with a written map, next lane.