diff --git a/CITATION.cff b/CITATION.cff
index 698d6620..cbc44446 100644
--- 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
index 90b95a75..ebc7cf96 100644
--- 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
index 1a6b3c50..33cf91ea 100644
--- 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
index 208579bf..e37365aa 100644
--- 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.
-
zinc at a shell prompt, with the drivers listed and curl fetching a page.
+
The zinc shell, driver processes and a curl request.
Chrome browsing Wikipedia on Ferrix.
-
btop showing the browser, compositor and drivers.
+
btop showing what's running.
@@ -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
index 9dd9153f..4cb5b1ee 100644
--- 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
index a248fe82..71e15dbc 100644
--- 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,13 +43,12 @@ 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:
@@ -54,12 +56,11 @@ 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
index 188c487c..f3953a56 100644
--- 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
new file mode 100644
index 00000000..724b2977
--- /dev/null
+++ 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
new file mode 100644
index 00000000..05f2beb7
--- /dev/null
+++ b/marketing/logo.svg
@@ -0,0 +1,17 @@
+
diff --git a/scripts/marketing/github-setup.sh b/scripts/marketing/github-setup.sh
index 06ab1047..fbc992d5 100755
--- 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
index e3a598be..d57a4aac 100644
--- a/website/404.html
+++ b/website/404.html
@@ -7,5 +7,5 @@
kernel panic: page not found
EFAULT: bad address
This page isn't mapped.
-
No mapping here is writable, executable or present. Back to Ferrix →
+
The link may have moved, or the URL may be wrong. Back to Ferrix →
