docs: refine ecosystem and writing workflows

.claude/commands/commit.md

@@ -47,8 +47,8 @@ Inspect the complete commit message, PR title, and PR body before sending them.
 If the staged changes only touch internal agent/workflow files, do not push or
 create a PR unless the user explicitly asked to publish, PR, or merge them.
 Internal workflow files include `.claude/commands/`, `.claude/skills/`,
-`.codex/skills/`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and agent
-automation notes.
+`.codex/skills/`, `.cursor/rules/`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and
+agent automation notes.
 
 For those internal-only changes, prefer a local commit or local working-tree
 change and report the files changed. If the user explicitly asks to open or

.claude/skills/loop-review/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: loop-review
+description: "Run OpenIAP's complete latest-main-to-merge review loop: review-self, commit and PR, five-minute CodeRabbit and CI polling, fixes, verification, and clean-head merge."
+---
+
+# Loop Review (Claude Code)
+
+The canonical workflow lives in `.codex/skills/loop-review/SKILL.md`. Read that
+file first and follow it fully.
+
+Use Claude Code's matching skills or commands for each delegated phase:
+
+- `/review-self` for pre-PR stabilization and exact-head fallback review.
+- `/commit --all --pr` for commit, push, PR, labels, and preview.
+- `/review-pr <PR>` for review threads, CodeRabbit, CI polling, and cleanup.
+- `ScheduleWakeup` for every five-minute re-entry; never use a shell sleep loop.
+
+Do not merge until the canonical exact-head clean gate is satisfied.

.codex/skills/generate-doc/SKILL.md

@@ -59,10 +59,10 @@ Before adding a release card, inspect the newest entries and package tags.
   belong to the same release train, expand that card into the single
   consolidated release entry and advance its date and title. Do not create a
   second card for the package versions.
-- Structure a consolidated train in this order: a short `Common changes`
-  summary, hosted IAPKit changes, versioned native and framework changes grouped
-  by package, migration or integration notes, and `Package Releases` at the
-  bottom (see the exact card layout in Editing Release Notes).
+- Use only sections with distinct user-visible behavior or required action.
+  Keep any shared summary first, affected native and framework notes next,
+  migration or integration action after them, and `Package Releases` at the
+  bottom (see Editing Release Notes).
 - IAPKit and its MCP deploy as services and have no package version. Include
   their user-visible behavior in the consolidated card, but never invent an
   IAPKit item in the versioned `Package Releases` list.
@@ -152,22 +152,37 @@ Follow the existing card pattern:
 
 Card section layout (mandatory for multi-package cards):
 
-- Use `h5` headings only for shared groups, in this order: `Common changes`
-  (optional), `Shared spec and native packages`, `Framework libraries`,
-  `Integration notes` (or migration notes), then the bordered
-  `Package Releases` block.
+- Use only the sections that contain distinct user-visible behavior or
+  information readers must act on. When present, keep this order:
+  1. `Common changes`
+  2. `Shared spec and native packages`
+  3. `Framework libraries`
+  4. `Integration notes` (or migration notes)
+  5. The bordered `Package Releases` block
 - Never add one `h5` heading per platform or framework (no `Apple`, `Google`,
-  `React Native`, `Expo`, ... headings). Each package's changes are exactly one
-  `<li>` inside the shared group list, written as
+  `React Native`, `Expo`, ... headings). Each package-specific behavior gets at
+  most one `<li>` inside the shared group list, written as
   `<strong>package version</strong> - prose description`
   (for example `<strong>react-native-iap 16.0.2</strong> - exposes ...`).
 - `Shared spec and native packages` holds `OpenIAP Spec`, `openiap-apple`, and
   `openiap-google` bullets; `Framework libraries` holds the framework SDK
-  bullets. Omit a bullet entirely when that package has no user-facing change.
+  bullets. Omit the section when it would be empty.
+- A package whose only change is selecting a shared native dependency,
+  regenerating types, or republishing the same behavior belongs only in
+  `Package Releases`. Do not manufacture one boilerplate bullet per wrapper.
+- One bullet may name multiple packages when the same user-visible behavior and
+  caveats apply to all of them. Keep distinct behavior in distinct bullets.
 - The July 29, 2026 card (`openiap-major-api-cleanup-2026-07-29`) and the
   August 4, 2026 card (`amazon-rvs-user-data-patch-train-2026-08-04`) are the
   reference implementations of this layout.
 
+## Reader-First Writing Standard
+
+Apply the canonical standard in
+`knowledge/internal/05-docs-patterns.md#reader-first-writing-standard` to every
+new or edited release card. Render the result and remove repeated facts,
+wrapper-only dependency boilerplate, and sections with no reader action.
+
 ## Multi-package Release Trains
 
 The consolidated release page remains the release-note SSOT, but a release that
@@ -180,9 +195,10 @@ project decision recorded from issue #206.
 - Group notable changes under the affected platform package or framework
   library (Google, Apple, IAPKit, React Native, Expo, Flutter, Godot, KMP, and
   MAUI). Omit groups with no user-facing change.
-- Keep each group concise. State the behavior users gain or the regression that
-  was fixed; do not list commit mechanics, version-bump-only commits, generated
-  files, or repeated cross-framework boilerplate.
+- Apply the Reader-First Writing Standard above. State the behavior users gain
+  or the regression that was fixed; do not list commit mechanics,
+  version-bump-only commits, generated files, or repeated cross-framework
+  boilerplate.
 - Put truly shared schema or release-process changes in one short shared group,
   then describe framework-specific wiring or caveats in the relevant framework
   group.

.codex/skills/generate-doc/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Generate OpenIAP Docs"
   short_description: "Document expected releases without duplicate trains"
-  default_prompt: "Use $generate-doc to update the existing unreleased OpenIAP card in place with common changes, per-package native and framework notes, and expected Package Releases links at the bottom."
+  default_prompt: "Use $generate-doc to update the existing unreleased OpenIAP card with concise user-visible changes for affected packages and the expected Package Releases links."

.codex/skills/loop-review/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: loop-review
+description: "Run OpenIAP's complete change-to-merge loop from the latest origin/main: create a semantic branch, implement and verify the requested change, run review-self until stable, commit and open a PR, poll CodeRabbit and CI every five minutes, fix and reverify findings, and merge only when the exact head is clean. Use when the user invokes $loop-review or explicitly asks for the recurring review-self, commit --pr, review-pr until clean, then merge workflow."
+---
+
+# Loop Review
+
+Own one OpenIAP change from a fresh `main` baseline through a verified merge.
+Use the repository workflows as SSOT instead of duplicating their detailed
+commands.
+
+## Load The Workflows
+
+Read these before acting:
+
+- `AGENTS.md`
+- `.codex/skills/openiap-workflows/SKILL.md`
+- `.codex/skills/review-self/SKILL.md`
+- `.claude/commands/commit.md`
+- `.claude/commands/review-pr.md`
+
+Load package conventions and specialized skills required by the changed paths.
+An explicit `$loop-review` invocation or explicit natural-language request for
+this complete loop authorizes the in-scope commit, push, PR, review replies,
+thread resolution, and merge. It does not authorize deployment, publication,
+release, or unrelated cleanup.
+
+## 1. Start From Current Main
+
+Before editing task files:
+
+1. Snapshot `git status --short --branch`. Preserve every existing change.
+2. For a new task, require a clean worktree, then run `git fetch origin`, switch
+   to `main`, and run `git pull --ff-only origin main`.
+3. Verify local `main` equals `origin/main`, then create a semantic branch named
+   according to `.claude/commands/commit.md`.
+4. Record the starting main SHA. The implementation diff must descend from that
+   SHA.
+
+Never start new implementation on a stale local `main`. If invoked for work
+already in progress, do not manually switch branches, stash, reset, or discard
+it. Treat that as a resumed loop, verify its recorded or merge-base baseline,
+and use the repository's guarded `rebase-main` workflow when an update from
+`origin/main` is needed; that workflow owns its safeguard stash and branch
+transitions. Stop for direction if an update would overwrite unrelated user
+work.
+
+## 2. Implement And Verify
+
+Implement the requested scope and run the checks required by each touched path.
+Keep generated files, documentation, previews, and knowledge context in sync
+through their canonical workflows. Do not proceed while the working diff has a
+known failing required check.
+
+## 3. Stabilize With Review Self
+
+Run `$review-self` immediately against the complete base-to-working-tree diff.
+Fix every validated in-scope finding and rerun affected verification. Continue
+with five-minute recurring wake-ups until two consecutive complete snapshots are
+clean, as defined by the review-self skill.
+
+Do not emulate recurring review with a shell sleep loop. Keep the loop state out
+of tracked files. Any material diff change resets the consecutive-clean count.
+
+## 4. Commit And Open The PR
+
+Follow `.claude/commands/commit.md --all --pr`:
+
+- Stage only files owned by the task.
+- Use the required commit order and an English conventional commit message.
+- Push the semantic branch and open an English PR against `main`.
+- Add applicable repository labels.
+- For a visible or interactive change, attach a preview recording under 10 MB.
+  Do not commit one-off preview media unless browser upload is blocked and the
+  documented fallback is required.
+
+Record the PR number and exact head SHA. A push invalidates all prior clean
+review coverage.
+
+## 5. Review PR Until The Exact Head Is Clean
+
+Run `.claude/commands/review-pr.md` immediately, then re-enter it every five
+minutes through the product's recurring wake-up mechanism.
+
+For every round:
+
+1. Fetch unresolved threads, review status, current head SHA, and required CI.
+2. Fix all valid findings in one coherent batch; push, reply to the exact inline
+   comments, and resolve only fixed or outdated threads under the command rules.
+3. Rerun the checks affected by the batch plus all previously failing checks.
+4. Request CodeRabbit again after a head change.
+5. If CodeRabbit is unavailable, use the exact-head one-pass `$review-self`
+   fallback defined by `review-pr`; never substitute another reviewer.
+6. Keep polling while review or CI is pending. Do not rerun expensive unchanged
+   local checks on a no-op poll.
+
+Clean means all of the following hold for the same head SHA:
+
+- zero unresolved actionable review threads;
+- CodeRabbit is clean, or its unavailable result has clean review-self fallback
+  coverage;
+- every required CI check is terminal and successful or explicitly allowed to
+  skip by repository policy;
+- the PR is mergeable and the branch contains every required update from main;
+- the worktree is clean and the final diff has been reread.
+
+## 6. Merge And Close The Loop
+
+Immediately before merging, refetch the PR and confirm its head still equals the
+clean reviewed SHA. Use the repository-supported merge method, defaulting to a
+squash merge with branch deletion when no stricter policy applies. Never bypass
+branch protection or merge a stale, pending, or failing head.
+
+After merge:
+
+1. Confirm the PR state is `MERGED` and record the merge commit.
+2. Remove temporary review-trigger and terminal-unavailability comments as
+   required by `review-pr`.
+3. Switch to `main` and fast-forward from `origin/main` only when doing so cannot
+   disturb other work.
+4. Report the PR, merge commit, final checks, review coverage, and any skipped
+   item. Do not deploy or release unless separately requested.
+
+## Stop Conditions
+
+Stop without merging when a required choice lacks authority, the same finding
+survives two fix attempts, an access blocker repeats under the source workflow's
+threshold, or the exact head cannot satisfy the clean gate. Report the concrete
+blocker; never describe a pending or partially reviewed PR as clean.

.codex/skills/loop-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Loop Review"
+  short_description: "Review, open a PR, and merge a clean OpenIAP change"
+  default_prompt: "Use $loop-review to start from the latest origin/main, stabilize the change, open a PR, address reviews, and merge it."

.codex/skills/openiap-workflows/SKILL.md

@@ -58,9 +58,10 @@ platform rows, connected-device rows, and explicit blocked/unsupported rows.
 ## Internal Workflow Change Guard
 
 Internal agent/workflow-only changes include `.claude/commands/`,
-`.claude/skills/`, `.codex/skills/`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`,
-and agent automation notes. Do not create a branch, push, or open a PR for
-those changes unless the user explicitly asks to publish, PR, or merge them.
+`.claude/skills/`, `.codex/skills/`, `.cursor/rules/`, `AGENTS.md`,
+`CLAUDE.md`, `GEMINI.md`, and agent automation notes. Do not create a branch,
+push, or open a PR for those changes unless the user explicitly asks to publish,
+PR, or merge them.
 
 If a user asks to update an internal workflow and does not explicitly ask for a
 PR, keep the change local and report the changed files. If a PR is already open

.cursor/rules/openiap-ssot.mdc

@@ -0,0 +1,15 @@
+---
+description: OpenIAP repository instruction routing
+globs:
+alwaysApply: true
+---
+
+- Treat `AGENTS.md` as the root project instruction SSOT. `CLAUDE.md` and
+  `GEMINI.md` are symlinks to it; do not maintain separate copies.
+- Before editing a package or library, read the relevant files linked from
+  `AGENTS.md`.
+- For any user-facing documentation, apply
+  `knowledge/internal/05-docs-patterns.md#reader-first-writing-standard` and the
+  package convention. Keep prose concise, actionable, and free of repetition.
+- Keep detailed rules in their canonical files. This Cursor adapter only routes
+  to them.

AGENTS.md

@@ -15,7 +15,6 @@ This document provides an overview for AI agents working across the OpenIAP mono
 | Docs Patterns           | [`knowledge/internal/05-docs-patterns.md`](knowledge/internal/05-docs-patterns.md)                                                                                         |
 | Git & Deployment        | [`knowledge/internal/06-git-deployment.md`](knowledge/internal/06-git-deployment.md)                                                                                       |
 | Docs Consistency / SSOT | [`knowledge/internal/07-docs-consistency.md`](knowledge/internal/07-docs-consistency.md) (run `bun audit:docs` before pushing API/Type doc edits)                          |
-| GV Cloud Workspaces     | [`knowledge/internal/08-gv-cloud-workspaces.md`](knowledge/internal/08-gv-cloud-workspaces.md)                                                                             |
 
 ## Monorepo Structure
 
@@ -89,6 +88,16 @@ well-known APIs. Keep only what the code cannot show: platform quirks, non-obvio
 constraints, and why an obvious alternative was rejected. Full checklist in
 [`knowledge/internal/03-coding-style.md`](knowledge/internal/03-coding-style.md#keep-them-short--especially-ai-generated-ones).
 
+### Reader-First Documentation
+
+Write every user-facing document for scanning and action. Lead with the outcome,
+state each fact once, and remove filler, implementation narration, repeated
+cross-package boilerplate, and detail that does not change user behavior. Keep
+required compatibility, migration, safety, and platform caveats. Apply the
+canonical standard in
+[`knowledge/internal/05-docs-patterns.md`](knowledge/internal/05-docs-patterns.md#reader-first-writing-standard),
+including its stricter release-note limits.
+
 ### Platform Function Naming
 
 - **iOS functions**: Must end with `IOS` suffix (e.g., `syncIOS`, `getReceiptDataIOS`)
@@ -205,9 +214,9 @@ Codex-compatible local skills in `.codex/skills/`, including
 `openiap-workflows` for mapping Claude slash-command workflows and `review-self`
 for repeated self-review of current work.
 
-Codex discovers `review-self` from this repository. Install the globally unique
-skills (`openiap-workflows` and `generate-doc`) into your local Codex home when
-needed:
+Codex discovers `review-self` and `loop-review` from this repository. Install
+the globally unique skills (`openiap-workflows` and `generate-doc`) into your
+local Codex home when needed:
 
 ```bash
 ./.codex/scripts/install-skills.sh
@@ -217,9 +226,9 @@ After installation, ask Codex normally (for example, "review PR 65" or
 "resolve issue 88"), or explicitly mention `$openiap-workflows` or
 `$review-self`.
 
-Keep `$review-self` repo-local. Other repositories provide project-specific
-skills with the same name, so globally linking it would make the most recently
-installed project overwrite the others.
+Keep `$review-self` and `$loop-review` repo-local. Their review, merge, and
+release-safety policies are project-specific; globally linking them could apply
+the wrong repository workflow elsewhere.
 
 ## Claude Code Compatibility
 
@@ -250,11 +259,20 @@ config at `.codex-plugin/mcp.json`) and `.claude-plugin/plugin.json` (Claude
 Code, inline MCP config). The `skills/` folder is shared by both agents, so
 keep its wording agent-neutral.
 
+## Cursor Compatibility
+
+Cursor reads the root `AGENTS.md` and `CLAUDE.md`; because `CLAUDE.md` is a
+symlink, both resolve to this SSOT. `.cursor/rules/openiap-ssot.mdc` is only a
+short always-applied router to the root and docs SSOT. Keep detailed project
+rules in `AGENTS.md` or `knowledge/internal/` instead of copying them into
+Cursor-specific files.
+
 ## Available Skills (Slash Commands / Codex Workflows)
 
 | Skill                | Description                                        | Usage                                 |
 | -------------------- | -------------------------------------------------- | ------------------------------------- |
 | `$review-self`       | Review and improve current work until stable       | `$review-self` or `$review-self <PR>` |
+| `$loop-review`       | Start from current main, review, PR, and merge     | `$loop-review`                        |
 | `$rebase-main`       | Pull main and safely rebase the current branch     | `$rebase-main`                        |
 | `/review-pr`         | Review PR comments, fix issues, resolve threads    | `/review-pr 65` or `/review-pr <url>` |
 | `/audit-code`        | Audit code against knowledge rules and latest APIs | `/audit-code`                         |
@@ -298,4 +316,3 @@ All comprehensive rules are documented in [`knowledge/internal/`](knowledge/inte
 5. **05-docs-patterns.md** - React modal patterns, component organization
 6. **06-git-deployment.md** - Commit format, deployment workflows
 7. **07-docs-consistency.md** - Docs/API/type consistency audits
-8. **08-gv-cloud-workspaces.md** - Safe TabTabTab `gv` cloud workspace policy

knowledge/README.md

@@ -52,7 +52,6 @@ knowledge/
 │   ├── 05-docs-patterns.md         # React modal patterns, components
 │   ├── 06-git-deployment.md        # Git conventions, deployment
 │   ├── 07-docs-consistency.md      # Documentation SSOT audits
-│   ├── 08-gv-cloud-workspaces.md   # Cloud workspace safety
 │   └── sandbox-subscription-billing-issue.md
 ├── external/                        # REFERENCE - External APIs
 │   ├── amazon-iap-api.md           # Amazon Appstore SDK reference