IntelIP · hudsonaikins · Jul 12, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,15 @@ All notable changes to Tabellio are recorded here.
 
 ### Added
 
+- Headless `tabellio-platform/v0.2` contract with configurable remote provider and Git-only public surface.
+- Legacy v0.1 platform reader for rollback and staged migration.
+- Provider-neutral remote repository contract and Forgejo repository provisioning/archive operations.
+- Stable Tabellio change-request identities independent from backend IDs.
+- Scoped agent API for repositories, credentials, change requests, validation, approval-bound merge intents, and jobs.
+- Bounded JSON HTTP adapter with tenant isolation, exact-SHA validation, and mutation idempotency.
+- Lease-based worker contract with heartbeat, bounded retries, terminal failure, and expired-lease recovery.
+- PostgreSQL control-plane schema for repositories, jobs, idempotency, webhooks, and credential audit metadata.
+- Private Forgejo production topology with PostgreSQL and Git-only Nginx gateway.
 - Provider-neutral exact-commit validation runner with committed argv manifests and no shell execution.
 - Bounded SHA-256 output evidence, detached worktree cleanup, and durable results on `refs/tabellio/validations`.
 - Local validation results integrated into durable review readiness.
@@ -46,6 +55,9 @@ All notable changes to Tabellio are recorded here.
 
 ### Changed
 
+- Forgejo is now private replaceable backend rather than product review surface.
+- Repository identity defaults to configured canonical remote instead of `origin`.
+- Removed GitHub package metadata and Code Storage transition placeholder.
 - Replaced Graphite as the planned stacked-review integration with host-agnostic git-spice.
 
 ## 0.1.0 - 2026-07-08

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -97,4 +97,4 @@ Before tagging a release:
 - run local checks
 - run an exact-head `tabellio-validate` pass
 - confirm the durable review cycle is ready
-- tag from a clean canonical Forgejo `main` commit
+- tag from clean canonical remote `main` commit
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 ![Tabellio product overview](docs/assets/tabellio-hero.svg)
 
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
-[![Forgejo](https://img.shields.io/badge/Forgejo-canonical%20forge-FB923C?logo=forgejo&logoColor=white)](https://forgejo.org/)
+[![Forgejo](https://img.shields.io/badge/Forgejo-private%20backend-FB923C?logo=forgejo&logoColor=white)](https://forgejo.org/)
 [![JSON Schema](https://img.shields.io/badge/JSON%20Schema-evidence%20contract-0B6BFF)](https://json-schema.org/)
 [![SARIF](https://img.shields.io/badge/SARIF-code%20scanning-2563EB)](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html)
 [![git-spice](https://img.shields.io/badge/git--spice-stacked%20review-B45309)](https://abhinav.github.io/git-spice/)
@@ -12,7 +12,7 @@
 
 Provider-neutral Git context and evidence for agentic development.
 
-Tabellio gives coding agents a deterministic Git foundation: standard Git repositories, isolated worktrees, immutable commit IDs, merge previews, compare-and-swap ref updates, and context packets tied to the exact diff. Forgejo is the canonical review adapter. Any Git remote may store code; no GitHub API or hosted workflow runtime is required.
+Tabellio gives coding agents a deterministic Git foundation: standard Git repositories, isolated worktrees, immutable commit IDs, merge previews, compare-and-swap ref updates, and context packets tied to the exact diff. Tabellio owns the headless workflow; Forgejo is the current private remote-repository adapter. Any compatible Git provider may replace it.
 
 ## What It Adds
 
@@ -60,31 +60,35 @@ AI-assisted pull requests should not depend on reviewer trust alone. Tabellio gi
 | Runtime | [Node.js 20+](https://nodejs.org/) | Runs the local writer and validators |
 | Validation | `tabellio-validate` on any trusted worker | Runs an exact committed command manifest and stores results on a Git ref |
 | Evidence contract | [JSON Schema](https://json-schema.org/) | Validates the evidence envelope and external-action policy |
-| Review surface | [Forgejo](https://forgejo.org/) | Hosts repositories, change requests, comments, reviews, and commit status |
+| Review surface | Tabellio | Owns canonical change-request identity, review state, validation, and approvals |
+| Remote backend | [Forgejo](https://forgejo.org/) | Privately implements Git transport, repository lifecycle, and synchronized review metadata |
 | Stacked review | [git-spice](https://abhinav.github.io/git-spice/) | Host-agnostic stack engine for small dependent change requests |
 | Checkpoint ledger | [Entire](https://entire.io/) and [Entire CLI](https://github.com/entireio/cli) | Required default for agent session and checkpoint context |
 | Git substrate | Standard Git CLI, bare repositories, and worktrees | Stores repositories, branches, commits, patches, and agent-created code state |
 | Agent review | [OpenAI Codex](https://openai.com/codex/) | Produces provider-neutral findings imported into the durable review ledger |
 | Prior art | [SLSA](https://slsa.dev/) and [in-toto](https://in-toto.io/) | Inspiration for provenance and supply-chain evidence, without a compliance claim |
 
-The current public origin may remain a code-storage mirror during migration. It is not a runtime dependency. Entire is the required checkpoint ledger; git-spice manages stacks; Forgejo hosts review; Tabellio owns validation and durable control refs.
+The public origin may remain a code-storage mirror during migration. It is not a runtime dependency. Entire is the required checkpoint ledger; git-spice manages stacks; private Forgejo implements the current remote backend; Tabellio owns review, validation, approvals, and durable control refs.
 
 ## Core Files
 
 | Path | Purpose |
 | --- | --- |
-| `tabellio.platform.json` | Canonical forge, stack, ledger, validation, review, and control-ref contract |
+| `tabellio.platform.json` | Headless remote, stack, ledger, validation, review, and control-ref contract |
 | `schemas/` | Evidence and external-action JSON schemas |
 | `scripts/providers/native-git-store.mjs` | Standard Git storage provider |
 | `scripts/providers/git-spice-stack-manager.mjs` | Read-only git-spice stack adapter |
 | `scripts/providers/git-spice-operations.mjs` | Approval-gated git-spice submit, update, sync, restack, and merge adapter |
 | `scripts/providers/entire-ledger-provider.mjs` | Metadata-only Entire checkpoint adapter |
-| `scripts/providers/forgejo-provider.mjs` | Read-only Forgejo repository and review adapter |
+| `scripts/providers/forgejo-provider.mjs` | Forgejo repository lifecycle and review backend adapter |
+| `scripts/lib/headless-api.mjs` | Scoped, idempotent agent API and queue contract |
+| `scripts/lib/headless-http.mjs` | Bounded JSON-over-HTTP adapter for external agents |
+| `scripts/lib/job-worker.mjs` | Lease-based worker execution and bounded retry contract |
 | `scripts/lib/git-json-ledger.mjs` | Versioned, compare-and-swap JSON state on standard Git refs |
 | `scripts/lib/review-cycle.mjs` | Durable forge and agent review/fix state machine |
 | `scripts/lib/validation-runner.mjs` | Exact-commit, shell-free validation with bounded evidence logs |
 | `scripts/lib/control-ref-transport.mjs` | Approval-gated, fast-forward-only sharing of review, validation, and Entire refs |
-| `infra/forgejo/` | Disposable localhost Forgejo integration lab |
+| `infra/forgejo/` | Disposable lab plus private Git-only production topology |
 | `scripts/lib/` | Git process, repository contract, worktree, and context primitives |
 | `scripts/` | Dependency-free capture, writer, and validators |
 | `examples/` | Minimal valid context, evidence, review, validation, stack, and ledger fixtures |
@@ -102,7 +106,7 @@ npm run tabellio:platform:check
 node scripts/tabellio-validate.mjs run --repo . --commit HEAD --manifest tabellio.validation.json
 ```
 
-Configure `TABELLIO_FORGE_URL`, `TABELLIO_FORGE_API_URL`, and `TABELLIO_FORGE_TOKEN_FILE` for Forgejo operations. Tokens stay in owner-readable files and never enter remote URLs or command arguments.
+Configure `TABELLIO_REMOTE_URL`, `TABELLIO_REMOTE_API_URL`, `TABELLIO_REMOTE_CREDENTIAL_FILE`, and `TABELLIO_REMOTE_NAME` for remote operations. Legacy Forgejo variables remain readable during migration. Credentials stay in owner-readable files and never enter remote URLs or command arguments.
 
 Validate the bundled fixture:
 

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -54,13 +54,14 @@ The lab is disposable and localhost-only. Generated secrets and Forgejo data rem
 
 ## Configure The Platform
 
-`tabellio.platform.json` makes the operating model explicit: Forgejo review, git-spice stacks, Entire checkpoints, local validation, and durable control refs.
+`tabellio.platform.json` makes the operating model explicit: headless remote repository, Tabellio review state, git-spice stacks, Entire checkpoints, local validation, and durable control refs.
 
 ```bash
 npm run tabellio:platform:check
-export TABELLIO_FORGE_URL=https://forge.example.test
-export TABELLIO_FORGE_API_URL=https://forge.example.test/api/v1
-export TABELLIO_FORGE_TOKEN_FILE=$HOME/.config/tabellio/forgejo-token
+export TABELLIO_REMOTE_URL=https://git.example.test
+export TABELLIO_REMOTE_API_URL=https://forgejo.internal.example.test/api/v1
+export TABELLIO_REMOTE_CREDENTIAL_FILE=$HOME/.config/tabellio/forgejo-token
+export TABELLIO_REMOTE_NAME=forgejo
 ```
 
 Run `tabellio-validate` from any trusted worker. The runner checks out the exact revision in an isolated worktree, executes only argv arrays committed in `tabellio.validation.json`, bounds captured output, and writes the result to `refs/tabellio/validations`.
@@ -84,7 +85,7 @@ node scripts/tabellio-control-ref.mjs plan \
   --operation publish \
   --remote forgejo \
   --repo-id example/repository \
-  --token-file "$TABELLIO_FORGE_TOKEN_FILE" \
+  --token-file "$TABELLIO_REMOTE_CREDENTIAL_FILE" \
   --out /tmp/control-ref-intent.json
 ```
 

diff --git a/docs/headless-control-plane.md b/docs/headless-control-plane.md
@@ -0,0 +1,77 @@
+# Headless Control Plane
+
+Tabellio owns agent workflow. Remote provider owns Git transport and repository implementation. Forgejo stays private and replaceable.
+
+## Public Surfaces
+
+| Surface | Purpose | Exposure |
+| --- | --- | --- |
+| Tabellio API | Repository jobs, scoped credentials, change requests, validation, merge intents, job status | Agent-facing |
+| Git gateway | Standard clone, fetch, and push | Agent-facing; smart HTTP routes only |
+| Forgejo API | Repository and review backend adapter | Private network only |
+| Forgejo UI | Operator break-glass debugging | Private network only; not product |
+
+## API Contract
+
+| Method | Path | Scope | Result |
+| --- | --- | --- | --- |
+| `GET` | `/v1/health` | none | Service health |
+| `POST` | `/v1/repositories` | `repository:write` | `202` provisioning job |
+| `GET` | `/v1/repositories/{id}` | `repository:read` | Canonical repository record |
+| `POST` | `/v1/repositories/{id}/credentials` | `credential:issue` | Short-lived Git credential; `no-store` |
+| `POST` | `/v1/change-requests` | `change-request:write` | `202` creation job |
+| `POST` | `/v1/validations` | `validation:run` | `202` exact-commit validation job |
+| `POST` | `/v1/merge-intents` | `merge:intent` | `202` exact-head intent job |
+| `POST` | `/v1/merge-intents/{id}/approvals` | `merge:approve` | `202` short-lived approval job |
+| `POST` | `/v1/merge-intents/{id}/executions` | `merge:execute` | `202` approval-bound merge job |
+| `GET` | `/v1/jobs/{id}` | `job:read` | Tenant-bound job state |
+
+Mutation requests require `Idempotency-Key`. API layer validates shape, scope, tenant, repository identity, and exact Git object IDs before queueing work. Routes stay thin. Workers perform provider calls and untrusted validation.
+
+## Runtime Boundaries
+
+```text
+agent
+  |-- JSON + scoped token --> Tabellio API --> PostgreSQL + durable queue
+  |                                      \--> isolated workers --> private Forgejo API
+  \-- Git smart HTTP ------> Git-only gateway ------------------> private Forgejo
+```
+
+Code, review ledgers, validation results, and Entire checkpoints remain Git-native. PostgreSQL stores operational records: repository bindings, jobs, leases, idempotency keys, webhook deliveries, and credential audit metadata. Credential secrets never enter PostgreSQL.
+
+## Deployment
+
+`infra/forgejo/compose.production.yml` proves production topology locally:
+
+- pinned Forgejo
+- PostgreSQL metadata database
+- durable named volumes
+- registration and Actions disabled
+- Forgejo port private
+- Nginx exposing only Git smart HTTP and health
+
+Production cloud mapping:
+
+- Forgejo container on private compute
+- managed PostgreSQL
+- encrypted durable filesystem for live repositories
+- object storage for backups, artifacts, and optional LFS
+- load balancer in front of Git gateway
+- separate Tabellio API and worker services
+- durable queue with dead-letter handling
+
+Do not mount object storage as live Git repository storage. Git needs filesystem semantics and atomic ref updates.
+
+## Failure Rules
+
+- Database unavailable: reject mutations before accepting work.
+- Queue unavailable: return `503`; never claim queued work.
+- Forgejo unavailable: retry bounded provider jobs; preserve queued intent.
+- Worker crash: lease expires; another worker reclaims job.
+- Duplicate request: return original job when digest matches; `409` when input differs.
+- Stale merge head: fail closed; require new review and approval.
+- Duplicate webhook: deduplicate by provider delivery ID.
+
+## Rollback
+
+Platform v0.1 configuration remains readable. Standard Git refs remain portable. Backend switch changes adapter configuration, not code or control-ledger formats. Never delete canonical refs during provider migration.
diff --git a/docs/operations-hardening.md b/docs/operations-hardening.md
@@ -19,7 +19,7 @@ Tabellio keeps code and control state in standard Git objects, but production sa
 
 ## Canonical And Mirror Repositories
 
-Forgejo is the canonical merge authority. A secondary Git host may store a mirror, but must receive the exact canonical main commit by fast-forward only:
+Configured remote repository is canonical merge authority. Current backend is Forgejo. A secondary Git host may store a mirror, but must receive the exact canonical main commit by fast-forward only:
 
 1. Validate the exact Forgejo change-request head.
 2. Merge through the approved git-spice operation.

diff --git a/docs/review-loop.md b/docs/review-loop.md
@@ -1,6 +1,6 @@
 # Durable Review And Fix Loop
 
-Tabellio keeps review state in standard Git, not in a GitHub-only database. Forgejo remains the visible collaboration surface. The durable control-plane record lives on `refs/tabellio/reviews` as immutable JSON ledger commits updated with compare-and-swap.
+Tabellio keeps review state in standard Git. Tabellio is the agent-facing review surface; Forgejo remains a private backend adapter. Durable control-plane records live on `refs/tabellio/reviews` as immutable JSON ledger commits updated with compare-and-swap.
 
 ## State Flow
 

diff --git a/docs/tooling-stack.md b/docs/tooling-stack.md
@@ -1,6 +1,6 @@
 # Agentic Tooling Stack
 
-Tabellio now owns the minimum Git substrate agents need. It uses standard Git rather than requiring a proprietary code-storage API. A forge can still store repositories and host review.
+Tabellio owns agent workflow and standard Git contracts. Private remote provider stores repositories and implements Git transport. Forgejo is current backend, not product surface.
 
 The main idea: agentic Git should be built around more than a patch. It should preserve the work request, the reason for the change, the runtime that produced it, the commands that ran, the checkpoints that explain it, and the side effects that require approval.
 
@@ -14,7 +14,7 @@ The main idea: agentic Git should be built around more than a patch. It should p
 | Checkpoint ledger | [Entire Checkpoints](https://entire.io/) and [Entire CLI](https://github.com/entireio/cli) | Links commits to agent sessions, prompts, transcript context, token usage, and attribution | Required default through `EntireLedgerProvider`; metadata normalized as `tabellio-ledger/v0.1` |
 | Evidence gate | Tabellio | Writes and validates the change evidence envelope and external-action policy | Core product surface |
 | Stacked review | [git-spice](https://abhinav.github.io/git-spice/) | Keeps dependent change requests small, ordered, reviewable, and resubmittable across Forgejo, Gitea, GitLab, Bitbucket, or GitHub | Read through `GitSpiceStackManager` into `tabellio-stack/v0.1` |
-| Canonical forge | Forgejo | Hosts code, change requests, comments, reviews, and commit status | Forgejo API adapter; no hosted workflow dependency |
+| Remote repository | Forgejo today; replaceable provider contract | Hosts Git objects and implements private repository/review APIs | Agent-facing surface remains Tabellio and standard Git |
 | Validation workers | Local agents or operator-managed workers | Run committed argv manifests against exact commits | Durable results under `refs/tabellio/validations` |
 | Control-ref transport | Standard Git protocol | Shares review, validation, and Entire state | Approval-gated and fast-forward-only |
 
@@ -38,7 +38,7 @@ task source
   -> immutable context packet
   -> read-only merge preview
   -> exact-commit validation result
-  -> Forgejo review and checks
+  -> Tabellio review with remote-provider synchronization
   -> approved control-ref publication
   -> explicit compare-and-swap merge or release gate
 ```
@@ -72,16 +72,19 @@ Included:
 - local writer and validators
 - provider-neutral change-request template and docs
 - disposable Forgejo 15.0.3 lab bound to localhost
-- read-only Forgejo provider for repositories, pull requests, reviews, comments, and commit statuses
+- Forgejo provider for repository lifecycle, Git remotes, pull requests, reviews, comments, and commit statuses
 - approval-gated git-spice submit, update, sync, restack, and merge operations with one-use receipts
 - Git-native review ledger with Forgejo feedback, provider-neutral agent findings, triage, fixes, and readiness state
 - provider-neutral exact-commit validation runner with durable results on `refs/tabellio/validations`
-- canonical Forgejo platform contract
+- provider-neutral headless platform contract with legacy v0.1 reader
+- scoped and idempotent headless API contract
+- lease-based worker retry and recovery contract
+- private Forgejo, PostgreSQL, and Git-only gateway production topology
 - approval-gated fast-forward transport for review, validation, and Entire refs
 
 Not included yet:
 
-- production Forgejo deployment
+- live production deployment
 - transcript indexing or storage outside Entire
 - forge comment publication, general review-thread mutation, and signed approvals
 - Codex review automation

diff --git a/infra/forgejo/README.md b/infra/forgejo/README.md
@@ -2,6 +2,18 @@
 
 This disposable Forgejo instance proves Tabellio can store and review code without GitHub.
 
+Production-shaped topology lives in `compose.production.yml`. It uses PostgreSQL, durable named volumes, private Forgejo networking, disabled registration and Actions, and an Nginx gateway exposing only Git smart HTTP.
+
+```bash
+export FORGEJO_DATABASE_PASSWORD='replace-through-secret-manager'
+export TABELLIO_GIT_DOMAIN=git.example.test
+export TABELLIO_GIT_ROOT_URL=https://git.example.test/
+docker compose -f infra/forgejo/compose.production.yml config
+docker compose -f infra/forgejo/compose.production.yml up -d
+```
+
+Example proves topology. Production operator must add TLS termination, encrypted volumes, managed database, backup/restore automation, secret-manager injection, monitoring, and tested upgrades. Do not expose Forgejo port or UI publicly.
+
 - HTTP binds only to `127.0.0.1:3300`.
 - SSH binds only to `127.0.0.1:2222`.
 - SQLite data stays under ignored `.tabellio/forgejo/`.