diff --git a/.changeset/sys-metadata-docblock-alignment.md b/.changeset/sys-metadata-docblock-alignment.md
new file mode 100644
index 0000000000..a5cd908a24
--- /dev/null
+++ b/.changeset/sys-metadata-docblock-alignment.md
@@ -0,0 +1,29 @@
+---
+"@objectstack/spec": patch
+---
+
+docs(spec): stop teaching `sys_metadata` as still keyed by `environment_id`
+
+Prose only — no behaviour change. The `environment.zod.ts` module docblock
+listed `sys_metadata` among the Control-Plane tables **"(with `environment_id`)"**,
+alongside the correct `sys_package_installation` (with `environment_id`)`
+entry (ADR-0003, UNIQUE `(environment_id, package_id)`), which is untouched.
+
+That parenthetical ships verbatim to two consumer-facing surfaces: the docs
+site (`content/docs/references/cloud/environment.mdx`, auto-generated from
+this docblock) and the published `.d.ts` — an editor tooltip for anyone
+importing `@objectstack/spec/cloud`.
+
+On the metadata tables, `environment_id` is retired, not live (AGENTS.md:8;
+ADR-0006 v4; `packages/metadata-core/src/objects/sys-metadata.object.ts` and
+`packages/metadata/src/loaders/database-loader.ts` both carry `@deprecated`
+notes to the same effect, and the loader's test pins `organization_id` in the
+write path with no `environment_id` filter anywhere). The docblock's own
+parenthetical was the one place still teaching the opposite.
+
+The replacement wording matches `AGENTS.md:8` exactly: it asserts only that
+`environment_id` is deprecated on the metadata tables in favor of
+`organization_id`, and says nothing about whether the cloud control plane's
+own `sys_metadata` table still keys by it — a fact this tree cannot settle.
+That framing is true under either reading, so it does not require resolving
+which one holds.
diff --git a/content/docs/permissions/system-context.mdx b/content/docs/permissions/system-context.mdx
index 5a4eb85ac7..1c9112108b 100644
--- a/content/docs/permissions/system-context.mdx
+++ b/content/docs/permissions/system-context.mdx
@@ -49,7 +49,7 @@ nothing to do with elevation.
 | `ExecutionContext.isSystem` — `packages/spec/src/kernel/execution-context.zod.ts:269` | The elevation flag on an operation's context | ✅ |
 | `Object.isSystem` — `packages/spec/src/data/object.zod.ts:1588` | Marks a **system object** (protected from deletion; defaults its org-wide sharing to `public` when no `sharingModel` is set) | ❌ |
 | `EmailTemplate.isSystem` — `packages/spec/src/system/email-template.zod.ts:125` | Built-in template; tenants may override but should not delete | ❌ |
-| `Environment.isSystem` — `packages/spec/src/cloud/environment.zod.ts:136` | Platform-infrastructure environment, not user data | ❌ |
+| `Environment.isSystem` — `packages/spec/src/cloud/environment.zod.ts:137` | Platform-infrastructure environment, not user data | ❌ |
 
 The collision is a genuine hazard rather than a naming nit: `Object.isSystem`
 changes an object's **default sharing**, and `ExecutionContext.isSystem` changes
diff --git a/content/docs/references/cloud/environment.mdx b/content/docs/references/cloud/environment.mdx
index 788285308a..5c6b762caa 100644
--- a/content/docs/references/cloud/environment.mdx
+++ b/content/docs/references/cloud/environment.mdx
@@ -26,7 +26,8 @@ a per-org `manifest_id` (see ADR-0003), so a single package + version
 Split of concerns:
 - **Control Plane**: `sys_environment` (includes physical DB addressing),
   `sys_package_installation` (with `environment_id`), `sys_environment_credential`,
-  `sys_environment_member`, `sys_metadata` (with `environment_id`).
+  `sys_environment_member`, `sys_metadata` (on the metadata tables, `environment_id`
+  is deprecated in favor of `organization_id` — ADR-0006 v4).
 - **Data Plane**: each environment DB contains only business objects
   (account, task, …). No system tables, no `environment_id` columns.
 
diff --git a/packages/spec/src/cloud/environment.zod.ts b/packages/spec/src/cloud/environment.zod.ts
index 6d64e3bbe5..d4e6bed9e7 100644
--- a/packages/spec/src/cloud/environment.zod.ts
+++ b/packages/spec/src/cloud/environment.zod.ts
@@ -26,7 +26,8 @@ import { lazySchema } from '../shared/lazy-schema';
  * Split of concerns:
  * - **Control Plane**: `sys_environment` (includes physical DB addressing),
  *   `sys_package_installation` (with `environment_id`), `sys_environment_credential`,
- *   `sys_environment_member`, `sys_metadata` (with `environment_id`).
+ *   `sys_environment_member`, `sys_metadata` (on the metadata tables, `environment_id`
+ *   is deprecated in favor of `organization_id` — ADR-0006 v4).
  * - **Data Plane**: each environment DB contains only business objects
  *   (account, task, …). No system tables, no `environment_id` columns.
  */