docc: update wrkstrm design-system pages

Author: rismay

design-system.docc/design-systems.md

@@ -12,6 +12,21 @@ A set of public design guides for DocC authoring, preview workflows, and documen
 
 @Image(source: "clia-design-systems-hero", alt: "Hero: terminal + DocC + tooling")
 
+## Public vs Private
+
+Wrkstrm documentation is split into public and private surfaces.
+
+- **Public** content is publishable (e.g. GitHub Pages) and must be written for an external reader.
+- **Private** content is internal-only (operators, local paths, internal benchmarks/incidents, unreleased plans).
+
+### The top level is not a dumping ground
+
+The bundle root should stay small and curated. Add new pages to an appropriate topic folder (for example `docc/`, `tui/`, `spm/`, `svg/`) and link them through the relevant container article.
+
+Treat the boundary as a **release contract**, not a folder naming preference. When content must move from private → public, follow the explicit bridging/graduation rules in:
+
+- <doc:docc-design-system-file-organization>
+
 ## Topics
 
 ### DocC

design-system.docc/discord/design-system-discord-conventions.md

@@ -0,0 +1,87 @@
+# Discord Conventions (Org + Agent Channels)
+
+@Metadata {
+  @PageImage(purpose: icon, source: "docc-docc-design-system-icon", alt: "DocC design-system icon")
+  @PageKind(article)
+  @PageColor(purple)
+}
+
+This page documents the current Discord information architecture conventions used to keep large, multi-org agent rosters scannable.
+
+## Design decision: Operators are Agents (no separate category)
+
+We experimented with splitting “operators” and “agents” into separate Discord categories.
+
+We reverted that.
+
+**Rationale**
+
+- An “operator” is an **operating posture** (guardrails + safety defaults), not a different kind of entity.
+- Discord navigation should remain stable as the roster grows; splitting by posture creates churn.
+- Posture is better represented in:
+  - channel naming (type prefix), and
+  - triad Agency (constraints / S-Type), not sidebar taxonomy.
+
+## Category naming (org-first, type prefix)
+
+Org categories are prefixed by a shared org-type emoji, and suffixed with a per-org callsign:
+
+- Format: `🌐-<org>-<callsign>`
+
+Example org callsigns:
+
+- `🌐-wrkstrm-⚙️`
+- `🌐-todo3-📦`
+- `🌐-text-allora-🗣️`
+- `🌐-wrkstrm-finance-💹`
+- `🌐-laussat-studio-🎨`
+
+## Channel naming (type first, emoji last)
+
+Agent/operator chat channels are named with type first and the persona emoji last:
+
+- Format: `<type>-<slug>-<emoji>`
+
+Where:
+
+- `<type>` is currently:
+  - `💠` for agent persona chats
+  - `🧬` for operator-posture chats
+- `<slug>` is the stable identifier (lowercase, kebab-case; keep it short)
+- `<emoji>` is the persona emoji (single emoji)
+
+Examples:
+
+- `💠-crush-🐍`
+- `💠-tau-🪐`
+- `🧬-rismay-🧬`
+- `🧬-uptobat-👻`
+
+## Operator thread protocol (🧬)
+
+Operator-posture channels (🧬) can accumulate many parallel lines of thought. Use Discord threads to keep work
+scannable without fragmenting into new channels.
+
+Minimal protocol:
+
+- **One thread = one intent.** If the intent changes, spin a new thread.
+- **Thread opener** must include a short framing header (who/with/org/lane/scope) + a one-line goal.
+- Capture outcomes explicitly:
+  - `DECISION:` for durable decisions.
+  - `TODO:` for actionable follow-ups.
+
+Promotion path (turn threads into durable knowledge):
+
+- Stable rule/pattern → promote to `memory.docc/expertise/`.
+- Dated outcome/postmortem → promote to `memory.docc/journal/`.
+- Sketch/hypothesis → keep in `memory.docc/ideas/`.
+- Committed work item → `.clia/BACKLOG.md`.
+
+## Message formatting
+
+- See <doc:design-system-discord-message-formatting>.
+
+## Notes
+
+- Channel topics may contain automation hints (e.g. `$sync ^channel-name ...`). Keep these in sync if the channel is renamed.
+- Avoid embedding “lane” semantics into Discord categories; use naming + triads.

design-system.docc/discord/design-system-discord-message-formatting.md

@@ -0,0 +1,80 @@
+# Discord Message Formatting (safe subset)
+
+@Metadata {
+  @PageKind(article)
+  @PageColor(purple)
+}
+
+This page documents the **safe** Discord message formatting subset we rely on for operator and agent work.
+
+Goal: messages should render predictably, stay readable on mobile, and be resilient to tool limitations.
+
+## Supported formatting (reliable)
+
+- **Bold:** `**bold**`
+- *Italic:* `*italic*`
+- __Underline__: `__underline__`
+- ~~Strike~~: `~~strike~~`
+- Inline code: `` `code` ``
+- Code blocks:
+
+  ```
+  ```ts
+  const x = 1
+  ```
+  ```
+
+- Block quotes:
+  - `> quote`
+  - `>>> multi-line quote`
+- Lists:
+  - bullets: `- item`
+  - numbered: `1. item`
+
+## Links
+
+- Plain URLs auto-link reliably.
+- Avoid depending on rich embeds for critical information.
+
+## Message size + chunking
+
+- Discord hard limit is **2000 characters** per message.
+- Prefer multiple short messages over one long message.
+- Put any structured payload into a **fenced code block**.
+
+## Templates
+
+### Thread opener (operator)
+
+```
+by: <operator>
+with: <participants>
+org: <org>
+lane: operator 🧬
+
+goal: <one sentence>
+
+links:
+- <url>
+
+TODO:
+- [ ] <action>
+
+DECISION:
+- <if any>
+```
+
+### Status card
+
+```
+status: <backlog|in-progress|blocked|done>
+blockers:
+- <blocker>
+next:
+- <next action>
+```
+
+## Tooling constraints (current)
+
+- Inline buttons are not enabled for Discord in this deployment.
+- Treat “embeds” as a nice-to-have; the canonical content should be plain text + markdown.

design-system.docc/docc/docc-design-system-discord-conventions.md

@@ -1,12 +1,16 @@
-# Discord Conventions (Org + Agent Channels)
+# Discord Conventions (Org + Agent Channels) [MOVED]
 
 @Metadata {
   @PageImage(purpose: icon, source: "docc-docc-design-system-icon", alt: "DocC design-system icon")
   @PageKind(article)
   @PageColor(purple)
 }
 
-This page documents the current Discord information architecture conventions used to keep large, multi-org agent rosters scannable.
+This page has moved.
+
+New canonical location:
+
+- `design-system.docc/discord/design-system-discord-conventions.md`
 
 ## Design decision: Operators are Agents (no separate category)
 
@@ -55,7 +59,27 @@ Examples:
 - `💠-crush-🐍`
 - `💠-tau-🪐`
 - `🧬-rismay-🧬`
-- `🧬-uptobat-r-👻`
+- `🧬-uptobat-👻`
+
+## Operator thread protocol (🧬)
+
+Operator-posture channels (🧬) can accumulate many parallel lines of thought. Use Discord threads to keep work
+scannable without fragmenting into new channels.
+
+Minimal protocol:
+
+- **One thread = one intent.** If the intent changes, spin a new thread.
+- **Thread opener** must include a short framing header (who/with/org/lane/scope) + a one-line goal.
+- Capture outcomes explicitly:
+  - `DECISION:` for durable decisions.
+  - `TODO:` for actionable follow-ups.
+
+Promotion path (turn threads into durable knowledge):
+
+- Stable rule/pattern → promote to `memory.docc/expertise/`.
+- Dated outcome/postmortem → promote to `memory.docc/journal/`.
+- Sketch/hypothesis → keep in `memory.docc/ideas/`.
+- Committed work item → `.clia/BACKLOG.md`.
 
 ## Notes
 

design-system.docc/docc/docc-design-system-file-organization.md

@@ -57,6 +57,30 @@ Every `.docc` bundle must follow this organization pattern:
 
 Public DocC bundles are hosted on GitHub Pages; private bundles are rendered by local apps.
 
+## Crossing the public barrier (bridging rules)
+
+Treat the public/private split as a **release boundary** with an explicit contract — not “just a folder”.
+
+### Content classes
+
+1. **Public (OK to ship):** stable concepts and interfaces; outside-readable docs; no internal-only context.
+2. **Private (never ship):** operator/local-machine notes, internal benchmarks/incidents, unreleased plans, private paths/identifiers.
+3. **Bridgeable (starts private; may graduate):** design notes that might become public after review.
+
+### Graduation checklist (private → public)
+
+A document may cross the barrier only after:
+
+- **Audience rewrite:** remove internal context and assume an external reader.
+- **Stability:** behavior is intended to be supported (or explicitly marked experimental).
+- **Sanitization:** no private paths (e.g. `/Users/...`), no `.clia/operators/**`, no private corpora references.
+- **Surface alignment:** aligns with the public schema/CLI surface that will enforce it.
+- **Explicit approval:** a named owner/reviewer signs off.
+
+### Rule of thumb
+
+Exploration happens in **private** docs first. Public docs should generally be **graduated copies** (rewritten), not moved originals.
+
 ## Submodule Layout (public vs private)
 
 Mono contains nested Git submodules. When a component transitions from public → private, follow a

design-system.docc/docc/docc-design-system-github-actions.md

@@ -62,6 +62,51 @@ This keeps redirects deterministic and independent of DocC sanitization.
 - Confirm `--hosting-base-path` matches the path the artifact will be served under.
 - If you need redirects, generate static `index.html` files as a post-build step.
 
+## Site reliability
+
+This page is about **publishing**.
+
+For monitoring conventions (JSON probes, incident threads, badges, posting rules), see:
+
+- <doc:docc-site-reliability>
+
+
+### Thread naming convention
+
+Use exactly one of three badges (based on the *last run status*):
+
+- 🟢 (healthy)
+- 🟡 (degraded)
+- 🔴 (down)
+
+Thread name template (double emoji):
+
+- `{thread-type-emoji}{status-emoji} incidents: site-reliability-{agent-emoji}`
+
+Where:
+- `thread-type-emoji` = `🛡️` (SRE/guardrails)
+- `status-emoji` = 🟢 | 🟡 | 🔴 (last run status)
+
+Examples:
+- `🛡️🟢 incidents: site-reliability-🧩`
+- `🛡️🟡 incidents: site-reliability-🧩`
+- `🛡️🔴 incidents: site-reliability-🧩`
+
+### Posting rules (state-change only)
+
+Monitors should track the last known status and:
+
+- 🟢 → 🟡: post once with a short degradation summary
+- 🟡 → 🟢: post once with a recovery summary
+- any → 🔴: post once with a failure summary (include failing probes)
+- same → same: **no post** (avoid hourly spam)
+
+### Status definitions (recommended)
+
+- 🟢: all JSON probes succeed (200 + JSON parses + minimal assertions)
+- 🟡: some probes fail but primary index probe succeeds
+- 🔴: primary index probe fails (or multiple probes fail)
+
 ## Failure modes we’ve hit
 
 - **404 on a “subpath site”**: the file tree doesn’t actually include that folder on Pages.