@a5c-ai/krate 5.0.1-staging.f672fe79b

package/docs/architecture-spec.md

@@ -0,0 +1,78 @@
+# Architecture Spec
+
+## Overview
+
+Krate splits forge responsibilities into a Kubernetes API control plane, Argo CD GitOps reconciliation, and a Gitea-backed Git data plane. The control plane provides resource semantics, RBAC, admission, watch, and declarative automation. Argo CD owns application sync/prune/self-heal, while Gitea serves Git traffic, repository storage, SSH keys, collaborators/teams, branch protection, webhooks, object storage metadata, and code search hooks.
+
+## Control plane
+
+Krate keeps the HTTP API controller role separate from Kubernetes resource ownership. The Krate API controller owns route-level orchestration, request validation, workflow-shaped responses, degraded-state errors, and UI affordances. It delegates Kubernetes intent to a narrow resource gateway, and that gateway calls the Kubernetes resource client for list/get/apply/delete/watch and SubjectAccessReview checks. The Kubernetes resource client is the only layer that shells out to `kubectl` in the local implementation and does not own UI flow decisions or product workflows. Git smart-HTTP and SSH traffic remain outside those control-plane roles and cross only the Git data-plane boundary.
+
+The control plane exposes two API classes:
+
+- CRDs for low-cardinality declarative configuration: `Repository`, `WebhookSubscription`, `RefPolicy`, `BranchProtection`, `RunnerPool`, `View`, and `Selector`.
+- Aggregated API resources for high-cardinality records: `PullRequest`, `Issue`, `Review`, `Pipeline`, `Job`, and `WebhookDelivery`.
+
+The aggregated API server must preserve `kubectl` ergonomics while storing records in Postgres. This avoids using etcd as the database for comments, reviews, CI logs, and delivery records.
+
+## Data plane
+
+The data plane consists of:
+
+- Gitea backend: Kubernetes-hosted Git server for smart-HTTP/SSH, repository APIs, SSH deploy keys, collaborators/teams, protected branches, and webhooks.
+- Repository storage: Gitea-managed persistent storage on Kubernetes volumes.
+- Object Storage: LFS objects, archives, artifacts, and large immutable blobs.
+- Code Search: Zoekt service/indexer per repository cohort in documented post-MVP roadmap stages.
+
+Routing resolves repository identity to the Gitea backend and records object/search placement separately. A single Gitea backend is enough for MVP, but the API and status model must not prevent future scale-out.
+
+## Scaling model
+
+- `git-upload-pack` reads scale horizontally on request rate.
+- `git-receive-pack` writes target the Gitea backend and keep the receive path warm for backlog handling.
+- Search indexers scale independently from Gitea backends and API servers.
+- Runner pools scale by queue depth with `warmReplicas` and `maxReplicas`.
+
+## Identity and authz flow
+
+1. A human signs in with OIDC.
+2. The UI exchanges or maps that identity into Kubernetes-compatible user/group identity.
+3. Server Components and route handlers call the API server with the user identity.
+4. Kubernetes RBAC and admission decide whether the action is allowed.
+5. CI jobs receive projected ServiceAccount tokens scoped to the pipeline/job context.
+
+## Policy model
+
+- Branch and ref policy: `RefPolicy` CRDs reconcile into Gitea-backed branch protection and receive-pack policy checks.
+- Outbound integrations: `WebhookSubscription` resources delivered through a durable queue and represented as `WebhookDelivery` records.
+- Resource policy: Kubernetes admission webhooks validate and mutate Krate API resources directly.
+
+## UI architecture
+
+The UI uses Next.js App Router. Server Components fetch directly from the Kubernetes/aggregated API. Watch streams are converted to SSE through route handlers. The Git proxy route streams smart-HTTP to the Gitea-backed data plane. Monaco or CodeMirror powers diff and code views.
+
+## Deployment topology
+
+Minimum deployment includes:
+
+- APIService and aggregated API server.
+- CRDs and conversion/defaulting as needed.
+- Postgres.
+- Controllers/operators.
+- Gitea backend.
+- Argo CD Application for GitOps reconciliation.
+- Object storage configuration.
+- Next.js UI.
+- Optional NATS, Kyverno, ARC, and ingress components depending on profile.
+
+## Implemented controller boundary proof
+
+The executable MVP keeps four controller-adjacent roles separate in code and tests:
+
+- `krate-api-controller` is the HTTP/application facade. It owns request validation, workflow-shaped repository DTOs, API errors, degraded-state responses, and UI snapshot composition. It must not shell out to `kubectl`, own watch internals, or schedule reconciliation loops.
+- `kubernetes-resource-gateway` is the narrow application port for Kubernetes resource operations. It owns list/get/apply/delete/watch delegation and Repository manifest application, but not page-flow or forge DTO decisions.
+- `kubernetes-resource-client` owns local `kubectl` execution, SubjectAccessReview checks, Kubernetes API discovery, resource apply/delete, and watch streams.
+- `krate-kubernetes-reconciler` owns Repository status projection, Gitea hosting intent, policy projection, and data-plane sync intent. It must not own HTTP routes or browser flows.
+
+`tests/krate.test.js` locks these boundaries with contract tests, while `scripts/validate-ui.mjs` checks that the UI model exposes the API controller, resource gateway, Kubernetes client, Kubernetes reconciler, and Git data-plane lanes.
+

package/docs/components/control-plane.md

@@ -0,0 +1,78 @@
+# Control Plane Component Requirements
+
+## Purpose
+
+The control plane makes Krate a Kubernetes API extension rather than a forge with Kubernetes integrations. It owns resource semantics, RBAC, admission, watch behavior, reconciliation entry points, and storage boundaries.
+
+## Responsibilities
+
+- Serve low-cardinality configuration as CRDs.
+- Serve high-cardinality social and execution records through an aggregated API server backed by Postgres.
+- Preserve Kubernetes API ergonomics for `kubectl`, controllers, admission, and watch clients.
+- Coordinate with repository, PR, runner, webhook, and policy controllers.
+
+## API and resource surface
+
+CRDs:
+
+- `Repository`
+- `WebhookSubscription`
+- `RefPolicy`
+- `BranchProtection`
+- `View` and `Selector`
+
+Aggregated resources:
+
+- `PullRequest`
+- `Issue`
+- `Review`
+- `Pipeline`
+- `Job`
+- `RunnerPool`
+- `WebhookDelivery`
+
+## Requirements
+
+- The aggregated API server must support Kubernetes discovery and normal verbs for relevant resources.
+- High-cardinality resources must not store primary records in etcd.
+- Resource schemas must expose status fields that controllers and UI can watch.
+- Status updates must be safe for concurrent controller writes.
+- API resources must be label-selectable for workflows such as similar run search and failed webhook queries.
+
+## Dependencies
+
+- kube-apiserver aggregation layer.
+- Postgres for high-cardinality records.
+- etcd for CRD-backed config only.
+- Admission webhook ecosystem.
+- Controllers for repositories, PRs, runners, and webhooks.
+
+## Security and policy
+
+- Authorization must be Kubernetes RBAC, not app-local permission logic.
+- Admission must be able to validate PR, issue, pipeline, and job resources.
+- Audit logs must identify the Kubernetes user/group or ServiceAccount behind each mutation.
+
+## Scaling and performance
+
+- API server must support watch streams for UI and controller clients.
+- Postgres indexes must support list, watch bookmarks, labels, field selectors, and common PR/pipeline queries.
+- API latency targets must be separated from Git data-plane latency targets.
+
+## Failure modes
+
+- Postgres unavailable: aggregated resources are degraded; CRD config remains discoverable.
+- APIService unavailable: UI and kubectl operations for aggregated resources fail clearly.
+- Admission failure: resource creation must fail closed for enforcing policies and expose actionable status.
+
+## Observability
+
+- Request latency, error rate, watch count, storage latency, admission latency, and reconciliation lag.
+- Kubernetes events for controller and API storage errors.
+
+## Acceptance criteria
+
+- `kubectl get repositories` and `kubectl get pullrequests` work.
+- Creating a PR can be blocked by a Kyverno policy.
+- PR/comment/review scale tests do not grow etcd as the primary database.
+- UI can watch PR and pipeline updates through the same API resources.

package/docs/components/data-plane.md

@@ -0,0 +1,69 @@
+# Data Plane Component Requirements
+
+## Purpose
+
+The data plane serves Git repositories through a Kubernetes-hosted Gitea backend while avoiding the impossible one-PVC-per-repository model. It separates Kubernetes resource intent from Gitea repository hosting, persistent storage, object storage metadata, and code search hooks.
+
+## Responsibilities
+
+- Terminate smart-HTTP and SSH Git traffic through Gitea.
+- Map repository identity to the Gitea backend and integration plan.
+- Store repositories in Gitea-managed persistent Kubernetes storage.
+- Store LFS objects, archives, and other large immutable objects in object storage.
+- Expose indexing hooks for Zoekt search.
+
+## API and resource surface
+
+- Repository status must include Gitea backend integration and health.
+- Gitea integration API must support route lookup, repo initialization, access checks, deploy keys, permissions, webhooks, and maintenance operations.
+- Gitea must expose smart-HTTP and SSH entry points and API-backed repository integration.
+
+## Requirements
+
+- MVP must support a Kubernetes-hosted Gitea backend for `git-upload-pack`, `git-receive-pack`, SSH keys, permissions, protected branches, and webhooks.
+- Architecture must allow Gitea backend scale-out without changing repository APIs.
+- Writes must keep warm capacity; push traffic must not scale from zero.
+- Reads may scale horizontally behind HPA.
+- Receive-pack must evaluate compiled ref policy before accepting protected ref updates.
+
+## Dependencies
+
+- RWX storage class such as EFS or CephFS.
+- Object storage for LFS and archives.
+- Repository operator for Gitea initialization and integration planning.
+- Identity/RBAC checks from control plane.
+- Optional Zoekt search service.
+
+## Security and policy
+
+- Git operations must authorize against Kubernetes identity and repository policy.
+- Custom hook execution must be sandboxed through WASM.
+- Gitea backend pods must mount only needed config, credentials, and repository storage.
+
+## Scaling and performance
+
+- Each Gitea backend target is capacity-planned by repository count, storage, and I/O profiles.
+- `git-upload-pack` scales on request rate.
+- `git-receive-pack` scales on backlog with warm minimums.
+- Search indexing must not starve Git read/write traffic.
+
+## Failure modes
+
+- Gitea backend unavailable: affected repositories show degraded status and API routes return actionable errors.
+- RWX volume degraded: writes pause or fail closed to protect repository integrity.
+- Object store unavailable: LFS/archive operations degrade separately from core Git refs where possible.
+- Gitea route cannot resolve repository: request fails with correlation ID and resource status pointer.
+
+## Observability
+
+- Git operation latency and error rate by operation, repository, and Gitea backend.
+- Gitea repository storage usage, inode usage, I/O wait, queue depth, and policy rejection count.
+- Gitea route-cache hit rate and backend health.
+
+## Acceptance criteria
+
+- `git clone`, `git fetch`, and `git push` work against a repository created by `kubectl`.
+- A protected branch update can be blocked by `RefPolicy`.
+- Read traffic can scale without adding repository PVCs.
+- Repository status exposes Gitea backend integration and health.
+

package/docs/components/hooks-events.md

@@ -0,0 +1,67 @@
+# Hooks and Events Component Requirements
+
+## Purpose
+
+Krate separates three commonly conflated hook mechanisms: server-side Git hooks, outbound HTTP webhooks, and Kubernetes admission webhooks. Each must have its own lifecycle, security model, observability, and UI surface.
+
+## Responsibilities
+
+- Model branch/ref behavior with `RefPolicy`.
+- Compile server-side policies into Gitea-backed receive-pack policy config.
+- Execute custom Git hooks in a WASM sandbox.
+- Deliver outbound webhooks durably with retries, signing, and replay.
+- Surface admission policies affecting Krate resources.
+
+## API and resource surface
+
+- `RefPolicy`: require commit signing, block force-pushes, require linear history, and future custom WASM hooks.
+- `WebhookSubscription`: endpoint, events, scope, secret reference, retry policy.
+- `WebhookDelivery`: request, response, status, latency, retry chain, replay metadata.
+- Admission policies: Kyverno/Gatekeeper/native policies applying to Krate resources.
+
+## Requirements
+
+- Server-side Git policy must run inside receive-pack and fail closed for protected refs.
+- Outbound delivery must use durable queueing with exponential backoff.
+- Deliveries must be HMAC-signed.
+- Delivery logs must be queryable with `kubectl` and visible in UI.
+- Admission policies must show in a repo Hooks & Policies view when they affect the repository.
+
+## Dependencies
+
+- Gitea repositories and Git receive-pack.
+- ConfigMap or mounted policy bundle distribution.
+- NATS JetStream or equivalent durable queue.
+- Secret storage for webhook signing.
+- Kyverno, Gatekeeper, or Kubernetes admission APIs.
+
+## Security and policy
+
+- Custom hooks must not shell out or mount broad secrets.
+- Webhook secrets must support rotation.
+- Replay must use current secrets and record a new delivery attempt.
+- Policy authoring must support audit mode before enforce mode.
+
+## Scaling and performance
+
+- Git hook evaluation must add bounded latency to receive-pack.
+- Webhook queueing must absorb bursts without blocking Git operations.
+- Delivery log queries must be indexed by repo, subscription, status, event type, and time.
+
+## Failure modes
+
+- Policy compilation fails: old valid policy remains active and status reports stale/error.
+- Webhook endpoint down: retries continue and delivery status records failure chain.
+- Queue unavailable: new deliveries fail or buffer according to configured durability mode.
+- Admission policy misconfigured: audit preview helps identify impact before enforcement.
+
+## Observability
+
+- Hook evaluation latency, policy rejection count, webhook delivery success/failure, retry count, endpoint latency, policy violation count.
+
+## Acceptance criteria
+
+- `RefPolicy` can block force-push to main.
+- Webhook test delivery appears in `WebhookDelivery` within seconds.
+- Failed deliveries expose request, response, latency, retries, and replay action.
+- Kyverno PR policy appears in the Hooks tab and can block PR creation.

package/docs/components/identity-rbac-policy.md

@@ -0,0 +1,73 @@
+# Identity, RBAC, and Policy Component Requirements
+
+## Purpose
+
+Krate inherits Kubernetes identity, RBAC, admission, and audit so the forge does not create a parallel permission system. Human actions and CI actions must be attributable to Kubernetes users, groups, or ServiceAccounts.
+
+## Responsibilities
+
+- Authenticate humans with GitHub OAuth, optional installation-configured SSO, or a delegated identity proxy.
+- Store `User`, `Team`, `Invite`, `IdentityMapping`, and `AuthProvider` resources as the Krate source of truth.
+- Manage native Kubernetes `ServiceAccount`, `Role`, `ClusterRole`, `RoleBinding`, and `ClusterRoleBinding` projections for users, teams, agents, and runners.
+- Map human users and groups into Kubernetes identities and repository identities.
+- Use TokenRequest or equivalent delegation for UI-to-API calls.
+- Issue scoped ServiceAccount identities for CI jobs, agent dispatch attempts, and runner pools.
+- Enforce trust tiers and policy through admission.
+
+## API and resource surface
+
+- `User`, `Team`, `Invite`, `IdentityMapping`, and `AuthProvider` CRDs.
+- RBAC Roles/ClusterRoles for forge resources.
+- ServiceAccounts for runner pools, jobs, and agent stacks.
+- Agent RBAC management resources such as `AgentServiceAccount`, `AgentRoleBinding`, `AgentSecretGrant`, and `AgentConfigGrant`.
+- Admission policies for `PullRequest`, `Pipeline`, `Job`, and related resources.
+- Policy templates for common PR and runner constraints.
+
+## Requirements
+
+- No core workflow may require PATs.
+- UI permission checks must be server-enforced by Kubernetes API calls.
+- Fork PR pipelines must run as untrusted jobs with no secrets and no cluster API access.
+- Runner trust tier must be admitted and enforced before scheduling.
+- Activity records must be traceable to Kubernetes identity.
+
+## Dependencies
+
+- GitHub OAuth app and optional OIDC/SSO provider configured through Helm values.
+- Kubernetes TokenRequest API.
+- Kubernetes RBAC.
+- Kyverno, Gatekeeper, or native ValidatingAdmissionPolicy where available.
+- Runner controller and scheduler.
+
+## Security and policy
+
+- Secrets may only be mounted into trusted jobs or agent dispatches that satisfy repo/ref/pipeline/trigger constraints and explicit Secret grants.
+- ConfigMaps used by tools, skills, MCP servers, agents, and runners must be admitted through explicit ConfigMap grants when they affect execution.
+- Untrusted jobs must not be able to mutate cluster resources.
+- Policy bypass must require explicit RBAC grants and be auditable.
+- Admission failures must return clear user-facing messages.
+
+## Scaling and performance
+
+- Token exchange and authorization must not become the UI bottleneck.
+- RBAC and admission checks must be cached only where safe and must respect revocation semantics.
+
+## Failure modes
+
+- OIDC provider unavailable: new logins fail; existing sessions follow configured token lifetime.
+- TokenRequest fails: UI actions fail closed.
+- Admission webhook unavailable: enforcement policies fail according to Kubernetes failure policy.
+- RBAC misconfiguration: UI must surface denied actions without hiding the underlying resource.
+
+## Observability
+
+- Auth failures, token exchange latency, RBAC denied counts, admission decisions, and trust-tier violations.
+- Audit events for privileged changes and policy bypass.
+
+## Acceptance criteria
+
+- An admin can invite users, manage teams, map sign-in identities, grant repository access, manage agent/runner ServiceAccounts, and bind native Kubernetes roles from the Krate UI.
+- A user can perform allowed PR actions based on Kubernetes RBAC.
+- A user is denied forbidden actions by the API server, not UI-only logic.
+- An untrusted fork PR cannot access secrets or privileged agent/runner ServiceAccounts.
+- A Kyverno policy can require PR descriptions or reviewer rules.

package/docs/components/kubevela-oam.md

@@ -0,0 +1,70 @@
+# KubeVela and OAM Integration
+
+Krate expands from a Git forge into an application delivery forge by installing KubeVela as an optional-but-first-class control-plane dependency and by assimilating the Open Application Model (OAM) into the Krate ontology.
+
+## Scope
+
+Krate will install and manage KubeVela from the deployed stack when `kubevela.enabled=true`. The default deployment path uses Argo CD to install the upstream `vela-core` Helm chart into `vela-system`, keeping the dependency GitOps-managed beside the Krate chart. KubeVela remains the owner of OAM runtime reconciliation; Krate wraps the experience with forge-native repository, pull request, environment, and pipeline flows.
+
+## OAM Concepts Assimilated
+
+- **Application**: the deployable unit composed from components, traits, workflow, policies, and scopes.
+- **Component**: the reusable workload module selected by a developer or platform team.
+- **Trait**: operational behavior attached to a component, such as ingress, scaler, rollout, or service binding.
+- **Scope**: grouping/boundary metadata for components, such as environment, network, or health grouping.
+- **Workflow step**: ordered delivery operation; Krate maps PR checks, preview deployment, promotion, rollback, and teardown into workflow steps.
+- **Definition**: platform capability catalog entry, exposed by KubeVela as component, trait, policy, and workflow step definitions.
+
+
+## OAM Spec Traceability
+
+Krate tracks the upstream OAM v0.3.0 model entities directly while using KubeVela's newer delivery extensions where available:
+
+| OAM spec entity | KubeVela/Kubernetes surface | Krate UI responsibility |
+| --- | --- | --- |
+| `Application` | `applications.core.oam.dev` in the forge namespace | Create from a repository, show status, workflow, component, trait, and scope projection. |
+| `ComponentDefinition` | `componentdefinitions.core.oam.dev` in `vela-system` | Populate component-type selectors instead of hard-coding only `webservice`. |
+| `WorkloadDefinition` | `workloaddefinitions.core.oam.dev` in `vela-system` when installed | Explain the Kubernetes workload implementation behind a component. |
+| `TraitDefinition` | `traitdefinitions.core.oam.dev` in `vela-system` | Attach operational overlays such as scaler, ingress, rollout, and service binding. |
+| `ScopeDefinition` | `scopedefinitions.core.oam.dev` in `vela-system` when installed | Expose grouping boundaries such as health scopes or environment scopes. |
+| KubeVela policy/workflow extensions | `policydefinitions.core.oam.dev`, `policies.core.oam.dev`, `workflowstepdefinitions.core.oam.dev`, and `workflows.core.oam.dev` | Wrap promotion, approval, rollback, topology, and override flows as forge actions. |
+| KubeVela runtime graph | `applicationrevisions.core.oam.dev` and cluster-scoped `resourcetrackers.core.oam.dev` | Show revision success and applied-resource ownership without Krate owning reconciliation. |
+
+The OAM spec notes that `Application` supersedes the earlier `ApplicationConfiguration` name. Krate uses `Application.core.oam.dev/v1beta1` for all generated manifests and keeps ApplicationConfiguration only as legacy terminology in documentation.
+
+## Deployment Contract
+
+Krate chart values define the KubeVela dependency:
+
+```yaml
+kubevela:
+  enabled: true
+  namespace: vela-system
+  chart:
+    repoURL: https://kubevela.github.io/charts
+    chart: vela-core
+    targetRevision: "1.10.8"
+  addons:
+    fluxcd:
+      enabled: true
+      onlyHelmComponents: true
+```
+
+The chart renders an Argo CD `Application` for KubeVela. The Krate controller discovers KubeVela CRDs through Kubernetes API discovery and exposes definition resources, OAM Applications, ApplicationRevisions, standalone Policy/Workflow resources, and cluster-scoped ResourceTrackers through the same `/api/controller` model used by repositories, issues, PRs, and pipelines.
+
+## Forge Experience
+
+Krate UI wraps KubeVela as an application delivery surface:
+
+1. A repository page can propose an OAM Application from the repo, branch, image, Helm chart, or service template.
+2. Pull requests can attach a preview OAM Application and show the KubeVela workflow status beside checks and reviews.
+3. The Applications page lists OAM Applications, components, traits, policies, and workflow steps without requiring users to learn raw CRDs first.
+4. YAML remains available for escape hatches: every generated OAM resource shows the Kubernetes object and `kubectl apply` equivalent.
+5. Promotion and rollback are modeled as forge actions but delegated to KubeVela Application workflow/status reconciliation.
+
+## Boundaries
+
+- Krate owns forge UX, repository-to-application intent, GitOps handoff, PR annotations, and Kubernetes-native API projection.
+- KubeVela owns OAM Application reconciliation, component/trait/policy/workflow definitions, and runtime status.
+- Argo CD owns installing KubeVela and reconciling Krate chart manifests.
+- Gitea owns Git hosting, SSH keys, repo permissions, issues, and pull requests.

package/docs/components/operations-publishing.md

@@ -0,0 +1,81 @@
+# Operations and Publishing Component Requirements
+
+## Purpose
+
+Operations and publishing turn Krate from an architecture into an installable, upgradeable, observable system. The MVP must ship as a Helm chart with a reproducible demo and production-shaped configuration paths.
+
+## Responsibilities
+
+- Package images, charts, CRDs, APIService, controllers, UI, Gitea backend, and Argo CD workloads.
+- Document install profiles and dependencies.
+- Define upgrade, rollback, backup, restore, and support expectations.
+- Provide release readiness gates and smoke tests.
+
+## Publish surface
+
+- Container images for aggregated API server, controllers, Gitea backend, UI, webhook delivery worker, and optional indexers.
+- Helm chart with CRDs, RBAC, ServiceAccounts, Deployments, Services, APIService, Gitea backend, Argo CD Application, config, and optional templates.
+- Example manifests for repository, PR policy, runner pool, webhook, and demo workflow.
+
+## Requirements
+
+- `helm install krate` must install the MVP in a documented cluster profile.
+- Chart values must allow BYO Argo CD, Gitea, Postgres, object storage, RWX storage class, ingress, OIDC provider, ARC, NATS, Kyverno, and Gatekeeper.
+- Demo mode must be explicit and not confused with production defaults.
+- Production install docs must call out HA, storage, backup, secrets, and network requirements.
+- Upgrade docs must describe CRD, Postgres, controller, Gitea backend, and Argo CD rollouts.
+
+## Dependencies
+
+- Kubernetes cluster with API aggregation support.
+- RWX storage provider.
+- Postgres.
+- Object storage.
+- OIDC provider.
+- Optional NATS JetStream, ARC, Kyverno/Gatekeeper, ingress controller, cert-manager.
+
+## Security and policy
+
+- Helm chart must install least-privilege RBAC.
+- Secrets must be configurable through existing cluster secret management.
+- Default network policies should separate API, UI, data-plane, and storage paths where possible.
+- Release artifacts must be signed or checksummed.
+
+## Scaling and performance
+
+- Chart values must expose replica counts and autoscaling knobs for API server, UI, Gitea backend, runner workers, and delivery workers.
+- Gitea backend sizing guidance must include repository count, storage, and I/O considerations.
+- Runner pool defaults must distinguish trusted warm capacity from untrusted cold starts.
+
+## Failure modes
+
+- Failed install: Helm output and events identify missing dependencies.
+- Failed migration: release blocks or rolls back before incompatible controllers start.
+- Failed Gitea rollout: receive-pack writes are protected from corruption.
+- Failed dependency: status pages and docs point to the exact degraded capability.
+
+## Observability
+
+- Default ServiceMonitor/PodMonitor templates where Prometheus is available.
+- Example dashboards for API, Git data plane, runners, webhooks, and storage.
+- Log correlation IDs across UI, API, Gitea backend, and delivery worker.
+
+## Acceptance criteria
+
+- Clean install creates all required Kubernetes resources.
+- Smoke test creates repository, pushes code, opens PR, runs CI, and applies a policy.
+- Backup and restore docs exist and are testable.
+- Release checklist gates chart, images, CRDs, migration, security, and docs.
+
+## Repository package artifacts
+
+The repository now includes a verified Kubernetes package lifecycle:
+
+- `charts/krate` provides the Helm-style chart surface with CRDs, APIService, RBAC, service accounts, workloads, services, a Gitea backend, an Argo CD Application surface, and network policy defaults.
+- `examples/minikube-demo.yaml` and `examples/policy-kyverno-pr-title.yaml` provide demo install resources.
+- `scripts/setup-minikube.mjs` provides dry-run and apply modes for local minikube setup.
+- `npm run e2e` validates the chart and minikube command plan without requiring a live cluster.
+- `npm run package:check` validates chart structure and npm pack contents.
+
+This is a production-shaped package contract for the executable Kubernetes-native model. Controller image build/publish, chart packaging, npm package validation, generated dist/example artifacts, UI build artifacts, and AKS Helm deployments for develop/staging/main are wired through `.github/workflows/publish.yml` with safe PR/branch/tag gates. Live-cluster conformance now runs through the branch deployment lane for `krate-develop.a5c.ai`, `krate-staging.a5c.ai`, and `krate.a5c.ai`.
+

package/docs/components/runners-ci.md

@@ -0,0 +1,66 @@
+# Runners and CI Component Requirements
+
+## Purpose
+
+Krate treats runners as a first-class forge domain while delegating execution to systems such as ARC, Tekton, or Buildkite Agent. The forge owns identity, caching, trust boundaries, cost attribution, and run UX.
+
+## Responsibilities
+
+- Define `RunnerPool`, `Pipeline`, and `Job` resources.
+- Schedule jobs into trusted or untrusted pools.
+- Integrate with ARC for MVP execution.
+- Provide live run state, logs, rerun controls, queue metrics, and cost visibility.
+- Scope caches by repository and pool.
+
+## API and resource surface
+
+- `RunnerPool`: image, resources, node selector, scaling policy, allowed repos, trust tier, serviceAccountRef, cache backend, warm/max replicas.
+- `Pipeline`: CI invocation, workflow file, repository/ref, runner pool, resume controls, status.
+- `Job`: step execution, runner pod owner, logs/status, identity, cache bindings.
+
+## Requirements
+
+- Trusted pools default to warm replicas for low latency.
+- Untrusted pools may scale from zero for safety and cost.
+- Admission must prevent untrusted code from scheduling on trusted pools.
+- BuildKit cache must be scoped per repo and pool, never shared across trust tiers.
+- Rerun failed and rerun from step must create new Pipeline resources.
+
+## Dependencies
+
+- ARC for MVP.
+- KEDA for queue-depth scaling.
+- Kubernetes Pods and ServiceAccounts.
+- S3-compatible cache backend.
+- Watch/SSE bridge for UI updates.
+
+## Security and policy
+
+- Job pods receive projected ServiceAccount tokens scoped to repo/ref/pipeline, and agent runner pods receive identities admitted by `AgentServiceAccount`/`AgentRoleBinding` policy.
+- Trusted jobs may receive configured secrets through explicit Secret grants; untrusted jobs receive none.
+- Runner images and node selectors must be policy-controlled.
+- Cost and cache data must not leak across tenants.
+
+## Scaling and performance
+
+- Pool dashboard must show warm/total replicas, queue depth, p50/p95 wait time, and last-hour cost.
+- KEDA scales between `warmReplicas` and `maxReplicas` based on queue depth.
+- Log streaming must be near real-time through Kubernetes Pod log watch and SSE.
+
+## Failure modes
+
+- Queue saturation: UI explains bottleneck with queue and node events.
+- Image pull failure: live run view surfaces pod events and failing image.
+- Node pressure: pool dashboard links to scheduling and node pressure signals.
+- Cache backend unavailable: jobs run without cache or fail according to pool policy.
+
+## Observability
+
+- Queue depth, wait latency, job duration, pod scheduling latency, image pull latency, cache hit rate, cost by pool/repo, failure signatures.
+
+## Acceptance criteria
+
+- ARC-backed workflow runs for a repository.
+- Fork PR jobs are admitted only into untrusted pools.
+- Live run view streams logs and step status.
+- Similar-failure search works by `failure.signature` labels.