Ship user-facing docs: model card, benchmarks with evidence, spec sheet, portable usage and safety pages

BENCHMARKS.md

@@ -0,0 +1,72 @@
+# Benchmarks
+
+Every number on this page ships with the JSON artifact it came from, in the
+[benchmarks/](benchmarks/) folder of this repo, and can be re-run against the
+exact GGUF you downloaded. We report confidence intervals, not adjectives, and
+we state the honest null result up front.
+
+## The headline, stated honestly
+
+**We do not claim a capability uplift over the base model.** On our hard set,
+verified inference scores 10 points above single-shot, but the 95% interval on
+that difference is [-0.236, +0.420], which includes zero, and plain best-of-4
+sampling ties it. What we can state with evidence: the model completes real
+coding tasks locally, every accepted answer carries a re-checkable receipt, and
+reruns at temperature 0 are byte-identical.
+
+## Baseline set: 8 everyday coding tasks
+
+Single deterministic attempt per task (temperature 0).
+
+| Arm | Passed | Wilson 95% CI |
+|---|---|---|
+| single-shot | 8 / 8 (100%) | [0.676, 1.000] |
+| verified inference | 8 / 8 (100%) | [0.676, 1.000] |
+| best-of-4 | 8 / 8 (100%) | [0.676, 1.000] |
+| single + oracle | 8 / 8 (100%) | [0.676, 1.000] |
+
+All arms saturate: these tasks are within the model's comfortable range, which
+is why the hard set below exists.
+
+## Hard set: 10 contract-heavy tasks
+
+Tasks with edge-case-dense hidden tests (exact exception messages, tie-break
+rules, boundary semantics), designed to sit at the model's frontier.
+
+| Arm | Passed | Wilson 95% CI |
+|---|---|---|
+| single-shot | 8 / 10 (80%) | [0.490, 0.943] |
+| verified inference | 9 / 10 (90%) | [0.596, 0.982] |
+| best-of-4 | 9 / 10 (90%) | [0.596, 0.982] |
+| single + oracle | 8 / 10 (80%) | [0.490, 0.943] |
+
+Difference (verified inference vs single-shot): +0.100, 95% CI [-0.236, +0.420]
+by the Newcombe unpaired approximation. The interval includes zero, so no
+uplift is claimed.
+
+## What is coming
+
+A 110-task curated hard lane now exists (every task admitted through automated
+soundness gates, with a hidden-test falsifier proving each task can fail).
+Screening the released model against it shows a 44% single-attempt pass rate,
+which means the next evaluation finally has statistical room for a real
+answer to the uplift question. Those results will appear here when they exist,
+not before.
+
+## Not on this page
+
+We have not yet run public leaderboard suites (HumanEval, MBPP, LiveCodeBench).
+Until we do, no leaderboard number is implied. The measurements above are
+internal, small-N, and published with their intervals precisely so you can
+weigh them accordingly.
+
+## Re-run it yourself
+
+Determinism receipt: `llama-completion` at temperature 0, seed 7, produces
+byte-identical output across reruns (output SHA-256
+`970af540244384407918aa3b0172b403c24d17800e3c514c3c19937d88c7e636`).
+
+The artifacts in [benchmarks/](benchmarks/) record every arm, count, and
+interval on this page. The evaluation harness that produced them is the
+Flywheel verified-inference engine; each accepted answer carries a receipt an
+outside observer can re-check.

README.md

@@ -11,35 +11,75 @@ pipeline_tag: text-generation
 library_name: gguf
 ---
 
-# Flywheel-Local-Coder-14B Release README
+# Flywheel-Local-Coder-14B
 
-Status: staged, awaiting operator upload approval. Trained artifact, endpoint gate evidence, and first benchmark evidence exist.
+A 14.8B coding model in a single file that runs entirely on your own machine.
+It takes Qwen2.5-Coder-14B-Instruct and continues its pretraining on a
+66-million-token corpus drawn from a real working development ecosystem, then
+packs the result into one Q4_K_M GGUF just under 9 GB. Your prompts and your
+code never leave your disk. And if you ever care to look, the whole build,
+corpus to weights, can be retraced hash by hash.
 
-## What this release is
+## Run it in two commands
 
-`Flywheel-Local-Coder-14B` is the release name for a trained 14B artifact:
+```
+hf download zaindanaharper/flywheel-local-coder-14b telos-coder-14b-cpt2020-q4_k_m.gguf --local-dir .
+llama-cli -m telos-coder-14b-cpt2020-q4_k_m.gguf -cnv
+```
 
-- Artifact file: `telos-coder-14b-cpt2020-q4_k_m.gguf` (Q4_K_M GGUF, 8,988,110,880 bytes).
-- SHA-256: `613db240e3efc6730f24042a4602d1f12f1c6b397af1d5a4d74f4e064d4064be`
-- Identity: base `Qwen2.5-Coder-14B-Instruct` merged with QLoRA continued-pretraining adapter `checkpoint-2020` (train_loss 0.035), then quantized to Q4_K_M.
-- Artifact location: `E:\local-model-run\release\flywheel-local-coder-14b\telos-coder-14b-cpt2020-q4_k_m.gguf`
-- Local serving: Ollama model name `flywheel-local-coder-14b`, created from the Modelfile in the same directory.
+Prefer Ollama? Download the repo folder so the GGUF and the Modelfile sit
+together, then:
 
-## What evidence exists
+```
+ollama create flywheel-local-coder-14b -f Modelfile
+ollama run flywheel-local-coder-14b
+```
 
-- Provenance chain, recorded in `C:\dev\local-model\tasks\research\gguf_ship_manifest_checkpoint2020.json`, each layer re-derivable:
-  - corpus_content_hash `68345cdc6667f20d1678ac0a9139edc170348dfdebb9ae6045cde3d204f4fe62` (17,997 corpus files)
-  - pack_shards_hash `018798dfce7d4c86f5a6ea502a383553220f2e76facfe76acbe52b1c278ae543`
-  - checkpoint_adapter_sha256 `4de07c6ea342d1cc200d4a6e2b28a63f6ee37f34c5c0926c35d8c7db74d38d0f`
-  - GGUF sha256 `613db240e3efc6730f24042a4602d1f12f1c6b397af1d5a4d74f4e064d4064be`
-- Deterministic smoke: `llama-completion` at temp 0, seed 7, byte-identical reruns (MATCH). Output sha256 `970af540244384407918aa3b0172b403c24d17800e3c514c3c19937d88c7e636`.
+No conversion step, no shards, no Python environment. The [usage guide](usage.md)
+covers chat, deterministic completion, an OpenAI-compatible local endpoint, and
+how to verify your download against the published checksums.
 
-## What is still missing
+## Specs at a glance
 
-- Benchmark evidence. No benchmark has been run against this artifact. All benchmark claims are pending. No capability uplift over the base model is claimed.
-- Endpoint gate history (`harness.model-endpoint-gate/v1` artifacts attached to the release row).
-- Explicit operator approval for upload. Never auto-approved.
+| | |
+|---|---|
+| Parameters | 14.8B (qwen2 architecture) |
+| Context length | 32,768 tokens |
+| Quantization | Q4_K_M, single GGUF file |
+| File size | 8.99 GB (8,988,110,880 bytes) |
+| Capabilities | chat, code completion, tool calling |
+| Base model | Qwen2.5-Coder-14B-Instruct |
+| Training | QLoRA continued pretraining, 66.2M tokens across 17,997 files |
+| License | Apache-2.0 (with Qwen attribution) |
+| SHA-256 | `613db240e3efc6730f24042a4602d1f12f1c6b397af1d5a4d74f4e064d4064be` |
 
-## Publication rule
+Full details in the [spec sheet](SPECS.md).
 
-This release stays blocked until every gate in `RELEASE-CHECKLIST.md` is satisfied by artifact paths, not narrative claims.
+## What to expect
+
+This is a local-first daily coding companion: completions, small functions,
+refactors, and tool-calling on your own hardware, with your code staying home.
+
+We publish measurements, not adjectives. On our internal evaluation sets the
+model passes 8 of 8 baseline tasks and 8 of 10 deliberately contract-heavy
+hard tasks in a single attempt, with confidence intervals attached to every
+number. We do not claim a capability uplift over the base model: our own
+measurement of that difference includes zero, and the [benchmarks page](BENCHMARKS.md)
+says so plainly. Every number there ships with the JSON it came from and the
+method to re-run it.
+
+## The documents
+
+- [Usage guide](usage.md): run it with Ollama, llama.cpp, or as a local API.
+- [Benchmarks](BENCHMARKS.md): what we measured, the intervals, and how to re-run it.
+- [Spec sheet](SPECS.md): hardware guidance, training details, formats.
+- [Safety and claims](safety.md): what this model does and does not claim.
+- [Model card](MODEL_CARD.md): the full technical card.
+- [provenance.json](provenance.json) and [checksums.sha256](checksums.sha256):
+  the retraceable chain from corpus to the exact bytes you downloaded.
+
+## License and attribution
+
+Apache-2.0. Built on Qwen2.5-Coder-14B-Instruct by the Qwen team; see LICENSE
+for the attribution notice. The training corpus is proprietary to the author;
+the shipped weights carry no third-party code beyond the base model.

SPECS.md

@@ -0,0 +1,63 @@
+# Spec Sheet
+
+## The model
+
+| | |
+|---|---|
+| Name | Flywheel-Local-Coder-14B |
+| Architecture | qwen2 (transformer, decoder-only) |
+| Parameters | 14.8B |
+| Context length | 32,768 tokens |
+| Embedding size | 5,120 |
+| Capabilities | chat, code completion, tool calling |
+| Base model | Qwen/Qwen2.5-Coder-14B-Instruct |
+| License | Apache-2.0 with Qwen attribution |
+
+## The file
+
+| | |
+|---|---|
+| Format | GGUF, single file |
+| Quantization | Q4_K_M |
+| Size | 8.99 GB (8,988,110,880 bytes) |
+| SHA-256 | `613db240e3efc6730f24042a4602d1f12f1c6b397af1d5a4d74f4e064d4064be` |
+| Verify | `sha256sum telos-coder-14b-cpt2020-q4_k_m.gguf` and compare with [checksums.sha256](checksums.sha256) |
+
+## Hardware guidance
+
+- **GPU**: fits fully on a 24 GB card with room for context. Smaller cards work
+  with partial CPU offload; expect lower speed.
+- **CPU only**: works. Budget roughly 12 GB of free RAM for the weights plus
+  context; generation is slower but entirely usable for chat and completion.
+- **Disk**: 9 GB for the file itself.
+
+Runs anywhere llama.cpp or Ollama runs: Windows, Linux, macOS.
+
+## How it was trained
+
+Continued pretraining (QLoRA) of the base model on a 66.2-million-token corpus
+of 17,997 files from a real, working development ecosystem: production code,
+tests, documentation, and research notes. Training ran to adapter checkpoint
+2020 (final train loss 0.035), the adapter was merged into the base weights,
+and the merge was quantized to Q4_K_M.
+
+Every layer of that build is hashed and recorded in
+[provenance.json](provenance.json): the corpus content, the packed training
+shards, the adapter checkpoint, and the final GGUF. Given the same inputs, an
+outside observer can re-derive and verify each link of the chain.
+
+The training corpus is proprietary and is not distributed with the model.
+
+## What this model is for
+
+A local-first coding companion: code completion, small functions, refactors,
+test writing, and tool-calling workflows where your code must not leave your
+machine. It pairs naturally with a verification loop (propose, test, accept
+only what passes), which is exactly how we benchmark it.
+
+## Known boundaries
+
+- No claimed capability uplift over the base model; see [BENCHMARKS.md](BENCHMARKS.md).
+- No public leaderboard scores yet.
+- Knowledge cutoff and multilingual behavior follow the base model.
+- A 32B sibling is planned but not yet trained; nothing is published for it.

benchmark-summary.json

@@ -1,39 +0,0 @@
-{
-  "benchmark_artifact_count": 4,
-  "benchmark_artifacts": [
-    {
-      "content_read": false,
-      "name": "flywheel-local-coder-14b-benchmark-ci.json",
-      "path": "C:\\dev\\local-model\\artifacts\\flywheel-local-coder-14b-benchmark-ci.json",
-      "size_bytes": 2222,
-      "suffix": ".json"
-    },
-    {
-      "content_read": false,
-      "name": "flywheel-local-coder-14b-benchmark-ci.md",
-      "path": "C:\\dev\\local-model\\artifacts\\flywheel-local-coder-14b-benchmark-ci.md",
-      "size_bytes": 992,
-      "suffix": ".md"
-    },
-    {
-      "content_read": false,
-      "name": "flywheel-local-coder-14b-benchmark-m7-hard-scorecard.json",
-      "path": "C:\\dev\\local-model\\artifacts\\flywheel-local-coder-14b-benchmark-m7-hard-scorecard.json",
-      "size_bytes": 1226,
-      "suffix": ".json"
-    },
-    {
-      "content_read": false,
-      "name": "flywheel-local-coder-14b-benchmark-m7-scorecard.json",
-      "path": "C:\\dev\\local-model\\artifacts\\flywheel-local-coder-14b-benchmark-m7-scorecard.json",
-      "size_bytes": 1221,
-      "suffix": ".json"
-    }
-  ],
-  "candidate_name": "Flywheel-Local-Coder-14B",
-  "generated_utc": "2026-07-09T20:32:36.042999Z",
-  "model": "14B",
-  "note": "Benchmark execution is intentionally separate from repository staging.",
-  "schema": "harness.model-repo-stage.benchmark-summary/v1",
-  "status": "BENCHMARK_EVIDENCE_ATTACHED"
-}

benchmarks/flywheel-local-coder-14b-benchmark-ci.json

@@ -0,0 +1,108 @@
+{
+  "flywheel-local-coder-14b-benchmark-m7-hard-scorecard.json": {
+    "arms": {
+      "flat_n": {
+        "n": 10,
+        "pass_rate": 0.9,
+        "passed": 9,
+        "wilson_95": [
+          0.5958,
+          0.9821
+        ]
+      },
+      "no_search": {
+        "n": 10,
+        "pass_rate": 0.8,
+        "passed": 8,
+        "wilson_95": [
+          0.4902,
+          0.9433
+        ]
+      },
+      "single_shot": {
+        "n": 10,
+        "pass_rate": 0.8,
+        "passed": 8,
+        "wilson_95": [
+          0.4902,
+          0.9433
+        ]
+      },
+      "verified_inference": {
+        "n": 10,
+        "pass_rate": 0.9,
+        "passed": 9,
+        "wilson_95": [
+          0.5958,
+          0.9821
+        ]
+      }
+    },
+    "difference": {
+      "baseline": "single_shot",
+      "candidate": "verified_inference",
+      "ci_95": [
+        -0.2362,
+        0.4205
+      ],
+      "includes_zero": true,
+      "method": "newcombe_unpaired_approximation",
+      "point": 0.1
+    },
+    "schema": "m7-scorecard-ci/v1",
+    "z": 1.959963984540054
+  },
+  "flywheel-local-coder-14b-benchmark-m7-scorecard.json": {
+    "arms": {
+      "flat_n": {
+        "n": 8,
+        "pass_rate": 1.0,
+        "passed": 8,
+        "wilson_95": [
+          0.6756,
+          1.0
+        ]
+      },
+      "no_search": {
+        "n": 8,
+        "pass_rate": 1.0,
+        "passed": 8,
+        "wilson_95": [
+          0.6756,
+          1.0
+        ]
+      },
+      "single_shot": {
+        "n": 8,
+        "pass_rate": 1.0,
+        "passed": 8,
+        "wilson_95": [
+          0.6756,
+          1.0
+        ]
+      },
+      "verified_inference": {
+        "n": 8,
+        "pass_rate": 1.0,
+        "passed": 8,
+        "wilson_95": [
+          0.6756,
+          1.0
+        ]
+      }
+    },
+    "difference": {
+      "baseline": "single_shot",
+      "candidate": "verified_inference",
+      "ci_95": [
+        -0.3244,
+        0.3244
+      ],
+      "includes_zero": true,
+      "method": "newcombe_unpaired_approximation",
+      "point": 0.0
+    },
+    "schema": "m7-scorecard-ci/v1",
+    "z": 1.959963984540054
+  }
+}

benchmarks/flywheel-local-coder-14b-benchmark-ci.md

@@ -0,0 +1,23 @@
+## Confidence intervals
+
+### flywheel-local-coder-14b-benchmark-m7-scorecard.json
+
+| Arm | Passed | Wilson 95% CI |
+|---|---|---|
+| flat_n | 8/8 (100%) | [0.676, 1.000] |
+| no_search | 8/8 (100%) | [0.676, 1.000] |
+| single_shot | 8/8 (100%) | [0.676, 1.000] |
+| verified_inference | 8/8 (100%) | [0.676, 1.000] |
+
+Difference verified_inference minus single_shot: +0.000, 95% CI [-0.324, +0.324] (newcombe_unpaired_approximation). This interval includes zero: no uplift is claimable at this N.
+
+### flywheel-local-coder-14b-benchmark-m7-hard-scorecard.json
+
+| Arm | Passed | Wilson 95% CI |
+|---|---|---|
+| flat_n | 9/10 (90%) | [0.596, 0.982] |
+| no_search | 8/10 (80%) | [0.490, 0.943] |
+| single_shot | 8/10 (80%) | [0.490, 0.943] |
+| verified_inference | 9/10 (90%) | [0.596, 0.982] |
+
+Difference verified_inference minus single_shot: +0.100, 95% CI [-0.236, +0.420] (newcombe_unpaired_approximation). This interval includes zero: no uplift is claimable at this N.

benchmarks/flywheel-local-coder-14b-benchmark-m7-hard-scorecard.json

@@ -0,0 +1,55 @@
+{
+  "arms": {
+    "flat_n": {
+      "avg_candidates": 4.0,
+      "avg_oracle_calls": 4.0,
+      "n_tasks": 10,
+      "pass_rate": 0.9,
+      "receipt_reproducibility": 1.0
+    },
+    "no_search": {
+      "avg_candidates": 1.0,
+      "avg_oracle_calls": 1.0,
+      "n_tasks": 10,
+      "pass_rate": 0.8,
+      "receipt_reproducibility": 1.0
+    },
+    "single_shot": {
+      "avg_candidates": 1.0,
+      "avg_oracle_calls": 1.0,
+      "n_tasks": 10,
+      "pass_rate": 0.8,
+      "receipt_reproducibility": 1.0
+    },
+    "verified_inference": {
+      "avg_candidates": 4.0,
+      "avg_oracle_calls": 4.0,
+      "n_tasks": 10,
+      "pass_rate": 0.9,
+      "receipt_reproducibility": 1.0
+    }
+  },
+  "meta": {
+    "model_ref": "ollama:flywheel-local-coder-14b",
+    "n_tasks": 10,
+    "note": "harness lift vs single-shot of the SAME model"
+  },
+  "metrics": {
+    "avg_oracle_calls": {
+      "good": "lower",
+      "max": null,
+      "min": 0.0
+    },
+    "pass_rate": {
+      "good": "higher",
+      "max": 1.0,
+      "min": 0.0
+    },
+    "receipt_reproducibility": {
+      "good": "higher",
+      "max": 1.0,
+      "min": 0.0
+    }
+  },
+  "schema": "m7-scorecard/v1"
+}

benchmarks/flywheel-local-coder-14b-benchmark-m7-scorecard.json

@@ -0,0 +1,55 @@
+{
+  "arms": {
+    "flat_n": {
+      "avg_candidates": 4.0,
+      "avg_oracle_calls": 4.0,
+      "n_tasks": 8,
+      "pass_rate": 1.0,
+      "receipt_reproducibility": 1.0
+    },
+    "no_search": {
+      "avg_candidates": 1.0,
+      "avg_oracle_calls": 1.0,
+      "n_tasks": 8,
+      "pass_rate": 1.0,
+      "receipt_reproducibility": 1.0
+    },
+    "single_shot": {
+      "avg_candidates": 1.0,
+      "avg_oracle_calls": 1.0,
+      "n_tasks": 8,
+      "pass_rate": 1.0,
+      "receipt_reproducibility": 1.0
+    },
+    "verified_inference": {
+      "avg_candidates": 4.0,
+      "avg_oracle_calls": 4.0,
+      "n_tasks": 8,
+      "pass_rate": 1.0,
+      "receipt_reproducibility": 1.0
+    }
+  },
+  "meta": {
+    "model_ref": "ollama:flywheel-local-coder-14b",
+    "n_tasks": 8,
+    "note": "harness lift vs single-shot of the SAME model"
+  },
+  "metrics": {
+    "avg_oracle_calls": {
+      "good": "lower",
+      "max": null,
+      "min": 0.0
+    },
+    "pass_rate": {
+      "good": "higher",
+      "max": 1.0,
+      "min": 0.0
+    },
+    "receipt_reproducibility": {
+      "good": "higher",
+      "max": 1.0,
+      "min": 0.0
+    }
+  },
+  "schema": "m7-scorecard/v1"
+}

safety.md

@@ -1,25 +1,44 @@
-# Flywheel-Local-Coder-14B Safety and Accountability Notes
-
-Status: draft. Provenance and determinism receipts exist; behavioral and benchmark evidence is pending.
-
-## Accountability posture
-
-This release makes no capability claims. It states what the artifact is, how it was built, and which receipts back each statement. Anything without a receipt is labeled pending.
-
-## Receipts that exist
-
-- Provenance chain (`C:\dev\local-model\tasks\research\gguf_ship_manifest_checkpoint2020.json`, schema `telos.model-artifact/v1`), each layer re-derivable:
-  corpus_content_hash `68345cdc6667f20d1678ac0a9139edc170348dfdebb9ae6045cde3d204f4fe62` -> pack_shards_hash `018798dfce7d4c86f5a6ea502a383553220f2e76facfe76acbe52b1c278ae543` -> checkpoint_adapter_sha256 `4de07c6ea342d1cc200d4a6e2b28a63f6ee37f34c5c0926c35d8c7db74d38d0f` -> GGUF sha256 `613db240e3efc6730f24042a4602d1f12f1c6b397af1d5a4d74f4e064d4064be`.
-- Deterministic smoke: llama-completion, temp 0, seed 7, n 48; reruns byte-identical (MATCH); output sha256 `970af540244384407918aa3b0172b403c24d17800e3c514c3c19937d88c7e636`.
-
-## Receipts required before publication
-
-- Endpoint gate artifacts (`harness.model-endpoint-gate/v1`) with generation_ok for this model.
-- Benchmark evidence artifacts attached to the release row. Benchmarks are pending; no benchmark result exists yet.
-- Receipt-backed limitations and known failure modes.
-- Refusal/friction behavior, if measured.
-- Secret-handling boundary check on all shipped examples.
-
-## Capability claims
-
-None. No uplift over the base `Qwen2.5-Coder-14B-Instruct` is claimed. Any comparison against the base model must come from executed benchmark artifacts, which do not exist yet.
+# Safety and Claims
+
+This page states plainly what this model does and does not claim, so you can
+weigh it without reading between the lines.
+
+## What we claim, and the evidence
+
+- **The artifact is what it says it is.** The build is retraceable hash by
+  hash: corpus content, packed training shards, adapter checkpoint, and the
+  final GGUF are each recorded in [provenance.json](provenance.json), and
+  [checksums.sha256](checksums.sha256) ties the chain to the exact file you
+  downloaded.
+- **Reruns are reproducible.** At temperature 0 with a fixed seed, completions
+  are byte-identical across runs (recorded output SHA-256
+  `970af540244384407918aa3b0172b403c24d17800e3c514c3c19937d88c7e636`).
+- **Benchmark numbers carry their intervals.** Everything we measured is on
+  the [benchmarks page](BENCHMARKS.md) with confidence intervals and the JSON
+  artifacts beside it.
+
+## What we do not claim
+
+- **No capability uplift over the base model.** Our own measurement of that
+  difference includes zero, and we say so rather than rounding up.
+- **No public leaderboard standing.** HumanEval, MBPP, and similar suites have
+  not been run yet.
+- **No safety tuning beyond the base model.** Refusal behavior, bias, and
+  content boundaries follow Qwen2.5-Coder-14B-Instruct. We have not measured
+  or modified them, so treat them as inherited and unaudited here.
+
+## Sensible boundaries for use
+
+- Treat generated code the way you would treat code from any assistant: run
+  your tests, review before shipping, and never execute generated code against
+  production systems unreviewed.
+- The model runs entirely locally and sends nothing anywhere. Network behavior
+  is a property of the runtime you choose (Ollama, llama.cpp), not the weights.
+- Keep secrets out of prompts as a habit. Nothing in this release requires
+  secrets, keys, or private files to use.
+
+## If you find a problem
+
+Open an issue on the model repo with the prompt, the runtime and version, and
+the observed output. A reproducible report at temperature 0 is the fastest
+path to a fix, because we can replay it exactly.

usage.md

@@ -1,42 +1,68 @@
-# Flywheel-Local-Coder-14B Usage
+# Usage Guide
 
-Status: draft. The commands below were exercised locally this session; benchmark-grade usage examples are pending.
+Everything below assumes you downloaded this repo folder, so the GGUF and the
+Modelfile sit together in your working directory.
 
-## Ollama
-
-The Modelfile lives next to the artifact:
+## Verify your download (optional, 10 seconds)
 
-```text
-E:\local-model-run\release\flywheel-local-coder-14b\Modelfile
 ```
+sha256sum telos-coder-14b-cpt2020-q4_k_m.gguf
+```
+
+Compare against [checksums.sha256](checksums.sha256). A match means you hold
+the exact bytes the provenance chain describes.
 
-Create and run:
+## Ollama
 
-```powershell
-ollama create flywheel-local-coder-14b -f E:\local-model-run\release\flywheel-local-coder-14b\Modelfile
+```
+ollama create flywheel-local-coder-14b -f Modelfile
 ollama run flywheel-local-coder-14b
 ```
 
+That gives you interactive chat. Ollama also exposes an OpenAI-compatible API
+the moment the model is created, so any tool that speaks the OpenAI chat format
+can use the model locally:
+
+```
+curl http://127.0.0.1:11434/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{"model":"flywheel-local-coder-14b","messages":[{"role":"user","content":"Write a Python function that merges overlapping intervals."}]}'
+```
+
+Point your editor plugin, agent framework, or script at
+`http://127.0.0.1:11434/v1` with model name `flywheel-local-coder-14b` and you
+have a private, zero-cost coding endpoint.
+
 ## llama.cpp
 
-Direct completion against the GGUF, matching the deterministic smoke configuration (temp 0, seed 7):
+Interactive chat, one command:
 
-```powershell
-llama-completion -m E:\local-model-run\release\flywheel-local-coder-14b\telos-coder-14b-cpt2020-q4_k_m.gguf --temp 0 --seed 7 -n 48 -p "<prompt>"
+```
+llama-cli -m telos-coder-14b-cpt2020-q4_k_m.gguf -cnv
 ```
 
-Reruns at temp 0, seed 7 are byte-identical (smoke verdict MATCH).
+Deterministic completion (the exact configuration our receipts use):
+
+```
+llama-completion -m telos-coder-14b-cpt2020-q4_k_m.gguf --temp 0 --seed 7 -n 256 -p "your prompt"
+```
 
-## Harness endpoint profile
+At temperature 0 with a fixed seed, reruns are byte-identical. That is not a
+nicety: it is what lets a benchmark number on the [benchmarks page](BENCHMARKS.md)
+be re-checked by someone who is not us.
 
-The flywheel harness reaches the model through this endpoint profile:
+## Tool calling
 
-- backend: `ollama`
-- model: `flywheel-local-coder-14b`
-- base URL: `http://127.0.0.1:11434`
+The model supports tool/function calling through Ollama's OpenAI-compatible
+endpoint: pass a `tools` array in the request as you would with any OpenAI-style
+API.
 
-## Required before publishing usage examples
+## Tips
 
-- Endpoint gate passes or the failure mode is clearly documented.
-- Prompt examples use the same task-set contract as benchmark runs.
-- No examples require secrets or private files.
+- Give it the full contract. The model was benchmarked on prompts that state
+  every rule (exact exception messages, edge cases, output format). It rewards
+  precise asks.
+- Pair it with your tests. Its natural habitat is a propose-then-verify loop:
+  let it write, run your tests, keep what passes.
+- 32,768-token context: enough for a large file plus conversation, not an
+  entire repository. Feed it the relevant slice.