@squadbase/vantage 0.7.0 → 0.7.1-dev1.01a6413

package/docs/en/agent-skills.md

@@ -1,6 +1,6 @@
 # Agents and Skills
 
-> The Claude Code agent skills bundled with Vantage. Place them into your app with vantage add skill (the project root by default, or anywhere via --dir, e.g. .claude/skills) to teach agents step-by-step workflows.
+> The Claude Code agent skills bundled with Vantage. Place them into your app with vantage add skill (into .squadbase/skills when .squadbase/ exists, else next to already-placed skills, else the project root; --dir overrides) to teach agents step-by-step workflows.
 
 Vantage bundles **Claude Code agent skills**. A skill packages a step-by-step workflow so an
 agent can pull it in exactly when it's needed. Unlike static reference material (these docs), a
@@ -22,13 +22,13 @@ All of these target an agent that is **building a Vantage app**.
 ## Placing them
 
 The skills ship inside the `@squadbase/vantage` package. `vantage add skill` copies them into
-your app. They land **directly under the project root** by default; `--dir` puts them elsewhere.
+your app. By default they land in **`.squadbase/skills/`** when the project has a `.squadbase/` directory, otherwise **next to the skills already placed** (the project root if there are none); `--dir` puts them elsewhere.
 
 ```bash
 vantage add skill                             # list the skills and where they sit (writes nothing)
-vantage add skill --all                       # every skill that isn't placed yet, under the root
+vantage add skill --all                       # every skill that isn't placed yet, in the default location
 vantage add skill vantage-app                 # a single skill by name
-vantage add skill --all --dir .claude/skills  # where Claude Code looks for them
+vantage add skill --all --dir .claude/skills  # choose the location
 vantage add skill --all --force               # refresh the placed copies in place
 ```
 
@@ -40,9 +40,9 @@ under the root, under `.claude/skills/`, under `.squadbase/skills/`, it doesn't
 ```text
 $ vantage add skill
 Bundled skills:
-  project-storage      .claude/skills/project-storage/
-  vantage-add-feature  .claude/skills/vantage-add-feature/
-  vantage-app          .claude/skills/vantage-app/
+  project-storage      .squadbase/skills/project-storage/
+  vantage-add-feature  .squadbase/skills/vantage-add-feature/
+  vantage-app          .squadbase/skills/vantage-app/
   vantage-design       not placed
   vantage-pitfalls     not placed
   vantage-slide        not placed
@@ -51,14 +51,13 @@ Bundled skills:
 With `--force`, the copies that were found are rewritten **where they are** (an explicit `--dir`
 still wins as the destination).
 
-A `--dir` path resolves from the project root (absolute paths work too). To have Claude Code pick
-them up automatically, place them in `.claude/skills/`:
+A `--dir` path resolves from the project root (absolute paths work too). In a Squadbase project, skills live in `.squadbase/skills/`:
 
 ```text
 your-app/
 ├── index.tsx
 ├── package.json
-└── .claude/
+└── .squadbase/
     └── skills/
         ├── vantage-app/SKILL.md
         ├── vantage-add-feature/SKILL.md
@@ -68,12 +67,12 @@ your-app/
         └── project-storage/SKILL.md
 ```
 
-Claude Code discovers `.claude/skills/` automatically. The agent loads and follows the matching
-skill based on the task at hand. For other agents, pass whatever directory that tool expects to
+The Squadbase agent reads `.squadbase/skills/`. It loads and follows the matching
+skill based on the task at hand. For Claude Code on its own, pass `--dir .claude/skills`, which Claude Code discovers automatically. For other agents, pass whatever directory that tool expects to
 `--dir`.
 
 > [!NOTE]
-> `.claude/` is tooling configuration, not app code. Vantage's static `check` diagnostics do not
+> `.squadbase/` is tooling configuration, not app code. Vantage's static `check` diagnostics do not
 > scan this directory, so placing skills there has no effect on your build or checks.
 
 ## Distribution and updates
@@ -83,7 +82,7 @@ skill based on the task at hand. For other agents, pass whatever directory that
   copies you've already placed, run `vantage add skill --all --force` — the destination is scanned
   for, so you don't have to remember the `--dir` you used originally.
 - **The Squadbase template ships them pre-placed.** Apps created from the template already contain
-  `.claude/skills/`. For a hand-made app, add them with `vantage add skill`.
+  `.squadbase/skills/`. For a hand-made app, add them with `vantage add skill`.
 
 ## `AGENTS.md` + `agents/*.md` (the app map and knowledge files)
 

package/docs/en/changelog.md

@@ -9,6 +9,14 @@ What changed in each Vantage release. Newest is on top.
 > minor release may include backwards-incompatible changes. A patch is limited to
 > backwards-compatible additions and bug fixes.
 
+## v0.7.1
+
+`vantage add skill` now prefers `.squadbase/skills/` (the location `readSkill` reads), else places new skills next to the ones already placed.
+
+- In a project with a `.squadbase/` directory, skills land in `.squadbase/skills/` even when none are placed yet.
+- Without `.squadbase/`, skills added by `vantage add skill <name>` or `--all --force` land next to the placed ones, not in the project root. If skills are split across directories, the one holding the most wins (ties: first alphabetically).
+- With no skills placed (root) and with `--dir`, behavior is unchanged.
+
 ## v0.7.0
 
 The UI parts and theme were rebuilt, with many new parts for KPIs, charts, slides and documents.

package/docs/en/parts/draft-chart.md

@@ -0,0 +1,42 @@
+# DraftChart
+
+> Wraps a chart proposal that has not been accepted yet. Faded on the dev server, left out of the build.
+
+Wrap a chart that was added to the page as a proposal and has not been accepted yet. It wraps one
+card. Until it is accepted, viewers of the published dashboard do not see it.
+
+```tsx
+import { DashboardCardPreset, DraftChart } from "@squadbase/vantage/components";
+import type { DraftChartProps } from "@squadbase/vantage/components";
+```
+
+```tsx
+<div className="grid gap-4 md:grid-cols-2">
+  <DraftChart>
+    <DashboardCardPreset data-sq-ref="campaign-roas" title="ROAS by campaign">
+      <BarChart data={rows} index="campaign" categories={["roas"]} />
+    </DashboardCardPreset>
+  </DraftChart>
+</div>
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `children` | `ReactElement` | The one card being proposed. |
+
+## What it shows
+
+- **`vantage dev`**: lays the page background colour (`--background`) over the card at 75%, so it
+  looks faded. While the pointer is over it, the overlay fades out over 200ms so the chart can be
+  read. The overlay does not take clicks or hovers. With `prefers-reduced-motion` the change is not
+  animated.
+- **`vantage build`**: renders nothing (the card inside is not mounted).
+
+`DraftChart` has no box of its own (`display: contents`). The card inside stays a direct child of the
+parent grid, so `col-span-*` and subgrid rows line up exactly as without `DraftChart`. It draws no
+buttons or text.
+
+## Accepting and removing
+
+To accept the chart, delete only the `<DraftChart>` and `</DraftChart>` tags and keep the card. To
+remove it, delete the whole `<DraftChart>…</DraftChart>` element.

package/docs/en/parts/page-shell.md

@@ -26,7 +26,7 @@ import {
 
 | Part | Role |
 | --- | --- |
-| `PageShell` | The outer stack |
+| `PageShell` | The outer stack. Pass `title` (and `description`) and it builds the header and `PageShellContent` for you, putting `children` in the body; without `title` it stays a plain `<div>` |
 | `PageShellHeader` | The underlined header band: heading on the left, `HeaderEnd` on the right. When the row is too narrow, `HeaderEnd` wraps below the heading |
 | `PageShellHeading` / `PageShellTitle` / `PageShellDescription` | The heading block |
 | `PageShellHeaderEnd` | The right-hand stack |

package/docs/index.json

@@ -108,7 +108,7 @@
       "section": "guide",
       "sectionTitle": "ガイド",
       "title": "エージェントと Skills",
-      "description": "Vantage に同梱された Claude Code の Agent Skills。vantage add skill でアプリに配置し（既定はルート直下、--dir で .claude/skills などに変更）、エージェントに手順を伴うワークフローを教える。",
+      "description": "Vantage に同梱された Claude Code の Agent Skills。vantage add skill でアプリに配置し（既定は .squadbase/ があれば .squadbase/skills、無ければ配置済みの Skill と同じ場所、それも無ければルート直下。--dir で変更）、エージェントに手順を伴うワークフローを教える。",
       "file": "ja/agent-skills.md",
       "order": 10
     },
@@ -724,6 +724,16 @@
       "file": "ja/parts/donut-chart.md",
       "order": 10
     },
+    {
+      "slug": "parts/draft-chart",
+      "lang": "ja",
+      "section": "components/parts",
+      "sectionTitle": "@squadbase/vantage/components",
+      "title": "DraftChart",
+      "description": "まだ採用されていないグラフの提案を囲む。開発サーバーでは薄く表示し、ビルドには出さない。",
+      "file": "ja/parts/draft-chart.md",
+      "order": 11
+    },
     {
       "slug": "parts/echart",
       "lang": "ja",
@@ -732,7 +742,7 @@
       "title": "EChart",
       "description": "Apache ECharts の薄いラッパー。配色はテーマトークンに追従する。",
       "file": "ja/parts/echart.md",
-      "order": 11
+      "order": 12
     },
     {
       "slug": "parts/filter-bar",
@@ -742,7 +752,7 @@
       "title": "FilterBar",
       "description": "フィルタ一式を 1 つの値オブジェクトで扱う行。",
       "file": "ja/parts/filter-bar.md",
-      "order": 12
+      "order": 13
     },
     {
       "slug": "parts/format",
@@ -752,7 +762,7 @@
       "title": "format / comparison",
       "description": "KPI・表・グラフで共有する数値の書式（formatValue）と、増減の計算（computeComparison）。",
       "file": "ja/parts/format.md",
-      "order": 13
+      "order": 14
     },
     {
       "slug": "parts/funnel-steps",
@@ -762,7 +772,7 @@
       "title": "FunnelSteps",
       "description": "ファネルの各段を棒で示す。転換率も出せる。",
       "file": "ja/parts/funnel-steps.md",
-      "order": 14
+      "order": 15
     },
     {
       "slug": "parts/heatmap",
@@ -772,7 +782,7 @@
       "title": "Heatmap",
       "description": "2 つのカテゴリの掛け合わせを濃淡で見せる型付きのヒートマップ。曜日 × 時間帯やコホートの継続率に。",
       "file": "ja/parts/heatmap.md",
-      "order": 15
+      "order": 16
     },
     {
       "slug": "parts/kpi-card",
@@ -782,7 +792,7 @@
       "title": "KpiCard",
       "description": "KPI 1 つ分のカード。値・増減・前期実績・結論の 1 文までを数値から組み立てる。",
       "file": "ja/parts/kpi-card.md",
-      "order": 16
+      "order": 17
     },
     {
       "slug": "parts/legend",
@@ -792,7 +802,7 @@
       "title": "Legend",
       "description": "複数のグラフで共有する、HTML だけの独立した凡例。",
       "file": "ja/parts/legend.md",
-      "order": 17
+      "order": 18
     },
     {
       "slug": "parts/line-chart",
@@ -802,7 +812,7 @@
       "title": "LineChart",
       "description": "推移を線で見せる型付きグラフ。行・x 軸の列・系列の列を渡すだけ。",
       "file": "ja/parts/line-chart.md",
-      "order": 18
+      "order": 19
     },
     {
       "slug": "parts/metric-value",
@@ -812,7 +822,7 @@
       "title": "MetricValue",
       "description": "KPI の数値。単位は MetricUnit で。",
       "file": "ja/parts/metric-value.md",
-      "order": 19
+      "order": 20
     },
     {
       "slug": "parts/multi-select",
@@ -822,7 +832,7 @@
       "title": "MultiSelect",
       "description": "検索できる複数選択。選択はチップで表示。",
       "file": "ja/parts/multi-select.md",
-      "order": 20
+      "order": 21
     },
     {
       "slug": "parts/page-shell",
@@ -832,7 +842,7 @@
       "title": "PageShell",
       "description": "ヘッダー帯・サマリー・本文からなるページ枠。",
       "file": "ja/parts/page-shell.md",
-      "order": 21
+      "order": 22
     },
     {
       "slug": "parts/placeholder",
@@ -842,7 +852,7 @@
       "title": "Placeholder",
       "description": "仮データであることを示す、インラインの目印。",
       "file": "ja/parts/placeholder.md",
-      "order": 22
+      "order": 23
     },
     {
       "slug": "parts/progress-circle",
@@ -852,7 +862,7 @@
       "title": "ProgressCircle",
       "description": "目標に対する達成率をリングで示す。中央に任意の内容を置ける。",
       "file": "ja/parts/progress-circle.md",
-      "order": 23
+      "order": 24
     },
     {
       "slug": "parts/sample-data",
@@ -862,7 +872,7 @@
       "title": "SampleData",
       "description": "まだ実データにつながっていない「見本の値」に印を付ける。",
       "file": "ja/parts/sample-data.md",
-      "order": 24
+      "order": 25
     },
     {
       "slug": "parts/scatter-chart",
@@ -872,7 +882,7 @@
       "title": "ScatterChart",
       "description": "2 つの数値の関係と外れ値を見せる型付きの散布図。大きさを足せばバブルチャートになる。",
       "file": "ja/parts/scatter-chart.md",
-      "order": 25
+      "order": 26
     },
     {
       "slug": "parts/searchable-select",
@@ -882,7 +892,7 @@
       "title": "SearchableSelect",
       "description": "検索できる単一選択。候補が多いときに。",
       "file": "ja/parts/searchable-select.md",
-      "order": 26
+      "order": 27
     },
     {
       "slug": "parts/section-header",
@@ -892,7 +902,7 @@
       "title": "SectionHeader",
       "description": "セクションの見出しとアクション。",
       "file": "ja/parts/section-header.md",
-      "order": 27
+      "order": 28
     },
     {
       "slug": "parts/segmented-control",
@@ -902,7 +912,7 @@
       "title": "SegmentedControl",
       "description": "単一選択のセグメント。ToggleGroup の配列を隠す。",
       "file": "ja/parts/segmented-control.md",
-      "order": 28
+      "order": 29
     },
     {
       "slug": "parts/sparkline",
@@ -912,7 +922,7 @@
       "title": "Sparkline",
       "description": "表のセルや KPI タイルに置く、インラインの推移グラフ。",
       "file": "ja/parts/sparkline.md",
-      "order": 29
+      "order": 30
     },
     {
       "slug": "parts/status-badge",
@@ -922,7 +932,7 @@
       "title": "StatusBadge",
       "description": "ドット付きのステータスバッジ。色は名前で決まる。",
       "file": "ja/parts/status-badge.md",
-      "order": 30
+      "order": 31
     },
     {
       "slug": "parts/tracker",
@@ -932,7 +942,7 @@
       "title": "Tracker",
       "description": "期間ごとの状態を小さなブロックの列で示す。稼働状況やバッチの結果に。",
       "file": "ja/parts/tracker.md",
-      "order": 31
+      "order": 32
     },
     {
       "slug": "parts/trend-indicator",
@@ -942,7 +952,7 @@
       "title": "TrendIndicator",
       "description": "非推奨。新規は Delta を使う。増減の矢印と変化率。",
       "file": "ja/parts/trend-indicator.md",
-      "order": 32
+      "order": 33
     },
     {
       "slug": "parts/updated-at",
@@ -952,7 +962,7 @@
       "title": "UpdatedAt",
       "description": "データの鮮度を示す更新時刻。相対時刻に、タイムゾーンつきの絶対時刻を添える。",
       "file": "ja/parts/updated-at.md",
-      "order": 33
+      "order": 34
     },
     {
       "slug": "parts/waterfall-chart",
@@ -962,7 +972,7 @@
       "title": "WaterfallChart",
       "description": "増減の積み上がりを見せる型付きのウォーターフォール。売上から粗利までの内訳や、前期からの増減要因に。",
       "file": "ja/parts/waterfall-chart.md",
-      "order": 34
+      "order": 35
     },
     {
       "slug": "markdown/markdown-renderer",
@@ -1360,7 +1370,7 @@
       "section": "guide",
       "sectionTitle": "Guide",
       "title": "Agents and Skills",
-      "description": "The Claude Code agent skills bundled with Vantage. Place them into your app with vantage add skill (the project root by default, or anywhere via --dir, e.g. .claude/skills) to teach agents step-by-step workflows.",
+      "description": "The Claude Code agent skills bundled with Vantage. Place them into your app with vantage add skill (into .squadbase/skills when .squadbase/ exists, else next to already-placed skills, else the project root; --dir overrides) to teach agents step-by-step workflows.",
       "file": "en/agent-skills.md",
       "order": 9
     },
@@ -1976,6 +1986,16 @@
       "file": "en/parts/donut-chart.md",
       "order": 10
     },
+    {
+      "slug": "parts/draft-chart",
+      "lang": "en",
+      "section": "components/parts",
+      "sectionTitle": "@squadbase/vantage/components",
+      "title": "DraftChart",
+      "description": "Wraps a chart proposal that has not been accepted yet. Faded on the dev server, left out of the build.",
+      "file": "en/parts/draft-chart.md",
+      "order": 11
+    },
     {
       "slug": "parts/echart",
       "lang": "en",
@@ -1984,7 +2004,7 @@
       "title": "EChart",
       "description": "A thin Apache ECharts wrapper whose colours follow the theme tokens.",
       "file": "en/parts/echart.md",
-      "order": 11
+      "order": 12
     },
     {
       "slug": "parts/filter-bar",
@@ -1994,7 +2014,7 @@
       "title": "FilterBar",
       "description": "A row of filters driven by one value object.",
       "file": "en/parts/filter-bar.md",
-      "order": 12
+      "order": 13
     },
     {
       "slug": "parts/format",
@@ -2004,7 +2024,7 @@
       "title": "format / comparison",
       "description": "The number formatting (formatValue) and change calculation (computeComparison) shared by KPIs, tables and charts.",
       "file": "en/parts/format.md",
-      "order": 13
+      "order": 14
     },
     {
       "slug": "parts/funnel-steps",
@@ -2014,7 +2034,7 @@
       "title": "FunnelSteps",
       "description": "A funnel drawn as bars, with conversion rates.",
       "file": "en/parts/funnel-steps.md",
-      "order": 14
+      "order": 15
     },
     {
       "slug": "parts/heatmap",
@@ -2024,7 +2044,7 @@
       "title": "Heatmap",
       "description": "A typed heatmap shading a grid of cells by value. For cohorts, weekday by hour counts and the like.",
       "file": "en/parts/heatmap.md",
-      "order": 15
+      "order": 16
     },
     {
       "slug": "parts/kpi-card",
@@ -2034,7 +2054,7 @@
       "title": "KpiCard",
       "description": "One KPI as a card — value, change, previous actual and a one-line conclusion, all derived from numbers.",
       "file": "en/parts/kpi-card.md",
-      "order": 16
+      "order": 17
     },
     {
       "slug": "parts/legend",
@@ -2044,7 +2064,7 @@
       "title": "Legend",
       "description": "A standalone chart legend in plain HTML, for sharing one legend between several charts.",
       "file": "en/parts/legend.md",
-      "order": 17
+      "order": 18
     },
     {
       "slug": "parts/line-chart",
@@ -2054,7 +2074,7 @@
       "title": "LineChart",
       "description": "A typed line chart for trends and comparisons. Pass rows, the x-axis column and the series columns.",
       "file": "en/parts/line-chart.md",
-      "order": 18
+      "order": 19
     },
     {
       "slug": "parts/metric-value",
@@ -2064,7 +2084,7 @@
       "title": "MetricValue",
       "description": "The KPI number, with MetricUnit for the unit.",
       "file": "en/parts/metric-value.md",
-      "order": 19
+      "order": 20
     },
     {
       "slug": "parts/multi-select",
@@ -2074,7 +2094,7 @@
       "title": "MultiSelect",
       "description": "Multiple choice with search; selections show as chips.",
       "file": "en/parts/multi-select.md",
-      "order": 20
+      "order": 21
     },
     {
       "slug": "parts/page-shell",
@@ -2084,7 +2104,7 @@
       "title": "PageShell",
       "description": "The page frame: header band, summary row, content.",
       "file": "en/parts/page-shell.md",
-      "order": 21
+      "order": 22
     },
     {
       "slug": "parts/placeholder",
@@ -2094,7 +2114,7 @@
       "title": "Placeholder",
       "description": "An inline marker for sample, not-yet-real data.",
       "file": "en/parts/placeholder.md",
-      "order": 22
+      "order": 23
     },
     {
       "slug": "parts/progress-circle",
@@ -2104,7 +2124,7 @@
       "title": "ProgressCircle",
       "description": "A ring showing progress toward a target, with anything you like in the middle.",
       "file": "en/parts/progress-circle.md",
-      "order": 23
+      "order": 24
     },
     {
       "slug": "parts/sample-data",
@@ -2114,7 +2134,7 @@
       "title": "SampleData",
       "description": "Marks the values inside it as sample values that are not yet connected to real data.",
       "file": "en/parts/sample-data.md",
-      "order": 24
+      "order": 25
     },
     {
       "slug": "parts/scatter-chart",
@@ -2124,7 +2144,7 @@
       "title": "ScatterChart",
       "description": "A typed scatter chart, or bubble chart with `size`. Shows how two numbers relate across items.",
       "file": "en/parts/scatter-chart.md",
-      "order": 25
+      "order": 26
     },
     {
       "slug": "parts/searchable-select",
@@ -2134,7 +2154,7 @@
       "title": "SearchableSelect",
       "description": "Single choice with search, for long option lists.",
       "file": "en/parts/searchable-select.md",
-      "order": 26
+      "order": 27
     },
     {
       "slug": "parts/section-header",
@@ -2144,7 +2164,7 @@
       "title": "SectionHeader",
       "description": "A section heading with its actions.",
       "file": "en/parts/section-header.md",
-      "order": 27
+      "order": 28
     },
     {
       "slug": "parts/segmented-control",
@@ -2154,7 +2174,7 @@
       "title": "SegmentedControl",
       "description": "Single-choice segments — it hides ToggleGroup's array.",
       "file": "en/parts/segmented-control.md",
-      "order": 28
+      "order": 29
     },
     {
       "slug": "parts/sparkline",
@@ -2164,7 +2184,7 @@
       "title": "Sparkline",
       "description": "An inline trend chart for table cells and KPI tiles.",
       "file": "en/parts/sparkline.md",
-      "order": 29
+      "order": 30
     },
     {
       "slug": "parts/status-badge",
@@ -2174,7 +2194,7 @@
       "title": "StatusBadge",
       "description": "A dot-and-label status badge, coloured by name.",
       "file": "en/parts/status-badge.md",
-      "order": 30
+      "order": 31
     },
     {
       "slug": "parts/tracker",
@@ -2184,7 +2204,7 @@
       "title": "Tracker",
       "description": "A row of small blocks, one per period, coloured by status. For uptime and batch results.",
       "file": "en/parts/tracker.md",
-      "order": 31
+      "order": 32
     },
     {
       "slug": "parts/trend-indicator",
@@ -2194,7 +2214,7 @@
       "title": "TrendIndicator",
       "description": "Deprecated — use Delta for new code. An arrow and a percentage.",
       "file": "en/parts/trend-indicator.md",
-      "order": 32
+      "order": 33
     },
     {
       "slug": "parts/updated-at",
@@ -2204,7 +2224,7 @@
       "title": "UpdatedAt",
       "description": "A freshness label such as \"23 minutes ago\". Shows the absolute time and zone on hover.",
       "file": "en/parts/updated-at.md",
-      "order": 33
+      "order": 34
     },
     {
       "slug": "parts/waterfall-chart",
@@ -2214,7 +2234,7 @@
       "title": "WaterfallChart",
       "description": "A typed waterfall chart. Shows how steps move a running total, such as revenue to gross profit.",
       "file": "en/parts/waterfall-chart.md",
-      "order": 34
+      "order": 35
     },
     {
       "slug": "markdown/markdown-renderer",