showpane 0.4.1 → 0.4.2

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

@@ -0,0 +1,263 @@
+---
+name: portal-analytics
+description: |
+  View portal engagement analytics in the terminal. Use when asked to "show analytics",
+  "portal stats", "how is the portal doing", "engagement", or "view counts". (showpane)
+allowed-tools: [Bash, Read, 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-analytics","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 queries the analytics backend for a specific portal or all portals in the organization and presents engagement data as a formatted ASCII dashboard in the terminal. It uses the `query-analytics.ts` bin script which reads event data from the database via Prisma.
+
+Analytics give the portal owner a quick read on whether clients are actually engaging with the content. Low views or stale activity flags portals that need attention -- a nudge to follow up, refresh content, or check that credentials are still working.
+
+## Steps
+
+### Step 1: Determine the target portal
+
+Check whether the user specified a portal slug:
+
+- If a slug was provided (e.g., "show analytics for whzan"), use that slug directly.
+- If no slug was provided, the skill will query analytics for ALL portals in the organization. Let the user know you are pulling org-wide analytics.
+
+Capture the slug (if any) and the ORG_SLUG from the preamble output for the next step.
+
+### Step 2: Query the analytics data
+
+Run the analytics query script. For a specific portal:
+
+```bash
+cd $APP_PATH && NODE_PATH="$APP_PATH/node_modules" npx tsx --tsconfig $APP_PATH/tsconfig.json $SKILL_DIR/bin/query-analytics.ts --slug <slug> --org-id <org_id>
+```
+
+For all portals (omit the `--slug` flag):
+
+```bash
+cd $APP_PATH && NODE_PATH="$APP_PATH/node_modules" npx tsx --tsconfig $APP_PATH/tsconfig.json $SKILL_DIR/bin/query-analytics.ts --org-id <org_id>
+```
+
+The script returns JSON on stdout. Expected shape for a single portal:
+
+```json
+{
+  "ok": true,
+  "portal": {
+    "slug": "whzan",
+    "companyName": "Whzan Digital Health",
+    "views": 45,
+    "tabSwitches": 123,
+    "lastActivity": "2026-04-07T10:30:00Z",
+    "mostViewedTab": "Services overview",
+    "previousPeriodViews": 33
+  }
+}
+```
+
+For all portals, the response includes a `portals` array with the same fields per entry plus an `orgSummary` object.
+
+If the script exits with a non-zero code, read stderr for the error JSON. Common errors:
+
+- `portal_not_found`: The slug does not exist in this organization. Suggest running `/portal list` to see available portals.
+- `no_analytics_data`: The portal exists but has zero recorded events. This is normal for brand-new portals.
+
+### Step 3: Format the output as an ASCII table
+
+Present the data in a clean, scannable terminal format. For a single portal:
+
+```
+Portal: whzan (Whzan Digital Health)
+Period: Last 30 days
+════════════════════════════════════════
+  Views:        45
+  Tab switches: 123
+  Last activity: 2026-04-07 10:30
+  Most viewed tab: "Services overview"
+════════════════════════════════════════
+```
+
+For multiple portals, use a summary table:
+
+```
+ANALYTICS (Demo Company) — Last 30 days
+════════════════════════════════════════════════════════════
+  Slug        Company              Views   Tab Switches  Last Activity
+  ─────────── ──────────────────── ─────── ───────────── ──────────────
+  whzan       Whzan Digital Health 45      123           7 Apr 10:30
+  acme        Acme Corp            12      34            5 Apr 14:22
+  example     Example Portal       0       0             Never
+════════════════════════════════════════════════════════════
+  Total views: 57 | Active portals: 2/3
+```
+
+### Step 4: Show trends when previous period data is available
+
+If the analytics response includes `previousPeriodViews` (or equivalent previous-period fields), calculate and display the delta:
+
+```
+  Views:        45 (+12 vs previous 30d)
+```
+
+Use a `+` prefix for increases and `-` for decreases. If the previous period had zero views and the current has some, show it as `(new activity)` rather than a percentage.
+
+For the multi-portal table, append a trend column:
+
+```
+  Slug        Views   Trend
+  ─────────── ─────── ──────────
+  whzan       45      +12 (+36%)
+  acme        12      -3 (-20%)
+  example     0       --
+```
+
+### Step 5: Provide actionable commentary
+
+After the table, add a brief note if any portals need attention:
+
+- **Zero views in 30 days**: "Portal 'example' has had no views. Consider checking credentials or sending a reminder to the client."
+- **Declining trend**: "Portal 'acme' views dropped 20%. The client may need a content refresh or follow-up call."
+- **Strong engagement**: "Portal 'whzan' is your most active portal. Good engagement."
+
+Keep commentary to 1-2 sentences maximum. Do not over-explain. The numbers speak for themselves.
+
+## Conventions
+
+- Always format dates as `DD Mon YYYY` or `DD Mon HH:MM` for recency (e.g., "7 Apr 10:30").
+- Use double-line box drawing (`═`) for outer borders and single-line (`─`) for internal dividers.
+- Right-align numeric columns in multi-portal tables for scannability.
+- If the user asks for a specific time period (e.g., "last 7 days"), pass `--period 7d` to the script if supported. Default is 30 days.
+- Never expose raw JSON to the user. Always format as the ASCII table described above.
+- If learnings indicate the user prefers a specific portal or checks analytics frequently, mention the most relevant portal first.
+
+## Analytics Events
+
+The analytics system tracks the following event types. Understanding what is tracked helps interpret the numbers:
+
+- **page_view**: Recorded when a client loads the portal page. One view per page load, not per session. If a client refreshes the page, that counts as a second view.
+- **tab_switch**: Recorded when a client clicks a different tab within the portal. This is the best engagement signal -- it means the client is actively exploring content, not just landing on the page and leaving.
+- **file_download**: Recorded when a client downloads a document from the Documents tab. This indicates high-intent engagement.
+- **share_link_access**: Recorded when someone accesses the portal via a share link rather than username/password login.
+
+When reading the analytics output, tab switches relative to views gives you a rough engagement depth. A portal with 10 views and 30 tab switches means clients are exploring (3 tabs per visit on average). A portal with 10 views and 2 tab switches means clients are landing and leaving.
+
+## Time Periods
+
+The default analytics period is 30 days. The script supports the following periods via the `--period` flag:
+
+- `7d` -- last 7 days (useful for checking recent activity after sharing a portal)
+- `30d` -- last 30 days (default, good general-purpose view)
+- `90d` -- last 90 days (useful for long-running client relationships)
+- `all` -- all time (useful for seeing total engagement since portal creation)
+
+When the user asks for a custom period, map their language to the closest supported option:
+- "this week" or "recent" -> `7d`
+- "this month" -> `30d`
+- "this quarter" -> `90d`
+- "total" or "all time" or "since we started" -> `all`
+
+## Interpreting Zero Activity
+
+A portal with zero views is not necessarily a problem. Context matters:
+
+- **New portal (created in last 7 days)**: Zero views is expected if credentials have not been shared yet. Note: "Portal was created recently. Share credentials with the client to start tracking engagement."
+- **Portal with credentials but no views**: The client may not have received the credentials, or the email landed in spam. Suggest: "Credentials exist but no one has logged in. Consider resending or generating a share link."
+- **Portal that previously had views but now has zero**: The client relationship may have gone cold. This is the most actionable signal -- suggest a follow-up.
+- **Portal with credentials and share link but no views**: The client may not have used the link yet, or it may have been buried in email. Suggest resending the share link with `/portal share`.
+
+## Telemetry
+
+If telemetry is enabled, the analytics skill records a minimal event after each query. The telemetry payload does not include any analytics data (view counts, portal slugs, or company names). It only records that the skill was invoked and how long the query took:
+
+```json
+{"skill":"portal-analytics","ts":"2026-04-07T12:00:00Z","duration_s":2,"outcome":"success"}
+```
+
+## Error Handling
+
+- If the preamble fails (no config, no Prisma), stop and show the error. Do not attempt to query analytics.
+- If `query-analytics.ts` returns a non-zero exit code, display the error message from stderr and suggest a fix.
+- If DATABASE_URL is empty, tell the user: "No database configured. Run /portal setup to connect your database."
+- If the analytics query times out (large dataset), suggest narrowing the period: "Query took too long. Try a shorter period: /portal analytics whzan --period 7d"
+
+## Learnings Integration
+
+After displaying analytics, check the learnings file for patterns that add context:
+
+- If a learning records when credentials were last shared for this portal, note the time gap: "Credentials were shared 3 days ago. Give the client a few more days before following up."
+- If a learning records that the user prefers weekly analytics checks, tailor the output to highlight week-over-week changes rather than 30-day totals.
+- Do not write new learnings from this skill. Analytics is a read-only operation.
+
+## Completion
+
+As a final step, log skill completion:
+
+```bash
+echo '{"skill":"portal-analytics","event":"completed","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> "$HOME/.showpane/timeline.jsonl" 2>/dev/null
+```
+
+## Related Skills
+
+- `/portal status` -- broader health dashboard with scoring (uses analytics as one input)
+- `/portal list` -- see all portals without analytics data
+- `/portal share` -- generate a share link for a portal with strong engagement

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

@@ -0,0 +1,341 @@
+---
+name: portal-create
+description: |
+  Scaffold a new client portal from a meeting transcript, template, or description.
+  Trigger phrases: "create a portal", "new portal", "set up a client page", "make a portal for". (showpane)
+allowed-tools: [Bash, Read, Write, Edit, Glob, Grep]
+---
+
+If the user asks for unsupported hosted behavior, risky upload types, or cloud-specific
+capabilities, read `skills/shared/platform-constraints.md` and apply the relevant limits.
+
+## Preamble (run first)
+
+```bash
+# Read config
+CONFIG="$HOME/.showpane/config.json"
+if [ ! -f "$CONFIG" ]; then
+  echo "Showpane not configured. Run /portal setup first."
+  exit 1
+fi
+APP_PATH=$(python3 -c "import json; d=json.load(open('$CONFIG')); print(d.get('app_path',''))" 2>/dev/null)
+DEPLOY_MODE=$(python3 -c "import json; d=json.load(open('$CONFIG')); print(d.get('deploy_mode','docker'))" 2>/dev/null)
+ORG_SLUG=$(python3 -c "import json; d=json.load(open('$CONFIG')); 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-create","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.
+
+## Steps
+
+### Step 1: Determine the portal slug
+
+If the user provided a slug (e.g., `/portal create acme-health`), use it. Otherwise, infer from context — the company name mentioned in conversation, a meeting transcript, or ask the user directly.
+
+Validate the slug by running:
+
+```bash
+cd "$APP_PATH" && NODE_PATH="$APP_PATH/node_modules" npx tsx --tsconfig "$APP_PATH/tsconfig.json" "$SKILL_DIR/bin/check-slug.ts" --slug <slug> --org-id <org_id>
+```
+
+The script returns `{"valid":true}` or `{"valid":false,"reason":"...","message":"..."}`. If invalid:
+- `reason: "format"` — slug must be lowercase alphanumeric + hyphens, 2-50 chars, no leading/trailing hyphens
+- `reason: "reserved"` — reserved names: api, client, s, admin, static, _next, health, example
+- `reason: "taken"` — a portal with this slug already exists for this org
+
+If invalid, explain the issue and ask for a different slug.
+
+Also ask for the client's website domain (e.g., "acme-health.com"). This is optional but enables auto-branding:
+- If provided, the client logo will be fetched via `getLogoUrl(domain)` and stored in `ClientPortal.logoUrl`
+- If not provided, an initial-based logo is generated via `getInitialLogo(companyName)` and stored as a data URI
+
+### Step 2: Granola MCP integration (optional)
+
+Try to use the Granola MCP `list_meetings` tool to fetch recent meetings. This is a convenience, not a requirement.
+
+**If Granola MCP is available:**
+1. Call `list_meetings` to get recent meetings
+2. Present the list to the user: date, title, participants
+3. Ask which meeting to use (or "none — I'll describe the portal manually")
+4. If a meeting is selected, call `get_meeting_transcript` to retrieve the full transcript
+5. Store the transcript for content analysis in Step 4
+
+**If Granola MCP is NOT available** (tool-not-found error):
+- Skip gracefully. Do not mention Granola or show an error.
+- Ask: "Do you have a meeting transcript to paste, or shall I work from a description?"
+- If the user pastes a transcript, store it for analysis
+- If no transcript, proceed to template selection with manual content
+
+Never fail or block because Granola is unavailable. It is purely additive.
+
+### Step 3: Template selection
+
+Ask which template to use as a starting point:
+
+1. **sales-followup** — Meeting notes, next steps, documents. Best after a sales call.
+2. **consulting** — Project overview, deliverables, timeline. Best for ongoing engagements.
+3. **onboarding** — Welcome, setup steps, resources. Best for new client onboarding.
+4. **blank** — Start from scratch with just an overview tab.
+
+Read the chosen template file from `$SKILL_DIR/templates/` for structural inspiration:
+
+```bash
+cat "$SKILL_DIR/templates/sales-followup/sales-followup-client.tsx"
+```
+
+Always also read the example portal as your quality and style reference:
+
+```bash
+cat "$APP_PATH/src/app/(portal)/client/example/example-client.tsx"
+```
+
+The template provides content structure. The example provides quality and styling. Match the example's patterns: card styles, typography, spacing, responsive breakpoints. Templates are inspiration, not rigid scaffolds. Adapt the structure to fit the actual content.
+
+### Step 4: Analyze transcript (if available)
+
+If a transcript was provided (from Granola or pasted), analyze it to extract:
+
+| Signal Found | Tab to Generate | Content Pattern |
+|---|---|---|
+| Meeting discussion topics | "Meetings" | Collapsible `<details>` sections per meeting with bullet points |
+| Action items, next steps, follow-ups | "Next Steps" | Numbered timeline with status indicators (done/pending) |
+| Documents mentioned (contracts, NDAs, proposals) | "Documents" | Download cards with file type icons from lucide-react |
+| Service descriptions, capabilities discussed | "Services" | Grid of cards with title and description |
+| Pricing, costs, tiers discussed | "Pricing" | Comparison table or tier cards |
+| Project phases, milestones | "Timeline" | Vertical timeline with phase markers |
+
+Always generate at minimum:
+- An **overview/welcome tab** (first tab, always)
+- At least **one additional tab** based on content
+
+If the transcript is rich, generate up to 5-6 tabs. Do not exceed 6 tabs total.
+
+Extract from the transcript:
+- **Company name** and contact details (for PortalShell props)
+- **Key discussion points** (for meeting notes)
+- **Agreed actions** (for next steps timeline)
+- **Mentioned documents** (for documents tab)
+- **Services or products discussed** (for services/overview content)
+
+### Step 5: Generate the portal files
+
+Create two files in `$APP_PATH/src/app/(portal)/client/<slug>/`:
+
+#### File 1: `page.tsx` (server component)
+
+```tsx
+import { <SlugName>PortalClient } from "./<slug>-client";
+
+export const metadata = {
+  title: "<Company Name> | Portal",
+};
+
+export default function <SlugName>Portal() {
+  return <<SlugName>PortalClient />;
+}
+```
+
+Convert the slug to PascalCase for the component name (e.g., `acme-health` becomes `AcmeHealth`).
+
+#### File 2: `<slug>-client.tsx` (client component)
+
+This is the main file. Follow these conventions exactly:
+
+**Imports:**
+```tsx
+"use client";
+
+import { type ReactNode } from "react";
+import { /* icons from lucide-react */ } from "lucide-react";
+import { cn } from "@/lib/utils";
+import { PortalShell } from "@/components/portal-shell";
+```
+
+**Structure:**
+- Define each tab's content as a separate function component within the file (e.g., `function OverviewTab()`, `function DocumentsTab()`)
+- Export a single named component: `export function <SlugName>PortalClient()`
+- The exported component returns `<PortalShell>` with all required props
+
+**PortalShell props (all required):**
+- `companyName` — the org's company name (from config/DB)
+- `companyLogo` — a `<span>` with the first letter of the company name, white text
+- `clientName` — the client's company name (from transcript or user input)
+- `clientLogoSrc` — if client domain was provided: use `getLogoUrl(domain)` from `app/src/lib/branding.ts`. If not: use `getInitialLogo(clientName)` to generate an SVG data URI. Store the chosen URL in the ClientPortal record's `logoUrl` field
+- `clientLogoAlt` — the client company name
+- `lastUpdated` — today's date formatted as "7 April 2026"
+- `contact` — object with `name`, `title`, `avatarSrc`, `email` (from org config)
+- `tabs` — array of tab objects with `id`, `label`, `icon`, `content`, and optional `badge`
+- `hideFooterOnTab` — set to `"overview"` (hides the contact footer on the first tab since it typically has contact info inline)
+
+**Styling conventions (match the example portal exactly):**
+- Cards: `rounded-2xl border bg-white shadow-sm`
+- Card padding: `p-5 sm:p-6`
+- Section headings: `text-base font-bold tracking-tight text-gray-900`
+- Body text: `text-sm leading-relaxed text-gray-600`
+- Small text: `text-xs text-gray-500`
+- Bullet points: use `<span>` dots with `h-1.5 w-1.5 rounded-full` for bullet markers
+- Status badges: `rounded-full px-2 py-0.5 text-[11px] font-medium` with color variants
+- Buttons: `rounded-lg bg-gray-900 px-5 py-2 text-xs font-semibold text-white`
+- Grid layouts: `grid gap-3 sm:grid-cols-2` for card grids
+- Spacing between sections: `mt-6` with `mb-4` for section headings
+- Responsive: mobile-first, use `sm:` breakpoints for wider layouts
+
+**Icon usage:**
+Import only the icons you need from `lucide-react`. Common choices:
+- `Presentation` for overview/services
+- `CalendarDays` for meetings
+- `FileText` for documents
+- `BarChart3` for analytics/strategy
+- `ListChecks` for next steps
+- `Download` for download buttons
+- `ChevronDown` for collapsible sections
+- `Clock` for timeline
+- `DollarSign` for pricing
+
+**For collapsible meeting sections**, use the same `<details>` pattern as the example:
+```tsx
+<details open={defaultOpen} className="group">
+  <summary className="flex cursor-pointer list-none items-center gap-1.5 text-left">
+    <ChevronDown className="h-3.5 w-3.5 shrink-0 text-gray-400 transition-transform group-open:rotate-180" />
+    <h4 className="text-sm font-semibold text-gray-900">{title}</h4>
+  </summary>
+  <div className="mt-2 pl-5">{children}</div>
+</details>
+```
+
+### Step 6: Create database record
+
+Run the create-portal script to register the portal in the database:
+
+```bash
+cd "$APP_PATH" && NODE_PATH="$APP_PATH/node_modules" npx tsx --tsconfig "$APP_PATH/tsconfig.json" "$SKILL_DIR/bin/create-portal.ts" --slug <slug> --company "<client_company_name>" --org-id <org_id>
+```
+
+This creates the `ClientPortal` record with the slug, company name, and links it to the Organization. It does NOT create credentials — that is a separate step via `/portal credentials`.
+
+### Step 7: Self-review
+
+After generating the files, read them back and verify:
+
+1. **PortalShell used?** The client component must use `<PortalShell>` as its root element.
+2. **Minimum 2 tabs?** Check the `tabs` array has at least 2 entries.
+3. **Contact info in props?** The `contact` prop must have `name`, `title`, `avatarSrc`, `email`.
+4. **"use client" directive?** Must be the first line of the client component.
+5. **Imports correct?** `cn` from `@/lib/utils`, `PortalShell` from `@/components/portal-shell`.
+6. **No hardcoded localhost URLs?** Links should be relative or use placeholders.
+7. **Responsive patterns?** Check for `sm:` breakpoints on grids and padding.
+8. **Tab content functions?** Each tab should have its own function, not inline JSX.
+
+If any check fails, fix the issue before proceeding.
+
+### Step 8: Open preview
+
+Check if the dev server is running:
+
+```bash
+lsof -i :3000 -sTCP:LISTEN -t 2>/dev/null
+```
+
+If running, open the portal in the browser:
+
+```bash
+open "http://localhost:3000/client/<slug>"
+```
+
+If not running, suggest:
+
+> "Start the dev server with `/portal dev` to preview your portal at http://localhost:3000/client/<slug>"
+
+### Step 9: Summary and next steps
+
+Print a summary:
+
+```
+Portal created: <slug>
+
+  Client:    <company_name>
+  Tabs:      Overview, Next Steps, Documents (3 tabs)
+  Files:     src/app/(portal)/client/<slug>/page.tsx
+             src/app/(portal)/client/<slug>/<slug>-client.tsx
+
+Next steps:
+  1. Create login credentials: /portal credentials <slug>
+  2. Preview the portal:       /portal preview <slug>
+  3. Edit content:             /portal update <slug>
+  4. Deploy:                   /portal deploy
+```
+
+### Step 10: Record learning
+
+Append a learning about the portal creation for future reference:
+
+```bash
+echo '{"skill":"portal-create","key":"portal-created","insight":"Created portal <slug> for <company>. Template: <template>. Tabs: <tab_list>.","confidence":8,"ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> "$HOME/.showpane/learnings.jsonl"
+```
+
+## Completion
+
+As a final step, log skill completion:
+
+```bash
+echo '{"skill":"portal-create","event":"completed","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> "$HOME/.showpane/timeline.jsonl" 2>/dev/null
+```
+
+## Conventions
+
+- Always use `"use client"` as the first line of the client component
+- Import `PortalShell` from `@/components/portal-shell`
+- Import `cn` from `@/lib/utils`
+- Import icons from `lucide-react`
+- Minimum 2 tabs, maximum 6
+- First tab is always overview/welcome
+- Tab content as separate function components within the file
+- Cards: `rounded-2xl border bg-white shadow-sm`
+- Text: `text-sm` for body, `text-base font-bold` for headings
+- Spacing: consistent `p-5 sm:p-6` for card padding
+- Scope lock: only create files in `$APP_PATH/src/app/(portal)/client/<slug>/`
+- Never modify shared components, other portals, or lib files during portal creation
+- The example portal at `$APP_PATH/src/app/(portal)/client/example/` is the gold standard — when in doubt, match its patterns