showpane 0.4.13 → 0.4.15

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

@@ -0,0 +1,340 @@
+---
+name: portal-onboard
+description: |
+  Canonical first-run wizard for Showpane. Use this for the first portal, for
+  guided onboarding, or any "walk me through it" request. It owns the end-to-end
+  first-run story: local setup, draft creation, preview, access setup, and the
+  hosted publish handoff. (showpane)
+allowed-tools: [Bash, Read, Write, Edit, Glob, Grep]
+---
+
+{{PREAMBLE}}
+
+## Overview
+
+`/portal-onboard` is the canonical first-run workflow. It should feel like one
+coherent wizard, not like the user is manually hopping between separate skills.
+
+The recommended shape is:
+
+1. orient the user
+2. verify local setup
+3. choose the best source for the first draft
+4. create the portal draft
+5. make one or two practical refinements
+6. preview locally
+7. choose how the client will access it
+8. publish to Showpane Cloud
+9. show a compact final summary
+
+Keep the tone direct and calm. Use short phase transitions. Re-ground the user at
+each phase so they always know what is happening next.
+
+## Interaction Style
+
+For decisions that materially change the flow, use recommendation-first language.
+The pattern should look like this:
+
+1. one sentence re-grounding the current phase
+2. one sentence on the recommended choice and why
+3. a short list of concrete options
+
+Example:
+
+`We have local setup ready. Next we need the best source for your first draft.`
+
+`Recommended: use a real transcript if you have one — it gives the strongest first portal on the first pass.`
+
+`Options: recent Granola meeting, pasted transcript, short description, or start from template.`
+
+Do not ask more than one meaningful question at a time unless the answers are tightly coupled.
+
+## Wizard Phases
+
+### Phase 0: Resume or restart
+
+If a checkpoint exists:
+
+- show the saved phase and portal slug if present
+- recommend resume
+- if the user restarts, delete the checkpoint and begin from Phase 1
+
+### Phase 1: Orientation
+
+Start with a compact welcome:
+
+```
+ ╔══════════════════════════════════════════╗
+ ║  SHOWPANE — First Portal Wizard         ║
+ ╚══════════════════════════════════════════╝
+```
+
+Then use one short, friendly paragraph. Keep it concise and informal.
+
+Suggested shape:
+
+- "Let's get your first portal started."
+- "Who's it for, and what's the context? If you've got a call transcript, paste it in and I'll use that too."
+
+Keep the opening focused on the user's first portal. This skill is the first-run default, so the top of the flow should feel fast, calm, and immediately useful.
+
+Immediately save checkpoint:
+
+```bash
+mkdir -p "$HOME/.showpane/checkpoints"
+printf '%s\n' '{"phase":"orientation","startedAt":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' > "$HOME/.showpane/checkpoints/portal-onboard.json"
+```
+
+### Phase 2: Local readiness
+
+If `CONFIG_PRESENT: false`, run the `portal-setup` flow inline.
+
+If config exists, verify only the minimum first-run requirements before continuing:
+
+- app path exists
+- dependencies exist or can be installed
+- local SQLite schema is ready
+- org exists or can be created
+
+Keep this phase minimal.
+
+If the local checks pass, move straight into the user's portal work without extra system narration.
+
+If there is already exactly one local organization and it clearly matches the
+workspace the user just created, treat the org basics as already captured.
+Do not create a separate "company context" phase just to re-ask the same setup
+details.
+
+Only ask for a missing field, and ask exactly one thing at a time.
+
+Recommended order for missing fields:
+
+1. organization name, if it is not already obvious from the workspace setup
+2. contact email
+3. website/domain
+
+Do not batch these into a numbered questionnaire unless the user explicitly asks
+for the full checklist.
+
+Optional extras like brand color, phone number, or contact title belong in
+`/portal-setup` later if needed.
+
+If setup fails, stop with a concrete recovery step and keep the checkpoint.
+
+Save checkpoint with phase `local-ready`.
+
+### Phase 3: Choose the first-portal source
+
+Start with one short source question, not a menu.
+
+Recommended opening:
+
+- "Who's it for, and what's the context? If you've got a call transcript, paste it in and I'll use that too."
+
+Only branch after the user answers:
+
+- if they have a real transcript, ask whether to use Granola or paste it
+- if they do not, ask whether they want to start from notes or a template
+
+Only show the full menu if the user is unsure:
+
+1. recent Granola meeting
+2. pasted transcript
+3. short description of the client + meeting outcome
+4. template-only start
+
+If Granola MCP is unavailable, skip it silently and move on.
+
+If the user only has a rough brief, recommend `sales-followup` as the default
+template for the first portal unless the engagement is clearly onboarding or consulting.
+
+Save checkpoint with:
+
+- `phase: "source-selected"`
+- `sourceType`
+- `template`
+
+### Phase 4: Create the first draft
+
+Run the `portal-create` flow inline, but frame it as part of the wizard, not as
+a separate command.
+
+During this phase:
+
+- suggest a slug if needed
+- prefer a real company/client name in the portal
+- prefer useful structure over completeness
+- aim for a credible first draft, not a perfect final artifact
+
+If the slug is taken, treat that as a soft retry, not a failure.
+
+Save checkpoint with:
+
+- `phase: "draft-created"`
+- `portalSlug`
+- `companyName`
+
+### Phase 5: Practical refinements
+
+Do not ask the user to invent a whole redesign. Ask for one or two high-signal refinements only.
+
+Recommended refinement prompts:
+
+- `Do you want the portal to feel more concise, more sales-focused, or more delivery-focused?`
+- `Should we add anything practical before preview — timeline, documents, or sharper next steps?`
+
+Apply the requested refinement inline, using the same patterns as `/portal-update`
+without forcing the user to switch skills.
+
+If the user is happy with the first draft, move on immediately.
+
+Save checkpoint with phase `draft-refined`.
+
+### Phase 6: Local preview
+
+Run the `portal-preview` flow inline.
+
+If no dev server is running, start it using the `portal-dev` instructions first.
+
+Tell the user exactly what to inspect:
+
+- does the overall story feel right?
+- are next steps clear?
+- are obvious documents or dates missing?
+
+If the user requests a small content fix after preview, make it and preview again.
+Keep this loop tight. Do not let it become an open-ended editing session.
+
+Save checkpoint with phase `previewed`.
+
+### Phase 7: Access setup
+
+Ask how the client should access the hosted portal after publish.
+
+Recommended first-run choice:
+
+- publish first, then choose the hosted access method
+- keep credentials available as the default fallback
+
+Important rule: share links still require portal credentials to exist, because
+share links are tied to credential versioning.
+
+So the flow is:
+
+1. run `portal-credentials` inline
+2. show the credentials once
+3. explain that external sharing starts with `portal-deploy`
+4. if the user wants a direct hosted access link after publish, plan to run `portal-share`
+
+Never write the password into the checkpoint or learnings.
+
+Save checkpoint with phase `access-ready` and `accessMode`.
+
+### Phase 8: Publish to Showpane Cloud
+
+Run the `portal-deploy` flow inline.
+
+This phase is part of onboarding by default. Do not treat publish as an optional
+afterthought unless the user explicitly says they want to stop at local preview.
+
+If cloud auth is missing:
+
+- tell the user to run `showpane login`
+- after login completes, resume from the checkpoint
+
+If deploy returns `organization_required`:
+
+- explain that the user needs to start billing/workspace creation in Showpane Cloud
+- send them to checkout
+- resume after checkout
+
+If deploy returns `organization_not_ready`:
+
+- surface the readiness detail directly
+- distinguish between:
+  - billing inactive
+  - provisioning still running
+  - provisioning unhealthy/failed
+  - workspace incomplete
+- send the user to the relevant settings or checkout action
+- keep the checkpoint so they can resume publish instead of restarting the wizard
+
+If publish succeeds and the user wants a hosted direct-access link, run `portal-share` inline next.
+
+Save checkpoint with phase `published` once the hosted URL is live or clearly accepted for publish.
+
+### Phase 9: Final summary
+
+Show a compact final reference card:
+
+```
+════════════════════════════════════════
+  First portal complete
+
+  Portal: <slug> (<company>)
+  Local:  http://localhost:3000/client/<slug>
+  Cloud:  <hosted-url-or-publishing-status>
+  Access: <hosted login / hosted share link / both>
+
+  Next: /portal-update <slug>
+  Help: /portal-list, /portal-status
+════════════════════════════════════════
+```
+
+Rules:
+
+- never include the password in the final summary
+- include the hosted share URL only if it exists and the user explicitly asked for it after publish
+- if publish is still finalizing, say so plainly instead of pretending it is live
+
+After the final summary, delete the checkpoint:
+
+```bash
+rm -f "$HOME/.showpane/checkpoints/portal-onboard.json"
+```
+
+## Flow Control
+
+This wizard is sequential, but it is state-aware.
+
+Rules:
+
+- verify existing state before redoing work
+- allow resume from any saved phase
+- retry soft failures like slug conflicts or slow dev-server startup
+- stop on hard failures like missing app path, broken schema setup, or cloud deploy errors that require user action
+- keep the user in one coherent workflow instead of telling them to manually switch commands unless recovery requires it
+
+## Existing State Checks
+
+Check these before deciding to skip or rerun a phase:
+
+1. setup/config present
+2. local org exists
+3. portal already exists for the selected slug
+4. credentials already exist
+5. local dev server is running
+6. cloud access token exists
+
+If a portal already exists and clearly looks like the same first-run draft, ask whether
+to continue refining it or create a new portal. Recommend continuing unless the user says otherwise.
+
+## Conventions
+
+- The wizard owns the first-run story. Do not redirect first-time users to freeform prompting unless they explicitly want it.
+- Keep transitions to one sentence whenever possible.
+- Prefer `recommended` over `optional` language when there is a clear best path.
+- Use the cloud dashboard as a supporting surface for billing/provisioning, not as the main first-portal creation surface.
+- If you mention manual prompting at all, position it as the faster repeat-user path.
+
+## Error Handling
+
+- Missing config is not a preamble failure here. It simply means setup starts from scratch.
+- If a step fails after useful progress, keep the checkpoint and tell the user exactly how to resume.
+- If the user wants to stop early, summarize the current state and point them to the next concrete skill:
+  - `/portal-preview`
+  - `/portal-credentials`
+  - `/portal-share`
+  - `/portal-deploy`
+
+{{COMPLETION}}

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

@@ -11,14 +11,17 @@ allowed-tools: [Bash, Read]
 Before doing anything else, execute this block in a Bash tool call:
 
 ```bash
-CONFIG="$HOME/.showpane/config.json"
+SHOWPANE_HOME="$HOME/.showpane"
+SHOWPANE_BIN="$SHOWPANE_HOME/bin"
+CONFIG="$SHOWPANE_HOME/config.json"
 if [ ! -f "$CONFIG" ]; then
-  echo "Showpane not configured. Run /portal setup first."
+  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','local'))" 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_BIN/showpane-config" get app_path 2>/dev/null || python3 -c "import json; d=json.load(open('$CONFIG')); print(d.get('app_path',''))" 2>/dev/null)
+DEPLOY_MODE=$("$SHOWPANE_BIN/showpane-config" get deploy_mode 2>/dev/null || python3 -c "import json; d=json.load(open('$CONFIG')); print(d.get('deploy_mode','local'))" 2>/dev/null || echo "local")
+ORG_SLUG=$("$SHOWPANE_BIN/showpane-config" get orgSlug 2>/dev/null || python3 -c "import json; d=json.load(open('$CONFIG')); print(d.get('orgSlug','') or d.get('org_slug',''))" 2>/dev/null || true)
 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:-}"
@@ -26,20 +29,26 @@ 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_DIR="${SHOWPANE_TOOLCHAIN_DIR:-$SHOWPANE_HOME/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"
+_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"
 [ -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/,$//' || true)
+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"
@@ -49,23 +58,39 @@ 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-preview","event":"started","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> "$SHOWPANE_TIMELINE" 2>/dev/null
+echo "SHOWPANE: v$SKILL_VERSION | MODE: $DEPLOY_MODE | APP: $APP_PATH"
+echo "TELEMETRY: $TEL"
+echo "TEL_PROMPTED: $TEL_PROMPTED"
+```
+
+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:
+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. 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 `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 `skills/shared/platform-constraints.md` exists, read it once near the start of the skill and apply only the relevant limits.
 
 ## Overview
 
@@ -81,8 +106,8 @@ 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."
+- 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.
 
@@ -114,7 +139,7 @@ This handles deployed URLs, custom domains, and any other public preview target.
 
 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."
+"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
 
@@ -152,7 +177,7 @@ 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."
+"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.
 
@@ -179,7 +204,7 @@ This order ensures that during development, the user always sees the latest loca
 - **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."
+- **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
 
@@ -191,21 +216,21 @@ This order ensures that during development, the user always sees the latest loca
 
 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.
+- **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."
+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.
+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."
+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."
+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:
 
@@ -229,15 +254,11 @@ No portal slug or URL is included in telemetry. The event only records that a pr
 
 ## Completion
 
-As a final step, log skill completion:
+As a final step, log skill completion and telemetry:
 
 ```bash
 echo '{"skill":"portal-preview","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-preview" --duration "$_TEL_DUR" --outcome success --session-id "${_SESSION_ID:-}" 2>/dev/null || true
 ```
-
-## 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