standards/guides/placement.md

# Placement guide — where should a new project live?

Reference doc for the "where does this run, which model, what data layer?" question. It
encodes two things: a stable **decision sequence** (rarely changes) and a set of
**infrastructure facts** (go stale — keep them current). `/new-project` walks this against
every new idea (`guides/new-project.md`, Phase 2); `how-i-work.md` points here so any
session placing a project consults it rather than guessing.

> ✅ **Verified with the owner 2026-06-15** (and cross-checked against the project repos).
> Keep this section current as the infra changes — see Maintenance. The *decision sequence*
> and the *substance rule* are stable regardless.

## Infrastructure facts (verified 2026-06-15)

**Start9 server** — one box, **StartOS 0.4.0**, **x86_64** (0.4.0 doesn't run on Raspberry
Pi / ARM, so x86 is the only option — build s9pks `x86_64`). It hosts long-running services
as s9pk packages. Running on it: Gitea (the default repo home for every project), Nextcloud
(file backup), Home Assistant, Core Lightning + Ride the Lightning (RTL), Open WebUI (the
sovereign chat layer), Vaultwarden, and Synapse (the Matrix homeserver, `matrix.gilliam.ai`).
Every Claude-built app also lives here: recap (public at `recaps.cc`), keysat, premier-gunner,
proof-of-work, recap-relay, ten31-database, spark-control.

**Inference — two NVIDIA DGX Sparks (ARM64), fronted by the Spark Control gateway on the
LAN.** Spark Control is the single HTTP endpoint every app calls; the two Sparks split by role:
- **LLM Spark** — vLLM, OpenAI-compatible. Serves whichever general model is currently
  activated (daily driver right now: **Qwen3.6**; Gemma and others are downloaded and
  hot-swappable from the Spark Control dashboard).
- **Audio / speech Spark** — Parakeet (STT), Kokoro (TTS), Sortformer + TitaNet (diarization),
  **bge-m3 embeddings + Qdrant**, and the rerank model. It also hosts the **matrix-bridge**
  container (on the WireGuard subnet).

Treated as real production capacity — recap / recap-relay (transcription + analysis),
ten31-database (CRM pipeline), ten31-signal-engine, and ten31-transcripts already depend on it.

**Don't hardcode a model name.** Route to the Spark Control gateway and ask its API which
model is live — that single-endpoint indirection is the point; the active model changes when
the owner swaps it from the dashboard.

**Data layer defaults** — SQLite for structured data; **Qdrant + bge-m3** (both on the
audio/speech Spark) when semantic retrieval is needed, with per-project collections; flat
files when that's the honest answer.

**Sovereignty boundary (standing rule)** — anything touching sensitive investor, LP, or
portfolio data uses local models only, via the Spark Control gateway, behind a redaction
boundary wherever free text could carry names. Frontier APIs (Anthropic etc.) are fine for
everything else. Non-negotiable per project; the only question is which side of the line the
project's data sits on — and AGENTS.md must state it so a session never wires a frontier call
to payload data.

**Access / networking** — three mechanisms, no others (Proton VPN and Tor were legacy and are
not in use):
- **LAN** — the default; apps, Sparks, and the box share it.
- **WireGuard** — how the owner's own devices reach LAN-only services when off-LAN.
- **StartTunnel** — Start9's ClearNet feature; publicly exposes selected services (recap at
  `recaps.cc`, Synapse/Matrix, and the ten31-database CRM — the CRM is ClearNet-exposed with
  app-level user auth so only the team reaches it).

**Dev machine** — macOS with Claude Code; also the s9pk / macOS-app build host. One-off and
personal CLI tools live here happily.

## Decision sequence (stable)

Walk these in order; each answer narrows the next.

**1. Sensitivity.** Does the project ingest, store, or send investor/LP/portfolio data to a
model? If yes: local inference mandatory, hosting on the home subnet strongly preferred, and
AGENTS.md must state the constraint explicitly so a coding session never "helpfully" wires in
a frontier API call with payload data.

**2. Runtime shape.** One-shot CLI / scheduled job / long-running service / interactive UI?
- One-shot or personal CLI → Mac. Don't deploy what doesn't need deploying.
- Scheduled job → Mac launchd if it only matters while the laptop lives; Start9 if it must
  run unattended 24/7.
- Long-running service, or anything other devices/family/agents need to reach → Start9.

**3. If Start9: s9pk or plain container?** s9pk earns its packaging cost when the service
wants the StartOS lifecycle — backups, health checks, dependency management, clean updates —
or could plausibly be published for others. Plain container (or script) wins for experiments,
single-user glue, and anything still changing shape weekly. Default for prototypes: container
now, promote to s9pk if it survives and stabilizes. Packaging for 0.4.x is nontrivial; don't
pay it on spec.

**4. Model routing.** Default to the local model via the Spark Control gateway when the
sovereignty boundary applies, when latency/cost favor local, or when the task is well within
the local model's capability. Don't hardcode a model name — call the gateway and ask which
model is active. Route to frontier (Claude API) for hard reasoning on non-sensitive data.
Record the chosen endpoint (gateway vs frontier) in AGENTS.md so sessions don't guess.

**5. Data layer.** SQLite unless there's a reason; Qdrant + bge-m3 when retrieval quality is
the product; flat files for logs and artifacts. Name Qdrant collections per-project to avoid
the shared-collection mess.

**6. Interface.** CLI first unless the UI *is* the product. If it must be reachable from the
phone or by the team off-LAN, decide up front how: expose it over ClearNet via StartTunnel
with app-level auth (how the CRM and `recaps.cc` are reached), or keep it LAN-only and reach
it over WireGuard from your own devices.

**7. Repo home.** Gitea on Start9. Always — even for parked-then-revived ideas, so history
accumulates in one place.

## Phase-exit criteria — the substance rule

Phase exits are falsifiable substance: numbers and demonstrable behavior. "46/46 tests
pass," "recap generated from a real 40-minute call in under 2 minutes," "correct doc in
top-3 for 9/10 canned queries." If the criterion can't fail, it isn't a criterion.

## Maintenance

The **infrastructure facts** section is the part that goes stale. When the infra changes —
new hardware, StartOS version, model lineup, network setup, a service added or retired —
update that section here rather than working around it in conversation. The decision sequence
and the substance rule rarely change.