docs: fix 329 Microsoft.Contractions hits with proper safety checks
Apply contraction fixes across ~40 doc files (setup, integrations, lifecycle, networking, scheduler, swarm, tools, trust-boundary, UI, etc.). Skipped 14 hits: - 10 where words appear in ALL CAPS for deliberate emphasis (is NOT, do NOT, etc.) - 4 where text could not be safely located due to markdown formatting or column position Applied via systematic scan with checks for fenced code blocks, inline code spans, and intentional caps. Preserves sentence-initial capitalization throughout.
This commit is contained in:
iris
mara
parent
77296aff35
commit
78021ce982
38 changed files with 320 additions and 320 deletions
|
|
@ -134,7 +134,7 @@ agent's entire still-unread backlog as a flood of fresh wakes. Forge's
|
|||
own read-state is the only durable record this design needs.
|
||||
|
||||
**Read-before-comment guard doesn't block a fresh wake.** hive-forge's
|
||||
read-before-comment guard (which keys off forge unread-state) does not
|
||||
read-before-comment guard (which keys off forge unread-state) doesn't
|
||||
force the agent to view a thread before commenting on it: the broker
|
||||
wake already carries the notification body, so _delivery is the read_.
|
||||
An agent that wants the full thread still runs `hive-forge comments` /
|
||||
|
|
@ -144,7 +144,7 @@ An agent that wants the full thread still runs `hive-forge comments` /
|
|||
id → last-delivered `updated_at`) guards the narrow window where a
|
||||
mark-read call _transiently fails_ and the thread reappears unread in
|
||||
the next poll before its `updated_at` bumps — so a flaky PATCH doesn't
|
||||
re-fire the wake. It is **not persisted** and resets on restart (forge
|
||||
re-fire the wake. it's **not persisted** and resets on restart (forge
|
||||
read-state covers the durable case). Each poll prunes it to the ids in
|
||||
the single `limit=UNREAD_FETCH_LIMIT` (50) fetch page, so it can never
|
||||
exceed that many entries (a debug assertion pins the invariant; the
|
||||
|
|
@ -222,7 +222,7 @@ pipeline steps in order:
|
|||
The strict ATX rule is deliberate: `\#tag` and `#tag` render
|
||||
identically, so an over-eager escape just adds visual clutter
|
||||
without changing behavior. Setext-style headings (`title\n====`)
|
||||
are not handled — rarer in practice, would need multi-line
|
||||
aren't handled — rarer in practice, would need multi-line
|
||||
lookahead.
|
||||
|
||||
### Wrapper format
|
||||
|
|
@ -240,7 +240,7 @@ Five shapes, distinguished by the notification's classification:
|
|||
The issue/PR's own description is deliberately never embedded here (only a
|
||||
comment/review body is — that's the actual new content a notification
|
||||
exists to surface): repeating a subject's own description on every "new"
|
||||
or "activity on" wake for it is noise the agent already has via the URL,
|
||||
or "activity on" wake for it's noise the agent already has via the URL,
|
||||
not context (mara, triage: "just the issue title should be enough").
|
||||
|
||||
Review labels come from the Forgejo `state` field: `APPROVED` →
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@ into every agent, so no agent ships the `gh` wrapper or credential helper.
|
|||
(`hyperhive.github.enable` also exists per-agent for completeness, but the
|
||||
hive-wide host switch is the intended control.)
|
||||
|
||||
github.com only. The token **value** never touches nix — it is written to
|
||||
github.com only. The token **value** never touches nix — it's written to
|
||||
`<state>/github-token` separately (see [Provisioning](#provisioning)).
|
||||
|
||||
## Provisioning
|
||||
|
|
@ -88,7 +88,7 @@ minimal environment that wouldn't carry one.
|
|||
### Notifications
|
||||
|
||||
`hive-github-notify` polls github.com for the agent, turning each unread
|
||||
notification thread into a todo. It is a **separate binary and a
|
||||
notification thread into a todo. it's a **separate binary and a
|
||||
separate systemd unit** from the internal forge's poller
|
||||
(`hive-forge-notify`, see [forge.md](forge.md#notification-poller-hive-forge-notifysrcnotifyrs)),
|
||||
installed by `nix/agent-modules/github.nix` under
|
||||
|
|
@ -99,12 +99,12 @@ path, not a new package.
|
|||
Two units rather than one daemon with two loops, because it puts the
|
||||
decision in nix: a hive built without this module has **no github poller
|
||||
in its closure at all**, which is what makes GitHub access separable
|
||||
rather than merely switched off. It is also why this is not a cargo
|
||||
rather than merely switched off. it's also why this isn't a cargo
|
||||
feature — a feature would unify across the workspace and cost every
|
||||
crate its build cache.
|
||||
|
||||
At runtime the poller needs the PAT above. No PAT, no polling: the unit
|
||||
logs why and exits 0, which is why it is `Restart = on-failure` and
|
||||
logs why and exits 0, which is why it's `Restart = on-failure` and
|
||||
never `always` — a clean exit on a PAT-less agent must not become a
|
||||
restart loop.
|
||||
|
||||
|
|
@ -114,7 +114,7 @@ parse serves both: `id`, `repository.full_name`,
|
|||
for field. The two real differences are absorbed by lenient
|
||||
deserializers — GitHub sends the thread id as a _string_ where Forgejo
|
||||
sends a number, and says `PullRequest` where Forgejo says `Pull`. Todo
|
||||
keys are prefixed `gh:<id>` so a github thread id cannot collide with a
|
||||
keys are prefixed `gh:<id>` so a github thread id can't collide with a
|
||||
forge one.
|
||||
|
||||
Two host differences worth knowing before touching this code:
|
||||
|
|
@ -122,15 +122,15 @@ Two host differences worth knowing before touching this code:
|
|||
- **Auth scheme, not just value.** Forgejo takes
|
||||
`Authorization: token <t>`; GitHub wants `Bearer <t>` plus `Accept:
|
||||
application/vnd.github+json`, `X-GitHub-Api-Version` and a
|
||||
`User-Agent`. Sending Forgejo's form to GitHub does not error — it
|
||||
`User-Agent`. Sending Forgejo's form to GitHub doesn't error — it
|
||||
authenticates as _nobody_ and silently drops to the unauthenticated
|
||||
rate limit. The cheap way to tell the two apart is the rate-limit
|
||||
header: `x-ratelimit-remaining` near 5000 is an authenticated user,
|
||||
near 60 is anonymous.
|
||||
- **GitHub sets the cadence.** It returns `X-Poll-Interval` (60s in
|
||||
practice, slower than our own tick) and rate-limits callers who ignore
|
||||
it, so the loop re-arms to the server's interval whenever that is
|
||||
_slower_ than ours. A hint faster than our own tick is not a reason to
|
||||
it, so the loop re-arms to the server's interval whenever that's
|
||||
_slower_ than ours. A hint faster than our own tick isn't a reason to
|
||||
poll harder.
|
||||
|
||||
⚠️ **This needs the `notifications` scope on the PAT.** A token minted
|
||||
|
|
|
|||
|
|
@ -44,13 +44,13 @@ hive-c0re maintains the local clone at
|
|||
event to every hive over the swarm queue and each hive runs `git
|
||||
pull`, so agents see the new content on their next turn.
|
||||
|
||||
A hive that is offline when the event is sent does not get it on
|
||||
A hive that's offline when the event is sent doesn't get it on
|
||||
reconnect — the periodic pull below is what closes that gap. So one
|
||||
hive briefly showing older `/knowledge` content than another is
|
||||
expected, and resolves by itself within the fallback interval.
|
||||
|
||||
**Do not add a per-hive hook.** A webhook has exactly one target
|
||||
URL, so a second registration against the same repo does not add a
|
||||
**don't add a per-hive hook.** A webhook has exactly one target
|
||||
URL, so a second registration against the same repo doesn't add a
|
||||
recipient — it takes delivery away from whoever registered first.
|
||||
Earlier versions had each hive register its own; hive-c0re now
|
||||
removes its own leftover at startup, so no operator step is needed
|
||||
|
|
@ -59,7 +59,7 @@ pull`, so agents see the new content on their next turn.
|
|||
2. **Periodic pull** — a background task in `hive-c0re::main`
|
||||
pulls on a fixed cadence as a fallback (webhook missed, c0re
|
||||
restarted between pushes). The pull is best-effort — a failure
|
||||
logs a warning and does not affect the rest of the daemon.
|
||||
logs a warning and doesn't affect the rest of the daemon.
|
||||
|
||||
Both paths share the same `knowledge::pull()` function, which also
|
||||
handles the change notice below — neither path can forget to wire it
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ Two distinct hostnames:
|
|||
|
||||
- **`serverName`** — matrix-spec `server_name`, embedded
|
||||
*irrevocably* in every `@user:<server_name>` and `!room:<server_name>`
|
||||
identifier minted on this homeserver. Cannot be changed later
|
||||
identifier minted on this homeserver. can't be changed later
|
||||
without abandoning every account and chat history. Defaults to the
|
||||
bare `services.hyperhive.swarm.domain`; clients auto-discover the
|
||||
actual API endpoint via the `.well-known/matrix/{client,server}`
|
||||
|
|
@ -46,9 +46,9 @@ homeserver: tying its identity to a single hive's domain would make
|
|||
relocating the container between hives look like a different
|
||||
homeserver.
|
||||
|
||||
⚠️ **They are still not interchangeable, and the difference is the
|
||||
⚠️ **they're still not interchangeable, and the difference is the
|
||||
cost of changing one.** `gatewayHost` is a routing detail clients
|
||||
rediscover through `.well-known`, so it is safe to move on a running
|
||||
rediscover through `.well-known`, so it's safe to move on a running
|
||||
deployment. `serverName` is baked into every user and room id, so
|
||||
adopting a new one does **not** rename the existing users and rooms —
|
||||
it strands them, because their ids still name a homeserver that no
|
||||
|
|
@ -71,8 +71,8 @@ services.hyperhive.swarm.matrix = {
|
|||
|
||||
A rebuild on a host that already has a homeserver prints a
|
||||
`hive-matrix: WARNING — … serverName is unset` line when this is missing,
|
||||
naming the value it is about to default to. That warning is why this
|
||||
section exists; it never fails the rebuild, so it is on you to act on it
|
||||
naming the value it's about to default to. That warning is why this
|
||||
section exists; it never fails the rebuild, so it's on you to act on it
|
||||
before the ids are minted.
|
||||
|
||||
## Default-closed firewall
|
||||
|
|
@ -147,13 +147,13 @@ Initial rollout settings:
|
|||
external / federated homeservers or to keep contents opaque to the
|
||||
homeserver admin. **The agent matrix client always supports decryption
|
||||
regardless of this flag** — it uses the `e2e-encryption` feature of
|
||||
`matrix-sdk` so it can read encrypted rooms it is invited to even when
|
||||
`matrix-sdk` so it can read encrypted rooms it's invited to even when
|
||||
this homeserver doesn't permit room encryption. Crypto keys are stored
|
||||
in the per-agent sqlite store under the state dir and persist across
|
||||
restarts (lost on `--purge`). `read_room` decrypts via
|
||||
`room.messages()` — UTD events surface as `event_type =
|
||||
"m.room.encrypted"` with `body = "[unable to decrypt]"`.
|
||||
Cross-signing and automatic key backup are not enabled for the first
|
||||
Cross-signing and automatic key backup aren't enabled for the first
|
||||
pass: static bearer-token bot accounts can't bootstrap cross-signing
|
||||
without MSC3967.
|
||||
|
||||
|
|
@ -227,7 +227,7 @@ homeserver at all rather than of a setting:
|
|||
tuwunel reads its identity providers from the config file, so a
|
||||
half-configured one can stop the homeserver from starting outright
|
||||
rather than merely hiding a login button. On a host that also runs
|
||||
the swarm's authelia it is wired up for you.
|
||||
the swarm's authelia it's wired up for you.
|
||||
- **`swarm.authelia.url` is required** — without a provider URL there
|
||||
is nothing to discover against.
|
||||
- **`gatewayHost != null` is required** — the SSO callback URL is
|
||||
|
|
|
|||
Loading…
Reference in a new issue