@orchid-labs/pluxx 0.1.0 → 0.1.3

package/README.md

@@ -1,573 +1,168 @@
 # pluxx
 
-**Build AI agent plugins once. Ship them everywhere.**
+**The cross-host compiler for MCP-backed plugins.**
 
-pluxx generates native plugin packages for Claude Code, Cursor, Codex, and OpenCode from a single config file. One source of truth — platform-specific outputs with the right manifests, rules, install scripts, hook handling, and MCP config when your plugin needs it.
+Import a raw MCP or an existing host-native plugin, keep one maintained source project, and compile native outputs for **Claude Code, Cursor, Codex, and OpenCode**.
 
-The product scope is intentionally tight:
+Pluxx is the authoring, maintenance, and compilation layer for MCP teams that want one source of truth instead of separate per-host plugin repos.
 
-- Pluxx owns the common cross-host plugin-authoring primitives
-- Pluxx does not try to model every host-specific extension feature yet
+- Docs: [docs.pluxx.dev](https://docs.pluxx.dev/)
+- Website: [pluxx.dev](https://pluxx.dev/)
 
-pluxx is Bun-first today. Use `bunx` or run it from a Bun workspace. The npm package includes a small launcher for global installs, but it still requires Bun at runtime.
+## Why Pluxx
 
-```bash
-bunx pluxx build
-```
-
-```
-dist/
-  claude-code/   .claude-plugin/plugin.json, .mcp.json, CLAUDE.md, hooks/hooks.json, skills
-  cursor/        .cursor-plugin/plugin.json, mcp.json, hooks/hooks.json, AGENTS.md, rules/
-  codex/         .codex-plugin/plugin.json, .mcp.json, AGENTS.md, interface metadata
-```
-
-## Platform Support
-
-| Platform | Status | Validated |
-|----------|--------|-----------|
-| **Claude Code** | Primary | `claude plugin validate` PASSED |
-| **Cursor** | Primary | Docs-audited, hooks + rules covered in lint |
-| **Codex** | Primary | Docs-audited, plugin packaging aligned; hooks remain external Codex config |
-| **OpenCode** | Primary | Generates JS/TS wrapper, active docs-parity work |
-| GitHub Copilot | Beta | Reuses Claude Code format (confirmed compatible) |
-| OpenHands | Beta | Generates .plugin/ manifest, needs live testing |
-| Warp | Beta | Generates skills + AGENTS.md |
-| Gemini CLI | Beta | Generates gemini-extension.json |
-| Roo Code | Beta | Generates .roorules + skills |
-| Cline | Beta | Generates .clinerules + skills |
-| AMP | Beta | Generates AGENT.md + skills |
-
-**Primary** = first-class launch target, actively maintained.
-**Beta** = generated, but less validated against live tool behavior.
-
-The mechanically generated source of truth for support and verification is [docs/compatibility.md](./docs/compatibility.md).
-
-If you want the operational version of the docs, start with the [Practical handbook](./docs/practical-handbook.md).
-If you want the explicit authoring walkthrough, use [Create a Pluxx plugin](./docs/create-a-pluxx-plugin.md).
-If you want the meta guide for using Pluxx *inside* Claude/Codex/Cursor/OpenCode, use [Use Pluxx in host agents](./docs/use-pluxx-in-host-agents.md).
-If you want the tightened product scope for what Pluxx should model first, use [Core primitives](./docs/core-primitives.md).
-If you want the current execution queue with milestones, dependencies, and delegated subtasks, use [Roadmap](./docs/roadmap.md).
-If you want the implementation target for release orchestration, use [publish v1 contract](./docs/publish-v1-contract.md).
-If you are planning marketplace-aware release flows, use [Marketplace submission prep](./docs/marketplace-submission-prep.md).
-
-## Why?
+Every host has different plugin contracts and different places to express the same intent:
 
-Tools like `npx skills` install SKILL.md files across agents. That covers **skills**.
+- manifests
+- instructions and rules
+- hook surfaces
+- agents and subagents
+- permission and approval controls
+- MCP auth wiring
+- brand and packaging metadata
 
-But a plugin is more than skills. A plugin bundles:
+Without Pluxx, those details drift across multiple repos. With Pluxx, you keep one source project and compile honest host-native outputs.
 
-| Component | What pluxx handles |
-|-----------|---------------------|
-| **Manifests** | `.claude-plugin/plugin.json` vs `.cursor-plugin/plugin.json` vs `.codex-plugin/plugin.json` |
-| **MCP auth** | Claude Code uses `headers`, Codex uses `bearer_token_env_var` plus `env_http_headers` / `http_headers`, Cursor uses Claude Desktop format |
-| **Hooks** | Different event names, different JSON schemas, and in Codex's case a separate runtime config path |
-| **Rules** | `CLAUDE.md` vs `rules/*.mdc` vs `AGENTS.md` |
-| **Brand metadata** | Codex has icons, colors, screenshots, default prompts. Others don't. |
-| **Subagents** | Different formats per platform |
+Pluxx is built around an explicit compiler model:
 
-Without pluxx you maintain separate copies for each platform. With pluxx you maintain one.
+- `preserve` when a primitive maps cleanly to a host-native surface
+- `translate` when the same intent belongs in a different host surface
+- `degrade` when a host only supports a weaker equivalent
+- `drop` when the host has no truthful native equivalent
 
-That value exists even if your plugin has no MCP at all. If you are hand-authoring skills, instructions, hooks, commands, or brand metadata, Pluxx still gives you one maintainable cross-host plugin project.
+That keeps the cross-host story explicit instead of pretending every platform works the same way.
 
-The sharpest launch wedge is still MCP-first authoring: start from an existing MCP server, generate a maintainable plugin scaffold, then keep shipping from one config.
+## Platform Focus
 
-## Core Primitives
+Pluxx is currently centered on the core four:
 
-Pluxx treats these as the canonical authoring model:
+- Claude Code
+- Cursor
+- Codex
+- OpenCode
 
-- `skills`
-- `instructions`
-- `mcp`
-- `userConfig`
-- `commands`
-- `agents`
-- `hooks`
-- `permissions`
-- `brand`
-- `assets/scripts`
-- `taxonomy`
+Other targets still exist as generated secondary/beta outputs, but the product and docs are intentionally optimized around the core four.
 
-These are the primitives that show up repeatedly in real plugins and real host integrations.
-
-## What Pluxx Does Not Model Yet
-
-These features exist in one or more hosts, but they are not the current product center:
-
-- `outputStyles`
-- `lspServers`
-- `bin/` executables
-- `monitors`
-- `channels`
-- `apps` abstraction
-- plugin data-dir abstraction
-- statuslines
-- themes / keybindings
-- sandbox or other user/admin runtime policy
-
-Pluxx should document these and revisit them later, but it should not expand the core mental model around them yet.
-
-When you scaffold from an MCP server, pluxx now drafts workflow-oriented skills from the discovered tools so the first pass is closer to a usable plugin.
-
-The next layer is `Agent` mode: Pluxx prepares the scaffold, context pack, and prompt pack; Claude Code or Codex does the semantic refinement. The product direction is documented in [docs/agent-mode.md](./docs/agent-mode.md).
+For the detailed compatibility and verification matrix, see [docs/compatibility.md](./docs/compatibility.md).
 
 ## Quick Start
 
 ```bash
-# Preferred: run via bunx
+npx @orchid-labs/pluxx init --from-mcp https://example.com/mcp --name my-plugin --yes
 
-# Start a plugin by hand
-bunx pluxx init my-plugin
 cd my-plugin
-# Edit pluxx.config.ts, add skills in ./skills/, then build
-
-# Or scaffold directly from an MCP server
-bunx pluxx init --from-mcp https://example.com/mcp
-
-# Legacy SSE MCP import
-bunx pluxx init --from-mcp https://example.com/sse --transport sse
-
-# Local stdio MCP import
-bunx pluxx init --from-mcp "npx -y @acme/mcp"
-
-# pluxx will introspect the server and draft grouped skills like
-# account-research, contact-discovery, hiring-signals, or technographics
-
-# Headless / CI-friendly import
-bunx pluxx init --from-mcp https://example.com/mcp --yes --name acme --display-name "Acme" --author "Acme" --targets claude-code,codex --grouping workflow --hooks safe --json
-
-# Remote MCPs that use custom header auth
-bunx pluxx init --from-mcp https://mcp.playkit.sh/mcp --yes --auth-env PLAYKIT_API_KEY --auth-type header --auth-header X-API-Key --auth-template '${value}'
-
-# OAuth-first MCPs: complete provider OAuth first, then pass the resulting token env var
-bunx pluxx init --from-mcp https://example.com/mcp --yes --auth-env OAUTH_ACCESS_TOKEN --auth-type bearer
-
-# Inspect the generated project without mutating files
-bunx pluxx doctor
-bunx pluxx init --from-mcp https://example.com/mcp --yes --dry-run
-
-# Refresh MCP-derived files later while preserving the custom sections
-bunx pluxx sync --json
-
-# Prepare an agent-facing context pack and prompt pack
-bunx pluxx agent prepare
-bunx pluxx agent prompt taxonomy
-
-# Or run the full import -> refine -> verify path in one shot
-bunx pluxx autopilot --from-mcp https://example.com/mcp --runner codex --mode quick --yes
-bunx pluxx autopilot --from-mcp https://example.com/mcp --runner codex --mode standard --yes --name acme --display-name "Acme" --author "Acme"
-bunx pluxx autopilot --from-mcp https://example.com/mcp --runner codex --mode thorough --yes --verbose-runner
-
-# Or let Claude/Cursor/OpenCode/Codex consume the pack headlessly
-bunx pluxx agent run taxonomy --runner claude
-bunx pluxx agent run taxonomy --runner cursor
-bunx pluxx agent run taxonomy --runner codex
-bunx pluxx agent run review --runner opencode --attach http://localhost:4096 --no-verify
-
-# Validate, build, and smoke-test the generated plugin
-bunx pluxx lint
-bunx pluxx build
-bunx pluxx test
+npx @orchid-labs/pluxx doctor
+npx @orchid-labs/pluxx lint
+npx @orchid-labs/pluxx build
+npx @orchid-labs/pluxx test
 ```
 
-`--attach` is only supported for the `opencode` runner.
-
-Autopilot modes:
-
-- `quick`: deterministic scaffold first, and only a taxonomy pass when MCP metadata warnings make it necessary
-- `standard`: balanced default; only runs the expensive passes when quality signals or extra docs/context justify them
-- `thorough`: always runs taxonomy, instructions, and review before verification
-
-## Product Boundary And Lifecycle
-
-Pluxx is for teams that want one maintained plugin source of truth across hosts.
+Common output shape:
 
-The best fit today is MCP developers and teams shipping MCP-backed plugins, because MCP import, auth translation, and sync create the most cross-host pain. But hand-authored plugins are still a valid use case.
-
-Pluxx owns:
-
-- plugin authoring scaffold, whether imported from MCP or authored manually
-- validation (`lint`, `doctor`, `test`)
-- platform bundle generation (`build`)
-- local installation for testing (`install`)
-- ongoing MCP-to-plugin maintenance (`sync`) for MCP-derived projects
-
-Pluxx does not own:
-
-- deploying or hosting your MCP backend service
-- running your production MCP infrastructure
-
-The normal lifecycle is:
-
-1. Start from an MCP import or a hand-authored plugin source repo.
-2. Refine the source project.
-3. Validate/build/install locally.
-4. If the plugin is MCP-backed, repoint sync to the deployed HTTP/SSE MCP when production is ready.
-5. Keep the same plugin repo as the long-term source of truth.
-
-Example local-to-production transition:
-
-```bash
-# Local development MCP
-bunx pluxx init --from-mcp "npx -y @acme/mcp"
-
-# Later, after your MCP backend is deployed
-bunx pluxx sync --from-mcp https://mcp.acme.com/mcp
+```text
+dist/
+  claude-code/
+  cursor/
+  codex/
+  opencode/
 ```
 
-Publish/distribution today is repo-first:
-
-1. Commit the generated plugin source repo (`pluxx.config.ts`, `skills/`, `INSTRUCTIONS.md`, `.pluxx/mcp.json`).
-2. Build platform bundles with `bunx pluxx build`.
-3. Distribute those bundles through your target channels (internal repo, releases, or platform-specific publish paths).
-
-Pluxx is the distribution and maintenance layer for plugin artifacts; MCP service deployment remains your responsibility.
-
-Generated MCP skill files include deterministic example requests derived from tool names and required inputs, so the first scaffold is useful before any AI refinement.
-
-Agent Mode stays file-first: Pluxx writes `.pluxx/agent/context.md`, `.pluxx/agent/plan.json`, and the prompt packs, then optional runner adapters can hand those files to `claude`, `opencode`, or `codex` in headless mode. Durable project-level prompt and context customization now lives in `pluxx.agent.md`, so users do not need to edit generated `.pluxx/agent/*.md` files directly.
-Runner output is summarized by default for `pluxx agent run` and `pluxx autopilot`; use `--verbose-runner` when you want full headless runner streaming.
-
-The dogfood coverage matrix across messy metadata, local stdio, OAuth-first servers, and production auth patterns is documented in [docs/mcp-dogfood-matrix.md](./docs/mcp-dogfood-matrix.md).
-
-For dogfooding inside Codex, this repo also ships a local plugin/skill pack at [plugins/pluxx](/Users/brandonguerrero/Documents/Orchid Automation/Orchid Labs/pluxx/plugins/pluxx) with focused skills for import, taxonomy refinement, instructions, review, and sync.
-There is now also a first-class self-hosting source project at [example/pluxx](/Users/brandonguerrero/Documents/Orchid Automation/Orchid Labs/pluxx/example/pluxx) that uses one Pluxx config to generate Claude Code, Cursor, Codex, and OpenCode outputs for the Pluxx plugin itself.
+For local stdio MCPs, pass the real executable command, not just the npm package name. The bin name can differ from the package name.
 
 ```bash
-# Optional: global install still shells out to Bun
-npm install -g pluxx
-pluxx init my-plugin
-
-# Scaffold a new plugin
-cd my-plugin
-
-# Edit pluxx.config.ts, create skills in ./skills/
-
-# Build for all platforms
-bunx pluxx build
-
-# Lint against all platform rules (47 checks)
-bunx pluxx lint
-
-# Diagnose local runtime + config health
-bunx pluxx doctor
-
-# Run config, lint, build, and smoke checks together
-bunx pluxx test
-
-# Build for specific platforms
-bunx pluxx build --target claude-code cursor codex opencode
-
-# Validate your config
-bunx pluxx validate
+npx @orchid-labs/pluxx init --from-mcp "npx -y -p @acme/mcp acme-mcp" --yes
 ```
 
-## Config
-
-```typescript
-// pluxx.config.ts
-import { definePlugin } from 'pluxx'
-
-export default definePlugin({
-  name: 'my-plugin',
-  version: '1.0.0',
-  description: 'What your plugin does',
-  author: { name: 'Your Name' },
-
-  // Skills (Agent Skills standard — shared across all platforms)
-  skills: './skills/',
-
-  // MCP servers (auth format auto-translated per platform)
-  mcp: {
-    'my-server': {
-      url: 'https://my-server.com/mcp',
-      auth: {
-        type: 'bearer',
-        envVar: 'MY_API_KEY',
-      },
-    },
-  },
-
-  // Hooks (generated where the platform supports plugin-packaged hooks;
-  // Codex currently keeps hook config in .codex/hooks.json outside plugin bundles)
-  hooks: {
-    sessionStart: [{
-      command: '${PLUGIN_ROOT}/scripts/setup.sh',
-    }],
-  },
-
-  // Instructions (generates CLAUDE.md, AGENTS.md, or .mdc rules)
-  instructions: './INSTRUCTIONS.md',
-
-  // Brand (used by platforms that support rich metadata)
-  brand: {
-    displayName: 'My Plugin',
-    color: '#3B82F6',
-    icon: './assets/icon.svg',
-    defaultPrompts: ['Try my plugin with this prompt'],
-  },
-
-  // Target platforms
-  targets: ['claude-code', 'cursor', 'codex', 'opencode'],
-})
-```
+## Command Cheat Sheet
 
-## What Gets Generated
+```text
+Need a new project from an MCP?
+  pluxx init --from-mcp <source> --yes
 
-### MCP Config Translation
+Need the all-in-one path?
+  pluxx autopilot --from-mcp <source> --runner <runner>
 
-You write one auth config. pluxx generates the correct format for each platform:
+Need deterministic checks?
+  pluxx doctor
+  pluxx lint
+  pluxx eval
+  pluxx build
+  pluxx test
 
-```typescript
-// You write:
-mcp: {
-  server: {
-    url: 'https://api.example.com/mcp',
-    auth: { type: 'bearer', envVar: 'API_KEY' },
-  },
-}
-```
+Need local installs too?
+  pluxx build --install
+  pluxx test --install
+  pluxx uninstall
 
-```jsonc
-// Claude Code gets:
-{ "headers": { "Authorization": "Bearer ${API_KEY}" } }
+Need agent refinement?
+  pluxx agent prepare [--website <url>] [--docs <url>]
+  pluxx agent run taxonomy --runner <runner>
+  pluxx agent run instructions --runner <runner>
+  pluxx agent run review --runner <runner>
 
-// Codex gets:
-{
-  "env_http_headers": {
-    "X-API-Key": "API_KEY"
-  }
-}
+Need to import an old host-native plugin?
+  pluxx migrate <path>
 
-// Cursor gets:
-{ "headers": { "Authorization": "Bearer ${API_KEY}" } }
-```
+Need to inspect a shipped bundle?
+  pluxx doctor --consumer <bundle>
 
-### Plugin Manifests
-
-Each platform gets its native manifest format:
-
-- **Claude Code**: `.claude-plugin/plugin.json` with skills, commands paths
-- **Cursor**: `.cursor-plugin/plugin.json` with explicit `rules/`, `hooks/hooks.json`, and `mcp.json` component paths
-- **Codex**: `.codex-plugin/plugin.json` with full `interface` block (brand color, icons, screenshots, default prompts, capabilities) plus external hooks via `.codex/hooks.json`
-- **OpenCode**: npm package + JS/TS plugin wrapper
-
-### Instructions to Platform-Native Rules
-
-Your single `INSTRUCTIONS.md` becomes:
-- `CLAUDE.md` for Claude Code
-- `AGENTS.md` for Codex and Cursor
-- `.mdc` rule files in `rules/` for Cursor (with frontmatter) when you specify rules in platform overrides
-
-### 47 Lint Checks
-
-`pluxx lint` catches platform-specific gotchas before you ship:
-
-- Codex rejects SKILL.md descriptions over 1024 characters
-- Claude Code silently truncates descriptions at 250 characters
-- Cursor and Cline require skill names to match their directory names
-- Codex allows max 3 default prompts, 128 chars each
-- Claude Code hook events must be PascalCase (26 valid events)
-- Manifest paths must start with `./` and cannot contain `../`
-- Plugin directories must be at root, not inside `.claude-plugin/`
-- Version must follow semver format
-- And 39 more checks across all platforms
-
-### Read-Only Diagnostics And Verification
-
-- `pluxx doctor` checks Bun/runtime health, config loadability, configured paths, MCP auth/transport shape, scaffold metadata, and install trust advisories.
-- `pluxx test` runs the default verification stack for a plugin project: config load, lint, build, and generated-output smoke checks.
-- `--json` is available for machine-readable output on `init --from-mcp`, `sync`, `doctor`, `lint`, `build`, `install --dry-run`, and `test`.
-- `--dry-run` previews file writes for `init --from-mcp` and `sync`, install paths for `install`, and output targets for `build`.
-
-### Platform Overrides
-
-For the 10% of cases where platforms diverge:
-
-```typescript
-platforms: {
-  'claude-code': {
-    skillDefaults: { effort: 'high' },
-  },
-  cursor: {
-    rules: [{
-      description: 'My conventions',
-      alwaysApply: false,
-    }],
-  },
-  codex: {
-    interface: {
-      capabilities: ['Interactive', 'Write'],
-      privacyPolicyURL: 'https://example.com/privacy',
-    },
-  },
-}
-```
-
-## Real-World Examples
-
-### Megamind (client intelligence plugin)
+Need deterministic MCP replay?
+  pluxx mcp proxy --from-mcp <source> --record tape.json
+  pluxx mcp proxy --replay tape.json
 
-The [example/megamind](./example/megamind) directory contains a full plugin that was previously hand-maintained as two separate copies. With pluxx, one config generates outputs for all platforms.
-
-```bash
-cd example/megamind
-bunx pluxx build
+Need to refresh from the MCP later?
+  pluxx sync
 ```
 
-### Prospeo (sales intelligence MCP)
+Full docs tree:
 
-The [examples/prospeo-mcp](./examples/prospeo-mcp) directory wraps a real MCP server into a multi-platform plugin with 4 skills:
+- [docs.pluxx.dev/getting-started/command-decision-tree](https://docs.pluxx.dev/getting-started/command-decision-tree)
 
-```bash
-cd examples/prospeo-mcp
-bunx pluxx build   # 52 files across 7 platforms
-bunx pluxx lint    # Catches real platform gotchas
-```
-
-## Testing Locally
-
-```bash
-# Check project health before generating anything
-bunx pluxx doctor
-
-# Build and install to Claude Code
-bunx pluxx build
-bunx pluxx install --target claude-code
-
-# Run the full plugin verification contract
-bunx pluxx test
-
-# Validate with Claude Code's own validator
-claude plugin validate ~/.claude/plugins/my-plugin
-# ✓ Validation passed
-```
-
-## CI / Automation
-
-Pluxx now ships a reusable GitHub workflow for plugin repos:
+## Core Commands
 
-```yaml
-name: Plugin Check
+Pluxx includes more than scaffold generation:
 
-on:
-  pull_request:
-  push:
-    branches: [main]
+- `pluxx eval` checks scaffold and prompt-pack quality
+- `pluxx migrate <path>` imports an existing host-native plugin into a Pluxx project
+- `pluxx doctor --consumer <bundle>` inspects built or installed plugin bundles from the user side
+- `pluxx mcp proxy --record` and `--replay` give you deterministic MCP tapes for debugging and CI
 
-jobs:
-  verify:
-    uses: orchidautomation/pluxx/.github/workflows/pluxx-plugin-check.yml@main
-    with:
-      working-directory: .
-      pluxx-version: latest
-```
-
-For headless local automation, prefer:
-
-```bash
-bunx pluxx init --from-mcp https://example.com/mcp --yes --json
-bunx pluxx sync --dry-run --json
-bunx pluxx test --json
-```
+## Authoring Model
 
-See [docs/getting-started.md](./docs/getting-started.md) for the full getting-started walkthrough, including the MCP-first path.
+Pluxx is intentionally opinionated around a compact cross-host model:
 
-## Hook Trust Model
+- skills
+- instructions
+- mcp
+- commands
+- hooks
+- permissions
+- userConfig
+- agents
+- brand and assets
+- taxonomy
 
-Hook commands are shell commands that execute on your machine when hook events fire. If you install a third-party plugin with hooks, you are trusting that plugin author with local command execution.
+Pluxx owns the deterministic scaffold, validation, and host compilation layer. Your host coding agent can refine taxonomy, instructions, and examples without breaking the structure.
 
-`pluxx install` now warns when the plugin config contains command hooks and prints each event/command pair before install proceeds.
+## Install And Runtime Notes
 
-Use `--trust` to bypass the confirmation prompt (useful in CI/non-interactive environments):
+- npm package: `@orchid-labs/pluxx`
+- preferred invocation: `npx @orchid-labs/pluxx ...`
+- global install also works: `npm install -g @orchid-labs/pluxx`
+- published CLI runtime: Node `>=18`
+- source builds and maintainer workflows also run on Node `>=18`
 
-```bash
-bunx pluxx install --trust
-```
-
-## CLI Commands
-
-| Command | What it does |
-|---------|-------------|
-| `pluxx init` | Interactive scaffold for a new plugin or `--from-mcp` import |
-| `pluxx doctor` | Read-only runtime, config, MCP, and trust diagnostics |
-| `pluxx build` | Generate plugin packages for all target platforms |
-| `pluxx lint` | 47 checks against all platform rules |
-| `pluxx test` | Run config, lint, build, and smoke checks together |
-| `pluxx sync` | Refresh MCP-derived scaffold files while preserving custom sections |
-| `pluxx validate` | Validate your config schema |
-| `pluxx install` | Symlink built plugins for local testing (prompts when hook commands exist) |
-| `pluxx install --trust` | Bypass hook trust confirmation |
-| `pluxx uninstall` | Remove symlinked plugins |
-| `pluxx dev` | Watch mode with auto-rebuild on file changes |
-| `pluxx migrate <path>` | Import an existing single-platform plugin |
-
-## How It Works
-
-```
-pluxx.config.ts          <- You define your plugin once
-       |
-       v
-  +---------+
-  |  Parse  |              Zod schema validation
-  +----+----+
-       |
-       v
-  +--------+
-  |  Lint  |               47 platform-specific checks
-  +----+---+
-       |
-       v
-  +----------+
-  | Generate |             Platform-specific generators
-  +-+--+--+--+
-    |  |  |
-    v  v  v
-  Claude  Cursor  Codex    + 8 beta platforms
-  Code
-```
+## Read Next
 
-## Comparison
-
-| | pluxx | npx skills | SkillKit |
-|---|:---:|:---:|:---:|
-| Install skills to multiple agents | - | Yes | Yes |
-| Generate plugin manifests | Yes | - | - |
-| MCP config with auth translation | Yes | - | - |
-| Hook generation per platform | Yes | - | - |
-| Brand/interface metadata | Yes | - | - |
-| Rules/instructions generation | Yes | - | Translate only |
-| Cross-platform lint (47 checks) | Yes | - | - |
-| Subagent configs | Yes | - | - |
-
-**pluxx builds plugins. The others install skills.** They're complementary — use `npx skills` to distribute your skills, use pluxx to build the full plugin package.
-
-## Built On
-
-- [Agent Skills](https://agentskills.io/) open standard (skills are pass-through, never modified)
-- [Zod](https://zod.dev/) for config validation with full TypeScript inference
-- [Bun](https://bun.sh/) for fast builds and TypeScript-native execution
-
-## Roadmap
-
-- [x] Core schema with Zod validation
-- [x] Generators: Claude Code, Cursor, Codex (fully supported) + 8 beta platforms
-- [x] CLI: `build`, `validate`, `init`, `lint`, `install`, `uninstall`, `dev`, `migrate`
-- [x] MCP auth normalization across platforms
-- [x] 47 lint checks from official docs (Firecrawl-verified)
-- [x] Real-world examples (Megamind + Prospeo)
-- [ ] `pluxx lint --fix` — auto-apply suggested fixes
-- [x] `pluxx init --from-mcp` — auto-scaffold plugins from existing MCP servers
-- [x] `pluxx doctor` — project and runtime health checks
-- [x] `pluxx test` — verification command for plugin repos
-- [x] CI/CD GitHub Action / reusable workflow
-- [ ] canonical `userConfig` / install-time secret handling
-- [ ] canonical permissions model across primary targets
-- [ ] build-time target cap validation for primary targets
-- [ ] `pluxx publish` — push to platform marketplaces
-- [ ] `pluxx diff` — show what changed per platform
-- [ ] Plugin analytics dashboard
-- [ ] Promote beta platforms to fully supported
+- [Getting started](./docs/getting-started.md)
+- [Create a Pluxx plugin](./docs/create-a-pluxx-plugin.md)
+- [How it works](./docs/how-it-works.md)
+- [Use Pluxx in host agents](./docs/use-pluxx-in-host-agents.md)
+- [Core primitives](./docs/core-primitives.md)
+- [OSS wedge and trust layer](./docs/oss-wedge-and-trust-layer.md)
+- [Compatibility matrix](./docs/compatibility.md)
+- [First proof and demo asset pack](./docs/first-proof-demo-asset-pack.md)
+- [Releasing Pluxx](./docs/releasing-pluxx.md)
 
 ## License