PRODUCT.md

Rama main · réplica de lectura del repositorio original.

# Product

<!-- impeccable:product-schema 1 -->

## Platform

web

(One Svelte bundle, served by the Go binary to a browser tab and to a frameless WebView2 app window
on Windows. The app window is a wrapper around the same web UI, not a native design language.)

## Users

Two audiences, one per app. Neither app compromises for the other's user.

- **The operator** uses the **dashboard** (main listen port). The technical person who owns the box:
  runs local models on their own GPU, tunes them, points tools like Claude Code, Open WebUI and the
  SDKs at the API. Often glancing at the dashboard while something else is running.
- **Household members** use the **playground** (its own port, login per person). People who know
  ChatGPT and nothing else, and have never heard of a GGUF. They chat, search the web, make pictures
  and use voice, from a phone or a laptop on the home network.

## Product Purpose

An all-in-one local inference platform: point it at a models folder and it works out what fits in
VRAM, launches each model with computed flags, and hot-swaps between them on demand behind one
OpenAI- and Anthropic-compatible API. It also ships its own chat app, a private ChatGPT for the
household.

Success for the operator: any model runs without hand-tuning a flag, and the dashboard shows what
the box is doing instead of a log to tail. Success for a household member: it works like the chat
apps they already know, and their conversations stay on the home computer.

## Positioning

Built for the box that runs several models, of different kinds (text, image, video, 3D, speech), on a
fixed amount of VRAM, with ONE shared scheduler accounting for all of it. Ollama and LM Studio are
good at getting one model running; Quartermaster computes context, offload and KV sizing per model
from the GGUF header and measured free VRAM, and orchestrates the inference servers the operator
already trusts (llama-server, stable-diffusion.cpp, whisper.cpp, vLLM, ...) rather than running
models itself.

## Operating Context

- Runs on the operator's own machine, reached over the LAN. Often a box with no internet access.
- Dashboard: desktop browser or the Windows app window, at a user-chosen interface scale, dark or
  light. Desktop only.
- Playground: any browser on the network, **including phones**. Login-gated, server-backed history
  per user.
- One GPU is often shared: the operator's agents and the household's chats hand models back and
  forth, so loading, eviction and swap state are part of what users see.
- Help ships inside the app (the wiki behind the sidebar Help button); the playground assistant can
  search it as a tool.

## Capabilities and Constraints

- **Offline / LAN-only:** nothing may be fetched at runtime (fonts, scripts, images are bundled).
- **No telemetry:** no analytics, tracking or phoning home, in the UI or anywhere else.
- **Plain-language playground:** every word in the playground must make sense to someone who only
  knows ChatGPT. No GGUF / quant / KV / offload jargon there. Technical vocabulary is fine, and
  expected, on the dashboard.
- **Mobile:** the playground must be fully usable on a phone. The dashboard does not need to be.
- Terminology: a "model" row in the catalog is one runnable configuration; quants, context tiers and
  `-vision` twins of the same weights are variants of one model. "Listener" is a port with its own
  model catalog.

## Brand Commitments

- Name: **Quartermaster**. Mark: the helm (`ui-svelte/public/favicon.svg`, `QmMark`).
- Tagline: "Run any model without tuning a single flag." Sub-line: "Chat, images and voice, all on
  one machine."
- Voice: plain, specific, first-person-honest ("A config file I got tired of writing"). States what
  it does and where it differs, checked claims, no hype.
- Copy rule: **no em dashes**, in UI copy or docs. Use a colon, comma or parentheses.

## Evidence on Hand

- Screenshots: `docs/assets/` (dashboard, model config, social preview), regenerated by
  `npm run shots` in `ui-svelte/`.
- Landing copy: `ui-svelte/site/content.mjs`, including a comparison with Ollama and LM Studio
  checked against their docs (September 2026).
- User guide: the help wiki (`internal/server/wiki_articles.json`, rendered to `docs/`).
- **None of these exist, do not fabricate them:** testimonials, customer names, user counts, press,
  benchmark claims beyond what the repo documents.

## Product Principles

1. **Compute it, then hand over the pen.** Defaults are derived from the hardware and the model;
   every computed value stays visible and overridable.
2. **Show the machine, not a log.** State (loaded, loading, evicted, VRAM, throughput) is surfaced
   where the user is looking, as it happens.
3. **Two users, two apps.** The operator gets density and precision; the household gets something
   that feels like the chat app they already use. Do not leak one app's vocabulary into the other.
4. **Private by construction.** Local, offline-capable, no telemetry, a login per person.

## Accessibility & Inclusion

- Interface scale is a product feature (the app window has no browser zoom): layouts must hold at
  every scale step.
- Motion honours `prefers-reduced-motion`; every control shows a keyboard focus ring.