@shoalrun/cli 0.0.0-stage → 0.1.0-alpha.11

package/styles/themes/palettes/kelp.yaml

@@ -0,0 +1,127 @@
+# kelp: Sea green on white. The light set matches the base tokens in tokens.css.
+light:
+  text: "#253735"
+  page: "#ffffff"
+  surface: "#ffffff"
+  link: "#096958"
+  link-hover: "#064c40"
+  focus: "#087c9c"
+  ink: "#142f2b"
+  accent: "#177866"
+  accent-contrast: "#ffffff"
+  header-muted: "#536a64"
+  header-border: "#dce7e2"
+  border: "#dfe8e3"
+  border-soft: "#edf1ee"
+  border-nested: "#dce6df"
+  field-surface: "#f6f9f7"
+  field-border: "#7f9389"
+  field-accent: "#9ebcaf"
+  presence-bg: "#e2f1e9"
+  presence-text: "#205740"
+  optional-bg: "#edf1ee"
+  optional-text: "#52645b"
+  muted: "#576b62"
+  nav-heading: "#607267"
+  section-heading: "#39594b"
+  nav-text: "#43584d"
+  nav-hover: "#f2f6f3"
+  nav-active: "#e9f4ed"
+  nav-active-text: "#18563e"
+  deprecated-bg: "#fbe9e7"
+  deprecated-text: "#843d36"
+  beta-bg: "#eeebfa"
+  beta-text: "#56448b"
+  development-bg: "#fff1d9"
+  development-text: "#75531c"
+  experimental-bg: "#e7f3f1"
+  experimental-text: "#245b55"
+  emphasis: "#256d52"
+  summary: "#52685c"
+  code-bg: "#f0f4f1"
+  code-text: "#e4f2e9"
+  code-muted: "#b8ccbf"
+  code-border: "#405c4f"
+  code-block: "#142f2b"
+  callout-line: "#4b9476"
+  callout-bg: "#f0f7f2"
+  callout-note-line: "#3975a6"
+  callout-note-bg: "#eff6fc"
+  callout-note-text: "#244f73"
+  callout-tip-line: "#2f8057"
+  callout-tip-bg: "#edf8f1"
+  callout-tip-text: "#245b3d"
+  callout-important-line: "#7456a6"
+  callout-important-bg: "#f5f0fb"
+  callout-important-text: "#583d80"
+  callout-warning-line: "#a46c16"
+  callout-warning-bg: "#fff7e6"
+  callout-warning-text: "#704b12"
+  callout-caution-line: "#b14943"
+  callout-caution-bg: "#fff0ee"
+  callout-caution-text: "#81372f"
+  strong-surface: "#142f2b"
+  strong-text: "#ffffff"
+dark:
+  text: "#d3e2dc"
+  page: "#0e1614"
+  surface: "#1b2623"
+  link: "#6fd3b0"
+  link-hover: "#9fe6cc"
+  focus: "#5cc9e6"
+  ink: "#eef6f2"
+  accent: "#4cc49a"
+  accent-contrast: "#062019"
+  header-muted: "#98aca4"
+  header-border: "#2b3b36"
+  border: "#27352f"
+  border-soft: "#1b2623"
+  border-nested: "#2f3f39"
+  field-surface: "#111b18"
+  field-border: "#61766f"
+  field-accent: "#3f7f6a"
+  presence-bg: "#173a2e"
+  presence-text: "#9fe8c8"
+  optional-bg: "#1f2a27"
+  optional-text: "#b3c4bd"
+  muted: "#9bb0a8"
+  nav-heading: "#93a8a0"
+  section-heading: "#b9cdc5"
+  nav-text: "#c0d1ca"
+  nav-hover: "#1a2724"
+  nav-active: "#173a2e"
+  nav-active-text: "#9fe8c8"
+  deprecated-bg: "#3d2020"
+  deprecated-text: "#f3aaa3"
+  beta-bg: "#2b2546"
+  beta-text: "#c9bcff"
+  development-bg: "#3a2e14"
+  development-text: "#f0cf8a"
+  experimental-bg: "#173a35"
+  experimental-text: "#9de0d0"
+  emphasis: "#6fd3b0"
+  summary: "#b0c3bb"
+  code-bg: "#1c2926"
+  code-text: "#dfeee7"
+  code-muted: "#9bb0a8"
+  code-border: "#2f3f39"
+  code-block: "#080d0c"
+  callout-line: "#4cc49a"
+  callout-bg: "#12251f"
+  callout-note-line: "#5b9bd5"
+  callout-note-bg: "#13253a"
+  callout-note-text: "#a8d1f5"
+  callout-tip-line: "#4fb07f"
+  callout-tip-bg: "#12281d"
+  callout-tip-text: "#9ce0ba"
+  callout-important-line: "#a283dd"
+  callout-important-bg: "#231a36"
+  callout-important-text: "#d2bff7"
+  callout-warning-line: "#d49a3a"
+  callout-warning-bg: "#2e2410"
+  callout-warning-text: "#f2cd8a"
+  callout-caution-line: "#e0766e"
+  callout-caution-bg: "#33191a"
+  callout-caution-text: "#f7b1aa"
+  strong-surface: "#050908"
+  strong-text: "#eef6f2"

package/styles/themes/palettes/vice.yaml

@@ -0,0 +1,127 @@
+# vice: Flamingo pink and aqua by day; neon on a night-purple sky after dark.
+light:
+  text: "#2b1633"
+  page: "#fff6fa"
+  surface: "#ffffff"
+  link: "#b0126a"
+  link-hover: "#7e0c4b"
+  focus: "#00807e"
+  ink: "#1c0a24"
+  accent: "#d0215f"
+  accent-contrast: "#ffffff"
+  header-muted: "#6d5670"
+  header-border: "#f2d6e5"
+  border: "#f0dbe7"
+  border-soft: "#f8ebf2"
+  border-nested: "#ecd3e1"
+  field-surface: "#fdf0f6"
+  field-border: "#a3809b"
+  field-accent: "#3cc9c0"
+  presence-bg: "#d9f6f3"
+  presence-text: "#005b59"
+  optional-bg: "#f6ebf1"
+  optional-text: "#5e4a62"
+  muted: "#6d5670"
+  nav-heading: "#6d5670"
+  section-heading: "#4a2c52"
+  nav-text: "#45304c"
+  nav-hover: "#fbe9f2"
+  nav-active: "#d9f6f3"
+  nav-active-text: "#005b59"
+  deprecated-bg: "#fbe9e7"
+  deprecated-text: "#843d36"
+  beta-bg: "#eeebfa"
+  beta-text: "#56448b"
+  development-bg: "#fff1d9"
+  development-text: "#75531c"
+  experimental-bg: "#e7f3f1"
+  experimental-text: "#245b55"
+  emphasis: "#00726f"
+  summary: "#5a4460"
+  code-bg: "#f9e6f0"
+  code-text: "#fbe9f4"
+  code-muted: "#cfb2d2"
+  code-border: "#4a2c55"
+  code-block: "#1c0a24"
+  callout-line: "#1ac7bd"
+  callout-bg: "#e8fbf9"
+  callout-note-line: "#3975a6"
+  callout-note-bg: "#eff6fc"
+  callout-note-text: "#244f73"
+  callout-tip-line: "#2f8057"
+  callout-tip-bg: "#edf8f1"
+  callout-tip-text: "#245b3d"
+  callout-important-line: "#7456a6"
+  callout-important-bg: "#f5f0fb"
+  callout-important-text: "#583d80"
+  callout-warning-line: "#a46c16"
+  callout-warning-bg: "#fff7e6"
+  callout-warning-text: "#704b12"
+  callout-caution-line: "#b14943"
+  callout-caution-bg: "#fff0ee"
+  callout-caution-text: "#81372f"
+  strong-surface: "#1c0a24"
+  strong-text: "#fff6fa"
+dark:
+  text: "#eadcf2"
+  page: "#140a24"
+  surface: "#241736"
+  link: "#ff6fb5"
+  link-hover: "#ffa3d2"
+  focus: "#3ee6dc"
+  ink: "#fff4fb"
+  accent: "#ff4fa3"
+  accent-contrast: "#1a0412"
+  header-muted: "#b8a3c8"
+  header-border: "#3a2553"
+  border: "#35214d"
+  border-soft: "#24163a"
+  border-nested: "#3d2858"
+  field-surface: "#190d2b"
+  field-border: "#8a6fa3"
+  field-accent: "#1ab3aa"
+  presence-bg: "#0f3a3f"
+  presence-text: "#8ff5ee"
+  optional-bg: "#2a1b40"
+  optional-text: "#cdbcdb"
+  muted: "#b8a3c8"
+  nav-heading: "#b39dc4"
+  section-heading: "#dcc8ea"
+  nav-text: "#dfd0ea"
+  nav-hover: "#26163d"
+  nav-active: "#0f3a3f"
+  nav-active-text: "#8ff5ee"
+  deprecated-bg: "#3d2020"
+  deprecated-text: "#f3aaa3"
+  beta-bg: "#2b2546"
+  beta-text: "#c9bcff"
+  development-bg: "#3a2e14"
+  development-text: "#f0cf8a"
+  experimental-bg: "#173a35"
+  experimental-text: "#9de0d0"
+  emphasis: "#3ee6dc"
+  summary: "#cdbcdb"
+  code-bg: "#2a1a40"
+  code-text: "#f6e8f8"
+  code-muted: "#b8a3c8"
+  code-border: "#3d2858"
+  code-block: "#0a0514"
+  callout-line: "#3ee6dc"
+  callout-bg: "#102a33"
+  callout-note-line: "#5b9bd5"
+  callout-note-bg: "#13253a"
+  callout-note-text: "#a8d1f5"
+  callout-tip-line: "#4fb07f"
+  callout-tip-bg: "#12281d"
+  callout-tip-text: "#9ce0ba"
+  callout-important-line: "#a283dd"
+  callout-important-bg: "#231a36"
+  callout-important-text: "#d2bff7"
+  callout-warning-line: "#d49a3a"
+  callout-warning-bg: "#2e2410"
+  callout-warning-text: "#f2cd8a"
+  callout-caution-line: "#e0766e"
+  callout-caution-bg: "#33191a"
+  callout-caution-text: "#f7b1aa"
+  strong-surface: "#07030f"
+  strong-text: "#fff4fb"

package/styles/themes/reef.css

@@ -0,0 +1,68 @@
+/* Reef: soft floating panels, pill navigation, and generous radii on a tinted page. */
+:root {
+  --font-body: "Figtree", "Figtree Fallback", ui-rounded, "SF Pro Rounded", ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  --radius-small: .7rem;
+  --radius-panel: 1.25rem;
+  --shadow-panel: var(--shadow-edge), 0 1px 2px #1a24400d, 0 8px 24px -12px #1a244026;
+  --width-site: 96rem;
+  --width-reference: 96rem;
+}
+
+/* The masthead floats as a rounded bar above the page. */
+.mast{background:transparent;border:0;padding:1rem 2rem 0}
+.mast-inner{background:var(--color-surface);border-radius:999px;box-shadow:var(--shadow-panel);min-height:3.75rem;padding:.6rem 1rem .6rem 1.4rem}
+.brand::before{width:1.1rem;height:1.1rem;border-radius:.35rem;transform:rotate(12deg);background:linear-gradient(135deg,var(--color-accent),color-mix(in srgb,var(--color-accent),#fff 40%))}
+.edition{border-radius:999px;background:var(--color-field-surface)}
+
+/* Navigation and reading column are separate floating panels. */
+.layout{padding-top:1.5rem;gap:1.5rem}
+.side{background:var(--color-surface);border:0;border-radius:var(--radius-panel);box-shadow:var(--shadow-panel);padding:1rem;top:1rem;max-height:calc(100dvh - 2rem)}
+.side .nav-tools{background:var(--color-surface)}
+.side h2{letter-spacing:.06em;padding-left:.7rem}
+.side a{border-radius:999px;padding-inline:.9rem}
+.side a[aria-current=page]{background:var(--color-nav-active);box-shadow:none}
+.side .nav-group>details>ul{border-left:0;margin-left:.2rem;padding-left:0}
+.nav-search input{border-radius:999px;padding-left:1rem}
+.content{background:var(--color-surface);border-radius:var(--radius-panel);box-shadow:var(--shadow-panel);padding:2.5rem clamp(1.5rem,4vw,3.5rem) 3rem}
+.page-head{border-bottom:0;padding-bottom:.5rem}
+.eyebrow{display:inline-block;background:var(--color-nav-active);color:var(--color-nav-active-text);border-radius:999px;padding:.2rem .7rem;letter-spacing:.08em}
+.page-head h1{letter-spacing:-.035em}
+.formats{border-radius:999px;padding-inline:.9rem;margin-left:-.9rem}
+.page-toc{background:var(--color-surface);border:0;border-radius:var(--radius-panel);box-shadow:var(--shadow-panel);padding:1rem 1.25rem}
+.content h2{border-top:0;padding-top:0}
+.content blockquote{border-left:0;border-radius:var(--radius-small);box-shadow:inset 4px 0 var(--callout-line,var(--color-callout-line))}
+.content table{border-collapse:separate;border-spacing:0;border:1px solid var(--color-border);border-radius:var(--radius-small);overflow:hidden}
+.content tr:last-child>td{border-bottom:0}
+.code-block,.content pre,.example-body pre{border-radius:var(--radius-small)}
+.examples{background:var(--color-surface);border:0;box-shadow:var(--shadow-panel)}
+.content .doc-card{border-color:transparent;background:var(--color-field-surface);transition:transform .15s ease,box-shadow .15s ease}
+.content .doc-card:hover{background:var(--color-surface);border-color:var(--color-border);box-shadow:var(--shadow-panel);transform:translateY(-2px)}
+.content .doc-card-icon{box-sizing:content-box;padding:.45rem;border-radius:.7rem;background:var(--color-nav-active)}
+.content .doc-tablist a{border-radius:999px;border:0;margin-bottom:.5rem}
+.content .doc-tablist a[aria-selected=true]{background:var(--color-strong-surface,var(--color-ink));color:var(--color-strong-text,var(--color-surface))}
+
+@media(max-width:48rem){
+  .mast{padding:.75rem .75rem 0}
+  .mast-inner{border-radius:var(--radius-panel)}
+  .layout,.layout.has-examples{padding:1rem .75rem 3rem}
+  .side{box-shadow:var(--shadow-panel);background:var(--color-surface);padding:0}
+  .page-toc{padding:0;box-shadow:var(--shadow-panel)}
+  .content{padding:1.5rem 1.1rem 2rem}
+}
+@media(prefers-reduced-motion:reduce){.content .doc-card{transition:none}.content .doc-card:hover{transform:none}}
+@media print{.content,.side,.examples{box-shadow:none}}
+
+/* Header tools follow the pill shape. */
+.site-search input,.header-actions a,.site-search-key{border-radius:999px}
+.site-search input{background:var(--color-page);border-color:transparent;padding-left:1.1rem}
+.site-search input:focus{background:var(--color-surface);border-color:var(--color-field-border)}
+.site-search-results{border:0;box-shadow:var(--shadow-panel),0 16px 40px -16px #1a244040}
+.site-search-results a{border-radius:.9rem}
+.header-actions a{padding-inline:1rem}
+.header-primary{box-shadow:0 4px 12px -4px color-mix(in srgb,var(--color-accent),transparent 40%)}
+
+/* Landing hero: a tinted panel inside the reading panel, with pill actions. */
+.content .hero{border:0;background:radial-gradient(70% 90% at 50% 0%,var(--color-nav-active),transparent 75%),var(--color-field-surface)}
+.content .hero[data-align=start]{background:linear-gradient(135deg,var(--color-nav-active),var(--color-field-surface) 70%)}
+.content .hero-action{border-radius:999px}
+.content .hero-primary{box-shadow:0 6px 16px -8px color-mix(in srgb,var(--color-accent),transparent 30%)}

package/styles/themes/vice.css

@@ -0,0 +1,56 @@
+/* Vice: a night-drive masthead with a sunset stripe, bold italic display type, and neon rules. */
+:root {
+  --font-body: "Figtree", "Figtree Fallback", "Avenir Next", Avenir, "Century Gothic", "Segoe UI", ui-sans-serif, system-ui, sans-serif;
+  --font-display: "Jost", "Jost Fallback", Futura, "Futura PT", "Avenir Next", "Century Gothic", ui-sans-serif, sans-serif;
+  --font-heading: var(--font-display);
+  --radius-small: .55rem;
+  --radius-panel: .9rem;
+  --sunset: linear-gradient(90deg, #ff4fa3, #ff8a3d 50%, #3ee6dc);
+  --width-site: 104rem;
+  --width-reference: 104rem;
+}
+
+/* The masthead is the night sky; the stripe beneath it is decorative. */
+.mast{position:relative;border:0}
+.mast::after{content:"";position:absolute;inset:auto 0 0;height:4px;background:var(--sunset)}
+.brand{font-family:var(--font-display);font-style:italic;font-weight:800;letter-spacing:.01em;text-transform:uppercase;color:var(--color-strong-text,var(--color-surface))}
+.brand::before{width:1.15rem;height:1.15rem;border-radius:50%;transform:none;background:linear-gradient(180deg,#ffd166,#ff8a3d 45%,#ff4fa3)}
+.header-link:hover{background:transparent;color:var(--color-strong-text,var(--color-surface));text-decoration:underline;text-decoration-color:#ff4fa3;text-decoration-thickness:2px}
+.header-actions a,.site-search input{border-radius:999px}
+
+/* Navigation: an aqua rail marks the current page. */
+.side h2,.eyebrow,.page-toc h2{font-family:var(--font-display);font-style:italic}
+.side a[aria-current=page]{box-shadow:inset 3px 0 var(--color-emphasis)}
+
+/* Display type with a sunset underline. */
+.eyebrow{color:var(--color-link);letter-spacing:.22em}
+.page-head{border-bottom:0;position:relative}
+.page-head::after{content:"";position:absolute;left:0;bottom:0;width:min(14rem,60%);height:4px;border-radius:2px;background:var(--sunset)}
+.page-head h1,.content :where(h2,h3){font-family:var(--font-heading);font-style:italic;font-weight:800;letter-spacing:-.02em}
+.page-head h1{text-transform:uppercase;letter-spacing:-.01em}
+.content h2{border-top:0;padding-top:0;padding-left:.8rem;box-shadow:inset 4px 0 var(--color-accent)}
+.content blockquote{border-left-color:var(--color-emphasis)}
+.formats,.header-primary{border-radius:999px}
+
+/* Cards pick up a sunset border and a soft neon glow on hover. */
+.content .doc-card{border:2px solid var(--color-border);transition:transform .15s ease,box-shadow .15s ease}
+.content .doc-card:hover{border-color:transparent;background:linear-gradient(var(--color-surface),var(--color-surface)) padding-box,var(--sunset) border-box;box-shadow:0 10px 30px -12px #ff4fa366;transform:translateY(-2px)}
+.content .doc-card-icon{color:var(--color-accent)}
+.content .doc-tablist a[aria-selected=true]{box-shadow:inset 0 -3px var(--color-accent)}
+.examples{border-width:2px}
+
+@media(max-width:48rem){.page-head h1{font-size:1.9rem}}
+@media(prefers-reduced-motion:reduce){.content .doc-card{transition:none}.content .doc-card:hover{transform:none}}
+@media(forced-colors:active){.mast::after,.page-head::after{background:CanvasText}}
+@media print{.mast::after,.page-head::after{display:none}}
+
+/* Landing hero: night sky with a sunset glow and stripe; the primary action wears the sunset. */
+.content .hero{overflow:hidden;border:0;background:radial-gradient(50rem 22rem at 85% 130%,#ff4fa340,transparent 65%),radial-gradient(30rem 16rem at 10% 120%,#3ee6dc26,transparent 60%),var(--color-strong-surface,var(--color-ink))}
+.content .hero::after{content:"";position:absolute;inset:auto 0 0;height:4px;background:var(--sunset)}
+.content .hero-title{font-style:italic;font-weight:800;text-transform:uppercase;letter-spacing:-.01em;color:var(--color-strong-text,var(--color-surface))}
+.content .hero-tagline{color:color-mix(in srgb,var(--color-strong-text,var(--color-surface)) 80%,transparent)}
+.content .hero-action{border-radius:999px;background:transparent;color:var(--color-strong-text,var(--color-surface));border-color:color-mix(in srgb,var(--color-strong-text,var(--color-surface)) 60%,transparent)}
+.content .hero-action:hover{background:#ffffff14;color:var(--color-strong-text,var(--color-surface))}
+.content .hero-primary{background:var(--sunset);border:0;color:#140a24}
+.content .hero-primary:hover{background:var(--sunset);color:#140a24;filter:brightness(1.08)}
+@media(forced-colors:active){.content .hero::after{background:CanvasText}}

package/styles/tokens.css

@@ -0,0 +1,91 @@
+:root {
+  color-scheme: light;
+  --font-body: "Inter", "Inter Fallback", ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  --font-code: "SFMono-Regular", Consolas, "Liberation Mono", monospace;
+  --font-heading: var(--font-body);
+  --color-text: #253735;
+  --color-page: #fff;
+  --color-surface: #fff;
+  --color-link: #096958;
+  --color-link-hover: #064c40;
+  --color-focus: #087c9c;
+  --color-ink: #142f2b;
+  --color-accent: #177866;
+  --color-header-muted: #536a64;
+  --color-header-border: #dce7e2;
+  --color-border: #dfe8e3;
+  --color-border-soft: #edf1ee;
+  --color-border-nested: #dce6df;
+  --color-field-surface: #f6f9f7;
+  --color-field-border: #7f9389;
+  --color-field-accent: #9ebcaf;
+  --color-presence-bg: #e2f1e9;
+  --color-presence-text: #205740;
+  --color-optional-bg: #edf1ee;
+  --color-optional-text: #52645b;
+  --color-muted: #576b62;
+  --color-nav-heading: #607267;
+  --color-section-heading: #39594b;
+  --color-nav-text: #43584d;
+  --color-nav-hover: #f2f6f3;
+  --color-nav-active: #e9f4ed;
+  --color-nav-active-text: #18563e;
+  --color-deprecated-bg: #fbe9e7;
+  --color-deprecated-text: #843d36;
+  --color-beta-bg: #eeebfa;
+  --color-beta-text: #56448b;
+  --color-development-bg: #fff1d9;
+  --color-development-text: #75531c;
+  --color-experimental-bg: #e7f3f1;
+  --color-experimental-text: #245b55;
+  --color-emphasis: #256d52;
+  --color-summary: #52685c;
+  /* Inline code uses this surface and inherits the surrounding text color. */
+  --color-code-bg: #f0f4f1;
+  /* Fenced blocks use code-text on the palette code-block surface. */
+  --color-code-text: #e4f2e9;
+  --color-code-muted: #b8ccbf;
+  --color-code-border: #405c4f;
+  --color-callout-line: #4b9476;
+  --color-callout-bg: #f0f7f2;
+  --color-callout-note-line: #3975a6;
+  --color-callout-note-bg: #eff6fc;
+  --color-callout-note-text: #244f73;
+  --color-callout-tip-line: #2f8057;
+  --color-callout-tip-bg: #edf8f1;
+  --color-callout-tip-text: #245b3d;
+  --color-callout-important-line: #7456a6;
+  --color-callout-important-bg: #f5f0fb;
+  --color-callout-important-text: #583d80;
+  --color-callout-warning-line: #a46c16;
+  --color-callout-warning-bg: #fff7e6;
+  --color-callout-warning-text: #704b12;
+  --color-callout-caution-line: #b14943;
+  --color-callout-caution-bg: #fff0ee;
+  --color-callout-caution-text: #81372f;
+  --code-foreground: var(--color-code-text);
+  --code-token-comment: var(--color-code-muted);
+  --code-token-punctuation: var(--color-code-text);
+  --code-token-keyword: #4cc49a;
+  --code-token-string: #9ce0ba;
+  --code-token-string-expression: #9ce0ba;
+  --code-token-constant: #f2cd8a;
+  --code-token-function: #a8d1f5;
+  --code-token-parameter: #d2bff7;
+  --code-token-link: #6fd3b0;
+  --shadow-edge: 0 0 #0000;
+  --nav-item-height: 2.75rem;
+  --nav-item-pad-y: .65rem;
+  --radius-small: .4rem;
+  --radius-panel: .75rem;
+  --width-site: 108rem;
+  --width-reference: 108rem;
+  --landing-width: 76rem;
+}
+/* Mouse and trackpad users get denser navigation; touch keeps 44px targets. */
+@media (pointer: fine) and (min-width: 48.0625rem) {
+  :root {
+    --nav-item-height: 2rem;
+    --nav-item-pad-y: .32rem;
+  }
+}

package/templates/api-reference.mdx

@@ -0,0 +1,133 @@
+---
+# API REFERENCE TEMPLATE. Delete every comment line (starting with #) before you publish.
+# Search the file for TODO and resolve every placeholder in double square brackets.
+# A page with a placeholder left cannot be published.
+#
+# Scaffold filled in id, title, summary, type, slug, channel, version, language, and access from
+# the command line, the file path, and your config. Rewrite title, summary, and slug for the reader.
+#
+# The build appends the operation details after this text. Write only what the OpenAPI file cannot
+# say. Do not repeat the method, path, fields, or examples. The build adds Related documentation
+# and Related guides lists after the details, so this page has no Related reading section.
+
+# Stable identity. Links, cards, navigation, and relationships use it, so it can outlive
+# a renamed file or a changed URL. Scaffold derived it from the file path. Shorten it if you like,
+# to lowercase words separated by dots or hyphens, such as reference.create-enrollment.
+# Never change it after publishing.
+id: api-reference.example
+
+# The page heading and the browser tab title. Use the operation's action and object, matching the
+# OpenAPI summary: "Create an enrollment", "List parcels". Sentence case, 60 characters or fewer.
+# Scaffold derived a placeholder title from the file name. Rewrite it.
+title: Example
+
+# One sentence of 160 characters or fewer that says what the operation does.
+# Good: "Create an enrollment for a parcel program and return its status."
+# Bad: "POST /enrollments" (The reader can see the method and path already.)
+# Scaffold wrote a draft summary that blocks publishing. Replace it.
+summary: Draft summary
+
+# Optional longer text for search and link previews. Two sentences at most, about 300 characters.
+# Add detail the summary leaves out, such as the version or the audience. Do not repeat the summary.
+# Delete this field if you have nothing to add.
+description: "[[TODO: Two sentences that add detail to the summary, or delete this field.]]"
+
+# The page kind. Leave this as api-reference. The build then adds the method, path, parameters, schemas, and examples from your OpenAPI file below the text on this page.
+type: api-reference
+
+# The URL path. Start with /. Use lowercase words separated by hyphens, and keep it stable.
+# Good: /reference/create-payment. Avoid dates and version numbers.
+slug: /reference/example
+
+# The publication this page belongs to. It must match an enabled entry in publications.enabled.
+# A page in a channel, version, or language that is not enabled is skipped without a warning.
+channel: production
+version: current
+language: en
+
+# The stable operation ID this page presents, from your apis config, such as cedar.createEnrollment.
+# Exactly one is allowed on an api-reference page. Scaffold sets it from the --operation flag.
+operations: []
+
+# Topic labels that help collections find this page. One to three, lowercase, short.
+# Use labels your team already uses. Do not invent one for a single page.
+tags:
+  - "[[TODO: One lowercase topic label, such as parcels. Add a line for each extra label.]]"
+
+# How this page looks when another page links to it with a card. The icon is a Lucide name in
+# lowercase, such as braces, package, or terminal. Browse the names at lucide.dev/icons.
+# An unknown name fails the build. To add a short label above the card title, or card text that
+# replaces the summary on cards only, add eyebrow or description: card: { icon: braces, eyebrow: API reference }
+card: { icon: braces }
+
+# ---------------------------------------------------------------------------------------------
+# OPTIONAL FIELDS. Uncomment one only when the rule in its comment applies.
+# ---------------------------------------------------------------------------------------------
+#
+# Who this page is for, shown as badges. Free text unless your config defines an audience
+# reader view, in which case use its choice IDs. Uncomment only if your site uses audiences.
+# audiences: [developers]
+#
+# Reader-view marks for pages that appear only in some views. Use only IDs from readerFilters.facets.
+# The product, area, and subarea fields set a single choice for a facet with the same name.
+# readerFilters: { audience: [developer] }
+# product: parcels
+# area: reporting
+# subarea: delivery
+#
+# Status of the feature or API this page covers: beta, in-development, or deprecated.
+# It shows a badge in navigation and the page header. Leave it out for a stable feature.
+# subjectLifecycle: beta
+#
+# Editorial state of this document, such as needs-review. Free text. It is kept but never shown.
+# lifecycle: needs-review
+#
+# Deepest heading level in the on-page table of contents. Use 0 to hide it, or 2 through 6.
+# The default is 3. Set 2 for a long page with many small subsections.
+# tocDepth: 2
+#
+# A local .png or .jpg, 1200 by 630 pixels, that replaces the generated link-preview image.
+# The path is relative to this file.
+# image: ./images/retry-enrollment.png
+#
+# Overrides for the browser title and meta description. Only title and description are supported.
+# seo:
+#   title: Retry a failed enrollment | Example API
+#   description: Retry an enrollment with the same idempotency key.
+#
+# Literal text for one output only. Keys: card, pageHeader, search, htmlDescription, socialCard.
+# displayText:
+#   socialCard: Retry a failed enrollment without creating duplicates.
+#
+# A named Markdown-header profile from your config, or a mapping that overrides the header.
+# markdownMetadata: minimal
+#
+# Values for snippets used on this page. They override project variables.
+# variables: { product: Parcel sandbox }
+
+# Publishing control. Scaffold sets draft, which keeps the page out of the site. Change to
+# { policy: public } only after every TODO is resolved and the text has been checked against the OpenAPI operation.
+access: { policy: draft }
+---
+
+[[TODO: Write one paragraph of 150 words or fewer. Put no heading above it. Say when a reader should use this operation and what it changes. Use this pattern: "This operation [creates, changes, or removes] [thing] and returns [result]. For [task context], see [how-to link]." Do not repeat the method, path, fields, or examples. The build adds those from the OpenAPI file.]]
+
+## Prerequisites
+
+[[TODO: OPTIONAL SECTION. Keep it only for a requirement the OpenAPI file does not show, such as an account setting, a feature flag, or a prior call. Delete this heading and text otherwise. One bullet per requirement, each linking to the page that explains it.]]
+
+- [[TODO: First requirement, with a link.]]
+
+## Considerations
+
+[[TODO: OPTIONAL SECTION. Keep it only for a limitation, side effect, or rule the OpenAPI file does not show. Examples are idempotency behavior, eventual consistency, and a call that cannot be undone. Delete this heading and text otherwise. One bullet per item, with the consequence in bold first.]]
+
+- [[TODO: First consideration.]]
+
+## Related tasks
+
+[[TODO: OPTIONAL SECTION. A how-to may walk through a task that uses this operation. If so, link to it by document ID and say what it adds. Delete this heading and text if no task page exists. Then add this page's ID to relatedApiReferences in the guide's frontmatter. Both pages then link to each other.]]
+
+## HTML, Markdown, and agents
+
+[[TODO: OPTIONAL SECTION. Keep it when the page uses a component or describes behavior that differs between HTML and Markdown or affects what an agent reads. Delete this heading and text otherwise. Describe what HTML shows or lets a reader do, what the Markdown twin contains, and what that means for an agent. Name the useful .md page, documents.json entry, or focused contract when relevant. Describe actual behavior in two to five sentences.]]

package/templates/cookbook.mdx

@@ -0,0 +1,38 @@
+---
+# COOKBOOK TEMPLATE. Delete comments and resolve every [[TODO: ...]] prompt before publishing.
+# Scaffold fills id, title, summary, type, slug, publication, and access from the command and config.
+# A cookbook helps readers choose among related, prebuilt recipes.
+
+# Stable identity for navigation, links, and cards.
+id: cookbook.example
+
+# Name the family of goals, such as "Notify Users".
+title: Choose a workflow
+
+# Explain which reader decision this cookbook helps with.
+summary: Find a reviewed recipe for your goal.
+
+# Leave this page kind as cookbook.
+type: cookbook
+
+# Stable lowercase URL path before publication prefixes. Start with /.
+slug: /cookbooks/example
+
+# These values must match the recipe publication used by CookbookChooser.
+channel: production
+version: current
+language: en
+
+# Keep draft until every linked recipe is public and the selected order makes sense.
+access: { policy: draft }
+---
+
+[[TODO: Explain the related goals and when readers should use this cookbook.]]
+
+## Choose a recipe
+
+[[TODO: List the complete public recipes with <DocCards docs={["recipe.one", "recipe.two"]} />, or configure options under cookbooks in docs.config.yaml and place <CookbookChooser id="your-cookbook-id" /> here. Choose one presentation and delete this prompt.]]
+
+## How these recipes fit together
+
+[[TODO: Explain shared setup, differences between choices, and the next useful recipe after completion. Delete this section if the choices are self-explanatory.]]