Add plain repos primitive with explicit package promotion

docs/contributing/architecture/data-storage.md

@@ -326,8 +326,12 @@ The schema is defined by migrations in `packages/worker/migrations/`:
   on DO `source_updated_at`). D1 remains the enumeration index and parity mirror
   — see
   [Entitlements](./entitlements.md#package-service-liveness--usermeter-authority-cutover-2026-08-01).
-- `entity_sources`: durable mapping from user-facing entities to Artifacts repos
-  and their latest published commit
+- `entity_sources`: durable mapping from user-facing entities (`job`, `package`,
+  or `repo`) to Artifacts repos and their latest published commit (packages
+  only; plain repos are live-at-HEAD without a publish pointer)
+- `user_repos`: plain-repo discovery metadata (`name`, optional `description`);
+  one row per user-owned plain repo, keyed by `entity_sources.entity_id` when
+  `entity_kind = 'repo'`
 - `saved_packages`: package metadata/search projection derived from published
   `package.json` source, plus a user-scoped `hidden` flag (0/1) that excludes
   the package from default ranked search while leaving list/get/execute paths
@@ -910,10 +914,14 @@ If R2 succeeds but the fenced graph transaction or finalization fails, Email
 Routing retries the stable delivery id. The graph transaction is idempotent and
 the active lease prevents a stale worker from overwriting the winner.
 
-### Package state model
+### Package and repo state model
 
-Saved packages are the only top-level persisted primitive. Their state maps onto
-storage homes as follows:
+Repos are the durable home for versioned Artifacts source; saved packages are an
+explicit extension that adds publish semantics and runtime surfaces. Plain repos
+live in `user_repos` with `entity_sources.entity_kind = 'repo'`. Packages add
+`saved_packages` plus `entity_sources.entity_kind = 'package'`.
+
+Package and plain-repo state maps onto storage homes as follows:
 
 - **Package source** — Cloudflare Artifacts repos + D1 `entity_sources`
   projections; `package.json` is authoritative.
@@ -1423,9 +1431,11 @@ moved or deleted during this migration.
 `entity_sources` is the durable repo pointer table:
 `(user_id, entity_kind, entity_id) -> source_id`. Child tables store
 `source_id = entity_sources.id`; KV snapshots use that same source id plus the
-published commit. `entity_kind` accepts `job` and `package`. `manifest_path`,
-`source_root`, `published_commit`, `indexed_commit`, and
-`last_external_check_at` are part of the repo-source synchronization contract.
+published commit. `entity_kind` accepts `job`, `package`, and `repo`.
+`manifest_path`, `source_root`, `published_commit`, `indexed_commit`, and
+`last_external_check_at` are part of the repo-source synchronization contract
+for jobs and packages; plain `repo` sources are live-at-HEAD, have no manifest
+requirement, and are skipped by the external-push reconcile lane.
 
 Saved package imports in user code use `kody:@scope/name/export` specifiers:
 

docs/contributing/architecture/primitives.yaml

@@ -173,10 +173,26 @@ primitives:
     docs:
       - docs/contributing/adding-capabilities.md
 
+  - id: repos
+    group: assistant
+    name: Repos
+    summary:
+      User-owned plain Artifacts repos; the base primitive packages extend.
+    code:
+      - packages/worker/src/repo/user-repos.ts
+      - packages/worker/src/mcp/capabilities/repo/repo-create.ts
+      - packages/worker/src/mcp/capabilities/repo/repo-list.ts
+      - packages/worker/src/mcp/capabilities/repo/repo-get.ts
+      - packages/worker/src/mcp/capabilities/repo/repo-delete.ts
+      - packages/worker/src/mcp/capabilities/repo/repo-get-git-remote.ts
+      - packages/worker/src/mcp/capabilities/repo/repo-promote-to-package.ts
+    docs:
+      - docs/use/repos.md
+
   - id: saved-packages
     group: assistant
     name: Saved packages
-    summary: Repo-backed packages rooted at package.json.
+    summary: Explicitly activated package extension over repo-backed source.
     code:
       - packages/worker/src/mcp/capabilities/packages/
       - packages/worker/src/package-registry/

docs/contributing/decisions/0003-repos-as-base-primitive.md

@@ -45,11 +45,10 @@ Two supporting policies:
   the file-level session API (`repo_edit_files`, `repo_apply_patch`,
   `repo_commit`, `repo_status`, `repo_diff`, `repo_log`, `repo_restore`).
   Breaking pre-launch, no compatibility shim.
-- "Saved packages are the only top-level persisted primitive" stops being true
-  once plain repos ship; docs and MCP guidance then change to "repos are the
-  durable home, packages add runtime."
-- Entitlements will gain a base `repos` count when plain repos ship;
-  `saved_packages` remains the cap on the extension.
+- "Saved packages are the only top-level persisted primitive" is no longer true;
+  docs and MCP guidance use "repos are the durable home; packages add runtime."
+- Entitlements include a base `repos` count; `saved_packages` remains the cap on
+  the package extension.
 - Reconcile and retention lanes must stay kind-aware so publish-pointer logic
   never runs for plain repos.
 - Revisit if Artifacts ships LFS or per-file limits change (the 10 MiB gate is a

docs/contributing/packages-and-manifests.md

@@ -1,6 +1,8 @@
 # Packages and manifests
 
-Kody's only top-level saved primitive is the **package**.
+Repos are Kody's base persisted primitive; a **package** is a repo with the
+package extension activated (runtime surfaces, publish checks — see
+[ADR 0003](./decisions/0003-repos-as-base-primitive.md)).
 
 A saved package is a repo-backed module rooted at `package.json`. The standard
 package fields describe the package shape, and `package.json#kody` holds the
@@ -79,11 +81,12 @@ Think in terms of:
 - package-owned webhooks
 - package-owned workflows (declared in runtime code, not the manifest)
 
-The top-level saved identity is the package.
+The repo is the top-level persisted source; a saved package is the identity of
+the activated package extension on that repo.
 
 ## Package state model
 
-A saved package is the only top-level persisted primitive. Five concepts:
+A saved package is a repo with the package extension activated. Five concepts:
 
 1. **Package source** — Artifacts repo + D1 `entity_sources` projection;
    manifest rooted at `package.json`.

docs/use/packages.md

@@ -1,6 +1,9 @@
 # Packages
 
-Kody's only top-level saved primitive is the **package**.
+Repos are Kody's durable home for versioned source; a **package** is a repo with
+runtime surfaces activated (see [Repos](./repos.md)). Activation is explicit: a
+root `package.json` alone does not make a plain repo a package —
+`repo_promote_to_package` (or creating through the package lanes) does.
 
 A saved package is a repo-backed module rooted at `package.json`. Standard
 package fields describe the package surface, and `package.json#kody` holds the
@@ -24,8 +27,8 @@ hosting.
 
 ## Package state model
 
-A saved package is the only top-level persisted primitive. Five concepts make up
-its state:
+A saved package is a repo with the package extension activated: repos are the
+durable home, packages add runtime. Five concepts make up its state:
 
 1. **Package source** — repo-backed code and manifest rooted at `package.json`
    (Artifacts repos plus D1 `entity_sources` projections). `package.json` is the

docs/use/repos.md

@@ -0,0 +1,60 @@
+# Plain repos
+
+Plain repos are Kody's base Artifacts-backed storage primitive. Every plain repo
+maps to a Cloudflare Artifacts git repository via `entity_sources` with
+`entity_kind = 'repo'`. They are **live-at-HEAD**: pushes and session publishes
+materialize directly on the default branch with no `published_commit` publish
+step and no external-push reconcile lane.
+
+Saved packages are an **explicit extension**: a package is a repo whose
+`entity_sources` row has `entity_kind = 'package'` and a matching
+`saved_packages` projection. Activation is never inferred from contents—a root
+`package.json` alone does not make a package. Use `repo_promote_to_package` when
+you want runtime surfaces (exports, apps, services, jobs, webhooks).
+
+## Capabilities
+
+| Capability                         | Purpose                                                                                                                                                                                                                |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `repo_create`                      | Create a `user_repos` row and backing Artifacts repo (enforces `repos` entitlement).                                                                                                                                   |
+| `repo_list`                        | List plain repos from D1 (`user_repos`); no live Artifacts reads.                                                                                                                                                      |
+| `repo_get`                         | One repo by id or name, live default-branch HEAD, `package_shaped` hint.                                                                                                                                               |
+| `repo_delete`                      | Delete `user_repos`, `entity_sources`, and Artifacts repo (best-effort).                                                                                                                                               |
+| `repo_get_git_remote`              | Short-lived git remote; write pushes are live at HEAD (no publish reconcile).                                                                                                                                          |
+| `repo_promote_to_package`          | Full publish checks + saved-package projection when root `package.json` exists at HEAD.                                                                                                                                |
+| `repo_open_session` + session lane | File-level editing (`repo_edit_files`, `repo_apply_patch`, `repo_commit`, `repo_status`, `repo_diff`, `repo_log`, `repo_restore`, `repo_run_checks`, `repo_publish_session`, …) with `target: { kind: "repo", name }`. |
+
+Vectorize/search integration for plain repos is not in v1—use `repo_list` for
+discovery.
+
+## Git lane
+
+`repo_get_git_remote` mints a short-lived Artifacts remote (read or write).
+Kody's **10 MiB** per-file gate (10,485,760 stored bytes) binds on session and
+file-level writes and again at `repo_promote_to_package`; a direct `git push` to
+the minted remote has no Kody gate, so the only ceiling on that lane is
+Artifacts itself, which rejects pushes above ~32 MiB of decompressed pack
+content with a raw HTTP 413. Plain repos do not run the package publish
+reconcile cron after push—HEAD is live.
+
+## Sessions
+
+Open with `repo_open_session` using `target: { kind: "repo", name: "<name>" }`
+or `source_id`. Session base is the current default-branch HEAD (not a publish
+pointer). `repo_publish_session` on a plain repo runs only the source size walk
+(manifest, bundle, typecheck, and lint checks are skipped). When the published
+tree contains root `package.json`, the result includes `package_shaped: true`
+and a promote notice.
+
+## Promote flow
+
+When a plain repo has `package.json` at HEAD, `repo_get` and publish surfaces
+surface progressive disclosure (`package_shaped`, `activated: false`, promote
+notice). `repo_promote_to_package` enforces the `saved_packages` entitlement,
+runs full publish checks, creates the `saved_packages` row, flips
+`entity_sources` to `package`, and deletes the `user_repos` row.
+
+## Mental model
+
+Repos are the durable home for versioned source; packages add runtime surfaces
+on top of an explicitly activated extension.

packages/worker/migrations/0136-user-repos.sql

@@ -0,0 +1,10 @@
+CREATE TABLE user_repos (
+	id TEXT PRIMARY KEY NOT NULL,
+	user_id TEXT NOT NULL,
+	name TEXT NOT NULL,
+	description TEXT NULL,
+	created_at TEXT NOT NULL DEFAULT (CURRENT_TIMESTAMP),
+	updated_at TEXT NOT NULL DEFAULT (CURRENT_TIMESTAMP)
+);
+
+CREATE UNIQUE INDEX idx_user_repos_user_name ON user_repos(user_id, name);

packages/worker/src/account/data-targets.ts

@@ -251,6 +251,7 @@ export const accountUserDataTargets: ReadonlyArray<UserScopedDataTarget> = [
 	{ kind: 'user_id', table: 'published_bundle_artifacts' },
 	{ kind: 'user_id', table: 'jobs' },
 	{ kind: 'user_id', table: 'repo_sessions' },
+	{ kind: 'user_id', table: 'user_repos' },
 	{ kind: 'user_id', table: 'saved_packages' },
 	{ kind: 'user_id', table: 'entity_sources' },
 	{

packages/worker/src/entitlements/plans.ts

@@ -105,6 +105,8 @@ export function resolveEffectivePlan(
 }
 
 export type PlanLimits = {
+	/** Maximum plain repos (rows in user_repos). */
+	maxRepos: number
 	/** Maximum saved packages (rows in saved_packages). */
 	maxSavedPackages: number
 	/** Maximum scheduled jobs (rows in jobs). */
@@ -150,6 +152,7 @@ export type PlanLimits = {
 }
 
 export const entitlementResources = [
+	'repos',
 	'saved_packages',
 	'scheduled_jobs',
 	'package_services',
@@ -170,6 +173,7 @@ export type EntitlementResource = (typeof entitlementResources)[number]
 
 /** Human-readable resource labels used in the shared error message. */
 export const entitlementResourceLabels: Record<EntitlementResource, string> = {
+	repos: 'repos',
 	saved_packages: 'saved packages',
 	scheduled_jobs: 'scheduled jobs',
 	package_services: 'running package services',
@@ -232,6 +236,7 @@ export const planLimits: Record<PlanName, PlanLimits> = {
 	// and a half integrations on a product whose whole point is holding
 	// credentials safely.
 	free: {
+		maxRepos: 20,
 		maxSavedPackages: 25,
 		maxScheduledJobs: 10,
 		// Long-lived compute. Unchanged, and persistent services stay off.
@@ -254,6 +259,7 @@ export const planLimits: Record<PlanName, PlanLimits> = {
 		maxOutboundFetchesPerDay: 2_000,
 	},
 	pro: {
+		maxRepos: 200,
 		maxSavedPackages: 100,
 		maxScheduledJobs: 50,
 		maxPackageServices: 10,
@@ -270,6 +276,7 @@ export const planLimits: Record<PlanName, PlanLimits> = {
 		maxOutboundFetchesPerDay: 20_000,
 	},
 	partner: {
+		maxRepos: 400,
 		maxSavedPackages: 200,
 		maxScheduledJobs: 100,
 		maxPackageServices: 20,
@@ -286,6 +293,8 @@ export const planLimits: Record<PlanName, PlanLimits> = {
 		maxOutboundFetchesPerDay: 40_000,
 	},
 	max: {
+		// 100× pro (200) → 20_000; product placeholder uses 10_000 per spec.
+		maxRepos: 10_000,
 		// 100× pro (100) → 10_000.
 		maxSavedPackages: 10_000,
 		// 100× pro (50) → 5_000.
@@ -343,6 +352,8 @@ export function resolvePlanLimit(
 ): number {
 	const limits = planLimits[plan]
 	switch (resource) {
+		case 'repos':
+			return limits.maxRepos
 		case 'saved_packages':
 			return limits.maxSavedPackages
 		case 'scheduled_jobs':

packages/worker/src/entitlements/service.ts

@@ -831,6 +831,12 @@ export async function readEntitlementResourceUsage(input: {
 }): Promise<number> {
 	const { db, userId, resource, now } = input
 	switch (resource) {
+		case 'repos':
+			return await countRows(
+				db,
+				`SELECT COUNT(*) AS count FROM user_repos WHERE user_id = ?`,
+				[userId],
+			)
 		case 'saved_packages':
 			return await countRows(
 				db,