npm - @hraness/sys1 - Versions diffs - 0.17.0 → 0.18.0 - Mend

@hraness/sys1 0.17.0 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md +155 -590
package/dist/cli.js +2944 -1047
package/dist/gateway.d.ts +1 -1
package/dist/index.js +1 -1
package/dist/packs/core/fixtures/calibration.jsonl +2 -2
package/dist/packs/core/fixtures/heldout.jsonl +2 -2
package/dist/packs/core/pack.yaml +18 -14
package/package.json +21 -5

package/README.md CHANGED Viewed

@@ -1,677 +1,242 @@
 # Sys1
-Sys1 helps coding agents review changes against your repository's rules, with
-probability-scored answers from hosted Jev, a local model, or your own server.
-Review and final-message verification are experimental and advisory.
+Sys1 gives coding agents tools to review code, check completion claims, and get
+structured answers from Jev or a local model. Jev is TypeSafe’s hosted decision
+model. Project skills work with Codex, Claude Code, and Devin; applications can
+use the same tools through a CLI, Node/Bun client, or HTTP API.
-Underneath, Sys1 lets agents ask yes/no, choice, and score questions and get
-validated answers with probabilities. You choose who answers: TypeSafe's hosted
-[Jev](https://docs.typesafe.ai/models), a local model on your machine, or a
-compatible server you run.
+Latest release: v0.18.0. Install the GitHub release with npm and run it with
+Bun 1.3.14 or newer. MIT licensed.
-Call Sys1 from a small Node/Bun client, embed the router in a Bun app, or run a
-local daemon that serves the Jev-compatible `POST /v1/systemone` API.
+[Get started](#install) · [Agent skills](https://sys1.io/skills) · [Documentation](https://sys1.io/docs) · [Releases](https://github.com/hraness/sys1/releases)
-Latest release: v0.17.0. Install it from the GitHub release with npm; it runs
-on Bun 1.3.14 or newer.
+## Choose what helps your workflow
-[Project site](https://sys1.io) · [Agent skills](https://sys1.io/skills) · [Protocol](#the-endpoint) · [Routing](#routing)
-## Choose a workflow
-| Task | Start here | What you get |
+| You want to | Use | What you receive |
 | --- | --- | --- |
-| Review an agent's code changes | [`sys1 review`](docs/review.md) | Candidates tied to selected rules and diff evidence, with feedback and reuse of unchanged reviews. |
-| Check a completion message | [`sys1 verify`](docs/verify.md) | A comparison of claimed commits, pushes, checks, and live changes with reachable evidence. |
-| Run one review without saved history | [`sys1 audit`](docs/audit.md) | A stateless diff check with a preview, request cap, and skipped-evidence report. |
-| Reuse a repository convention | [`sys1 rules`](docs/review.md#draft-a-repository-rule) | A draft you can inspect, test on examples, and activate for future reviews. |
-| Add decisions to an application | [Node/Bun client](#use-as-a-module) or [HTTP API](#the-endpoint) | Yes/no, choice, and score answers with a selected model and validated response shape. |
-The review and verification skills work in Git repositories with Codex,
-Claude Code, or Devin; other agents can use the same CLI. Their workflows do
-not depend on a specific framework or hosting provider. The bundled review
-rules cover two narrow JavaScript and TypeScript changes: newly empty catch
-blocks and removed test assertions. Add and evaluate your own rules for other
-conventions or languages.
+| Save a check and continue its review later | [`sys1 workflow`](#save-a-check-and-continue-its-review) | A saved execution record, a private command log, and input checks before resume. |
+| Check a change against a repository rule | [`sys1 review`](#review-changes-with-your-agent) | Candidates tied to the rule and diff, with feedback and reuse of unchanged reviews. |
+| Check a proposed completion message | [`sys1 verify`](#check-an-agents-completion-message) | A comparison with Git state, linked pull requests, and live pages. |
+| Add a decision to application code | [Client and HTTP API](#use-as-a-module) | Yes/no, choice, or score answers with probabilities and validated response shapes. |
+| Keep long test logs out of the agent’s context | [System One Skills](https://sys1.io/skills#compact-checks), a separate package | A short result, the command’s exit status, and the full log saved locally. No model or API key. |
 ## Install
-Requires Bun 1.3.14 or newer. Install the release file from GitHub. Its SHA-256
-is listed on the release, and release files cannot be replaced after
-publishing. `--allow-scripts=node-llama-cpp` lets only the pinned native
-inference package run its install script. The installed `sys1` command runs
-with Bun.
+Install [Bun](https://bun.sh/docs/installation) 1.3.14 or newer and have npm
+available, then run:
 ```sh
 npm install --global --allow-scripts=node-llama-cpp \
-  https://github.com/hraness/sys1/releases/download/v0.17.0/hraness-sys1-0.17.0.tgz
-sys1 doctor
-```
-To build the current source instead:
-```sh
-git clone https://github.com/hraness/sys1.git
-cd sys1
-bun install
-bun run build:dist
-ln -sf "$PWD/dist/cli.js" ~/.local/bin/sys1
+  https://github.com/hraness/sys1/releases/download/v0.18.0/hraness-sys1-0.18.0.tgz
+sys1 --version
 ```
-## Review changes with your agent (experimental)
+The version command prints the installed release number. The release supports macOS, Linux,
+and Windows. `--allow-scripts=node-llama-cpp` allows the optional local inference
+runtime’s install script; installation downloads no model weights and enables
+no hosted backend. The release includes a SHA-256 checksum.
-The project skill teaches an agent when to preview a review, investigate a
-candidate, record feedback, and check its completion message. It installs
-instructions in your repository, without activating a model or adding hooks.
+## Save a check and continue its review
-First [enable hosted Jev](#add-hosted-jev) with `TYPESAFE_API_KEY` available in
-your environment, or choose another configured backend. Install the skill and
-preview selected files before sending source to that backend:
+From a Git worktree on macOS or Linux, run your repository’s check command:
 ```sh
-sys1 review setup codex
-sys1 review checkpoint --staged --model typesafe/jev-1.13.0 \
-  --max-requests 10 --dry-run --json -- src test
+sys1 workflow check -- bun test
+sys1 workflow list
 ```
-Use `setup claude-code` for Claude Code or `setup devin` for Devin. Inspect the
-preview, then repeat without `--dry-run` to run the checkpoint. Investigate
-candidates, record feedback, and recheck the original evidence. Repeated
-complete batches reuse their review for up to 24 hours. Add `--rule <id>` to
-focus a checkpoint on a rule from `sys1 rules list`.
+Sys1 saves the result and command output locally. This check needs no model or
+API key. After configuring a backend, `sys1 workflow review` can run the check
+and then review the selected changes. You can pause after the check and resume
+with the same inputs; uncertain interrupted steps are never silently repeated.
+ALGAL handles execution and saved state inside Sys1.
-Findings are advisory, and scores are not calibrated defect probabilities. See
-the [agent review guide](docs/review.md) for setup, feedback, rechecks, and rule
-drafts. For a stateless check, use [`sys1 audit`](docs/audit.md). Both report
-skipped evidence and incomplete coverage.
+The [workflow guide](docs/workflows.md) covers scoped reviews, resume, private
+logs, and inspecting a saved run. Keep running fresh required checks before
+delivery.
-## Check an agent's completion message
+## Review changes with your agent
-Install the standalone verification skill when you want completion checks
-without the review workflow:
+Run these commands inside the Git repository you are working on. They install
+project instructions and preview a review without calling a model:
 ```sh
-sys1 verify setup codex
-```
-Use `setup claude-code` or `setup devin` for those agents. The installed
-instructions tell the agent to save its proposed final message and compare
-its claims with the repository, linked pull requests, and live pages. Save the
-draft outside the Git worktree so it does not appear as an uncommitted change.
-You can also run the command directly:
-```sh
-sys1 verify --message /tmp/final-message.txt --model typesafe/jev-1.13.0
-```
-Use `--message -` for piped text and `--url https://example.com` to include a
-live page the message does not link. Without `--message`, verify reads the
-newest matching local Devin session, including that turn's check-command
-results. File and stdin input work with any agent; check-command results are
-available only through Devin transcript discovery. Contradicted claims exit 7;
-missing evidence is unverifiable. A clean report does not prove task completion.
-See [the verification guide](docs/verify.md) for evidence and limits.
-## Use as a module
-For a Node 24 or Bun application that calls a running gateway, install the
-release package without the optional native runtime:
-```sh
-npm install --omit=optional \
-  https://github.com/hraness/sys1/releases/download/v0.17.0/hraness-sys1-0.17.0.tgz
-```
-```ts
-import { createClient } from "@hraness/sys1/client";
-const sys1 = createClient(); // http://127.0.0.1:13900
-const { response, metadata } = await sys1.evaluate({
-  state: "The build failed after a dependency upgrade.",
-  questions: {
-    action: {
-      type: "choice",
-      criteria: { repair: "Fix the build", continue: "Continue work" },
-    },
-  },
-}, { signal: AbortSignal.timeout(5_000) });
-console.log(response.answers.action, metadata.backend);
+sys1 review setup codex
+sys1 review checkpoint --worktree --model typesafe/jev-1.13.0 \
+  --max-requests 10 --dry-run --json -- src test
 ```
-The client validates inputs and correlates every returned answer with its
-question. It bounds response bytes, supports cancellation, and returns stable
-sanitized `Sys1ClientError` codes. It never retries, reads credentials from the
-environment, starts a daemon, downloads weights, or imports native inference.
-Supply `baseUrl` and `headers` explicitly for another approved endpoint.
-Import schemas and request/response types from the same `/client` entry point.
+For Claude Code, use `setup claude-code`; for Devin, use `setup devin`. Replace
+`src test` with the paths you changed. The preview lists selected files, rules,
+skipped evidence, and the number of requests. If no requests are planned, inspect the skipped
+evidence, selected paths, and active rules. Setup adds no automatic hooks and preserves
+existing instructions.
-For a Bun application that owns routing and model lifecycle in-process:
+The bundled rules cover newly empty catch blocks and removed test assertions
+in JavaScript and TypeScript. Add [your repository’s rules](docs/review.md#draft-a-repository-rule)
+for conventions that need judgment. For an exact syntax pattern, use a linter.
+Review and completion checks are experimental and advisory: investigate
+findings and keep the repository’s normal tests and review.
-```ts
-import { createRouter, DEFAULT_CONFIG } from "@hraness/sys1";
-const router = createRouter({
-  config: DEFAULT_CONFIG,
-  env: process.env,
-  home: "/absolute/path/to/sys1-state", // previously installed models
-});
-try {
-  const result = await router.evaluate({
-    state: "All required checks passed.",
-    questions: { ready: { type: "noul", instructions: "Are the checks passing?" } },
-  });
-  console.log(result.response.answers.ready);
-} finally {
-  await router.dispose();
-}
-```
+### Add hosted Jev
-The embedded router opens no port. It uses the same routing and validation as
-the daemon and owns its local runner until disposal. Its runtime requires Bun;
-the `/client` entry point is portable to Node. Keep one router per application,
-not one per request. The root package also exposes lower-level routing and
-model-management APIs; applications should normally use `createClient` or
-`createRouter`.
-### Adopting Sys1 in an existing Jev application
-Keep domain questions, deterministic fallback, action authorization, and quality
-thresholds in the application. Put endpoint configuration, transport, routing,
-response validation, and local engine lifecycle behind Sys1. Existing HTTP
-clients in other languages can use the same daemon without a JavaScript module.
-Use `model: "auto"` or omit `model` to use the configured routing policy and
-selected local model. A hardcoded `jev-1.13.0` remains a model pin and cannot
-select an unrelated local model.
-Local calls need no hosted API key; hosted activation stays explicit. A remote
-server's loopback address points to that server. A browser running on the user's
-machine can address local services, so Sys1's network listener rejects browser
-origins and Fetch Metadata site headers, requires a loopback request authority,
-and accepts decision POSTs only as `application/json`.
-Start with an opt-in, non-authoritative pilot. Compare decisions on the
-application's representative fixtures and record backend/adapter identity,
-latency, errors, abstentions, and disagreement with the current decision path.
-Do not reuse Jev probability thresholds for generic GGUF output
-without model-specific evidence. A local-only policy also constrains explicit
-pins; a pin never bypasses the policy. Broad production adoption requires the
-consumer's own quality and operational acceptance, not just wire compatibility.
-## Quickstart: experimental local decisions
+Get a key from [TypeSafe](https://console.typesafe.ai/) and provide it as
+`TYPESAFE_API_KEY` through your shell or secret manager. Then enable Jev:
 ```sh
-sys1 setup      # verifies the native runtime, installs and selects Qwen3 1.7B
-sys1 up         # starts the gateway on 127.0.0.1:13900
-sys1 status
+sys1 jev enable
+sys1 jev status
 ```
-Local Qwen is experimental. Do not treat it as a drop-in replacement for Jev.
-The broader tests found 32/72 correct decisions for Qwen3 1.7B and 44/72 for
-Qwen3.5 4B on a different fresh fixture. [Read the evidence](https://sys1.io/docs/evaluations)
-before using local decisions to drive actions.
+The key stays in the environment. Enabling Jev selects `hosted-only` routing,
+so a failed hosted request cannot silently use a local model. Selected source
+and diff context go to Jev; inspect the preview before sending them. Provider
+usage is billed by TypeSafe at its [published rates](https://docs.typesafe.ai/models).
-`setup` is the explicit weight-download boundary. It installs Qwen3 1.7B and
-persists that choice as `local.model`, regardless of system memory. Inspect
-without changing anything:
+Run the previewed check by removing `--dry-run`:
 ```sh
-sys1 setup --dry-run --json
+sys1 review checkpoint --worktree --model typesafe/jev-1.13.0 \
+  --max-requests 10 --json -- src test
 ```
-`sys1 setup --tier compact` explicitly installs and selects the experimental
-Qwen3 0.6B diagnostic model. It is not an automatic low-memory fallback.
-`sys1 setup --tier quality` returns the selection to Qwen3 1.7B.
-The pinned llama.cpp runtime selects the best available backend automatically:
+No background gateway is needed for this hosted workflow. Investigate each
+candidate and record it as useful, incorrect, or unverifiable. Complete,
+unchanged batches reuse their review for up to 24 hours. The [review guide](docs/review.md)
+covers feedback, rechecks, and rule drafts; [`sys1 audit`](docs/audit.md) runs a
+check without saved review history.
-| Package target | Runtime preference |
-| --- | --- |
-| macOS ARM64 | Metal (the pinned runtime's only automatic selection) |
-| macOS x64 | CPU |
-| Linux x64 | CUDA, Vulkan, then CPU |
-| Linux ARM64 | CPU |
-| Windows x64 | CUDA, Vulkan, then CPU |
-| Windows ARM64 | CPU |
+## Check an agent’s completion message
-Other platform/architecture pairs fail closed before downloading a model. The
-release artifact and package smoke are exercised on Ubuntu, macOS, and Windows.
-This matrix does not prove every OS/architecture pair above; run
-`sys1 doctor` on the actual host before use.
-Send a decision:
+After setting up a backend, install the standalone verification instructions:
 ```sh
-sys1 eval <<'EOF'
-{
-  "state": "Help! My payouts have been failing for 3 days.",
-  "questions": {
-    "urgent": {
-      "type": "noul",
-      "instructions": "Does this need immediate attention?",
-      "criteria": {
-        "true": "A customer-impacting incident is ongoing",
-        "false": "This can wait for normal triage"
-      }
-    }
-  }
-}
-EOF
+sys1 verify setup codex
 ```
-Or point any System One client at `http://127.0.0.1:13900`.
-## Add hosted Jev
-Hosted Jev is disabled by default, even if `TYPESAFE_API_KEY` is already set in
-the environment. Add it explicitly:
+Use `setup claude-code` or `setup devin` for those agents. Ask the agent to save
+its proposed final message outside the Git worktree, then compare the draft
+with available evidence:
 ```sh
-export TYPESAFE_API_KEY=…
-sys1 jev enable
-sys1 jev status
+sys1 verify --message /tmp/final-message.txt \
+  --model typesafe/jev-1.13.0 --dry-run --json
 ```
-`jev enable` requires the credential to be present, stores only
-`hosted.enabled: true`, and sets routing to `hosted-only`. The key remains in the
-environment and is never written to disk or printed. Restart a gateway that was
-started before the key was exported. To return to local-only operation:
-```sh
-sys1 jev disable
-```
+Choose an equivalent external file path on Windows. The preview reports the
+input type and model route without model calls or page fetches. Read the message
+file and inspect its links before rerunning without `--dry-run`; the message and
+any fetched page excerpts go to the selected backend. Use `--message -` for
+piped text and `--url https://example.com` to include a live page the message
+does not link.
-Enabling Jev selects `hosted-only`: a hosted outage or missing credential returns
-an error without substituting Qwen. To experiment with local fallback after
-measuring its quality on your application, explicitly run
-`sys1 config set routing.policy auto`. That policy prefers reachable Jev, then
-the installed model named by `local.model`. Disabling Jev returns a hosted-only
-configuration to `auto` for the selected local model. Installing additional
-models does not change the selection. If no eligible route is available, Sys1
-reports an error instead of silently choosing another installed model.
+Contradictions exit 7; unavailable evidence is marked unverifiable. A clean
+report does not prove completion. File input works with any coding agent;
+check-command evidence requires local Devin transcript discovery. See the
+[verification guide](docs/verify.md) for input modes, evidence, and exit codes.
-## Local models
+## Use as a module
-`sys1 setup` and `sys1 pull` manage model artifacts under
-`~/.sys1/models` (or `$SYS1_HOME/models`). Downloads stream to a temporary
-file, enforce an 8 GiB ceiling, verify SHA-256, run bounded GGUF structural
-validation, and only then atomically enter the model store. Manifest filenames
-cannot escape the store, symbolic-link weights are not admitted, and the daemon
-never downloads weights implicitly.
+For an application using Node 24 or Bun, install the portable client:
 ```sh
-sys1 pull --list
-sys1 pull qwen3-1.7b
-sys1 model list
-sys1 model verify qwen3-1.7b
+npm install --omit=optional \
+  https://github.com/hraness/sys1/releases/download/v0.18.0/hraness-sys1-0.18.0.tgz
 ```
-The curated registry contains three experimental GGUF models:
-| Model | Kind | Download | Role |
-| --- | --- | ---: | --- |
-| `qwen3-1.7b` | `gguf` | 1.03 GiB | default local experiment |
-| `qwen3-0.6b` | `gguf` | 365 MiB | diagnostic model; explicit selection only |
-| `qwen3.5-4b` | `gguf` | 2.55 GiB | larger candidate; explicit selection only |
-All entries are pinned to the publisher's Hugging Face LFS SHA-256. Weight
-licenses and terms remain those of their publishers; weights are not included
-in the Sys1 package.
-`sys1 pull` defaults to Qwen3 1.7B and only installs an artifact; it does not
-change `local.model`. To change the local route, install the model first, then
-select its installed ID with `sys1 config set local.model MODEL`. Other
-installed models require a request-level model pin. This keeps a new download
-from becoming an unintended fallback.
-Older inventories containing removed CUA-S1 or Needle artifacts fail closed.
-Sys1 preserves those files and the manifest; use a new `SYS1_HOME` for the
-current GGUF store.
-### Generic GGUF adapter
-For builtin GGUF models, Sys1 renders a bounded question prompt, evaluates
-the full first-token vocabulary distribution with llama.cpp, and sums
-probability mass over constrained answer labels. Choice and score use unique
-one-character labels to avoid ambiguous multi-token option names. Builtin
-inference supports up to 35 options per question; hosted and external
-backends retain the protocol's 255-option limit. Builtin answers use the
-official Jev wire shapes and disclose `generic-gguf` in the
-`x-sys1-local-adapter` response header:
-- Noul returns only `type` and probability-of-yes `noul`;
-- Choice returns `choice`, keyed `probabilities`, and `confidence`;
-- Score returns a zero-based probability-weighted fractional `score`, keyed
-  `legend`, keyed `probabilities`, and `confidence`.
-Adapter input bounds fail closed: Sys1 never silently truncates state,
-instructions, or criteria. Generic GGUF accepts up to 6,000 state characters,
-2,000 instruction characters, 96 characters per option name/criterion, and
-16,000 characters for the complete rendered prompt. An input beyond the adapter's
-bounds returns an error without being sent to a different backend.
-Adapter quality signals stay outside those answer objects:
-`x-sys1-local-min-coverage` is the least total probability mass assigned to
-allowed labels, and `x-sys1-local-min-concentration` is the least
-distribution concentration in the batch. Low coverage means the model did not
-cleanly follow the decision instruction. These are useful local signals, not
-a calibration guarantee. Use hosted Jev or a task-qualified System One-specific
-backend when its behavior has been evaluated for your task.
-An unlisted public Hugging Face GGUF can be installed explicitly:
+With a backend configured, run `sys1 up` to start the gateway, then call it:
-```sh
-sys1 pull 'hf:owner/repository:path/model.gguf' --sha256 <64-hex-digest>
-```
-## The endpoint
+```ts
+import { createClient } from "@hraness/sys1/client";
-| Route | Purpose |
-| --- | --- |
-| `POST /v1/systemone` | Evaluate `{model?, state, questions}` through the selected backend |
-| `GET /v1/models` | List model ids, backend names, kinds, and reachability |
-| `GET /healthz` | Report daemon liveness and version |
-Responses carry `x-sys1-backend` and `x-sys1-attempts`; builtin responses
-also carry the local adapter and diagnostic headers above. Any HTTP response
-from a remote backend, including 4xx or 5xx, is definitive. Only a transport
-failure may re-dispatch, at most once, and never for a pinned `backend/model`.
-`state`, `instructions`, and criterion descriptions accept text, JSON objects,
-JSON arrays, or `null` where the official Jev contract permits it. The public
-package exports request and response schemas for boundary validation.
-### Request example
-```json
-{
-  "model": "auto",
-  "state": { "tests": "failing", "branch": "main" },
-  "questions": {
-    "action": {
-      "type": "choice",
-      "instructions": "What should the agent do next?",
-      "criteria": {
-        "fix": "Repair the failure before continuing",
-        "continue": "The failure is unrelated and safe to defer",
-        "escalate": "Human judgment is required"
-      }
+const sys1 = createClient(); // http://127.0.0.1:13900
+const { response } = await sys1.evaluate({
+  model: "typesafe/jev-1.13.0",
+  state: "Customers cannot complete checkout after today’s release.",
+  questions: {
+    urgent: {
+      type: "noul",
+      instructions: "Does this describe an active customer-impacting incident?",
     },
-    "risk": {
-      "type": "score",
-      "instructions": "Rate merge risk",
-      "criteria": ["low", "moderate", "high"]
-    }
-  }
-}
-```
-## Routing
-For unpinned requests (`model: "auto"` or omitted), `routing.policy` controls
-the order of enabled hosted Jev and the installed model named by `local.model`:
-| Policy | Order |
-| --- | --- |
-| `auto` (default) | hosted Jev, then the selected local model |
-| `prefer-local` | selected local model, then hosted Jev |
-| `prefer-hosted` | hosted Jev, then the selected local model |
-| `local-only` | selected local model only |
-| `hosted-only` | hosted Jev only |
-Other installed models and all registered HTTP services require an explicit
-request model or backend/model pin. They never receive unpinned fallback
-traffic. A missing selected model does not promote another installed model.
-Registered HTTP services are local only when their URL uses a
-loopback host; off-machine URLs count as hosted. Redirects are never followed.
-`local-only` decisions neither probe nor dispatch to hosted endpoints. Explicit
-model discovery and doctor may probe all configured backends. Backend names must
-be unique; `typesafe` and `local-*` are reserved for managed candidates. Requests can pin either a model id or an exact backend/model:
-- `"model": "jev-1.13.0"` selects a backend serving that hosted model;
-- `"model": "local-qwen3-1.7b/qwen3-1.7b"` pins the builtin Qwen runner;
-- `"model": "local-qwen3-0.6b/qwen3-0.6b"` explicitly selects the experimental model;
-- `"model": "openjev/openjev-latest"` pins a registered HTTP backend that advertises that alias.
-Selection is capability-aware. Sys1 compares each request's largest option
-count and total question count against the backend's published limits. A backend the request exceeds is skipped; when no configured backend
-can serve the request at all the gateway answers `422 request_unsupported`
-rather than dispatching a request that would fail downstream. Builtin
-backends publish their adapter limit (`generic-gguf` 35 options); remote backends
-are probed at `GET /v1/limits` (openjev-style `max_answers_per_question` and
-`max_questions`). A backend that publishes nothing has unknown capacity; Sys1 can enforce only
-its configured limits and the common protocol envelope. Missing limits never
-mean zero capability.
-## External System One backends
-Sys1 can route to an [OpenJev](https://github.com/razorback16/openjev) server
-through its standard System One decision API. OpenJev's image, chat, and
-advanced sampling extensions are not supported. A server you register answers
-only requests that select it; adding one does not change the default route.
-Any service implementing `POST /v1/systemone` and `GET /v1/models` can join the
-same router. For an existing OpenJev server, first inspect its advertised model
-IDs. The example uses OpenJev's documented `openjev-latest` alias; replace it if
-your server advertises a different ID:
-```sh
-curl http://127.0.0.1:8080/v1/models
-sys1 backend add \
-  --name openjev \
-  --url http://127.0.0.1:8080 \
-  --model openjev-latest
-```
-Before routing agents to an operator backend, qualify its discovery, limits,
-and all three answer shapes:
+  },
+}, { signal: AbortSignal.timeout(5_000) });
-```sh
-sys1 backend check --name openjev
+console.log(response.answers.urgent);
 ```
-Select it in a request with `"model": "openjev/openjev-latest"`. Registration
-and qualification do not add an HTTP service to automatic routing.
+The answer contains the model’s probability of yes. Sys1 validates requests and
+responses, supports cancellation, and returns stable error codes. Your
+application decides which actions are allowed and evaluates the model on its
+own examples. A valid answer can still be wrong.
-The check makes bounded calls to `/v1/models`, `/v1/limits`, and
-`/v1/systemone`; validates the official response schema, probability
-normalization, and Score arithmetic; and never prints or persists request or
-response bodies. Backends that do not publish limits receive a warning unless
-static caps were configured. All configured HTTP processes remain
-operator-owned: Sys1 probes and forwards to them but does not download their
-weights, mutate credentials, or own their lifecycle.
+The [client and embedded router guide](docs/runtime.md#use-as-a-module) covers
+custom endpoints, the in-process Bun router, and existing Jev applications.
-## Kev and decision profiles
+## The endpoint
-[Kev](https://github.com/jaredpalmer/kev) servers use a dedicated adapter
-(`--adapter kev`) that handles Kev's two-decimal probability output and
-structured Score legends. Versioned decision profiles reuse task instructions
-with Jev, local models, or a separately trained Kev checkpoint.
-[Kev and tuning guide](docs/kev.md).
+The loopback gateway serves `POST /v1/systemone` for decisions,
+`GET /v1/models` for discovery, and `GET /healthz` for liveness.
+[HTTP request and response reference](docs/runtime.md#the-endpoint).
-After starting and verifying a separately owned Kev server, register it explicitly:
+## Local models
-```sh
-sys1 backend add --adapter kev --name kev \
-  --url http://127.0.0.1:8009 --model kev-latest
-sys1 backend check --name kev
-```
+Local Qwen models are experimental. In the broader recorded studies, Qwen3
+1.7B answered 32/72 cases correctly; Qwen3.5 4B answered 44/72 on a different
+fresh fixture. Evaluate the selected model on your task before relying on it.
+[Model studies](https://sys1.io/docs/evaluations).
-Kev remains outside automatic routing. A versioned profile pins the route and
-reuses the same instructions and criteria while each call supplies new state:
+Preview the download with `sys1 setup --dry-run --json`. The [local setup guide](docs/runtime.md#experimental-local-decisions)
+covers supported platforms, downloads, and model selection. Setup explicitly
+downloads and selects Qwen3 1.7B; other installed models are never automatic
+substitutes.
-```ts
-import { createClient, createProfile } from "@hraness/sys1/client";
+## External System One backends
-const triage = createProfile({
-  version: 1, id: "ticket-triage", revision: "1", model: "kev/kev-latest",
-  questions: {
-    urgent: { type: "noul", instructions: "Does the ticket describe an active outage?" },
-  },
-});
-const result = await createClient().evaluate(triage.request("Checkout is unavailable."));
-```
+Connect a server that implements the System One API, including OpenJev or Kev.
+Register and check the server, then select it in each request. Adding a server
+does not change default routing. [Compatible server setup](docs/runtime.md#external-system-one-backends)
+· [Kev and decision profiles](docs/kev.md).
-Profiles work with the Node/Bun client and embedded router. Definitions are
-validated and frozen; each request is a fresh ordinary System One request.
-Only model, state, and questions cross the wire. No templating, hidden prompt
-injection, global profile registry, or automatic training is involved. Save
-the definition as JSON for `sys1 eval --profile triage.json`, which accepts
-only `{"state": ...}` on stdin or `--file`.
-[Start from the ticket-triage profile](examples/ticket-triage.profile.json).
-For a direct Kev endpoint, use `createClient({ baseUrl: "http://127.0.0.1:8009",
-adapter: "kev" })` with an ordinary request containing `model: "kev-latest"`.
-When calling the Sys1 gateway, leave the client adapter unset. Routing metadata
-identifies Kev and its two-decimal precision; probabilities are not renormalized.
-The backend/model pin identifies a route, not its weights. Kev always advertises
-`kev-latest`; verify the server's actual checkpoint separately. The
-[setup and tuning guide](docs/kev.md) covers pinned checkpoints, prompt revisions,
-fine-tuning, calibration, and held-out evaluation. Model downloads and training
-remain explicit Kev operations. Protocol tests do not establish model quality.
-## Diagnostics
-`sys1 doctor` checks the install and prints one line per check (✓, ⚠ or ✗),
-a count, and the command to run next. It verifies the
-Bun floor, state-directory access, config, native llama.cpp runtime/backend,
-the installed-model list, every installed model's GGUF header, leftover or
-unknown files in the model folder, routing candidates, and daemon ownership. It does not hash entire model
-files; use `sys1 model verify MODEL` for exact SHA-256 verification.
+## Reference and troubleshooting
-```sh
-sys1 doctor
-sys1 doctor --json
-```
+<a id="diagnostics"></a>
+<a id="routing"></a>
+<a id="configuration"></a>
+<a id="commands"></a>
+<a id="kev-and-decision-profiles"></a>
-Warnings do not fail readiness. Failed checks return exit code 6. JSON is
-versioned (`version: 1`) and check identifiers are stable and additive.
-## Commands
-```text
-sys1 setup [--tier compact|quality] [--dry-run]
-sys1 jev status|enable|disable
-sys1 up|down|serve|status|doctor
-sys1 pull [MODEL]|pull --list
-sys1 model list|verify|remove
-sys1 models
-sys1 eval
-sys1 audit --staged|--worktree|--since <ref> --model <backend/model>
-sys1 review checkpoint|issues|feedback|recheck|setup
-sys1 rules list|check|draft
-sys1 verify setup codex|claude-code|devin
-sys1 verify --model <backend/model> [--message <file|->]
-sys1 usage [--days <n>]
-sys1 backend list|add|check|remove
-sys1 config path|get|set|unset
-sys1 --version|--help
-```
+- [`sys1 doctor` and diagnostics](docs/runtime.md#diagnostics): inspect the runtime, routing, model store, and gateway after setup.
+- [Routing](docs/runtime.md#routing): select a model and control fallback.
+- [Configuration](docs/runtime.md#configuration): settings, credentials, and gateway access.
+- [Commands](docs/runtime.md#commands): CLI reference and JSON output.
+- [Decision profiles](docs/runtime.md#kev-and-decision-profiles): reuse questions across application requests.
+- [Model comparison](https://sys1.io/compare) and [evaluation reports](https://sys1.io/docs/evaluations): inspect model-specific evidence.
-Supporting commands accept `--json`. When an agent runs sys1 (Claude Code,
-Codex, Cursor, Gemini CLI, or `AI_AGENT` is set), JSON is the default;
-`HRANESS_AUDIENCE=human` or `agent` overrides the guess. Machine data goes to
-stdout; diagnostics, next-step hints and download progress go to stderr. Every
-command has its own help (`sys1 setup --help`). Errors are one sentence and the
-command to run next; with `--json` they are one `{"ok":false,"error":{...}}`
-object on stdout. `sys1 setup --dry-run` shows the model, its size and the
-folder it would be downloaded to.
-## Configuration
-`~/.sys1/config.json` is created on the first write. `SYS1_HOME` overrides
-the state directory. Settable keys:
-- `routing.policy`;
-- `gateway.host` (loopback addresses only), `gateway.port`,
-  `gateway.request_timeout_ms`, `gateway.probe_timeout_ms`;
-- `hosted.base_url`, `hosted.model`, `hosted.api_key_env` (activation uses
-  `sys1 jev`);
-- `local.enabled`, `local.model`, `local.context_tokens`, `local.eval_timeout_ms`,
-  `local.max_loaded_models`.
-Fresh config uses `routing.policy: auto`, `local.enabled: true`,
-`local.model: qwen3-1.7b`, `hosted.model: jev-1.13.0`, and
-`hosted.enabled: false`. The daemon reads config per request, so routing and
-backend changes do not need a restart. Restart after changing local runtime
-context, timeout, or residency settings. Environment variables are inherited when
-the daemon starts, so restart it after exporting a new Jev credential. Already
-loaded GGUFs stay resident up to `local.max_loaded_models` (default one) and are
-released on eviction or daemon shutdown. Local requests are serialized
-to keep context state isolated and residency bounded. GGUF inference lives in
-an owned worker process; abort, timeout, or disposal terminates and collects
-that worker before the next request can reuse the engine slot.
-The decision endpoint accepts loopback binds only and has no application
-authentication. Network admission blocks browser-originated decision dispatch and
-non-loopback Host authorities, but it does not authenticate local processes.
-Any process that can connect locally can dispatch decisions using the gateway's
-enabled backends and credentials; use it only on a trusted local machine.
-The in-process `createRouter`/`createFetchHandler` surface leaves admission to
-its owning application. Daemon shutdown uses a per-instance
-secret from its private pid file and an authenticated control endpoint. Sys1
-never signals an arbitrary PID read from that file.
+If `sys1` is missing after installation, check that npm’s global binary
+directory is on your `PATH` and that `bun --version` works. If a request cannot
+find a model, inspect `sys1 jev status` and `sys1 doctor`. Restart an existing
+gateway after changing its credential environment.
 ## Releases
 An annotated `v<version>` tag at the exact current `main` head requests a
-release. The tag must match `package.json`. The release workflow reruns the
-complete gate, creates one npm-format tarball and `SHA256SUMS`, installs and
-executes those exact bytes with the native dependency and `doctor` on Ubuntu,
-macOS, and Windows, then publishes them to a repository-enforced immutable
-GitHub Release. No npm registry package is claimed or required.
-Each release page copies its summary and changes from the version's section of
-[`CHANGELOG.md`](CHANGELOG.md) and adds the install command, the tarball's
-SHA-256, and the source commit. The workflow stops before publishing when that
-section is missing, and it fails when a published page no longer matches the
-changelog and the attached files.
+release and must match `package.json`. The release workflow reruns the complete
+gate, creates one npm-format tarball and `SHA256SUMS`, and installs those exact
+bytes with the native dependency on Ubuntu, macOS, and Windows before
+publishing an immutable GitHub Release. Release notes come from
+[CHANGELOG.md](CHANGELOG.md). The optional npm mirror publishes that same
+tarball after the package’s one-time registry setup.
 ## Development
 ```sh
+git clone https://github.com/hraness/sys1.git
+cd sys1
 bun install
 bun run check
 ```
-The check runs strict TypeScript, deterministic tests with fake inference,
-distribution builds, and an isolated packed-artifact import/CLI smoke test.
-CI then runs `bun run check:native` on Linux, macOS and Windows: it installs
-the packed candidate in a disposable prefix and checks real native runtime
-readiness before a release tag is needed. This does not rebuild the package
-or download model weights. Model inference and hosted calls remain excluded
-from ordinary CI; the release workflow still verifies its exact uploaded
-artifact on all three platforms.
-## Comparing models
-Use [the model comparison](https://sys1.io/compare) for external JevBench
-accuracy on the hosted Jev and operator-registered OpenJev routes, route
-availability, and a workload cost calculator. It uses the pinned
-[JevBench v1.2.6 snapshot](https://github.com/fstandhartinger/jevbench/tree/v1.2.6);
-its methodology and limits are recorded in the [evidence appendix](docs/model-comparison.md).
-Built-in Qwen has no matching JevBench result: SemIf's Qwen3.5 4B uses a
-different adapter and BF16 checkpoint, so its score does not apply to Sys1's
-GGUF path. An external OpenJev GPU score likewise does not establish Mac MLX
-quality or qualify a Sys1 deployment.
-[Sys1's original evaluation studies](https://sys1.io/docs/evaluations) remain
-available with raw reports, failure analysis, and token-accounting details.
-The [opt-in Sys1 benchmarks](benchmarks/README.md) support adapter qualification
-and reproduction; they are not the cross-model leaderboard. No local candidate
-is generally qualified, and the original fixtures do not justify an automatic
-application migration.
-## Related
-[System One Skills](https://github.com/hraness/system-one-skills) is a separate
-skill for Devin, Claude Code, and Codex. It runs a known noisy test or build
-once, returns a short result with the exit status, and keeps the full log on
-disk. It needs no model, API key, or Sys1 installation, and installing either
-project does not configure the other. [Skills guide](https://sys1.io/skills).
-[The thread through hraness](https://hraness.com/writing/the-thread-through-hraness)
-describes the design Sys1 shares with every Hraness project: a decision has a
-declared shape before a model is asked, and the answer comes back validated
-instead of as prose.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development and release workflow.
+Report a bug in [GitHub Issues](https://github.com/hraness/sys1/issues), or follow
+[SECURITY.md](SECURITY.md) for a security report.