Merge pull request #512 from signalwire/fern/prompt-guardrails

Reframe prompt guardrails, document the SWAIG wire protocol, and replace AI diagrams with themed SVGs

Author: Devon-White

.claude/docs/mdx-style-reference.md

@@ -1,6 +1,6 @@
 # MDX style — deep reference
 
-The five rules in `.claude/rules/` (`mdx-style`, `mdx-mechanics`, `mdx-components`, `mdx-reference-pages`, `docs-conventions`) are the binding contract and auto-load on MDX work. This file is the rationale and depth behind them: read it when doing dedicated style work (polishing a page, writing a new guide from scratch, adjudicating a style dispute), not for routine edits. Nothing in `.claude/docs/` auto-loads. Built 2026-07-21 from a five-track research pass (Claude Code docs, this repo's 2,801-page corpus, Fern's docs source, and external style-guide research); the full source-evaluation and per-rule provenance tables are recorded in the PR that introduced these rules.
+The rules in `.claude/rules/` are the binding contract: `mdx-style`, `mdx-mechanics`, `mdx-components`, `mdx-reference-pages`, and `docs-conventions` load on work under `fern/`; `spec-conventions` loads on TypeSpec under `specs/`; and root `CLAUDE.md` carries the repo-wide facts every session. Path-scoped rules fire when a matching file is read, so open the matching rule yourself when you create a file from scratch. This file is the rationale and depth behind them: read it when doing dedicated style work (polishing a page, writing a new guide from scratch, adjudicating a style dispute), not for routine edits. Nothing in `.claude/docs/` auto-loads. Built 2026-07-21 from a five-track research pass (Claude Code docs, this repo's 2,801-page corpus, Fern's docs source, and external style-guide research); the full source-evaluation and per-rule provenance tables are recorded in the PR that introduced these rules.
 
 ## Diátaxis in depth
 

.claude/rules/docs-conventions.md

@@ -2,6 +2,8 @@
 paths:
   - "fern/**/*.mdx"
   - "fern/**/*.md"
+  - "fern/**/*.yml"
+  - "fern/**/*.yaml"
 ---
 
 # Doc types — what you may edit
@@ -14,7 +16,7 @@ paths:
 | Guides, tutorials, concepts | `fern/products/*/pages/**` | Yes |
 | Snippets/partials | `fern/snippets/**` | Yes — re-check every page that includes them |
 
-Generated artifacts — `fern/apis/**` and `specs/**/tsp-output/**` — are never hand-edited; the next build overwrites them.
+Generated artifacts — `specs/**/tsp-output/**` and the OpenAPI files it emits (`fern/apis/signalwire-rest/openapi.yaml`, `fern/apis/compatibility/openapi.yaml`) — are never hand-edited; the next build overwrites them. Not all of `fern/apis/` is generated: `calling-rpc/openrpc.yaml` has no generator and is hand-maintained (currently commented out of `fern/products/apis/apis.yml`). TypeSpec conventions live in `spec-conventions`.
 
 ## Applying audit findings
 

.claude/rules/mdx-mechanics.md

@@ -2,6 +2,8 @@
 paths:
   - "fern/**/*.mdx"
   - "fern/**/*.md"
+  - "fern/**/*.yml"
+  - "fern/**/*.yaml"
 ---
 
 # MDX mechanics — Fern
@@ -57,6 +59,7 @@ Every page is also served as plain Markdown (append `.md` to its URL to preview)
 ## Checks
 
 - After MDX edits: `yarn fern-md-check`. If you touched any nav yml: `yarn fern-check`.
+- The MDX check only validates pages the nav references — it runs over the whole site and takes no file argument. Wire a new page into its `<product>.yml` before checking, or nothing validates it, CI included.
 - Hand-verify `#anchor` fragments in links you touched — no CI check covers them (lychee skips fragments).
 - Never run `yarn start:dev` (dev server) — ask the user to preview, and hand them the changed page URLs.
 - Propose commits via diff; don't commit unasked.

.claude/rules/mdx-style.md

@@ -34,11 +34,18 @@ One page, one type. Smells: a tutorial or how-to that keeps stopping to explain
 - No emoji — not in headings, tab/card titles, or prose. Say good/bad in words. [SW]
 - Terminology: "Server SDKs" (never "Agents SDK"); tokens are *created*/*issued* (never *minted*); "resource addresses" (never "Fabric addresses"); expand every acronym at first use. [SW]
 
+## Accessibility and inclusive language [G][MS]
+
+- Link text names its destination and stands alone out of context — readers using screen readers scan link-to-link. Never "click here", "this page", "read more", or a bare URL as the label.
+- Don't identify anything by sight alone. Name the control by its label, not its position or color ("the green button on the right").
+- Bias-free wording: no ableist idioms (crazy, insane, blind to, dumb), no military or political metaphors, and no culture-bound idioms that won't survive translation. Describe people, not conditions.
+
 ## Grounding [SW]
 
 - Every fact traces to specs, source, the dashboard, or a ticket. Can't verify? Write `[NEEDS SOURCE: what's missing]` — never guess. Never invent params, endpoints, components, or behavior.
 - Customer-facing only: no internal implementation detail (backend endpoints, transports, engine-side params). Placeholder data only — no real names, emails, or domains.
 - Examples do real work: tool call → your server → system of record → response. No knowledge-trivia bots.
+- Examples run as written: real imports, every required parameter, and only placeholders the reader can obviously fill. Verify each against the spec or SDK source — and against an actual run when the page ships a whole flow.
 - Don't cite other vendors' docs as authority; never disparage anyone's product.
 
 ## Modes

.claude/rules/spec-conventions.md

@@ -0,0 +1,31 @@
+---
+paths:
+  - "specs/**/*.tsp"
+  - "specs/**/*.ts"
+---
+
+# Spec conventions — TypeSpec
+
+`specs/` generates the REST reference (`signalwire-rest`, `compatibility-api`) and the SWML schemas. There are no MDX pages for any of it. Build with `yarn build:specs`, and commit the `.tsp` source together with the regenerated output; `specs/**/tsp-output/**` and the OpenAPI files under `fern/apis/` are artifacts the next build overwrites.
+
+## Modeling
+
+- Model the real API. Verify every field, type, default, and enum against backend source before adding it, and never invent one to make a shape tidy. Can't verify it? Leave it out and say so.
+- Source-verified is not the same as public. A field the engine reads belongs in a public spec only once a customer can actually obtain and set it.
+- Prefer structural modeling over magic decorators. Standards-first: keep any workaround quarantined and removable, with a comment naming what it works around.
+- No discriminated union when the discriminator is optional — OpenAPI requires the discriminator field to be required, and backends usually default it. Keep the params flat and cover the variants in prose.
+- When a payload is byte-identical to one that already exists, reference the canonical model instead of forking it for a separate nav entry.
+
+## Editing
+
+- `Unknown decorator` means a missing import, not a decorator to delete — the semantics differ (`@oneOf` is not implicit `anyOf`). Fix the import.
+- Apply repetitive edits by hand, one block at a time. No bulk scripts over spec files.
+- Decorator semantics belong in the emitter: wrap the stock emitter and delegate to it (`$onEmit` is exported). Never post-process emitted YAML in the build.
+
+## Prose inside specs
+
+`@doc` and `@example` text ships to customers, so the voice, grounding, and no-internal-details rules in `mdx-style` govern it.
+
+## Checks
+
+`yarn build:specs` must succeed, and the spec format's own validator or CLI is the conformance gate — schema-valid is not the same as idiomatic. Never write off a pre-existing build or CI error as out of scope; it usually marks real drift.

CLAUDE.md

@@ -0,0 +1,27 @@
+# SignalWire docs
+
+Fern-powered documentation site. Two sources of truth: MDX pages under `fern/products/**/pages/`, and TypeSpec under `specs/` that generates the REST and SWML reference.
+
+## Authoring rules
+
+`.claude/rules/` holds the binding conventions. They are path-scoped and fire when a matching file is read — so when you create a file from scratch, open the matching rule first: `mdx-style`, `mdx-mechanics`, `mdx-components`, `mdx-reference-pages`, `docs-conventions` for anything under `fern/`; `spec-conventions` for `specs/`. Rationale and depth behind the style rules: `.claude/docs/mdx-style-reference.md` (read on demand, never auto-loads).
+
+## Don't hand-edit generated output
+
+`specs/**/tsp-output/**` and the OpenAPI files it produces (`fern/apis/signalwire-rest/openapi.yaml`, `fern/apis/compatibility/openapi.yaml`) are build artifacts. The REST reference has no MDX at all: change the `.tsp` under `specs/`, run `yarn build:specs`, and commit source plus regenerated output together. When a rendered page is wrong, fix the generator or its source — never patch the output, which the next build overwrites.
+
+## Everything here is customer-facing
+
+Assume no prior knowledge, and never expose internal implementation detail — backend endpoints, transports, engine-side params. Every fact traces to source, a spec, the dashboard, or a ticket; if you can't verify one, write `[NEEDS SOURCE: what's missing]` instead of guessing.
+
+## Verify
+
+| Change | Run |
+|---|---|
+| MDX pages | `yarn fern-md-check` |
+| Nav yml (`fern/docs.yml`, `fern/products/*/*.yml`) | `yarn fern-check` |
+| TypeSpec under `specs/` | `yarn build:specs` |
+
+CI runs `fern-check` and `fern-md-check` on every PR. No check covers `#anchor` fragments — verify by hand any link you touch.
+
+Never start the dev server (`yarn start`, `yarn start:dev`, `fern docs dev`). Ask the user to preview, and hand them the URLs of the pages you changed.