plugin: add SpeakSwiftly launchagent setup skill (#8)

Author: gaelic-ghost

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "speak-swiftly-server",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "Repo-local Codex plugin for the SpeakSwiftlyServer MCP surface, focused operator skills, and shared local MCP configuration.",
   "author": {
     "name": "Gale",
@@ -23,7 +23,7 @@
   "interface": {
     "displayName": "SpeakSwiftly",
     "shortDescription": "Local speech and playback workflows for Codex.",
-    "longDescription": "Repo-local Codex plugin for the SpeakSwiftlyServer MCP surface, including focused skills for runtime operation, voice workflows, and text-profile authoring.",
+    "longDescription": "Repo-local Codex plugin for the SpeakSwiftlyServer MCP surface, including focused skills for LaunchAgent setup, runtime operation, voice workflows, and text-profile authoring.",
     "developerName": "Gale",
     "category": "Productivity",
     "capabilities": [
@@ -33,6 +33,8 @@
     "websiteURL": "https://github.com/gaelic-ghost/SpeakSwiftlyServer",
     "defaultPrompt": [
       "Use SpeakSwiftly to read this reply aloud.",
+      "Set up SpeakSwiftly on this machine as a background service.",
+      "Help me install or validate the SpeakSwiftly LaunchAgent service.",
       "Inspect the local SpeakSwiftly runtime and queue state.",
       "Create or edit a SpeakSwiftly text profile."
     ]

.mcp.json

@@ -3,7 +3,7 @@
     "speak_swiftly": {
       "type": "http",
       "url": "http://127.0.0.1:7337/mcp",
-      "note": "Connects to the local SpeakSwiftlyServer MCP surface exposed by the shared HTTP server. The usual live local service listens on APP_PORT=7337 with APP_MCP_PATH=/mcp, but built-in runtime defaults keep APP_MCP_ENABLED=false until MCP is turned on through APP_CONFIG_FILE or APP_MCP_ENABLED=true."
+      "note": "Connects to the local SpeakSwiftlyServer MCP surface exposed by the shared HTTP server. When this plugin is installed through a Codex marketplace, the plugin provides the Codex-side MCP registration for this endpoint. The live service still needs to expose /mcp on 127.0.0.1:7337, and built-in runtime defaults keep APP_MCP_ENABLED=false until MCP is turned on through APP_CONFIG_FILE or APP_MCP_ENABLED=true."
     }
   }
 }

README.md

@@ -225,11 +225,12 @@ print(layout.runtimeProfileRootURL.path)
 
 ## Codex Plugin
 
-This repository is also packaged as a repo-local Codex plugin through [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json). The plugin points at the checked-in [`.mcp.json`](./.mcp.json) connection for the local `speak_swiftly` MCP server and the tracked [skills](./skills/) bundle that teaches Codex how to use the surface intentionally.
+This repository is also packaged as a repo-local Codex plugin through [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json). The plugin points at the checked-in [`.mcp.json`](./.mcp.json) connection for the local `speak_swiftly` MCP server and the tracked [skills](./skills/) bundle that teaches Codex how to use the surface intentionally. When the plugin is installed through a Codex marketplace, Codex installs the plugin into its plugin cache and loads that installed copy from there, so the plugin surface is the normal Codex-side MCP wiring path. Users should not need to add a second handwritten global MCP entry just to reach the local server.
 
-The first plugin pass currently ships four focused skills:
+The first plugin pass currently ships five focused skills:
 
 - [`speak-swiftly-mcp`](./skills/speak-swiftly-mcp/SKILL.md) for broad MCP orientation and workflow selection
+- [`speak-swiftly-launchagent-setup`](./skills/speak-swiftly-launchagent-setup/SKILL.md) for installing, refreshing, validating, and removing the per-user LaunchAgent-backed service
 - [`speak-swiftly-runtime-operator`](./skills/speak-swiftly-runtime-operator/SKILL.md) for runtime state, playback, queue, and request control
 - [`speak-swiftly-voice-workflows`](./skills/speak-swiftly-voice-workflows/SKILL.md) for voice profiles, live speech, and retained artifacts
 - [`speak-swiftly-text-profiles`](./skills/speak-swiftly-text-profiles/SKILL.md) for normalization styles, stored profiles, and replacement editing

skills/speak-swiftly-launchagent-setup/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: speak-swiftly-launchagent-setup
+description: Use when a user wants to set up SpeakSwiftlyServer on their machine as a per-user LaunchAgent, or needs to install, refresh, promote, inspect, validate, troubleshoot, or remove that background service. This skill covers the supported launch-agent CLI workflow, plugin-aware Codex access expectations, required config-file checks, staged-artifact expectations, and end-to-end HTTP plus MCP health verification.
+---
+
+# SpeakSwiftly LaunchAgent Setup
+
+Use this skill when the user wants the standalone `SpeakSwiftlyServer` to run as a per-user background service managed by `launchd`.
+
+## Start Here
+
+- Use the supported `SpeakSwiftlyServerTool launch-agent ...` commands instead of hand-editing property lists or calling `launchctl` directly.
+- Read the repo operator guidance in [README.md](../../README.md) first, then [LaunchAgent-Workflow.md](../../Sources/SpeakSwiftlyServer/SpeakSwiftlyServer.docc/Articles/LaunchAgent-Workflow.md) when the user needs the full setup model.
+- If the user is asking about Codex access to the running service, remember that the installed plugin already handles the Codex-side MCP registration through [`.mcp.json`](../../.mcp.json). The setup work here is about getting the live server healthy at `http://127.0.0.1:7337/mcp`, not about hand-editing Codex config files.
+- Phrase the setup outcome in user terms like "set up SpeakSwiftly on this machine," "install the background service," "make the local service reachable from Codex," or "fix the LaunchAgent install," because those are the kinds of requests this skill should trigger on.
+
+## Normal Setup Flow
+
+1. Print the property list first with `xcrun swift run SpeakSwiftlyServerTool launch-agent print-plist`.
+2. Confirm the config file the service should use. The standard live-service path is `~/Library/Application Support/SpeakSwiftlyServer/server.yaml` unless the user explicitly wants another file.
+3. If the staged live artifact is already the intended executable, run `xcrun swift run SpeakSwiftlyServerTool launch-agent install --config-file /absolute/path/to/server.yaml`.
+4. If the user wants the current checkout to become the live service now, run `xcrun swift run SpeakSwiftlyServerTool launch-agent promote-live --config-file /absolute/path/to/server.yaml`.
+5. Verify the result with `xcrun swift run SpeakSwiftlyServerTool healthcheck`.
+
+## When To Use Each Command
+
+- `launch-agent print-plist`:
+  Use before install work or when the user wants to inspect exactly what will be staged into `~/Library/LaunchAgents`.
+- `launch-agent install --config-file ...`:
+  Use when the staged release artifact under `.release-artifacts/current` is already the executable the user wants `launchd` to boot.
+- `launch-agent promote-live --config-file ...`:
+  Use when the intent is "make this checkout become the live service now." This rebuilds and stages the release artifact first, then refreshes the LaunchAgent install.
+- `launch-agent status`:
+  Use when the user wants to inspect the installed state, label, plist location, or staged executable details.
+- `launch-agent uninstall`:
+  Use when the user explicitly wants the per-user background service removed.
+- `healthcheck`:
+  Use after install, promotion, config changes, or troubleshooting. It is the supported end-to-end probe for both HTTP and MCP.
+
+## Validation And Troubleshooting
+
+- Treat `healthcheck` as the primary verification path because it probes `GET /healthz`, reads `GET /runtime/host`, and sends a real MCP `initialize` request to `/mcp`.
+- If the HTTP process is healthy but Codex still cannot use the MCP surface, do not jump straight to telling the user to edit Codex config. First check whether the server is actually exposing `/mcp`. The plugin install should already handle the Codex-side connection; the remaining failure is usually that MCP is disabled in the server config or environment. The MCP endpoint exists only when `APP_MCP_ENABLED=true` or the config file enables MCP.
+- If the user wants to understand whether the live background service is using the staged artifact or a different executable, rely on `launch-agent status`, install output, and the printed plist rather than inferring from filesystem timestamps alone.
+- If the user needs queue, playback, or backend control after the service is already installed, switch to `$speak-swiftly-runtime-operator` instead of stretching this skill into runtime operations.
+- If the question is about using the live MCP surface from Codex after setup, switch to `$speak-swiftly-mcp`.