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

package/agent-docs/start.md

@@ -0,0 +1,201 @@
+---
+id: guide.overview
+title: Getting started
+summary: Create a site, publish a page, and check both formats.
+type: tutorial
+area: project
+subarea: project-overview
+canonical: /start
+---
+
+# Getting started
+
+> 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 > Getting started
+
+**Updated: 2026-10-27.**
+
+This quickstart takes you from installing Shoalrun to your own working documentation site. You will scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
+
+> **Alpha:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between alpha releases.
+
+## Prerequisites
+
+Install Node.js 22.12 or newer and npm. Use the npm that comes with Node.js; Shoalrun sets no separate npm version. The commands below use a POSIX shell, such as Bash or Zsh.
+
+The public npm package needs no account or token.
+
+## Start your own project
+
+Install an exact version of the alpha and initialize the minimal starter:
+
+```sh
+mkdir my-docs
+cd my-docs
+npm init -y
+npm install --save-exact @shoalrun/cli@0.1.0-alpha.11
+npx --no-install shoalrun init .
+```
+
+The starter puts `docs.config.yaml` and `content/` in your project. Initialization refuses to overwrite starter files, and preserves unrelated files such as the package manifest and lockfile.
+
+Preview the starter:
+
+```sh
+npx --no-install shoalrun dev docs.config.yaml site-dist --port 8765
+```
+
+Open `http://127.0.0.1:8765/`. You should see the Acme handbook example with a welcome page and an installation page. Press **Ctrl+C** to stop the preview before continuing.
+
+## Create a page
+
+Start new pages from a template. From the same `my-docs/` directory, scaffold the built-in how-to template:
+
+```sh
+npx --no-install shoalrun scaffold how-to -n content/first-page.mdx \
+  --id guide.first-page --title 'Your first page'
+```
+
+The command creates draft frontmatter and a body with prompts for outcomes, steps, checks, and recovery. It derives the slug `/first-page` and refuses to overwrite existing files. Use a registered project template when your team has one; [create a page](https://www.shoalrun.com/author/add-page.md) explains the choices.
+
+Open `content/first-page.mdx`. Set `updated` to today's date in `YYYY-MM-DD` format. Replace its generated summary with `Find the installation guide and check its Markdown page.` Keep `access.policy` set to `draft` while completing the prompts.
+
+For this example, replace the generated YAML header with the following completed header. It omits the optional `description` and `tags` fields, whose template prompts would otherwise prevent publication. Use today's date for `updated`:
+
+```yaml title="Completed page frontmatter"
+id: guide.first-page
+title: Your first page
+summary: Find the installation guide and check its Markdown page.
+type: how-to
+slug: /first-page
+channel: production
+version: current
+language: en
+updated: 2026-10-24
+access: { policy: draft }
+card: { icon: book-open }
+```
+
+For this small walkthrough, replace the template body below the closing frontmatter delimiter with this completed example. It keeps the introduction, actions, and verification together:
+
+```md title="Completed template body"
+Find this handbook's installation instructions and their Markdown copy.
+This page is for readers exploring the example documentation site.
+
+## Before you begin
+
+Run the local documentation preview and open its home page.
+No account or credentials are needed.
+
+## Complete the task
+
+1. Open Setup in the sidebar.
+2. Choose Install Acme to open the [installation guide](doc:guide.install).
+3. Read the example version command. Acme is fictional; do not run it.
+
+## Check the result
+
+The installation page shows an example command: `acme --version`.
+Open `/install.md` on the same local server and find that command there too.
+
+## Handle common failures
+
+If the page does not load, restart the preview and check its printed address.
+If the installation page is missing, restore the minimal starter's install file.
+
+## How it works for agents
+
+The Markdown page contains the same instructions and version command.
+Its installation link points to `/install.md`.
+
+## Next steps
+
+Read the [installation guide](doc:guide.install) in either format.
+
+## Editorial evidence
+
+The minimal starter's `content/install.mdx` supplies the page and example command.
+```
+
+Review the content and replace every remaining template prompt before setting `access: { policy: public }` in the header. The build rejects unfinished public drafts, including the generated draft summary.
+
+`id` is the stable target used by navigation and `doc:` links. `slug` sets the page URL. Keep the generated publication fields; the minimal starter enables their combination.
+
+## Add the page to navigation
+
+In `docs.config.yaml`, replace the existing `navigation` block with this block. Keep the rest of the file:
+
+```yaml title="docs.config.yaml"
+navigation:
+  - id: welcome
+    doc: guide.welcome
+  - id: setup
+    label: Setup
+    items:
+      - id: install
+        doc: guide.install
+      - id: first-page
+        doc: guide.first-page
+```
+
+Creating a page does not add it to navigation automatically. This entry puts **Your first page** under **Setup**, using its frontmatter title as the label.
+
+## Build and check both outputs
+
+Validate the configuration, build the site, and serve it:
+
+```sh
+npx --no-install shoalrun config validate docs.config.yaml
+npx --no-install shoalrun build docs.config.yaml site-dist
+npx --no-install shoalrun serve site-dist --port 8765
+```
+
+Check these URLs in your browser:
+
+- `http://127.0.0.1:8765/first-page`: the HTML page, with **Your first page** in the sidebar.
+- `http://127.0.0.1:8765/first-page.md`: the same content as Markdown.
+
+The installation link should take you to `/install` in HTML and `/install.md` in the Markdown output. Commands print JSON and return a nonzero exit code on failure. If a page is missing, check its publication fields and navigation entry.
+
+Press **Ctrl+C** to stop the server. For ongoing writing, run the `dev` command again; it rebuilds and refreshes the browser when you save edits. Builds replace the whole output directory, so keep `site-dist/` separate from your source files. Add `site-dist/` and `.shoalrun/` to your project's `.gitignore` if you do not want to track generated files.
+
+## Make it yours
+
+Change `site.title` in `docs.config.yaml`, replace the Acme example content, and keep adding pages with the [add a page guide](https://www.shoalrun.com/author/add-page.md). The [configuration guide](https://www.shoalrun.com/configuration.md) explains how to compose project settings. The [page metadata guide](https://www.shoalrun.com/author/frontmatter.md) explains drafts and shared defaults. For help from an agent, see [use the bundled agent skills](https://www.shoalrun.com/contribute/agent-skills.md).
+
+Continue by [adding an OpenAPI API](https://www.shoalrun.com/publish/api-references.md), or [publish your site](https://www.shoalrun.com/publish.md).
+
+## Migrating from GitHub Packages
+
+The public npm package needs no account or token. If you used the earlier GitHub Packages alpha, run `npm config get @shoalrun:registry`. Remove or replace any `@shoalrun:registry=https://npm.pkg.github.com` entry in your project or user `.npmrc`. To explicitly select npm during migration, add `--@shoalrun:registry=https://registry.npmjs.org` to the install command below. Commit the updated manifest and lockfile together, and check that Shoalrun resolves from `registry.npmjs.org`.
+
+## Build this site
+
+If you maintain Shoalrun’s documentation source, follow [Build this documentation site](https://www.shoalrun.com/recipes/build-docs.md). That workflow uses the docs repository and its npm scripts.
+
+## Check writing style
+
+For checks on your own built site, see [audit documentation](https://www.shoalrun.com/publish/audit.md).
+
+## Related reading
+
+### Next steps
+
+- [Create a page](https://www.shoalrun.com/author/add-page.md) — Create another page and add it to navigation.
+
+### Reference while working
+
+- [CLI reference](https://www.shoalrun.com/cli.md) — Look up each command's arguments, defaults, and failure cases.
+
+- [Example configs](https://www.shoalrun.com/config/examples.md) — Start from a complete config for a common kind of site.
+
+- [Glossary](https://www.shoalrun.com/glossary.md) — Look up a term a guide uses before you know it.
+
+### Related topics
+
+- [Use the bundled agent skills](https://www.shoalrun.com/contribute/agent-skills.md) — Give an agent the same setup and authoring workflow as a bundled skill.
+
+- [How Shoalrun works](https://www.shoalrun.com/concepts.md) — Learn the build pipeline and the terms the rest of these docs use.

package/agent-docs/start.sections/add-the-page-to-navigation.md

@@ -0,0 +1,50 @@
+---
+id: guide.overview
+title: Getting started
+summary: Create a site, publish a page, and check both formats.
+type: tutorial
+area: project
+subarea: project-overview
+canonical: /start
+---
+
+# Getting started
+
+> 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 > Getting started
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/start.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Create a page](https://www.shoalrun.com/author/add-page.md) — Create another page and add it to navigation.
+
+This quickstart takes you from installing Shoalrun to your own working documentation site. You will scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
+
+> **Alpha:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between alpha releases.
+
+## Add the page to navigation
+
+In `docs.config.yaml`, replace the existing `navigation` block with this block. Keep the rest of the file:
+
+```yaml title="docs.config.yaml"
+navigation:
+  - id: welcome
+    doc: guide.welcome
+  - id: setup
+    label: Setup
+    items:
+      - id: install
+        doc: guide.install
+      - id: first-page
+        doc: guide.first-page
+```
+
+Creating a page does not add it to navigation automatically. This entry puts **Your first page** under **Setup**, using its frontmatter title as the label.

package/agent-docs/start.sections/build-and-check-both-outputs.md

@@ -0,0 +1,50 @@
+---
+id: guide.overview
+title: Getting started
+summary: Create a site, publish a page, and check both formats.
+type: tutorial
+area: project
+subarea: project-overview
+canonical: /start
+---
+
+# Getting started
+
+> 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 > Getting started
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/start.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Create a page](https://www.shoalrun.com/author/add-page.md) — Create another page and add it to navigation.
+
+This quickstart takes you from installing Shoalrun to your own working documentation site. You will scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
+
+> **Alpha:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between alpha releases.
+
+## Build and check both outputs
+
+Validate the configuration, build the site, and serve it:
+
+```sh
+npx --no-install shoalrun config validate docs.config.yaml
+npx --no-install shoalrun build docs.config.yaml site-dist
+npx --no-install shoalrun serve site-dist --port 8765
+```
+
+Check these URLs in your browser:
+
+- `http://127.0.0.1:8765/first-page`: the HTML page, with **Your first page** in the sidebar.
+- `http://127.0.0.1:8765/first-page.md`: the same content as Markdown.
+
+The installation link should take you to `/install` in HTML and `/install.md` in the Markdown output. Commands print JSON and return a nonzero exit code on failure. If a page is missing, check its publication fields and navigation entry.
+
+Press **Ctrl+C** to stop the server. For ongoing writing, run the `dev` command again; it rebuilds and refreshes the browser when you save edits. Builds replace the whole output directory, so keep `site-dist/` separate from your source files. Add `site-dist/` and `.shoalrun/` to your project's `.gitignore` if you do not want to track generated files.

package/agent-docs/start.sections/build-this-site.md

@@ -0,0 +1,35 @@
+---
+id: guide.overview
+title: Getting started
+summary: Create a site, publish a page, and check both formats.
+type: tutorial
+area: project
+subarea: project-overview
+canonical: /start
+---
+
+# Getting started
+
+> 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 > Getting started
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/start.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Create a page](https://www.shoalrun.com/author/add-page.md) — Create another page and add it to navigation.
+
+This quickstart takes you from installing Shoalrun to your own working documentation site. You will scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
+
+> **Alpha:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between alpha releases.
+
+## Build this site
+
+If you maintain Shoalrun’s documentation source, follow [Build this documentation site](https://www.shoalrun.com/recipes/build-docs.md). That workflow uses the docs repository and its npm scripts.

package/agent-docs/start.sections/check-writing-style.md

@@ -0,0 +1,35 @@
+---
+id: guide.overview
+title: Getting started
+summary: Create a site, publish a page, and check both formats.
+type: tutorial
+area: project
+subarea: project-overview
+canonical: /start
+---
+
+# Getting started
+
+> 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 > Getting started
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/start.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Create a page](https://www.shoalrun.com/author/add-page.md) — Create another page and add it to navigation.
+
+This quickstart takes you from installing Shoalrun to your own working documentation site. You will scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
+
+> **Alpha:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between alpha releases.
+
+## Check writing style
+
+For checks on your own built site, see [audit documentation](https://www.shoalrun.com/publish/audit.md).

package/agent-docs/start.sections/create-a-page.md

@@ -0,0 +1,105 @@
+---
+id: guide.overview
+title: Getting started
+summary: Create a site, publish a page, and check both formats.
+type: tutorial
+area: project
+subarea: project-overview
+canonical: /start
+---
+
+# Getting started
+
+> 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 > Getting started
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/start.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Create a page](https://www.shoalrun.com/author/add-page.md) — Create another page and add it to navigation.
+
+This quickstart takes you from installing Shoalrun to your own working documentation site. You will scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
+
+> **Alpha:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between alpha releases.
+
+## Create a page
+
+Start new pages from a template. From the same `my-docs/` directory, scaffold the built-in how-to template:
+
+```sh
+npx --no-install shoalrun scaffold how-to -n content/first-page.mdx \
+  --id guide.first-page --title 'Your first page'
+```
+
+The command creates draft frontmatter and a body with prompts for outcomes, steps, checks, and recovery. It derives the slug `/first-page` and refuses to overwrite existing files. Use a registered project template when your team has one; [create a page](https://www.shoalrun.com/author/add-page.md) explains the choices.
+
+Open `content/first-page.mdx`. Set `updated` to today's date in `YYYY-MM-DD` format. Replace its generated summary with `Find the installation guide and check its Markdown page.` Keep `access.policy` set to `draft` while completing the prompts.
+
+For this example, replace the generated YAML header with the following completed header. It omits the optional `description` and `tags` fields, whose template prompts would otherwise prevent publication. Use today's date for `updated`:
+
+```yaml title="Completed page frontmatter"
+id: guide.first-page
+title: Your first page
+summary: Find the installation guide and check its Markdown page.
+type: how-to
+slug: /first-page
+channel: production
+version: current
+language: en
+updated: 2026-10-24
+access: { policy: draft }
+card: { icon: book-open }
+```
+
+For this small walkthrough, replace the template body below the closing frontmatter delimiter with this completed example. It keeps the introduction, actions, and verification together:
+
+```md title="Completed template body"
+Find this handbook's installation instructions and their Markdown copy.
+This page is for readers exploring the example documentation site.
+
+## Before you begin
+
+Run the local documentation preview and open its home page.
+No account or credentials are needed.
+
+## Complete the task
+
+1. Open Setup in the sidebar.
+2. Choose Install Acme to open the [installation guide](doc:guide.install).
+3. Read the example version command. Acme is fictional; do not run it.
+
+## Check the result
+
+The installation page shows an example command: `acme --version`.
+Open `/install.md` on the same local server and find that command there too.
+
+## Handle common failures
+
+If the page does not load, restart the preview and check its printed address.
+If the installation page is missing, restore the minimal starter's install file.
+
+## How it works for agents
+
+The Markdown page contains the same instructions and version command.
+Its installation link points to `/install.md`.
+
+## Next steps
+
+Read the [installation guide](doc:guide.install) in either format.
+
+## Editorial evidence
+
+The minimal starter's `content/install.mdx` supplies the page and example command.
+```
+
+Review the content and replace every remaining template prompt before setting `access: { policy: public }` in the header. The build rejects unfinished public drafts, including the generated draft summary.
+
+`id` is the stable target used by navigation and `doc:` links. `slug` sets the page URL. Keep the generated publication fields; the minimal starter enables their combination.

package/agent-docs/start.sections/make-it-yours.md

@@ -0,0 +1,37 @@
+---
+id: guide.overview
+title: Getting started
+summary: Create a site, publish a page, and check both formats.
+type: tutorial
+area: project
+subarea: project-overview
+canonical: /start
+---
+
+# Getting started
+
+> 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 > Getting started
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/start.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Create a page](https://www.shoalrun.com/author/add-page.md) — Create another page and add it to navigation.
+
+This quickstart takes you from installing Shoalrun to your own working documentation site. You will scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
+
+> **Alpha:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between alpha releases.
+
+## Make it yours
+
+Change `site.title` in `docs.config.yaml`, replace the Acme example content, and keep adding pages with the [add a page guide](https://www.shoalrun.com/author/add-page.md). The [configuration guide](https://www.shoalrun.com/configuration.md) explains how to compose project settings. The [page metadata guide](https://www.shoalrun.com/author/frontmatter.md) explains drafts and shared defaults. For help from an agent, see [use the bundled agent skills](https://www.shoalrun.com/contribute/agent-skills.md).
+
+Continue by [adding an OpenAPI API](https://www.shoalrun.com/publish/api-references.md), or [publish your site](https://www.shoalrun.com/publish.md).

package/agent-docs/start.sections/migrating-from-github-packages.md

@@ -0,0 +1,35 @@
+---
+id: guide.overview
+title: Getting started
+summary: Create a site, publish a page, and check both formats.
+type: tutorial
+area: project
+subarea: project-overview
+canonical: /start
+---
+
+# Getting started
+
+> 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 > Getting started
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/start.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Create a page](https://www.shoalrun.com/author/add-page.md) — Create another page and add it to navigation.
+
+This quickstart takes you from installing Shoalrun to your own working documentation site. You will scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
+
+> **Alpha:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between alpha releases.
+
+## Migrating from GitHub Packages
+
+The public npm package needs no account or token. If you used the earlier GitHub Packages alpha, run `npm config get @shoalrun:registry`. Remove or replace any `@shoalrun:registry=https://npm.pkg.github.com` entry in your project or user `.npmrc`. To explicitly select npm during migration, add `--@shoalrun:registry=https://registry.npmjs.org` to the install command below. Commit the updated manifest and lockfile together, and check that Shoalrun resolves from `registry.npmjs.org`.

package/agent-docs/start.sections/prerequisites.md

@@ -0,0 +1,37 @@
+---
+id: guide.overview
+title: Getting started
+summary: Create a site, publish a page, and check both formats.
+type: tutorial
+area: project
+subarea: project-overview
+canonical: /start
+---
+
+# Getting started
+
+> 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 > Getting started
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/start.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Create a page](https://www.shoalrun.com/author/add-page.md) — Create another page and add it to navigation.
+
+This quickstart takes you from installing Shoalrun to your own working documentation site. You will scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
+
+> **Alpha:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between alpha releases.
+
+## Prerequisites
+
+Install Node.js 22.12 or newer and npm. Use the npm that comes with Node.js; Shoalrun sets no separate npm version. The commands below use a POSIX shell, such as Bash or Zsh.
+
+The public npm package needs no account or token.

package/agent-docs/start.sections/related-reading.md

@@ -0,0 +1,45 @@
+---
+id: guide.overview
+title: Getting started
+summary: Create a site, publish a page, and check both formats.
+type: tutorial
+area: project
+subarea: project-overview
+canonical: /start
+---
+
+# Getting started
+
+> 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 > Getting started
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/start.md)
+
+This quickstart takes you from installing Shoalrun to your own working documentation site. You will scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
+
+> **Alpha:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between alpha releases.
+
+## Related reading
+
+### Next steps
+
+- [Create a page](https://www.shoalrun.com/author/add-page.md) — Create another page and add it to navigation.
+
+### Reference while working
+
+- [CLI reference](https://www.shoalrun.com/cli.md) — Look up each command's arguments, defaults, and failure cases.
+
+- [Example configs](https://www.shoalrun.com/config/examples.md) — Start from a complete config for a common kind of site.
+
+- [Glossary](https://www.shoalrun.com/glossary.md) — Look up a term a guide uses before you know it.
+
+### Related topics
+
+- [Use the bundled agent skills](https://www.shoalrun.com/contribute/agent-skills.md) — Give an agent the same setup and authoring workflow as a bundled skill.
+
+- [How Shoalrun works](https://www.shoalrun.com/concepts.md) — Learn the build pipeline and the terms the rest of these docs use.