club-3090/docs/README.md

club-3090 docs index

Two tracks. Pick the one that matches what you're doing.

• User track — "I have GPUs and a model; how do I serve it?"
• Contributor / maintainer track — "I'm working on the v0.8.0 pull pipeline, patches, or the calibration loop."

Every link below resolves to a file in this repo.

---

User track

Start here if you want to run a model.

Doc	What it is
GETTING_STARTED.md	Start here — 5-minute clone-to-curl path. No decisions, no menus.
SINGLE_CARD.md	1× RTX 3090 — workload → curated config → quick start.
DUAL_CARD.md	2× RTX 3090 (PCIe / NVLink auto-detected) — workload → config → quick start.
MULTI_CARD.md	3+ GPUs — TP scaling math, derivation from dual.yml, valid TP values.
PULL.md	Any HF safetensors repo — evaluate against the KV math, honest about confidence.
BRING_YOUR_OWN.md	Serve + tune + validate your own model/compose (any engine, single or dual) without touching the catalog.
HARDWARE.md	Card-class questions — 4090/5090, power caps, NVLink, laptop EC power.
GLOSSARY.md	TPS / KV / MTP / TP and the rest of the vocabulary.
FAQ.md	Common setup and operational questions.
COMPARISONS.md	Self-host vs cloud APIs — cost crossover and when each wins.
EXAMPLES.md	Worked end-to-end usage examples.
IMAGE_STUDIO.md	Local image generation (Ideogram-4 via ComfyUI) + chat in one UI (Open WebUI), coexisting on 2 GPUs.

---

Contributor / maintainer track

The v0.8.0 pull pipeline (in pipeline order)

A model slug flows through these stages. Read them in order to understand the whole.

Stage	Doc	What it owns
[D]	COMPOSE_GENERATOR.md	The #141 compose generator — the substrate that owns the arch→patches matrix.
Gate	PULL_GATE.md	scripts/pull.sh — the locked 6-stratum abort taxonomy, [C0]/[C2a]/[B]/[C1] gates, §4.1 confidence×verdict table.
[E]	PULL_EMIT_DERIVED.md	Download → boot → smoke for a download-eligible derived model; writes the §6 capture artifacts.
[F]	LOOP.md	The calibration loop — reads the capture bundle, classifies, runs the inbound-trust pipeline, dedups failures into the tracker.

Patch & model contribution

Doc	What it is
PATCH_POLICY.md	When/how a patch ships, the local-overlay vs upstream rules.
PATCH_ATTRIBUTION.md	The Phase-A patch-attribution matrix — arch → engine-pin → required patches.
ADDING_MODELS.md	How a new model gets added to the curated catalog.
KV_MATH.md	The KV-cache math the [B] fit verdict is computed from.

Stack reference & ops

Doc	What it is
ARCHITECTURE.md	Repo/stack architecture overview.
UPSTREAM.md	Upstream PR / issue tracker for this stack.
NIGHTLY_BUMP_RUNBOOK.md	Procedure for bumping the vLLM nightly pin.
CONTAINER_RUNTIMES.md	Docker / container runtime notes.

---

Reference matrices & deep dives

These are cross-cutting references both tracks reach for.

Doc	What it is
scripts/switch.sh --list (runtime command, not a doc)	The authoritative compose × slug matrix. Registry-derived from scripts/lib/profiles/compose_registry.py, so it's always current — every launchable slug with its topology, model, engine, KV format, and max ctx. Run this rather than trusting any hand-maintained table; the static lists in the per-topology docs are illustrative, this is the source of truth.
engines/	Per-engine deep dives — vLLM, llama.cpp, SGLang.
INFERENCE_ENGINES.md	Engine picker — which engine for which workload, and structural gaps.
CLIFFS.md	The accumulated-context / prefill failure modes (Cliff 2, Cliff 2b) and how to detect them.
DTYPE_MATRIX.md	Supported dtype × model × engine matrix.
KERNEL_MATRIX.md	Quant-kernel availability and alignment constraints.
QUALITY_TEST.md	The quality-test harness and what it measures.
RESULTS_CARD.md	The standard 3-panel format (Serving · Quality · Takeaways) for sharing a config's measured results.
STRUCTURED_COT.md	The bounded-thinking / structured-CoT compose path.
TQ3_MTP_GENESIS.md	TQ3 KV × MTP × Genesis-patch results and config.