Update socket and agent-plugin-skills docs and bump subtree versions

README.md

@@ -19,11 +19,11 @@ Mixed-model monorepo for Gale's Codex plugin and skills repositories.
 
 ### Status
 
-This repository is active and maintained as the superproject layer.
+This repository is active and maintained as the superproject coordination layer.
 
 ### What This Project Is
 
-`socket` is the superproject Gale uses to keep several Codex plugin and skills repositories under one Git root while OpenAI's documented Codex plugin system still lacks a better shared-parent scoping model. It owns the repo-root Codex marketplace at [`.agents/plugins/marketplace.json`](./.agents/plugins/marketplace.json), the monorepo-owned nested plugin directories under [`plugins/`](./plugins/), the remaining subtree sync paths for `apple-dev-skills`, `python-skills`, and `SpeakSwiftlyServer`, and the root maintainer docs that explain how the mixed model works.
+`socket` is the superproject Gale uses to keep several Codex plugin and skills repositories under one Git root while OpenAI's documented Codex plugin system still lacks a better shared-parent scoping model. It owns the repo-root Codex marketplace at [`.agents/plugins/marketplace.json`](./.agents/plugins/marketplace.json), the monorepo-owned child directories under [`plugins/`](./plugins/), the remaining subtree sync paths for `apple-dev-skills`, `python-skills`, and `SpeakSwiftlyServer`, and the root maintainer docs that explain how the mixed model works.
 
 ### Motivation
 
@@ -55,6 +55,7 @@ Use `socket` when the task is about the superproject layer:
 - mixed monorepo policy
 - subtree sync flow for `apple-dev-skills`, `python-skills`, or `SpeakSwiftlyServer`
 - cross-repo maintainer guidance
+- coordinated release-prep work that needs the root docs and child version surfaces to stay in sync
 
 When the work is really about one child repository's own behavior, start from that child directory's docs instead.
 
@@ -68,13 +69,13 @@ Sync the root maintainer environment with:
 uv sync --dev
 ```
 
-Only `apple-dev-skills`, `python-skills`, and `SpeakSwiftlyServer` still use subtree sync workflows.
+Only `apple-dev-skills`, `python-skills`, and `SpeakSwiftlyServer` still use subtree sync workflows. `socket` itself does not ship a root plugin; the marketplace is the root packaged surface here.
 
 ### Workflow
 
 Treat Gale's local `socket` checkout as the normal day-to-day checkout on `main`. Work in the monorepo copy first, and use the relevant directory under [`plugins/`](./plugins/) for child-repository changes unless the task is explicitly about the root marketplace or root maintainer docs. Reach for a feature branch or a dedicated worktree only when the change needs extra isolation.
 
-Keep root docs and marketplace wiring in sync with packaging changes in the same pass. For monorepo-owned child directories, edit the relevant directory under [`plugins/`](./plugins/) directly and commit in `socket`. For `apple-dev-skills`, `python-skills`, and `SpeakSwiftlyServer`, keep subtree sync operations explicit and isolated.
+Keep root docs and marketplace wiring in sync with packaging changes in the same pass. For monorepo-owned child directories, edit the relevant directory under [`plugins/`](./plugins/) directly and commit in `socket`. For `apple-dev-skills`, `python-skills`, and `SpeakSwiftlyServer`, keep subtree sync operations explicit and isolated. When a release-prep pass bumps subtree-managed child versions, update the child repo metadata in `socket` and keep the corresponding child docs aligned at the same time.
 
 Use [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the maintainer workflow boundary and [`ROADMAP.md`](./ROADMAP.md) for root planning and historical notes.
 
@@ -136,7 +137,7 @@ The root superproject docs are:
 
 ## Plugin Surfaces
 
-Treat `socket` as the canonical home for the monorepo-owned nested directories and as the subtree host for the remaining imported child repos.
+Treat `socket` as the canonical home for the monorepo-owned child directories and as the subtree host for the remaining imported child repos.
 
 - `agent-plugin-skills`, `dotnet-skills`, `productivity-skills`, `rust-skills`, `things-app`, and `web-dev-skills` are monorepo-owned here.
 - `apple-dev-skills`, `python-skills`, and `SpeakSwiftlyServer` preserve explicit subtree sync paths.
@@ -161,4 +162,4 @@ That marketplace points at the actual packaged surface each child repository tre
 
 For `things-app`, that root marketplace path stays the same after the bundled-server move because the installable plugin root is still `./plugins/things-app`; only the child repo's internal server layout changed, from `mcp/things-app-mcp/` to top-level `mcp/`.
 
-The mixed shape is intentional for now. `socket` does not try to flatten those child repo packaging models into one fake uniform layout.
+The mixed shape is intentional for now. `socket` does not try to flatten those child repo packaging models into one fake uniform layout, and it does not define a second aggregate Codex plugin root above the child repos.

ROADMAP.md

@@ -23,13 +23,13 @@
 ## Milestone Progress
 
 - Milestone 2: subtree workflow hardening - Planned
-- Milestone 3: release and sync discipline - Planned
+- Milestone 3: release and sync discipline - In Progress
 
 ## Milestone 2: subtree workflow hardening
 
 ### Status
 
-Planned
+In Progress
 
 ### Scope
 
@@ -56,10 +56,13 @@ Planned
 ### Tickets
 
 - [ ] Document the expected root release and sync rhythm once the current subtree migration experiment stabilizes.
+- [ ] Keep the root docs aligned with the current child packaging model during coordinated release-prep passes.
+- [ ] Make coordinated minor or patch bumps across `socket` and subtree-managed child repos explicit instead of relying on ad hoc release notes.
 
 ### Exit Criteria
 
 - [ ] Superproject release guidance is explicit enough that root changes can be shipped without improvising process each time.
+- [ ] Root docs still describe the live packaging and versioning model after a coordinated release-prep pass.
 
 ## Backlog Candidates
 

docs/maintainers/plugin-packaging-strategy.md

@@ -34,9 +34,12 @@ The current direction is:
 2. import them into `socket/plugins/` as subtrees
 3. keep the `socket` marketplace ready to list each plugin independently
 4. only add marketplace entries for child repos that actually ship `.codex-plugin/plugin.json`
+5. keep root `socket` docs aligned with child packaging moves and coordinated release-prep changes instead of treating the marketplace file as the only source of truth
 
 Child-repo internal layout changes do not automatically imply root marketplace changes. If a child repo keeps the same packaged plugin root, keep the `socket` marketplace path stable and only update the root docs to explain the child's new internal layout. Recent example: `things-app` kept its marketplace path at `./plugins/things-app` while moving its bundled MCP server from `mcp/things-app-mcp/` to top-level `mcp/` inside that child repo.
 
+`socket` itself still does not define an aggregate root plugin above the child repos. The root packaged surface here is the marketplace catalog, not a second shared plugin bundle.
+
 ## Follow-up Decision
 
 Once several child repos have stable plugin packaging, decide whether `socket` needs:

docs/maintainers/subtree-workflow.md

@@ -73,6 +73,7 @@ After subtree work:
 
 - verify the directory shape under `plugins/apple-dev-skills/`, `plugins/python-skills/`, or `plugins/SpeakSwiftlyServer/`
 - update socket docs and marketplace wiring in a separate focused commit when needed
+- if the subtree work is part of a coordinated release-prep pass, keep the child repo version metadata and child docs aligned before pushing the subtree back out
 
 ## Add A New Subtree-Managed Child Repository
 

plugins/agent-plugin-skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-plugin-skills",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "Installable maintainer skills for skills-export repositories.",
   "author": {
     "name": "Gale",
@@ -20,7 +20,7 @@
   "interface": {
     "displayName": "Agent Plugin Skills",
     "shortDescription": "Maintainer skills for skills-export repositories.",
-    "longDescription": "Installable maintainer skills for skills-export repositories, with blunt guidance about Codex plugin scoping limits and repo-shape maintenance workflows.",
+    "longDescription": "Installable maintainer skills for skills-export repositories, with clear guidance about Codex plugin boundaries and repo-shape maintenance workflows.",
     "developerName": "Gale",
     "category": "Developer Tools",
     "capabilities": [

plugins/agent-plugin-skills/AGENTS.md

@@ -1,15 +1,87 @@
 # AGENTS.md
 
-## Repository Role
+Use this file for durable repo-local guidance that Codex should follow before changing code, docs, or workflow surfaces in this repository.
 
-- This repository is the canonical home for maintainer skills that target skills-export and plugin-export repositories.
-- Treat `productivity-skills` as the default baseline maintainer layer for general repo docs and workflow guidance; this repo is the narrower specialist layer for exported-skill and exported-plugin repo shapes.
-- Root `skills/` is the canonical authored and exported surface.
-- This repo ships source-repo plugin packaging at [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json) and intentionally does not keep a repo-local Codex marketplace file for itself.
+## Repository Scope
 
-## Repo-specific Rules
+### What This File Covers
 
-- Keep Codex limitation wording blunt. When this repo discusses Codex plugin export boundaries, say plainly that repo-visible plugins come from the documented marketplace model rather than from a richer repo-private scoping system.
-- Do not recreate nested staged plugin directories, repo-local installer workflows, or install-surface validation machinery in this repository unless Gale explicitly asks for that reversal.
-- Keep repo-maintainer docs under [`docs/maintainers/`](./docs/maintainers/), and keep installed skills independent from those docs.
-- Keep `docs/maintainers/reality-audit.md` and `docs/maintainers/workflow-atlas.md` aligned with the shipped maintainer-skill surface.
+- `agent-plugin-skills` is the canonical home for maintainer skills that target skills-export and plugin-export repositories.
+- This root file governs the repo-wide maintainer docs, the source-first plugin packaging surface at [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json), and the authored skill surface under [`skills/`](./skills/).
+
+### Where To Look First
+
+- Start with [README.md](./README.md), [CONTRIBUTING.md](./CONTRIBUTING.md), and [ROADMAP.md](./ROADMAP.md).
+- For Codex packaging or install-surface questions, read [`docs/maintainers/codex-plugin-install-surfaces.md`](./docs/maintainers/codex-plugin-install-surfaces.md).
+- For current repo-shape and inventory expectations, read [`docs/maintainers/reality-audit.md`](./docs/maintainers/reality-audit.md) and [`docs/maintainers/workflow-atlas.md`](./docs/maintainers/workflow-atlas.md).
+
+## Working Rules
+
+### Change Scope
+
+- Keep work bounded to the repo surface that actually changed.
+- When a skill contract changes, update the nearby maintainer docs and tests in the same pass.
+- Do not widen work into installer revival, nested packaging, or repo-shape experiments unless Gale explicitly asks for that scope change.
+
+### Source of Truth
+
+- Root [`skills/`](./skills/) is the canonical authored and exported surface.
+- Treat maintainer docs under [`docs/maintainers/`](./docs/maintainers/) as the durable explanation layer for repo policy and packaging boundaries.
+- Keep Codex plugin guidance aligned with the current OpenAI docs: only `plugin.json` belongs in `.codex-plugin/`, while `skills/` stays at the plugin root.
+- Keep Codex plugin-boundary wording factual and explicit: repo-visible plugins come from the documented marketplace model, and OpenAI does not document a richer repo-private scoping model beyond that.
+
+### Communication and Escalation
+
+- Surface scope expansion before adding new maintainer workflows, new packaging layers, or new repo families.
+- If docs and shipped skill behavior diverge, fix the skill or narrow the docs so they match instead of preserving soft ambiguity.
+- When a wording choice could overstate Codex packaging behavior, prefer the narrower documented claim and name the exact surface involved.
+
+## Commands
+
+### Setup
+
+```bash
+uv sync --dev
+```
+
+### Validation
+
+```bash
+uv run pytest
+```
+
+### Optional Project Commands
+
+There are no additional repo-level commands worth calling out beyond the `uv` sync and test flow.
+
+## Review and Delivery
+
+### Review Expectations
+
+- Keep edits compact, repo-specific, and grounded in the shipped skill surface.
+- When changing docs, preserve the split between public-facing project docs, contributor workflow docs, maintainer reference docs, and agent guidance.
+- When changing skill behavior or audit logic, include the nearest tests or validation updates in the same pass.
+
+### Definition of Done
+
+- The changed surface is consistent across the relevant skill, maintainer doc, and test coverage.
+- README, CONTRIBUTING, AGENTS, and ROADMAP stay aligned with the current repo shape when one of them materially changes.
+- `uv run pytest` passes after changes that touch shipped skills, maintainer automation, or docs-backed audit expectations.
+
+## Safety Boundaries
+
+### Never Do
+
+- Do not recreate nested staged plugin directories or repo-local installer workflows in this repository.
+- Do not invent hidden plugin install surfaces, undocumented scoping behavior, or stale packaging overlays.
+- Do not treat maintainer docs as a substitute for the actual shipped skill contract.
+
+### Ask Before
+
+- Ask before adding new maintainer workflows, new repo-family support, or new packaging layers.
+- Ask before turning this repo into a broader plugin-management surface beyond its current maintainer-skill role.
+- Ask before deleting a maintainer reference doc unless its durable conclusions have been moved somewhere still-live.
+
+## Local Overrides
+
+There are no deeper `AGENTS.md` files in this repository today. If one is added later, that narrower file should refine this root guidance for the subtree where it lives.

plugins/agent-plugin-skills/CONTRIBUTING.md

@@ -0,0 +1,110 @@
+# Contributing to agent-plugin-skills
+
+Use this guide when preparing changes so the repository stays understandable, runnable, and reviewable for the next maintainer.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Contribution Workflow](#contribution-workflow)
+- [Local Setup](#local-setup)
+- [Development Expectations](#development-expectations)
+- [Pull Request Expectations](#pull-request-expectations)
+- [Communication](#communication)
+- [License and Contribution Terms](#license-and-contribution-terms)
+
+## Overview
+
+### Who This Guide Is For
+
+Use this guide if you are changing the shipped maintainer skills, the repo-local maintainer docs, or the small Python-backed audit tooling that supports those skills.
+
+### Before You Start
+
+Read [README.md](./README.md) for the public project shape, [AGENTS.md](./AGENTS.md) for durable repo rules, and the relevant maintainer docs under [`docs/maintainers/`](./docs/maintainers/) before changing packaging or guidance wording.
+
+If your change touches a skill contract, plan to update the nearest docs and tests in the same pass.
+
+## Contribution Workflow
+
+### Choosing Work
+
+Pick work that clearly belongs to this repository's narrow role: maintainer guidance for skills-export and plugin-export repos. General repo-doc cleanup belongs in `productivity-skills` unless this repo's narrower plugin-repo boundary is the real subject.
+
+When the work is about Codex plugin behavior, confirm the current OpenAI docs first instead of relying on older local assumptions.
+
+### Making Changes
+
+Keep root [`skills/`](./skills/) canonical, keep repo-level maintainer explanations under [`docs/maintainers/`](./docs/maintainers/), and keep source-repo plugin metadata under [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json).
+
+Do not reintroduce nested staged plugin directories, installer-era workflows, or vague install-surface language while making an unrelated fix.
+
+### Asking For Review
+
+A change is ready for review when the docs split still makes sense, nearby tests are updated when needed, and the final wording is explicit about which Codex surface or repo contract it is talking about.
+
+## Local Setup
+
+### Runtime Config
+
+This repository uses `uv` for local Python tooling. Sync the dev environment before running tests:
+
+```bash
+uv sync --dev
+```
+
+This repo does not require dedicated local services or repo-specific secret configuration for normal docs and test work.
+
+### Runtime Behavior
+
+Most changes here are static docs, skill content, and small audit scripts. The main sign that the repo is healthy is that the shipped tests pass and the updated docs still match the shipped skill surface.
+
+Run the normal validation flow with:
+
+```bash
+uv run pytest
+```
+
+## Development Expectations
+
+### Naming Conventions
+
+Keep the repo's core terms stable:
+
+- `skill` means the reusable workflow-authoring unit under `skills/`
+- `plugin` means the installable Codex distribution bundle rooted at `.codex-plugin/plugin.json`
+- `subagent` means a delegated runtime worker, not a packaged repo surface
+
+Match existing file, skill, and maintainer-doc names unless the change is explicitly about renaming.
+
+### Accessibility Expectations
+
+This repository is mostly docs and maintainer tooling rather than end-user UI, but contributors should still keep instructions, prompts, and audit output readable, plain, and unambiguous.
+
+If a change makes maintainer-facing language harder to scan or more ambiguous, treat that as a quality issue and fix it before asking for review.
+
+### Verification
+
+Prefer the grounded repo checks:
+
+```bash
+uv sync --dev
+uv run pytest
+```
+
+If you changed only prose, still sanity-check the nearby docs for split clarity and internal consistency before handing the work off.
+
+## Pull Request Expectations
+
+A good pull request keeps the scope narrow, explains which repo surface changed, and calls out any linked doc, test, or packaging updates that were needed to keep the repository coherent.
+
+If the change updates skill behavior or audit expectations, mention the validation you ran and which nearby docs moved with it.
+
+## Communication
+
+Surface uncertainty early when a change might widen the repository's role, soften a documented Codex boundary, or reintroduce old installer-era assumptions.
+
+If a task starts to require a new maintainer workflow, a new supported repo family, or a broader packaging model, pause and confirm that expansion before continuing.
+
+## License and Contribution Terms
+
+Contributions are governed by the repository license. See [LICENSE](./LICENSE) for the applicable terms.