Define the selected-surface acceptance gate

README.md

@@ -141,24 +141,19 @@ export KERNEL_ACC=1
 export KERNEL_API_KEY="..."
 ```
 
-Browser-pool acceptance tests additionally require:
+Browser-pool and data-source acceptance tests additionally require:
 
 ```sh
 export KERNEL_PROJECT_ID="..."
 ```
 
-Run the durable resource acceptance tests:
-
-```sh
-go test -count=1 -timeout=30m -v ./internal/resources/browserpool -run TestAcc
-go test -count=1 -timeout=30m -v ./internal/resources/project -run TestAcc
-```
-
 The tests create uniquely named durable resources and register independent
-cleanup. Browser-pool deletion remains `force=false`. The tests do not acquire
-browsers or perform runtime recovery.
+cleanup. Browser-pool deletion remains `force=false`. The tests do not acquire,
+release, or recover browsers.
+
+Use the commands in the [selected-surface acceptance matrix](docs/acceptance.md).
+It is the source of truth for current live coverage and the pre-tag release run.
 
 ## Architecture
 
 See [docs/architecture.md](docs/architecture.md) for package layout, Terraform semantics, testing strategy, and release planning.
-

docs/acceptance.md

@@ -0,0 +1,89 @@
+# Selected-Surface Acceptance Matrix
+
+This document is the live-API release gate for the provider's selected public
+surface. Unit tests remain the fast default. Acceptance tests run only through
+explicit local opt-in or the manual GitHub Actions workflow.
+
+The selected surface contains two managed resources and four read-only data
+sources. It does not claim coverage for future or unregistered Kernel objects.
+
+## Gate Rules
+
+- Set both `TF_ACC=1` and `KERNEL_ACC=1`.
+- Use unique `kernel-tf-*` names for every created fixture.
+- Register cleanup as soon as a canonical ID exists.
+- Verify deletion through a follow-up API read.
+- Keep browser-pool deletion non-forceful.
+- Never acquire, release, flush, invoke, or recover runtime state.
+- Keep live tests out of pull-request CI.
+- Run the complete matrix against the release commit before tagging.
+
+## Environment
+
+```sh
+export TF_ACC=1
+export KERNEL_ACC=1
+export KERNEL_API_KEY=...
+export KERNEL_PROJECT_ID=...
+export KERNEL_ALT_PROJECT_ID=... # optional second project
+export KERNEL_BASE_URL=...       # optional non-production API
+```
+
+`KERNEL_PROJECT_ID` is required for the browser-pool resource and all four data
+sources. The project resource is organization-scoped and does not require it.
+
+## Matrix
+
+| Surface | Package | Live scenario |
+| --- | --- | --- |
+| `kernel_project` resource | `./internal/resources/project` | Create, rename with stable ID, no-drift plan, canonical-ID import, post-import no drift, delete, and HTTP 404 verification. |
+| `kernel_browser_pool` resource | `./internal/resources/browserpool` | Create, durable update with stable ID, no-drift plan, provider-default and explicit project scope, bare and project-qualified import, non-force delete, and HTTP 404 verification. |
+| `kernel_project` data source | `./internal/datasources/project` | Create a unique project fixture, read it by ID and exact name, read the provider-default project, verify durable metadata and no drift, then delete and require coded `not_found`. |
+| `kernel_profile` data source | `./internal/datasources/profile` | Create a durable profile fixture through the SDK, read it by ID and exact name with explicit and default project scope, verify durable metadata and no drift, then delete and require coded `not_found`. |
+| `kernel_proxy` data source | `./internal/datasources/proxy` | Create a managed datacenter proxy fixture through the SDK, read it by ID and exact name with explicit and default project scope, verify durable masked metadata and no drift, then delete and require coded `not_found`. |
+| `kernel_extension` data source | `./internal/datasources/extension` | Upload a durable extension fixture through the SDK, read it by ID and exact name with explicit and default project scope, verify durable metadata excludes runtime usage, verify no drift, then delete and require coded `not_found`. |
+
+The tests exist in the repository. That does not prove they passed against a
+particular release commit; the release record supplies that evidence.
+
+## Commands
+
+Run packages independently for fast failure isolation:
+
+```sh
+go test -count=1 -timeout=30m -v ./internal/resources/project -run TestAcc
+go test -count=1 -timeout=30m -v ./internal/resources/browserpool -run TestAcc
+go test -count=1 -timeout=30m -v ./internal/datasources/project -run TestAcc
+go test -count=1 -timeout=30m -v ./internal/datasources/profile -run TestAcc
+go test -count=1 -timeout=30m -v ./internal/datasources/proxy -run TestAcc
+go test -count=1 -timeout=30m -v ./internal/datasources/extension -run TestAcc
+```
+
+The manual `Acceptance` workflow runs the same six packages as separate matrix
+jobs with `fail-fast: false`. Live acceptance remains a manual pre-tag gate.
+
+## Outside The Selected Surface
+
+The release does not include a browser-pool data source or profile, proxy,
+extension, deployment, app, or API-key resources. Runtime/session operations
+remain outside Terraform. Unregistered surfaces are not acceptance blockers for
+this selected release.
+
+## Release Record
+
+Record the following in the release PR or release issue:
+
+```text
+Commit:
+Workflow run URL:
+API environment:
+Started at:
+Completed at:
+Package results:
+Interrupted or timed-out jobs:
+Leaked-resource audit completed:
+```
+
+Do not record credentials or secret values. A process-level timeout can bypass
+`t.Cleanup`; follow the cleanup procedure in
+[Release And Security Checklist](release.md) before rerunning or tagging.

docs/architecture.md

@@ -221,6 +221,9 @@ Acceptance tests must:
 - avoid browser/session runtime operations
 - exercise import and real delete behavior for each resource
 
+The current registered coverage and pre-tag live run are defined by the
+[Selected-Surface Acceptance Matrix](acceptance.md).
+
 ## PR Slicing
 
 PRs must be small, coherent, and shippable. No PR should rely on hidden follow-up work to keep the repo healthy.

docs/release.md

@@ -12,15 +12,13 @@ Use this checklist before publishing a Kernel Terraform provider version.
 - Run `terraform fmt -check -recursive examples`.
 - Run `go test -short -timeout=2m ./...`.
 - Run `go vet ./...`.
-- Run the complete opt-in acceptance matrix for every v1 resource and data source with real credentials before the first public release.
-  - Browser pools: `TF_ACC=1 KERNEL_ACC=1 KERNEL_API_KEY=... KERNEL_PROJECT_ID=... go test -count=1 -timeout=30m -v ./internal/resources/browserpool -run TestAcc`.
-  - Projects: `TF_ACC=1 KERNEL_ACC=1 KERNEL_API_KEY=... go test -count=1 -timeout=30m -v ./internal/resources/project -run TestAcc`.
-  - The manual `Acceptance` workflow runs both packages in parallel; expand its matrix as v1 resources land and keep live tests out of normal PR CI.
+- Run the complete [selected-surface acceptance matrix](acceptance.md) with real credentials against the release commit.
+  - The manual `Acceptance` workflow runs all six packages as independent matrix jobs. Keep live tests out of normal pull-request CI.
   - Process-level timeouts can bypass Go test cleanup. After an interrupted or hard-timeout run:
-    1. In the Kernel dashboard or durable API, find projects and browser pools named `kernel-tf-*` that were created during the failed workflow run.
-    2. Delete leaked browser pools first with `force=false`. If deletion conflicts with a lease, wait for the lease to end; do not force-release or recover the browser from Terraform cleanup.
-    3. Delete a leaked project only after its child resources are gone and the organization still has another active project.
-    4. Read each canonical resource ID and require a 404 before considering cleanup complete.
+    1. In the Kernel dashboard or durable API, find projects, browser pools, profiles, proxies, and extensions named `kernel-tf-*` that were created during the failed workflow run.
+    2. Delete leaked browser pools with `force=false`. If deletion conflicts with a lease, wait for the lease to end; do not force-release or recover the browser from Terraform cleanup.
+    3. Delete other leaked project-scoped fixtures, then delete a leaked project only after its child resources are gone and the organization still has another active project.
+    4. Read each canonical ID and require the expected not-found response before considering cleanup complete.
 - Verify unscoped API calls send no `X-Kernel-Project-Id` header; it is sent only when a resource-level `project_id` or the provider default resolves a project.
 - Confirm `terraform-registry-manifest.json` contains protocol `["6.0"]` for Terraform Plugin Framework.
 - Confirm the repository license before the first public release. Do not publish a public tag until `LICENSE` exists or the release owner has explicitly documented the licensing decision.