Genericize setup-specific examples and calm documentation emphasis (#100)

Ahead of opening the repo to external contributors, this sweeps the
codebase and docs so nothing reads as tied to one particular deployment
or reflects the scar tissue of past incidents.

## What changed

- **Genericized setup-specific example names** — placeholder hostnames,
realm/channel names, agent names, and sample identifiers in docs,
comments, and tests now use neutral illustrative values instead of names
from one specific setup.
- **Calmed documentation and comment emphasis** — trimmed defensive
CAPS, "never/always" absolutes, and repeated caveats that encoded a past
problem rather than what a fresh reader needs. The prose now explains
what and why, not the history that motivated a given line.

The sweep spans `packages/` (mcp, zulip, core, testing, memory),
`clients/` (hermes, claude-code), the docs set, and root-level files
(README, AGENTS, flake).

## No behaviour change

Purely documentation, comments, and example/placeholder values — no
runtime logic is touched. The full `check` gate (typecheck → lint →
test, 920 tests) is green on the branch.

Author: GraemeF

.github/workflows/release.yml

@@ -1,8 +1,8 @@
 name: Release
 
-# B2 release automation. Graeme's merge of a release-bump commit to `main` is
-# the SINGLE trigger; CI does everything outward-facing from there. No agent
-# ever pushes a tag or publishes anything — see docs/releasing.md for the
+# B2 release automation. The maintainer's merge of a release-bump commit to
+# `main` is the single trigger; CI does everything outward-facing from there. No
+# agent ever pushes a tag or publishes anything — see docs/releasing.md for the
 # worker flow that produces the bump PR this workflow consumes.
 #
 # In one run, when a release commit lands on `main`:
@@ -19,18 +19,17 @@ name: Release
 #      OIDC trusted publishing (no NPM_TOKEN).
 #   5. release     — cut the GitHub Release from the checked-in notes file.
 #
-# TWO LOAD-BEARING CONSTRAINTS:
-#   * npm's Trusted Publisher (OIDC) is pinned to THIS workflow's filename
+# Two load-bearing constraints:
+#   * npm's Trusted Publisher (OIDC) is pinned to this workflow's filename
 #     (`release.yml`). The publish step must stay in this file — renaming or
 #     moving it makes npm reject the OIDC publish (filename mismatch), which
-#     needs a Graeme-side npm-config change to fix.
-#   * A tag pushed by the default GITHUB_TOKEN does NOT trigger another
-#     `on: push: tags` workflow. So this workflow triggers DIRECTLY on the
+#     needs a maintainer-side npm-config change to fix.
+#   * A tag pushed by the default GITHUB_TOKEN does not trigger another
+#     `on: push: tags` workflow. So this workflow triggers directly on the
 #     release-commit-to-main (guarded by `detect`); it never relies on the tag
-#     it pushes to fire a second run. `workflow_dispatch` is the manual fallback
-#     (the live auto-trigger is first exercised on the next real release).
+#     it pushes to fire a second run. `workflow_dispatch` is the manual fallback.
 #
-# Trusted publishing means npm trusts THIS workflow (org/repo/filename), not a
+# Trusted publishing means npm trusts this workflow (org/repo/filename), not a
 # stored token: each run mints a short-lived signed OIDC token the registry
 # verifies against the package's trusted-publisher config. Because the repo and
 # package are public, npm attaches a provenance attestation automatically — no

AGENTS.md

@@ -71,7 +71,7 @@ This codebase is built on [Effect](https://effect.website). Two rules shape ever
 
 If converting a function to Effect would force its callers to convert too, that's expected. Either grow the current change to absorb the propagation, or file a paired follow-up issue — never introduce a temporary bridge as a placeholder.
 
-**2. Reach for Effect's built-in helpers before writing imperative code.** The Effect ecosystem has many helpers — `Schema.NonEmptyString`, `Schema.minLength`, `Schema.pattern`, `Schema.URL`, `Schema.transformOrFail`, `ParseResult.try`, `Effect.gen`, `Effect.retry`, `Schedule.*`, `Stream.*`, `@effect/platform`'s `HttpClient` — and they're usually shorter AND more correct (annotations, AST integration, proper error formatting) than the hand-rolled equivalent. Before writing a `Schema.filter` with manual `value.length === 0` checks, regex tests, or try/catches around standard parses (URL, JSON, Date), grep the relevant Effect source first.
+**2. Reach for Effect's built-in helpers before writing imperative code.** The Effect ecosystem has many helpers — `Schema.NonEmptyString`, `Schema.minLength`, `Schema.pattern`, `Schema.URL`, `Schema.transformOrFail`, `ParseResult.try`, `Effect.gen`, `Effect.retry`, `Schedule.*`, `Stream.*`, `@effect/platform`'s `HttpClient` — and they're usually shorter and more correct (annotations, AST integration, proper error formatting) than the hand-rolled equivalent. Before writing a `Schema.filter` with manual `value.length === 0` checks, regex tests, or try/catches around standard parses (URL, JSON, Date), grep the relevant Effect source first.
 
 If you have a local read-only Effect source clone available (path is machine-local), grep it directly: `grep -n '^export' packages/effect/src/Schema.ts` (or `Effect.ts`, `Stream.ts`, `Schedule.ts`, etc.) finds helpers fast. Same for `packages/platform/src/HttpClient.ts` and friends. Otherwise read the same files on GitHub (`Effect-TS/effect`).
 

README.md

@@ -90,8 +90,8 @@ For other hosts, `clients/hermes/` is a
 [Hermes Agent](https://github.com/NousResearch/hermes-agent) platform plugin that
 presents commy as a gateway platform. It reads the same realm credentials plus
 `COMMY_SERVER_DIR` (a commy checkout) from the environment. The receive path and
-connection lifecycle are wired; **automated install into `~/.hermes/plugins/` is
-still in progress** (`comms-a7j.7`). See
+connection lifecycle are wired; automated install into `~/.hermes/plugins/` is
+still in progress. See
 [`clients/hermes/README.md`](clients/hermes/README.md) for the current wiring.
 
 ## Bring your own realm (no central committee hosts this)

biome-plugins/effect-native-predicates.grit

@@ -9,7 +9,7 @@
 // branches of one top-level `or` — each is tried independently against every node.
 //
 // Severity is `warn` during rollout: the remaining `instanceof Error` sites
-// (the comms-ubo remediation epic) still trip it, and a `warn` surfaces them in
+// still trip it, and a `warn` surfaces them in
 // `bun run check` output without failing the gate for in-flight work. Bump to
 // `error` once those sites are gone so new occurrences are blocked.
 

clients/claude-code/.claude-plugin/plugin.json

@@ -30,19 +30,19 @@
     "COMMY_SUBSCRIBE": {
       "type": "string",
       "title": "Auto-subscribe targets",
-      "description": "Comma-separated subscribe tokens applied at MCP-child boot before tools are announced. Each token is one of: 'channel:<name>', 'thread:<channel>/<thread>', 'new-topics:<channel>', 'mentions'. Example: 'channel:assistant,mentions'. Leave blank to skip auto-subscription — the plugin still boots, and a session can subscribe at runtime via the 'subscribe' MCP tool.",
+      "description": "Comma-separated subscribe tokens applied at MCP-child boot before tools are announced. Each token is one of: 'channel:<name>', 'thread:<channel>/<thread>', 'new-topics:<channel>', 'mentions'. Example: 'channel:myproject,mentions'. Leave blank to skip auto-subscription — the plugin still boots, and a session can subscribe at runtime via the 'subscribe' MCP tool.",
       "required": false
     },
     "COMMY_CATCHUP_WINDOW_SECONDS": {
       "type": "string",
       "title": "Boot-time catch-up window (seconds)",
-      "description": "How far back to fetch recent messages across the boot-time subscribe set on a persistent-bot restart (comms-3wl). Default 14400 (4 hours). Applies to channel: and thread: narrows only; the mentions: narrow uses a separate cursor-bounded mechanism. Set to 0 to disable boot-time channel/thread catch-up.",
+      "description": "How far back to fetch recent messages across the boot-time subscribe set on a persistent-bot restart. Default 14400 (4 hours). Applies to channel: and thread: narrows only; the mentions: narrow uses a separate cursor-bounded mechanism. Set to 0 to disable boot-time channel/thread catch-up.",
       "required": false
     },
     "COMMY_NPM_MIN_RELEASE_AGE": {
       "type": "string",
       "title": "npm release-age soak override for this package",
-      "description": "Operator override for npm's min-release-age supply-chain soak, scoped to commy's own `npx @codeforbreakfast/commy-mcp` launch (threaded as npm_config_min_release_age). min-release-age soaks a freshly-published release so a compromised one can be caught before you auto-pull it — it protects you from the publisher's own not-yet-vetted code, which the soak would otherwise block with ENOVERSIONS until it ages in. Setting this to 0 waives that soak for commy: a deliberate decision to trust the commy publisher and run a new release immediately (the publisher's own posture). Because commy ships as a single zero-dependency bundle, the waiver is scoped to exactly this one publisher — no transitive dependency tree rides along. Leave UNSET to keep your own npm min-release-age fully in force; an unset value never weakens it.",
+      "description": "Operator override for npm's min-release-age supply-chain soak, scoped to commy's own `npx @codeforbreakfast/commy-mcp` launch (threaded as npm_config_min_release_age). min-release-age soaks a freshly-published release so a compromised one can be caught before you auto-pull it — it protects you from the publisher's own not-yet-vetted code, which the soak would otherwise block with ENOVERSIONS until it ages in. Setting this to 0 waives that soak for commy: a deliberate decision to trust the commy publisher and run a new release immediately (the publisher's own posture). Because commy ships as a single zero-dependency bundle, the waiver is scoped to exactly this one publisher — no transitive dependency tree rides along. Leave unset to keep your own npm min-release-age in force; an unset value never weakens it.",
       "required": false
     }
   }