Update setup flow for people who just want to get a live rendered pat…

.claude/commands/deps.md

@@ -1,12 +1,45 @@
-MUST HAVE:
-- deno 2 https://docs.deno.com/runtime/getting_started/installation/
-
-REALLY SHOULD HAVE:
-- gh https://github.com/cli/cli
-- claude code
-  - `npm i -g @anthropic/claude-code`
-  - mcp
-    - `claude mcp add --transport sse linear-server https://mcp.linear.app/sse`
-      - then use `/linear` for workflow
-    - `claude mcp add playwright npx '@playwright/mcp@latest'`
-      - then use `/explore-recipe`, `/imagine-recipe` or `/recipe-dev` etc.
+# Dependencies and Integrations
+
+**Note**: If you just want to get set up quickly, use the `/setup` command. This file documents all the dependencies for reference.
+
+## Required
+
+**Deno 2**: Runtime for backend, tooling, and pattern development
+- Install: https://docs.deno.com/runtime/getting_started/installation/
+- Verify: `deno --version`
+
+## Recommended for Development
+
+**GitHub CLI**: For PR and issue workflows
+- Install: https://github.com/cli/cli
+- Used by various slash commands for GitHub integration
+
+**Claude Code**: For AI-assisted development
+- Install: `npm i -g @anthropic/claude-code`
+- Provides slash commands and AI assistance for pattern development
+
+## Optional MCP Integrations
+
+These enhance Claude Code with additional capabilities:
+
+**Linear MCP Server**: Task and project management
+```bash
+claude mcp add --transport sse linear-server https://mcp.linear.app/sse
+```
+- Enables `/linear` command for workflow management
+
+**Playwright MCP**: Browser automation for testing patterns
+```bash
+claude mcp add playwright npx '@playwright/mcp@latest'
+```
+- Required for `/explore-recipe` and interactive pattern testing
+- Automatically tests deployed patterns in browser
+
+## What Gets Installed by Setup
+
+When you run `/setup` or follow the setup guide, you'll:
+1. Build the `ct` binary (pattern deployment tool)
+2. Create a local identity key (`claude.key`)
+3. Optionally start local backend/frontend servers
+
+No additional dependencies are required to deploy your first pattern!

.claude/commands/onboarding.md

@@ -1,7 +1,15 @@
 # Common Tools Repository Onboarding Tour
 
+**Note**: This command provides an interactive tour of the codebase and concepts. If you want to actually set up a development environment and deploy your first pattern, use the `/setup` command instead.
+
 This command provides an interactive tour of the Common Tools platform repository, helping new contributors understand where to find information and how to navigate the codebase effectively.
 
+## Before You Start
+
+**New to this repository?**
+- Want to actually deploy a pattern and start coding? → Use `/setup` command
+- Want to understand the concepts and codebase structure first? → Continue with this tour
+
 ## Getting Started (Essential Foundation)
 
 **Everyone starts here to get oriented:**

.claude/commands/setup.md

@@ -0,0 +1,115 @@
+# Setup Command - Automated Setup
+
+This command automatically sets up your local Common Tools environment, starts the servers, and deploys your first pattern.
+
+## What This Command Does
+
+1. Checks that Deno is installed
+2. Builds the ct binary if needed
+3. Creates an identity key if needed
+4. Starts local backend and frontend servers
+5. Deploys a demo pattern
+6. Gives you the URL to visit and next steps
+
+## Instructions for Claude
+
+When the user invokes this command:
+
+### Step 1: Check Prerequisites
+
+Check if deno is installed:
+```bash
+deno --version
+```
+
+If not installed, tell the user:
+"You need to install Deno first. Visit https://docs.deno.com/runtime/getting_started/installation/ and then run this command again."
+
+### Step 2: Build ct Binary (if needed)
+
+Use the `ct` skill to build the binary if needed. The ct skill documents the binary vs source approach and build commands.
+
+### Step 3: Create Identity Key (if needed)
+
+Check if identity key exists:
+```bash
+ls -la claude.key
+```
+
+If it doesn't exist, create it:
+```bash
+./dist/ct id new > claude.key
+```
+
+Tell the user: "Created your local identity key (claude.key)"
+
+### Step 4: Start Local Servers
+
+Start the backend in background:
+```bash
+cd packages/toolshed && deno task dev
+```
+
+Wait 5 seconds, then start the frontend in background:
+```bash
+cd packages/shell && deno task dev-local
+```
+
+Wait 5 seconds for frontend to be ready.
+
+Tell the user: "Started local backend (port 8000) and frontend (port 5173)"
+
+### Step 5: Deploy Demo Pattern
+
+Deploy the checkbox demo pattern:
+```bash
+./dist/ct charm new --identity claude.key --api-url http://localhost:8000 --space test-space packages/patterns/ct-checkbox-cell.tsx
+```
+
+Capture the charm ID from the output.
+
+Tell the user: "Deployed demo pattern! Charm ID: [CHARM_ID]"
+
+### Step 6: Give User Next Steps
+
+Tell the user:
+
+"✅ Setup complete! Here's what to do next:
+
+**1. Visit your pattern:**
+   Open: http://localhost:5173/test-space/[CHARM_ID]
+
+**2. First time? Register:**
+   - Click '➕ Register'
+   - Click '🔑 Generate Passphrase'
+   - Click '🔒 I've Saved It - Continue'
+   - You'll see your checkbox demo running!
+
+**3. Next steps for development:**
+   - Use the `pattern-dev` skill for iterative pattern development workflow
+   - The pattern-dev skill's workflow-guide.md explains:
+     - How to deploy more patterns
+     - How to modify and update patterns with `setsrc`
+     - Best practices for building multi-pattern architectures
+   - Browse packages/patterns/ for examples
+   - Use the `ct` skill for all ct command usage
+
+**Good patterns to try next:**
+- ct-select.tsx - Dropdown component
+- dice.tsx - Random dice roller
+- counter.tsx - Simple counter with handlers
+
+The servers are running in the background. Have fun building!"
+
+### Step 7: Remember the Charm ID
+
+Store the charm ID so you can reference it if the user asks questions later.
+
+## Important Notes for Claude
+
+- Always use background mode when starting servers (`run_in_background: true`)
+- Wait for servers to fully start before deploying patterns
+- Capture and show the charm ID to the user
+- Make the URL clickable/clear
+- Explain the registration flow clearly (it's confusing the first time)
+- Show concrete examples for next steps, not just generic advice

docs/QUICKSTART.md

@@ -0,0 +1,118 @@
+# Quick Start Guide
+
+This guide gets you from a fresh checkout to deploying your first pattern in under 5 minutes.
+
+## Prerequisites
+
+Just Deno 2:
+```bash
+deno --version  # Should show 2.x
+```
+
+If not installed: https://docs.deno.com/runtime/getting_started/installation/
+
+## Setup Steps
+
+### 1. Build the ct tool
+
+```bash
+deno task build-binaries --cli-only
+```
+
+This creates `./dist/ct` for deploying patterns.
+
+### 2. Create an identity
+
+```bash
+./dist/ct id new > claude.key
+```
+
+### 3. Start local services
+
+**Option A - Full local stack:**
+```bash
+# Terminal 1: Backend
+cd packages/toolshed && deno task dev
+
+# Terminal 2: Frontend
+cd packages/shell && deno task dev-local
+```
+
+**Option B - Remote backend (simpler):**
+```bash
+cd packages/shell && deno task dev
+```
+
+### 4. Deploy a pattern
+
+```bash
+# Local backend:
+./dist/ct charm new --identity claude.key \
+  --api-url http://localhost:8000 \
+  --space my-space \
+  packages/patterns/ct-checkbox-cell.tsx
+
+# Remote backend:
+./dist/ct charm new --identity claude.key \
+  --api-url https://toolshed.saga-castor.ts.net \
+  --space my-space \
+  packages/patterns/ct-checkbox-cell.tsx
+```
+
+The command outputs a charm ID like `baedreie...`
+
+### 5. View your pattern
+
+Open browser to:
+```
+http://localhost:5173/my-space/[CHARM_ID]
+```
+
+## Using Claude Code
+
+If you have Claude Code installed, just run:
+```bash
+claude
+```
+
+Then type: `/setup` to get interactive setup assistance.
+
+## What's Next?
+
+- **Pattern Development**: Use Claude Skills with `pattern-dev` for AI-assisted development
+- **Documentation**: Read `docs/common/RECIPES.md` and `docs/common/PATTERN_DEV_DEPLOY.md`
+- **Examples**: Browse `packages/patterns/` for pattern examples
+- **ct Commands**: Run `./dist/ct --help` to see all available commands
+
+## Recommended First Patterns
+
+Self-contained patterns perfect for learning:
+- `ct-checkbox-cell.tsx` - Interactive checkbox demo
+- `ct-select.tsx` - Dropdown component
+- `ct-tags.tsx` - Tags input
+
+## Common Issues
+
+**ct binary not found**: Run `deno task build-binaries --cli-only`
+
+**Frontend won't connect**: Use `dev-local` task for local backend, `dev` for remote
+
+**Deno not found**: Install from https://docs.deno.com/runtime/getting_started/installation/
+
+## Using the ct Tool
+
+```bash
+# Deploy new pattern
+./dist/ct charm new -i claude.key -a http://localhost:8000 -s space pattern.tsx
+
+# Update existing pattern
+./dist/ct charm setsrc -i claude.key -a http://localhost:8000 -s space -c [id] pattern.tsx
+
+# Inspect pattern
+./dist/ct charm inspect -i claude.key -a http://localhost:8000 -s space -c [id]
+
+# Get pattern source
+./dist/ct charm getsrc -i claude.key -a http://localhost:8000 -s space -c [id] output.tsx
+```
+
+For more ct commands, see the ct Claude Skill or run `./dist/ct --help`.