@overscore/cli 0.11.12 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overscore/cli",
-  "version": "0.11.12",
+  "version": "0.12.0",
   "description": "CLI for deploying Overscore dashboards and publishing analyses",
   "bin": {
     "overscore": "dist/index.js"

package/templates/analysis/.claude/CLAUDE.md

@@ -99,7 +99,7 @@ npx @overscore/cli analysis publish
 
 This uploads `report.html` and the entire bundle (this CLAUDE.md, `analysis-log.md`, the `.claude/` tree, etc.) to Overscore. The analysis becomes available at `https://<project>.overscore.dev/analysis/{{SLUG}}`. Re-publishing overwrites the previous version. **Always preview `report.html` in a browser and get the user's approval before publishing.**
 
-After publish succeeds and you've shared the link, invoke the **`save-knowledge`** skill. It shows what's already in the context files, proposes specific additions from this session, and lets the user accept or adjust before anything is written. Don't skip it — it's a short conversation, and it's what makes the next session start informed instead of blank.
+**Immediately after the publish command exits successfully and you've shared the link**, invoke the **`save-knowledge`** skill. This is mandatory, not optional. Do not wait for the user to ask "save what we learned" — the debrief always runs after a successful publish. If nothing new came up this session, the skill will say so in one line and you're done.
 
 ## When the user wants to turn this into a dashboard
 
@@ -110,7 +110,8 @@ Analyses are static. If the user asks to "make this a real dashboard" or "turn t
 The following files in `.claude/rules/` load automatically when you touch matching files — you don't need to read them now:
 
 - **`sql-style.md`** — BigQuery dialect and SQL formatting (loads when editing SQL or `analysis-log.md`)
-- **`report-html.md`** — Self-contained HTML rules and dark-theme spec (loads when editing `report.html`)
-- **`report-components.md`** — Copy-paste HTML/SVG component snippets: KPI cards, charts, tables, heatmaps (loads when editing `report.html`)
+- **`report-html.md`** — Self-contained HTML rules (theme-agnostic) (loads when editing `report.html`)
+- **`report-components.md`** — Optional copy-paste snippets in Overscore's dark theme; skip if your aesthetic differs (loads when editing `report.html`)
 - **`analysis-methodology.md`** — Investigation loop, when to ask vs query (loads when editing `analysis-log.md`)
+- **`.claude/skills/customize-aesthetic/SKILL.md`** — drives intentional aesthetic choices for the report
 - **`knowledge/INDEX.md`** — Project knowledge base catalog (auto-loaded every session via @import above)

package/templates/analysis/.claude/rules/report-components.md

@@ -3,9 +3,13 @@ paths:
   - "report.html"
 ---
 
-# Report components — copy-paste snippets
+# Report components — optional starter snippets
 
-These are ready-made HTML/CSS/SVG components for `report.html`. Each follows the Overscore dark theme from `report-html.md`. Copy the CSS into your `<style>` block, paste the HTML where needed, and fill in real data.
+These are ready-made HTML/CSS/SVG components for `report.html` in **one specific aesthetic** — Overscore's dark theme (near-black background, white text, violet/blue/emerald/amber accents). They're useful when you want polished components fast and the analysis aesthetic happens to match.
+
+**This file is not the rule for how reports should look.** If the analysis is going in a different direction (editorial print, high-contrast light, warm earth tones, terminal-dense, brand-matched, etc.), skip this file entirely — write components from scratch following the structural and information-design rules in `report-html.md` and `data-viz.md`.
+
+Run the `customize-aesthetic` skill to pick a distinctive direction before writing the report. If that direction matches dark/violet, the snippets below give you a head start. Otherwise, they're just one example of how the parts can fit together.
 
 ---
 

package/templates/analysis/.claude/rules/report-html.md

@@ -9,21 +9,23 @@ paths:
 
 ## Hard rules
 
-- **Inline all CSS.** No `<link rel="stylesheet">`, no Tailwind CDN, no Google Fonts. Use a single `<style>` block in the `<head>`.
+- **Inline all CSS.** No `<link rel="stylesheet">`, no Tailwind CDN, no Google Fonts (or use a `data:` URI / system stack). Use a single `<style>` block in the `<head>`.
 - **Bake the data into the HTML.** No `fetch()`, no `XMLHttpRequest`, no API calls. The numbers must be visible to anyone who opens the file with no logins, no tokens, no broken external dependencies.
 - **Charts are inline.** Inline SVG is the safest option. Embedded base64 PNGs are OK. A self-contained chart library (Recharts/D3 from CDN) is acceptable **only if the data is already baked into the page** and the script tag is inline-loaded — but inline SVG is preferred because it survives indefinitely.
 - **No `useQuery`, no `@overscore/client`, no React.** This is a static HTML file, not a React app.
 
-## Dark theme — Overscore brand
+## Aesthetic direction
 
-Match the Overscore visual style:
+This file does **not** prescribe a visual style. Pick one intentionally with the `customize-aesthetic` skill — analyses are share-once artifacts where distinctive design matters more than consistency.
 
-- **Background:** `#0a0a0f` (near-black)
-- **Cards:** `rgba(255,255,255,0.03)` background with `1px solid rgba(255,255,255,0.06)` border, generous padding, `border-radius: 16px`
-- **Text:** `#fff` for headlines and numbers, `rgba(255,255,255,0.6)` for body, `rgba(255,255,255,0.4)` for secondary
-- **Accents:** violet `#8b5cf6`, blue `#3b82f6`, emerald `#10b981`, amber `#f59e0b`
-- **Font:** `-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif`
-- **Spacing:** generous — `padding: 4rem 2rem` on the body, `max-width: 900px`, `margin: 0 auto` to center
+A polished report commits to:
+- **A tone** (editorial print, high-contrast minimal, warm earth tones, terminal-dense, etc.)
+- **Typography** (a specific display face + body face — not "system-ui" by default)
+- **A palette** (named hex codes, one or two saturated accents, the rest muted)
+
+If `this-analysis.md` has a `## Visual style` section, use it. Otherwise, run the `customize-aesthetic` skill before writing the report skeleton.
+
+Avoid the AI default: `#0a0a0f` background, `rgba(255,255,255,0.6)` text, violet/blue accents on glassmorphic cards. It's recognizable as "generated."
 
 ## Structure
 
@@ -48,38 +50,49 @@ A good analysis report has these sections in order:
   <title>The headline finding goes here</title>
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <style>
+    :root {
+      /* Replace with palette from this-analysis.md ## Visual style */
+      --bg: #fafaf7;
+      --fg: #1a1a1a;
+      --muted: rgba(26,26,26,0.55);
+      --subtle: rgba(26,26,26,0.08);
+      --accent: #3a3a3a;
+      --card: rgba(0,0,0,0.02);
+    }
     body {
-      background: #0a0a0f;
-      color: #fff;
-      font-family: -apple-system, BlinkMacSystemFont, sans-serif;
+      background: var(--bg);
+      color: var(--fg);
+      font-family: ui-serif, Georgia, serif; /* Replace with your chosen face */
       max-width: 900px;
       margin: 0 auto;
       padding: 4rem 2rem;
       line-height: 1.6;
     }
     .card {
-      background: rgba(255,255,255,0.03);
-      border: 1px solid rgba(255,255,255,0.06);
-      border-radius: 16px;
+      background: var(--card);
+      border: 1px solid var(--subtle);
+      border-radius: 12px;
       padding: 1.5rem;
       margin: 1.5rem 0;
     }
-    .kpi { font-size: 2.5rem; font-weight: 600; }
-    .label { color: rgba(255,255,255,0.4); font-size: 0.875rem; text-transform: uppercase; letter-spacing: 0.05em; }
+    .kpi { font-size: 2.5rem; font-weight: 600; font-feature-settings: "tnum"; }
+    .label { color: var(--muted); font-size: 0.875rem; text-transform: uppercase; letter-spacing: 0.05em; }
     h1, h2, h3 { font-weight: 600; }
     h1 { font-size: 2rem; margin-bottom: 0.5rem; }
-    .footer { margin-top: 4rem; color: rgba(255,255,255,0.3); font-size: 0.75rem; }
+    .footer { margin-top: 4rem; color: var(--muted); font-size: 0.75rem; }
   </style>
 </head>
 <body>
   <h1>Headline finding here</h1>
-  <p style="color: rgba(255,255,255,0.6);">Executive summary in 2-3 sentences.</p>
+  <p style="color: var(--muted);">Executive summary in 2-3 sentences.</p>
   <!-- KPI cards, charts, conclusions, etc. -->
   <div class="footer">Generated YYYY-MM-DD · {{TITLE}}</div>
 </body>
 </html>
 ```
 
+The CSS variables are placeholders — replace them with the palette and fonts from `this-analysis.md`. The skeleton above is in a neutral editorial direction; pick what fits the analysis.
+
 **Mobile responsiveness.** Reports are often opened on phones from Slack links. The skeleton's `max-width: 900px` and viewport meta tag handle the basics, but also:
 - Use `clamp()` or media queries for KPI font sizes (`font-size: clamp(1.5rem, 5vw, 2.5rem)`) so they don't overflow on 375px screens.
 - KPI card grids should wrap: `display: grid; grid-template-columns: repeat(auto-fit, minmax(140px, 1fr))`.

package/templates/analysis/.claude/skills/customize-aesthetic/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: customize-aesthetic
+description: Drives intentional visual design choices for an Overscore analysis report. Use when the user wants a custom look, says "redesign this", "change the theme", "make it [adjective]", or when the start-analysis interview reaches the aesthetic step.
+---
+
+# Customize aesthetic
+
+Most AI-generated reports look the same — dark with violet accents, system fonts, glassmorphic cards, generic everything. Resist that default. A report that gets reopened weeks later commits to a specific aesthetic direction.
+
+## When to invoke
+
+- The user asks to "redesign", "restyle", "make it [adjective]", or says they don't like the current look
+- The `start-analysis` interview has reached the aesthetic step
+- The user describes a tone, brand, or reference ("like a McKinsey deck", "newspaper feel", "warm earth tones")
+
+## What this skill does NOT change
+
+The data visualization rules in `.claude/rules/data-viz.md` apply regardless of aesthetic:
+- No pie charts, no 3D, no dual y-axes
+- KPI cards with comparisons (green up, red down)
+- 5-9 components max
+- Bars start at zero
+- Mobile-responsive at 375px
+
+The report structural rules in `.claude/rules/report-html.md` also stand: inline CSS, baked data, no network calls, self-contained.
+
+Aesthetic is the *visual treatment* — typography, palette, density, surface treatment. The *information design* and the *technical envelope* are both settled.
+
+## How to choose a direction
+
+Before changing any code, get clear answers to three things:
+
+1. **Tone in one phrase** — "editorial print", "high-contrast minimal", "warm earth tones", "brutalist data", "Bloomberg terminal", "Notion clean", "Stripe modern". One phrase, not a list of adjectives.
+2. **Typography** — serif/sans/mono? Display face? Body weight? Numbers in tabular figures? Don't accept "Inter" as an answer — that's the default that produces same-looking output. If the user shrugs, suggest a specific face that fits the tone (e.g., Söhne Mono for terminal, Fraunces for editorial).
+3. **Palette** — one or two saturated accents, the rest muted. Pick *named* colors (paper white #fafaf7, ink charcoal #1a1a1a, terracotta #c45a3e) so they read as a system, not as defaults.
+
+If the user can't answer, suggest 2-3 distinct directions with a one-line characterization each. Pick one before writing code.
+
+## Common failure modes
+
+- Reaching for `#0a0a0f` + white text as a "neutral" default — that's the AI default with the brand stripped off, not a distinct aesthetic
+- Mixing two directions ("modern but also editorial") — pick one
+- Adding glassmorphic blur and backdrop filters by default — that's 2023 SaaS, not a choice
+
+## After picking a direction
+
+Write the aesthetic decision to `this-analysis.md` under a `## Visual style` heading. Include:
+- The tone phrase
+- The typography choice (font families, key sizes)
+- The palette (with hex codes)
+- Any density and surface rules (spacing, borders)
+
+This keeps future sessions consistent without re-deciding the same choices.
+
+---
+
+Inspired by Anthropic's `frontend-design` skill (github.com/anthropics/claude-code, MIT-licensed) — adapted for Overscore's analysis report context.

package/templates/analysis/.claude/skills/start-analysis/SKILL.md

@@ -1,11 +1,6 @@
 ---
 name: start-analysis
 description: Interviews the user before querying data at the start of a new Overscore analysis. Captures the real question, known tables, success criteria, hypotheses, time window, and data quirks, then writes this-analysis.md and proposes a query plan for approval. Use when this-analysis.md is empty, or when the user says "investigate", "look into", or "analyze" something for the first time.
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash(npx @overscore/cli query run *)
 ---
 
 # Starting an analysis the right way
@@ -22,7 +17,7 @@ This skill exists to make sure that conversation happens before any SQL runs.
 
 Do NOT invoke this on a re-pull of an existing analysis with prior queries logged — that's a continuation, not a fresh start, and the prior log already has the context.
 
-## The interview — 6 questions, 2 minutes
+## The interview — 7 questions, 2 minutes
 
 Read `interview-template.md` for the literal prompts. The interview covers:
 
@@ -32,8 +27,9 @@ Read `interview-template.md` for the literal prompts. The interview covers:
 4. **Hypotheses** — ask the user for 1-3 things they suspect might be true. Even rough hypotheses give you a query plan to test against.
 5. **Time window and filters** — ask what time range, what cohort, what to include/exclude. These are the most common sources of wasted queries when wrong.
 6. **Anything else weird** — ask "is there anything I should know about this data?" Users usually surface 1-2 known quirks ("dates before 2024 are unreliable," "we have a test_user flag we exclude").
+7. **Aesthetic direction for the final report** — ask if they have a tone in mind (editorial print, high-contrast minimal, warm earth tones, terminal-dense, brand-matched) or want you to pick one. Distinctive design matters more on share-once reports than on internal dashboards. If they name a direction, invoke the `customize-aesthetic` skill when you start `report.html`. If they're open, pick one yourself before writing the report — don't default to the AI dark+violet look.
 
-Ask these one or two at a time conversationally — don't dump all 6 at once like a form. The user will respond more openly to a real conversation.
+Ask these one or two at a time conversationally — don't dump all 7 at once like a form. The user will respond more openly to a real conversation.
 
 ## After the interview
 
@@ -47,6 +43,7 @@ Ask these one or two at a time conversationally — don't dump all 6 at once lik
    - **Success Criteria** — quote the user on what "done" looks like
    - **Time Window & Filters** — the date range, cohort, what to include/exclude
    - **Known Quirks** — anything about the data the user flagged upfront
+   - **Visual style** (if the user named an aesthetic direction): tone phrase, typography, palette with hex codes. See the `customize-aesthetic` skill. Skip if not specified yet — fill in when you start the report.
 
    This is the context file that loads automatically every future session. Don't skip it.
 

package/templates/analysis/.claude/skills/start-analysis/interview-template.md

@@ -24,8 +24,12 @@ These are the literal questions to ask the user during the start-analysis interv
 
 ## 6. Anything weird about this data
 
-> Last one: is there anything about this data I should know upfront? Quirks, known issues, things that look suspicious but are actually fine, conventions you use? Those are the things that bite if I find out about them three queries in instead of right now.
+> Is there anything about this data I should know upfront? Quirks, known issues, things that look suspicious but are actually fine, conventions you use? Those are the things that bite if I find out about them three queries in instead of right now.
+
+## 7. Aesthetic direction for the report
+
+> Last one — when we eventually write the report, any tone in mind? Examples: editorial print, high-contrast minimal, warm earth tones, terminal-dense, your company brand. If you have a reference (a deck, a blog post, an article you liked the look of), tell me. Or just say "pick one for me" and I'll commit to a distinctive direction. (We don't default to the generic AI dark-with-violet look — it reads as "generated.") You can answer this now or when we start the report; either is fine.
 
 ---
 
-After all 6 answers, summarize back what you heard and ask the user to confirm. Then write the initial entry in `analysis-log.md` and propose the query plan.
+After all 7 answers, summarize back what you heard and ask the user to confirm. Then write the initial entry in `analysis-log.md` and propose the query plan. If the user named an aesthetic direction, note it in `this-analysis.md` so it's ready when you start `report.html` (the `customize-aesthetic` skill will fire then).

package/templates/analysis/report.html

@@ -5,9 +5,12 @@
 <title>{{TITLE}}</title>
 <meta name="viewport" content="width=device-width, initial-scale=1" />
 <style>
-  body { background: #0a0a0f; color: #fff; font-family: -apple-system, BlinkMacSystemFont, sans-serif; padding: 4rem 2rem; max-width: 800px; margin: 0 auto; }
+  /* Starter — replace with the palette and fonts from this-analysis.md ## Visual style.
+     Don't default to the AI look (dark + violet + glassmorphic). Pick a distinctive
+     direction first; see the customize-aesthetic skill. */
+  body { font-family: ui-sans-serif, system-ui, sans-serif; padding: 4rem 2rem; max-width: 800px; margin: 0 auto; line-height: 1.6; }
   h1 { font-weight: 600; }
-  p { color: rgba(255,255,255,0.6); }
+  p { color: #555; }
 </style>
 </head>
 <body>