thinkncollab-shell 0.0.19 → 2.0.0-beta.1

package/Readme.md

@@ -1,577 +1,321 @@
-# ThinkNCollab Shell (`thinknsh`)
+# ThinkNCollab Shell V2 (`thinknsh`)
 
-A real-time collaborative terminal shell with WebSocket integration, built on top of the ThinkNCollab platform. Run commands, join rooms, chat with teammates, manage tasks, share terminals — all from your CLI.
+> **The Native-First Collaborative Developer OS: Lightweight MicroVM Sandbox & Zero-Daemon Dev Runner with Live Database Snapshots, P2P Terminal Multiplexing, and OCI Compatibility.**
 
----
-
-## Table of Contents
-
-- [Features](#features)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Configuration](#configuration)
-- [Environment Variables](#environment-variables)
-- [CLI Flags](#cli-flags)
-- [Interactive Shell](#interactive-shell)
-- [Commands Reference](#commands-reference)
-  - [Auth Commands](#auth-commands)
-  - [Room Commands](#room-commands)
-  - [Message Commands](#message-commands)
-  - [Task Commands](#task-commands)
-  - [Terminal Share Commands](#terminal-share-commands)
-  - [Notification Commands](#notification-commands)
-  - [Shell Commands](#shell-commands)
-  - [GitHub Integration Commands](#github-integration-commands)
-- [`tncproject` Auto-Boot](#tncproject-auto-boot)
-- [Notification Window](#notification-window)
-- [Built-in Shell Features](#built-in-shell-features)
-- [Single-Command Mode](#single-command-mode)
-- [Examples](#examples)
+[![npm version](https://img.shields.io/npm/v/thinkncollab-shell.svg)](https://www.npmjs.com/package/thinkncollab-shell)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+[![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows%20(WSL2)-brightgreen.svg)](#platform-isolation-matrix)
+[![Runtime](https://img.shields.io/badge/Runtime-Apple_Virtualization_%7C_crun_OCI-blueviolet.svg)](#core-capabilities)
 
 ---
 
-## Features
+## 🌟 What is ThinkNCollab Shell?
 
-- 🚀 **Custom Shell** — Full-featured interactive REPL with persistent history
-- 🔌 **WebSocket Integration** — Real-time bidirectional sync with ThinkNCollab servers
-- 👥 **Room Collaboration** — Join rooms, chat, and see who's online in real time
-- 📋 **Task Management** — Accept, start, complete, and reject tasks from the CLI
-- 📺 **Terminal Sharing** — Share your live terminal session with teammates (read + write access)
-- 🔔 **Notification Window** — Background TCP-based popup window for live events
-- 🔑 **`tncproject` Auto-Boot** — Drop a config file in your project root to auto-login and join a room on shell start
-- 🛡️ **Shell Token Auth** — Secure HMAC-SHA256 token validation for shell connections
-- 📁 **File System** — Built-in `ls`, `cd`, `pwd`, plus passthrough to your system shell
-- 📜 **History** — Persisted command history at `~/.thinknsh_history`
-- 🎨 **Colored Output** — chalk-powered terminal output
-
----
+**ThinkNCollab Shell (`thinknsh`)** is a native-first development shell, process sandbox, and collaborative runtime built to eliminate everyday developer environment friction.
 
-## Installation
-
-```bash
-# Install globally (recommended)
-npm install -g thinkncollab-shell
-
-# Or install locally in a project
-npm install thinkncollab-shell
-```
-
-After a global install the `thinknsh` binary is available everywhere on your system.
+Instead of running a heavy 4GB+ RAM virtual machine daemon just to boot a local database, wrestling with teammate database migration drift, or sharing laggy video screens, **ThinkNCollab unifies your code, database, and terminal into a single peer-to-peer developer shell.**
 
 ---
 
-## Quick Start
-
-```bash
-# 1. Start the interactive shell
-thinknsh
-
-# 2. Log in
-thinknsh> login
+## 📦 Containers: `thinknsh run`, `build`, `compose`
 
-# 3. Join a room
-thinknsh> join <room-id>
-
-# 4. Send a message
-thinknsh> say Hello team!
-
-# 5. Check session status
-thinknsh> status
-```
-
----
-
-## Configuration
-
-By default `thinknsh` connects to `https://thinkncollab.com`. Override the server in any session using environment variables:
+thinknsh has its own container engine, **dock**. You run, build and compose OCI containers with thinknsh commands. No other tool is needed. Images come from any OCI registry (the public one that hosts alpine, postgres and nginx works out of the box), containers run with `crun` on a real Linux kernel, and all state lives in one SQLite file. The daemon starts by itself on the first command.
 
 ```bash
-export THINKNCOLLAB_SERVER=https://thinkncollab.com
-export THINKNCOLLAB_API_URL=https://thinkncollab.com
-export THINKNCOLLAB_WS_URL=https://thinkncollab.com
-thinknsh
-```
-
-Or inline for a single run:
+thinknsh run --rm -it alpine sh                                   # interactive shell (Ctrl-P Ctrl-Q detaches)
+thinknsh run -d --name db -e POSTGRES_PASSWORD=dev -p 5432:5432 postgres:16
+thinknsh ps                                                       # -a for stopped ones too
+thinknsh logs -f db
+thinknsh exec -it db psql -U postgres
+thinknsh build -t myapp .                                         # Containerfile (or the classic build file name)
+thinknsh compose up -d                                            # compose.yaml in this folder
+thinknsh compose logs -f
+thinknsh compose down -v
+thinknsh login -u me ghcr.io                                      # asks for the password (or --password-stdin)
+thinknsh tag myapp ghcr.io/me/myapp:1.0 && thinknsh push ghcr.io/me/myapp:1.0
+thinknsh logout ghcr.io
+```
+
+Registry logins are checked with the registry, then saved per registry host in `~/.tnc/dock/auth.json` (mode 0600, read only by the dock daemon, never shown by any command). `thinknsh login` with an email, or with no arguments, still signs you in to ThinkNCollab; with `-u`, `--password-stdin` or a registry host it logs in to a container registry. `thinknsh push ecr://…` and `push --export` still go to the sandbox exporter. Registries on `localhost`/`127.0.0.1` use plain HTTP; for another plain-HTTP registry (a LAN registry for `thinknsh cluster`), list its host:port in `TNC_DOCK_INSECURE_REGISTRIES`.
+
+Every command has its own help, for example `thinknsh run --help`. The full list:
+
+| Area | Commands |
+| :--- | :--- |
+| Containers | `run`, `create`, `start`, `stop`, `restart`, `kill`, `rm`, `ps`, `logs`, `exec`, `wait`, `inspect` |
+| Images | `images`, `pull`, `push`, `build`, `tag`, `rmi`, `image prune` |
+| Registries | `login [-u USER] [--password-stdin] [REGISTRY]`, `logout [REGISTRY]` |
+| Agent workspaces | `workspace up / open / apps / ls / shell / exec / ssh-config / stop / rm` |
+| Dev services | `service start postgres\|redis\|mysql [-p PORT]`, `service stop / restart / status / logs / rm [-v]` |
+| Local registry | `registry start [PORT] / stop / status / push IMAGE / pull IMAGE` |
+| Apps | `compose up / down / ps / logs / exec / build / pull / start / stop / restart / rm / config` |
+| Storage and networks | `volume ls / create / rm / inspect / prune`, `network ls / create / rm / connect / disconnect / prune` |
+| Files and state | `cp`, `diff`, `export`, `commit`, `save`, `load`, `import`, `history`, `stats`, `top`, `pause` / `unpause`, `rename`, `update`, `port` |
+| Engine | `system info / df / prune`, `dock setup / start / stop / status / selftest / check / config`, `dock autostart [--off]` (macOS: start at login) |
+| Other tools and engines | `dock use [--system] [--off]` (engine CLI, compose, buildx, VS Code Dev Containers, testcontainers, the standard socket path), `dock env`, `dock migrate` |
+| Dashboard | `dock ui` — containers, logs, live stats, images, volumes, networks in the browser; `dock app` — TNC Dock in the macOS menu bar |
+| CI on this machine | `ci run [WORKFLOW] [--job ID]`, `ci list` — `.tnc/workflows` jobs, matrix legs for amd64 and arm64, services, JavaScript / composite / container actions, artifacts, each in a fresh container |
+
+### One container for all your coding agents: `thinknsh workspace`
+
+Instead of a separate sandbox for every AI tool, run one secure TNC container and point every agent and editor at it: Claude desktop, the Codex app, Cursor, Antigravity IDE, VS Code, and the `claude` / `codex` CLIs.
 
 ```bash
-THINKNCOLLAB_SERVER=https://thinkncollab.com thinknsh
+thinknsh workspace up ~/code/myapp                                   # one project → /work
+thinknsh workspace up ~/web ~/api ~/infra --name main                 # several → /work/web, /work/api, /work/infra
+thinknsh workspace apps                                              # which apps are installed and how each connects
+thinknsh workspace open main --app cursor                            # editors open straight onto it (cursor, antigravity, vscode)
+ssh tnc-main                                                         # terminal; then claude, codex, npm test, …
 ```
 
-Session credentials are saved to `~/.thinkncollab/session.json` and are automatically restored on the next launch — you only need to `login` once.
+| App | How it connects |
+| :--- | :--- |
+| Claude desktop | Code tab → environment picker → SSH → `tnc-<name>` → folder `/work` |
+| Codex app | Settings → Connections → enable `tnc-<name>` → folder `/work` (log in once: `thinknsh workspace exec <name> codex login --device-auth`) |
+| Cursor, Antigravity IDE, VS Code | `thinknsh workspace open <name> --app …`, or Remote-SSH → `tnc-<name>` |
+| Terminal | `ssh tnc-<name>` or `thinknsh workspace shell <name>` |
 
----
+Antigravity: only the IDE has SSH; the Antigravity agent manager app does not. VS Code needs the Remote - SSH extension.
 
-## Environment Variables
+What you get: your folders inside the container (edits land on your Mac at once), a home volume that keeps agent logins and editor servers across rebuilds, and one set of RAM/CPU limits (`-m 2g --cpus 2` by default) for all the tools together. With several folders, editors open `/run/tnc-workspace/<name>.code-workspace` (a multi-root workspace).
 
-| Variable | Default | Description |
-|---|---|---|
-| `THINKNCOLLAB_SERVER` | `https://thinkncollab.com` | Base URL for both REST and WebSocket |
-| `THINKNCOLLAB_API_URL` | `https://thinkncollab.com` | REST API base URL (overrides SERVER for API calls) |
-| `THINKNCOLLAB_WS_URL` | `https://thinkncollab.com` | WebSocket server URL |
-| `THINKNCOLLAB_AUTO_CONNECT` | `false` | Set to `true` to auto-connect WebSocket on shell start |
-| `THINKNSH_NOTIFY_PORT` | auto-assigned | TCP port for the notification window (set automatically) |
+Security: SSH listens on `127.0.0.1` only, with a per-workspace key and a pinned host key (no trust-on-first-use, no passwords, no root login). Sessions run as user `tnc` with **zero Linux capabilities**, `no-new-privileges`, no sudo and no setuid binaries, so an agent cannot become root inside the container. Process and memory limits apply. For a system package, you (not the agent) run `thinknsh workspace exec --root <name> apt-get install …`. Apps that connect run their own engine inside the workspace with your login for that app (Claude, Codex), stored in the workspace's home volume. `workspace up` writes the `tnc-<name>` host entries into a marked block at the end of `~/.ssh/config` (skip with `--no-ssh-config`); `workspace rm` removes them and never touches your folders.
 
-In production all three URL variables typically point to the same host:
+What runs where:
 
-```bash
-export THINKNCOLLAB_SERVER=https://thinkncollab.com
-export THINKNCOLLAB_API_URL=https://thinkncollab.com
-export THINKNCOLLAB_WS_URL=https://thinkncollab.com
-export THINKNCOLLAB_AUTO_CONNECT=true
-```
+| Where | What |
+| :--- | :--- |
+| Inside the workspace (one per project, or one per `--name` for several folders) | Every agent and editor server, your code under `/work`, language tools, tests, `npm` / `pip` installs in the home volume |
+| Next to it, as separate containers | Databases and services you start with `thinknsh compose up` or `thinknsh run`; the workspace joins their networks and reaches them by name |
+| On your machine | The dock engine itself (and, on macOS, the Linux VM it runs containers in) |
 
----
-
-## CLI Flags
-
-These flags are used **before** entering the interactive shell.
-
-| Flag | Alias | Description |
-|---|---|---|
-| `--help` | `-h` | Show help and exit |
-| `--version` | `-v` | Print installed version and exit |
+The workspace cannot start containers itself: it has no access to the engine and no Linux capabilities, which is what keeps an agent from escaping it. Start services from your own terminal; the workspace joins their network so agents reach them by service name:
 
 ```bash
-thinknsh --help
-thinknsh --version
-```
-
----
-
-## Interactive Shell
-
-Running `thinknsh` with no arguments starts the interactive shell. A notification window opens automatically in a new terminal (on macOS, Windows, and most Linux DEs).
-
-```
-$ thinknsh
-
-  ████████╗██╗  ██╗██╗███╗   ██╗██╗  ██╗███╗   ██╗ ...
-  ╔══════════════════════════════════════════════════════╗
-  ║     ThinkNCollab Shell v0.0.5                        ║
-  ║     Type 'help' for commands                         ║
-  ╚══════════════════════════════════════════════════════╝
-
-  Notification server ready on port 7379
-  Notification window opening...
-
-username@thinknsh:~ $
-```
-
-The prompt shows your current room and connection state:
-
-```
-[room-abc123] ● username@thinknsh:~/projects $
-```
-
-Type `help` at any time to list all available commands.
-
----
-
-## Commands Reference
-
-### Auth Commands
-
-#### `login`
-Authenticate interactively with your ThinkNCollab account. Credentials are saved and restored automatically on subsequent launches.
-
-```
-thinknsh> login
-  Email   : you@example.com
-  Password: ********
-  ✅ Logged in as You
-```
-
-#### `logout`
-End the current session and clear saved credentials.
-
-```
-thinknsh> logout
-  ✅ Logged out successfully
-```
-
-#### `whoami`
-Display the currently authenticated user.
-
-```
-thinknsh> whoami
-  👤 Logged in as: Raman Singh (raman@thinkncollab.com)
-```
-
----
-
-### Room Commands
-
-#### `join <room-id>`
-Join a collaboration room. Establishes a WebSocket connection, loads the last 30 messages, and starts streaming live events.
-
-```
-thinknsh> join room-abc123
-  ✅ Joined: My Project Room
-```
-
-#### `leave`
-Leave the current room and disconnect from its event stream.
-
-```
-thinknsh> leave
-```
-
-#### `rooms`
-List all rooms you have access to.
-
-```
-thinknsh> rooms
-  [1] frontend-team   (ID: room-abc123)  👥 4 members
-  [2] backend-infra   (ID: room-def456)  👥 2 members
-```
-
----
-
-### Message Commands
-
-#### `say <message>` / `msg <message>`
-Send a message to the room you are currently in. No quotes needed for multi-word messages.
-
-```
-thinknsh> say PR is up for review — branch feature/auth-fix
-```
-
----
-
-### Task Commands
-
-These commands require you to be logged in and in a room. They emit real-time events to all room members and update the [Shell Users presence page](https://thinkncollab.com) instantly.
-
-#### `task list`
-Show tasks assigned to you in the current room.
-
-```
-thinknsh> task list
-  [1] Fix login redirect bug       — high    · pending
-  [2] Write API documentation      — medium  · in-progress
-  [3] Review onboarding flow       — low     · pending
-```
-
-#### `task accept <task-id>`
-Mark a task as accepted. Emits a `task:accepted` event to the room — teammates see it live on the board.
-
-```
-thinknsh> task accept 64f1a2b3c4d5e6f7a8b9c0d1
-  ✅ Task accepted: Fix login redirect bug
-```
-
-#### `task start <task-id>`
-Mark a task as in-progress and broadcast a `task:started` event. Your active task appears on the Shell Users presence page for all teammates to see.
+thinknsh compose up -d                      # in the project folder: db, redis, … on <project>_default
+thinknsh workspace up                       # finds compose.yaml in the folder and joins that project's networks
+thinknsh workspace exec myapp getent hosts db   # agents use postgres://db:5432, http://api:3000, …
+```
+
+`--compose FILE|DIR` picks another compose project, `--no-compose` joins none, and `--network NET` (repeatable) joins any other network. The choice is remembered for the next `workspace up`, and `workspace ls` shows the networks. The order of `compose up` and `workspace up` does not matter: a compose network that does not exist yet is created then, the way `compose up` would. Joining a network only adds reach to the containers on it; the workspace keeps zero capabilities and still has no engine access. While the workspace is on a compose network, `compose down` leaves that network in place (it is in use) and the next `compose up` reuses it.
+
+New here? Read the step-by-step guide: [`docs/HOW-TO-USE.md`](docs/HOW-TO-USE.md).
+
+### What works today
+
+| Feature | Status |
+| :--- | :--- |
+| Run, attach, interactive terminals, exec, logs, exit codes, signals | ✅ |
+| Pull from public and private OCI registries (token and basic auth) | ✅ |
+| Build: Containerfile, multi-stage, build args, targets, layer cache, `.tncignore`, `RUN --mount` (cache, secret, bind, tmpfs), heredocs | ✅ |
+| BuildKit: buildx and BuildKit-mode builds through the engine CLI (`--secret`, cache mounts, and SSH-agent forwarding in BuildKit mode) | ✅ |
+| Compose: build, depends_on with `service_healthy`, healthchecks, profiles, `.env`, `extends`, `secrets`, `configs`, recreate on change | ✅ |
+| Networks with name resolution, named volumes, bind mounts, published TCP and UDP ports, `host.tnc.internal` | ✅ |
+| `linux/amd64` images on Apple Silicon (Rosetta 2; P8 compatibility check is optional) | ✅ |
+| Copy files in and out (`cp`), commit, save/load, export/import, stats, top | ✅ |
+| Unmodified tools: engine CLI, compose, VS Code Dev Containers (incl. Features), testcontainers | ✅ checked by `tests/ecosystem` |
+| Move images and volumes over from another engine (`dock migrate`) | ✅ |
+| Dashboard in the browser (`dock ui`) | ✅ |
+| Local CI (`ci run`, and TNC CI/CD runs from the dashboard): jobs, `needs`, matrix, both CPUs on one machine, `services` on localhost, `GITHUB_ENV`/`GITHUB_OUTPUT` | ✅ (macOS/Windows jobs and third-party actions are skipped) |
+| `--network container:<name>` and compose `network_mode: service:<name>` | ✅ |
+| GPUs | ❌ not yet (not possible on macOS) |
+| Push to a registry (skips existing layers, cross-repo mount), registry login/logout | ✅ |
+| Agent workspaces over SSH (key-only, loopback, no capabilities) | ✅ |
+| Rootless mode | ❌ not yet |
+| Deploy compose apps to your own servers | ✅ `thinknsh cluster deploy` |
+
+### Platforms
+
+| Platform | How containers run | Status |
+| :--- | :--- | :--- |
+| macOS, Apple Silicon | Small Linux VM on Apple Virtualization.framework (`tnc-vz`). It boots on the first container and sleeps after 5 idle minutes. | ✅ Verified: unit, check suite, e2e, cluster and selftest |
+| macOS, Intel | Same VM, x86_64 kernel | 🟡 Built, waiting for selftest reports |
+| Windows 10/11, x64 or ARM64 | Dedicated WSL2 distro `tnc-dock`. `C:\` paths work in `-v`. The distro stops when idle. | 🟡 Built, waiting for selftest reports |
+| Linux, x86_64 or aarch64 | Native namespaces and cgroups, no VM | 🟡 CI job set up, first results pending |
+
+### Memory (measured, not estimated)
+
+Measured on an Apple Silicon Mac with `thinknsh bench`. Run the same command on your machine to measure it there:
+
+| State | Memory |
+| :--- | :--- |
+| dock running, VM asleep | ≈ 18 MB |
+| VM awake, idle | ≈ 306 MB |
+| postgres + redis running | ≈ 491–563 MB |
+
+### Install
+
+Downloads and the full guide are at **https://thinkncollab.com/dock**.
+
+1. **Node.js 22.5 or newer.** dock stores its state with `node:sqlite`.
+2. **Windows only:** turn on WSL2 in an administrator PowerShell, then reboot. If WSL is already installed, run `wsl --update` instead.
+   ```powershell
+   wsl --install --no-distribution
+   ```
+3. **Install thinknsh and the runtime.** `setup` picks the right files for your OS and CPU, checks every sha256 against the bundle manifest, and installs them:
+   ```bash
+   npm install -g https://thinkncollab.com/downloads/dock/0.2.0/thinkncollab-shell.tgz
+   thinknsh dock setup
+   ```
+   On Linux, dock runs containers natively as root: run `sudo thinknsh dock setup` and `sudo thinknsh dock start`, then `sudo groupadd tnc-dock && sudo usermod -aG tnc-dock $USER` and restart dock to use the commands without sudo.
+   On a machine without internet, download the files for your platform and `manifest.json` from the downloads page into one folder, then run `thinknsh dock setup --from <folder>`.
+4. **Run something:**
+   ```bash
+   thinknsh run --rm -p 8080:80 nginx:alpine
+   ```
+   Then open http://localhost:8080.
+
+### Check it works on your machine
 
+```bash
+thinknsh dock selftest     # 12 real checks; writes ~/.tnc/dock/selftest-<os>-<cpu>-<time>.json
+thinknsh dock check        # all API/CLI compatibility cases; P8 is reported but is not required at the current P7 phase
+thinknsh bench idle        # memory, measured on this machine
 ```
-thinknsh> task start 64f1a2b3c4d5e6f7a8b9c0d1
-  ▶ Started: Fix login redirect bug
-```
-
-#### `task complete <task-id>`
-Mark a task as completed. Emits `task:completed` — the card on the board animates green for all viewers and your active task slot clears on the presence page.
-
-```
-thinknsh> task complete 64f1a2b3c4d5e6f7a8b9c0d1
-  ✓ Completed: Fix login redirect bug
-```
-
-#### `task reject <task-id>`
-Reject a task assignment. Emits `task:rejected` to the room.
-
-```
-thinknsh> task reject 64f1a2b3c4d5e6f7a8b9c0d1
-  ✕ Rejected: Fix login redirect bug
-```
-
----
-
-### Terminal Share Commands
-
-Terminal sharing lets you stream your live shell session to teammates. Viewers watch in real time; you can optionally grant write access to specific users.
-
-#### `share start`
-Start sharing your terminal in the current room. A session ID is created and room members are notified.
-
-```
-thinknsh> share start
-  📺 Terminal share started
-  Session : ts-7x9k2m
-  Room    : frontend-team
-```
-
-#### `share stop`
-End the current sharing session. All viewers are disconnected.
-
-```
-thinknsh> share stop
-  📺 Terminal share ended
-```
-
-#### `share grant <user-id>`
-Grant write access to a viewer. They can now send input to your shell.
-
-```
-thinknsh> share grant 64f1a2b3c4d5e6f7a8b9c0d1
-  ✍️  Write access granted
-```
-
-#### `share revoke <user-id>`
-Revoke write access from a user (they remain a read-only viewer).
-
-```
-thinknsh> share revoke 64f1a2b3c4d5e6f7a8b9c0d1
-```
-
-#### `share kick <user-id>`
-Remove a viewer from the session entirely.
-
-```
-thinknsh> share kick 64f1a2b3c4d5e6f7a8b9c0d1
-```
-
-#### `share status`
-List current viewers and which ones have write access.
-
-```
-thinknsh> share status
-  Viewers  : 2
-    👁  Priya Sharma        (read-only)
-    ✍  Alex Kumar           (write)
-```
-
----
 
-### Notification Commands
+If a check fails, send the selftest JSON file. It contains the machine details and the exact error of each check.
 
-#### `notify <message>`
-Send a push notification to all other members in the current room. The message appears in their notification feed instantly.
+### For contributors: build and test from source
 
-```
-thinknsh> notify Staging deploy complete — please re-test
-  📢 Notification sent to 3 member(s)
+```bash
+git clone -b shell/dock <repo> && cd ThinkNCollab-Shell-V2 && npm install
+native/bundle/build.sh aarch64 dist-bundles     # also: x86_64, darwin (macOS only)
+native/bundle/build.sh manifest dist-bundles 0.2.2
+node bin/thinknsh.js dock setup --from dist-bundles
+npm test                                       # unit tests (CLI, compose, engine, Windows backend)
+node tests/dock-e2e.js                         # end to end against the running daemon
+node bin/thinknsh.js dock check                # every command against the running daemon
 ```
 
-Supports optional type and title:
-
-```
-thinknsh> notify type=task_progress title="Build Done" All tests passing
-```
+Architecture and the runtime layout are documented in [`src/dock/README.md`](src/dock/README.md).
+A step-by-step guide for users is in [`docs/HOW-TO-USE.md`](docs/HOW-TO-USE.md).
 
 ---
 
-### Shell Commands
-
-#### `status`
-Show a full overview of your session.
-
-```
-thinknsh> status
-  WebSocket : ✓ Connected
-  Socket ID : abc123...
-  Room      : frontend-team
-  Auth      : ✓ Logged in
-  User      : Raman Singh
-```
-
-#### `help`
-List all registered commands grouped by category.
-
-#### `clear`
-Clear the terminal screen.
-
-#### `cd <path>`
-Change the working directory. Supports `~`, `..`, absolute and relative paths.
-
-#### `ls [-a]`
-List files in the current directory. Pass `-a` to include hidden files.
-
-#### `pwd`
-Print the current working directory.
-
-#### `history`
-Show the full command history for this session.
-
-#### `set [key value]`
-Set a shell variable. Run with no arguments to list all variables.
-
-```
-thinknsh> set ROOM room-abc123
-thinknsh> join $ROOM
-```
-
-#### `unset <key>`
-Delete a shell variable.
-
-#### `connect` / `disconnect`
-Manually connect or disconnect the WebSocket.
-
-#### `exit` / `quit`
-Exit the shell gracefully (saves history, closes TCP notification server, disconnects WebSocket).
+## ⚡ Core Capabilities
+
+### 1. One container engine for everything
+* **Containers, apps and services through dock:** `run`, `build`, `compose`, `workspace`, `service` and `registry` all run on the same engine (see the containers section above). On macOS that is one small Linux VM (`tnc-vz`) that sleeps when idle; on Windows one WSL2 distro; on Linux the host kernel.
+* **Dev databases in one command:** `thinknsh service start postgres` (also `redis`, `mysql`) runs it as a container on `127.0.0.1`, waits until it is healthy, prints the connection URL, and keeps its data in a volume across restarts and upgrades.
+* **Bind mounts from your folders:** `-v ./src:/app` shares files both ways (VirtioFS on macOS, `/mnt/c` on Windows).
+* **Port conflict protection:** publishing a port that is already in use fails with a message instead of taking over the running program.
+* **Older names still work:** `capsule`, `vault`, `mesh`, `stack` and `vm` run `build`/`images`, `volume`, `network`, `compose` and `dock`, and print the new command each time. `vault backup` / `restore` copy a volume to or from a `.tar.gz` file. `dev`, `sandbox`, `snapshot`, `freeze` and `resume` still use the older sandbox engine (`src/core/sandbox`, frozen).
+
+### 2. Multi-Layer Collaborative State Sync (`room share` / `room pull`)
+* Share entire development environments between teammates in seconds without third-party registries.
+* **Encrypted Multi-Layer Bundle:** Packages workspace code, live database snapshots (Postgres, Mongo, Redis), and sanitized `.env` secrets into a single AES-256-GCM encrypted bundle.
+* **Hybrid Transport:** Direct Gigabit Wi-Fi LAN P2P mesh (zero cloud bandwidth) with automatic fallback to ephemeral in-memory cloud socket relays.
+
+### 3. Smart 3-Way Code & Secret Merge Engine
+* **Non-Destructive:** Local files created by developers are never deleted during sync.
+* **Git 3-Way Line Merge (`git merge-file`):** Non-conflicting edits auto-merge with zero conflicts. Overlapping edits receive standard conflict markers (`<<<<<<< LOCAL` ... `>>>>>>> INCOMING`), activating VS Code's interactive CodeLens UI.
+* **Smart `.env` Reconciliation:** Preserves local developer overrides (custom ports, local keys) while appending missing teammate secrets.
+* **1-Click Safety Undo (`room undo`):** Pre-merge safety snapshots allow instant rollback if desired.
+
+### 4. Low-Bandwidth Terminal Multiplexing
+* **Semantic ANSI Text vs Video Pixels:** Streams UTF-8 terminal text chunks over WebSockets instead of rendering video frames, eliminating screen sharing latency and blur.
+* **Sub-Millisecond Dynamic RBAC:** Grant and revoke peer keyboard input access in real-time.
+* **AAD Replay Defense:** Cryptographically binds Additional Authenticated Data (`term-input:${sessionId}:${senderId}:${roomId}:${seq}`) to prevent keystroke replay attacks.
+* **Emergency Host Lock:** Instantly drop all remote input with one command.
+
+### 5. Signal-Grade E2EE Security
+* **60-Digit Out-of-Band Safety Numbers:** Verify channels on calls to guarantee zero MITM interception.
+* **TOFU Registry:** Trust-On-First-Use cryptographic registry for peer public keys.
+* **Forward Secrecy Key Rotation (`room rotate-key`):** Automatically rekeys rooms when members leave, preventing evicted members from decrypting future streams or states.
 
 ---
 
-### GitHub Integration Commands
-
-These commands let you interact with the GitHub repository linked to your current room. Requires connecting your GitHub account and repository on the Web Dashboard first.
-
-#### `statusgh`
-Show GitHub connection status and linked repository details.
-* **Aliases:** `statusgt`, `gh-status`
-* **Example:** `statusgh`
-
-#### `issues`
-List open issues in the linked GitHub repository.
-* **Aliases:** `gh-issues`
-* **Example:** `issues`
-
-#### `pulls`
-List open pull requests in the linked GitHub repository.
-* **Aliases:** `prs`, `gh-pulls`, `gh-prs`
-* **Example:** `pulls`
+## 🖥️ Terminal Sharing Architecture
 
-#### `commits`
-List the last 15 commits in the linked GitHub repository.
-* **Aliases:** `gh-commits`
-* **Example:** `commits`
+ThinkNCollab terminal pair programming operates on semantic text streams rather than video capture:
 
-#### `issue-create <title> <body>`
-Create a new issue in the linked GitHub repository. If arguments are missing, the shell prompts for them interactively.
-* **Aliases:** `create-issue`, `gh-issue-create`, `gh-create-issue`
-* **Example:** `issue-create "API Timeout" "GET /thinknsh is failing under load"`
+* **Text Streams Over WebSocket:** Raw PTY output (ANSI escape sequences and UTF-8 characters) is encrypted and streamed directly to connected peers, rendering natively in their local terminal client.
+* **Zero Video Overhead:** Avoids high-bandwidth video encoding/decoding, delivering sharp text reproduction and minimal latency even over constrained networks.
+* **Cryptographic Session Integrity:** Every keystroke packet is tagged with an incremental sequence counter and AES-256-GCM authentication tag bound to the active room, session, and peer identity.
 
 ---
 
-## `tncproject` Auto-Boot
-
-Place a `tncproject` file in your project root to auto-login and auto-join a room when `thinknsh` starts in that directory — no manual `login` or `join` needed.
-
-```
-.tncproject
-```
-
-On startup the shell sends the encrypted config to the server, receives a shell token, saves the session, connects WebSocket, and joins the project room automatically:
-
-```
-  📄 tncproject found
-     Room : room-abc123
-     File : /home/user/myproject/tncproject
-
-  ✅ Raman Singh → room "My Project Room"
-```
+## 📋 Platform Isolation Matrix
 
-If `tncproject` auth fails, the shell falls back to manual login.
+| Capability | macOS | Linux | Windows (WSL2) |
+| :--- | :--- | :--- | :--- |
+| **Isolation Primitive** | Apple Virtualization (`tnc-vz` MicroVM + `crun`) / Seatbelt fallback | Kernel namespaces (`unshare` / `crun`) | WSL2 utility environment |
+| **Resource Caps** | Dynamic Memory Ballooning + VirtioFS | `cgroups v2` (memory, CPU, pids) | WSL2 cgroups v2 |
+| **Networking & Discovery** | Native `vsock` relay + Virtio-Net | Virtual bridge + veth + iptables | Netsh port proxy + localhost |
+| **Snapshot Strategy** | APFS Copy-on-Write (`cp -cR`) | Btrfs / XFS reflink (`--reflink=auto`) | VSS / Directory copy fallback |
 
 ---
 
-## Notification Window
+## 🚀 Installation & Quick Start
 
-When `thinknsh` starts it launches a background TCP notification server on an auto-assigned port (default start: `7379`) and opens a second terminal window to display live events — messages, task updates, user joins/leaves — without interrupting your main shell prompt.
-
-On **VS Code** (Windows) the notification window cannot be auto-spawned. The shell prints the command to run it manually:
+```bash
+# Install globally via npm
+npm install -g thinkncollab-shell
 
+# Or run instantly via npx
+npx thinkncollab-shell
 ```
-  VS Code detected — open a new terminal tab and run:
-  $env:THINKNSH_NOTIFY_PORT=7379; node "path/to/notification-window.js"
-```
-
-On **macOS** it opens in a new Terminal.app window. On **Linux** it tries `gnome-terminal`, `xterm`, and `konsole` in order.
-
----
-
-## Built-in Shell Features
-
-### Persistent History
-Command history is saved to `~/.thinknsh_history` (up to 1000 entries) and restored on every launch. Use **Up/Down arrows** to navigate.
 
-### Session Persistence
-After `login`, your session token is saved to `~/.thinkncollab/session.json`. The next time you start `thinknsh` you are already authenticated — no password prompt.
+Both `thinknsh` and `tnc` command shortcuts are registered:
 
-### Shell Variables
 ```bash
-thinknsh> set ROOM room-abc123
-thinknsh> join $ROOM
+thinknsh --version
+# 2.0.0
 ```
 
-### Aliases
-Built-in aliases: `ll` → `ls -la`, `..` → `cd ..`, `~` → `cd ~`.
+---
 
-### System Shell Passthrough
-Any command that is not a `thinknsh` built-in runs directly in your system shell (`bash` / `cmd.exe`):
+## 💻 CLI Cheat Sheet
 
+### Containers
 ```bash
-thinknsh> git status
-thinknsh> npm install
-thinknsh> python manage.py migrate
+thinknsh run -d --name pg -p 5433:5432 -e POSTGRES_PASSWORD=secret postgres:alpine
+thinknsh run -d --name cache -p 6379:6379 -m 512m redis:alpine
+thinknsh ps
+thinknsh exec pg psql -U postgres -c "SELECT version();"
+thinknsh logs -f pg
+thinknsh stop pg && thinknsh rm pg
+thinknsh compose up -d
 ```
 
-> **Note:** On Windows, `open`, `which`, `grep`, `touch`, and `cat` are blocked (not available in cmd.exe) — use Windows equivalents or WSL.
-
-### Quote Parsing
-Single and double quotes are supported for arguments with spaces:
-
+### Room State & Database Sync
 ```bash
-thinknsh> say "Deployment done — all green ✅"
-thinknsh> notify "title=Release v2.1" Pushed to prod
+thinknsh room share [name]         # Publish code, Postgres, Mongo & Redis state
+thinknsh room share --no-code      # Publish database & environment only
+thinknsh room pull [state-id]      # Smart-merge teammate state into workspace
+thinknsh room merge [state-id]     # Explicit 3-way merge
+thinknsh room undo                 # Rollback last merge from safety backup
+thinknsh room states               # List shared states with service & code indicators
+thinknsh room verify               # Display 60-digit E2EE safety number & TOFU peers
+thinknsh room rotate-key           # Rekey room for forward secrecy
 ```
 
----
-
-## Single-Command Mode
-
-Run any command as a one-liner without entering the interactive shell:
-
+### Real-Time Terminal Pair Programming
 ```bash
-thinknsh status
-thinknsh whoami
-thinknsh rooms
-thinknsh join room-abc123
-thinknsh say "Deployment complete ✅"
-thinknsh task list
-thinknsh notify "All tests passing"
+thinknsh share                     # Start real-time PTY terminal sharing session
+thinknsh share --readonly          # Start in read-only broadcast mode
 ```
 
-Chain with `&&` for scripting:
-
+### Native Sandboxes & Process Control
 ```bash
-thinknsh login && thinknsh join room-abc123 && thinknsh say "I'm online"
+thinknsh dev --port 3000           # Launch service in native process sandbox
+thinknsh ps                        # Inspect active sandboxes & memory usage
+thinknsh freeze <name>             # Pause sandbox process (0% CPU/RAM)
+thinknsh resume <name>             # Resume paused sandbox instantly
+thinknsh snapshot create <name>    # Create sub-second CoW volume snapshot
+thinknsh snapshot restore <name>   # Restore volume state
 ```
 
----
-
-## Examples
-
+### Multi-Language Package Manager (`dep`)
 ```bash
-# Full interactive session
-thinknsh
-thinknsh> login
-thinknsh> rooms
-thinknsh> join room-abc123
-thinknsh> say Good morning everyone 🚀
-thinknsh> task list
-thinknsh> task accept 64f1a...
-thinknsh> task start 64f1a...
-thinknsh> task complete 64f1a...
-thinknsh> share start
-thinknsh> share grant 64f2b...
-thinknsh> share stop
-thinknsh> notify "Daily standup in 5 mins"
-thinknsh> status
-thinknsh> exit
-
-# tncproject auto-boot (no login needed)
-cd ~/myproject         # contains tncproject
-thinknsh               # auto-logs in + auto-joins room
-
-# Quick one-liners from CI / scripts
-thinknsh say "Build #142 passed ✅"
-thinknsh notify "Hotfix deployed to production"
-thinknsh task complete $TASK_ID
+thinknsh dep install <pkg>         # Track & install package across npm/pip/cargo/go
+thinknsh dep list                  # List all tracked dependencies
+thinknsh dep sync                  # Reconcile environment from thinkncollab.yml
 ```
 
 ---
 
-## License
+## 📄 License
 
-© ThinkNCollab
+Apache License 2.0. See [LICENSE](LICENSE) for details.  
+Copyright (c) 2024-2026 ThinkNCollab Systems Inc. All rights reserved.