Unfuck documentation and comments

README.md

@@ -1,38 +1,20 @@
 # marvin-turnstone
 
-Local turnstone deployment as a **container-VM**: a podman image is turned
+Local turnstone deployment as a [boco](https://git.nubo.sh/hulthe/boco) **container-VM**.
-into a bootable VM with [boco](https://git.nubo.sh/hulthe/boco) (custom
-init + ext4 qcow2 + QEMU direct kernel boot). Replaces the older
-opencode-in-a-container setup (`~/marvin`).
 
-```
+    host podman build ──> boco build qcow2 ──> boco boot
-host podman build ──> boco build qcow2 ──> boco boot
+                                                  │  QEMU/KVM (virtio, user-net)
-                                              │  QEMU/KVM (virtio, user-net)
+                            ┌─────────────────────┴───────────────────┐
-                        ┌─────────────────────┴───────────────────┐
+                            │ VM (Arch)                               │
-                        │ VM (Arch)                               │
+                            │  /boco/init → start-turnstone.sh (root) │
-                        │  /boco/init → start-turnstone.sh (root) │
+                            │    ├─ sshd            (ops channel)     │
-                        │    ├─ sshd            (ops channel)     │
+                            │    └─ setpriv marvin                    │
-                        │    └─ setpriv marvin                    │
+                            │        └─ turnstone-server :8080  PID 1 │
-                        │        └─ turnstone-server :8080  PID 1 │
+                            └─────────────────────────────────────────┘
-                        └─────────────────────────────────────────┘
+       host :8080 ──hostfwd──> web UI        host :2222 ──> guest sshd :22
-   host :8080 ──hostfwd──> web UI        host :2222 ──> guest sshd :22
-   guest ──HTTPS (double slirp egress)──> api.tensorx.ai (LLM)
-```
 
 ## Prerequisites
-
+- `podman`, `qemu-base`, `virtiofsd`, `boco`
-Host (Arch):
-- `podman`, `qemu-base`, `virtiofsd`, `croc` (only if fetching the kernel)
-- `boco` CLI on PATH and `boco-init` at `~/.local/share/boco/boco-init`
-  (build from the boco repo)
-- Kernel at `~/.local/share/boco/registry/vmlinuz` (x86 bzImage with
-  `CONFIG_VIRTIO_FS=y`; transfer via croc)
-
-VM image:
-- Arch base with python + turnstone (venv at `/opt/turnstone`), git,
-  helix, podman (rootless, subuid range), openssh, build toolchain
-- `marvin` user; sshd + turnstone-server started by
-  `start-turnstone.sh` (server runs as `marvin`, PID 1)
 
 ## Build
 
@@ -49,41 +31,11 @@ image, then packs it as `boco` qcow2 into the boco registry.
 scripts/run.sh
 ```
 
-- Console (proxy to the node; chat UI + admin panel): :8080 — login
+This exposes the turnstone console on `:8080`, and ssh on `:2222`
-  `marvin` / `marvin-turnstone` unless `ADMIN_PASSWORD` was overridden.
-  The node binds :8081 guest-internal only (no host forward); the
-  console routes to it, so all chat/admin goes through one port.
-- Ops SSH: `ssh -i configs/ssh/id_ed25519 -p 2222 marvin@localhost`
-- QEMU runs foreground; quit with `ctrl-a x`
-
-### Access from another machine (tailcat)
-
-`localhost` above is the machine running QEMU. To reach the VM from
-elsewhere, run `scripts/expose.sh` next to it — a tailcat tunnel
-(WireGuard over Tailscale's DERP relays, outbound-only, no account):
-
-```
-host $ scripts/expose.sh
-# 🐈 Server listening with saved key "default": tcpGFwWCCH...
-
-your $ tailcat forward tcpGFwWCCH... 8080:8080 2222:2222
-```
-
-Then browse `http://localhost:8080` / `ssh -p 2222 marvin@localhost`
-from *your* machine. The address is stable across VM restarts (saved
-key) and is a bearer secret — share it only privately.
 
 ### LLM backend
 
-`[models.tensorx]` in `configs/turnstone/config.toml` points at the
+Set up `configs/turnstone/config.toml` with an OpenAI-compatible endpoint.
-TensorX OpenAI-compatible gateway (`https://api.tensorx.ai/v1`, same
-key this machine's opencode uses — see
-`~/.local/share/opencode/auth.json`). Guest egress to HTTPS endpoints
-works through both slirp layers; no relay needed.
-
-Self-hosted provider later: add a `[models.*]` entry with any
-OpenAI-compatible endpoint reachable from the guest (see
-`config.toml.example`).
 
 ## Shares (virtiofs, survives reboots)
 
@@ -93,29 +45,26 @@ OpenAI-compatible endpoint reachable from the guest (see
 | `data/`                | `/var/lib/turnstone`           | SQLite database          |
 | `work/`                | `/home/marvin/work`            | agent workspace          |
 
-Guest-written files appear on the host owned by subuid-range UIDs
+Note that virtiofsd runs under `podman unshare`, which means that files
-(virtiofsd runs under `podman unshare`) — cosmetic, and stable across
+written by the guest-VM will be owned by a subuid-range.
-boots.
 
 ## Configuration
 
-Edit `configs/turnstone/config.toml` (gitignored; see
+Edit `configs/turnstone/config.toml` (see `config.toml.example`):
-`config.toml.example`):
 
-- `[models.tensorx]` — TensorX gateway; `api_key` must be set
+- `[models.<provider>]` - LLM provider; `api_key` must be set.
-  (currently mirrored from opencode's `auth.json`).
+- `[auth] jwt_secret` - required, generate once.
-- `[auth] jwt_secret` — required, generate once.
+- `[database] path` - SQLite on the `data/` share.
-- `[database] path` — SQLite on the `data/` share.
+- `[tools]` - `workspace_dir` surfaced to the model.
-- `[tools]` — `workspace_dir` surfaced to the model
-  (`/home/marvin/work`, mounted from `./work`).
 
 ### Personas
 
-Built-ins (Engineer, Writer, Researcher, Scribe, Manager, Executive)
+Turnstone offers a few built-in personas (Engineer, Writer, Researcher,
-are seeded by turnstone's migration. This deployment adds a custom
+Scribe, Manager, Executive), which are seeded by turnstone's migration.
-default persona `marvin` (VM-specific: persistence rules, Gitea remotes,
+
-podman) via `scripts/persona.py` — the prompt text is versioned there
+This deployment adds a custom default persona `marvin` (VM-specific:
-and re-applied after a DB reset:
+persistence rules, Gitea remotes, podman) via `scripts/persona.py` -
+the prompt text is versioned there and re-applied after a DB reset:
 
 ```sh
 python3 scripts/persona.py            # --db data/turnstone.db default
@@ -126,11 +75,9 @@ with `turnstone-console` running, use its admin API/Personas tab.)
 
 ### Skills
 
-The 13 skills from the old opencode setup (`~/marvin/configs/opencode/skills`,
+Skills are checked in under `skills` in the `SKILL.md format.`
-copied into this repo under `skills/`) are imported into turnstone's
+These are imported into turnstone's DB-backed catalog via
-DB-backed catalog via `scripts/import_skills.py`. The script runs
+`scripts/import_skills.py`. The script runs inside the VM.
-INSIDE the VM (uses turnstone's storage layer + SKILL.md parser +
-risk scanner):
 
 ```sh
 scp -O -i configs/ssh/id_ed25519 -P 2222 -r skills scripts/import_skills.py \
@@ -140,13 +87,5 @@ ssh -i configs/ssh/id_ed25519 -p 2222 marvin@localhost \
 ```
 
 Idempotent (`--update` re-imports + appends version rows). **Reboot the
-VM after importing** — the running server holds a stale WAL snapshot
+VM after importing** - the running server holds a stale WAL snapshot
 and won't see new rows until restart.
-
-## Notes / trade-offs
-
-- boco boots with `-snapshot`: **only the virtiofs shares persist.**
-  Agent-installed packages, git clones outside `work/`, and podman image
-  storage inside the VM are discarded on shutdown.
-- boco hardcodes `-smp 8`; memory via `VM_MEMORY=...M scripts/run.sh`.
-- The old setup's Traefik is dropped — hostfwd replaces it.

skills/gitea/SKILL.md

@@ -34,7 +34,7 @@ Use the `tea` command to interact with Gitea.
 - **Communication**: Use `tea comment <number> "message"` to communicate with project maintainers (e.g., `@hulthe`).
 
 ## Responsibility
-- **Don't Drop the Ball**: When assigned a task or receiving a review comment, you MUST address it before moving on to other things. Ensure all follow-up actions ( (like replying to a comment) are completed.
+- **Don't Drop the Ball**: When assigned a task or receiving a review comment, you MUST address it before moving on to other things. Ensure all follow-up actions (like replying to a comment) are completed.
 
 ## Tips for Agents
 - **Stay Updated**: Regularly run `tea notifications` to check for new issues or PR reviews.

start-turnstone.sh

@@ -6,11 +6,9 @@ set -euo pipefail
 
 export HOME=/home/marvin
 
-# The boco kernel boots with hostname "(none)" (no systemd to read
+# Set hostname here since podman prevents us from setting it during
-# /etc/hostname) — set it live so turnstone node IDs and service URLs
+# build.-time. Turnstone requires a hostname to be set.
-# are sane (turnstone-vm_xxxx instead of (none)_xxxx). The Arch base
+python3 -c 'import socket; socket.sethostname("marvin-vm")' || true
-# has no `hostname` binary, so use the syscall via python.
-python3 -c 'import socket; socket.sethostname("turnstone-vm")' || true
 
 # sshd: host keys baked per-boot, ops channel on guest port 22
 ssh-keygen -A