# The Alloy Manual

Alloy is an opinionated tiling user layer for Fedora Silverblue: an immutable
base, the sway compositor, a curated terminal-first stack, and one authored
control surface, the `alloy` console.

This manual is for people who run Alloy. It says what the system does, which
keys do it, and what to do when something does not work. The design documents
one directory up (`docs/MANIFESTO.md`, `docs/STACK.md`, `docs/CONSOLE.md` and
the rest) explain why each pick was made; they are written for whoever works on
Alloy, not for whoever uses it. Nothing here replaces them.

Alloy is pre-v0. Where a thing is not built yet, this manual says so instead of
describing it in the future tense.

## Chapters

1. [What Alloy is](01-what-alloy-is.md)
2. [Building your image](02-building-your-image.md)
3. [Installing](03-installing.md)
4. [The first fifteen minutes](04-first-fifteen-minutes.md)
5. [Keybindings](05-keybindings.md)
6. [The console](06-the-console.md)
7. [Installing software](07-installing-software.md)
8. [Updating and rolling back](08-updating-and-rolling-back.md)
9. [Files, editing, and media](09-files-and-apps.md)
10. [The shell](10-the-shell.md)
11. [Appearance](11-appearance.md)
12. [Network, mesh, sync, and backup](12-continuity.md)
13. [Hardware and peripherals](13-hardware.md)
14. [Troubleshooting](14-troubleshooting.md)
15. [Questions](15-faq.md)

## Two things to know before anything else

**Nobody downloads Alloy.** There is no image to fetch and no registry to pull
from. You take the source, build an installer ISO on your own Linux machine,
and write it to a USB stick. Chapter 2 covers it.

**An installed machine never reaches out on its own.** It does not check for
updates, does not phone home, and does not enroll in anything until you ask.
Updating means rebuilding the image and switching to it, which chapter 8
covers.