.cursorrules

# Rocket Ride Data Toolchain - AI Assistant Instructions

## Read ALL Documentation First

**Before ANY Rocket Ride code, read ALL 6 files at `docs/agents/`:**

1. **`ROCKETRIDE_QUICKSTART.md`** ← Start here, copy working examples
2. `ROCKETRIDE_README.md`
3. `ROCKETRIDE_python_API.md` or `ROCKETRIDE_typescript_API.md`
4. `ROCKETRIDE_PIPELINE_RULES.md`
5. `ROCKETRIDE_COMPONENT_REFERENCE.md`
6. `ROCKETRIDE_COMMON_MISTAKES.md`

**If user request is ambiguous: STOP and ask. Do NOT guess.**

---

## ✓ Before Submitting Code

- [ ] Read ROCKETRIDE_QUICKSTART.md and used as template
- [ ] Read all 6 documentation files
- [ ] Verified code follows documented patterns
- [ ] Quoted relevant documentation in response

**Cannot check all boxes? Don't submit code.**

---

## Documentation Guide

| Need | File |
|------|------|
| Working examples | ROCKETRIDE_QUICKSTART.md |
| Setup checklist | ROCKETRIDE_README.md |
| Client methods | ROCKETRIDE_python_API.md or ROCKETRIDE_typescript_API.md |
| Pipeline rules | ROCKETRIDE_PIPELINE_RULES.md |
| Components | ROCKETRIDE_COMPONENT_REFERENCE.md |
| Troubleshooting | ROCKETRIDE_COMMON_MISTAKES.md |

**The co-located per-package docs — assembled into the docs site by `builder docs:build` — are the source of truth. The agent integration docs at `docs/agents/` are the assistant-facing integration reference within it; read them first before writing any RocketRide integration code.**


## Co-located documentation rule

Documentation is co-located with the code it documents and is gathered into the
docs site by `builder docs:build`. When a change alters a public contract, update
the corresponding co-located doc in the SAME change:

- A node's inputs, outputs, or config schema -> prose in `nodes/src/nodes/<name>/doc.md`.
  Never hand-edit content between `<!-- ROCKETRIDE:GENERATED:PARAMS START -->` and
  `<!-- ROCKETRIDE:GENERATED:PARAMS END -->`; it is regenerated from `services*.json`
  by `nodes:docs-generate`.
- A public TypeScript SDK signature -> `packages/client-typescript/docs/`. Reference
  under `docs/reference/` is generated by `client-typescript:docs-generate` (do not edit).
- A public Python SDK signature -> `packages/client-python/docs/` (reference generated).
- The MCP protocol surface -> `packages/client-mcp/docs/`.
- The WebSocket (5565) / engine protocol surface -> `packages/server/docs/`.
- The `.pipe` schema (`packages/client-typescript/src/client/types/pipeline.ts`) -> its
  reference regenerates to `/pipeline-reference`.
- The VS Code extension surface -> `apps/vscode/docs/`.
- Spine/landing pages (Home, Quickstart, Concepts, Cloud, Troubleshooting, Glossary,
  Cursor/Windsurf stubs) -> `packages/docs/content-static/`.

Prose-only edits and internal refactors that do not change a public contract do not
require doc updates. Treat the doc as part of the change, not a follow-up. Do not create
a separate docs repo or a top-level docs site folder. Verify with `builder docs:build`.