spirewise 1.7.1 → 1.8.0

package/skills/ai-agent-os-design-system/accessibility-system.md

@@ -0,0 +1,67 @@
+# Accessibility System — AI Agent Operating System
+
+Agent UIs add specific a11y demands: **graphs/timelines** can hide structure, **status** is
+often color-only, **streaming logs** can spam screen readers, and the **command palette** is a
+complex widget. This system bakes WCAG 2.1 AA into the agent-OS craft.
+
+## Agent visuals (graphs / timelines / traces)
+- **Every graph/timeline/trace has a text equivalent.** Provide an ordered `<ol>` (steps +
+  dependencies + status) or `<table>` of the run, referenced via `aria-describedby`, plus a
+  concise `aria-label`/summary ("4-step run: classify → retrieve → draft → send; succeeded").
+  **Prefer building the Run Timeline as a real `<ol>`** — it's accessible by construction.
+- **Agent Graph (SVG):** `role="img"` + `aria-label` + a described text list; nodes that are
+  interactive are real `<button>`/`<a>` (focusable, keyboard-operable) that open the Inspector,
+  with `aria-describedby` to their detail. Don't ship a graph whose only representation is pixels.
+- **Status is never color-only.** Every status = color **+ icon/shape + text label** (the Status
+  Chip). A grayscale view must still convey state.
+- **Contrast:** node/edge/timeline marks ≥ 3:1 from background and adjacent; status text/icons AA.
+
+## Streaming logs / consoles (don't spam SR)
+- Tool-Call Stream / Terminal use `role="log"` with **`aria-live="polite"`** (never `assertive`)
+  so updates are announced calmly; provide a **pause** control for streaming.
+- Real, copyable text (not canvas-only); a labelled scroll region; respect reduced motion
+  (show full output, no typewriter loop).
+
+## Command Palette (complex widget — get it right)
+- Open via **Cmd/Ctrl-K AND a visible button** (don't rely on the shortcut alone).
+- `role="dialog"` + **focus-trap**; input is a combobox (`role="combobox"`, `aria-expanded`,
+  `aria-controls`); results `role="listbox"` / `role="option"` with `aria-activedescendant`;
+  ↑/↓ to move, Enter to run, **Esc to close**; focus returns to the trigger on close.
+
+## Color & contrast (UI)
+- Body ≥ 4.5:1, large/UI ≥ 3:1 on the dark surfaces. The accent doubles as the active-path
+  color and the primary action — keep context clear (label CTAs; the path is in a graph context).
+- Don't convey meaning by color alone anywhere (status, edges, deltas) — pair with icon/label/shape.
+
+## Focus & keyboard
+- **Always-visible focus:** `:focus-visible { outline:2px solid var(--ring); outline-offset:2px }`
+  on every control (nodes, palette, timeline steps, tabs, accordions). No bare `outline:none`.
+- Logical tab order; focusing a node/step scrolls it into view; no traps (except modal/palette
+  focus-trap with Esc). **Skip link** to `#main` first in DOM.
+
+## Semantics & structure
+- One `<h1>` per page; ordered headings. Landmarks `<header><nav><main id="main"><section><footer>`.
+  Runs/sequences `<ol>`; quotes `<blockquote><cite>`; code `<pre><code>`; collapsibles `<details>`
+  or button-driven. Native over ARIA; minimal correct ARIA.
+
+## Motion
+- Honor `prefers-reduced-motion`: run shows final/complete state, no progression replay/pulse/
+  typewriter/edge-flow. No essential run info conveyed only by animation.
+
+## Forms & controls
+- Range/filters/search/inputs have programmatic `<label>`s; errors in text + `aria-describedby`;
+  results announced (`aria-live="polite"`) when a run/filter updates content.
+
+## Touch & responsive
+- **Tap targets ≥ 44×44px** (nodes, palette items, timeline steps, controls); workspace stacks;
+  graphs simplify/scroll; consoles get a labelled scroll region; 200% zoom OK; pinch-zoom not disabled.
+
+## Checklist (run before finishing)
+1. Every graph/timeline/trace: text/list equivalent + `aria` summary; interactive nodes are real
+   focusable controls; status not color-only.
+2. Streaming logs: `role="log"` `aria-live="polite"` + pause; real copyable text.
+3. Command palette: Cmd-K **+** visible button; dialog focus-trap; combobox/listbox semantics; Esc.
+4. AA contrast for text; ≥3:1 for node/edge/status marks; meaning never color-only.
+5. Visible focus on all controls; focusing a node/step reveals it; skip link; logical order.
+6. Reduced motion → final-state run; correct semantics (ol/landmarks/details).
+7. 44px targets; workspace/graph/console reflow; 200% zoom; zoom not disabled.

package/skills/ai-agent-os-design-system/color-system.md

@@ -0,0 +1,102 @@
+# Color System — AI Agent Operating System
+
+A calm **control-room** palette: neutral dark surfaces so the agent mechanics read clearly, a
+single accent that traces the **active path**, and a disciplined **agent status** system
+(running/success/error/waiting/needs-approval/blocked) plus **node/edge** tokens for graphs.
+Ships **control-room dark by default**; a light theme is included. Sections separate via
+surface elevation + tone — **never borders**. Override `--accent` to rebrand. Contrast: text ≥
+4.5:1, status/graph marks ≥ 3:1.
+
+## Tokens (`:root`) — control-room dark (default)
+
+```css
+:root {
+  /* ---- Background / surfaces (neutral; mechanics pop) ---- */
+  --bg-base:   #0a0c10;   /* page */
+  --bg-900:    #0e1116;   /* section */
+  --bg-800:    #12161d;   /* alt section */
+  --surface-1: #141923;   /* panel / card */
+  --surface-2: #1a212d;   /* raised / hover / console header */
+  --surface-3: #222b3a;   /* popover / input / node */
+  --canvas:    #0b0e13;   /* graph/console canvas (slightly deeper) */
+
+  /* ---- Text ---- */
+  --text-primary:   #eef2f8;
+  --text-secondary: #aeb7c7;
+  --text-muted:     #828c9e;   /* log meta, labels */
+  --text-faint:     #58616f;   /* inactive nodes — non-essential */
+  --text-on-accent: #04121f;
+
+  /* ---- Borders / grid (panel + node/edge — NOT between sections) ---- */
+  --border-subtle:  rgba(255,255,255,0.06);
+  --border-default: rgba(255,255,255,0.11);   /* panel/node edges */
+  --grid-line:      rgba(255,255,255,0.05);   /* faint console grid */
+  --ring:           #5b9dff;   /* focus ring */
+
+  /* ---- Accent (the ACTIVE PATH / primary action) ---- */
+  --accent:        #5b9dff;  /* signal blue */
+  --accent-hover:  #74acff;
+  --accent-press:  #4a87ec;
+  --accent-soft:   rgba(91,157,255,0.14);
+  --accent-glow:   0 0 0 1px var(--accent-soft), 0 0 24px rgba(91,157,255,0.25);
+
+  /* ---- AGENT STATUS (color + always paired with icon + label) ---- */
+  --st-queued:  #828c9e; --st-queued-soft:  rgba(130,140,158,0.16);
+  --st-running: #5b9dff; --st-running-soft: rgba(91,157,255,0.16);
+  --st-waiting: #38bdf8; --st-waiting-soft: rgba(56,189,248,0.16);
+  --st-approve: #f5a524; --st-approve-soft: rgba(245,165,36,0.16);  /* needs-approval */
+  --st-success: #2dd4a0; --st-success-soft: rgba(45,212,160,0.16);
+  --st-failed:  #f4516c; --st-failed-soft:  rgba(244,81,108,0.16);
+  --st-blocked: #c0566b; --st-blocked-soft: rgba(192,86,107,0.16);
+
+  /* ---- Graph nodes / edges ---- */
+  --node-bg:      var(--surface-3);
+  --node-border:  var(--border-default);
+  --node-active:  var(--accent);            /* current node */
+  --edge:         rgba(255,255,255,0.18);   /* default connector */
+  --edge-active:  var(--accent);            /* active path edge (glows) */
+  --edge-dashed:  6 6;                       /* dasharray for pending/conditional */
+
+  /* ---- Generic semantic (alerts/badges) ---- */
+  --good: var(--st-success); --warn: var(--st-approve); --bad: var(--st-failed); --info: var(--st-waiting);
+
+  /* ---- Subtle gradient (control-room atmosphere; behind canvas only) ---- */
+  --grad-canvas: radial-gradient(60% 60% at 50% 0%, rgba(91,157,255,0.10), transparent 60%);
+}
+```
+
+## Palette roles
+
+- **Background / surfaces** (`--bg-*`, `--surface-*`, `--canvas`): neutral, layered control-room
+  tones. Panels/cards are the containers; alternate `--bg-900`/`--bg-800` between sections to
+  separate by tone — **never a border**. Graph/console sit on `--canvas`.
+- **Text** (`--text-*`): primary for headings/active labels, secondary body, muted log meta,
+  faint for inactive nodes. Never `--text-faint` for essential content.
+- **Borders / grid** (`--border-*`, `--grid-line`): panel + **node/edge** edges and the faint
+  console grid — these are *inside* components, **not** dividers between page sections.
+- **Accent** (`--accent*`): the **active path / current step** in graphs/timelines AND the
+  primary action. One accent — don't scatter it; it should mean "this is live / do this".
+- **Agent status** (`--st-*`): the heart of the system. Every node/step/run/log line uses a
+  status token **plus an icon + text label** (never color alone). Consistent across all components.
+- **Graph nodes/edges** (`--node-*`, `--edge*`): node fills/borders, default vs active vs dashed
+  (pending/conditional) edges; active edge uses the accent and may glow.
+- **Semantic / gradient:** alerts/badges map to status; one subtle gradient lives behind the
+  graph/console canvas only.
+
+## Usage rules
+
+1. **Neutral UI, meaningful color.** Reserve saturated color for **status** and the **active
+   path**; keep chrome neutral so the run reads clearly.
+2. **Status is never color-only.** Always color + icon + label (see design-principles table).
+3. **One accent = live/primary.** The active edge/node and the primary CTA share the accent;
+   don't use accent for decoration.
+4. **Separate sections with surface/tone + space, not lines.** Mandatory.
+5. **Verify contrast:** text AA; status colors ≥ 3:1 from background and distinguishable for
+   color-blind users (the icon/label carries it regardless).
+
+## Optional light theme
+
+`[data-theme="light"]`: `--bg-base:#f7f9fc; --bg-900:#ffffff; --bg-800:#f1f4f9; --surface-1:#ffffff;
+--surface-2:#f3f6fb; --canvas:#f8fafd; --text-primary:#0a0c10; --text-secondary:#3a4252;
+--text-muted:#5d6678; --grid-line:rgba(10,12,16,0.06); --accent:#2563eb;` + light-tuned status
+hues; re-verify contrast. **Control-room dark is the default identity.**

package/skills/ai-agent-os-design-system/component-library.md

@@ -0,0 +1,147 @@
+# Component Library — AI Agent Operating System
+
+Specs for the 17 required components **plus the agent components** (Agent Graph, Run Timeline,
+Tool-Call Stream, Reasoning Trace, Command Palette, Status Chip, Inspector). Agent visuals are
+**hand-built inline SVG/Canvas/semantic HTML — no graph/charting library** — and **every visual
+has a text/list equivalent**. Each: purpose, anatomy, tokens, states, responsive + a11y. **No
+borders between sections.**
+
+Shared primitives:
+
+```css
+.btn { display:inline-flex; align-items:center; gap: var(--space-2); font-weight:600;
+  font-size:.9375rem; padding: var(--space-2) var(--space-5); border-radius: var(--radius-md);
+  border:1px solid transparent; cursor:pointer; transition: background .15s ease, border-color .15s ease; }
+.btn-primary { background: var(--accent); color: var(--text-on-accent); }
+.btn-primary:hover { background: var(--accent-hover); }
+.btn-secondary { background: var(--surface-2); color: var(--text-primary); border-color: var(--border-default); }
+.panel { background: var(--surface-1); border:1px solid var(--border-default);
+  border-radius: var(--radius-lg); padding: var(--panel-pad); }
+:where(a,button,input,[tabindex]):focus-visible { outline:2px solid var(--ring); outline-offset:2px; }
+```
+
+## ★ Status Chip (used everywhere)
+A mono UPPERCASE chip = **dot/icon + label**, colored by status (`--st-*`). Never color-only.
+```html
+<span class="chip chip--running"><span class="dot" aria-hidden="true"></span> RUNNING</span>
+```
+States: queued · running (pulse) · waiting · needs-approval · succeeded · failed · blocked.
+
+## ★ Agent Graph (inline SVG, no library) + REQUIRED text equivalent
+A node/edge graph of the agent workflow (or multi-agent topology). Anatomy: **nodes** (`.panel`-
+like boxes: agent/tool/step name, status chip, mono label) connected by **edges** (SVG paths;
+default `--edge`, dashed for conditional/pending, **`--edge-active` glowing for the active
+path**). One accent traces the live path; completed nodes recede, failures stand out. Built with
+inline SVG (positions computed in JS or authored). **Provide an ordered list/`<table>` equivalent**
+(steps + dependencies + status) referenced via `aria-describedby`, plus an `aria-label` summary.
+Interactive: nodes focusable/clickable to open the **Inspector**; keyboard-navigable.
+
+## ★ Run Timeline (semantic HTML + SVG accents)
+An ordered timeline of run steps. Each step: index · mono name · **status chip** · duration
+(tabular) · expandable detail (inputs/outputs/tool used/logs). Vertical (mobile/dense) or
+horizontal. Built as an `<ol>` (already accessible) with a connector line; active step
+highlighted, completed muted. This is the most accessible way to show a run — prefer it.
+
+## ★ Tool-Call Stream (console)
+A streaming console (`.console`) of tool invocations: `→ tool.name(args)` then `← result`
+(or error), each with a **status chip** + timestamp (mono, tabular). Auto-scroll while
+"running" (pausable); virtualize/scroll long streams. a11y: it's a log → `role="log"`
+`aria-live="polite"` (polite, not assertive); real text, copyable.
+
+## ★ Reasoning Trace
+A collapsible step trace: `Plan → Thought → Action → Observation …`, mono, indented, each
+collapsible. Shows the agent's reasoning honestly (and where humans approve). a11y: nested
+`<ol>`/`<details>`; expandable by keyboard.
+
+## ★ Command Palette (Cmd/Ctrl-K)
+A modal palette to run agents/commands: search input + grouped results + keyboard nav (↑/↓/
+Enter, Esc). The signature agent-OS interaction. a11y: `role="dialog"` + focus-trap, listbox
+semantics (`role="listbox"/"option"`, `aria-activedescendant`), Cmd/Ctrl-K + a visible button
+to open it (don't rely on the shortcut alone).
+
+## ★ Inspector
+A side `.panel` showing the selected node/step: name, status, inputs, outputs, tool schema,
+logs, timing. Updates on node selection. Keyboard-reachable.
+
+---
+
+## 1. Navbar
+Sticky, neutral bar; gains subtle background on scroll. Logo · nav links · **Cmd-K** hint
+button · primary CTA + "Sign in" · mobile hamburger. **Extensionless hrefs**. Optional product
+mega-menu. Mobile: overlay, focus-trap, ESC. a11y: `aria-current`, `aria-expanded`.
+
+## 2. Hero
+Layout AH-A/AH-B/AH-C — copy + CTAs + an **agent workspace / run / terminal** preview. One H1,
+one primary CTA (distinct from status/accent-path color). Leads with the real mechanic; coherent example run.
+
+## 3. Feature Grid
+`.grid.cols-3` of `.panel`s (icon · H3 · body), or **F-C** feature + a live mini graph/run per
+feature. Hover lift.
+
+## 4. Bento Grid
+An agent bento: a graph tile + run-timeline tile + status/metric tiles, varied spans, one anchor.
+
+## 5. Testimonials
+Quote cards, optionally paired with a customer **run result** (e.g., "resolves 62% of tickets
+autonomously"). `<blockquote>` + `<cite>`.
+
+## 6. Logos Section
+"Trusted by" + logo row (monochrome), generous spacing. `<img alt>`.
+
+## 7. Pricing
+Layout P-A/P-B. Tiers (run/seat/usage based) as `.panel`s; price tabular; highlighted tier +
+"Most popular"; usage/seat toggle; maybe a small runs-included meter. a11y: real switch/radio.
+
+## 8. FAQ
+Accordion; `<button>` + collapsible answer. a11y: `aria-expanded`/`aria-controls`.
+
+## 9. CTA
+Centered band, big H2, primary CTA (accent — note it doubles as the active-path color, so keep
+context clear) + secondary. `--section-y-lg`, no border.
+
+## 10. Footer
+Mega footer: brand · columns · status page link · legal · social. `<footer>`, `<nav>` lists.
+
+## 11. Dashboard Preview
+The **agent console shell** (Layout APP): sidebar (agents/runs/tools) + top bar (Cmd-K, status)
++ workspace (graph + inspector + timeline) with realistic data. The centerpiece product visual.
+
+## 12. Agent Workflow Section
+The required component — render it as an **Agent Graph** and/or **Run Timeline** with a coherent
+example (e.g., Plan → Retrieve → Act → Verify → Handoff). Active path glows; status throughout.
+a11y: `<ol>` text equivalent + graph `aria` summary.
+
+## 13. Code Preview
+Mono code (define/invoke an agent, tool schema, SDK) in a window-framed `.panel` with copy.
+`<pre><code>`; pair with the run it produces where apt.
+
+## 14. Terminal Preview
+CLI invoking an agent (`agent run "…"`) streaming output; mono; optional typewriter (reduced
+motion → final). Real text.
+
+## 15. Trust Section
+A **status/metric** band: success rate, avg run time, tool calls/day, uptime — mono tabular
+numbers + status chips; count-up on reveal (final value in DOM). The agent trust beat.
+
+## 16. Security Section
+Compliance badges (SOC 2/ISO/GDPR/HIPAA) + agent-specific assurances: **guardrails,
+human-in-the-loop approvals, sandboxing, audit logs, permissions/scopes, data residency** as a
+clean list + "Security docs" link. Badges alt text. (Critical for agent products.)
+
+## 17. Enterprise Section
+"Built for enterprise" panel: SSO/RBAC/SLAs/VPC/on-prem + agent governance (approval policies,
+spend limits, audit) + "Talk to sales" CTA. No border.
+
+---
+
+## Component rules
+- **Agent visuals are inline SVG/Canvas/semantic HTML, library-free, coherent (no gibberish),
+  and each has a text/list equivalent** + `aria` summary; **status is never color-only** (chip =
+  color + icon + label).
+- Compose from shared `.btn`/`.panel`/`.console`/tokens + the status system — no graph libraries.
+- Every interactive element (nodes, palette, sort, tabs, timeline steps) has hover **and**
+  `:focus-visible` and is keyboard-operable.
+- Every component reflows: workspace stacks; consoles/timelines scroll; graphs simplify by `md`/`sm`.
+- Decorative chrome `aria-hidden`; informative visuals keep alt/text equivalents.
+- Restraint: neutral UI; the accent = active path/primary action only; no AI-magic clichés;
+  panel/node edges are inside components — **never between page sections**.

package/skills/ai-agent-os-design-system/design-principles.md

@@ -0,0 +1,79 @@
+# Design Principles — AI Agent Operating System
+
+The philosophy distilled from agentic/dev-tool references (Cursor, Cognition/Devin, Sierra,
+Lindy, Manus, LangGraph, Replit, Linear, Vercel) and modern AI sites (OpenAI, Anthropic,
+Perplexity). The standard: a website that feels like a **real operating system for agents** —
+precise, transparent, and trustworthy — not an "AI magic" gimmick.
+
+## The one-sentence philosophy
+
+**Show the agent thinking and acting.** Render the product's real mechanics — plans, steps,
+tools, handoffs, states, and outcomes — in a calm control-room UI, so visitors *understand and
+trust* how the agent works.
+
+## Core principles
+
+1. **Render the mechanics, don't illustrate them.** Lead with the actual model — an **agent
+   graph**, a **run timeline**, a **tool-call stream**, a **reasoning trace**, a **command
+   palette** — using realistic example data, not abstract glowing orbs.
+2. **Status is the core language.** Every agent/step/run has a state: `queued · running ·
+   waiting · needs-approval · succeeded · failed · blocked`. A single, consistent **status
+   system** (color + icon + label) appears in graphs, timelines, logs, and tables.
+3. **Transparency = trust.** Show the plan before the result, the tools the agent used, the
+   human-in-the-loop approvals, and the guardrails. Enterprises buy agents they can audit.
+4. **Calm control room.** Dark, precise, monospace-accented tooling aesthetic — dense but
+   legible. One accent traces the **active path / current step**; everything else is neutral.
+5. **Trace the flow.** Make the path obvious: the active edge glows, the current step
+   highlights, completed steps recede, failures stand out. The eye should follow the run.
+6. **Coherent, real example runs.** Use a concrete scenario end-to-end (e.g. "resolve a
+   support ticket": classify → retrieve → draft → get approval → send). Never gibberish steps.
+7. **Honest about autonomy.** Distinguish autonomous vs human-approved actions; show where the
+   human is in the loop. Don't overclaim "fully autonomous magic."
+8. **Density done right.** Logs, traces, and graphs are information-dense; strict alignment,
+   monospace, and consistent status make density calm rather than chaotic.
+9. **Developer-credible.** Real-looking code/SDK snippets, tool schemas, and API calls signal a
+   genuine platform (Cursor/Replit/LangGraph energy).
+10. **Accessible by construction.** Every graph/timeline/trace has a text equivalent; status is
+    never color-only; the command palette and interactive runs are keyboard-navigable.
+
+## The status system (use everywhere)
+
+| State | Meaning | Encoding (color + icon + label) |
+|---|---|---|
+| queued | waiting to start | neutral · ◦ · "Queued" |
+| running | in progress | accent/info · ▷ (pulse) · "Running" |
+| waiting | on a dependency/tool | info · ⋯ · "Waiting" |
+| needs-approval | human-in-the-loop | warn · ◆ · "Needs approval" |
+| succeeded | done OK | good · ✓ · "Succeeded" |
+| failed | errored | bad · ✕ · "Failed" |
+| blocked | can't proceed | bad/neutral · ▣ · "Blocked" |
+
+Always pair color with the icon **and** the text label — never color alone.
+
+## Visual-hierarchy laws
+
+- **One H1 per page**; in an agent view, the **active run / primary graph** is the focal point.
+- **Goal → plan → run → outcome.** Lead a section with the goal, then the plan/graph, then the
+  timeline/logs, then the result.
+- **Contrast ladder:** active step brightest, completed steps muted, pending faint; the accent
+  marks only the active path.
+- **One primary CTA per viewport** (distinct from status/accent-path color).
+- **Group with panels + the grid**, not borders between sections.
+- **Accent = the live path / primary action** — don't scatter it across the series.
+
+## Reference cues (what each does well)
+
+- **Cursor / Replit / Cognition:** real code/agent runs, IDE-grade UI, dev credibility.
+- **Sierra / Lindy / Manus:** agent workflows, handoffs, human-in-the-loop, enterprise tone.
+- **LangGraph:** the graph-of-agents mental model rendered clearly.
+- **Linear / Vercel:** precise, calm, fast product polish to wrap it all in.
+
+## Do / Don't
+
+**Do:** render real mechanics (graph/timeline/tool stream/trace/palette) · a consistent status
+system (color+icon+label) · trace the active path with one accent · coherent example runs ·
+show human-in-the-loop + guardrails · dense-but-legible mono UI · text equivalents for visuals.
+
+**Don't:** glowing brains/orbs/sci-fi clichés · gibberish/fake agent steps · status by color
+alone · graphs/timelines without text equivalents · over-animated chaos that hides the run ·
+overclaiming autonomy · borders between sections · heavy gradients/glass · library-built graphs.

package/skills/ai-agent-os-design-system/example-page-structures.md

@@ -0,0 +1,93 @@
+# Example Page Structures — AI Agent Operating System
+
+Ready-to-assemble, **agent-mechanic-led** page blueprints. Each section names a layout (see
+`layout-system.md`) and components (see `component-library.md`). Lead with the product's real
+mechanics (graph / run timeline / tool stream / trace); keep the UI neutral with one accent
+tracing the active path; **every agent visual has a text/list equivalent**; coherent example
+runs throughout. No borders between sections (separate by whitespace + surface elevation + tone).
+
+Legend: `AH-* / GR / RT / TS / RTr / MG / F-* / P-* / C-* / Q-* / FT-*` layouts · components by name.
+
+## MANDATORY: 15+ page site map (≈20), 10+ sections/page, clean URLs
+
+Always ship a **full multipage website with 15+ pages (≈20)** — never a single landing page.
+Every page carries **at least 10 sections (≈12)**, **no borders/dividers between sections**, pure
+HTML/CSS/vanilla JS (**graphs/timelines = inline SVG/Canvas/semantic HTML, no library**),
+**extensionless URLs**. Required 20-page map:
+
+```
+/                Home              /customers      Customers
+/platform        Platform          /case-studies   Case Studies
+/solutions       Solutions         /developers     Developers
+/products        Products          /docs           Documentation  ← + DOC-A subpages
+/features        Features          /about          About
+/ai-agents       AI Agents         /careers        Careers
+/enterprise      Enterprise        /blog           Blog           ← + article pages
+/security        Security          /contact        Contact
+/pricing         Pricing           /partners       Partners
+                                   /resources      Resources   /faq  FAQ
+```
+
+Each blueprint below is a **10-section** skeleton — extend toward 12, never fewer than 10. Every
+page must include: **Hero (workspace/run) · Feature Sections · Product Highlights · Trust Signals
+· Testimonials · Use Cases · Statistics · Integrations · CTA · Footer.**
+
+---
+
+## 1. Home (default)
+1. **Navbar** (+ Cmd-K trigger) — extensionless links
+2. **Hero** `AH-A` — copy + CTAs + **agent workspace** preview (Agent Graph, active path glowing + mini Run Timeline)
+3. **Logos Section** — trusted-by row
+4. **Agent Workflow** — **Agent Graph** of a real example (Plan → Retrieve → Act → Verify → Handoff)
+5. **Run Timeline** `RT` — the same run as a step timeline (status + durations + logs)
+6. **Tool-Call Stream** `TS` — streaming console of tool invocations
+7. **Statistics** — status/metric band (success rate, avg run time, tool calls/day; count-up)
+8. **Testimonials** — quote + a customer run result
+9. **Pricing** `P-A` (or teaser) — run/seat/usage tiers
+10. **CTA** `C-A` + **Footer** `FT-A`
+
+## 2. Platform / Product
+1. Navbar · 2. **Hero** `AH-A` (workspace) · 3. **Graph + Inspector** `GR` · 4. **Run Timeline**
+`RT` · 5. **Tool-Call Stream** `TS` · 6. **Dashboard Preview** (agent console shell) · 7.
+Feature `F-B` (copy↔run) · 8. Integrations · 9. Statistics/trust · 10. CTA + Footer
+
+## 3. AI Agents / Features
+1. Navbar · 2. **Hero** `AH-B` (a live run) · 3.–8. feature sections each pairing copy with the
+relevant mechanic (graph, timeline, tool stream, reasoning trace, multi-agent handoff `MG`,
+command palette) · 9. Integrations · 10. CTA + Footer
+
+## 4. Developers / Documentation
+- **Developers:** Navbar · **Hero** `AH-C` (**Command Palette / Terminal** invoking an agent) ·
+  Logos · **Code Preview** (define/invoke an agent, tool schema) + the run it produces · Feature
+  grid · Use Cases · Statistics (API/agent metrics) · CTA ("Read docs"/"Get API key") · Footer (≥10).
+- **Docs:** `DOC-A` three-pane; inline graphs/run-timelines + their `<ol>` equivalents; mono code;
+  breadcrumb; sticky nav.
+
+## 5. Enterprise / Security
+1. Navbar · 2. Hero (outcome-led + a governed run) · 3. Logos · 4. Feature `F-B` · 5.
+**Enterprise** (SSO/RBAC/SLAs/VPC + agent governance: approvals, spend limits, audit) · 6.
+**Security** (guardrails, human-in-the-loop, sandboxing, audit logs, compliance badges) · 7.
+Statistics (uptime/success) · 8. Testimonials (exec) · 9. CTA (contact) · 10. Footer
+
+## 6. Pricing
+1. Navbar · 2. Hero (short + plan/usage toggle) · 3. **Pricing** `P-A/P-B` (run/seat/usage tiers
+with a runs-included meter) · 4. Feature/usage comparison · 5. Enterprise band · 6. Logos · 7.
+Statistics · 8. Testimonials · 9. **FAQ** `Q-A` · 10. CTA + Footer
+
+## 7. Content pages (About, Customers, Case Studies, Careers, Blog, Partners, Resources, Contact, FAQ)
+Reach **≥10 sections** using agent mechanics where they help: Hero → body (customer logo grid,
+**case-study with a real example run + result metrics**, values, open roles, article list, partner
+tiers, resource cards, contact form) → Trust Signals → Statistics → Testimonials → Integrations →
+CTA → Footer. Case studies especially lead with **a coherent example run + outcome metrics**.
+
+---
+
+## Assembly notes
+- **Scale is mandatory:** 15+ pages, **≥10 sections each**. Never a single/thin page.
+- **Lead with real mechanics** (goal → plan → run → outcome); one coherent example run across a
+  page's agent visuals; consistent **status system**; **every visual has a text/list equivalent**.
+- **Neutral UI, one accent for the active path/primary action;** mono for logs/traces/labels;
+  no AI-magic clichés; honest about human-in-the-loop.
+- **No borders/dividers between sections** — whitespace + surface elevation + tone. Node/edge/
+  panel borders live inside components.
+- Use **real, plausible runs/data** (not gibberish steps); mark guesses `[PLACEHOLDER]`.

package/skills/ai-agent-os-design-system/layout-system.md

@@ -0,0 +1,74 @@
+# Layout & Grid System — AI Agent Operating System
+
+A 12-column fluid grid + canonical **agent-OS** layouts. Data/agent sections use compact
+control-room layouts (graph + inspector, run timeline, console); marketing sections are airier.
+**No borders between sections.**
+
+## Grid
+
+```css
+:root { --grid-cols: 12; --grid-gap: var(--panel-gap); }
+
+.grid { display: grid; gap: var(--grid-gap);
+        grid-template-columns: repeat(var(--grid-cols), 1fr); }
+.cols-2 { grid-template-columns: repeat(2, 1fr); }
+.cols-3 { grid-template-columns: repeat(3, 1fr); }
+.cols-4 { grid-template-columns: repeat(4, 1fr); }
+.split  { grid-template-columns: 1fr 1fr; }
+/* Agent workspace: canvas + side inspector */
+.workspace { grid-template-columns: 1fr 320px; }
+.span-8{grid-column:span 8} .span-4{grid-column:span 4} .span-6{grid-column:span 6}
+@media (max-width:1024px){ .workspace{grid-template-columns:1fr} .span-8,.span-4{grid-column:span 12} }
+@media (max-width:760px){ .split,.cols-2{grid-template-columns:1fr} }
+@media (max-width:900px){ .cols-3,.cols-4{grid-template-columns:repeat(2,1fr)} }
+```
+
+Breakpoints: `sm 480` · `md 768` · `lg 1024` · `xl 1280` · `2xl 1440`. Mobile-first; the
+agent workspace collapses (inspector moves below the graph); consoles scroll; graphs reflow.
+
+## Canonical layouts
+
+### Hero
+- **AH-A Workspace hero (default):** copy + CTAs on one side; an **agent workspace** preview on
+  the other (or full-width below) — an **Agent Graph** with the active path glowing + a small
+  **Run Timeline**. Leads with the product's real mechanic.
+- **AH-B Run hero:** a single live **Run Timeline / Tool-Call Stream** front and center (a real
+  example run streaming/progressing).
+- **AH-C Terminal hero:** a **Command Palette / Terminal** invoking the agent (Cursor/Replit feel).
+
+### Agent sections
+- **GR Graph + inspector:** `.workspace` — Agent Graph (canvas) + a side **Inspector** panel
+  (selected node's tools/inputs/outputs/status).
+- **RT Run timeline:** a vertical/horizontal timeline of steps with states + durations + logs.
+- **TS Tool-call stream:** a streaming console of tool invocations (name, args, result, status).
+- **RTr Reasoning trace:** a collapsible step-by-step trace (plan → thought → action → observe).
+- **MG Multi-agent handoff:** lanes/columns per agent showing handoffs between them.
+
+### Feature / marketing
+- **F-A 3-up feature cards** · **F-B alternating copy↔agent-visual** · **F-C feature + live mini graph/run**.
+
+### Pricing / CTA / FAQ / Footer
+- **P-A 3-tier** (middle highlighted; usage/run-based tiers) + toggle; **P-B 2-tier + enterprise**.
+- **C-A CTA band** (distinct from status/accent-path color). **Q-A Accordion FAQ.** **FT-A Mega footer.**
+
+### App / Docs
+- **APP Agent console shell:** left sidebar (agents/runs/tools) + top bar (command palette,
+  status) + the workspace — the in-product layout shown in previews.
+- **DOC-A Three-pane docs:** nav · prose (`--container-md`) · TOC; inline graphs/traces; mono
+  code; breadcrumb.
+
+## Composition rules
+
+1. **Separate sections by surface/tone + space, NEVER borders.** Alternate `--bg-900`/`--bg-800`
+   (add `.section--alt`); `.section{border:0}`; no `<hr>`. Node/edge borders, timeline
+   connectors, and panel edges are *inside* components — not section dividers.
+2. **Lead agent sections with the goal**, then plan/graph, then run timeline/logs, then outcome
+   (goal → plan → run → result). One primary agent mechanic per section.
+3. **Trace the active path.** In every graph/timeline, the active node/edge uses the accent;
+   completed steps recede; failures stand out (status system).
+4. **Coherent example runs.** Use one realistic scenario across the page's agent visuals.
+5. **At least 10 sections per page**, **15+ pages.** Never thin.
+6. **Rhythm:** workspace hero → logos/trust → graph+inspector → run timeline → tool stream →
+   feature (copy↔run) → metrics/trust → security → pricing → FAQ → CTA → footer.
+7. **Reflow:** workspace → stacked (graph then inspector); consoles/timelines get a labelled
+   scroll region; graphs simplify (fewer nodes / horizontal scroll) on mobile; no page h-scroll.

package/skills/ai-agent-os-design-system/motion-system.md

@@ -0,0 +1,85 @@
+# Motion System — AI Agent Operating System
+
+Motion here **shows the agent working** — a run progresses, nodes activate along the path,
+tool output streams, status pulses. It's precise and purposeful (not decorative), and never
+required to understand the run. Everything degrades under `prefers-reduced-motion`.
+
+Distilled from Cursor/Replit (live runs, streaming), Linear/Vercel (crisp micro-interactions),
+and OpenAI/Anthropic/Perplexity (calm restraint).
+
+## Tokens
+
+```css
+:root {
+  --dur-fast: 120ms;   --dur-base: 220ms;  --dur-slow: 380ms;  --dur-run: 600ms;
+  --ease-out: cubic-bezier(0.2, 1, 0.3, 1);
+  --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
+  --pulse: 1.6s;       /* running-status pulse loop */
+}
+```
+
+## Principles
+1. **Motion narrates the run.** Animate to show progression (active node/edge advancing, steps
+   completing, output streaming) — clarity, not flair.
+2. **Short + eased** for UI (120–380ms); a run progression beat ~600ms per step.
+3. **Compositor-friendly + cheap:** `transform`/`opacity`/`stroke-dashoffset`; rAF-throttle
+   scroll; `IntersectionObserver` for reveal/start.
+4. **One run animates at a time** in view; don't animate every graph simultaneously.
+5. **Final state is the truth.** With motion off, the run shows its final/complete state (all
+   steps + statuses), fully readable.
+
+## Patterns
+
+- **Run progression (signature):** on reveal, the example run advances step-by-step — each step's
+  status chip flips queued→running→succeeded, the **active edge** draws (`stroke-dashoffset`) to
+  the next node, the current node highlights. Loops once or plays then settles complete.
+- **Node activation:** the active node lifts/glows (`--accent-glow`), prior nodes recede to muted;
+  a failed node flashes the `--st-failed` state once then holds.
+- **Running pulse:** `running` status chips/dots pulse subtly (`--pulse` opacity/scale loop) —
+  the only looping motion; stops when the step completes (and under reduced motion).
+- **Streaming output:** tool-call stream / terminal lines append with a quick fade; optional
+  stepped typewriter for a command. Auto-scroll while running (pausable).
+- **Edge flow (optional):** a faint dashed-offset animation along the active edge to imply data
+  flow — subtle, off for reduced motion.
+- **Reveal:** sections/panels fade-rise on enter (IO), gentle stagger.
+- **Hover:** panel/node lift, button bg shift, row hover; command-palette open/close fade+scale.
+- **Count-up (metrics):** quick mono roll; final value in DOM.
+- **Nav:** subtle background/shadow after ~24px scroll.
+
+## Reduced motion (required)
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after { animation-duration:.001ms !important;
+    animation-iteration-count:1 !important; transition-duration:.001ms !important;
+    scroll-behavior:auto !important; }
+}
+```
+Under reduced motion: render the run in its **final/complete state** (all steps + final
+statuses), no progression replay, no pulse/edge-flow/typewriter/count-up loops; streaming shows
+the full output immediately. The run is fully understandable without any motion.
+
+## Minimal vanilla helpers
+
+```js
+const RM = matchMedia('(prefers-reduced-motion: reduce)').matches;
+// start the example run when it scrolls into view (else show final state)
+const io = new IntersectionObserver((es)=>es.forEach(e=>{ if(e.isIntersecting){
+  const el=e.target;
+  if(RM) el.classList.add('run--final');     // all steps complete, no animation
+  else   playRun(el);                         // step through statuses with timers/rAF
+  io.unobserve(el);
+}}, {threshold:.4});
+document.querySelectorAll('[data-run]').forEach(el=>io.observe(el));
+```
+```css
+.chip--running .dot { animation: pulse var(--pulse) ease-in-out infinite; }
+@keyframes pulse { 0%,100%{ opacity:1 } 50%{ opacity:.4 } }
+[data-reveal]{ opacity:0; transform: translateY(14px);
+  transition: opacity var(--dur-slow) var(--ease-out), transform var(--dur-slow) var(--ease-out); }
+[data-reveal].in{ opacity:1; transform:none; }
+.edge.is-active{ stroke: var(--edge-active); stroke-dasharray: var(--len); stroke-dashoffset: var(--len);
+  transition: stroke-dashoffset var(--dur-run) var(--ease-out); }
+.edge.is-active.drawn{ stroke-dashoffset: 0; }
+@media (prefers-reduced-motion: reduce){ .chip--running .dot{ animation:none } }
+```