# Architecture

## System shape

```text
questionnaire
    ↓
skills/web-studio/SKILL.md ───── orchestration and stage contracts
    ├── agents/the-designer.md ─ creative direction and craft QA
    ├── hooks/direction-gate.js  project-write boundary
    ├── templates/               persistent artifact contracts
    ├── scripts/visual-checks.js measurable browser findings
    ├── scripts/validate-run.js  receipt order/completion classifier
    ├── scripts/install.js       owned Claude-home installation boundary
    ├── scripts/doctor.js        installed-state and capability diagnosis
    ├── optional model/media CLIs external capabilities
    └── runs/<run_id>.jsonl      append-only stage receipts
```

## Authority boundaries

| Component | May decide | Must not imply |
|---|---|---|
| Web Studio skill | sequence, routing, halt conditions | that instructions are runtime enforcement |
| The Designer | direction, visual system, craft score | human brand approval or permission to publish |
| Direction gate | whether `Write` / `Edit` proceeds in a gated project | protection from other tools, shell writes, or processes |
| Visual checks | overflow, broken image, and tap-size findings | full accessibility, usability, performance, or design quality |
| Second model | budget and mechanical consistency | aesthetic authority, external evaluator status, or independence from operator-selected evidence |
| Media tool | render an approved brief | rights, consent, or factual authenticity |
| Host | publish approved output | domain authority or business acceptance |

## Direction gate

The gate is a `.direction-gate.json` file discovered by walking upward from a
target file. The hook canonicalizes the nearest existing target ancestor first,
so a new file addressed through a symlink alias is still mapped to its physical
project. Before signing, Claude Code `Write` and `Edit` hook calls are denied.
Signed and unsigned states have strict field and timestamp shapes; malformed,
unknown-field, non-regular, or symlink gate files fail closed. Gate writes use
an atomic temporary-file rename. A signed gate is preserved if initialization
repeats.

This boundary is deliberately narrow. It does not intercept shell commands,
third-party tools, or writes performed outside the configured Claude Code hook.
Calling it a general filesystem sandbox would be false.

## Stage record

Each stage transition appends a one-line record to `runs/<run_id>.jsonl` using
the schema in `runs/README.md`. `scripts/validate-run.js` deterministically
rejects malformed, out-of-order, duplicate, mixed-run, and false-complete
receipts and classifies valid records as `COMPLETE` or `PARTIAL`. It validates
evidence after it is written; it does not execute or orchestrate stages. A
future runner should be considered only if it preserves operator control and
keeps creative decisions outside the state machine.

## Degraded modes

Optional second-model and image-generation tools may be absent. The pipeline
continues with a declared substitution: self-review for mechanics or CSS/SVG
art direction in place of generated media. The receipt must name the actual
path. Deploy remains a distinct stage and cannot be replaced with a local URL.

## Data and trust

Studio Memory lives under `~/.web-studio/`; project gates live in project
directories; canonical generated media lives in a local library; run logs may
contain prompts, URLs, model identifiers, and spend. Operators must review
those artifacts for client, personal, credential, or confidential data before
committing or sharing them.