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.

> ⚠️ **The infrastructure facts below are UNVERIFIED.** They were generated one-shot from
> chat history and have **not** been confirmed against the actual setup. Treat every fact in
> the next section as provisional until reviewed and corrected with the user — see the
> standards `ROADMAP.md` item "Verify & correct the placement guide." The *decision sequence*
> and the *substance rule* are sound regardless; it's the specific service/model/network
> facts that need a pass.

## Infrastructure facts (PROVISIONAL — last generated June 2026, not yet verified)

**Start9 server** — StartOS 0.4.x. Hosts long-running services as s9pk packages or plain
containers. Believed running: Gitea (version control for LLM-assisted projects — the default
repo home), Nextcloud (general file backup), Home Assistant (Container install), Electrs,
Core Lightning + RTL, Open WebUI as the sovereign chat/session layer.

**Inference** — Two NVIDIA DGX Sparks behind the Spark Control HTTP gateway on the LAN,
serving Qwen3 (vLLM, OpenAI-compatible endpoints) as the primary production backend. Kokoro
for TTS. bge-m3 for embeddings. Treated as real production capacity — existing apps (call
transcription/recap, CRM pipeline, email-summary agent) already depend on it.

**Data layer defaults** — SQLite for structured data; Qdrant + bge-m3 when semantic
retrieval is needed; 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 gateway. 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.

**Access** — WireGuard split-tunnel from macOS to the home subnet (runs alongside Proton
VPN). iOS is constrained to a single VPN tunnel; workarounds are Tor onion addresses or a
merged WireGuard config. So "reachable from phone" is a real design constraint, not a
footnote.

**Dev machine** — macOS with Claude Code. 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 local Qwen3 via the Spark gateway when the sovereignty
boundary applies, when latency/cost favor local, or when the task is well within Qwen3's
capability. Route to frontier (Claude API) for hard reasoning on non-sensitive data. Record
the chosen endpoint 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, remember the iOS single-tunnel constraint — decide up front whether that means onion
address, merged WireGuard config, or "Mac-only is fine."

**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.