moving

docs/CONTRIBUTING.md

@@ -0,0 +1,172 @@
+# Contributing to Waggle
+
+## Prerequisites
+
+- **Node.js 20+** (required)
+- **Rust toolchain** (only for the desktop app -- `app/` package)
+- **Docker** (only for team mode tests -- PostgreSQL and Redis)
+
+## Setup
+
+```bash
+git clone https://github.com/marolinik/waggle-os.git
+cd waggle-os
+npm install
+```
+
+## Running the App
+
+```bash
+# Local server / sidecar (http://localhost:3333)
+cd packages/server && npx tsx src/local/start.ts
+# — or, from the repo root: npm run dev:server
+
+# Web app (http://localhost:8080)
+npm run dev          # — or: npm run dev:web
+
+# Desktop app (requires Rust)
+cd app && npm run tauri dev
+
+# CLI REPL
+cd packages/cli && npx tsx src/index.ts
+```
+
+## Running Tests
+
+Tests are the product's safety net. All PRs must pass the full test suite.
+
+```bash
+# Run all tests (3000+ across 190+ files)
+npx vitest run
+
+# Watch mode during development
+npx vitest
+
+# Run tests for a specific package
+npx vitest run packages/core
+
+# Run a specific test file
+npx vitest run packages/agent/src/__tests__/tools.test.ts
+
+# Coverage report
+npx vitest run --coverage
+```
+
+### Test Requirements
+
+- All existing tests must pass before submitting a PR
+- New features require accompanying tests
+- Bug fixes require a regression test
+- Team mode tests require Docker services running (`docker compose up -d`)
+
+### Test Organization
+
+Tests live alongside source files in `__tests__/` directories or as `.test.ts` siblings. The monorepo uses a single Vitest config at the root.
+
+## Pull Request Process
+
+1. **Fork** the repository and create a feature branch from `main`
+2. **Read the CLAUDE.md** for execution rules and product truths
+3. **Make your changes** following the slice-based approach (one focused change per PR)
+4. **Write tests** for new functionality
+5. **Run the full test suite**: `npx vitest run`
+6. **Verify the build**: `npx tsc --noEmit`
+7. **Submit a pull request** against `main`
+8. **Describe your changes**: what was added, what was preserved, what was tested
+
+### PR Title Format
+
+Use descriptive titles that indicate the type of change:
+
+- `feat: add Notion connector` -- new feature
+- `fix: memory search scope filtering` -- bug fix
+- `refactor: extract FrameStore from MindDB` -- code restructuring
+- `test: add coverage for approval gates` -- test additions
+- `docs: update API reference` -- documentation
+
+## Code Style
+
+### TypeScript
+
+- ESM modules (`"type": "module"` in package.json)
+- Explicit imports (no barrel re-exports)
+- Strict TypeScript (`strict: true`)
+- Use `type` imports where possible: `import type { Foo } from './foo.js'`
+- Include `.js` extensions in imports (ESM requirement)
+
+### File Organization
+
+- One concept per file where practical
+- Co-locate tests: `foo.ts` and `__tests__/foo.test.ts`
+- Route files export a Fastify plugin async function
+- Types go in the `@waggle/shared` package if used across packages
+
+### Naming Conventions
+
+- Files: `kebab-case.ts`
+- Types/Interfaces: `PascalCase`
+- Functions/variables: `camelCase`
+- Constants: `UPPER_SNAKE_CASE`
+- Route handlers: descriptive comments with HTTP method and path
+
+### Error Handling
+
+- Route handlers catch errors and return appropriate HTTP status codes
+- Non-critical operations use try/catch with empty catch (logging is acceptable)
+- Critical operations throw with descriptive error messages
+- Avoid swallowing errors silently in core logic
+
+## Package Structure
+
+### Adding to an Existing Package
+
+1. Add your source file in the appropriate directory
+2. Export from the package's `index.ts` if it's a public API
+3. Add tests in the `__tests__/` directory
+4. Run `npx vitest run packages/<name>` to verify
+
+### Key Directories
+
+```
+packages/<name>/
+  src/
+    index.ts          # Public exports
+    __tests__/        # Test files
+  package.json        # Package metadata
+  tsconfig.json       # TypeScript config
+```
+
+## Product Rules
+
+Read `CLAUDE.md` in the repo root for the full execution protocol. Key rules:
+
+- **Waggle is workspace-native** -- do not collapse into a global chat
+- **Memory is a product primitive** -- do not treat it as decorative
+- **Tool transparency matters** -- users see what the agent does
+- **Approval gates are required** for sensitive operations
+- **No scope reduction without approval** -- do not simplify features "for now"
+- **Tests are part of the product** -- not an afterthought
+
+## Troubleshooting
+
+### Windows: sidecar fails to start with an esbuild platform error
+
+The Fastify sidecar runs through `tsx`, which uses esbuild. On a clean Windows
+machine the platform-specific esbuild binary is sometimes not resolved, and
+`npm run dev:server` (or `npx tsx src/local/start.ts`) fails with an error like
+`Cannot find module @esbuild/win32-x64` or an esbuild version/host mismatch.
+
+Fix it by installing the matching Windows esbuild binary without adding it to
+`package.json`:
+
+```bash
+npm i @esbuild/win32-x64@0.28.0 --no-save
+```
+
+This affects **Windows only** — macOS and Linux resolve their esbuild binaries
+normally. The version should match the esbuild your install resolved; `0.28.0`
+is the known-good pin for the sidecar.
+
+## Questions?
+
+Open an issue for architecture questions, feature proposals, or bug reports.