# Example-Site Specification Draft Status: draft for review. Source: synthesis of workflow evidence P1-P6 (structure, tests, OpenAPI drift, reference-site reuse, error/UX audit, falsification gaps). No live probes were run; counts and bodies cited below are source/grep-level and need the falsification reruns in Section 11 before this becomes normative. Conventions: MUST/SHOULD/MAY per RFC 2119. This spec wins over code on conflict until amended in the same change. ## 1. Scope, goals, non-goals Goals: - One example site that demonstrates every framework module through a consistent shell, nav, page, form, error, and JS contract. - Commercial and scientific tone: direct, factual, user friendly; no complexity pushed to the visitor. - Responsive at 360px viewport minimum; narrow screens get dropdowns/collapse, never hidden nav with no fallback. - Fully specified: every shared component, envelope, tag, and automation gate is declared here. Non-goals: - Production auth hardening and threat modeling (out of scope for now). - Live vendor calls in default suite (paid/live routes stay dry-run or skipped without keys/network). - Rewriting framework modules; the example consumes them via the documented demo mounts. ## 2. Quality standards, coverage targets, caps, floors ### 2.1 Test standard - Example suite is integration-only; isolated unit tests are forbidden. Arrange/Act/Assert with Fixture plus TestClient, PASS:/FAIL: protocol (tests/README.md). - Target: `example suite: 265 passed, 0 failed` (AGENTS.md). Current inventory: 265 files under tests/example, 285 under tests/src. Any count change MUST update this spec plus AGENTS.md in the same change. - Per-route minimum (4 cases): happy path, auth-fail or 404/405, validation/422, limit/edge. Applies to every mounted route including /readyz, /startupz (currently misplaced in probes_test.cpp; MUST move to tests/example/readyz and tests/example/startupz). - Matrix test: GET every index href, require 2xx/3xx (401 allowed only for /auth/me), minimum row count declared (today >=37; index catalog carries ~40 features in 16 groups). - Loud skips: unverifiable input is rejected with reason plus counter, never silently stored. ### 2.2 Build and lint gates - Warning-free build with -std=c++23 -Wall -Wextra everywhere. -Werror MUST be universal; today it is missing in example, app, data, cli, observability, realtime, tenancy, audit, governance, supplychain .mk files. Closing that gap is required. - `make lint` = warning-free build plus repo-wide em-dash grep. No tidy/sanitizer/format/coverage gate exists today; until one lands, the lint target is the gate and MUST stay green. - Pipeline order: lint -> suite -> bump -> changelog -> commit -> tag -> deploy -> verify. Timeout 30 min, then escalate. ### 2.3 Coverage targets - Route coverage: 100 percent of mounted router registrations reachable from index matrix or docs table, or explicitly listed as excluded (paid/live prefixes /voice, /google, /agent, /ai excluded from locust by design). - OpenAPI coverage: 100 percent of mounted routes appear in served spec (today 3 manual adds vs ~490 registrations; see Section 9). - Component coverage: every named component in Section 5 has at least one route-level test rendering it. - JS coverage: every shipped asset JS file has a route test that loads its page plus a simulated POST exercising its err/out path. ### 2.4 Caps (static ceilings, no autotuning) - Suite: 10 min total, 30 s single test, zero flakes (tests/README.md). - HTTP demo payloads: 64 KB request body, 256 KB response body, 100 items per list page default. - Rate: 60 req/min per demo write endpoint when loopback deployed; 429 with Retry-After on breach. - Embedded bundle: 5 MB total under example/assets; single asset 512 KB max. - Gate output panels: 200 lines max with truncation notice; stats tiles: 12 max. - Locust headless run: 60 s, 10 users default. ### 2.5 Floors (never crossed alone; dry-run, stop, page human) - Protected: specs/, CHANGELOG.md, VERSION, git tags, retention windows, destructive file deletes, history rewrite, force push, hard reset. - Docs/off behavior: doc routes disabled by default in prod (prod 404 test required). - Destructive/paid demo calls: dry-run by default, explicit confirm to execute; no auto-spend. - Release: max 1 release per green run; failed live verification blocks tag. ## 3. Whole-site structure ### 3.1 Information architecture - Single shell (base.html) with sticky masthead, main, footer. One shell template only; merge page.html, ent_page.html, platform_page.html into one. - Global topbar MUST cover all 16 index groups (today only 7 links: Index/Templates/Forms/Stats/Voice/Docs/Health). Groups: routing, requests, data, security, static, realtime, observability, operations, doos, tenancy, audit, governance, google(+voice), agent, vendors(/ai), tools, plus Other fallback. Narrow screens use the existing details-dropdown pattern (keep; it beats the reference-site nav-hide). - Index page: grouped matrix via IndexCatalog render, filter input (no-JS safe), needs-API-key badges on google/agent/vendors groups. - Every detail page: section-head (numeral + lede), breadcrumbs (Index / Group / Page), back-link, section nav where page has 2+ sections. - Docs page: filterable register table (see Section 5), not a plain list. - Static vs embedded: example/static holds shell CSS/JS (app.css, app.js, index.js); example/assets holds per-demo JS bundled to build/example/gen/assets.cpp and served under /embedded/{name}. ### 3.2 Route map (mount contract) - Core: / (index), /health, /readyz, /startupz, /metrics, /telemetry, /routing*, /orm/users, /kv/items, /cache/lookup, /pubsub/publish, /auth/*, /sessions/*, /security/*, /security-extra/*, /formats/data, /templates/page, /forms/contact, /validate/user, /ws, /socketio, /sse, /streaming, /webdav, /expose, /supervisor/*, /restclient, /clients/*, /operability/*, /cli/*, /workflow/release, /supplychain/sbom.json, /openapi.json, /docs, /stats, /stats/data, /voice, /voice/say|hear|turn|reset, /google/status, /doos, /doos/status, /doos/create, /doos/delete, /tenancy/*, /audit/*, /governance/*, /v1|v2/items. - Agent (9, /agent/): models, runtime, sessions, sandbox, registry, armor, optimize, adk, live. - AI (20, /ai/): xai, xaiplatform, anthropic, anthropicadmin, meta, deepseek, openai, openaiplatform, openaiadmin, openrouter, compat, mistral, cohere, perplexity, bedrock, azure, huggingface, audio, media, retrieval. - Google (7, /google/): discovery, cloudai, enterprise, data, maps, workspace, ops. - Contract for agent/ai/google: GET page plus status returns 2xx always; POST/DELETE without key returns 503 with machine-readable not_configured/google_not_configured; validation failures return 422; paid/destructive runs dry-run unless confirm:true. - Doos: GET page, GET status JSON, POST create, POST delete with confirm=yes (else dry-run). Demo store: DOOS_HOME else build/doos-demo. ### 3.3 Build, deploy, verify-live - Standalone: make -f example/example.mk example|example-test|example-clean|example-locust. Whole repo: make, make test, make lint via root Makefile aggregation. - Deploy: loopback living-server on EXAMPLE_PORT (default 8000), pid build/example/run/server.pid, health-gated; verify via tools/verify_deploy.py. - Verify-live gate (manual today, MUST stay manual until wired): health probe, /metrics scrape, index 360px markup checks (viewport meta, .nav-narrow collapse), crawl first 10 matrix links. Any red step halts the pipeline. ## 4. Per-module look (page contract) Every demo page MUST follow this skeleton in order: 1. Breadcrumbs plus section-head (numeral, title, one-line lede, status pill if the module has state). 2. Config/status strip: molo-config-status element (configured/not-configured/live/dry-run) for key-gated modules. 3. How-it-works block: steps or tabs plus callout for paid/dry-run notes. 4. Interactive form(s): shared FormView builder only (Section 7); one primary submit; confirm control per Section 7 for paid/destructive. 5. Output area: molo-json-out (codeblock in panel-dark) plus molo-alert region; run-button triggers fetch; output capped at 200 lines. 6. Reference row: link to /docs entry plus OpenAPI operation id. Look rules: - One section class vocabulary from Section 5; no per-vendor invented section classes or id prefixes. - No page-local