fix: various multi-host fixes (#10)

## Summary

Brings the plugin in line with where each host actually is today (Claude
Code, Codex CLI 0.125+, Cursor, Gemini CLI, OpenCode), and starts
pushing the install path through native marketplace commands instead of
shell scripts.

## What's in here

**Hooks**
The session-start hook used to be a single bash script that printed a
static banner. It's now split into a small detection library
(`hooks/lib/`) and a thin emitter, with PowerShell and Node ports so the
same logic runs on every host. The detector scans the project for
signals (`pyproject.toml` deps, Python imports, file globs) and injects
targeted reminders to use the relevant skill — `litestar`, `sqlspec`,
`advanced-alchemy`, `litestar-saq`, etc. The matcher map is data-only
(`hooks/lib/skill-map.json`) so new skills just add an entry.
`LITESTAR_SKILLS_HOOK_DISABLE=1` opts out.

**Codex plugin layout**
Codex 0.125 stopped accepting `source.path: \"./\"` for a marketplace,
so the plugin moved to a nested layout under
`.agents/plugins/plugins/litestar-skills/`. Marketplace config lives at
`.agents/plugins/marketplace.json`. `.gitignore` got a narrow carve-out
so just those two paths are tracked — the rest of `.agents/` stays
authoring-only.

**Subagents**
The four host-specific dialects (Claude / Codex / Gemini / OpenCode) of
`litestar-reviewer` were drifting whenever one was edited. They're now
generated from a single YAML source via `tools/generate-agents.py`, with
a CI check that fails on hand-edits. To change the agent: edit the YAML,
run `make agents`, commit both.

**OpenCode plugin**
The plugin file used to be an empty stub. It's now a real plugin that
injects skill reminders into the system prompt via
`experimental.chat.system.transform` and respects
`managedConfig.disabledPlugins` / `allowedPlugins` so org policy
actually takes effect.

**Policy & install docs**
Added `docs/policy.md` covering per-host allow/ask/deny grammar and
managed-settings paths, plus a drop-in
`templates/managed-settings/claude-code.json`. Gemini's `excludeTools`
now ships opinionated defaults blocking `sudo`, `rm -rf /*`, and `* |
sh`/`* | bash` patterns. Each host got its own `INSTALL.md` and the
README has a real support-tier matrix.

**Validation**
The Claude `userConfig` schema is now enforced (camelCase keys, valid
types, required `title`); deprecated `decision: approve|block` and
undocumented `${CLAUDE_PLUGIN_DATA}` are rejected. `make check`
validates the four hook manifests, mirrors flow's
`validate-codex-manifest.py`, and the agent generator drift gate.

**Distribution**
`docs/submission-tracker.md` lays out a 3-phase rollout (zero-gatekeeper
→ form/PR → async/blocked) so submissions to skills.sh, the Anthropic
community directory, openai/skills, and the various awesome-* lists are
tracked rather than ad-hoc. README points users at `npx skills add
litestar-org/litestar-skills`.

## Verification

- `make check` is clean (lint, type-check, 100 tests, manifest sync at
0.1.2 across 13 files, agent drift gate, Codex manifest validator).
- `claude plugin tag .claude-plugin --dry-run` accepts the manifest.
- `codex plugin marketplace add .` accepts the marketplace.
- Reference: same-author multi-host plugin at `~/code/c/flow` learned a
lot of these things the hard way; this PR ports the patterns over.

Author: cofin

.agents/plugins/marketplace.json

@@ -0,0 +1,31 @@
+{
+  "name": "litestar-marketplace",
+  "interface": {
+    "displayName": "Litestar Skills",
+    "shortDescription": "First-party Litestar framework skills: handlers, DTOs, DI, plugins, MCP, SAQ, Granian, SQLSpec, Advanced Alchemy"
+  },
+  "metadata": {
+    "description": "The Litestar Marketplace — opinionated first-party skills, plugins, subagents, commands, and MCP servers for Litestar and its ecosystem"
+  },
+  "owner": {
+    "name": "litestar-org",
+    "url": "https://github.com/litestar-org"
+  },
+  "plugins": [
+    {
+      "name": "litestar-skills",
+      "version": "0.1.2",
+      "description": "Opinionated first-party agent skills, plugins, subagents, slash commands, and MCP servers for the Litestar framework ecosystem",
+      "source": { "source": "local", "path": "./plugins/litestar-skills" },
+      "policy": { "installation": "AVAILABLE" },
+      "category": "Development",
+      "author": {
+        "name": "Cody Fincher",
+        "email": "cofin@litestar.dev"
+      },
+      "homepage": "https://github.com/litestar-org/litestar-skills",
+      "license": "MIT",
+      "keywords": ["litestar", "skills", "sqlspec", "advanced-alchemy", "msgspec", "dishka", "granian", "saq", "vite", "mcp"]
+    }
+  ]
+}

.codex-plugin/plugin.json …itestar-skills/.codex-plugin/plugin.json.codex-plugin/plugin.json renamed to .agents/plugins/plugins/litestar-skills/.codex-plugin/plugin.json .codex-plugin/plugin.json renamed to .agents/plugins/plugins/litestar-skills/.codex-plugin/plugin.json

@@ -0,0 +1,76 @@
+# Claude Code — Install
+
+## One-line install (recommended)
+
+Inside a Claude Code session:
+
+```text
+/plugin marketplace add litestar-org/litestar-skills
+/plugin install litestar-skills@litestar-marketplace
+```
+
+The `/plugin` commands run **inside** Claude Code — they cannot be automated from a shell. Claude prompts for any `userConfig` values on first install (none today), then enables the plugin.
+
+## What gets loaded
+
+| Path | Loaded by Claude as |
+| --- | --- |
+| `skills/<name>/SKILL.md` | Skills (description-based auto-activation) |
+| `commands/<prefix>/<command>.toml` | Slash commands (e.g. `/litestar:new-app`) |
+| `.claude-plugin/agents/<name>.md` | Subagents (PascalCase tool list dialect) |
+| `hooks/hooks-claude.json` → `hooks/session-start.sh` | SessionStart hook injecting Litestar skill reminders |
+
+## Project-local install (less common)
+
+If you want the plugin scoped to one project rather than your user directory:
+
+```bash
+git clone https://github.com/litestar-org/litestar-skills .claude-plugin-local
+```
+
+Then in `.claude/settings.json`:
+
+```json
+{
+  "plugins": [".claude-plugin-local"]
+}
+```
+
+Most users should prefer the marketplace install — Claude handles updates, version pinning, and `userConfig` migration for you.
+
+## Updating
+
+```text
+/plugin marketplace update litestar-marketplace
+/plugin update litestar-skills@litestar-marketplace
+```
+
+## Verifying the install
+
+In a Claude Code session:
+
+```text
+/status
+```
+
+Should show `litestar-skills` under enabled plugins. Open a Litestar project (one with `litestar` in `pyproject.toml`) and a fresh session — the SessionStart hook injects a context paragraph naming `litestar-skills:litestar` (plus any other detected skills).
+
+## Restricting capabilities
+
+Claude Code is the only host with a mature allow/ask/deny grammar. See [`docs/policy.md`](../docs/policy.md) for per-rule syntax and managed-settings paths. A drop-in template for org-managed installs lives at [`templates/managed-settings/claude-code.json`](../templates/managed-settings/claude-code.json).
+
+To deny a specific litestar-skills skill:
+
+```json
+{
+  "permissions": {
+    "deny": ["Skill(litestar-skills:litestar-deployment)"]
+  }
+}
+```
+
+## Troubleshooting
+
+- **`Unrecognized key: "displayName"`** — your local clone is on a stale revision. Pull main; root-level `displayName` was removed (it's only valid inside marketplace.json plugin entries, not in plugin.json).
+- **Hook doesn't inject context** — ensure the session was started in a directory containing `pyproject.toml`. The hook short-circuits silently when no Litestar-ecosystem signals are detected. Override with `LITESTAR_SKILLS_HOOK_DISABLE=1` to confirm the hook is firing.
+- **`/status` doesn't show the plugin** — `/plugin marketplace add` and `/plugin install` are separate steps. Run both.

.claude-plugin/INSTALL.md

@@ -20,7 +20,8 @@
       "homepage": "https://github.com/litestar-org/litestar-skills",
       "license": "MIT",
       "keywords": ["litestar", "skills", "sqlspec", "advanced-alchemy", "msgspec", "dishka", "granian", "saq", "vite", "mcp"],
-      "category": "Development"
+      "category": "Development",
+      "policy": { "installation": "AVAILABLE" }
     }
   ]
 }

.claude-plugin/marketplace.json

@@ -1,6 +1,5 @@
 {
   "name": "litestar-skills",
-  "displayName": "Litestar Skills",
   "description": "Opinionated first-party agent skills, plugins, subagents, slash commands, and MCP servers for the Litestar framework ecosystem",
   "version": "0.1.2",
   "author": {
@@ -13,5 +12,6 @@
   "keywords": ["litestar", "skills", "agent", "ai", "sqlspec", "advanced-alchemy", "granian", "msgspec", "dishka", "mcp"],
   "skills": ["./skills/"],
   "commands": ["./commands/"],
-  "agents": ["./.claude-plugin/agents/litestar-reviewer.md"]
+  "agents": ["./.claude-plugin/agents/litestar-reviewer.md"],
+  "hooks": "./hooks/hooks-claude.json"
 }

.claude-plugin/plugin.json

@@ -1,66 +1,69 @@
 # Codex CLI — Install
 
-Three install paths.
+> **Codex CLI 0.125+** is required. Earlier versions accept the `source: "./"` marketplace shape but newer versions reject it.
 
-## Option 1: User-level plugin (recommended)
+## Option 1: Marketplace install (recommended)
 
 ```bash
-git clone https://github.com/litestar-org/litestar-skills ~/.codex/plugins/litestar-skills
+codex plugin marketplace add litestar-org/litestar-skills
+```
+
+Then in a Codex session:
+
+```text
+/plugins
 ```
 
-Codex auto-discovers plugins in `~/.codex/plugins/`. The clone includes `.codex/agents/litestar-reviewer.toml` (pure-TOML custom agent; tools inherited from your session `config.toml`).
+Enable `litestar-skills` from the list. The plugin manifest lives at `.agents/plugins/plugins/litestar-skills/.codex-plugin/plugin.json`; the marketplace catalog is `.agents/plugins/marketplace.json` at the repo root.
 
-## Option 2: Repo-scoped marketplace (team)
+## Option 2: Local marketplace (for development)
 
-For a single project, clone into the repo's `plugins/` directory and register a local marketplace:
+If you have the repo cloned and want Codex to pick up your local changes:
 
 ```bash
-mkdir -p plugins
-git clone https://github.com/litestar-org/litestar-skills plugins/litestar-skills
-mkdir -p .codex
-cat > .codex/marketplace.json <<'EOF'
-{
-  "name": "litestar-marketplace",
-  "description": "The Litestar Marketplace — opinionated first-party skills, plugins, subagents, commands, and MCP servers for Litestar and its ecosystem",
-  "plugins": [
-    { "name": "litestar-skills", "source": "./plugins/litestar-skills" }
-  ]
-}
-EOF
+codex plugin marketplace add /path/to/litestar-skills
 ```
 
-## Option 3: Skills-only via `.agents/skills/`
+Codex auto-discovers the marketplace at `.agents/plugins/marketplace.json` and the nested plugin under `.agents/plugins/plugins/litestar-skills/`.
 
-If you only want the skills (no plugin metadata or custom agent), clone and copy:
+## Option 3: User-level clone (legacy fallback)
 
 ```bash
-git clone --depth 1 https://github.com/litestar-org/litestar-skills /tmp/litestar-skills
-mkdir -p .agents/skills
-cp -r /tmp/litestar-skills/skills/* .agents/skills/
+git clone https://github.com/litestar-org/litestar-skills ~/.codex/plugins/litestar-skills
 ```
 
-Codex reads `.agents/skills/` natively at session start.
+Codex auto-discovers plugins under `~/.codex/plugins/`. Provided as a fallback for environments where `codex plugin marketplace add` is unavailable.
 
 ## Custom agents
 
-Codex custom agents live in `.codex/agents/*.toml` and are discovered automatically when the plugin is installed. The repo ships `litestar-reviewer` — invoke with `$agent litestar-reviewer` inside Codex.
+Codex custom agents live in `.codex/agents/*.toml` (pure TOML; tools inherited from session `config.toml`). The repo ships `litestar-reviewer` — invoke with `$agent litestar-reviewer` inside Codex.
+
+The four host-dialect agent files are generated from canonical YAML sources at `tools/agent-sources/<name>.yaml`. Run `make agents` after editing the source.
 
 ## Updating
 
+```bash
+codex plugin marketplace upgrade litestar-marketplace
+```
+
+For Option 3:
+
 ```bash
 cd ~/.codex/plugins/litestar-skills && git pull
 ```
 
 ## Verification
 
-Inside Codex:
+In a Codex session:
 
 ```text
 $skill list | grep litestar
 $agent list | grep litestar-reviewer
 ```
 
-## Disabling Specific Skills
+The SessionStart hook (`hooks/session-start.sh`, dispatched via `hooks/hooks-codex.json`) should inject project-aware Litestar skill reminders into the session context.
+
+## Disabling specific skills
 
 Edit `~/.codex/config.toml`:
 
@@ -69,3 +72,13 @@ Edit `~/.codex/config.toml`:
 path = "/path/to/skill/SKILL.md"
 enabled = false
 ```
+
+## Why the nested layout
+
+Codex CLI 0.125.0+ requires local marketplace `source.path` to:
+
+1. Start with `./`
+2. Be a non-empty subdirectory (rejects `./` alone)
+3. Contain no `..` traversal
+
+That's why the plugin lives under `./plugins/litestar-skills` (relative to `.agents/plugins/marketplace.json`) instead of being collocated with the marketplace file.

.codex/INSTALL.md

@@ -0,0 +1,52 @@
+# Cursor — Install
+
+## In-editor install
+
+Inside Cursor:
+
+```text
+/add-plugin
+```
+
+Then search for `litestar-skills` (once the plugin is approved on the Cursor marketplace — submission is pending; see [docs/roadmap.md](../docs/roadmap.md)).
+
+## Local-development install
+
+Until the plugin lands on the Cursor marketplace, install it locally:
+
+```bash
+mkdir -p ~/.cursor/plugins/local
+ln -s "$(pwd)" ~/.cursor/plugins/local/litestar-skills
+```
+
+Then restart Cursor. The plugin manifest at `.cursor-plugin/plugin.json` is auto-discovered.
+
+## What gets loaded
+
+| Path | Loaded by Cursor as |
+| --- | --- |
+| `skills/<name>/SKILL.md` | Skills (agentskills.io standard, adopted in Cursor 2.4+) |
+| `commands/<prefix>/<command>.toml` | Slash commands |
+| `hooks/hooks-cursor.json` → `hooks/session-start.sh` | SessionStart hook |
+
+## Updating
+
+If installed via the local symlink, just `git pull` in the cloned directory:
+
+```bash
+cd ~/.cursor/plugins/local/litestar-skills && git pull
+```
+
+## Restricting capabilities
+
+Cursor has no documented public deny grammar today. Restriction options:
+
+- Uninstall via `/remove-plugin`
+- Team / Enterprise plans support private team marketplaces with central governance — talk to your Cursor admin
+
+See [`docs/policy.md`](../docs/policy.md) for the full per-host reference.
+
+## Troubleshooting
+
+- **Plugin not discovered** — ensure the symlink target points at the repo root (the directory containing `.cursor-plugin/plugin.json`), not at `.cursor-plugin/` itself.
+- **Hook doesn't fire** — Cursor's SessionStart hook reads `./hooks/hooks-cursor.json`; ensure the `hooks` field in `.cursor-plugin/plugin.json` is present (it is, as of v0.2).

.cursor-plugin/INSTALL.md

@@ -13,5 +13,10 @@
   "keywords": ["litestar", "skills", "agent", "ai", "sqlspec", "advanced-alchemy"],
   "skills": "./skills/",
   "commands": "./commands/",
-  "hooks": "./hooks/hooks-cursor.json"
+  "hooks": "./hooks/hooks-cursor.json",
+  "interface": {
+    "displayName": "Litestar Skills",
+    "shortDescription": "First-party Litestar framework skills: handlers, DTOs, DI, plugins, MCP, SAQ, Granian, SQLSpec, Advanced Alchemy",
+    "category": "Development"
+  }
 }

.cursor-plugin/plugin.json

@@ -0,0 +1,54 @@
+# Gemini CLI — Install
+
+## One-line install (recommended)
+
+```bash
+gemini extensions install https://github.com/litestar-org/litestar-skills --auto-update
+```
+
+Gemini auto-indexes the repo into its [extension gallery](https://geminicli.com/extensions/) via the `gemini-cli-extension` GitHub topic.
+
+## What gets loaded
+
+| Path | Loaded by Gemini as |
+| --- | --- |
+| `skills/<name>/SKILL.md` | Skills (agentskills.io standard) |
+| `commands/<prefix>/<command>.toml` | Slash commands |
+| `agents/<name>.md` | Subagents (YAML-list tool dialect) |
+| `hooks/hooks.json` (auto-discovered) → `hooks/session-start.sh` | SessionStart hook |
+| `gemini-extension.json` `excludeTools` | Tool denylist (sudo, rm -rf, curl\|sh, etc.) |
+| `GEMINI.md` | Per-host context file (auto-loaded) |
+
+The hook manifest at `hooks/hooks.json` uses Gemini's `${extensionPath}${/}` substitution + a `bun || node || bash` multi-runtime fallback so the SessionStart hook works on any machine.
+
+## Updating
+
+```bash
+gemini extensions update litestar-skills
+```
+
+## Verifying the install
+
+In a Gemini session, ask: *"What Litestar skills are available?"* — Gemini should list the skills loaded from this extension. Or check the gallery:
+
+```bash
+gemini extensions list | grep litestar
+```
+
+## Restricting capabilities
+
+Gemini ships a denylist via `excludeTools` in `gemini-extension.json`. The repo ships defenses against:
+
+- All `sudo` invocations (bare, prefixed, semicolon-chained, embedded, piped)
+- Destructive `rm -rf` against root, `$HOME`, and `~`
+- `curl | sh`, `wget | sh`, and any `*|sh`/`*|bash` install-script piping
+
+See [`docs/policy.md`](../docs/policy.md) for the full pattern list.
+
+**Caveat:** Gemini's `excludeTools` does NOT apply to MCP servers bundled with the extension itself ([gemini-cli #8481](https://github.com/google-gemini/gemini-cli/issues/8481)). Treat it as belt-and-suspenders, not a hard guarantee.
+
+## Troubleshooting
+
+- **`gemini extensions install` fails on a fresh clone** — the manifest is `gemini-extension.json` at the repo root (sibling of `README.md`). If the file isn't present, your checkout may be on a pre-Gemini-support revision.
+- **Hook doesn't inject context** — the hook short-circuits silently when no Litestar-ecosystem signals are detected in the cwd. Override with `LITESTAR_SKILLS_HOOK_DISABLE=1` to confirm it's firing. The hook scans `pyproject.toml`, Python imports (capped), and a curated set of file globs (`Dockerfile`, `Chart.yaml`, `*.tf`, etc.).
+- **`bun`/`node` not found at hook time** — the multi-runtime fallback ends with `bash` so a system without Bun or Node still gets the hook.

.gemini/INSTALL.md

@@ -32,8 +32,16 @@ build/
 # Host-local settings (may contain per-machine paths or tokens)
 .claude/settings.local.json
 
-# Flow framework state — local-only per project convention
-.agents/
+# Flow framework state — local-only per project convention.
+# `.agents/*` (NOT `.agents/`) so git descends into the directory and honors
+# the `!`-includes below. Codex CLI 0.125+ requires the marketplace file at
+# `.agents/plugins/marketplace.json` AND a nested plugin subtree at
+# `.agents/plugins/plugins/<name>/` (because Codex rejects `source.path: "./"`).
+.agents/*
+!.agents/plugins/
+.agents/plugins/*
+!.agents/plugins/marketplace.json
+!.agents/plugins/plugins/
 .beads/
 
 # Beads / Dolt internals