workweaver 0.1.0__py3-none-any.whl

apps/landing/tests/e2e/test_checkout_flow.spec.ts

@@ -0,0 +1,439 @@
+/**
+ * E2E Test: Stripe Checkout Flow
+ *
+ * Tests the complete signup → Stripe Checkout → onboarding flow.
+ *
+ * Reference: WORKPLAN.md TASK-6.0B.002
+ * Legacy requirement reference: P1.7B.1 — Sign-Up Flow (Stripe + Auth)
+ *
+ * Test Coverage:
+ * 1. Email signup → verification → Stripe Checkout redirect
+ * 2. Google OAuth signup → Stripe Checkout redirect
+ * 3. Stripe Checkout success → redirect to onboarding
+ * 4. Stripe Checkout cancel → return to signup
+ * 5. Tenant context preservation through the flow
+ * 6. sessionStorage cleanup after completion
+ */
+
+import { test, expect, Page, BrowserContext } from '@playwright/test';
+
+/**
+ * Test configuration
+ */
+const API_BASE_URL = process.env.API_BASE_URL || 'http://localhost:8000/api/v1';
+const LANDING_URL = process.env.LANDING_URL || 'http://localhost:3000';
+const DASHBOARD_URL = process.env.DASHBOARD_URL || 'http://localhost:3001';
+
+/**
+ * Test data
+ */
+const TEST_USER = {
+  email: `test-${Date.now()}@example.com`,
+  password: 'TestPassword123!',
+  name: 'Test User',
+};
+
+const TEST_VERIFICATION_CODE = '123456'; // Mock code for testing
+
+/**
+ * Helper: Mock email signup API
+ */
+async function mockEmailSignup(page: Page, userEmail: string) {
+  await page.route(`${API_BASE_URL}/auth/signup/email`, async (route) => {
+    await route.fulfill({
+      status: 202,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        detail: 'Verification code sent to email',
+        email: userEmail,
+      }),
+    });
+  });
+}
+
+/**
+ * Helper: Mock email verification API
+ */
+async function mockEmailVerification(page: Page, userEmail: string) {
+  await page.route(`${API_BASE_URL}/auth/signup/email/verify`, async (route) => {
+    const mockTenantId = `TENANT#${Date.now()}`;
+    const mockUserId = `USER#${Date.now()}`;
+    const mockCheckoutUrl = `${LANDING_URL}/checkout-success.html?session_id=test_session_${Date.now()}&tenant_id=${mockTenantId}`;
+
+    await route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        tenant_id: mockTenantId,
+        user_id: mockUserId,
+        email: userEmail,
+        status: 'pending_payment',
+        role: 'admin',
+        auth_provider: 'email_password',
+        next_step: 'stripe_checkout',
+        stripe_checkout_url: mockCheckoutUrl,
+      }),
+    });
+  });
+}
+
+/**
+ * Helper: Mock Google OAuth signup API
+ */
+async function mockGoogleOAuth(page: Page, userEmail: string) {
+  await page.route(`${API_BASE_URL}/auth/signup/google`, async (route) => {
+    const mockTenantId = `TENANT#${Date.now()}`;
+    const mockUserId = `USER#${Date.now()}`;
+    const mockCheckoutUrl = `${LANDING_URL}/checkout-success.html?session_id=test_session_${Date.now()}&tenant_id=${mockTenantId}`;
+
+    await route.fulfill({
+      status: 201,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        tenant_id: mockTenantId,
+        user_id: mockUserId,
+        email: userEmail,
+        status: 'pending_payment',
+        role: 'admin',
+        auth_provider: 'google',
+        next_step: 'stripe_checkout',
+        stripe_checkout_url: mockCheckoutUrl,
+      }),
+    });
+  });
+}
+
+/**
+ * Test 1: Email signup → verification → Stripe Checkout redirect
+ */
+test('should complete email signup, verify email, and redirect to Stripe Checkout', async ({ page }) => {
+  // Setup mocks
+  await mockEmailSignup(page, TEST_USER.email);
+  await mockEmailVerification(page, TEST_USER.email);
+
+  // Navigate to signup page
+  await page.goto(`${LANDING_URL}/signup`);
+
+  // Fill out signup form
+  await page.fill('#name', TEST_USER.name);
+  await page.fill('#email', TEST_USER.email);
+  await page.fill('#password', TEST_USER.password);
+
+  // Submit form
+  await page.click('#emailSubmitBtn');
+
+  // Wait for toast notification
+  await expect(page.locator('.toast.visible')).toBeVisible();
+  await expect(page.locator('#toastTitle')).toContainText('Check Your Email');
+
+  // Should redirect to verification page
+  await expect(page).toHaveURL(/\/verify\.html/);
+
+  // Verify email display
+  await expect(page.locator('#emailDisplay')).toContainText(TEST_USER.email);
+
+  // Enter verification code
+  const codeInputs = page.locator('.code-input');
+  for (let i = 0; i < 6; i++) {
+    await codeInputs.nth(i).fill(TEST_VERIFICATION_CODE[i]);
+  }
+
+  // Submit verification
+  await page.click('#submitBtn');
+
+  // Wait for success toast
+  await expect(page.locator('.toast.visible')).toBeVisible();
+  await expect(page.locator('#toastTitle')).toContainText('Email Verified');
+
+  // Verify sessionStorage has tenant context
+  const pendingTenantId = await page.evaluate(() => sessionStorage.getItem('pendingTenantId'));
+  const pendingEmail = await page.evaluate(() => sessionStorage.getItem('pendingEmail'));
+
+  expect(pendingTenantId).toBeTruthy();
+  expect(pendingEmail).toBe(TEST_USER.email);
+
+  // Should redirect to checkout-success (simulating Stripe Checkout return)
+  await expect(page).toHaveURL(/\/checkout-success\.html/);
+  await expect(page).toHaveURL(/session_id=/);
+  await expect(page).toHaveURL(/tenant_id=/);
+});
+
+/**
+ * Test 2: Google OAuth signup → Stripe Checkout redirect
+ */
+test('should complete Google OAuth signup and redirect to Stripe Checkout', async ({ page }) => {
+  // Setup mock
+  await mockGoogleOAuth(page, TEST_USER.email);
+
+  // Navigate to signup page
+  await page.goto(`${LANDING_URL}/signup`);
+
+  // Click Google OAuth button
+  await page.click('#googleBtn');
+
+  // Wait for response (mocked)
+  await expect(page.locator('.toast.visible')).toBeVisible();
+
+  // Verify sessionStorage has tenant context
+  const pendingTenantId = await page.evaluate(() => sessionStorage.getItem('pendingTenantId'));
+  const pendingEmail = await page.evaluate(() => sessionStorage.getItem('pendingEmail'));
+
+  expect(pendingTenantId).toBeTruthy();
+  expect(pendingEmail).toBe(TEST_USER.email);
+
+  // Should redirect to Stripe Checkout (checkout-success.html in test)
+  await expect(page).toHaveURL(/\/checkout-success\.html/);
+  await expect(page).toHaveURL(/session_id=/);
+  await expect(page).toHaveURL(/tenant_id=/);
+});
+
+/**
+ * Test 3: Stripe Checkout success → redirect to onboarding
+ */
+test('should redirect to dashboard onboarding after successful payment', async ({ page }) => {
+  const mockSessionId = `test_session_${Date.now()}`;
+  const mockTenantId = `TENANT#${Date.now()}`;
+
+  // Set sessionStorage context (simulating previous signup step)
+  await page.goto(`${LANDING_URL}/checkout-success.html?session_id=${mockSessionId}&tenant_id=${mockTenantId}`);
+
+  // Set pending tenant context
+  await page.evaluate((tenantId) => {
+    sessionStorage.setItem('pendingTenantId', tenantId);
+    sessionStorage.setItem('pendingEmail', 'test@example.com');
+  }, mockTenantId);
+
+  // Reload page with context
+  await page.reload();
+
+  // Wait for loading state to complete
+  await page.waitForSelector('#loading-state', { state: 'hidden' });
+
+  // Verify success state is visible
+  await expect(page.locator('#success-state')).toBeVisible();
+
+  // Verify payment details
+  await expect(page.locator('.detail-value').nth(0)).toContainText('$500.00/month');
+  await expect(page.locator('.detail-value').nth(1)).toContainText('Completed');
+  await expect(page.locator('.detail-value').nth(2)).toContainText('Active');
+
+  // Verify sessionStorage has payment info
+  const tenantId = await page.evaluate(() => sessionStorage.getItem('tenant_id'));
+  const checkoutSessionId = await page.evaluate(() => sessionStorage.getItem('checkout_session_id'));
+  const paymentCompleted = await page.evaluate(() => sessionStorage.getItem('payment_completed'));
+
+  expect(tenantId).toBe(mockTenantId);
+  expect(checkoutSessionId).toBe(mockSessionId);
+  expect(paymentCompleted).toBe('true');
+
+  // Verify onboarding button href points to dashboard
+  const onboardingBtn = page.locator('#onboarding-btn');
+  await expect(onboardingBtn).toHaveAttribute('href', `${DASHBOARD_URL}/onboarding/`);
+
+  // Wait for auto-redirect (should happen after 5 seconds)
+  // The test clicks the button manually to avoid waiting
+  await onboardingBtn.click();
+
+  // Verify redirect to dashboard onboarding
+  await expect(page).toHaveURL(`${DASHBOARD_URL}/onboarding/`);
+});
+
+/**
+ * Test 4: Stripe Checkout cancel → return to signup
+ */
+test('should handle cancelled checkout and allow retry', async ({ page }) => {
+  // Navigate to cancel page
+  await page.goto(`${LANDING_URL}/checkout-cancel.html`);
+
+  // Verify cancel message is displayed
+  await expect(page.locator('h1')).toContainText('Payment Cancelled');
+
+  // Verify retry button exists
+  const retryBtn = page.locator('a[href="/signup/"]');
+  await expect(retryBtn).toBeVisible();
+
+  // Click retry to return to signup
+  await retryBtn.click();
+
+  // Verify redirect to signup
+  await expect(page).toHaveURL(/\/signup/);
+});
+
+/**
+ * Test 5: Tenant context preservation through flow
+ */
+test('should preserve tenant context from signup through onboarding', async ({ page, context }) => {
+  const mockTenantId = `TENANT#${Date.now()}`;
+  const mockEmail = 'context-test@example.com';
+
+  // Setup mocks
+  await mockEmailSignup(page, mockEmail);
+  await mockEmailVerification(page, mockEmail);
+
+  // Step 1: Signup
+  await page.goto(`${LANDING_URL}/signup`);
+  await page.fill('#name', 'Context Test');
+  await page.fill('#email', mockEmail);
+  await page.fill('#password', 'Password123!');
+  await page.click('#emailSubmitBtn');
+
+  // Step 2: Verify email
+  await page.waitForURL(/\/verify\.html/);
+
+  const codeInputs = page.locator('.code-input');
+  for (let i = 0; i < 6; i++) {
+    await codeInputs.nth(i).fill(TEST_VERIFICATION_CODE[i]);
+  }
+  await page.click('#submitBtn');
+
+  // Step 3: Checkout success
+  await page.waitForURL(/\/checkout-success\.html/);
+
+  // Verify tenant context is preserved
+  const tenantId = await page.evaluate(() => sessionStorage.getItem('tenant_id'));
+  const tenantEmail = await page.evaluate(() => sessionStorage.getItem('tenant_email'));
+
+  expect(tenantId).toBeTruthy();
+  expect(tenantEmail).toBe(mockEmail);
+
+  // Click onboarding button
+  await page.click('#onboarding-btn');
+
+  // Verify redirect to dashboard onboarding
+  await expect(page).toHaveURL(`${DASHBOARD_URL}/onboarding/`);
+
+  // Note: In production, the dashboard would read the tenant context from URL params or cookies
+  // The assertions above verify sessionStorage is properly set
+});
+
+/**
+ * Test 6: SessionStorage cleanup after completion
+ */
+test('should clean up sessionStorage after onboarding completion', async ({ page }) => {
+  const mockSessionId = `test_session_${Date.now()}`;
+  const mockTenantId = `TENANT#${Date.now()}`;
+
+  // Set sessionStorage with all pending items
+  await page.goto(`${LANDING_URL}/checkout-success.html?session_id=${mockSessionId}&tenant_id=${mockTenantId}`);
+
+  await page.evaluate((tenantId) => {
+    sessionStorage.setItem('pendingTenantId', tenantId);
+    sessionStorage.setItem('pendingEmail', 'test@example.com');
+    sessionStorage.setItem('pendingName', 'Test User');
+  }, mockTenantId);
+
+  // Reload to trigger confirmation logic
+  await page.reload();
+
+  // Wait for success state
+  await page.waitForSelector('#success-state', { state: 'visible' });
+
+  // Verify new storage items are set
+  const tenantId = await page.evaluate(() => sessionStorage.getItem('tenant_id'));
+  const checkoutSessionId = await page.evaluate(() => sessionStorage.getItem('checkout_session_id'));
+
+  expect(tenantId).toBe(mockTenantId);
+  expect(checkoutSessionId).toBe(mockSessionId);
+
+  // Note: Cleanup would happen in the dashboard onboarding after completion
+  // This test verifies the data is available for the next step
+});
+
+/**
+ * Test 7: Error handling - missing session_id
+ */
+test('should handle missing session_id gracefully', async ({ page }) => {
+  // Navigate to checkout-success without session_id
+  await page.goto(`${LANDING_URL}/checkout-success.html`);
+
+  // Wait for loading state to complete
+  await page.waitForSelector('#loading-state', { state: 'hidden' });
+
+  // Verify error state is shown
+  await expect(page.locator('#error-state')).toBeVisible();
+  await expect(page.locator('h1')).toContainText('Payment Confirmation Pending');
+
+  // Verify manual redirect button still works
+  const errorBtn = page.locator('#error-state .btn-primary');
+  await expect(errorBtn).toHaveAttribute('href', `${DASHBOARD_URL}/onboarding/`);
+});
+
+/**
+ * Test 8: Cross-domain redirect handling
+ */
+test('should handle cross-domain redirect from landing to dashboard', async ({ page, context }) => {
+  const mockSessionId = `test_session_${Date.now()}`;
+  const mockTenantId = `TENANT#${Date.now()}`;
+
+  // Navigate to checkout-success
+  await page.goto(`${LANDING_URL}/checkout-success.html?session_id=${mockSessionId}&tenant_id=${mockTenantId}`);
+
+  // Set tenant context
+  await page.evaluate((tenantId) => {
+    sessionStorage.setItem('pendingTenantId', tenantId);
+    sessionStorage.setItem('pendingEmail', 'cross-domain@example.com');
+  }, mockTenantId);
+
+  // Reload to trigger confirmation
+  await page.reload();
+
+  // Wait for success state
+  await page.waitForSelector('#success-state', { state: 'visible' });
+
+  // Click onboarding button
+  await page.click('#onboarding-btn');
+
+  // In cross-domain scenarios, sessionStorage won't persist
+  // The dashboard should read tenant context from URL parameters
+  // Verify the redirect happens
+  await expect(page).toHaveURL(/\/onboarding\/$/);
+});
+
+/**
+ * Test 9: Billing email prefill in Stripe Checkout
+ */
+test('should prefill billing email from signup in Stripe Checkout', async ({ page }) => {
+  const mockEmail = 'billing-test@example.com';
+
+  // Setup mocks
+  await mockEmailSignup(page, mockEmail);
+  await mockEmailVerification(page, mockEmail);
+
+  // Signup with email
+  await page.goto(`${LANDING_URL}/signup`);
+  await page.fill('#name', 'Billing Test');
+  await page.fill('#email', mockEmail);
+  await page.fill('#password', 'Password123!');
+  await page.click('#emailSubmitBtn');
+
+  // Verify email
+  await page.waitForURL(/\/verify\.html/);
+  const codeInputs = page.locator('.code-input');
+  for (let i = 0; i < 6; i++) {
+    await codeInputs.nth(i).fill(TEST_VERIFICATION_CODE[i]);
+  }
+  await page.click('#submitBtn');
+
+  // Verify Stripe Checkout URL includes email (in production, Stripe would prefill this)
+  await page.waitForURL(/\/checkout-success\.html/);
+
+  const pendingEmail = await page.evaluate(() => sessionStorage.getItem('pendingEmail'));
+  expect(pendingEmail).toBe(mockEmail);
+
+  // Note: In production, Stripe Checkout would prefill customer_email from the session
+});
+
+/**
+ * Test 10: Payment amount verification
+ */
+test('should display correct payment amount ($500/month)', async ({ page }) => {
+  const mockSessionId = `test_session_${Date.now()}`;
+
+  await page.goto(`${LANDING_URL}/checkout-success.html?session_id=${mockSessionId}`);
+
+  // Wait for success state
+  await page.waitForSelector('#success-state', { state: 'visible' });
+
+  // Verify payment amount
+  await expect(page.locator('.detail-value').first()).toContainText('$500.00/month');
+});

apps/shared/__init__.py

@@ -0,0 +1 @@
+"""Shared application helpers used across Workweaver services."""

apps/shared/decision_taxonomy.py

@@ -0,0 +1,110 @@
+"""Canonical decision taxonomy shared across backend and learning-service."""
+
+from __future__ import annotations
+
+from typing import Final
+
+
+DECISION_TYPES_IN_ORDER: Final[tuple[str, ...]] = (
+    "tool_call",
+    "exception_granted",
+    "policy_override",
+    "reply_routing",
+)
+
+LEGACY_DECISION_OUTCOMES: Final[frozenset[str]] = frozenset({"success", "failure", "blocked"})
+REPLY_ROUTING_OUTCOMES: Final[frozenset[str]] = frozenset(
+    {
+        "positive_interest",
+        "positive_meeting_intent",
+        "positive_info_request",
+        "referral",
+        "objection",
+        "hard_no",
+        "not_now",
+        "out_of_office",
+        "unsubscribe",
+        "bounce",
+        "ambiguous",
+    }
+)
+
+DECISION_OUTCOMES_IN_ORDER: Final[tuple[str, ...]] = (
+    "success",
+    "failure",
+    "blocked",
+    "positive_interest",
+    "positive_meeting_intent",
+    "positive_info_request",
+    "referral",
+    "objection",
+    "hard_no",
+    "not_now",
+    "out_of_office",
+    "unsubscribe",
+    "bounce",
+    "ambiguous",
+)
+
+DECISION_TYPE_OUTCOMES: Final[dict[str, frozenset[str]]] = {
+    "tool_call": LEGACY_DECISION_OUTCOMES,
+    "exception_granted": LEGACY_DECISION_OUTCOMES,
+    "policy_override": LEGACY_DECISION_OUTCOMES,
+    "reply_routing": REPLY_ROUTING_OUTCOMES,
+}
+
+DEFAULT_PRECEDENT_OUTCOMES: Final[dict[str, frozenset[str] | None]] = {
+    "tool_call": frozenset({"success"}),
+    "exception_granted": frozenset({"success"}),
+    "policy_override": frozenset({"success"}),
+    "reply_routing": None,
+}
+
+ALL_DECISION_TYPES: Final[frozenset[str]] = frozenset(DECISION_TYPES_IN_ORDER)
+ALL_DECISION_OUTCOMES: Final[frozenset[str]] = frozenset(DECISION_OUTCOMES_IN_ORDER)
+
+
+def ordered_decision_types() -> tuple[str, ...]:
+    """Return decision types in stable schema/test order."""
+
+    return DECISION_TYPES_IN_ORDER
+
+
+def ordered_decision_outcomes() -> tuple[str, ...]:
+    """Return decision outcomes in stable schema/test order."""
+
+    return DECISION_OUTCOMES_IN_ORDER
+
+
+def allowed_decision_types() -> frozenset[str]:
+    """Return the canonical decision types."""
+
+    return ALL_DECISION_TYPES
+
+
+def allowed_outcomes_for(decision_type: str) -> frozenset[str]:
+    """Return allowed outcomes for one decision type."""
+
+    return DECISION_TYPE_OUTCOMES.get(str(decision_type or "").strip().lower(), frozenset())
+
+
+def default_precedent_outcomes(decision_type: str) -> frozenset[str] | None:
+    """Return default outcome filter for precedent lookup.
+
+    `None` means do not filter by one outcome at query time.
+    """
+
+    return DEFAULT_PRECEDENT_OUTCOMES.get(str(decision_type or "").strip().lower())
+
+
+def is_valid_decision_type(decision_type: str) -> bool:
+    return str(decision_type or "").strip().lower() in DECISION_TYPE_OUTCOMES
+
+
+def is_valid_decision_outcome(decision_type: str, outcome: str) -> bool:
+    allowed = allowed_outcomes_for(decision_type)
+    return str(outcome or "").strip().lower() in allowed
+
+
+def is_valid_outcome_for(decision_type: str, outcome: str) -> bool:
+    return is_valid_decision_outcome(decision_type, outcome)

apps/shared/design-system/README.md

@@ -0,0 +1,141 @@
+# Workweaver Design System — canonical source
+
+> Plain glass on bright white. Warm saffron edges. Zero redundant clicks.
+
+This directory is the **single source of truth** for every visual + interaction
+primitive in Workweaver — landing, runtime, and dashboard. Everything else
+either imports from here or is deprecated.
+
+## Contract
+
+| File | What it contains |
+| --- | --- |
+| `colors_and_type.css` | All design tokens: ink scale, glass, saffron accent, semantic colors, radii, spacing, shadows, motion, typography. **No hex values appear anywhere outside this file.** |
+| `workweaver.css`      | All component primitives: shell, sidebar, topbar, command bar, card, button, chip, badge, KPI, input, toggle, tabs, list rows, **Unified Timeline** (5 altitudes), Zara launcher, command palette, approval banner, marketing sections. |
+| `workweaver.js`       | All interactive primitives: `ww.Timeline` (altitude switcher + inline action delegation), `ww.Palette` (⌘K), `ww.Zara` (state machine), `ww.api` (typed `/api/v1/*` wrapper with domain shortcuts), `ww.toast`, `ww.store` (localStorage namespace `ww.*`). |
+
+## Canonical entry points
+
+The design system is consumed by exactly two HTML entry points. Every other
+HTML file in the repo is either embedded by these (rare) or deprecated.
+
+| URL | File | Role |
+| --- | --- | --- |
+| `/` (landing) | `apps/landing/public/index.html` | Marketing site. |
+| `/runtime/` | `apps/dashboard/runtime/index.html` | Mission Control — the signed-in product. Hash-routed across `#/mission`, `#/inbox`, `#/memory`, `#/evidence`, `#/harness`, `#/connected`, `#/settings`. |
+
+The runtime is the **only** product surface. Goals, OKRs, tasks, schedule,
+runs, approvals, evidence — they all render on the **Unified Timeline** at
+the matching altitude (Quarter / Month / Week / Day / Hour). There is no
+separate Goals page, no separate OKRs page. One data graph, five views.
+
+## Propagation
+
+The canonical files in `apps/shared/design-system/` are copied verbatim into
+the served locations:
+
+```
+apps/shared/design-system/colors_and_type.css   →
+  apps/dashboard/design-system/colors_and_type.css
+  apps/landing/public/design-system/colors_and_type.css
+  apps/landing/public/css/colors_and_type.css
+
+apps/shared/design-system/workweaver.css   →
+  apps/dashboard/design-system/workweaver.css
+  apps/landing/public/design-system/workweaver.css
+
+apps/shared/design-system/workweaver.js   →
+  apps/dashboard/design-system/workweaver.js
+  apps/landing/public/design-system/workweaver.js
+```
+
+When updating any of the three canonical files, run:
+
+```bash
+cp apps/shared/design-system/colors_and_type.css apps/dashboard/design-system/colors_and_type.css
+cp apps/shared/design-system/colors_and_type.css apps/landing/public/design-system/colors_and_type.css
+cp apps/shared/design-system/colors_and_type.css apps/landing/public/css/colors_and_type.css
+cp apps/shared/design-system/workweaver.css apps/dashboard/design-system/workweaver.css
+cp apps/shared/design-system/workweaver.css apps/landing/public/design-system/workweaver.css
+cp apps/shared/design-system/workweaver.js apps/dashboard/design-system/workweaver.js
+cp apps/shared/design-system/workweaver.js apps/landing/public/design-system/workweaver.js
+```
+
+Both nginx configs (`apps/landing/nginx/*.conf`, `apps/dashboard/nginx/*.conf`)
+serve the per-app `design-system/` directory — they do not have a `/shared/`
+mount. That's why we copy.
+
+## Class naming
+
+Every class is prefixed `ww-`. Modifiers use `ww-x--y` (BEM-like). State uses
+`is-on`, `is-active`, `is-now`, `is-unread`, `is-open`, `is-selected`.
+
+## Backend API contract
+
+`workweaver.js` ships typed wrappers around the canonical backend:
+
+```js
+ww.api.mission.analytics()
+ww.api.mission.timeline({ since })
+ww.api.mission.goals()
+ww.api.inbox.list({ limit })
+ww.api.memory.facts()
+ww.api.memory.recall(query)
+ww.api.connectors.list()
+ww.api.skills.list()
+ww.api.harness.pending()
+ww.api.harness.approve(id, payload)
+ww.api.harness.reject(id, reason)
+ww.api.harness.brake()
+ww.api.evidence.list({ limit })
+ww.api.evidence.trace(id)
+ww.api.simulation.run(config)
+ww.api.simulation.promote(runId)
+ww.api.settings.get()
+ww.api.settings.put(patch)
+```
+
+All shortcut methods are thin wrappers around `ww.api.{get,post,put,patch,del}`
+(direct fetch wrappers if you need them). Default base URL is
+`window.location.origin + "/api/v1"`. Override via `window.WW_API_BASE`.
+
+Every page loader is **fail-soft**: if the API 404s or errors, the surface
+falls through to demo data. That means the design system is dogfoodable even
+without a backend — useful for static previews and design review.
+
+## Voice
+
+- Sentence case in UI; Title Case only for brand nouns (Mission Control,
+  Execution Runtime, Evidence Graph, WorkMemory, Connected Tools, AI-Ops
+  Identity, Proof Card, Emergency Brake, Harness System).
+- Specific verbs, specific nouns. Never `revolutionize`, `unleash`, `seamless`,
+  `leverage`, `empower`, `unlock`, `journey`, `magical`, `10x`.
+- Active, present tense. Address the user as `you`. Refer to the AI in third
+  person ("Zara proposes", "Workweaver ran").
+- No emoji. Iconography is Font Awesome 6.5.1 (free) + inline SVG.
+
+## Iconography
+
+- Font Awesome 6.5.1 free CDN — `<i class="fas fa-X" aria-hidden="true">`.
+- Inline SVG for the Workweaver mark (`apps/landing/public/landing-assets/`,
+  `apps/dashboard/runtime/index.html` inlines the W+gear).
+- Every icon must have an accessible label (visible text, tooltip, or
+  `aria-label`).
+
+## What "no wrong way to use it" means
+
+Every block on the timeline exposes the same action contract:
+`approve`, `redirect`, `pause`, `handoff`, `trace`. The Timeline class
+handles delegation; the host page wires the actions to backend calls.
+Inline actions appear on hover/focus only — calm by default.
+
+⌘K opens the command palette. The palette registers every nav target,
+altitude, and action. There is no "hidden" action — every action is
+discoverable from the palette.
+
+## Reference
+
+The original spec lives at `.workweaver-design/` (README.md, SKILL.md,
+HANDOFF.md). It defines voice, interaction principles, the unified-timeline
+pattern, banned words, asset rules. The design system in this directory is
+the **implementation** of that spec.