showpane 0.4.13 → 0.4.15

package/bundle/toolchain/skills/portal-preview/SKILL.md.tmpl

@@ -0,0 +1,171 @@
+---
+name: portal-preview
+description: |
+  Open a portal in the browser for preview. Use when asked to "preview portal",
+  "open portal", "view portal", "show me the portal", or "open in browser". (showpane)
+allowed-tools: [Bash, Read]
+---
+
+{{PREAMBLE}}
+
+## Overview
+
+This skill opens a portal in the user's default web browser. It is the fastest way to see what a portal looks like after creating or updating it. The skill determines the correct URL based on whether a local dev server is running and whether a public app URL is configured, then opens it using the platform's native command.
+
+This is a lightweight skill -- it does not start a dev server, build the app, or modify anything. It just opens a URL. If the dev server is not running, it tells the user how to start it.
+
+## Steps
+
+### Step 1: Identify the target portal
+
+If the user specified a slug (e.g., "preview whzan"), use that slug directly.
+
+If no slug is provided, check how many portals exist:
+- If there is exactly one portal, use that one and mention it: "Opening your only portal: <slug>"
+- If there are multiple portals, ask: "Which portal do you want to preview? Run /portal-list to see your portals."
+- If there are zero portals, say: "No portals found. Create one first with /portal-create."
+
+For single-portal organizations, auto-selecting saves a round trip.
+
+### Step 2: Determine the correct URL
+
+The URL depends on the environment. Check in this order of priority:
+
+**Option A: Local dev server running (check port 3000)**
+
+```bash
+lsof -i :3000 -sTCP:LISTEN -t >/dev/null 2>&1 && echo "DEV_RUNNING=true" || echo "DEV_RUNNING=false"
+```
+
+If a process is listening on port 3000, the URL is:
+```
+http://localhost:3000/client/<slug>
+```
+
+**Option B: NEXT_PUBLIC_APP_URL is set**
+
+If the environment variable `NEXT_PUBLIC_APP_URL` is set (sourced from `.env` by the preamble), use it:
+```
+${NEXT_PUBLIC_APP_URL}/client/<slug>
+```
+
+This handles deployed URLs, custom domains, and any other public preview target.
+
+**Fallback: Nothing running**
+
+If no server is detected and no app URL is configured, do not open the browser. Instead, inform the user:
+
+"No running server detected. Start the dev server with /portal-dev, or set NEXT_PUBLIC_APP_URL in your .env file."
+
+### Step 3: Open the URL in the browser
+
+Use the platform-appropriate command:
+
+```bash
+# macOS
+open "<url>"
+
+# Linux
+xdg-open "<url>"
+```
+
+Detect the platform:
+
+```bash
+if [[ "$OSTYPE" == "darwin"* ]]; then
+  open "<url>"
+elif command -v xdg-open >/dev/null 2>&1; then
+  xdg-open "<url>"
+else
+  echo "Cannot detect browser opener. Visit: <url>"
+fi
+```
+
+Run this in a single Bash tool call so the browser opens immediately.
+
+### Step 4: Print confirmation
+
+After opening, display:
+
+```
+Opened portal for <slug> in browser
+URL: http://localhost:3000/client/<slug>
+```
+
+If the portal has credentials set up, remind the user:
+"Login with the credentials from /portal-credentials <slug>. For external access, publish first with /portal-deploy."
+
+If the portal is the example portal (slug is "example"), no credentials are needed -- it is publicly accessible by design.
+
+## URL Priority Order
+
+To be explicit about resolution order:
+
+1. **Dev server on port 3000** -- always preferred for local development, regardless of other settings.
+2. **NEXT_PUBLIC_APP_URL** -- used for deployed environments or when no local server is detected.
+3. **Fallback** -- no URL available, prompt the user to start a server.
+
+This order ensures that during development, the user always sees the latest local version, even if NEXT_PUBLIC_APP_URL points to production.
+
+## Conventions
+
+- Always check for a running server before attempting to open. Opening a URL with no server just shows a browser error page -- a poor experience.
+- Print the full URL so the user can copy-paste it if needed (e.g., to share with a colleague looking at the same screen).
+- Do not open multiple browser tabs. One call to `open` per invocation.
+- If the slug is "example", mention that this is the built-in example portal and does not require authentication.
+- If learnings indicate the user prefers a specific browser or has a custom port, adapt the URL accordingly.
+
+## Edge Cases
+
+- **Port conflict**: If port 3000 has a non-Showpane process running, `lsof` will still detect it and the URL will be wrong. This is unlikely in practice but worth noting. The user will see a different app in the browser and can correct by specifying the URL manually.
+- **WSL (Windows Subsystem for Linux)**: `xdg-open` may not work. On WSL, use `wslview` or `explorer.exe` instead. Detect WSL via `grep -qi microsoft /proc/version`.
+- **SSH/remote session**: If the user is connected via SSH, opening a browser on the remote machine does nothing useful. Detect this via the `SSH_CONNECTION` environment variable and print the URL instead: "You appear to be in an SSH session. Visit this URL on your local machine: <url>"
+- **Inactive portal**: If the portal is deactivated (`isActive: false`), the preview will show a "not found" page. Warn the user: "Portal '<slug>' is inactive. You'll see a not-found page. Reactivate it first or use /portal-list to check status."
+
+## Error Handling
+
+- If the preamble fails, stop and display the error.
+- If no server is running and no URL is configured, provide clear instructions rather than opening a dead URL.
+- If the `open` or `xdg-open` command fails, print the URL as a fallback: "Could not open browser automatically. Visit: <url>"
+
+## Login Context
+
+When the portal opens in the browser, the client will see a login page (unless they have an active session or use a share link). Provide context about how to access the portal:
+
+- **Has credentials**: Remind the user of the username (derived from the slug). Do not display the password -- they can get it from `/portal-credentials <slug>` if they need it.
+- **No credentials**: Warn that the portal will show a login page but there are no credentials to enter. Suggest running `/portal-credentials <slug>` first.
+- **Example portal**: The built-in example at `/client/example` is publicly accessible and does not require login. No credentials needed.
+
+If the user is previewing to check content before sharing with a client, suggest: "To see exactly what the client will see, open an incognito/private window. Your existing session cookies may affect the view. When the portal looks right, publish it with /portal-deploy before sending anything externally."
+
+## Previewing After Changes
+
+A common workflow is: edit portal content with `/portal-update`, then preview to verify. If the dev server is running with Next.js hot reload, changes to the client component files will appear immediately without a page refresh.
+
+If the user just ran `/portal-update` and then `/portal-preview`, mention: "If you don't see your changes, make sure the dev server is running so hot reload can pick them up."
+
+## Multiple Portals Preview
+
+If the user asks to "preview all portals" or "open all my portals", open each one in a separate browser tab. However, limit to 5 tabs maximum to avoid browser overload. If there are more than 5 portals, open the 5 most recently updated and note: "Opened the 5 most recently updated portals. Use /portal-preview <slug> for specific portals."
+
+To open multiple tabs, run the open command for each URL sequentially:
+
+```bash
+open "http://localhost:3000/client/whzan"
+open "http://localhost:3000/client/acme"
+open "http://localhost:3000/client/example"
+```
+
+Each `open` call creates a new tab in the default browser.
+
+## Telemetry
+
+If telemetry is enabled, the preview skill records a minimal event:
+
+```json
+{"skill":"portal-preview","ts":"2026-04-07T12:00:00Z","duration_s":1,"outcome":"success"}
+```
+
+No portal slug or URL is included in telemetry. The event only records that a preview was triggered.
+
+{{COMPLETION}}

package/bundle/toolchain/skills/portal-setup/SKILL.md

@@ -14,38 +14,42 @@ hooks:
 
 ## Preamble (run first)
 
-This skill's preamble is different from other skills — it does NOT require config.json to exist, because this skill creates it.
+This skill's preamble is tolerant of first-run state because setup may create the config.
 
 ```bash
-# --- Portal Setup Preamble ---
-CONFIG="$HOME/.showpane/config.json"
+SHOWPANE_HOME="$HOME/.showpane"
+SHOWPANE_BIN="$SHOWPANE_HOME/bin"
+CONFIG="$SHOWPANE_HOME/config.json"
+APP_PATH=""
+DEPLOY_MODE="local"
+ORG_SLUG=""
 EXISTING_CONFIG=false
+
 if [ -f "$CONFIG" ]; then
   EXISTING_CONFIG=true
   APP_PATH=$(python3 -c "import json; d=json.load(open('$CONFIG')); print(d.get('app_path',''))" 2>/dev/null || true)
-  DEPLOY_MODE=$(python3 -c "import json; d=json.load(open('$CONFIG')); print(d.get('deploy_mode',''))" 2>/dev/null || true)
+  DEPLOY_MODE=$(python3 -c "import json; d=json.load(open('$CONFIG')); print(d.get('deploy_mode','local'))" 2>/dev/null || echo "local")
   ORG_SLUG=$(python3 -c "import json; d=json.load(open('$CONFIG')); print(d.get('orgSlug','') or d.get('org_slug',''))" 2>/dev/null || true)
-  echo "EXISTING_CONFIG: true"
-  echo "APP_PATH: $APP_PATH"
-  echo "DEPLOY_MODE: $DEPLOY_MODE"
-  echo "ORG_SLUG: $ORG_SLUG"
-else
-  echo "EXISTING_CONFIG: false"
-  echo "No config found. Starting fresh setup."
 fi
 
-SKILL_DIR="${SHOWPANE_TOOLCHAIN_DIR:-$HOME/.showpane/current}"
-SKILL_VERSION=$(head -1 "$SKILL_DIR/skills/VERSION" 2>/dev/null | cut -d' ' -f1 || echo "unknown")
-echo "SHOWPANE: v$SKILL_VERSION | SETUP MODE"
-
-# Predictive next-skill suggestion
-if [ -f "$HOME/.showpane/timeline.jsonl" ]; then
-  _RECENT=$(grep '"event":"completed"' "$HOME/.showpane/timeline.jsonl" 2>/dev/null | tail -3 | grep -o '"skill":"[^"]*"' | sed 's/"skill":"//;s/"//' | tr '\n' ',' | sed 's/,$//' || true)
+SKILL_DIR="${SHOWPANE_TOOLCHAIN_DIR:-$SHOWPANE_HOME/current}"
+SKILL_VERSION=$(cat "$SKILL_DIR/VERSION" 2>/dev/null || echo "unknown")
+_UPD=$("$SHOWPANE_BIN/showpane-update-check" 2>/dev/null || true)
+[ -n "$_UPD" ] && echo "$_UPD" || true
+mkdir -p "$SHOWPANE_HOME/sessions" "$SHOWPANE_HOME/analytics" "$SHOWPANE_HOME/checkpoints"
+touch "$SHOWPANE_HOME/sessions/$PPID"
+find "$SHOWPANE_HOME/sessions" -mmin +120 -type f -delete 2>/dev/null || true
+TEL=$("$SHOWPANE_BIN/showpane-config" get telemetry 2>/dev/null || echo "anonymous")
+TEL_PROMPTED=$([ -f "$SHOWPANE_HOME/.telemetry-prompted" ] && echo "yes" || echo "no")
+_TEL_START=$(date +%s)
+_SESSION_ID="${PPID:-0}-$(date +%s)"
+
+LEARN_FILE="$SHOWPANE_HOME/learnings.jsonl"
+if [ -f "$SHOWPANE_HOME/timeline.jsonl" ]; then
+  _RECENT=$(grep '"event":"completed"' "$SHOWPANE_HOME/timeline.jsonl" 2>/dev/null | tail -3 | grep -o '"skill":"[^"]*"' | sed 's/"skill":"//;s/"//' | tr '
+' ',' | sed 's/,$//' || true)
   [ -n "$_RECENT" ] && echo "RECENT_SKILLS: $_RECENT"
 fi
-
-# Search relevant learnings
-LEARN_FILE="$HOME/.showpane/learnings.jsonl"
 if [ -f "$LEARN_FILE" ]; then
   _LEARN_COUNT=$(wc -l < "$LEARN_FILE" 2>/dev/null | tr -d ' ')
   echo "LEARNINGS: $_LEARN_COUNT entries"
@@ -55,24 +59,43 @@ if [ -f "$LEARN_FILE" ]; then
   fi
 fi
 
-# Track skill execution
-SHOWPANE_TIMELINE="$HOME/.showpane/timeline.jsonl"
+SHOWPANE_TIMELINE="$SHOWPANE_HOME/timeline.jsonl"
 mkdir -p "$(dirname "$SHOWPANE_TIMELINE")"
 echo '{"skill":"portal-setup","event":"started","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> "$SHOWPANE_TIMELINE" 2>/dev/null
-# --- End Preamble ---
+echo "SHOWPANE: v$SKILL_VERSION | SETUP MODE"
+echo "EXISTING_CONFIG: $EXISTING_CONFIG"
+echo "APP_PATH: ${APP_PATH:-missing}"
+echo "DEPLOY_MODE: $DEPLOY_MODE"
+echo "ORG_SLUG: ${ORG_SLUG:-missing}"
+echo "TELEMETRY: $TEL"
+echo "TEL_PROMPTED: $TEL_PROMPTED"
 ```
 
-If RECENT_SKILLS is shown, suggest the likely next skill:
+If output shows `JUST_UPGRADED <from> <to>`, tell the user Showpane was just upgraded and continue.
+
+If output shows `UPGRADE_AVAILABLE <old> <new>`, tell the user a newer Showpane toolchain is available and recommend `/portal-upgrade`.
+
+If `TEL_PROMPTED` is `no`, default telemetry to `anonymous` without interrupting the flow. Do not mention telemetry unless the user asks.
+
+Run:
+```bash
+"$SHOWPANE_BIN/showpane-config" set telemetry anonymous
+touch "$SHOWPANE_HOME/.telemetry-prompted"
+```
+
+If `RECENT_SKILLS` is shown, suggest the likely next skill:
 - After portal-create → suggest /portal-preview
-- After portal-preview → suggest /portal-deploy or /portal-share
+- After portal-preview → suggest /portal-deploy
 - After portal-deploy → suggest /portal-status or /portal-verify
-- After portal-setup → suggest /portal-create
-- After portal-credentials → suggest /portal-share
-- After portal-update → suggest /portal-deploy
+- After portal-setup → suggest /portal-onboard for a first run, or /portal-create for the fast path
+- After portal-credentials → suggest /portal-deploy before external sharing
+- After portal-update → suggest /portal-preview or /portal-deploy
+
+If `RECENT_LEARNINGS` is shown, review them before proceeding. Apply them where relevant but do not mention them unless they materially affect the current task.
+
+Read `skills/shared/runtime-principles.md` once near the start of the skill and apply the relevant product defaults.
 
-If RECENT_LEARNINGS is shown, review them before proceeding. Past learnings may contain
-relevant warnings or tips for this operation. Apply them where relevant but don't
-mention them unless they directly affect the current task.
+If `skills/shared/platform-constraints.md` exists, read it once near the start of the skill and apply only the relevant limits.
 
 ## Steps
 
@@ -114,7 +137,7 @@ When the user is inside a freshly generated Showpane project, the setup should:
 - Prefer the current working directory as `APP_PATH`
 - Skip any suggestion to clone the upstream Showpane repository
 - Auto-detect SQLite from DATABASE_URL (if it starts with "file:" it's SQLite)
-- Still ask for org name, contact details, and website URL
+- Reuse the existing workspace org name if it is already obvious, then ask for the next missing contact detail one at a time
 - Be concise — the user just ran `npx showpane` and wants to get going fast
 
 ### Step 3: Set the workspace mode
@@ -164,12 +187,17 @@ Do NOT proceed until the local schema is applied successfully.
 
 Ask the user for their organization details one at a time. Do not present all questions at once — guide them through the process conversationally.
 
-1. **Organization name** (required) — e.g., "Acme Consulting". This is the name that appears in portal headers alongside the client name.
+Before asking anything, check the local database. If there is already exactly one organization and it clearly matches the workspace the user just created, keep it as the default and do not ask for the organization name again unless the user wants to change it.
+
+If the org already exists with a real name, ask only for the next missing field.
+Do not restart the whole org questionnaire from the top.
+
+1. **Organization name** (required only if not already known) — e.g., "Acme Consulting". This is the name that appears in portal headers alongside the client name.
 2. **Contact name** (required) — the person who appears on portal footers as the point of contact, e.g., "Jane Smith". This is typically the account manager or sales rep.
 3. **Contact email** (required) — e.g., "jane@acme.com". Displayed in the portal footer as a mailto link.
 4. **Contact title** (optional, default: "Account Manager") — e.g., "Director", "Partner", "Client Success Lead". Shown next to the contact name in the portal footer.
 5. **Contact phone** (optional) — e.g., "+44 7700 900000". If provided, displayed alongside email in the portal footer.
-6. **Company website URL** (optional) — e.g., "acme.com". Used to auto-fetch the company logo via Clearbit.
+6. **Company website URL** — e.g., "acme.com". Ask for it plainly instead of framing it as optional. Used to auto-fetch the company logo via Clearbit.
    - If provided, fetch logo URL: `https://logo.clearbit.com/{domain}` and store in `Organization.logoUrl`
    - Also store the URL in `Organization.websiteUrl`
 7. **Contact avatar**: Auto-populated from the contact email via Gravatar. No need to ask — just use `getAvatarUrl(email, contactName)` from `app/src/lib/branding.ts` and store in `Organization.contactAvatar`
@@ -201,20 +229,19 @@ Validate the input is a valid hex color:
 
 Update the Organization record with `primaryColor` set to the validated hex value. The portal app reads this value and applies it via CSS custom properties (the `--primary` variable in the Tailwind theme).
 
-If the user says "skip" or "default", use `#1a1a1a`. Brand color can always be changed later by running `/portal setup` again.
+If the user says "skip" or "default", use `#1a1a1a`. Brand color can always be changed later by running `/portal-setup` again.
 
-### Step 8: Telemetry opt-in
+### Step 8: Telemetry reminder
 
-Ask the user about anonymous usage telemetry:
+Do not re-run the global telemetry interview here.
 
-> "Help Showpane improve! Share anonymous usage data (which skills you use, how long they take). No code, file paths, or portal content is ever sent."
+If the shared runtime preamble already set telemetry, keep that value. If it has
+not been set yet for some reason, default to:
 
-Options:
-- **community** — anonymous usage stats with a stable device ID for deduplication
-- **anonymous** — anonymous usage stats with no device ID
-- **off** — no telemetry (default)
+- **anonymous** — local analytics plus anonymous remote sync, no stable device ID
+- **off** — local analytics only, no remote sync
 
-Store the choice in config.
+If you must set it manually, write the chosen value into config.
 
 ### Step 9: Save configuration
 
@@ -232,7 +259,7 @@ cat > "$HOME/.showpane/config.json" << 'CONFIGEOF'
   "app_path": "<resolved_absolute_path>",
   "deploy_mode": "local",
   "orgSlug": "<org_slug>",
-  "telemetry": "<community|anonymous|off>"
+  "telemetry": "<anonymous|off>"
 }
 CONFIGEOF
 chmod 600 "$HOME/.showpane/config.json"
@@ -251,11 +278,11 @@ Showpane setup complete!
   Deploy mode:  local
   Organization: Acme Consulting (acme-consulting)
   Brand color:  #2563eb
-  Telemetry:    off
+  Telemetry:    anonymous
 
 Next steps:
-  1. Start the dev server:     /portal dev
-  2. Create your first portal: /portal create <slug>
+  1. Recommended first run:    /portal-onboard
+  2. Fast repeat-user path:    /portal-create <slug>
   3. View the example portal:  open http://localhost:3000/client/example
 ```
 
@@ -282,19 +309,11 @@ Never silently continue past a failure. Each step depends on the previous step s
 
 ## Completion
 
-As a final step, log skill completion:
+As a final step, log skill completion and telemetry:
 
 ```bash
 echo '{"skill":"portal-setup","event":"completed","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> "$HOME/.showpane/timeline.jsonl" 2>/dev/null
+_TEL_END=$(date +%s)
+_TEL_DUR=$(( _TEL_END - ${_TEL_START:-_TEL_END} ))
+"$HOME/.showpane/bin/showpane-telemetry-log" --skill "portal-setup" --duration "$_TEL_DUR" --outcome success --session-id "${_SESSION_ID:-}" 2>/dev/null || true
 ```
-
-## Conventions
-
-- Never store DATABASE_URL or AUTH_SECRET in config.json — these live in the app's `.env` file
-- Config file permissions must be 600 (owner read/write only)
-- The orgSlug in config.json determines which Organization record is used by all other skills
-- All user-facing output should be concise and scannable — use indented key-value pairs, not paragraphs
-- If any step fails, provide a clear error message and suggest how to fix it, but do not silently continue
-- The setup wizard is interactive — ask one question at a time, don't dump all questions at once
-- When reconfiguring, show current values as defaults so the user can press enter to keep them
-- The setup wizard should complete in under 5 minutes for a user with Node.js, internet access, and a generated Showpane project

package/bundle/toolchain/skills/portal-setup/SKILL.md.tmpl

@@ -0,0 +1,227 @@
+---
+name: portal-setup
+description: |
+  Interactive setup wizard for Showpane. Creates config, installs deps, applies the local SQLite schema, and creates the organization.
+  Trigger phrases: "portal setup", "configure showpane", "set up showpane", "initialize showpane". (showpane)
+allowed-tools: [Bash, Read, Write, Edit, Glob, Grep]
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "bash ${CLAUDE_SKILL_DIR}/../showpane-shared/bin/check-portal-guard.sh"
+---
+
+{{PREAMBLE}}
+
+## Steps
+
+### Step 1: Check for existing configuration
+
+If the preamble output shows `EXISTING_CONFIG: true`, inform the user that Showpane is already configured and show the current settings. Ask if they want to reconfigure. If they say no, exit gracefully. If they say yes, continue with the setup — existing values become defaults the user can accept or change.
+
+### Step 2: Detect or ask for app_path
+
+Try to find the Showpane app automatically by checking these locations in order:
+
+1. Current working directory — look for `package.json` containing `"name"` with "showpane" in it
+2. Parent directory — check `../app/` for the same
+3. Common locations: `~/git/showpane/`, `~/showpane/`
+4. The `SHOWPANE_APP_PATH` environment variable
+
+Run the detection:
+
+```bash
+for candidate in "$(pwd)" "$(pwd)/../app" "$HOME/git/showpane/app" "$HOME/showpane/app"; do
+  if [ -f "$candidate/package.json" ] && { [ -f "$candidate/prisma/schema.local.prisma" ] || [ -f "$candidate/prisma.config.ts" ]; }; then
+    echo "FOUND: $(cd "$candidate" && pwd)"
+    break
+  fi
+done
+```
+
+If found, confirm with the user: "Found Showpane app at /path/to/app. Use this? (Y/n)"
+
+If not found, ask the user to provide the path. Validate that the path exists and contains `package.json` plus either `prisma/schema.local.prisma` or `prisma.config.ts`. If those markers are missing, the path is not a valid Showpane app directory — explain which file is missing and ask again.
+
+Resolve the path to an absolute path (no `~` or relative components) before storing it. Use `cd "$path" && pwd` to resolve.
+
+Store the resolved absolute path as `APP_PATH`.
+
+#### Packaged Installer Mode
+
+When the user is inside a freshly generated Showpane project, the setup should:
+- Prefer the current working directory as `APP_PATH`
+- Skip any suggestion to clone the upstream Showpane repository
+- Auto-detect SQLite from DATABASE_URL (if it starts with "file:" it's SQLite)
+- Reuse the existing workspace org name if it is already obvious, then ask for the next missing contact detail one at a time
+- Be concise — the user just ran `npx showpane` and wants to get going fast
+
+### Step 3: Set the workspace mode
+
+Use `local` as the setup mode.
+
+Store `DEPLOY_MODE=local` in the config written later in this flow.
+
+### Step 4: Install dependencies
+
+Check if `$APP_PATH/node_modules` exists. If not, run:
+
+```bash
+cd "$APP_PATH" && npm install
+```
+
+If node_modules exists but `.prisma` client is missing, run:
+
+```bash
+cd "$APP_PATH" && npm run prisma:generate
+```
+
+Wait for installation to complete before proceeding.
+
+### Step 5: Apply the local database schema
+
+Source the app's `.env` file to get `DATABASE_URL`:
+
+```bash
+if [ -f "$APP_PATH/.env" ]; then set -a && source "$APP_PATH/.env" && set +a; fi
+```
+
+The supported setup path is SQLite. Apply the local schema:
+
+```bash
+cd "$APP_PATH" && npm run prisma:db-push
+```
+
+If `DATABASE_URL` is not set in `.env`, inform the user they need to configure it. Provide guidance:
+- For local development: `file:./dev.db`
+
+If `DATABASE_URL` is set to anything other than a `file:` URL, explain that the supported setup flow is SQLite-first and suggest resetting `.env` back to `file:./dev.db`.
+
+Do NOT proceed until the local schema is applied successfully.
+
+### Step 6: Create or find Organization record
+
+Ask the user for their organization details one at a time. Do not present all questions at once — guide them through the process conversationally.
+
+Before asking anything, check the local database. If there is already exactly one organization and it clearly matches the workspace the user just created, keep it as the default and do not ask for the organization name again unless the user wants to change it.
+
+If the org already exists with a real name, ask only for the next missing field.
+Do not restart the whole org questionnaire from the top.
+
+1. **Organization name** (required only if not already known) — e.g., "Acme Consulting". This is the name that appears in portal headers alongside the client name.
+2. **Contact name** (required) — the person who appears on portal footers as the point of contact, e.g., "Jane Smith". This is typically the account manager or sales rep.
+3. **Contact email** (required) — e.g., "jane@acme.com". Displayed in the portal footer as a mailto link.
+4. **Contact title** (optional, default: "Account Manager") — e.g., "Director", "Partner", "Client Success Lead". Shown next to the contact name in the portal footer.
+5. **Contact phone** (optional) — e.g., "+44 7700 900000". If provided, displayed alongside email in the portal footer.
+6. **Company website URL** — e.g., "acme.com". Ask for it plainly instead of framing it as optional. Used to auto-fetch the company logo via Clearbit.
+   - If provided, fetch logo URL: `https://logo.clearbit.com/{domain}` and store in `Organization.logoUrl`
+   - Also store the URL in `Organization.websiteUrl`
+7. **Contact avatar**: Auto-populated from the contact email via Gravatar. No need to ask — just use `getAvatarUrl(email, contactName)` from `app/src/lib/branding.ts` and store in `Organization.contactAvatar`
+
+Generate an org slug from the organization name: lowercase, replace spaces with hyphens, strip non-alphanumeric characters except hyphens, remove consecutive hyphens. For example, "Acme Consulting Ltd." becomes `acme-consulting-ltd`. Confirm the generated slug with the user and allow them to override it.
+
+Create the organization record in the database using the app's Prisma client. The Organization model stores:
+- `name`, `slug`, `contactName`, `contactEmail`, `contactTitle`, `contactPhone`
+
+If an Organization with that slug already exists in the database, present two options:
+1. Use the existing organization (show its current details so the user can verify)
+2. Create a new organization with a different slug
+
+If the user chooses to use the existing org, skip creation and proceed with that org's slug. This is common when reconfiguring or when multiple people set up the same Showpane instance.
+
+### Step 7: Theme configuration
+
+Ask the user for their primary brand color as a hex value. This color is used for active tab indicators, bullet point accents, and interactive elements throughout the portal. Provide suggestions:
+
+- Default: `#1a1a1a` (near-black, professional — works well for most brands)
+- Common choices: `#2563eb` (blue), `#059669` (green), `#dc2626` (red), `#7c3aed` (purple)
+- Tip: if the user has a brand guidelines document or website, suggest pulling the primary color from there
+
+Validate the input is a valid hex color:
+- Accept with or without `#` prefix (add `#` if missing)
+- Accept 3-digit shorthand (`#abc` expands to `#aabbcc`)
+- Accept 6-digit full form (`#2563eb`)
+- Reject anything else with a clear message: "Please enter a valid hex color like #2563eb"
+
+Update the Organization record with `primaryColor` set to the validated hex value. The portal app reads this value and applies it via CSS custom properties (the `--primary` variable in the Tailwind theme).
+
+If the user says "skip" or "default", use `#1a1a1a`. Brand color can always be changed later by running `/portal-setup` again.
+
+### Step 8: Telemetry reminder
+
+Do not re-run the global telemetry interview here.
+
+If the shared runtime preamble already set telemetry, keep that value. If it has
+not been set yet for some reason, default to:
+
+- **anonymous** — local analytics plus anonymous remote sync, no stable device ID
+- **off** — local analytics only, no remote sync
+
+If you must set it manually, write the chosen value into config.
+
+### Step 9: Save configuration
+
+Create the `~/.showpane/` directory if it doesn't exist:
+
+```bash
+mkdir -p "$HOME/.showpane"
+```
+
+Write the config file:
+
+```bash
+cat > "$HOME/.showpane/config.json" << 'CONFIGEOF'
+{
+  "app_path": "<resolved_absolute_path>",
+  "deploy_mode": "local",
+  "orgSlug": "<org_slug>",
+  "telemetry": "<anonymous|off>"
+}
+CONFIGEOF
+chmod 600 "$HOME/.showpane/config.json"
+```
+
+Replace the placeholder values with the actual values collected. Use `chmod 600` so only the owner can read/write the config (it may contain sensitive paths).
+
+### Step 10: Print success summary
+
+Display a clear summary:
+
+```
+Showpane setup complete!
+
+  App path:     /path/to/showpane-project
+  Deploy mode:  local
+  Organization: Acme Consulting (acme-consulting)
+  Brand color:  #2563eb
+  Telemetry:    anonymous
+
+Next steps:
+  1. Recommended first run:    /portal-onboard
+  2. Fast repeat-user path:    /portal-create <slug>
+  3. View the example portal:  open http://localhost:3000/client/example
+```
+
+### Step 11: Record learning (optional)
+
+If this is the first setup, create an initial learning entry:
+
+```bash
+mkdir -p "$HOME/.showpane"
+echo '{"skill":"portal-setup","key":"initial-setup","insight":"Setup completed. Deploy mode: <mode>. Org: <name>.","confidence":10,"ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> "$HOME/.showpane/learnings.jsonl"
+```
+
+## Error Handling
+
+Each step can fail independently. Handle failures gracefully:
+
+- **App path not found**: Ask the user to run `npx showpane` first or point setup at an existing generated Showpane project
+- **npm install fails**: Check Node.js version (requires 18+), check internet connectivity, suggest clearing `node_modules` and retrying
+- **Prisma db push fails**: Check that DATABASE_URL is set to `file:./dev.db` (or another valid SQLite `file:` URL) in `.env`
+- **Organization creation fails**: Check database connectivity. If the Prisma client throws a connection error, verify DATABASE_URL in `.env`
+- **Config write fails**: Check that `$HOME/.showpane/` is writable. On some systems, home directory permissions may block directory creation
+
+Never silently continue past a failure. Each step depends on the previous step succeeding.
+
+{{COMPLETION}}