repo: add README

README.md

@@ -0,0 +1,275 @@
+# Livedocs CLI
+
+Run Livedocs notebooks locally on your machine while using the hosted web interface.
+
+Livedocs CLI lets you execute Python notebooks with full access to local files, databases, and compute resources. The runtime (Middleman + Jedi) runs on your machine; the editing experience stays in the browser at livedocs.com.
+
+## Installation
+
+### Quick Install (recommended)
+
+```bash
+curl -fsSL https://livedocs.com/install.sh | bash
+```
+
+The installer will prompt to add `~/.livedocs/bin` to your PATH. To skip the prompt and auto-configure:
+
+```bash
+curl -fsSL https://livedocs.com/install.sh | bash -s -- --setup-path
+```
+
+### Requirements
+
+- macOS (arm64/x86_64) or Linux (amd64/arm64)
+- [uv](https://docs.astral.sh/uv/) - Python package manager (the installer will check for this)
+- Python 3.12 (installed automatically via uv)
+
+Install uv if you don't have it:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### Verify Installation
+
+```bash
+livedocs --version
+livedocs --help
+```
+
+## Quick Start
+
+1. **Pair with your workspace**
+
+   ```bash
+   livedocs setup
+   ```
+
+   This opens your browser to authenticate. Once approved, your workspace token is stored securely in your system keychain.
+
+2. **Launch a notebook**
+
+   ```bash
+   livedocs launch
+   ```
+
+   Select from your recent notebooks or create a new one. The CLI starts the runtime and opens the editor in your browser.
+
+3. **Stop the session**
+
+   Press `Ctrl+C` in the terminal, or:
+
+   ```bash
+   livedocs stop
+   ```
+
+## Commands
+
+### `livedocs setup`
+
+Pair the CLI with your Livedocs workspace using device-code authentication.
+
+```bash
+livedocs setup                    # Interactive browser-based auth
+livedocs setup --api-token TOKEN  # Use a pre-generated API token
+livedocs setup --no-browser       # Print the auth URL instead of opening it
+```
+
+### `livedocs launch`
+
+Start a local runtime session for a notebook.
+
+```bash
+livedocs launch                        # Interactive notebook picker
+livedocs launch --notebook <ID>        # Launch specific notebook by ID
+livedocs launch --new                  # Create and launch a new notebook
+livedocs launch --new --import <file>  # Import a Jupyter .ipynb file
+livedocs launch --attach               # Keep terminal attached to stream logs
+```
+
+By default, sessions run detached. Use `--attach` to see logs inline.
+
+### `livedocs stop`
+
+Stop a running session.
+
+```bash
+livedocs stop              # Stop the most recent session
+livedocs stop --id <ID>    # Stop a specific session
+livedocs stop --all        # Stop all sessions
+```
+
+### `livedocs status`
+
+Show installed bundle version and session history.
+
+```bash
+livedocs status
+livedocs status --verbose  # Include additional debug info
+```
+
+### `livedocs logs`
+
+Tail logs from runtime processes.
+
+```bash
+livedocs logs                      # Tail all logs
+livedocs logs --session <ID>       # Logs for a specific session
+livedocs logs --target middleman   # Only Middleman logs
+livedocs logs --target jedi        # Only Jedi (AI) logs
+```
+
+### `livedocs update`
+
+Update to the latest CLI bundle.
+
+```bash
+livedocs update              # Update to latest
+livedocs update --check-only # Check without installing
+livedocs update --force      # Reinstall current version
+livedocs update --channel staging  # Switch release channel
+```
+
+### `livedocs gc`
+
+Clean up old sessions and runtime artifacts.
+
+```bash
+livedocs gc                # Remove stopped sessions older than 7 days
+livedocs gc --all          # Remove all stopped sessions
+livedocs gc --dry-run      # Show what would be removed
+```
+
+### `livedocs whoami`
+
+Display current authentication and workspace info.
+
+```bash
+livedocs whoami
+```
+
+### `livedocs logout`
+
+Remove stored workspace tokens.
+
+```bash
+livedocs logout
+```
+
+## Configuration
+
+Configuration is stored in `~/.livedocs/config.toml`:
+
+```toml
+channel = "stable"                          # Release channel (stable, staging, dev)
+api_base_url = "https://api.livedocs.com"   # Core API endpoint
+web_base_url = "https://livedocs.com"       # Web app URL
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `LIVEDOCS_HOME` | Override the root directory (default: `~/.livedocs`) |
+| `LIVEDOCS_API_BASE_URL` | Override the API endpoint |
+| `LIVEDOCS_WEB_BASE_URL` | Override the web app URL |
+| `LIVEDOCS_CHANNEL` | Override release channel for install script |
+| `LIVEDOCS_VERSION` | Pin to a specific CLI version |
+
+## Directory Structure
+
+```
+~/.livedocs/
+  bin/                  # CLI binary symlink
+  bundles/              # Downloaded CLI bundles by version
+    1.2.1/
+      bin/
+      middleman/
+      wheels/
+      manifest.json
+  current -> bundles/1.2.1  # Active bundle symlink
+  runtime/              # Python environments and session workspaces
+    1.2.1/
+      python/           # uv-managed Python environment
+      jedi/             # Jedi (AI service) environment
+      sessions/         # Per-session runtime directories
+  sessions/             # Session metadata (JSON)
+  logs/                 # Log files by session
+  user_files/           # Persistent working directory for notebooks
+  config.toml           # CLI configuration
+```
+
+## How It Works
+
+When you run `livedocs launch`:
+
+1. The CLI authenticates with Livedocs Core using your workspace token
+2. Core allocates a runtime session and returns connection credentials
+3. The CLI bootstraps a Python environment (if needed) using uv
+4. Middleman (the notebook runtime) and Jedi (AI assistant) start as supervised processes
+5. Your browser opens the Livedocs editor, connected to your local runtime
+6. Code executes locally with full access to your machine's resources
+
+The web interface handles editing, collaboration features, and notebook persistence. The local runtime handles code execution, file I/O, and AI operations.
+
+## Troubleshooting
+
+### "command not found: livedocs"
+
+Your PATH doesn't include `~/.livedocs/bin`. Either:
+
+- Run `source ~/.zshrc` (or your shell's rc file)
+- Open a new terminal
+- Re-run the installer with `--setup-path`
+
+### "uv is required"
+
+Install uv first:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### Session fails to start
+
+Check the logs:
+
+```bash
+livedocs logs --session <ID>
+```
+
+Common issues:
+- Port conflict: another process is using port 8000
+- Missing dependencies: run `livedocs update --force` to reinstall
+- Stale session: run `livedocs gc` to clean up
+
+### Authentication errors
+
+Re-run setup to refresh your workspace token:
+
+```bash
+livedocs logout
+livedocs setup
+```
+
+## Uninstall
+
+Remove the CLI and all data:
+
+```bash
+rm -rf ~/.livedocs
+```
+
+Remove the PATH entry from your shell profile (`~/.zshrc`, `~/.bashrc`, etc.) if you used `--setup-path`.
+
+## Security
+
+- Workspace tokens are stored in your system's secure credential storage (macOS Keychain, Linux Secret Service)
+- Session tokens are ephemeral and stored with restricted permissions (0600)
+- All communication with Livedocs Core uses HTTPS
+- Local runtime binds to localhost by default
+
+## Support
+
+- Documentation: https://livedocs.com/docs
+- Issues: support@livedocs.com