@bjoernrochel/sevro 0.1.0-rc.2 → 0.1.0-rc.20

package/CONTRIBUTING.md

@@ -0,0 +1,170 @@
+# Contributing to Sevro
+
+Contributions are welcome: runner fixes, extension examples, tests, documentation,
+and useful bug reports. Agent guidance lives in `AGENTS.md` in a source checkout.
+The [public contracts](docs/contracts.md) define the behavior compatibility boundary.
+
+## Contribution licensing
+
+By intentionally submitting a contribution for inclusion, you confirm that you
+created it or have permission to license it, including employer-owned work.
+Identify third-party material and its license separately; do not grant rights
+you lack. You make your contribution available under [Sevro's public license](LICENSE).
+
+In addition, you grant Björn Rochel a worldwide, perpetual, non-exclusive,
+irrevocable, royalty-free copyright license to use, reproduce, modify, publicly
+display, publicly perform, distribute, and license or sublicense the contribution
+and its derivatives under other terms, including open-source and commercial
+licenses. You retain copyright. This grants permission, not ownership.
+
+Other recipients receive the public terms unless separately licensed. This is
+not an Apache-2.0 grant to every recipient. The additional grant lets the
+maintainer offer alternatives without obtaining new copyright permission from
+each contributor. If you cannot agree, raise that before submitting work for
+inclusion. Contributions are provided without warranties to the extent permitted
+by applicable law.
+
+## Set up development
+
+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
+bun install --frozen-lockfile
+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
+
+[The TypeScript quality contract](docs/typescript-quality.md) defines the checked
+source inventory, type-aware lint, strict typing, focused functions, reproducible
+properties, and independent statement and branch coverage requirements.
+Run the complete acceptance command:
+
+```sh
+bun run check:typescript
+```
+
+It performs frozen installation, schema freshness, formatting, lint, typing,
+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
+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
+typed; they do not enter the production coverage denominator. New or changed
+source dispositions require review.
+
+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).
+Documentation checks supplement #1 rather than replacing its contract.
+
+## Delivery and CI ownership
+
+An implementation PR is complete only when required CI checks pass for its exact
+published commit. A request to open or update a PR includes monitoring CI and
+repairing in-scope failures; it does not authorize merging or unrelated changes.
+
+- Use GitHub CI in `.github/workflows/verify.yml` for full acceptance validation.
+  It provides the configured OS, architecture, runtime and native-tool versions,
+  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 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,
+  bypass checks, or add artificial tests just to move a counter. Remove impossible
+  branches by clarifying validated invariants rather than inventing impossible inputs.
+- Bind validation to the candidate's exact source and commit. Changes to source,
+  tests, tooling, dependencies, schemas, workflows, or guidance invalidate prior
+  candidate evidence; require the applicable CI gates on the updated published head.
+- After authorized publication, observe required checks for the exact PR head
+  until they finish. Queued or running checks, a successful older commit, and a
+  passing subset are not completion.
+- On failure, inspect the failed job and retained artifacts, reproduce the cause
+  locally when useful, repair within the authorized scope, and publish a non-force
+  update to the same PR. Continue monitoring without waiting for the user to notice
+  the failure or request correction; do not open a duplicate PR or merge it.
+- If an external blocker prevents progress, report its concrete evidence and the
+  unfinished checks. Keep the PR's status and description honest; do not report
+  delivery as complete while required checks remain failing or unobserved.
+
+Release metadata follows `docs/releases.md` and its existing verified-source CI
+reuse policy; these implementation gates do not require release test reruns.
+
+## Tests, fixtures, and schemas
+
+Preserve real Bun filesystem/process integration tests and native isolation.
+Use deterministic fixtures under `tests/fixtures/`; keep evaluator-only inputs
+outside candidate workspaces. Keep credentials and raw trial evidence out of Git.
+Add meaningful regression coverage for reproducible bugs. Fixtures should
+establish observable behavior, not mirror implementation.
+
+After changing a schema, regenerate its checked-in validators:
+
+```sh
+bun run schemas:generate
+bun run schemas:check
+```
+
+Commit schemas and validators together. Public v1 schemas and extension
+capabilities are compatibility boundaries. Document changed meaning, validate
+external inputs, and keep missing evidence from becoming a pass.
+
+## Documentation and pull requests
+
+Give each page one reader need: tutorial, how-to, reference, or explanation.
+Maintain the [hub](docs/README.md), old destinations, prerequisites, expected
+results, and limitations. Preserve historical observations as evidence rather
+than rewriting them to describe current behavior.
+
+Use imperative Conventional Commit subjects without trailing periods. Do not
+add `Co-authored-by` or AI attribution trailers. Do not change author metadata
+without explicit instruction. A PR explains the problem, changed behavior,
+compatibility limits, and checks actually performed. Do not claim unexecuted
+native trials or remote CI results.
+
+## Maintainer releases
+
+Follow [releases](docs/releases.md): reuse successful source CI, choose a new
+version, and submit the release commit through a PR. Release PRs reuse the
+existing full quality gate and run static metadata checks; releases do not
+rerun local or CI tests. After the PR merges, prepare and inspect the exact
+tarball and verify its license, provenance, and checksums before publication.
+After changing `package.json.version`, run `bun run docs:sync` to refresh the
+[current release](docs/installing.md#current-release). `check:docs`, release
+preparation, and package-install validation reject stale release documentation.
+Package-install, native, and Darrow compatibility tests belong to development
+or an explicitly requested diagnostic, not the release process. Darrow's
+dependency update is a separate PR.
+Publication, tags, registry changes, and alternative licensing are separate
+maintainer actions; preparing a contribution does not authorize them.

package/LICENSE

@@ -1,159 +1,86 @@
-Business Source License 1.1
+Sevro Source Available License 1.0
 
-License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
-"Business Source License" is a trademark of MariaDB Corporation Ab.
+Copyright (c) 2026 Björn Rochel
 
------------------------------------------------------------------------------
+1. Definitions
 
-Parameters
+"Software" means Sevro source code, executable forms, documentation, and
+modifications or derivative works of those materials, except material
+explicitly identified as having separate terms. Logo/branding permissions
+are separate and stated in docs/assets/README.md. Third-party material
+retains its identified license.
 
-Licensor:             Björn Rochel <bjoern@bjro.de>
+"You" means the person or legal entity exercising these rights.
 
-Licensed Work:        Sevro — a standalone evaluation runner for coding agents.
-                      The Licensed Work is (c) 2026 Björn Rochel.
+2. Free use and modification
 
-Additional Use Grant: You may make production use of the Licensed Work only
-                      as follows:
+Subject to this license, you may use, copy, modify, and create derivative
+works of the Software without a license fee, for any purpose. This includes
+commercial and non-commercial work, paid education, research, evaluation,
+consulting, and organizational use.
 
-                        (a) use within your own organization, for any
-                            purpose, commercial or non-commercial, provided
-                            that such use is not Commercial Educational
-                            Production Use;
+3. Free redistribution and origin
 
-                        (b) use while performing professional, consulting,
-                            or contract services for your own clients,
-                            provided that those services do not include
-                            Commercial Educational Production Use;
+You may redistribute the Software in source or executable form, including
+modified versions, without charge and under this license. Include this
+license, retain applicable copyright/attribution/origin notices, identify
+Sevro as the source of covered code, and prominently identify modifications.
+Do not claim another person's contribution was authored by you or imply
+that a modified version is an official Sevro release.
 
-                        (c) use in preparing or delivering training,
-                            workshops, courses, talks, presentations, or
-                            other educational offerings, or in creating or
-                            publishing blog posts, articles, or other
-                            educational content, provided that such
-                            production use is not Commercial Educational
-                            Production Use;
+These conditions also apply to covered code in combined distributions.
+Independently authored material containing no covered Software may have
+separate terms that neither restrict these rights nor circumvent section 4.
 
-                        (d) use in research, evaluation, and personal
-                            projects, provided that such use is not
-                            Commercial Educational Production Use;
+4. No sale or paid hosted access under this public license
 
-                      provided that such production use does not include
-                      distributing, selling, sublicensing, hosting, or
-                      otherwise offering the Licensed Work, or a derivative
-                      work of the Licensed Work, to third parties as a
-                      product or service whose principal value is the
-                      functionality of the Licensed Work.
+You may not charge directly or indirectly for copies of the Software, a
+license to it, or access to its functionality as a hosted or managed service.
+This includes modified, derivative, renamed, and rebranded versions. Bundling
+or relabeling does not avoid this condition, including when the principal
+value of a paid offering is access to the Software's functionality.
 
-                      For purposes of this Additional Use Grant,
-                      "Commercial Educational Production Use" means
-                      production use of the Licensed Work in preparing,
-                      delivering, or publishing any educational offering or
-                      content where you or anyone acting on your behalf:
+You may charge for independent professional services, training, research,
+analysis, or other work performed using the Software, provided the payment
+is not for copies, licensing, or hosted access to its functionality. Calling
+a charge a hosting, subscription, service, or support fee does not permit
+charging for otherwise restricted access.
 
-                        (i) receives or expects to receive, directly or
-                            indirectly, a fee, compensation, sponsorship, or
-                            other consideration in connection with it;
+Restricted distribution or hosted access requires a separate license from
+the relevant rights holder. Contact Björn Rochel at bjoern@bjro.de for
+alternative terms. This public license grants no general right to relicense
+covered Software under other terms.
 
-                        (ii) supplies it as part of, or uses it to advertise
-                             or promote, a paid product, service, membership,
-                             or engagement; or
+5. Contributions and separate grants
 
-                        (iii) uses it to generate leads or obtain any other
-                              direct or indirect commercial benefit.
+Contributions intentionally submitted for inclusion are governed by the
+terms in CONTRIBUTING.md, including the additional copyright license to
+Björn Rochel. Contributors retain copyright. Additional/alternative grants
+apply only to their stated recipients and terms, not to every recipient.
 
-                      Reasonable reimbursement of expenses alone does not
-                      constitute Commercial Educational Production Use.
-                      Commercial Educational Production Use is not included
-                      in this Additional Use Grant.
+6. Independent inputs, outputs, and branding
 
-                      For clarity, nothing in this Additional Use Grant
-                      limits the non-production rights granted under the
-                      Terms below.
+This license does not by itself apply to independently authored cases,
+datasets, extensions, prompts, or outputs merely because Sevro processes
+them. Material copying or deriving from covered Software remains subject
+to its applicable terms. Other material/input licenses still apply.
 
-                      For clarity, contributing modifications back to the
-                      Licensed Work, and publishing forks that are
-                      themselves offered free of charge under this License,
-                      are permitted.
+This software license grants no trademark or logo rights. Separate project
+identification permissions appear in docs/assets/README.md.
 
-Change Date:          Two years from the date on which the applicable
-                      version of the Licensed Work is first made publicly
-                      available. The Change Date is determined separately
-                      for each released version.
+7. Termination
 
-Change License:       Mozilla Public License, version 2.0
+Your permissions terminate if you violate these conditions. Other recipients'
+compliant permissions are not terminated by your violation. The relevant
+rights holder may reinstate permissions.
 
-For information about alternative licensing arrangements for the Licensed Work,
-please contact: bjoern@bjro.de
+8. Disclaimer and liability
 
------------------------------------------------------------------------------
+To the fullest extent permitted by applicable law, the Software is provided
+"as is", without express or implied warranties, including merchantability,
+fitness for a particular purpose, title, or non-infringement. No author,
+contributor, or rights holder is liable for damages or other liability
+arising from the Software or its use, in contract, tort, or otherwise.
 
-Notice
-
-Business Source License 1.1
-
-Terms
-
-The Licensor hereby grants you the right to copy, modify, create derivative
-works, redistribute, and make non-production use of the Licensed Work. The
-Licensor may make an Additional Use Grant, above, permitting limited
-production use.
-
-Effective on the Change Date, or the fourth anniversary of the first publicly
-available distribution of a specific version of the Licensed Work under this
-License, whichever comes first, the Licensor hereby grants you rights under
-the terms of the Change License, and the rights granted in the paragraph
-above terminate.
-
-If your use of the Licensed Work does not comply with the requirements
-currently in effect as described in this License, you must purchase a
-commercial license from the Licensor, its affiliated entities, or authorized
-resellers, or you must refrain from using the Licensed Work.
-
-All copies of the original and modified Licensed Work, and derivative works
-of the Licensed Work, are subject to this License. This License applies
-separately for each version of the Licensed Work and the Change Date may vary
-for each version of the Licensed Work released by Licensor.
-
-You must conspicuously display this License on each original or modified copy
-of the Licensed Work. If you receive the Licensed Work in original or
-modified form from a third party, the terms and conditions set forth in this
-License apply to your use of that work.
-
-Any use of the Licensed Work in violation of this License will automatically
-terminate your rights under this License for the current and all other
-versions of the Licensed Work.
-
-This License does not grant you any right in any trademark or logo of
-Licensor or its affiliates (provided that you may use a trademark or logo of
-Licensor as expressly required by this License).
-
-TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
-AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
-EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
-TITLE.
-
-MariaDB hereby grants you permission to use this License's text to license
-your works, and to refer to it using the trademark "Business Source License",
-as long as you comply with the Covenants of Licensor below.
-
-Covenants of Licensor
-
-In consideration of the right to use this License's text and the "Business
-Source License" name and trademark, Licensor covenants to MariaDB, and to all
-other recipients of the licensed work to be provided by Licensor:
-
-1. To specify as the Change License the GPL Version 2.0 or any later version,
-   or a license that is compatible with GPL Version 2.0 or a later version,
-   where "compatible" means that software provided under the Change License
-   can be included in a program with software provided under GPL Version 2.0
-   or a later version. Licensor may specify additional Change Licenses
-   without limitation.
-
-2. To either: (a) specify an additional grant of rights to use that does not
-   impose any additional restriction on the right granted in this License, as
-   the Additional Use Grant; or (b) insert the text "None".
-
-3. To specify a Change Date.
-
-4. Not to modify this License in any other way.
+This is a source-available license, not an OSI open-source license. It has
+no automatic change date. Earlier releases retain their original grants.

package/README.md

@@ -1,72 +1,89 @@
 # Sevro
 
-Sevro is a standalone evaluation runner for agentic coding capabilities. It is
-being extracted from [Darrow](https://github.com/BjRo/darrow/issues/95). This
-checkout runs locally and packs as an installable npm tarball.
-The npm package is `@bjoernrochel/sevro`; its installed command is `sevro`.
-
-The public v1 contracts are [the extension protocol](docs/extension-protocol-v1.md)
-and [run results](docs/results-v1.md). Sevro owns these generic interfaces;
-projects own their cases and evaluator policy.
-The [generic report](docs/report-v1.md) summarizes retained public results
-without treating unknown measurements as zero or inferring matched comparisons.
-
-Machine-readable contracts live in [`schemas/`](schemas/). Run `bun install`,
-`bun test`, `bun run typecheck`, `bun run format:check`, and
-`bun run test:package-install` to validate the npm tarball locally. The package
-test packs and installs Sevro in a temporary project, then runs the installed
-CLI without a Sevro Git checkout.
-
-The [release workflow](docs/releases.md) prepares a versioned artifact with its
-file inventory and checksums, verifies that exact tarball, and documents manual
-publication, trusted publishing, Darrow pinning, updates, and rollback.
-
-Sevro uses the owner-selected [Business Source License 1.1](LICENSE), preserving
-Darrow's terms and parameters with Sevro named as the Licensed Work. The first
-published candidate is `0.1.0-rc.1`. This checkout prepares `0.1.0-rc.2` with
-the concurrent Darrow runner updates; its publication and Darrow pin update
-remain separate steps.
-
-[`extension-client.ts`](src/extension-client.ts) validates one request and
-response per extension process and negotiates the v1 protocol. It enforces
-message limits, timeouts, response identity, and process-group cancellation.
-
-[`extension-session.ts`](src/extension-session.ts) runs the negotiated
-`resolve`, `prepare`, and `evaluate` methods and checks source stability and
-evidence references. The engine accepts additive extension checks for inline
-cases.
-
-[`results.ts`](src/results.ts) reduces checks to separate execution, grading,
-and task states, applies case thresholds, and maps the aggregate to a CLI exit
-category.
-[`identity.ts`](src/identity.ts) computes versioned comparison identities from
-canonical JSON. The [identity contract](docs/identity-v1.md) defines the input
-dimensions.
-
-The [built-in output graders](docs/builtin-graders-v1.md) evaluate regex, JSON,
-and inline schema assertions on bounded final-message observations.
-
-The [first engine slice](docs/engine-slice.md) executes resolved cases through
-an injected host adapter and retains trial evidence before fixture cleanup.
-The [advisory review fixture](docs/advisory-fixture.md) builds a separate Git
-view of the complete candidate change while withholding evaluator paths.
-The [development CLI](docs/development-cli.md) runs that path with a trusted
-adapter module or the bundled Codex and Claude Code routes and emits a
-machine-readable result.
-The [native control observation](docs/native-controls.md) exposes bounded tool
-labels for extension policy on both Codex and Claude, with explicit completeness.
-
-The packaged [basic example](examples/basic/) runs without Darrow or a model
-account. From this checkout, run the graded case with:
+<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">
+</p>
+
+Sevro runs repeatable evaluations of coding agents. Give it a case, a host
+adapter, and success criteria; it retains execution, grading results, and
+evidence. Projects own their benchmark cases and policy through Sevro's
+[extension boundary](docs/extension-protocol-v1.md).
+
+Sevro grew out of [Darrow](https://github.com/BjRo/darrow), but works without a
+Darrow checkout. Try [your first evaluation](docs/getting-started.md): no model
+account is required.
+
+## Status and environments
+
+Sevro is under active development. The npm package is `@bjoernrochel/sevro`;
+its command is `sevro`. The [current release](docs/installing.md#current-release) includes runtime
+configuration, native goals, selected plugin hooks, and the current licensing terms.
+Earlier `rc.1` and `rc.2` packages retain their original BSL grants.
+See [installation and release differences](docs/installing.md).
+
+Use Bun 1.3.13. The development checkout runs native isolation on macOS with
+`sandbox-exec` and on Ubuntu with `bubblewrap` and `socat`.
+Contributor package/release checks also need Node 24 and npm.
+Windows support is unverified. The basic example uses an injected
+deterministic adapter and needs no native model credentials.
+
+## Install and get a first result
 
 ```sh
-bun src/cli.ts run --json \
-  --case-file "$PWD/examples/basic/graded.json" \
-  --adapter-module "$PWD/examples/basic/host.ts" \
-  --project-root "$PWD" --results-root /tmp/sevro-basic-results \
-  --condition passive --trials 1 --threshold 1
+mkdir sevro-demo
+cd sevro-demo
+bun init -y
 ```
 
-Use `prompt-only.json` in place of `graded.json` to see successful execution
-with `task.verdict: not_assessed`. The package installation check runs both
-cases through the installed CLI, with no Sevro source checkout present.
+Install the [current release](docs/installing.md#current-release) in that directory.
+Continue with [your first evaluation](docs/getting-started.md): the exact command,
+expected `passed` result, and retained evidence. Read [installation](docs/installing.md)
+for updates, removal, and source checkouts.
+
+The development checkout and freshly built packages provide a
+[demo-to-iteration workflow](docs/evaluation-workflow.md): initialize real
+assertions, prepare, execute, read progress and inspect the latest result.
+The published `rc.11` package uses the installed tutorial above.
+
+## Find your next task
+
+The [documentation hub](docs/README.md) routes to running evaluations, authoring
+cases and extensions, reading results, troubleshooting, and architecture.
+Public v1 contracts are the [extension protocol](docs/extension-protocol-v1.md),
+[results and evidence](docs/results-v1.md), and [report](docs/report-v1.md).
+Machine-readable contracts live in [schemas/](schemas/).
+
+## Ask the repository guide
+
+Open this checkout in a fresh Codex or Claude Code session and ask
+“What is Sevro, and how do I run my first evaluation?” Explicit invocation is
+`$sevro-guide` in Codex or `/sevro-guide` in Claude Code.
+The guide reads sources, cites its answers, and handles follow-ups. It explains
+commands; execution requires a separate request. See the
+[guide contract and verification limits](docs/specs/repository-guide.md).
+The npm package does not install the repository guide.
+
+## Contribute
+
+[CONTRIBUTING.md](CONTRIBUTING.md) covers setup, checks, fixtures, schema
+regeneration, compatibility, and releases. [Documentation quality](docs/documentation-quality.md)
+defines documentation checks and review.
+
+Run `bun run check:typescript` for the complete quality gate and
+`bun run check:typescript --fast` before committing. The
+[TypeScript quality contract](docs/typescript-quality.md) defines the source
+inventory, strict typing, property tests, coverage integrity, and supported
+environment.
+
+## License and acknowledgements
+
+The [current release](docs/installing.md#current-release) uses the [Sevro Source Available License 1.0](LICENSE).
+Use is free in every context, including commercial work and paid education.
+Selling copies, rebranded versions, or hosted access to Sevro's functionality
+requires a separate license. Modification and free redistribution remain allowed.
+It is source-available, not an OSI open-source license. Read
+[licensing](docs/licensing.md) for contribution grants and earlier BSL releases.
+
+Björn Rochel created the logo. Sevro's name is inspired by the character in
+Pierce Brown's _Red Rising_. Thank you, Pierce Brown, for the world and characters
+that inspired both Sevro and Darrow. See [acknowledgements](docs/acknowledgements.md).

package/docs/README.md

@@ -0,0 +1,44 @@
+# Sevro documentation
+
+<img src="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)              |
+| 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
+
+Ask ordinary Sevro questions in a fresh repository session, or use `$sevro-guide`
+in Codex and `/sevro-guide` in Claude Code. The
+canonical guide at `.agents/skills/sevro-guide/SKILL.md` reads evidence and
+explains it; it does not run installations, tests, or evaluations.
+It belongs to this repository, not an npm installation.
+
+## Sources and authority
+
+[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.
+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](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/acknowledgements.md

@@ -0,0 +1,14 @@
+# Acknowledgements
+
+Sevro is named after the character in [Pierce Brown's _Red Rising_ series](https://www.piercebrown.com/redrisingsaga).
+Thank you, Pierce Brown, for the world and characters that inspired both Sevro
+and Darrow. This acknowledges inspiration, not ownership of the fictional
+character or affiliation with the author.
+
+Björn Rochel created the Sevro logo. Its black/red track motif gives the runner
+its own visual identity alongside [Darrow](https://github.com/BjRo/darrow).
+Read [brand assets and permitted uses](assets/README.md).
+
+Sevro's standalone runner grew out of Darrow's evaluation work. Darrow remains
+an integration and source of ideas; the deterministic example works independently.
+Return to the [documentation hub](README.md).