Standardize project operations docs

AGENTS.md

@@ -7,7 +7,8 @@ React provider, hook, type, documentation, and package-boundary work.
 
 - Documentation structure: `docs/README.md`
 - Documentation wording and source checks: `docs/style-guide.md`
-- Check failures and CI expectations: `docs/project/check-failure-playbook.md`
+- Branch and release operations: `docs/project/branch-policy.md`,
+  `docs/project/release-policy.md`, and `docs/project/release-runbook.md`
 - Public package overview: `README.md`
 - Provider and context behavior: `src/components/SocketProvider.tsx` and
   `src/components/context.ts`
@@ -24,7 +25,7 @@ React provider, hook, type, documentation, and package-boundary work.
 - `docs/README.md` describes the documentation layout.
 - Agent-readable package context belongs in `docs/agents/` when the issue scope
   calls for that content.
-- Maintainer planning and failure guidance live in `docs/project/`; do not treat
+- Maintainer branch and release guidance live in `docs/project/`; do not treat
   these notes as public package guarantees.
 - Before changing public docs or examples, read `docs/README.md`,
   `docs/style-guide.md`, and any referenced source or tests.
@@ -55,9 +56,9 @@ Use existing package scripts as executable conventions:
 - `npm run pack:dry-run`
 - `npm run prepack`
 
-There is no automated example build script yet. If one is added, route failures
-through `docs/project/check-failure-playbook.md` and keep fixes tied to
-source-backed documentation or runnable examples.
+There is no automated example build script yet. If one is added, keep failures
+tied to source-backed documentation or runnable examples and route release
+decisions through `docs/project/release-runbook.md`.
 
 Do not publish npm releases, rename packages, or move this package into a
 monorepo unless explicitly requested.

docs/README.md

@@ -11,13 +11,12 @@ structure the public docs site exposes.
   pages, examples, migration notes, and React integration notes.
 - `docs/agents/`: LLM-readable package context, indexes, and structured
   metadata.
-- `docs/project/`: maintainer-facing planning notes that should not be treated
-  as public package documentation. Start with
-  [`docs/project/README.md`](./project/README.md) for the internal-docs index,
-  then use `docs/project/socket-store-contract-map.md` for cross-package
-  contract work, `docs/project/store-creation-path.md` for the official store
-  creation decision, and `docs/project/release-order.md` for cross-repository
-  release order.
+- `docs/project/`: maintainer-facing operations docs that should not be treated
+  as public package documentation. Use
+  [`docs/project/README.md`](./project/README.md), then the
+  [branch policy](./project/branch-policy.md),
+  [release policy](./project/release-policy.md), and
+  [release runbook](./project/release-runbook.md).
 
 Root files keep their existing roles: `README.md` is the concise package
 overview, `example/` contains runnable app code, and `src/` is the source of
@@ -38,8 +37,8 @@ Public docs explain the supported React adapter contract: provider setup, hook
 behavior, schema-safe topic usage, subscription cleanup, React rendering
 expectations, examples, and non-goals.
 
-Project docs may track verification playbooks, release decisions, and planning
-context. Do not present project notes as package guarantees.
+Project docs may track branch policy, release policy, and release operations.
+Do not present project notes as package guarantees.
 
 Agent-facing docs should point to public docs, source files, examples, and
 metadata without duplicating complete API references.
@@ -51,16 +50,11 @@ GitHub Pages deploys the VitePress output from `docs/public/` to the
 `npm run docs:build`, uploads only `docs/public/.vitepress/dist`, and publishes
 that artifact to <https://nerdchanii.github.io/react-socket-store/>.
 
-Maintainer notes in `docs/project/` and local planning notes are outside the
-VitePress source tree and are not deployed. If Pages is not enabled for the
+Maintainer operations docs in `docs/project/` are outside the VitePress source
+tree and are not deployed. If Pages is not enabled for the
 repository yet, an owner must configure Pages to use GitHub Actions as the
 source before the workflow can publish.
 
-Use [`docs/project/README.md`](./project/README.md) as the entry point for
-internal repository notes. If an accepted process or architecture rule needs a
-single long-lived source of truth, record that need there and promote the rule
-into a dedicated SPEC instead of repeating it across closeout notes.
-
 To roll back a bad docs deployment, revert the commit that changed the public
 docs or workflow and let the `Pages` workflow deploy the reverted artifact. If
 the workflow itself is failing, disable Pages publication in repository settings

docs/agents/agent-context.json

@@ -20,8 +20,8 @@
       "covers": ["provider example", "store-direct example", "Next.js App Router example", "expected message flow"]
     },
     {
-      "path": "docs/public/agents/index.md",
-      "covers": ["agent guide", "provider versus store-direct choice", "Next.js Client Component constraints", "socket-store contract links", "MCP docs-query evaluation"]
+      "path": "docs/agents/examples.md",
+      "covers": ["agent examples reference", "provider versus store-direct choice", "Next.js Client Component constraints"]
     },
     {
       "path": "docs/public/nextjs/index.md",
@@ -78,10 +78,11 @@
     "test-d/",
     "example/",
     "docs/style-guide.md",
-    "docs/project/check-failure-playbook.md"
+    "docs/project/release-policy.md",
+    "docs/project/release-runbook.md"
   ],
   "examples": [
-    { "name": "provider-backed React app", "path": "docs/public/examples/index.md#local-vite-provider-example", "source": "README.md" },
+    { "name": "provider-backed React app", "path": "docs/public/examples/index.md#local-vite-app", "source": "README.md" },
     { "name": "store-direct hook usage", "path": "docs/public/examples/index.md#react-router-loader-initial-snapshot", "source": "docs/public/guide/index.md" },
     { "name": "Next.js App Router client island", "path": "docs/public/examples/index.md#next-js-app-router-client-island", "source": "docs/public/nextjs/index.md" },
     { "name": "runnable Vite example", "path": "example/", "source": "example/README.md" }

docs/project/README.md

@@ -1,44 +1,31 @@
-# Project Docs
-
-`docs/project/` is for maintainer-facing notes that explain repository
-decisions, verification workflow, and historical closeout context. These files
-are not part of the public package contract.
-
-## File Guide
+---
+title: Project Docs
+doc_type: index
+status: active
+owner: maintainers
+applies_to: react-socket-store
+last_reviewed: 2026-05-29
+---
 
-- `socket-store-contract-map.md`: cross-package contract inventory for adapter
-  work that depends on `socket-store`.
-- `store-creation-path.md`: the accepted store creation path for public docs
-  and examples.
-- `release-order.md`: cross-repository release-order guidance for maintainers.
-- `check-failure-playbook.md`: how to triage local or CI failures without
-  weakening checks.
-- `documentation-examples-closeout.md`: historical closeout note for the #10
-  documentation and runnable examples umbrella.
-- `agent-docs-mcp-closeout.md`: historical closeout note for the #13 agent
-  docs and MCP evaluation umbrella.
-
-## Keep, Update, Or Retire
+# Project Docs
 
-- Keep durable maintainer references such as contract maps, store creation
-  decisions, release order, and failure playbooks.
-- Keep closeout notes only as historical reconciliation records. They should
-  say which umbrella issue they close and should not be treated as ongoing
-  policy documents.
-- Move user-facing guidance back to `docs/public/`.
-- Move agent-oriented package context back to `docs/agents/`.
+`docs/project/` contains maintainer-only operations docs. These files are not
+part of the public package contract.
 
-## When A SPEC Would Be The Right SSOT
+## Current Set
 
-This folder intentionally avoids introducing a full SPEC or ADR system. If the
-repository later accepts long-lived process or architecture rules that multiple
-project notes must follow, those accepted rules should move into a dedicated
-SPEC and these notes should link to it instead of restating them.
+- [branch-policy.md](./branch-policy.md): branch families, maintenance branches, and backport
+  rules.
+- [release-policy.md](./release-policy.md): release eligibility, adapter-specific release rules, and
+  cross-repository order rules.
+- [release-runbook.md](./release-runbook.md): the step-by-step release and publish flow.
+- [templates/policy-template.md](./templates/policy-template.md): template for future policy docs.
+- [templates/runbook-template.md](./templates/runbook-template.md): template for future runbooks.
 
-The clearest current SPEC candidates are:
+## Rules
 
-- cross-repository release-order policy
-- accepted package-boundary rules between `react-socket-store` and
-  `socket-store`
-- accepted store-creation and adapter-integration conventions once they stop
-  evolving as issue-by-issue docs work
+- Keep this folder limited to active maintainer operations.
+- Put supported adapter behavior in `docs/public/`, `docs/agents/`, or the
+  package root docs.
+- Do not keep closeout notes, historical reconciliation docs, or one-off
+  decision memos here.

docs/project/branch-policy.md

@@ -0,0 +1,61 @@
+---
+title: Branch Policy
+doc_type: policy
+status: active
+owner: maintainers
+applies_to: react-socket-store
+last_reviewed: 2026-05-29
+source_of_truth: docs/project/branch-policy.md
+---
+
+# Branch Policy
+
+`react-socket-store` uses trunk-based development. The goal is to keep `main`
+close to releasable adapter behavior while allowing short-lived task branches
+and, only when necessary, explicit maintenance branches.
+
+## Branch Roles
+
+- `main`: the default trunk branch. It should stay release-ready after every
+  merge.
+- `codex/*`, `feature/*`, `fix/*`, and `docs/*`: short-lived work branches for
+  pull requests.
+- `release/<major>.<minor>`: protected maintenance branches for patch releases
+  on an existing minor line.
+- `hotfix/*`: emergency fix branches for the currently affected release line.
+
+Do not introduce a long-lived `dev` branch.
+
+## Normal Development Flow
+
+1. Branch from the latest `main`.
+2. Keep the change scoped to one issue or pull request purpose.
+3. Merge only after CI passes and the adapter still matches the intended public
+   contract.
+4. Delete short-lived branches after merge unless another open pull request is
+   stacked on them.
+
+## Maintenance And Backports
+
+- Create `release/<major>.<minor>` only after a released minor line needs
+  supported patch maintenance.
+- Backport only critical bug fixes, security fixes, or release-blocking
+  compatibility fixes.
+- If the same fix also belongs on `main`, land or cherry-pick it there as well.
+
+## Cleanup Rules
+
+Automatic cleanup may delete merged, inactive short-lived branches in these
+families:
+
+- `codex/*`
+- `feature/*`
+- `fix/*`
+- `docs/*`
+
+Automatic cleanup must not delete:
+
+- `main`
+- `release/*`
+- active `hotfix/*`
+- branches used as the base for an open stacked pull request