fix(cloud-dev): open /dev/ URL by default, restore background node_modules copy

- Append /dev/ to all URLs shown/opened in `crayon cloud run`
- Restore background node_modules population in entrypoint.sh (reverts
  unintentional blocking change from d2162fd); dev server can start
  immediately via parent-directory lookup to /node_modules in image root
- Improve entrypoint comments to clarify the flock/preinstall relationship
  and that the copy seeds the volume for fast subsequent npm installs

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: cevian

README.md

@@ -15,93 +15,49 @@ This installs all dependencies (Node.js, Claude Code, Tiger CLI) and sets up the
 After installation, open a new terminal and run:
 
 ```bash
-crayon run
+crayon cloud run
 ```
-___
-### Want to contribute? - Developer Guide
+Want to contribute? See [DEVELOPMENT.md](DEVELOPMENT.md).
 
-To use the plugin from source:
+## Quick Start
 
 ```bash
-git clone https://github.com/timescale/crayon.git
-cd crayon
-pnpm install
-pnpm build
-npx tsx packages/core/src/cli/index.ts install --force
+crayon cloud run
 ```
 
-> **Note:** This outputs the `claude --plugin-dir <path>` command you need to run Claude Code with the local plugin.
-
-## Quick Start
-
-From an app directory (e.g., `examples/uptime-app`):
+This spins up a cloud sandbox and opens the dev environment in your browser. Describe what you want to automate — Claude will build, test, and iterate on your workflow automatically. Once ready, trigger it manually or connect it to a webhook.
 
+Prefer working in your terminal?
 ```bash
-# List available workflows
-pnpm crayon list
-
-# Run a workflow
-pnpm crayon run url-check -i '{"url": "https://example.com"}'
-
-# View run history
-pnpm crayon history
-
-# Get details for a specific run (supports short IDs like git)
-pnpm crayon history bc44c8b1
+crayon cloud claude
 ```
 
+
 ## CLI Commands
 
 | Command | Description |
 |---------|-------------|
-| `crayon list` | List all available workflows |
-| `crayon list --json` | Output as JSON |
-| `crayon run <workflow> -i <json>` | Run a workflow with JSON input |
-| `crayon run <workflow> --json` | Output result as JSON |
-| `crayon history` | List past workflow executions |
-| `crayon history -n 10` | Limit to N runs |
-| `crayon history -w <name>` | Filter by workflow name |
-| `crayon history <run-id>` | Get details of a specific run |
+| `crayon cloud run` | Start a new or existing workspace |
+| `crayon cloud claude` | Connect to a claude session on the sanbox |
+
 
 ## Project Structure
 
 ```
 crayon/
 ├── packages/
-│   ├── core/       # SDK + runtime (crayon)
-│   ├── cli/        # CLI tool (runcrayon)
-│   └── ui/         # UI components (@crayon/ui)
-├── skills/         # Claude Code skills
-│   ├── spec-author/
-│   ├── compile-workflow/
-│   └── validate-spec/
-└── examples/
-    └── uptime-app/ # Example application
+│   ├── core/         # SDK + CLI + MCP server + Dev UI (published as `crayon`)
+│   ├── ui/           # React UI components (@crayon/ui)
+│   └── auth-server/  # OAuth server (Nango-based)
+└── skills/           # Claude Code skills
+    ├── create-workflow/
+    ├── compile-workflow/
+    ├── refine-node/
+    ├── integrations/
+    └── deploy/
 ```
 
-## Testing Local Changes Against Cloud
-
-To test local core changes on a cloud dev machine:
-
-1. **Build & push a Docker image with your changes:**
-   ```bash
-   cd packages/core/docker && ./build-dev.sh <tag>
-   ```
-
-2. **Start the local auth server** (separate terminal):
-   ```bash
-   cd packages/auth-server && pnpm dev
-   ```
-
-3. **Create a new cloud machine using the local auth server:**
-   ```bash
-   CRAYON_SERVER_URL=http://localhost:3000 pnpm --filter runcrayon exec node dist/cli/index.js cloud run
-   ```
-
-4. **Open the dev UI** at `https://<fly-app-name>.fly.dev/dev/`
-
 ## Requirements
 
-- Node.js 20+
-- PostgreSQL with TimescaleDB (or use Timescale Cloud)
-- `DATABASE_URL` environment variable
+- Node.js 22+
+- A Claude Subscription

packages/core/docker/entrypoint.sh

@@ -76,9 +76,13 @@ if [ ! -f "$APP_DIR/package.json" ]; then
   log "  Running crayon init..."
   su -s /bin/bash "$DEV_USER" -c "cd '$APP_DIR' && "$CRAYON" init '$APP_NAME' --dir . --no-install"
 
-  # Copy pre-cached /node_modules onto the volume.
-  # Runs before the dev server starts so Turbopack can resolve packages.
-  log "  Populating node_modules..."
+  # Copy pre-cached /node_modules onto the volume in the background.
+  # The dev server starts immediately — Node.js resolves packages via parent-directory
+  # lookup to /node_modules in the image root. The copy seeds the volume so that later
+  # `npm install <pkg>` only fetches the new package instead of reinstalling everything.
+  # The app's preinstall hook (package.json) blocks on this same lock file, so any
+  # `npm install` invoked before the copy finishes will wait rather than racing.
+  log "  Starting node_modules population in background..."
   touch /tmp/node_modules.lock
   (
     exec 9>/tmp/node_modules.lock
@@ -92,7 +96,7 @@ if [ ! -f "$APP_DIR/package.json" ]; then
       rm -rf "$APP_DIR/node_modules_temp"
       log "  node_modules already exists, discarding temp copy"
     fi
-  )
+  ) &
 
   log "  Scaffold complete"
 fi

packages/core/src/cli/cloud-dev.ts

@@ -122,8 +122,9 @@ export async function runCloudRun(): Promise<void> {
     if (choice !== "__new__") {
       const existing = existingSandboxes.find((m) => m.app_name === choice);
       if (existing?.app_url) {
-        p.log.info(`URL: ${pc.cyan(existing.app_url)}`);
-        openInBrowser(existing.app_url);
+        const devUrl = existing.app_url.replace(/\/$/, "") + "/dev/";
+        p.log.info(`URL: ${pc.cyan(devUrl)}`);
+        openInBrowser(devUrl);
       }
       p.log.info(`Status: ${pc.bold(existing?.fly_state ?? "unknown")}`);
       p.outro(pc.green("Sandbox ready."));
@@ -227,10 +228,11 @@ export async function runCloudRun(): Promise<void> {
         )) as { status: string; url?: string; error?: string };
 
         if (statusResult.status === "running") {
-          const url = statusResult.url ?? createResult.appUrl;
+          const baseUrl = statusResult.url ?? createResult.appUrl;
+          const devUrl = baseUrl.replace(/\/$/, "") + "/dev/";
           s.stop(pc.green("Sandbox is running!"));
-          p.log.info(`URL: ${pc.cyan(url)}`);
-          openInBrowser(url);
+          p.log.info(`URL: ${pc.cyan(devUrl)}`);
+          openInBrowser(devUrl);
           p.outro(pc.green("Cloud dev environment is ready!"));
           return;
         }
@@ -249,7 +251,7 @@ export async function runCloudRun(): Promise<void> {
     }
 
     s.stop(pc.yellow("Sandbox is still starting"));
-    p.log.info(`URL: ${pc.cyan(createResult.appUrl)}`);
+    p.log.info(`URL: ${pc.cyan(createResult.appUrl.replace(/\/$/, "") + "/dev/")}`);
     p.log.info("Sandbox is taking longer than expected. Check status with:");
     p.log.info("  crayon cloud status");
     p.outro(pc.yellow("Cloud dev environment is starting..."));