docs: rewrite READMEs with progressive disclosure, add SECURITY.md and roadmap

Main README restructured: collapsable features, quick start with secure defaults, Why a GUI section, roadmap Package READMEs (web/desktop/vscode) rewritten with runtime-specific focus; VSCode includes full commands and settings Added SECURITY.md, non-dev contributing guide, and updated CONTRIBUTING.md with dev scripts and ports
2026-03-05 03:07:26 +02:00
parent 7e38a47e4b
commit f6e0dafeb5
15 changed files with 390 additions and 310 deletions
@@ -1,25 +1,47 @@
 # Contributing to OpenChamber

-## Development
+## Getting Started

 ```bash
 git clone https://github.com/btriapitsyn/openchamber.git
 cd openchamber
 bun install
-
-# Web development
-bun run dev:web:full
-
-# Desktop app (Tauri)
-bun run desktop:dev
-
-# VS Code extension
-bun run vscode:build && code --extensionDevelopmentPath="$(pwd)/packages/vscode"
-
-# Production build
-bun run build
 ```

+## Dev Scripts
+
+### Web
+
+| Script | Description | Ports |
+|--------|-------------|-------|
+| `bun run dev:web:full` | Build watcher + Express server. No HMR — manual refresh after changes. | `3001` (server + static) |
+| `bun run dev:web:hmr` | Vite dev server + Express API. **Open the Vite URL for HMR**, not the backend. | `5180` (Vite HMR), `3902` (API) |
+
+Both are configurable via env vars: `OPENCHAMBER_PORT`, `OPENCHAMBER_HMR_UI_PORT`, `OPENCHAMBER_HMR_API_PORT`.
+
+### Desktop (Tauri)
+
+```bash
+bun run desktop:dev
+```
+
+Launches Tauri in dev mode with WebView devtools enabled and a distinct dev icon.
+
+### VS Code Extension
+
+```bash
+bun run vscode:dev    # Watch mode (extension + webview rebuild on save)
+```
+
+To test in VS Code:
+```bash
+bun run vscode:build && code --extensionDevelopmentPath="$(pwd)/packages/vscode"
+```
+
+### Shared UI (`packages/ui`)
+
+No dev server — this is a source-level library consumed by other packages. During development, `bun run dev` runs type-checking in watch mode.
+
 ## Before Submitting

 ```bash
@@ -31,21 +53,40 @@ bun run build        # Must succeed
 ## Code Style

 - Functional React components only
- TypeScript strict mode - no `any` without justification
- Use existing theme colors/typography - don't add new ones
+- TypeScript strict mode — no `any` without justification
+- Use existing theme colors/typography from `packages/ui/src/lib/theme/` — don't add new ones
 - Components must support light and dark themes
+- Prefer early returns and `if/else`/`switch` over nested ternaries
+- Tailwind v4 for styling; typography via `packages/ui/src/lib/typography.ts`

 ## Pull Requests

 1. Fork and create a branch
 2. Make changes
-3. Run validation commands above
+3. Run the validation commands above
 4. Submit PR with clear description of what and why

 ## Project Structure

+```
+packages/
+  ui/        Shared React components, hooks, stores, and theme system
+  web/       Web server (Express) + frontend (Vite) + CLI
+  desktop/   Tauri macOS app (thin shell around the web UI)
+  vscode/    VS Code extension (extension host + webview)
+```
+
 See [AGENTS.md](./AGENTS.md) for detailed architecture reference.

+## Not a developer?
+
+You can still help:
+
+- Report bugs or UX issues — even "this felt confusing" is valuable feedback
+- Test on different devices, browsers, or OS versions
+- Suggest features or improvements via issues
+- Help others in Discord
+
 ## Questions?

-Open an issue.
+Open an [issue](https://github.com/btriapitsyn/openchamber/issues) or ask in [Discord](https://discord.gg/ZYRSdnwwKA).