From ed2464d5e286ef2692e5614e304d6e73201f6476 Mon Sep 17 00:00:00 2001 From: Mac Anderson Date: Sat, 12 Sep 2026 02:40:04 -0700 Subject: [PATCH 1/2] docs(readme): fix the broken logo and state where Stella sits next to Oxagen The README header pointed at docs/brand/logo/svg/lockup-color-light.svg, which #6473 (the house-system adoption) deleted along with the rest of the comet kit, so GitHub rendered a broken image above the badges. It now uses the vendored stella-wordmark-{dark,light}.svg pair behind prefers-color-scheme sources, with the light file as the fallback. The copy is brought onto the same position the site and the Oxagen repo already state: - The tagline is the site's h1 ("a terminal coding agent that proves its work finished") in place of "Reference Grade Agent Loop". - A short "Stella and Oxagen" section states the split from ADR-043 and ADR-053 on the Oxagen side: Stella runs the agent, Oxagen governs the run; Stella is the coding agent and the CGP/trace reference implementation, Oxagen is the governance plane with no agent loop; the two meet at the opt-in evidence drain and at stella-serve, which Oxagen's in-app assistant runs on. It also names the shared house brand and the stella* mark. - The workspace-layout paragraph that called crates/stella-tui/src/palette.rs the hand-maintained palette mirrored by tokens.css is replaced with what is true since v5.0 and #6473: design/tokens/stella-tokens.json is normative, gen-tokens.py emits the terminal tokens and the CSS, and sync-brand-assets.mjs vendors the marks from the house kit. Verified: check-doc-links, check-invariants, check-command-docs, check-brand-case, check-line-citations, check-rendering-facts and make tokens all pass; every relative link and image path in the README resolves. --- README.md | 47 +++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 39 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 292cdf531..e7656794a 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,13 @@

- - stella + + + stella*

-

Reference Grade Agent Loop

-

Open Source · Rust · BYOK · No Phone Home

+

A terminal coding agent that proves its work finished.

+

Open source · Rust · BYOK · Nothing leaves your machine

CI status @@ -30,6 +31,31 @@ provider you configured — the two paths that would export anything else (Oxagen Enterprise enrollment, or a `drain` block in `~/.stella/cloud.json`) exist in no default install. Written in Rust as a workspace of focused crates. +### Stella and Oxagen + +**Stella runs the agent. [Oxagen](https://oxagen.sh) governs the run.** They +are two products from one company, and the split between them is deliberate: + +- **Stella is the coding agent.** It plans, runs tools, verifies, and + records what it did. It is also the reference implementation of the + [Context Graph Protocol](https://github.com/macanderson/context-graph-protocol) + and of the run/turn/step trace vocabulary Oxagen reads. +- **Oxagen is the governance plane.** It grounds, governs, explains, meters, + and rates agents. It runs no agent loop of its own, so nothing in this + repository is duplicated there and nothing there runs a sandbox, a file + system, or a subagent. Those stay on your machine, in this CLI. +- **They meet at two seams, both opt in.** Evidence flows *out* only when you + configure a `cloud.json` drain or an Enterprise enrollment (see + [Telemetry](#telemetry)); Oxagen grades and rates that record and never + re-runs it. Oxagen's own in-app assistant flows the *other* way: it is a + turn on [`stella-serve`](crates/stella-serve/README.md), the headless + engine, which holds no key and runs no tool, so every completion and tool + call comes back to Oxagen's gates. + +Both products share the [Oxagen house brand system](https://github.com/macanderson/oxagen-house-brand): +one typeface, one gold, and one glyph in that gold per wordmark. Stella's mark +is the asterisk in `stella*`, and nothing is ever set to its left. + ## Features - **BYOK, auto-detected** — set one provider's API key and Stella finds it. @@ -641,10 +667,15 @@ Alongside the Rust workspace, the documentation site ([stella.oxagen.sh](https://stella.oxagen.sh)) lives at `website/` (Next.js + Fumadocs) as a **self-contained** package: its own `package.json`, `pnpm-lock.yaml`, and pnpm settings all sit in that directory, and the repo -root is pure cargo. The two toolchains share no code — the one thing crossing -between them is the brand palette: `crates/stella-tui/src/palette.rs` is the -hand-maintained normative source, mirrored by `website/src/app/tokens.css` -(`--stella-*`), and the two must be edited together. +root is pure cargo. The two toolchains share no code. The one thing crossing +between them is the brand: `design/tokens/stella-tokens.json` is the normative +palette, and it adopts the Oxagen house table. `scripts/gen-tokens.py` emits +the terminal tokens (`stella-tui-theme`) and `design/tokens/stella-tokens.css` +from it, which the site's `tokens.css` carries verbatim under a checker +(`make tokens-update` regenerates, `make tokens` checks), and +`scripts/sync-brand-assets.mjs` vendors the marks, icons, and spinner from the +house kit into `docs/brand/` (`--check` runs in CI). Edit the JSON or rebuild +the kit; never the generated files. ## Development From d06e7bc06584f3450bfc1af94906657060870288 Mon Sep 17 00:00:00 2001 From: Mac Anderson Date: Sat, 12 Sep 2026 03:07:04 -0700 Subject: [PATCH 2/2] docs(readme): say why the split exists, and name stella-serve's wire protocol check-prose rejected two words the new section added: 'deliberate' (filler-adverb -- state the reason or say nothing) and 'headless' (interface-jargon). The split sentence now states the consequence, that neither product duplicates the other, and stella-serve is described as driving the engine over a wire protocol, which is what the crate's own README row already says. --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index e7656794a..05e22434d 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ exist in no default install. Written in Rust as a workspace of focused crates. ### Stella and Oxagen **Stella runs the agent. [Oxagen](https://oxagen.sh) governs the run.** They -are two products from one company, and the split between them is deliberate: +are two products from one company, and neither duplicates the other: - **Stella is the coding agent.** It plans, runs tools, verifies, and records what it did. It is also the reference implementation of the @@ -48,9 +48,9 @@ are two products from one company, and the split between them is deliberate: configure a `cloud.json` drain or an Enterprise enrollment (see [Telemetry](#telemetry)); Oxagen grades and rates that record and never re-runs it. Oxagen's own in-app assistant flows the *other* way: it is a - turn on [`stella-serve`](crates/stella-serve/README.md), the headless - engine, which holds no key and runs no tool, so every completion and tool - call comes back to Oxagen's gates. + turn on [`stella-serve`](crates/stella-serve/README.md), which drives the + engine over a wire protocol and holds no key and runs no tool itself, so + every completion and tool call comes back to Oxagen's gates. Both products share the [Oxagen house brand system](https://github.com/macanderson/oxagen-house-brand): one typeface, one gold, and one glyph in that gold per wordmark. Stella's mark