# AGENTS.md

Contributor guide for humans and agents working in this repository. This file
is the single source of truth for repo-wide rules — `.claude/CLAUDE.md` and
`.cursorrules` point here.

## Overview

Monorepo for the RocketRide (Aparavi) data toolchain: a C++ engine
(`packages/server/`), Python SDK and nodes (`packages/client-python/`,
`nodes/`), a TypeScript SDK and VS Code extension (`packages/client-typescript/`,
`apps/vscode/`), and supporting packages. `./builder` wraps builds and test
orchestration.

## Where to look — task routing

Read the doc for your task before writing code. Paths are repo-relative.

| Task | Read |
|---|---|
| Use RocketRide / write integration code | `docs/agents/context/ROCKETRIDE_README.md` first, then the other `ROCKETRIDE_*` files there |
| Build or edit a node | `docs/development/nodes/readme-schema.md` (README contract), `docs/development/nodes/services-schema.md` (services.json contract), `docs/development/nodes/index.md` (what a node is; the per-node READMEs are the catalog) |
| Test a node | `docs/development/nodes/testing.md` |
| Client (SDK) docs | `docs/development/clients/readme-schema.md`; sources in `docs/public/<name>/` |
| MCP surface | `docs/public/mcp/` |
| Engine internals | `docs/development/engine/index.md` |
| WebSocket (5565) protocol | `docs/public/product/connect/websocket/` |
| Crash reporting / minidumps | `docs/development/engine/crash-reporting.md` |
| Shell apps | `docs/public/product/guides/apps/index.md` (app API), `docs/development/apps/index.md` (monorepo setup) |
| Document a shipped app | `apps/<app>/` only (`README.md`, `docs/`, `assets/`); never a site page or spine entry. Exceptions: VS Code (`docs/docusaurus/apps/vscode/`) and App Builder (`docs/public/product/guides/apps/app-builder.md`) |
| Builder / hooks | `docs/development/builder/reference.md` (run builds), `docs/development/builder/authoring.md` (write tasks.js), `docs/development/builder/pre-commit-hooks.md` |
| Product docs (site spine) | `docs/public/product/` |

## Common commands

```bash
./builder build                  # Build EVERYTHING (global command: expands to every module's :build — server, shell, all UIs, SDKs, vscode)
./builder test                   # All tests
python -m pytest <path>          # Python tests directly
python -m ruff check <path>      # Python lint (format: ruff format)
npx tsc --noEmit                 # TypeScript type-check

# Documentation checks
./builder docs:validate                              # node README + client-doc schemas (also inside docs:test)
python3 scripts/validate-node-readme.py <node-dir>   # one node (--all nodes/src/nodes for every node)
python3 scripts/validate-client-docs.py              # client docs parity
node scripts/build.js docs:check                     # export drift gate (CI-enforced)
./builder docs:build                                 # stage the docs site
```

## Conventions

- **Commits**: conventional commits (`feat(scope):`, `fix(scope):`, `chore(scope):`).
- **Branches**: `feat/RR-<ticket>-short-description`, `fix/RR-<ticket>-...`; PR base is `develop`.
- **Python**: 3.10+, single quotes, ruff for lint/format.
- **TypeScript**: tabs, single quotes, semicolons.
- **Store apps**: pipelines bundled in an app for the public store use
  catalog nodes only (the nodes that ship with the engine; see 'Catalog
  nodes only' in `docs/agents/context/ROCKETRIDE_APPS.md`). `scaffold_node`
  and `local_nodes` are for self-hosted engines and for nodes contributed
  to the catalog, never for a store app.
- **VS Code extension only**: wrap errors with `Callout.call()` (no raw
  try/catch), throw `AppError` (never plain `Error`), log via `logger.*`
  (never `console.log`). Docs-site theme components (`docs/docusaurus`) are
  exempt by design.

## Documentation rules

Hand-written docs live in the top-level `docs/` tree and are gathered into the
docs site by `builder docs:build`. When a change alters a public contract,
update the corresponding doc in the SAME change:

- Product docs (quickstart, concepts, integrations, examples, evaluate,
  glossary, troubleshooting, cloud, self-hosting) → `docs/public/product/`.
- Public TypeScript SDK signature → `docs/public/typescript/` (guides).
  Generated reference under `packages/client-typescript/docs/reference/`
  (do not edit; regenerated by `client-typescript:docs-generate`).
- Public Python SDK signature → `docs/public/python/` (reference generated).
- MCP protocol surface → `docs/public/mcp/`.
- WebSocket (5565) / engine protocol surface → `docs/public/product/connect/websocket/`.
- `.pipe` schema (`packages/client-typescript/src/client/types/pipeline.ts`) →
  reference regenerates to `/reference/pipeline-reference` (generated — do not edit).
- VS Code extension surface → site pages in `docs/docusaurus/apps/vscode/`; marketplace README in `apps/vscode/README.md`.
- Any other app (`apps/<app>/`) → docs stay inside that app's folder. Per-app
  docs are never staged into the site; App Builder and VS Code are the only
  exceptions, and no new ones are added.
- Contributor docs (setup, builder, engine internals, node authoring, hooks) →
  `docs/development/`.
- Third-party integration guides → `docs/public/product/connect/`.
- Agent-facing docs (`ROCKETRIDE_*`) → `docs/agents/context/` (packed into the
  `/client/docs` bundle by `./builder client-docs:agent`; see `docs/agents/README.md`).

**Nodes are the exception**: node docs stay co-located at
`nodes/src/nodes/<name>/README.md`, following
`docs/development/nodes/readme-schema.md`. The
`ROCKETRIDE:GENERATED:PARAMS` region is maintained by `nodes:docs-generate`
— never edit it by hand. Validate with
`python3 scripts/validate-node-readme.py <node-dir>`.

**Package READMEs are generated committed copies**: edit
`docs/public/<name>/README.md` (typescript, python, n8n, chat-widget; the MCP
source is `docs/public/mcp/stdio/README.md`),
then run `./builder docs:export`; never edit `packages/client-*/README.md`,
`packages/n8n-nodes/README.md`, or `packages/chat-widget/README.md` directly.
CI runs `./builder docs:check` to
catch drift. The VS Code marketplace readme is `apps/vscode/README.md`,
owned by the extension alongside its `assets/`; the VSIX build stages it
with its image links rewritten to absolute URLs.

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. Verify with
`builder docs:build` and `builder docs:check`.