add instructions for pack, unpack, studio cmds

Author: NiloCK

packages/cli/README.md

@@ -2,6 +2,14 @@
 
 A command-line tool for scaffolding Skuilder course applications.
 
+A Skuilder course consists of:
+- a Vue.js application
+- a data layer (static or dynamic)
+
+Static data-layer courses are self-contained as JSON files, and can be deployed as a static site.
+
+Dynamic data-layer courses are served from a CouchDB database and require a more involved setup ⚠️ **which is not currently well documented** ⚠️.
+
 ## Installation
 
 Install globally via npm:
@@ -16,9 +24,11 @@ Or use npx to run without installing:
 npx skuilder init my-course
 ```
 
-## Usage
+## Commands
+
+### Project Initialization
 
-### Create a new project
+#### Create a new project
 
 ```bash
 skuilder init my-anatomy-course
@@ -29,9 +39,9 @@ This will start an interactive prompt to configure your project:
 - Data layer type (static or dynamic)
 - CouchDB connection details (for dynamic)
 - Theme selection
-- Course ID to import (optional)
+- Course ID to import (optional import from a live CouchDB server)
 
-### Non-interactive mode
+#### Non-interactive mode
 
 ```bash
 skuilder init physics-101 \
@@ -40,7 +50,7 @@ skuilder init physics-101 \
   --no-interactive
 ```
 
-### Dynamic data layer with CouchDB
+#### Dynamic data layer with CouchDB
 
 ```bash
 skuilder init biology-course \
@@ -50,14 +60,113 @@ skuilder init biology-course \
   --theme=medical
 ```
 
-## Command Options
+#### Command Options
 
 - `--data-layer <type>` - Choose data layer: `static` or `dynamic` (default: dynamic)
 - `--theme <name>` - Select theme: `default`, `medical`, `educational`, or `corporate` (default: default)
 - `--no-interactive` - Skip interactive prompts and use provided options
 - `--couchdb-url <url>` - CouchDB server URL (required for dynamic data layer)
 - `--course-id <id>` - Course ID to import from CouchDB (optional)
 
+### Studio Mode (Content Editing)
+
+Studio mode provides a complete visual editing environment for static courses:
+
+```bash
+skuilder studio                    # Launch in current directory
+skuilder studio ./my-course        # Launch against specific packed course directory
+skuilder studio --port 6000        # Use custom CouchDB port
+skuilder studio --no-browser       # Don't auto-open browser
+```
+
+#### What Studio Mode Does
+
+Studio mode creates a full editing environment by starting multiple services:
+
+1. **CouchDB Instance** (Docker container on port 5985+)
+   - Temporary database for editing course content
+   - Automatically loads your static course data
+
+2. **Express API Server** (port 3001+)
+   - Handles database operations and file writes
+   - Provides REST API for the web editor
+
+3. **Studio Web Interface** (port 7174+)
+   - Visual course editor with Vue.js
+   - Create/edit cards, manage tags, bulk import
+   - Live preview of changes
+
+#### Studio Workflow
+
+1. **Load Course Data**: Unpacks your `public/static-courses/` JSON files into temporary CouchDB
+2. **Visual Editing**: Use the web interface to modify course content
+3. **Save Changes**: Click "Flush to Static" to write changes back to your course files
+4. **Important**: Studio mode **overwrites** your source files - backup before major edits
+
+#### Requirements
+
+- **Docker**: Required for CouchDB instance
+- **Static Course Project**: Valid package.json with vue-skuilder dependencies
+- **Course Data**: Existing content in `public/static-courses/` directory
+
+#### Studio Mode vs Regular Development
+
+| Feature | Regular Dev (`npm run dev`) | Studio Mode (`skuilder studio`) |
+|---------|----------------------------|--------------------------------|
+| Purpose | View/test course | Edit course content |
+| Data Source | Static JSON files | Temporary CouchDB + Web Editor |
+| Editing | Manual JSON editing | Visual web interface |
+| Services | Just Vite dev server | CouchDB + Express + Studio UI |
+| File Changes | Manual | Automatic via "Flush to Static" |
+
+### Course Data Management
+
+#### Pack/Unpack Commands
+
+For advanced users working with CouchDB data:
+
+```bash
+# Convert CouchDB course to static files
+skuilder pack my-course-id \
+  --server http://localhost:5984 \
+  --username admin \
+  --password secret \
+  --output ./exported-course
+
+# Convert static files to CouchDB course
+skuilder unpack ./course-data \
+  --server http://localhost:5984 \
+  --username admin \
+  --password secret \
+  --database coursedb-imported \
+  --validate
+```
+
+**Pack Command Options:**
+- `--server <url>` - CouchDB server URL (default: http://localhost:5984)
+- `--username <user>` - CouchDB username for authentication
+- `--password <pass>` - CouchDB password for authentication
+- `--output <dir>` - Output directory for static files (default: ./static-courses)
+- `--chunk-size <size>` - Documents per chunk for large courses (default: 1000)
+- `--no-attachments` - Skip downloading course attachments
+
+**Unpack Command Options:**
+- `--server <url>` - CouchDB server URL (default: http://localhost:5984)
+- `--username <user>` - CouchDB username for authentication
+- `--password <pass>` - CouchDB password for authentication
+- `--database <name>` - Target database name (auto-generated if not provided)
+- `--as <name>` - Custom name for the unpacked course
+- `--chunk-size <size>` - Documents per batch upload (default: 100)
+- `--validate` - Run migration validation after unpack
+- `--cleanup-on-error` - Remove database if migration fails
+
+**Use Cases:**
+- **Studio Mode Internal**: These commands power studio mode's load/save operations
+- **Migration**: Move courses between static and dynamic deployments
+- **Backup/Restore**: Export course data for safekeeping or transfer
+- **CI/CD Workflows**: Automate course deployment and synchronization
+- **Development**: Test with production course data locally
+
 ## Generated Project Structure
 
 ```
@@ -138,8 +247,13 @@ node packages/cli/dist/cli.js init test-project
 
 ## Requirements
 
-- Node.js 18.0.0 or higher
-- npm or yarn package manager
+### System Requirements
+
+- **Node.js 18.0.0 or higher**
+- **npm or yarn package manager**
+- **Docker** (required for studio mode only)
+  - Used to run temporary CouchDB instances
+  - Not needed for basic project creation or static course viewing
 
 ## Dependencies