docs(G3): quickstart + troubleshooting for the working command surface (#43)

Add docs/QUICKSTART.md (workspace layout → `up` saga → status/down → recovery →
opt-in proxy/dns/trust/secrets) and docs/TROUBLESHOOTING.md (doctor-first; up
failures, ledger recovery, WSL2 locking, concurrency, *.localhost/HTTPS,
secrets, the update notifier). Both document only implemented, e2e-verified
behavior (M2 saga + M4/M5 opt-ins). Part of G3; migration/threat-model docs
follow.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: gustavobertoi

docs/QUICKSTART.md

@@ -0,0 +1,99 @@
+# devstack — Quickstart
+
+`devstack` runs one warm set of shared infrastructure (Postgres/Redis/MinIO) on a
+tool-owned Docker network and lets many project stacks attach to it — instead of a
+duplicate database per repo. This guide covers the commands that work today.
+
+> **Prerequisites:** Docker Engine + Compose v2.20+, git ≥ 2.30. Run
+> `devstack doctor` first — it probes everything and prints a one-line fix for
+> anything missing.
+
+## 1. Lay out a workspace
+
+A workspace is one `workspace.yaml` (the shared layer) plus a `devstack.yaml` per
+repo (the portable project layer):
+
+```yaml
+# workspace.yaml
+apiVersion: devstack/v1
+kind: Workspace
+name: acme
+shared:
+  postgres: { template: postgres, params: { version: "16" } }
+  redis:    { template: redis }
+projects:
+  - { name: api, path: services/api }
+```
+
+```yaml
+# services/api/devstack.yaml
+apiVersion: devstack/v1
+kind: Project
+name: api
+services:
+  api:
+    template: php.laravel.nginx
+    uses: [workspace.shared.postgres, workspace.shared.redis]
+    healthcheck: { kind: http, port: 8080, path: /healthz }
+    env:
+      import:
+        - { from: workspace.shared.postgres, vars: [host, port, user, password, database] }
+```
+
+## 2. Bring it up
+
+```bash
+devstack up
+```
+
+One idempotent command runs the saga: **preflight → network → generate →
+shared (health-gated) → compose-up → hooks**. The shared services start once and
+are gated healthy *before* your project starts. Re-running `up` is near-instant —
+satisfied phases are skipped (resumable via the state ledger); a crash mid-run
+resumes; a failure compensates (drops ref rows / downs the project) but **never
+destroys data** (your DB volumes survive).
+
+```bash
+devstack up --json          # machine-readable phase records
+devstack up api             # only the named project(s) + the shared services they use
+devstack up --build         # rebuild images first
+devstack up --no-hooks      # skip lifecycle hooks
+```
+
+## 3. Inspect and tear down
+
+```bash
+devstack status             # per-project service health + last saga outcome + shared ref graph
+devstack shared status      # shared services, ref counts, consuming projects
+devstack down               # stop this workspace's project stacks, release their refs
+devstack shared gc          # report shared services at zero refs (--stop to actually stop them)
+```
+
+`down` leaves the shared services running by default (warm DBs are cheap). The
+external network and volumes are never touched by `down`.
+
+## 4. Recovery
+
+The state ledger is a *cache of reality*, never the source of truth:
+
+```bash
+devstack shared doctor            # reconcile: prune ref rows for projects no longer live
+devstack doctor --rebuild-state   # reconstruct the ledger from live container labels + config
+```
+
+## 5. Local HTTPS, DNS, and secrets (opt-in)
+
+```bash
+# Reverse proxy: set network.proxy.engine: caddy in workspace.yaml, then:
+sudo devstack dns setup           # marker-fenced /etc/hosts for *.localhost
+sudo devstack trust install       # install the local CA (mkcert)
+devstack trust status             # diagnose CA / certutil / WSL2 readiness
+
+# Offline secrets with SOPS+age:
+devstack secrets keygen -o ~/.config/devstack/age.txt   # generate an age key
+export SOPS_AGE_KEY_FILE=~/.config/devstack/age.txt
+# reference secrets in devstack.yaml env as secret://<provider>/<file>#<key>
+```
+
+See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) when something doesn't work, and
+[ARCHITECTURE.md](ARCHITECTURE.md) for the design.

docs/TROUBLESHOOTING.md

@@ -0,0 +1,66 @@
+# devstack — Troubleshooting
+
+Run **`devstack doctor`** first — it runs the real probe matrix (daemon, compose,
+git, filesystem, trust, dns) and prints a one-line remediation for each problem.
+`devstack doctor --json` emits the machine-readable contract.
+
+## `up` fails or hangs
+
+- **"docker daemon not reachable" (preflight).** Start Docker / fix
+  `DOCKER_HOST` or the active `docker context`. `devstack doctor` confirms the
+  context the ledger is keyed by.
+- **A shared service never goes healthy.** `up` fails fast and inlines the last
+  log lines of the failing service plus the failing healthcheck. Slow stateful
+  images (Postgres/MinIO) on Docker Desktop/WSL2 may need a larger `startPeriod`
+  in the service's `healthcheck:`.
+- **"dependsOn cycle: a → b → a".** A `dependsOn` loop is reported with the full
+  path at generate time — break the cycle.
+- **"condition: healthy … declares no healthcheck".** A `dependsOn` edge with
+  `condition: healthy` requires the target to define a `healthcheck:`. Add one or
+  use `condition: started`.
+
+## State / ledger
+
+- **Stale ref counts after a crash or manual `docker rm`.** Reconcile:
+  `devstack shared doctor` (prunes refs for projects no longer live). Every
+  command also self-heals lazily.
+- **Corrupt or lost `state.db`.** `devstack doctor --rebuild-state` reconstructs
+  the shared-service + ref rows from live container labels + your config. A backup
+  is written before any migration.
+- **WSL2 "database is locked" / flaky locking.** Keep `XDG_STATE_HOME` and
+  `XDG_RUNTIME_DIR` on the Linux filesystem (ext4/tmpfs), not `/mnt/*` (9p).
+  `devstack doctor` warns when they're on an unreliable filesystem.
+
+## Concurrency
+
+Two terminals running `devstack` at once is safe: only the four mutating points
+(network-ensure, port allocation, ref rows, `CREATE ROLE`) briefly serialize on
+the machine-global lock; everything else interleaves.
+
+## Local HTTPS / DNS
+
+- **`*.localhost` doesn't resolve.** `*.localhost` is not zero-config everywhere
+  (WSL2/minimal Ubuntu lack systemd-resolved; macOS ≤15 resolves it only in
+  browsers; Firefox ignores `/etc/hosts`). Run `sudo devstack dns setup` to write
+  the marker-fenced `/etc/hosts` block; `devstack dns status` shows what's
+  missing.
+- **Browser shows an untrusted cert.** `sudo devstack trust install` (needs
+  `mkcert`; `certutil` from `libnss3-tools` for Firefox). `devstack trust status`
+  prints the exact missing tool. On WSL2 the CA must also be imported into the
+  Windows store (browsers run on Windows).
+
+## Secrets
+
+- **A `secret://` value isn't reaching the container.** Generated files only ever
+  carry the *key name* (the value is injected at runtime) — that's by design (no
+  secret value is ever written to disk). Check the provider is declared in
+  `workspace.yaml secrets.providers` and that its kind's backend is reachable.
+- **SOPS+age:** ensure `SOPS_AGE_KEY_FILE` points at your key
+  (`devstack secrets keygen -o <file>` generates one) and the `sops` binary is on
+  PATH.
+
+## Updates
+
+- A new-release notice may print after a command. Suppress it with
+  `DEVSTACK_NO_UPDATE_NOTIFIER=1`. The check is throttled (once/day) and never
+  blocks or fails a command.