@miraiva_test/miravia-order-report 0.1.13 → 0.1.15

package/dist/SKILL.md

@@ -5,6 +5,21 @@ description: Query Miravia seller order data via Open API, export filtered order
 
 # Miravia Order Report
 
+## ⚠ Agent Self-Check Protocol (MANDATORY before task completion)
+
+Before telling the user "report is ready", the Agent MUST answer ALL of the following:
+
+| # | Question | Required Answer |
+|---|----------|----------------|
+| 1 | Is this a report scenario (refund/business/auto)? | If NO → skip to Step 6. If YES → continue. |
+| 2 | Did I read `metrics.json` and generate `insights.json`? | Must be YES |
+| 3 | Did I run `render_final.py` and see `RENDER_CHECK: OK`? | Must be YES |
+| 4 | Is the final HTML path shown in stdout? | Must be YES |
+
+**If any answer is NO for a report scenario → return to Step 5. Do NOT present the 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 |
@@ -50,7 +65,7 @@ These rules are referenced throughout the workflow. Each is defined **once** her
 | 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. |
+| C6 | **Executive Summary = LLM-generated (BLOCKING)** | Report scenarios (refund/business/auto) do NOT produce HTML until AI insights pass validation. Pipeline: export_orders.py → metrics.json + report_data.json → Agent generates insights.json → render_final.py validates & renders HTML. Invalid insights = no HTML output. |
 | 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. |
@@ -203,47 +218,49 @@ python scripts/export_orders.py \
 - 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)
+**Output for report scenarios (refund/business/auto):**
+- `report_data :` → pre-computed dashboard data (used by render_final.py)
+- `metrics :` → structured metrics for AI analysis
+- `TASK_INCOMPLETE:` → HTML is NOT yet generated; proceed to Step 5
+
+### Step 5: AI Insights Generation & Final Render (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[]" }, ... } }`
+- Filename: `insights.json` in the output directory.
+- Schema: `{ "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.
+- **Top-level has ONLY `presets`** — do NOT add `lang`, `generated_at`, or other fields.
 
 **③ Validate** JSON:
 ```bash
 python3 -c "import json; json.load(open('<insights_path>'))" && echo 'OK'
 ```
 
-**④ Inject** into HTML:
+**④ Render final HTML** (insights validation is built-in — invalid insights = render refused):
 ```bash
-python3 scripts/inject_insights.py --html <report_path> --insights <insights_path>
+python3 scripts/render_final.py --report-data <report_data_path> --insights <insights_path> --output <DIR> --lang <LANG>
 ```
 
-**⑤ 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
-```
+**Expected stdout signals:**
+- `insights  : validated OK` → structure passed
+- `report    :` → HTML file path
+- `RENDER_CHECK: OK` → ✅ proceed to Step 6
+- Exit code 2 = insights validation failed → regenerate insights.json and retry
+
+**⑤ If `RENDER_CHECK: OK`** → report is complete, proceed to Step 6.
+
+**⑤b If exit code 2** (validation failed) → fix insights.json and re-run render_final.py.
+  Common fixes: ensure all `highlights` are objects (not strings), check `severity`/`priority` values.
 
 ### Step 6: Present Results
 
+**Precondition (refund/business/auto):** `RENDER_CHECK: OK` observed in Step 5 stdout. If not met → return to Step 5.
+
 - `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.
@@ -300,9 +317,12 @@ See [reference.md](reference.md) for field mapping and Excel column definitions.
 | `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 |
+| `report_data :` | Pre-computed data JSON path | Internal: used by render_final.py |
+| `metrics :` | Metrics JSON path | **STOP polling → enter Step 5** (do NOT announce completion) |
+| `NEXT_ACTION_REQUIRED:` | render_final.py command | Agent MUST generate insights then execute this |
+| `TASK_INCOMPLETE:` | Hard gate signal | HTML not yet generated — insights + render pending |
+| `report :` | Final HTML path (from render_final.py) | Show to user, open in browser |
+| `RENDER_CHECK: OK` | HTML validated | Step 5 complete ✅ (proceed to Step 6) |
 | `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 |
@@ -320,8 +340,9 @@ Features: Platform filter (All/Miravia/M2A), time filter (all/7d/30d), Chart.js
 ## Related Documents
 
 | Document | Purpose |
-|----------|---------|
+|----------|--------|
 | [executive_summary_prompt_v2.md](executive_summary_prompt_v2.md) | Authoritative prompt for AI insights generation |
+| [scripts/render_final.py](scripts/render_final.py) | Final HTML renderer (validates insights before rendering) |
 | [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 |

package/dist/VERSION

@@ -1 +1 @@
-0.1.13
+0.1.15

package/dist/scripts/auth_cli.py

@@ -507,7 +507,13 @@ def _decrypt_cipher_to_creds(
 
 
 def _fmt_expires(expires_str: str) -> str:
-    """Format expiry time string (YYYY-MM-DD HH:MM) with remaining time description."""
+    """Format expiry time string (YYYY-MM-DD HH:MM) with remaining time description.
+
+    Since expires_at is stored at minute precision (YYYY-MM-DD HH:MM, i.e. seconds=0),
+    we align 'now' to the same minute granularity (truncate seconds to 0) before computing
+    the remaining delta. This prevents display artifacts like '29d 23h 59m' when the actual
+    remaining time is effectively 30 full days.
+    """
     if not expires_str:
         return "<unknown>"
     # Try parsing YYYY-MM-DD HH:MM format
@@ -521,7 +527,10 @@ def _fmt_expires(expires_str: str) -> str:
             ts = int(expires_str)
         except (ValueError, TypeError):
             return expires_str
-    delta = ts - int(time.time())
+    # Align now to minute boundary (truncate seconds) to match expires_at precision
+    now_ts = int(time.time())
+    now_ts = now_ts - (now_ts % 60)
+    delta = ts - now_ts
     iso = time.strftime("%Y-%m-%d %H:%M", time.localtime(ts))
     if delta <= 0:
         return f"{iso}  (EXPIRED {-delta}s ago)"
@@ -717,6 +726,9 @@ class _CallbackHandler(http.server.BaseHTTPRequestHandler):
 
         Parses ``YYYY-MM-DD HH:MM`` format (produced by _expires_at()).
         Falls back to fixed 30-day text on failure, ensuring callback page is not blocked.
+
+        Since expires_at is minute-precision, aligns 'now' to the same granularity
+        to avoid '29 days' display when the actual validity is effectively 30 days.
         """
         t = _I18N_TEXTS.get(lang, _I18N_TEXTS[_DEFAULT_LANG])
         if not expires_at:
@@ -732,7 +744,10 @@ class _CallbackHandler(http.server.BaseHTTPRequestHandler):
                 ts = int(expires_at)
             except (TypeError, ValueError):
                 return t["token_valid_30days"]
-        delta = ts - int(time.time())
+        # Align now to minute boundary to match expires_at precision
+        now_ts = int(time.time())
+        now_ts = now_ts - (now_ts % 60)
+        delta = ts - now_ts
         if delta <= 0:
             return t["token_expired"]
         iso = time.strftime("%Y-%m-%d %H:%M", time.localtime(ts))

package/dist/scripts/export_orders.py

@@ -1334,13 +1334,28 @@ def run(args: argparse.Namespace) -> int:
         print(f"output    : {excel_path}")
 
     if do_report:
-        html_path = out_dir / f"miravia_order_report_{fname_range}_{ts}.html"
-        html_path = _resolve_collision(html_path)
-        render_v4_report(rows, html_path, range_label=range_label, lang=getattr(args, 'lang', 'en'))
-        print(f"report    : {html_path}")
+        # Phase 1: Compute report data payload and metrics (NO HTML yet).
+        # HTML rendering is deferred to render_final.py AFTER Agent generates
+        # and validates insights.json. This ensures the final HTML always
+        # contains a complete AI Executive Summary.
+        import report_v4
+
+        # Compute pre-aggregated report data (window.DATA payload)
+        report_data = report_v4.prepare_report_data(
+            rows=rows,
+            range_label=range_label,
+            export_columns=EXPORT_COLUMNS,
+            lang=getattr(args, 'lang', 'en'),
+        )
+        report_data_path = out_dir / f"report_data_{fname_range}_{ts}.json"
+        report_data_path = _resolve_collision(report_data_path)
+        report_data_path.write_text(
+            json.dumps(report_data, ensure_ascii=False, indent=2, default=str),
+            encoding="utf-8",
+        )
+        print(f"report_data : {report_data_path}")
 
         # Export structured metrics for Agent LLM analysis
-        import report_v4
         metrics_data = report_v4.export_metrics(
             rows=rows,
             export_columns=EXPORT_COLUMNS,
@@ -1355,8 +1370,9 @@ def run(args: argparse.Namespace) -> int:
         )
         print(f"metrics   : {metrics_path}")
 
-        if getattr(args, "open_browser", True):
-            _open_in_browser(html_path)
+        # ★ Hard gate: Agent MUST generate insights and call render_final.py
+        print(f"NEXT_ACTION_REQUIRED: python3 scripts/render_final.py --report-data {report_data_path} --insights <insights_path> --output {out_dir} --lang {getattr(args, 'lang', 'en')}")
+        print(f"TASK_INCOMPLETE: Data exported. Agent must now generate insights.json from metrics, then call render_final.py to produce the final HTML report.")
 
     # Write skill invocation log
     _write_run_log(

package/dist/scripts/render_final.py

@@ -0,0 +1,297 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Render final HTML report with pre-validated AI insights (SKILL.md Step 5 terminal).
+
+This script is the MANDATORY final step for report scenarios (refund/business/auto).
+It performs strict validation of insights.json before rendering HTML, ensuring
+the delivered report always contains a complete AI Executive Summary.
+
+Workflow:
+  1. export_orders.py generates: report_data.json + metrics.json
+  2. Agent reads metrics.json, generates insights.json (LLM analysis)
+  3. THIS SCRIPT validates insights.json structure → renders final HTML
+
+Usage:
+    python3 scripts/render_final.py \
+        --report-data ./out/report_data_xxx.json \
+        --insights ./out/insights.json \
+        --output ./out \
+        --lang en
+
+Prerequisites:
+    - report_data.json: produced by export_orders.py (pre-computed window.DATA payload)
+    - insights.json: produced by Agent per executive_summary_prompt_v2.md
+
+Exit codes:
+    0 = success (HTML rendered and opened)
+    1 = argument/file error
+    2 = insights validation failed (Agent must regenerate)
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from pathlib import Path
+from typing import Any, Dict
+
+# Allow direct execution from scripts/ directory
+THIS_DIR = Path(__file__).resolve().parent
+sys.path.insert(0, str(THIS_DIR))
+
+
+# -------- Insights Validation --------
+
+def _validate_insight_object(insight: Any, preset_key: str) -> list[str]:
+    """Validate a single InsightObject against frontend _validateInsight() rules.
+
+    Returns a list of error messages (empty = valid).
+    """
+    errors: list[str] = []
+    prefix = f"presets.{preset_key}"
+
+    if not insight or not isinstance(insight, dict):
+        errors.append(f"{prefix}: must be a non-null object")
+        return errors
+
+    # summary: required string
+    summary = insight.get("summary")
+    if not isinstance(summary, str) or not summary.strip():
+        errors.append(f"{prefix}.summary: must be a non-empty string")
+
+    # highlights: required array of objects
+    highlights = insight.get("highlights")
+    if not isinstance(highlights, list):
+        errors.append(f"{prefix}.highlights: must be an array")
+    else:
+        for i, h in enumerate(highlights):
+            if not isinstance(h, dict):
+                errors.append(f"{prefix}.highlights[{i}]: must be an object, got {type(h).__name__}")
+                continue
+            if not isinstance(h.get("title"), str):
+                errors.append(f"{prefix}.highlights[{i}].title: must be a string")
+            if not isinstance(h.get("detail"), str):
+                errors.append(f"{prefix}.highlights[{i}].detail: must be a string")
+            sev = h.get("severity")
+            if sev not in ("high", "medium", "low"):
+                errors.append(f"{prefix}.highlights[{i}].severity: must be high/medium/low, got {sev!r}")
+
+    # actions: required array of objects
+    actions = insight.get("actions")
+    if not isinstance(actions, list):
+        errors.append(f"{prefix}.actions: must be an array")
+    else:
+        for i, ac in enumerate(actions):
+            if not isinstance(ac, dict):
+                errors.append(f"{prefix}.actions[{i}]: must be an object, got {type(ac).__name__}")
+                continue
+            if not isinstance(ac.get("text"), str):
+                errors.append(f"{prefix}.actions[{i}].text: must be a string")
+            pri = ac.get("priority")
+            if pri not in ("P0", "P1", "P2"):
+                errors.append(f"{prefix}.actions[{i}].priority: must be P0/P1/P2, got {pri!r}")
+
+    return errors
+
+
+def validate_insights(insights_data: Any) -> tuple[bool, list[str]]:
+    """Validate insights.json structure per executive_summary_prompt_v2.md §8.
+
+    Checks:
+      1. Top-level has "presets" key (dict)
+      2. Each preset value is a valid InsightObject
+      3. At least one non-empty preset exists
+
+    Returns:
+        (is_valid, error_messages)
+    """
+    errors: list[str] = []
+
+    if not isinstance(insights_data, dict):
+        return False, ["Root must be a JSON object"]
+
+    presets = insights_data.get("presets")
+    if not isinstance(presets, dict):
+        return False, ["Root must contain 'presets' key as an object"]
+
+    if not presets:
+        return False, ["'presets' is empty — no analysis generated"]
+
+    for key, value in presets.items():
+        errs = _validate_insight_object(value, key)
+        errors.extend(errs)
+
+    is_valid = len(errors) == 0
+    return is_valid, errors
+
+
+# -------- Rendering --------
+
+def _jinja_env():
+    from jinja2 import Environment, FileSystemLoader
+    return Environment(
+        loader=FileSystemLoader(str(THIS_DIR.parent / "templates")),
+        autoescape=True,
+    )
+
+
+def render_html(report_data: Dict[str, Any], insights_data: Dict[str, Any],
+                out_dir: Path, lang: str = "en") -> Path:
+    """Inject validated insights into report data and render final HTML.
+
+    Returns the path to the generated HTML file.
+    """
+    import report_v4
+
+    # Inject insights into the data payload
+    report_data["agentInsights"] = insights_data
+
+    # Determine output filename from meta
+    range_start = report_data.get("meta", {}).get("range_start", "")
+    range_end = report_data.get("meta", {}).get("range_end", "")
+    range_label = f"{range_start} ~ {range_end}" if range_end else range_start
+
+    # Generate filename
+    ts = time.strftime("%Y%m%d%H%M%S")
+
+    def _safe_fn(s: str) -> str:
+        import re
+        m = re.match(r'^(.*?)([+-]\d{2}:\d{2}|Z)?$', s)
+        if m:
+            base, tz = m.group(1), m.group(2) or ""
+            base = base.replace(":", "").replace("T", "_")
+            tz = tz.replace(":", "").replace("+", "p").replace("-", "m")
+            return base + tz
+        return s.replace(":", "").replace("+", "p").replace("-", "m").replace("T", "_")
+
+    fname_range = f"{_safe_fn(range_start)}_{_safe_fn(range_end)}" if range_end else _safe_fn(range_start)
+    html_path = out_dir / f"miravia_order_report_{fname_range}_{ts}.html"
+
+    # Avoid collision
+    if html_path.exists():
+        for i in range(1, 100):
+            cand = html_path.parent / f"{html_path.stem}_{i}{html_path.suffix}"
+            if not cand.exists():
+                html_path = cand
+                break
+
+    # Render via report_v4.render_from_data()
+    jinja_env = _jinja_env()
+    report_v4.render_from_data(report_data, html_path, range_label, jinja_env, lang)
+    return html_path
+
+
+def _open_in_browser(html_path: Path) -> None:
+    """Open HTML report in default browser (best-effort)."""
+    import webbrowser
+    import subprocess
+    import platform
+
+    url = html_path.resolve().as_uri()
+    try:
+        if webbrowser.open(url, new=2):
+            print(f"opened    : {url}")
+            return
+    except Exception as e:
+        print(f"warning: webbrowser.open failed: {e}", file=sys.stderr)
+    try:
+        sysname = platform.system()
+        if sysname == "Darwin":
+            subprocess.Popen(["open", str(html_path)])
+        elif sysname == "Windows":
+            os.startfile(str(html_path))  # type: ignore[attr-defined]
+        else:
+            subprocess.Popen(["xdg-open", str(html_path)])
+        print(f"opened    : {url}")
+    except Exception as e:
+        print(f"warning: failed to open browser ({e}); open manually: {html_path}",
+              file=sys.stderr)
+
+
+# -------- CLI --------
+
+def main() -> int:
+    p = argparse.ArgumentParser(
+        prog="render_final",
+        description=(
+            "Render final HTML report with validated AI insights. "
+            "This is the terminal step of the report pipeline — HTML is only "
+            "produced after insights pass structural validation."
+        ),
+    )
+    p.add_argument("--report-data", required=True,
+                   help="Path to report_data JSON (from export_orders.py)")
+    p.add_argument("--insights", required=True,
+                   help="Path to insights.json (Agent-generated)")
+    p.add_argument("--output", default="./out",
+                   help="Output directory for the HTML file")
+    p.add_argument("--lang", default="en", choices=["en", "es", "it", "zh"],
+                   help="Report language")
+    p.add_argument("--no-open", dest="open_browser", action="store_false",
+                   default=True, help="Do not auto-open browser after render")
+    args = p.parse_args()
+
+    # 1. Load report_data
+    report_data_path = Path(args.report_data).expanduser().resolve()
+    if not report_data_path.exists():
+        print(f"error: report_data file not found: {report_data_path}", file=sys.stderr)
+        return 1
+    try:
+        report_data = json.loads(report_data_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as e:
+        print(f"error: failed to read report_data: {e}", file=sys.stderr)
+        return 1
+
+    # 2. Load insights
+    insights_path = Path(args.insights).expanduser().resolve()
+    if not insights_path.exists():
+        print(f"error: insights file not found: {insights_path}", file=sys.stderr)
+        return 1
+    try:
+        insights_data = json.loads(insights_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        print(f"error: insights.json is not valid JSON: {e}", file=sys.stderr)
+        print("       Agent must regenerate insights.json from scratch.", file=sys.stderr)
+        return 2
+
+    # 3. Validate insights structure (BLOCKING — invalid insights = no HTML)
+    is_valid, errors = validate_insights(insights_data)
+    if not is_valid:
+        print("error: insights.json failed structural validation:", file=sys.stderr)
+        for err in errors[:10]:  # show first 10 errors
+            print(f"  - {err}", file=sys.stderr)
+        if len(errors) > 10:
+            print(f"  ... and {len(errors) - 10} more errors", file=sys.stderr)
+        print("\nAgent must fix insights.json and retry. See executive_summary_prompt_v2.md §8.",
+              file=sys.stderr)
+        return 2
+
+    print(f"insights  : validated OK ({len(insights_data.get('presets', {}))} presets)")
+
+    # 4. Render final HTML
+    out_dir = Path(args.output).expanduser().resolve()
+    out_dir.mkdir(parents=True, exist_ok=True)
+    html_path = render_html(report_data, insights_data, out_dir, lang=args.lang)
+    print(f"report    : {html_path}")
+
+    # 5. Validate rendering (lightweight check: file exists and has reasonable size)
+    if html_path.exists():
+        size_kb = html_path.stat().st_size / 1024
+        if size_kb < 10:
+            print(f"warning: HTML file suspiciously small ({size_kb:.1f} KB)", file=sys.stderr)
+        print(f"RENDER_CHECK: OK (size={size_kb:.0f}KB)")
+    else:
+        print("RENDER_CHECK: FAIL (file not created)", file=sys.stderr)
+        return 1
+
+    # 6. Open in browser
+    if args.open_browser:
+        _open_in_browser(html_path)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/dist/scripts/report_v4.py

@@ -1608,8 +1608,15 @@ _PRESET_DAYS = [7, 30, 90, 180, 365]
 
 def render(rows: List[Dict[str, Any]], out_path: Path,
            range_label: str, jinja_env, export_columns,
-           default_max_orders: int, lang: str = "en") -> Path:
-    """Render v4 unified dashboard HTML with embedded AI-generated insights."""
+           default_max_orders: int, lang: str = "en",
+           insights: Any = None) -> Path:
+    """Render v4 unified dashboard HTML with embedded AI-generated insights.
+
+    Args:
+        insights: Optional pre-validated insights dict. If provided, it is
+                  embedded directly into window.DATA.agentInsights, eliminating
+                  the need for post-hoc inject_insights.py injection.
+    """
     import pandas as pd
 
     t = get_translations(lang)
@@ -1638,11 +1645,11 @@ def render(rows: List[Dict[str, Any]], out_path: Path,
             else:
                 preset_data[str(days)] = all_dims  # same as all, share reference
 
-    # ---- agentInsights placeholder (LLM injects real content via inject_insights.py) ----
-    # The rule-engine generate_insights() has been retired — only LLM-generated
-    # multi-language insights are used. The empty placeholder ensures the HTML
-    # renders gracefully until inject_insights.py overwrites this field.
-    agent_insights = {"presets": {}}
+    # ---- agentInsights: use provided insights or empty placeholder ----
+    if insights and isinstance(insights, dict):
+        agent_insights = insights
+    else:
+        agent_insights = {"presets": {}}
 
     # ---- assemble data payload ----
     range_start = range_label.split(" ~ ")[0] if " ~ " in range_label else range_label
@@ -1664,6 +1671,78 @@ def render(rows: List[Dict[str, Any]], out_path: Path,
         **all_dims,
     }
 
+    return render_from_data(data, out_path, range_label, jinja_env, lang)
+
+
+def prepare_report_data(rows: List[Dict[str, Any]], range_label: str,
+                        export_columns, lang: str = "en") -> Dict[str, Any]:
+    """Compute report data payload WITHOUT rendering HTML.
+
+    Returns the complete window.DATA dict (minus agentInsights) that can be
+    serialized to JSON and later passed to render_from_data() along with
+    validated insights.
+
+    This enables the two-phase workflow:
+      Phase 1: export_orders.py → rows → prepare_report_data() → report_data.json + metrics.json
+      Phase 2: Agent generates insights.json
+      Phase 3: render_final.py → validates insights + render_from_data() → final HTML
+    """
+    import pandas as pd
+
+    t = get_translations(lang)
+
+    df = pd.DataFrame(rows, columns=export_columns) if rows else pd.DataFrame(columns=export_columns)
+    currency = _common_currency(df)
+    overall = _compute_overall(df)
+
+    all_dims = _compute_dims(df, currency, t=t)
+    preset_data: Dict[str, Any] = {"0": all_dims}
+
+    if not df.empty:
+        dates = pd.to_datetime(df["created_at"], errors="coerce")
+        max_date = dates.max()
+        for days in _PRESET_DAYS:
+            cutoff = max_date.normalize() - pd.Timedelta(days=days - 1)
+            subset = df[dates >= cutoff]
+            if len(subset) < len(df):
+                preset_data[str(days)] = _compute_dims(subset, currency, t=t)
+            else:
+                preset_data[str(days)] = all_dims
+
+    range_start = range_label.split(" ~ ")[0] if " ~ " in range_label else range_label
+    range_end = range_label.split(" ~ ")[1] if " ~ " in range_label else ""
+
+    return {
+        "meta": {
+            "range_start": range_start,
+            "range_end": range_end,
+            "generated_at": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+            "currency": currency,
+            "total_orders": overall["orders"],
+            "total_items": overall["items"],
+            "buyer_id_available": _check_buyer_id_available(df),
+        },
+        "dailyData": _build_daily_data(df, range_start=range_start, range_end=range_end),
+        "presetData": preset_data,
+        "agentInsights": {"presets": {}},  # placeholder; replaced at render time
+        # Top-level dimensional fields (backward compat)
+        **all_dims,
+    }
+
+
+def render_from_data(data: Dict[str, Any], out_path: Path,
+                     range_label: str, jinja_env,
+                     lang: str = "en") -> Path:
+    """Render HTML from a pre-computed data payload.
+
+    This is the final rendering step. Accepts an already-assembled data dict
+    (from prepare_report_data or render) and produces the HTML file.
+    If data['agentInsights'] contains validated insights, they will be embedded
+    directly — no post-hoc injection needed.
+    """
+    t = get_translations(lang)
+    currency = data.get("meta", {}).get("currency", "EUR")
+
     # ---- load static assets for inline embedding ----
     _static_dir = Path(__file__).resolve().parent.parent / "static"
     _chartjs_path = _static_dir / "chart.umd.min.js"

package/dist/templates/report_v4.html

@@ -974,9 +974,18 @@ function switchLang(lang){
   document.documentElement.lang=T.lang_code||lang;
   document.title=T.page_title||document.title;
   // Update all static elements with data-i18n attribute
+  // Preserve child elements (e.g. ai-badge spans) by only updating text nodes
   document.querySelectorAll('[data-i18n]').forEach(el=>{
     const key=el.dataset.i18n;
-    if(T[key]!=null)el.textContent=T[key];
+    if(T[key]==null)return;
+    if(el.children.length>0){
+      // Element has child elements — only replace the leading text node
+      const first=el.firstChild;
+      if(first&&first.nodeType===3){first.textContent=T[key]+' ';}
+      else{el.insertBefore(document.createTextNode(T[key]+' '),el.firstChild);}
+    }else{
+      el.textContent=T[key];
+    }
   });
   // Re-init time filter buttons & platform filters with new labels
   initTF();initPlatformFilters();

package/lib/build-zip.js

@@ -0,0 +1,91 @@
+/**
+ * build-zip.js — Generate miravia-order-report.zip for OSS upload.
+ *
+ * Usage:  node lib/build-zip.js
+ *
+ * Steps:
+ *   1. Run build-dist.js to regenerate dist/ (with VERSION stamp)
+ *   2. Zip dist/ contents → <workspace>/dist/miravia-order-report.zip
+ *
+ * This script is the SINGLE source of truth for zip packaging.
+ * Do NOT manually run zip commands — always use this script.
+ */
+
+'use strict';
+
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+// ---------- Paths ----------
+const LIB_DIR = __dirname;
+const PACKAGE_ROOT = path.join(LIB_DIR, '..');
+const DIST_DIR = path.join(PACKAGE_ROOT, 'dist');
+
+// Workspace root: traverse up to find pom.xml at project root
+function findWorkspaceRoot(start) {
+  let dir = start;
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, 'pom.xml')) && fs.existsSync(path.join(dir, 'ai-skill'))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  // Fallback: 10 levels up from npm-package/lib
+  return path.resolve(PACKAGE_ROOT, '..', '..', '..', '..', '..', '..', '..', '..');
+}
+
+const WORKSPACE_ROOT = findWorkspaceRoot(PACKAGE_ROOT);
+const OUTPUT_DIR = path.join(WORKSPACE_ROOT, 'dist');
+const OUTPUT_ZIP = path.join(OUTPUT_DIR, 'miravia-order-report.zip');
+
+// ---------- Step 1: Build dist/ ----------
+console.log('━━━ Step 1: Building dist/ via build-dist.js ━━━\n');
+execSync(`node ${path.join(LIB_DIR, 'build-dist.js')}`, { stdio: 'inherit' });
+
+// Verify dist/ exists and has VERSION
+if (!fs.existsSync(path.join(DIST_DIR, 'VERSION'))) {
+  console.error('\n✗ ERROR: dist/VERSION not found after build. Aborting.');
+  process.exit(1);
+}
+
+// ---------- Step 2: Create zip ----------
+console.log('\n━━━ Step 2: Creating zip package ━━━\n');
+
+// Ensure output directory exists
+if (!fs.existsSync(OUTPUT_DIR)) {
+  fs.mkdirSync(OUTPUT_DIR, { recursive: true });
+}
+
+// Remove old zip if exists
+if (fs.existsSync(OUTPUT_ZIP)) {
+  fs.unlinkSync(OUTPUT_ZIP);
+}
+
+// Create zip from dist/ contents (no wrapping folder, flat structure)
+try {
+  execSync(`zip -r "${OUTPUT_ZIP}" . -x "*.DS_Store"`, {
+    cwd: DIST_DIR,
+    stdio: 'inherit',
+  });
+} catch (e) {
+  console.error('\n✗ ERROR: zip command failed. Ensure zip is installed.');
+  process.exit(1);
+}
+
+// ---------- Step 3: Verify ----------
+console.log('\n━━━ Step 3: Verification ━━━\n');
+
+const stat = fs.statSync(OUTPUT_ZIP);
+const sizeKB = (stat.size / 1024).toFixed(1);
+const version = fs.readFileSync(path.join(DIST_DIR, 'VERSION'), 'utf8').trim();
+
+console.log(`  ✓ Output:  ${OUTPUT_ZIP}`);
+console.log(`  ✓ Size:    ${sizeKB} KB`);
+console.log(`  ✓ Version: ${version}`);
+
+// ---------- Step 4: Clean up dist/ ----------
+fs.rmSync(DIST_DIR, { recursive: true });
+console.log(`  ✓ Cleaned: dist/ removed`);
+
+console.log(`\n✔ Done. Ready to upload to OSS.`);

package/lib/installer.js

@@ -28,6 +28,9 @@ const AGENT_DIRS = {
     path.join(process.cwd(), '.qoder', 'skills'),
     path.join(os.homedir(), '.qoder', 'skills'),
   ],
+  qoderwork: [
+    path.join(os.homedir(), '.qoderwork', 'skills'),
+  ],
   cursor: [
     path.join(process.cwd(), '.cursor', 'skills'),
     path.join(os.homedir(), '.cursor', 'skills'),
@@ -36,8 +39,16 @@ const AGENT_DIRS = {
     path.join(os.homedir(), '.claude', 'skills'),
   ],
   codex: [
+    path.join(os.homedir(), '.agents', 'skills'),
+    path.join(process.cwd(), '.agents', 'skills'),
+  ],
+  antigravity: [
+    path.join(os.homedir(), '.agents', 'skills'),
     path.join(process.cwd(), '.agents', 'skills'),
+  ],
+  opencode: [
     path.join(os.homedir(), '.agents', 'skills'),
+    path.join(process.cwd(), '.agents', 'skills'),
   ],
   gemini: [
     path.join(process.cwd(), '.gemini', 'skills'),
@@ -55,6 +66,8 @@ function getAllCandidateDirs() {
     // Cross-platform standard (highest priority)
     path.join(process.cwd(), '.agents', 'skills'),
     path.join(os.homedir(), '.agents', 'skills'),
+    // QoderWork user-global skill directory (UI panel scans here)
+    path.join(os.homedir(), '.qoderwork', 'skills'),
     // Platform-specific directories
     path.join(process.cwd(), '.qoder', 'skills'),
     path.join(process.cwd(), '.cursor', 'skills'),
@@ -101,10 +114,38 @@ function detectSkillDir(flags) {
     }
   }
 
-  // Fresh install: default to the cross-platform standard directory (.agents/skills)
+  // Fresh install: detect runtime environment and choose the appropriate default.
+  // Key concern: avoid installing into transient sandbox/workspace directories that
+  // the platform's UI/scanner cannot discover.
+
+  // QoderWork: CWD is inside ~/.qoderwork/workspace/<session>/ (ephemeral sandbox).
+  // Install to ~/.qoderwork/skills/ so the UI panel can find it.
+  const qoderworkWsPrefix = path.join(os.homedir(), '.qoderwork', 'workspace');
+  if (process.cwd().startsWith(qoderworkWsPrefix)) {
+    return path.join(os.homedir(), '.qoderwork', 'skills');
+  }
+
+  // Cloud sandbox detection (Codex / Antigravity / OpenCode):
+  // These run inside ephemeral containers. ~/.agents/skills is correct for the session
+  // but won't persist. Prefer project-level .agents/skills so user can commit to repo.
+  // Detect cloud sandbox: CWD is not under user's real home, or typical cloud workspace roots.
+  const cwd = process.cwd();
+  const home = os.homedir();
+  const isCloudSandbox = (
+    cwd === '/workspace' || cwd.startsWith('/workspace/') ||
+    cwd === '/home/user' || cwd.startsWith('/home/user/') ||
+    process.env.CODEX_SANDBOX === '1' ||
+    process.env.CLOUD_ENVIRONMENT === 'true'
+  );
+  if (isCloudSandbox) {
+    // Project-level: persists if user commits to git
+    return path.join(cwd, '.agents', 'skills');
+  }
+
+  // Local environment (Qoder, Cursor, Claude Code, etc.):
+  // Default to user-global ~/.agents/skills (cross-platform standard).
   // This is the universal convention supported by Codex, Gemini, Antigravity, OpenCode, etc.
-  // Do NOT fall back to .qoder/skills or .cursor/skills just because they exist.
-  return path.join(process.cwd(), '.agents', 'skills');
+  return path.join(home, '.agents', 'skills');
 }
 
 /**
@@ -314,7 +355,7 @@ function install(flags) {
   }
 
   console.log('\n\x1b[1m📋 Next steps:\x1b[0m');
-  console.log('  1. Open your AI Agent (Qoder / Cursor / Claude Code)');
+  console.log('  1. Open your AI Agent (Qoder / QoderWork / Cursor / Claude Code / Codex / Antigravity)');
   console.log('  2. Say: "authorize miravia skill"');
   console.log('  3. Complete browser authorization');
   console.log('  4. Then ask: "export last week Miravia orders"\n');
@@ -345,10 +386,11 @@ function upgrade(flags) {
   let upgraded = 0;
   for (const skillDir of skillDirs) {
     const targetDir = path.join(skillDir, SKILL_NAME);
-    const agentLabel = skillDir.includes('.qoder') ? 'Qoder'
+    const agentLabel = skillDir.includes('.qoderwork') ? 'QoderWork'
+      : skillDir.includes('.qoder') ? 'Qoder'
       : skillDir.includes('.cursor') ? 'Cursor'
       : skillDir.includes('.claude') ? 'Claude'
-      : skillDir.includes('.agents') ? 'Codex'
+      : skillDir.includes('.agents') ? 'Codex/Antigravity/OpenCode'
       : skillDir.includes('.gemini') ? 'Gemini' : 'Unknown';
     const scope = skillDir.startsWith(os.homedir() + path.sep + '.') ? 'user' : 'project';
 
@@ -415,7 +457,7 @@ Commands:
 
 Options:
   --target <path>   Specify custom installation directory
-  --agent <type>    Agent type: qoder | cursor | claude | codex | gemini
+  --agent <type>    Agent type: qoder | qoderwork | cursor | claude | codex | antigravity | opencode | gemini
   --no-venv         Skip venv creation, use system pip
   -v, --version     Show version
   -h, --help        Show this help
@@ -423,13 +465,17 @@ Options:
 Notes:
   'upgrade' without --agent will update ALL detected agent platforms.
   Use --agent to limit upgrade to a single platform.
+  Cloud sandboxes (Codex/Antigravity): skill installed to project .agents/skills/ for git persistence.
 
 Supported platforms:
-  Qoder        (.qoder/skills)
-  Cursor       (.cursor/skills)
-  Claude Code  (~/.claude/skills)
-  OpenAI Codex (.agents/skills)
-  Google Gemini (.gemini/skills)
+  Qoder              (.qoder/skills)
+  QoderWork          (~/.qoderwork/skills)
+  Cursor             (.cursor/skills)
+  Claude Code        (~/.claude/skills)
+  OpenAI Codex       (~/.agents/skills)
+  Google Antigravity (~/.agents/skills)
+  OpenCode           (~/.agents/skills)
+  Google Gemini      (.gemini/skills)
 
 Examples:
   npx ${PKG.name} install

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miraiva_test/miravia-order-report",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Miravia Order Report Skill installer — one command to install the Miravia order export & analytics skill into any AI Agent (Qoder / Cursor / Claude Code).",
   "bin": {
     "miravia-skill": "./bin/cli.js"
@@ -12,7 +12,8 @@
   ],
   "scripts": {
     "prepublishOnly": "node lib/build-dist.js",
-    "postpublish": "node lib/clean-dist.js"
+    "postpublish": "node lib/clean-dist.js",
+    "build:zip": "node lib/build-zip.js"
   },
   "keywords": [
     "miravia",