Why this exists
While writing #83, #84, and #85 we verified every claim against the netclaw source (0.25.0-beta.5) and the installed binary. Three claims in those issues turned out to be aspirational rather than actual — the code does something weaker or worse than the issue describes.
We documented current behavior rather than intended behavior. This epic tracks the doc changes to make once the upstream fixes land, so those deliberate compromises don't quietly become permanent.
Upstream fixes and the docs they unblock
| Upstream |
Defect |
Doc compromise made today |
Revisit when fixed |
| netclaw-dev/netclaw#1674 |
--input-modalities accepts raw integers (1→Text) despite the intended rejection |
#83 asked us to state integers are rejected. We documented named flags only and stayed silent on the integer path rather than promise a guarantee the code doesn't make. |
Add the explicit "raw integers are rejected" statement to cli/model.md once true. |
| netclaw-dev/netclaw#1675 |
Legacy env-override migration guard throws an unhandled exception (stack trace, crash log, exit 134) instead of a clean error |
guides/migrating-model-config states the guard exists and quotes the message, but does not present it as a clean error path. |
Reword to a normal validation error once it exits 1 cleanly. |
| netclaw-dev/netclaw#1676 |
Unresolved Models.Roles reference crashes netclaw doctor and doctor --fix (exit 134); model list misdiagnoses it as unparseable and directs operators to those very commands |
We could not tell readers to run doctor to diagnose an unresolved reference — it core-dumps. Docs describe manual repair of the role reference instead. |
Restore the normal "run netclaw doctor" guidance once it reports instead of crashing. |
Also worth knowing (documented as-is, no upstream fix expected)
Not blocking
None of this blocks #83/#84/#85 from shipping. The pages are accurate against the current release; this is about reclaiming the parts we had to leave out.
Why this exists
While writing #83, #84, and #85 we verified every claim against the netclaw source (
0.25.0-beta.5) and the installed binary. Three claims in those issues turned out to be aspirational rather than actual — the code does something weaker or worse than the issue describes.We documented current behavior rather than intended behavior. This epic tracks the doc changes to make once the upstream fixes land, so those deliberate compromises don't quietly become permanent.
Upstream fixes and the docs they unblock
--input-modalitiesaccepts raw integers (1→Text) despite the intended rejectioncli/model.mdonce true.guides/migrating-model-configstates the guard exists and quotes the message, but does not present it as a clean error path.Models.Rolesreference crashesnetclaw doctoranddoctor --fix(exit 134);model listmisdiagnoses it as unparseable and directs operators to those very commandsdoctorto diagnose an unresolved reference — it core-dumps. Docs describe manual repair of the role reference instead.netclaw doctor" guidance once it reports instead of crashing.Also worth knowing (documented as-is, no upstream fix expected)
ShouldProbeForMetadatagates probing toopenai-type providers using OAuth device/PKCE. For Ollama, Anthropic, OpenRouter, github-copilot, openai-compatible, and even API-key OpenAI, no probe runs — so issue docs: documentnetclaw model setmetadata overrides (context-window, modalities, clear flags) #83's--context-window-skips-the-probe / modality-flags-don't asymmetry is a real distinction but a no-op for most users. Docs avoid implyingmodel setvalidates that your model exists."kind": "HmacTimestamped"). Both webhook pages taught PascalCase keys and said so explicitly. Because deserialization is case-insensitive the published examples still validated, so this never surfaced as a bug — corrected under docs(configuration): document timestamped-HMAC webhook verification #84/docs(cli): document hmac-timestamped webhook flags and examples #85 to matchwebhook-route.v1.schema.json.Not blocking
None of this blocks #83/#84/#85 from shipping. The pages are accurate against the current release; this is about reclaiming the parts we had to leave out.