moving

docs/guides/getting-started.md

@@ -0,0 +1,211 @@
+# Getting Started with Waggle
+
+This guide walks you through installing Waggle, configuring your API key, creating your first workspace, having your first conversation, and understanding how memory works.
+
+## Prerequisites
+
+- **Node.js 20+** (for local server and CLI)
+- **An LLM API key** (Anthropic recommended; OpenAI, Google, and 100+ others supported)
+- **Rust toolchain** (only if building the desktop app from source)
+
+## Installation
+
+### Option 1: One-line self-host (Linux / macOS)
+
+Best for a VPS or homelab, where you want a headless server rather than the desktop app:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/marolinik/waggle-os/main/install.sh | bash
+```
+
+The installer checks prerequisites (Node.js 20+, git — no sudo), clones the repo, builds the packages and web UI, then starts the sidecar and prints its URL (`http://127.0.0.1:3333`). A short wizard (all Enter-defaulted) lets you change the install dir, port, and data dir; add `--yes` to accept every default non-interactively. It boots in echo mode with zero API keys, so the UI works right away — add a provider key later under **Settings → API Keys**.
+
+Manage the server afterward with `scripts/waggle-server.sh {start|stop|status|logs}`. Windows users should use the desktop app (Option 2) — the one-line installer targets Linux and macOS only.
+
+### Option 2: Desktop App (Recommended)
+
+Download the latest release for your platform from [GitHub Releases](https://github.com/marolinik/waggle/releases).
+
+**Windows**: Run the `.msi` installer. Waggle appears in your Start menu.
+
+**macOS**: Open the `.dmg` and drag Waggle to Applications.
+
+The desktop app bundles a Node.js sidecar that runs the local server automatically.
+
+### Option 3: CLI / Web
+
+If you prefer a browser-based interface or want to run Waggle without the desktop shell:
+
+```bash
+# Clone the repository
+git clone https://github.com/marolinik/waggle.git
+cd waggle
+npm install
+
+# Start the local server
+cd packages/server
+npx tsx src/local/start.ts
+```
+
+The server starts on http://localhost:3333. Open it in any browser.
+
+### Option 4: CLI REPL
+
+For a terminal-native experience:
+
+```bash
+cd packages/cli
+npx tsx src/index.ts
+```
+
+## Step 1: Add Your API Key
+
+Waggle needs at least one LLM provider key to function. Anthropic (Claude) is recommended.
+
+### Desktop / Web UI
+
+1. Open **Settings** (gear icon in the sidebar or press `Ctrl+,`)
+2. Go to the **Models** tab
+3. Click **Add Provider**
+4. Select **Anthropic** and paste your API key (starts with `sk-ant-`)
+5. Click **Save**
+
+Your key is stored in the local vault (AES-256-GCM encrypted), never sent to Waggle's servers.
+
+### CLI / Config File
+
+Edit `~/.waggle/config.json`:
+
+```json
+{
+  "defaultModel": "claude-sonnet-4-6",
+  "providers": {
+    "anthropic": {
+      "apiKey": "sk-ant-your-key-here",
+      "models": ["claude-sonnet-4-6", "claude-haiku-3"]
+    }
+  }
+}
+```
+
+### Verify Your Key
+
+In Settings > Models, click **Test Key**. A green checkmark means you are ready.
+
+## Step 2: Create Your First Workspace
+
+Workspaces are the core organizational unit in Waggle. Each workspace has its own memory, sessions, files, and context. Think of a workspace as a dedicated brain for a project or topic.
+
+1. Press **Ctrl+N** or click **New Workspace** in the sidebar
+2. Enter a name (e.g., "Product Research" or "Q1 Planning")
+3. Choose a group (e.g., "Work", "Personal", "Learning")
+4. Optionally select a persona (Researcher, Writer, Coder, etc.)
+5. Optionally link a directory on disk for file-aware operations
+6. Click **Create**
+
+You land on the **Workspace Home** screen. It shows a summary, suggested prompts, and recent threads.
+
+## Step 3: Your First Conversation
+
+Type a message in the input area. Here are good first messages:
+
+- "Tell me about this project so I can remember it"
+- "Help me think through what to work on first"
+- "What can you do in this workspace?"
+
+The agent responds with streaming output. You will see:
+
+- **Tool calls** shown as collapsible cards (file reads, web searches, memory saves)
+- **Memory saves** happening automatically when the agent learns something important
+- **Approval gates** for sensitive operations (the agent asks before executing risky actions)
+
+### Try a Slash Command
+
+Type `/catchup` to get a workspace restart summary. Type `/help` to see all 14 commands.
+
+### Upload a File
+
+Click the paperclip icon or drag a file into the chat. Waggle supports:
+
+- **Documents**: PDF, DOCX, PPTX
+- **Spreadsheets**: XLSX, CSV
+- **Images**: PNG, JPG, GIF, WebP, SVG
+- **Code**: Any text-based source file
+- **Archives**: ZIP (lists contents)
+
+Files are ingested into workspace memory and available to the agent.
+
+## Step 4: Understanding Memory
+
+Memory is a core product primitive, not a side feature. Two memory layers work together:
+
+### Personal Mind (`~/.waggle/default.mind`)
+
+Your personal knowledge base. Facts about you, your preferences, recurring context. Shared across all workspaces.
+
+### Workspace Mind (`~/.waggle/workspaces/{id}/workspace.mind`)
+
+Project-specific memory. Decisions, research findings, architectural choices, meeting notes. Scoped to one workspace.
+
+### How Memory Works
+
+1. **Auto-save**: The agent automatically saves important information during conversations -- decisions, facts, preferences, and findings.
+2. **Explicit save**: You can say "Remember that we decided to use PostgreSQL" and the agent writes it to the appropriate mind.
+3. **Memory search**: The agent searches memory before responding, giving you continuity across sessions.
+4. **Memory browser**: Open the Memory tab in any workspace to browse, search, and manage stored frames.
+
+### Memory Frames
+
+Each memory unit is a "frame" with:
+- **Content**: The actual information
+- **Importance**: critical, important, normal, temporary
+- **Frame type**: Information (I), Decision (D), Preference (P), etc.
+- **Timestamp**: When it was created
+- **Access count**: How often it has been retrieved
+
+## Step 5: Return Tomorrow
+
+When you come back to a workspace, Waggle gives you an instant catch-up:
+
+1. **Workspace Home** shows a summary of what happened, recent decisions, and suggested next prompts
+2. **Type `/catchup`** for a detailed briefing
+3. **Resume a thread** by clicking any recent session in the sidebar
+4. **Context is automatic** -- the agent loads relevant memory before its first response
+
+This is the core daily-use loop:
+
+> Open workspace -> instant context -> real work help -> memory-first response -> visible progress -> return later without losing thread
+
+## Next Steps
+
+- **[Workspaces Guide](workspaces.md)** -- Workspace types, switching, home screen, personas
+- **[Capabilities Guide](capabilities.md)** -- Install skill packs and browse the marketplace
+- **[Connectors Guide](connectors.md)** -- Connect GitHub, Slack, Google, and 26 other services
+- **[Commands Reference](../reference/commands.md)** -- All 14 slash commands with examples
+- **[Team Mode Guide](team-mode.md)** -- Set up shared workspaces for your team
+
+## File Locations
+
+| Item | Path |
+|------|------|
+| Config | `~/.waggle/config.json` |
+| Personal mind | `~/.waggle/default.mind` |
+| Workspace minds | `~/.waggle/workspaces/{id}/workspace.mind` |
+| Session logs | `~/.waggle/workspaces/{id}/sessions/*.jsonl` |
+| Installed skills | `~/.waggle/skills/*.md` |
+| Installed plugins | `~/.waggle/plugins/` |
+| Marketplace DB | `~/.waggle/marketplace.db` |
+| Vault (encrypted) | `~/.waggle/vault.db` |
+| Server logs | Console output (stdout) |
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl+N` | New workspace |
+| `Ctrl+,` | Settings |
+| `Ctrl+K` | Quick switch workspace |
+| `Ctrl+Shift+M` | Toggle memory browser |
+| `Enter` | Send message |
+| `Shift+Enter` | Newline in message |
+| `/` | Start slash command |