[CTX-0078] docs(hygiene): remove research citations, add reference spine section, date evidence

sdk/plugin-api-v1-lua-surface-rfc.md

@@ -28,11 +28,13 @@ candidate spellings recorded in the corpus:
 | Candidate                                                        | Recorded in                                                                                                              |
 | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
 | `bitty.commands.*`, `bitty.events.*`, `bitty.ui.*` namespaces    | [Plugin Platform RFC host namespaces](../specifications/plugin-platform-rfc.md) (explicitly illustrative)                |
-| `bitty.api.register_panel/on_event/get_terminal_state`           | `bitty-docs` finding `FIND-0003` `ECO-SDK-01` (recorded in the shared checkout; not yet on `origin/main`)                |
-| `register_panel/on_event/get_terminal_state` (R-SDK-1 gate list) | `bitty` CarryCtx note `PX-1199` (CTX-0221 first-plugin-batch plan, planning only)                                        |
+| `bitty.api.register_panel/on_event/get_terminal_state`           | Draft-review note only; no accepted contract behind this spelling                                                        |
+| `register_panel/on_event/get_terminal_state` (R-SDK-1 gate list) | First-plugin-batch plan (planning only; no accepted contract)                                                            |
 | `bitty.services:get(...)` colon-style methods                    | [Plugin Reuse and Provider Ecology RFC](../packaging/plugin-reuse-and-providers.md) (Draft, post-1.0 provider follow-up) |
 
-Evidence revisions inspected read-only during drafting: `bitty` `1ea2f66`
+Evidence revisions below are drafting-time evidence inspected read-only
+before the 2026-09-11 ratification, not live verification pointers:
+`bitty` `1ea2f66`
 (local checkout; `bitty-plugin-host` and `bitty-lua` sources; the workspace was
 behind `origin/main` at inspection time), `bitty-plugin-sdk` main at `0fbefe7`
 (manifest/lint, mock host, and conformance merged via CTX-0032/#57,
@@ -652,11 +654,9 @@ dispositions are:
   [ADR 0006](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/decisions/adrs/ADR-0006-os-env-policy.md),
   [ADR 0007](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/decisions/adrs/ADR-0007-async-gc.md) — accepted runtime,
   environment, and async contracts.
-- `FIND-0003` `ECO-SDK-01` (bitty-docs finding recorded in the shared
-  checkout; not yet committed to `origin/main` at draft time) — candidate
-  spelling and SDK readiness gap.
 - `bitty` `1ea2f66` — `crates/bitty-plugin-host/src/event.rs` (closed
   `EventKind`/`EventPayload`), `registry.rs`, `host.rs`, `capability.rs`,
   `manifest.rs`; `crates/bitty-lua/src/lib.rs` (VM budgets, no host bridge).
-- `bitty-plugin-sdk` `0fbefe7` (main) — manifest/lint, mock host, and
+- `bitty-plugin-sdk` `0fbefe7` (main at draft time; drafting-time evidence,
+  not a live verification pointer) — manifest/lint, mock host, and
   conformance; merged CTX-0032/#57, CTX-0033/#58, CTX-0036/#60, evidence only.

sdk/reference/commands.md

@@ -133,6 +133,16 @@ would be illustrative, never verified.
   form and the activation registration is checked after canonicalization;
   mismatch fails activation with a `validation` diagnostic (RFC, LUA-OQ-3).
 
+## Compatibility and versioning
+
+Draft reference: this page states the candidate v1 spellings and carries no
+compatibility promise while its status is draft. The target contract is the
+[Compatibility policy](../plugin-api-v1-lua-surface-rfc.md#compatibility-policy)
+in the accepted Plugin API v1 Lua Surface RFC: the surface is stable within
+`1.x`, additions ship as minor versions, and removals or narrowings require a
+major version, gated by the manifest `compat.plugin-api` range against the
+runtime `bitty.api_version`.
+
 ## References
 
 - [Plugin API v1 Lua Surface RFC](../plugin-api-v1-lua-surface-rfc.md)

sdk/reference/env.md

@@ -164,6 +164,16 @@ granted-path claim beyond this denial shape is follow-up work.
 - Out of scope (no source): enumeration of keys, writes to the host
   environment, and any delivery, caching, or reload semantics.
 
+## Compatibility and versioning
+
+Draft reference: this page states the candidate v1 spellings and carries no
+compatibility promise while its status is draft. The target contract is the
+[Compatibility policy](../plugin-api-v1-lua-surface-rfc.md#compatibility-policy)
+in the accepted Plugin API v1 Lua Surface RFC: the surface is stable within
+`1.x`, additions ship as minor versions, and removals or narrowings require a
+major version, gated by the manifest `compat.plugin-api` range against the
+runtime `bitty.api_version`.
+
 ## References
 
 - [Plugin API v1 Lua Surface RFC](../plugin-api-v1-lua-surface-rfc.md)

sdk/reference/events.md

@@ -143,6 +143,16 @@ end)
   payload-less kinds (whose v1 shape declares no fields), which reject any
   key (RFC compatibility policy).
 
+## Compatibility and versioning
+
+Draft reference: this page states the candidate v1 spellings and carries no
+compatibility promise while its status is draft. The target contract is the
+[Compatibility policy](../plugin-api-v1-lua-surface-rfc.md#compatibility-policy)
+in the accepted Plugin API v1 Lua Surface RFC: the surface is stable within
+`1.x`, additions ship as minor versions, and removals or narrowings require a
+major version, gated by the manifest `compat.plugin-api` range against the
+runtime `bitty.api_version`.
+
 ## References
 
 - [Plugin API v1 Lua Surface RFC](../plugin-api-v1-lua-surface-rfc.md)

sdk/reference/keymaps.md

@@ -121,6 +121,16 @@ chord)` (RFC).
 - Suggestions are generation-scoped captures owned by `(PluginId,
 generation)` and disposed with it.
 
+## Compatibility and versioning
+
+Draft reference: this page states the candidate v1 spellings and carries no
+compatibility promise while its status is draft. The target contract is the
+[Compatibility policy](../plugin-api-v1-lua-surface-rfc.md#compatibility-policy)
+in the accepted Plugin API v1 Lua Surface RFC: the surface is stable within
+`1.x`, additions ship as minor versions, and removals or narrowings require a
+major version, gated by the manifest `compat.plugin-api` range against the
+runtime `bitty.api_version`.
+
 ## References
 
 - [Plugin API v1 Lua Surface RFC](../plugin-api-v1-lua-surface-rfc.md)

sdk/reference/notify.md

@@ -113,6 +113,16 @@ end
 - Granted-path delivery is pinned only by the `FakeServices` seam, not by a
   passing test; any delivery claim beyond acceptance is follow-up work.
 
+## Compatibility and versioning
+
+Draft reference: this page states the candidate v1 spellings and carries no
+compatibility promise while its status is draft. The target contract is the
+[Compatibility policy](../plugin-api-v1-lua-surface-rfc.md#compatibility-policy)
+in the accepted Plugin API v1 Lua Surface RFC: the surface is stable within
+`1.x`, additions ship as minor versions, and removals or narrowings require a
+major version, gated by the manifest `compat.plugin-api` range against the
+runtime `bitty.api_version`.
+
 ## References
 
 - [Plugin API v1 Lua Surface RFC](../plugin-api-v1-lua-surface-rfc.md)

sdk/reference/process.md

@@ -115,6 +115,16 @@ a wired host backend.
   directory, environment inheritance, streaming, signaling, and any
   normative v1 guarantee.
 
+## Compatibility and versioning
+
+Draft reference: this page states the candidate v1 spellings and carries no
+compatibility promise while its status is draft. The target contract is the
+[Compatibility policy](../plugin-api-v1-lua-surface-rfc.md#compatibility-policy)
+in the accepted Plugin API v1 Lua Surface RFC: the surface is stable within
+`1.x`, additions ship as minor versions, and removals or narrowings require a
+major version, gated by the manifest `compat.plugin-api` range against the
+runtime `bitty.api_version`.
+
 ## References
 
 - [Lua Reference Overview](overview.md) (error contract, capability gating,

sdk/reference/services.md

@@ -123,6 +123,16 @@ test exercises a wired backend.
 - Out of scope (no source): resolution ordering, caching, retry, timeouts,
   and any concrete interface names or schemas.
 
+## Compatibility and versioning
+
+Draft reference: this page states the candidate v1 spellings and carries no
+compatibility promise while its status is draft. The target contract is the
+[Compatibility policy](../plugin-api-v1-lua-surface-rfc.md#compatibility-policy)
+in the accepted Plugin API v1 Lua Surface RFC: the surface is stable within
+`1.x`, additions ship as minor versions, and removals or narrowings require a
+major version, gated by the manifest `compat.plugin-api` range against the
+runtime `bitty.api_version`.
+
 ## References
 
 - [Plugin API v1 Lua Surface RFC](../plugin-api-v1-lua-surface-rfc.md)

sdk/reference/settings.md

@@ -102,6 +102,16 @@ bitty.store.set("flag", retention)
 - Settings access never leaves the plugin's own namespace; cross-plugin or
   core settings reads are outside v1 (RFC).
 
+## Compatibility and versioning
+
+Draft reference: this page states the candidate v1 spellings and carries no
+compatibility promise while its status is draft. The target contract is the
+[Compatibility policy](../plugin-api-v1-lua-surface-rfc.md#compatibility-policy)
+in the accepted Plugin API v1 Lua Surface RFC: the surface is stable within
+`1.x`, additions ship as minor versions, and removals or narrowings require a
+major version, gated by the manifest `compat.plugin-api` range against the
+runtime `bitty.api_version`.
+
 ## References
 
 - [Plugin API v1 Lua Surface RFC](../plugin-api-v1-lua-surface-rfc.md)

sdk/reference/store.md

@@ -166,6 +166,16 @@ Further limits:
   module performs no I/O, and durability reduces to the host keeping the
   owning `PluginStore` alive across generations (`store.rs`).
 
+## Compatibility and versioning
+
+Draft reference: this page states the candidate v1 spellings and carries no
+compatibility promise while its status is draft. The target contract is the
+[Compatibility policy](../plugin-api-v1-lua-surface-rfc.md#compatibility-policy)
+in the accepted Plugin API v1 Lua Surface RFC: the surface is stable within
+`1.x`, additions ship as minor versions, and removals or narrowings require a
+major version, gated by the manifest `compat.plugin-api` range against the
+runtime `bitty.api_version`.
+
 ## References
 
 - [Plugin API v1 Lua Surface RFC](../plugin-api-v1-lua-surface-rfc.md)

sdk/reference/tasks-timers.md

@@ -145,6 +145,16 @@ Over-cap and handle-exhaustion behavior for both families is pinned by
 - Timer fire and task resumption deliver through the accepted event path,
   so the three-level queue budgets still apply (RFC).
 
+## Compatibility and versioning
+
+Draft reference: this page states the candidate v1 spellings and carries no
+compatibility promise while its status is draft. The target contract is the
+[Compatibility policy](../plugin-api-v1-lua-surface-rfc.md#compatibility-policy)
+in the accepted Plugin API v1 Lua Surface RFC: the surface is stable within
+`1.x`, additions ship as minor versions, and removals or narrowings require a
+major version, gated by the manifest `compat.plugin-api` range against the
+runtime `bitty.api_version`.
+
 ## References
 
 - [Plugin API v1 Lua Surface RFC](../plugin-api-v1-lua-surface-rfc.md)

sdk/reference/terminal.md

@@ -122,6 +122,16 @@ local snap = bitty.terminal.snapshot({ scope = "semantic" })
   rest on the `FakeServices` seam and the RFC shape, never on verified
   delivery.
 
+## Compatibility and versioning
+
+Draft reference: this page states the candidate v1 spellings and carries no
+compatibility promise while its status is draft. The target contract is the
+[Compatibility policy](../plugin-api-v1-lua-surface-rfc.md#compatibility-policy)
+in the accepted Plugin API v1 Lua Surface RFC: the surface is stable within
+`1.x`, additions ship as minor versions, and removals or narrowings require a
+major version, gated by the manifest `compat.plugin-api` range against the
+runtime `bitty.api_version`.
+
 ## References
 
 - [Plugin API v1 Lua Surface RFC](../plugin-api-v1-lua-surface-rfc.md)

sdk/reference/ui.md

@@ -223,6 +223,16 @@ UI slots require a matching claim declaration`
 - Out of scope (no source): focus behavior, panel routing, and any
   composer behavior beyond the internal scene-diff step.
 
+## Compatibility and versioning
+
+Draft reference: this page states the candidate v1 spellings and carries no
+compatibility promise while its status is draft. The target contract is the
+[Compatibility policy](../plugin-api-v1-lua-surface-rfc.md#compatibility-policy)
+in the accepted Plugin API v1 Lua Surface RFC: the surface is stable within
+`1.x`, additions ship as minor versions, and removals or narrowings require a
+major version, gated by the manifest `compat.plugin-api` range against the
+runtime `bitty.api_version`.
+
 ## References
 
 - [Plugin API v1 Lua Surface RFC](../plugin-api-v1-lua-surface-rfc.md)

specifications/manifest-capability-authority.md

@@ -33,8 +33,7 @@ sidebar_order: 19
 
 ## Purpose and scope
 
-The 2026-09-24 cross-contract review campaign
-(`research/review/2026-09-24/11-final-cross-contracts.md`) identified five
+Cross-contract review identified five
 grammar conflicts where SDK, host implementation, template, and canonical
 documentation disagreed:
 
@@ -501,7 +500,5 @@ following criteria are satisfied:
   capability model.
 - [Package Follow-up RFC](../packaging/package-followup-rfc.md): resolver
   constraint grammar and prerelease policy.
-- Cross-contract review campaign:
-  `research/review/2026-09-24/11-final-cross-contracts.md`, cluster CC-01.
 - Issues: bitty-plugins-docs #95 (parent contract decision), #96 (grammar
   publication).