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

package/agent-docs/author/components/diagrams/pele-gallery.sections/systems-and-structures.md

@@ -0,0 +1,291 @@
+---
+id: reference.pele-gallery
+title: Pele gallery
+summary: Browse Mermaid-syntax diagrams and flowchart shapes rendered with Pele.
+type: reference
+area: components
+subarea: components-visuals
+canonical: /author/components/diagrams/pele-gallery
+---
+
+# Pele gallery
+
+> 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 > Pele gallery
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/components/diagrams/pele-gallery.md)
+
+Browse examples of Pele's 33 built-in diagram families, including its version display, and 48 flowchart shapes. Every example uses Shoalrun's [Diagram component](https://www.shoalrun.com/author/components/diagrams.md) with Mermaid syntax. These illustrate notation; they do not describe live services or measured product results.
+
+Open **Source** beneath a diagram to copy its syntax. See [Pele's examples](https://pele.run/examples) for more variations and [compatibility notes](https://pele.run/compatibility) for differences from Mermaid.
+
+## Systems and structures
+
+### Class
+
+Describe types, fields, and relationships.
+
+**Class**
+
+Describe types, fields, and relationships.
+
+[View Class diagram](https://www.shoalrun.com/assets/diagrams/mermaid-af73adf46c1d18e97da9-light.svg)
+
+```mermaid
+classDiagram
+ class Page {
+ +String title
+ +String slug
+ +render()
+ }
+ class Section {
+ +String heading
+ }
+ Page "1" *-- "many" Section
+```
+
+### Source: Class
+
+```mermaid
+classDiagram
+ class Page {
+ +String title
+ +String slug
+ +render()
+ }
+ class Section {
+ +String heading
+ }
+ Page "1" *-- "many" Section
+```
+
+### Entity relationship
+
+Show entities and relationship cardinality.
+
+**Entity relationship**
+
+Show entities and relationship cardinality.
+
+[View Entity relationship diagram](https://www.shoalrun.com/assets/diagrams/mermaid-2c935f03a00d8732c5f6-light.svg)
+
+```mermaid
+erDiagram
+ PROJECT ||--o{ PAGE : contains
+ PAGE ||--o{ SECTION : contains
+ PAGE {
+ string id PK
+ string title
+ }
+ SECTION {
+ string heading
+ }
+```
+
+### Source: Entity relationship
+
+```mermaid
+erDiagram
+ PROJECT ||--o{ PAGE : contains
+ PAGE ||--o{ SECTION : contains
+ PAGE {
+ string id PK
+ string title
+ }
+ SECTION {
+ string heading
+ }
+```
+
+### Architecture
+
+Connect services using built-in symbols.
+
+**Architecture**
+
+Connect services using built-in symbols.
+
+[View Architecture diagram](https://www.shoalrun.com/assets/diagrams/mermaid-2604ab6aac56722b033b-light.svg)
+
+```mermaid
+architecture-beta
+ group docs(cloud)[Documentation]
+ service app(server)[Site] in docs
+ service store(database)[Content] in docs
+ app:R -- L:store
+```
+
+### Source: Architecture
+
+```mermaid
+architecture-beta
+ group docs(cloud)[Documentation]
+ service app(server)[Site] in docs
+ service store(database)[Content] in docs
+ app:R -- L:store
+```
+
+### C4
+
+Describe a system and its users at a high level.
+
+**C4**
+
+Describe a system and its users at a high level.
+
+[View C4 diagram](https://www.shoalrun.com/assets/diagrams/mermaid-d31ce80c287440a978dd-light.svg)
+
+```mermaid
+C4Context
+ title Documentation context
+ Person(reader, "Reader", "Finds instructions")
+ System(docs, "Documentation", "Published guides")
+ Rel(reader, docs, "Reads")
+```
+
+### Source: C4
+
+```mermaid
+C4Context
+ title Documentation context
+ Person(reader, "Reader", "Finds instructions")
+ System(docs, "Documentation", "Published guides")
+ Rel(reader, docs, "Reads")
+```
+
+### Block
+
+Arrange connected blocks in explicit columns.
+
+**Block**
+
+Arrange connected blocks in explicit columns.
+
+[View Block diagram](https://www.shoalrun.com/assets/diagrams/mermaid-4b2a2cf39d3fe9446598-light.svg)
+
+```mermaid
+block-beta
+ columns 3
+ a["Author"] b["Build"] c["Publish"]
+ a --> b
+ b --> c
+```
+
+### Source: Block
+
+```mermaid
+block-beta
+ columns 3
+ a["Author"] b["Build"] c["Publish"]
+ a --> b
+ b --> c
+```
+
+### Mindmap
+
+Organize related documentation topics.
+
+**Mindmap**
+
+Organize related documentation topics.
+
+[View Mindmap diagram](https://www.shoalrun.com/assets/diagrams/mermaid-5132acfd3a5b749b60f6-light.svg)
+
+```mermaid
+mindmap
+ root((Documentation))
+  Authoring
+   Pages
+   Components
+  Publishing
+   Builds
+   Hosting
+```
+
+### Source: Mindmap
+
+```mermaid
+mindmap
+ root((Documentation))
+  Authoring
+   Pages
+   Components
+  Publishing
+   Builds
+   Hosting
+```
+
+### Tree view
+
+Display a directory hierarchy.
+
+**Tree view**
+
+Display a directory hierarchy.
+
+[View Tree view diagram](https://www.shoalrun.com/assets/diagrams/mermaid-b87a0cb8033d4ea6c61b-light.svg)
+
+```mermaid
+treeView-beta
+ "docs"
+  "content"
+   "start.mdx"
+   "configuration.mdx"
+  "docs.config.yaml"
+```
+
+### Source: Tree view
+
+```mermaid
+treeView-beta
+ "docs"
+  "content"
+   "start.mdx"
+   "configuration.mdx"
+  "docs.config.yaml"
+```
+
+### Requirement
+
+Connect an implementation element to a requirement.
+
+**Requirement**
+
+Connect an implementation element to a requirement.
+
+[View Requirement diagram](https://www.shoalrun.com/assets/diagrams/mermaid-9b74d503a97fb3b146ea-light.svg)
+
+```mermaid
+requirementDiagram
+ requirement readable {
+ id: 1
+ text: Preserve essential instructions
+ risk: low
+ verifymethod: test
+ }
+ element markdown {
+ type: renderer
+ }
+ markdown - satisfies -> readable
+```
+
+### Source: Requirement
+
+```mermaid
+requirementDiagram
+ requirement readable {
+ id: 1
+ text: Preserve essential instructions
+ risk: low
+ verifymethod: test
+ }
+ element markdown {
+ type: renderer
+ }
+ markdown - satisfies -> readable
+```

package/agent-docs/author/components/diagrams.md

@@ -0,0 +1,163 @@
+---
+id: guide.component.diagrams
+title: Diagrams
+summary: Render flowcharts, sequence diagrams, charts, and graphs from D2 or
+  Mermaid source as static SVG.
+type: reference
+area: components
+subarea: components-visuals
+canonical: /author/components/diagrams
+---
+
+# Diagrams
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Overview
+
+**Updated: 2026-10-27.**
+
+Use `<Diagram>` for flowcharts, sequence diagrams, charts, and other graphs written as text. D2 is the default engine, with TALA as its default layout. Set `engine="mermaid"` for Mermaid syntax, rendered by [Pele](https://pele.run). Diagrams render to SVG during the build, so readers do not need a diagram script in their browser. Set a literal pixel `width`, such as `width="440"`, to cap the diagram's displayed width while allowing it to shrink on narrow screens.
+
+For the diagram languages themselves, use the official [D2 tour](https://d2lang.com/tour/intro/) and [Mermaid syntax reference](https://mermaid.js.org/intro/syntax-reference.html). Shoalrun's component controls how their source is published; those references cover each language's shapes, connections, and diagram types.
+
+Every diagram needs a short `title` and `summary`. The summary states the point of the diagram; it does not need to repeat every connection. For a complex diagram, add a fuller explanation in nearby prose so readers can understand its meaning without the graphic.
+
+## Syntax
+
+Choose D2 or Mermaid for the source language.
+
+### D2
+
+Copy the complete component, including its fenced source:
+
+````mdx
+<Diagram title="Documentation build" summary="One source produces an HTML page and a Markdown page.">
+
+```d2
+source: MDX source
+build: Shoalrun build
+html: HTML page
+markdown: Markdown page
+source -> build
+build -> html
+build -> markdown
+```
+
+</Diagram>
+````
+
+**Documentation build**
+
+One source produces an HTML page and a Markdown page.
+
+[View Documentation build diagram](https://www.shoalrun.com/assets/diagrams/d2-41baf7c4fc6643bdcf27-light.svg)
+
+```d2
+source: MDX source
+build: Shoalrun build
+html: HTML page
+markdown: Markdown page
+source -> build
+build -> html
+build -> markdown
+```
+
+Use `layout="elk"` or `layout="dagre"` when a directional flow reads better than TALA's architecture layout. D2 accepts only these three layout values.
+
+Browse the [D2 gallery](https://www.shoalrun.com/author/components/diagrams/d2-gallery.md) for containers, tables, classes, sequences, grids, and basic shapes with copyable source.
+
+The official [D2 layout guide](https://d2lang.com/tour/layouts/) compares the engines. The [D2 style guide](https://d2lang.com/tour/style/) and [theme guide](https://d2lang.com/tour/themes/) cover source-level shape styles and theme options.
+
+### Mermaid
+
+Set the engine explicitly and keep the fence language `mermaid`:
+
+````mdx
+<Diagram title="Review flow" summary="The author submits a page, then a reviewer approves it." engine="mermaid">
+
+```mermaid
+flowchart LR
+  author[Author] --> review[Review]
+  review --> publish[Publish]
+```
+
+</Diagram>
+````
+
+**Review flow**
+
+The author submits a page, then a reviewer approves it.
+
+[View Review flow diagram](https://www.shoalrun.com/assets/diagrams/mermaid-dc162ff4396acc50d4ec-light.svg)
+
+```mermaid
+flowchart LR
+  author[Author] --> review[Review]
+  review --> publish[Publish]
+```
+
+## Attributes
+
+Use these attributes to configure the component.
+
+| Attribute | Required | Meaning                                                                                                            |
+| --------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
+| `title`   | Yes      | Short literal name for the diagram.                                                                                |
+| `summary` | Yes      | Literal explanation of the diagram's point.                                                                        |
+| `engine`  | No       | `d2` by default; use `mermaid` for Mermaid source.                                                                 |
+| `layout`  | No       | D2 only: `tala` by default, or `elk` or `dagre`.                                                                   |
+| `width`   | No       | Pixel width from 1 through 4096 as a literal string, such as `"440"`; the diagram still shrinks on narrow screens. |
+
+Keep the source in one fenced code block inside the component. When quoting a complete example in Markdown, use four backticks around the outer `mdx` block so its inner three-backtick fence stays intact.
+
+See the [diagram gallery](https://www.shoalrun.com/author/components/diagrams/pele-gallery.md) for examples of every built-in Pele diagram family and 48 flowchart shapes. Use [Mermaid’s syntax reference](https://mermaid.js.org/intro/syntax-reference.html) to write the source and [Pele’s compatibility guide](https://pele.run/compatibility) to check rendering differences. External Mermaid plugins are not supported.
+
+## Styling and readability
+
+Pele diagrams inherit Shoalrun’s active palette, fonts, and corner radius. They update with light/dark mode and the theme switcher without re-rendering. Shoalrun maps Pele’s native CSS variables to its theme tokens; there is no second set of diagram aliases to learn.
+
+Override Pele’s variables in [project CSS](https://www.shoalrun.com/author/css.md). For example, adjust the nodes and their text together:
+
+```css title="styles/project.css"
+.content .doc-diagram .pele {
+  --pele-surface: var(--color-field-surface);
+  --pele-fg: var(--color-ink);
+  --pele-border: var(--color-accent);
+  --pele-radius: 8px;
+}
+```
+
+See [Pele’s styling guide](https://pele.run/theming) for all variables, series colors, and element classes. Its [examples](https://pele.run/examples) show more diagram variations. Fixed source-level colors do not follow the palette; check their contrast in both modes. Custom fonts can change label widths, so inspect long labels after overriding fonts.
+
+Without `width`, a diagram fills the available content width. Set `width="520"` to cap one diagram at 520 pixels; it still shrinks on narrower screens. Use `.doc-diagram` and `.doc-diagram figcaption` to style the frame and caption.
+
+D2 still renders separate light and dark SVG images using themes 0 and 200. Project CSS can style their frames and dimensions, but cannot reach individual nodes inside those image files.
+
+## HTML, Markdown, and agents
+
+Pele generates inline SVG during the build. It needs no browser or client-side renderer, and the diagram works without JavaScript. Each SVG has an accessible name from `title` and a visible caption with the `summary`. Published light/dark SVG files remain available for direct links and Markdown readers.
+
+The `.md` page retains the title, summary, SVG link, and original fenced D2 or Mermaid source. Readers and agents can inspect the structure without running a diagram library. Changing the renderer does not remove the source or explanation.
+
+Shoalrun disables diagram links, external images, and JavaScript callbacks. It rejects active SVG content before publication. Arbitrary HTML labels and Mermaid’s named themes are not supported by this renderer. Keep essential instructions in the summary or surrounding text.
+
+Keep a diagram in one fenced code block inside `<Diagram>`. The fence language must match the engine: `d2` or `mermaid`. Unknown engines, invalid layouts, missing titles or summaries, and render failures stop the build with the source file and diagram title.
+
+## Related reading
+
+### Next steps
+
+- [D2 gallery](https://www.shoalrun.com/author/components/diagrams/d2-gallery.md) — Compare D2 diagrams and shape syntax before writing your own.
+
+- [Pele gallery](https://www.shoalrun.com/author/components/diagrams/pele-gallery.md) — Compare diagram families and flowchart shapes before choosing syntax.
+
+### Reference while working
+
+- [CSS and theme reference](https://www.shoalrun.com/author/css.md) — Look up the diagram frame, color-mode image, and caption selectors.
+
+### Related topics
+
+- [Images](https://www.shoalrun.com/author/components/images.md) — Render a diagram from source with a caption and responsive width.

package/agent-docs/author/components/doc-link.md

@@ -0,0 +1,62 @@
+---
+id: guide.component.doc-link
+title: DocLink
+summary: Link to a page by stable document ID.
+type: reference
+area: components
+subarea: components-navigation
+canonical: /author/components/doc-link
+---
+
+# DocLink
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > DocLink
+
+**Updated: 2026-10-27.**
+
+`<DocLink>` resolves a document ID to its URL in the current publication. It is useful in MDX when the link should use a stable target and optionally inherit the target page's title.
+
+## Which link should I use?
+
+Choose a link form based on whether the destination is a document, a section, or an external resource.
+
+| Link                                                        | Use it for                                                                     | What happens                                                |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------- |
+| `[Read the guide](doc:guide.frontmatter)`                   | Most links to another Shoalrun page.                                           | Resolves the stable document ID in the current publication. |
+| `<DocLink doc="guide.frontmatter">Read the guide</DocLink>` | An MDX link by ID, especially when you want the target title as fallback text. | Resolves the same target as `doc:` Markdown.                |
+| `[Open the specification](https://example.test/spec)`       | External sites, downloads, or other URLs without a Shoalrun document ID.       | Keeps the authored URL.                                     |
+| `[Jump to fields](#fields)`                                 | A section on the current page.                                                 | Keeps the fragment link.                                    |
+
+Prefer `doc:` Markdown for ordinary prose. Both ID-based forms survive a target slug change and fail the build if the target is unavailable in this publication. A normal Markdown link to a Shoalrun route can work, but the authored URL must be updated if that route changes. Raw HTML or JSX anchors such as `<a href="...">` do not have a semantic adapter in this prototype and fail the build; use Markdown links instead.
+
+## Syntax
+
+```mdx
+<DocLink doc="guide.frontmatter">Read the frontmatter guide</DocLink>
+```
+
+## Attributes
+
+Use these attributes to configure the component.
+
+| Attribute | Required | Meaning                                                   |
+| --------- | -------- | --------------------------------------------------------- |
+| `doc`     | Yes      | Stable ID of a page available in the current publication. |
+
+If the body is empty, the target page title supplies the link text. Keep explicit body text plain. See [content and stable IDs](https://www.shoalrun.com/author/content.md).
+
+## HTML, Markdown, and agents
+
+The build keeps only the plain text inside `DocLink`, so emphasis or code formatting there is dropped. HTML links to the page; the Markdown twin links to its `.md` URL. An agent following that link receives the target’s Markdown page.
+
+## Related reading
+
+### Related topics
+
+- [Content and stable IDs](https://www.shoalrun.com/author/content.md) — Link to pages by stable ID so links survive slug changes.
+
+- [Cards and collections](https://www.shoalrun.com/author/components/cards.md) — Link to a page inline, or show it as a card with its summary.

package/agent-docs/author/components/fields.md

@@ -0,0 +1,123 @@
+---
+id: guide.component.fields
+title: Fields
+summary: Write field lists in MDX with the same readable format as OpenAPI schemas.
+type: reference
+area: components
+subarea: components-prose
+canonical: /author/components/fields
+---
+
+# Fields
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Fields
+
+**Updated: 2026-10-27.**
+
+Use `<Fields>` and `<Field>` to describe fields that are not selected from an OpenAPI schema, or to explain a small task-specific subset in your own words. The list uses the same field styling as generated schemas. If the exact contract already exists in OpenAPI, [ApiSchema](https://www.shoalrun.com/author/components/api-embeds.md) can include the source schema or one of its fields.
+
+## Syntax
+
+```mdx
+<Fields>
+<Field name="name" type="string" required minLength="1" maxLength="80" example="Casey">
+
+The name shown to readers.
+
+</Field>
+<Field name="options" type="object" optional nullable>
+
+Extra display settings.
+
+<Fields>
+<Field name="compact" type="boolean" optional default="false">
+
+Use a shorter layout.
+
+</Field>
+</Fields>
+
+</Field>
+</Fields>
+```
+
+- `name` — **required**
+
+  string; minLength: 1; maxLength: 80
+
+  Example: `Casey`
+
+  The name shown to readers.
+
+- `options` — **optional**
+
+  object; nullable
+
+  Extra display settings.
+
+  - `compact` — **optional**
+
+    boolean
+
+    Default: `false`
+
+    Use a shorter layout.
+
+`Fields` takes no attributes and needs direct `Field` children. A `Field` body accepts ordinary Markdown and supported MDX, including a nested `Fields` list. A standalone `Field` or other direct child of `Fields` fails the build.
+
+## Attributes
+
+### Attribute reference
+
+All values are literal MDX attributes. Text and numbers use quoted strings; flags are bare attributes. These declarations describe fields in the published page. They do not validate user input at runtime.
+
+| `Field` attribute        | Required | Meaning                                                                             |
+| ------------------------ | -------- | ----------------------------------------------------------------------------------- |
+| `name`                   | Yes      | Nonempty field name.                                                                |
+| `type`                   | Yes      | Nonempty type label, such as `string`, `integer`, or `array of objects`.            |
+| `required`, `optional`   | No       | Bare presence flags. Omission means optional; the two flags cannot appear together. |
+| `nullable`               | No       | Bare flag allowing a `null` value. It does not change whether the field is present. |
+| `min`, `max`             | No       | Finite numeric value bounds; `minimum` and `maximum` are equivalent spellings.      |
+| `minLength`, `maxLength` | No       | Nonnegative integer string-length bounds.                                           |
+| `minItems`, `maxItems`   | No       | Nonnegative integer array-size bounds.                                              |
+| `format`, `pattern`      | No       | Nonempty text for a format name or pattern.                                         |
+| `example`, `default`     | No       | Literal text shown as an example or default value.                                  |
+| `deprecated`             | No       | Bare flag marking the field as deprecated.                                          |
+
+Bounds must be numeric, and each minimum must be no greater than its maximum. `min` cannot be combined with `minimum`, nor `max` with `maximum`. Keep the declared type, constraints, and examples consistent with the actual contract.
+
+```mdx
+<Fields>
+<Field name="rank" type="integer" optional min="0" max="10" example="3">
+
+Position in the list.
+
+</Field>
+</Fields>
+```
+
+## HTML, Markdown, and agents
+
+The build writes a normal nested Markdown list. Each item starts with the field name and presence rule, followed by its type and authored body. For the first field above, the twin contains:
+
+```md
+- `name` — **required**
+
+  string; minLength: 1; maxLength: 80
+
+  Example: `Casey`
+
+  The name shown to readers.
+```
+
+Both formats include every field and description. The authored text is part of the page rather than copied from OpenAPI, so keep it aligned with the contract when it describes an API.
+
+## Related reading
+
+### Related topics
+
+- [ApiExample and ApiSchema](https://www.shoalrun.com/author/components/api-embeds.md) — Write field lists by hand in the same format as generated schemas.