@bjoernrochel/sevro 0.1.0-rc.7 → 1.0.0

package/CONTRIBUTING.md

@@ -26,8 +26,10 @@ by applicable law.
 
 ## Set up development
 
-Use Bun 1.3.13, Git, Node 24, and npm. Full suite isolation uses `sandbox-exec`
-on macOS or `bubblewrap` and `socat` on Ubuntu. Windows acceptance is unverified.
+Use Bun 1.3.13, Git, Node 24, npm, and ripgrep (`rg`). Full suite isolation uses `sandbox-exec`
+on macOS or `bubblewrap` and `socat` on Ubuntu. The macOS synthetic libc regression
+fixtures compile with `/usr/bin/cc`, supplied by Apple's Command Line Tools.
+Windows acceptance is unverified.
 From a fresh checkout:
 
 ```sh
@@ -36,6 +38,13 @@ bun run test:docs-examples
 ```
 
 The second command checks the tutorial in fresh consumer/contributor directories.
+Its complete recipe checks also require UV, Python 3, mise, and an existing
+`mise install node@24.13.0` installation; see [recipe prerequisites](docs/recipes.md).
+CI explicitly provisions these tools. Missing prerequisites fail with a named
+setup instruction rather than skipping a recipe.
+To run recipe commands from this source checkout, set
+`export SEVRO_RECIPES="$PWD/examples/recipes"` from the repository root, then
+follow the [recipe commands](docs/recipes.md#prepare-a-recipe-project).
 Native model trials need their own [credentials and prerequisites](docs/native-hosts.md).
 
 ## Quality contract and checks
@@ -54,8 +63,9 @@ documentation and guide dry-run checks, tutorial examples, the real Bun suite,
 coverage integrity and thresholds, and installed-package validation. Statements
 and branches must each reach at least 95% using raw exact counts over the
 platform-reachable authored production inventory, including unimported files.
-The macOS and Ubuntu gates each measure their reachable host modules; the exact
-module and branch-outcome exclusions are recorded in coverage artifacts. The five explicitly
+The local-only macOS gate and Ubuntu CI gate each measure their reachable host
+modules; the exact module and branch-outcome exclusions are recorded in coverage
+artifacts. The five explicitly
 inventoried generated AJV validators are excluded from coverage because this
 target measures authored runner behavior; their syntax, schema freshness, typed
 boundaries and runtime tests remain checked. Tests and fixtures remain linted and
@@ -66,6 +76,12 @@ Before committing, use `bun run check:typescript --fast` after installing the
 locked dependencies. This runs inventory, schema, formatting, lint, typing and
 documentation checks; it does not replace full acceptance. CI retains machine-readable coverage
 reports under `.quality/` and exposes the stable `TypeScript quality` status.
+The complete command's `static`, `docs`, `tests` and `package` phases run as
+concurrent CI jobs. CI divides the tests among four duration-balanced jobs and
+requires one combined coverage gate; every test and both 95% thresholds remain
+required. Superseded runs for the same pull request are cancelled. After frozen installation, use
+`bun run check:typescript --phase <name>` to run one phase locally; it does not
+replace acceptance across all four. See the [phase inventory](docs/typescript-quality.md).
 
 Run `bun run check:docs:external` separately and [triage network failures](docs/documentation-quality.md#external-links).
 Guide changes also need [native evals](docs/guide-evaluation.md).
@@ -82,8 +98,8 @@ repairing in-scope failures; it does not authorize merging or unrelated changes.
   non-root user, and isolation prerequisites. Reproducing that environment locally
   with Docker is optional for diagnosis and is not a publication prerequisite.
 - After the local pre-commit checks, publish the authorized candidate to its PR
-  and require `bun run check:typescript` to succeed in GitHub CI before reporting
-  delivery as complete. A local run, fast check, targeted suite, or historical
+  and require all four canonical `check:typescript` phases to succeed in GitHub CI
+  before reporting delivery as complete. A local run, fast check, targeted suite, or historical
   result does not establish that the current Ubuntu gate passes.
 - Keep the quality bar intact. Repair behavior or add meaningful coverage for
   accepted behavior; do not lower thresholds, exempt authored sources, skip tests,

package/README.md

@@ -1,7 +1,7 @@
 # Sevro
 
 <p align="center">
-  <img src="docs/assets/sevro-logo.png" alt="Sevro logo: a black S-shaped track with red segments above the sevro wordmark" width="360">
+  <img src="https://raw.githubusercontent.com/BjRo/sevro/main/docs/assets/sevro-logo.png" alt="Sevro logo: a black S-shaped track with red segments above the sevro wordmark" width="360">
 </p>
 
 Sevro runs repeatable evaluations of coding agents. Give it a case, a host
@@ -40,6 +40,10 @@ Continue with [your first evaluation](docs/getting-started.md): the exact comman
 expected `passed` result, and retained evidence. Read [installation](docs/installing.md)
 for updates, removal, and source checkouts.
 
+Then follow the [demo-to-iteration workflow](docs/evaluation-workflow.md):
+initialize real assertions, prepare, execute, read progress and inspect the
+latest result.
+
 ## Find your next task
 
 The [documentation hub](docs/README.md) routes to running evaluations, authoring

package/docs/README.md

@@ -1,22 +1,25 @@
 # Sevro documentation
 
-<img src="assets/sevro-wordmark.svg" alt="Sevro wordmark" width="220">
+<img src="https://raw.githubusercontent.com/BjRo/sevro/main/docs/assets/sevro-wordmark.svg" alt="Sevro wordmark" width="220">
 
 Start with the task you want to complete. These pages work without an agent.
 
-| I want to…                                    | Read                                                     |
-| --------------------------------------------- | -------------------------------------------------------- |
-| Get a result without a model account          | [Your first evaluation](getting-started.md)              |
-| Install, update, remove, or use a checkout    | [Installation](installing.md)                            |
-| Run evaluations and select a host             | [Running evaluations](running-evaluations.md)            |
-| Create cases and reusable policy              | [Cases and extensions](creating-cases.md)                |
-| Interpret verdicts, evidence, and comparisons | [Reading results](reading-results.md)                    |
-| Run Codex or Claude with isolation            | [Native hosts](native-hosts.md)                          |
-| Reuse host tools or enable goals and hooks    | [Runtime configuration](runtime-v1.md)                   |
-| Resolve a symptom                             | [Troubleshooting](troubleshooting.md)                    |
-| Understand runner responsibilities            | [Architecture](architecture.md)                          |
-| Change Sevro or its documentation             | [Contributing](../CONTRIBUTING.md)                       |
-| Understand licensing and branding             | [Licensing](licensing.md) and [assets](assets/README.md) |
+| I want to…                                     | Read                                                     |
+| ---------------------------------------------- | -------------------------------------------------------- |
+| Get a result without a model account           | [Your first evaluation](getting-started.md)              |
+| Initialize, prepare, run and iterate           | [Evaluation workflow](evaluation-workflow.md)            |
+| Install, update, remove, or use a checkout     | [Installation](installing.md)                            |
+| Run evaluations and select a host              | [Running evaluations](running-evaluations.md)            |
+| Create cases and reusable policy               | [Cases and extensions](creating-cases.md)                |
+| Copy a complete coding, skill or runtime setup | [Runnable recipes](recipes.md)                           |
+| Interpret verdicts, evidence, and comparisons  | [Reading results](reading-results.md)                    |
+| Run Codex or Claude with isolation             | [Native hosts](native-hosts.md)                          |
+| Reuse host tools or enable goals and hooks     | [Runtime configuration](runtime-v1.md)                   |
+| Save recurring evaluation selections           | [Run settings](run-settings-v1.md)                       |
+| Resolve a symptom                              | [Troubleshooting](troubleshooting.md)                    |
+| Trace runner lifecycle, ownership, and changes | [Architecture](architecture.md)                          |
+| Change Sevro or its documentation              | [Contributing](../CONTRIBUTING.md)                       |
+| Understand licensing and branding              | [Licensing](licensing.md) and [assets](assets/README.md) |
 
 ## Ask the guide
 
@@ -30,11 +33,12 @@ It belongs to this repository, not an npm installation.
 
 [Current contracts](contracts.md) define interfaces. The
 [guide specification](specs/repository-guide.md) defines the repository assistant.
-[Historical validation](evidence.md) records observations, not current guarantees.
+[Historical validation](https://github.com/BjRo/sevro/blob/main/docs/evidence.md) records observations, not current guarantees.
 There is no accepted Rust migration decision here;
 [issue #2](https://github.com/BjRo/sevro/issues/2) tracks research.
 
 Read [documentation quality](documentation-quality.md),
+[the usability study protocol](https://github.com/BjRo/sevro/blob/main/docs/usability-study.md),
 [guide evaluation](guide-evaluation.md), [releases](releases.md), and
 [acknowledgements](acknowledgements.md) for maintenance.
 Return to the [Sevro introduction](../README.md).

package/docs/architecture.md

@@ -4,22 +4,143 @@ Sevro owns generic execution/evidence contracts. Projects own cases and policy.
 This lets Darrow and other integrations use the same runner without importing
 their benchmark policy into it.
 
-| Responsibility                                    | Sources                                                                                                            |
-| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| Parse commands/select explicit routes             | [CLI](../src/cli.ts), [CLI reference](development-cli.md)                                                          |
-| Prepare, execute, grade, retain, clean up         | [Engine](../src/engine.ts), [engine slice](engine-slice.md)                                                        |
-| Negotiate trusted extension calls                 | [Client](../src/extension-client.ts), [session](../src/extension-session.ts), [protocol](extension-protocol-v1.md) |
-| Run native hosts and retain bounded observations  | [Codex](codex-host.md), [native controls](native-controls.md), [host sources](../src/hosts/)                       |
-| Reduce execution/grading/task states              | [Result source](../src/results.ts), [contract](results-v1.md)                                                      |
-| Bind comparison identities and release provenance | [Identity](identity-v1.md), [releases](releases.md)                                                                |
-| Summarize retained results                        | [Report](report-v1.md)                                                                                             |
-
-Completed evidence is retained before cleanup. Missing observations remain
-unavailable; unknown measurements do not become zero. Extensions cannot
-silently replace isolation/persistence or built-in policy. The
+This page explains this checkout's implementation and points to acceptance
+tests for changes. [Current contracts](contracts.md) define public behavior;
+[historical validation](https://github.com/BjRo/sevro/blob/main/docs/evidence.md) records bounded past observations. The
+[engine slice](https://github.com/BjRo/sevro/blob/main/docs/engine-slice.md) retains its earlier scope and detailed lifecycle
+explanation. Implementation paths and test scenarios here are navigation, not
+evidence that a particular candidate passed validation.
+
+[`engine.ts`](../src/engine.ts) remains the programmatic facade, and
+[`cli.ts`](../src/cli.ts) remains the installed command entrypoint. The CLI
+loads and assembles evaluation options; evaluation modules coordinate the run
+and its trials.
+
+## Evaluation lifecycle
+
+[`runEvaluation`](../src/evaluation/run.ts) prepares inputs before allocating
+run resources, retains preparation artifacts, and reserves candidate and
+semantic workspace roots as needed before calling the trial scheduler. The map
+follows the path of a retained trial; individual stages can be skipped or fail.
+
+```mermaid
+flowchart TD
+    P["Validate and prepare evaluation inputs"] --> R["Allocate run storage and owner; reserve workspace roots"]
+    R --> W["Admit trial and materialize its reserved fixture"]
+    subgraph Trial["Each admitted trial"]
+        W --> C["Initialize grading bases; execute candidate"]
+        C --> E["Retain candidate artifacts; observe output; prepare grading views"]
+        E --> G["Output, shell, Git, semantic, and extension grading"]
+        G --> A["Assess execution, grading, and task separately"]
+        A --> V["Optional independent advisory review"]
+        V --> T["Retain raw candidate response; atomically write trial evidence"]
+        T --> K["Collect completed trial and checkpoint its reference"]
+        K --> D["Release temporary views; clear or retain fixture contents"]
+    end
+    D --> J["All admitted trials drain"]
+    J --> F["Write final run evidence; finalize owner checkpoint"]
+    F --> X["Finalize retained workspaces; release other reservations"]
+```
+
+[`scheduleTrials`](../src/evaluation/scheduler.ts) bounds active work by the
+prepared job limit. It admits a trial before
+[`prepareTrialWorkspace`](../src/evaluation/resources.ts) materializes that
+trial's fixture. Each [`EvaluationTrial`](../src/evaluation/trial.ts) owns its
+mutable state and writer. Its `run()` method keeps candidate execution,
+artifact retention, grading, assessment, advisory review, persistence, and
+cleanup in one visible order. Grading helpers return checks, observations,
+and failures; the coordinator incorporates those results and stops new
+admission when an execution or required grading error is detected, before
+advisory work, persistence, or cleanup. The scheduler also stops admission on
+cancellation and waits for active workers. A failed task check alone does not
+close admission. Already admitted peers drain and retain their evidence, including
+when they finish out of order.
+
+[`runAdvisoryReview`](../src/evaluation/advisory.ts) handles its own host call,
+assessment, retained response, and auxiliary workspace cleanup. It depends on
+candidate completion, independently of the task assessment. The
 [advisory fixture](advisory-fixture.md) gives review a separate Git view with
-evaluator inputs withheld.
+evaluator inputs withheld. Its recommendation or host failure does not change
+task grading; a failure to retain its evidence remains a persistence error.
+
+Successful [semantic response parsing](../src/evaluation/semantic.ts) clears
+auxiliary fixture contents; successful advisory response parsing removes its
+auxiliary fixture. Both retain response evidence first, including valid failed
+check verdicts or advisory recommendations.
+
+The [trial writer](../src/evidence/trial-writer.ts) writes the trial artifact
+before the coordinator marks it persisted and hands it to the
+[result collector](../src/evaluation/collection.ts). The collector registers
+the completed record, orders records by trial number, and checkpoints retained
+artifact paths. After active work drains, the run coordinator validates and
+writes `run.json` before finalizing the owner as complete or interrupted.
+Persistence failures cannot produce a successful result; the run's failure
+path attempts a diagnostic checkpoint while preserving the original failure.
+
+Trial cleanup releases candidate artifact runtimes and transcript views even
+when the trial fails. Persisted successful fixture contents are cleared while
+their empty reserved roots remain until active work drains. Failed, cancelled,
+grading-error, unavailable-evidence, and failed-task fixtures are retained;
+[workspace ownership](../src/fixtures/workspace-state.ts) tracks their inactive
+retention and startup expiry after 24 hours. Saved evidence stays outside that
+cleanup. See the [results retention contract](results-v1.md#identity-and-provenance)
+for the public boundary, including ownership that cannot be verified.
+
+Dry preparation still validates and materializes fixtures, including declared
+fixture setup, and retains trial records. It skips candidate execution and
+grading, recording `not_run` / `not_requested` / `not_assessed`, as exercised by
+the [engine trial suite](../tests/src/engine-trials.test.ts). Missing observations
+remain unavailable; missing required evidence cannot become a pass. Optional
+unknown measurements remain unknown rather than becoming zero. Extensions
+cannot silently replace isolation, persistence,
+or built-in policy. The [results](results-v1.md) and
+[extension protocol](extension-protocol-v1.md) contracts define those semantics.
+
+## State ownership
+
+[`EvaluationContext`](../src/evaluation/context.ts) carries four explicit
+collaborators: prepared inputs, run resources, the result collector, and retained
+preparation-artifact references. It does not combine mutable trial fields with
+the preparation plan.
+
+| Data or state                  | Owner                                                                                                                                                           | Boundary                                                                                                                                                                                                                                                                          |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Prepared inputs                | [`PreparedEvaluation` in `plan.ts`](../src/evaluation/plan.ts)                                                                                                  | Named fixture, check, and invocation groups plus routes, provenance, redacted configuration, and comparison identity. Preparation completes before run allocation.                                                                                                                |
+| Run resources and reservations | [`RunResources` and `RunWorkspaceReservations` in `resources.ts`](../src/evaluation/resources.ts)                                                               | Run ID, evidence/state locations, process owner, and candidate/semantic reservations. Reservations outlive completed fixture contents; retained workspaces are tracked separately from completed roots.                                                                           |
+| Mutable trial state            | [`TrialRuntimeState` and `EvaluationTrial` in `trial.ts`](../src/evaluation/trial.ts)                                                                           | Candidate result, observations, checks, assessment, temporary views, advisory result, and persisted milestone belong to one admitted trial. Grading receives narrow inputs and explicit effects rather than this state object.                                                    |
+| Collected run results          | [`ResultCollector` in `collection.ts`](../src/evaluation/collection.ts)                                                                                         | Private completed summaries, evidence, and diagnostics; trial-number ordering, snapshots for aggregation, and checkpoint requests. [`run-owner.ts`](../src/run-owner.ts) verifies process ownership and writes owner/checkpoint state.                                            |
+| Evidence writes                | [`TrialEvidenceWriter`](../src/evidence/trial-writer.ts), [preparation retention](../src/evaluation/resources.ts), [run finalization](../src/evaluation/run.ts) | The trial writer owns filenames, private writes, hashes, artifact references, and typed trial-persistence failures. Resource helpers retain preparation bytes; run finalization writes aggregate evidence. [`storage.ts`](../src/storage.ts) supplies atomic private JSON writes. |
+
+Fixture modules own materialization and workspace preparation. Runtime modules
+own declared host runtime policy and private state. Evidence modules validate
+host observations and artifacts, verify retained bytes, and normalize optional
+usage without constructing fixtures. Native host implementations and graders
+remain in their own families.
+
+## Where to change behavior
+
+Start with the responsibility, then inspect its observable acceptance scenarios.
+These are useful starting suites, not an exhaustive validation list. The
+[contribution checks](../CONTRIBUTING.md#quality-contract-and-checks) still govern
+candidate acceptance.
+
+| Responsibility                                                    | Implementation and reference                                                                                                                                                                                                                                                             | Relevant acceptance tests                                                                                                                                                                                                         |
+| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Parse commands/select explicit routes                             | [CLI entrypoint](../src/cli.ts), [invocation parsing](../src/cli/invocation.ts), [CLI reference](development-cli.md)                                                                                                                                                                     | [Invalid invocations](../tests/src/cli/invocation-validation.test.ts)                                                                                                                                                             |
+| Load and prepare a CLI evaluation                                 | [Input loading](../src/cli/loading.ts), [preparation](../src/cli/preparation.ts), [host construction](../src/cli/hosts.ts), [extension resolution](../src/cli/extension.ts), [evaluation assembly](../src/cli/evaluation.ts)                                                             | [Case/configuration validation](../tests/src/cli/case-validation.test.ts)                                                                                                                                                         |
+| Present CLI results and own cancellation                          | [Presentation](../src/cli/presentation.ts), [cancellation](../src/cli/cancellation.ts), [command lifecycle](../src/cli/command.ts)                                                                                                                                                       | [CLI states and exits](../tests/src/cli/results.test.ts), [signal retention](../tests/src/cli/trial-retention.test.ts)                                                                                                            |
+| Prepare evaluation inputs and grade trials                        | [Engine facade](../src/engine.ts), [plan](../src/evaluation/plan.ts), [grading](../src/evaluation/grading.ts), [semantic grading](../src/evaluation/semantic.ts), [evaluation modules](../src/evaluation/), [engine slice](https://github.com/BjRo/sevro/blob/main/docs/engine-slice.md) | [Preparation refusals](../tests/src/evaluation/preparation-validation.test.ts), [semantic grading failures](../tests/src/evaluation/semantic-grading-failures.test.ts), [engine lifecycle](../tests/src/engine-lifecycle.test.ts) |
+| Schedule trials, retain evidence, and finalize ownership          | [Scheduler](../src/evaluation/scheduler.ts), [trial coordinator](../src/evaluation/trial.ts), [reservations](../src/evaluation/resources.ts), [collection](../src/evaluation/collection.ts), [run owner](../src/run-owner.ts)                                                            | [Concurrent admission and ordering](../tests/src/cli/concurrency.test.ts), [trial failures and retention](../tests/src/evaluation/trial-retention.test.ts), [checkpoint refusals](../tests/src/run-owner-checkpoints.test.ts)     |
+| Prepare, construct, and clean up fixtures                         | [Fixture modules](../src/fixtures/), [construction](../src/fixtures/create.ts), [preparation artifacts](../src/fixtures/preparation.ts), [content cleanup](../src/fixtures/cleanup.ts), [workspace ownership](../src/fixtures/workspace-state.ts)                                        | [Artifact preparation](../tests/src/fixtures/artifact-preparation.test.ts), [workspace lifecycle](../tests/src/fixtures/workspace-lifecycle.test.ts)                                                                              |
+| Resolve runtime policy, discovery, and private state              | [Runtime modules](../src/runtime/), [configuration](../src/runtime/config.ts)                                                                                                                                                                                                            | [Runtime environment](../tests/src/runtime/environment.test.ts), [candidate artifact lifetime](../tests/src/candidate-artifacts.test.ts)                                                                                          |
+| Validate host results and retain bounded evidence                 | [Host results](../src/evidence/host-results.ts), [trial writer](../src/evidence/trial-writer.ts), [retained artifacts](../src/evidence/retained-artifacts.ts), [usage](../src/evidence/usage.ts)                                                                                         | [Host evidence refusals](../tests/src/evaluation/host-evidence.test.ts), [failed-host evidence retention](../tests/src/evaluation/trial-retention.test.ts)                                                                        |
+| Negotiate trusted extension calls                                 | [Client](../src/extension-client.ts), [session](../src/extension-session.ts), [extension grading](../src/evaluation/grading.ts), [protocol](extension-protocol-v1.md)                                                                                                                    | [Negotiated engine behavior](../tests/src/evaluation/extension-engine.test.ts), [extension grading outcomes](../tests/src/evaluation/extension-grading.test.ts)                                                                   |
+| Run independent advisory review                                   | [Advisory execution](../src/evaluation/advisory.ts), [blind fixture](../src/fixtures/advisory.ts), [advisory fixture explanation](advisory-fixture.md)                                                                                                                                   | [Advisory failures](../tests/src/evaluation/advisory-failures.test.ts), [blind change view](../tests/src/fixtures/advisory.test.ts)                                                                                               |
+| Run native hosts and retain bounded observations                  | [Codex](codex-host.md), [native controls](native-controls.md), [host sources](../src/hosts/), [shared process mechanics](../src/process-lifecycle.ts), [native waiting](../src/hosts/process-lifecycle.ts)                                                                               | [Native process admission and byte bounds](../tests/src/hosts/native-process-boundaries.test.ts)                                                                                                                                  |
+| Reduce execution/grading/task states and maintain contract shapes | [Result reduction](../src/results.ts), [shared semantic types](../src/contract-types.ts), [wire types](../src/schema-types.ts), [runtime schema boundary](../src/schema.ts), [results contract](results-v1.md)                                                                           | [State and exit precedence](../tests/src/results.test.ts), [evidence schema boundaries](../tests/src/schema/evidence-boundaries.test.ts)                                                                                          |
+| Bind comparison identities and release provenance                 | [Preparation identity inputs](../src/evaluation/plan.ts), [identity hashing](../src/identity.ts), [provenance](../src/provenance.ts), [identity contract](identity-v1.md), [releases](releases.md)                                                                                       | [CLI identity](../tests/src/cli/identity.test.ts), [package release provenance](../tests/scripts/release.test.ts)                                                                                                                 |
+| Summarize retained results                                        | [Report implementation](../src/report.ts), [report contract](report-v1.md)                                                                                                                                                                                                               | [Report states and CLI](../tests/src/report.test.ts)                                                                                                                                                                              |
 
-These paths describe this checkout. [Historical validation](evidence.md) records
-bounded past observations. [Rust research](https://github.com/BjRo/sevro/issues/2)
-does not establish a migration; public interfaces remain useful independently.
+[Rust research](https://github.com/BjRo/sevro/issues/2) does not establish a
+migration; public interfaces remain useful independently. Return to the
+[documentation hub](README.md).

package/docs/assets/README.md

@@ -1,11 +1,12 @@
 # Sevro brand assets
 
 Björn Rochel created the supplied logo in 2026. Its original artwork and white
-background are preserved in `sevro-logo.png`.
+background are preserved in `sevro-logo.png` in the repository. The npm package
+retains these permissions; download the artwork from the links below.
 
-- [Full logo](sevro-logo.png): supplied 1254 × 1254 PNG including the wordmark.
-- [Compact symbol](sevro-symbol.svg): the same artwork framed around the S track.
-- [Wordmark](sevro-wordmark.svg): the same artwork framed around the name.
+- [Full logo](https://raw.githubusercontent.com/BjRo/sevro/main/docs/assets/sevro-logo.png): supplied 1254 × 1254 PNG including the wordmark.
+- [Compact symbol](https://raw.githubusercontent.com/BjRo/sevro/main/docs/assets/sevro-symbol.svg): the same artwork framed around the S track.
+- [Wordmark](https://raw.githubusercontent.com/BjRo/sevro/main/docs/assets/sevro-wordmark.svg): the same artwork framed around the name.
 
 SVG variants embed the supplied PNG; they are not traced vector redrawings.
 Keep a white backing on dark pages; no transparent variant is claimed. Use the

package/docs/builtin-graders-v1.md

@@ -38,8 +38,10 @@ The shell-check process runner accepts a bounded evaluator-owned `run` string,
 optional `expectedExitCode` and `timeoutMs`, plus `expectExact`, `expectRegex`,
 `notRegex`, and regex `flags` for stdout. Exact matching removes one final
 newline; regex matching always uses multiline mode. The runner executes with
-`sh -e`. On macOS and Linux it runs through the outer sandbox with network access denied,
-a credential-free environment, and caller-declared protected roots. Without a
+`sh -e`. On macOS and Linux it runs through the outer sandbox with network access denied
+by default, a credential-free environment, and caller-declared protected roots.
+The runtime [local HTTP option](runtime-v1.md#local-http-test-servers) permits
+socket-using upstream tests while retaining outbound isolation. Without a
 stdout assertion, process output is discarded. With one, the runner captures
 at most 1 MiB in memory and retains only its digest and byte length. Oversized
 or invalid UTF-8 output is a grading error.
@@ -49,11 +51,16 @@ one bounded observation per check. A mismatched exit code or stdout assertion
 fails the task; an isolation, timeout, or process error makes grading
 an error. Callers must supply `shellIsolation.protectedRoots` for any shell
 check. The engine also protects its package source, project, results, user
-home, configured host homes, and active peer fixtures. The caller's list must
+home, configured host homes, and other managed workspaces. The caller's list must
 include any other source worktrees or private roots. A peer path already
 canonicalized by the engine remains in the deny profile if that peer is
 removed before the sandbox starts; unverified missing roots still fail.
 
+On macOS, validated runtime grants also permit limited
+[ancestor metadata reads](runtime-v1.md#macos-ancestor-metadata) so libc can
+canonicalize granted paths. Protected ancestor listings and ungranted sibling
+data remain inaccessible.
+
 `sevro.git-head` accepts `kind: "changed"`, `"unchanged"`, or
 `"base-ancestor"` for a generated or repository Git fixture. The engine
 captures the fixture's base HEAD before the candidate turn, then compares the
@@ -98,3 +105,10 @@ shell checks and semantic hosts can read retained candidate native files through
 live native tree. Native transcripts are untrusted candidate evidence; a grader
 must not follow instructions inside them. Missing or partial capture remains
 explicit in the index and does not establish required complete evidence.
+
+With [candidate artifact access](runtime-v1.md#candidate-artifact-access),
+shell checks and semantic/advisory hosts can also read explicitly declared
+subtrees in the candidate's original private home. Named paths reach commands
+through `SEVRO_CANDIDATE_ARTIFACT_<UPPERCASE_NAME>`, independently of native
+transcript access. These grants are read-only; other candidate home contents
+remain protected. Missing or unsafe declared directories make grading an error.