showpane 0.4.1 → 0.4.2

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

@@ -0,0 +1,277 @@
+---
+name: portal-onboard
+description: |
+  Guided first-run experience that chains setup, create, credentials, and preview.
+  Use when asked to "get started", "onboard", "first time setup", "walk me through",
+  or "set up showpane from scratch". (showpane)
+allowed-tools: [Bash, Read, Write, Edit, Glob, Grep]
+---
+
+## Preamble (run first)
+
+Before doing anything else, execute this block in a Bash tool call:
+
+```bash
+CONFIG="$HOME/.showpane/config.json"
+if [ ! -f "$CONFIG" ]; then
+  echo "Showpane not configured. Run /portal setup first."
+  exit 1
+fi
+APP_PATH=$(cat "$CONFIG" | python3 -c "import sys,json; print(json.loads(sys.stdin.read()).get('app_path',''))" 2>/dev/null)
+DEPLOY_MODE=$(cat "$CONFIG" | python3 -c "import sys,json; print(json.loads(sys.stdin.read()).get('deploy_mode','docker'))" 2>/dev/null)
+ORG_SLUG=$(cat "$CONFIG" | python3 -c "import sys,json; d=json.loads(sys.stdin.read()); print(d.get('orgSlug','') or d.get('org_slug',''))" 2>/dev/null)
+APP_PATH="${SHOWPANE_APP_PATH:-$APP_PATH}"
+if [ -f "$APP_PATH/.env" ]; then set -a && source "$APP_PATH/.env" && set +a; fi
+DATABASE_URL="${DATABASE_URL:-}"
+if [ ! -d "$APP_PATH/node_modules/.prisma" ]; then
+  echo "App dependencies not installed. Run: cd $APP_PATH && npm install"
+  exit 1
+fi
+SKILL_DIR="${SHOWPANE_TOOLCHAIN_DIR:-$HOME/.showpane/current}"
+SKILL_VERSION=$(cat "$SKILL_DIR/VERSION" 2>/dev/null || echo "unknown")
+echo "SHOWPANE: v$SKILL_VERSION | MODE: $DEPLOY_MODE | APP: $APP_PATH"
+LEARN_FILE="$HOME/.showpane/learnings.jsonl"
+[ -f "$LEARN_FILE" ] && echo "LEARNINGS: $(wc -l < "$LEARN_FILE" | tr -d ' ') loaded" || echo "LEARNINGS: 0"
+
+# 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/,$//')
+  [ -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"
+  if [ "$_LEARN_COUNT" -gt 0 ] 2>/dev/null; then
+    echo "RECENT_LEARNINGS:"
+    tail -5 "$LEARN_FILE" 2>/dev/null
+  fi
+fi
+
+# Track skill execution
+SHOWPANE_TIMELINE="$HOME/.showpane/timeline.jsonl"
+mkdir -p "$(dirname "$SHOWPANE_TIMELINE")"
+echo '{"skill":"portal-onboard","event":"started","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> "$SHOWPANE_TIMELINE" 2>/dev/null
+```
+
+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-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
+
+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.
+
+## Overview
+
+This skill is the guided first-run experience for Showpane. It chains four other skills together in sequence -- setup, create, credentials, and preview -- walking the user through each step with clear transitions. The goal is to go from zero to a working portal in the browser in under 5 minutes.
+
+This is specifically designed for users who have just installed Showpane and want to see it working end-to-end. It is opinionated about the order of operations and provides more context and encouragement than the individual skills would on their own.
+
+The onboard flow is linear. Each step depends on the previous one completing successfully. If any step fails, the flow stops and provides recovery instructions rather than skipping ahead.
+
+## Steps
+
+### Step 1: Welcome message
+
+Start with a welcome that sets expectations. First, display the ASCII welcome banner:
+
+```
+ ╔══════════════════════════════════════════╗
+ ║  SHOWPANE — Client Portal Generator     ║
+ ╚══════════════════════════════════════════╝
+```
+
+Then continue with:
+
+"Welcome to Showpane! Let's set up your first client portal. This will take about 5 minutes and we'll go through four steps:
+
+1. Configure Showpane (app path, database, organization)
+2. Create your first portal
+3. Set up login credentials
+4. Open it in your browser
+
+Let's get started."
+
+This framing is important. It tells the user what to expect and roughly how long it will take. Uncertainty causes drop-off.
+
+### Step 2: Run the setup flow
+
+Read the instructions from `skills/portal-setup/SKILL.md` and execute the setup flow inline. This means you follow the setup skill's instructions as if the user had run `/portal setup` directly.
+
+The setup flow will:
+- Detect the app path (or ask the user)
+- Verify the database connection
+- Create or select an organization
+- Write the config to `~/.showpane/config.json`
+- Set file permissions
+
+During setup, also ask for the company's website URL (e.g., "acme.com"). This is used for auto-branding:
+- Fetch the company logo via `getLogoUrl(domain)` from `app/src/lib/branding.ts`
+- The logo URL will be stored in the Organization record's `logoUrl` field
+- If the user doesn't have a website, skip — the initial-based fallback works fine
+
+Also ask for the contact's email address and use `getAvatarUrl(email, contactName)` to auto-populate the contact avatar.
+
+**Important**: If setup detects that Showpane is already configured (config file exists, database is connected, org exists), acknowledge it and skip to the next step: "Showpane is already configured. Skipping setup."
+
+If setup fails at any point (database not reachable, app not found), stop the onboard flow and provide clear instructions: "Setup needs to be completed before we can continue. Fix the issue above and run /portal onboard again."
+
+After successful setup, transition:
+
+"Setup complete! Your Showpane instance is configured. Let's create your first portal."
+
+### Granola MCP Integration
+
+After setup, check if Granola MCP tools are available by attempting to call `list_meetings`. 
+
+If available:
+- Show: "I found your Granola meetings. Want to use a recent call as the source for your first portal?"
+- List recent meetings with date + title
+- If selected, use the transcript to pre-populate portal content
+
+If not available:
+- Skip silently. Do not mention Granola or show an error.
+
+### Step 3: Run the create flow
+
+Read the instructions from `skills/portal-create/SKILL.md` and execute the create flow inline. This creates the portal page files and database record.
+
+During onboarding, provide a bit more guidance than the standalone create skill would:
+
+- Suggest a slug if the user is unsure: "Pick a short name for the portal URL, like your client's company name in lowercase. For example: 'acme' or 'whzan'."
+- If the user has Granola MCP connected, offer to pull a recent meeting as the source material. If not, prompt for a brief description of the client and what the portal should contain.
+- Use the sales-followup template as the default suggestion for first-time users: "We'll use the sales follow-up template as a starting point. You can customize everything after."
+
+After successful creation, transition:
+
+"Great! Portal '<slug>' created for <company>. Now let's set up credentials so your client can log in."
+
+If creation fails (e.g., slug already taken), help the user pick a different slug and retry. Do not abort the entire onboard flow for a recoverable error.
+
+### Step 4: Run the credentials flow
+
+Read the instructions from `skills/portal-credentials/SKILL.md` and execute the credentials flow inline. This creates a username and password for the portal.
+
+During onboarding, the credentials flow is straightforward -- generate initial credentials. There is no rotation to handle on first run.
+
+After credentials are generated, display them clearly:
+
+"Credentials created. Save these -- they are shown once:
+
+  Username: <username>
+  Password: <password>
+
+You'll share these with your client (or use /portal share to generate a link instead)."
+
+Transition to the final step:
+
+"Almost done! Let's open your portal in the browser."
+
+### Step 5: Run the preview flow
+
+Read the instructions from `skills/portal-preview/SKILL.md` and execute the preview flow inline. This opens the portal in the user's default browser.
+
+During onboarding, add a note about what the user will see:
+
+"Opening your portal now. You'll see a login page. Use the credentials above to log in, or just review the page to make sure everything looks right."
+
+If no dev server is running, start one: "The dev server isn't running. Let me start it for you." Then run the dev server startup (from `/portal dev` instructions) and wait for it to be ready before opening the browser.
+
+After the browser opens, transition to the final summary.
+
+### Step 6: Final summary
+
+Display the completion summary in an ASCII box:
+
+```
+════════════════════════════════════════
+  Showpane is ready!
+  
+  Portal: <slug> (<company>)
+  URL: http://localhost:3000/client/<slug>
+  Username: <username>
+  
+  Next: /portal deploy to go live
+  Help: /portal list, /portal status
+════════════════════════════════════════
+```
+
+Note: Do NOT include the password in the final summary. It was shown once during Step 4. The summary is a reference card the user might screenshot or scroll back to, so it should not contain the password.
+
+After the summary, provide a brief "what's next" orientation:
+
+"Your portal is live locally. Here's what you can do next:
+
+- `/portal deploy` -- push to production so your client can access it
+- `/portal share <slug>` -- generate a share link (no login needed)
+- `/portal update <slug>` -- edit the portal content
+- `/portal analytics <slug>` -- track client engagement
+- `/portal status` -- see a dashboard of all your portals"
+
+## Flow Control
+
+This skill is a sequential orchestrator. Each step depends on the previous one:
+
+```
+setup -> create -> credentials -> preview -> summary
+```
+
+Rules:
+- **Never skip a step.** Even if the user says "I already have credentials", verify by checking the database. If credentials exist, acknowledge and move on. But do not skip the check.
+- **Stop on hard failures.** If setup cannot connect to the database, or create fails due to a missing dependency, stop and explain. Do not try to continue with a broken foundation.
+- **Retry on soft failures.** If the user picks a slug that is taken, help them pick another. If the dev server takes a moment to start, wait. These are not reasons to abort.
+- **Respect existing state.** If the user already has a configured Showpane, an existing portal, and credentials, acknowledge each one and skip to the next incomplete step. The onboard flow should work for both brand-new and partially-set-up installations.
+
+## Detecting Existing State
+
+Before each step, check whether it has already been completed:
+
+1. **Setup**: Check if `~/.showpane/config.json` exists and is valid. If yes, skip setup.
+2. **Create**: Check if the org has at least one portal (via `list-portals.ts`). If yes, ask: "You already have portals. Want to create another, or skip to credentials?"
+3. **Credentials**: Check if the selected portal has credentials (from list response `hasCredentials` field). If yes, skip credentials.
+4. **Preview**: Always run. Opening the browser is always useful.
+
+## Conventions
+
+- Use encouraging but not patronizing language. "Great!" and "Let's move on" are fine. "Wow, amazing job!" is too much.
+- Keep transitions between steps to one sentence. Do not recap what just happened -- the user can see it.
+- Use double-line box drawing (`═`) for the final summary box only. Keep step transitions as plain text.
+- If the total onboard time exceeds 10 minutes (e.g., due to long create flow with Granola), do not comment on it. The user is working, not racing.
+- If learnings exist from a previous session, load them silently. The onboard flow benefits from prior context without mentioning it.
+
+## Error Handling
+
+- If the preamble itself fails (no config), this is expected for first-run. In this specific case, do NOT abort. Instead, proceed directly to the setup step: "Looks like Showpane isn't configured yet. Let's fix that."
+- If any bin/ script returns a non-zero exit, read the error from stderr, display it, and suggest a fix.
+- If the user wants to bail out mid-flow, respect it: "No problem. You can pick up where you left off by running the individual skills: /portal setup, /portal create, /portal credentials, /portal preview."
+
+## Special Case: Preamble Failure
+
+Unlike other skills, `/portal onboard` should NOT hard-fail if the preamble reports "Showpane not configured." The entire point of this skill is to handle first-run. If the config file does not exist, catch the preamble error and proceed to Step 2 (setup) which will create the config.
+
+To handle this: Run the preamble, capture the output. If it includes "not configured", note that setup is needed and continue. Do not exit.
+
+## Completion
+
+As a final step, log skill completion:
+
+```bash
+echo '{"skill":"portal-onboard","event":"completed","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> "$HOME/.showpane/timeline.jsonl" 2>/dev/null
+```
+
+## Related Skills
+
+This skill chains the following skills inline (read their SKILL.md files for detailed instructions):
+- `/portal setup` -- Step 2
+- `/portal create` -- Step 3
+- `/portal credentials` -- Step 4
+- `/portal preview` -- Step 5
+- `/portal dev` -- called within Step 5 if needed
+- `/portal deploy` -- suggested as next step in the summary

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

@@ -0,0 +1,257 @@
+---
+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 (run first)
+
+Before doing anything else, execute this block in a Bash tool call:
+
+```bash
+CONFIG="$HOME/.showpane/config.json"
+if [ ! -f "$CONFIG" ]; then
+  echo "Showpane not configured. Run /portal setup first."
+  exit 1
+fi
+APP_PATH=$(cat "$CONFIG" | python3 -c "import sys,json; print(json.loads(sys.stdin.read()).get('app_path',''))" 2>/dev/null)
+DEPLOY_MODE=$(cat "$CONFIG" | python3 -c "import sys,json; print(json.loads(sys.stdin.read()).get('deploy_mode','docker'))" 2>/dev/null)
+ORG_SLUG=$(cat "$CONFIG" | python3 -c "import sys,json; d=json.loads(sys.stdin.read()); print(d.get('orgSlug','') or d.get('org_slug',''))" 2>/dev/null)
+APP_PATH="${SHOWPANE_APP_PATH:-$APP_PATH}"
+if [ -f "$APP_PATH/.env" ]; then set -a && source "$APP_PATH/.env" && set +a; fi
+DATABASE_URL="${DATABASE_URL:-}"
+if [ ! -d "$APP_PATH/node_modules/.prisma" ]; then
+  echo "App dependencies not installed. Run: cd $APP_PATH && npm install"
+  exit 1
+fi
+SKILL_DIR="${SHOWPANE_TOOLCHAIN_DIR:-$HOME/.showpane/current}"
+SKILL_VERSION=$(cat "$SKILL_DIR/VERSION" 2>/dev/null || echo "unknown")
+echo "SHOWPANE: v$SKILL_VERSION | MODE: $DEPLOY_MODE | APP: $APP_PATH"
+LEARN_FILE="$HOME/.showpane/learnings.jsonl"
+[ -f "$LEARN_FILE" ] && echo "LEARNINGS: $(wc -l < "$LEARN_FILE" | tr -d ' ') loaded" || echo "LEARNINGS: 0"
+
+# 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/,$//')
+  [ -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"
+  if [ "$_LEARN_COUNT" -gt 0 ] 2>/dev/null; then
+    echo "RECENT_LEARNINGS:"
+    tail -5 "$LEARN_FILE" 2>/dev/null
+  fi
+fi
+
+# Track skill execution
+SHOWPANE_TIMELINE="$HOME/.showpane/timeline.jsonl"
+mkdir -p "$(dirname "$SHOWPANE_TIMELINE")"
+echo '{"skill":"portal-preview","event":"started","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> "$SHOWPANE_TIMELINE" 2>/dev/null
+```
+
+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-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
+
+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.
+
+## 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 the deployment mode and whether a local dev server is running, 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: Docker deploy mode (check port 8080)**
+
+If `DEPLOY_MODE` is `docker`, check if the container is running:
+
+```bash
+lsof -i :8080 -sTCP:LISTEN -t >/dev/null 2>&1 && echo "DOCKER_RUNNING=true" || echo "DOCKER_RUNNING=false"
+```
+
+If running, the URL is:
+```
+http://localhost:8080/client/<slug>
+```
+
+**Option C: 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 production/staging URLs, custom domains, and any other deployment 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>. Or generate a share link with /portal share <slug> to bypass login."
+
+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. **Docker on port 8080** -- used when deploy_mode is docker and the container is running.
+3. **NEXT_PUBLIC_APP_URL** -- used for production or staging environments, or when no local server is detected.
+4. **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."
+
+## 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 is running a production build (docker mode), they may need to rebuild first.
+
+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 (hot reload) or rebuild with /portal deploy for docker mode."
+
+## 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
+
+As a final step, log skill completion:
+
+```bash
+echo '{"skill":"portal-preview","event":"completed","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> "$HOME/.showpane/timeline.jsonl" 2>/dev/null
+```
+
+## Related Skills
+
+- `/portal dev` -- start the local development server
+- `/portal share` -- generate a link that works for anyone, not just the local machine
+- `/portal deploy` -- deploy to production so the portal is accessible externally
+- `/portal credentials` -- get or rotate login credentials for the portal