docs: flesh out the README

Sponsored-by: author

1 files changed, 96 insertions, 1 deletions

diff --git a/README.md b/README.md
index c86b7e1..6c7f98c 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,98 @@
 # ambient-run -- build safely and securely in a local virtual machyine
 
-FIXME.
+`ambient-run` builds a software project in a local virtual machine,
+safely and securely
+
+
+## Example
+
+A software developer would use this program to build their project in
+a tightly controlled environment like this:
+
+```sh
+$ ambient-run build myproject.yaml
+```
+
+## Discussion
+
+`ambient-run` is the first component of Ambient CI, which will be a
+continuous integration system. The build is run in a virtual machine
+that does not have any networking, mainly for security. All source and
+dependencies are provided to the build, when it start, as the lack of
+networking means it can't, for example, download them at build time.
+The lack of networking also means the build can't leak secrets or
+attack other computers over the network.
+
+## Stakeholders
+
+* Lars Wirzenius is the instigator and primary developer.
+* Daniel Silverstone is an advisor.
+
+## Requirements
+
+See [`ambient-run.md`] for detailed requirements and acceptance
+criteria.
+
+## Architecture
+
+`ambient-run` runs a VM using QEMU. The VM is given the source code
+and dependencies using read-only virtual drives. It will also be
+provided read-write drives for caching and for output artifacts. All
+drives contain tar archives, not file systems, to make them easier,
+safer, and more secure to deal with.
+
+## Building
+
+To build the documentation, run:
+
+~~~sh
+$ make
+~~~
+
+To build the software, run the usual Rust command:
+
+~~~sh
+$ cargo build
+~~~
+
+## Testing
+
+
+To run the automated test suite, run the usual Rust command:
+
+~~~sh
+$ cargo test
+~~~
+
+## Deployment
+
+To create a binary to install, run:
+
+~~~sh
+$ cargo install --path=.
+~~~
+
+There is a `debian/` directory with rudimentary Debian packaging,
+which can be build in the usual Debian way.
+
+## Contributing
+
+See <https://codeberg.org/ambient/ambient-run> for the public git
+repository. Please open issues, or send patches, via that.
+
+## Legalese
+
+Copyright 2023 Lars Wirzenius.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+ .
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+ .
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.