@a5c-ai/krate 5.0.1-staging.f672fe79b

package/docs/agents/system-overview.md

@@ -0,0 +1,88 @@
+# Agent system overview
+
+## Purpose
+
+This document is the short entry point for the full agent orchestration spec set. It explains the product shape, implementation boundaries, and first build target without requiring readers to open every detailed spec first.
+
+## Product thesis
+
+Krate agents are repository-native work executors. They should feel like a CI run plus a durable chat/session: queued on runner capacity, scoped to a repository/ref/source object, governed by Kubernetes-native RBAC and grants, observable in real time, artifact-producing, approval-gated, and linked back to Code, Issues, Pull Requests, Runs, Hooks, Workspaces, Inbox, and Settings.
+
+Agent Mux provides adapter/session/chat/runtime capabilities. Krate owns the repository graph, resource model, policy, triggers, RBAC, secret/config grants, context assembly, dispatch run state, approvals, artifacts, audit, and UI hierarchy.
+
+## Big picture flow
+
+```text
+Repository/PR/Issue/Pipeline/Webhook/manual action
+  -> trigger or manual dispatch request
+  -> context assembly and redaction
+  -> permission review
+  -> AgentDispatchRun and AgentDispatchAttempt
+  -> Agent Mux launch/session binding
+  -> event/transcript/artifact reconciliation
+  -> approvals and optional write-back
+  -> repository page projections and audit
+```
+
+## Main resource families
+
+| Family | Resources | Why it exists |
+| --- | --- | --- |
+| Stack config | `AgentStack`, `AgentToolProfile`, `AgentMcpServer`, `AgentSkill`, `AgentSubagent` | defines what can run. |
+| Permission config | `AgentServiceAccount`, `AgentRoleBinding`, `AgentSecretGrant`, `AgentConfigGrant` | defines who/what can access roles, secrets, config, and runners. |
+| Trigger config | `AgentTriggerRule`, `AgentContextLabel`, `AgentWorkspacePolicy` | defines when/how context and workspace are selected. |
+| Execution records | `AgentDispatchRun`, `AgentDispatchAttempt`, `AgentSession`, `AgentTriggerExecution` | tracks work like CI runs. |
+| Context/artifacts | `AgentContextBundle`, `AgentArtifact`, `AgentReviewArtifact` | makes prompts and outputs durable/auditable. |
+| Human gates | `AgentApproval` | gates tools, secrets, write-back, release actions, and risky operations. |
+| Work graph links | `AgentWorkspace`, `WorkItemSessionLink`, `WorkItemWorkspaceLink` | connects sessions/workspaces/runs to issues, PRs, and repository pages. |
+
+## First build target
+
+The MVP is intentionally narrow:
+
+1. Define one read-only/diagnostic stack.
+2. Validate Kubernetes-native ServiceAccount/RBAC/Secret/Config access.
+3. Dispatch manually from Code or Runs.
+4. Create `AgentDispatchRun`, `AgentDispatchAttempt`, context bundle, and permission snapshot before Agent Mux launch.
+5. Show the run beside CI runs and in `/agents/runs`.
+6. Bind Agent Mux session if configured; otherwise show a clear degraded state.
+
+Deferred from MVP: auto triggers, write-back, branch pushes, full workspace lifecycle, subagent execution, retention jobs, and production MCP management.
+
+## Existing Krate seams to preserve
+
+- `src/resource-model.js` remains the kind/schema source of truth.
+- `src/kubernetes-controller.js` remains the Kubernetes-style resource gateway.
+- `src/api-controller.js` remains the HTTP/application facade.
+- `src/controller-ui.js` remains the server-projected UI model.
+- `/api/controller/resources` remains the generic list/apply path.
+- `/api/watch/orgs/[org]/*` is the watch/SSE pattern.
+- Repository routes stay under `/orgs/[org]/repositories/[repo]/...`.
+
+Typed agent APIs and pages should wrap these seams, not bypass them.
+
+## Safety invariants
+
+- No Secret values in browser, prompt preview, status, logs, audit, or docs examples.
+- Kubernetes RBAC remains authoritative.
+- Labels/comments/context labels cannot grant permissions.
+- Untrusted/forked refs cannot use privileged ServiceAccounts or secrets.
+- Agent output cannot write back without policy and approval.
+- Agent Mux is not source of truth for Krate repository objects.
+- Every visible UI action maps to resource/action/controller/watch state.
+
+## Where to read next
+
+- Start implementation with [MVP vertical slice spec](./mvp-vertical-slice-spec.md).
+- Add kinds from [Agent CRD schema spec](./crd-schema-spec.md).
+- Add controllers from [Controller reconciliation spec](./controller-reconciliation-spec.md).
+- Use [API contract spec](./api-contract-spec.md) for route bodies.
+- Use [UI flow and state spec](./ui-flow-spec.md) for screens.
+- Use [Security threat model](./security-threat-model.md) before enabling write-back or secrets.
+- Use [Developer implementation checklist](./developer-implementation-checklist.md) as the execution checklist.
+
+## Company brain memory layer
+
+Krate should include an org-level company brain as a first-class context source. The company brain is a managed internal Git repository containing Atlas-style YAML graph records, Markdown files with YAML frontmatter, ontology definitions, and free-form Markdown notes searchable with grep. Dispatches can read current memory or a historical memory ref, and every selected memory item is captured in `AgentContextBundle` through `AgentMemorySnapshot` and `AgentMemoryQuery` records.
+
+This layer belongs to Krate's repository and policy plane: Krate owns memory repository configuration, RBAC, path/kind grants, ref resolution, context digests, update approvals, validation, and audit. Agent Mux may execute memory tools inside a session only after Krate admits those capabilities.

package/docs/agents/tools-mcp-skills-spec.md

@@ -0,0 +1,189 @@
+# Agent tools, MCP, and skills spec
+
+## Purpose
+
+This document defines how Krate should manage native tools, MCP servers, and skills as first-class system capabilities. Tools, MCP servers, and skills are not just UI settings; they affect launch options, permission review, Secret/ConfigMap requirements, audit, and dispatch readiness.
+
+## Resource ownership
+
+| Capability | Resource | Scope |
+| --- | --- | --- |
+| Native tools and shell/filesystem/network policy | `AgentToolProfile` | stack/repository/org |
+| MCP server endpoint and discovered tools | `AgentMcpServer` | global/org/repository/stack |
+| Reusable runbook or prompt/tool bundle | `AgentSkill` | global/org/repository/stack |
+| Required roles/secrets/configs | `AgentCapabilityRequirement` | computed per stack/capability |
+| Secret access | `AgentSecretGrant` | subject + purpose + source scope |
+| Config access | `AgentConfigGrant` | subject + purpose + source scope |
+
+## `AgentToolProfile`
+
+Tool profiles should describe categories, not raw prompt text.
+
+Required concerns:
+
+- native tool enablement: shell, filesystem, browser, code search, git, test runner, package manager;
+- filesystem scope: no-fs, read-only, repo-write, workspace-write;
+- network scope: deny, allowlist, repository-host-only, unrestricted-with-approval;
+- command allow/deny lists;
+- approval policy by tool class;
+- required roles;
+- required Secret/ConfigMap refs;
+- audit level.
+
+Readiness checks:
+
+- command deny patterns compile;
+- filesystem policy compatible with runner trust tier;
+- network policy compatible with repository policy;
+- required roles admitted;
+- required Secret/ConfigMap grants admitted;
+- adapter supports requested native tools.
+
+## `AgentMcpServer`
+
+MCP servers should be managed as runtime dependencies with health and permission state.
+
+Required concerns:
+
+- transport: stdio, SSE, streamable HTTP;
+- command/args or URL;
+- env refs and header refs;
+- Secret/ConfigMap refs;
+- discovered tools and schemas;
+- allowed stacks/orgs/[org]/repositories;
+- network policy;
+- approval policy;
+- health and last probe.
+
+MCP health states:
+
+- `Unknown`: not probed yet;
+- `Ready`: reachable and schema discovered;
+- `Degraded`: reachable but some tools unavailable;
+- `Denied`: policy/RBAC/grant blocked;
+- `Failed`: probe failed;
+- `Disabled`: lifecycle disabled.
+
+## `AgentSkill`
+
+Skills should behave like reusable capability bundles.
+
+Skill fields:
+
+- description and owner;
+- source format: file, directory, package, inline;
+- source ref and version;
+- prompt fragment;
+- required tools;
+- required MCP servers;
+- required Secret/ConfigMap refs;
+- compatible base agents/adapters;
+- task kinds;
+- output contract;
+- validation status.
+
+Skill validation:
+
+1. Source exists and version resolves.
+2. Prompt fragment passes policy checks.
+3. Required tools/MCP servers exist and are admitted.
+4. Required Secret/ConfigMap grants exist for selected stack identity.
+5. Output contract is compatible with task kind and UI projection.
+
+## Capability requirement graph
+
+Every stack should have a computed dependency graph:
+
+```text
+AgentStack
+  -> AgentToolProfile
+    -> required roles/secrets/configs
+  -> AgentMcpServer
+    -> transport/network/secrets/configs/discovered tools
+  -> AgentSkill
+    -> prompt fragment/tools/MCP/secrets/configs/output contract
+  -> AgentSubagent
+    -> tool subset/skill subset/MCP subset
+```
+
+The graph should produce `AgentCapabilityRequirement` records and UI warnings.
+
+## UI requirements
+
+### Tools page
+
+- list tool profiles;
+- show allowed/denied commands;
+- show filesystem/network policy;
+- show consuming stacks;
+- show required grants and missing grants;
+- preview launch impact.
+
+### MCP page
+
+- list servers and health;
+- show discovered tools;
+- show Secret/ConfigMap refs without values;
+- show allowed stacks and denied stacks;
+- run probe/dry-run when authorized.
+
+### Skills page
+
+- list skills by task kind;
+- show prompt fragment preview;
+- show required tools/MCP/secrets/configs;
+- show consuming stacks;
+- show validation errors and output contract.
+
+### Stack builder integration
+
+The stack builder must show tools/MCP/skills as dependency cards with:
+
+- readiness;
+- missing roles/secrets/configs;
+- adapter support;
+- approval requirements;
+- launch option preview;
+- audit level.
+
+## Dispatch-time behavior
+
+At dispatch launch:
+
+1. Expand selected tools, MCP servers, and skills.
+2. Re-run permission review.
+3. Materialize only admitted launch options.
+4. Snapshot dependency graph digest.
+5. Send admitted tool/MCP/skill configuration to Agent Mux.
+6. Record tool/MCP/skill versions in attempt status.
+
+## Security rules
+
+- A skill cannot grant tools, roles, secrets, configs, or approval mode by prompt text.
+- MCP server command/env/header refs must use grants and policy.
+- Shell tools default to approval for privileged commands.
+- Network access defaults to deny or allowlist.
+- Tool output containing suspected secrets must be redacted before transcript/artifact persistence.
+
+## Acceptance criteria
+
+- A stack cannot dispatch with a tool requiring an ungranted Secret.
+- MCP health and discovered tools are visible before dispatch.
+- Skills show required tools/MCP/secrets/configs and output contract.
+- Tool/MCP/skill launch options are snapshotted into dispatch attempts.
+- UI can explain exactly why a capability is disabled or approval-gated.
+
+## Company brain memory tools
+
+Memory tools are normal tool capabilities and require the same stack admission, permission review, audit, and Agent Mux launch gating as other tools.
+
+| Tool | Purpose | Required grant |
+| --- | --- | --- |
+| `memory.graph.search` | search graph records by text, kind, edge, owner, repo, stack, or association | memory query grant for allowed kinds/paths. |
+| `memory.record.read` | read a graph or Markdown record by ID/path at the dispatch memory ref | memory read grant. |
+| `memory.docs.grep` | grep allowed free-form Markdown paths at the pinned commit | memory grep grant. |
+| `memory.snapshot.diff` | compare pinned memory with current or another ref | memory diff grant. |
+| `memory.update.propose` | create a proposed memory patch artifact | memory propose-update grant. |
+| `memory.ontology.validate` | validate proposed graph/frontmatter changes | memory validation grant. |
+
+Tools default to the dispatch `AgentMemorySnapshot`. Accessing current memory from a historical-memory run requires explicit refresh or approval so agents cannot silently escape the pinned context.

package/docs/agents/traceability-matrix.md

@@ -0,0 +1,79 @@
+# Agent traceability matrix
+
+## Purpose
+
+This matrix maps product requirements to resources, controllers, UI surfaces, docs, and validation gates. It is intended for implementation reviews and PR checklists.
+
+## Requirement traceability
+
+| Requirement | Resources | Controllers/APIs | UI surfaces | Primary docs | Validation |
+| --- | --- | --- | --- | --- | --- |
+| Define an agent stack | `AgentStack`, tools, MCP, skills, subagents | stack controller, resource API | `/agents/stacks` | stack, CRD, tools, subagent specs | schema + UI validation |
+| Validate ServiceAccount/RBAC | `AgentServiceAccount`, `AgentRoleBinding` | RBAC controller, permission review API | `/agents/permissions`, stack builder | RBAC spec | permission tests |
+| Grant Secret/Config access | `AgentSecretGrant`, `AgentConfigGrant` | secret/config controller | `/agents/secrets`, grant wizards | RBAC spec, tools spec | no-secret-value tests |
+| Assemble prompt/context | `AgentContextBundle`, context labels | context bundle service | dispatch composer, run detail | context spec | redaction tests |
+| Dispatch manually from repo | `AgentDispatchRun`, `AgentDispatchAttempt` | dispatch API/controller | Code/Runs pages | MVP, API, repo integration | API + UI tests |
+| Show CI-like run | dispatch run/attempt/session | dispatch controller, watch API | `/agents/runs`, repo Runs | UI flow, repository integration | UI validation |
+| Bind Agent Mux session | attempt/session | Agent Mux client | run detail chat panel | adapter contract | gateway fallback tests |
+| Manage tools/MCP/skills | tool/MCP/skill resources | stack/capability controllers | `/agents/tools`, `/mcp`, `/skills` | tools spec | capability tests |
+| Run subagents | `AgentSubagent`, attempts/artifacts | dispatch/subagent controller | run detail subagent tree | subagent spec | child permission tests |
+| Produce artifacts | artifacts/review artifacts | artifact service | run/PR/issue/pipeline pages | artifacts spec | digest tests |
+| Gate write-back | approvals/artifacts | approval controller | inbox/run detail | artifacts, security specs | idempotency tests |
+| Trigger from CI/webhook | trigger rules/executions | trigger controller | rules/hooks/pipelines | CI, trigger, API specs | dry-run/dedupe tests |
+| Manage workspace lifecycle | workspace/link resources | workspace controller | workspaces/issues/PR/run | workspace spec | lifecycle tests |
+| Observe and audit | audit/events/metrics | all controllers | run detail/insights | observability spec | audit/no-secret tests |
+| Package/deploy agents | CRDs/chart values/templates | chart/package validation | operations install | chart spec | package check |
+
+## File traceability
+
+| Future implementation file | Governing docs |
+| --- | --- |
+| `src/resource-model.js` | CRD schema, MVP, developer checklist |
+| `src/kubernetes-controller.js` | CRD schema, controller reconciliation, chart spec |
+| `src/controller-ui.js` | UI flow, repository integration, observability |
+| `src/api-controller.js` | API contract, controller reconciliation |
+| `src/agent-permission-review.js` | RBAC spec, API contract, MVP |
+| `src/agent-stack-controller.js` | stack spec, tools spec, RBAC spec |
+| `src/agent-context-bundles.js` | context assembly spec |
+| `src/agent-dispatch-controller.js` | controller reconciliation, adapter contract, MVP |
+| `src/agent-mux-client.js` | Agent Mux adapter contract |
+| `src/agent-trigger-controller.js` | CI spec, controller reconciliation |
+| `src/agent-workspace-controller.js` | workspace lifecycle spec |
+| `src/agent-approval-controller.js` | artifacts/write-back spec |
+| `apps/web/app/agents/*` | UI flow, repository integration |
+| `charts/krate/*` | chart packaging, storage migration |
+| `examples/agents/*` | resource examples, package validation |
+| `tests/*` | acceptance test matrix |
+
+## Review checklist
+
+Before merging implementation work, reviewers should ask:
+
+- Which requirement row does this change satisfy?
+- Which resource/controller/UI path backs the user action?
+- Does the change preserve current generic resource/watch APIs?
+- Are Secret values excluded from responses/status/logs/tests?
+- Are denied states explainable from server-side conditions?
+- Did package/docs/UI validation run?
+- Did the PR update the affected docs and examples?
+
+## Org memory traceability
+
+| Requirement | Resources | Controllers | UI | Docs | Validation |
+| --- | --- | --- | --- | --- | --- |
+| Org namespace isolation | `Organization`, `OrgNamespaceBinding` | org controller, admission | org switcher, YAML panels | org scoping spec | cross-org rejection tests |
+| Company brain per org | `AgentMemoryRepository`, `AgentMemorySource` | memory controller | `/orgs/[org]/agents/memory` | memory specs | memory query permission tests |
+| Babysitter run memory import | `AgentRunMemoryImport`, `AgentRunJournalEvent` | memory import controller | memory imports panel | memory runbook | redaction/import validation |
+| Historical memory dispatch | `AgentMemorySnapshot`, `AgentMemoryQuery` | context assembler | dispatch memory advanced panel | context integration | refAt resolution tests |
+
+## Current app seam traceability
+
+| Seam | Current file | Agent/memory use |
+| --- | --- | --- |
+| Org shell/navigation | `apps/web/app/ui-shell.jsx` | add Agents nav, memory attention counters, org breadcrumbs. |
+| Org routes | `apps/web/app/orgs/[org]/*` | add `/agents/*` and `/agents/memory/*`. |
+| Repo tabs | `apps/web/app/orgs/[org]/repositories/[repo]/*` | add dispatch actions, linked sessions/workspaces, memory associations. |
+| Org resource API | `apps/web/app/api/orgs/[org]/resources/*` | list/apply agent and memory resources. |
+| Watch API | `apps/web/app/api/watch/[[...resource]]/route.js` | stream org-scoped agent runs/imports after resource support. |
+| Resource model | `src/resource-model.js` | add agent/memory kinds with `organizationRef`. |
+| API controller | `src/api-controller.js` | add typed dispatch, memory query, import, approve, merge actions. |

package/docs/agents/ui-flow-spec.md

@@ -0,0 +1,211 @@
+# Agent UI flow and state spec
+
+## Purpose
+
+This document translates the agent specs into concrete UI flows that fit the existing Krate app. Current UI facts:
+
+- Repository routes are already organized under `/orgs/[org]/repositories/[repo]/code`, `/issues`, `/pull-requests`, `/runs`, `/hooks`, and `/settings`.
+- `apps/web/app/ui-shell.jsx` centralizes most page rendering and favors GitHub-like repository pages with advanced YAML panels.
+- `LiveWatchPanel` already consumes `/api/watch/orgs/[org]/*` streams.
+- Existing pages emphasize disabled states backed by access checks and advanced plans hidden behind expandable panels.
+
+Agent UI should extend this style instead of becoming a separate chat-only dashboard.
+
+## Navigation additions
+
+Global routes:
+
+- `/agents`: operational overview.
+- `/agents/stacks`: stack registry and builder.
+- `/agents/runs`: dispatch queue.
+- `/agents/runs/[run]`: run/session detail.
+- `/agents/rules`: trigger rules and dry-run.
+- `/agents/workspaces`: workspace inventory.
+- `/agents/approvals`: approval inbox.
+- `/agents/identities`: ServiceAccounts, users, teams, native RBAC projections.
+- `/agents/secrets`: Secret/ConfigMap grants and consumers.
+- `/agents/permissions`: role templates, RoleBindings, drift, and permission review.
+
+Repository route extensions:
+
+- `/orgs/[org]/repositories/[repo]/code`: add `Dispatch agent` button, selected paths, branch/ref, active workspace/session chips.
+- `/orgs/[org]/repositories/[repo]/issues`: add agent-ready board/list, context labels, linked workspaces/sessions/runs.
+- `/orgs/[org]/repositories/[repo]/pull-requests`: add diagnose/repair/review agents, patch artifacts, write-back approvals.
+- `/orgs/[org]/repositories/[repo]/runs`: show `AgentDispatchRun` rows beside `Pipeline` and `Job` rows.
+- `/orgs/[org]/repositories/[repo]/hooks`: show trigger matches, delivery replay, and rule evaluation.
+- `/orgs/[org]/repositories/[repo]/settings/agents`: stack permissions, triggers, ServiceAccounts, grants, runner policy.
+
+## Stack builder flow
+
+1. Choose base agent and adapter.
+2. Choose model/provider and prompt.
+3. Select runtime ServiceAccount.
+4. Select tool profile, MCP servers, skills, subagents, context labels.
+5. Choose runner pool and workspace policy.
+6. UI calls permission review.
+7. UI shows capability requirements matrix.
+8. User fixes missing RBAC/Secret/Config grants or removes capabilities.
+9. UI previews resource YAML.
+10. Save applies resources through controller API.
+
+Required states:
+
+- no adapters configured;
+- adapter capability unavailable;
+- ServiceAccount missing;
+- role escalation denied;
+- missing Secret grant;
+- missing ConfigMap grant;
+- Secret key missing;
+- ConfigMap key sensitive/hidden;
+- stack ready;
+- stack ready but requires approval for selected sources.
+
+## Secret grant wizard
+
+Entry points:
+
+- stack builder warning;
+- tool profile page;
+- skill detail page;
+- MCP server page;
+- `/agents/secrets`;
+- denied dispatch explanation.
+
+Flow:
+
+1. Show requesting capability and why it needs the Secret.
+2. Show selected runtime ServiceAccount and repository/ref scope.
+3. Let authorized user select Secret/key metadata or create write-only key.
+4. Select purpose, mount policy, trigger/ref scope, and approval requirement.
+5. Preview `AgentSecretGrant` YAML and permission review result.
+6. Apply grant and recompute stack readiness.
+
+UI must never show Secret values after write.
+
+## Config grant wizard
+
+Flow mirrors Secret grant wizard, but ConfigMap values can be shown only when native RBAC permits and Krate sensitivity policy allows it. Otherwise show key names and metadata only.
+
+## Permission review panel
+
+Reusable panel for stack builder, trigger dry-run, dispatch composer, and denied run states.
+
+Sections:
+
+- actor and Kubernetes identity;
+- runtime ServiceAccount and runner ServiceAccount;
+- role checks;
+- required Secrets and grants;
+- required ConfigMaps and grants;
+- trust-tier constraints;
+- approval requirements;
+- least-privilege suggested fixes;
+- YAML preview for permitted fixes.
+
+## Dispatch composer flow
+
+On Code/Issue/PR/Pipeline pages:
+
+1. User opens dispatch composer.
+2. Source refs are prefilled from route context.
+3. User chooses stack, task kind, context labels, paths/artifacts/logs, workspace mode.
+4. UI calls permission review and context preview.
+5. User confirms.
+6. API creates `AgentDispatchRun` and `AgentDispatchAttempt` before Agent Mux launch.
+7. UI navigates to run detail or keeps an inline status chip.
+
+## Run detail flow
+
+Layout should feel like a CI check page plus Agent Mux chat:
+
+- Header: repository, source object, branch/SHA, stack, runner, ServiceAccounts, phase, approvals.
+- Left: source context, logs/artifacts/files/context labels.
+- Center: Agent Mux transcript and continuation composer.
+- Right: attempts, event timeline, tools, MCP, skills, subagents, Secret/Config grants, approvals, artifacts.
+- Footer: cancel/retry/resume/fork/continue controls when admitted.
+
+States:
+
+- queued;
+- runner waiting;
+- permission snapshot pending;
+- Agent Mux session binding pending;
+- stream disconnected/reconnecting;
+- waiting for approval;
+- workspace missing/rebase conflict;
+- adapter launch rejected;
+- succeeded/failed/cancelled.
+
+## Repository settings agents tab
+
+This page is the GitHub-like management hub for a repository:
+
+- enabled stacks;
+- allowed triggers;
+- allowed runner pools;
+- runtime ServiceAccounts;
+- runner ServiceAccounts;
+- Secret grants;
+- ConfigMap grants;
+- role bindings;
+- dry-run permission review.
+
+The page should show safe defaults first and advanced YAML only in expandable panels, matching current Krate UI conventions.
+
+## Empty and denied states
+
+Every action-disabled state must include:
+
+- action attempted;
+- resource involved;
+- Kubernetes identity used;
+- missing permission or policy reason;
+- whether the user can fix it;
+- link to permission review or relevant settings page.
+
+## Integration with current app
+
+Initial implementation can reuse:
+
+- `apps/web/app/ui-shell.jsx` page patterns;
+- `ResourceTable` for generic resource visibility;
+- `PlanCard` for YAML previews;
+- `LiveWatchPanel` for dispatch/watch streams;
+- existing repository route wrappers in `apps/web/app/orgs/[org]/repositories/[repo]/*/page.jsx`.
+
+Typed components should be introduced once the resource/controller contracts exist.
+
+## Memory user flows
+
+### Configure company brain
+
+1. Admin opens `/agents/memory` and creates or adopts `AgentMemoryRepository`.
+2. Krate validates layout and ontology.
+3. Admin creates `AgentMemorySource` policies for repositories, teams, stacks, and triggers.
+4. UI shows generated YAML, RBAC implications, and validation status.
+
+### Dispatch with memory
+
+1. User opens repository Code, Issue, PR, or Pipeline page.
+2. User opens dispatch composer and expands Memory.
+3. UI shows default memory source, current commit, query preview, and selected records/excerpts.
+4. User optionally chooses explicit ref, snapshot tag, or `refAt` timestamp.
+5. Krate resolves commit and creates `AgentMemorySnapshot` before launch.
+
+### Review memory update
+
+1. Agent proposes memory update from run detail.
+2. UI shows diff, source run, evidence, ontology validation, secret scan, and owners.
+3. Reviewer approves, requests changes, rejects, or merges.
+4. Merge updates memory repo and links new commit to the source run.
+
+## Org-scoped route migration flow
+
+1. User opens `/orgs/[org]/repositories/[repo]/code`.
+2. Server resolves visible repositories matching `[repo]`.
+3. Krate stays within the explicit `/orgs/[org]` route and never resolves a repository without org context.
+4. If multiple matches exist, show an org picker with visible org names only.
+5. If no match exists, show a normal not-found state without leaking private orgs.
+
+All dispatch composers, memory pages, deployment pages, and settings pages should use org-aware routes directly.