collabmd 0.1.48 → 0.1.51

package/README.md

@@ -26,7 +26,7 @@ Throughout this guide, **vault** simply means a regular folder on your computer
 
 Requirements for the fastest first run:
 
-- Node.js 24 for `npx` and source installs
+- Node.js 26 for `npx` and source installs
 - ripgrep for global text search (`rg`; included in the Docker image)
 - Homebrew only if you want the `brew install` path
 
@@ -49,7 +49,7 @@ Tunnel: disabled
 Ready for collaboration. Press Ctrl+C to stop.
 ```
 
-Prefer Homebrew or source install? Jump to [Installation options](#installation-options).
+Prefer Homebrew or source install? Jump to [Installation options](docs/installation.md).
 
 ## See it in action
 
@@ -66,6 +66,8 @@ Prefer video? [Open the WebM demo](https://raw.githubusercontent.com/andes90/col
 - **Realtime collaboration** — multiple people can edit the same file at the same time via Yjs
 - **External edit sync** — changes made from tools like Obsidian or direct file writes are reflected back into open documents and the file explorer
 - **Git review** — review an open file's changes, include them in the next commit, and commit with a message from the browser
+- **Experimental WebMCP workspace access** — supported browser agents can use the same Vault search, read, exact-edit, document-creation, syntax, and Excalidraw tools as remote MCP while acting as the logged-in collaborator
+- **Remote AI agent access** — connect any Streamable HTTP MCP client to search, cite, edit, and create supported Vault Content; protected workspaces use scoped, revocable Agent Connections
 - **File upload** — import multiple supported Markdown, HTML, Base, diagram, image, and PDF files into the vault from the file explorer
 - **Markdown with context** — live preview, wiki-links, backlinks, outline, quick switcher, and scroll sync
 - **Global text search** — search text across supported vault files with ripgrep-backed results grouped by file
@@ -83,68 +85,6 @@ Prefer video? [Open the WebM demo](https://raw.githubusercontent.com/andes90/col
 - Editing notes and diagrams together while keeping everything as plain files on disk
 - Giving browser access to collaborators who do not use your local markdown setup
 
-## Installation options
-
-### Requirements
-
-- macOS, Linux, or Windows (via WSL2)
-- Node.js 24 for `npx` and source installs
-- ripgrep for global text search. Install with `brew install ripgrep` on macOS, `apk add ripgrep` on Alpine, or `apt install ripgrep` on Debian/Ubuntu. Docker images already include it.
-
-### Run via npx (Node.js)
-
-If you have Node.js installed, you can run CollabMD directly without installing it globally:
-
-```bash
-npx collabmd@latest ~/my-vault --no-tunnel
-```
-
-Open `http://localhost:1234`.
-
-### Install with Homebrew
-
-```bash
-brew tap andes90/tap
-brew install collabmd
-collabmd ~/my-vault --no-tunnel
-```
-
-Or in a single command:
-
-```bash
-brew install andes90/tap/collabmd
-collabmd ~/my-vault --no-tunnel
-```
-
-Open `http://localhost:1234`.
-
-### Install from source
-
-```bash
-git clone https://github.com/andes90/collabmd.git
-cd collabmd
-npm install
-npm run build
-npm link       # optional: makes `collabmd` available globally
-collabmd ~/my-vault --no-tunnel
-```
-
-Open `http://localhost:1234`.
-
-For a safer first run, start local-only:
-
-```bash
-collabmd ~/my-vault --no-tunnel
-```
-
-If you want to share the session over the internet, protect it first:
-
-```bash
-collabmd ~/my-vault --auth password
-```
-
-If `cloudflared` is installed, CollabMD starts a quick tunnel by default unless you pass `--no-tunnel`.
-
 ## Share with a collaborator
 
 If you want to share the workspace over the internet, start with password auth:
@@ -169,8 +109,9 @@ Then share the printed URL and password with your collaborator. If `cloudflared`
 
 - Single-instance deployment only: collaboration room state is kept in-process and is not shared across replicas
 - `oidc` currently supports Google only
-- Hosted workspace mode currently provides the backend/API surface; Team Settings UI, invitation email delivery, GitHub callback redirect polish, and GitHub App checkout/publish wiring are still pending
+- Hosted workspace mode now includes a basic Team Settings UI (collaborators, pending invitations, roles, and access history) plus claim, setup, and invitation-acceptance screens; invitation email delivery, GitHub callback redirect polish, and GitHub App checkout/publish wiring are still pending
 - Text-anchored comments support markdown, Mermaid, PlantUML, and Structurizr DSL files. Excalidraw supports element-anchored threads; draw.io comments are not supported
+- WebMCP requires experimental browser support and an active CollabMD tab; for local Chrome testing, enable `chrome://flags/#enable-webmcp-testing`. It uses the browser session rather than an Agent Connection and does not provide remote access, per-agent scopes, delete, rename, attachments, Git, commit, or publish tools
 - Windows use is supported via WSL2 rather than native Windows execution
 
 ## How it works
@@ -183,7 +124,7 @@ CollabMD starts a local server, scans the vault, and opens a browser-based edito
 
 - **File explorer sidebar** — upload, browse, create, rename, and delete `.md`, `.markdown`, `.mdx`, `.html`, `.htm`, `.base`, `.mmd`, `.mermaid`, `.puml`, `.plantuml`, `.dsl`, `.excalidraw`, `.drawio`, `.pdf`, and supported image files plus folders
 - **Live preview** — rendered as you type, with sandboxed static HTML, syntax-highlighted code blocks, public video embeds, plus Mermaid, PlantUML, and Structurizr diagrams
-- **Anchored comments** — add comments from the editor or selected Excalidraw elements, reopen threads in context, and review them from the comments drawer
+- **Anchored comments and diagram links** — add comments from the editor or selected Excalidraw elements, reopen threads in context, and link Excalidraw elements to other vault diagrams with focused navigation
 - **`[[wiki-links]]` + backlinks** — jump between notes and inspect linked mentions
 - **Room chat** — discuss changes without leaving the workspace
 - **Presence + follow mode** — see who is online and follow another collaborator's active cursor
@@ -203,550 +144,16 @@ Markdown video embeds are opt-in and use standard image syntax such as `![Video]
 
 Your filesystem is the source of truth. CollabMD reads files from disk, uses Yjs for realtime collaboration, and continuously writes plain text back to disk as you type. External changes from tools like Obsidian, direct file writes, or git-driven file updates are watched and reconciled back into live rooms and the explorer. The file explorer can import multiple supported vault files at once; uploads preserve their names and bytes, reject duplicates, and include PDF files for readonly preview.
 
-## Usage
-
-```bash
-collabmd [directory] [options]
-```
-
-### Arguments
-
-| Argument | Description |
-|----------|-------------|
-| `directory` | Path to the vault directory (default: current directory) |
-
-### Options
-
-| Option | Description | Default |
-|--------|-------------|---------|
-| `-p, --port` | Port to listen on | `1234` |
-| `--host` | Host to bind to | `127.0.0.1` |
-| `--auth` | Auth strategy: `none`, `password`, `oidc` | `none` |
-| `--auth-password` | Password for `--auth password` | generated per run |
-| `--local-plantuml` | Start the bundled local docker-compose PlantUML service | off |
-| `--local-structurizr` | Start the bundled local Structurizr renderer | off |
-| `--no-tunnel` | Don't start Cloudflare Tunnel | tunnel on |
-| `-v, --version` | Show version | |
-| `-h, --help` | Show help | |
-
-### Examples
-
-```bash
-# Serve the current directory locally
-collabmd --no-tunnel
-
-# Serve a specific vault locally
-collabmd ~/my-vault --no-tunnel
-
-# Use a custom port, no tunnel
-collabmd --port 3000 --no-tunnel
-
-# Share with collaborators using a generated password
-collabmd --auth password
-
-# Require an explicit password
-collabmd --auth password --auth-password "shared-secret"
-
-# Use Google OIDC on a stable public domain
-PUBLIC_BASE_URL=https://notes.example.com \
-AUTH_OIDC_CLIENT_ID=your-google-client-id \
-AUTH_OIDC_CLIENT_SECRET=your-google-client-secret \
-collabmd --auth oidc --no-tunnel
-
-# Use the local docker-compose PlantUML service
-collabmd --local-plantuml
-
-# Use the local Structurizr renderer for .dsl workspaces
-collabmd --local-structurizr
-
-# Serve an Obsidian vault
-collabmd ~/Documents/Obsidian/MyVault
-```
-
-## Public access
-
-CollabMD can optionally expose the session using a [Cloudflare Quick Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/). Since the editor uses same-origin WebSocket routing (`/ws/:file`), the tunnel works for both HTTP and collaboration traffic.
-
-If you are exposing the session publicly, `collabmd --auth password` is the intended first-line protection. When you do not pass `--auth-password`, CollabMD generates a password for that host run and prints it in the terminal. Restarting the app rotates that password and the signed session secret.
-
-To share safely:
-
-```bash
-collabmd ~/my-vault --auth password
-```
-
-`cloudflared` is optional. Install it only if you want public tunnel access:
-
-- macOS: `brew install cloudflared`
-- Linux/Windows: [official installer](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)
-
-To disable the tunnel:
-
-```bash
-collabmd --no-tunnel
-```
-
-### Google OIDC setup
-
-`--auth oidc` uses Google OpenID Connect with the authorization code + PKCE flow.
-
-For the full Google Cloud Console walkthrough, including where to create the OAuth client and copy the client ID/client secret, see [docs/google-oidc-setup.md](https://github.com/andes90/collabmd/blob/master/docs/google-oidc-setup.md).
-
-Required environment variables:
-
-```bash
-PUBLIC_BASE_URL=https://notes.example.com
-AUTH_OIDC_CLIENT_ID=your-google-client-id
-AUTH_OIDC_CLIENT_SECRET=your-google-client-secret
-```
-
-In Google Cloud Console, create a Web application OAuth client and register this redirect URI:
-
-```text
-https://notes.example.com/api/auth/oidc/callback
-```
-
-If you mount the app under a subpath with `BASE_PATH=/collabmd`, the redirect URI becomes:
-
-```text
-https://notes.example.com/collabmd/api/auth/oidc/callback
-```
-
-Notes:
-
-- OIDC requires a stable public URL and is not compatible with ephemeral Cloudflare Quick Tunnel URLs
-- After sign-in, the verified Google name/email become the displayed app identity and the default in-app git commit author
-- Set `AUTH_SESSION_MAX_AGE_MS` to keep the signed-in session valid longer than the default token lifetime
-- You can restrict sign-in to exact users with `AUTH_OIDC_ALLOWED_EMAILS` or entire domains with `AUTH_OIDC_ALLOWED_DOMAINS`
-- The CLI disables the tunnel automatically when `--auth oidc` is active
-
-### Single-tenant hosted workspace mode
-
-Hosted workspace mode is for manually provisioned, single-tenant deployments: one CollabMD app replica for one team, one workspace, one vault source, and one hosted metadata store. It is not a shared multi-tenant account system.
-
-Hosted mode requires Google OIDC:
-
-```bash
-AUTH_STRATEGY=oidc
-PUBLIC_BASE_URL=https://notes.example.com
-AUTH_OIDC_CLIENT_ID=your-google-client-id
-AUTH_OIDC_CLIENT_SECRET=your-google-client-secret
-COLLABMD_HOSTED_ENABLED=true
-```
-
-The first Team Admin is created through an email-bound workspace claim. Set the intended admin email and a one-time claim token when provisioning the deployment:
-
-```bash
-COLLABMD_HOSTED_CLAIM_EMAIL=admin@example.com
-COLLABMD_HOSTED_CLAIM_TOKEN=generated-one-time-secret
-```
-
-The claim is seeded into hosted metadata and expires after 7 days. The claimant must sign in with the matching verified Google email. After claim, Team Admins can manage active memberships, pending invitations, roles, and the access audit trail through the hosted API. The first roles are:
-
-- `admin` — can manage team access and configure initial workspace setup
-- `collaborator` — can access, edit, and publish changes after setup is complete
-
-Hosted metadata is stored in SQLite and defaults to `.collabmd/hosted.sqlite` inside the vault directory. Override it when the metadata store should live on a separate persistent volume:
-
-```bash
-COLLABMD_HOSTED_METADATA_DB_PATH=/data/.collabmd/hosted.sqlite
-```
-
-Hosted vault-source setup is GitHub-only in the first version and uses a GitHub App installation flow. Configure the GitHub App credentials on the server:
-
-```bash
-COLLABMD_GITHUB_APP_ID=123456
-COLLABMD_GITHUB_APP_SLUG=collabmd
-COLLABMD_GITHUB_APP_PRIVATE_KEY_FILE=/run/secrets/collabmd_github_app_private_key.pem
-```
-
-`COLLABMD_GITHUB_APP_PRIVATE_KEY` is also supported for environments that inject the private key directly. The Team Admin starts setup, installs the GitHub App, and selects exactly one repository. CollabMD resolves the installation and repository from GitHub, captures the selected repository's default branch as the configured branch, and stores that vault-source metadata in SQLite. The browser does not directly submit trusted repository or installation metadata.
-
-Current backend endpoints include:
-
-- `GET /api/hosted/status`
-- `POST /api/hosted/claim`
-- `POST /api/hosted/vault-source/github/setup`
-- `GET /api/hosted/vault-source/github/callback`
-- `GET /api/hosted/memberships`
-- `POST /api/hosted/invitations`
-- `POST /api/hosted/invitations/accept`
-- `GET /api/hosted/audit`
-
-Until the Team Settings UI and invitation email delivery are added, these are backend integration points rather than a complete hosted onboarding screen.
-
-### Draw.io setup
-
-CollabMD uses diagrams.net for `.drawio` rendering and editing. By default it points at the hosted embed runtime:
-
-```bash
-COLLABMD_DRAWIO_BASE_URL=https://embed.diagrams.net
-```
-
-You can also point it at a self-hosted diagrams.net deployment:
-
-```bash
-COLLABMD_DRAWIO_BASE_URL=https://drawio.example.com
-```
-
-If the draw.io runtime is unavailable, direct `.drawio` file opens fall back to plain XML editing instead of leaving the file inaccessible.
-
-You can also configure the tunnel via environment variables:
-
-```bash
-TUNNEL_TARGET_PORT=4000 collabmd
-TUNNEL_TARGET_URL=http://127.0.0.1:4000 collabmd
-CLOUDFLARED_EXTRA_ARGS="--loglevel info" collabmd
-```
-
-For the full runtime env var reference, see the `Environment variables` details block in the Development section below.
-
-## Docker / Coolify deployment
-
-Published image: `ghcr.io/andes90/collabmd:latest`
-
-From the vault directory:
-
-```bash
-docker run --rm -p 1234:1234 -v "$PWD:/data" ghcr.io/andes90/collabmd:latest
-```
-
-Open `http://localhost:1234`. The published Docker image includes `ripgrep`, so global text search works without installing extra packages in the container.
-
-The container listens on `0.0.0.0:1234` and stores vault files at `/data`.
-
-### Kubernetes / Helm
-
-CollabMD now includes a Helm chart at [`packaging/helm/collabmd`](./packaging/helm/collabmd).
-
-Use it when you want a Kubernetes-native deployment with:
-
-- one supported application replica
-- a persistent volume mounted at `/data`
-- optional ingress
-- optional bundled PlantUML
-- secret-backed auth and private git bootstrap settings
-
-Quick start:
-
-```bash
-helm install collabmd ./packaging/helm/collabmd
-```
-
-For examples covering ingress, OIDC, PlantUML, and private git bootstrap, see [packaging/helm/collabmd/README.md](./packaging/helm/collabmd/README.md).
-
-To bootstrap `/data` from a private git repository instead, pass the repo URL plus SSH credentials:
-
-```bash
-docker run \
-  -p 1234:1234 \
-  -v /path/to/persistent/vault:/data \
-  -e COLLABMD_GIT_REPO_URL=git@github.com:your-org/your-private-vault.git \
-  -e COLLABMD_GIT_SSH_PRIVATE_KEY_B64="$(base64 < ~/.ssh/id_ed25519 | tr -d '\n')" \
-  -e COLLABMD_GIT_USER_NAME="CollabMD Bot" \
-  -e COLLABMD_GIT_USER_EMAIL="bot@example.com" \
-  ghcr.io/andes90/collabmd:latest
-```
-
-For a full local and Docker test walkthrough, including key generation and deploy-key setup, see [docs/private-git-deployment.md](https://github.com/andes90/collabmd/blob/master/docs/private-git-deployment.md).
-
-When `COLLABMD_GIT_REPO_URL` is set, CollabMD clones into `COLLABMD_VAULT_DIR` on first boot, then reuses that checkout on later starts. If the checkout already exists, startup validates that `origin` matches. Clean checkouts are fast-forwarded to the remote default branch; dirty checkouts are reused as-is and startup skips the sync.
-
-After bootstrap, CollabMD adds `.collabmd/` to the checkout's local git exclude file at `.git/info/exclude` so runtime metadata stays out of git status without modifying the repo's tracked `.gitignore`.
-
-File-based secrets are also supported and take precedence over base64 input:
-
-```bash
-docker run \
-  -p 1234:1234 \
-  -v /path/to/persistent/vault:/data \
-  -v ~/.ssh/id_ed25519:/run/secrets/collabmd_git_key:ro \
-  -v ~/.ssh/known_hosts:/run/secrets/collabmd_known_hosts:ro \
-  -e COLLABMD_GIT_REPO_URL=git@github.com:your-org/your-private-vault.git \
-  -e COLLABMD_GIT_SSH_PRIVATE_KEY_FILE=/run/secrets/collabmd_git_key \
-  -e COLLABMD_GIT_SSH_KNOWN_HOSTS_FILE=/run/secrets/collabmd_known_hosts \
-  -e COLLABMD_GIT_USER_NAME="CollabMD Bot" \
-  -e COLLABMD_GIT_USER_EMAIL="bot@example.com" \
-  ghcr.io/andes90/collabmd:latest
-```
-
-### Local docker-compose with private diagram renderers
-
-The included `docker-compose.yml` runs a prebuilt CollabMD image together with local PlantUML and Structurizr containers. PlantUML SVG rendering and Structurizr `workspace.dsl` previews stay on the private Docker network automatically.
-
-```bash
-mkdir -p data/vault
-docker compose up
-```
-
-Open `http://localhost:1234`.
-
-To test Google OIDC locally with the included compose setup, register this redirect URI in Google Cloud Console:
-
-```text
-http://localhost:1234/api/auth/oidc/callback
-```
-
-Then start compose with the OIDC env vars:
-
-```bash
-AUTH_STRATEGY=oidc \
-PUBLIC_BASE_URL=http://localhost:1234 \
-AUTH_OIDC_CLIENT_ID=your-google-client-id \
-AUTH_OIDC_CLIENT_SECRET=your-google-client-secret \
-docker compose up
-```
-
-If you change `COLLABMD_HOST_PORT`, update `PUBLIC_BASE_URL` and the Google redirect URI to match that host port.
-
-By default, compose uses `COLLABMD_IMAGE=ghcr.io/andes90/collabmd:latest`. If you want to test a local image while developing instead:
-
-```bash
-docker build -t collabmd:local .
-COLLABMD_IMAGE=collabmd:local docker compose up
-```
-
-The PlantUML container is published on loopback by default at `http://127.0.0.1:18080`, and Structurizr is published at `http://127.0.0.1:19090` for host-based CLI use:
-
-```bash
-npm run start:local-plantuml
-
-# Start CollabMD with Structurizr DSL support
-npm run start:local-structurizr -- --no-tunnel
-```
-
-To use an existing vault on your machine instead of `./data/vault`:
-
-```bash
-HOST_VAULT_DIR=/absolute/path/to/vault docker compose up
-```
-
-`HOST_VAULT_DIR` controls the host-side bind mount source. The app uses `COLLABMD_VAULT_DIR` for the in-container vault path and defaults that to `/data` in Docker.
-
-To bootstrap the compose-managed vault from a private repo, set the git env vars in `.env` and keep `HOST_VAULT_DIR` on a persistent host path. For file-based SSH auth, point `COLLABMD_GIT_SSH_PRIVATE_KEY_FILE` and `COLLABMD_GIT_SSH_KNOWN_HOSTS_FILE` at mounted secret paths; for simpler setups, set `COLLABMD_GIT_SSH_PRIVATE_KEY_B64` instead.
-
-If you want the in-app Git commit action to work inside the container without OIDC, also set `COLLABMD_GIT_USER_NAME` and `COLLABMD_GIT_USER_EMAIL` so CollabMD can configure the checkout identity automatically. With `AUTH_STRATEGY=oidc`, CollabMD uses the signed-in Google identity for each commit instead.
-
-To change the host port:
-
-```bash
-COLLABMD_HOST_PORT=3000 docker compose up
-```
-
-To change the local PlantUML host port used by both `docker compose` and `--local-plantuml`:
-
-```bash
-PLANTUML_HOST_PORT=18081 npm run start:local-plantuml
-```
-
-Recommended Coolify setup:
-
-1. Use the included `Dockerfile`.
-2. Expose port `1234`.
-3. Mount a persistent volume to `/data` for the vault checkout and runtime files. It can be pre-populated with markdown files or start empty when `COLLABMD_GIT_REPO_URL` is enabled.
-4. Add `COLLABMD_GIT_REPO_URL` plus either `COLLABMD_GIT_SSH_PRIVATE_KEY_FILE` or `COLLABMD_GIT_SSH_PRIVATE_KEY_B64` if the vault should be cloned from a private repo.
-5. Mount `known_hosts` and set `COLLABMD_GIT_SSH_KNOWN_HOSTS_FILE` if you want strict host verification.
-6. Add a health check for `GET /health` with enough startup grace for the initial clone.
-7. Run a single replica only because room state is in-process and not shared across instances.
-8. Set `BASE_PATH` if the app is mounted under a subpath such as `/collabmd`.
-9. Set `PUBLIC_WS_BASE_URL` only if your WebSocket endpoint differs from the app origin.
-
-For a standard Coolify reverse-proxy setup, the default same-origin WebSocket routing works as-is and you should not need `PUBLIC_WS_BASE_URL`.
-
-Health check: `GET /health`
-
-## Troubleshooting
-
-- `npx collabmd@latest` fails immediately: confirm you are running Node.js 24, which is the supported runtime for source and npm usage
-- The app is reachable only from localhost: pass `--host 0.0.0.0` or set `HOST=0.0.0.0` when you intend to expose it on your network
-- Port `1234` is already in use: pass `--port 3000` or set `PORT` to another free port
-- Tunnel did not start: install `cloudflared`, or pass `--no-tunnel` to stay local-only
-- `--auth oidc` fails on startup: set `PUBLIC_BASE_URL`, `AUTH_OIDC_CLIENT_ID`, and `AUTH_OIDC_CLIENT_SECRET`, and make sure the Google redirect URI matches `/api/auth/oidc/callback`
-- Google login loops back to the auth screen: verify the configured `PUBLIC_BASE_URL` matches the browser URL and that your reverse proxy forwards HTTPS correctly
-- `--local-plantuml` fails: make sure Docker is installed and running, or point `PLANTUML_SERVER_URL` at another PlantUML server
-- Global text search is disabled: install `ripgrep` on the server host and restart CollabMD. Docker images already include `ripgrep`.
-- Private git bootstrap fails on startup: verify `COLLABMD_GIT_REPO_URL` plus either `COLLABMD_GIT_SSH_PRIVATE_KEY_FILE` or `COLLABMD_GIT_SSH_PRIVATE_KEY_B64`
-- WSL2 path issues: run CollabMD against a directory inside your Linux filesystem when possible rather than a mounted Windows path
-
-## Development
-
-Install dependencies:
-
-```bash
-npm install
-```
-
-Build and run:
-
-```bash
-npm start
-```
-
-Open `http://localhost:1234`.
-
-Useful commands:
-
-```bash
-npm run build                 # Build the Vite client into dist/client
-npm run check                 # Syntax check all entry points
-npm run dev:client            # Start the Vite dev server with API/WebSocket proxying
-npm run dev:server            # Start only the backend server for local frontend development
-npm run start                 # Build + start server
-npm run start:local-plantuml  # Build + start server with local docker-compose PlantUML
-npm run start:local-structurizr # Build + start server with local Structurizr
-npm run start:prod            # Start server (expects previous build)
-npm run test                  # Run unit + e2e tests
-npm run test:unit             # Fast Node-based unit tests
-npm run test:e2e              # Playwright browser tests
-npm run tunnel                # Start only the Cloudflare tunnel
-npm run plantuml:up           # Start only the local docker-compose PlantUML service
-npm run plantuml:down         # Stop only the local docker-compose PlantUML service
-npm run structurizr:up        # Start only the local Structurizr renderer
-npm run structurizr:down      # Stop only the local Structurizr renderer
-npm run capture:readme-assets # Regenerate the README screenshot and demo assets
-```
-
-## Testing
-
-### Unit tests
-
-```bash
-npm run test:unit
-```
-
-Covers the vault file store, HTTP endpoints, collaboration room behavior, WebSocket integration, and supporting domain logic.
-
-### End-to-end tests
-
-```bash
-npx playwright install chromium    # first time only
-npm run test:e2e
-```
-
-Playwright boots the full app against the `test-vault/` directory and verifies the file explorer, editor, preview, collaboration, chat, outline, and scroll sync flows.
-
-### All tests
-
-```bash
-npm run test
-```
-
-<details>
-<summary>Architecture</summary>
-
-```text
-bin/
-  collabmd.js              CLI entry point
-src/
-  client/
-    app/                     Vite-owned HTML entries and browser entry modules
-    application/           app orchestration, preview rendering, workspace coordination
-    bootstrap/             app-shell composition and startup wiring
-    domain/                markdown editing, wiki-link, room, and vault helpers
-    infrastructure/        runtime config, auth bootstrap, browser ports, collaborative editor session
-    presentation/          file explorer, backlinks, quick switcher, outline, scroll sync, theme, layout
-    static/                Vite passthrough assets copied into the built client
-    styles/                app CSS
-  domain/                  shared wiki-link helpers
-  server/
-    auth/                  strategy selection and cookie-backed auth sessions
-    config/                environment loading
-    domain/                collaboration room model, registry, backlink index, server-side abstractions
-    infrastructure/        HTTP handlers, git service, vault file store, PlantUML, WebSocket gateway
-    startup/               preflight vault bootstrap, including remote git checkout setup
-dist/
-  client/                  built client served by the backend and packaged for release
-scripts/
-  cloudflare-tunnel.mjs    Cloudflare quick tunnel helper
-  local-plantuml-compose.mjs
-  capture-readme-assets.mjs
-vite.config.mjs            Vite multi-page build and dev-server proxy config
-```
-
-</details>
-
-<details>
-<summary>Environment variables</summary>
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `HOST` | Bind host | `127.0.0.1` (dev), `0.0.0.0` (prod) |
-| `PORT` | HTTP + WebSocket port | `1234` |
-| `AUTH_STRATEGY` | Auth strategy: `none`, `password`, `oidc` | `none` |
-| `AUTH_PASSWORD` | Shared password for `AUTH_STRATEGY=password` | generated per run |
-| `AUTH_SESSION_COOKIE_NAME` | Session cookie name | `collabmd_auth` |
-| `AUTH_SESSION_SECRET` | Cookie signing secret | generated per run |
-| `AUTH_SESSION_MAX_AGE_MS` | Optional auth session lifetime in milliseconds; when set, cookies persist until that expiry | |
-| `PUBLIC_BASE_URL` | Stable public app origin required for `AUTH_STRATEGY=oidc` | |
-| `AUTH_OIDC_CLIENT_ID` | Google OAuth client ID used for `AUTH_STRATEGY=oidc` | |
-| `AUTH_OIDC_CLIENT_SECRET` | Google OAuth client secret used for `AUTH_STRATEGY=oidc` | |
-| `AUTH_OIDC_ALLOWED_EMAILS` | Comma-separated exact email allowlist for `AUTH_STRATEGY=oidc` | |
-| `AUTH_OIDC_ALLOWED_DOMAINS` | Comma-separated email domain allowlist for `AUTH_STRATEGY=oidc` | |
-| `BASE_PATH` | URL path prefix for subpath deployments | |
-| `COLLABMD_HOSTED_ENABLED` | Enable single-tenant hosted workspace mode; requires `AUTH_STRATEGY=oidc` | `false` |
-| `COLLABMD_HOSTED_METADATA_DB_PATH` | SQLite database path for hosted workspace metadata | `<vault>/.collabmd/hosted.sqlite` |
-| `COLLABMD_HOSTED_CLAIM_EMAIL` | Verified Google email allowed to claim the first Team Admin role | |
-| `COLLABMD_HOSTED_CLAIM_TOKEN` | One-time token required for the first workspace claim | |
-| `COLLABMD_GITHUB_APP_ID` | GitHub App ID used for hosted vault-source setup | |
-| `COLLABMD_GITHUB_APP_SLUG` | GitHub App slug used to build the installation setup URL | |
-| `COLLABMD_GITHUB_APP_PRIVATE_KEY` | GitHub App private key; `\n` escapes are converted to newlines | |
-| `COLLABMD_GITHUB_APP_PRIVATE_KEY_FILE` | File path for the GitHub App private key; used when direct key input is not set | |
-| `COLLABMD_GITHUB_API_BASE_URL` | GitHub API base URL for hosted vault-source setup | `https://api.github.com` |
-| `COLLABMD_GITHUB_HTML_BASE_URL` | GitHub web base URL for installation setup | `https://github.com` |
-| `COLLABMD_GITHUB_SETUP_FLOW_COOKIE_NAME` | Signed cookie name for the GitHub App setup callback flow | `collabmd_github_setup_flow` |
-| `PLANTUML_SERVER_URL` | Upstream PlantUML server base URL used for server-side SVG rendering | `https://www.plantuml.com/plantuml` |
-| `STRUCTURIZR_SERVER_URL` | Structurizr Local-compatible sidecar base URL used for `.dsl` previews | disabled |
-| `COLLABMD_STRUCTURIZR_MIRROR_DIR` | Writable disposable mirror directory passed to Structurizr | `<vault>/.collabmd/structurizr` |
-| `COLLABMD_STRUCTURIZR_TRUSTED_EXECUTABLE_DSL` | Allow Structurizr `!script` and `!plugin` directives; keep false for untrusted vaults | `false` |
-| `COLLABMD_DRAWIO_BASE_URL` | diagrams.net base URL used for `.drawio` viewing and editing | `https://embed.diagrams.net` |
-| `COLLABMD_WIKI_LINK_AUTO_CREATE` | Create missing markdown files when clicking unresolved wiki-links; set to `false` to disable | `true` |
-| `COLLABMD_SEARCH_MAX_FILE_SIZE` | Maximum size of each file considered by global text search; supports bytes or `K`, `M`, and `G` suffixes | `1M` |
-| `COLLABMD_SEARCH_MAX_BUFFER_BYTES` | Maximum ripgrep output buffer for one global text search | `2097152` |
-| `COLLABMD_MAX_PDF_UPLOAD_BYTES` | Maximum size of a PDF upload in bytes; other uploads remain limited to the default 8 MiB request-body limit | `52428800` |
-| `COLLABMD_VAULT_DIR` | Vault directory path | CLI: current directory, server entrypoint: `data/vault`, Docker: `/data` |
-| `COLLABMD_GIT_ENABLED` | Enable or disable git integration in the UI and API | `true` |
-| `COLLABMD_GIT_REPO_URL` | Remote git repository used to bootstrap the vault checkout | |
-| `COLLABMD_GIT_SSH_PRIVATE_KEY_FILE` | SSH private key file path for remote git auth; preferred over base64 input | |
-| `COLLABMD_GIT_SSH_PRIVATE_KEY_B64` | Base64-encoded SSH private key used when no key file path is provided | |
-| `COLLABMD_GIT_SSH_KNOWN_HOSTS_FILE` | Optional `known_hosts` file path for strict SSH host verification | |
-| `COLLABMD_GIT_USER_NAME` | Fallback git author/committer name for in-app commits when OIDC is not active | |
-| `COLLABMD_GIT_USER_EMAIL` | Fallback git author/committer email for in-app commits when OIDC is not active | |
-| `WS_BASE_PATH` | WebSocket base path | `/ws` |
-| `PUBLIC_WS_BASE_URL` | Public WebSocket URL override for reverse proxies | |
-| `HTTP_KEEP_ALIVE_TIMEOUT_MS` | Keep-alive timeout | `5000` |
-| `HTTP_HEADERS_TIMEOUT_MS` | Header read timeout | `60000` |
-| `HTTP_REQUEST_TIMEOUT_MS` | Request timeout | `30000` |
-| `WS_HEARTBEAT_INTERVAL_MS` | Heartbeat interval for evicting dead clients | `30000` |
-| `WS_ROOM_IDLE_GRACE_MS` | Delay before closing empty collaboration rooms to disk | `15000` |
-| `WS_MAX_BUFFERED_AMOUNT_BYTES` | Max outbound buffer per WebSocket | `16777216` |
-| `WS_MAX_PAYLOAD_BYTES` | Max inbound WebSocket frame | `16777216` |
-| `CLOUDFLARED_BIN` | `cloudflared` binary path | `cloudflared` |
-| `TUNNEL_TARGET_HOST` | Tunnel target host | `127.0.0.1` |
-| `TUNNEL_TARGET_PORT` | Tunnel target port | `1234` |
-| `TUNNEL_TARGET_URL` | Full tunnel target URL override | |
-| `CLOUDFLARED_EXTRA_ARGS` | Extra `cloudflared` flags | |
-
-Copy the example file:
-
-```bash
-cp .env.example .env
-```
-
-</details>
-
-## Notes
 
-- The filesystem is the source of truth; Yjs provides the collaboration layer.
-- When `COLLABMD_GIT_REPO_URL` is set, startup clones the configured repo into `COLLABMD_VAULT_DIR` on first boot and reuses an existing same-origin checkout on later starts.
-- If `COLLABMD_GIT_SSH_KNOWN_HOSTS_FILE` is not set, SSH falls back to `StrictHostKeyChecking=accept-new`.
-- External filesystem edits are reconciled back into active rooms and the explorer. Ambiguous watcher bursts still fall back to batched workspace reconciliation.
-- `.obsidian`, `.git`, `.trash`, and `node_modules` directories are ignored.
-- Markdown, HTML, Base, Mermaid, PlantUML, Structurizr DSL, draw.io, Excalidraw, PDF, and image files are tracked by the vault tree; global text search indexes supported text formats.
-- PlantUML preview rendering is server-side and uses `PLANTUML_SERVER_URL`; point it at a self-hosted renderer if you do not want to use the public PlantUML service.
-- Structurizr previews use a read-only official Local sidecar and a disposable `.collabmd/structurizr` mirror; the authoritative vault is never mounted into the renderer as its data directory.
-- `docker compose up` uses the included local PlantUML and Structurizr services and avoids public diagram renderers by default. The initial git clone may also require a longer health-check grace period than a purely local vault.
-- `collabmd --local-plantuml` and `npm run start:local-plantuml` start the local PlantUML compose service. `collabmd --local-structurizr` starts Structurizr Local against `http://127.0.0.1:${STRUCTURIZR_HOST_PORT:-19090}`.
+## Docs
 
+- [Installation](docs/installation.md) — requirements, npx, Homebrew, and source installs
+- [Configuration](docs/configuration.md) — CLI usage and environment variables
+- [Auth and access](docs/auth-and-access.md) — password, Google OIDC, and hosted workspaces
+- [Deployment](docs/deployment.md) — Docker, Coolify, Helm, and private git
+- [AI agents](docs/ai-agents.md) — MCP and WebMCP access
+- [Development](docs/dev/development.md) — architecture, dev commands, and tests
+- [Troubleshooting](docs/troubleshooting.md)
 ## License
 
 MIT