docs: v1.2 followups — table-to-card layouts, K8s example, social-card SEO

[cjimti]

Three threads of post-v1.2.0 docs polish, bundled because they all surfaced together while reviewing the live site against the v1.2.0 release.

Summary

• Identifier-shaped tokens never wrap mid-character again. Markdown tables hyphenate backtick'd identifiers when columns are narrow (auth.allow_anonymous rendered as auth.all / ow_anony / mous; 00-namespace.yaml rendered as 00-namespace.yam / l). Three new card components (.api-endpoint, .config-key, .def-card) anchor the identifier on its own line at full row width with type/default chips locked to a second line. Conversions across 9 docs pages (43 config keys, 30 HTTP endpoints, route lists, surface lists, method lists, file-system paths).
• Self-contained Kubernetes example. New examples/kubernetes/ with one file per resource (Namespace + Postgres Service/Secret/StatefulSet + mcp-test Secret/ConfigMap/Service/Deployment/Ingress) and a bash installer that generates secrets in-place, applies in numeric order with [N/M] progress, gates on Postgres readiness, patches a config-hash/secret-hash so config edits trigger rollouts. Documented at docs/operations/kubernetes.md with each manifest's full YAML embedded inline (verbatim from disk; a python check enforces no drift between embeds and source).
• SEO surface aligned with v1.2. llms.txt updated with the new Operations pages. mkdocs-material's social plugin enabled (gated enabled: !ENV [CI, false] so dev builds without imaging deps still work). On deploy, every page gets a 1200×630 PNG card baked with its title, description, and Plexara typography (Outfit display, midnight + slate palette), so Twitter/X switches from summary to summary_large_image and Slack/LinkedIn previews look intentional.

Plus: ASCII box-drawing diagrams in gateway-testing.md converted to mermaid (flowchart LR for client/gateway/mcp-test/audit topology, sequenceDiagram autonumber for the identity-forwarding contrast).

Files

Area	Files	Change
CSS components	docs/stylesheets/extra.css	+430 lines (.api-endpoint, .config-key, .def-card with shared border/radius/copper-hover vocabulary, slate-mode variants, reduced-motion gates)
HTTP API reference	docs/reference/http-api.md	30 endpoint cards + 4 JSONB filter cards
Config reference	docs/configuration/reference.md	43 cards across 8 sections (server, oidc, api_keys, auth, database, audit, portal, tools)
Env vars	docs/configuration/environment.md	11 env-var cards with maps to chips
Audit page	docs/operations/audit.md	column cards + 6 endpoint cards (the second table that was hidden below the JSONB filter section)
Portal page	docs/operations/portal.md	10 route cards
MCP reference	docs/reference/mcp.md	5 method cards
Surface tables	docs/getting-started/{overview,quickstart}.md	7 + 4 def-cards
Mermaid	docs/operations/gateway-testing.md	2 diagrams converted from ASCII
Kubernetes example	examples/kubernetes/*.{yaml,sh,md} (10 files) + docs/operations/kubernetes.md + mkdocs.yml nav + docs/operations/deployment.md cross-link	new
SEO	docs/llms.txt, mkdocs.yml, .github/workflows/docs.yml	inspection + kubernetes pages added; social plugin enabled in CI; cairo / freetype / libpng / libjpeg / libffi / libz dev packages installed for cairosvg + Pillow

Total: 26 files, +3375 / −188.

Card design vocabulary

Same shell as the carousel slides shipped in PR #12: 1px --md-default-fg-color--lightest border, --plex-radius-md, copper hover-tint with shadow lift. 3px left strip color-codes the entry's category:

• .api-endpoint--get → --copper-400 (read, frequent)
• .api-endpoint--post → --copper-700 (write)
• .api-endpoint--delete → coral #b04829 (destructive but not traffic-light red)
• .config-key--required → deeper --copper-700 (required-config has the same coral chip variant in the meta row, shared with the DELETE pill so destructive verbs and required-config-failures share one visual lookout)

Head row is a fixed two-row stack (flex-direction: column): identifier on row 1 at full row width (no wrap), [label] value chips on row 2 in the same horizontal slot every card. Description body sits below in DM Sans, indented under the identifier so the eye doesn't have to reset.

Kubernetes example architecture

client → Ingress (nginx + cert-manager) → Deployment mcp-test → StatefulSet postgres

Manifests in examples/kubernetes/:

• Numeric prefix is the apply order (00, 10, 12, 14, 20, 25, 30, 40, 50).
• install.sh confirms the kubectl context, fills REPLACE_ME_* placeholders with openssl rand output on first run, applies in sequence with [N/M] progress, waits for pod/postgres-0 Ready (180s) before applying mcp-test, waits for the Deployment rollout (180s).
• mkdocs-material[imaging]-driven social cards make the docs page itself shareable.

Verification

• mkdocs build --strict ✅ (zero warnings, zero broken refs).
• make verify ✅ (Go suite untouched; ran for sentinel parity).
• All 9 K8s manifests pass kubectl apply --dry-run=client.
• Python script in the commit verifies every embedded YAML in kubernetes.md matches its on-disk source verbatim (no paraphrasing drift).
• Site-wide audit confirms 0 mid-token wraps remain on identifier-shaped backtick'd content.
• Browser-driven smoke test on the live mkdocs serve confirmed: card layouts render, chips lock to a fixed slot, mermaid renders in both themes, lightbox carousel still works (PR feat(audit): portal inspection UI — drawer, compare page, walkthrough docs #12 shipped that; not regressed).

Pre-commit gate

Three separate review rounds across the three commits, each verdict CLEAN. Findings caught in-tree before commit:

• MAJOR: YAML drift between kubernetes.md embeds and the on-disk manifests (paraphrased valueFrom: {secretKeyRef: ...}). Fixed: embeds are now byte-identical to the on-disk source.
• MINOR: em-dashes in CSS comments and install.sh header (project hard-rule violation). Fixed.
• MINOR: missing libz-dev in the social-plugin system-deps list (parity with mkdocs-material upstream). Fixed.
• NIT: indent inconsistency in a reduced-motion CSS block. Fixed.

Test plan

• CI: Deploy Documentation workflow runs green on this branch's merge.
• On the deployed site, share /operations/inspection/ to a Slack/Twitter test channel and confirm the 1200×630 social card renders with the Plexara colors and Outfit typography.
• Click a method pill / route / config key on the live /configuration/reference/ page and confirm no horizontal scroll on a 1440px viewport, even for the longest identifier (server.streamable.session_timeout).
• Open /operations/kubernetes/ and confirm each YAML block has a copy button (mkdocs-material default) and the file-path title displays correctly.
• git clone && cd examples/kubernetes && INGRESS_HOST=test.example.com ./install.sh --dry-run against a real cluster context.
• llms.txt: visit https://mcp-test.plexara.io/llms.txt post-merge, confirm the two new Operations bullets are present.