AGENTS.md

@@ -93,15 +93,19 @@ them. Revisit only if the stated reason stops holding.
   gates on one operation, so it gates on a permission, and a bundle is just a group with several
   grants (groups nest). Ory's own "permission" (the `Resource` `permits`: view/edit/delete) is the
   separate per-row tier.
-- **Tightening a discovery rule breaks every already-copied plugin, and CI cannot see it.** `plugins/`
+- **A stricter manifest rule breaks already-copied plugins, and while `HOST_API_VERSION` is frozen the
-  is an operator-owned drop-in mount that ships empty, so every test — unit and e2e — only ever sees a
+  failure names a symptom rather than the cause.** `plugins/` is an operator-owned drop-in mount that
-  *fresh* copy of `examples/`. An operator's copy is whatever version they took. When a manifest rule
+  ships empty, so no test ever sees a *stale* copy — an operator's is whatever version they took. On
-  gets stricter, it must ship with a README → Upgrading entry and a re-copy instruction, and the
+  2026-08-05 the `<resource>:<action>` rule stopped a pre-existing `plugins/admin` at boot with
-  discovery error carries a line saying so. Learned the hard way twice on 2026-08-05: the
+  "route gates on admin", which reads as the operator's bug rather than an out-of-date copy.
-  `<resource>:<action>` rule bricked a pre-existing `plugins/admin` at boot, and the matching
+  **Accepted during development** (maintainer, 2026-08-05): `checkApiVersion` is already the right
-  `ADMIN_PERMISSIONS` check bricked it on a value that had been the shipped default. Fail-loud stays
+  mechanism — a breaking manifest change bumps the major and a stale plugin is refused by *version*,
-  right — the alternative is a route gating on a name nobody can be granted, i.e. a permanent silent
+  which says plainly what happened. That only starts working once the freeze lifts, so until then a
-  403 — but "loud" has to include the remedy.
+  stricter rule ships with a README → Upgrading entry and the discovery error carries the re-copy
+  hint. **Valid while `HOST_API_VERSION` stays frozen at 1.0.0** — when the first external plugin
+  lifts it (see the Rules section), the version check takes over and this note can go.
+  Fail-loud stays right either way: the alternative is a route gating on a name nobody can be
+  granted, i.e. a permanent silent 403.
 - **A permission name is always `<resource>:<action>`** — `scheduling:read`, `users:write`. A bare
   word names *who someone is* — a role — and roles are groups here; the old catch-all `admin`
   permission was exactly that mistake, split into `users:`/`groups:`/`permissions:`/`oauth2-clients:`

README.md

@@ -1756,6 +1756,11 @@ docker compose up -d --build
 Do the same for any other folder you copied out of `examples/`. A plugin you wrote yourself needs the
 manifest change the error names — the same rules the shipped examples follow.
 
+Once [`HOST_API_VERSION`](#contract-versioning) starts moving, you won't have to read the rule to know
+why: a breaking manifest change bumps the major, and a plugin built against an older host is refused
+by **version**, naming both. The version is frozen at `1.0.0` until the first external plugin exists,
+so for now the error names the rule it tripped instead.
+
 ### Breaking changes
 
 - **Permission names must be `<resource>:<action>`** (2026-08-05). A manifest gating on — or