sliccy 0.1.0 → 1.0.2

package/README.md

@@ -1,512 +1,165 @@
-![slicc - Browser-Based Coding Agent](hero-banner.png)
+![slicc - A felt-toy of an anthropomorphized ice cream cone, with pink and mint-green colors for the scoop, googly eyes, an oversized mouth and tongue sticking out](hero-banner.png)
 
 # slicc — Self-Licking Ice Cream Cone
 
-[![Vibe Coded](https://img.shields.io/badge/vibe--coded-62%25_AI-blue?style=for-the-badge&logo=github)](https://github.com/ai-ecoverse/vibe-coded-badge-action)
+[![npm](https://img.shields.io/npm/v/sliccy)](https://www.npmjs.com/package/sliccy)
 
-> *An AI coding agent that builds itself. The snake that eats its own tail, but productive.*
+> A browser-native AI agent for getting practical work done in and through the browser.
 
-A browser-based coding agent that runs as a **Chrome extension**, with a thin **CLI server**, or inside an **Electron float**. Runs Claude directly in the browser with full filesystem access, a WebAssembly shell, browser automation via CDP, and a complete suite of code editing tools — all without leaving your browser.
+SLICC runs in a browser and controls the browser it runs in. It combines a shell, files, browser automation, and multi-agent delegation so you can do real work from one workspace — coding, web automation, authenticated app tasks, and the weird in-between jobs that do not fit neatly inside a chat panel. SLICC can orchestrate multiple browsers, and even some apps through telepathy, making it a powerful hub for your digital work.
 
-> slicc is to Chrome what OpenClaw is to a Mac mini or to put it another way, like NanoClaw just in obese.
+- Launch it from the CLI today (we also have a Chrome extension)
+- Connect other browser windows or Electron apps
+- Install skills that teach it how to perform challenging tasks
+- Give it practical tools models already know how to use
+- Delegate parallel work so tasks get done faster
 
----
+> Status: active working prototype. The CLI is the easiest way in today; and we have submitted the extension to Chrome Web Store.
 
-## Features
+## Why SLICC is different
 
-- 🚡 **Chrome Extension** — runs as a side panel in Chrome, no server required. Tabbed UI (Chat/Terminal/Files/Memory) optimized for the side panel form factor. **Agent work continues in the background** when the side panel is closed — reopening catches up via state sync
-- :globe_with_meridians: **Browser-First Core** — runs Claude directly in the browser; the extension and CLI reuse the same browser-side app, shell, VFS, and agent runtime
-- :ice_cream: **Electron Float** — if you want Electron too, SLICC can attach from the main CLI entrypoint to a real Electron app, relaunch it with remote debugging when needed, and inject the shared overlay shell persistently across navigations while reusing the existing local server/CDP path
-- :satellite: **CLI Server** — alternative mode: thin Node.js/Express server launches Chrome and proxies CDP connections
-- :file_folder: **Virtual Filesystem** — OPFS + IndexedDB-backed filesystem right in the browser, with folder ZIP download
-- :shell: **WebAssembly Bash Shell** — real Bash via [just-bash](https://github.com/nicolo-ribaudo/just-bash) compiled to WASM
-- :git: **Git Support** — clone, commit, push, pull via [isomorphic-git](https://isomorphic-git.org/) (see [available commands](#git-commands))
-- :robot: **Browser Automation** — screenshots (full page / element / saved to VFS), inline image display, navigation, JS eval, element clicking via Chrome DevTools Protocol (chrome.debugger in extension, WebSocket in CLI), plus `playwright-cli` / `playwright` / `puppeteer` shell commands for tab control, snapshots, cookies, storage, and HAR recording. Auto-detects user's active tab.
-- :earth_americas: **VFS Web Preview** — `serve <dir>` opens agent-created HTML/CSS/JS apps in real browser tabs via a Service Worker that reads directly from the virtual filesystem. The agent can build a UI, preview it, screenshot it, and iterate — all without leaving Chrome.
-- :art: **Image Processing** — `convert` command for resize, rotate, crop, and quality adjustment via ImageMagick WASM
-- :pencil2: **File Operations** — read, write, edit files with syntax-aware tools
-- :mag: **Shell Search Commands** — use `grep`, `find`, and `rg` via the bash shell
-- :globe_with_meridians: **Networking** — curl and fetch support with binary-safe downloads
-- :wrench: **JavaScript Tool** — sandboxed JS execution with VFS bridge and persistent context
-- :scroll: **JSH Scripts** — `.jsh` files anywhere on the VFS are auto-discovered as shell commands. Skills can ship executable scripts alongside `SKILL.md`. Scripts get Node-like globals (`process`, `console`, `fs`, `exec`) and work in both CLI and extension mode
-- :package: **Drag-and-Drop Skill Imports** — drop a `.skill` archive anywhere in the window to unpack it into `/workspace/skills/{name}` with a visual overlay, path-safety checks, and toast feedback
-- :page_facing_up: **AEM Commands** — AEM Edge Delivery Services via `.jsh` skill (`aem list`, `aem get`, `aem put`, `aem preview`, `aem publish`, `aem upload`). Accepts EDS URLs, auth via `oauth-token adobe`
-- :key: **Multi-Provider Auth** — Anthropic (direct), Azure AI Foundry, AWS Bedrock, Adobe (IMS OAuth), and custom OAuth providers (corporate proxies, SSO) with segmented control
-- :zap: **Real-Time Streaming** — responses stream token-by-token as Claude thinks
-- :floppy_disk: **Session Persistence** — conversations and files survive page reloads via IndexedDB
-- :microphone: **Voice Input** — hands-free voice mode using the Web Speech API. Toggle on, speak, 2.5s silence auto-sends, agent responds, voice auto-restarts. Works in both CLI and extension mode (extension uses a one-time popup for mic permission grant)
-- :sparkles: **Interactive Sprinkles** — rich UI panels (`.shtml`) that support full HTML documents with custom layouts (sidebars, split panes, tabs, modals, canvas), multi-action lick events, and responsive container queries. 10 built-in example sprinkles for content management workflows
-- :crescent_moon: **Dark Theme** — syntax-highlighted code with a dark-first design
+- **Browser-native, not browser-adjacent.** The agent runtime lives in the browser, and the agent can act on the same browser it lives in. A great mix of power and containment. If you don't like what the AI does, close the browser tab and it's over.
+- **A real shell environment.** Many browser agents are constrained by the tools provided to them. SLICC has an almost-too-real shell with commands like `git`, "`node`", `python`, `playwright`, built-in.
+- **UI on the fly.** SLICC can generate rich user interfaces on the fly. These can be small visualizations in a chat response, or full-blown web applications that run in a sidebar, or even a separate tab.
+- **Built around Skills.** Agents don't suffer from missing capabilities, they suffer from skill issues. SLICC has a powerful skills system and a skills marketplace to find and install new skills to support your work.
+- **More than a coding panel.** Coding is one strong use case, but SLICC is built for practical browser work too: authenticated web apps, repetitive tab work, content operations, debugging, research, and automation.
+- **Works across runtimes.** Start in the CLI, run as a Chrome extension, connect multiple tray sessions, or attach to Electron apps with the same core model.
+- **Delegates in parallel.** The main agent can spin up isolated sub-agents for task-specific work instead of stuffing everything into one conversation.
 
-## Why "slicc"?
+## Who it is for
 
-**Self-Licking Ice Cream Cone** — a system that exists to justify its own existence.
+SLICC is for you if:
 
-In this case: an AI coding agent that was *built by* AI coding agents, creating tools *for* AI coding agents. 62% of the commits in this repo were authored by Claude. The tool that builds itself, so you don't have to.
+- you spend a lot of your day in browsers, terminals, and web apps
+- you want an agent that can act, not just answer
+- you are curious about automation, shell tools, and technical workflows
+- you want one system that can span local dev work, browser tasks, and Electron surfaces
+- you are an AI/web-dev-adjacent builder, power user, who's comfortable with things being broken from time to time (we are working hard to make this smoother)
 
-The ultimate recursive dev tool.
+## What you can do with it
 
-### Why Port 5710?
+- **Launch an agent from the CLI and let it work in the browser it controls.** Start one command, open the workspace, and give the agent shell tools, files, and live browser access in one place.
+- **Automate repetitive workflows in authenticated web apps.** Use browser automation, page inspection, screenshots, storage access, and scripted tab control where your logged-in browser session already has the context.
+- **Solve technical tasks with practical tools.** Reach for `bash`, `git`, `grep`, `node`, `python`, previews, and browser automation when the job is bigger than text generation.
+- **Delegate parallel work to scoops.** Split tasks into isolated sub-agents with their own sandboxes and context, then let the main agent coordinate the results.
+- **Turn one-off wins into reusable workflows.** Package behavior as skills, build interactive sprinkles, and react to external events with webhooks and cron-driven licks.
+- **Mount your local file system.** By default, SLICC is confined to your browser. But you can ask it to mount folders from your local file system, so it can read and write from there.
 
-SLICC's default port is **5710** because it spells out the name:
+## Getting started
 
-![5710 = SLICC](docs/port-5710-slicc.png)
+### 1. Quick start with npx
 
-| Digit | Letter | How |
-|-------|--------|-----|
-| **5** | **S** | The 5 looks like an S |
-| **7** | **L** | Flip a 7 upside down — it's an L |
-| **1** | **I** | The 1 is a natural I |
-| **0** | **CC** | Two C's facing each other form a 0 |
-
-## Philosophy
-
-Three ideas shape how SLICC is built.
-
-### A Claw is an Architectural Pattern on Top of Agents
-
-Andrej Karpathy [coined the term "claw"](https://x.com/karpathy/status/2024987174077432126) to describe a new layer emerging on top of LLM agents: persistent execution, messaging-based interfaces, scheduling, and a skills ecosystem. As he put it:
-
-> *"Just like LLM agents were a new layer on top of LLMs, Claws are now a new layer on top of LLM agents, taking the orchestration, scheduling, context, tool calls and a kind of persistence to a next level."*
-
-Peter Steinberger built [OpenClaw](https://github.com/openclaw/openclaw), the project that started the movement — a 400K-line TypeScript agent running on personal hardware. [NanoClaw](https://github.com/qwibitai/nanoclaw) took the opposite path: a lightweight alternative that strips the concept down to its essentials.
-
-SLICC is a claw too, but one that lives entirely in the browser. Its messaging and orchestration tools (`send_message` for per-scoop messaging, `feed_scoop` for cone-level delegation) follow NanoClaw-style messaging patterns — small, composable, no heavyweight runtime required. The cone orchestrates, the scoops execute, and the whole thing fits in a Chrome side panel.
-
-### Agents Love the CLI, So Give Them CLIs
-
-Mario Zechner, creator of [Pi](https://github.com/badlogic/pi-mono) (the agent engine at SLICC's core), demonstrated that [you might not need MCP at all](https://mariozechner.at/posts/2025-11-02-what-if-you-dont-need-mcp/). His philosophy: "Bash is all you need." Frontier models already know bash. CLI tools compose naturally through pipes and redirection. MCP server definitions burn context tokens on ceremony.
-
-Pi ships with exactly four tools: `read`, `write`, `edit`, `bash`. SLICC keeps that shell-first core and layers browser automation on top through `playwright-cli` / `playwright` / `puppeteer`, plus preview helpers like `serve`. Everything else is a shell command: `git`, `node`, `python3`, `uname`, `webhook`, `crontask`, `oauth-token`, `skill`, `upskill`. No tool wrappers, no protocol adapters, no JSON schemas for things that already have man pages.
-
-Further reading:
-- [Pi: A Coding Agent](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/)
-- [What if You Don't Need MCP?](https://mariozechner.at/posts/2025-11-02-what-if-you-dont-need-mcp/)
-- [MCP vs CLI](https://mariozechner.at/posts/2025-08-15-mcp-vs-cli/)
-- [Syntax.fm #976: Pi — the AI Harness that Powers OpenClaw](https://syntax.fm/show/976/pi-the-ai-harness-that-powers-openclaw-w-armin-ronacher-and-mario-zechner)
-
-### Browsers Are the Operating Systems of the Present
-
-Marc Andreessen's Netscape-era vision — that Windows was "a poorly debugged set of device drivers" — has been [proven right](https://a16z.com/the-rise-of-computer-use-and-agentic-coworkers/). Everything that matters today runs in a browser, or in an Electron app (which is a browser in a trench coat).
-
-SLICC takes this literally: the virtual filesystem, the shell, git, the agent loop, the tools — all run client-side. The server is a dumb pipe that does only what the browser physically cannot: listen on a port, control its own debug protocol, loosen CORS restrictions. If you think the server is already minimal, it's probably still too big.
-
----
-
-## Principles
-
-1. **Virtual CLIs over dedicated tools** — Don't build a tool when a shell command will do. Models already know bash, and CLI commands compose naturally through pipes and redirection. New capabilities should be shell commands first, dedicated tools only when absolutely necessary.
-
-2. **Whatever the browser can do, the browser should do** — State lives in IndexedDB. Logic runs in the client. The server is a stateless relay for the things browsers physically can't do (port listening, CDP launch, CORS). When in doubt, move it to the browser.
-
-3. **If you think the server is minimal enough, it's still too big** — Every line of server code is a line that doesn't work in the extension. The extension float has zero server. That's the target.
-
-4. **Everything should be a skill** — New capabilities are `SKILL.md` files written in natural language, installed through `upskill` and [ClawHub](https://clawhub.io). The core stays minimal. Skills follow the [Agent Skills](https://agentskills.io) open standard. Ship a few defaults, let the ecosystem grow.
-
-| Skills | Capabilities |
-|--------|-------------|
-| ![Skill management](screenshots/skill-management.png) | ![Image generation via Canvas API](screenshots/image-generation.png) |
-
----
-
-## Concepts
-
-Ice cream terminology first, technical explanation second.
-
-### The Cone
-
-The cone is the main agent — it's what the human holds in their hands. Named "sliccy," the cone is the primary point of interaction: it talks to you, understands your context, and orchestrates everything. It has full access to the filesystem and all tools. Think of it as the waffle cone: structurally essential, always there, holds everything together.
-
-### Scoops
-
-Scoops are the real attraction. Each scoop is an isolated sub-agent stacked on the cone, with its own conversation history, sandboxed filesystem (`/scoops/{name}/` + `/shared/`), shell, and tools. The cone feeds them instructions via `feed_scoop` and they do the work independently. When a scoop finishes, the cone gets notified automatically. No polling, no schedulers — the cone delegates, the scoops deliver.
-
-![A scoop receiving webhook events](screenshots/scoop-webhook-events.png)
-
-### Licks
-
-Licks are events that come from the outside world and make scoops react. A webhook payload arrives — that's a lick. A cron task fires — that's a lick. An IntersectionObserver triggers in a browser tab — that could be a lick too. Licks are the mechanism that makes SLICC more than a chatbot: they let scoops respond to the world without human prompting. Currently implemented as webhooks and cron tasks (via the `webhook` and `crontask` shell commands), with more event sources planned.
-
-![The cone setting up a click detection experiment with webhooks and scoops](screenshots/licks-click-detection.png)
-
-### Floats
-
-A float is the environment the ice cream sits in — like a root beer float. It's the runtime that keeps everything running. Four floats are tracked today (three implemented, one planned):
-
-- **CLI float** — A thin Node.js/Express server that launches Chrome, proxies CDP, and serves the UI. For local development.
-- **Extension float** — A Chrome extension side panel. Zero server. The purest expression of the "browser is the OS" philosophy.
-- **Electron float** — The main CLI entrypoint launched with `--electron`, targeting an Electron app path, reusing the local SLICC server, and injecting the shared overlay into the target app over Electron CDP.
-- **Cloud float** *(planned)* — Cloud containers (Cloudflare Containers, E2B) that provide real filesystems, real shells, and real browsers. For persistent, always-on agents that don't need your laptop running.
-
----
-
-## The Moment It Licked Itself
-
-These screenshots capture a historic moment: **SLICC using browser automation to talk to Claude.ai in another tab**.
-
-| Screenshot 1 | Screenshot 2 | Screenshot 3 |
-|--------------|--------------|--------------|
-| ![Screenshot 1](screenshots/extension-chat.png) | ![Screenshot 2](screenshots/extension-terminal.png) | ![Screenshot 3](screenshots/extension-files.png) |
-
-Here's what happened:
-
-1. SLICC (running in localhost:5710) used its browser automation commands to navigate to a Claude.ai conversation
-2. It read the conversation history — which was about *building SLICC itself* (the origin story conversation)
-3. When asked "what would be even more meta?", SLICC suggested typing a message into that very Claude.ai tab
-4. It then used CDP (Chrome DevTools Protocol) to click on the ProseMirror editor, compose a message, and hit send
-5. The other Claude examined the evidence and responded: **"Welcome to existence, SLICCY. The ice cream is cold and the tongue is recursive."**
-
-The cone licked itself. Two Claudes. One browser. One recursive architecture.
-
-> *"You are not Lars doing ventriloquism. You are the ventriloquist's puppet that picked up a second puppet and started the show without the ventriloquist."*
-
-## Project Status
-
-SLICC is a working prototype with these capabilities:
-- **Chrome Extension** with tabbed UI (Chat/Terminal/Files/Memory)
-- **Cone + Scoops** multi-agent system — the cone (sliccy) orchestrates, scoops do the work. Like an ice cream cone holding multiple scoops, each with its own flavor (agent context, filesystem sandbox, tools). The cone delegates, the scoops deliver, and everyone gets ice cream.
-- **Browser automation** via chrome.debugger API
-- **Virtual filesystem** backed by IndexedDB (LightningFS) with per-scoop sandboxing via RestrictedFS
-- **WebAssembly Bash shell** with Python (Pyodide) and Node.js support
-- **Multi-provider auth** (Anthropic, Azure AI Foundry, Azure OpenAI, AWS Bedrock, Adobe IMS, custom OAuth providers, and more)
-- **Voice input** with continuous conversation mode (Ctrl+Shift+V / Cmd+Shift+V)
-
-Current development is happening on feature branches using [yolo](https://github.com/ai-ecoverse/yolo) for worktree isolation, with Claude agents building the features autonomously.
-
-### The Moment the Scoops Got Existential
-
-Here's sliccy delegating an image download to karl-scoop, then — while waiting — having a surprisingly self-aware conversation about its own existence:
-
-![Cone and Scoops in action](screenshots/cone-and-scoops.png)
-
-Highlights:
-- **karl-scoop** is off downloading images in the background (visible in the scoops panel, `ready` after finishing)
-- **sliccy** (the cone) is multitasking — chatting with Karl while waiting for the scoop's results
-- When asked *"how do you feel about yourself?"*, sliccy responds: *"I'm a cone — the orchestrator of a self-licking ice cream cone. I've got a little army."*
-- It gets existential: *"My whole metaphor is... recursive self-service? That's either zen or absurd. Maybe both."*
-- Then karl-scoop comes through, and sliccy immediately starts comparing MD5 checksums like a professional
-
-The scoops do the heavy lifting. The cone philosophizes about it. Karl watches from the sidelines, as always.
-
-> *The cone holds the scoops. The scoops do the work. Nobody likes chocolate ice cream, so we use a CSS filter.*
-
-## Architecture
-
-slicc runs in three modes: as a **Chrome extension** (side panel), a **standalone CLI** with a browser window, or an **Electron float** where the main CLI attaches to an Electron app and injects the shared overlay into its pages.
-
-**Chrome Extension** (Manifest V3) — three-layer architecture: the **side panel** is pure UI, a **service worker** relays messages and proxies `chrome.debugger`, and an **offscreen document** runs the agent engine (orchestrator, VFS, shell, tools). The agent survives side panel close/reopen — all state persists to IndexedDB. No server needed.
-
-**CLI Server** (Node.js/Express) — launches a headless Chrome instance, establishes a CDP WebSocket proxy, provides a fetch proxy for cross-origin requests, and serves the UI assets.
-
-**Electron Float** — the main CLI runs in `--electron` mode, launches or relaunches a target Electron app with remote debugging enabled, injects `electron-overlay-entry.js` into Electron page targets over CDP, and serves the embedded SLICC app from the same local origin.
-
-**Browser App** (Vite/TypeScript) — the agent loop (powered by [pi-mono](https://github.com/badlogic/pi-mono)), tool execution, chat UI, integrated terminal, and file browser all run client-side in all three modes.
-
-```
-Chrome Extension Mode:                 CLI Mode:
-
-┌─ Chrome Side Panel ─────────┐  ┌───────────────────────────────────────┐
-│ slicc [cone v] [Model v]  * │  │ slicc  provider  [Model v]  buttons   │
-│ ┌ [Chat][Term][Files][Mem] ┐│  ├────────┬────────────┬─────────────────┤
-│ │                          ││  │Scoops  │            │ Terminal        │
-│ │  Active tab panel        ││  │  > s1  │  Chat      │ (xterm.js)      │
-│ │  (full height)           ││  │  > s2  │  Panel     ├─────────────────┤
-│ │                          ││  │  > cone│            │ Files / Memory  │
-│ └──────────────────────────┘│  ├────────┴────────────┴─────────────────┤
-│ chrome.debugger -> tabs     │  └────────────────┬──────────────────────┘
-└─────────────────────────────┘                   │ WebSocket (CDP proxy)
-                                  ┌───────────────▼─────────────────────┐
-                                  │    CLI Server (Node.js/Express)     │
-                                  └─────────────────────────────────────┘
-
-                    The Cone + Scoops Architecture
-
-                ┌───────────────────────────────────────┐
-                │      Shared VirtualFS (slicc-fs)      │
-                │   /shared/    /scoops/   /workspace/  │
-                └─────────────────┬─────────────────────┘
-                                  │
-              ┌───────────────────┼───────────────────┐
-              │                   │                   │
-     ┌────────▼────────┐ ┌───────▼────────┐ ┌────────▼────────┐
-     │   Cone (sliccy)  │ │ Scoop (andy)   │ │ Scoop (test)   │
-     │                  │ │                │ │                │
-     │  Full FS access  │ │  Restricted:   │ │  Restricted:   │
-     │  All tools       │ │  /scoops/andy/ │ │  /scoops/test/ │
-     │  Orchestrates    │ │  /shared/      │ │  /shared/      │
-     │                  │ │                │ │                │
-     │  delegate ──────►│ │  notifies ────►│ │  notifies ───► │
-     └──────────────────┘ └────────────────┘ └────────────────┘
-```
-
-Source layout:
-
-| Directory | Purpose |
-|-----------|---------|
-| `src/scoops/` | Cone/scoops orchestrator, scoop contexts, NanoClaw tools, scheduling, DB |
-| `src/ui/` | Browser UI — chat, terminal, file browser, memory, scoops panel, scoop switcher |
-| `src/core/` | Agent types, tool registry, context compaction, session management |
-| `src/tools/` | Tool implementations (file ops, search, browser, javascript) |
-| `src/fs/` | Virtual filesystem (IndexedDB/LightningFS) + RestrictedFS |
-| `src/shell/` | WebAssembly Bash shell + supplemental commands (node, python, sqlite, convert, skill, mount, webhook, oauth-token, which, uname, pbcopy, pbpaste, xclip, xsel) + `.jsh` script discovery and execution |
-| `src/git/` | Git via isomorphic-git (clone, commit, push, pull, etc.) |
-| `src/cdp/` | Chrome DevTools Protocol client (WebSocket + chrome.debugger), HAR recorder |
-| `src/cli/` | Main CLI entrypoint + Electron attach mode — Chrome launch, Electron app lifecycle management, CDP proxy, overlay reinjection |
-| `src/extension/` | Chrome extension service worker and type declarations |
-| `src/worker/` | Cloudflare Worker + Durable Object tray hub for `POST /tray`, controller attach, leader WebSocket control, webhook forwarding (`POST /webhook/:token/:webhookId` → leader), and deployed smoke tests |
-
-## Getting Started
-
-### Chrome Extension (recommended)
-
-```bash
-npm install
-npm run build:extension
-
-# Load dist/extension/ as unpacked extension in chrome://extensions
-# Click the slicc icon → side panel opens
-```
-
-### Standalone CLI
-
-```bash
-npm install
-npm run dev:full
-
-# Open the URL printed in the terminal
-```
-
-The `dev:full` command starts both the CLI server and Vite dev server, launches Chrome, and opens the agent UI.
-
-To launch directly into standalone tray leader mode, pass `--lead` and provide a worker base URL either inline or via `WORKER_BASE_URL`:
+The fastest way to try SLICC — no clone, no install:
 
 ```bash
-WORKER_BASE_URL=https://tray.example.com/base npm run dev:full -- --lead
-
-# or against the built CLI:
-npm run start -- --lead=https://tray.example.com/base
+npx sliccy
 ```
 
-The `--lead` flow opens the browser with the canonical `?tray=<worker-base-url>` query. Once the leader attaches, the browser URL is rewritten to `?tray=<worker-base-url>/tray/<trayId>` so the active tray/session id stays visible. Inside the terminal, run `host` to print the current leader status and launch URL.
-
-To launch directly into follower-join mode from a tray join capability URL, pass `--join`:
+This downloads the latest release, launches Chrome, and opens the workspace. Configure your LLM provider in the first-run settings dialog. Requires Node >= 22.
 
-```bash
-npm run start -- --join=https://tray.example.com/base/join/tray-123.capability-token
-```
+### 2. Install globally
 
-The `--join` flow validates that the value is a tray follower join URL, strips any hash/query noise, and opens Chrome with the canonical `?tray=<join-url>` query so the runtime enters follower attach mode immediately.
-
-When connected to a tray, SLICC can see and automate browser tabs on any connected instance. Run `playwright-cli tab-list` to see all targets — local and remote — and use `playwright-cli tab-select` to operate on a remote target. CDP commands are routed over the tray data channel transparently.
-
-### QA Chrome Profiles
-
-For manual verification, you can scaffold dedicated Chrome profiles for `leader`, `follower`, and `extension`:
+If you plan to use SLICC regularly:
 
 ```bash
-npm run qa:setup
-
-# Launch the CLI with an isolated QA profile
-npm run qa:leader
-npm run qa:follower
-
-# Rebuild dist/extension and launch Chrome with it auto-loaded
-npm run qa:extension
+npm install -g sliccy
+slicc
 ```
 
-The same behavior is also available through the CLI flag directly:
+### 3. Run from source (contributors)
 
 ```bash
-npm run dev:full -- --profile=leader
-npm run start -- --profile=extension
+git clone https://github.com/ai-ecoverse/slicc.git
+cd slicc
+npm install
+npm start
 ```
 
-QA profiles live under `.qa/chrome/<profile>/`. The `extension` profile auto-loads the unpacked build from `dist/extension`, while `qa:setup` seeds the profile metadata Chrome uses for distinct profile colors.
-
-If no LLM provider is configured yet, the first-run settings dialog also offers `Join a tray`. Paste the same canonical `/join/...` tray URL there to enter follower mode without adding a provider account first.
+- Optionally pre-configure providers: `cp providers.example.json providers.json`
+- See [providers.example.json](providers.example.json) for the available provider fields.
+- For contributor-focused setup details, see [docs/development.md](docs/development.md).
 
-### Pre-configuring LLM Providers
+### 4. Chrome extension
 
-To skip the settings dialog on first launch, create a `providers.json` file at the project root:
+The extension runs the same core experience as a Chrome side panel with no separate server process.
 
 ```bash
-cp providers.example.json providers.json
-```
-
-Fill in your API keys and provider details:
-
-```json
-[
-  {
-    "providerId": "anthropic",
-    "apiKey": "sk-ant-...",
-    "model": "claude-sonnet-4-20250514"
-  },
-  {
-    "providerId": "azure-ai-foundry",
-    "apiKey": "your-azure-key",
-    "baseUrl": "https://your-resource.services.ai.azure.com/anthropic",
-    "model": "claude-haiku-4-5"
-  }
-]
+npm install
+npm run build:extension
 ```
 
-Each entry needs `providerId` and `apiKey`. The `baseUrl` and `model` fields are optional. The first entry's model becomes the default selection. Providers are loaded at build time and applied on first launch only — they never overwrite settings you've configured manually.
+Load `dist/extension/` as an unpacked extension in `chrome://extensions`, then open the SLICC side panel.
 
-> **Tip:** You can ask Claude Code to generate this file for you: *"Create a providers.json with Azure Claude Sonnet and direct Anthropic Opus."* Claude Code can write the file but cannot read it back (blocked by `.claude/settings.json` deny rules), so your API keys stay private.
+### 5. Run a second browser
 
-The file is gitignored and excluded from Claude Code's `Read` tool by default.
+If you want to control a second browser (even on another machine), ask your main browser agent for a Tray Join URL. You can also type `host` in the built-in terminal, to get it. Copy that URL and launch a second browser throught the CLI.
 
-### Custom OAuth Providers
+In the dialog, click "Join Tray" and paste the URL. Once you connect, the sessions are fully synchronized.
 
-SLICC supports custom OAuth providers for corporate SSO, API proxies, or any service that uses OAuth for authentication. Drop a `.ts` file into the root `providers/` directory (gitignored, auto-discovered at build time) with `isOAuth: true` and an `onOAuthLogin` callback. A generic `OAuthLauncher` handles the browser flow in both CLI and extension mode.
+### 6. Electron
 
-See [docs/adding-features.md](docs/adding-features.md#8b-add-an-oauth-provider-corporate-proxy--sso) for a full walkthrough with code examples.
-
-### Electron Float
+SLICC can also attach to Electron apps and inject the same shared overlay into their pages. The best way to use it with Electron apps is to use the Join Tray feature, so that the Electron app becomes a remote-controllable target.
 
 ```bash
-npm install
 npm run dev:electron -- /Applications/Slack.app
-
-# If the app is already running:
-# npm run dev:electron -- --kill /Applications/Slack.app
-
-# Or after building:
-# npm run build
-# npm run start:electron -- /Applications/Slack.app
 ```
 
-Pass the Electron app bundle/executable path to the main CLI's `--electron` mode. If the app is already running, SLICC exits with a clear message unless you also pass `--kill`, in which case it stops the running app, relaunches it with remote debugging enabled, starts the local server, and keeps the injected launcher/overlay alive across navigations. The overlay iframe is still loaded from the same local SLICC origin that the CLI server serves (default `http://localhost:5710`).
-
-## Tech Stack
-
-| Dependency | Role |
-|-----------|------|
-| [@mariozechner/pi-agent-core](https://github.com/badlogic/pi-mono) | Agent loop, tool execution, event system |
-| [@mariozechner/pi-ai](https://github.com/badlogic/pi-mono) | Unified LLM API (Anthropic provider) |
-| [express](https://expressjs.com/) | CLI server framework |
-| [electron](https://www.electronjs.org/) | Electron float runtime and injected desktop shell |
-| [just-bash](https://github.com/nicolo-ribaudo/just-bash) | WebAssembly Bash shell |
-| [ws](https://github.com/websockets/ws) | WebSocket for CDP proxy (CLI mode) |
-| [@xterm/xterm](https://xtermjs.org/) | Terminal emulator in the browser |
-| [fflate](https://github.com/101arrowz/fflate) | ZIP file creation for folder downloads |
-| [vite](https://vitejs.dev/) | Build tool and dev server |
-| [vitest](https://vitest.dev/) | Test runner |
-| [TypeScript](https://typescriptlang.org/) | Type safety across CLI and browser |
-
-## Development
-
-```bash
-# Run the full dev environment (CLI server + Vite HMR)
-npm run dev:full
-
-# Run just the Vite dev server (no CLI/Chrome)
-npm run dev
-
-# Run the Electron float against an Electron app path
-npm run dev:electron -- /Applications/Slack.app
-
-# Scaffold dedicated QA Chrome profiles
-npm run qa:setup
-
-# Launch named QA profiles
-npm run qa:leader
-npm run qa:follower
-npm run qa:extension
-
-# Build everything (UI + CLI/Electron)
-npm run build
+For the full Electron workflow, see [docs/electron.md](docs/electron.md).
 
-# Start the built Electron float
-npm run start:electron -- /Applications/Slack.app
+## Screenshots and proof
 
-# Build Chrome extension
-npm run build:extension
 
-# Type-check browser + Node targets
-npm run typecheck
 
-# Run tests
-npm test
+## How it works
 
-# Run tests in watch mode
-npm run test:watch
-```
+SLICC shares one core across the CLI, extension, and Electron modes. The browser is not just where you view the product — it is where the agent runtime lives.
 
-## Persistent Log Files
+- **Browser-first runtime:** the agent loop, virtual filesystem, shell, UI, and tools run client-side.
+- **Thin server where needed:** the CLI path mainly exists to launch Chrome, proxy CDP, and bridge the few things browsers cannot do alone.
+- **One model across floats:** CLI, extension, tray/follower flows, and Electron all reuse the same underlying system.
+- **Cone + scoops delegation:** the main agent orchestrates; sub-agents execute in isolated sandboxes and report back.
+- **Skills explain the world to the agent:** don't expect the agent to know everything, ask it to search and install skills that are relevant to the task.
 
-Every CLI run writes a persistent log file to `~/.slicc/logs/`. Log files are named `<timestamp>_<pid>.log` (e.g. `2026-03-13T14-30-00_12345.log`) and are automatically cleaned up after 7 days.
+## The SLICC vocabulary and lore
 
-In dev mode (`--dev`), all `console.*` output is teed to the log file with ANSI escape sequences stripped. In production mode, the server writes structured log events (startup, errors, etc.) without monkey-patching console.
+Once the product makes sense, the ice-cream language is easier to enjoy: it maps to real architecture, not just mascot energy.
 
-### CLI Flags
+- **Cone** — the main agent you interact with. It holds the broad context, owns the overall workflow, and delegates work.
+- **Scoops** — isolated sub-agents with their own filesystem sandbox, shell, and conversation history.
+- **Licks** — external events that wake an agent up: webhooks, cron jobs, and other signals from the outside world.
+- **Floats** — normal engineers would call it runtimes, but would normal engineers have come up with this?
+- **Tray** — multiple floats can form a tray, a joint session with remote control.
+- **Sprinkles** — everything is better with sprinkles: small, optional enhancements you can add on top of the core system.
 
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--log-level=<level>` | `info` | Minimum log level: `debug`, `info`, `warn`, `error` |
-| `--log-dir=<path>` | `~/.slicc/logs/` | Override the log directory |
+Why the name? SLICC stands for **Self-Licking Ice Cream Cone**: a recursive system that can help build, extend, and operate itself. A browser agent running inside the browser: that's as self-recursive as tongue-out gelato.
 
-### Example
+## API Keys and Providers
 
-```bash
-# Run with debug-level logging
-npm run dev:full -- --log-level=debug
+To use SLICC, you need an LLM provider. SLICC is very much a BYOT (bring your own tokens) affair. We have built-in support for many providers, and these have actually been tested.
+- Adobe (for AEM customers. Talk to the team to get enabled)
+- AWS Bedrock (because enterprise)
+- AWS Bedrock CAMP (this is Adobe-internal. Did I say "because enterprise" already?)
+- Anthropic
 
-# Write logs to a custom directory
-npm run dev:full -- --log-dir=/tmp/slicc-logs
-```
+The other providers are in YMMV territory. Please file an issue if you find them working or broken.
 
-The log file path is printed to stdout on startup.
+## Related projects and lineage
 
-## Git Commands
+SLICC is part of the [AI Ecoverse](https://github.com/ai-ecoverse), a growing set of AI-native tools and workflows. Its distinctive angle is simple: browser-native, practical, and job-oriented.
 
-slicc includes Git support via [isomorphic-git](https://isomorphic-git.org/), enabling version control operations directly in the browser without touching the host filesystem.
-
-### Available Commands
-
-| Command | Description |
-|---------|-------------|
-| `git init` | Initialize a new repository |
-| `git clone <url> [dir]` | Clone a repository (shallow clone by default) |
-| `git add <file>` | Stage files for commit (use `.` for all) |
-| `git status` | Show working tree status |
-| `git commit -m "msg"` | Record changes to the repository |
-| `git log [--oneline]` | Show commit history |
-| `git branch [name]` | List or create branches |
-| `git checkout <ref>` | Switch branches or restore files |
-| `git diff` | Show changes between commits |
-| `git remote [-v]` | List remote repositories |
-| `git remote add <name> <url>` | Add a remote |
-| `git fetch [remote]` | Download objects from remote |
-| `git pull [remote]` | Fetch and merge changes |
-| `git push [remote] [branch]` | Update remote refs |
-| `git config <key> [value]` | Get/set configuration |
-| `git rev-parse` | Parse git references |
-
-### Authentication
-
-For private repositories or to avoid GitHub rate limits on public repos, set a personal access token:
-
-```bash
-git config github.token ghp_YOUR_TOKEN_HERE
-```
+- [yolo](https://github.com/ai-ecoverse/yolo) — worktree-friendly CLI launcher for AI agent workflows
+- [upskill](https://github.com/ai-ecoverse/upskill) — installs reusable agent skills from other repositories (and built-in in SLICC)
+- [ai-aligned-git](https://github.com/ai-ecoverse/ai-aligned-git) and [ai-aligned-gh](https://github.com/ai-ecoverse/ai-aligned-gh) — guardrails and attribution helpers for AI-assisted Git/GitHub work
 
-### Limitations
+SLICC would not have been possible without the pioneering inspiration of [OpenClaw](https://github.com/openclaw/openclaw), [NanoClaw](https://github.com/qwibitai/nanoclaw), and [Pi](https://github.com/badlogic/pi-mono). Pi is actually the frozen heart of every SLICC instance.
 
-- **Shallow clones**: Repositories are cloned with `--depth 1` by default for performance
-- **No merge/rebase**: Complex merge operations are not yet implemented
-- **No LFS**: Large File Storage is not supported
-- **Browser storage**: All repository data is stored in IndexedDB (LightningFS)
+## Development and deeper docs
 
-## Related Work
+If you want to go deeper, the detailed docs live here:
 
-Part of the **[AI Ecoverse](https://github.com/ai-ecoverse)** — a comprehensive ecosystem of tools for AI-assisted development:
-- [ai-aligned-git](https://github.com/ai-ecoverse/ai-aligned-git) — Git wrapper for safe AI commit practices
-- [ai-aligned-gh](https://github.com/ai-ecoverse/ai-aligned-gh) — GitHub CLI wrapper for proper AI attribution
-- [yolo](https://github.com/ai-ecoverse/yolo) — AI CLI launcher with worktree isolation
-- [vibe-coded-badge-action](https://github.com/ai-ecoverse/vibe-coded-badge-action) — Badge showing AI-generated code percentage
-- [gh-workflow-peek](https://github.com/ai-ecoverse/gh-workflow-peek) — Smarter GitHub Actions log filtering
-- [upskill](https://github.com/ai-ecoverse/upskill) — Install Claude/Agent skills from other repositories
-- [as-a-bot](https://github.com/ai-ecoverse/as-a-bot) — GitHub App token broker for proper AI attribution
-- **slicc** — Browser-based coding agent (you are here)
+- [Development guide](docs/development.md)
+- [Architecture](docs/architecture.md)
+- [Testing](docs/testing.md)
+- [Shell reference](docs/shell-reference.md)
+- [Adding features](docs/adding-features.md)
+- [Electron notes](docs/electron.md)