Move things-app bundled MCP to a top-level directory

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.

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:

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:

plugins/things-app/.mcp.json

@@ -6,6 +6,6 @@
       "python",
       "app/server.py"
     ],
-    "cwd": "../../mcp/things-app-mcp"
+    "cwd": "../../mcp"
   }
 }

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.

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.