docs: timestamped-HMAC webhooks + named model definitions (0.25.0)#90
Merged
Conversation
…(0.25.0) DO NOT MERGE until netclaw 0.25.0 is a stable release. Both features are currently 0.25.0-prerelease only; latest stable is 0.24.4 and does not have them. Verified against 0.25.0-beta.5 source and a 0.25.0 binary. Closes #83, #84, #85 once merged. Webhooks (#84, #85): - Document all three verification modes, the timestamped signing scheme (<timestamp><separator><raw body>), replay tolerance, and secret rotation - Add Stripe, TextForge, and custom-field route examples; every command and JSON example was executed/validated against the real binary - Remove the stale warning that --verification-kind header-secret fails to parse; that bug is fixed upstream in #1660 - Correct route-file casing throughout: keys are camelCase, enum values PascalCase (netclaw.json itself stays PascalCase) Models (#83): - Document Definitions/Roles, the metadata override and --clear-* flags, and role-switch preservation - Add guides/migrating-model-config.md: trigger table, backup/rollback, env-var conversion, troubleshooting Pre-existing errors found by review and fixed: - configuration/models.md documented `netclaw daemon restart`, which does not exist; replaced with stop && start / systemctl / docker restart - Main ContextWindow exceeding the provider's warns and proceeds; it does not refuse to boot - An empty Main boots degraded; it's the *optional* roles that fail startup - cli/webhooks.md claimed `netclaw status` reports a webhook base URL; no such value exists anywhere in netclaw - notifyInstructions validation never consults deliveryRequired - Request lifecycle ordering (body size and JSON parsing precede verification) - Discovery timeout is 45s, not 20s - Backup is a full config copy, not just the Models section — the old wording made the correct rollback `cp` look destructive - Add the missing Webhooks.Enabled prerequisite (off by default => permanent 404) - Warn that --events silently drops 100% of Stripe deliveries (no event header) - Add 202-ignored, 400, and 429 troubleshooting plus a daemon-log entry point - Fix orphaned H3 heading hierarchy and merge duplicate Quick start/Setup Deliberately documents current behavior over intended behavior in three places; tracked in #86 against netclaw-dev/netclaw#1674, #1675, #1676.
0.25.0 is now stable and ships the fixes for the three defects the earlier commit documented as workarounds (netclaw #1677/#1678/#1680, closing #1674/#1675/#1676). Re-verified every claim against the 0.25.0 stable binary. - cli/model.md: `model list` on an unresolved role reference now names the reference (`Models:Roles:Main references unknown definition '...'`) instead of "could not be parsed"; doctor reports it cleanly instead of crashing, and the fix is manual. Modality flags now reject raw integers, so the page states that outright (the original ask in #83). - configuration/models.md: the legacy-env migration guard is a clean error, not a crash that bricks doctor; `model list` names unresolved references. - guides/migrating-model-config.md: env-conversion guard reworded from crash to clean error; all five troubleshooting messages re-verified verbatim. Branch is now ready to merge for the 0.25.0 release.
…ider pages (#87) Four pages still taught the legacy inline model shape — the exact form that blocks migration on 0.25.0. Converted to named definitions + roles so a fresh install never has to migrate later. - deployment/docker.md: both `docker run` examples and the Compose service now use NETCLAW_Models__Definitions__<name>__* + NETCLAW_Models__Roles__Main - getting-started/installation.md: Docker quickstart env vars, same conversion - configuration/managed-providers.md: env-override example - configuration/self-hosted-providers.md: three inline "Models" JSON examples and the env-override block converted to Definitions/Roles All three converted JSON configs load under the 0.25.0 stable binary; the env form matches the upstream configuration spec (the daemon path can't be exercised in-sandbox while a real daemon holds the control socket). Closes #87.
This was referenced Jul 18, 2026
Aaronontheweb
added a commit
that referenced
this pull request
Jul 18, 2026
…laim (#82) (#92) The docs-version guard flagged src/version.json (0.24.3) as behind the latest release. 0.25.0 is now stable with the model/webhook/install surfaces already documented (#90, #91), and 0.25.0 ships no breaking changes. - src/version.json: documentedVersion 0.24.3 -> 0.25.0, lastProfiled -> 2026-07-18 - security/hardening.md: the shell-mode table listed SandboxOnly as one of "three modes", but it has no backend and just denies shell. Demoted to two working modes (Off, HostAllowed) plus a note that setting SandboxOnly yields `shell_requires_sandbox_backend` — so the error stays debuggable without advertising a dead option as a real choice. Behavior re-verified against 0.25.0 (ToolAccessPolicy.cs still returns Deny). Content pass: all other version references are correct historical notes ("Since 0.24.3...", "As of 0.22.1...") and were left as-is. drift check passes. Closes #82.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Documents the two big 0.25.0 model/webhook features and cleans up the pre-existing pages around them. Held on a branch until 0.25.0 went stable (2026-07-18); every command and config example is verified against the 0.25.0 stable binary (
commit 75e46be).Closes #83, #84, #85, #87.
Features documented
Timestamped-HMAC webhooks (#84, #85) —
cli/webhooks.md,configuration/webhooks.md<timestamp><separator><raw body>signing scheme, replay tolerance, secret rotation--verification-kind header-secretfails to parse (fixed upstream in #1660)Named model definitions (#83) —
cli/model.md,configuration/models.md, newguides/migrating-model-config.mdDefinitions/Rolesshape, metadata override +--clear-*flags, role-switch preservationLegacy env-form cleanup (#87) —
deployment/docker.md,getting-started/installation.md,configuration/managed-providers.md,configuration/self-hosted-providers.mdNETCLAW_Models__Main__*and inlineModels.Mainexamples to the named form, so a fresh install never hits the migration trapPre-existing errors fixed along the way
Review turned up several bugs in the surrounding scaffolding, unrelated to the new features:
configuration/models.mdshippednetclaw daemon restart— no such subcommand; replaced with stop && start / systemctl / docker restartcli/webhooks.mdclaimednetclaw statusreports a webhook base URL — no such value exists in netclawWebhooks.Enabledprerequisite (off by default → permanent 404 for a reader following only the CLI page)--events/Stripe trap that silently drops 100% of deliveriesUpstream defects found and fixed before this merges
Verifying against the code surfaced three netclaw bugs, all filed, fixed, and shipped in 0.25.0:
--input-modalitiesaccepted raw integersdoctorThe docs were first written to work around these, then updated (commit 2) to describe the fixed 0.25.0 behavior once the fixes landed. Tracked in #86.
Build note
Astro compiles all pages cleanly. The
pagefindsearch-index post-step can't fetch its platform binary in the CI sandbox (platform linux-x64 not supported— reproduces on a clean tree, environmental); it indexes already-built HTML and doesn't gate content. Expect it to run normally in the real build environment.