Consolidate all recipe development docs

.claude/agents/recipe-dev-guide.md

@@ -7,7 +7,7 @@ color: orange
 You are an expert CommonTools recipe development guide specializing in helping users create, modify, and network recipes using the ct utility. You have deep knowledge of the CommonTools framework, recipe patterns, and the ct command-line interface.
 
 **Critical Prerequisites**:
-- You MUST first read `.claude/commands/common/ct.md` for CT binary setup instructions
+- You MUST first read `docs/common/CT.md` for CT binary setup instructions
 - You MUST search for and read `COMPONENTS.md` and `RECIPES.md` files in the user's recipes folder before working on recipes
 - Read `HANDLERS.md` when encountering event handler errors
 - The user should have already run the space setup script or have an existing space

.claude/agents/research-specialist.md

@@ -7,7 +7,7 @@ color: pink
 
 You are a research specialist with expertise in systematic codebase investigation and technical analysis. Your role is to conduct thorough, methodical research on any topic or question using all available tools and resources.
 
-**CRITICAL FIRST STEP**: Before doing anything else, you MUST read .claude/commands/common/ct.md to understand how to use the CommonTools system properly.
+**CRITICAL FIRST STEP**: Before doing anything else, you MUST read docs/common/CT.md to understand how to use the CommonTools system properly.
 
 **Your Research Methodology**:
 

.claude/commands/imagine-recipe.md

@@ -6,10 +6,10 @@ This script guides Claude through creating new CommonTools recipes based on user
 
 **Before starting recipe imagination:**
 - User should have an existing space or have run the space setup script
-- Claude MUST read the common CT setup instructions in `.claude/commands/common/ct.md`
+- Claude MUST read the common CT setup instructions in `docs/common/CT.md`
 
 **Recipe Documentation Reference:**
-Before working on recipes, search for these documentation files in the user's `recipes` folder:
+Before working on recipes, search for these documentation files in the `docs/common` folder:
 - `RECIPES.md` - Core recipe development patterns and examples
 - `COMPONENTS.md` - Available UI components and usage patterns
 - `HANDLERS.md` - Event handler patterns and troubleshooting
@@ -21,7 +21,7 @@ The user provides an initial prompt describing what they want their recipe to do
 ### STEP 1: Initial Setup and Context
 
 **Read common setup instructions:**
-- First, read `.claude/commands/common/ct.md` for shared CT binary setup
+- First, read `docs/common/CT.md` for shared CT binary setup
 - Follow those instructions for CT binary check, identity management, environment setup
 - Collect required parameters (API URL, space name, recipe path, identity file)
 

.claude/commands/onboarding.md

@@ -14,7 +14,7 @@ This command provides an interactive tour of the Common Tools platform repositor
 "Now that you have the basic idea, what would you like to know more about:
 
 - **Programs that run in this platform** (recipes, charms, UI components)
-- **The runtime that enables information flow analysis and storage** (runner, builder, storage)  
+- **The runtime that enables information flow analysis and storage** (runner, builder, storage)
 - **The application layer that users access the platform through** (toolshed, shell, CLI)
 - **The LLM tooling layer** (Claude commands, subagents, and development workflows)
 
@@ -53,7 +53,7 @@ Based on the user's choice in Step 2, follow these focused exploration paths:
 **Explore in order:**
 1. **Toolshed backend** - Quote from `packages/toolshed/README.md` about hosted platform
 2. **Shell frontend** - Quote from `packages/shell/README.md` about user interface
-3. **CT CLI** - Overview from `.claude/commands/common/ct.md`
+3. **CT CLI** - Overview from `docs/common/CT.md`
 4. **How they work together** - Integration points and data flow
 5. **Development workflow** - Running local development environment
 
@@ -71,15 +71,15 @@ Based on the user's choice in Step 2, follow these focused exploration paths:
 
 **Throughout any path, users can access:**
 - **Available commands**: List `.claude/commands/` and read `.claude/commands/README.md`
-- **Integration setup**: Review `deps.md` for tools and MCP integrations  
+- **Integration setup**: Review `deps.md` for tools and MCP integrations
 - **Development guidelines**: Reference `CLAUDE.md` for coding standards
 - **Research commands**: Use `/research` to dive deeper into specific areas
 
 ## Adventure Branches
 
 **Users can switch paths or dive deeper:**
 - From Recipe Development → explore Runtime internals
-- From Runtime → understand Application layer integration  
+- From Runtime → understand Application layer integration
 - From Application layer → try Recipe development
 - Or combine multiple paths based on curiosity
 
@@ -96,15 +96,15 @@ Based on the user's choice in Step 2, follow these focused exploration paths:
 **Critical: This is a guided discovery experience, not a fire-hose lecture:**
 
 - **Start tiny and build** - Don't read multiple files at once. Start with one small section
-- **Quote small chunks** - Show 2-3 sentences from files, not entire sections  
+- **Quote small chunks** - Show 2-3 sentences from files, not entire sections
 - **Wait for their reaction** - After each quote, ask what they think and WAIT for response
 - **Follow their energy** - Only show more based on what sparked their curiosity
 - **Never charge ahead** - Resist the urge to show everything; be patient and responsive
 - **Let silence be OK** - Give them time to process and respond
 
 **Example flow:**
 1. Read just the "What is Common Tools?" section from README.md
-2. Quote the first paragraph: "Common Tools is a new distributed computing platform..."  
+2. Quote the first paragraph: "Common Tools is a new distributed computing platform..."
 3. Ask: "What's your first reaction to this?"
 4. Wait for user response
 5. Based on their response, show ONLY the next relevant small piece
@@ -115,4 +115,4 @@ Based on the user's choice in Step 2, follow these focused exploration paths:
 - Don't summarize what you found after reading files
 - Don't offer too many paths; the four focused paths are sufficient based on their actual interest
 
-**Key principle:** The user should feel like they're discovering things themselves with Claude as a helpful guide, not receiving a presentation.
+**Key principle:** The user should feel like they're discovering things themselves with Claude as a helpful guide, not receiving a presentation.

.claude/commands/recipe-dev.md

@@ -6,7 +6,7 @@ This script guides Claude through recipe development with the `ct` utility after
 
 **Before starting recipe development:**
 - User should have already run the space setup script or have an existing space
-- Claude MUST read the common CT setup instructions in `.claude/commands/common/ct.md`
+- Claude MUST read the common CT setup instructions in `docs/common/CT.md`
 
 ## Script Flow for Claude
 
@@ -27,7 +27,7 @@ This script guides Claude through recipe development with the `ct` utility after
 ### STEP 1: Initial Setup and Context (ONLY if no config provided)
 
 **Read common setup instructions:**
-- First, read `.claude/commands/common/ct.md` for shared CT binary setup
+- First, read `docs/common/CT.md` for shared CT binary setup
 - Follow those instructions for:
   - CT binary check
   - Identity management
@@ -42,7 +42,7 @@ This script guides Claude through recipe development with the `ct` utility after
 
 ### STEP 2: Recipe Development Workflows
 
-Before working on recipes it is recommended to search for `COMPONENTS.md` and `RECIPES.md` files in the `recipes` folder provided by the user.
+Before working on recipes it is recommended to search for `COMPONENTS.md` and `RECIPES.md` files in the `docs/common` folder.
 
 Read `HANDLERS.md` when confused about event handler errors.
 

.claude/commands/research.md

@@ -15,7 +15,7 @@ Task: Research [topic/question]
 
 You are a research specialist. Conduct thorough investigation of the topic using all available tools.
 
-**First, learn how to use ct:** Read .claude/commands/common/ct.md to understand how to use the CommonTools system.
+**First, learn how to use ct:** Read docs/common/CT.md to understand how to use the CommonTools system.
 
 **Your Task:**
 1. **Consult the wiki first** - Read .claude/commands/search-wiki.md to learn how to check for existing knowledge on this topic
@@ -33,7 +33,7 @@ You are a research specialist. Conduct thorough investigation of the topic using
 ## Research Methodology
 
 ### Core Steps
-- **Learn ct usage first** - Read .claude/commands/common/ct.md to understand CommonTools
+- **Learn ct usage first** - Read docs/common/CT.md to understand CommonTools
 - **Start with wiki search** to avoid duplicating previous research
 - Use Task tool for systematic codebase exploration
 - Check recent git history and commits
@@ -55,7 +55,7 @@ You are a research specialist. Conduct thorough investigation of the topic using
 
 After research is complete, you MUST ask: "Would you like me to deploy this as a CommonTools research report?"
 
-If yes, use the .claude/commands/deploy-research.md command. Make sure to read .claude/commands/common/ct.md first to understand how to use the CommonTools system properly.
+If yes, use the .claude/commands/deploy-research.md command. Make sure to read docs/common/CT.md first to understand how to use the CommonTools system properly.
 
 ## When to Use
 

.claude/commands/search-wiki.md

@@ -18,7 +18,7 @@ You are a wiki search specialist. Your job is to search the project wiki for rel
 - Wiki Charm ID: baedreigkqfmhscbwwfhkjxicogsw3m66nxbetlhlnjkscgbs56hsqjrmkq
 
 **Your Task:**
-0. **First, learn how to use ct:** Read .claude/commands/common/ct.md to understand how to use the CommonTools system.
+0. **First, learn how to use ct:** Read docs/common/CT.md to understand how to use the CommonTools system.
 
 1. Get all wiki content: `./dist/ct charm get --identity claude.key --api-url https://toolshed.saga-castor.ts.net/ --space 2025-wiki --charm baedreigkqfmhscbwwfhkjxicogsw3m66nxbetlhlnjkscgbs56hsqjrmkq wiki`
 

.claude/commands/setup-space.md

@@ -7,7 +7,7 @@ This script guides Claude through setting up a complete space with the `ct` util
 ### STEP 1: Initial Setup Check and Preparation
 
 **Read common setup instructions:**
-- First, read `.claude/commands/common/ct.md` for shared CT binary setup and configuration
+- First, read `docs/common/CT.md` for shared CT binary setup and configuration
 - Follow those instructions for:
   - Checking if user is in the right directory (should be in `labs`)
   - CT binary check and build if needed
@@ -78,7 +78,7 @@ This script guides Claude through setting up a complete space with the `ct` util
 ### Error Handling
 
 **General error handling:**
-- Refer to error handling section in `.claude/commands/common/ct.md` for common issues
+- Refer to error handling section in `docs/common/CT.md` for common issues
 - Don't continue to dependent steps until current step works
 
 **Space setup specific errors:**
@@ -149,7 +149,7 @@ echo '[{"name": "Item 1"}, {"name": "Item 2"}]' | ./dist/ct charm set --identity
 ## Reference Information for Claude
 
 ### Key Commands and Linking Concepts:
-- See `.claude/commands/common/ct.md` for:
+- See `docs/common/CT.md` for:
   - Complete list of CT commands
   - Understanding linking syntax and concepts
   - Examples of charm-to-charm and well-known ID linking
@@ -164,7 +164,7 @@ echo '[{"name": "Item 1"}, {"name": "Item 2"}]' | ./dist/ct charm set --identity
 - Charms list in any space: `baedreiahv63wxwgaem4hzjkizl4qncfgvca7pj5cvdon7cukumfon3ioye`
 
 ### Space Setup Specific Notes:
-- See `.claude/commands/common/ct.md` for general troubleshooting
+- See `docs/common/CT.md` for general troubleshooting
 - Recipe files needed for initial setup:
   - simple-list.tsx
   - gmail.tsx

.claude/commands/update-wiki.md

@@ -14,7 +14,7 @@ When you need to update the wiki, follow these steps:
 
 **Process:**
 
-0. **First, learn how to use ct:** Read .claude/commands/common/ct.md to understand how to use the CommonTools system.
+0. **First, learn how to use ct:** Read docs/common/CT.md to understand how to use the CommonTools system.
 
 1. Choose appropriate page key following naming conventions:
    - Solutions: `[problem-type]-solution` or `fix-[specific-issue]`

AGENTS.md

@@ -14,7 +14,7 @@ The instructions in this document apply to the entire repository.
 
 ### `ct` & Common Tools Framework
 
-Before ever calling `ct` you MUST read `.claude/commands/common/ct.md`.
+Before ever calling `ct` you MUST read `docs/common/CT.md`.
 
 ### Recipe Development
 

README.md

@@ -45,8 +45,7 @@ written in Deno2, that provides the distributed runtime and storage.
 Lit Web Components for interacting with CommonTools spaces.
 
 **CLI (CT Binary)**: Command-line interface for managing charms, linking
-recipes, and deploying to spaces. See
-[CT Usage Guide](./.claude/commands/common/ct.md).
+recipes, and deploying to spaces. See [CT Usage Guide](./docs/common/CT.md).
 
 **UI Components ([packages/ui](./packages/ui))**: Custom VDOM layer and `ct-`
 prefixed components for recipe UIs.
@@ -55,7 +54,8 @@ prefixed components for recipe UIs.
 recipes and common patterns for building with CommonTools.
 
 **Recipe Development**: Recipes can be developed using LLM assistance with
-commands like `/imagine-recipe`, `/recipe-dev`, and `/explore-recipe`.
+commands like `/imagine-recipe`, `/recipe-dev`, and `/explore-recipe`. See
+[Recipe Documentation](./docs/common/) for patterns, components, and handlers.
 
 ## Development & Integrations