@a5c-ai/krate 5.0.1-staging.f672fe79b

package/docs/agents/org-memory-ui-implementation-map.md

@@ -0,0 +1,114 @@
+# Org memory UI implementation map
+
+## Purpose
+
+This document maps the org-scoped company brain and agent memory requirements onto the current Krate web app seams. It is docs-only and should guide implementation without changing code yet.
+
+## Current UI anchors
+
+The app already has organization-first navigation and repository routes:
+
+| Current file/route | Existing role |
+| --- | --- |
+| `apps/web/app/ui-shell.jsx` | shared app shell, org switcher, org navigation, repository navigation, `orgHref()` route helper. |
+| `apps/web/app/orgs/page.jsx` | organization list. |
+| `apps/web/app/orgs/[org]/page.jsx` | org dashboard. |
+| `apps/web/app/orgs/[org]/repositories/page.jsx` | org repository list. |
+| `apps/web/app/orgs/[org]/repositories/[repo]/code/page.jsx` | org-scoped code page. |
+| `apps/web/app/orgs/[org]/repositories/[repo]/issues/page.jsx` | org-scoped issues page. |
+| `apps/web/app/orgs/[org]/repositories/[repo]/pull-requests/page.jsx` | org-scoped reviews/PR page. |
+| `apps/web/app/orgs/[org]/repositories/[repo]/runs/page.jsx` | org-scoped runs page. |
+| `apps/web/app/orgs/[org]/repositories/[repo]/hooks/page.jsx` | org-scoped automations page. |
+| `apps/web/app/orgs/[org]/repositories/[repo]/settings/page.jsx` | org-scoped repository settings. |
+| `apps/web/app/orgs/[org]/deployments/page.jsx` | org-scoped deployment page. |
+| `apps/web/app/orgs/[org]/runs/page.jsx` | org-level run center. |
+| `apps/web/app/api/orgs/[org]/resources/*` | org-scoped resource API bridge. |
+
+This means the future agent/memory work should extend the existing org route tree rather than introduce global `/agents` pages first.
+
+## Missing routes to add later
+
+| Route | Purpose | Primary resources |
+| --- | --- | --- |
+| `/orgs/[org]/agents` | org agent dashboard | stacks, runs, approvals, memory health. |
+| `/orgs/[org]/agents/stacks` | stack registry and builder | `AgentStack`, tools, MCP, skills, subagents. |
+| `/orgs/[org]/agents/runs` | all org agent dispatches | `AgentDispatchRun`, attempts, sessions. |
+| `/orgs/[org]/agents/runs/[run]` | CI-like run detail with Agent Mux chat | run, attempt, session, context, artifacts. |
+| `/orgs/[org]/agents/rules` | trigger management | `AgentTriggerRule`, executions. |
+| `/orgs/[org]/agents/workspaces` | workspace/session/work item management | `AgentWorkspace`, links. |
+| `/orgs/[org]/agents/memory` | company brain dashboard | memory repo, ontology, imports, updates. |
+| `/orgs/[org]/agents/memory/graph` | graph browser | graph records and edges. |
+| `/orgs/[org]/agents/memory/search` | grep/frontmatter search | memory query. |
+| `/orgs/[org]/agents/memory/imports` | `.a5c` and session import review | `AgentRunMemoryImport`. |
+| `/orgs/[org]/agents/memory/updates` | memory update PR/review queue | `AgentMemoryUpdate`. |
+| `/orgs/[org]/agents/permissions` | RBAC/secret/config/memory grants | grants and capability requirements. |
+
+Repository pages should link into these routes with the active org and repo preserved in query params or source refs.
+
+## Navigation changes
+
+Add an `Agents` top-level item to org navigation after `Runs` and before `Capacity`. The item should display attention counters for:
+
+- running/failed agent dispatches;
+- pending approvals;
+- memory imports awaiting review;
+- blocked stacks due to missing RBAC, secrets, config, or memory grants;
+- stale memory ontology/index status.
+
+The `Advanced` page should keep raw resource plans, but day-to-day agent and memory management belongs under `Agents`.
+
+## Repository page integrations
+
+| Repository tab | Agent/memory additions |
+| --- | --- |
+| Code | dispatch agent from path/ref; include company brain records associated with path/repo; memory source preview. |
+| Issues | linked sessions/workspaces/runs; issue-trigger dispatch; related memory runbooks and retrospectives. |
+| Pull requests | failed-check repair dispatch; review artifacts; related decisions/runbooks; memory update suggestions. |
+| Runs | merge CI pipeline rows with agent dispatch rows; link to Agent Mux chat/session. |
+| Hooks | trigger dry-run and webhook-to-agent rule preview. |
+| Settings | `AgentMemorySource`, stack defaults, trigger rules, permissions, secret/config/memory grants. |
+
+## Components to add later
+
+| Component | Responsibility |
+| --- | --- |
+| `AgentDashboardPage` | org-level agent overview and attention cards. |
+| `AgentRunDetailPage` | CI-like run timeline, Agent Mux chat, context, memory, artifacts. |
+| `MemoryDashboardPage` | company brain health, current commit, ontology, imports, updates. |
+| `MemoryGraphBrowser` | node/edge browsing with org-scoped permissions. |
+| `MemorySearchPanel` | graph/frontmatter/grep queries with redaction and source preview. |
+| `MemoryImportReviewPanel` | `.a5c` import diff, redaction, validation, approval, merge. |
+| `OrgScopedResourceGuard` | validates org route params against resource labels/namespace before render. |
+| `AgentPermissionReviewPanel` | explains missing RBAC, Secret, ConfigMap, memory, tool, skill grants. |
+
+## API calls needed by UI
+
+- `GET /api/orgs/[org]/resources` for generic resource tables.
+- `GET /api/orgs/[org]/agents/summary` for attention counters.
+- `POST /api/orgs/[org]/agents/dispatch` for manual dispatch.
+- `GET /api/orgs/[org]/agents/runs/[run]` for run detail projection.
+- `POST /api/orgs/[org]/agents/memory/query` for preview/search.
+- `POST /api/orgs/[org]/agents/memory/import-babysitter-run` for run import.
+- `POST /api/orgs/[org]/agents/memory/updates/[id]/approve` for review actions.
+- `GET /api/watch/orgs/[org]/agentdispatchruns` for live run updates.
+
+## UX acceptance criteria
+
+- Agent and memory pages never render without an org route param.
+- Legacy global agent routes redirect to org routes only when org is unambiguous.
+- Every memory result shows source path, memory commit, digest, and permission status.
+- Every imported `.a5c` run shows source run, session, retention tier, redaction status, validation report, and target memory PR.
+- Repository pages link to org-scoped agent/memory routes without losing repo context.
+
+## Implementation order
+
+1. Add resource-model kinds and examples so generic resource tables can display agent/memory data.
+2. Add org route shells for `/orgs/[org]/agents` and `/orgs/[org]/agents/memory` with empty states.
+3. Add summary endpoints and attention counters.
+4. Add repository dispatch affordances and memory association previews.
+5. Add run detail with Agent Mux session panel.
+6. Add memory query/search/graph views.
+7. Add memory import review and update review flows.
+8. Add live watch streams and notification counters.
+
+Each step should preserve the existing org shell and advanced YAML panels.

package/docs/agents/org-memory-vertical-slice-spec.md

@@ -0,0 +1,168 @@
+# Org memory vertical slice spec
+
+## Purpose
+
+This document defines the smallest coherent implementation slice for org-scoped agent memory. It is designed to prove that Krate can manage an org company brain, assemble memory into an agent dispatch, import curated run memory, and preserve org isolation without implementing every advanced UI or automation path.
+
+## Slice outcome
+
+A user can:
+
+1. select an org;
+2. open a repository in that org;
+3. configure a company brain memory source for the repository;
+4. manually dispatch an agent with a memory preview;
+5. inspect the run detail with memory snapshot provenance;
+6. import a summarized run/session into the org memory repo;
+7. query that imported memory in a later dispatch;
+8. verify that another org cannot read or import the memory.
+
+## Included resources
+
+Config resources:
+
+- `Organization`;
+- `OrgNamespaceBinding`;
+- `Repository`;
+- `AgentStack`;
+- `AgentMemoryRepository`;
+- `AgentMemorySource`;
+- `AgentMemoryOntology`;
+- `AgentServiceAccount`;
+- `AgentRoleBinding`.
+
+Aggregated resources:
+
+- `AgentDispatchRun`;
+- `AgentDispatchAttempt`;
+- `AgentSession`;
+- `AgentContextBundle`;
+- `AgentMemorySnapshot`;
+- `AgentMemoryQuery`;
+- `AgentRunMemoryImport`;
+- `AgentArtifact`;
+- `AgentApproval`.
+
+Deferred resources for later slices:
+
+- `AgentSubagent` advanced trees;
+- full `AgentMemoryUpdate` editing UI beyond import PRs;
+- broad trigger automation;
+- cross-org sharing;
+- raw artifact-byte retention;
+- vector/embedding indexes.
+
+## UI scope
+
+Required screens:
+
+| Screen | Minimum capability |
+| --- | --- |
+| `/orgs/[org]` | shows Agents and Memory attention cards. |
+| `/orgs/[org]/repositories/[repo]/code` | manual dispatch button with memory preview. |
+| `/orgs/[org]/repositories/[repo]/runs` | shows agent dispatch rows beside pipeline rows. |
+| `/orgs/[org]/agents/runs/[run]` | shows run timeline, Agent Mux session placeholder/link, context bundle, memory snapshot. |
+| `/orgs/[org]/agents/memory` | shows memory repo health, current commit, ontology status, imports. |
+| `/orgs/[org]/agents/memory/search` | can query selected graph/Markdown sources. |
+| `/orgs/[org]/agents/memory/imports/[import]` | review summarized import, redaction, validation, PR/merge state. |
+| `/orgs/[org]/repositories/[repo]/settings` | can attach `AgentMemorySource` to the repo. |
+
+## API scope
+
+Required endpoints:
+
+| Endpoint | Minimum capability |
+| --- | --- |
+| `GET /api/orgs/[org]/agents/summary` | dashboard counters. |
+| `POST /api/orgs/[org]/agents/dispatch` | create manual dispatch with memory snapshot. |
+| `GET /api/orgs/[org]/agents/runs/[run]` | run detail projection. |
+| `POST /api/orgs/[org]/agents/memory/query` | graph/frontmatter/grep preview. |
+| `POST /api/orgs/[org]/agents/memory/resolve-ref` | current and explicit ref resolution. |
+| `POST /api/orgs/[org]/agents/memory/import-babysitter-run` | summary-only import. |
+| `POST /api/orgs/[org]/agents/memory/imports/[import]/approve` | approve import PR/merge. |
+| `GET /api/watch/orgs/[org]/agentdispatchruns` | run updates. |
+| `GET /api/watch/orgs/[org]/agentrunmemoryimports` | import updates. |
+
+Historical `refAt` can be included if cheap after current/explicit refs, but should not block the first slice.
+
+## Memory repository scope
+
+Minimum layout:
+
+```text
+.company-brain/
+  README.md
+  babysitter/MEMORY.md
+  ontology/node-kinds.yaml
+  ontology/edge-kinds.yaml
+  runbooks/
+  repositories/
+  babysitter/sessions/
+  babysitter/runs/
+  indexes/ontology-report.json
+```
+
+Minimum validators:
+
+- parse YAML and Markdown frontmatter;
+- require `id`, `kind`, `title`, `owners`, `status` for canonical records;
+- detect duplicate IDs;
+- detect unknown edge kinds;
+- scan for secret-like values;
+- verify imported run memory has org/repo/source digests.
+
+## Dispatch acceptance path
+
+```text
+Given org a5c has repo krate and memory repo org-company-brain
+And repo krate has AgentMemorySource krate-ci-memory
+When a user dispatches agent claude-code-ci-repair from /orgs/a5c/repositories/krate/code
+Then Krate resolves memory repo main to a commit
+And creates AgentMemorySnapshot and AgentContextBundle
+And creates AgentDispatchRun and AgentDispatchAttempt
+And the run detail shows selected memory records/excerpts and digests
+```
+
+## Import acceptance path
+
+```text
+Given an AgentDispatchRun completed in org a5c
+And its session has a summary and .a5c run metadata
+When a user creates a summary-only AgentRunMemoryImport
+Then Krate redacts and normalizes the source material
+And opens or records a reviewable memory update
+And after approval merges into org-company-brain
+And later memory search can find the imported session/run summary
+```
+
+## Cross-org negative path
+
+```text
+Given org a5c and org other both have memory repos
+When an a5c dispatch requests memory from other
+Then Krate rejects with CROSS_ORG_REF_DENIED
+And no memory content is returned in preview, prompt, transcript, audit, or tool output
+```
+
+## Validation gates
+
+- Unit/schema tests for new resources and required `organizationRef` fields.
+- API tests for org mismatch and route ambiguity.
+- Context assembly test for memory snapshot digest creation.
+- Import test for summary-only `.a5c` run memory with redaction.
+- UI smoke for org memory dashboard and run detail memory provenance.
+- Package validation for CRDs/examples/docs.
+
+## Out of scope
+
+- Multi-org sharing.
+- Full raw journal retention.
+- Editing arbitrary memory files in UI.
+- Vector search.
+- Advanced subagent orchestration.
+- Automated issue/PR/label triggers beyond manual dispatch.
+
+## Fixture and payload references
+
+- [Org memory API payload examples](./org-memory-api-payload-examples.md) defines the JSON contracts for this slice.
+- [Org memory E2E fixture plan](./org-memory-e2e-fixture-plan.md) defines the deterministic data needed to prove this slice without external services.

package/docs/agents/org-resource-model-delta-spec.md

@@ -0,0 +1,111 @@
+# Org resource model delta spec
+
+## Purpose
+
+This document captures the concrete resource-model delta between the current Krate core and the proposed org-scoped agent/memory layer. The current model already includes `Organization` and `OrgNamespaceBinding`; the agent memory work should extend that model consistently instead of creating a parallel tenant system.
+
+## Existing core model anchors
+
+Current core resource definitions already include:
+
+- `Organization` as platform identity with a bound tenant namespace;
+- `OrgNamespaceBinding` as the binding from org to namespace;
+- `Repository`, `User`, `Team`, `Invite`, `IdentityMapping`, `AuthProvider`, `SSHKey`, `RepositoryPermission`, `WebhookSubscription`, `RefPolicy`, `BranchProtection`, `RunnerPool`, `View`, and `Selector` with `organizationRef` requirements;
+- aggregated `PullRequest`, `Issue`, `Review`, `Pipeline`, `Job`, and `WebhookDelivery` with `organizationRef` requirements.
+
+Agent resources should follow the same storage split and naming style.
+
+## Config resources to add
+
+| Kind | Context | Required spec | Notes |
+| --- | --- | --- | --- |
+| `AgentStack` | agents | `organizationRef`, `baseAgent`, `adapter`, `runtimeIdentity` | org-scoped reusable agent definition. |
+| `AgentSubagent` | agents | `organizationRef`, `stackRef`, `role` | child-agent definition. |
+| `AgentToolProfile` | agents | `organizationRef`, `allowedTools` | native tool policy. |
+| `AgentMcpServer` | agents | `organizationRef`, `endpoint`, `transport` | MCP server config. |
+| `AgentSkill` | agents | `organizationRef`, `source`, `capabilities` | skill definition and dependencies. |
+| `AgentTriggerRule` | agents | `organizationRef`, `sources`, `agentStack` | webhook/CI/issue/PR/manual trigger policy. |
+| `AgentContextLabel` | agents | `organizationRef`, `promptFragment`, `allowedSources` | reviewed context snippet. |
+| `AgentWorkspacePolicy` | agents | `organizationRef`, `mode`, `retentionPolicy` | worktree/runtime policy. |
+| `AgentServiceAccount` | identity | `organizationRef`, `serviceAccountName` | org namespace ServiceAccount binding. |
+| `AgentRoleBinding` | identity | `organizationRef`, `subject`, `roleRef` | desired RBAC binding. |
+| `AgentSecretGrant` | identity | `organizationRef`, `subject`, `secretRef` | secret key access. |
+| `AgentConfigGrant` | identity | `organizationRef`, `subject`, `configMapRef` | ConfigMap key access. |
+| `AgentMemoryRepository` | agents | `organizationRef`, `repositoryRef`, `defaultBranch` | org company brain repo. |
+| `AgentMemorySource` | agents | `organizationRef`, `repositoryRef`, `include` | memory read/query policy. |
+| `AgentMemoryOntology` | agents | `organizationRef`, `memoryRepository`, `ontologyPath` | ontology validation policy. |
+| `AgentMemoryAssociation` | agents | `organizationRef`, `memoryRef`, `targetRef` | memory-to-resource edge. |
+
+## Aggregated resources to add
+
+| Kind | Context | Required spec | Notes |
+| --- | --- | --- | --- |
+| `AgentDispatchRun` | agents | `organizationRef`, `repository`, `agentStack`, `sourceRefs` | CI-like agent run. |
+| `AgentDispatchAttempt` | agents | `organizationRef`, `agentDispatchRun`, `attemptReason` | retry/fork attempt. |
+| `AgentSession` | agents | `organizationRef`, `agentMuxSessionId`, `dispatchRun` | Agent Mux session projection. |
+| `AgentWorkspace` | agents | `organizationRef`, `repository`, `workspacePath` | worktree/runtime state. |
+| `AgentApproval` | agents | `organizationRef`, `dispatchRun`, `action` | human approval state. |
+| `AgentContextBundle` | agents | `organizationRef`, `dispatchRun`, `digest` | immutable context snapshot. |
+| `AgentArtifact` | agents | `organizationRef`, `dispatchRun`, `kind`, `digest` | run output. |
+| `AgentTriggerExecution` | agents | `organizationRef`, `triggerRule`, `sourceEvent` | trigger evaluation. |
+| `AgentMemorySnapshot` | agents | `organizationRef`, `memoryRepository`, `resolvedCommit` | pinned memory snapshot. |
+| `AgentMemoryQuery` | agents | `organizationRef`, `snapshotRef`, `query` | graph/frontmatter/grep query. |
+| `AgentMemoryUpdate` | agents | `organizationRef`, `memoryRepository`, `changes` | memory PR/update proposal. |
+| `AgentRunMemoryImport` | agents | `organizationRef`, `memoryRepository`, `source` | curated `.a5c`/session import. |
+| `AgentRunJournalEvent` | agents | `organizationRef`, `runRef`, `sequence`, `digest` | imported journal event projection. |
+
+## Schema conventions
+
+All added resources should use:
+
+```yaml
+metadata:
+  namespace: krate-org-a5c
+  labels:
+    krate.a5c.ai/org: a5c
+spec:
+  organizationRef: a5c
+status:
+  phase: Pending
+  conditions: []
+```
+
+`organizationRef` is required even when namespace can imply org, because aggregated API resources may be stored outside etcd and need an explicit partition key.
+
+## Index requirements
+
+Aggregated tables need org-first compound indexes:
+
+- `(organization_ref, repository, created_at)` for repository activity;
+- `(organization_ref, phase, updated_at)` for dashboards;
+- `(organization_ref, agent_stack, created_at)` for agent run lists;
+- `(organization_ref, memory_repository, resolved_commit)` for memory snapshots;
+- `(organization_ref, source_run, created_at)` for memory imports;
+- `(organization_ref, work_item_ref)` for issue/session/workspace links.
+
+## Admission requirements
+
+- `organizationRef` must match namespace binding for namespaced resources.
+- Aggregated resources must store org even when created from a namespaced parent.
+- Cross-org target refs are invalid unless `OrgSharingPolicy` admits them.
+- Secret and ConfigMap refs must name resources in the org namespace unless a future replication policy exists.
+- Memory repository refs must belong to the same org as the dispatch or import.
+
+## Acceptance criteria
+
+- A resource implementer can add agent/memory kinds to `src/resource-model.js` without inventing new storage categories.
+- Every new kind has `organizationRef` and org labels.
+- List/watch APIs can filter by org before repository, stack, run, or memory filters.
+- Package validation can assert the full set of org-scoped CRDs and examples.
+
+## Package validation additions
+
+Package validation should eventually assert:
+
+- every new agent/memory kind has a resource definition;
+- every config kind has a CRD example with `organizationRef`;
+- every aggregated kind has an API schema example with `organizationRef`;
+- org-scoped labels are present in examples;
+- `AgentRunMemoryImport` examples include redaction and retention policy;
+- memory snapshot examples include resolved commit and digest fields;
+- route docs refer to `/orgs/[org]` canonical paths.

package/docs/agents/org-route-resource-model-spec.md

@@ -0,0 +1,183 @@
+# Org route and resource model spec
+
+## Purpose
+
+Krate should behave as an organization-first forge. This document defines how org scope affects routes, API paths, resource refs, namespaces, controllers, deployments, repositories, and agent memory.
+
+## Route model
+
+Preferred UI routes:
+
+| Route | Purpose |
+| --- | --- |
+| `/orgs` | list visible orgs and recent activity. |
+| `/orgs/[org]` | org dashboard: repositories, deployments, agents, memory, runners, audit. |
+| `/orgs/[org]/repositories` | org repository list. |
+| `/orgs/[org]/repositories/[repo]/code` | repository code browser. |
+| `/orgs/[org]/repositories/[repo]/issues` | issues and work item boards. |
+| `/orgs/[org]/repositories/[repo]/pull-requests` | PRs and reviews. |
+| `/orgs/[org]/repositories/[repo]/runs` | CI and agent dispatch rows. |
+| `/orgs/[org]/deployments` | deployment/environment inventory. |
+| `/orgs/[org]/agents` | agent dashboard. |
+| `/orgs/[org]/agents/runs/[run]` | dispatch detail and Agent Mux session. |
+| `/orgs/[org]/agents/memory` | company brain memory. |
+| `/orgs/[org]/settings` | org RBAC, namespace, policies, billing/cost if applicable. |
+
+Non-org repository and deployment routes are not part of the product surface. Users enter repository, deployment, run, and settings flows through `/orgs/[org]/...` so the current org is always explicit.
+
+## API route model
+
+Preferred API routes:
+
+| Route | Purpose |
+| --- | --- |
+| `/api/orgs/[org]/resources` | generic org-scoped resource list/apply. |
+| `/api/orgs/[org]/repositories/[repo]/...` | repository-scoped actions. |
+| `/api/orgs/[org]/deployments/[deployment]/...` | deployment-scoped actions. |
+| `/api/orgs/[org]/agents/runs` | dispatch list/create. |
+| `/api/orgs/[org]/agents/memory/query` | memory query. |
+| `/api/orgs/[org]/agents/memory/import-babysitter-run` | run memory import. |
+| `/api/watch/orgs/[org]/...` | org-scoped watches. |
+
+Non-org API routes must not operate on org resources. Organization work is always explicit through `/orgs/[org]`, `/api/orgs/[org]/...`, or `/api/watch/orgs/[org]/...`.
+
+## Resource reference shape
+
+Every product resource should either include `spec.organizationRef` or be namespaced under an org namespace where org can be inferred.
+
+```yaml
+metadata:
+  namespace: krate-org-a5c
+  labels:
+    krate.a5c.ai/org: a5c
+spec:
+  organizationRef: a5c
+```
+
+Cross-resource refs should include org when ambiguity is possible:
+
+```yaml
+repositoryRef:
+  organization: a5c
+  name: krate
+deploymentRef:
+  organization: a5c
+  name: krate-web
+memoryRepositoryRef:
+  organization: a5c
+  name: org-company-brain
+```
+
+## Deployment scoping
+
+Deployments and environments are org siblings to repositories, not global resources.
+
+```text
+Organization
+  -> Repository
+  -> Deployment
+    -> Environment
+    -> ReleasePolicy
+    -> RuntimeStatus
+    -> DeploymentSecretGrant
+  -> AgentDispatchRun
+    -> may target Repository and Deployment in same org
+```
+
+Agent dispatches that operate on deployments must use an org ServiceAccount and deployment-scoped grants. A repository agent cannot mutate a deployment in another org.
+
+## Namespace enforcement
+
+Controllers must enforce:
+
+- resource namespace matches org namespace;
+- `metadata.labels[krate.a5c.ai/org]` matches `spec.organizationRef`;
+- referenced repository/deployment/memory/secret/config resources belong to the same org;
+- ServiceAccount tokens are mounted only from the org namespace;
+- cross-org refs require `OrgSharingPolicy` and explicit audit.
+
+## UI behavior
+
+- The org switcher is global and persistent.
+- Breadcrumbs always start with org.
+- Search results group by org and hide unauthorized orgs entirely.
+- YAML previews show namespace, org label, and `organizationRef`.
+- Copyable `kubectl` examples include `-n <org-namespace>`.
+- Empty states explain when a user has access to an org but no repositories, deployments, agents, or memory sources.
+
+## Controller behavior
+
+```text
+watch event
+  -> resolve namespace
+  -> resolve organization
+  -> validate labels and organizationRef
+  -> validate same-org references
+  -> compute effective RBAC and grants
+  -> reconcile side effects in org namespace
+  -> write status/audit with org and namespace
+```
+
+Controllers may use shared caches and cluster roles for observation, but all writes and runtime side effects are namespaced to the owning org unless explicitly platform-scoped.
+
+## Acceptance criteria
+
+- All repository, deployment, agent, runner, memory, session, workspace, secret, config, and audit records have org context.
+- Ambiguous non-org routes are not product surface and return not found instead of selecting an org silently.
+- API and watch routes are org-scoped by construction.
+- Controller status and audit events include org and namespace.
+- Cross-org references fail closed by default.
+
+## Org-scoped resource kind matrix
+
+| Domain | Resource examples | Org rule |
+| --- | --- | --- |
+| Core tenancy | `Organization`, `OrgNamespaceBinding`, `OrgSharingPolicy` | platform-owned; binds org to namespace. |
+| Repositories | `Repository`, `PullRequest`, `Issue`, `Review`, `WebhookDelivery` | must match org namespace and labels. |
+| Deployments | `Deployment`, `Environment`, release policies, runtime status | org-scoped sibling to repository. |
+| Agents | `AgentStack`, `AgentTriggerRule`, `AgentDispatchRun`, `AgentSession`, `AgentWorkspace` | org-scoped; may reference same-org repo/deployment/memory. |
+| Memory | `AgentMemoryRepository`, `AgentMemorySource`, `AgentMemorySnapshot`, `AgentRunMemoryImport` | org-scoped; memory repo per org by default. |
+| Identity | `AgentServiceAccount`, `AgentRoleBinding`, `AgentSecretGrant`, `AgentConfigGrant` | namespace-bound to org. |
+| Runners | `RunnerPool`, runner ServiceAccounts, workspace policies | org-scoped unless explicitly shared. |
+| Audit | audit records, approval records, policy evaluations | include org and namespace always. |
+
+## Admission checklist
+
+Before accepting a create/update or starting a controller side effect, Krate must verify:
+
+1. `organizationRef` exists and is visible to the actor.
+2. target namespace equals the org namespace binding.
+3. org labels match `organizationRef`.
+4. referenced repository, deployment, memory repo, runner pool, secret, config, ServiceAccount, stack, trigger, session, and workspace are in the same org.
+5. actor or ServiceAccount has Kubernetes RBAC for the namespace and Krate permission for the product action.
+6. any cross-org reference has an admitted `OrgSharingPolicy`.
+7. audit event can be emitted before external side effects.
+
+## Org sharing policy
+
+Cross-org sharing should be rare and explicit.
+
+```yaml
+kind: OrgSharingPolicy
+metadata:
+  name: a5c-read-shared-memory
+spec:
+  sourceOrg: a5c
+  targetOrg: platform-shared
+  allowedRefs:
+    - kind: AgentMemoryRepository
+      name: shared-engineering-memory
+      permissions: [memory.graph.query, memory.records.read]
+  expiresAt: 2026-06-01T00:00:00Z
+  approvalPolicy:
+    requiredApprovers: [team:security]
+```
+
+Sharing policies cannot grant Secret or ConfigMap values across orgs unless a separate secret replication policy exists.
+
+## Migration requirements
+
+- Add org columns/labels to aggregated tables before enforcing org filters.
+- Backfill existing demo resources into a default org such as `a5c`.
+- Keep org-scoped watch tests passing before enabling multi-org data.
+- Flip admission from audit to enforce after backfill and UI route migration are complete.