@a5c-ai/kradle 5.0.1-staging.3abdf9534c25

package/docs/todos.md

@@ -0,0 +1,4 @@
+https://kradle-staging.a5c.ai/api/orgs/default/policy-reports shows: Kyverno CRDs are not installed or are not readable by the Kradle service account - helm should install everything needed.
+
+❯ refactor the C:\Users\tmusk\IdeaProjects\babysitter\packages\kradle\web to 3 packages , kradle\sdk, kradle\web and kradle\cli (web and cli
+  should depend on sdk), the sdk is the client sdk. the cli should have a command to run itself as an mcp server.

package/docs/user-stories.md

@@ -0,0 +1,78 @@
+# User Stories
+
+## Developer stories
+
+### Open and review a PR
+
+As a developer, I want to review a PR in a three-pane view with file tree, diff, conversation, inline comments, suggested edits, and CI status so that I can complete reviews quickly.
+
+Acceptance criteria:
+
+- Given I open a PR, when the page loads, then I see changed files, diff, discussion, reviewers, merge state, and related pipeline runs.
+- Given I use keyboard shortcuts, when I press navigation keys, then I can move between files and comments without leaving the keyboard.
+- Given I add a suggested edit, when I submit it, then the UI exposes the equivalent resource/YAML mutation.
+
+### Debug a failing run
+
+As a developer, I want a live run view with step navigation, log streaming, failure copy, similar-run search, and rerun controls so that I can diagnose failures without switching tools.
+
+Acceptance criteria:
+
+- Given a job is running, when logs are emitted, then the UI streams them through SSE without polling.
+- Given a step fails, when I click find similar runs, then Kradle queries pipelines by failure signature labels.
+- Given I rerun from a step, when I submit, then Kradle creates a new `Pipeline` with `resumeFrom`.
+
+## Platform engineer stories
+
+### Configure a runner pool
+
+As a platform engineer, I want a split form/YAML runner pool editor so that pool configuration is easy to edit and still GitOps-auditable.
+
+Acceptance criteria:
+
+- Given I edit image, resources, node selector, warm replicas, max replicas, trust tier, and cache backend, when fields change, then YAML updates live.
+- Given I save, when the operation succeeds, then the same manifest can be copied as `kubectl apply`.
+- Given I click save to repo, when configured, then Kradle opens a PR against the platform config repo.
+
+### Roll out PR policy safely
+
+As a platform engineer, I want policy templates, CEL/raw modes, audit preview, and enforcement controls so that I can govern PRs without breaking teams unexpectedly.
+
+Acceptance criteria:
+
+- Given I select a policy template, when I preview it, then existing PRs that would violate the policy are listed.
+- Given the policy is in audit mode, when a violating PR is created, then it is recorded but not blocked.
+- Given I switch to enforce mode, when a violating PR is created, then admission blocks it with an actionable message.
+
+## Repo admin stories
+
+### Add and verify a webhook
+
+As a repo admin, I want to create a webhook, send a test delivery, inspect failures, and replay deliveries so integrations are operationally transparent.
+
+Acceptance criteria:
+
+- Given I create a subscription, when I send a test delivery, then a `WebhookDelivery` resource appears within seconds.
+- Given delivery fails, when I open the log, then I see request headers, body, response, latency, retries, and error details.
+- Given I click replay, when secrets are current, then Kradle re-fires the event and records a new delivery attempt.
+
+## Team lead stories
+
+### Cross-repo triage
+
+As a team lead, I want inbox filters and saved views stored as resources so that triage workflows can be versioned and shared.
+
+Acceptance criteria:
+
+- Given I create a filter for priority issues and PRs, when I save it, then Kradle stores a `Selector` or `View` resource.
+- Given another user applies the resource, when they open the inbox, then they see the same triage view.
+- Given the view is exported, when committed to Git, then it can be reviewed and applied like any other config.
+
+## Excellent-flow coverage
+
+- Open and review a PR.
+- Debug a failing run.
+- Configure a runner pool.
+- Add a webhook and verify it works.
+- Write a PR policy with audit-to-enforce rollout.
+- Cross-repo triage with saved filters.

package/docs/web-console-spec.md

@@ -0,0 +1,533 @@
+# Kradle Web Console Specification
+
+> Exhaustive reference for the Kradle web console.
+> Source: `packages/kradle/web/`
+> Framework: Next.js 16 + React 19 (App Router)
+
+---
+
+## 1. Page Inventory (57 pages)
+
+### 1.1 Top-Level Pages
+
+| # | Route | File | Data Source | Purpose | Interactive Elements |
+|---|-------|------|-------------|---------|---------------------|
+| 1 | `/` | `page.jsx` | None | Landing/home page | Login CTA, org selector |
+| 2 | `/login` | `login/page.jsx` | `listEnabledAuthProviders()` | Authentication login | Provider buttons (GitHub, SSO) |
+| 3 | `/logout` | `logout/page.jsx` | None | Session logout | Auto-redirect to /login |
+| 4 | `/orgs` | `orgs/page.jsx` | `fetchControllerUiModel()` | Organization list | Org cards, create org button |
+| 5 | `/people` | `people/page.jsx` | `fetchControllerUiModel()` | People directory | User search, team filter |
+
+### 1.2 Organization Dashboard (5 pages)
+
+| # | Route | File | Data Source | Purpose | Interactive Elements |
+|---|-------|------|-------------|---------|---------------------|
+| 6 | `/orgs/[org]` | `orgs/[org]/page.jsx` | `uiModel.views.dashboard` | Org dashboard overview | Cards (repos, PRs, issues, runs), activity feed, quick actions |
+| 7 | `/orgs/[org]/profile` | `orgs/[org]/profile/page.jsx` | `uiModel.identity` | User profile | Edit display name, email; linked identities |
+| 8 | `/orgs/[org]/people` | `orgs/[org]/people/page.jsx` | `uiModel.identity.users` | Org members | Invite button, team assignment, role toggle |
+| 9 | `/orgs/[org]/inbox` | `orgs/[org]/inbox/page.jsx` | `notifications.listNotifications()` | Notification inbox | Mark as read, filter by type, clear all |
+| 10 | `/orgs/[org]/insights` | `orgs/[org]/insights/page.jsx` | `uiModel.metrics` | Analytics and insights | Time range selector, metric cards |
+
+### 1.3 Ship (Repositories & Code) — 9 pages
+
+| # | Route | File | Data Source | Purpose | Interactive Elements |
+|---|-------|------|-------------|---------|---------------------|
+| 11 | `/orgs/[org]/repositories` | `orgs/[org]/repositories/page.jsx` | `uiModel.views.dashboard.repositories` | Repository list | Create repo form, visibility filter, search |
+| 12 | `/orgs/[org]/repositories/[repo]/code` | `repositories/[repo]/code/page.jsx` | `git-proxy` API | Code browser | File tree, branch selector, breadcrumb |
+| 13 | `/orgs/[org]/repositories/[repo]/pull-requests` | `repositories/[repo]/pull-requests/page.jsx` | `uiModel resources PullRequest` | PR list | Status filter, create PR button |
+| 14 | `/orgs/[org]/repositories/[repo]/issues` | `repositories/[repo]/issues/page.jsx` | `uiModel resources Issue` | Issue list | Label filter, assignee, new issue |
+| 15 | `/orgs/[org]/repositories/[repo]/issues/[issue]` | `issues/[issue]/page.jsx` | Issue resource | Issue detail | Comment form, label editor, close/reopen |
+| 16 | `/orgs/[org]/repositories/[repo]/hooks` | `repositories/[repo]/hooks/page.jsx` | `WebhookSubscription` | Webhook config | Add webhook form, delivery list, replay |
+| 17 | `/orgs/[org]/repositories/[repo]/runs` | `repositories/[repo]/runs/page.jsx` | `AgentDispatchRun` filtered by repo | Repo agent runs | Run list, dispatch button, status filter |
+| 18 | `/orgs/[org]/repositories/[repo]/settings` | `repositories/[repo]/settings/page.jsx` | Repository resource | Repo settings | Rename, visibility toggle, danger zone (delete) |
+| 19 | `/orgs/[org]/runs` | `orgs/[org]/runs/page.jsx` | `uiModel.agents.runs` | All runs overview | Filter by stack, status, repository |
+
+### 1.4 Manage (Access & Policy) — 8 pages
+
+| # | Route | File | Data Source | Purpose | Interactive Elements |
+|---|-------|------|-------------|---------|---------------------|
+| 20 | `/orgs/[org]/access/permissions` | `access/permissions/page.jsx` | `uiModel.identity.permissions` | Permission management | Grant/revoke, subject selector, permission level |
+| 21 | `/orgs/[org]/access/ssh-keys` | `access/ssh-keys/page.jsx` | `uiModel.identity.sshKeys` | SSH key management | Add key form, revoke button, scope filter |
+| 22 | `/orgs/[org]/access/branch-protection` | `access/branch-protection/page.jsx` | `BranchProtection` resources | Branch rules | Ref pattern input, toggle required reviews |
+| 23 | `/orgs/[org]/settings` | `orgs/[org]/settings/page.jsx` | Organization resource | Org settings | Display name, slug, namespace info, danger zone |
+| 24 | `/orgs/[org]/settings/secrets` | `settings/secrets/page.jsx` | `/api/orgs/:org/secrets` | Secret management | Add secret form, delete, grant management |
+| 25 | `/orgs/[org]/hooks-events` | `orgs/[org]/hooks-events/page.jsx` | `WebhookSubscription + Delivery` | Webhook events | Subscription list, delivery inspector, replay |
+| 26 | `/orgs/[org]/deployments` | `orgs/[org]/deployments/page.jsx` | `uiModel.delivery` | Deployments | Application list, release history, health |
+| 27 | `/orgs/[org]/runners-ci` | `orgs/[org]/runners-ci/page.jsx` | `RunnerPool + Pipeline + Job` | Runner pools & CI | Pool editor, pipeline list, job detail |
+
+### 1.5 Agents — 24 pages
+
+| # | Route | File | Data Source | Purpose | Interactive Elements |
+|---|-------|------|-------------|---------|---------------------|
+| 28 | `/orgs/[org]/agents` | `agents/page.jsx` | `uiModel.agents` | Agent overview | Stack count cards, active runs, pending approvals |
+| 29 | `/orgs/[org]/agents/stacks` | `agents/stacks/page.jsx` | `uiModel.agents.stacks` | Stack list | Readiness indicators, create button |
+| 30 | `/orgs/[org]/agents/stacks/new` | `agents/stacks/new/page.jsx` | `STACK_LAYERS, COMPOSITION_FACETS` | Create stack | Multi-step StackBuilder form |
+| 31 | `/orgs/[org]/agents/stacks/[name]` | `agents/stacks/[name]/page.jsx` | AgentStack resource | Stack detail | Conditions list, capabilities graph, edit |
+| 32 | `/orgs/[org]/agents/runs` | `agents/runs/page.jsx` | `uiModel.agents.runs` | Dispatch run list | Phase filter, repository filter, cost summary |
+| 33 | `/orgs/[org]/agents/runs/[runId]` | `agents/runs/[runId]/page.jsx` | AgentDispatchRun + Attempt | Run detail | Attempt timeline, transcript, workspace link |
+| 34 | `/orgs/[org]/agents/sessions` | `agents/sessions/page.jsx` | `uiModel.agents.sessions` | Session list | Active/completed filter, cost column |
+| 35 | `/orgs/[org]/agents/sessions/[sessionId]` | `agents/sessions/[sessionId]/page.jsx` | AgentSession + Transcript | Session detail | SessionTabs: transcript, tools, cost, shell |
+| 36 | `/orgs/[org]/agents/rules` | `agents/rules/page.jsx` | `uiModel.agents.rules` | Trigger rule list | Source type badges, enable/disable toggle |
+| 37 | `/orgs/[org]/agents/rules/new` | `agents/rules/new/page.jsx` | Stack list for dropdown | Create trigger rule | TriggerRuleForm with source type selector |
+| 38 | `/orgs/[org]/agents/rules/[ruleName]` | `agents/rules/[ruleName]/page.jsx` | AgentTriggerRule resource | Rule detail | Edit form, execution history |
+| 39 | `/orgs/[org]/agents/approvals` | `agents/approvals/page.jsx` | `uiModel.agents.approvals` | Approval queue | Approve/Deny buttons, filter by action type |
+| 40 | `/orgs/[org]/agents/workspaces` | `agents/workspaces/page.jsx` | `uiModel.agents.workspaces` | Workspace list | Phase badges, repository links |
+| 41 | `/orgs/[org]/agents/workspaces/[workspaceId]` | `agents/workspaces/[workspaceId]/page.jsx` | KradleWorkspace resource | Workspace detail | Codespace launch, associations, run history |
+| 42 | `/orgs/[org]/agents/settings` | `agents/settings/page.jsx` | Adapter + Provider + Gateway | Agent settings | Adapter config, provider forms, gateway URL |
+| 43 | `/orgs/[org]/agents/projects` | `agents/projects/page.jsx` | `uiModel.agents.projects` | Project list | Create project, kanban toggle |
+| 44 | `/orgs/[org]/agents/projects/[projectId]` | `agents/projects/[projectId]/page.jsx` | KradleProject resource | Project detail | Kanban board, issue list, settings |
+| 45 | `/orgs/[org]/agents/projects/[projectId]/issues` | `projects/[projectId]/issues/page.jsx` | Issues filtered by project | Project issues | Filter, create issue |
+| 46 | `/orgs/[org]/agents/projects/[projectId]/issues/[issue]` | `issues/[issue]/page.jsx` | Issue resource | Project issue detail | Comment, labels, assign |
+| 47 | `/orgs/[org]/agents/memory` | `agents/memory/page.jsx` | `uiModel.agents.memoryRepositories` | Memory overview | Repository list, snapshot count |
+| 48 | `/orgs/[org]/agents/memory/search` | `agents/memory/search/page.jsx` | Memory query API | Memory search | MemorySearchForm, results display |
+| 49 | `/orgs/[org]/agents/memory/ontology` | `agents/memory/ontology/page.jsx` | AgentMemoryOntology | Ontology editor | MemoryOntologyEditor, node/edge kind editors |
+| 50 | `/orgs/[org]/agents/memory/imports` | `agents/memory/imports/page.jsx` | `uiModel.agents.memoryImports` | Import list | Status badges, review button |
+| 51 | `/orgs/[org]/agents/memory/imports/[importId]` | `agents/memory/imports/[importId]/page.jsx` | AgentRunMemoryImport | Import detail | MemoryImportReview, approve/reject |
+
+### 1.6 External — 4 pages
+
+| # | Route | File | Data Source | Purpose | Interactive Elements |
+|---|-------|------|-------------|---------|---------------------|
+| 52 | `/orgs/[org]/external` | `orgs/[org]/external/page.jsx` | ExternalBackendProvider list | External overview | Provider cards, add button |
+| 53 | `/orgs/[org]/external/providers/new` | `external/providers/new/page.jsx` | Provider type list | Add provider | ExternalProviderWizard (multi-step) |
+| 54 | `/orgs/[org]/external/sync` | `external/sync/page.jsx` | ExternalSyncState | Sync dashboard | ExternalSyncDashboard, trigger sync |
+| 55 | `/orgs/[org]/external/conflicts` | `external/conflicts/page.jsx` | ExternalSyncConflict list | Conflict list | ExternalConflictResolver, strategy selector |
+
+### 1.7 Observe & Tools — 4 pages
+
+| # | Route | File | Data Source | Purpose | Interactive Elements |
+|---|-------|------|-------------|---------|---------------------|
+| 56 | `/orgs/[org]/api-docs` | `orgs/[org]/api-docs/page.jsx` | controllerEndpoints | API documentation | Endpoint list, try-it panel |
+| 57 | `/orgs/[org]/controller-api` | `orgs/[org]/controller-api/page.jsx` | Full snapshot | Controller API explorer | ApiExplorer with request/response |
+| 58 | `/orgs/[org]/advanced-plans` | `orgs/[org]/advanced-plans/page.jsx` | Resource YAML | Advanced plans | YAML editor, apply button |
+| 59 | `/orgs/[org]/operations-install` | `orgs/[org]/operations-install/page.jsx` | uiModel.operations | Operations install guide | Copy commands, step indicators |
+
+---
+
+## 2. Component Library (56 components)
+
+### 2.1 Agent Components
+
+| # | Component | File | Props | State | API Calls | Key Behavior |
+|---|-----------|------|-------|-------|-----------|--------------|
+| 1 | ApprovalActions | `approval-actions.jsx` | `{ approval, org, onDecide }` | — | POST approvals/:name/decide | Approve/Deny buttons with reason modal |
+| 2 | ApprovalModeToggle | `approval-mode-toggle.jsx` | `{ stack, onToggle }` | `useState(mode)` | — | Toggle between yolo/prompt/deny |
+| 3 | DispatchButton | `dispatch-button.jsx` | `{ stack, repo, org, onDispatch }` | `useState(loading)` | POST agents/dispatch | One-click dispatch with loading state |
+| 4 | RunActions | `run-actions.jsx` | `{ run, org }` | — | — | Retry, cancel, view workspace links |
+| 5 | RuleActions | `rule-actions.jsx` | `{ rule, org }` | — | — | Edit, disable, delete trigger rule |
+| 6 | StackActions | `stack-actions.jsx` | `{ stack, org }` | — | — | Edit, dispatch, delete stack |
+| 7 | StackBuilder | `stack-builder.jsx` | `{ org, layers, onSave }` | Multi-step form state | POST resources | Multi-step agent stack creation wizard |
+| 8 | StackBuilderGraph | `stack-builder-graph.jsx` | `{ stack, capabilities }` | — | — | Visual capability graph |
+| 9 | SessionCost | `session-cost.jsx` | `{ session, transcript }` | — | — | Token count and cost display |
+| 10 | SessionShell | `session-shell.jsx` | `{ sessionId, org }` | SSE subscription | SSE stream | Terminal-style live session viewer |
+| 11 | SessionTabs | `session-tabs.jsx` | `{ session, transcript }` | `useState(activeTab)` | — | Tabbed: Transcript, Tools, Cost, Shell |
+| 12 | ToolInspector | `tool-inspector.jsx` | `{ mcpServers, toolProfiles }` | — | — | MCP tool listing with status |
+| 13 | TriggerRuleForm | `trigger-rule-form.jsx` | `{ org, stacks, onSave }` | Form state | POST resources | Source type selector, cron/webhook/comment/label fields |
+
+### 2.2 Memory Components
+
+| # | Component | File | Props | Key Behavior |
+|---|-----------|------|-------|--------------|
+| 14 | MemorySearchForm | `memory-search-form.jsx` | `{ org, onSearch }` | Mode selector (graph/grep/both), query input, kind filter, depth |
+| 15 | MemoryOntologyEditor | `memory-ontology-editor.jsx` | `{ ontology, org }` | Node kind editor, edge kind editor, vocabulary |
+| 16 | MemoryImportReview | `memory-import-review.jsx` | `{ importResource, org }` | Diff view, approve/reject buttons |
+
+### 2.3 External Components
+
+| # | Component | File | Props | Key Behavior |
+|---|-----------|------|-------|--------------|
+| 17 | ExternalConflictResolver | `external-conflict-resolver.jsx` | `{ conflict, org }` | Side-by-side diff, strategy buttons |
+| 18 | ExternalProviderList | `external-provider-list.jsx` | `{ providers }` | Cards with status indicators |
+| 19 | ExternalProviderWizard | `external-provider-wizard.jsx` | `{ org, onComplete }` | Multi-step: type → credentials → scope → confirm |
+| 20 | ExternalSyncDashboard | `external-sync-dashboard.jsx` | `{ syncStates, org }` | Status overview with metrics |
+
+### 2.4 Kanban Components
+
+| # | Component | File | Props | Key Behavior |
+|---|-----------|------|-------|--------------|
+| 21 | KanbanCard | `kanban-card.jsx` | `{ item, onDragStart }` | Draggable card with issue/PR preview |
+| 22 | KanbanColumn | `kanban-column.jsx` | `{ status, items, onDrop }` | Drop target column |
+| 23 | KanbanEnhanced | `kanban-enhanced.jsx` | `{ project, issues }` | Full board with columns |
+| 24 | KanbanFilters | `kanban-filters.jsx` | `{ onFilter }` | Label, assignee, repository filters |
+| 25 | KanbanInteractive | `kanban-interactive.jsx` | `{ project, org }` | SSE-powered live kanban with drag-drop |
+
+### 2.5 Workspace Components
+
+| # | Component | File | Props | Key Behavior |
+|---|-----------|------|-------|--------------|
+| 26 | WorkspacePanel | `workspace-panel.jsx` | `{ workspace }` | Overview: phase, repo, branch, PVC |
+| 27 | WorkspaceCodespace | `workspace-codespace.jsx` | `{ workspace, org }` | Launch/stop codespace, URL display |
+| 28 | WorkspaceAssociations | `workspace-associations.jsx` | `{ workspace }` | Add/remove run, user, session links |
+| 29 | WorkspaceRunHistory | `workspace-run-history.jsx` | `{ workspace, runs }` | Active runs, historical runs table |
+
+### 2.6 Repository Components
+
+| # | Component | File | Props | Key Behavior |
+|---|-----------|------|-------|--------------|
+| 30 | RepoCodeBrowser | `repo-code-browser.jsx` | `{ org, repo, branch }` | File tree + content viewer via git-proxy |
+| 31 | RepoRuns | `repo-runs.jsx` | `{ runs, org }` | Filtered run list for a repository |
+| 32 | PullRequestList | `pull-request-list.jsx` | `{ pullRequests, org }` | PR list with status indicators |
+| 33 | IssueList | `issue-list.jsx` | `{ issues, org }` | Filterable issue list |
+| 34 | IssueEditor | `issue-editor.jsx` | `{ issue, org }` | Rich issue create/edit form |
+| 35 | WebhookManager | `webhook-manager.jsx` | `{ subscriptions, deliveries }` | CRUD webhooks, delivery inspector |
+
+### 2.7 Global Components
+
+| # | Component | File | Props | Key Behavior |
+|---|-----------|------|-------|--------------|
+| 36 | CommandPalette | `command-palette.jsx` | `{ org }` | Cmd+K / Ctrl+K; full-text search, quick nav |
+| 37 | KeyboardShortcuts | `keyboard-shortcuts.jsx` | — | ? overlay; nav shortcuts, action shortcuts |
+| 38 | GlobalSearch | `global-search.jsx` | `{ org }` | Full-text search across all resources |
+| 39 | NotificationBell | `notification-bell.jsx` | `{ org }` | Badge with unread count, dropdown panel |
+| 40 | ActivityFeed | `activity-feed.jsx` | `{ org, events }` | Time-grouped activity entries |
+| 41 | HealthMonitor | `health-monitor.jsx` | `{ connection }` | System component status indicators |
+| 42 | LiveUpdates | `live-updates.jsx` | `{ org, onEvent }` | SSE connection, auto-reconnect |
+| 43 | ThemeRuntime | `theme-runtime.jsx` | — | Dark/light toggle, system preference detection |
+| 44 | KradleLoading | `kradle-loading.jsx` | `{ label? }` | Branded loading spinner |
+
+### 2.8 Settings Components
+
+| # | Component | File | Props | Key Behavior |
+|---|-----------|------|-------|--------------|
+| 45 | AgentSettingsForm | `agent-settings-form.jsx` | `{ org }` | Combined adapters + providers + gateway form |
+| 46 | SettingsAdapters | `settings-adapters.jsx` | `{ adapters, org }` | Adapter CRUD |
+| 47 | SettingsProviders | `settings-providers.jsx` | `{ providers, org }` | Provider CRUD |
+| 48 | SettingsGateway | `settings-gateway.jsx` | `{ gateway, org }` | Gateway URL + feature flags |
+| 49 | AppSettings | `app-settings.jsx` | `{ org }` | App-level settings |
+| 50 | SecretManager | `secret-manager.jsx` | `{ org }` | Secret CRUD with masked values |
+| 51 | RunnerPoolManager | `runner-pool-manager.jsx` | `{ pools, org }` | Pool sizing with warm/max sliders |
+| 52 | UserProfile | `user-profile.jsx` | `{ user, org }` | Profile display and edit |
+
+### 2.9 Utility Components
+
+| # | Component | File | Props | Key Behavior |
+|---|-----------|------|-------|--------------|
+| 53 | ResourceActions | `resource-actions.jsx` | `{ resource, org }` | View/Edit/Delete menu |
+| 54 | ResourceCrudActions | `resource-crud-actions.jsx` | `{ kind, org }` | Full CRUD buttons |
+| 55 | CodeEditor | `code-editor.jsx` | `{ value, language, onChange }` | Syntax-highlighted editor |
+| 56 | ApiExplorer | `api-explorer.jsx` | `{ endpoints }` | Interactive API testing |
+| 57 | DeploymentPipeline | `deployment-pipeline.jsx` | `{ applications }` | Visual pipeline progress |
+
+---
+
+## 3. Data Flow Architecture
+
+### 3.1 Fetch Pipeline
+
+```
+Page Component (Server Component)
+    → loadKradleUi() / fetchControllerUiModel({ baseUrl, org })
+        → HTTP GET /api/controller?org=<org>
+            → createKradleHttpHandler matches route
+                → createControllerUiModel(snapshot, { organization })
+                    → Stale-while-revalidate cache (30s TTL)
+    → Pass data as props to Client Components
+```
+
+### 3.2 Controller UI Model Shape
+
+`createControllerUiModel()` produces:
+
+```javascript
+{
+  product: 'Kradle',
+  status: 'ready' | 'degraded',
+  namespace: 'kradle-org-acme',
+  platformNamespace: 'kradle-system',
+  org: { name, slug, displayName, namespace },
+  orgs: [...],
+  generatedAt: ISO timestamp,
+  controller: { mode, endpoints, architecture, storage, connection, apiService, commands },
+  metrics: { components, resources, events, users, teams, repositories, pullRequests, issues, projects, pipelines, ... },
+  components: [...runtimeComponents],
+  resources: [...KRADLE_RESOURCES mapped with items],
+  events: [...last 8 K8s events],
+  delivery: { applications, runtime, capabilityCatalog },
+  policyEngine: { mode, health, profiles, templates, bindings, violations },
+  agents: { stacks, runs, rules, sessions, workspaces, approvals, adapters, providers, projects, gateway, transcripts, memoryRepositories, memorySnapshots, memoryImports },
+  identity: { counts, providers, users, teams, invites, mappings, permissions, sshKeys, reconciliation },
+  validation: [...healthChecks],
+  views: { dashboard, pullRequestReview, failingRun, runnerPoolEditor, webhookInspector, triageView }
+}
+```
+
+### 3.3 API Proxy Routes (Web)
+
+| Route | Target | Method |
+|-------|--------|--------|
+| `/api/orgs` | Kradle API | GET |
+| `/api/orgs/[org]/repositories` | Resource CRUD | GET/POST |
+| `/api/auth/[provider]` | OAuth redirect | GET |
+| `/api/auth/callback/[provider]` | OAuth callback | GET |
+| `/api/auth/logout` | Session destruction | POST |
+| `/api/auth/delegated` | Delegated identity | GET |
+| `/api/atlas/search` | Atlas graph search | POST |
+| `/api/git-proxy` | Gitea tree/blob proxy | POST |
+| `/api/watch/[...resource]` | SSE watch endpoint | GET |
+
+---
+
+## 4. Navigation Architecture
+
+### 4.1 Navigation Groups
+
+| Group | Icon | Pages | Section |
+|-------|------|-------|---------|
+| **Ship** | Code | Repositories, PRs, Issues, Code, Runs | Primary development |
+| **Manage** | Settings | Permissions, SSH Keys, Branch Protection, Settings, Secrets, Deployments, Runners | Administration |
+| **Agents** | Bot | Stacks, Runs, Sessions, Rules, Approvals, Workspaces, Projects, Memory | AI orchestration |
+| **Observe** | Eye | Hooks & Events, Insights, Inbox, Health, API Docs | Monitoring |
+| **External** | Link | Providers, Sync, Conflicts | Integration |
+
+### 4.2 Command Palette
+
+- Trigger: `Cmd+K` (macOS) / `Ctrl+K` (Windows/Linux)
+- Features: full-text search across resources, quick page navigation, recent items
+- Implementation: `command-palette.jsx`
+
+### 4.3 Keyboard Shortcuts
+
+- `?` — Show shortcut overlay
+- `j/k` — Navigate items in lists
+- `n` — New (context-dependent)
+- `Escape` — Close modal/palette
+
+---
+
+## 5. Real-Time Updates
+
+### 5.1 LiveUpdates Component
+
+```jsx
+// Connection lifecycle:
+// 1. Connect to /api/orgs/:org/agents/events/stream
+// 2. Receive {"type":"connected"} — mark as connected
+// 3. Process {"type":"resource-change", kind, name, operation}
+// 4. On disconnect: auto-reconnect with backoff
+// 5. Receive {"type":"heartbeat"} every 30s — keepalive
+```
+
+### 5.2 SSE-Powered Components
+
+| Component | SSE Usage |
+|-----------|-----------|
+| KanbanInteractive | Live card movement on issue/PR status changes |
+| NotificationBell | Real-time unread count updates |
+| ActivityFeed | New events prepended |
+| SessionShell | Live transcript streaming |
+| HealthMonitor | Connection status indicator |
+
+---
+
+## 6. Theme System
+
+### 6.1 Implementation
+
+- CSS custom properties for all colors
+- Two theme sets: `light` and `dark`
+- Applied via `data-theme` attribute on `<html>`
+- ThemeRuntime component manages state
+
+### 6.2 Persistence
+
+```javascript
+// Read: localStorage.getItem('kradle-theme')
+// Write: localStorage.setItem('kradle-theme', theme)
+// Default: window.matchMedia('(prefers-color-scheme: dark)').matches
+// Auto-update: mediaQuery.addEventListener('change', handler)
+```
+
+---
+
+## 7. Form Patterns
+
+### 7.1 Multi-Step Forms
+
+| Form | Steps | Source |
+|------|-------|--------|
+| StackBuilder | Model → Provider → Transport → Tools → Skills → Review | `stack-builder.jsx` |
+| ExternalProviderWizard | Type → Credentials → Scope → Confirm | `external-provider-wizard.jsx` |
+| TriggerRuleForm | Source Type → Config → Stack Selection → Review | `trigger-rule-form.jsx` |
+
+### 7.2 Error Handling
+
+- Inline field errors below inputs
+- Toast notifications for operation failures (auto-dismiss)
+- Error boundary component (`error.jsx`) for unhandled errors
+- Form-level validation before submission
+
+### 7.3 Loading States
+
+- `KradleLoading` spinner for full-page loads
+- Disabled buttons with spinner during submission
+- Skeleton loading for list views
+- Optimistic updates on create/edit (revert on failure)
+
+---
+
+## 8. Authentication Flow (Web)
+
+### 8.1 Login Flow
+
+```
+/login → Click provider → /api/auth/[provider]
+    → 302 to OAuth provider
+    → User authorizes
+    → /api/auth/callback/[provider]?code=...
+    → Exchange code → Create session cookie
+    → 302 to /orgs/[org]
+```
+
+### 8.2 Session Validation
+
+- Cookie `kradle_session` sent on every request
+- Web API routes verify via `parseSessionCookie()`
+- Invalid sessions: redirect to `/login`
+- Logout: clear cookie with `Max-Age=0`, redirect to `/login`
+
+---
+
+## 9. Error Page
+
+Source: `packages/kradle/web/app/error.jsx`
+
+- React Error Boundary component
+- Displays error message and stack trace (dev mode)
+- "Try Again" button to reset error state
+- Falls back to minimal UI on catastrophic failure
+
+
+---
+
+## ML Navigation Group
+
+### Inference Service List
+
+**Route:** `/orgs/{org}/inference/services`
+
+**Components:**
+- Service table: name, model format badge, inference protocol, phase badge (Pending/Ready/Failed), endpoint URL
+- Create button opens an inline form
+
+**Actions:** Create service, delete (confirmation dialog)
+
+**Data source:** `GET /api/orgs/{org}/inference/services`
+
+### Inference Service Detail
+
+**Route:** `/orgs/{org}/inference/services/{name}`
+
+**Sections:**
+- Spec viewer: predictor model config (modelFormat, storageUri, protocolVersion), resource limits/requests
+- Status panel: phase, endpoint URL, conditions timeline, error message
+- Test panel: send inference request (JSON input editor -> response panel), protocol selector (V1/V2)
+
+**Data source:** `GET /api/orgs/{org}/inference/services/{name}`
+
+### Inference Test Panel
+
+Embedded within service detail. Sends `POST /api/orgs/{org}/inference/services/{name}/infer`.
+
+- Input: JSON editor with schema hint for the selected model format
+- Output: formatted JSON response panel
+- Protocol toggle: V1 / V2
+- Response time display
+
+### Serving Runtime Manager
+
+**Route:** `/orgs/{org}/inference/runtimes`
+
+**Components:**
+- Runtime table: name, supported model formats (comma-separated), container image
+- Create runtime button and form
+
+**Data source:** `GET /api/orgs/{org}/inference/runtimes`
+
+---
+
+## Artifacts Navigation Group
+
+### Registry List
+
+**Route:** `/orgs/{org}/artifacts/registries`
+
+**Components:**
+- Registry cards: name, type badge (npm/pip/docker/generic), storage backend, feed count
+- Create registry button and modal form
+
+**Data source:** `GET /api/orgs/{org}/artifacts/registries`
+
+### Feed Browser
+
+**Route:** `/orgs/{org}/artifacts/registries/{registry}/feeds`
+
+**Components:**
+- Feed list: name, visibility badge (public/private), version count, install command code snippet
+- Create feed button, manage access policies button
+
+**Data source:** `GET /api/orgs/{org}/artifacts/feeds`
+
+### Version Table
+
+**Route:** `/orgs/{org}/artifacts/registries/{registry}/feeds/{feed}`
+
+**Components:**
+- Paginated version table: package name, version, size (human-readable), publishedBy, publishedAt, checksum (truncated SHA-256)
+- Publish version button (file upload + metadata form)
+- Download button per version
+
+**Data source:** `GET /api/orgs/{org}/artifacts/feeds/{feed}/versions`
+
+### Access Policies
+
+Embedded as a tab within feed detail.
+
+- Table: subject, permission badge (read/write/admin), expiresAt
+- Add policy form, revoke button per entry
+
+---
+
+## Assistant Navigation Group
+
+### Chat Interface
+
+**Route:** `/orgs/{org}/assistant`
+
+**Components:**
+- Session sidebar: scrollable list of sessions (org:sessionId), new session button, session delete button
+- Chat panel: message thread with user/assistant bubbles, SSE streaming renders chunks in real time
+- Input bar: expandable textarea, send button, model selector dropdown
+
+**Data source:**
+- `POST /api/orgs/{org}/assistant/chat` (SSE stream)
+- `GET /api/orgs/{org}/assistant/sessions` (session list)
+
+### Generation Form
+
+**Route:** `/orgs/{org}/assistant/generate`
+
+**Components:**
+- Prompt textarea
+- Optional JSON schema editor (collapsible)
+- Generate button
+- Response viewer: formatted JSON when schema provided, markdown otherwise
+
+**Data source:** `POST /api/orgs/{org}/assistant/generate`
+
+### Session Sidebar
+
+Embedded in the chat interface. Lists all sessions for the current org. Clicking a session loads its message history. Delete button calls `DELETE /api/orgs/{org}/assistant/sessions/{sessionId}` and clears the thread.
+
+---
+
+## Updated Navigation Structure
+
+| Group | Routes |
+|-------|--------|
+| Repositories | `/repos`, `/repos/{name}/*` |
+| Agents | `/agents`, `/agents/stacks`, `/agents/runs`, `/agents/memory` |
+| **ML** | `/inference/services`, `/inference/runtimes` |
+| **Artifacts** | `/artifacts/registries`, feeds, versions |
+| **Assistant** | `/assistant`, `/assistant/generate` |
+| Policy | `/policies`, `/policy-exceptions` |
+| Settings | `/settings/*` |