docs: add socket marketplace screenshot

ACCESSIBILITY.md

@@ -73,15 +73,15 @@ Root scripts, workflow steps, validation failures, and documentation headings sh
 
 ### Color, Contrast, and Motion
 
-The root superproject should not rely on color alone to communicate meaning in documentation or generated summaries. When screenshots, diagrams, or visual artifacts are added later, they should include text labels or surrounding context that does not depend on color perception. Root docs should avoid animation-dependent explanations.
+The root superproject should not rely on color alone to communicate meaning in documentation or generated summaries. Screenshots, diagrams, and other visual artifacts should include text labels or surrounding context that does not depend on color perception. Root docs should avoid animation-dependent explanations.
 
 ### Zoom, Reflow, and Responsive Behavior
 
 Root documentation should remain readable under normal browser zoom and narrow layout behavior on GitHub. Prefer short paragraphs, flat list structures, and code blocks that are still understandable when horizontally scrolled.
 
 ### Media, Captions, and Alternatives
 
-If the root repository later adds media such as screenshots, diagrams, or recorded demos, contributors should provide adjacent text that explains the point of the artifact. If audio or video is ever added at the root level, include captions or a transcript where practical.
+Root media assets live under [`docs/media/`](./docs/media/). Contributors should provide meaningful alt text plus adjacent text that explains the point of each screenshot, diagram, or recorded demo. If audio or video is ever added at the root level, include captions or a transcript where practical.
 
 ## Engineering Workflow
 
@@ -109,6 +109,7 @@ For accessibility-relevant root changes, contributors should manually review:
 - heading hierarchy and section ordering in edited Markdown
 - link text and table-of-contents accuracy
 - code-block readability and command accuracy
+- image alt text, adjacent media explanations, and relative media paths
 - terminal output from root scripts for clarity and ambiguity
 - GitHub-rendered formatting when a change significantly reshapes a root document
 
@@ -175,4 +176,5 @@ Root accessibility review should happen whenever:
 
 ### Review History
 
+- 2026-05-02: Added root screenshot guidance after introducing README media under `docs/media/`.
 - 2026-04-14: Added the first root `ACCESSIBILITY.md` for the `socket` superproject and documented the root-only accessibility boundary around docs, metadata, and maintainer automation.

CONTRIBUTING.md

@@ -44,6 +44,8 @@ When changing user-facing plugin install or update docs, make the Git-backed mar
 
 For coordinated child-skill guidance, keep the root explanation small and put detailed behavior in the child repo that owns the skill surface. The root docs should explain why the pass is coordinated; the child docs should explain the actual skill contract.
 
+When adding root screenshots or other documentation media, place them under [`docs/media/`](./docs/media/), use portable descriptive filenames, and add nearby text that explains what the artifact proves or demonstrates. Do not rely on image content alone to explain a workflow.
+
 ### Asking For Review
 
 A root change is ready for review when:
@@ -129,6 +131,8 @@ If the changed surface also introduces or expands Python-backed repo checks, add
 
 When editing docs, also review the rendered Markdown structure and cross-links for the files you changed.
 
+When editing docs that include media, also review the image path, alt text, and adjacent explanatory prose.
+
 ## Pull Request Expectations
 
 A good root PR should make the changed superproject surface obvious. Include:

README.md

@@ -2,6 +2,10 @@
 
 Mixed-model monorepo for Gale's Codex plugin and skills repositories.
 
+![Codex plugin directory filtered to the Socket marketplace, showing Productivity Skills featured above installable Socket child plugins.](./docs/media/codex-plugin-directory-socket-productivity-skills.png)
+
+The screenshot shows the Codex plugin directory filtered to the `Socket` marketplace. This is the user-facing catalog surface that `socket` provides: adding the marketplace exposes the child plugins, and users still choose which entries to install or enable.
+
 ## Table of Contents
 
 - [Overview](#overview)
@@ -155,6 +159,8 @@ When a child repository or helper surface grows Python-backed validation beyond
 ├── ACCESSIBILITY.md
 ├── CONTRIBUTING.md
 ├── docs/
+│   ├── media/
+│   │   └── codex-plugin-directory-socket-productivity-skills.png
 │   └── maintainers/
 │       ├── plugin-packaging-strategy.md
 │       ├── release-modes.md
@@ -186,6 +192,7 @@ The root superproject docs are:
 - [ACCESSIBILITY.md](./ACCESSIBILITY.md) for the root accessibility contract around docs, metadata, and maintainer automation
 - [`docs/maintainers/`](./docs/maintainers/) for the deeper maintainer references behind the mixed-monorepo and subtree model
 - [`docs/maintainers/release-modes.md`](./docs/maintainers/release-modes.md) for the `standard` and `subtrees` release modes
+- [`docs/media/`](./docs/media/) for README screenshots and other root documentation media assets
 
 ## Plugin Surfaces
 

ROADMAP.md

@@ -7,6 +7,7 @@
 - [Milestone Progress](#milestone-progress)
 - [Milestone 2: subtree workflow hardening](#milestone-2-subtree-workflow-hardening)
 - [Milestone 3: release and sync discipline](#milestone-3-release-and-sync-discipline)
+- [Milestone 4: Speak Swiftly plugin split](#milestone-4-speak-swiftly-plugin-split)
 - [Backlog Candidates](#backlog-candidates)
 - [History](#history)
 
@@ -25,6 +26,7 @@
 
 - Milestone 2: subtree workflow hardening - Completed
 - Milestone 3: release and sync discipline - Completed
+- Milestone 4: Speak Swiftly plugin split - Planned
 
 ## Milestone 2: subtree workflow hardening
 
@@ -72,12 +74,45 @@ Completed
 
 Completed Milestone 3 by aligning the release-mode docs, subtree sync rules, shared-version workflow, and roadmap backlog cleanup around the current mixed monorepo model.
 
+## Milestone 4: Speak Swiftly plugin split
+
+### Status
+
+Planned
+
+### Scope
+
+- [ ] Create `plugins/speak-swiftly/` as a normal monorepo-owned Codex plugin whose payload is limited to the Codex-facing surfaces: `.codex-plugin/plugin.json`, `.mcp.json`, `hooks/`, `skills/`, user guidance, and any doctor or install-check helper scripts.
+- [ ] Keep `plugins/SpeakSwiftlyServer/` as a pull-only subtree mirror of the standalone Swift package while the split is underway, but stop treating that full source mirror as the preferred public Codex plugin payload.
+- [ ] Update the root marketplace so the public Speak Swiftly Codex plugin entry points at `./plugins/speak-swiftly` instead of `./plugins/SpeakSwiftlyServer` once the new plugin root is validated.
+- [ ] Update root README, plugin-packaging strategy, subtree workflow guidance, and child-facing docs so users understand the split: Codex users install the `speak-swiftly` plugin from `socket`; app embedders use the `SpeakSwiftlyServer` Swift package directly.
+- [ ] Decide whether the `SpeakSwiftlyServer` subtree remains useful as a source mirror after the split, or whether future `socket` releases can rely on the standalone repository plus the smaller monorepo-owned plugin directory.
+
+### Tickets
+
+- [ ] Inventory the current `SpeakSwiftlyServer` plugin-only payload and copy or move the minimal files into `plugins/speak-swiftly/` without importing Swift package sources, tests, build products, or release machinery.
+- [ ] Rename the plugin identity and display surface intentionally. Prefer plugin name `speak-swiftly` and display name `Speak Swiftly` unless install compatibility requires a transitional alias or migration note.
+- [ ] Adapt the MCP registration and hooks so paths stay `./`-relative to the new plugin root and still target the installed local service at `127.0.0.1:7337`.
+- [ ] Port or rewrite the hook doctor so it can validate the new socket-managed plugin root, the installed plugin cache, legacy global hooks, live service reachability, and expected voice profile.
+- [ ] Add a migration note for users who installed `speak-swiftly-server` from `socket`, including how to install or enable `speak-swiftly` and when it is safe to remove the old plugin entry.
+- [ ] Run `uv run scripts/validate_socket_metadata.py` after marketplace changes, then install or inspect the plugin through Codex to confirm the plugin directory shows the new entry.
+
+### Exit Criteria
+
+- [ ] The `socket` marketplace exposes a small `speak-swiftly` plugin whose installable root contains only Codex plugin surfaces and intentional support docs/scripts.
+- [ ] `SpeakSwiftlyServer` remains the source of truth for the Swift package, executable, LaunchAgent, embedded API, HTTP/MCP implementation, and release notes.
+- [ ] User-facing docs no longer recommend installing the full `SpeakSwiftlyServer` subtree mirror from `socket` as the default Codex plugin path.
+- [ ] The new plugin can be installed or enabled from the Git-backed `gaelic-ghost/socket` marketplace, and the doctor confirms hook, MCP, runtime, and voice-profile health.
+- [ ] The old `speak-swiftly-server` marketplace entry is either removed, marked transitional with a documented sunset path, or intentionally retained with a clear reason.
+
 ## Backlog Candidates
 
 No active backlog candidates are currently tracked here. Add new candidates only when they represent real future work that is not already covered by the maintainer docs or milestone history.
 
 ## History
 
+- Added root `docs/media` screenshot assets and README media guidance so the Codex plugin-directory catalog surface is visible without weakening text-first documentation.
+- Planned the `Speak Swiftly` plugin split so the public Codex plugin payload can move into a small monorepo-owned `plugins/speak-swiftly/` directory instead of requiring the full `SpeakSwiftlyServer` Swift package subtree mirror.
 - Added coordinated OpenAI Codex Hooks guidance across `agent-plugin-skills` and `productivity-skills`, with future `maintain-project-hooks` work tracked in the productivity roadmap.
 - Updated `socket` and plugin guidance so ordinary user installs and updates default to Git-backed Codex marketplace sources and official marketplace add/upgrade commands.
 - Added coordinated Codex subagent guidance across `agent-plugin-skills` and `productivity-skills`, grounding skill wording in OpenAI's current explicit-trigger `subagents` model while keeping the root docs clear about why the pass belongs in `socket`.

docs/maintainers/plugin-packaging-strategy.md

@@ -43,6 +43,38 @@ Recent monorepo-owned examples follow that rule directly: `things-app` and `card
 
 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` keeps its marketplace path at `./plugins/things-app` while its bundled MCP server lives at top-level `mcp/` inside that child repo.
 
+## Planned Speak Swiftly Split
+
+`SpeakSwiftlyServer` is the exception that now needs to move away from child-root packaging in `socket`.
+
+The current marketplace entry points at `./plugins/SpeakSwiftlyServer`, which is the full pull-only subtree mirror of the standalone Swift package. That keeps the plugin install technically valid because the subtree root contains `.codex-plugin/plugin.json`, `.mcp.json`, `skills/`, and `hooks/`, but it also couples the public Codex plugin payload to the entire Swift package source tree, tests, maintainer docs, and release workflow. That is the wrong long-term shape for users who only want Codex to talk to an already-running local Speak Swiftly service.
+
+The planned direction is a small monorepo-owned plugin root:
+
+```text
+plugins/speak-swiftly/
+├── .codex-plugin/
+│   └── plugin.json
+├── .mcp.json
+├── hooks/
+├── skills/
+├── README.md
+└── scripts/
+```
+
+That plugin should own only the Codex-facing distribution surface:
+
+- plugin identity, install metadata, and user-facing prompts
+- MCP registration for the local service endpoint
+- final-reply speech hooks
+- focused operator skills
+- doctor or install-check scripts for plugin, hook, runtime, and voice-profile health
+- migration guidance from the old `speak-swiftly-server` plugin entry
+
+The standalone `SpeakSwiftlyServer` repository should remain the source of truth for the Swift package, executable, LaunchAgent behavior, embedded API, HTTP/MCP implementation, API docs, release notes, and live-service validation. `socket/plugins/SpeakSwiftlyServer` may remain a pull-only source mirror while that is still useful for release coordination, but it should stop being the preferred public Codex plugin payload once `plugins/speak-swiftly/` exists.
+
+When the split lands, update `.agents/plugins/marketplace.json` so the public Speak Swiftly plugin entry points at `./plugins/speak-swiftly`, then run the marketplace audit and `uv run scripts/validate_socket_metadata.py`. Update README, ROADMAP, subtree workflow guidance, and any SpeakSwiftlyServer-facing install docs in the same pass so users see one coherent story: Codex users install `speak-swiftly` from the Git-backed `socket` marketplace; app embedders use `SpeakSwiftlyServer` as a Swift package.
+
 `socket` itself still does not define an aggregate root plugin above the child repos. The root Codex-facing surface here is the marketplace catalog, not a packaged plugin payload or a second shared plugin bundle.
 
 OpenAI's current [Codex plugin docs](https://developers.openai.com/codex/plugins/build) allow local repo marketplaces, personal marketplaces, and Git-backed marketplace sources through [`codex plugin marketplace add`](https://developers.openai.com/codex/plugins/build#add-a-marketplace-from-the-cli). The preferred user install and update path is therefore Git-backed:

docs/media/README.md

@@ -0,0 +1,18 @@
+# Media Assets
+
+Root documentation media for the `socket` superproject.
+
+## Current Assets
+
+| File | Use |
+| --- | --- |
+| [`codex-plugin-directory-socket-productivity-skills.png`](./codex-plugin-directory-socket-productivity-skills.png) | README screenshot showing the Codex plugin directory filtered to the `Socket` marketplace, with `Productivity Skills` featured. |
+| [`codex-plugin-directory-socket-speak-swiftly.png`](./codex-plugin-directory-socket-speak-swiftly.png) | Alternate Codex plugin-directory screenshot with `Speak Swiftly` featured. |
+| [`codex-plugin-directory-socket-python-skills.png`](./codex-plugin-directory-socket-python-skills.png) | Alternate Codex plugin-directory screenshot with `Python Skills` featured. |
+
+## Maintenance Rules
+
+- Use descriptive, portable filenames without spaces.
+- Keep screenshots near the docs that reference them, and prefer relative Markdown links.
+- Give every image meaningful alt text that explains the relevant UI state.
+- Add adjacent prose when the screenshot carries workflow meaning that should not depend on visual inspection alone.