showpane 0.4.13 → 0.4.15

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

@@ -1,46 +1,50 @@
 ---
 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)
+  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 (run first)
 
-Before doing anything else, execute this block in a Bash tool call:
+Before doing anything else, execute this block in a Bash tool call.
+
+This preamble is intentionally tolerant of first-run state. It must not fail just because `~/.showpane/config.json` does not exist yet.
 
 ```bash
-CONFIG="$HOME/.showpane/config.json"
-if [ ! -f "$CONFIG" ]; then
-  echo "Showpane not configured. Run /portal setup first."
-  exit 1
+SHOWPANE_HOME="$HOME/.showpane"
+SHOWPANE_BIN="$SHOWPANE_HOME/bin"
+CONFIG="$SHOWPANE_HOME/config.json"
+APP_PATH=""
+DEPLOY_MODE="local"
+ORG_SLUG=""
+CONFIG_PRESENT=false
+
+if [ -f "$CONFIG" ]; then
+  CONFIG_PRESENT=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','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)
 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_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_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"
-[ -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)
-  [ -n "$_RECENT" ] && echo "RECENT_SKILLS: $_RECENT"
-fi
-
-# Search relevant learnings
-LEARN_FILE="$HOME/.showpane/learnings.jsonl"
+CHECKPOINT="$SHOWPANE_HOME/checkpoints/portal-onboard.json"
+_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 "$LEARN_FILE" ]; then
   _LEARN_COUNT=$(wc -l < "$LEARN_FILE" 2>/dev/null | tr -d ' ')
   echo "LEARNINGS: $_LEARN_COUNT entries"
@@ -49,229 +53,394 @@ if [ -f "$LEARN_FILE" ]; then
     tail -5 "$LEARN_FILE" 2>/dev/null
   fi
 fi
+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
+
+if [ -n "$APP_PATH" ] && [ -f "$APP_PATH/.env" ]; then
+  set -a && source "$APP_PATH/.env" && set +a
+fi
 
-# Track skill execution
-SHOWPANE_TIMELINE="$HOME/.showpane/timeline.jsonl"
+SHOWPANE_TIMELINE="$SHOWPANE_HOME/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
+echo "SHOWPANE: v$SKILL_VERSION | MODE: $DEPLOY_MODE"
+echo "CONFIG_PRESENT: $CONFIG_PRESENT"
+echo "APP_PATH: ${APP_PATH:-missing}"
+echo "ORG_SLUG: ${ORG_SLUG:-missing}"
+echo "TELEMETRY: $TEL"
+echo "TEL_PROMPTED: $TEL_PROMPTED"
+if [ -f "$CHECKPOINT" ]; then
+  echo "CHECKPOINT_PRESENT: true"
+  echo "CHECKPOINT_DATA:"
+  cat "$CHECKPOINT"
+else
+  echo "CHECKPOINT_PRESENT: false"
+fi
+```
+
+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. Apply them where relevant but do not mention them unless they materially affect the current task.
 
-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.
+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
 
-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.
+`/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:
 
-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.
+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
 
-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.
+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.
 
-## Steps
+## Interaction Style
 
-### Step 1: Welcome message
+For decisions that materially change the flow, use recommendation-first language.
+The pattern should look like this:
 
-Start with a welcome that sets expectations. First, display the ASCII welcome banner:
+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 — Client Portal Generator     ║
+ ║  SHOWPANE — First Portal Wizard         ║
  ╚══════════════════════════════════════════╝
 ```
 
-Then continue with:
+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.
 
-"Welcome to Showpane! Let's set up your first client portal. This will take about 5 minutes and we'll go through four steps:
+If config exists, verify only the minimum first-run requirements before continuing:
 
-1. Configure Showpane (app path, database, organization)
-2. Create your first portal
-3. Set up login credentials
-4. Open it in your browser
+- app path exists
+- dependencies exist or can be installed
+- local SQLite schema is ready
+- org exists or can be created
 
-Let's get started."
+Keep this phase minimal.
 
-This framing is important. It tells the user what to expect and roughly how long it will take. Uncertainty causes drop-off.
+If the local checks pass, move straight into the user's portal work without extra system narration.
 
-### Step 2: Run the setup flow
+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.
 
-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.
+Only ask for a missing field, and ask exactly one thing at a time.
 
-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
+Recommended order for missing fields:
 
-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
+1. organization name, if it is not already obvious from the workspace setup
+2. contact email
+3. website/domain
 
-Also ask for the contact's email address and use `getAvatarUrl(email, contactName)` to auto-populate the contact avatar.
+Do not batch these into a numbered questionnaire unless the user explicitly asks
+for the full checklist.
 
-**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."
+Optional extras like brand color, phone number, or contact title belong in
+`/portal-setup` later if needed.
 
-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."
+If setup fails, stop with a concrete recovery step and keep the checkpoint.
 
-After successful setup, transition:
+Save checkpoint with phase `local-ready`.
 
-"Setup complete! Your Showpane instance is configured. Let's create your first portal."
+### Phase 3: Choose the first-portal source
 
-### Granola MCP Integration
+Start with one short source question, not a menu.
 
-After setup, check if Granola MCP tools are available by attempting to call `list_meetings`. 
+Recommended opening:
 
-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
+- "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."
 
-If not available:
-- Skip silently. Do not mention Granola or show an error.
+Only branch after the user answers:
 
-### Step 3: Run the create flow
+- 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
 
-Read the instructions from `skills/portal-create/SKILL.md` and execute the create flow inline. This creates the portal page files and database record.
+Only show the full menu if the user is unsure:
 
-During onboarding, provide a bit more guidance than the standalone create skill would:
+1. recent Granola meeting
+2. pasted transcript
+3. short description of the client + meeting outcome
+4. template-only start
 
-- 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."
+If Granola MCP is unavailable, skip it silently and move on.
 
-After successful creation, transition:
+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.
 
-"Great! Portal '<slug>' created for <company>. Now let's set up credentials so your client can log in."
+Save checkpoint with:
 
-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.
+- `phase: "source-selected"`
+- `sourceType`
+- `template`
 
-### Step 4: Run the credentials flow
+### Phase 4: Create the first draft
 
-Read the instructions from `skills/portal-credentials/SKILL.md` and execute the credentials flow inline. This creates a username and password for the portal.
+Run the `portal-create` flow inline, but frame it as part of the wizard, not as
+a separate command.
 
-During onboarding, the credentials flow is straightforward -- generate initial credentials. There is no rotation to handle on first run.
+During this phase:
 
-After credentials are generated, display them clearly:
+- 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
 
-"Credentials created. Save these -- they are shown once:
+If the slug is taken, treat that as a soft retry, not a failure.
 
-  Username: <username>
-  Password: <password>
+Save checkpoint with:
 
-You'll share these with your client (or use /portal share to generate a link instead)."
+- `phase: "draft-created"`
+- `portalSlug`
+- `companyName`
 
-Transition to the final step:
+### Phase 5: Practical refinements
 
-"Almost done! Let's open your portal in the browser."
+Do not ask the user to invent a whole redesign. Ask for one or two high-signal refinements only.
 
-### Step 5: Run the preview flow
+Recommended refinement prompts:
 
-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.
+- `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?`
 
-During onboarding, add a note about what the user will see:
+Apply the requested refinement inline, using the same patterns as `/portal-update`
+without forcing the user to switch skills.
 
-"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 the user is happy with the first draft, move on immediately.
 
-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.
+Save checkpoint with phase `draft-refined`.
 
-After the browser opens, transition to the final summary.
+### Phase 6: Local preview
 
-### Step 6: Final summary
+Run the `portal-preview` flow inline.
 
-Display the completion summary in an ASCII box:
+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:
 
 ```
 ════════════════════════════════════════
-  Showpane is ready!
-  
+  First portal complete
+
   Portal: <slug> (<company>)
-  URL: http://localhost:3000/client/<slug>
-  Username: <username>
-  
-  Next: /portal deploy to go live
-  Help: /portal list, /portal status
+  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
 ════════════════════════════════════════
 ```
 
-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.
+Rules:
 
-After the summary, provide a brief "what's next" orientation:
+- 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
 
-"Your portal is live locally. Here's what you can do next:
+After the final summary, delete the checkpoint:
 
-- `/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"
+```bash
+rm -f "$HOME/.showpane/checkpoints/portal-onboard.json"
+```
 
 ## Flow Control
 
-This skill is a sequential orchestrator. Each step depends on the previous one:
-
-```
-setup -> create -> credentials -> preview -> summary
-```
+This wizard is sequential, but it is state-aware.
 
 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
+- 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
 
-Before each step, check whether it has already been completed:
+## Existing State Checks
 
-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
+Check these before deciding to skip or rerun a phase:
 
-- 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.
+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
 
-## Error Handling
+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.
 
-- 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."
+## Conventions
 
-## Special Case: Preamble Failure
+- 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.
 
-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.
+## Error Handling
 
-To handle this: Run the preamble, capture the output. If it includes "not configured", note that setup is needed and continue. Do not exit.
+- 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
 
-As a final step, log skill completion:
+As a final step, log skill completion and telemetry:
 
 ```bash
 echo '{"skill":"portal-onboard","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-onboard" --duration "$_TEL_DUR" --outcome success --session-id "${_SESSION_ID:-}" 2>/dev/null || true
 ```
-
-## 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