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

package/agent-docs/example-api/create-note.md

@@ -0,0 +1,344 @@
+---
+id: reference.create-note
+title: Create a note
+summary: Preview an API operation page built from a small, fictional OpenAPI file.
+type: api-reference
+area: api
+subarea: api-examples
+canonical: /example-api/create-note
+---
+
+# Create a note
+
+> 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) > Document an API > Examples > Example Notes API > Create a note
+
+**Updated: 2026-10-19.**
+
+> Fictional API example. This page demonstrates documentation features; its operations do not describe a live service.
+
+This page is a live example of an API reference generated by Shoalrun. The [source OpenAPI file](https://www.shoalrun.com/api/notes/production/current/openapi.yaml) defines one fictional operation; this introduction is authored in MDX. The build combines them into the operation details below and the example panel on the right.
+
+> **Example only:** The Notes API is fictional. These requests are examples, not calls to a live service.
+
+OpenAPI for this operation: [Download JSON](https://www.shoalrun.com/api/operations/production/current/en/notes-create-2f1dbbdb63898bb3e6946fd275e1f38452bda5b95569e75144d6fa72b711b892.json).
+
+## POST /notes
+
+Create a note
+
+Save a short note in this fictional API.
+
+### Servers
+
+`https://api.example.test`
+
+### Request body
+
+Required.
+
+#### application/json
+
+object
+
+1 property
+
+- `text` `string` **required** 
+
+  maxLength: 280
+
+  The note to save.
+
+##### Example: A greeting
+
+Key: greeting. Location: request; application/json. Authored in OpenAPI.
+
+```json
+{
+  "text": "Hello from Shoalrun!"
+}
+```
+
+Example request (cURL):
+
+```bash
+curl --request POST \
+  --url 'https://api.example.test/notes' \
+  --header 'Content-Type: application/json' \
+  --data-raw '{"text":"Hello from Shoalrun!"}'
+```
+
+##### Example: A reminder
+
+Key: reminder. Location: request; application/json. Authored in OpenAPI.
+
+```json
+{
+  "text": "Review the release notes."
+}
+```
+
+Example request (cURL):
+
+```bash
+curl --request POST \
+  --url 'https://api.example.test/notes' \
+  --header 'Content-Type: application/json' \
+  --data-raw '{"text":"Review the release notes."}'
+```
+
+##### Example: A question
+
+Key: question. Location: request; application/json. Authored in OpenAPI.
+
+```json
+{
+  "text": "Is the preview ready?"
+}
+```
+
+Example request (cURL):
+
+```bash
+curl --request POST \
+  --url 'https://api.example.test/notes' \
+  --header 'Content-Type: application/json' \
+  --data-raw '{"text":"Is the preview ready?"}'
+```
+
+##### Example: A status update
+
+Key: update. Location: request; application/json. Authored in OpenAPI.
+
+```json
+{
+  "text": "The build passed."
+}
+```
+
+Example request (cURL):
+
+```bash
+curl --request POST \
+  --url 'https://api.example.test/notes' \
+  --header 'Content-Type: application/json' \
+  --data-raw '{"text":"The build passed."}'
+```
+
+##### Example: A handoff
+
+Key: handoff. Location: request; application/json. Authored in OpenAPI.
+
+```json
+{
+  "text": "Casey owns the next review."
+}
+```
+
+Example request (cURL):
+
+```bash
+curl --request POST \
+  --url 'https://api.example.test/notes' \
+  --header 'Content-Type: application/json' \
+  --data-raw '{"text":"Casey owns the next review."}'
+```
+
+##### Example: A meeting note
+
+Key: meeting. Location: request; application/json. Authored in OpenAPI.
+
+```json
+{
+  "text": "Discuss the API response shape."
+}
+```
+
+Example request (cURL):
+
+```bash
+curl --request POST \
+  --url 'https://api.example.test/notes' \
+  --header 'Content-Type: application/json' \
+  --data-raw '{"text":"Discuss the API response shape."}'
+```
+
+##### Example: A follow-up
+
+Key: followup. Location: request; application/json. Authored in OpenAPI.
+
+```json
+{
+  "text": "Check the example links."
+}
+```
+
+Example request (cURL):
+
+```bash
+curl --request POST \
+  --url 'https://api.example.test/notes' \
+  --header 'Content-Type: application/json' \
+  --data-raw '{"text":"Check the example links."}'
+```
+
+##### Example: A short label
+
+Key: label. Location: request; application/json. Authored in OpenAPI.
+
+```json
+{
+  "text": "Needs review"
+}
+```
+
+Example request (cURL):
+
+```bash
+curl --request POST \
+  --url 'https://api.example.test/notes' \
+  --header 'Content-Type: application/json' \
+  --data-raw '{"text":"Needs review"}'
+```
+
+##### Example: Unicode text
+
+Key: unicode. Location: request; application/json. Authored in OpenAPI.
+
+```json
+{
+  "text": "Café notes"
+}
+```
+
+Example request (cURL):
+
+```bash
+curl --request POST \
+  --url 'https://api.example.test/notes' \
+  --header 'Content-Type: application/json' \
+  --data-raw '{"text":"Café notes"}'
+```
+
+##### Example: A completion note
+
+Key: completion. Location: request; application/json. Authored in OpenAPI.
+
+```json
+{
+  "text": "Documentation published."
+}
+```
+
+Example request (cURL):
+
+```bash
+curl --request POST \
+  --url 'https://api.example.test/notes' \
+  --header 'Content-Type: application/json' \
+  --data-raw '{"text":"Documentation published."}'
+```
+
+### Responses
+
+#### 201: Created
+
+`application/json`
+
+The saved note.
+
+A saved note with its author, labels, and display metadata.
+
+7 properties
+
+- `id` `string` **always present** 
+
+  The generated note ID.
+
+- `text` `string` **always present** 
+
+  maxLength: 280
+
+  The saved text.
+
+- `createdAt` `string` **always present** 
+
+  format: date-time
+
+  When the note was created.
+
+- `archivedAt` `string` **always present** **nullable** 
+
+  format: date-time
+
+  When the note was archived, or null while active.
+
+- `author` `object` **always present** 
+
+  The person who created the note.
+
+  2 properties
+
+  - `id` `string` **always present** 
+
+    The author's user ID.
+
+  - `displayName` `string` **always present** 
+
+    The author's display name.
+
+- `tags` `list of string` **may be absent** 
+
+  Labels used to organize the note.
+
+  Array items:
+
+  string
+
+- `metadata` `object` **may be absent** 
+
+  Optional display information for a note.
+
+  2 properties
+
+  - `source` `string` **may be absent** 
+
+    Where the note came from.
+
+  - `pinned` `boolean` **may be absent** 
+
+    Whether the note stays at the top.
+
+##### Example: Created release note
+
+Key: saved. Location: response 201; application/json. Authored in OpenAPI.
+
+An active note with a nested author, two labels, and optional display metadata.
+
+```json
+{
+  "id": "note_123",
+  "text": "Review the release candidate.",
+  "createdAt": "2026-10-18T09:30:00Z",
+  "archivedAt": null,
+  "author": {
+    "id": "usr_42",
+    "displayName": "Morgan Lee"
+  },
+  "tags": [
+    "release",
+    "review"
+  ],
+  "metadata": {
+    "source": "release-checklist",
+    "pinned": true
+  }
+}
+```
+
+## Related guides
+
+- [Prepare a note request](https://www.shoalrun.com/example-api/write-note.md) — Prepare a fictional note payload and follow its linked operation contracts.

package/agent-docs/example-api/generated/get-note-cbedb319.md

@@ -0,0 +1,165 @@
+---
+id: reference.notes.getNote
+title: Get a note
+summary: GET /notes/{id}
+type: api-reference
+area: api
+subarea: api-reference
+canonical: /example-api/generated/get-note-cbedb319
+---
+
+# Get a note
+
+> 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) > Document an API > Examples > Example Notes API > Notes > Get a note
+
+**Updated: 2026-10-19.**
+
+> Fictional API example. This page demonstrates documentation features; its operations do not describe a live service.
+
+This reference is generated from the OpenAPI description. It shows the operation contract; follow any related guides below for task steps and context.
+
+OpenAPI for this operation: [Download JSON](https://www.shoalrun.com/api/operations/production/current/en/notes-getnote-939949cb510084389ae9dd3cd545e8b07ea14d76ec4d15bee06660e70c669b19.json).
+
+## GET /notes/{id}
+
+Get a note
+
+Read a saved note from this fictional API.
+
+### Servers
+
+`https://api.example.test`
+
+### Parameters
+
+#### id (path)
+
+Required
+
+string
+
+**Known note ID**: `"note_123"`
+
+### Example request
+
+```bash
+curl --request GET \
+  --url 'https://api.example.test/notes/YOUR_ID'
+```
+
+### Responses
+
+#### 200: OK
+
+`application/json`
+
+The saved note.
+
+A saved note with its author, labels, and display metadata.
+
+7 properties
+
+- `id` `string` **always present** 
+
+  The generated note ID.
+
+- `text` `string` **always present** 
+
+  maxLength: 280
+
+  The saved text.
+
+- `createdAt` `string` **always present** 
+
+  format: date-time
+
+  When the note was created.
+
+- `archivedAt` `string` **always present** **nullable** 
+
+  format: date-time
+
+  When the note was archived, or null while active.
+
+- `author` `object` **always present** 
+
+  The person who created the note.
+
+  2 properties
+
+  - `id` `string` **always present** 
+
+    The author's user ID.
+
+  - `displayName` `string` **always present** 
+
+    The author's display name.
+
+- `tags` `list of string` **may be absent** 
+
+  Labels used to organize the note.
+
+  Array items:
+
+  string
+
+- `metadata` `object` **may be absent** 
+
+  Optional display information for a note.
+
+  2 properties
+
+  - `source` `string` **may be absent** 
+
+    Where the note came from.
+
+  - `pinned` `boolean` **may be absent** 
+
+    Whether the note stays at the top.
+
+##### Example: Retrieved release note
+
+Key: saved. Location: response 200; application/json. Authored in OpenAPI.
+
+```json
+{
+  "id": "note_123",
+  "text": "Review the release candidate.",
+  "createdAt": "2026-10-18T09:30:00Z",
+  "archivedAt": null,
+  "author": {
+    "id": "usr_42",
+    "displayName": "Morgan Lee"
+  },
+  "tags": [
+    "release",
+    "review"
+  ],
+  "metadata": {
+    "source": "release-checklist",
+    "pinned": true
+  }
+}
+```
+
+#### 404: Not Found
+
+`application/json`
+
+No note has that ID.
+
+object
+
+2 properties
+
+- `code` `string` **always present** 
+
+- `message` `string` **always present** 
+
+## Related guides
+
+- [Prepare a note request](https://www.shoalrun.com/example-api/write-note.md) — Prepare a fictional note payload and follow its linked operation contracts.

package/agent-docs/example-api/write-note.md

@@ -0,0 +1,55 @@
+---
+id: guide.example-note
+title: Prepare a note request
+summary: Prepare a fictional note payload and follow its linked operation contracts.
+type: how-to
+area: api
+subarea: api-examples
+canonical: /example-api/write-note
+---
+
+# Prepare a note request
+
+> 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) > Document an API > Examples > Example Notes API > Prepare a note request
+
+**Updated: 2026-10-26.**
+
+> Fictional API example. This page demonstrates documentation features; its operations do not describe a live service.
+
+The Notes API is fictional. This short guide demonstrates how a task page can point readers to an API reference without hard-coding the reference's URL.
+
+## Prepare a note
+
+Choose a short message and save this JSON as `request.json`. The fictional create operation accepts this body at `POST /notes`:
+
+```json title="request.json"
+{"text":"Hello from Shoalrun!"}
+```
+
+The API references linked below cover creating and reading a note. The links on this page and on each reference are generated from `relatedApiReferences` in this guide's frontmatter. The Create a note page has an authored introduction; the Get a note page is generated from the spec without an MDX source page.
+
+## Check the request
+
+From the directory containing `request.json`, check that the message is a nonempty string:
+
+```sh
+node -e 'const note = require("./request.json"); if (typeof note.text !== "string" || !note.text.trim()) process.exit(1); console.log(note.text)'
+```
+
+The example prints `Hello from Shoalrun!` and exits successfully. If parsing fails or the command exits with code 1, correct the JSON or supply a nonempty message. Compare the payload with the [Create a note contract](https://www.shoalrun.com/example-api/create-note.md) before adapting it to a real API. This check validates the local example; the fixture has no live endpoint to receive a request.
+
+## Related reading
+
+### Next steps
+
+- [Create a note](https://www.shoalrun.com/example-api/create-note.md) — Read the generated API reference this guide links to.
+
+## Related API references
+
+- [Create a note](https://www.shoalrun.com/example-api/create-note.md) — Preview an API operation page built from a small, fictional OpenAPI file.
+
+- [Get a note](https://www.shoalrun.com/example-api/generated/get-note-cbedb319.md) — GET /notes/{id}

package/agent-docs/explore.md

@@ -0,0 +1,54 @@
+---
+id: guide.explore
+title: Explore the docs
+summary: Explore topics and follow connections to find your next page.
+type: overview
+area: discovery
+subarea: discovery-search
+subjectLifecycle: experimental
+canonical: /explore
+---
+
+# Explore the docs
+
+> 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 > Explore the docs
+
+**Updated: 2026-10-25.**
+
+**Status: Experimental.**
+
+## Agent entry point
+
+**Start by fetching [documents.json](https://www.shoalrun.com/documents.json). Use this manifest to navigate the documentation and inspect the knowledge graph.**
+
+Read `documents` for page IDs, titles, summaries, categories, and Markdown URLs. Read `relationships` for source and target IDs, relationship types, and authored reasons. Follow a page's Markdown URL to read its content. Use the [documentation index](https://www.shoalrun.com/llms.min.txt) when you need a text list of pages.
+
+The interactive visualization below is for human navigation. Agents should use the manifest directly; parsing the graph controls or running browser JavaScript is unnecessary.
+
+The Markdown twin contains this guide and its topic links. Use the manifest for the complete page catalog and relationship data.
+
+**Experimental visualization.** Layouts, filters, and interactions may change as we improve this explorer.
+
+Choose a topic, find a page, and follow the connections. Filter by area, subarea, or page type to narrow your view. Select a page to read its summary and see where it leads.
+
+## Start with a topic
+
+- [Get started](https://www.shoalrun.com/what-is-shoalrun.md): understand Shoalrun and set up a documentation project.
+- [Write documentation](https://www.shoalrun.com/author/add-page.md): create a page and publish it in navigation.
+- [Use components](https://www.shoalrun.com/author/components.md): add examples, diagrams, and other structured content.
+- [Publish your site](https://www.shoalrun.com/publish.md): build and deploy your documentation.
+- [Browse recipes](https://www.shoalrun.com/author/cookbooks.md): choose a procedure for your task.
+
+The map groups pages by their declared area and subarea. These categories describe the subject of each page independently of navigation. Circles show topics within topics. Select a topic circle to zoom into it, then select a page to preview it. Branches start with the main node. Select it to reveal topics, then expand or collapse individual branches to find their pages. Connections show the reading relationships between pages. Matrix places source pages on rows and destination pages on columns. Select a marked cell to inspect its relationships. Filtered matrices open at a readable size. Scroll to move through the matrix, or pinch or hold Ctrl while scrolling to zoom. **Readable** restores the label size; **Fit** shows the whole matrix. Symbols identify relationship types without relying on color, and related topics and comparisons appear in both directions. Force arranges pages around those same reading relationships. Circle size reflects the number of pages in a topic.
+
+Scroll or pinch to zoom, drag to pan, or use the zoom buttons. **Fit** brings the whole map into view. When the map is focused, use the arrow keys to pan, `+` and `-` to zoom, and `0` to fit.
+
+Filter relationships to follow prerequisites, next steps, references, related topics, comparisons, or deeper reading. Edges show their type and point from the source page to its related page. Related topics and comparisons apply in both directions. Focus, Audience, and Reader filters use the site's configured page facets. Pages without a value for a facet remain available to every reader.
+
+The sidebar's **Why they’re connected** explanation is authored text from each relationship's `reason` field in `docs/config/relationships.yaml`, published in `documents.json` at build time. Viewing the graph makes no model calls and generates no new relationships or explanations. To change that text, edit the reason and rebuild. [Declare relationships](https://www.shoalrun.com/author/related-reading.md) explains the fields and validation.
+
+Select a page to preview its summary and follow a connection, or choose **Read this page** to open it. The matching page list offers the same page selection without using the map. Connections use the site's declared reading relationships; a page can be useful even when it has no declared connections.