SetZero · SetZero · Sep 27, 2026 · Sep 27, 2026 · Sep 27, 2026 · Sep 27, 2026
diff --git a/CITATION.cff b/CITATION.cff
@@ -1,10 +1,10 @@
 cff-version: 1.2.0
-message: If you refer to Ferrix in a paper or a talk, please cite it as below.
-title: "Ferrix: a Rust operating system that runs rustc and builds itself"
+message: If you use Ferrix in your research, please cite this repository.
+title: "Ferrix: an experimental Rust operating system"
 type: software
 authors:
   - name: Sebastian Dauenhauer
 repository-code: https://github.com/SetZero/ferrix
 url: https://setzero.github.io/ferrix/
 license: MIT
-keywords: [operating system, Rust, kernel, Linux ABI, btrfs, Wayland, AI agents]
+keywords: [operating system, Rust, Linux ABI, userland drivers, btrfs, Wayland]
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,7 +1,7 @@
 # Contributing to Ferrix
 
-Thank you for looking. The most useful thing you can do is boot Ferrix, run
-something on it, and tell us what broke.
+Boot Ferrix, try something, and tell us where it breaks. A clear report is as
+useful as a patch.
 
 ## Report what you find
 
@@ -28,6 +28,6 @@ something on it, and tell us what broke.
 
 ## How Ferrix is made
 
-Most of Ferrix is written by a fleet of AI agents (Claude sessions) under a
-human product owner, who decides scope and priorities. Contributions from
-people go through the same gates, and are reviewed like anything else.
+Most code is written in Claude sessions. The project owner chooses what to
+build and reviews the results. Contributions from other people go through the
+same checks.
diff --git a/GUIDE.md b/GUIDE.md
@@ -20,11 +20,10 @@ rustc 1.97.1 (8bab26f4f 2026-07-14)
 rustc-gate: hello from rustc on Ferrix
 ```
 
-And since 2026-09-23 it builds itself. `cargo xtask test-selfhost` gives
-Ferrix that toolchain with Cargo added, this tree and its vendored crates on
-one btrfs volume, runs `cargo xtask build --arch x86_64` inside it -- the
-command you run on a Linux host -- then takes the image Ferrix made off the
-volume and boots it:
+Since 2026-09-23 it has also built and booted its own x86-64 image.
+`cargo xtask test-selfhost` puts Cargo, this tree and its vendored crates on a
+btrfs volume. Ferrix runs `cargo xtask build --arch x86_64` inside the guest.
+The test then takes the image Ferrix made from the volume and boots it:
 
 ```
    93.49 |   image /data/src/build/x86_64/ferrix.img (63 KiB loader, 75510 KiB kernel, 10666 KiB initramfs)
@@ -33,17 +32,15 @@ volume and boots it:
 
 ## How it is built
 
-Ferrix is written by a fleet of AI agents: many Claude sessions working at
-once, each in its own git worktree. A human product owner decides scope and
-priorities. A coordinator session orders the landings on `main`, and a
-certification consultant reviews every change to the kernel core. The first
-public commit is dated 2026-09-11. `rustc` ran on Ferrix on 2026-09-22, and
-Ferrix built its own image the day after.
-
-Nothing about the process is hidden. A change lands only when its gate
-passes, and every change to what the image holds boots the whole system on
-all three architectures before it lands. The rules the fleet works by,
-and the incidents behind each one, are in [docs/CONVENTIONS.md](docs/CONVENTIONS.md).
+Claude sessions write most of the code, each in a separate git worktree. The
+project owner sets priorities, a coordinator handles merges into `main`, and
+a certification consultant reviews changes to the kernel core. The first
+public commit was on 2026-09-11. `rustc` ran on Ferrix on 2026-09-22; Ferrix
+built and booted its first x86-64 image the next day.
+
+Changes land after their tests pass. Changes to the boot image also run the
+boot test on all three architectures. The working rules, including the
+mistakes behind them, are in [docs/CONVENTIONS.md](docs/CONVENTIONS.md).
 The [roadmap](docs/roadmap/README.md) and [backlog](docs/BACKLOG.md) show
 what each session owns and what is left.
 
@@ -105,17 +102,15 @@ ARMv7-A — so firmware calls a Rust `efi_main` with a stack set up and the MMU
 on. There is no bootstrap assembly on any of them, which is unusual and is a
 direct consequence of choosing UEFI over Multiboot or a bare kernel boot.
 
-The assembly that does exist — 437 lines against some 211,000 of Rust,
-**99.79% Rust** — is confined to constructs the machine defines before a Rust
-function could run: installing a translation regime and jumping to an address
-that did not exist a moment earlier, trap and system-call entry, the context
-switch, and the CPU primitives with no Rust spelling. `docs/ASSEMBLY.md` is
+The assembly that does exist is confined to constructs the machine defines
+before a Rust function could run: installing a translation regime and jumping
+to an address that did not exist a moment earlier, trap and system-call entry,
+the context switch, and CPU primitives with no Rust spelling. `docs/ASSEMBLY.md` is
 the argument for each one; `scripts/check/check-asm-budget.py` fails the build on
 any site that is not on the list, on a file over its budget, and on an entry
 that has gone stale.
 
-That number is a trend, not a gate. Assembly here is a fixed cost that does not
-grow with the system, so the percentage rises as the OS is written.
+The allow-list and line counts live in `scripts/check/check-asm-budget.py`.
 
 ## Getting started
 

diff --git a/README.md b/README.md
@@ -9,13 +9,13 @@
 
 **Linux apps without Linux.**
 
-Ferrix is an experimental operating system with its own Rust kernel. It runs
-several unmodified Linux programs, including Chrome, `git`, `curl` and `rustc`.
-The disk, network, graphics and input drivers live in separate processes, so
-Ferrix can restart a driver that crashes.
+Boot Ferrix in QEMU and you can open its Wayland desktop, browse with Chrome,
+or run `git`, `curl` and `rustc`. Those are ordinary Linux binaries running on
+Ferrix's own Rust kernel. Disk, network, graphics and input drivers run as
+separate processes that Ferrix can restart if they crash.
 
-It has a desktop you can boot today. It is still a research project, with
-important pieces such as authentication and process isolation unfinished.
+Ferrix is still experimental. Authentication and parts of process isolation
+are unfinished, so it is not ready to be your everyday OS.
 
 [Boot Ferrix](#boot-ferrix) · [See what works](#what-works) ·
 [Read the technical guide](GUIDE.md) · [Visit the website](https://setzero.github.io/ferrix/)
@@ -29,9 +29,9 @@ important pieces such as authentication and process isolation unfinished.
     <td width="33%"><img src="docs/brand/screenshots/btop.png" alt="btop showing Chrome, the compositor and driver processes"></td>
   </tr>
   <tr>
-    <td>zinc at a shell prompt, with the drivers listed and <code>curl</code> fetching a page.</td>
+    <td>The zinc shell, driver processes and a <code>curl</code> request.</td>
     <td>Chrome browsing Wikipedia on Ferrix.</td>
-    <td><code>btop</code> showing the browser, compositor and drivers.</td>
+    <td><code>btop</code> showing what's running.</td>
   </tr>
 </table>
 
@@ -92,4 +92,5 @@ and what changed afterward. Human contributions are welcome; see
 [CONTRIBUTING.md](CONTRIBUTING.md).
 
 Ferrix is MIT licensed. [Explore the code and component docs](GUIDE.md#layout),
-[follow releases](docs/RELEASES.md), or [open an issue](https://github.com/SetZero/ferrix/issues).
+[get the logo and press kit](marketing/README.md), or
+[open an issue](https://github.com/SetZero/ferrix/issues).
diff --git a/docs/RELEASES.md b/docs/RELEASES.md
@@ -1,14 +1,13 @@
 # Ferrix — releases
 
-Each testable milestone on `main` is an annotated tag, verified by the product
-owner before tagging as `docs/BACKLOG.md`'s *Milestones* rule says. The notes
-here are the tag's, kept short: what a person can try, and what is known not
-to work yet. Newest first.
-
-Pushing a tag publishes its section here, verbatim, as a GitHub Release
-(`.github/workflows/release.yml`); a tag with no section fails there. The
-release cadence, naming and the shape of the notes are in
-[docs/marketing/PLAYBOOK.md](marketing/PLAYBOOK.md) §3.
+These are snapshots of older Ferrix milestones, newest first. Each one records
+what worked and what was still missing at the time. For the current state,
+read [the roadmap](roadmap/where-it-stands.md).
+
+Milestone tags are annotated and checked by the project owner before they are
+published. The release workflow uses the matching section from this file as
+its notes. See the [discovery plan](marketing/PLAYBOOK.md#what-to-do-next-in-order)
+for how future releases should be presented.
 
 ## stage-11.1-network-display-and-threads — 2026-09-16, features at a89aeb25
 

diff --git a/docs/brand/BRAND.md b/docs/brand/BRAND.md
@@ -1,5 +1,8 @@
 # Ferrix brand
 
+The shareable logo, colours and reusable copy are collected in the
+[press and brand kit](../../marketing/README.md).
+
 ## The mark
 
 `logo-mark.svg` is a cube of iron's crystal lattice (body-centred cubic,
@@ -40,26 +43,24 @@ JetBrains Mono on the web for code and terminal output.
 
 ## Voice
 
-- **Claims come with their proof.** Every headline names the gate that checks
-  it, or quotes that gate's log. Write "runs `rustc`", not "supports Rust
-  development".
-- **Describe how it is built plainly.** Keep the AI-agent process in the
-  project story and documentation, after explaining what Ferrix does.
-- **Numbers, not adjectives.** Write "850k lines of Rust, none vendored" rather
-  than "massive", and "11 days" rather than "incredibly fast".
+- **Claims come with their proof.** Put a screenshot, command or test close to
+  each technical claim. Write "runs `rustc`", not "supports Rust development".
+- **Describe how it is built plainly.** Explain the Claude sessions in the
+  project story, after explaining what Ferrix does.
+- **Show the evidence.** Name a working program, a test or a screenshot instead
+  of using adjectives such as "massive" or "incredible".
 - **Honest about limits.** It is not a daily driver. Say so before someone asks.
 
 Website hero:
 
 * Eyebrow: *Ferrix · an experimental Rust OS*
 * Headline: *Linux apps without Linux.*
 
-The README banner uses the same headline. The first paragraph explains it: tested Linux programs run unchanged
-on Ferrix's own Rust kernel. Disk, network, graphics and input drivers are
-separate processes that can restart after a crash. Name working programs as
-evidence; explain the human project owner's role in the "Who wrote it"
-section. Do not imply that every Linux program works or that Ferrix is ready
-for daily use.
+The README banner uses the same headline. Explain it nearby: tested Linux
+programs run unchanged on Ferrix's own Rust kernel. Name working programs as
+evidence, and say that drivers run in separate, restartable processes. Keep
+the project's working process in its own section. Never imply that every
+Linux program works or that Ferrix is ready for daily use.
 
 Avoid "self-hosting" on its own: stage 20 (full self-hosting) is still in
 progress. "Builds its own image" is what the gate proves.
diff --git a/docs/marketing/PLAYBOOK.md b/docs/marketing/PLAYBOOK.md
@@ -3,6 +3,9 @@
 Updated 2026-09-27. Ferrix is experimental software. Lead with what a visitor
 can see and try, then explain how it was built.
 
+The reusable logo, colours and short descriptions are in the
+[press and brand kit](../../marketing/README.md).
+
 ## The story
 
 **Hook:** Linux apps without Linux.

diff --git a/marketing/README.md b/marketing/README.md
@@ -0,0 +1,66 @@
+# Ferrix press and brand kit
+
+Ferrix is an experimental Rust operating system. Its own kernel runs tested
+Linux programs without changing the binaries, while disk, network, graphics
+and input drivers run as restartable processes.
+
+## Copy you can use
+
+**Short:** Ferrix runs Linux apps without Linux. It has its own Rust kernel and
+drivers that run outside the kernel.
+
+**Longer:** Ferrix is an experimental operating system written in Rust. You can
+boot its Wayland desktop in QEMU and run unmodified Linux programs such as
+Chrome, `git`, `curl` and `rustc`. Its disk, network, graphics and input
+drivers run as separate processes that can restart after a crash. Ferrix is a
+research project; authentication and parts of process isolation are still in
+progress.
+
+The [README](../README.md) has boot commands. The [technical guide](../GUIDE.md)
+shows how to reproduce the compiler and image-build tests. Check the
+[roadmap](../docs/roadmap/where-it-stands.md) before describing work in
+progress as finished.
+
+## Logo and images
+
+- [Logo mark (SVG)](logo.svg): the vector mark on a transparent background.
+- [Dark banner](../docs/brand/banner-dark.png) and [light banner](../docs/brand/banner-light.png): README headers.
+- [Social preview](../docs/brand/social-preview.png): a wide image for shared links.
+- [Screenshots](../docs/brand/screenshots/CAPTIONS.md): real captures, with notes on how they were made.
+- [Favicon](../docs/brand/favicon.svg): the mark on a dark tile, for small icons.
+
+Use the SVG mark with the word “Ferrix” set beside it. Keep its proportions,
+leave some space around it, and use it on a background where the grey outline
+remains visible. The mark is the existing Ferrix logo; it is not a substitute
+for the project's name in running text. The source asset also lives at
+[`docs/brand/logo-mark.svg`](../docs/brand/logo-mark.svg); the two SVG files
+should remain identical.
+
+## Visual identity
+
+| | Dark | Light | Use |
+|---|---|---|---|
+| Background | `#0d0f12` | `#f7f5f2` | Page background |
+| Surface | `#161a20` | `#ffffff` | Panels and cards |
+| Text | `#eef1f5` | `#16181c` | Main copy |
+| Muted text | `#9aa4b2` | `#5b6470` | Captions |
+| Rust orange | `#ff7a2b` | `#c64a06` | Links and highlights |
+
+Use Inter for display and body text. Use JetBrains Mono for code on the web;
+the generated banners use Liberation Mono. The fonts bundled in
+[`assets/fonts`](../assets/fonts) are the ones used for repository artwork.
+The [brand notes](../docs/brand/BRAND.md) cover the image sources and other
+colour tokens.
+
+## Voice
+
+Write as if you are showing someone the system at your desk. Say what runs,
+how to try it and what still fails. Give a command, screenshot or source link
+for a technical claim. Avoid grand claims about changing computing or
+“redefining” operating systems. “Linux apps without Linux” is a short hook,
+not a promise that every Linux program works. Mention the Claude-led build
+process when explaining the project, after explaining what Ferrix does.
+
+For a press mention, link to the [website](https://setzero.github.io/ferrix/)
+and [source repository](https://github.com/SetZero/ferrix). Ferrix is MIT
+licensed; see [LICENSE](../LICENSE) for the terms.
diff --git a/marketing/logo.svg b/marketing/logo.svg
diff --git a/scripts/marketing/github-setup.sh b/scripts/marketing/github-setup.sh
@@ -13,7 +13,7 @@ repo=SetZero/ferrix
 
 # Keep the public description short enough to read in repository search.
 gh repo edit "$repo" \
-  --description "Experimental Rust operating system running unmodified Linux apps on its own kernel, with restartable userland drivers and a Wayland desktop." \
+  --description "Linux apps without Linux. Ferrix is an experimental Rust OS with a Wayland desktop and drivers outside the kernel." \
   --homepage "https://setzero.github.io/ferrix/" \
   --enable-discussions \
   --enable-issues \

diff --git a/website/404.html b/website/404.html
@@ -7,5 +7,5 @@
 <pre class="term">kernel panic: page not found
   EFAULT: bad address</pre>
 <h2 style="margin-top:32px">This page isn't mapped.</h2>
-<p class="sub">No mapping here is writable, executable or present. <a href="/ferrix/">Back to Ferrix &rarr;</a></p>
+<p class="sub">The link may have moved, or the URL may be wrong. <a href="/ferrix/">Back to Ferrix &rarr;</a></p>
 </div></main></body></html>