diff --git a/README.md b/README.md
index 14ff7c34d..e54e72ead 100644
--- a/README.md
+++ b/README.md
@@ -141,6 +141,7 @@ Treat `socket` as the canonical home for the monorepo-owned nested directories a
 - `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.
 - Some child repos expose plugin packaging from the repo root, while others keep a nested packaged plugin root inside their own repository tree.
+- `things-app` still packages from its child-repo root at `./plugins/things-app`, but its bundled MCP server now lives directly under that child repo's top-level `mcp/` directory rather than under a second nested server folder.
 
 ## Marketplace Shape
 
@@ -158,4 +159,6 @@ That marketplace points at the actual packaged surface each child repository tre
 - `./plugins/things-app`
 - `./plugins/web-dev-skills`
 
+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.
diff --git a/docs/maintainers/plugin-packaging-strategy.md b/docs/maintainers/plugin-packaging-strategy.md
index 486e83dcb..c11daed44 100644
--- a/docs/maintainers/plugin-packaging-strategy.md
+++ b/docs/maintainers/plugin-packaging-strategy.md
@@ -35,6 +35,8 @@ The current direction is:
 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`
 
+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.
+
 ## Follow-up Decision
 
 Once several child repos have stable plugin packaging, decide whether `socket` needs:
diff --git a/docs/maintainers/subtree-workflow.md b/docs/maintainers/subtree-workflow.md
index e864a6c27..f85e7bed2 100644
--- a/docs/maintainers/subtree-workflow.md
+++ b/docs/maintainers/subtree-workflow.md
@@ -107,10 +107,13 @@ Use these rules:
 - list every non-private imported child plugin surface by default
 - keep private child repos out of the public marketplace, and remove their entries if their directories are retired from the monorepo
 - point `source.path` at the actual child surface the imported repo treats as installable
+- do not change a marketplace path just because a child repo rearranged files internally; if the packaged plugin root is unchanged, keep the same `source.path`
 - do not invent a second socket-level plugin wrapper when the child repo already has one
 - do not leave stale marketplace entries behind after a packaging move or subtree removal
 - keep one surviving plugin identity for each real child plugin
 
+Recent example: `things-app` moved its bundled MCP server from `mcp/things-app-mcp/` to top-level `mcp/` inside the child repo, but the root marketplace entry stayed `./plugins/things-app` because the installable plugin root did not move.
+
 ## Release Flow
 
 For socket releases:
diff --git a/plugins/things-app/.mcp.json b/plugins/things-app/.mcp.json
index 11a4712fe..f4c5e71b5 100644
--- a/plugins/things-app/.mcp.json
+++ b/plugins/things-app/.mcp.json
@@ -6,6 +6,6 @@
       "python",
       "app/server.py"
     ],
-    "cwd": "../../mcp/things-app-mcp"
+    "cwd": "../../mcp"
   }
 }
diff --git a/plugins/things-app/AGENTS.md b/plugins/things-app/AGENTS.md
index 1bc197c5f..282eafad0 100644
--- a/plugins/things-app/AGENTS.md
+++ b/plugins/things-app/AGENTS.md
@@ -1,22 +1,118 @@
 # AGENTS.md
 
-## Repository Role
+Use this file for durable repo-local guidance that Codex should follow before changing code, docs, or project workflow surfaces in this repository.
 
-- This repository is the canonical home for `things-digest-generator` and `things-reminders-manager`.
-- Keep active skills under [`skills/`](./skills/).
-- Keep the bundled FastMCP server under [`mcp/things-app-mcp/`](./mcp/things-app-mcp/).
-- Keep root plugin metadata thin and explicit.
+## Repository Scope
 
-## Source Of Truth
+### What This File Covers
 
-1. root [README.md](./README.md) for the mixed repo model and install-surface explanation
-2. root [`skills/`](./skills/) for canonical workflow authoring
-3. [`mcp/things-app-mcp/`](./mcp/things-app-mcp/) for the bundled server package, tests, and server-specific docs
-4. root plugin manifests and marketplace files for install metadata only
+- `things-app` is the canonical home for Gale's Things-oriented skills, the bundled FastMCP server, and the thin plugin packaging that exposes those surfaces to Codex and Claude.
+- Use this file to coordinate the root guidance files, the authored skill surfaces under [`skills/`](./skills/), the bundled server package under [`mcp/`](./mcp/), and the repo-root plugin metadata.
+- Treat this repository as a mixed skills-plus-server repo on purpose. Do not collapse those surfaces into one vague "plugin" layer.
 
-## Repo-specific Rules
+### Where To Look First
 
-- Preserve the existing skill names unless a migration is explicitly requested.
-- Update repo docs in the same change when the active skill inventory changes.
-- Keep the repo honest about shipping three maintained surfaces: root skills, the bundled MCP server, and thin plugin packaging metadata.
-- Do not let plugin manifests or marketplace files become the source of truth for workflow content or MCP-server behavior.
+- Start with [README.md](./README.md), [CONTRIBUTING.md](./CONTRIBUTING.md), and [ROADMAP.md](./ROADMAP.md) for the current repo shape and contributor expectations.
+- Read [`mcp/README.md`](./mcp/README.md) before changing the bundled server package or its local validation flow.
+- Read the specific skill under [`skills/`](./skills/) before changing workflow behavior or renaming any workflow surface.
+
+## Working Rules
+
+### Change Scope
+
+- Keep work bounded to the surface that actually changed: root skills, bundled server, or thin packaging metadata.
+- When one change crosses those boundaries, update the nearby docs in the same pass so the mixed-repo model stays explicit.
+- Surface scope widening before introducing a new skill, renaming a shipped workflow, changing the packaged MCP command contract, or adding another install/discovery surface.
+
+### Source of Truth
+
+- Treat root [`skills/`](./skills/) as the source of truth for workflow-authoring behavior.
+- Treat [`mcp/`](./mcp/) as the source of truth for bundled server code, tests, helper commands, and server-specific docs.
+- Treat [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json), [`.claude-plugin/plugin.json`](./.claude-plugin/plugin.json), and [`.mcp.json`](./.mcp.json) as packaging and launch metadata only.
+- Keep the repo honest about the install surfaces that actually exist. Do not claim a discovery mirror, license file, or packaged surface is present unless it is checked in here.
+
+### Communication and Escalation
+
+- Start from the root docs when the task is about the mixed repo model, contributor workflow, packaging boundaries, or root guidance alignment.
+- Start from the bundled server docs when the task is really about FastMCP behavior, AppleScript routing, auth-token handling, or HTTP smoke flows.
+- Stop and surface the tradeoff before broadening the repo from its current two-skill scope into a larger Things automation bundle or a materially different plugin packaging model.
+
+## Commands
+
+### Setup
+
+Repo-root setup:
+
+```bash
+uv sync --dev
+```
+
+Bundled server setup:
+
+```bash
+cd mcp
+uv sync
+```
+
+### Validation
+
+Repo-root validation:
+
+```bash
+uv run pytest
+```
+
+Bundled server validation:
+
+```bash
+cd mcp
+uv run pytest
+uv run ruff check .
+uv run mypy .
+```
+
+### Optional Project Commands
+
+Bundled server smoke and helper commands live under `mcp`:
+
+```bash
+cd mcp
+make inspect
+make smoke-http
+make smoke-json
+make smoke-read
+```
+
+## Review and Delivery
+
+### Review Expectations
+
+- Keep README, CONTRIBUTING, ROADMAP, AGENTS, and the bundled server README aligned when a shared contract changes.
+- Say clearly which surface changed and which validation path you ran.
+- When a change only affects one surface, avoid broad edits in unrelated packaging or server files.
+
+### Definition of Done
+
+- The change is grounded in the correct source-of-truth surface for the behavior you touched.
+- The relevant validation commands ran for the changed surface.
+- Nearby docs and packaging metadata were updated when behavior, install wiring, or contributor workflow changed.
+
+## Safety Boundaries
+
+### Never Do
+
+- Do not rename the shipped skills or MCP server surface casually.
+- Do not treat plugin manifests or launch metadata as the source of truth for workflow behavior.
+- Do not claim install surfaces or local files exist when they are not checked in here.
+- Do not skip the bundled server README and tests when changing `mcp/`.
+
+### Ask Before
+
+- Ask before adding another skill, another packaged host surface, or another bundled service.
+- Ask before changing the packaged MCP command contract or the relative `cwd` model in [`.mcp.json`](./.mcp.json).
+- Ask before making repo-wide terminology changes that would rename user-facing workflows, tool names, or packaging concepts.
+
+## Local Overrides
+
+- There are currently no deeper `AGENTS.md` files below this repo root.
+- Use the specific skill docs under `skills/` and the bundled server docs under `mcp/` as narrower workflow guidance when work happens there.
diff --git a/plugins/things-app/CONTRIBUTING.md b/plugins/things-app/CONTRIBUTING.md
new file mode 100644
index 000000000..fb920445b
--- /dev/null
+++ b/plugins/things-app/CONTRIBUTING.md
@@ -0,0 +1,143 @@
+# Contributing to things-app
+
+Use this guide when preparing changes so the repo stays understandable, runnable, and reviewable across its three active surfaces: root skills, the bundled MCP server, and thin plugin packaging metadata.
+
+## 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 when contributing to the root Things skills, the bundled FastMCP server under `mcp/`, or the repo-root plugin packaging and guidance files that tie those surfaces together.
+
+### Before You Start
+
+- Read [README.md](./README.md) for the mixed repo model and install-surface overview.
+- Read [AGENTS.md](./AGENTS.md) for durable maintainer boundaries.
+- Read [`mcp/README.md`](./mcp/README.md) before changing the bundled server package.
+- Confirm which surface actually owns the behavior you want to change before editing files.
+
+## Contribution Workflow
+
+### Choosing Work
+
+Choose work by identifying the owning surface first:
+
+- `skills/` for workflow-authoring behavior
+- `mcp/` for server implementation and FastMCP tooling
+- repo-root packaging files and docs for installation, discovery, and contributor guidance
+
+If the change needs to cross those boundaries, keep the scope explicit and update the nearby docs in the same pass.
+
+### Making Changes
+
+Keep edits bounded and coherent. Change the authored surface first, then update packaging metadata or root docs only when the shipped contract actually changed. Avoid letting launch metadata drift into the role of behavioral source of truth.
+
+For server changes, prefer editing and validating inside `mcp/` rather than patching around behavior from root docs or plugin files.
+
+### Asking For Review
+
+Ask for review when the owning surface is clear, the relevant checks have run, and the docs affected by that change are aligned. Call out whether the change touched root skills, the bundled server, packaging metadata, or more than one of those surfaces.
+
+## Local Setup
+
+### Runtime Config
+
+Root skill-maintainer setup:
+
+```bash
+uv sync --dev
+```
+
+Bundled server setup:
+
+```bash
+cd mcp
+uv sync
+```
+
+Server update flows may require a Things auth token. The bundled server supports:
+
+- explicit `auth_token` arguments to update tools
+- `THINGS_AUTH_TOKEN` in the environment
+- keychain-backed token storage through the bundled auth tools
+
+Read and update flows also assume macOS with Things.app installed.
+
+### Runtime Behavior
+
+Nothing needs to run continuously for repo-root skill work. The root `pyproject.toml` currently supports a narrow pytest surface for the digest skill tests.
+
+For bundled server work:
+
+- Codex packaging uses stdio launch through [`.mcp.json`](./.mcp.json)
+- local smoke flows use the HTTP helper commands inside `mcp`
+- read tools depend on macOS Automation permission for the host app controlling Things
+
+If read calls fail locally, verify Automation permissions before assuming the server code is broken.
+
+## Development Expectations
+
+### Naming Conventions
+
+- Keep the existing skill names stable unless a migration is explicitly intended.
+- Use `skill`, `bundled MCP server`, and `plugin packaging` consistently so the repo shape stays understandable.
+- Match existing tool names and avoid introducing alternate names for the same user-facing workflow unless the change intentionally includes a migration.
+
+### Accessibility Expectations
+
+This repository is mostly documentation, workflow-authoring, and local automation surfaces rather than end-user UI. Accessibility work here mainly means keeping contributor docs readable, install instructions explicit, and tool descriptions clear enough to use without guessing.
+
+When a change affects user-facing examples, commands, or workflow guidance, keep the language plain and the step order easy to follow in ordinary Markdown readers.
+
+### Verification
+
+Run the checks that match the surface you changed.
+
+Repo-root validation:
+
+```bash
+uv run pytest
+```
+
+Bundled server validation:
+
+```bash
+cd mcp
+uv run pytest
+uv run ruff check .
+uv run mypy .
+```
+
+Useful bundled-server smoke commands:
+
+```bash
+cd mcp
+make smoke-http
+make smoke-json
+make smoke-read
+```
+
+## Pull Request Expectations
+
+Summarize what changed, why it changed, and which repo surface owns the behavior. Point reviewers to the most relevant docs or server files first, and include the exact validation commands you ran.
+
+If packaging metadata changed, call out whether the launch command, relative `cwd`, or shipped discovery surfaces changed with it.
+
+## Communication
+
+Surface questions early when a change starts widening from one repo surface into another, especially if it would rename a shipped workflow, add another packaging surface, or change the bundled MCP contract.
+
+When in doubt, ask whether the work should stay in root skills, move into `mcp/`, or remain thin packaging-only maintenance.
+
+## License and Contribution Terms
+
+Keep contributor-facing license language aligned with the repository's checked-in license terms. If a local `LICENSE` file is added or changed, update this guide and [README.md](./README.md) in the same pass.
diff --git a/plugins/things-app/README.md b/plugins/things-app/README.md
index acf59f2cf..26b7a1c39 100644
--- a/plugins/things-app/README.md
+++ b/plugins/things-app/README.md
@@ -2,148 +2,185 @@
 
 Canonical home for Gale's Things.app skills, bundled local MCP server, and plugin packaging.
 
-For maintainer policy and source-of-truth boundaries, see [AGENTS.md](./AGENTS.md).
+For maintainer policy and source-of-truth boundaries, see [AGENTS.md](./AGENTS.md). For contributor workflow, setup, and review expectations, see [CONTRIBUTING.md](./CONTRIBUTING.md).
 
 ## Table of Contents
 
 - [Overview](#overview)
-- [Setup](#setup)
+- [Quick Start](#quick-start)
 - [Usage](#usage)
 - [Development](#development)
-- [Verification](#verification)
+- [Repo Structure](#repo-structure)
 - [Release Notes](#release-notes)
 - [License](#license)
 - [Active Skills](#active-skills)
 - [Bundled MCP Server](#bundled-mcp-server)
 - [Packaging](#packaging)
-- [Maintainer Python Tooling](#maintainer-python-tooling)
-- [Repository Layout](#repository-layout)
 
 ## Overview
 
-This repository ships three closely related surfaces:
+`things-app` ships three related surfaces in one repo:
 
 - reusable Things-oriented skills under [`skills/`](./skills/)
-- the bundled FastMCP server under [`mcp/things-app-mcp/`](./mcp/things-app-mcp/)
-- plugin packaging metadata at the repo root for Codex and Claude Code
+- a bundled FastMCP server under [`mcp/`](./mcp/)
+- thin Codex and Claude plugin packaging metadata at the repo root
 
 ### Status
 
-`things-app` is active and currently ships maintained Things-oriented skills, plugin packaging metadata, and the bundled MCP server described below.
+`things-app` is active and currently maintained as a mixed skills-plus-server repository.
 
 ### What This Project Is
 
-This repository is the canonical home for Gale's Things-focused automation workflows and the local MCP server they depend on.
+This repository is the canonical home for Gale's Things-focused automation workflows and the local MCP server those workflows depend on.
 
 ### Motivation
 
-It exists to keep the Things workflow surface, the server implementation, and the plugin packaging story aligned in one place instead of spreading those pieces across separate repos.
+It keeps the Things workflow surface, the bundled server implementation, and the plugin packaging story aligned in one place instead of splitting those concerns across separate repositories.
 
-## Setup
+## Quick Start
 
-Start with the install and packaging guidance in this README, then use the server-specific docs inside [`mcp/things-app-mcp/`](./mcp/things-app-mcp/) when the work is really about the bundled FastMCP package.
+This repo is primarily a maintainer and power-user surface rather than an end-user app with a single quick-start flow.
 
-## Usage
+If you want to use the workflow guidance, start with the skills under [`skills/`](./skills/). If you want to work on the bundled server, go straight to [`mcp/README.md`](./mcp/README.md). If you are changing the repo itself, use the contributor workflow in [CONTRIBUTING.md](./CONTRIBUTING.md).
 
-Use the surface that matches the job you are doing:
+## Usage
 
-- root [`skills/`](./skills/) for Things workflow guidance
-- root plugin manifests for Codex or Claude plugin installation
-- [`mcp/things-app-mcp/`](./mcp/things-app-mcp/) for the bundled local MCP server package and its server-specific validation
+Use the surface that matches the job:
 
-## Development
+- root [`skills/`](./skills/) for Things reminder and planning workflows
+- root plugin metadata for Codex or Claude installation and discovery
+- [`mcp/`](./mcp/) for the local FastMCP server, its docs, and its server-specific checks
 
-### Setup
+The current active skills are intentionally narrow:
 
-Work from the canonical source surfaces in this repository and keep docs, packaging metadata, and server guidance aligned in the same change.
+- `things-reminders-manager` for deterministic create and update flows around Things reminders and scheduled to-dos
+- `things-digest-generator` for week-ahead planning digests built from Things reads or equivalent JSON exports
 
-### Workflow
+## Development
 
-Edit root skills first when changing workflow behavior. Edit the bundled MCP server in `mcp/things-app-mcp/` when the server behavior changes. Treat plugin manifests and marketplace wiring as install metadata rather than as the source of truth for workflow logic.
+### Setup
 
-## Verification
+The repo has two distinct Python environments:
 
-Run the validation commands that match the surface you changed.
+- repo root for the digest-skill maintainer tooling and tests
+- `mcp/` for the bundled server package and its lint, typecheck, and smoke flows
 
-For the repo-root Python-backed skill surface:
+Root setup:
 
 ```bash
 uv sync --dev
-uv run pytest
 ```
 
-For the bundled MCP server package:
+Bundled server setup:
 
 ```bash
-cd mcp/things-app-mcp
+cd mcp
 uv sync
-uv run pytest
 ```
 
-## Release Notes
-
-Use Git history and GitHub releases to track shipped changes for this repository, especially when skills, packaging metadata, and the bundled MCP server move together.
-
-## License
-
-See [LICENSE](./LICENSE).
-
-## Active Skills
+### Workflow
 
-- `things-reminders-manager`: deterministic create and update workflows for Things reminders and scheduled todos
-- `things-digest-generator`: week-ahead planning digests built from Things MCP reads or equivalent JSON exports
+Keep the source-of-truth boundaries straight:
 
-## Bundled MCP Server
+- edit root [`skills/`](./skills/) when workflow behavior changes
+- edit [`mcp/`](./mcp/) when server behavior changes
+- treat [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json), [`.claude-plugin/plugin.json`](./.claude-plugin/plugin.json), and [`.mcp.json`](./.mcp.json) as install metadata, not as the source of truth for workflow logic
 
-The former standalone `things-app-mcp` project now lives under [`mcp/things-app-mcp/`](./mcp/things-app-mcp/), with its own package metadata, tests, docs, and README.
+When a change touches more than one surface, update the nearby docs in the same pass so the mixed-repo model stays explicit and accurate.
 
-Use its local docs and tests when the work is really about the server package rather than the root skill and plugin surfaces.
+### Validation
 
-## Packaging
+Run the checks that match the surface you changed.
 
-This repository keeps root workflow content and plugin metadata separate on purpose.
+Repo-root skill validation:
 
-- root [`skills/`](./skills/) is the canonical workflow-authoring surface
-- [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json) and [`.claude-plugin/plugin.json`](./.claude-plugin/plugin.json) describe install metadata
-- [`.agents/skills`](./.agents/skills) and [`.claude/skills`](./.claude/skills) are discovery mirrors into root `skills/`
-- the bundled server stays self-contained under [`mcp/things-app-mcp/`](./mcp/things-app-mcp/)
+```bash
+uv run pytest
+```
 
-Helpful references:
+Bundled server validation:
 
-- [OpenAI Codex Skills](https://developers.openai.com/codex/skills)
-- [OpenAI Codex plugins](https://developers.openai.com/codex/plugins)
-- [Claude Code Skills](https://code.claude.com/docs/en/skills)
-- [Claude Code Plugins](https://code.claude.com/docs/en/plugins)
-
-## Maintainer Python Tooling
+```bash
+cd mcp
+uv run pytest
+uv run ruff check .
+uv run mypy .
+```
 
-Repo-root Python tooling is intentionally narrow and currently supports the Python-backed digest skill test surface:
+For local HTTP smoke checks while working on the bundled server:
 
 ```bash
-uv sync --dev
-uv run pytest
+cd mcp
+make smoke-http
+make smoke-json
 ```
 
-## Repository Layout
+## Repo Structure
 
 ```text
 .
-├── .agents/
-│   └── skills -> ../skills
 ├── .claude/
 │   └── skills -> ../skills
 ├── .claude-plugin/
 │   └── plugin.json
 ├── .codex-plugin/
 │   └── plugin.json
+├── .mcp.json
 ├── AGENTS.md
-├── LICENSE
+├── CONTRIBUTING.md
 ├── README.md
 ├── ROADMAP.md
 ├── mcp/
-│   └── things-app-mcp/
 ├── pyproject.toml
 └── skills/
     ├── things-digest-generator/
     └── things-reminders-manager/
 ```
+
+## Release Notes
+
+Use Git history and GitHub releases to track shipped changes, especially when skills, packaging metadata, and the bundled MCP server move together.
+
+## License
+
+Keep this README aligned with the repository's checked-in license terms. If `things-app` gains or changes a local `LICENSE` file, update this section and [CONTRIBUTING.md](./CONTRIBUTING.md) in the same pass.
+
+## Active Skills
+
+- [`skills/things-reminders-manager/`](./skills/things-reminders-manager/): deterministic create and update workflows for Things reminders and scheduled to-dos
+- [`skills/things-digest-generator/`](./skills/things-digest-generator/): week-ahead planning digests built from Things MCP reads or equivalent JSON exports
+
+## Bundled MCP Server
+
+The former standalone `things-app-mcp` project now lives directly under [`mcp/`](./mcp/), with its own package metadata, helper commands, tests, and server-specific docs.
+
+The packaged Codex MCP entrypoint in [`.mcp.json`](./.mcp.json) launches that server with:
+
+```json
+{
+  "things-app": {
+    "command": "uv",
+    "args": ["run", "python", "app/server.py"],
+    "cwd": "../../mcp"
+  }
+}
+```
+
+That relative `cwd` matters because the plugin packaging lives at repo root while the server stays self-contained inside the bundled package directory.
+
+## Packaging
+
+This repository keeps authored workflow content and packaging metadata separate on purpose.
+
+- root `skills/` is the canonical workflow-authoring surface
+- [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json) points Codex at the root skills and bundled MCP config
+- [`.claude-plugin/plugin.json`](./.claude-plugin/plugin.json) describes the Claude plugin package
+- [`.claude/skills`](./.claude/skills) is the checked-in discovery mirror currently present in this repo
+- the bundled FastMCP server stays self-contained under [`mcp/`](./mcp/)
+
+Helpful references:
+
+- [OpenAI Codex Skills](https://developers.openai.com/codex/skills)
+- [OpenAI Codex plugins](https://developers.openai.com/codex/plugins)
+- [Claude Code Skills](https://code.claude.com/docs/en/skills)
+- [Claude Code Plugins](https://code.claude.com/docs/en/plugins)
diff --git a/plugins/things-app/ROADMAP.md b/plugins/things-app/ROADMAP.md
index ffbc1168f..daef5219e 100644
--- a/plugins/things-app/ROADMAP.md
+++ b/plugins/things-app/ROADMAP.md
@@ -1,36 +1,60 @@
 # Project Roadmap
 
+## Table of Contents
+
+- [Vision](#vision)
+- [Product Principles](#product-principles)
+- [Milestone Progress](#milestone-progress)
+- [Milestone 5: guidance and maintenance modernization](#milestone-5-guidance-and-maintenance-modernization)
+- [Backlog Candidates](#backlog-candidates)
+- [History](#history)
+
 ## Vision
 
-- Keep `things-app` as the canonical home for Gale's Things-oriented skills plus the bundled Things MCP server, with packaging that stays honest about the mixed skills-and-server repository model.
+- Keep `things-app` as the canonical home for Gale's Things-oriented skills plus the bundled Things MCP server, with documentation and packaging that stay honest about the mixed skills-and-server repository model.
 
-## Product principles
+## Product Principles
 
 - Keep root `skills/` as the canonical skill-authoring surface.
-- Keep the bundled MCP server self-contained under `mcp/things-app-mcp/`.
+- Keep the bundled MCP server self-contained under `mcp/`.
 - Keep plugin packaging thin and explicit.
-- Keep root docs, server docs, and packaging metadata aligned with the same mixed-repo model.
+- Keep root docs, server docs, and packaging metadata aligned in the same pass when shared behavior changes.
 
 ## Milestone Progress
 
-- [ ] Milestone 5: future Things workflow expansion
+- Milestone 5: guidance and maintenance modernization - In Progress
+
+## Milestone 5: guidance and maintenance modernization
+
+### Status
+
+In Progress
+
+### Scope
 
-## Milestone 5: future Things workflow expansion
+- [ ] Refresh the root maintainer docs so `README.md`, `CONTRIBUTING.md`, `ROADMAP.md`, and `AGENTS.md` describe the same mixed repo model and the same source-of-truth boundaries.
+- [ ] Tighten the split between root-skill maintenance guidance and bundled-server guidance so contributors can tell which validation path applies to which surface.
 
-Scope:
+### Tickets
 
-- Expand the Things workflow surface deliberately instead of adding ad hoc helpers.
+- [ ] Keep the root README focused on project shape, usage, packaging, and high-level validation entrypoints.
+- [ ] Maintain a separate CONTRIBUTING guide with grounded setup, workflow, and review expectations for root skills, plugin packaging, and the bundled MCP server.
+- [ ] Keep AGENTS guidance explicit about source-of-truth boundaries, validation commands, and scope-escalation triggers.
+- [ ] Re-run the maintainer guidance audits after doc updates so the subtree stays on the canonical schemas.
 
-Tickets:
+### Exit Criteria
 
-- [ ] Decide whether the next addition should be another skill, MCP server capability, or both.
-- [ ] Keep any new workflow aligned with the repository's canonical mixed-repo model.
+- [ ] The root guidance files pass the maintainer-schema checks without placeholder text or contradictory claims.
+- [ ] A contributor can tell, from the root docs alone, whether their change belongs in `skills/`, `mcp/`, or the thin plugin metadata.
 
-Exit criteria:
+## Backlog Candidates
 
-- [ ] New Things workflow additions fit the same skills-plus-server repository contract.
+- [ ] Expand the repo-root maintainer tooling once more than one root skill needs Python-backed verification.
+- [ ] Add broader bundled-server smoke coverage when new Things tool families or auth-sensitive update flows are introduced.
+- [ ] Revisit packaging mirrors if the repo starts shipping additional host-specific discovery surfaces beyond the current Codex and Claude layout.
 
 ## History
 
 - Completed Milestones 1 through 3 by establishing this repo as the canonical Things skill home, importing the bundled MCP server, and aligning the plugin packaging story around the shared authored surface.
-- Completed Milestone 4 by tightening the repo docs, clarifying which validation runs from repo root versus `mcp/things-app-mcp/`, and keeping the mixed-repo packaging story consistent across the root docs.
+- Completed Milestone 4 by tightening the repo docs, clarifying which validation runs from repo root versus `mcp/`, and keeping the mixed-repo packaging story consistent across the root docs.
+- Opened Milestone 5 to modernize the root guidance contract around a cleaner README and CONTRIBUTING split plus explicit maintainer-schema alignment.
diff --git a/plugins/things-app/mcp/things-app-mcp/.codex/environments/environment.toml b/plugins/things-app/mcp/.codex/environments/environment.toml
similarity index 100%
rename from plugins/things-app/mcp/things-app-mcp/.codex/environments/environment.toml
rename to plugins/things-app/mcp/.codex/environments/environment.toml
diff --git a/plugins/things-app/mcp/things-app-mcp/.gitignore b/plugins/things-app/mcp/.gitignore
similarity index 100%
rename from plugins/things-app/mcp/things-app-mcp/.gitignore
rename to plugins/things-app/mcp/.gitignore
diff --git a/plugins/things-app/mcp/things-app-mcp/.python-version b/plugins/things-app/mcp/.python-version
similarity index 100%
rename from plugins/things-app/mcp/things-app-mcp/.python-version
rename to plugins/things-app/mcp/.python-version
diff --git a/plugins/things-app/mcp/things-app-mcp/Makefile b/plugins/things-app/mcp/Makefile
similarity index 100%
rename from plugins/things-app/mcp/things-app-mcp/Makefile
rename to plugins/things-app/mcp/Makefile
diff --git a/plugins/things-app/mcp/things-app-mcp/README.md b/plugins/things-app/mcp/README.md
similarity index 98%
rename from plugins/things-app/mcp/things-app-mcp/README.md
rename to plugins/things-app/mcp/README.md
index 9cde369d7..4eaeeaae3 100644
--- a/plugins/things-app/mcp/things-app-mcp/README.md
+++ b/plugins/things-app/mcp/README.md
@@ -230,4 +230,4 @@ uv run mypy .
 
 ## License
 
-Covered by the parent [`things-app`](../../README.md) repository license and tracked as part of that repo's combined release surface.
+Covered by the parent [`things-app`](../README.md) repository license and tracked as part of that repo's combined release surface.
diff --git a/plugins/things-app/mcp/things-app-mcp/app/__init__.py b/plugins/things-app/mcp/app/__init__.py
similarity index 100%
rename from plugins/things-app/mcp/things-app-mcp/app/__init__.py
rename to plugins/things-app/mcp/app/__init__.py
diff --git a/plugins/things-app/mcp/things-app-mcp/app/applescript_client.py b/plugins/things-app/mcp/app/applescript_client.py
similarity index 100%
rename from plugins/things-app/mcp/things-app-mcp/app/applescript_client.py
rename to plugins/things-app/mcp/app/applescript_client.py
diff --git a/plugins/things-app/mcp/things-app-mcp/app/server.py b/plugins/things-app/mcp/app/server.py
similarity index 100%
rename from plugins/things-app/mcp/things-app-mcp/app/server.py
rename to plugins/things-app/mcp/app/server.py
diff --git a/plugins/things-app/mcp/things-app-mcp/app/things_client.py b/plugins/things-app/mcp/app/things_client.py
similarity index 100%
rename from plugins/things-app/mcp/things-app-mcp/app/things_client.py
rename to plugins/things-app/mcp/app/things_client.py
diff --git a/plugins/things-app/mcp/things-app-mcp/app/token_store.py b/plugins/things-app/mcp/app/token_store.py
similarity index 100%
rename from plugins/things-app/mcp/things-app-mcp/app/token_store.py
rename to plugins/things-app/mcp/app/token_store.py
diff --git a/plugins/things-app/mcp/things-app-mcp/app/tools.py b/plugins/things-app/mcp/app/tools.py
similarity index 100%
rename from plugins/things-app/mcp/things-app-mcp/app/tools.py
rename to plugins/things-app/mcp/app/tools.py
diff --git a/plugins/things-app/mcp/things-app-mcp/docs/examples.md b/plugins/things-app/mcp/docs/examples.md
similarity index 100%
rename from plugins/things-app/mcp/things-app-mcp/docs/examples.md
rename to plugins/things-app/mcp/docs/examples.md
diff --git a/plugins/things-app/mcp/things-app-mcp/docs/things-route-matrix.md b/plugins/things-app/mcp/docs/things-route-matrix.md
similarity index 100%
rename from plugins/things-app/mcp/things-app-mcp/docs/things-route-matrix.md
rename to plugins/things-app/mcp/docs/things-route-matrix.md
diff --git a/plugins/things-app/mcp/things-app-mcp/pyproject.toml b/plugins/things-app/mcp/pyproject.toml
similarity index 100%
rename from plugins/things-app/mcp/things-app-mcp/pyproject.toml
rename to plugins/things-app/mcp/pyproject.toml
diff --git a/plugins/things-app/mcp/things-app-mcp/scripts/local_fastmcp.sh b/plugins/things-app/mcp/scripts/local_fastmcp.sh
similarity index 100%
rename from plugins/things-app/mcp/things-app-mcp/scripts/local_fastmcp.sh
rename to plugins/things-app/mcp/scripts/local_fastmcp.sh
diff --git a/plugins/things-app/mcp/things-app-mcp/tests/test_applescript_client.py b/plugins/things-app/mcp/tests/test_applescript_client.py
similarity index 100%
rename from plugins/things-app/mcp/things-app-mcp/tests/test_applescript_client.py
rename to plugins/things-app/mcp/tests/test_applescript_client.py
diff --git a/plugins/things-app/mcp/things-app-mcp/tests/test_things_client.py b/plugins/things-app/mcp/tests/test_things_client.py
similarity index 100%
rename from plugins/things-app/mcp/things-app-mcp/tests/test_things_client.py
rename to plugins/things-app/mcp/tests/test_things_client.py
diff --git a/plugins/things-app/mcp/things-app-mcp/tests/test_token_store.py b/plugins/things-app/mcp/tests/test_token_store.py
similarity index 100%
rename from plugins/things-app/mcp/things-app-mcp/tests/test_token_store.py
rename to plugins/things-app/mcp/tests/test_token_store.py
diff --git a/plugins/things-app/mcp/things-app-mcp/tests/test_tools.py b/plugins/things-app/mcp/tests/test_tools.py
similarity index 100%
rename from plugins/things-app/mcp/things-app-mcp/tests/test_tools.py
rename to plugins/things-app/mcp/tests/test_tools.py
diff --git a/plugins/things-app/mcp/things-app-mcp/uv.lock b/plugins/things-app/mcp/uv.lock
similarity index 100%
rename from plugins/things-app/mcp/things-app-mcp/uv.lock
rename to plugins/things-app/mcp/uv.lock