docs(local-model): label the route experimental and write down the rules

- docs/api-reference.md: GET /api/local-model is labeled experimental
  until the step that sets a model up ships, so its payload is not a
  stable /api/v1 contract one stage before that step changes it. The
  section now describes the verdict as judged, the three sentences of
  the memory reason, the notes, the speed rounding and which size to
  show as the installed memory. The os-fallback description was wrong:
  the free disk space is reported there too.
- docs/versioning-policy.md: the route is listed under the experimental
  surfaces.
- docs/wiki/Settings-Reference.md: App Settings > Models > Model on this
  Mac, in the words of a user.
- CLAUDE.md and src/web/CLAUDE.md: the invariants the code relies on
  (read-only, the probe, harness rows as data, the meaning of limited,
  the word Recommended, one unit, labels from the payload, when the
  card and the group show).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Codeman maintainer committed 2026-11-06 17:38:12 +01:00
1 parent 8281045cf2
commit 66ca92f7cf
6 files changed
+46 -8

No files matched your search

+13
View File
@@ -86,6 +86,19 @@ covered like any other stable behavior. Other agent commands and API routes keep
their existing guarantees. Promotion to stable requires an explicit documented
decision.
### Experimental local model recommendation
`GET /api/v1/local-model` (and its `/api` alias) is labeled experimental, so item 3
above applies to it: its path, its payload (the hardware facts, the verdicts and
reasons, the candidate fields and the English sentences in `headline` and
`notes`) and its behavior may change or be removed in a MINOR or PATCH release.
It is read-only today: it looks at the Mac the server runs on and says which
local model fits. The step that sets a model up from Codeman is not built yet
and will change what the route reports, which is why the shape is not promised.
It is not behind a setting (it writes nothing and adds no settings key); it is
admin only in multi-user mode. Promotion to stable requires an explicit
documented decision.
## Deprecation policy
When we need to change a covered surface: