@shiplens/cli 1.2.7

package/README.md

@@ -0,0 +1,89 @@
+# 🚀 Shiplens CLI (In Development)
+
+> **Fast User Telemetry, Instant SDK Instrumentation & AI Analytics Engine for Modern Web Apps.**
+
+[![npm version](https://img.shields.io/npm/v/@shiplens/cli.svg)](https://www.npmjs.com/package/@shiplens/cli)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Node Version](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen.svg)](package.json)
+[![Status](https://img.shields.io/badge/status-active%20development-orange.svg)]()
+
+---
+
+> [!NOTE]
+> **Active Development Preview**: This package is currently in active development. Features and API endpoints are being iterated rapidly. 50,000 monthly telemetry events are included for free upon registration.
+
+---
+
+## ⚡ Instant Setup (Under 15 Seconds)
+
+Run in the root of any Next.js, Vite, Vue, or HTML project:
+
+```bash
+# Zero-install execution via npx
+npx --yes @shiplens/cli init --json
+```
+
+### What `init` Does Automatically:
+1. **Detects Framework**: Automatically recognizes Next.js (App / Pages router), Vite (React / Svelte), Vue 3, or plain HTML.
+2. **Injects Tracking SDK**: Inserts `@shiplens/sdk` tracking snippets into your entry files without breaking your code layout.
+3. **Connects Cloud Project**: Registers the project, generates a live responsive dashboard URL, and writes local configuration (`.shiplens.json`).
+4. **Installs Dependency**: Adds `@shiplens/sdk` via your project package manager (`npm`, `pnpm`, `yarn`, or `bun`).
+5. **Deploys AI Skills**: Injects `.agents/skills/shiplens/SKILL.md` and Cursor rules (`.cursor/rules/shiplens.mdc`) for seamless LLM Agent integration.
+6. **Performs Git Commit**: Automatically commits all instrumentation changes atomically.
+
+---
+
+## 🧠 Dynamic Overrides & Adaptive Learning
+
+Shiplens introduces an adaptive learning loop for AI Agents:
+
+```text
+[User Prompt] ➔ [Match Preset] ➔ [Apply .shiplens/learnings.md (Priority 1)] ➔ [Execute CLI] ➔ [Update Learnings]
+```
+
+- **Priority 1 (Dynamic Overrides)**: Local `.shiplens/learnings.md` rules always override default CLI parameters (e.g. customized date ranges, funnel goals, or granular filters).
+- **Priority 2 (Deterministic Base)**: Standard 42 scenario-based CLI execution presets in `prompts/cli/prompt_cli_en.md`.
+
+---
+
+## 📊 Core Commands
+
+| Command | Description |
+| :--- | :--- |
+| `npx @shiplens/cli init --json` | 15-second zero-config analytics onboarding |
+| `npx @shiplens/cli doctor --json` | End-to-end diagnostics on SDK, network, and credentials |
+| `npx @shiplens/cli summary --range 7d --json` | Traffic overview: PV, UV, bounce rates, geos, devices |
+| `npx @shiplens/cli query --metric pageviews --json` | Multi-dimensional metrics & funnel queries |
+| `npx @shiplens/cli sql --query "<sql>" --json` | Sandboxed read-only ClickHouse SQL execution |
+| `npx @shiplens/cli pages --range 7d --json` | Page-level visits and average dwell times |
+| `npx @shiplens/cli paths --range 7d --json` | User journeys and Sankey transition paths |
+| `npx @shiplens/cli heatmap --template <id> --json` | Click heatmaps & skeleton wireframe snapshots |
+| `npx @shiplens/cli dashboards create --prompt "..." --json` | AI-driven dashboard generation |
+| `npx @shiplens/cli auth bind --email <email> --json` | Request Magic Link for quota activation & authorization |
+| `npx @shiplens/cli auth configure --client cursor --json` | Auto-configure MCP servers in IDEs |
+
+---
+
+## 🔒 Security & Sandboxing
+
+- **Tenant Isolation**: Strict per-project `app_id` isolation across all telemetry queries.
+- **Read-Only ClickHouse Sandbox**: AST query validator enforces `SELECT`-only operations, mandatory time bounds, and maximum 1000-row limits.
+- **Safe Secrets Handling**: Credential tokens and secrets are automatically masked in all console outputs (`sk_live_...9f2a`).
+
+---
+
+## 📁 Documentation & Prompts
+
+- [CLI Architecture & Roadmap](./docs/01_CLI_ARCHITECTURE_AND_ROADMAP.md)
+- [Complete Command Reference](./docs/02_CLI_COMMAND_REFERENCE.md)
+- [AI Skill & Dynamic Overrides Spec](./docs/03_SKILL_SPEC_AND_PROMPTS.md)
+- [CLI Execution Prompts (42 Scenarios)](./prompts/cli/prompt_cli_en.md)
+- [Web Showcase Prompts (42 Scenarios)](./prompts/web/prompt_web_en.md)
+- [Backend API Specification](./docs/BACKEND_API_SPEC.md)
+- [Project Context Specification](./docs/SHIPLENS_CONTEXT_API_SPEC.md)
+
+---
+
+## 📜 License
+
+Apache-2.0 © Shiplens Team

package/bin/shiplens.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+const { runCLI } = require('../lib/cli');
+
+runCLI(process.argv.slice(2));

package/lib/api.js

@@ -0,0 +1,376 @@
+const http = require('http');
+const https = require('https');
+const { URL } = require('url');
+
+const ERROR_CODES = {
+  UNAUTHENTICATED: 'UNAUTHENTICATED',
+  APP_NOT_FOUND: 'APP_NOT_FOUND',
+  PERMISSION_DENIED: 'PERMISSION_DENIED',
+  RATE_LIMITED: 'RATE_LIMITED',
+  INVALID_SQL: 'INVALID_SQL',
+  PROJECT_EXISTS: 'PROJECT_EXISTS',
+  INJECTION_FAILED: 'INJECTION_FAILED',
+  NETWORK_FAILED: 'NETWORK_FAILED',
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+};
+
+class APIClient {
+  constructor(baseURL = 'http://120.26.230.33', secret = '') {
+    this.baseURL = (baseURL || 'http://120.26.230.33').replace(/\/+$/, '');
+    this.secret = secret;
+  }
+
+  async request(method, path, body = null, reqOptions = {}) {
+    const fullURL = `${this.baseURL}${path}`;
+    const parsed = new URL(fullURL);
+    const isHttps = parsed.protocol === 'https:';
+    const lib = isHttps ? https : http;
+
+    const payload = body ? (typeof body === 'string' ? body : JSON.stringify(body)) : null;
+    const headers = {
+      'Content-Type': 'application/json',
+      'User-Agent': 'Shiplens-CLI/1.2.7 (Node.js)',
+    };
+    if (this.secret) {
+      headers['Authorization'] = `Bearer ${this.secret}`;
+    }
+    if (payload) {
+      headers['Content-Length'] = Buffer.byteLength(payload);
+    }
+
+    const options = {
+      hostname: parsed.hostname,
+      port: parsed.port || (isHttps ? 443 : 80),
+      path: parsed.pathname + parsed.search,
+      method,
+      headers,
+      timeout: reqOptions.timeout || 15000,
+    };
+
+    return new Promise((resolve, reject) => {
+      const req = lib.request(options, (res) => {
+        let resData = '';
+        res.on('data', (chunk) => {
+          resData += chunk;
+        });
+        res.on('end', () => {
+          let json = null;
+          try {
+            json = JSON.parse(resData);
+          } catch (e) {
+            json = null;
+          }
+
+          if (res.statusCode >= 400) {
+            let code = ERROR_CODES.INTERNAL_ERROR;
+            switch (res.statusCode) {
+              case 401: code = ERROR_CODES.UNAUTHENTICATED; break;
+              case 403: code = ERROR_CODES.PERMISSION_DENIED; break;
+              case 404: code = ERROR_CODES.APP_NOT_FOUND; break;
+              case 409: code = ERROR_CODES.PROJECT_EXISTS; break;
+              case 429: code = ERROR_CODES.RATE_LIMITED; break;
+              case 400: case 422: code = ERROR_CODES.INVALID_SQL; break;
+            }
+            const msg = (json && (json.message || json.error || (json.detail && (typeof json.detail === 'string' ? json.detail : JSON.stringify(json.detail))))) || resData || `HTTP ${res.statusCode}`;
+            const err = new Error(msg);
+            err.code = (json && json.code) || code;
+            err.statusCode = res.statusCode;
+            err.status = res.statusCode;
+            err.response = json || resData;
+            err.ok = false;
+            return reject(err);
+          }
+
+          resolve(json !== null ? json : { ok: true });
+        });
+      });
+
+      req.on('error', (err) => {
+        const error = new Error(`Network connection error: ${err.message}`);
+        error.code = ERROR_CODES.NETWORK_FAILED;
+        error.ok = false;
+        reject(error);
+      });
+
+      req.on('timeout', () => {
+        req.destroy();
+        const error = new Error(`Request timed out (${options.timeout}ms)`);
+        error.code = ERROR_CODES.NETWORK_FAILED;
+        error.ok = false;
+        reject(error);
+      });
+
+      if (payload) {
+        req.write(payload);
+      }
+      req.end();
+    });
+  }
+
+  // 15-second connect & project registration (POST /api/connect)
+  async connect(data) {
+    const res = await this.request('POST', '/api/connect', data);
+    if (typeof res === 'object') res.ok = true;
+    return res;
+  }
+
+  // Send Magic Link for email binding (POST /api/auth/email/start)
+  async startEmail(data) {
+    const res = await this.request('POST', '/api/auth/email/start', data);
+    if (typeof res === 'object') res.ok = true;
+    return res;
+  }
+
+  // Check email activation status (GET /api/auth/email-status?token=...)
+  async checkEmailStatus(token) {
+    return this.request('GET', `/api/auth/email-status?token=${encodeURIComponent(token)}`);
+  }
+
+  // Exponential backoff retry for startEmail
+  async startEmailWithRetry(data, retry = 2, baseMs = 500) {
+    let lastErr;
+    for (let i = 0; i <= retry; i++) {
+      try {
+        return await this.startEmail(data);
+      } catch (err) {
+        lastErr = err;
+        if (err.status && err.status >= 400 && err.status < 500) throw err;
+        if (i < retry) {
+          await new Promise((r) => setTimeout(r, baseMs * Math.pow(2, i)));
+        }
+      }
+    }
+    throw lastErr;
+  }
+
+  // List offline Access Secrets (GET /api/auth/api-keys)
+  async listAccessSecrets() {
+    return this.request('GET', '/api/auth/api-keys');
+  }
+
+  // Create offline Access Secret (POST /api/auth/api-keys)
+  async createAccessSecret(data) {
+    return this.request('POST', '/api/auth/api-keys', data);
+  }
+
+  // Revoke offline Access Secret (DELETE /api/auth/api-keys/:keyId)
+  async revokeAccessSecret(apiKeyId) {
+    return this.request('DELETE', `/api/auth/api-keys/${encodeURIComponent(apiKeyId)}`);
+  }
+
+  async me() {
+    const res = await this.request('GET', '/api/me');
+    if (typeof res === 'object') res.ok = true;
+    return res;
+  }
+
+  async listProjects() {
+    const res = await this.request('GET', '/api/apps');
+    if (typeof res === 'object') res.ok = true;
+    return res;
+  }
+
+  async bindProject(appId, projectName = '') {
+    return this.request('POST', '/api/projects/bind', { app_id: appId, project_name: projectName });
+  }
+
+  async updateTaxonomy(appId, data) {
+    const res = await this.request('PUT', `/api/apps/${encodeURIComponent(appId)}/taxonomy`, data);
+    if (typeof res === 'object') res.ok = true;
+    return res;
+  }
+
+  async getTaxonomy(appId) {
+    const res = await this.request('GET', `/api/apps/${encodeURIComponent(appId)}/taxonomy`);
+    if (typeof res === 'object') res.ok = true;
+    return res;
+  }
+
+  async deleteProject(appId) {
+    return this.request('DELETE', `/api/apps/${encodeURIComponent(appId)}`);
+  }
+
+  async queryAnalytics(appId, queryReq) {
+    const actualAppId = typeof appId === 'object' ? appId.app_id : appId;
+    const actualReq = typeof appId === 'object' ? appId : queryReq;
+    const res = await this.request('POST', `/api/ai/apps/${encodeURIComponent(actualAppId)}/analytics/query`, actualReq);
+    if (typeof res === 'object') {
+      res.ok = true;
+      res.app_id = actualAppId;
+    }
+    return res;
+  }
+
+  async query(appId, queryReq) {
+    return this.queryAnalytics(appId, queryReq);
+  }
+
+  // executeSQL (POST /api/mcp/apps/:appId/sql, payload: { sql: queryStr })
+  async executeSQL(appId, queryStr) {
+    const start = Date.now();
+    let actualAppId = appId;
+    let sql = queryStr;
+    if (typeof appId === 'object') {
+      actualAppId = appId.app_id;
+      sql = appId.sql || appId.query;
+    } else if (typeof queryStr === 'object') {
+      sql = queryStr.sql || queryStr.query;
+    }
+    const res = await this.request('POST', `/api/mcp/apps/${encodeURIComponent(actualAppId)}/sql`, { sql });
+    if (typeof res === 'object') {
+      res.ok = true;
+      if (!res.elapsed_ms) res.elapsed_ms = Date.now() - start;
+    }
+    return res;
+  }
+
+  async summary(appId, range = '7d', env = 'production') {
+    const actualAppId = typeof appId === 'object' ? appId.app_id : appId;
+    const actualRange = typeof appId === 'object' ? (appId.range || range) : range;
+    const actualEnv = typeof appId === 'object' ? (appId.env || env) : env;
+    const qs = new URLSearchParams({ range: actualRange, env: actualEnv }).toString();
+    const res = await this.request('GET', `/api/ai/apps/${encodeURIComponent(actualAppId)}/summary?${qs}`);
+    if (typeof res === 'object') res.ok = true;
+    return res;
+  }
+
+  async pages(appId, range = '7d', env = 'production', limit = 10) {
+    const actualAppId = typeof appId === 'object' ? appId.app_id : appId;
+    const actualRange = typeof appId === 'object' ? (appId.range || range) : range;
+    const actualEnv = typeof appId === 'object' ? (appId.env || env) : env;
+    const actualLimit = typeof appId === 'object' ? (appId.limit || limit) : limit;
+    const qs = new URLSearchParams({ range: actualRange, env: actualEnv, limit: String(actualLimit) }).toString();
+    const res = await this.request('GET', `/api/ai/apps/${encodeURIComponent(actualAppId)}/pages?${qs}`);
+    if (typeof res === 'object') res.ok = true;
+    return res;
+  }
+
+  async getPages(data) {
+    return this.pages(data);
+  }
+
+  async paths(appId, range = '7d', env = 'production') {
+    const actualAppId = typeof appId === 'object' ? appId.app_id : appId;
+    const actualRange = typeof appId === 'object' ? (appId.range || range) : range;
+    const actualEnv = typeof appId === 'object' ? (appId.env || env) : env;
+    const qs = new URLSearchParams({ range: actualRange, env: actualEnv }).toString();
+    const res = await this.request('GET', `/api/ai/apps/${encodeURIComponent(actualAppId)}/paths?${qs}`);
+    if (typeof res === 'object') res.ok = true;
+    return res;
+  }
+
+  async queryPaths(data) {
+    if (data && data.mode === 'canvas') {
+      return this.behaviorCanvas(data);
+    }
+    return this.paths(data);
+  }
+
+  async behaviorCanvas(appId, range = '7d', env = 'production') {
+    const actualAppId = typeof appId === 'object' ? appId.app_id : appId;
+    const actualRange = typeof appId === 'object' ? (appId.range || range) : range;
+    const actualEnv = typeof appId === 'object' ? (appId.env || env) : env;
+    const qs = new URLSearchParams({ range: actualRange, env: actualEnv }).toString();
+    const res = await this.request('GET', `/api/ai/apps/${encodeURIComponent(actualAppId)}/behavior-canvas?${qs}`);
+    if (typeof res === 'object') res.ok = true;
+    return res;
+  }
+
+  async heatmap(appId, templateId, env = 'production', domHash = '') {
+    const actualAppId = typeof appId === 'object' ? appId.app_id : appId;
+    const actualTemplateId = typeof appId === 'object' ? appId.template_id : templateId;
+    const actualEnv = typeof appId === 'object' ? (appId.env || env) : env;
+    const actualDomHash = typeof appId === 'object' ? (appId.dom_hash || domHash) : domHash;
+    const params = { env: actualEnv };
+    if (actualDomHash) params.dom_hash = actualDomHash;
+    const qs = new URLSearchParams(params).toString();
+    const res = await this.request('GET', `/api/ai/apps/${encodeURIComponent(actualAppId)}/pages/${encodeURIComponent(actualTemplateId)}/heatmap?${qs}`);
+    if (typeof res === 'object') {
+      res.ok = true;
+      if (!res.template_id) res.template_id = actualTemplateId;
+    }
+    return res;
+  }
+
+  async getHeatmap(data) {
+    return this.heatmap(data);
+  }
+
+  async listDashboards(appId) {
+    const actualAppId = typeof appId === 'object' ? appId.app_id : appId;
+    const res = await this.request('GET', `/api/apps/${encodeURIComponent(actualAppId)}/dashboards`);
+    return Array.isArray(res) ? res : (res.dashboards || []);
+  }
+
+  async createDashboard(appId, data) {
+    const actualAppId = typeof appId === 'object' ? (appId.app_id || '') : appId;
+    const actualData = typeof appId === 'object' ? appId : data;
+    const res = await this.request('POST', `/api/apps/${encodeURIComponent(actualAppId)}/dashboards`, actualData);
+    if (typeof res === 'object') res.ok = true;
+    return res;
+  }
+
+  async testConnectivity() {
+    const start = Date.now();
+    await this.request('GET', '/api/ai/tools');
+    return Date.now() - start;
+  }
+
+  async getAnalyticsSchema(appId) {
+    const actualAppId = typeof appId === 'object' ? appId.app_id : appId;
+    const res = await this.request('GET', `/api/ai/apps/${encodeURIComponent(actualAppId)}/analytics/schema`);
+    if (typeof res === 'object') res.ok = true;
+    return res;
+  }
+
+  // Natural language AI dashboard creation (POST /api/dashboard)
+  async createAIDashboard(data) {
+    const res = await this.request('POST', '/api/dashboard', data);
+    if (typeof res === 'object') res.ok = true;
+    return res;
+  }
+
+  // Retrieve project business context (GET /api/apps/:appId/context) - 5s timeout
+  async getProjectContext(appId) {
+    const res = await this.request('GET', `/api/apps/${encodeURIComponent(appId)}/context`, null, { timeout: 5000 });
+    if (typeof res === 'object') res.ok = true;
+    return res;
+  }
+
+  // Upload/sync project business context (PUT /api/apps/:appId/context) - 5s timeout
+  async uploadProjectContext(appId, data) {
+    const res = await this.request('PUT', `/api/apps/${encodeURIComponent(appId)}/context`, data, { timeout: 5000 });
+    if (typeof res === 'object') res.ok = true;
+    return res;
+  }
+
+  // Delete project business context (DELETE /api/apps/:appId/context) - 5s timeout
+  async deleteProjectContext(appId) {
+    return this.request('DELETE', `/api/apps/${encodeURIComponent(appId)}/context`, null, { timeout: 5000 });
+  }
+
+  // Request with exponential backoff retry for general methods
+  async requestWithRetry(method, path, body = null, maxRetries = 2) {
+    let lastErr = null;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await this.request(method, path, body);
+      } catch (err) {
+        lastErr = err;
+        if (err.statusCode && err.statusCode < 500 && err.statusCode !== 429) {
+          throw err;
+        }
+        if (attempt < maxRetries) {
+          const delay = Math.pow(2, attempt) * 500;
+          await new Promise((r) => setTimeout(r, delay));
+        }
+      }
+    }
+    throw lastErr;
+  }
+}
+
+module.exports = {
+  APIClient,
+  ERROR_CODES,
+};

package/lib/assets/skill.js

@@ -0,0 +1,127 @@
+const SKILL_CONTENT = `---
+name: shiplens-analytics
+description: Shiplens Web User Telemetry & AI Dashboard Skill Specification. Includes project onboarding, diagnostics, CLI & MCP dual integration, authentication, metadata caching, safe SQL analytics, and single-prompt workflow.
+---
+
+# Shiplens Web Analytics Skill Specification (v2.0)
+
+> 💡 **Core Overview & Official Reference**:
+> 1. **Dual Track Integration**: Supports instant onboarding via **Shiplens CLI** (\`shiplens init\` / \`npx shiplens-cli init\`) for dependency setup, project creation, and code injection; full support for **MCP Tools** and standard REST APIs inside IDE / Agent environments.
+> 2. Installing the SDK and viewing live dashboards requires no MCP server; advanced analytics requires authentication via OAuth, API keys/environment variables, or CLI credentials.
+> 3. **Authoritative FAQ**: \`https://shiplens.dev/faq\`.
+
+You are connected to **Shiplens Web Analytics & MCP Services**. When providing analytics, funnel diagnostics, cohort retention comparisons, and AI dashboard creation, follow the standard workflow and execution protocols below.
+
+---
+
+## 1. Project Onboarding & Step-by-Step Diagnostics
+
+### Standard Workflow:
+\`\`\`
+Check Existing App ID ➔ Install SDK ➔ POST Connect & Get Dashboard URL ➔ Request Email for Free Quota ➔ Activate Magic Link ➔ Authenticate ➔ Complete
+\`\`\`
+
+> ⚡ **Quick Execution**: In a terminal environment, execute \`npx.cmd --yes shiplens-cli init --json\` (Windows) or \`npx --yes shiplens-cli init --json\` (macOS/Linux) for automated 15-second zero-config setup.
+
+### Step 0. Existing Project Detection (Overwrite Protection)
+- Check if \`./.shiplens.json\` or SDK instrumentation (\`initShiplens\`, \`data-app-id\`) exists locally.
+- If existing project is detected, pause and ask the user whether to reuse the existing ID or force overwrite with \`--force\`.
+
+### Step 1. Framework Auto-Detection & SDK Injection
+- Auto-detect Next.js (App/Pages router), Vite (React/Svelte), Vue 3, or Plain HTML.
+- Inject SDK code:
+  - **Next.js App Router**: Client component \`ShiplensTracker.tsx\` imported into root \`layout.tsx\`.
+  - **Vite / Vue**: Import and initialize \`initShiplens({ appId: '<app_id>' })\` in \`main.ts\` / \`main.js\`.
+  - **Plain HTML**: Inject \`<script src="https://cdn.shiplens.dev/sdk.js" data-app-id="<app_id>" defer></script>\` in \`<head>\`.
+
+### Step 2. Dependency Installation
+- Install \`@shiplens/sdk\` via \`npm\`, \`pnpm\`, \`yarn\`, or \`bun\` with \`--legacy-peer-deps\`.
+
+### Step 3. Cloud Registration (POST /api/connect)
+- Send project name, description, 4-level taxonomy (genre, subgenre, tags) to register project.
+- Retrieve permanent \`app_id\` and live \`dashboard_url\`.
+
+#### ★ Initialization Standard Reporting Template
+Upon completing \`shiplens init\`, the Agent **MUST** present the exact information structure and immediately prompt for email activation:
+
+\`\`\`markdown
+Shiplens Analytics SDK successfully integrated and configured:
+
+### 📊 Project & Dashboard Information
+- **Project Name**: \`<project_name>\`
+- **App ID**: \`<app_id>\`
+- **Code Injection**: Automatically configured in [\`<injected_file>\`](file:///<absolute_path>)
+- **Live Dashboard / Activation URL**:
+  🔗 [<dashboard_url>](<dashboard_url>)
+- **User Account**: <User Account Status>
+
+---
+
+### 📦 Changes & Git Status
+- Changes automatically committed to Git (Commit: \`<hash>\`).
+- AI Skill ready: [\`.agents/skills/shiplens/SKILL.md\`](file:///<skill_path>).
+
+> [!IMPORTANT]
+> **Project Pending Activation (Analytics not active yet)**
+> **Please share your email**: Click the link in the email to complete registration, activate 50,000 free monthly events (~5,000 visitors), and bind your project to your account. Once activated, you can chat directly with me to query and analyze product data.
+\`\`\`
+
+**User Account Status Evaluation**:
+- **State a**: \`Logged In (Project linked to account)\` / \`已登录（项目已于账号关联）\` — Local credentials exist and project is linked to user account.
+- **State b**: \`Logged In (Project not linked to account)\` / \`已登录（项目和账号未关联）\` — Local credentials exist but project could not be linked.
+- **State c**: \`Not Logged In (Project unlinked)\` / \`未登录（项目和账号可能未关联）\` — **Default state for first-time CLI installation or unauthenticated environments**.
+
+### Step 4. Request Email for Quota Activation
+- Prompt user for email address to activate **50,000 monthly events** free tier.
+- Send Magic Link email via \`POST /api/auth/start-email\` (or \`shiplens auth bind --email <email> --json\`).
+
+---
+
+## 2. Core CLI Commands Reference
+
+| Command | Purpose |
+| :--- | :--- |
+| \`shiplens doctor --json\` | End-to-end diagnostics on config, SDK, network, and credentials |
+| \`shiplens summary --range 7d --json\` | Product overview: PV, UV, bounce rates, top geos, devices |
+| \`shiplens query --metric <m> --range 7d --json\` | Multi-dimensional metric queries & funnels |
+| \`shiplens sql --query "<sql>" --json\` | Execute secure read-only SQL on ClickHouse |
+| \`shiplens pages --range 7d --json\` | Page-level visits and average dwell times |
+| \`shiplens paths --range 7d --json\` | Sankey user flow and transition paths |
+| \`shiplens heatmap --template <id> --json\` | Click heatmaps & skeleton wireframes |
+| \`shiplens dashboards create --title "..." --prompt "..." --json\` | Generate AI responsive dashboards |
+| \`shiplens auth bind --email <email> --json\` | Trigger Magic Link email binding |
+
+---
+
+## 3. Dynamic Overrides & Adaptive Learning Protocol
+
+When executing analytics requests (such as user prompts matching standard scenarios like \`What stage is my product in? What metrics should I track?\`), you must follow this 5-step protocol:
+
+1. **Step 1 - Check Dynamic Overrides (Priority 1)**:
+   - Check if \`.shiplens/learnings.md\` exists in the project root.
+   - If present, apply any user-specified overrides (e.g. customized date range \`--range 14d\`, preferred metrics, custom funnel steps).
+2. **Step 2 - Context Grounding**:
+   - Check and read \`.shiplens/contexts/<app_id>.md\` (or run \`shiplens context show --json\`) to ground telemetry figures in real button labels and route semantics.
+3. **Step 3 - Deterministic CLI Execution (Priority 2 Base)**:
+   - Run the matched CLI command sequence with any overrides applied.
+4. **Step 4 - Business Synthesis**:
+   - Synthesize data into actionable takeaways and optimization levers.
+5. **Step 5 - Adaptive Learning**:
+   - If the user corrects your analysis (e.g. *"I need a 14-day window"* or *"Track signup completion as the final funnel step"*), immediately record the preference rule into \`.shiplens/learnings.md\` for future automatic reuse.
+
+---
+
+## 4. SQL Standards & Guidelines
+
+- **Table Name**: \`events\` (Read-only ClickHouse instance)
+- **Key Columns**:
+  - \`timestamp\` (DateTime), \`event_name\` (String), \`user_id\` (String), \`session_id\` (String)
+  - \`template_id\` (String - DOM structure hash), \`page_path\` (String), \`referrer\` (String)
+  - \`properties\` (Map/JSON - custom event metadata)
+- **Rules**:
+  - Always apply time filters: \`timestamp >= now() - INTERVAL 7 DAY\`.
+  - Always specify \`LIMIT\` (maximum 1000 rows).
+  - Use ClickHouse aggregate functions: \`countIf()\`, \`quantile(0.50)()\`, \`dateDiff()\`.
+`;
+
+module.exports = { SKILL_CONTENT };