Harden CLI information architecture, protocol semantics, and maintainer workflows

ARCHITECTURE.md

@@ -111,11 +111,24 @@ These are the invariants the codebase should preserve.
 
 ## Known Architectural Debt
 
-The deepest remaining architecture gap is still in protocol execution semantics.
-
-`protocols/` now owns richer semantic descriptors for controls, windows, metrics, ranking, figures, and artifacts, but not all of that meaning is compiled from one executable typed analysis program yet. Some assay semantics still live partly in protocol metadata and partly in compiler behavior.
-
-That is the next rooted cut. When that work lands, `reader inspect`, `reader protocols`, and `reader explain` should report the semantic analysis program directly instead of primarily reporting compiled plugin mechanics.
+The deepest remaining debt is now concentration, not split semantic ownership.
+
+The compiled semantic program is explicit end-to-end, from bound protocol
+through compiled plan to experiment semantics and inspection payloads. The
+remaining architecture pressure is that too much assay detail still collects in
+three places:
+
+- `src/reader/protocols/builtins.py`
+- `src/reader/protocols/_builtins_plate_reader_variants.py`
+- `src/reader/protocols/compiler.py`
+- `src/reader/workbench/notebooks/` for retron-review flows
+
+The public builtin catalog is smaller than before because the heavier
+plate-reader variants now live in a family helper, and notebook launch
+preflight/runtime state is split from the planner. Even so, those surfaces are
+still large enough that future assay families can turn them into semantic
+monoliths if new logic is not pushed down into domain modules and
+family-specific helpers.
 
 ## Extension Guide
 

QUALITY.md

@@ -124,7 +124,14 @@ These are the failure classes that quality work should continue to reduce.
 
 ## Current Open Quality Debt
 
-The main unresolved quality debt is still semantic, not documentation. Protocol windows, controls, metrics, and ranking are not yet compiled from one executable typed analysis program. Until that changes, there is still some duplicate truth between protocol metadata and compiler behavior.
+The main unresolved quality debt is now concentration and documentation drift.
+
+Semantic ownership is explicit, but two areas still need sustained pressure:
+
+- large protocol surfaces can accumulate too much family-specific behavior in a
+  few files
+- maintainer docs can drift unless they keep linking to real code surfaces and
+  the docs integrity check stays part of the gate
 
 ## Definition Of Done
 

README.md

@@ -4,16 +4,31 @@
 
 ![reader banner](assets/reader-banner.svg)
 
-`reader` is a toolkit for organizing experiment directories and running config-driven analysis pipelines over structured assay data. Each experiment has a clear working layout: raw inputs live in `inputs/`, optional notebooks live in `notebooks/`, generated results live in `outputs/`, and a `reader/v7` `config.yaml` describes what should be run.
+`reader` organizes experiment directories and runs config-driven analysis
+pipelines over structured assay data. Each experiment uses a fixed layout:
+raw inputs in `inputs/`, optional notebooks in `notebooks/`, generated results
+in `outputs/`, and a `reader/v7` `config.yaml` that declares the run.
 
 ---
 
 ## Documentation
 
-- [Documentation index](docs/README.md): complete map of user docs, reference docs, and maintainer docs.
-- [Getting started](docs/guides/getting_started.md): install `reader`, verify the environment, and inspect the first experiment.
-- [Preflight, run, verify](docs/guides/preflight_run_verify.md): deterministic path for inspecting, executing, and checking one experiment.
-- [Automation and JSON](docs/guides/automation.md): machine-readable discovery, inspection, and preflight surfaces.
+- [Documentation index](docs/README.md): full map of user, reference, and
+  maintainer docs.
+- [Getting started](docs/guides/getting_started.md): install `reader`, check
+  the environment, and inspect a first experiment.
+- [Preflight, run, verify](docs/guides/preflight_run_verify.md): inspect,
+  validate, and execute one experiment.
+- [Automation and JSON](docs/guides/automation.md): machine-readable
+  discovery, inspection, and preflight routes.
+- [Data Operations Plan](docs/guides/data_operations_plan.md): classify data
+  before intake and capture the minimum metadata needed for reliable reuse.
+- [Experiment bootstrap](docs/guides/experiment_bootstrap.md): create an
+  experiment from local or Drive-backed inputs.
+- [Workbench gardening](docs/guides/workbench_gardening.md): maintainer
+  workflow for architecture and docs cleanup.
 - [CLI reference](docs/core/cli.md): full command reference.
-- [Configuring `reader/v7`](docs/core/pipeline.md): the public authoring surface for experiment configs.
-- [Repo maintenance](docs/repo-maintenance.md): maintainer verification and CI lanes.
+- [Configuring `reader/v7`](docs/core/pipeline.md): schema and protocol-owned
+  config surface.
+- [Repo maintenance](docs/repo-maintenance.md): repo-wide checks, CI, and
+  maintainer routines.

RELIABILITY.md

@@ -123,10 +123,10 @@ Use the cheapest command that answers the current question.
 
 - use `reader validate --no-files` for schema-only checks
 - use `reader run --dry-run` before executing a slice
-- use `reader ls --details --format json` for fleet-wide inspection
+- use `reader ls --details --format json` for workbench-wide inspection
 - use `reader inspect --format json` for one experiment’s current state
 
-This follows the same harness principle highlighted in OpenAI’s harness-engineering article: better harnesses reduce retries by shortening the path from action to trustworthy feedback.
+Shorter feedback loops reduce retries by shortening the path from action to trustworthy feedback.
 
 Use [docs/guides/automation.md](./docs/guides/automation.md) for the compact JSON route.
 
@@ -140,9 +140,14 @@ Use [docs/guides/automation.md](./docs/guides/automation.md) for the compact JSO
 
 ## Current Reliability Debt
 
-The largest remaining reliability debt is semantic rather than operational. Protocol controls, windows, metrics, and ranking are still not one executable typed analysis DAG. That means some assay truth is still split between protocol metadata and compiler behavior.
+The largest remaining reliability debt is no longer semantic ambiguity. It is
+change-surface concentration and documentation freshness.
 
-Operationally, the workbench is more reliable when inspection and dry-run routes are used first. Architecturally, full reliability requires finishing that semantic cut.
+Operationally, the workbench is reliable when inspection and dry-run routes are
+used first. Structurally, the higher-risk failures now come from oversized
+maintainer surfaces such as the protocol kernel and retron notebook bundle, or
+from docs that stop matching those surfaces closely enough for operators and
+agents to trust them.
 
 ## Related Docs
 

docs/README.md

@@ -1,39 +1,57 @@
 # Documentation index
 
-Use this index to find the smallest document that matches what you need. Start
-with the guides if you want to understand how `reader` is organized or how an
-experiment moves from inputs to outputs. Use the reference pages when you need
-exact CLI or config details.
+Use this index to find the smallest doc that answers the current question.
+Start with the guides if you want to see how `reader` moves from inputs to
+outputs. Use the reference pages when you need exact CLI or config details.
 
 ## Start here
 
-- [Getting started](./guides/getting_started.md): install `reader`, check the environment, and inspect the first experiment.
-- [Common tasks](./guides/common_routes.md): shortest command paths for discovery, validation, execution, and JSON output.
+- [Getting started](./guides/getting_started.md): install `reader`, check the
+  environment, and inspect a first experiment.
+- [Common tasks](./guides/common_routes.md): shortest routes for discovery,
+  validation, execution, and JSON output.
 
 ## Core workflows
 
-- [Preflight, run, verify](./guides/preflight_run_verify.md): deterministic operating path for one experiment.
-- [Automation and JSON](./guides/automation.md): machine-readable discovery, inspection, and preflight surfaces.
+- [Preflight, run, verify](./guides/preflight_run_verify.md): inspect,
+  validate, and execute one experiment.
+- [Automation and JSON](./guides/automation.md): machine-readable discovery,
+  inspection, and preflight routes.
+- [Data Operations Plan](./guides/data_operations_plan.md): classify datasets,
+  capture metadata minimums, and keep intake decisions explicit.
+- [Experiment bootstrap](./guides/experiment_bootstrap.md): create an
+  experiment from local or Drive-backed inputs and verify the run.
 - [End-to-end demo](./guides/demo.md): one concrete walkthrough from discovery to outputs.
 
 ## User guides
 
-- [Retron sponge screen guide](./guides/retron_sponge_screen.md): matched-control sponge assay setup, runtime flow, plots, and exports.
-- [Notebooks](./guides/notebooks.md): notebook scaffolding and Marimo usage in experiment directories.
+- [Retron sponge screen guide](./guides/retron_sponge_screen.md): matched-control
+  sponge assay setup, runtime flow, plots, and exports.
+- [Notebooks](./guides/notebooks.md): notebook scaffolding and Marimo usage in
+  experiment directories.
 - [Marimo reference](./guides/marimo_reference.md): notebook widgets, patterns, and examples.
 
 ## Reference
 
 - [CLI reference](./core/cli.md): full command reference.
-- [Configuring `reader/v7`](./core/pipeline.md): config schema and protocol-owned authoring surface.
+- [Configuring `reader/v7`](./core/pipeline.md): config schema and protocol-owned settings.
 
 ## Maintainer docs
 
-- [Repo change gate](./repo-change-gate.md): minimum gate before landing tracked changes.
-- [Repo maintenance](./repo-maintenance.md): repo-wide verification, CI lanes, and maintenance surfaces.
-- [Plugin development](./core/plugins.md): add or extend ingest, transform, plot, export, and validator plugins.
+- [Repo change gate](./repo-change-gate.md): minimum gate before landing
+  tracked changes.
+- [Repo maintenance](./repo-maintenance.md): repo-wide checks, CI, and
+  maintenance guidance.
+- [Workbench gardening](./guides/workbench_gardening.md): maintainer workflow
+  for architecture, docs, and verification-surface cleanup.
+- [SFXI triptych sequence plot spec](./dev/sfxi_triptych_sequence_plugin_spec.md):
+  dev spec for promoting the SFXI triptych/BaseRender preview into a formal
+  plot plugin with a versioned dnadesign render contract.
+- [Plugin development](./core/plugins.md): add or extend ingest, transform,
+  plot, export, and validator plugins.
 - [Architecture](../ARCHITECTURE.md): system structure, ownership boundaries, and invariants.
-- [Design](../DESIGN.md): product and information-design rules for the public surface.
+- [Design](../DESIGN.md): product and information-design rules for the public
+  UI and docs.
 - [Quality](../QUALITY.md): quality bar, evidence expectations, and failure taxonomy.
 - [Reliability](../RELIABILITY.md): preflight, run, verify, and recovery expectations.
 - [Security](../SECURITY.md): trust boundaries and safe defaults.