showpane 0.4.13 → 0.4.14

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,46 @@ 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 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`, ask the user once about telemetry and then record the decision:
+
+- anonymous — local analytics plus anonymous remote sync, with no stable device id
+- off — local analytics only, no remote sync
+
+After the user chooses, run:
+```bash
+"$SHOWPANE_BIN/showpane-config" set telemetry <anonymous|off>
+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.
 
 ## Steps
 
@@ -203,18 +229,17 @@ Update the Organization record with `primaryColor` set to the validated hex valu
 
 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 +257,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 +276,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 +307,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,222 @@
+---
+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)
+- Still ask for org name, contact details, and website URL
+- 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.
+
+1. **Organization name** (required) — 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.
+   - 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}}

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

@@ -14,14 +14,17 @@ If the user asks for broader share-link capabilities than Showpane supports, rea
 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."
   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:-}"
@@ -29,20 +32,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"
@@ -52,27 +61,46 @@ 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-share","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 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`, ask the user once about telemetry and then record the decision:
+
+- anonymous — local analytics plus anonymous remote sync, with no stable device id
+- off — local analytics only, no remote sync
+
+After the user chooses, run:
+```bash
+"$SHOWPANE_BIN/showpane-config" set telemetry <anonymous|off>
+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. 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
 
-This skill generates a signed share link that allows a client to access their portal without entering a username and password. The link is useful for initial onboarding, sending to a client after a meeting, or providing access to someone who does not have the portal credentials.
+This skill generates a signed share link that allows someone to access a hosted portal without entering a username and password. Treat it as a hosted convenience after publish, not as the default answer to first-run sharing.
 
 Share links use HMAC-SHA256 signed tokens. The token encodes the portal slug, a share scope, and the current credential version. Share links do not expire automatically. If credentials are rotated after the link is generated, the link becomes invalid automatically -- this is by design.
 
@@ -92,7 +120,7 @@ Run the share link generator:
 cd $APP_PATH && NODE_PATH="$APP_PATH/node_modules" npx tsx --tsconfig $APP_PATH/tsconfig.json $SKILL_DIR/bin/generate-share-link.ts --slug <slug> --org-id <org_id>
 ```
 
-The script reads AUTH_SECRET from the app's `.env` file (sourced by the preamble) and uses the `signShareToken` function from the app's `client-auth.ts` module. It constructs a full URL using NEXT_PUBLIC_APP_URL (also from `.env`).
+The script reads AUTH_SECRET from the app's `.env` file (sourced by the preamble) and uses the `signShareToken` function from the app's `client-auth.ts` module. It constructs a full URL using NEXT_PUBLIC_APP_URL (also from `.env`), so for external sharing the recommended path is: deploy first, then generate the share link.
 
 Expected success response:
 
@@ -127,7 +155,7 @@ Present the link in a clear, copy-friendly ASCII box:
 
 After displaying the link, add this note:
 
-"Send this link to the client. They can access the portal without logging in. The link stays valid until the portal credentials are rotated or the portal is deactivated."
+"This link is meant for the hosted portal. The link stays valid until the portal credentials are rotated or the portal is deactivated."
 
 If the user has previously generated share links (check learnings for patterns), you can skip the explanation and just show the link.
 
@@ -147,7 +175,7 @@ Do NOT log the share URL to learnings or telemetry. The URL contains the signed
 - Always display the full URL, never truncate or abbreviate it. The user needs to copy-paste it.
 - Make it clear that the link does not expire automatically and is revoked by credential rotation or portal deactivation.
 - Use double-line box drawing (`═`) for the border around the link.
-- If NEXT_PUBLIC_APP_URL is `http://localhost:3000`, warn the user: "This is a local development URL. The client won't be able to access it remotely. Deploy the app with /portal deploy, then generate the share link again."
+- If NEXT_PUBLIC_APP_URL is `http://localhost:3000`, warn the user immediately: "This is a local development URL. Do not send this to a client. Publish with /portal deploy first, then generate the share link again."
 
 ## Error Handling
 
@@ -186,11 +214,11 @@ The signature is computed using AUTH_SECRET from the app's `.env`. If AUTH_SECRE
 
 Common patterns for using share links in practice:
 
-**After a meeting**: Create the portal with `/portal create`, set up credentials with `/portal credentials`, then immediately generate a share link. Send the link in the follow-up email. The client can access the portal instantly without needing to remember a password.
+**After publish**: Deploy the portal with `/portal deploy`, then generate a share link if you want a direct hosted access URL instead of asking the client to log in with credentials.
 
 **For quick reviews**: If a colleague or stakeholder needs to see the portal but should not have permanent credentials, a share link is ideal. It can be reused and does not create a full operator login.
 
-**Re-sharing after content update**: If you update portal content with `/portal update` and want the client to see the changes, generate a fresh share link and send it. This is often easier than asking them to log in again.
+**Re-sharing after content update**: If you update portal content with `/portal update`, publish the latest version if needed, then generate a fresh share link and send it.
 
 ## Learnings Integration
 
@@ -220,14 +248,11 @@ If the user wants to revoke all outstanding share links immediately, the mechani
 
 ## Completion
 
-As a final step, log skill completion:
+As a final step, log skill completion and telemetry:
 
 ```bash
 echo '{"skill":"portal-share","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-share" --duration "$_TEL_DUR" --outcome success --session-id "${_SESSION_ID:-}" 2>/dev/null || true
 ```
-
-## Related Skills
-
-- `/portal credentials` -- set up or rotate credentials (required before sharing)
-- `/portal preview` -- open the portal locally to verify content before sharing
-- `/portal analytics` -- check engagement after sharing to see if the client accessed the portal