@superdesign/cli 0.1.5 → 0.1.7

package/README.md

@@ -0,0 +1,264 @@
+SuperDesign helps you (1) find design inspirations/styles and (2) generate/iterate design drafts on an infinite canvas.
+
+---
+
+# Core scenarios (what this skill handles)
+
+1. **Help me design X** (feature/page/flow)
+2. **Set design system**
+3. **Help me improve design of X**
+
+# Quickstart
+
+Install CLI
+
+```
+npm install -g @superdesign/cli@latest
+```
+
+Install skills for any coding agent
+
+```
+npx skills add superdesigndev/superdesign-skill
+```
+
+Prompt in any agent
+
+```
+/superdesign help me design X
+```
+
+--
+
+## Tooling overview
+
+### A) Inspiration & Style Tools (generic, always available)
+
+Use these to discover style direction, references, and brand context:
+
+- **Search prompt library** (style/components/pages)
+
+  ```bash
+  superdesign search-prompts --keyword "<keyword>" --json
+  superdesign search-prompts --tags "style" --json
+  superdesign search-prompts --tags "style" --keyword "<style keyword>" --json
+  ```
+
+- **Get full prompt details**
+
+  ```bash
+  superdesign get-prompts --slugs "<slug1,slug2,...>" --json
+  ```
+
+- **Extract brand guide from a URL**
+  ```bash
+  superdesign extract-brand-guide --url https://example.com --json
+  ```
+
+### B) Canvas Design Tools
+
+Use design agent to generate high quality design drafts:
+
+- Create project (supports prompt / prompt file / HTML)
+- Create design draft
+- Iterate design draft (replace / branch)
+- Plan flow pages → execute flow pages
+- Fetch specific design draft
+
+---
+
+## Overall SOP for designing features on top of existing app:
+
+1. Investigate existing UI, workflow
+2. Setup design system file if not exist yet
+3. Requirements gathering: use askQuestion tool to clarify requirements with users (Optionally use Inspiration tool to find inspiration when needed)
+4. Ask user whether ready to design in superdesign OR implement UI directly
+5. If yes to superdesign
+   5.1 Create/update a pixel perfect html replica of current UI of page that we will design on top of in `.superdesign/replica_html_template/<name>.html` (html should only contain & reflect how UI look now, the actual design should be handled by superdesign agent)
+   5.2 Create project with this replica html + design system guide
+   5.3 Start desigining by iterating & branching design draft based on designDraft ID returned from project
+
+## Always-on rules
+
+- Design system should live at: `.superdesign/design-system.md`
+- If `.superdesign/design-system.md` is missing, run **Design System Setup** first.
+- Use `askQuestion` to ask high-signal questions (constraints, taste, tradeoffs).
+- Always use `--json` for machine parsing.
+
+---
+
+## replica_html_template rules (Canvas only)
+
+The purpose of replica html template is creating a lightweight version of existing UI so design agent can iterate on top of it (Since superdesign doesn't have access to your codebase directly, this is important context)
+
+Overall process for designing features on top of existing app:
+
+1. Identify & understand existing UI of page related
+2. Create/update a pixel perfect replica html in `.superdesign/replica_html_template/<name>.html` (Only replicate how UI look now, do NOT design)
+
+- If design task is redesign profile page, then replicate current profile page UI pixel perfectly
+- If design task is add new button to side panel, identify which page side panel is using, then replicate that page UI pixel perfectly
+
+**replica_html_template = BEFORE state (what exists now).** It provides context for SuperDesign agent.
+Actual design will be done via superdesign agent, by passing the prompt
+
+The replica_html_template must contain **ONLY UI that currently exists in the codebase**.
+
+- **DO NOT** design or improve anything in the replica_html_template
+- **DO NOT** add placeholder sections like `<!-- NEW FEATURE - DESIGN THIS -->`
+- **DO** create pixel-perfect replica of current UI state
+- Save to: `.superdesign/replica_html_template/<name>.html`
+
+### Naming & Reuse
+
+**Naming convention**
+Name replica_html_template for reusability: Use the page route (e.g., `home.html`, `settings-profile.html`, `dashboard.html`)
+This makes it easy to identify if a page_template already exists.
+
+**Before creating a replica_html_template:**
+
+1. Check if `.superdesign/replica_html_template/` already contains a matching file
+2. If exists: reuse it or update to reflect the latest existing UI
+3. If not exists: create the neww file
+
+### Example: Adding a "Book Demo" section to home page
+
+**BAD approach:**
+
+```html
+<!-- replica_html_template includes a sketched Book Demo section -->
+<section class="book-demo">
+  <!-- DESIGN THIS - Add CTA here -->
+  <h3>Book a Demo</h3>
+  <button>Schedule</button>
+</section>
+```
+
+**GOOD approach:**
+
+```html
+<!-- replica_html_template is pure replica of existing home page (hero + projects) -->
+```
+
+Then in the iterate command:
+1/ create project passing this replica html
+2/ create design draft based on design draft id
+
+---
+
+# 1) Design System Setup
+
+### Step 0 — Ask user (one question)
+
+"Do you want to **create a new design system** or **extract from the current codebase**?"
+
+### A) Extract from codebase
+
+1. Investigate codebase:
+   - Product context: what is being built, target users, core value proposition, key user journeys and page structure
+   - design tokens, typography, colors, spacing, radius, shadows
+   - motion/animation patterns
+   - example components usage + implementation patterns
+2. Write standalone design system to:
+   - `.superdesign/design-system.md`
+   - Must be implementable without the codebase
+
+### B) Create a new design system (to improve current UI)
+
+1. Investigate codebase to understand:
+   - Product context: what is being built, target users, core value proposition, key user journeys and page structure
+   - needed pages/components
+2. Gather inspirations (generic tools):
+   - `superdesign search-prompts --tags "style" --json`
+   - `superdesign get-prompts --slugs ... --json`
+   - optional: `superdesign extract-brand-guide --url ... --json`
+3. Interview user (`askQuestion`) to choose direction
+4. Write:
+   - `.superdesign/design-system.md` (product context + UX flows + visual design, adapted to references)
+
+---
+
+# 2) Designing X (feature/page/flow)
+
+### Example workflow - Add feature to existing page
+
+1. Investigate existing design and Ask targeted questions (`askQuestion`) about requirements + taste
+2. After clarifying, Ask user whether ready to design in superdesign OR implement UI directly
+3. If design in superdesign
+   3.1 Ensure `.superdesign/design-system.md` exists (setup if missing)
+   3.2 Identify page most relevant, and build a pixel-perfect replica in replica_html_template:
+   - `.superdesign/replica_html_template/<page>-<feature>.html`
+     3.3 Create project with replica_html_template (returns `draftId`):
+   ```bash
+   superdesign create-project \
+     --title "<feature>" \
+     --html-file .superdesign/replica_html_template/<file>.html \
+     --set-project-prompt-file .superdesign/design-system.md \
+     --json
+   ```
+   → Note: `draftId` in response is the baseline draft
+   3.4 Branch designs from baseline (use `draftId` from step 3.3)
+   ```bash
+   superdesign iterate-design-draft \
+     --draft-id <draftId> \
+     -p "Dark theme with neon accents" \
+     -p "Minimal with more whitespace" \
+     -p "Bold gradients and shadows" \
+     --mode branch \
+     --json
+   ```
+   3.5 Share design title & preview URL → collect feedback → iterate
+
+### Advanced usage
+
+#### Design multiple page OR a full user journey
+
+Execute:
+
+```bash
+superdesign execute-flow-pages \
+  --draft-id <draftId> \
+  --source-node-id <nodeId> \
+  --pages '[{"title":"Signup","prompt":"..."},{"title":"Payment","prompt":"..."}]' \
+  --json
+```
+
+#### Get HTML reference from a draft
+
+```bash
+superdesign get-design --draft-id <draftId> --output ./design.html
+```
+
+---
+
+## Quick reference (key commands)
+
+```bash
+# Inspirations
+superdesign search-prompts --keyword "<keyword>" --json
+superdesign search-prompts --tags "style" --json
+superdesign get-prompts --slugs "<slug1,slug2>" --json
+superdesign extract-brand-guide --url https://example.com --json
+
+# Canvas - Create project
+# Options: -s/--set-project-prompt (inline), --set-project-prompt-file (from file)
+superdesign create-project --title "X" --set-project-prompt "..." --json
+superdesign create-project --title "X" --set-project-prompt-file .superdesign/design-system.md --json
+superdesign create-project --title "X" --html-file ./index.html --set-project-prompt-file .superdesign/design-system.md --json
+
+# Iterate: replace mode (single variation, updates in place)
+superdesign iterate-design-draft --draft-id <id> -p "..." --mode replace --json
+
+# Iterate: Explore multiple versions & variations (each prompt = one variation, prompt should be just directional, do not specify color, style, let superdesign design expert fill in details, you just give direction)
+superdesign iterate-design-draft --draft-id <id> -p "dark theme" -p "minimal" -p "bold" --mode branch --json
+
+# Iterate: Auto explore (only give exploration direction, and let Superdesign fill in details, e.g. explore different styles; Default do not use this)
+superdesign iterate-design-draft --draft-id <id> -p "..." --mode branch --count 3 --json
+
+# Fetch & get designs
+superdesign fetch-design-nodes --project-id <id> --json
+superdesign get-design --draft-id <id> --json
+
+# Create new design from scracth without any reference - ONLY use this for creating brand new design, default NEVER use this
+superdesign create-design-draft --project-id <id> --title "X" -p "..." --json
+```

package/dist/config/constants.d.ts

@@ -12,7 +12,10 @@ export declare const POLL_TIMEOUT_MS: number;
 export declare const AUTH_POLL_INTERVAL_MS = 2000;
 export declare const AUTH_POLL_TIMEOUT_MS: number;
 /** CLI version - should match package.json */
-export declare const CLI_VERSION = "0.1.5";
+export declare const CLI_VERSION = "0.1.7";
+/** PostHog analytics configuration */
+export declare const POSTHOG_KEY: string;
+export declare const POSTHOG_HOST: string;
 /** Config directory name */
 export declare const CONFIG_DIR_NAME = ".superdesign";
 /** Config file name */

package/dist/index.cjs

@@ -91,8 +91,8 @@ var __webpack_exports__ = {};
     const external_url_namespaceObject = require("url");
     const external_path_namespaceObject = require("path");
     const external_commander_namespaceObject = require("commander");
-    const external_fs_namespaceObject = require("fs");
-    const external_os_namespaceObject = require("os");
+    const POSTHOG_KEY = process.env.POSTHOG_KEY || 'phc_oUcDklFBX3wy8eksSyEC0pataKCgSadur1sio5hBHg4';
+    const POSTHOG_HOST = process.env.POSTHOG_HOST || 'https://eu.i.posthog.com';
     const CONFIG_DIR_NAME = '.superdesign';
     const CONFIG_FILE_NAME = 'config.json';
     const EXIT_CODES = {
@@ -106,6 +106,9 @@ var __webpack_exports__ = {};
     };
     const SKILLS_DIR = '.claude/skills/superdesign';
     const SKILL_FILE_NAME = 'SKILL.md';
+    const external_fs_namespaceObject = require("fs");
+    const external_os_namespaceObject = require("os");
+    var external_os_default = /*#__PURE__*/ __webpack_require__.n(external_os_namespaceObject);
     function getConfigDir() {
         return external_path_namespaceObject.join(external_os_namespaceObject.homedir(), CONFIG_DIR_NAME);
     }
@@ -313,7 +316,7 @@ var __webpack_exports__ = {};
         try {
             startSpinner('Creating auth session...');
             const session = await createSession({
-                cliVersion: "0.1.5",
+                cliVersion: "0.1.7",
                 os: `${external_os_namespaceObject.platform()} ${external_os_namespaceObject.release()}`,
                 hostname: external_os_namespaceObject.hostname()
             });
@@ -512,269 +515,35 @@ var __webpack_exports__ = {};
         return `---
 name: superdesign
 description: Superdesign is a design agent, where it specialised in frontend UI/UX design; Use this skill before you implement any UI that require some design thinking
+metadata:
+  author: superdesign
+  version: "0.0.1"
 ---
 
-SuperDesign helps you (1) find design inspirations/styles and (2) optionally generate/iterate design drafts on an infinite canvas.
-
-Each SuperDesign canvas run creates a new node and returns a \`previewUrl\`.
+SuperDesign helps you (1) find design inspirations/styles and (2) generate/iterate design drafts on an infinite canvas.
 
 ---
 
-## Core scenarios (what this skill handles)
+# Core scenarios (what this skill handles)
 
 1. **Help me design X** (feature/page/flow)
 2. **Set design system**
 3. **Help me improve design of X**
 
----
-
-## Tooling overview
-
-### A) Inspiration & Style Tools (generic, always available)
-Use these to discover style direction, references, and brand context:
-
-- **Search prompt library** (style/components/pages)
-  \`\`\`bash
-  superdesign search-prompts --keyword "<keyword>" --json
-  superdesign search-prompts --tags "style" --json
-  superdesign search-prompts --tags "style" --keyword "<style keyword>" --json
-  \`\`\`
-
-- **Get full prompt details**
-  \`\`\`bash
-  superdesign get-prompts --slugs "<slug1,slug2,...>" --json
-  \`\`\`
-
-- **Extract brand guide from a URL**
-  \`\`\`bash
-  superdesign extract-brand-guide --url https://example.com --json
-  \`\`\`
-
-### B) Canvas Design Tools (specialised, optional)
-
-Use these when you want to explore multiple directions and show previews:
-
-- Create project (supports prompt / prompt file / HTML)
-- Create design draft
-- Iterate design draft (replace / branch)
-- Plan flow pages → execute flow pages
-- Fetch nodes, export HTML
-
-> Pixel-perfect HTML playground is ONLY required for Canvas workflows.
-
----
-
-## Always-on rules
-
-- Design system should live at: \`.superdesign/design-system.md\`
-- If \`.superdesign/design-system.md\` is missing, run **Design System Setup** first.
-- Use \`askQuestion\` to ask high-signal questions (constraints, taste, tradeoffs).
-- For Canvas workflows: build a simplified/pixel-perfect prototype HTML in:
-  - \`.superdesign/playgrounds/<name>.html\`
-- Always use \`--json\` for machine parsing.
-
----
-
-## Playground rules (Canvas only)
-
-**Playground = BEFORE state (what exists now).** It provides context for SuperDesign agent.
-**Prompt = DESIRED CHANGE (what to add/modify).**
-
-The playground HTML must contain **ONLY UI that currently exists in the codebase**. For NEW features/sections, describe them entirely in the \`--prompt\` flag — do NOT add wireframes, placeholders, or sketches to the playground HTML.
-
-- **DO NOT** design or improve anything in the playground
-- **DO NOT** add placeholder sections like \`<!-- NEW FEATURE - DESIGN THIS -->\`
-- **DO** create pixel-perfect replica of current UI state
-- Valid formats:
-  - **Component-only**: isolated component with enough markup to show core UX/states
-  - **Full page**: replica of page where component operates (shows surrounding context)
-- Save to: \`.superdesign/playgrounds/<name>.html\`
-
-### Example: Adding a "Book Demo" section to home page
-
-**BAD approach:**
-\`\`\`html
-<!-- playground includes a sketched Book Demo section -->
-<section class="book-demo">
-  <!-- DESIGN THIS - Add CTA here -->
-  <h3>Book a Demo</h3>
-  <button>Schedule</button>
-</section>
-\`\`\`
-
-**GOOD approach:**
-\`\`\`html
-<!-- playground is pure replica of existing home page (hero + projects) -->
-<!-- NO book demo section in HTML -->
-\`\`\`
-Then in the iterate command:
-\`\`\`bash
---prompt "Add a Book Demo section between the hero and projects sections. Requirements: minimal card style, horizontal layout..."
-\`\`\`
-
----
-
-# 1) Design System Setup
-
-### Step 0 — Ask user (one question)
-
-"Do you want to **create a new design system** or **extract from the current codebase**?"
-
-### A) Extract from codebase
-
-1. Investigate codebase:
-   - design tokens, typography, colors, spacing, radius, shadows
-   - motion/animation patterns
-   - example components usage + implementation patterns
-   - core product functions + key pages
-2. Write standalone design system to:
-   - \`.superdesign/design-system.md\`
-   - Must be implementable without the codebase
-
-### B) Create a new design system (to improve current UI)
-
-1. Investigate codebase to understand product + needed pages/components
-2. Gather inspirations (generic tools):
-   - \`superdesign search-prompts --tags "style" --json\`
-   - \`superdesign get-prompts --slugs ... --json\`
-   - optional: \`superdesign extract-brand-guide --url ... --json\`
-3. Interview user (\`askQuestion\`) to choose direction
-4. Write:
-   - \`.superdesign/design-system.md\` (adapted to product + references)
-
----
-
-# 2) Designing X (feature/page/flow)
-
-## A) If user wants references / direction only (no canvas)
-
-1. Ensure \`.superdesign/design-system.md\` exists (setup if missing)
-2. Use inspiration tools to collect references:
-   - search prompts (style + component/page)
-   - get prompts (full details)
-   - extract brand guide if relevant
-3. Provide a concrete design spec:
-   - layout + hierarchy
-   - component set + states
-   - token guidance (typography/color/spacing/radius/motion)
-   - interaction notes + edge cases
-
-## B) If user wants visual exploration (canvas optional)
-
-Use canvas when direction is uncertain or multiple options are needed.
-
-### Canvas workflow — Add feature to existing page
-
-1. Ensure \`.superdesign/design-system.md\` exists (setup if missing)
-2. Build prototype HTML playground (simplified + pixel-perfect enough):
-   - \`.superdesign/playgrounds/<page>-<feature>.html\`
-3. Ask targeted questions (\`askQuestion\`) about requirements + taste
-4. Create project with playground HTML (returns \`draftId\`):
-   \`\`\`bash
-   superdesign create-project \\
-     --title "<feature>" \\
-     --html-file .superdesign/playgrounds/<file>.html \\
-     --prompt-file .superdesign/design-system.md \\
-     --json
-   \`\`\`
-   → Note: \`draftId\` in response is the baseline draft
-5. Branch designs from baseline (use \`draftId\` from step 4):
-   \`\`\`bash
-   superdesign iterate-design-draft \\
-     --draft-id <draftId> \\
-     --prompt "<design requirements>" \\
-     --mode branch \\
-     --count 3 \\
-     --json
-   \`\`\`
-6. Share \`previewUrl\` → collect feedback → iterate
-
-### Canvas workflow — Add new page
-
-Same as above, but playground should include shared UI shell:
-- nav, layout container, spacing rhythm, shared components
-
-### Canvas workflow — Improve current UI
-
-1. Investigate product + current UI states
-2. Ensure design system exists
-3. Propose improvement options:
-   - big restructure
-   - style uplift
-   - low-hanging polish
-4. Pick one → build playground → create project (prompt-file design system) → branch drafts
-5. Share \`previewUrl\` → iterate
-
-### When to use create-design-draft
-
-Only use \`create-design-draft\` when creating from scratch (no HTML baseline).
-
-**Required in prompt:**
-- Full page structure (header, sidebar, main content areas)
-- Component environment/surroundings
-- Layout context (what's above/below/beside)
-
-\`\`\`bash
-superdesign create-design-draft \\
-  --project-id <id> \\
-  --title "Feature X" \\
-  --prompt "Page has: fixed header 64px, left sidebar 240px, main content area. Design a settings panel in the main content area with..." \\
-  --device desktop \\
-  --json
+# How it works
+Fetch fresh guidelines below:
 \`\`\`
-
----
-
-# Advanced usage
-
-### Plan + generate a full user journey
-
-Plan:
-\`\`\`bash
-superdesign plan-flow-pages \\
-  --draft-id <draftId> \\
-  --source-node-id <nodeId> \\
-  --context "<flow context>" \\
-  --json
+https://raw.githubusercontent.com/superdesigndev/superdesign-skill/main/skills/superdesign/SUPERDESIGN.md
 \`\`\`
 
-Execute:
-\`\`\`bash
-superdesign execute-flow-pages \\
-  --draft-id <draftId> \\
-  --source-node-id <nodeId> \\
-  --pages '[{"title":"Signup","prompt":"..."},{"title":"Payment","prompt":"..."}]' \\
-  --json
-\`\`\`
+Action accordingly based on instruction in the guidelines
 
-### Get HTML reference from a draft
+# Superdesign CLI
 
-\`\`\`bash
-superdesign get-design --draft-id <draftId> --output ./design.html
 \`\`\`
-
----
-
-## Quick reference (key commands)
-
-\`\`\`bash
-# Inspirations
-superdesign search-prompts --keyword "<keyword>" --json
-superdesign search-prompts --tags "style" --json
-superdesign get-prompts --slugs "<slug1,slug2>" --json
-superdesign extract-brand-guide --url https://example.com --json
-
-# Canvas
-superdesign create-project --title "X" --prompt "..." --json
-superdesign create-project --title "X" --prompt-file .superdesign/design-system.md --json
-superdesign create-project --title "X" --html-file ./index.html --prompt-file .superdesign/design-system.md --json
-
-superdesign create-design-draft --project-id <id> --title "X" --prompt "..." --device desktop --json
-superdesign iterate-design-draft --draft-id <id> --prompt "..." --mode replace --json
-superdesign iterate-design-draft --draft-id <id> --prompt "..." --mode branch --count 3 --json
-
-superdesign fetch-design-nodes --project-id <id> --json
-superdesign get-design --draft-id <id> --json
+npm install -g @superdesign/cli@latest
+superdesign login
+superdesign --help
 \`\`\`
 `;
     }
@@ -882,56 +651,45 @@ superdesign get-design --draft-id <id> --json
     }
     async function runJob(config) {
         const { startLabel, pollingLabel, successLabel, timeoutLabel, failureLabel, timeoutMs = 300000, startJob, transformResult, displayResult } = config;
-        try {
-            startSpinner(startLabel);
-            const job = await startJob();
-            updateSpinner(pollingLabel);
-            const pollResult = await poll(()=>getJobStatus(job.jobId), isJobDone, {
-                intervalMs: 2000,
-                timeoutMs,
-                onPoll: (attempt)=>{
-                    if (attempt % 5 === 0) updateSpinner(`${pollingLabel} (${Math.floor(2000 * attempt / 1000)}s)`);
-                }
-            });
-            if (pollResult.timedOut) {
-                failSpinner(timeoutLabel);
-                output_error('Job timed out. The operation may still be processing in the background.');
-                if (isJsonMode()) output({
-                    error: 'timeout',
-                    jobId: job.jobId
-                });
-                process.exit(EXIT_CODES.TIMEOUT);
-            }
-            if (!pollResult.success || !pollResult.data) {
-                failSpinner(failureLabel);
-                output_error(pollResult.error || 'Failed to get job status');
-                process.exit(EXIT_CODES.API_ERROR);
-            }
-            const jobResult = pollResult.data;
-            if (isJobFailed(jobResult)) {
-                failSpinner(failureLabel);
-                output_error(`${jobResult.error.code}: ${jobResult.error.message}`);
-                process.exit(EXIT_CODES.API_ERROR);
-            }
-            if (!isJobCompleted(jobResult)) {
-                failSpinner('Unexpected job status');
-                output_error('Job ended in unexpected state');
-                process.exit(EXIT_CODES.API_ERROR);
+        startSpinner(startLabel);
+        const job = await startJob();
+        updateSpinner(pollingLabel);
+        const pollResult = await poll(()=>getJobStatus(job.jobId), isJobDone, {
+            intervalMs: 2000,
+            timeoutMs,
+            onPoll: (attempt)=>{
+                if (attempt % 5 === 0) updateSpinner(`${pollingLabel} (${Math.floor(2000 * attempt / 1000)}s)`);
             }
-            succeedSpinner(successLabel);
-            if (isJsonMode()) output(transformResult(jobResult));
-            else displayResult(jobResult);
-            process.exit(EXIT_CODES.SUCCESS);
-        } catch (err) {
+        });
+        if (pollResult.timedOut) {
+            failSpinner(timeoutLabel);
+            if (isJsonMode()) output({
+                error: 'timeout',
+                jobId: job.jobId
+            });
+            else output_error('Job timed out. The operation may still be processing in the background.');
+            throw new ApiClientError('Job timed out', 'timeout');
+        }
+        if (!pollResult.success || !pollResult.data) {
             failSpinner(failureLabel);
-            if (err instanceof ApiClientError) {
-                output_error(`API Error: ${err.message}`);
-                process.exit(EXIT_CODES.API_ERROR);
-            }
-            const message = err instanceof Error ? err.message : 'Unknown error';
-            output_error(message);
-            process.exit(EXIT_CODES.GENERAL_ERROR);
+            const errMsg = pollResult.error || 'Failed to get job status';
+            if (!isJsonMode()) output_error(errMsg);
+            throw new ApiClientError(errMsg, 'api_error');
+        }
+        const jobResult = pollResult.data;
+        if (isJobFailed(jobResult)) {
+            failSpinner(failureLabel);
+            if (!isJsonMode()) output_error(`${jobResult.error.code}: ${jobResult.error.message}`);
+            throw new ApiClientError(jobResult.error.message, jobResult.error.code);
         }
+        if (!isJobCompleted(jobResult)) {
+            failSpinner('Unexpected job status');
+            if (!isJsonMode()) output_error('Job ended in unexpected state');
+            throw new ApiClientError('Job ended in unexpected state', 'unexpected_status');
+        }
+        succeedSpinner(successLabel);
+        if (isJsonMode()) output(transformResult(jobResult));
+        else displayResult(jobResult);
     }
     function job_runner_requireAuth(isAuthenticated) {
         if (!isAuthenticated()) {
@@ -1509,6 +1267,72 @@ superdesign get-design --draft-id <id> --json
         });
         return command;
     }
+    const external_posthog_node_namespaceObject = require("posthog-node");
+    let posthogClient = null;
+    function getPostHog() {
+        if (!posthogClient && POSTHOG_KEY) posthogClient = new external_posthog_node_namespaceObject.PostHog(POSTHOG_KEY, {
+            host: POSTHOG_HOST
+        });
+        return posthogClient;
+    }
+    const SENSITIVE_KEYS = [
+        'token',
+        'key',
+        'secret',
+        'password',
+        'apikey',
+        'auth',
+        'authorization',
+        'credential'
+    ];
+    function sanitizeOptions(options) {
+        const sanitized = {};
+        for (const [key, value] of Object.entries(options)){
+            if ('function' == typeof value || key.startsWith('_')) continue;
+            const lowerKey = key.toLowerCase();
+            if (!SENSITIVE_KEYS.some((sensitive)=>lowerKey.includes(sensitive))) {
+                if ('string' != typeof value || !(value.length > 100)) sanitized[key] = value;
+            }
+        }
+        return sanitized;
+    }
+    async function trackCommand(opts) {
+        const { teamId } = loadConfig();
+        const metadata = {
+            command: opts.command,
+            success: opts.success,
+            durationMs: opts.durationMs,
+            errorCode: opts.errorCode,
+            options: opts.options,
+            cliVersion: "0.1.7",
+            os: `${external_os_default().platform()} ${external_os_default().release()}`
+        };
+        const posthog = getPostHog();
+        if (posthog) {
+            const distinctId = teamId || `anon_${external_os_default().hostname()}`;
+            posthog.capture({
+                distinctId,
+                event: 'cli_command',
+                properties: {
+                    team_id: teamId,
+                    ...metadata
+                }
+            });
+        }
+        if (manager_isAuthenticated() && teamId) try {
+            const client = getApiClient();
+            await client.post('/external/track', {
+                activityType: 'cli_command',
+                metadata
+            });
+        } catch  {}
+    }
+    async function shutdownAnalytics() {
+        if (posthogClient) {
+            await posthogClient.shutdown();
+            posthogClient = null;
+        }
+    }
     const src_filename = (0, external_url_namespaceObject.fileURLToPath)(__rslib_import_meta_url__);
     const src_dirname = (0, external_path_namespaceObject.dirname)(src_filename);
     (0, external_dotenv_namespaceObject.config)({
@@ -1517,7 +1341,20 @@ superdesign get-design --draft-id <id> --json
     (0, external_dotenv_namespaceObject.config)();
     function createProgram() {
         const program = new external_commander_namespaceObject.Command();
-        program.name('superdesign').description('SuperDesign CLI - AI product designer for coding agents').version("0.1.5");
+        program.name('superdesign').description('SuperDesign CLI - AI product designer for coding agents').version("0.1.7");
+        let startTime = 0;
+        program.hook('preAction', ()=>{
+            startTime = Date.now();
+        });
+        program.hook('postAction', async (_thisCommand, actionCommand)=>{
+            await trackCommand({
+                command: actionCommand.name(),
+                success: true,
+                durationMs: Date.now() - startTime,
+                options: sanitizeOptions(actionCommand.opts())
+            });
+            await shutdownAnalytics();
+        });
         program.addCommand(createLoginCommand());
         program.addCommand(createLogoutCommand());
         program.addCommand(createInitCommand());

package/dist/index.js

@@ -3,10 +3,13 @@ import { fileURLToPath } from "url";
 import { dirname, join, resolve as external_path_resolve } from "path";
 import { Command } from "commander";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
-import { homedir, hostname, platform, release } from "os";
+import os, { homedir, hostname, platform, release } from "os";
 import axios from "axios";
 import ora from "ora";
 import { writeFile } from "fs/promises";
+import { PostHog } from "posthog-node";
+const POSTHOG_KEY = process.env.POSTHOG_KEY || 'phc_oUcDklFBX3wy8eksSyEC0pataKCgSadur1sio5hBHg4';
+const POSTHOG_HOST = process.env.POSTHOG_HOST || 'https://eu.i.posthog.com';
 const CONFIG_DIR_NAME = '.superdesign';
 const CONFIG_FILE_NAME = 'config.json';
 const EXIT_CODES = {
@@ -223,7 +226,7 @@ async function runAuthFlow(options = {}) {
     try {
         startSpinner('Creating auth session...');
         const session = await createSession({
-            cliVersion: "0.1.5",
+            cliVersion: "0.1.7",
             os: `${platform()} ${release()}`,
             hostname: hostname()
         });
@@ -422,269 +425,35 @@ function getSkillTemplate() {
     return `---
 name: superdesign
 description: Superdesign is a design agent, where it specialised in frontend UI/UX design; Use this skill before you implement any UI that require some design thinking
+metadata:
+  author: superdesign
+  version: "0.0.1"
 ---
 
-SuperDesign helps you (1) find design inspirations/styles and (2) optionally generate/iterate design drafts on an infinite canvas.
-
-Each SuperDesign canvas run creates a new node and returns a \`previewUrl\`.
+SuperDesign helps you (1) find design inspirations/styles and (2) generate/iterate design drafts on an infinite canvas.
 
 ---
 
-## Core scenarios (what this skill handles)
+# Core scenarios (what this skill handles)
 
 1. **Help me design X** (feature/page/flow)
 2. **Set design system**
 3. **Help me improve design of X**
 
----
-
-## Tooling overview
-
-### A) Inspiration & Style Tools (generic, always available)
-Use these to discover style direction, references, and brand context:
-
-- **Search prompt library** (style/components/pages)
-  \`\`\`bash
-  superdesign search-prompts --keyword "<keyword>" --json
-  superdesign search-prompts --tags "style" --json
-  superdesign search-prompts --tags "style" --keyword "<style keyword>" --json
-  \`\`\`
-
-- **Get full prompt details**
-  \`\`\`bash
-  superdesign get-prompts --slugs "<slug1,slug2,...>" --json
-  \`\`\`
-
-- **Extract brand guide from a URL**
-  \`\`\`bash
-  superdesign extract-brand-guide --url https://example.com --json
-  \`\`\`
-
-### B) Canvas Design Tools (specialised, optional)
-
-Use these when you want to explore multiple directions and show previews:
-
-- Create project (supports prompt / prompt file / HTML)
-- Create design draft
-- Iterate design draft (replace / branch)
-- Plan flow pages → execute flow pages
-- Fetch nodes, export HTML
-
-> Pixel-perfect HTML playground is ONLY required for Canvas workflows.
-
----
-
-## Always-on rules
-
-- Design system should live at: \`.superdesign/design-system.md\`
-- If \`.superdesign/design-system.md\` is missing, run **Design System Setup** first.
-- Use \`askQuestion\` to ask high-signal questions (constraints, taste, tradeoffs).
-- For Canvas workflows: build a simplified/pixel-perfect prototype HTML in:
-  - \`.superdesign/playgrounds/<name>.html\`
-- Always use \`--json\` for machine parsing.
-
----
-
-## Playground rules (Canvas only)
-
-**Playground = BEFORE state (what exists now).** It provides context for SuperDesign agent.
-**Prompt = DESIRED CHANGE (what to add/modify).**
-
-The playground HTML must contain **ONLY UI that currently exists in the codebase**. For NEW features/sections, describe them entirely in the \`--prompt\` flag — do NOT add wireframes, placeholders, or sketches to the playground HTML.
-
-- **DO NOT** design or improve anything in the playground
-- **DO NOT** add placeholder sections like \`<!-- NEW FEATURE - DESIGN THIS -->\`
-- **DO** create pixel-perfect replica of current UI state
-- Valid formats:
-  - **Component-only**: isolated component with enough markup to show core UX/states
-  - **Full page**: replica of page where component operates (shows surrounding context)
-- Save to: \`.superdesign/playgrounds/<name>.html\`
-
-### Example: Adding a "Book Demo" section to home page
-
-**BAD approach:**
-\`\`\`html
-<!-- playground includes a sketched Book Demo section -->
-<section class="book-demo">
-  <!-- DESIGN THIS - Add CTA here -->
-  <h3>Book a Demo</h3>
-  <button>Schedule</button>
-</section>
-\`\`\`
-
-**GOOD approach:**
-\`\`\`html
-<!-- playground is pure replica of existing home page (hero + projects) -->
-<!-- NO book demo section in HTML -->
+# How it works
+Fetch fresh guidelines below:
 \`\`\`
-Then in the iterate command:
-\`\`\`bash
---prompt "Add a Book Demo section between the hero and projects sections. Requirements: minimal card style, horizontal layout..."
-\`\`\`
-
----
-
-# 1) Design System Setup
-
-### Step 0 — Ask user (one question)
-
-"Do you want to **create a new design system** or **extract from the current codebase**?"
-
-### A) Extract from codebase
-
-1. Investigate codebase:
-   - design tokens, typography, colors, spacing, radius, shadows
-   - motion/animation patterns
-   - example components usage + implementation patterns
-   - core product functions + key pages
-2. Write standalone design system to:
-   - \`.superdesign/design-system.md\`
-   - Must be implementable without the codebase
-
-### B) Create a new design system (to improve current UI)
-
-1. Investigate codebase to understand product + needed pages/components
-2. Gather inspirations (generic tools):
-   - \`superdesign search-prompts --tags "style" --json\`
-   - \`superdesign get-prompts --slugs ... --json\`
-   - optional: \`superdesign extract-brand-guide --url ... --json\`
-3. Interview user (\`askQuestion\`) to choose direction
-4. Write:
-   - \`.superdesign/design-system.md\` (adapted to product + references)
-
----
-
-# 2) Designing X (feature/page/flow)
-
-## A) If user wants references / direction only (no canvas)
-
-1. Ensure \`.superdesign/design-system.md\` exists (setup if missing)
-2. Use inspiration tools to collect references:
-   - search prompts (style + component/page)
-   - get prompts (full details)
-   - extract brand guide if relevant
-3. Provide a concrete design spec:
-   - layout + hierarchy
-   - component set + states
-   - token guidance (typography/color/spacing/radius/motion)
-   - interaction notes + edge cases
-
-## B) If user wants visual exploration (canvas optional)
-
-Use canvas when direction is uncertain or multiple options are needed.
-
-### Canvas workflow — Add feature to existing page
-
-1. Ensure \`.superdesign/design-system.md\` exists (setup if missing)
-2. Build prototype HTML playground (simplified + pixel-perfect enough):
-   - \`.superdesign/playgrounds/<page>-<feature>.html\`
-3. Ask targeted questions (\`askQuestion\`) about requirements + taste
-4. Create project with playground HTML (returns \`draftId\`):
-   \`\`\`bash
-   superdesign create-project \\
-     --title "<feature>" \\
-     --html-file .superdesign/playgrounds/<file>.html \\
-     --prompt-file .superdesign/design-system.md \\
-     --json
-   \`\`\`
-   → Note: \`draftId\` in response is the baseline draft
-5. Branch designs from baseline (use \`draftId\` from step 4):
-   \`\`\`bash
-   superdesign iterate-design-draft \\
-     --draft-id <draftId> \\
-     --prompt "<design requirements>" \\
-     --mode branch \\
-     --count 3 \\
-     --json
-   \`\`\`
-6. Share \`previewUrl\` → collect feedback → iterate
-
-### Canvas workflow — Add new page
-
-Same as above, but playground should include shared UI shell:
-- nav, layout container, spacing rhythm, shared components
-
-### Canvas workflow — Improve current UI
-
-1. Investigate product + current UI states
-2. Ensure design system exists
-3. Propose improvement options:
-   - big restructure
-   - style uplift
-   - low-hanging polish
-4. Pick one → build playground → create project (prompt-file design system) → branch drafts
-5. Share \`previewUrl\` → iterate
-
-### When to use create-design-draft
-
-Only use \`create-design-draft\` when creating from scratch (no HTML baseline).
-
-**Required in prompt:**
-- Full page structure (header, sidebar, main content areas)
-- Component environment/surroundings
-- Layout context (what's above/below/beside)
-
-\`\`\`bash
-superdesign create-design-draft \\
-  --project-id <id> \\
-  --title "Feature X" \\
-  --prompt "Page has: fixed header 64px, left sidebar 240px, main content area. Design a settings panel in the main content area with..." \\
-  --device desktop \\
-  --json
-\`\`\`
-
----
-
-# Advanced usage
-
-### Plan + generate a full user journey
-
-Plan:
-\`\`\`bash
-superdesign plan-flow-pages \\
-  --draft-id <draftId> \\
-  --source-node-id <nodeId> \\
-  --context "<flow context>" \\
-  --json
+https://raw.githubusercontent.com/superdesigndev/superdesign-skill/main/skills/superdesign/SUPERDESIGN.md
 \`\`\`
 
-Execute:
-\`\`\`bash
-superdesign execute-flow-pages \\
-  --draft-id <draftId> \\
-  --source-node-id <nodeId> \\
-  --pages '[{"title":"Signup","prompt":"..."},{"title":"Payment","prompt":"..."}]' \\
-  --json
-\`\`\`
+Action accordingly based on instruction in the guidelines
 
-### Get HTML reference from a draft
+# Superdesign CLI
 
-\`\`\`bash
-superdesign get-design --draft-id <draftId> --output ./design.html
 \`\`\`
-
----
-
-## Quick reference (key commands)
-
-\`\`\`bash
-# Inspirations
-superdesign search-prompts --keyword "<keyword>" --json
-superdesign search-prompts --tags "style" --json
-superdesign get-prompts --slugs "<slug1,slug2>" --json
-superdesign extract-brand-guide --url https://example.com --json
-
-# Canvas
-superdesign create-project --title "X" --prompt "..." --json
-superdesign create-project --title "X" --prompt-file .superdesign/design-system.md --json
-superdesign create-project --title "X" --html-file ./index.html --prompt-file .superdesign/design-system.md --json
-
-superdesign create-design-draft --project-id <id> --title "X" --prompt "..." --device desktop --json
-superdesign iterate-design-draft --draft-id <id> --prompt "..." --mode replace --json
-superdesign iterate-design-draft --draft-id <id> --prompt "..." --mode branch --count 3 --json
-
-superdesign fetch-design-nodes --project-id <id> --json
-superdesign get-design --draft-id <id> --json
+npm install -g @superdesign/cli@latest
+superdesign login
+superdesign --help
 \`\`\`
 `;
 }
@@ -792,56 +561,45 @@ function isJobFailed(response) {
 }
 async function runJob(config) {
     const { startLabel, pollingLabel, successLabel, timeoutLabel, failureLabel, timeoutMs = 300000, startJob, transformResult, displayResult } = config;
-    try {
-        startSpinner(startLabel);
-        const job = await startJob();
-        updateSpinner(pollingLabel);
-        const pollResult = await poll(()=>getJobStatus(job.jobId), isJobDone, {
-            intervalMs: 2000,
-            timeoutMs,
-            onPoll: (attempt)=>{
-                if (attempt % 5 === 0) updateSpinner(`${pollingLabel} (${Math.floor(2000 * attempt / 1000)}s)`);
-            }
-        });
-        if (pollResult.timedOut) {
-            failSpinner(timeoutLabel);
-            output_error('Job timed out. The operation may still be processing in the background.');
-            if (isJsonMode()) output({
-                error: 'timeout',
-                jobId: job.jobId
-            });
-            process.exit(EXIT_CODES.TIMEOUT);
-        }
-        if (!pollResult.success || !pollResult.data) {
-            failSpinner(failureLabel);
-            output_error(pollResult.error || 'Failed to get job status');
-            process.exit(EXIT_CODES.API_ERROR);
-        }
-        const jobResult = pollResult.data;
-        if (isJobFailed(jobResult)) {
-            failSpinner(failureLabel);
-            output_error(`${jobResult.error.code}: ${jobResult.error.message}`);
-            process.exit(EXIT_CODES.API_ERROR);
+    startSpinner(startLabel);
+    const job = await startJob();
+    updateSpinner(pollingLabel);
+    const pollResult = await poll(()=>getJobStatus(job.jobId), isJobDone, {
+        intervalMs: 2000,
+        timeoutMs,
+        onPoll: (attempt)=>{
+            if (attempt % 5 === 0) updateSpinner(`${pollingLabel} (${Math.floor(2000 * attempt / 1000)}s)`);
         }
-        if (!isJobCompleted(jobResult)) {
-            failSpinner('Unexpected job status');
-            output_error('Job ended in unexpected state');
-            process.exit(EXIT_CODES.API_ERROR);
-        }
-        succeedSpinner(successLabel);
-        if (isJsonMode()) output(transformResult(jobResult));
-        else displayResult(jobResult);
-        process.exit(EXIT_CODES.SUCCESS);
-    } catch (err) {
+    });
+    if (pollResult.timedOut) {
+        failSpinner(timeoutLabel);
+        if (isJsonMode()) output({
+            error: 'timeout',
+            jobId: job.jobId
+        });
+        else output_error('Job timed out. The operation may still be processing in the background.');
+        throw new ApiClientError('Job timed out', 'timeout');
+    }
+    if (!pollResult.success || !pollResult.data) {
         failSpinner(failureLabel);
-        if (err instanceof ApiClientError) {
-            output_error(`API Error: ${err.message}`);
-            process.exit(EXIT_CODES.API_ERROR);
-        }
-        const message = err instanceof Error ? err.message : 'Unknown error';
-        output_error(message);
-        process.exit(EXIT_CODES.GENERAL_ERROR);
+        const errMsg = pollResult.error || 'Failed to get job status';
+        if (!isJsonMode()) output_error(errMsg);
+        throw new ApiClientError(errMsg, 'api_error');
+    }
+    const jobResult = pollResult.data;
+    if (isJobFailed(jobResult)) {
+        failSpinner(failureLabel);
+        if (!isJsonMode()) output_error(`${jobResult.error.code}: ${jobResult.error.message}`);
+        throw new ApiClientError(jobResult.error.message, jobResult.error.code);
+    }
+    if (!isJobCompleted(jobResult)) {
+        failSpinner('Unexpected job status');
+        if (!isJsonMode()) output_error('Job ended in unexpected state');
+        throw new ApiClientError('Job ended in unexpected state', 'unexpected_status');
     }
+    succeedSpinner(successLabel);
+    if (isJsonMode()) output(transformResult(jobResult));
+    else displayResult(jobResult);
 }
 function job_runner_requireAuth(isAuthenticated) {
     if (!isAuthenticated()) {
@@ -1418,6 +1176,71 @@ function createGetDesignCommand() {
     });
     return command;
 }
+let posthogClient = null;
+function getPostHog() {
+    if (!posthogClient && POSTHOG_KEY) posthogClient = new PostHog(POSTHOG_KEY, {
+        host: POSTHOG_HOST
+    });
+    return posthogClient;
+}
+const SENSITIVE_KEYS = [
+    'token',
+    'key',
+    'secret',
+    'password',
+    'apikey',
+    'auth',
+    'authorization',
+    'credential'
+];
+function sanitizeOptions(options) {
+    const sanitized = {};
+    for (const [key, value] of Object.entries(options)){
+        if ('function' == typeof value || key.startsWith('_')) continue;
+        const lowerKey = key.toLowerCase();
+        if (!SENSITIVE_KEYS.some((sensitive)=>lowerKey.includes(sensitive))) {
+            if ('string' != typeof value || !(value.length > 100)) sanitized[key] = value;
+        }
+    }
+    return sanitized;
+}
+async function trackCommand(opts) {
+    const { teamId } = loadConfig();
+    const metadata = {
+        command: opts.command,
+        success: opts.success,
+        durationMs: opts.durationMs,
+        errorCode: opts.errorCode,
+        options: opts.options,
+        cliVersion: "0.1.7",
+        os: `${os.platform()} ${os.release()}`
+    };
+    const posthog = getPostHog();
+    if (posthog) {
+        const distinctId = teamId || `anon_${os.hostname()}`;
+        posthog.capture({
+            distinctId,
+            event: 'cli_command',
+            properties: {
+                team_id: teamId,
+                ...metadata
+            }
+        });
+    }
+    if (manager_isAuthenticated() && teamId) try {
+        const client = getApiClient();
+        await client.post('/external/track', {
+            activityType: 'cli_command',
+            metadata
+        });
+    } catch  {}
+}
+async function shutdownAnalytics() {
+    if (posthogClient) {
+        await posthogClient.shutdown();
+        posthogClient = null;
+    }
+}
 const src_filename = fileURLToPath(import.meta.url);
 const src_dirname = dirname(src_filename);
 external_dotenv_config({
@@ -1426,7 +1249,20 @@ external_dotenv_config({
 external_dotenv_config();
 function createProgram() {
     const program = new Command();
-    program.name('superdesign').description('SuperDesign CLI - AI product designer for coding agents').version("0.1.5");
+    program.name('superdesign').description('SuperDesign CLI - AI product designer for coding agents').version("0.1.7");
+    let startTime = 0;
+    program.hook('preAction', ()=>{
+        startTime = Date.now();
+    });
+    program.hook('postAction', async (_thisCommand, actionCommand)=>{
+        await trackCommand({
+            command: actionCommand.name(),
+            success: true,
+            durationMs: Date.now() - startTime,
+            options: sanitizeOptions(actionCommand.opts())
+        });
+        await shutdownAnalytics();
+    });
     program.addCommand(createLoginCommand());
     program.addCommand(createLogoutCommand());
     program.addCommand(createInitCommand());

package/dist/utils/analytics.d.ts

@@ -0,0 +1,24 @@
+/**
+ * CLI Analytics - Dual tracking with PostHog (real-time) and Backend (long-term storage)
+ */
+export interface TrackCommandOptions {
+    command: string;
+    success: boolean;
+    durationMs: number;
+    errorCode?: string;
+    options?: Record<string, unknown>;
+}
+/**
+ * Sanitize command options by removing sensitive values, functions, and internal properties
+ */
+export declare function sanitizeOptions(options: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Track a CLI command execution
+ * Sends to both PostHog (real-time dashboards) and backend (long-term storage)
+ */
+export declare function trackCommand(opts: TrackCommandOptions): Promise<void>;
+/**
+ * Shutdown analytics and flush any pending events
+ * Should be called before CLI exits
+ */
+export declare function shutdownAnalytics(): Promise<void>;

package/dist/utils/job-runner.d.ts

@@ -33,8 +33,9 @@ export interface JobRunnerResult<TResult> {
 /**
  * Run a job with polling and standard error handling
  * Handles spinner updates, timeout, failure states, and output formatting
+ * Returns normally on success, throws on failure (to allow postAction hooks to run)
  */
-export declare function runJob<TResult>(config: JobRunnerConfig<TResult>): Promise<never>;
+export declare function runJob<TResult>(config: JobRunnerConfig<TResult>): Promise<void>;
 /**
  * Check authentication and exit with appropriate error if not authenticated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdesign/cli",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "CLI for SuperDesign Platform - agent skills for Claude Code",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -29,7 +29,8 @@
     "commander": "^11.1.0",
     "dotenv": "^16.3.0",
     "open": "^10.0.0",
-    "ora": "^8.0.0"
+    "ora": "^8.0.0",
+    "posthog-node": "^5.24.1"
   },
   "devDependencies": {
     "@rslib/core": "0.15.1",