From 87b732336770dcac3a50cddf8affd8f25fce3543 Mon Sep 17 00:00:00 2001
From: Kyle Isom <kyle@imap.cc>
Date: Sun, 15 Mar 2026 10:33:47 -0700
Subject: [PATCH] Add README with quick-start and links to detailed docs

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d195e7f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,78 @@
+# Metacrypt
+
+Metacrypt is a cryptographic service for the [Metacircular](https://metacircular.net) platform. It provides an encrypted secrets barrier and pluggable cryptographic engines (CA/PKI, SSH CA, transit encryption, user-to-user encryption) over a gRPC and HTTPS API. Authentication is delegated to [MCIAS](https://mcias.metacircular.net:8443/docs).
+
+It operates using a seal/unseal model similar to HashiCorp Vault: the service starts sealed on every boot and must be unlocked with a password before cryptographic operations are available.
+
+## Quick Start
+
+### Prerequisites
+
+- Go 1.23+
+- A running [MCIAS](https://mcias.metacircular.net:8443/docs) instance
+- TLS certificate and key for the server
+
+### Build
+
+```bash
+make metacrypt metacrypt-web
+```
+
+### Configure
+
+```bash
+cp deploy/examples/metacrypt.toml /srv/metacrypt/metacrypt.toml
+# Edit to set listen_addr, tls_cert, tls_key, database.path, mcias.server_url
+```
+
+### Initialize
+
+```bash
+./metacrypt init --config /srv/metacrypt/metacrypt.toml
+```
+
+This prompts for a seal password and generates the master encryption key. **Store the seal password securely — it cannot be recovered if lost.**
+
+### Run
+
+```bash
+./metacrypt server --config /srv/metacrypt/metacrypt.toml
+```
+
+The service starts **sealed**. Unseal it:
+
+```bash
+curl -sk -X POST https://localhost:8443/v1/unseal \
+    -H 'Content-Type: application/json' \
+    -d '{"password":"<seal-password>"}'
+```
+
+Or use the web UI: navigate to `https://<host>:8443/`.
+
+### Docker
+
+```bash
+make docker
+docker compose -f deploy/docker/docker-compose.yml up -d
+```
+
+See [RUNBOOK.md](RUNBOOK.md#docker-install) for volume setup instructions.
+
+## Further Reading
+
+| Document | Contents |
+|---|---|
+| [ARCHITECTURE.md](ARCHITECTURE.md) | Cryptographic design, key hierarchy, engine architecture, API reference, security model |
+| [RUNBOOK.md](RUNBOOK.md) | Installation, daily operations, backup/restore, monitoring, troubleshooting |
+| [PKI-ENGINE-PLAN.md](PKI-ENGINE-PLAN.md) | CA engine implementation plan |
+
+## Development
+
+```bash
+make build      # Build all packages
+make test       # Run tests
+make vet        # Static analysis
+make lint       # golangci-lint
+make proto      # Regenerate protobuf/gRPC stubs
+make proto-lint # Lint and check proto breaking changes
+```