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

package/agent-docs/styling/themes.md

@@ -0,0 +1,128 @@
+---
+id: guide.themes
+title: Themes
+summary: Pick a site shape, pair it with a color palette, and choose how light
+  and dark mode behave.
+type: reference
+area: appearance
+subarea: appearance-themes
+canonical: /styling/themes
+---
+
+# Themes
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Themes
+
+**Updated: 2026-10-27.**
+
+The `theme` setting controls how the HTML site looks. It has five keys, and each has a default:
+
+```yaml title="docs.config.yaml"
+theme:
+  preset: reef      # site shape
+  palette: harbor   # colors
+  mode: system      # light, dark, or system
+  toggle: true      # reader switch for light and dark mode
+  fonts: system     # optional: turn off the preset's bundled fonts
+```
+
+Omit `theme` to keep the default: the `shoal` preset, the `kelp` palette, the preset's fonts, and light mode only. An unknown value fails the build.
+
+To see every combination on a real page, open [Try a theme](https://www.shoalrun.com/styling/try.md).
+
+Start with a preset. Change the [palette](https://www.shoalrun.com/styling/palettes.md) if its colors don't fit your brand. Set the [mode](https://www.shoalrun.com/styling/color-modes.md) if readers need dark mode. Use [project CSS](https://www.shoalrun.com/author/css.md) for anything else.
+
+## Presets
+
+A preset sets the shape of the site. It controls layout, corner radii, and type, and how panels, navigation, and cards look. Each preset has a default palette. Any palette works with any preset.
+
+| Preset   | Shape                                                                                                                    | Default palette |
+| -------- | ------------------------------------------------------------------------------------------------------------------------ | --------------- |
+| `shoal`  | Flat page with a ruled sidebar and square-cornered controls.                                                             | `kelp`          |
+| `reef`   | Rounded panels float on a tinted page. Navigation items and controls are pills.                                          | `coral`         |
+| `ledger` | A technical manual with an inked masthead, serif body text, monospace headings, numbered sections, and hard-edged cards. | `ink`           |
+| `vice`   | A night masthead with a sunset stripe, bold italic display type, neon section rules, and cards that glow on hover.       | `vice`          |
+
+Presets change CSS only. Page markup, URLs, and Markdown twins stay the same.
+
+## Fonts
+
+Each preset ships its own fonts, so the site looks the same on every operating system:
+
+| Preset   | Body           | Headings       | Code             |
+| -------- | -------------- | -------------- | ---------------- |
+| `shoal`  | Inter          | Inter          | System monospace |
+| `reef`   | Figtree        | Figtree        | System monospace |
+| `ledger` | Source Serif 4 | JetBrains Mono | JetBrains Mono   |
+| `vice`   | Figtree        | Jost           | System monospace |
+
+The fonts are Latin variable fonts under the SIL Open Font License. The build copies them to `/assets/fonts/` with their license files. A browser downloads only the faces a page uses, and the page preloads its body font. Characters outside the Latin set use the system fallback. Until a font arrives, the page uses a local font resized to match it. Text doesn't shift when the bundled font loads. Agents read the Markdown twins, which load no fonts.
+
+To use system fonts only, set `fonts: system`. Each preset then falls back to its system font stack.
+
+### Use your own fonts
+
+Set any of `body`, `headings`, and `code`. A role you leave out keeps the preset's font. `headings` defaults to the body font.
+
+```yaml title="docs.config.yaml"
+theme:
+  preset: reef
+  fonts:
+    body:
+      family: Acme Sans
+      files:
+        - ./fonts/AcmeSans.woff2
+        - { file: ./fonts/AcmeSans-Italic.woff2, style: italic }
+    headings: Acme Display
+    code:
+      family: Berkeley Mono
+      files: [./fonts/BerkeleyMono.woff2]
+```
+
+- `family` is the name CSS uses. A plain string, such as `headings: Acme Display`, names a font without shipping files. Use it for a font that [project CSS](https://www.shoalrun.com/author/css.md) loads, or one installed on readers' machines.
+- `files` lists local `.woff2`, `.woff`, `.ttf`, or `.otf` files, relative to the config file that declares them. The build copies them to `/assets/fonts/project/`. File names can use letters, numbers, dots, dashes, and underscores, and two files can't share a name.
+- Each file can set `style` (`normal` or `italic`) and `weight`, such as `400` or `"100 900"`. The default weight, `"100 900"`, suits variable fonts; give each static file its own weight.
+
+A missing file, an unsupported format, or an unknown key fails the build. Check that your font license allows web embedding.
+
+Fonts set here become the `--font-body`, `--font-heading`, and `--font-code` [CSS tokens](https://www.shoalrun.com/author/css.md), each followed by a system fallback.
+
+## Load order
+
+The HTML page links stylesheets in this order. Later files override earlier ones.
+
+1. `/assets/site.css`, which imports the base tokens and header styles.
+2. `/assets/theme.css`, for a preset other than `shoal`.
+3. `/assets/palette.css`, generated for any palette or mode other than `kelp` in light mode.
+4. `/assets/fonts.css`, generated from `theme.fonts`, unless it's `system` and sets nothing.
+5. `/assets/project.css`, from `site.customCss`.
+
+When a site uses a non-default preset, palette, or mode, the `html` element carries `data-theme` and `data-palette`. The `ledger` and `vice` presets also set `data-masthead="inked"`, which switches header tools to light text on a dark masthead. Project CSS can target one combination:
+
+```css title="styles/project.css"
+[data-theme="ledger"] .page-head h1 { letter-spacing: 0; }
+```
+
+## HTML, Markdown, and agents
+
+Presets and fonts style the HTML page through generated stylesheets. They do not change its Markdown text or add font and layout instructions to the Markdown twin. An agent reading Markdown receives the authored content without needing the theme assets. Keep labels, hierarchy, and instructions meaningful without relying on typography or position alone.
+
+## Related reading
+
+### Next steps
+
+- [Color palettes](https://www.shoalrun.com/styling/palettes.md) — Choose the colors the preset uses.
+
+- [Light and dark mode](https://www.shoalrun.com/styling/color-modes.md) — Decide whether readers get light mode, dark mode, or a toggle.
+
+### Go deeper
+
+- [CSS and theme reference](https://www.shoalrun.com/author/css.md) — Customize tokens and selectors beyond what presets and palettes offer.
+
+### Related topics
+
+- [Try a theme](https://www.shoalrun.com/styling/try.md) — Preview every preset, palette, and color mode on a live page.

package/agent-docs/styling/try.md

@@ -0,0 +1,94 @@
+---
+id: guide.theme-preview
+title: Try a theme
+summary: Preview every preset, palette, and color mode on this page, then copy
+  the config.
+type: how-to
+area: appearance
+subarea: appearance-themes
+canonical: /styling/try
+---
+
+# Try a theme
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > Try a theme
+
+**Updated: 2026-10-27.**
+
+Pick a shape, a palette, and a mode. This page restyles itself as you choose. Scroll down to see how each option styles the sample content, then copy the config into `docs.config.yaml`.
+
+Every preset works with every palette, in light or dark mode.
+
+| Preset   | Shape                                                                               | Default palette |
+| -------- | ----------------------------------------------------------------------------------- | --------------- |
+| `shoal`  | Flat page with a ruled sidebar and square-cornered controls.                        | `kelp`          |
+| `reef`   | Rounded panels on a tinted page, with pill navigation and controls.                 | `coral`         |
+| `ledger` | Technical manual with an inked masthead, monospace headings, and numbered sections. | `ink`           |
+| `vice`   | Night masthead with a sunset stripe, bold italic type, and neon rules.              | `vice`          |
+
+| Palette    | Colors                                                          |
+| ---------- | --------------------------------------------------------------- |
+| `kelp`     | Sea green on white.                                             |
+| `coral`    | Coral accent over cool blue-gray neutrals.                      |
+| `ink`      | Black ink on warm paper with a vermilion accent.                |
+| `harbor`   | Navy ink, blue links, and a yellow callout rule.                |
+| `amethyst` | Violet accents over lavender neutrals.                          |
+| `vice`     | Flamingo pink and aqua by day, neon on night purple after dark. |
+
+```yaml title="docs.config.yaml"
+theme:
+  preset: vice
+  palette: harbor
+  mode: system
+```
+
+The preview lasts until you leave the page or press **Reset**. It does not change the site for other readers. Your site's [project CSS](https://www.shoalrun.com/author/css.md) still applies on top of the preview.
+
+## Sample content
+
+A guide page mixes prose, [links](https://www.shoalrun.com/styling/themes.md), `inline code`, and components. Each preset styles them in its own way.
+
+> **Tip:** Try the `vice` shape in dark mode.
+
+### A table
+
+Use this sample to inspect table headers, cell spacing, and inline values in the selected theme.
+
+| Setting   | Default        | Values                                 |
+| --------- | -------------- | -------------------------------------- |
+| `preset`  | `shoal`        | `shoal`, `reef`, `ledger`, `vice`      |
+| `palette` | Preset default | Any built-in name, or a custom palette |
+| `mode`    | `light`        | `light`, `dark`, `system`              |
+
+### A code block
+
+```yaml title="docs.config.yaml"
+theme:
+  preset: reef
+  palette: amethyst
+  mode: system
+```
+
+### Tabs
+
+### Light
+
+Readers always see the light set.
+
+### Dark
+
+Readers always see the dark set.
+
+### System
+
+The site follows each reader's system setting, with an optional toggle.
+
+## Related reading
+
+### Related topics
+
+- [Themes](https://www.shoalrun.com/styling/themes.md) — Preview every preset, palette, and color mode on a live page.

package/agent-docs/what-is-shoalrun.md

@@ -0,0 +1,56 @@
+---
+id: guide.what-is-shoalrun
+title: What is Shoalrun?
+summary: A one-page introduction to Shoalrun's document-first approach, its
+  outputs, and the current prototype.
+type: overview
+area: project
+subarea: project-overview
+canonical: /what-is-shoalrun
+---
+
+# What is Shoalrun?
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > What is Shoalrun?
+
+**Updated: 2026-10-27.**
+
+Shoalrun is a documentation compiler for product and API docs. It reads project configuration, Markdown and supported MDX pages, and optional local OpenAPI files. From those sources, it builds a site for people and readable Markdown pages for agents. The normal build is deterministic: it makes no model calls or network requests.
+
+## Documents have an identity
+
+In Shoalrun, a document is more than a file at a path. It has a stable ID, metadata, and relationships to other documents. Navigation, page cards, and links can refer to that ID. You can move a source file without reconnecting those parts of the site. The published URL is a separate choice: changing a page's slug changes its URL and may need a redirect.
+
+That identity lets information connect across the site. A guide can link to an exact API operation, a related page, or a complete workflow without relying on where its source file lives.
+
+## One source serves different readers
+
+Shoalrun builds HTML and a Markdown twin from the same accepted content. Browser components can give people tabs, diagrams, and other ways to explore an idea; their Markdown form keeps the useful content readable without browser scripts. Authors can also write a section for just one output when people and agents need different explanations. The build publishes a document manifest and discovery files so software can find the pages and their relationships.
+
+## Authors control the connections
+
+Shoalrun also supports AI-assisted writing with human review. Use your existing coding agent with project guidance and checked edit tools. [Authoring tools](https://www.shoalrun.com/author/agent-overview.md) provide project-wide discovery and isolated snapshot validation for ordinary working-tree edits. You accept the content, inspect its HTML and Markdown, and decide when to publish. The normal compiler build remains independent of the models.
+
+Project-owned YAML can define navigation, relationships, templates, and API sources in separate files. Shoalrun combines the files and can trace where a setting came from. Public builds check links and publication variants, and changes to imported OpenAPI content require a renewed review digest.
+
+Optional ingredients, recipes, and cookbooks extend the same idea to tasks. An ingredient is a reusable action; a reviewed recipe completes one goal. A cookbook helps readers choose the complete recipes they need.
+
+## Where it stands
+
+The public documentation site shows output built by Shoalrun. Install the alpha CLI from npm using [Getting started](https://www.shoalrun.com/start.md). The [project status](https://www.shoalrun.com/status.md) lists implemented capabilities and current limits.
+
+## Related reading
+
+### Next steps
+
+- [How Shoalrun works](https://www.shoalrun.com/concepts.md) — Follow a document through the compiler and see how IDs and routes work.
+
+- [Getting started](https://www.shoalrun.com/start.md) — Follow the getting-started workflow if you have access to the prototype.
+
+### Related topics
+
+- [About Shoalrun](https://www.shoalrun.com/about.md) — Read the author's motivation and design philosophy.

package/assets/analytics.js

@@ -0,0 +1,72 @@
+// No service SDK, endpoint, storage, or transport belongs to this module.
+// The project adapter owns initialization, consent, and delivery.
+const source = document.querySelector('#analytics-config');
+if (source) {
+  const page = Object.freeze(JSON.parse(source.textContent));
+  let adapter;
+  let ready = false;
+  let enabled = true;
+  const setEnabled = value => { if (typeof value === 'boolean') enabled = value; };
+  const scalar = value => typeof value === 'string' ? value.slice(0, 256)
+    : typeof value === 'boolean' || typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+  const propertiesOf = properties => Object.fromEntries(Object.entries(properties ?? {}).slice(0, 32).flatMap(([key, value]) => {
+    if (!/^[a-zA-Z][a-zA-Z0-9_]{0,63}$/.test(key) || ['constructor', 'prototype'].includes(key)) return [];
+    const safe = Array.isArray(value) ? value.slice(0, 32).map(scalar).filter(value => value !== undefined) : scalar(value);
+    return safe === undefined ? [] : [[key, safe]];
+  }));
+  const component = element => {
+    if (!(element instanceof Element)) return {};
+    const scope = element.closest('article, .examples, .side, .page-toc, .mast') ?? document.body;
+    const heading = element.closest('article') ? [...document.querySelectorAll('article :is(h2,h3,h4)[id]')].filter(h => h.compareDocumentPosition(element) & Node.DOCUMENT_POSITION_FOLLOWING).at(-1) : undefined;
+    const kind = element.matches('.walkthrough') ? 'walkthrough' : element.matches('.doc-tabs') ? 'tabs' : element.matches('details') ? 'disclosure' : element.matches('.code-block') ? 'code' : 'control';
+    const selector = kind === 'walkthrough' ? '.walkthrough' : kind === 'tabs' ? '.doc-tabs' : kind === 'disclosure' ? 'details' : kind === 'code' ? '.code-block' : 'a,button,select';
+    const ordinal = [...scope.querySelectorAll(selector)].indexOf(element) + 1;
+    return { componentId: element.dataset.analyticsId || element.id || `${heading?.id ?? 'page'}:${kind}:${ordinal}`, componentType: kind, ...(heading ? { headingId: heading.id } : {}) };
+  };
+  const track = (name, properties = {}, element) => {
+    if (!ready || !enabled || typeof name !== 'string' || !/^[a-z][a-z0-9_]{0,63}$/.test(name)) return false;
+    try {
+      const event = { schemaVersion: 1, name, properties: { ...propertiesOf(properties), ...component(element), ...page } };
+      Promise.resolve(adapter.track(event)).catch(() => {});
+      return true;
+    } catch { return false; }
+  };
+  globalThis.shoalrunAnalytics = Object.freeze({ track, setEnabled, get enabled() { return ready && enabled; } });
+
+  // Links retain normal browser behavior, including keyboard and modified clicks.
+  document.addEventListener('click', event => {
+    const target = event.target instanceof Element ? event.target : null;
+    const summary = target?.closest('summary');
+    if (summary?.parentElement.matches('details.doc-collapsible, article details.doc-info-hint')) intendedDisclosures.add(summary.parentElement);
+    const anchor = target?.closest('a[href]');
+    if (!anchor || anchor.closest('.doc-tablist, .site-search-results') || anchor.matches('.heading-anchor')) return;
+    const region = anchor.closest('.section-nav, .side, .page-toc, .doc-breadcrumbs, .related-reading, .doc-card, .hero-actions, .site-footer, .mast, article, .page-formats');
+    if (!region) return;
+    let url;
+    try { url = new URL(anchor.href); } catch { return; }
+    if (!['http:', 'https:'].includes(url.protocol)) return;
+    const names = { 'section-nav': 'sections', side: 'sidebar', 'page-toc': 'toc', 'doc-breadcrumbs': 'breadcrumbs', 'related-reading': 'related', 'doc-card': 'card', 'hero-actions': 'hero', 'site-footer': 'footer', mast: 'header', 'page-formats': 'formats' };
+    const regionName = Object.entries(names).find(([className]) => region.classList.contains(className))?.[1] ?? 'content';
+    track('navigation_click', { region: regionName, targetPath: url.pathname, external: url.origin !== location.origin }, anchor);
+  });
+  const intendedDisclosures = new WeakSet();
+  document.addEventListener('toggle', event => {
+    const details = event.target;
+    if (!intendedDisclosures.has(details)) return;
+    intendedDisclosures.delete(details);
+    track('disclosure_toggle', { open: details.open }, details);
+  }, true);
+
+  // Import and init never block component scripts or normal navigation. Events
+  // before readiness or while disabled are discarded rather than queued.
+  import('./analytics-adapter.js').then(async module => {
+    if (typeof module.track !== 'function') throw new Error('Missing track export');
+    adapter = module;
+    if (module.init !== undefined) {
+      if (typeof module.init !== 'function') throw new Error('Invalid init export');
+      await module.init(Object.freeze({ page, setEnabled, track }));
+    }
+    ready = true;
+    track('page_view');
+  }).catch(() => { enabled = false; });
+}