@mod-computer/cli 0.1.1 → 0.2.1

package/README.md

@@ -22,6 +22,8 @@ mod-cli bridges local and collaborative workflows. It syncs the local filesystem
 
 **Merge**: Combine branches by merging their changes. Mod detects conflicts at the file level and surfaces them for resolution. Metadata (comments, traces) merges automatically. After merge, the target branch contains changes from both branches with full history preserved.
 
+**Deployment**: Automatic change tracking doesn't mean automatic deployment. Changes sync continuously, but deployment is an explicit action. When ready to deploy, push to git to trigger CI/CD pipelines. Mod handles real-time sync and versioning; git remains the deployment coordination point. This separation lets teams collaborate freely without worrying that every edit triggers a deploy. Work continuously, deploy intentionally.
+
 **Git Integration**: In git repositories, sync respects git branch scope. Changes on a git branch sync to the corresponding Mod branch. Switching git branches switches sync context automatically. For non-git directories, Mod branches work independently. The CLI integrates with git workflows but doesn't require git.
 
 **Metadata Layer**: Workspaces and files carry metadata: comments, notes, and traces. The CLI provides commands to read and write metadata locally. Agents can query file context before making changes and write traces linking code to requirements. Teams see the same metadata in the web app. This shared context layer makes agent reasoning visible and lets teams annotate code without changing source files.
@@ -110,6 +112,76 @@ pnpm dev        # Watch mode
 pnpm test       # Run tests
 ```
 
+## Local Testing with Dev Mode
+
+For testing cross-client workspace syncing on localhost without OAuth, use dev mode authentication:
+
+### Prerequisites
+
+1. **Start the sync server**:
+   ```bash
+   cd packages/mod-sync-server
+   node src/server.js
+   # Server runs on ws://localhost:3030
+   ```
+
+2. **Start the web app** (in another terminal):
+   ```bash
+   cd packages/mod-app-new
+   pnpm dev
+   # App runs on http://localhost:3000
+   # Dev mode automatically enabled (no VITE_MOD_AUTH_URL needed)
+   ```
+
+### Testing Workflow
+
+1. **Login with dev mode**:
+   ```bash
+   AUTOMERGE_WS_URL=ws://localhost:3030 mod auth login --dev
+   ```
+   This creates a local `dev@localhost` user shared between CLI and web app.
+
+2. **Connect a workspace**:
+   ```bash
+   cd /path/to/your/project
+   AUTOMERGE_WS_URL=ws://localhost:3030 mod init
+   ```
+   Select or create a workspace. The workspace connects to your local directory.
+
+3. **Register workspaces to your user**:
+   ```bash
+   AUTOMERGE_WS_URL=ws://localhost:3030 mod workspace register
+   ```
+   This adds all connected workspaces to your user's workspace list, making them visible in the web app.
+
+4. **View in web app**:
+   - Open `http://localhost:3000` in your browser
+   - Refresh the page to see your workspaces
+   - Both CLI and web app share the same `dev@localhost` user document
+   - Changes sync via `ws://localhost:3030`
+
+### Verification
+
+Check authentication status:
+```bash
+AUTOMERGE_WS_URL=ws://localhost:3030 mod auth status
+```
+
+List connected workspaces:
+```bash
+AUTOMERGE_WS_URL=ws://localhost:3030 mod workspace list
+```
+
+View sync diagnostics at `http://localhost:3000/debug/sync` to see tracked documents and sync state.
+
+### Notes
+
+- Dev mode uses a shared `dev@localhost` user across CLI and web app
+- No OAuth required - authentication happens locally
+- User document ID is stored in `~/.mod/config`
+- Both clients must connect to the same sync server (`ws://localhost:3030`)
+- Run `mod workspace register` after creating new workspaces to sync them to the web app
+
 ## Thoughts
 
 **Daemon architecture**: The sync daemon runs as a background process rather than requiring an active terminal. This lets developers work normally while sync happens invisibly. The daemon writes logs to `~/.mod/logs/sync.log` for debugging.