diff --git a/.changeset/registry-env-requires.md b/.changeset/registry-env-requires.md
new file mode 100644
index 000000000..b8988076e
--- /dev/null
+++ b/.changeset/registry-env-requires.md
@@ -0,0 +1,8 @@
+---
+"@emdash-cms/registry-client": minor
+"@emdash-cms/plugin-cli": minor
+"@emdash-cms/admin": minor
+"emdash": minor
+---
+
+Registry plugins can now declare environment requirements. A plugin's manifest may set a release-level `requires` block (e.g. `{ "env:emdash": ">=1.0.0", "env:astro": ">=4.16" }`), which is published into the release record. When browsing a registry plugin, the admin compares those constraints against the running EmDash and Astro versions: if the host doesn't satisfy them, it shows a compatibility warning and disables the Install button. The server enforces the same check on install and update, refusing an incompatible release with `ENV_INCOMPATIBLE` so the gate can't be bypassed.
diff --git a/packages/admin/src/components/RegistryPluginDetail.tsx b/packages/admin/src/components/RegistryPluginDetail.tsx
index 028359cef..a8bdb7894 100644
--- a/packages/admin/src/components/RegistryPluginDetail.tsx
+++ b/packages/admin/src/components/RegistryPluginDetail.tsx
@@ -14,17 +14,20 @@
  */
 
 import { Badge, Button, LinkButton, Select } from "@cloudflare/kumo";
+import { checkEnvCompatibility } from "@emdash-cms/registry-client/env";
 import { useLingui } from "@lingui/react/macro";
 import { ShieldCheck, Warning } from "@phosphor-icons/react";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { Link } from "@tanstack/react-router";
 import * as React from "react";
 
+import { fetchManifest } from "../lib/api/client.js";
 import {
 	artifactProxyUrl,
 	canonicalCapabilitiesForDriftCheck,
 	extractMediaArtifacts,
 	getRegistryPackage,
+	hostEnvFromManifest,
 	installRegistryPlugin,
 	listRegistryReleases,
 	releasePassesPolicy,
@@ -61,6 +64,16 @@ export function RegistryPluginDetail({ pluginId, config }: RegistryPluginDetailP
 		},
 	});
 
+	// Host environment versions (`env:emdash`, `env:astro`) — used to evaluate
+	// the selected release's `requires` constraints before offering install.
+	// Derived from the admin manifest the shell already fetches under the same
+	// query key, so this view adds no extra round-trip.
+	const { data: manifest } = useQuery({
+		queryKey: ["manifest"],
+		queryFn: fetchManifest,
+	});
+	const hostEnv = React.useMemo(() => hostEnvFromManifest(manifest), [manifest]);
+
 	// Parse `<publisher>/<slug>` out of the route param. The publisher
 	// segment is either a handle (`example.dev`) or a DID
 	// (`did:plc:abc...`). Slugs are `[A-Za-z][A-Za-z0-9_-]*` (no `/`),
@@ -242,6 +255,20 @@ export function RegistryPluginDetail({ pluginId, config }: RegistryPluginDetailP
 
 	const policyOk =
 		release && pkg ? releasePassesPolicy(release, { did: pkg.did, slug }, config.policy) : true;
+
+	// Environment compatibility: compare the selected release's `requires`
+	// constraints against the running host. `requires` is the lexicon's open
+	// `unknown` value; `checkEnvCompatibility` guards its shape. Mirrors the
+	// server-side install gate so the admin can't offer an install the server
+	// would reject. While the manifest is still loading `hostEnv` is empty, so
+	// every constraint is skipped (fail-open until the data arrives; the server
+	// gate is the authority either way).
+	const envMismatches = React.useMemo(() => {
+		if (!release) return [];
+		return checkEnvCompatibility(release.release?.requires, hostEnv);
+	}, [release, hostEnv]);
+	const envOk = envMismatches.length === 0;
+
 	// Handle resolution affects display only -- installs are addressed
 	// by DID, so an unverified or missing handle doesn't block install.
 	// A handle that *claims* a value but doesn't verify (`status:
@@ -417,7 +444,7 @@ export function RegistryPluginDetail({ pluginId, config }: RegistryPluginDetailP
 					) : (
 						<Button
 							variant="primary"
-							disabled={!release || !policyOk || handleResult.status === "invalid"}
+							disabled={!release || !policyOk || !envOk || handleResult.status === "invalid"}
 							onClick={() => setShowConsent(true)}
 						>
 							{t`Install`}
@@ -484,6 +511,32 @@ export function RegistryPluginDetail({ pluginId, config }: RegistryPluginDetailP
 				</div>
 			) : null}
 
+			{/* Environment compatibility notice. Mirrors the server install gate
+			    (ENV_INCOMPATIBLE): the selected release declares `requires`
+			    constraints the running host doesn't satisfy. Install is
+			    disabled until the host is upgraded. */}
+			{release && !envOk ? (
+				<div
+					className="flex items-start gap-3 rounded-md border border-kumo-warning bg-kumo-warning/10 p-4 text-kumo-warning"
+					role="status"
+				>
+					<Warning className="mt-0.5 h-5 w-5 shrink-0" />
+					<div>
+						<p className="font-medium">{t`Not compatible with this environment`}</p>
+						<p className="mt-1 text-sm text-kumo-default">
+							{t`This release requires a newer environment than your site currently runs. Upgrade before installing.`}
+						</p>
+						<ul className="mt-2 space-y-1 text-sm text-kumo-default">
+							{envMismatches.map((m) => (
+								<li key={m.key}>
+									{t`${envLabel(m.key)} ${m.required} required — you have ${m.host}.`}
+								</li>
+							))}
+						</ul>
+					</div>
+				</div>
+			) : null}
+
 			{/* Description */}
 			{description ? <p className="text-base text-kumo-default">{description}</p> : null}
 
@@ -665,6 +718,17 @@ function isPreReleaseVersion(version: string): boolean {
 	return PRE_RELEASE_VERSION_RE.test(version);
 }
 
+/**
+ * Human-readable name for a `requires` env key. The known EmDash environments
+ * get their proper product names; anything else falls back to the key with the
+ * `env:` prefix stripped (product names, not localised strings).
+ */
+function envLabel(key: string): string {
+	if (key === "env:emdash") return "EmDash";
+	if (key === "env:astro") return "Astro";
+	return key.startsWith("env:") ? key.slice("env:".length) : key;
+}
+
 const YANKED_LABEL_VALUE = "security:yanked";
 
 /**
diff --git a/packages/admin/src/lib/api/client.ts b/packages/admin/src/lib/api/client.ts
index 94acb3497..0e436a167 100644
--- a/packages/admin/src/lib/api/client.ts
+++ b/packages/admin/src/lib/api/client.ts
@@ -54,6 +54,8 @@ export interface FindManyResult<T> {
  */
 export interface AdminManifest {
 	version: string;
+	/** Version of Astro the host is built with, when resolvable. */
+	astroVersion?: string;
 	hash: string;
 	collections: Record<
 		string,
diff --git a/packages/admin/src/lib/api/registry.ts b/packages/admin/src/lib/api/registry.ts
index fc2468c43..2c2bea105 100644
--- a/packages/admin/src/lib/api/registry.ts
+++ b/packages/admin/src/lib/api/registry.ts
@@ -26,12 +26,21 @@ import type {
 	ValidatedReleaseView,
 	ValidatedSearchPackages,
 } from "@emdash-cms/registry-client/discovery";
+import { hostEnvFromVersions } from "@emdash-cms/registry-client/env";
+import type { HostEnv } from "@emdash-cms/registry-client/env";
 import { i18n } from "@lingui/core";
 import { msg } from "@lingui/core/macro";
 
-import { API_BASE, apiFetch, parseApiResponse, throwResponseError } from "./client.js";
+import {
+	API_BASE,
+	apiFetch,
+	parseApiResponse,
+	throwResponseError,
+	type AdminManifest,
+} from "./client.js";
 
 export type { Did, Handle };
+export type { HostEnv };
 
 // ---------------------------------------------------------------------------
 // Types
@@ -294,6 +303,18 @@ export async function listRegistryReleases(
 	return client.listReleases(did, slug, opts);
 }
 
+/**
+ * Derive the host environment versions (`env:emdash`, `env:astro`) the running
+ * EmDash install advertises, so a release's `requires` constraints can be
+ * evaluated client-side before offering install. Reads the already-fetched
+ * admin manifest (`version`, `astroVersion`) rather than issuing a second
+ * request. The dev-skip / astro-omit rule is shared with the server gate via
+ * `hostEnvFromVersions`.
+ */
+export function hostEnvFromManifest(manifest: AdminManifest | undefined): HostEnv {
+	return hostEnvFromVersions(manifest?.version, manifest?.astroVersion);
+}
+
 /**
  * Resolve a publisher DID to its claimed handle using the same
  * `LocalActorResolver` pattern as `@emdash-cms/plugin-cli` and
diff --git a/packages/core/src/api/errors.ts b/packages/core/src/api/errors.ts
index ec1569fb6..1ec1c783b 100644
--- a/packages/core/src/api/errors.ts
+++ b/packages/core/src/api/errors.ts
@@ -201,6 +201,7 @@ export const ErrorCode = {
 	AGGREGATOR_NOT_FOUND: "AGGREGATOR_NOT_FOUND",
 	CAPABILITY_ESCALATION: "CAPABILITY_ESCALATION",
 	ROUTE_VISIBILITY_ESCALATION: "ROUTE_VISIBILITY_ESCALATION",
+	ENV_INCOMPATIBLE: "ENV_INCOMPATIBLE",
 	INSTALL_FAILED: "INSTALL_FAILED",
 	UNINSTALL_FAILED: "UNINSTALL_FAILED",
 	SEARCH_FAILED: "SEARCH_FAILED",
@@ -414,6 +415,7 @@ export function mapErrorStatus(code: string | undefined): number {
 		case ErrorCode.ALREADY_INSTALLED:
 		case ErrorCode.ALREADY_CONFIGURED:
 		case ErrorCode.ALREADY_UP_TO_DATE:
+		case ErrorCode.ENV_INCOMPATIBLE:
 			return 409;
 
 		// 410 Gone
diff --git a/packages/core/src/api/handlers/index.ts b/packages/core/src/api/handlers/index.ts
index 09be34fef..9f48888ae 100644
--- a/packages/core/src/api/handlers/index.ts
+++ b/packages/core/src/api/handlers/index.ts
@@ -171,6 +171,7 @@ export {
 
 // Registry handlers (experimental)
 export {
+	assertEnvCompatible,
 	assertSafeArtifactUrl,
 	handleRegistryInstall,
 	handleRegistryUninstall,
diff --git a/packages/core/src/api/handlers/registry.ts b/packages/core/src/api/handlers/registry.ts
index 8c556fdb1..51bb70d9a 100644
--- a/packages/core/src/api/handlers/registry.ts
+++ b/packages/core/src/api/handlers/registry.ts
@@ -40,6 +40,8 @@
 
 import { ClientResponseError, ClientValidationError } from "@atcute/client";
 import type { Did } from "@atcute/lexicons";
+import { checkEnvCompatibility, findSkippedEnvConstraints } from "@emdash-cms/registry-client/env";
+import type { HostEnv } from "@emdash-cms/registry-client/env";
 import type { Kysely } from "kysely";
 
 import type { Database } from "../../database/types.js";
@@ -520,6 +522,52 @@ async function fetchArtifact(mirrors: string[], declaredUrl: string): Promise<Ui
 	);
 }
 
+/**
+ * The shape of a single env-compatibility failure returned to the admin in
+ * the `ENV_INCOMPATIBLE` error's `details`.
+ */
+interface EnvIncompatibleError {
+	code: "ENV_INCOMPATIBLE";
+	message: string;
+	details: { requires: Record<string, string>; host: HostEnv };
+}
+
+/**
+ * Gate a release's `requires` constraints against the running host
+ * environment. `requires` is the lexicon-`unknown` value off the signed
+ * release record — never trust its shape; `checkEnvCompatibility` guards it.
+ *
+ * Returns `null` when every advertised constraint is satisfied (or there are
+ * none), or a structured `ENV_INCOMPATIBLE` error naming the unsatisfied
+ * constraints and the host versions. The error carries the guarded `requires`
+ * and `host` maps so the admin can render the same mismatch the UI gate shows.
+ */
+export function assertEnvCompatible(
+	requires: unknown,
+	hostEnv: HostEnv,
+): EnvIncompatibleError | null {
+	// A constraint the host can't evaluate (unknown or unparseable host
+	// version) downgrades the gate to a no-op for that env. Log it so a
+	// silent bypass is observable rather than invisible.
+	for (const skipped of findSkippedEnvConstraints(requires, hostEnv)) {
+		console.warn(
+			`[registry] env compatibility constraint skipped: ${skipped.key} requires ${skipped.required} but host version is ${skipped.reason}`,
+		);
+	}
+	const mismatches = checkEnvCompatibility(requires, hostEnv);
+	if (mismatches.length === 0) return null;
+	const guarded: Record<string, string> = {};
+	for (const m of mismatches) guarded[m.key] = m.required;
+	const summary = mismatches
+		.map((m) => `${m.key} requires ${m.required} but host is ${m.host}`)
+		.join("; ");
+	return {
+		code: "ENV_INCOMPATIBLE",
+		message: `This release is not compatible with the current environment: ${summary}.`,
+		details: { requires: guarded, host: hostEnv },
+	};
+}
+
 // ── Install ────────────────────────────────────────────────────────
 
 export async function handleRegistryInstall(
@@ -528,7 +576,7 @@ export async function handleRegistryInstall(
 	sandboxRunner: SandboxRunner | null,
 	registryConfigInput: RegistryConfigInput | undefined,
 	input: RegistryInstallInput,
-	opts?: { configuredPluginIds?: Set<string> },
+	opts?: { configuredPluginIds?: Set<string>; hostEnv?: HostEnv },
 ): Promise<ApiResult<RegistryInstallResult>> {
 	// Accept either the bare-string shorthand or the full
 	// `RegistryConfig` object (see `RegistryConfigInput`).
@@ -737,6 +785,17 @@ export async function handleRegistryInstall(
 			};
 		}
 
+		// Step 3b: environment compatibility. The signed release record may
+		// carry a `requires` block (`env:emdash`, `env:astro`, ...). Refuse
+		// the install if the running host doesn't satisfy a constraint, so a
+		// stale browser tab or non-UI caller can't bypass the admin's
+		// disabled Install button. `requires` is lexicon-`unknown`; the
+		// helper guards its shape.
+		if (opts?.hostEnv) {
+			const envError = assertEnvCompatible(releaseView.release?.requires, opts.hostEnv);
+			if (envError) return { success: false, error: envError };
+		}
+
 		// Step 3a: enforce the configured minimum release age. The browser
 		// applies the same check up front for UX, but the gate lives here
 		// -- a stale browser tab, a deep link, or a non-admin-UI caller
@@ -1212,6 +1271,7 @@ export async function handleRegistryUpdate(
 		version?: string;
 		confirmCapabilityChanges?: boolean;
 		confirmRouteVisibilityChanges?: boolean;
+		hostEnv?: HostEnv;
 	},
 ): Promise<ApiResult<RegistryUpdateResult>> {
 	const registryConfig = coerceRegistryConfig(registryConfigInput);
@@ -1363,6 +1423,14 @@ export async function handleRegistryUpdate(
 			};
 		}
 
+		// Environment compatibility gate. An ungated update could otherwise
+		// land a version whose `requires` the host doesn't satisfy. Same
+		// guard as install; `requires` is lexicon-`unknown`.
+		if (opts?.hostEnv) {
+			const envError = assertEnvCompatible(signedRelease.requires, opts.hostEnv);
+			if (envError) return { success: false, error: envError };
+		}
+
 		const declaredUrl = signedRelease.artifacts?.package?.url;
 		const declaredChecksum = signedRelease.artifacts?.package?.checksum;
 		if (!declaredUrl || !declaredChecksum) {
diff --git a/packages/core/src/astro/integration/index.ts b/packages/core/src/astro/integration/index.ts
index be342fd2c..c1aee2607 100644
--- a/packages/core/src/astro/integration/index.ts
+++ b/packages/core/src/astro/integration/index.ts
@@ -10,6 +10,8 @@
  * to avoid bundling Node.js-only code into the production build.
  */
 
+import { createRequire } from "node:module";
+
 import type { AstroIntegration, AstroIntegrationLogger } from "astro";
 
 import { validateAllowedOrigins, validateOriginShape } from "../../auth/allowed-origins.js";
@@ -34,6 +36,23 @@ export type {
 } from "./runtime.js";
 export { getStoredConfig } from "./runtime.js";
 
+/**
+ * Resolve the version of Astro the host project is building with, by reading
+ * `astro/package.json` from the project's own dependency tree. Surfaced to the
+ * admin and the registry install gate so a plugin's `env:astro` constraint can
+ * be evaluated against the real host version. Returns `undefined` if Astro
+ * can't be resolved (shouldn't happen in a real build, but never throw here).
+ */
+function resolveAstroVersion(): string | undefined {
+	try {
+		const require = createRequire(import.meta.url);
+		const pkg = require("astro/package.json") as { version?: unknown };
+		return typeof pkg.version === "string" ? pkg.version : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
 /** Default storage: Local filesystem in .emdash directory */
 const DEFAULT_STORAGE = local({
 	directory: "./.emdash/uploads",
@@ -204,6 +223,13 @@ export function emdash(config: EmDashConfig = {}): AstroIntegration {
 				command,
 			}) => {
 				printBanner(logger);
+				// Capture the host's Astro version so the runtime can expose it
+				// to the admin and the registry install gate for `env:astro`
+				// constraint checks.
+				const astroVersion = resolveAstroVersion();
+				if (astroVersion !== undefined) {
+					serializableConfig.astroVersion = astroVersion;
+				}
 				// Extract i18n config from Astro config
 				// Astro locales can be strings OR { path, codes } objects — normalize to paths
 				if (astroConfig.i18n) {
diff --git a/packages/core/src/astro/integration/runtime.ts b/packages/core/src/astro/integration/runtime.ts
index 3fe2b44d7..61d504a9c 100644
--- a/packages/core/src/astro/integration/runtime.ts
+++ b/packages/core/src/astro/integration/runtime.ts
@@ -527,6 +527,14 @@ export interface EmDashConfig {
 		/** URL or path to a custom favicon for the admin panel. */
 		favicon?: string;
 	};
+
+	/**
+	 * Version of Astro the host project is building with. Populated by the
+	 * integration's `astro:config:setup` hook (not authored by the user) and
+	 * surfaced to the admin and the registry install gate so a plugin's
+	 * `env:astro` requirement can be evaluated against the real host version.
+	 */
+	astroVersion?: string;
 }
 
 const STORED_CONFIG_KEY = Symbol.for("emdash:stored-config");
diff --git a/packages/core/src/astro/routes/api/admin/plugins/registry/[id]/update.ts b/packages/core/src/astro/routes/api/admin/plugins/registry/[id]/update.ts
index dc711a919..7d85b5c1e 100644
--- a/packages/core/src/astro/routes/api/admin/plugins/registry/[id]/update.ts
+++ b/packages/core/src/astro/routes/api/admin/plugins/registry/[id]/update.ts
@@ -9,6 +9,7 @@
  * routes and `confirmRouteVisibilityChanges` is absent.
  */
 
+import { hostEnvFromVersions } from "@emdash-cms/registry-client/env";
 import type { APIRoute } from "astro";
 import { z } from "zod";
 
@@ -17,6 +18,8 @@ import { apiError, handleError, unwrapResult } from "#api/error.js";
 import { handleRegistryUpdate } from "#api/index.js";
 import { isParseError, parseOptionalBody } from "#api/parse.js";
 
+import { VERSION } from "../../../../../../../version.js";
+
 export const prerender = false;
 
 const updateBodySchema = z.object({
@@ -64,6 +67,7 @@ export const POST: APIRoute = async ({ params, request, locals }) => {
 				version: body.version,
 				confirmCapabilityChanges: body.confirmCapabilityChanges,
 				confirmRouteVisibilityChanges: body.confirmRouteVisibilityChanges,
+				hostEnv: hostEnvFromVersions(VERSION, emdash.config.astroVersion),
 			},
 		);
 
diff --git a/packages/core/src/astro/routes/api/admin/plugins/registry/install.ts b/packages/core/src/astro/routes/api/admin/plugins/registry/install.ts
index 25aa9d08e..20e7a966d 100644
--- a/packages/core/src/astro/routes/api/admin/plugins/registry/install.ts
+++ b/packages/core/src/astro/routes/api/admin/plugins/registry/install.ts
@@ -12,6 +12,7 @@
  * view time (handle is best-effort per the lexicon).
  */
 
+import { hostEnvFromVersions } from "@emdash-cms/registry-client/env";
 import type { APIRoute } from "astro";
 import { z } from "zod";
 
@@ -20,6 +21,8 @@ import { apiError, handleError, unwrapResult } from "#api/error.js";
 import { handleRegistryInstall } from "#api/index.js";
 import { isParseError, parseBody } from "#api/parse.js";
 
+import { VERSION } from "../../../../../../version.js";
+
 export const prerender = false;
 
 const installBodySchema = z.object({
@@ -91,7 +94,10 @@ export const POST: APIRoute = async ({ request, locals }) => {
 				version: body.version,
 				acknowledgedDeclaredAccess: body.acknowledgedDeclaredAccess,
 			},
-			{ configuredPluginIds: reservedPluginIds },
+			{
+				configuredPluginIds: reservedPluginIds,
+				hostEnv: hostEnvFromVersions(VERSION, emdash.config.astroVersion),
+			},
 		);
 
 		if (!result.success) return unwrapResult(result);
diff --git a/packages/core/src/astro/types.ts b/packages/core/src/astro/types.ts
index 0ac391ddc..3a2f51a8d 100644
--- a/packages/core/src/astro/types.ts
+++ b/packages/core/src/astro/types.ts
@@ -108,6 +108,12 @@ export interface EmDashManifest {
 	version: string;
 	commit?: string;
 	hash: string;
+	/**
+	 * Version of Astro the host project is built with. Present when the
+	 * integration could resolve it. Surfaced so the admin can evaluate a
+	 * registry plugin's `env:astro` requirement against the running host.
+	 */
+	astroVersion?: string;
 	collections: Record<string, ManifestCollection>;
 	plugins: Record<string, ManifestPlugin>;
 	/**
diff --git a/packages/core/src/emdash-runtime.ts b/packages/core/src/emdash-runtime.ts
index 388e474ba..e88c57532 100644
--- a/packages/core/src/emdash-runtime.ts
+++ b/packages/core/src/emdash-runtime.ts
@@ -2048,6 +2048,7 @@ export class EmDashRuntime {
 		return {
 			version: VERSION,
 			commit: COMMIT,
+			astroVersion: this.config.astroVersion,
 			hash: manifestHash,
 			collections: manifestCollections,
 			plugins: manifestPlugins,
diff --git a/packages/core/tests/unit/api/registry-env-compat.test.ts b/packages/core/tests/unit/api/registry-env-compat.test.ts
new file mode 100644
index 000000000..8c79358b9
--- /dev/null
+++ b/packages/core/tests/unit/api/registry-env-compat.test.ts
@@ -0,0 +1,61 @@
+/**
+ * Environment-compatibility gate for registry install/update.
+ *
+ * `handleRegistryInstall` and `handleRegistryUpdate` both call
+ * `assertEnvCompatible` after release selection / yank-check and before the
+ * artifact fetch. The full handler path needs a mocked DiscoveryClient (tracked
+ * separately); these tests exercise the gate's decision logic directly — the
+ * same helper both handlers use — plus the host-env builder and the error-code
+ * status mapping that surfaces `ENV_INCOMPATIBLE` to the admin.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { mapErrorStatus } from "../../../src/api/errors.js";
+import { assertEnvCompatible } from "../../../src/api/handlers/registry.js";
+
+describe("assertEnvCompatible", () => {
+	const host = { "env:emdash": "1.2.0", "env:astro": "4.12.0" };
+
+	it("returns null when every constraint is satisfied", () => {
+		expect(
+			assertEnvCompatible({ "env:emdash": ">=1.0.0", "env:astro": ">=4.0.0" }, host),
+		).toBeNull();
+	});
+
+	it("returns null when there are no constraints", () => {
+		expect(assertEnvCompatible(undefined, host)).toBeNull();
+		expect(assertEnvCompatible({}, host)).toBeNull();
+	});
+
+	it("returns an ENV_INCOMPATIBLE error when a constraint is not satisfied", () => {
+		const error = assertEnvCompatible({ "env:astro": ">=4.16" }, host);
+		expect(error?.code).toBe("ENV_INCOMPATIBLE");
+		expect(error?.details.requires).toEqual({ "env:astro": ">=4.16" });
+		expect(error?.details.host).toEqual(host);
+		expect(error?.message).toContain("env:astro");
+	});
+
+	it("reports every unsatisfied constraint, skipping satisfied ones", () => {
+		const error = assertEnvCompatible({ "env:emdash": ">=2.0.0", "env:astro": ">=4.0.0" }, host);
+		expect(error?.details.requires).toEqual({ "env:emdash": ">=2.0.0" });
+	});
+
+	it("does not crash on a garbage requires shape", () => {
+		expect(assertEnvCompatible("garbage", host)).toBeNull();
+		expect(assertEnvCompatible(42, host)).toBeNull();
+		expect(assertEnvCompatible({ "env:astro": 999 }, host)).toBeNull();
+		expect(assertEnvCompatible(null, host)).toBeNull();
+	});
+
+	it("skips constraints for envs the host does not advertise", () => {
+		expect(assertEnvCompatible({ "did:plc:abc": "^1.0.0" }, host)).toBeNull();
+		expect(assertEnvCompatible({ "env:astro": ">=4.16" }, { "env:emdash": "1.2.0" })).toBeNull();
+	});
+});
+
+describe("ENV_INCOMPATIBLE status mapping", () => {
+	it("maps to 409 Conflict", () => {
+		expect(mapErrorStatus("ENV_INCOMPATIBLE")).toBe(409);
+	});
+});
diff --git a/packages/core/tests/unit/api/registry-env-gate-handler.test.ts b/packages/core/tests/unit/api/registry-env-gate-handler.test.ts
new file mode 100644
index 000000000..a1e663005
--- /dev/null
+++ b/packages/core/tests/unit/api/registry-env-gate-handler.test.ts
@@ -0,0 +1,141 @@
+/**
+ * Environment-compatibility gate wired through the real handler.
+ *
+ * `registry-env-compat.test.ts` exercises the gate's decision helper in
+ * isolation. This file drives `handleRegistryUpdate` end-to-end with a mocked
+ * `DiscoveryClient` so the wiring is covered: that `assertEnvCompatible` runs
+ * after release selection, that `opts.hostEnv` reaches it, and that an
+ * `ENV_INCOMPATIBLE` result aborts *before* any artifact fetch.
+ */
+
+import BetterSqlite3 from "better-sqlite3";
+import { Kysely, SqliteDialect } from "kysely";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { runMigrations } from "../../../src/database/migrations/runner.js";
+import type { Database as DbSchema } from "../../../src/database/types.js";
+import type { SandboxRunner } from "../../../src/plugins/sandbox/types.js";
+import { PluginStateRepository } from "../../../src/plugins/state.js";
+import type { Storage } from "../../../src/storage/types.js";
+
+/** A storage stub: present so the null-storage guard passes, never exercised. */
+const stubStorage = {
+	async download() {
+		throw new Error("not implemented");
+	},
+} as unknown as Storage;
+
+const getLatestRelease = vi.fn();
+const listReleases = vi.fn();
+const getPackage = vi.fn();
+
+vi.mock("@emdash-cms/registry-client/discovery", () => ({
+	DiscoveryClient: class {
+		getLatestRelease = getLatestRelease;
+		listReleases = listReleases;
+		getPackage = getPackage;
+	},
+}));
+
+const PUBLISHER = "did:plc:abc";
+const SLUG = "gallery";
+
+/**
+ * A release view shaped enough to pass the update handler's identity
+ * cross-check and reach the env gate, carrying a `requires` block.
+ */
+function releaseViewWithRequires(version: string, requires: Record<string, string>) {
+	return {
+		did: PUBLISHER,
+		package: SLUG,
+		version,
+		labels: [],
+		mirrors: [],
+		release: {
+			package: SLUG,
+			version,
+			requires,
+			// A real declared artifact URL: if the gate failed to abort, the
+			// handler would proceed to fetch this, tripping the `fetch` spy.
+			artifacts: {
+				package: {
+					url: "https://artifacts.test/gallery-2.0.0.tar.gz",
+					checksum: "sha256-deadbeef",
+				},
+			},
+		},
+	};
+}
+
+describe("handleRegistryUpdate env gate", () => {
+	let db: Kysely<DbSchema>;
+	let handleRegistryUpdate: typeof import("../../../src/api/handlers/registry.js").handleRegistryUpdate;
+	const stubSandbox = { isAvailable: () => true } as unknown as SandboxRunner;
+	const config = { aggregatorUrl: "https://aggregator.test" };
+	let fetchSpy: ReturnType<typeof vi.fn>;
+
+	beforeEach(async () => {
+		({ handleRegistryUpdate } = await import("../../../src/api/handlers/registry.js"));
+		const sqlite = new BetterSqlite3(":memory:");
+		db = new Kysely<DbSchema>({ dialect: new SqliteDialect({ database: sqlite }) });
+		await runMigrations(db);
+
+		const repo = new PluginStateRepository(db);
+		await repo.upsert("r_gallery000000000", "1.0.0", "active", {
+			source: "registry",
+			registryPublisherDid: PUBLISHER,
+			registrySlug: SLUG,
+		});
+
+		getLatestRelease.mockReset();
+		listReleases.mockReset();
+		getPackage.mockReset();
+		fetchSpy = vi.fn(() => {
+			throw new Error("artifact fetch must not run when the env gate rejects");
+		});
+		vi.stubGlobal("fetch", fetchSpy);
+	});
+
+	afterEach(async () => {
+		vi.unstubAllGlobals();
+		await db.destroy();
+	});
+
+	it("rejects with ENV_INCOMPATIBLE and fetches no artifact when the host fails `requires`", async () => {
+		getLatestRelease.mockResolvedValue(
+			releaseViewWithRequires("2.0.0", { "env:astro": ">=5.0.0" }),
+		);
+
+		const result = await handleRegistryUpdate(
+			db,
+			stubStorage,
+			stubSandbox,
+			config,
+			"r_gallery000000000",
+			{ hostEnv: { "env:emdash": "1.2.0", "env:astro": "4.16.0" } },
+		);
+
+		expect(result.success).toBe(false);
+		expect(result.error?.code).toBe("ENV_INCOMPATIBLE");
+		expect(fetchSpy).not.toHaveBeenCalled();
+	});
+
+	it("does not reject when the host satisfies `requires` (gate passes through)", async () => {
+		getLatestRelease.mockResolvedValue(
+			releaseViewWithRequires("2.0.0", { "env:astro": ">=4.0.0" }),
+		);
+
+		const result = await handleRegistryUpdate(
+			db,
+			stubStorage,
+			stubSandbox,
+			config,
+			"r_gallery000000000",
+			{ hostEnv: { "env:emdash": "1.2.0", "env:astro": "4.16.0" } },
+		);
+
+		// The gate passes; the update proceeds past it. With null storage the
+		// handler then fails downstream — but never with ENV_INCOMPATIBLE.
+		expect(result.error?.code).not.toBe("ENV_INCOMPATIBLE");
+	});
+});
diff --git a/packages/plugin-cli/schemas/emdash-plugin.schema.json b/packages/plugin-cli/schemas/emdash-plugin.schema.json
index 6b3e34e28..a36973805 100644
--- a/packages/plugin-cli/schemas/emdash-plugin.schema.json
+++ b/packages/plugin-cli/schemas/emdash-plugin.schema.json
@@ -472,42 +472,69 @@
 		"__schema43": {
 			"type": "object",
 			"properties": {
-				"artifacts": {
+				"requires": {
 					"$ref": "#/$defs/__schema44"
+				},
+				"artifacts": {
+					"$ref": "#/$defs/__schema47"
 				}
 			},
 			"additionalProperties": false,
 			"title": "Release",
-			"description": "Per-release fields, such as media artifacts (icon / screenshot / banner)."
+			"description": "Per-release fields: environment constraints (`requires`) and media artifacts (icon / screenshot / banner)."
 		},
 		"__schema44": {
+			"type": "object",
+			"propertyNames": {
+				"$ref": "#/$defs/__schema45"
+			},
+			"additionalProperties": {
+				"$ref": "#/$defs/__schema46"
+			},
+			"title": "Environment requirements",
+			"description": "Host environment constraints for this release, keyed by `env:*` (e.g. \"env:astro\", \"env:emdash\") with semver-range values. EmDash refuses to install a release whose constraints the host does not satisfy.",
+			"examples": [
+				{
+					"env:emdash": ">=1.0.0",
+					"env:astro": ">=4.16"
+				}
+			]
+		},
+		"__schema45": {
+			"type": "string"
+		},
+		"__schema46": {
+			"type": "string",
+			"minLength": 1
+		},
+		"__schema47": {
 			"type": "object",
 			"properties": {
 				"icon": {
-					"$ref": "#/$defs/__schema45"
+					"$ref": "#/$defs/__schema48"
 				},
 				"banner": {
-					"$ref": "#/$defs/__schema49"
+					"$ref": "#/$defs/__schema52"
 				},
 				"screenshots": {
-					"$ref": "#/$defs/__schema50"
+					"$ref": "#/$defs/__schema53"
 				}
 			},
 			"additionalProperties": false,
 			"title": "Artifacts",
 			"description": "Release media artifacts. `icon` and `banner` are single images; `screenshots` is a gallery array."
 		},
-		"__schema45": {
-			"$ref": "#/$defs/__schema46"
+		"__schema48": {
+			"$ref": "#/$defs/__schema49"
 		},
-		"__schema46": {
+		"__schema49": {
 			"type": "object",
 			"properties": {
 				"file": {
-					"$ref": "#/$defs/__schema47"
+					"$ref": "#/$defs/__schema50"
 				},
 				"lang": {
-					"$ref": "#/$defs/__schema48"
+					"$ref": "#/$defs/__schema51"
 				}
 			},
 			"required": [
@@ -517,13 +544,13 @@
 			"title": "Artifact file reference",
 			"description": "A media file (PNG / JPEG / WebP / GIF / AVIF) bundled into a release as an icon, screenshot, or banner."
 		},
-		"__schema47": {
+		"__schema50": {
 			"type": "string",
 			"minLength": 1,
 			"maxLength": 1024,
 			"description": "Path to the image file, relative to the manifest. Resolved, hashed, measured, and uploaded at publish time."
 		},
-		"__schema48": {
+		"__schema51": {
 			"type": "string",
 			"minLength": 2,
 			"maxLength": 64,
@@ -533,15 +560,15 @@
 				"pt-BR"
 			]
 		},
-		"__schema49": {
-			"$ref": "#/$defs/__schema46"
+		"__schema52": {
+			"$ref": "#/$defs/__schema49"
 		},
-		"__schema50": {
+		"__schema53": {
 			"minItems": 1,
 			"maxItems": 8,
 			"type": "array",
 			"items": {
-				"$ref": "#/$defs/__schema46"
+				"$ref": "#/$defs/__schema49"
 			},
 			"title": "Screenshots",
 			"description": "Screenshot gallery for the plugin's detail page (<= 8 entries)."
diff --git a/packages/plugin-cli/src/commands/publish.ts b/packages/plugin-cli/src/commands/publish.ts
index 46400e3c1..75c66a250 100644
--- a/packages/plugin-cli/src/commands/publish.ts
+++ b/packages/plugin-cli/src/commands/publish.ts
@@ -320,6 +320,7 @@ async function runPublish(args: PublishArgs): Promise<void> {
 		url: args.url,
 		profileInput,
 		repo: manifestLoad?.manifest.repo,
+		requires: manifestLoad?.manifest.requires,
 		artifacts,
 		allowOverwrite: args["allow-overwrite"],
 		logger,
diff --git a/packages/plugin-cli/src/manifest/schema.ts b/packages/plugin-cli/src/manifest/schema.ts
index ff163466b..cdb7e74ba 100644
--- a/packages/plugin-cli/src/manifest/schema.ts
+++ b/packages/plugin-cli/src/manifest/schema.ts
@@ -60,6 +60,7 @@ import {
 	PLUGIN_VERSION_MAX_LENGTH,
 	PLUGIN_VERSION_RE,
 } from "@emdash-cms/plugin-types";
+import { isValidVersionRange } from "@emdash-cms/registry-client/env";
 import { z } from "zod";
 
 // ──────────────────────────────────────────────────────────────────────────
@@ -245,6 +246,42 @@ export const RepoSchema = z
 		examples: ["https://github.com/emdash-cms/plugin-gallery"],
 	});
 
+/** `env:<name>` requirement keys (one or more non-colon characters). */
+const REQUIRES_ENV_KEY_RE = /^env:[^:]+$/;
+
+/**
+ * Release-level environment constraints. Mirrors `release.json#requires`: a
+ * map of `env:*` keys (host environment requirements) or package DIDs to
+ * semver-range constraint strings. EmDash uses `env:emdash` and `env:astro`.
+ *
+ * Keys are validated structurally (`env:<name>` or `did:<method>:<id>`) and
+ * values against the shared range grammar in `@emdash-cms/registry-client/env`,
+ * the same evaluator the install gate and the admin compatibility warning use,
+ * so a publisher can't ship a constraint that no consumer can evaluate.
+ */
+export const RequiresSchema = z
+	.record(
+		z
+			.string()
+			.refine(
+				(k) => REQUIRES_ENV_KEY_RE.test(k) || isDid(k),
+				'requires key must be an `env:*` requirement (e.g. "env:astro") or a package DID',
+			),
+		z
+			.string()
+			.min(1, "requires range must be a non-empty semver range")
+			.refine(
+				isValidVersionRange,
+				'requires range must be a valid semver range (e.g. ">=4.16", "^4.0.0", ">=4.16.0 <5.0.0")',
+			),
+	)
+	.meta({
+		title: "Environment requirements",
+		description:
+			'Host environment constraints for this release, keyed by `env:*` (e.g. "env:astro", "env:emdash") with semver-range values. EmDash refuses to install a release whose constraints the host does not satisfy.',
+		examples: [{ "env:emdash": ">=1.0.0", "env:astro": ">=4.16" }],
+	});
+
 // ──────────────────────────────────────────────────────────────────────────
 // Identity (slug + version)
 // ──────────────────────────────────────────────────────────────────────────
@@ -603,12 +640,14 @@ export const ArtifactsSchema = z
  */
 export const ReleaseSchema = z
 	.object({
+		requires: RequiresSchema.optional(),
 		artifacts: ArtifactsSchema.optional(),
 	})
 	.strict()
 	.meta({
 		title: "Release",
-		description: "Per-release fields, such as media artifacts (icon / screenshot / banner).",
+		description:
+			"Per-release fields: environment constraints (`requires`) and media artifacts (icon / screenshot / banner).",
 	});
 
 // ──────────────────────────────────────────────────────────────────────────
@@ -717,8 +756,9 @@ export const ManifestSchema = z
 		// Optional release fields.
 		repo: RepoSchema.optional(),
 
-		// Per-release media artifacts (icon / screenshot / banner). File
-		// refs are resolved relative to the manifest at publish time.
+		// Per-release block: environment constraints (`requires`) and media
+		// artifacts (icon / screenshot / banner). File refs are resolved
+		// relative to the manifest at publish time.
 		release: ReleaseSchema.optional(),
 	})
 	.strict()
diff --git a/packages/plugin-cli/src/manifest/translate.ts b/packages/plugin-cli/src/manifest/translate.ts
index 25428abae..08a69c74f 100644
--- a/packages/plugin-cli/src/manifest/translate.ts
+++ b/packages/plugin-cli/src/manifest/translate.ts
@@ -50,6 +50,13 @@ export interface NormalisedManifest {
 	keywords: string[] | undefined;
 	repo: string | undefined;
 
+	/**
+	 * Release-level environment constraints (`release.requires`). Map of
+	 * `env:*`/DID keys to semver ranges. Release-level, not profile-level —
+	 * passed to `publishRelease` separately, never via `manifestToProfileInput`.
+	 */
+	requires: Record<string, string> | undefined;
+
 	/**
 	 * Release media artifacts (icon / screenshot / banner). File refs only —
 	 * the publish command resolves, measures, and uploads them. `undefined`
@@ -178,6 +185,7 @@ export function normaliseManifest(manifest: Manifest, packageVersion?: string):
 		description: manifest.description,
 		keywords: manifest.keywords,
 		repo: manifest.repo,
+		requires: manifest.release?.requires,
 		artifacts: manifest.release?.artifacts,
 		// Schema validation already gates capability strings to the
 		// current vocabulary via a runtime check, so by the time we get
diff --git a/packages/plugin-cli/src/publish/api.ts b/packages/plugin-cli/src/publish/api.ts
index fd8d00fa4..cce29460e 100644
--- a/packages/plugin-cli/src/publish/api.ts
+++ b/packages/plugin-cli/src/publish/api.ts
@@ -187,6 +187,12 @@ export interface PublishOptions {
 	 * immutable per version, so this is not a first-publish-only field.
 	 */
 	repo?: string;
+	/**
+	 * Environment constraints for this release (`release.requires` in the
+	 * lexicon). Map of `env:*`/DID keys to semver ranges. Written to the
+	 * release record when non-empty; omitted otherwise.
+	 */
+	requires?: Record<string, string>;
 	/**
 	 * Resolved media artifacts (icon / screenshot / banner) for this release.
 	 * Already uploaded and measured by the caller. Written verbatim into the
@@ -291,6 +297,8 @@ interface PackageReleaseRecordShape {
 	};
 	/** Source-repository URL (`release.repo`). Omitted when not provided. */
 	repo?: string;
+	/** Environment constraints (`release.requires`). Omitted when empty. */
+	requires?: Record<string, string>;
 	/**
 	 * Open-union extension container, keyed by NSID. Releases of type
 	 * `emdash-plugin` MUST include a `releaseExtension` entry carrying the
@@ -446,6 +454,9 @@ export async function publishRelease(options: PublishOptions): Promise<PublishRe
 	if (options.repo !== undefined) {
 		releaseRecord.repo = options.repo;
 	}
+	if (options.requires !== undefined && Object.keys(options.requires).length > 0) {
+		releaseRecord.requires = options.requires;
+	}
 	applyArtifacts(releaseRecord, options.artifacts);
 
 	type WriteOp =
diff --git a/packages/plugin-cli/tests/manifest-schema.test.ts b/packages/plugin-cli/tests/manifest-schema.test.ts
index c0e8ad78e..2237244c8 100644
--- a/packages/plugin-cli/tests/manifest-schema.test.ts
+++ b/packages/plugin-cli/tests/manifest-schema.test.ts
@@ -21,6 +21,7 @@ import {
 	LicenseSchema,
 	ManifestSchema,
 	RepoSchema,
+	RequiresSchema,
 	SecurityContactSchema,
 } from "../src/manifest/schema.js";
 
@@ -123,6 +124,42 @@ describe("RepoSchema", () => {
 	});
 });
 
+describe("RequiresSchema", () => {
+	it("accepts env:* keys with semver-range values", () => {
+		expect(RequiresSchema.parse({ "env:emdash": ">=1.0.0", "env:astro": ">=4.16" })).toEqual({
+			"env:emdash": ">=1.0.0",
+			"env:astro": ">=4.16",
+		});
+	});
+
+	it("accepts caret, tilde, and AND-set ranges", () => {
+		expect(
+			RequiresSchema.parse({
+				"env:astro": "^4.0.0",
+				"env:emdash": ">=1.0.0 <2.0.0",
+			}),
+		).toBeTruthy();
+		expect(RequiresSchema.parse({ "env:astro": "~4.16.0" })).toBeTruthy();
+	});
+
+	it("accepts forward-compat DID-shaped keys", () => {
+		expect(RequiresSchema.parse({ "did:plc:abc123": "^1.0.0" })).toEqual({
+			"did:plc:abc123": "^1.0.0",
+		});
+	});
+
+	it("rejects keys that are neither env:* nor DID-shaped", () => {
+		expect(RequiresSchema.safeParse({ astro: ">=4.16" }).success).toBe(false);
+		expect(RequiresSchema.safeParse({ "env:": ">=4.16" }).success).toBe(false);
+	});
+
+	it("rejects values that aren't valid semver ranges", () => {
+		expect(RequiresSchema.safeParse({ "env:astro": "not-a-range" }).success).toBe(false);
+		expect(RequiresSchema.safeParse({ "env:astro": "" }).success).toBe(false);
+		expect(RequiresSchema.safeParse({ "env:astro": ">=" }).success).toBe(false);
+	});
+});
+
 describe("ArtifactFileSchema", () => {
 	it("accepts a bare file ref", () => {
 		expect(ArtifactFileSchema.safeParse({ file: "./icon.png" }).success).toBe(true);
@@ -339,9 +376,26 @@ describe("ManifestSchema (full document)", () => {
 			description: "Image gallery block for EmDash.",
 			keywords: ["gallery", "images", "media"],
 			repo: "https://github.com/emdash-cms/plugin-gallery",
+			release: { requires: { "env:emdash": ">=1.0.0", "env:astro": ">=4.16" } },
 			capabilities: ["content:read"],
 			storage: { events: { indexes: ["timestamp"] } },
 		});
 		expect(result.success).toBe(true);
 	});
+
+	it("accepts a manifest with release-level requires", () => {
+		const result = ManifestSchema.safeParse({
+			...minimal,
+			release: { requires: { "env:astro": ">=4.16" } },
+		});
+		expect(result.success).toBe(true);
+	});
+
+	it("rejects a manifest with an invalid requires range", () => {
+		const result = ManifestSchema.safeParse({
+			...minimal,
+			release: { requires: { "env:astro": "not-a-range" } },
+		});
+		expect(result.success).toBe(false);
+	});
 });
diff --git a/packages/plugin-cli/tests/manifest-translate.test.ts b/packages/plugin-cli/tests/manifest-translate.test.ts
index 3aa80f289..501d3332b 100644
--- a/packages/plugin-cli/tests/manifest-translate.test.ts
+++ b/packages/plugin-cli/tests/manifest-translate.test.ts
@@ -94,6 +94,27 @@ describe("normaliseManifest", () => {
 		).toThrow(/disagrees/);
 	});
 
+	it("passes release-level requires through unchanged", () => {
+		const normalised = normaliseManifest({
+			version: "0.1.0",
+			license: "MIT",
+			author: { name: "Jane" },
+			security: { email: "s@example.com" },
+			release: { requires: { "env:emdash": ">=1.0.0", "env:astro": ">=4.16" } },
+		});
+		expect(normalised.requires).toEqual({ "env:emdash": ">=1.0.0", "env:astro": ">=4.16" });
+	});
+
+	it("leaves requires undefined when the manifest omits it", () => {
+		const normalised = normaliseManifest({
+			version: "0.1.0",
+			license: "MIT",
+			author: { name: "Jane" },
+			security: { email: "s@example.com" },
+		});
+		expect(normalised.requires).toBeUndefined();
+	});
+
 	it("throws when no version is available anywhere", () => {
 		expect(() =>
 			normaliseManifest({
@@ -118,6 +139,7 @@ describe("manifestToProfileBootstrap", () => {
 			description: "desc",
 			keywords: ["k"],
 			repo: "https://github.com/example/p",
+			requires: undefined,
 			capabilities: [],
 			allowedHosts: [],
 			storage: {},
@@ -142,6 +164,7 @@ describe("manifestToProfileBootstrap", () => {
 			description: undefined,
 			keywords: undefined,
 			repo: undefined,
+			requires: undefined,
 			capabilities: [],
 			allowedHosts: [],
 			storage: {},
@@ -168,6 +191,7 @@ describe("manifestToProfileInput", () => {
 			description: "desc",
 			keywords: ["k1", "k2"],
 			repo: "https://github.com/example/p",
+			requires: { "env:astro": ">=4.16" },
 			capabilities: [],
 			allowedHosts: [],
 			storage: {},
@@ -186,6 +210,8 @@ describe("manifestToProfileInput", () => {
 		expect(input.name).toBe("Test");
 		expect(input.description).toBe("desc");
 		expect(input.keywords).toEqual(["k1", "k2"]);
+		// requires is release-level, never folded into the profile input.
+		expect("requires" in input).toBe(false);
 	});
 
 	it("omits name, description and keywords when the manifest doesn't set them", () => {
@@ -200,6 +226,7 @@ describe("manifestToProfileInput", () => {
 			description: undefined,
 			keywords: undefined,
 			repo: undefined,
+			requires: undefined,
 			capabilities: [],
 			allowedHosts: [],
 			storage: {},
diff --git a/packages/plugin-cli/tests/publish.test.ts b/packages/plugin-cli/tests/publish.test.ts
index 044dccd3b..1ee4eac8e 100644
--- a/packages/plugin-cli/tests/publish.test.ts
+++ b/packages/plugin-cli/tests/publish.test.ts
@@ -142,6 +142,28 @@ describe("publishRelease", () => {
 			expect(value.artifacts.package.contentType).toBe("application/gzip");
 		});
 
+		it("writes release-level requires into the release record when provided", async () => {
+			const pds = new MockPds({ did: TEST_DID });
+			await publishRelease(
+				buildOptions(pds, {
+					requires: { "env:emdash": ">=1.0.0", "env:astro": ">=4.16" },
+				}),
+			);
+
+			const release = pds.records.get(`at://${TEST_DID}/${NSID.packageRelease}/test-plugin:1.0.0`);
+			const value = release!.value as { requires?: Record<string, string> };
+			expect(value.requires).toEqual({ "env:emdash": ">=1.0.0", "env:astro": ">=4.16" });
+		});
+
+		it("omits requires from the release record when empty or absent", async () => {
+			const pds = new MockPds({ did: TEST_DID });
+			await publishRelease(buildOptions(pds, { requires: {} }));
+
+			const release = pds.records.get(`at://${TEST_DID}/${NSID.packageRelease}/test-plugin:1.0.0`);
+			const value = release!.value as Record<string, unknown>;
+			expect("requires" in value).toBe(false);
+		});
+
 		it("hard-fails when license is missing, with no records written", async () => {
 			const pds = new MockPds({ did: TEST_DID });
 			const opts = buildOptions(pds, {
diff --git a/packages/registry-client/package.json b/packages/registry-client/package.json
index a618bac31..c7d98663d 100644
--- a/packages/registry-client/package.json
+++ b/packages/registry-client/package.json
@@ -20,6 +20,10 @@
 		"./discovery": {
 			"types": "./dist/discovery/index.d.ts",
 			"default": "./dist/discovery/index.js"
+		},
+		"./env": {
+			"types": "./dist/env/index.d.ts",
+			"default": "./dist/env/index.js"
 		}
 	},
 	"files": [
@@ -37,11 +41,13 @@
 		"@atcute/atproto": "catalog:",
 		"@atcute/client": "catalog:",
 		"@atcute/lexicons": "catalog:",
-		"@emdash-cms/registry-lexicons": "workspace:*"
+		"@emdash-cms/registry-lexicons": "workspace:*",
+		"semver": "catalog:"
 	},
 	"devDependencies": {
 		"@arethetypeswrong/cli": "catalog:",
 		"@types/node": "catalog:",
+		"@types/semver": "catalog:",
 		"publint": "catalog:",
 		"tsdown": "catalog:",
 		"typescript": "catalog:",
diff --git a/packages/registry-client/src/env/index.ts b/packages/registry-client/src/env/index.ts
new file mode 100644
index 000000000..10c978cdf
--- /dev/null
+++ b/packages/registry-client/src/env/index.ts
@@ -0,0 +1,166 @@
+/**
+ * Environment compatibility for release `requires` constraints.
+ *
+ * A release record's `requires` block is a map of `env:*` keys (host
+ * environment requirements like `env:emdash`, `env:astro`) or package DIDs to
+ * semver-range constraint strings. The lexicon types it as `unknown`; nothing
+ * upstream guarantees its shape, so {@link parseRequires} guards it before any
+ * consumer reads it.
+ *
+ * Range evaluation delegates to node-semver (`satisfies` / `validRange` /
+ * `valid`), so the full range grammar — comparator sets, caret, tilde, partial
+ * versions, wildcards, and `||` unions — and node-semver's prerelease gating
+ * apply. semver is pure JS, so this stays isomorphic across the CLI
+ * (publish-time validation), the server (install/update gate), and the admin
+ * (browser compat warning), all sharing one implementation.
+ */
+
+import { satisfies, valid, validRange } from "semver";
+
+export interface HostEnv {
+	/** Map of `env:*` key to the host's current version of that environment. */
+	[key: string]: string | undefined;
+}
+
+export interface EnvMismatch {
+	/** The `requires` key that was not satisfied (e.g. `env:astro`). */
+	key: string;
+	/** The required range string from the release record. */
+	required: string;
+	/** The host's version of that environment. */
+	host: string;
+}
+
+/** `env:<name>` keys, where `<name>` is one or more non-colon characters. */
+const ENV_KEY_RE = /^env:[^:]+$/;
+/** Structural DID shape: `did:<method>:<id>` (forward-compat for package deps). */
+const DID_KEY_RE = /^did:[a-z]+:.+$/;
+
+/**
+ * Build the host-environment map the install/update gate compares a release's
+ * `requires` against, from the EmDash and Astro versions the host advertises.
+ *
+ * An environment whose version is unknown is omitted so the gate skips it
+ * rather than blocking on a version it can't evaluate: an uncompiled build
+ * reporting `"dev"` for EmDash, or an unresolved Astro version. Shared by the
+ * server install/update gate and the admin's client-side compat warning so the
+ * dev-skip / astro-omit rule lives in exactly one place.
+ */
+export function hostEnvFromVersions(
+	emdashVersion: string | undefined,
+	astroVersion: string | undefined,
+): HostEnv {
+	const host: HostEnv = {};
+	if (emdashVersion && emdashVersion !== "dev") host["env:emdash"] = emdashVersion;
+	if (astroVersion) host["env:astro"] = astroVersion;
+	return host;
+}
+
+/**
+ * Guard the lexicon-`unknown` `requires` value into a string-valued record of
+ * recognised keys. Drops any entry whose key is not `env:*`/DID-shaped or whose
+ * value is not a string. Never throws.
+ */
+export function parseRequires(value: unknown): Record<string, string> {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return {};
+	const out: Record<string, string> = {};
+	for (const [key, raw] of Object.entries(value)) {
+		if (typeof raw !== "string") continue;
+		if (!ENV_KEY_RE.test(key) && !DID_KEY_RE.test(key)) continue;
+		out[key] = raw;
+	}
+	return out;
+}
+
+/**
+ * True when `range` is a syntactically valid version range we can evaluate.
+ *
+ * The empty string is rejected: node-semver normalises it to `*` (match any),
+ * which is never what a publisher means when they write a constraint.
+ */
+export function isValidVersionRange(range: string): boolean {
+	if (range.trim() === "") return false;
+	return validRange(range) !== null;
+}
+
+/**
+ * True when `version` satisfies `range`.
+ *
+ * Fails open (returns `true`) when either input is unparseable: an unparseable
+ * host version cannot be proven incompatible, and an unparseable range is
+ * garbage we decline to enforce. Both cases are non-blocking by design — the
+ * gate only refuses on a definite mismatch.
+ *
+ * `includePrerelease` evaluates a prerelease host version (a beta EmDash/Astro
+ * build) by its precedence rather than excluding it from release-only ranges.
+ * Without it, node-semver would refuse `1.0.0-rc.1` against `*` or `>=0.13.0`,
+ * blocking a prerelease host that is not a definite mismatch.
+ */
+export function satisfiesRange(version: string, range: string): boolean {
+	if (valid(version) === null) return true;
+	if (validRange(range) === null) return true;
+	return satisfies(version, range, { includePrerelease: true });
+}
+
+/**
+ * Compare a release's `requires` against the host environment and return the
+ * env keys whose host version does not satisfy the required range.
+ *
+ * Entries the host doesn't advertise (no known version for that key) are
+ * skipped — we can't evaluate a constraint against an environment we don't
+ * know we're running in. The `requires` argument is the raw lexicon-`unknown`
+ * value; it is guarded internally.
+ */
+export function checkEnvCompatibility(requires: unknown, host: HostEnv): EnvMismatch[] {
+	const parsed = parseRequires(requires);
+	const mismatches: EnvMismatch[] = [];
+	for (const [key, range] of Object.entries(parsed)) {
+		const hostVersion = host[key];
+		if (hostVersion === undefined) continue;
+		if (!satisfiesRange(hostVersion, range)) {
+			mismatches.push({ key, required: range, host: hostVersion });
+		}
+	}
+	return mismatches;
+}
+
+/** An `env:*` constraint that could not be enforced against the host. */
+export interface SkippedEnvConstraint {
+	/** The `env:*` key whose constraint was skipped. */
+	key: string;
+	/** The required range string from the release record. */
+	required: string;
+	/**
+	 * `"unknown"`: the host advertises no version for this env.
+	 * `"unparseable"`: the host version exists but isn't valid semver.
+	 */
+	reason: "unknown" | "unparseable";
+}
+
+/**
+ * Find the `env:*` constraints in `requires` that {@link checkEnvCompatibility}
+ * silently skips because the host can't evaluate them: the host advertises no
+ * version for that env, or advertises one that isn't parseable semver. These
+ * are the cases where a hard gate degrades to a no-op, so the server can log
+ * them rather than bypass silently.
+ *
+ * DID-keyed constraints are excluded — those are forward-compat package deps,
+ * not host environments, and their absence from the host map is expected.
+ */
+export function findSkippedEnvConstraints(
+	requires: unknown,
+	host: HostEnv,
+): SkippedEnvConstraint[] {
+	const parsed = parseRequires(requires);
+	const skipped: SkippedEnvConstraint[] = [];
+	for (const [key, range] of Object.entries(parsed)) {
+		if (!ENV_KEY_RE.test(key)) continue;
+		const hostVersion = host[key];
+		if (hostVersion === undefined) {
+			skipped.push({ key, required: range, reason: "unknown" });
+		} else if (valid(hostVersion) === null) {
+			skipped.push({ key, required: range, reason: "unparseable" });
+		}
+	}
+	return skipped;
+}
diff --git a/packages/registry-client/src/index.ts b/packages/registry-client/src/index.ts
index 365afe71d..680adcc2d 100644
--- a/packages/registry-client/src/index.ts
+++ b/packages/registry-client/src/index.ts
@@ -44,3 +44,15 @@ export {
 export { type PublishingClientFromHandlerOptions, PublishingClient } from "./publishing/index.js";
 
 export { type DiscoveryClientOptions, DiscoveryClient } from "./discovery/index.js";
+
+export {
+	type EnvMismatch,
+	type HostEnv,
+	type SkippedEnvConstraint,
+	checkEnvCompatibility,
+	findSkippedEnvConstraints,
+	hostEnvFromVersions,
+	isValidVersionRange,
+	parseRequires,
+	satisfiesRange,
+} from "./env/index.js";
diff --git a/packages/registry-client/tests/env.test.ts b/packages/registry-client/tests/env.test.ts
new file mode 100644
index 000000000..287ec04a3
--- /dev/null
+++ b/packages/registry-client/tests/env.test.ts
@@ -0,0 +1,227 @@
+import { describe, expect, it } from "vitest";
+
+import {
+	checkEnvCompatibility,
+	findSkippedEnvConstraints,
+	hostEnvFromVersions,
+	isValidVersionRange,
+	parseRequires,
+	satisfiesRange,
+} from "../src/env/index.js";
+
+describe("isValidVersionRange", () => {
+	it("accepts comparator ranges", () => {
+		expect(isValidVersionRange(">=4.16")).toBe(true);
+		expect(isValidVersionRange(">=4.16.0")).toBe(true);
+		expect(isValidVersionRange(">4.0.0")).toBe(true);
+		expect(isValidVersionRange("<=2.0.0")).toBe(true);
+		expect(isValidVersionRange("<2.0.0")).toBe(true);
+		expect(isValidVersionRange("=1.2.3")).toBe(true);
+		expect(isValidVersionRange("1.2.3")).toBe(true);
+	});
+
+	it("accepts caret and tilde ranges", () => {
+		expect(isValidVersionRange("^4.0.0")).toBe(true);
+		expect(isValidVersionRange("^4.16")).toBe(true);
+		expect(isValidVersionRange("~4.16.0")).toBe(true);
+		expect(isValidVersionRange("~4")).toBe(true);
+	});
+
+	it("accepts wildcard and any", () => {
+		expect(isValidVersionRange("*")).toBe(true);
+		expect(isValidVersionRange("4.x")).toBe(true);
+		expect(isValidVersionRange("4.16.x")).toBe(true);
+	});
+
+	it("accepts AND-joined comparator sets", () => {
+		expect(isValidVersionRange(">=4.16.0 <5.0.0")).toBe(true);
+	});
+
+	it("accepts || union ranges", () => {
+		expect(isValidVersionRange("^4.0.0 || ^5.0.0")).toBe(true);
+	});
+
+	it("accepts prerelease versions in comparators", () => {
+		expect(isValidVersionRange(">=6.0.0-beta.0")).toBe(true);
+	});
+
+	it("rejects empty and garbage", () => {
+		expect(isValidVersionRange("")).toBe(false);
+		expect(isValidVersionRange("   ")).toBe(false);
+		expect(isValidVersionRange("not-a-range")).toBe(false);
+		expect(isValidVersionRange(">=")).toBe(false);
+		expect(isValidVersionRange("4.16.0.0")).toBe(false);
+		expect(isValidVersionRange(">>4.0.0")).toBe(false);
+	});
+});
+
+describe("satisfiesRange", () => {
+	it("evaluates comparator ranges", () => {
+		expect(satisfiesRange("4.16.0", ">=4.16")).toBe(true);
+		expect(satisfiesRange("4.16.1", ">=4.16.0")).toBe(true);
+		expect(satisfiesRange("4.12.0", ">=4.16")).toBe(false);
+		expect(satisfiesRange("4.16.0", ">4.16.0")).toBe(false);
+		expect(satisfiesRange("4.16.1", ">4.16.0")).toBe(true);
+	});
+
+	it("evaluates caret ranges", () => {
+		expect(satisfiesRange("4.16.0", "^4.0.0")).toBe(true);
+		expect(satisfiesRange("4.99.0", "^4.0.0")).toBe(true);
+		expect(satisfiesRange("5.0.0", "^4.0.0")).toBe(false);
+		expect(satisfiesRange("3.9.0", "^4.0.0")).toBe(false);
+	});
+
+	it("evaluates tilde ranges", () => {
+		expect(satisfiesRange("4.16.5", "~4.16.0")).toBe(true);
+		expect(satisfiesRange("4.17.0", "~4.16.0")).toBe(false);
+	});
+
+	it("evaluates AND-joined comparator sets", () => {
+		expect(satisfiesRange("4.16.0", ">=4.16.0 <5.0.0")).toBe(true);
+		expect(satisfiesRange("5.0.0", ">=4.16.0 <5.0.0")).toBe(false);
+	});
+
+	it("matches the wildcard against any version", () => {
+		expect(satisfiesRange("4.16.0", "*")).toBe(true);
+		expect(satisfiesRange("1.0.0-rc.1", "*")).toBe(true);
+	});
+
+	it("evaluates || union ranges", () => {
+		expect(satisfiesRange("5.1.0", "^4.0.0 || ^5.0.0")).toBe(true);
+		expect(satisfiesRange("3.0.0", "^4.0.0 || ^5.0.0")).toBe(false);
+	});
+
+	it("evaluates a prerelease host by precedence, not excluded from release ranges", () => {
+		expect(satisfiesRange("1.0.0-rc.1", ">=0.13.0")).toBe(true);
+		expect(satisfiesRange("4.1.0-beta.2", "^4.0.0")).toBe(true);
+	});
+
+	it("treats an unparseable host version as satisfied (cannot prove incompatible)", () => {
+		expect(satisfiesRange("dev", ">=4.16")).toBe(true);
+		expect(satisfiesRange("", ">=4.16")).toBe(true);
+	});
+
+	it("treats an unparseable range as satisfied (cannot enforce garbage)", () => {
+		expect(satisfiesRange("4.16.0", "not-a-range")).toBe(true);
+	});
+});
+
+describe("parseRequires", () => {
+	it("returns env:* and DID keys with string values", () => {
+		const parsed = parseRequires({
+			"env:emdash": ">=1.0.0",
+			"env:astro": ">=4.16",
+			"did:plc:abc123": "^1.0.0",
+		});
+		expect(parsed).toEqual({
+			"env:emdash": ">=1.0.0",
+			"env:astro": ">=4.16",
+			"did:plc:abc123": "^1.0.0",
+		});
+	});
+
+	it("drops non-string values", () => {
+		expect(parseRequires({ "env:astro": 4 })).toEqual({});
+		expect(parseRequires({ "env:astro": { foo: "bar" } })).toEqual({});
+	});
+
+	it("drops keys that are not env:* or DID-shaped", () => {
+		expect(parseRequires({ astro: ">=4.16", "env:": ">=1", foo: ">=1" })).toEqual({});
+	});
+
+	it("returns an empty object for non-object input", () => {
+		expect(parseRequires(undefined)).toEqual({});
+		expect(parseRequires(null)).toEqual({});
+		expect(parseRequires("garbage")).toEqual({});
+		expect(parseRequires(42)).toEqual({});
+		expect(parseRequires([])).toEqual({});
+	});
+});
+
+describe("checkEnvCompatibility", () => {
+	it("returns no mismatches when every constraint is satisfied", () => {
+		const result = checkEnvCompatibility(
+			{ "env:emdash": ">=1.0.0", "env:astro": ">=4.16" },
+			{ "env:emdash": "1.2.0", "env:astro": "4.16.0" },
+		);
+		expect(result).toEqual([]);
+	});
+
+	it("reports the env keys whose host version does not satisfy the range", () => {
+		const result = checkEnvCompatibility(
+			{ "env:emdash": ">=1.0.0", "env:astro": ">=4.16" },
+			{ "env:emdash": "1.2.0", "env:astro": "4.12.0" },
+		);
+		expect(result).toEqual([{ key: "env:astro", required: ">=4.16", host: "4.12.0" }]);
+	});
+
+	it("skips env keys the host does not advertise (no known version)", () => {
+		const result = checkEnvCompatibility(
+			{ "did:plc:abc": "^1.0.0" },
+			{ "env:emdash": "1.2.0", "env:astro": "4.16.0" },
+		);
+		expect(result).toEqual([]);
+	});
+
+	it("guards unknown requires shapes without crashing", () => {
+		expect(checkEnvCompatibility(undefined, { "env:emdash": "1.2.0" })).toEqual([]);
+		expect(checkEnvCompatibility("garbage", { "env:emdash": "1.2.0" })).toEqual([]);
+		expect(checkEnvCompatibility({ "env:astro": 999 }, { "env:astro": "4.16.0" })).toEqual([]);
+	});
+
+	it("skips host envs whose version is unknown/unparseable", () => {
+		const result = checkEnvCompatibility({ "env:emdash": ">=1.0.0" }, { "env:emdash": "dev" });
+		expect(result).toEqual([]);
+	});
+});
+
+describe("findSkippedEnvConstraints", () => {
+	it("returns nothing when every env constraint is evaluable", () => {
+		expect(
+			findSkippedEnvConstraints(
+				{ "env:emdash": ">=1.0.0", "env:astro": ">=4.0.0" },
+				{ "env:emdash": "1.2.0", "env:astro": "4.16.0" },
+			),
+		).toEqual([]);
+	});
+
+	it("flags an env the host does not advertise as unknown", () => {
+		expect(findSkippedEnvConstraints({ "env:astro": ">=4.16" }, { "env:emdash": "1.2.0" })).toEqual(
+			[{ key: "env:astro", required: ">=4.16", reason: "unknown" }],
+		);
+	});
+
+	it("flags an env whose host version is not parseable semver", () => {
+		expect(findSkippedEnvConstraints({ "env:emdash": ">=1.0.0" }, { "env:emdash": "dev" })).toEqual(
+			[{ key: "env:emdash", required: ">=1.0.0", reason: "unparseable" }],
+		);
+	});
+
+	it("ignores DID-keyed constraints (package deps, not host envs)", () => {
+		expect(findSkippedEnvConstraints({ "did:plc:abc": "^1.0.0" }, {})).toEqual([]);
+	});
+
+	it("does not crash on a garbage requires shape", () => {
+		expect(findSkippedEnvConstraints("garbage", {})).toEqual([]);
+		expect(findSkippedEnvConstraints(null, {})).toEqual([]);
+	});
+});
+
+describe("hostEnvFromVersions", () => {
+	it("maps emdash + astro versions to env:* keys", () => {
+		expect(hostEnvFromVersions("1.2.0", "4.16.0")).toEqual({
+			"env:emdash": "1.2.0",
+			"env:astro": "4.16.0",
+		});
+	});
+
+	it("omits a dev emdash build so the gate skips it", () => {
+		expect(hostEnvFromVersions("dev", "4.16.0")).toEqual({ "env:astro": "4.16.0" });
+	});
+
+	it("omits each env whose version is unknown", () => {
+		expect(hostEnvFromVersions("1.2.0", undefined)).toEqual({ "env:emdash": "1.2.0" });
+		expect(hostEnvFromVersions(undefined, "4.16.0")).toEqual({ "env:astro": "4.16.0" });
+		expect(hostEnvFromVersions(undefined, undefined)).toEqual({});
+	});
+});
diff --git a/packages/registry-client/tsdown.config.ts b/packages/registry-client/tsdown.config.ts
index 6d7423e90..35689997a 100644
--- a/packages/registry-client/tsdown.config.ts
+++ b/packages/registry-client/tsdown.config.ts
@@ -5,6 +5,7 @@ export default defineConfig({
 		"src/index.ts",
 		"src/credentials/index.ts",
 		"src/discovery/index.ts",
+		"src/env/index.ts",
 		"src/publishing/index.ts",
 	],
 	format: ["esm"],
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d5cb3fcfd..8c60fa566 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -207,6 +207,9 @@ catalogs:
     '@types/react-dom':
       specifier: 19.2.3
       version: 19.2.3
+    '@types/semver':
+      specifier: ^7.5.8
+      version: 7.7.1
     astro:
       specifier: ^6.3.0
       version: 6.3.5
@@ -237,6 +240,9 @@ catalogs:
     react-dom:
       specifier: 19.2.4
       version: 19.2.4
+    semver:
+      specifier: ^7.6.3
+      version: 7.7.4
     tsdown:
       specifier: 0.20.3
       version: 0.20.3
@@ -2008,6 +2014,9 @@ importers:
       '@emdash-cms/registry-lexicons':
         specifier: workspace:*
         version: link:../registry-lexicons
+      semver:
+        specifier: 'catalog:'
+        version: 7.7.4
     devDependencies:
       '@arethetypeswrong/cli':
         specifier: 'catalog:'
@@ -2015,6 +2024,9 @@ importers:
       '@types/node':
         specifier: 'catalog:'
         version: 24.10.13
+      '@types/semver':
+        specifier: 'catalog:'
+        version: 7.7.1
       publint:
         specifier: 'catalog:'
         version: 0.3.17
@@ -6779,6 +6791,9 @@ packages:
   '@types/sax@1.2.7':
     resolution: {integrity: sha512-rO73L89PJxeYM3s3pPPjiPgVVcymqU490g0YO5n5By0k2Erzj6tay/4lr1CHAAU4JyOWd1rpQ8bCf6cZfHU96A==}
 
+  '@types/semver@7.7.1':
+    resolution: {integrity: sha512-FmgJfu+MOcQ370SD0ev7EI8TlCAfKYU+B4m5T3yXc1CiRN94g/SZPtsCkk506aUDtlMnFZvasDwHHUcZUEaYuA==}
+
   '@types/trusted-types@2.0.7':
     resolution: {integrity: sha512-ScaPdn1dQczgbl0QFTeTOmVHFULt394XJgOQNoyVhZ6r2vLnMLJfBPd53SB52T/3G36VI1/g2MZaX0cwDuXsfw==}
 
@@ -16452,6 +16467,8 @@ snapshots:
     dependencies:
       '@types/node': 24.10.13
 
+  '@types/semver@7.7.1': {}
+
   '@types/trusted-types@2.0.7':
     optional: true
 
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index d58411f9d..cb196cc30 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -132,6 +132,7 @@ catalog:
   "@types/better-sqlite3": ^7.6.12
   "@types/react": 19.2.14
   "@types/react-dom": 19.2.3
+  "@types/semver": ^7.5.8
   astro: ^6.3.0
   astro-iconset: ^0.0.4
   better-sqlite3: ^12.8.0
@@ -142,6 +143,7 @@ catalog:
   publint: 0.3.17
   react: 19.2.4
   react-dom: 19.2.4
+  semver: ^7.6.3
   tsdown: 0.20.3
   typescript: ^6.0.3
   vite: ^8.0.11