@a5c-ai/krate 5.0.1-staging.f672fe79b

package/docs/external/security-auth-permissions.md

@@ -0,0 +1,81 @@
+# Security, auth, and permissions
+
+## Purpose
+
+External backend integration introduces provider tokens, webhooks, native permissions, and bidirectional writes. This document defines the security model.
+
+## Auth principles
+
+- Prefer GitHub Apps over PATs.
+- Store app IDs, private keys, webhook secrets, and client secrets in Kubernetes Secrets.
+- Never store provider access tokens in resource status.
+- Installation tokens are short-lived and cached in memory only when possible.
+- User-attributed writes require both Krate authorization and provider user authorization.
+
+## Secret resources
+
+```yaml
+kind: Secret
+metadata:
+  name: github-app-a5c
+  namespace: krate-org-a5c
+type: Opaque
+stringData:
+  app-id: "..."
+  private-key.pem: "..."
+  webhook-secret: "..."
+```
+
+`ExternalBackendProvider.spec.authRef` points to the Secret. UI displays only Secret name/key metadata.
+
+## Permission checks
+
+Every write requires:
+
+1. Krate org/RBAC permission;
+2. provider binding allows interface and write mode;
+3. provider credentials have required native permission;
+4. actor attribution policy is satisfied;
+5. approval policy is satisfied for agents or high-risk writes;
+6. audit event is emitted.
+
+## Webhook security
+
+- Require HTTPS in production.
+- Validate provider signature before parsing payload.
+- Enforce replay/dedupe by delivery ID and timestamp where available.
+- Queue processing after quick 2XX response.
+- Store raw payloads only according to retention and redaction policy.
+- Avoid logging headers or payload fields containing secrets.
+
+## No-leak requirements
+
+Provider secrets and tokens must not appear in:
+
+- API responses;
+- resource status;
+- Kubernetes events;
+- sync events;
+- logs;
+- UI;
+- browser traces;
+- memory/context bundles;
+- test artifacts.
+
+## Agent interactions
+
+Agents may propose external writes, but Krate owns approval and execution. Agent write-back to GitHub issues, PRs, checks, comments, labels, or branch updates must produce an `ExternalWriteIntent` and pass approval policy unless explicitly trusted.
+
+## Audit fields
+
+Audit external operations with:
+
+- org and namespace;
+- provider and binding;
+- interface;
+- actor and optional provider user;
+- native object ID/URL;
+- action;
+- write intent ID;
+- result;
+- digest of request/response with secrets removed.

package/docs/external/sync-state-machines.md

@@ -0,0 +1,108 @@
+# External sync state machines
+
+## Purpose
+
+This document defines stable phases and transitions for provider setup, bindings, webhook deliveries, backfill, write intents, conflicts, and provider health. UI, controllers, tests, and audit should use these phases consistently.
+
+## Provider phases
+
+| Phase | Meaning |
+| --- | --- |
+| `Pending` | resource created, not yet validated. |
+| `Authenticating` | controller is checking credentials. |
+| `Discovering` | capabilities, installation, and rate-limit metadata are being discovered. |
+| `Ready` | provider can serve at least one enabled interface. |
+| `Degraded` | provider is usable but has warnings such as rate limits or partial interface failure. |
+| `Paused` | user paused sync/write operations. |
+| `Failed` | provider cannot be used until configuration changes. |
+
+## Binding phases
+
+| Phase | Meaning |
+| --- | --- |
+| `Pending` | binding accepted. |
+| `ValidatingTarget` | target Krate repo/project/org is being validated. |
+| `RegisteringWebhook` | provider webhook registration is in progress. |
+| `Backfilling` | initial sync is running. |
+| `Ready` | binding sync is active. |
+| `Conflict` | sync conflicts exist but binding may continue. |
+| `Paused` | sync paused for this binding. |
+| `Failed` | binding cannot sync. |
+
+## Webhook delivery phases
+
+| Phase | Meaning |
+| --- | --- |
+| `Received` | request accepted. |
+| `SignatureRejected` | signature validation failed; no payload processing. |
+| `Queued` | valid delivery queued. |
+| `Normalizing` | provider payload is becoming canonical events. |
+| `Processing` | sync controller is applying events. |
+| `Succeeded` | event applied or safely deduped. |
+| `Retrying` | transient failure. |
+| `DeadLettered` | repeated failure needs operator action. |
+
+## Backfill phases
+
+| Phase | Meaning |
+| --- | --- |
+| `Scheduled` | backfill requested. |
+| `Listing` | provider objects are being paginated. |
+| `Hydrating` | details are being fetched. |
+| `Applying` | Krate projections are being updated. |
+| `Checkpointing` | cursor/high-watermark is being persisted. |
+| `Succeeded` | backfill completed. |
+| `RateLimited` | paused until reset. |
+| `Failed` | backfill failed. |
+
+## Write intent phases
+
+| Phase | Meaning |
+| --- | --- |
+| `PendingApproval` | approval required before provider call. |
+| `ReadyToSend` | admitted and queued for provider write. |
+| `Sending` | provider call in progress. |
+| `AwaitingConfirmation` | provider response accepted; waiting for webhook/read confirmation. |
+| `Succeeded` | provider state confirmed. |
+| `Conflict` | provider state changed or rejected due to version mismatch. |
+| `Retrying` | transient failure. |
+| `Rejected` | human or policy rejected the write. |
+| `Failed` | non-retryable failure. |
+
+## Conflict phases
+
+| Phase | Meaning |
+| --- | --- |
+| `Open` | conflict requires resolution. |
+| `Resolving` | selected resolution is being applied. |
+| `Resolved` | conflict closed and sync confirmed. |
+| `Ignored` | unsupported or intentionally ignored field. |
+| `Superseded` | newer sync state replaced this conflict. |
+
+## State transition invariants
+
+- `SignatureRejected` deliveries never become `Processing`.
+- `DeadLettered` deliveries require explicit replay or skip.
+- `PendingApproval` write intents never call provider before approval.
+- `Succeeded` write intents include provider native response or confirmation digest.
+- `Conflict` states must link to `ExternalSyncConflict`.
+- `Paused` provider/binding states block new backfills and writes but preserve webhook delivery records.
+
+## UI state mapping
+
+| State | UI tone | Action |
+| --- | --- | --- |
+| `Ready` | good | normal actions. |
+| `Degraded` | warning | show reason and retry/backfill actions. |
+| `RateLimited` | warning | show reset time. |
+| `Conflict` | danger/warning | link to conflict resolution. |
+| `Paused` | neutral | resume action. |
+| `Failed` | danger | show configuration fix. |
+| `DeadLettered` | danger | replay or skip action. |
+
+## Acceptance criteria
+
+- Every external backend resource has a stable phase and conditions.
+- Tests assert phase transitions, not only final data shape.
+- UI uses consistent status language across providers.
+- Audit events include phase transitions for deliveries, writes, and conflicts.

package/docs/external/unified-external-backend-model.md

@@ -0,0 +1,107 @@
+# Unified external backend model
+
+## Purpose
+
+Krate needs one provider model that can represent GitHub and future externally managed systems without assuming every backend is a full Git forge. A backend can support any combination of three provider interfaces:
+
+- issue tracking;
+- CI/CD;
+- git forge.
+
+## Provider capability model
+
+```yaml
+kind: ExternalBackendProvider
+spec:
+  organizationRef: a5c
+  providerType: github
+  displayName: GitHub a5c-ai
+  baseUrl: https://github.com
+  apiBaseUrl: https://api.github.com
+  capabilities:
+    issueTracking: true
+    cicd: true
+    gitForge: true
+  authRef:
+    kind: Secret
+    name: github-app-a5c
+  syncPolicyRef: github-default-sync
+```
+
+Provider capability does not mean every repository enables every capability. `ExternalBackendBinding` controls which Krate repositories or org scopes use which interface.
+
+## Three unified interfaces
+
+| Interface | Krate domain | GitHub example | Other provider examples |
+| --- | --- | --- | --- |
+| Issue tracking | `Issue`, comments, labels, milestones, project/work-item fields | GitHub Issues/Projects | Jira, Linear, Azure Boards. |
+| CI/CD | `Pipeline`, `Job`, checks, triggers, runners, artifacts/logs | GitHub Actions/Checks | Buildkite, CircleCI, Jenkins, Azure Pipelines. |
+| Git forge | `Repository`, `PullRequest`, refs, commits, keys, collaborators, branch protection | GitHub repositories and PRs | GitLab, Bitbucket, Gitea, raw Git + custom PR layer. |
+
+## Ownership modes
+
+| Mode | Meaning |
+| --- | --- |
+| `external-owned` | external backend is source of truth; Krate mirrors and can request changes through provider API. |
+| `krate-owned` | Krate owns desired state and reconciles it to the provider. |
+| `bidirectional` | both systems may change state; conflicts are detected and resolved by policy or user review. |
+| `read-only` | Krate only imports state and never writes. |
+| `write-through` | user changes in Krate are immediately applied to provider after admission. |
+| `reviewed-write` | user/agent changes create a proposed change requiring approval. |
+
+Ownership is configured per interface and sometimes per resource type. For example, GitHub can be external-owned for PR discussions, Krate-owned for deploy keys, and bidirectional for labels.
+
+## External identity fields
+
+Every synced resource should store:
+
+```yaml
+external:
+  providerRef: github-a5c
+  interface: gitForge
+  nativeId: "123456"
+  nativeNumber: 42
+  nodeId: PR_kwDO...
+  url: https://github.com/a5c-ai/krate/pull/42
+  apiUrl: https://api.github.com/repos/a5c-ai/krate/pulls/42
+  etag: W/"..."
+  cursor: opaque-cursor
+  lastSeenAt: 2026-05-11T12:00:00Z
+  lastSyncedAt: 2026-05-11T12:00:05Z
+  resourceVersion: provider-specific-version
+```
+
+`nodeId` is optional but preferred for GitHub because REST and GraphQL can both reference global node IDs.
+
+## Binding model
+
+```yaml
+kind: ExternalBackendBinding
+spec:
+  organizationRef: a5c
+  providerRef: github-a5c
+  targetRef:
+    kind: Repository
+    name: krate
+  interfaces:
+    issueTracking:
+      enabled: true
+      mode: bidirectional
+    cicd:
+      enabled: true
+      mode: external-owned
+    gitForge:
+      enabled: true
+      mode: bidirectional
+  externalRef:
+    owner: a5c-ai
+    repository: krate
+```
+
+## Acceptance criteria
+
+- A provider can support one, two, or all three interfaces.
+- Krate resources preserve external native IDs and cursors.
+- Sync mode is explicit by interface.
+- Cross-org provider bindings are rejected unless an org sharing policy admits them.
+- UI can explain whether an action is local, mirrored, write-through, or reviewed-write.

package/docs/external/user-facing-changes.md

@@ -0,0 +1,67 @@
+# User-facing changes
+
+## Purpose
+
+External backend support should feel native in Krate while making ownership and sync status obvious. Users should know when data is mirrored from GitHub, when Krate can write back, and when a conflict requires attention.
+
+## Global UI changes
+
+- Add `External Integrations` under org settings.
+- Add provider badges to synced repositories, issues, PRs, runs, and settings.
+- Add native provider links on detail pages.
+- Add sync health cards on org dashboard.
+- Add conflict and rate-limit attention items to Inbox/Insights.
+
+## Provider setup wizard
+
+Steps:
+
+1. choose provider type, starting with GitHub;
+2. choose interfaces: issue tracking, CI/CD, git forge;
+3. configure auth: GitHub App app ID, private key Secret, webhook Secret, installation ID;
+4. choose repositories or org-wide scope;
+5. choose sync modes per interface;
+6. run permission/capability check;
+7. create `ExternalBackendProvider`, binding, and sync policy resources.
+
+## Repository settings
+
+External backend section shows:
+
+- provider and native URL;
+- enabled interfaces and ownership modes;
+- last webhook delivery and last backfill;
+- conflicts and rate-limit warnings;
+- managed vs mirrored settings;
+- sync now, pause sync, replay webhook, disconnect actions.
+
+## Issue/PR/run pages
+
+- Native GitHub links are visible but secondary.
+- Sync state indicates current, stale, conflict, or degraded.
+- Mutating controls show whether the action is local, write-through, or reviewed-write.
+- Agent-generated external writes require explicit approval unless policy allows them.
+
+## Runs and CI
+
+- GitHub Actions workflow runs appear beside Krate-native pipelines.
+- External jobs show provider, native URL, status, logs/artifacts availability, rerun/cancel capability.
+- External runners are labeled provider-managed, Krate-managed, or mirrored.
+
+## Conflict UI
+
+Conflicts show:
+
+- field name;
+- Krate value;
+- external value;
+- last synced time;
+- ownership mode;
+- resolution actions: keep external, apply Krate, manual edit, ignore unsupported.
+
+## Acceptance criteria
+
+- Users can configure GitHub without editing YAML, but YAML remains available.
+- Users can tell which system owns each field/action.
+- External sync failures are visible and actionable.
+- Provider write actions are audited and permission-checked.

package/docs/gaps.md

@@ -0,0 +1,161 @@
+# Product gaps
+
+## Org-scoped company brain and run memory gap
+
+Krate needs an explicit org scoping layer across the product. Repositories, deployments, agent stacks, triggers, runners, workspaces, sessions, company brain memory, secrets, config, and audit should all resolve under an `Organization`, with one Kubernetes namespace per org by default.
+
+Required gap closures:
+
+- add `Organization` and namespace binding semantics to product/API/resource docs;
+- make repository and deployment routes org-aware, with no non-org repository or deployment routes;
+- require org labels and namespace refs on product resources;
+- reject cross-org refs by default in controllers and admission;
+- scope ServiceAccounts, Roles, RoleBindings, Secrets, ConfigMaps, runners, agents, and users to the org namespace;
+- manage one dedicated company brain memory repo per org;
+- store admitted `MEMORY.md`, Babysitter sessions, `.a5c` run journals, task results, artifact manifests, and retrospectives in that org memory repo;
+- expose org memory and run imports in `/orgs/[org]/agents/memory`;
+- support historical memory dispatch by resolving the org memory repo to a commit from a timestamp;
+- include org, namespace, memory commit, session ID, run ID, and journal digest in audit records.
+
+The org-scoped resource model and route model are now implementation requirements: `Organization` resources live in the platform namespace, while each org binds exactly one namespace that contains repositories, deployments, runners, identity mappings, issues, reviews, runs, automations, memory, secrets, config, and audit records.
+
+## Detailed gap matrix
+
+| Gap | Why it matters | Docs now covering it |
+| --- | --- | --- |
+| Org namespace model | prevents repos, deployments, agents, memory, secrets, and sessions from mixing across tenants | `docs/agents/org-scoping-namespace-spec.md`, `docs/agents/org-route-resource-model-spec.md` |
+| Org-aware routes | makes navigation GitHub-like and avoids ambiguous repository slugs | `docs/agents/org-route-resource-model-spec.md`, `docs/agents/ui-flow-spec.md` |
+| Babysitter run memory import | turns useful `.a5c` run state into governed org memory without raw dumps | `docs/agents/agent-run-memory-import-spec.md` |
+| `MEMORY.md` in company brain | provides a stable org orchestration entrypoint | `docs/agents/shared-memory-company-brain-spec.md` |
+| Historical memory refs | enables reproducible runs with memory from a prior timestamp | `docs/agents/memory-context-integration-spec.md` |
+| Org-scoped audit | makes cross-controller activity attributable and recoverable | `docs/agents/observability-audit-spec.md` |
+
+## Remaining implementation follow-ups
+
+- Define retention tiers for raw `.a5c` journal content versus summarized memory records.
+- Decide whether generated memory indexes are committed to the org memory repo or stored as object artifacts with digest refs.
+- Add org-scoped agent memory routes and audit records after the route/resource foundation is in place.
+
+## Next implementation decomposition
+
+The next docs-to-code decomposition should be:
+
+1. org resource model and namespace binding;
+2. org-first routes with no non-org repository or deployment route surface;
+3. org admission preflight and same-org reference checks;
+4. memory repository/source read-only UI;
+5. memory context snapshots and historical refs;
+6. `AgentRunMemoryImport` summary-only import;
+7. curated journal imports and retention tiers;
+8. memory update review, PR merge, and rollback.
+
+This order avoids adding memory write paths before org isolation and admission are enforceable.
+
+## Current implementation alignment gaps
+
+Current code already includes some org foundations:
+
+- `src/resource-model.js` includes `Organization`, `OrgNamespaceBinding`, and `organizationRef` on core resources.
+- `apps/web/app/orgs/[org]` contains org dashboard, repositories, deployments, runs, inbox, people, hooks, insights, and settings-like pages.
+- `apps/web/app/api/orgs/[org]/resources` provides an org-scoped resource API seam.
+
+Remaining gaps are therefore additive:
+
+- add agent/memory resources to the existing resource model;
+- add `/orgs/[org]/agents/*` route tree;
+- add memory query/import/update APIs under existing org API structure;
+- add route guards and same-org admission for new resources;
+- add UI links from existing repository pages to agent dispatch and memory association flows;
+- add `AgentRunMemoryImport` validation and review UI.
+
+## Docs-to-implementation readiness checklist
+
+Before code work starts, the docs now require these checks to be true:
+
+- resource model delta lists every new agent/memory kind and storage class;
+- UI implementation map points every new surface at an existing or future org route;
+- API contract defines org-scoped routes and stable errors;
+- controller spec defines org preflight and memory import reconciliation;
+- acceptance matrix includes cross-org denial and memory import scenarios;
+- gaps file records current implementation seams and remaining additive work.
+
+The main unresolved product choice is retention: how much `.a5c` journal detail should be imported by default beyond summary-only and curated-journal modes.
+
+## Vertical slice acceptance target
+
+The first code milestone should follow `docs/agents/org-memory-vertical-slice-spec.md` exactly. Success means a single-org manual dispatch can consume company brain memory, show the memory snapshot in run detail, import a summary-only Babysitter/Agent Mux run into the same org memory repo, and prove cross-org memory denial.
+
+Anything beyond that is a later slice unless it directly enables the vertical path.
+
+## Fixture-driven implementation proof
+
+The future implementation should be considered incomplete until the fixture plan in `docs/agents/org-memory-e2e-fixture-plan.md` can run locally. The fixture intentionally includes duplicate repo slugs across orgs and secret-like `.a5c` journal content so route ambiguity, org isolation, and redaction are proven rather than assumed.
+
+## QA automation gaps
+
+The QA strategy in `docs/tests` is intentionally broader than current implementation. Remaining gaps:
+
+- Add browser automation framework and route smoke tests.
+- Add coverage reporting and thresholds.
+- Split current Node tests into unit, integration, API, and E2E directories as suites grow.
+- Add deterministic fixtures under `tests/fixtures` for org, repository, memory, `.a5c`, Agent Mux, webhooks, runners, and deployments.
+- Add security/no-secret scans over API responses, browser traces, memory imports, and artifacts.
+- Add org-scoped agent/company-brain vertical-slice tests.
+- Add live/staging gates for Gitea, Argo CD, KubeVela, NATS, ARC, object storage, and Agent Mux.
+- Add release artifacts for coverage, browser traces, rendered manifests, and SBOM/signing when release gates mature.
+
+## QA adoption roadmap gaps
+
+The docs now define a staged QA adoption roadmap. Implementation remains to:
+
+- create `tests/fixtures` and helper fakes;
+- add Playwright/browser route smoke;
+- add coverage reporting and thresholds;
+- add stable API error tests;
+- add security/package hardening scans;
+- automate the org-memory vertical slice;
+- add live/staging reliability profiles;
+- publish quality intelligence such as flaky tests and coverage trends.
+
+## External backend integration gaps
+
+The `docs/external` specs define GitHub and future provider integration, but implementation remains to:
+
+- add `ExternalBackendProvider`, `ExternalBackendBinding`, sync policy, delivery, event, sync state, write intent, conflict, and object-link resources;
+- implement provider registry and GitHub App auth without PATs;
+- add three provider interfaces: issue tracking, CI/CD, and git forge;
+- add webhook ingest, signature validation, delivery replay, event normalization, and backfill;
+- add bidirectional sync conflict handling and reviewed write intents;
+- add UI provider setup, repository sync status, external badges, conflict resolution, and sync health;
+- add tests and fixtures for GitHub webhooks, Actions, issues, PRs, repos, keys, branch protection, rate limits, and cross-org denial.
+
+## Expanded external backend gaps
+
+Additional provider work now documented but not implemented:
+
+- provider type registry and adapter descriptor loading;
+- GitLab, Bitbucket Cloud/Data Center, Azure DevOps, Jira, Linear, Buildkite, CircleCI, Jenkins, Gitea external, Gerrit, raw Git, and custom provider profiles;
+- org-scoped external backend settings UI and setup wizard;
+- provider binding UI for mixed-interface backends;
+- conflict and write-intent review UI;
+- detailed `ExternalWebhookDelivery`, `ExternalSyncEvent`, `ExternalWriteIntent`, and `ExternalObjectLink` schemas;
+- provider plugin contract and interface-specific sync controllers;
+- rate-limit aware sync scheduling and status surfaces.
+
+
+
+----
+
+[ ] - add tools mux to enforce external tool use granular permissions beyond amux support for sanboxing and policy enforcement.
+
+## External provider implementation-ready gaps
+
+The external backend docs now define manifests, mappings, state machines, and UX flows. Remaining implementation gaps:
+
+- create a provider capability manifest registry and loader;
+- add `ExternalProviderCapabilityManifest` validation or bundled manifest files;
+- implement external object envelope persistence on synced resources;
+- implement rich text conversion and loss warnings for Jira/Linear/provider-specific formats;
+- implement stable phase enums for providers, bindings, deliveries, backfills, writes, and conflicts;
+- implement mixed-provider flows such as GitHub forge plus Buildkite CI;
+- add UX acceptance tests for setup, conflict resolution, reviewed writes, webhook recovery, and rate limits.

package/docs/install.md

@@ -0,0 +1,94 @@
+# Installation and Local Development
+
+Krate is a Kubernetes-native forge package with a local validation harness. You can run the deterministic harness, inspect the Next.js console, and dry-run the minikube install path while the install/runtime contract is expressed as Kubernetes resources, an Argo CD Application surface, and a Gitea-backed Git data plane.
+
+## Prerequisites
+
+- Node.js 20 or newer
+- npm
+- Optional for cluster dry-runs and live install experiments: Docker, minikube, kubectl, and Helm
+
+## Fast path
+
+```bash
+npm install
+npm run check
+npm run dev
+```
+
+`npm run dev` starts the Next.js console from `apps/web` and renders data from the executable Krate lifecycle snapshot.
+
+## Validation commands
+
+```bash
+npm run build          # writes dist/krate-summary.json and dist/krate-lifecycle.json
+npm test               # unit coverage for resource, component, and handoff behavior
+npm run e2e            # chart and minikube dry-run lifecycle coverage
+npm run package:check  # npm package and chart/package metadata checks
+npm run smoke          # Kubernetes contract smoke assertions
+npm run ui:validate    # UI file and data-contract validation
+npm run ui:build       # production Next.js build with deterministic standalone tracing
+npm run check          # all deterministic gates
+```
+
+## Next.js UI
+
+```bash
+npm run ui:dev
+npm run ui:build
+```
+
+The UI covers overview, repositories/data plane, runners/CI, identity and policy, hooks/events, operations/install, and lifecycle validation. It imports the Krate Kubernetes/Gitea/Argo CD contract model from `src/index.js`; no cluster is required for local UI development.
+
+The Next.js proxy protects all UI pages and authenticated API routes with the `krate_session` cookie. `/login` and `/api/auth/*` remain public entrypoints for starting and ending sessions.
+
+## Minikube package path
+
+Preview the commands without mutating your machine:
+
+```bash
+npm run setup:minikube -- --dry-run --json
+```
+
+When you have minikube, kubectl, Helm, and Docker available and want to apply the package locally:
+
+```bash
+npm run setup:minikube -- --apply
+```
+
+This applies the Helm-style chart from `charts/krate` and demo resources from `examples/minikube-demo.yaml`.
+
+## Troubleshooting
+
+- If `npm run ui:build` fails after dependency changes, rerun `npm install` and retry.
+- `kubectl port-forward` does not inject delegated identity headers; it only tunnels TCP. For local browser login without an identity proxy, explicitly set `auth.delegatedIdentity.enabled=true` and `auth.delegatedIdentity.localDevelopment.enabled=true`, then use `/api/auth/delegated` on `localhost`. Leave local development login disabled outside local clusters.
+- If minikube tools are missing, use `npm run setup:minikube -- --dry-run --json` to see the required tools and commands.
+- If `npm run check` fails, run the individual command listed above to isolate whether the issue is docs, unit tests, e2e package validation, smoke, or UI build.
+
+## Current release surface
+
+Krate now includes the verified Kubernetes-native runtime contract, Helm-style chart surface, Argo CD Application surface, Gitea backend integration, minikube handoff, production-shaped controller image build, and GitHub publishing workflow. The Dockerfile builds the runnable `bin/krate-server.mjs` controller API with a `/healthz` check plus the Next.js web app, and `.github/workflows/publish.yml` validates the full local gate before publishing or uploading package, dist, chart, example, UI, and image artifacts. Pull requests build images without pushing; branch/tag contexts can publish GHCR images, tagged releases can push the Helm chart to GHCR OCI, and commits to `develop`, `staging`, and `main` deploy the Helm chart to AKS at `krate-develop.a5c.ai`, `krate-staging.a5c.ai`, and `krate.a5c.ai`.
+
+The local harness is intentionally deterministic: it validates resource contracts, Gitea API-shaped integration, Argo CD Application generation, lifecycle behavior, package surface, and UI without requiring external services. Live-cluster conformance remains the follow-up environment gate beyond this executable Kubernetes package.
+
+## Local runtime API
+
+Run `npm run serve` to start the local stateful Krate API on port 3080. The API exposes `GET /healthz`, `GET /api/orgs/[org]/snapshot`, `GET /api/orgs/[org]/runtime-resources/:kind`, `POST /api/orgs/[org]/repositories`, `POST /api/orgs/[org]/pullrequests`, `POST /api/orgs/[org]/pullrequests/:name/checks/complete`, `POST /api/orgs/[org]/pullrequests/:name/reviews`, and `POST /api/orgs/[org]/pullrequests/:name/merge`.
+
+These endpoints execute the same control-plane, runner, webhook, policy, and Kubernetes/Gitea integration code used by the tests; they are a deterministic harness for the cluster package contract, not a replacement architecture. GET /api/orgs/[org]/snapshot returns a KrateRuntimeSnapshot export with the etcd/postgres storage boundary, audit log, and events. POST /api/orgs/[org]/snapshot imports that export into the running local API so backup/restore behavior is executable in tests instead of only documented.
+
+## KubeVela / OAM delivery plane
+
+Set kubevela.enabled=true to let the Krate chart create an Argo CD Application that installs KubeVela ela-core into ela-system. Krate then discovers core.oam.dev resources and exposes OAM Applications, component definitions, trait definitions, policy definitions, and workflow step definitions through the forge UI and controller JSON.
+
+
+## Optional Kyverno integration
+
+Krate can run without Kyverno, connect to a platform-owned Kyverno install, or manage Kyverno through Argo CD for local/greenfield clusters. Use `externalDependencies.kyverno.mode`:
+
+- `auto` (default): Krate discovers an existing Kyverno install when CRDs are readable, otherwise keeps native Krate policy resources available.
+- `disabled`: no policy-engine dependency; Hooks & Policies shows native Krate policy resources only.
+- `byo`: Krate requires/discovers Kyverno CRDs/controllers and reads policy reports/exceptions using the chart RBAC.
+- `managed`: Krate renders an Argo CD `Application` for the upstream Kyverno Helm chart and still exposes all raw YAML/`kubectl` actions.
+
+The first implementation slice is intentionally admission-safe and non-fatal: if Kyverno is absent, the controller model reports an auto-discovery degraded policy engine instead of breaking repository, run, or deployment flows. Enforce-mode product promises require the Krate aggregated API server path to remain behind kube-apiserver admission.