feat(one-shot): 264 cards × bilingual + gacha-as-full-card + arxiv-slug fix

.claude/skills/one-shot-card/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: one-shot-card
+description: Use when a wiki concept/entity/source page or a mm chapter needs a visual TL;DR card. Produces a `.mdx` file that renders through `<OneShotCard>` in the Astro site. Design-first workflow — different cards should LOOK different.
+argument-hint: <source-file-path-or-slug> [lang=zh|en]
+user-invocable: true
+---
+
+# One-Shot Card
+
+Generate a TL;DR "一图流" card — a poster-style visual summary of any
+main-content page — as a `.mdx` file consumed by Astro's `cards`
+collection and rendered through `<OneShotCard>`.
+
+## Core principle (north star)
+
+> **充分利用有效面积，用版面体现重要性，最后再叠加审美。**
+
+Before you pick blocks, do **design-first thinking**. An A4 vertical
+card is a *poster*, not a document. Content does NOT simply flow from
+top to bottom in paragraphs — the visual weight of each region should
+mirror how important that content is. If there's a hero idea, give it a
+hero zone. If there's a core one-liner, give it its own band. If there
+are siblings, put them side-by-side.
+
+Never let a card finish at 60% height with a half-empty bottom. Fill the
+surface, or cut content until what remains fills it gracefully.
+
+**Different cards should LOOK different.** Do not default to the same
+template each time. The point of one-shot cards is that each is a
+dedicated poster, not a row in a uniform grid.
+
+## Inputs
+
+- Source file path — e.g. `wikis/concepts/causal-dag.md`,
+  `docs/zh/mental-models/ch-02-cybernetics/01-helmsman.md`, or a mm
+  chapter root.
+- Target language — `zh` (default) or `en`.
+
+## Process (MANDATORY ORDER — do not skip design)
+
+### 1 · Read the source
+
+Parse the source file. Note: title, tagline candidates, core structure
+(h2/h3 + first bullet of each), cross-references, cited sources,
+(for source kind) author/year/URL.
+
+### 2 · Design-first: rank and allocate
+
+Before writing a single line of MDX, answer these questions:
+
+1. **What are the 3–5 things this card must communicate?** Rank by
+   importance (most → least).
+2. **Which is the hero?** The single most important idea / the
+   signature visual. This gets the biggest surface area.
+3. **Is there a signature visual?** (An SVG topology, a compare table, a
+   formula, a timeline, a matrix.) If yes, it IS the hero.
+4. **What natural structure does this content have?** (N-case breakdown
+   / compare-contrast / timeline / hierarchical / quote + takeaways / KV
+   biographical.) This picks the layout pattern.
+5. **What is the 1-line core definition?** The sentence that if a reader
+   reads nothing else, they got the concept. This deserves its own band.
+
+### 3 · Pick a layout approach — let different cards look different
+
+Do **NOT** default to the same template for every card. Choose per-content:
+
+| Content signature | Layout approach | Good fit for |
+|---|---|---|
+| One signature SVG + elaboration | **Hero-on-top** (bleed): large hero band, then tan core band, then small detail/refs band | concepts with a structural diagram (causal-dag, fractal) |
+| Compare/contrast two sides | **Dual-column split** (bleed, `<Band cols={2}>`): two panels side-by-side | pros vs cons, challenges vs strengths, symbol vs connectionist |
+| N ordered steps / rules | **Rule-stack** (bleed with stacked bands; ink accent for 1st) | `do-calculus` three rules, multi-step processes |
+| One person + their facts | **Portrait-KV** (bleed; 2-col top: hero-han + KV stack; bottom caption) | `entities/judea-pearl`, historical figures |
+| One killer quote + 2–3 takeaways | **Quote-hero + takeaways-foot** (bleed; tan band with `<CoreDef>` quote on top; paper-sunk band with numbered takeaways) | source cards, paper digests |
+| Narrative chapter TL;DR | **Band-rhythm** (bleed; alternating tone bands each carrying one idea) | `chapters/ch-*`, overview cards |
+
+None are mandatory — the table is a *menu*. If a card's content
+suggests a different composition, follow that.
+
+### 4 · Decide: `default` or `bleed` layout
+
+- **`default`** (layout field omitted): shell renders kind badge + seal +
+  title block + footer refs/source; body slots into a padded middle
+  region. Good when the card is small and you want the shell to frame
+  it.
+- **`bleed`** (`layout: bleed` in frontmatter): shell renders ONLY the
+  A4 frame + palette lock. The body composes everything edge-to-edge
+  using `<Band>` / `<Kicker>` / `<HeroHan>` / `<CoreDef>` and inline
+  SVG/KV/Quote/etc. You are responsible for putting the title, kind
+  tag, and footer refs somewhere in the composition (usually: an ink or
+  tan top-band for title+kicker, and a paper-sunk or ink bottom-band
+  for refs+source).
+
+**Default for rich cards is `bleed`.** It's the only way to get real
+infographic composition with color zones.
+
+### 5 · Compose the MDX
+
+- Start from a layout skeleton (menu in §3 or invent one).
+- Fill content into zones. Each zone's content should be the minimum
+  needed to do its job — no filler to "fill space". If content doesn't
+  fit, adjust zone sizes.
+- Use `<Band grow>` on the zone that should absorb any leftover vertical
+  space (typically the hero / compare zone, never the footer).
+- Inline SVG is encouraged — 400×100 of 3 topologies tells more than
+  three text pillars. Use `currentColor` and token-driven fill/stroke
+  so dark mode flips automatically.
+- Unusual compositions welcome: rotated text, vertical rails, hero
+  number accents, compare-matrix tables. The A4 frame is the only hard
+  limit.
+
+### 6 · Write to disk
+
+Path: `site/src/content/cards/{lang}/{kind-plural}/{slug}.mdx`
+
+`{kind-plural}` ∈ `concepts` / `entities` / `sources` / `chapters`.
+
+**Never set `kind` or `slug` in frontmatter** — derived from path.
+
+### 7 · Hand off
+
+Return:
+- Path of the file written.
+- 1-sentence statement of the layout approach chosen and *why*.
+- Review URL:
+  - wiki entries: `http://localhost:4321/{lang}/wiki/{kind-plural}/{slug}`
+  - any card (isolated view): `http://localhost:4321/card-fragment/{lang}/{kind-plural}/{slug}?theme=dark`
+
+The author will eyeball and iterate.
+
+## Hard constraints (imposed by the component — can't escape)
+
+- A4 vertical aspect ratio (1 : 1.414).
+- `max-height: calc(100vh - 120px)`.
+- `overflow: hidden` — the card clips. If content overflows, the author
+  sees it and will trim. Do NOT add internal scrolling.
+- Palette locked to `tokens.css`. Never hard-code hex values.
+
+## Non-constraints (you choose freely)
+
+- Number of zones / bands / SVG panels.
+- Vertical rhythm — bleed bands can be any height you want.
+- Typographic weights/sizes within the provided fonts.
+- Whether the kind tag / title / footer lives in the shell's default
+  chrome (default layout) or inside a band you author (bleed layout).
+
+## Background
+
+- `references/aesthetic.md` — tokens + voice
+- `references/blocks.md` — block kit catalog (incl. new `<Band>`,
+  `<Kicker>`, `<HeroHan>`, `<CoreDef>`)
+- `references/layouts.md` — the 6 layout approaches above with worked
+  MDX skeletons
+- `references/sources-card.md` — source-kind special fields
+- `references/exemplars/` — real mdx files annotated with *why* each
+  layout choice was made
+
+## Skill chain
+
+- Produce one sample; author reviews.
+- If layout is wrong (feels flat, feels crowded, feels samey), iterate:
+  swap the approach, re-generate.
+- Phase-2 targets ~5 异质 samples, one per archetype. Batch-regen for
+  P3 is a separate spec — don't try to mass-produce here.

.claude/skills/one-shot-card/references/aesthetic.md

@@ -0,0 +1,57 @@
+# Card Aesthetic — Palette & Voice
+
+## Palette (tokens.css)
+
+- `--paper` — main background (宣纸底)
+- `--paper-raised` — card body background (展签纸)
+- `--paper-sunk` — recessed slots (contained code, chips)
+- `--ink` — primary text
+- `--ink-soft` — body prose
+- `--ink-faint` — captions, meta labels
+- `--rule` — hairlines
+- `--vermilion` — seal, accent; use sparingly (印章 only, or one chip)
+- `--gold` — quieter accent (entity seal, source year)
+- `--celadon` — rarest accent (rare structural emphasis)
+
+The dark-mode palette flips automatically via `[data-theme="dark"]`.
+Your card should not hard-code any hex value.
+
+### Gotcha — day/night inversion of `--paper` and `--ink`
+
+In light mode `--paper` is cream, `--ink` is near-black.
+In dark mode they flip: `--paper` is near-black, `--ink` is cream.
+
+So a rule like `color: var(--paper)` on an "ink-dark band" gives cream text in
+light mode but near-black text in dark mode — invisible either way depending
+on the band.
+
+**Always inherit the enclosing band's text color for body/chip text** —
+use `color: currentColor` (the band already sets the correct text color
+via `<Band>`'s own CSS, flipped for both modes).
+
+For semi-transparent variants use `color-mix(in oklab, currentColor 70%, transparent)`
+or simply `opacity: 0.75` — both track the band's text direction.
+
+Never write `color: var(--paper)` / `color: var(--ink)` directly inside a
+card's `<style>` block unless you are 100% sure which band encloses it AND
+you want the value to flip with theme mode.
+
+## Voice (for tagline + body)
+
+- 留白是美德 — if a pillar or bullet can be cut, cut it
+- 表达清楚优先于字数 — clarity > conciseness when they conflict
+- Chinese: prefer 意象 over 说教. "舵手" beats "the thing that steers".
+- English: terse, concrete. Avoid "allows" / "enables" — use active verbs.
+- Inline code (`A → B → C`) for symbols; block `<Formula>` only for
+  multi-symbol equations.
+
+## Card-kind personality
+
+- `concept` — structural; the card should show what the concept IS (its
+  components, invariants, mechanisms). `<PillarGrid>` default.
+- `entity` — biographical; who they are, what they did. `<KV>` default.
+- `source` — distill; one killer quote + 2-3 takeaways. `<Quote>` default.
+- `chapter` — narrative; prose + a divider + a final punchline. `<Stack>`
+  default.
+
+These are starting points, not rules. Content decides.

.claude/skills/one-shot-card/references/blocks.md

@@ -0,0 +1,147 @@
+# Block Kit Catalog
+
+All blocks live in `site/src/components/card/blocks/`. Import in MDX:
+
+```mdx
+import Pillar from '~/components/card/blocks/Pillar.astro';
+```
+
+## `<PillarGrid cols={2|3|4}>` + `<Pillar label="…">`
+
+3-column structural breakdown. Each pillar carries a short mono-label +
+a 1-line body. Use for: concepts with 2-4 cases/modes/patterns.
+
+```mdx
+<PillarGrid cols={3}>
+  <Pillar label="Chain">`A → B → C` 条件化 B 阻断</Pillar>
+  <Pillar label="Fork">`A ← B → C` B 是混淆</Pillar>
+  <Pillar label="Collider">`A → B ← C` 条件化反而打开</Pillar>
+</PillarGrid>
+```
+
+## `<KV label="…">`
+
+Key-value stack. Use for: entities (biographical), sources (metadata).
+
+```mdx
+<KV label="生年">1936—</KV>
+<KV label="图灵奖">2011 · 因果推理</KV>
+```
+
+## `<Formula>`
+
+Centered mono block for equations.
+
+```mdx
+<Formula>P(Y | do(X)) = Σ<sub>z</sub> P(Y | X, z) P(z)</Formula>
+```
+
+## `<Quote cite="…">`
+
+Vermilion left-bar pull quote. Use for: sources (the killer line).
+
+```mdx
+<Quote cite="Pearl 2009">没有因果就没有反事实。</Quote>
+```
+
+## `<Caption>`
+
+Small caps muted line. Use for: aside notes under a formula / pillar row.
+
+```mdx
+<Caption>Rule 3 covers a special case of Rule 1 under intervention.</Caption>
+```
+
+## `<Chip tone="vermilion|gold|celadon|ink">`
+
+Inline tag. Use sparingly.
+
+```mdx
+<Chip tone="vermilion">核心</Chip>
+```
+
+## `<Divider dot={true}/>`
+
+A hairline (optional center dot in vermilion).
+
+```mdx
+<Divider/>
+```
+
+## `<Stack gap={12}>`
+
+Vertical rhythm control. Replaces manual `<br/>` sequences.
+
+```mdx
+<Stack gap={10}>
+  <div>line 1</div>
+  <div>line 2</div>
+</Stack>
+```
+
+## Layout primitives (for `layout: bleed` cards)
+
+These enable color-zoned / bento composition — see `references/layouts.md`
+for worked examples.
+
+### `<Band tone cols dense grow>`
+
+A full-width horizontal band. Each band carries its own background tone.
+When composing a bleed-mode card, the body is a vertical stack of
+`<Band>`s. Tones: `paper` / `paper-raised` / `paper-sunk` / `ink` / `tan`
+/ `celadon` / `gold`. `cols={2|3}` splits the band into columns.
+`dense` shrinks vertical padding. `grow` makes this band absorb any
+leftover vertical space (usually the hero band).
+
+```mdx
+<Band tone="ink" dense><Kicker>概念 · CAUSAL DAG</Kicker></Band>
+<Band tone="paper-raised" grow>…hero content…</Band>
+<Band tone="tan"><CoreDef>d-分离就是 ...</CoreDef></Band>
+<Band tone="paper-sunk" cols={2}><div>left</div><div>right</div></Band>
+```
+
+### `<Kicker>`
+
+Small mono all-caps label. A quiet top-line that says "meta".
+
+```mdx
+<Kicker>概念 · 因果 · REF-2026-03</Kicker>
+```
+
+### `<HeroHan size="md|lg|xl">`
+
+Oversized Han-display character(s) — visual anchor. Use once per card.
+Typical placement: top-left of an ink-toned band.
+
+```mdx
+<HeroHan size="xl">舵</HeroHan>
+<HeroHan size="lg">Pearl</HeroHan>
+```
+
+### `<CoreDef>`
+
+Italic emphasized core-definition line. Typical placement: inside a
+`tone="tan"` or `tone="paper-sunk"` band between hero and detail. Signals
+"this is the crystallized one-liner".
+
+```mdx
+<CoreDef>如果 c 没有发生，e 就不会发生 —— 最接近实际世界的可能世界中亦然。</CoreDef>
+```
+
+## Escape hatch
+
+Anything else is fair game: plain markdown, `<p>`, `<ul>`, inline SVG,
+`<Mermaid>` (if you import it). The A4 frame will clip overflow — that's
+your feedback loop.
+
+## MDX gotchas
+
+- **`<style>` blocks must wrap CSS in a JSX template literal** to avoid
+  MDX's parser treating `{ margin: 0 }` as an object literal:
+  ```mdx
+  <style>{`
+    .my-class { margin: 0; color: var(--ink); }
+  `}</style>
+  ```
+- **Avoid `{/* comments */}` inside deeply nested SVG** — strip them.
+- **Don't set `kind` or `slug` in frontmatter** — derived from path.

.claude/skills/one-shot-card/references/exemplars/concept-causal-dag.mdx

@@ -0,0 +1,29 @@
+{/* exemplar: concept card showing 3-case structural breakdown via PillarGrid + Divider + Formula. Good when a concept has a clean "N patterns + one unifying rule" shape. */}
+
+---
+schemaVersion: one-shot-card/v1
+title: 因果有向无环图
+titleAlt: Causal DAG
+tagline: 链 / 叉 / 对撞 · d-分离 · 去混淆的桥
+refs:
+  - concepts/structural-causal-model
+  - concepts/do-calculus
+sourceLine: 参 Pearl (2009); Book of Why (2018)
+---
+
+import PillarGrid from '~/components/card/blocks/PillarGrid.astro';
+import Pillar from '~/components/card/blocks/Pillar.astro';
+import Divider from '~/components/card/blocks/Divider.astro';
+import Formula from '~/components/card/blocks/Formula.astro';
+
+<PillarGrid cols={3}>
+  <Pillar label="Chain">`A → B → C`<br/>条件化 B 阻断</Pillar>
+  <Pillar label="Fork">`A ← B → C`<br/>B 是混淆因子</Pillar>
+  <Pillar label="Collider">`A → B ← C`<br/>条件化反而打开</Pillar>
+</PillarGrid>
+
+<Divider/>
+
+**d-分离** — 给定 Z 阻断 X→Y 的所有路径 ⇒ X ⊥ Y | Z。
+
+<Formula>P(Y | do(X)) = Σ<sub>z</sub> P(Y | X, Z=z) P(Z=z)</Formula>