chore: release

.changeset/seven-windows-play.md

@@ -0,0 +1,39 @@
+---
+"lerobot": minor
+"@lerobot/node": minor
+"@lerobot/web": minor
+---
+
+\# Changes Summary
+
+\## Features
+
+\- feat(node): add `connectPort()` function for direct port connections
+
+\- feat(node): implement proper `findPort()` / `connectPort()` API separation
+
+\- feat(node): add comprehensive Node.js README with API documentation
+
+\- feat(lint): add ESLint configuration for both Node.js and Web packages
+
+\## Fixes
+
+\- fix(node): resolve motor position reading to return instant real values
+
+\- fix(node): implement proper calibration flow matching Python lerobot
+
+\- fix(node): resolve EventEmitter memory leaks in motor communication
+
+\- fix(examples): update all Node.js examples to use correct API pattern
+
+\## Documentation
+
+\- docs(web): clarify `findPort()` vs `connectPort()` API differences
+
+\- docs: add Python compatibility notes for calibration files
+
+\## Refactor
+
+\- refactor: unify `CalibrationResults` type across Node.js and Web packages
+
+\- refactor: remove legacy type aliases and old `src` folder structure

docs/conventions.md

@@ -246,6 +246,15 @@ packages/
 - Shared constants and protocols via dedicated utils
 - Cross-platform compatibility for data formats (calibration files, etc.)
 
+**Critical API Design: Node.js `findPort()` vs `connectPort()` Separation**
+
+- **`findPort()`**: Discovery only - returns `DiscoveredPort[]` with `path` and `robotType`
+- **`connectPort(portPath, robotType, robotId)`**: Connection only - returns `RobotConnection`
+- **Beginner Flow**: `findPort()` → pick from results → `connectPort()` → use robot
+- **Advanced Flow**: Direct `connectPort()` when port is known
+- **Why Separated**: Node.js can programmatically list ports (unlike browser security model)
+- **Python Compatibility**: Matches Python lerobot's separation of discovery vs connection
+
 **CLI Architecture & Separation of Concerns:**
 
 - **Library (`@lerobot/node`)**: Pure programmatic API for Node.js applications
@@ -512,9 +521,24 @@ const response = await new Promise((resolve, reject) => {
 
 ### Development Process Requirements
 
-#### CLI Build Process
+#### Optimized Development Workflow (No Constant Rebuilding)
+
+**✅ PERFECT Development Setup:**
+
+1. **Terminal 1**: `cd packages/node && pnpm dev` (watch mode)
+2. **Terminal 2**: `cd packages/cli && pnpm dev teleoperate ...` (direct TypeScript execution)
+
+**❌ WRONG**: Constantly running `pnpm build` and clearing `node_modules`
+
+**Why This Works:**
 
-- **Critical**: After TypeScript changes, MUST run `pnpm run build` to update CLI
+- Node package rebuilds automatically on changes
+- CLI dev mode uses `vite-node` to run TypeScript directly
+- No package caching issues, immediate feedback
+
+#### CLI Build Process (Production Only)
+
+- **Critical**: After TypeScript changes, MUST run `pnpm run build` to update CLI for production
 - **Global CLI**: `lerobot` command uses compiled `dist/` files, not source
 - **Testing Flow**: Edit source → Build → Test CLI → Repeat
 - **Common Mistake**: Testing source changes without rebuilding CLI
@@ -746,18 +770,11 @@ private handleKeyboardInput(key: string): void {
 
 **Package Development Without Constant Rebuilding:**
 
-**✅ PERFECT Development Setup:**
+**✅ PERFECT Development Setup (documented above in Development Process Requirements):**
 
-1. **Terminal 1**: `cd packages/node && pnpm dev` (watch mode)
-2. **Terminal 2**: `cd packages/cli && pnpm dev teleoperate ...` (direct TypeScript execution)
-
-**❌ WRONG**: Constantly running `pnpm build` and clearing `node_modules`
-
-**Why This Works:**
-
-- Node package rebuilds automatically on changes
-- CLI dev mode uses `vite-node` to run TypeScript directly
-- No package caching issues, immediate feedback
+- Use `pnpm dev` for watch mode development
+- Use `vite-node` for direct TypeScript execution
+- Avoid constant rebuilding and `node_modules` clearing
 
 ##### 🔧 CLI Architecture Lessons