docs(introduction): write the Introduction section content

docs/introduction/status-roadmap.md

@@ -4,6 +4,36 @@ title: "🗺️ Project status and roadmap"
 
 # 🗺️ Project status and roadmap
 
-An honest map of what works today versus what is still coming. Pre-alpha, staying at 0.x for now.
+CryptOS is **pre-alpha**. It stays on version `0.x` and is not ready for production yet. Here is an honest picture of what is finished and what is still coming.
 
-> This page is a stub. The full write-up lands in the documentation content workstream. 🚧
+## ✅ Works today
+
+The whole "brain" of a certificate authority is built and unit-tested:
+
+- Making the signing key **inside the TPM**, and never letting it out in the clear.
+- Self-signing a **Root certificate** that follows the certificate standard (RFC 5280) to the letter.
+- The **first-boot ceremony** that creates that Root, step by step.
+- The **machine config** file that describes a node.
+- The encrypted **API** (mTLS gRPC) and the tamper-evident **audit log**.
+- The full **`cryptosctl`** command-line tool.
+- Building the OS image and turning it into a bootable **ISO** for a platform such as VMware.
+
+## 🚧 In flight
+
+Booting a real node from start to finish:
+
+- **Maintenance mode** — the very first boot, before anything is installed, where you set the node up.
+- **Install to disk**, then reboot into the ceremony.
+
+This is where the active work is right now.
+
+## 🧭 Roadmap
+
+- **Phase 2** — the **issuing** role and the protocol adapters (ACME, SCEP, EST, and more) so CryptOS can hand certificates to other machines, plus the **Fleet Manager** web app for running many nodes at once.
+- **Phase 3** — high-availability pairs, many independent Roots, signed add-on extensions, and disaster recovery.
+
+The version stays at `0.x` until the whole system lands. There is no 1.0 yet.
+
+## One thing to know today
+
+Right now a node signs exactly one certificate: **its own Root**. Handing out certificates to *other* machines arrives with the issuing role in Phase 2.

docs/introduction/what-is-cryptos.md

@@ -6,9 +6,27 @@ slug: "/"
 # 🔐 What is CryptOS?
 
 :::tip[✅ Works today]
-This describes CryptOS as it works right now.
+The core described here is built and tested. Booting it end-to-end on real hardware is still in progress — see [Project status and roadmap](./status-roadmap.md).
 :::
 
-A plain-language intro: CryptOS is a locked-down computer whose only job is to be a certificate authority.
+CryptOS is a computer with **one job**: to be a certificate authority (CA).
 
-> This page is a stub. The full write-up lands in the documentation content workstream. 🚧
+A certificate authority is the thing that hands out digital ID cards — called **certificates** — and vouches that they are real. Websites, servers, and devices use these ID cards to prove who they are and to talk to each other safely. 🔐
+
+Think of CryptOS like a passport office that **only** makes passports. It sits in a locked vault. There is no front desk you can walk up to and no back door. The only way to ask it for anything is through one small, locked mail slot: a secure, encrypted connection.
+
+## What makes it different
+
+- 🚫 **No way to log in.** No SSH, no password screen, no shell, no user accounts. There is nothing to break into, because there is no door. Every action goes through one encrypted API.
+- 🔑 **The secret key never leaves the chip.** The key CryptOS signs certificates with is made *inside* a security chip called a TPM, and it is never written to disk where someone could copy it.
+- 🧱 **It cannot be changed while it runs.** The system is read-only. You describe how a node should behave in **one file** ahead of time, and that is exactly what it does.
+
+## What it can do today
+
+You can build a CryptOS image, boot it in a virtual machine, and have it create its very first identity — a **Root CA** — right inside the TPM. It signs its own certificate, and you can check that the certificate is valid, all from one command-line tool called `cryptosctl`.
+
+## Where to go next
+
+- New to certificates? Start with [Certificates and CAs 101](../concepts/certificates-101.md).
+- Want the honest picture of what is done and what is coming? Read [Project status and roadmap](./status-roadmap.md).
+- Ready to try it yourself? Head to [Try It Locally](../try-it-locally/requirements.md).

docs/introduction/why.md

@@ -4,6 +4,28 @@ title: "🤔 Why it is built this way"
 
 # 🤔 Why it is built this way
 
-The reasons behind no login, an unchangeable system, and keys held in hardware — in simple terms.
+CryptOS makes some unusual choices on purpose. Each one trades a little convenience for a lot of safety. Here is the thinking behind them, in plain terms.
 
-> This page is a stub. The full write-up lands in the documentation content workstream. 🚧
+## 🚫 Why there is no way to log in
+
+Every way *in* to a computer is also a way in for an attacker — a login screen, a shell, a remote desktop. CryptOS removes them all. There is no SSH, no shell, and no user accounts. You cannot log in, and neither can anyone else. The only way to talk to it is one encrypted API, and that door checks your ID every single time.
+
+## 🔑 Why the key lives in a chip
+
+The key CryptOS signs with is its crown jewel. If that key ever leaked, every certificate it made would be suspect. So the key is created *inside* a tamper-resistant chip — the **TPM** — and never leaves it in a form anyone could copy. Even someone holding the hard drive cannot read it.
+
+## 🧱 Why it cannot change while running
+
+If the running system cannot be changed, an attacker cannot quietly slip something in. The files are read-only. And if anything ever did go wrong, a reboot brings the machine back to a known, trusted state.
+
+## 📝 Why everything is one config file
+
+You describe a whole node in a single file — its role, its network, its settings — before it boots. There is no clicking around and no guessing what state a machine is in. You can read the change, review it, and keep it in version control, just like code.
+
+## 🔒 Why one door for everything
+
+Because every action goes through the same encrypted API, every action can be checked against who you are and written into a log that cannot be secretly edited. One door is a door you can actually watch.
+
+---
+
+This is the same idea behind [Talos Linux](https://www.talos.dev), pointed squarely at running a certificate authority.