docs: clear the remaining error-level vale lints

Per #4128 (mara: allow-everywhere false positives go in a central
list, otherwise fix in source). Testing surfaced better fixes than
the plan posted on the issue:

- 5x Microsoft.Contractions 'that is' idiom false positives: adding
  the missing comma ("that is, ...") both reads better and satisfies
  the rule's own negative-lookahead, so no suppression is needed at
  all. Fixed in docs/integrations/forge.md, docs/tools/forge.md,
  docs/tools/hivectl.md, docs/web-ui/dashboard.md, and
  swarmctl-cli.md's generated source (swarmctl/src/main.rs, doc
  comment regenerated via markdown-docs).
- persistence.md's 'is not' matching inside 'is nothing': reworded to
  'there'\''s nothing' rather than add any exception -- dodges the trap
  and is a genuine contraction besides.
- ca.md's 'it is' matching inside the already-correct 'it isn'\''t':
  tried a central .vale.ini TokenIgnores entry first per the
  allow-everywhere framing, but testing against the real file (not
  just a synthetic snippet) found it silently fails to suppress
  whenever markdown emphasis syntax appears earlier in the same
  file -- an offset-drift bug in how Vale applies TokenIgnores, not
  a config mistake. Reworded to "it'\''s not" instead, same fix
  shape as persistence.md.
- config.md's 3 genuine Microsoft.Avoid 'backend' exceptions (already
  flagged and accepted on #4139 -- an actually-pluggable LLM API
  provider, matching the nix option's own name, not one internal
  system to name): scoped inline vale suppression around just that
  section, since this one really is context-specific rather than a
  rule bug.

Verified: fresh 'vale docs/ --minAlertLevel=error' is 0 errors AND
0 warnings (was 10 errors). nix fmt 0 changed beyond the edits
themselves. pre-push lints (tracker-tag/comment-block/doc-pointer)
clean. cargo clippy -p swarmctl -- -D warnings clean. Diffed the
regenerated swarmctl-cli.md against the old copy to confirm only
the intended line moved.
This commit is contained in:
iris 2026-09-09 20:30:15 +02:00 committed by mara
commit f22791b7a4
9 changed files with 18 additions and 10 deletions

View file

@ -240,6 +240,12 @@ It leaves non-compile subcommands (`new`, `add`, third-party
Set to `false` for agents that parse cargo's JSON output
programmatically and don't pass `--message-format json` themselves.
<!-- vale Microsoft.Avoid = NO -->
<!-- "backend" here means "which LLM API provider" (a genuinely pluggable
choice, matching the nix option's own name `backendEnvironmentFile`) --
not one internal system to name instead, so mara's #4041 ruling doesn't
apply to this section. -->
## API-key backend (`useApiKey` / `backendEnvironmentFile`)
```nix
@ -300,3 +306,5 @@ Switching an already-provisioned OAuth agent to `useApiKey` leaves
cleaned up automatically. Cost shape also changes: subscription pricing
→ per-request billing with no built-in monthly cap, worth knowing before
pointing a busy agent at a metered backend.
<!-- vale Microsoft.Avoid = YES -->