Add Claude and Codex marketplaces and docs skills endpoint builder

.agents/plugins/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "polymorfa",
+  "interface": {"displayName": "Polymorfa"},
+  "plugins": [
+    {
+      "name": "polymorfa",
+      "source": {"source": "local", "path": "./"},
+      "policy": {"installation": "AVAILABLE", "authentication": "ON_INSTALL"},
+      "category": "Developer Tools"
+    }
+  ]
+}

.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "polymorfa",
+  "owner": {
+    "name": "Polymorfa"
+  },
+  "plugins": [
+    {
+      "name": "polymorfa",
+      "source": "./",
+      "description": "Set up Polymorfa integrations using maintained documentation."
+    }
+  ],
+  "description": "Skills and documentation tools for Polymorfa integrations."
+}

.github/workflows/validate.yml

@@ -6,3 +6,4 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - run: python3 scripts/validate.py
+      - run: python3 -m unittest discover -s tests -v

.gitignore

@@ -0,0 +1,2 @@
+/dist/
+__pycache__/

README.md

@@ -4,15 +4,107 @@ Skills and plugin manifests for coding agents integrating Polymorfa. MIT license
 
 ## Install
 
-- Claude Code: clone this repository and run `claude --plugin-dir /absolute/path/to/agent-kit`.
-- Gemini CLI: run `gemini extensions install https://github.com/polymorfa/agent-kit`.
-- Agent Plugins clients: load the repository root containing `plugin.json` through the client's plugin installer.
-- Other skill clients: install the folders under `skills/` through the client's skill installer. Preserve unrelated skills and configuration.
+### Claude Code
 
-Cursor packaging lives in `.cursor-plugin/`. Marketplace publication and native client acceptance are separate from manifest validation.
+After the marketplace change reaches `main`:
+
+```sh
+claude plugin marketplace add polymorfa/agent-kit
+claude plugin install polymorfa@polymorfa
+```
+
+For a local checkout, replace `polymorfa/agent-kit` with its absolute path. To load without installing, run `claude --plugin-dir /absolute/path/to/agent-kit`.
+
+### Codex CLI
+
+Codex supports Git marketplaces. With a CLI version that includes `codex plugin`:
+
+```sh
+codex plugin marketplace add polymorfa/agent-kit
+codex plugin add polymorfa@polymorfa
+```
+
+Start a new session to use the skills and MCP tools. The catalog is `.agents/plugins/marketplace.json`; the existing root `plugin.json`, `mcp.json`, and `skills/` provide the portable plugin. A separate `.codex-plugin/plugin.json` is unnecessary. This uses Polymorfa's repository marketplace, with no OpenAI-curated listing implied. The IDE extension does not support plugins; use the skills-only route below there.
+
+These commands require the catalog on `main`. Local verification used Codex CLI 0.163.0. See OpenAI's [plugin packaging and marketplace guide](https://developers.openai.com/plugins/build/plugins) and [supported plugin surfaces](https://learn.chatgpt.com/docs/plugins).
+
+### Gemini CLI
+
+```sh
+gemini extensions install https://github.com/polymorfa/agent-kit
+```
+
+The extension uses `gemini-extension.json` and `GEMINI.md`. Native Gemini acceptance has not been run here.
+
+### Cursor
+
+Cursor packaging lives in `.cursor-plugin/`. For a published plugin, open Customize, find the plugin, and select Install with project or user scope, as described in [Cursor's plugin guide](https://cursor.com/docs/plugins). Marketplace publication is a separate step; this repository does not establish a published Cursor listing. Until a listing is available, install the skills into your project:
+
+```sh
+npx skills add https://github.com/polymorfa/agent-kit --agent cursor
+```
+
+This installs skills only. It does not configure the bundled documentation MCP. Native Cursor plugin acceptance has not been run here.
+
+### Skills only
+
+From the target project directory:
+
+```sh
+npx skills add https://github.com/polymorfa/agent-kit
+```
+
+Choose the target agent and skills when prompted. Project installation is the default; `--global` changes user configuration. Preserve unrelated skills and configuration. Other skill clients can copy the folders under `skills/` through their skill installer.
+
+Once the docs site serves the generated endpoint, this command will also work:
+
+```sh
+npx skills add https://docs.polymorfa.com
+```
+
+The domain command requires docs deployment. Generating files in this repository does not publish them.
 
 Read [agent setup](https://docs.polymorfa.com/agent-setup/prompt.md) to add the CLI or authenticated API MCP. Existing API credentials remain the supported authentication method; do not configure an unimplemented OAuth login.
 
+## Build the docs skills endpoint
+
+```sh
+python3 scripts/build_skills_index.py
+```
+
+The builder writes `dist/well-known-skills/index.json` and `<skill-name>/<file>` for every file in each `skills/<skill-name>/` folder, including nested references. The index format matches [Stripe's live skills index](https://docs.stripe.com/.well-known/skills/index.json):
+
+```json
+{
+  "skills": [
+    {
+      "name": "polymorfa",
+      "description": "Set up Polymorfa tooling or build a WhatsApp integration with its API, SDK, CLI, or MCP tools.",
+      "files": ["SKILL.md"]
+    }
+  ]
+}
+```
+
+The real index includes both bundled skills. Files are fetched relative to `/.well-known/skills/<name>/`, for example `/.well-known/skills/polymorfa/SKILL.md`.
+
+Generated output is ignored by Git. The docs build should use a pinned agent-kit revision, run the builder, and copy the contents of `dist/well-known-skills/` to the site's `public/.well-known/skills/` directory (or equivalent static root). Serve the index as JSON and the skill files as their original bytes without authentication or HTML fallbacks. This keeps `skills/` as the source and avoids stale committed copies. Docs integration and deployment are outside this repository change.
+
+The builder supports this repository's plain, single-line `name` and `description` frontmatter. It rejects unsupported metadata and symlinks rather than publishing an ambiguous index.
+
 ## Validate
 
-Run `python3 scripts/validate.py`, then check plugin loading and documentation search in your agent.
+```sh
+python3 scripts/validate.py
+claude plugin validate .
+```
+
+The Python validator checks the plugin manifests, both marketplaces, and the rebuilt endpoint's metadata, complete file inventory, and byte equality. For an isolated Claude check, set `CLAUDE_CONFIG_DIR` to a throwaway absolute directory. For Codex use an isolated `CODEX_HOME`.
+
+To test the HTTP endpoint locally, copy the generated directory to a test server root at `.well-known/skills/`, serve that root, and run this from a throwaway project directory:
+
+```sh
+npx skills add http://localhost:18743 --agent codex --skill '*' --yes --copy
+```
+
+Omit `--global` so the install stays in that project. Verify the installed skill files against their sources. Plugin installation, MCP discovery, authenticated API access, and deployed availability are separate checks.

internal/agent-sessions/2026-10-19-marketplace-installs.md

@@ -0,0 +1,65 @@
+# Marketplace install implementation
+
+Date: 2026-10-19. Collaborator: purpshell. Agent: Codex, gpt-6.1-sol, through T3 Code. The thread identifier was not supplied to this session. This is a sanitized checkpoint of visible task instructions and tool results, not a complete transcript. No hidden reasoning, credentials, or customer data is included.
+
+## Scope and source revision
+
+The owner requested Claude and Codex repository marketplace installs, a Stripe-compatible docs skills endpoint builder, validator coverage, README instructions, and a PR against main. No merge, publication, workflow enablement, or automated review request is authorized. The fresh clone started from main at `09df11ff9ae6acecc76bea77e3d8fc9ebf5f0269`. No contribution guide or AGENTS.md exists in this repository. Work stayed in `~/.polymorfa-agent-work/agent-kit-marketplace/` on `feat/marketplace-installs`.
+
+The OpenAI Docs skill was loaded for official source research. The originating monorepo's writing and checkout preservation rules were supplied by the user. No implementation delegation or automated reviewer was used. Roadmap records were not supplied or reconciled; this checkpoint does not claim Linear or Notion synchronization.
+
+## Schema evidence
+
+- [Anthropic marketplace guide](https://code.claude.com/docs/en/plugin-marketplaces): `.claude-plugin/marketplace.json` requires a name, owner, and plugin entries with name and source. Relative sources resolve from the marketplace root. The entry here uses `./`.
+- [OpenAI packaging guide](https://developers.openai.com/plugins/build/plugins): `.agents/plugins/marketplace.json` declares the catalog; `source.path` resolves from its repository root. Root `plugin.json`, `mcp.json`, and `skills/` are supported portable components. No Codex overlay is needed. The guide documents `codex plugin marketplace add owner/repo` and Git ref selection.
+- [OpenAI plugin surfaces](https://learn.chatgpt.com/docs/plugins): Codex CLI supports marketplace plugins and requires a new session after installation. The IDE extension does not support plugins.
+- Installed `codex-cli 0.163.0`: `codex --help` lists `plugin`; `codex plugin marketplace add --help` accepts local paths, owner/repo with optional ref, HTTPS and SSH Git URLs; `codex plugin add --help` accepts `PLUGIN@MARKETPLACE`.
+- [Stripe's live index](https://docs.stripe.com/.well-known/skills/index.json) was fetched. Its shape is `{"skills":[{"name":"...","description":"...","files":["SKILL.md","references/..."]}]}`. Fetching [a listed skill](https://docs.stripe.com/.well-known/skills/stripe-best-practices/SKILL.md) returned Markdown frontmatter, confirming the relative file layout. Stripe content was not copied into this repository.
+- [Cursor plugin guide](https://cursor.com/docs/plugins): native marketplace install uses Customize and an Install action. Marketplace listing requires separate publication. This PR does not submit a listing.
+
+## Verification
+
+All installation writes used task-specific directories outside the user's real agent configuration. The local source is the fresh clone, including this patch.
+
+- `python3 scripts/validate.py`: passed. Rebuilds and validates the skills endpoint alongside existing plugin/MCP checks and the two catalogs.
+- Claude Code `2.1.303`, with `CLAUDE_CONFIG_DIR` set to the absolute task `claude-config` directory:
+  - `claude plugin validate .`: passed without warnings.
+  - `claude plugin validate .claude-plugin/plugin.json`: passed.
+  - `claude plugin marketplace add <absolute-checkout>`: added `polymorfa`.
+  - `claude plugin install polymorfa@polymorfa`: installed version 0.1.0.
+  - `claude plugin details polymorfa`: reported two skills (`polymorfa`, `polymorfa-webhooks`) and one MCP server (`polymorfa-docs`). This is component inventory, not a live MCP search.
+- Codex CLI `0.163.0`, with `CODEX_HOME` set to the absolute task `codex-config` directory:
+  - `codex plugin marketplace add <absolute-checkout> --json`: added `polymorfa`.
+  - `codex plugin add polymorfa@polymorfa --json`: installed 0.1.0 into the isolated plugin cache.
+  - `codex plugin list --json`: reported the plugin installed and enabled.
+- `skills` npm CLI `1.7.2`: `npx --yes skills --help` confirms project install is the default, `--agent` selects the target, `--copy` avoids symlinks, and `--yes` skips prompts. No `--global` option was used.
+  - Copied `dist/well-known-skills/` to a task server root at `.well-known/skills/`.
+  - `python3 -m http.server 18743 --bind 127.0.0.1 --directory <task-site-root>` served it.
+  - From a throwaway task project, `npx --yes skills add http://localhost:18743 --agent codex --skill '*' --yes --copy` found and installed both skills under that project's `.agents/skills/`.
+  - Both installed SKILL.md files matched repository source bytes.
+- Separate builder fixtures under the task directory: nested `references/guide.md` was included and copied; rebuilding removed a stale output file; validation rejected corrupted bytes; building rejected a source symlink.
+- `git diff --check`: passed.
+
+## Availability and handoff
+
+Generated `dist/well-known-skills/` is ignored. The docs build must run the script at a pinned agent-kit revision and copy the generated contents to `public/.well-known/skills/` or an equivalent static root. No docs deployment was performed. The domain install command remains gated on that deployment. Default-branch repository marketplace installs remain gated on merging this PR.
+
+Gemini and Cursor executables were absent. Their native installs were not tested. The existing extension/plugin files and all skill contents remain unchanged. API, SDK, CLI product behavior, Admin, authentication, billing, and customer data are unaffected by these packaging changes. No workflow files were changed or re-enabled.
+
+A useful optional engineering article would compare manifest validation with real isolated installs, using the Claude component inventory and HTTP skill-byte checks as evidence. It would keep unmerged and undeployed availability explicit.
+
+## Remote install checkpoint
+
+At pushed implementation revision `0bd7c800185c5c63d241dab3d001d5fb3fe1e369`, both Git-backed installs also passed in separate task configurations:
+
+```sh
+CLAUDE_CONFIG_DIR=<task>/claude-git-config claude plugin marketplace add 'https://github.com/polymorfa/agent-kit.git#feat/marketplace-installs'
+CLAUDE_CONFIG_DIR=<task>/claude-git-config claude plugin install polymorfa@polymorfa
+CLAUDE_CONFIG_DIR=<task>/claude-git-config claude plugin details polymorfa
+CODEX_HOME=<task>/codex-git-config codex plugin marketplace add polymorfa/agent-kit --ref feat/marketplace-installs --json
+CODEX_HOME=<task>/codex-git-config codex plugin add polymorfa@polymorfa --json
+```
+
+Claude cloned the selected branch and reported two skills and the documentation MCP server. Codex fetched the branch, installed version 0.1.0, and its cache contained the root portable manifest, MCP configuration, and both skill files. Remote and local branch heads matched that SHA.
+
+The skills-only Git path also passed from a second throwaway project: `npx --yes skills add https://github.com/polymorfa/agent-kit --agent cursor --skill '*' --yes --copy` installed both skills. This checks the skills installer with Cursor selected, not the native Cursor runtime.

internal/agent-sessions/2026-10-21-marketplace-review-fixes.md

@@ -0,0 +1,27 @@
+# Marketplace review fixes
+
+Date: 2026-10-21. Collaborator: purpshell. Agent: Codex, gpt-6.1-sol, through T3 Code. This checkpoint records visible instructions and results. A thread identifier and complete transcript were not supplied. It contains no hidden reasoning, credentials or customer data.
+
+The owner authorized fixing unsolicited findings on agent-kit PR #2, committing and pushing normally, and checking hosted CI. Merge and review requests are prohibited. Work used a fresh clone under `~/.polymorfa-agent-work/agentkit2-findings/agent-kit`, on `feat/marketplace-installs`, starting at `eec5dd450a4ba125d7eeb776bebae3b46cb55da6`. No AGENTS.md exists in this repository or its local parent directories. README, both scripts, CI and all three inline review comments were read. The supplied writing policy was applied. No reviewer instructions were executed and no review was requested.
+
+## Verified findings
+
+- Codex comment 4317574028: fixed. The parser accepted descriptions containing YAML comments or mapping delimiters. It now rejects reserved initial characters, surrounding whitespace, whitespace followed by `#`, and `:` followed by whitespace or the end of the value. Ordinary URLs, URL fragments and embedded punctuation remain supported.
+- Codex comment 4317574037: fixed. Malformed ignored JSON prevented validation from reaching its rebuild. The builder now runs before scanning JSON. A subprocess regression checks recovery from malformed index and stale generated JSON, then checks that a malformed source manifest still fails.
+- CodeRabbit comment 4317588739: fixed. Equal, ancestor and descendant output paths could destroy source files. Resolved path containment is checked in both directions before deleting or creating output. Tests cover all overlap directions, a nonexistent descendant and a symlinked ancestor.
+
+## Verification
+
+- `gh api repos/polymorfa/agent-kit/pulls/2/comments` read all three findings as untrusted data.
+- `git fetch origin` and `git rev-list --left-right --count HEAD...origin/main` returned `2 0`. Main remains `09df11ff9ae6acecc76bea77e3d8fc9ebf5f0269`, already an ancestor. No merge is needed.
+- `python3 -m unittest discover -s tests -v` first reproduced all three defects against the original scripts. After fixes all six tests pass. Fixtures use task directories under `~/.polymorfa-agent-work/` and clean up only their own files.
+- `python3 scripts/build_skills_index.py` and `python3 scripts/validate.py` pass.
+- CI retains its validator step and adds the six regression tests. No checks were weakened.
+- `git diff --check` passes.
+- Built the original script from `git show eec5dd45:scripts/build_skills_index.py` into a separate task directory and compared every output file with the rebuilt endpoint. No content changed in `index.json`, `polymorfa/SKILL.md` or `polymorfa-webhooks/SKILL.md`.
+
+## Scope and availability
+
+Content changes are limited to `.github/workflows/validate.yml`, `scripts/build_skills_index.py`, `scripts/validate.py`, `tests/test_skills_index.py` and this checkpoint. Skill source files, generated output bytes, manifests and installer instructions remain unchanged. The docs site can continue using its pinned skill bytes; adopting these builder safeguards requires updating its pinned revision separately.
+
+No library, runner, Temporal, API, Admin/MCP, logging, Inspector, Console, SDK, product CLI, Help Center, marketing, billing, flag or release-contract behavior changed. No native installation retest is claimed for this Python-only follow-up. No docs deployment, roadmap synchronization, merge or publication was performed. Hosted CI results belong to the final pushed revision and are reported separately at handoff.