{
  "markdown": "# Velt Plugin for Cursor\n\nAdd real-time collaboration (comments, presence, cursors, CRDT editing, notifications) to React and Next.js apps using AI-assisted setup.\n\n## What You Get\n\n- **8 slash commands**: `/install-velt`, `/add-comments`, `/add-crdt`, `/add-notifications`, `/add-presence`, `/add-cursors`, `/screenshot`, `/velt-help`\n- **4 agent-skills**: 118 implementation rules for setup, comments, CRDT, and notifications\n- **Velt Expert agent**: specialized AI persona for Velt architecture guidance\n- **6 embedded rules**: always-on best practices for setup, auth, document identity, comments, CRDT, notifications\n- **MCP servers**: velt-installer (guided setup) + velt-docs (documentation search)\n\n## Architecture\n\nThe plugin is a **combo meal** — each component has a clear, non-overlapping role:\n\n| Component | Role | What it does |\n|-----------|------|-------------|\n| **MCP Installer** | Orchestrator | WHAT to do, WHEN, in what ORDER. Generates installation plans with \"READ FIRST:\" directives pointing to specific skill files. |\n| **Skills (agent-skills)** | Knowledge base | HOW to implement. Contains exact code patterns, import paths, extension ordering, CSS. Skills are the single source of truth for implementation. |\n| **CLI** (`@velt-js/add-velt`) | Scaffolding | Quick-start code generation — login, VeltProvider setup, user auth boilerplate. |\n| **Velt Docs MCP** | Fallback only | ONLY used when skills don't cover a topic. Never used during installation if skills exist. |\n| **Slash command skills** | Triggers | Thin wrappers that invoke the MCP installer and tell Cursor to follow its plan. |\n\n## Quick Start\n\n1. Install the plugin in Cursor\n2. Open a React or Next.js project\n3. Type `/install-velt` in the chat\n4. Follow the guided setup\n\n## Installing Skills to Cursor\n\nCursor reads skills from `~/.cursor/skills/`, NOT from the plugin directory. After building the plugin, you must deploy skills to Cursor:\n\n```bash\nnpm run deploy        # Copy skills to ~/.cursor/skills/\n```\n\nOr manually:\n```bash\nnpm run build         # Build plugin from source\nnpm run deploy        # Deploy to Cursor\n```\n\nThis also runs automatically as part of `npm run all`.\n\n### Why is this needed?\n\nCursor does not load skills directly from plugin directories. It reads from `~/.cursor/skills/` which is a separate location. Without deploying, Cursor uses stale copies of the skills.\n\nAgent-skills (velt-setup-best-practices, etc.) are handled separately — they're installed via `npx skills add velt-js/agent-skills` and symlinked into `~/.cursor/skills/` automatically.\n\n## Development\n\n```bash\nnpm run sync      # Copy agent-skills from ../agent-skills\nnpm run build     # Build plugin from packages/shared source\nnpm run deploy    # Deploy skills to ~/.cursor/skills/\nnpm run validate  # Validate plugin completeness\nnpm run all       # sync + build + deploy + validate\n```\n\n## Issues We Found & Fixed\n\n### 1. Cursor reads skills from `~/.cursor/skills/`, not the plugin directory\n\n**Problem:** After building the plugin, Cursor ignored the updated skills in the repo and used stale copies from `~/.cursor/skills/` (installed separately in Feb 2026). All our changes to skill SKILL.md files had no effect.\n\n**Root cause:** Cursor loads skills from `~/.cursor/skills/`, not from plugin directories. The plugin's `skills/` directory is only used by the build system.\n\n**Fix:** Added `npm run deploy` (scripts/deploy-skills.mjs) which copies built skills to `~/.cursor/skills/`. This is now part of `npm run all`.\n\n### 2. MCP installer was cached via npx\n\n**Problem:** After updating the MCP installer and publishing to npm, Cursor still used the old version because npx caches packages.\n\n**Fix:** Clear the npx cache after publishing: `rm -rf ~/.npm/_npx`\n\n### 3. Skills competed with MCP for orchestration\n\n**Problem:** The install-velt SKILL.md had its own \"BLOCKING PREREQUISITE\" workflow, priority chain, and rule-reading checklist that competed with the MCP installer's plan output. The velt-expert agent also tried to orchestrate independently. Cursor couldn't follow 4 competing instruction sets.\n\n**Fix:** Simplified all skills to thin MCP wrappers (\"call MCP, follow its plan\"). MCP is now the single orchestrator, skills are the single knowledge base.\n\n### 4. onMouseDown vs onClick in TipTap BubbleMenu\n\n**Problem:** Cursor generated `onMouseDown` for BubbleMenu comment buttons despite the TipTap-specific rules and MCP code examples all using `onClick`.\n\n**Root cause:** The MCP plan directed Cursor to \"READ `AGENTS.md` → look up `mode-tiptap`\". When Cursor read the AGENTS.md index, it saw all 12 comment mode rules listed together. 6 of the 7 editor mode rules (Lexical, Slate, Plate, Quill, Ace, CodeMirror) use `onMouseDown` in their code examples — only mode-tiptap uses `onClick`. Cursor picked up the majority pattern from the wrong rules.\n\n**Fix:** Changed the MCP plan to reference **specific rule file paths** (e.g., `skills/velt-crdt-best-practices/rules/shared/tiptap/tiptap-comments-integration.md`) instead of the AGENTS.md index. Added \"Do NOT read other editor mode rules\" directive to prevent cross-contamination.\n\n### 5. `history: false` vs `undoRedo: false`\n\n**Problem:** Source rule files and the velt-expert agent said `StarterKit.configure({ history: false })` which is the Tiptap v2 API. Tiptap v3 renamed it to `undoRedo: false`.\n\n**Fix:** Updated all source files. Grep for `history: false` returns 0 hits (only appears in \"do NOT use\" context).\n\n## Structure\n\n```\nvelt-plugin/                    (repo root = plugin root)\n├── .plugin/plugin.json         # Open Plugins manifest\n├── .cursor-plugin/plugin.json  # Cursor compat manifest\n├── .mcp.json                   # MCP server registration\n├── skills/                     # 8 plugin skills + 4 bundled agent-skills\n├── rules/                      # 6 embedded .mdc rules\n├── agents/                     # velt-expert agent\n├── guides/                     # Embedded best practices reference\n├── assets/                     # Logo\n└── scripts/\n    ├── build.mjs               # Generate manifests and MCP config\n    ├── deploy-skills.mjs       # Deploy skills to ~/.cursor/skills/\n    ├── sync-agent-skills.mjs   # Sync agent-skills from sibling repo\n    └── validate.mjs            # Validate plugin completeness\n```\n\n## Related\n\n- [Velt Plugin for Claude Code](https://github.com/velt-js/velt-plugin-claude)\n- [Velt Agent Skills](https://github.com/velt-js/agent-skills) (118 implementation rules)\n- [Velt MCP Installer](https://www.npmjs.com/package/@velt-js/mcp-installer)\n- [Velt CLI](https://www.npmjs.com/package/@velt-js/add-velt)\n- [Velt Documentation](https://docs.velt.dev)\n\n## License\n\nMIT\n",
  "bytes": 6703,
  "sha": "da5e1c985a2837fd79341bbb6f9106929549069edde245a563c0aa80831af271",
  "repo_slug": "velt-js/velt-plugin",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_velt_js_velt_plugin_velt_48329579/readme"
}