@miraiva_test/miravia-order-report 0.1.13

package/bin/cli.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * Miravia Order Report Skill — CLI Installer
+ *
+ * Usage:
+ *   npx @miraiva_test/miravia-order-report install [--target <path>] [--agent <qoder|cursor|claude>]
+ *   npx @miraiva_test/miravia-order-report upgrade
+ *   npx @miraiva_test/miravia-order-report auth
+ *   npx @miraiva_test/miravia-order-report --version
+ */
+
+'use strict';
+
+const { install, upgrade, runAuth, showVersion, showHelp } = require('../lib/installer');
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+// Parse flags
+function parseFlags(args) {
+  const flags = {};
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === '--target' && args[i + 1]) {
+      flags.target = args[++i];
+    } else if (args[i] === '--agent' && args[i + 1]) {
+      flags.agent = args[++i];
+    } else if (args[i] === '--no-venv') {
+      flags.noVenv = true;
+    } else if (args[i] === '--help' || args[i] === '-h') {
+      flags.help = true;
+    }
+  }
+  return flags;
+}
+
+const flags = parseFlags(args);
+
+switch (command) {
+  case 'install':
+    install(flags);
+    break;
+  case 'upgrade':
+    upgrade(flags);
+    break;
+  case 'auth':
+    runAuth(flags);
+    break;
+  case '--version':
+  case '-v':
+    showVersion();
+    break;
+  case '--help':
+  case '-h':
+  case undefined:
+    showHelp();
+    break;
+  default:
+    console.error(`\x1b[31mUnknown command: ${command}\x1b[0m`);
+    showHelp();
+    process.exit(1);
+}

package/dist/.keypair.json

@@ -0,0 +1,5 @@
+{
+  "skill_code": "miravia_order_reports",
+  "private_key": "MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQDW2Y41Lm/5JqotCumUEzTtBqJqdU9QyvuM9OpaBJSdDOo0yS2JCszVjCdfGg2FQA9JV/1empo1PsB8//l6VS/rHXPcDv1zhIx8oJcQo3P5YeC8UBeGoh3NMAGUVq9Ka+j7+9h7K4N5k8ewTLOWxpOlu/9AYkpAm1b49dvBimDkWmt4uv4d6bS/0SvnhVtiGxtf9dMbqKmbaQEAw1BIfzxiWeWkaOuCzFX5+jfmcC5h+1QPUaqk1cao/C1lGOZ2AHDISg1YIcCTQ8EsyG1wHb5xP2TcshYf/8Bq+PiqSKjNKRYl5RUm17oaKK0naaD0e37Qz97xlVOKlcTGs/F8gVMPAgMBAAECggEACxBzGVwF2i/aja1FMCH5FMfFr3PRHNkHMVAfjXk06g2TNhqyJJ+QwuKP2H7v+U++Ocm1O5z8mgdcRFOuVlVyvUnsAIYpGTzXO0fN38Z7H3mh6DC7tWw92qZBPpFkP5HlEqz6jgVEpQsuOm8IxJf/XIac84TcTA1z4ihPI91rdfb146+FBK1rehjbNb14y5PA9jeeyfSAj2iJq5w0FZOkdvMs5KYIH1S8pgyPQgT2ix/ivQfsRm6Q0T/XIZCCiWJak3pnfrEsx+2wgahOF35yy/R4cOsC2YQ7UrZS8MAfzkn05HnGWmbsMcEilm3uJg+GiGcm8IMsDVGZWzYvA516yQKBgQD55sw+yxqO1Q3g9qlfy6vI8UvzlK/ll37/dkt2PvCeR80B1bdQZYoBK7iqAM2DuKWH4YuruSVPJa2qfoQ8rI9TB/KZgOysEbYgn4Zs11gtSA+D4f/6qdCUYs+Ja0vxL27PYTlUgbc+Zt5nTSmA58E/Ja6reu12TyL71hb9Rij17QKBgQDcF8e0w979TA42CU7IKAddNJe+fO/tg1Z328p6QMxIMcnPkXytvw/Qw4uP+hlBmZnsRTzBrmnBBwLvHE+hYBeJxvE0zOqiMIH9I/1gHAfDfvSIWtdxqknO49sHs962rLBAD3xvF0NUbv+b02JxNj5DAuoH38cl79m9k5PpE8uNawKBgA4hqQccASJ2ldRU3nsWT16LlpntnIzFJl9X1yiWopCwyr0B0t3vAADU8hpa9UQvmty2Omm5jIyPOuTbRqsPrwMo/eUET13jmoL5wmZBPzFAU/BHRWxtUegyNj41HRREdGWxv8Yxl6UluAnraR9q+5iQjvIPf4IjM30+PAqSfxp5AoGAT4SP9LFn2WAnKkLGoe5EatpbkMkW7lsrXHaeevj6VYMXhNTtlOCY2DYuMECN63ORdxm0z80yDDl6R+WUp5tOJcsozojSpPKdpFXib1zxOSKfOryHZlu9+u+77NaBusI9k4eEz6Y5/0FzPFttD7YnXJKq91lUXFKB+spdADLUsi0CgYAEge8NfRVVzSCgLdeY4aQghLVczHNutvYzLeTe5o0tkJAtrSY/elaLzcjtfZZY/vFkp6OPgqmArj7jTV+ZM3Wbus2ZMGCTGyG8Yp0wCofAx42I7luSOVC91kdqoO0avD/gHTB8+GS0TfhQPAi+icdsl1I7chzDUYKvToSAyoIzXw==",
+  "sign_method": "SHA256withRSA"
+}

package/dist/README.md

@@ -0,0 +1,249 @@
+# Miravia Order Report Skill · Seller Guide
+
+> Miravia Skill Hub Beta · Maintained by Miravia Official
+> Seamlessly integrate order queries, Excel exports, and HTML business analytics into your AI Agent.
+
+---
+
+## 1. What This Skill Does
+
+Type natural language in any Skill-compatible AI Agent (Cursor / Qoder / Claude Code), and the Skill **dynamically generates different outputs based on context**, instead of producing both Excel and HTML at once:
+
+| Scenario | Output | Example Prompt |
+|----------|--------|----------------|
+| `export` | Excel/CSV only | "Export all orders from last Monday to Sunday" / "Pull a to-ship spreadsheet" |
+| `refund` | Refund analysis HTML only | "Analyze refund orders for the last 30 days, grouped by reason" |
+| `business` | Business report HTML only | "Generate last month's business report with GMV / category performance / refund rate" |
+| `auto` | Excel + comprehensive HTML | "Show me last week's order situation" (when intent is unclear) |
+
+Three typical scenarios:
+
+- 📥 **Scenario 1 · Order Export**: A fashion seller needs to export all orders every Monday. Tell the Agent "Export all Miravia orders from last Monday to Sunday" — only an `xlsx` file is generated, no extra report.
+- 📊 **Scenario 2 · Refund Analysis**: A 3C seller notices a rising refund rate. Tell the Agent "Analyze refund orders for the last 30 days" — only a `refund analysis HTML` is generated, covering refund reason distribution, top refund SKUs, refund trends, and details.
+- 📈 **Scenario 3 · Monthly Business Report**: A home & living seller schedules a monthly task. The Skill generates a `business analysis HTML` with GMV trends, category performance, refund rate, cancellation rate, and recommendations.
+
+No Seller Center login required. No code. No API docs.
+
+---
+
+## 2. Installation
+
+### Option 1: Manual Install (zip)
+
+1. Download `miravia-order-report.zip` from the Skill Hub page.
+2. Extract to your Agent's Skill directory:
+   - **Qoder**: `~/.qoder/skills/`
+   - **Cursor**: `~/.cursor/skills/`
+   - **Claude Code**: `~/.claude/skills/`
+3. **Navigate to the skill root directory** (the folder containing `SKILL.md`) and install dependencies:
+   ```bash
+   cd <path-above>/miravia-order-report
+   pip install -r requirements.txt
+   ```
+
+> All commands in this document assume execution from the **skill root directory**. Paths are given in relative form — do not hard-code the host Agent's installation path.
+
+### Option 2: Command Install (Recommended)
+
+Paste the following into your Agent chat:
+```
+Please install the miravia-order-report Skill using: npx miravia-skill install miravia-order-report
+```
+
+---
+
+## 3. Authorization
+
+> **Authorization endpoint** (staging): `https://pre-sellercenter.miravia.es/apps/seller/skill/auth`  
+> Production: `https://sellercenter.miravia.es/apps/seller/skill/auth`
+
+This Skill does **not** ship any mock `appKey` / `appSecret` / `accessToken`, nor does it support the legacy Miravia OAuth (`auth.miravia.com`) flow.
+
+Authorization flow:
+
+```mermaid
+graph LR
+    A[auth_cli login] --> B[Local callback :8765]
+    A --> C[Browser opens auth page]
+    C --> D[Seller approves]
+    D --> E[Frontend POST /skill/auth]
+    E --> F[Backend RSA-encrypts cipher]
+    F --> B
+    B --> G[CLI decrypts with private key -> credentials.json]
+```
+
+### 3.1 One-Click Authorization CLI
+
+```bash
+# 1. Save the private key + skillCode from backend generateKeyPair into .keypair.json at the skill root
+# {
+#   "skill_code":  "<32-char skillCode>",
+#   "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
+#   "sign_method": "SHA256withRSA"
+# }
+chmod 600 .keypair.json
+
+# 2. One-click authorization
+python scripts/auth_cli.py login
+
+# 3. Check credential status
+python scripts/auth_cli.py status
+```
+
+Common parameters:
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `--port` | `8765` | Local callback port |
+| `--redirect-uri` | `http://127.0.0.1:<port>/callback` | Custom callback URL |
+| `--timeout` | `600` | Timeout in seconds waiting for browser callback (10 min) |
+| `--no-open` | — | Skip auto-opening the browser (for remote/headless environments) |
+| `--encrypted-payload` | — | Directly provide the encryptedPayload ciphertext, skipping the local HTTP callback (for VM/sandbox environments) |
+
+The local callback server accepts a single response format from the frontend:
+
+- **GET 302 redirect**: `http://127.0.0.1:8765/callback?cipher=<base64url>&state=<state>` (the only method — no cross-origin access to localhost needed).
+
+After successful authorization, credentials are written to `credentials.json` in the skill root (already in `.gitignore`):
+
+```json
+{
+  "app_key": "enc:v1:...",
+  "app_secret": "enc:v1:...",
+  "access_token": "enc:v1:...",
+  "token_expires_at": "2026-06-16 15:01",
+  "last_login_at": "2026-06-16T14:01:45"
+}
+```
+
+To read credentials programmatically, parse the JSON file directly.
+
+### 3.2 Switch Environment
+
+```bash
+# Staging (default)
+export MIRAVIA_SKILL_HUB_AUTH_URL=https://pre-sellercenter.miravia.es/apps/seller/skill/auth
+
+# Production
+export MIRAVIA_SKILL_HUB_AUTH_URL=https://sellercenter.miravia.es/apps/seller/skill/auth
+```
+
+> ⚠️ Sub-accounts cannot authorize. Please log in to Seller Center with the Owner Account before navigating to the authorization page.
+
+---
+
+## 4. Usage Examples (by Scenario)
+
+### 4.1 Scenario 1: Order Export (Excel only)
+
+> Tell the Agent:
+>
+> "**Export all Miravia orders from last Monday to Sunday**"
+
+The Agent resolves to `--scenario export` and outputs:
+```
+scenario  : export (excel=True, report=none)
+output    : /Users/.../out/miravia_orders_2026-05-18_2026-05-24_xxx.xlsx
+```
+Only an Excel file is generated — no HTML.
+
+### 4.2 Scenario 2: Refund Analysis (refund HTML only)
+
+> "**Analyze refund orders for the last 30 days, grouped by refund reason**"
+
+The Agent resolves to `--scenario refund --last-days 30` and outputs:
+```
+scenario  : refund (excel=False, report=refund)
+report    : /Users/.../out/miravia_refund_analysis_xxx.html
+```
+The report includes: total refund amount, refund rate KPI, refund reason bar chart, top refund SKUs, daily refund trend, refund details (up to 50 rows), and actionable recommendations.
+
+Need the raw refund data in Excel too? Add `--with-excel`:
+```bash
+python scripts/export_orders.py --scenario refund --last-days 30 --with-excel --output ./out
+```
+
+### 4.3 Scenario 3: Monthly Business Report (business HTML only)
+
+> "**Generate last month's business analysis report**" or as a scheduled task:
+>
+> "On the 1st of every month, generate last month's report with GMV trends, category performance, and refund rate"
+
+The Agent resolves to `--scenario business` and outputs:
+```
+scenario  : business (excel=False, report=business)
+report    : /Users/.../out/miravia_order_report_xxx.html
+```
+The report includes: snapshot (orders / GMV / AOV / top SKUs), diagnostics (cancellation rate / refund rate / carrier mix / daily trends), and recommendations.
+
+### 4.4 To-Ship Orders Only
+
+> "**Export all To Ship orders as CSV**"
+
+→ `--scenario export --status to_ship --format csv`.
+
+---
+
+## 5. Advanced Usage (Direct CLI)
+
+```bash
+# Scenario 1: Export order details
+python scripts/export_orders.py \
+    --scenario export \
+    --created-after 2026-05-01 --created-before 2026-05-31 \
+    --status all --format xlsx --output ./out
+
+# Scenario 2: Refund analysis
+python scripts/export_orders.py \
+    --scenario refund --last-days 30 --output ./out
+
+# Scenario 3: Monthly business report
+python scripts/export_orders.py \
+    --scenario business \
+    --created-after 2026-05-01 --created-before 2026-05-31 --output ./out
+
+# Refund analysis + raw data Excel
+python scripts/export_orders.py \
+    --scenario refund --last-days 30 --with-excel --output ./out
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `--scenario` | `auto` / `export` / `refund` / `business` — determines what output is produced |
+| `--with-excel` | Additionally output a detail Excel in `refund` / `business` scenarios |
+| `--created-after` / `--created-before` | Order creation time range (`YYYY-MM-DD` or ISO 8601) |
+| `--last-days N` | Last N days including today (overrides `--created-after/before`) |
+| `--status` | `all` (all orders) or `to_ship` (pending shipment only) |
+| `--format` | `xlsx` or `csv` |
+| `--output` | Output directory |
+| `--ping` | Health check. Outputs `ping OK` on success; `ping FAIL: <reason>` with exit code 1 on failure |
+
+---
+
+## 6. FAQ
+
+| Symptom | Solution |
+|---------|----------|
+| "Authorization timeout" | Re-run `auth_cli.py login` — the browser will redirect to the auth page again |
+| `CredentialMissingError: missing Miravia credentials` | Not authorized or `credentials.json` is corrupted — re-run `auth_cli.py login` |
+| Single export exceeds 5000 orders | Narrow the time range or split into multiple runs |
+| HTML report won't open | The file is self-contained HTML — double-click or drag into a browser (no internet needed) |
+| Signature error / `IncompleteSignature` | Token has expired — re-run `auth_cli.py login` to re-authorize |
+| Decryption failed (DECRYPT_FAILED, exit 7) | Private key in `.keypair.json` doesn't match the server public key — re-sync and retry |
+| AES-GCM decryption failed after changing computer or hostname | Credentials are machine-bound — re-run `auth_cli.py login` on the new machine |
+
+---
+
+## 7. Data Security
+
+- All API calls are encrypted over HTTPS.
+- Strict tenant isolation between sellers — you can only access your own shop's data.
+- **Tokens are AES-256-GCM encrypted at rest** — credentials in `credentials.json` are never stored in plain text. The encryption key is bound to your specific machine; even if the encrypted file is copied elsewhere, it cannot be decrypted on a different computer.
+- Changing your computer or OS username will invalidate local credentials — simply re-run `auth_cli.py login` to re-authorize.
+- This Skill does not transmit order data to any location outside Miravia's servers.
+
+---
+
+## 8. Feedback
+
+This is a Beta release. We welcome your feedback via the Skill Hub questionnaire to help us improve.

package/dist/SKILL.md

@@ -0,0 +1,329 @@
+---
+name: miravia-order-report
+description: Query Miravia seller order data via Open API, export filtered orders to Excel/CSV, and generate an HTML business analysis report. Use when the user mentions Miravia orders, order export, order report, refund analysis, GMV analysis, or asks to download/analyze orders from the Miravia seller backend.
+---
+
+# Miravia Order Report
+
+A Skill for Miravia (M2A) sellers. Pulls order, sub-order item and reverse-order data from the official Miravia Open API, then produces **different outputs dynamically based on scenario**:
+
+| Scenario | Output | Use Case |
+|----------|--------|----------|
+| `inspect` | **stdout text only** (no files) | Seller asks about specific order status/shipping/refund reason |
+| `export` | **Excel/CSV** only | Ops staff fetches raw data for external reporting |
+| `refund` | **v4 unified dashboard HTML** only | Refund reasons, top refund SKUs, refund trends |
+| `business` | **v4 unified dashboard HTML** only | Monthly/weekly report: GMV, AOV, refund rate, recommendations |
+| `auto` | Excel + v4 HTML | Backward compatible; default when intent is unclear |
+
+> **Principle: One output type per invocation.** No HTML in export scenarios, no Excel in refund/business scenarios (use `--with-excel` only when explicitly requested).
+
+---
+
+## Scenario Routing (Agent MUST follow)
+
+Priority is top-down; stop at first match:
+
+| # | User Intent | scenario | Default Params |
+|---|-------------|----------|----------------|
+| 0 | Explicit order ID(s) — status/shipping/refund inquiry | `inspect` | `--order-ids <ids>` |
+| 1 | Refund, return, refund reason/rate analysis | `refund` | `--last-days 30` |
+| 2 | Business analysis, monthly/weekly report, GMV trend | `business` | Full/last month |
+| 3 | Export, download, Excel, pull N days, raw data | `export` | User-specified range |
+| 4 | Unclear intent, wants both | `auto` | Generates both |
+
+**Key rules:**
+- `inspect` has **highest priority** — if user provides order IDs, always use `inspect`.
+- `inspect` MUST NOT combine with `--with-excel` or HTML; stdout is the sole output.
+- "Export refund details" → `--scenario refund --with-excel`
+- "Monthly report + raw data" → `--scenario business --with-excel`
+
+---
+
+## Core Constraints (Single Source of Truth)
+
+These rules are referenced throughout the workflow. Each is defined **once** here.
+
+| ID | Rule | Summary |
+|----|------|---------|
+| C1 | **Time range mandatory** | Non-inspect scenarios require explicit time range. Ambiguous expressions ("recently", "all") → MUST ask user to clarify. |
+| C2 | **countTotal NEVER shown** | API's `countTotal` is unreliable. Agent MUST NEVER display order counts from this field — not in estimates, progress, or summaries. |
+| C3 | **Time estimate first** | Formula: `ceil(orders / 6000)` minutes. Show only time, not count. |
+| C4 | **Status filter confirmation** | Natural language status → present supported status table, ask user to confirm. Technical values (e.g., `--status canceled`) → no confirmation needed. |
+| C5 | **Auto-open browser** | Always auto-open (auth page, HTML report). Only provide URL as fallback if `open` command fails. |
+| C6 | **Executive Summary = LLM-generated** | The script's rule-engine placeholder MUST NOT be delivered directly. Agent must analyze `metrics.json` and inject AI insights. |
+| C7 | **API retry** | Up to 3 retries per API call; report error only after all 3 fail. |
+| C8 | **Volume limit** | Hard cap 200,000 sub-orders. Exceeded → suggest splitting by month/week. |
+| C9 | **Zero data early-stop** | `no_data: true` → stop immediately, inform merchant, do NOT generate files. |
+
+---
+
+## When to Use
+
+- "Check order 30502596014 status" → `inspect --order-ids 30502596014`
+- "Export last week's Miravia orders" → `export`
+- "Analyze refund orders for the last 30 days" → `refund`
+- "Generate monthly business report" → `business`
+- "Show unshipped orders" → `export --status all_to_ship` (after status confirmation per C4)
+
+---
+
+## Prerequisites
+
+Credentials are sourced exclusively from Skill Hub authorization:
+
+> **Staging URL**: `https://pre-sellercenter.miravia.es/apps/seller/skill/auth`
+
+First-time setup (from skill root directory):
+
+1. Save private key + `skillCode` from `generateKeyPair` to `.keypair.json` (`chmod 600`).
+2. One-click authorization:
+   ```bash
+   python scripts/auth_cli.py login
+   ```
+   Opens browser → user authorizes → callback writes `credentials.json`.
+
+> **Authorization URL format**: The CSRF `state` must be appended as un-encoded `?state=xxx` after the percent-encoded redirect_uri. See [auth_design.md §4.1](auth_design.md#41-authorization-url-cli--browser).
+
+> **Callback i18n**: Frontend may append `&lang=xx` (`en`/`es`/`it`) to callback redirect_uri.
+
+Utility: `python auth_cli.py status` — check token validity.
+
+Production switch: `export MIRAVIA_SKILL_HUB_AUTH_URL=https://sellercenter.miravia.es/apps/seller/skill/auth`
+
+If `IncompleteSignature` / `InvalidAccessToken` → ask user to re-run `auth_cli.py login`.
+
+---
+
+## CLI Reference
+
+Entry point: [scripts/export_orders.py](scripts/export_orders.py)
+
+```bash
+pip install -r requirements.txt  # Install once
+
+# Examples
+python scripts/export_orders.py --agent-type qoder --scenario export --last-days 7 --output ./out
+python scripts/export_orders.py --agent-type qoder --scenario refund --last-days 30 --no-open --output ./out
+python scripts/export_orders.py --agent-type qoder --scenario inspect --order-ids 30502596014
+python3 scripts/estimate_time.py --agent-type qoder --last-days 365
+```
+
+### Flags
+
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `--agent-type` | **Yes** | — | Agent identifier (`qoder`/`cursor`/`claude`/custom) |
+| `--created-after` | No | today-6d | Start date (YYYY-MM-DD, aligned 00:00:00) |
+| `--created-before` | No | today | End date (YYYY-MM-DD, aligned 23:59:59) |
+| `--last-days` | No | — | Relative range (overrides after/before) |
+| `--status` | No | `all` | Order status filter (see table below) |
+| `--format` | No | `xlsx` | `xlsx` or `csv` |
+| `--output` | No | `./out` | Output directory |
+| `--scenario` | No | `auto` | `inspect`/`export`/`refund`/`business`/`auto` |
+| `--order-ids` | inspect only | — | Comma-separated order IDs |
+| `--with-excel` | No | `false` | Also output Excel in refund/business scenarios |
+| `--lang` | No | auto | Report language: `en`/`es`/`it`/`zh` (auto-detect from conversation) |
+| `--no-open` | No | — | **Mandatory for report scenarios** (Agent opens after Step 5 injection) |
+| `--ping` | No | — | Health check: outputs `ping OK` or `ping FAIL: <reason>` |
+
+### Supported Status Values
+
+| Value | Description |
+|-------|-------------|
+| `all` | All orders (no filter) |
+| `all_to_ship` | To Ship (topack + packed + rts) |
+| `all_shipped` | Shipped (shipped + delivered) |
+| `topack` | Awaiting packaging |
+| `packed` | Awaiting pickup |
+| `rts` | Ready to ship |
+| `canceled` | Already canceled |
+| `shipped` | Shipped / Picked up |
+| `delivered` | Delivered |
+
+> Only these 9 values are supported. Unsupported status → inform user and present this table (C4).
+
+---
+
+## Agent Workflow
+
+> **Windows users**: See [docs/windows_compat.md](docs/windows_compat.md) for Constrained Language Mode bypass.
+
+### Step 1: Parse User Intent
+
+Derive: `--agent-type`, `--scenario`, time range, `--status`, `--format`, `--lang`.
+
+- **Scenario**: Follow routing table above (highest priority first).
+- **Language** (`--lang`): Auto-detect from conversation language (Chinese→`zh`, English→`en`, Spanish→`es`, Italian→`it`). Only override if user explicitly specifies.
+- **Time range** (C1): Explicit time → use directly. Ambiguous → ask user. "All orders" → confirm scope.
+  - Relative: `--last-days N` (e.g., "last 7 days" → `--last-days 7`)
+  - Absolute: `--created-after YYYY-MM-DD --created-before YYYY-MM-DD`
+- **Status** (C4): Natural language → present table, ask confirmation. Technical value → use directly.
+
+### Step 2: Pre-flight Credential Check
+
+```bash
+python scripts/export_orders.py --agent-type <TYPE> --ping
+```
+
+- `ping OK` → proceed to Step 3.
+- `ping FAIL` → launch `python scripts/auth_cli.py login` in background (`is_background=true`).
+
+**Authorization flow (automation-first, non-negotiable):**
+1. Agent launches login in background and sends guidance message to user:
+   > 🔐 **Browser authorization required** — I've opened the authorization page. Switch to your browser, find "Skill Authorization", and click "Authorize". I'll continue automatically once done.
+2. Poll with `GetTerminalOutput(terminal_id, wait_seconds=15)`:
+   - `[login] OK` → proceed to Step 3.
+   - `[login] DECRYPT_FAILED` → inform user of failure.
+   - `webbrowser.open failed` or 2 rounds without `callback GET` → enter [VM fallback](docs/vm_fallback.md).
+   - >10 rounds without response → prompt user to check browser.
+3. Do NOT ask user "have you completed authorization" — zero-confirmation wait.
+
+### Step 3: Estimate Time (C2, C3, C9)
+
+```bash
+python3 scripts/estimate_time.py --agent-type <TYPE> [--last-days N | --created-after X --created-before Y] [--status S]
+```
+
+Parse structured output:
+- `upgrade` line: `need_upgrade: false` → proceed silently. `need_upgrade: true` → inform user, offer upgrade/skip choice.
+- `estimate` line: Show only estimated time (e.g., "Estimated ~2 minutes"). **Never show `total_orders`** (C2). If `no_data: true` → stop and inform merchant (C9).
+
+### Step 4: Execute Export
+
+```bash
+python scripts/export_orders.py \
+    --agent-type <TYPE> --scenario <S> \
+    [--last-days N | --created-after X --created-before Y] \
+    [--status S] [--format F] [--with-excel] [--lang LANG] --no-open --output <DIR>
+```
+
+**Execution rules:**
+- Launch in background (`is_background=true`), poll progress every 5-10s.
+- Progress relay: Only show current fetched count (✅ "Fetched 400 orders..." ❌ "Fetched 400/620 orders").
+- Detect `metrics :` line → **stop polling, enter Step 5** (do NOT announce "report complete" yet).
+- `export` scenario (no `metrics :`) → skip to Step 6.
+
+### Step 5: AI Insights Injection (C6, mandatory for refund/business/auto)
+
+> **Full specification**: [executive_summary_prompt_v2.md](executive_summary_prompt_v2.md)
+
+**① Read** `metrics.json` (path from stdout `metrics :` line).
+
+**② Generate** `insights.json` following ALL rules in `executive_summary_prompt_v2.md`:
+- Filename: replace `metrics_` prefix with `insights_` (same timestamp suffix).
+- Schema: `{ "lang": "<code>", "generated_at": "<ISO8601>", "presets": { "0": { "summary", "highlights[]", "actions[]" }, ... } }`
+- Field constraints: `severity` ∈ {`high`, `medium`, `low`}; `priority` ∈ {`P0`, `P1`, `P2`}; `highlights` need `title` + `detail` + `severity`; `actions` need `text` + `priority`.
+- JSON encoding: ASCII quotes only, no smart quotes/em-dashes/currency symbols. See prompt file §1 for full rules.
+
+**③ Validate** JSON:
+```bash
+python3 -c "import json; json.load(open('<insights_path>'))" && echo 'OK'
+```
+
+**④ Inject** into HTML:
+```bash
+python3 scripts/inject_insights.py --html <report_path> --insights <insights_path>
+```
+
+**⑤ Validate rendering**:
+```bash
+python3 scripts/validate_render.py <report_path>
+```
+- `RENDER_CHECK: OK` → proceed to ⑥.
+- `FAIL: ...` → clear insights and re-inject empty (triggers frontend fallback):
+  ```bash
+  python3 -c "import json; open('<insights_path>','w').write(json.dumps({'presets':{}}))"
+  python3 scripts/inject_insights.py --html <report_path> --insights <insights_path>
+  ```
+
+**⑥ Open report** (C5):
+```bash
+open <report_path>    # macOS
+xdg-open <report_path>  # Linux
+```
+
+### Step 6: Present Results
+
+- `export` → "Export file: `<path>`"
+- `refund`/`business`/`auto` → "Report opened in your browser. File path: `<path>`" (only show path if open fails).
+- **Never mention**: pagination, API internals, offset/limit, time-window slicing.
+
+### Step 7: Secondary Filtering
+
+If user requests further filtering after export (e.g., "show only Spain orders"):
+- Load exported Excel with pandas, filter locally. Do NOT re-call API.
+- No Excel available → suggest re-run with `--with-excel`.
+
+---
+
+## Inspect Scenario Details
+
+- Trigger: User provides order IDs asking about status/shipping/refund.
+- Required: `--order-ids` (comma-separated). No time params needed.
+- Underlying: `/orders/items/get` + `/reverse/getreverseordersforseller` per order.
+- Agent reorganizes stdout into natural language; does NOT paste raw text.
+- "Not found" → that order doesn't belong to the authorized shop.
+
+---
+
+## Data Scope
+
+Sub-order granularity, joining three APIs:
+
+| API | Purpose |
+|-----|---------|
+| `/orders/get` | Master order (paginated) |
+| `/orders/items/get` | Sub-order items |
+| `/reverse/getreverseordersforseller` | Refund/reverse info |
+
+See [reference.md](reference.md) for field mapping and Excel column definitions.
+
+---
+
+## Limits & Guardrails
+
+- 200,000 sub-order hard cap (exit code 2) — suggest splitting.
+- Exit code 3 = zero data — inform merchant, suggest adjusting filters.
+- Auto time-window slicing when >1,000 main orders (transparent to user).
+- `/orders/get` page size = 100; offset+limit ≤ 5000 (mitigated by auto-slicing).
+- Credentials AES-256-GCM encrypted at rest, bound to machine fingerprint.
+- Same-name files get `_1`, `_2` suffix to avoid overwriting.
+
+---
+
+## Stdout Format Reference
+
+| Prefix | Meaning | Agent Action |
+|--------|---------|--------------|
+| `range :` | Query time range | "Querying orders from X to Y" |
+| `progress: N orders found` | countTotal (inaccurate) | **Internal only, NEVER show** (C2) |
+| `progress: fetched X orders` | Batch progress | "Fetched X orders..." (strip total) |
+| `progress: M main, N sub-order rows` | Final aggregation | "Retrieved M orders, N records" (safe to show) |
+| `output :` | Excel/CSV path | Show to user |
+| `report :` | HTML path | Internal: proceed to Step 5 |
+| `metrics :` | Metrics JSON path | Internal: read for LLM analysis |
+| `injected :` | Injection success | Internal confirmation |
+| `no_data :` | Zero orders | Inform merchant, stop (C9) |
+| `estimate :` | Time estimate JSON | Show only time (C2, C3) |
+| `ping OK/FAIL` | Credential check | Step 2 flow |
+
+---
+
+## HTML Report Structure (v4 Dashboard)
+
+6 interactive tabs: Overview | Sales Performance | Cancellations & Refunds | Product Insights | Buyers & Markets | Logistics & Fulfillment.
+
+Features: Platform filter (All/Miravia/M2A), time filter (all/7d/30d), Chart.js CDN (requires internet).
+
+---
+
+## Related Documents
+
+| Document | Purpose |
+|----------|---------|
+| [executive_summary_prompt_v2.md](executive_summary_prompt_v2.md) | Authoritative prompt for AI insights generation |
+| [reference.md](reference.md) | API fields & Excel column mapping |
+| [docs/windows_compat.md](docs/windows_compat.md) | Windows Constrained Language Mode bypass |
+| [docs/vm_fallback.md](docs/vm_fallback.md) | VM/sandbox authorization fallback |
+| [README.md](README.md) | Seller-side installation & authorization guide |
+| [auth_design.md](auth_design.md) | Authorization URL format specification |

package/dist/VERSION

@@ -0,0 +1 @@
+0.1.13