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

package/agent-docs/example-api/cedar/get-parcel-edee10e6.md

@@ -0,0 +1,122 @@
+---
+id: reference.cedar.getParcel
+title: Get a parcel
+summary: GET /parcels/{parcelId}
+type: api-reference
+area: api
+subarea: api-reference
+canonical: /example-api/cedar/get-parcel-edee10e6
+---
+
+# Get a parcel
+
+> 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 > Cedar Parcel API · styling lab > Parcels > Get a parcel
+
+**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/cedar-getparcel-93cdaec636ea6466eb0bee3486d38759473a72eae27c8bb56f644ff654d0372f.json).
+
+## GET /parcels/{parcelId}
+
+Get a parcel
+
+This lookup route does not use the API's default authentication.
+
+### Servers
+
+`https://lookup.api.cedar-parcel.example/v1` — Public lookup host
+
+### Authentication
+
+No authentication required.
+
+### Parameters
+
+#### parcelId (path)
+
+Required
+
+string
+
+### Example request
+
+```bash
+curl --request GET \
+  --url 'https://lookup.api.cedar-parcel.example/v1/parcels/YOUR_PARCELID'
+```
+
+### Responses
+
+#### 200: OK
+
+`application/json`
+
+Parcel found.
+
+5 properties
+
+- `parcelId` `string` **always present** 
+
+- `status` `enum<string>` **always present**&#x20;
+
+  Available options: `"label_created"`, `"in_transit"`, `"delivered"`, `"exception"`
+
+- `declaredValue` `number` **always present**&#x20;
+
+  minimum: 0; multipleOf: 0.01
+
+  Value in currency units, to the nearest cent.
+
+- `recipient` `object` **always present**&#x20;
+
+  2 properties
+
+  - `city` `string` **always present**&#x20;
+
+  - `postalCode` `string` **always present**&#x20;
+
+- `events` `list of object` **may be absent**&#x20;
+
+  Tracking history in chronological order.
+
+  Array items:
+
+  object
+
+  3 properties
+
+  - `kind` `enum<string>` **always present**&#x20;
+
+    Available options: `"pickup"`, `"scan"`, `"delivery"`
+
+  - `at` `string` **always present**&#x20;
+
+    format: date-time
+
+  - `details` `string` **may be absent** **nullable**&#x20;
+
+#### 404: Not Found
+
+`application/problem+json`
+
+No parcel has that identifier.
+
+4 properties
+
+- `type` `string` **always present**&#x20;
+
+  format: uri
+
+- `title` `string` **always present**&#x20;
+
+- `status` `integer` **always present**&#x20;
+
+- `detail` `string` **may be absent**&#x20;

package/agent-docs/example-api/cedar/list-parcels-0345fb5f.md

@@ -0,0 +1,271 @@
+---
+id: reference.cedar.listParcels
+title: List parcel records
+summary: GET /Search/parcels/{scope}
+type: api-reference
+area: api
+subarea: api-reference
+subjectLifecycle: in-development
+canonical: /example-api/cedar/list-parcels-0345fb5f
+---
+
+# List parcel records
+
+> 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 > Cedar Parcel API · styling lab > Query > List parcel records
+
+**Updated: 2026-10-19.**
+
+**Status: In development.**
+
+> 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/cedar-listparcels-b04dddee79753501d9f40ff84583f7b915b7cb919cf9f442e7c2b47ea3c4d7e3.json).
+
+## GET /Search/parcels/{scope}
+
+List parcel records
+
+List records for an account or region. Use `downloadAs` to request a
+file; the same successful status can return JSON, CSV, or a spreadsheet.
+
+### Servers
+
+`https://sandbox.api.cedar-parcel.example/v1` — Sandbox
+
+`https://api.cedar-parcel.example/v1` — Production
+
+### Authentication
+
+Use one of these authentication options:
+
+**Bearer token**
+
+HTTP bearer (JWT).
+
+Short-lived service token.
+
+**API key**
+
+API key in header X-Parcel-Key.
+
+Long-lived account key.
+
+### Parameters
+
+#### scope (path)
+
+Required
+
+The account or region identifier.
+
+string
+
+**Default example**: `"region-demo"`
+
+#### Filters (query)
+
+Optional
+
+OpenAPI calls this placeholder `parameters`. Send a filter expression directly in the query string, without `parameters=`.
+
+Query form: `?declaredValue(gt)=100`. Replace the field, operator, and value for your filter.
+
+Source notes, accepted fields, and operators
+
+Placeholder for field/operator filters. Do not send `parameters=`.
+Put each expression directly in the URL, for example
+`declaredValue(gt)=100`.
+
+Accepted fields: `createdAt` (gt, ge, lt, le, eq),
+`declaredValue` (gt, ge, lt, le, eq), `carrier` (eq, ne, in),
+`recipientCity` (eq, ct), and `status` (eq, ne, in).
+`in` values are separated by `|`.
+
+object
+
+Additional-key schema:
+
+string
+
+**High declared value**: `declaredValue(gt)=100`
+
+**City contains text**: `recipientCity(ct)=port`
+
+#### downloadAs (query)
+
+Optional
+
+Return a file instead of JSON when specified.
+
+string
+
+Available options: `"csv"`, `"xlsx"`
+
+#### skipRows (query)
+
+Optional
+
+Number of records to skip.
+
+integer; default: 0
+
+#### maxRows (query)
+
+Optional
+
+Maximum records to return. Zero or a negative value requests all records.
+
+integer; default: 20
+
+### Example request
+
+```bash
+curl --request GET \
+  --url 'https://sandbox.api.cedar-parcel.example/v1/Search/parcels/YOUR_SCOPE?recipientCity(ct)=port' \
+  --header 'Authorization: Bearer YOUR_TOKEN'
+```
+
+### Responses
+
+#### 200: OK
+
+`application/json`
+
+`text/csv`
+
+`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
+
+A page of records, or a downloadable file if `downloadAs` is set.
+The response format depends on the query value.
+
+##### application/json
+
+minProperties: 3; maxProperties: 3
+
+3 properties
+
+- `records` `list of object` **always present** 
+
+  uniqueItems: true
+
+  Array items:
+
+  5 properties
+
+  - `parcelId` `string` **always present** 
+
+  - `status` `enum<string>` **always present**&#x20;
+
+    Available options: `"label_created"`, `"in_transit"`, `"delivered"`, `"exception"`
+
+  - `declaredValue` `number` **always present**&#x20;
+
+    minimum: 0; multipleOf: 0.01
+
+    Value in currency units, to the nearest cent.
+
+  - `recipient` `object` **always present**&#x20;
+
+    2 properties
+
+    - `city` `string` **always present**&#x20;
+
+    - `postalCode` `string` **always present**&#x20;
+
+  - `events` `list of object` **may be absent**&#x20;
+
+    Tracking history in chronological order.
+
+    Array items:
+
+    object
+
+    3 properties
+
+    - `kind` `enum<string>` **always present**&#x20;
+
+      Available options: `"pickup"`, `"scan"`, `"delivery"`
+
+    - `at` `string` **always present**&#x20;
+
+      format: date-time
+
+    - `details` `string` **may be absent** **nullable**&#x20;
+
+- `totalRecords` `integer` **always present**&#x20;
+
+  minimum: 0
+
+- `nextCursor` `string` **always present** **nullable**&#x20;
+
+  Always present; null on the last page.
+
+Additional properties: not allowed.
+
+##### Example: First page
+
+Key: firstPage. Location: response 200; application/json. Authored in OpenAPI.
+
+```json
+{
+  "records": [
+    {
+      "parcelId": "pcl_demo_001",
+      "status": "in_transit",
+      "declaredValue": 145.5,
+      "recipient": {
+        "city": "Northport",
+        "postalCode": "00012"
+      }
+    }
+  ],
+  "totalRecords": 1,
+  "nextCursor": null
+}
+```
+
+##### text/csv
+
+string
+
+CSV rows with a header line.
+
+##### Example: Default example
+
+Key: default. Location: response 200; text/csv. Authored in OpenAPI.
+
+```text
+parcelId,status,declaredValue
+pcl_demo_001,in_transit,145.5
+
+```
+
+##### application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
+
+string; format: binary
+
+A spreadsheet download.
+
+#### 400: Bad Request
+
+`application/problem+json`
+
+A field name or comparison operator is unsupported.
+
+4 properties
+
+- `type` `string` **always present**&#x20;
+
+  format: uri
+
+- `title` `string` **always present**&#x20;
+
+- `status` `integer` **always present**&#x20;
+
+- `detail` `string` **may be absent**&#x20;

package/agent-docs/example-api/cedar/parcel-delivered-7d1ba6db.md

@@ -0,0 +1,122 @@
+---
+id: reference.cedar.parcelDelivered
+title: Parcel delivered event
+summary: "Webhook event: parcel.delivered"
+type: api-reference
+area: api
+subarea: api-reference
+canonical: /example-api/cedar/parcel-delivered-7d1ba6db
+---
+
+# Parcel delivered event
+
+> 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 > Cedar Parcel API · styling lab > Parcels > Parcel delivered event
+
+**Updated: 2026-10-19.**
+
+> Fictional API example. This page demonstrates documentation features; its operations do not describe a live service.
+
+This webhook reference is generated from the OpenAPI description. The provider sends this event to the receiver.
+
+OpenAPI for this operation: [Download JSON](https://www.shoalrun.com/api/operations/production/current/en/cedar-parceldelivered-ee7a193b8a236fe55bf24a20d15e8a4b8070165ed00f4d62899e0de91560f188.json).
+
+## Webhook: parcel.delivered
+
+The provider sends a POST request for this event to the receiver's webhook URL.
+
+Parcel delivered event
+
+The service sends this event to the receiver's webhook URL.
+
+### Authentication
+
+Use one of these authentication options:
+
+**Bearer token**
+
+HTTP bearer (JWT).
+
+Short-lived service token.
+
+**API key**
+
+API key in header X-Parcel-Key.
+
+Long-lived account key.
+
+### Request body
+
+Required.
+
+#### application/json
+
+5 properties
+
+- `eventId` `string` **required** 
+
+- `parcelId` `string` **required** 
+
+- `occurredAt` `string` **required** 
+
+  format: date-time
+
+- `outcome` `enum<string>` **required**&#x20;
+
+  Available options: `"delivered"`, `"returned"`
+
+- `proof` `one of several types` **required**&#x20;
+
+  Use exactly one of these shapes:
+
+  **Photo proof** · 2 properties
+
+  object
+
+  2 properties
+
+  - `kind` `string` **required**&#x20;
+
+    const: "photo"
+
+  - `url` `string` **required**&#x20;
+
+    format: uri
+
+  **Signature proof** · 2 properties
+
+  object
+
+  2 properties
+
+  - `kind` `string` **required**&#x20;
+
+    const: "signature"
+
+  - `signedBy` `string` **required**&#x20;
+
+##### Example: Delivered at doorstep
+
+Key: doorstep. Location: request; application/json. Authored in OpenAPI.
+
+```json
+{
+  "eventId": "evt_demo_001",
+  "parcelId": "pcl_demo_001",
+  "occurredAt": "2026-01-02T10:15:00Z",
+  "outcome": "delivered",
+  "proof": {
+    "kind": "photo",
+    "url": "https://media.cedar-parcel.example/proof/demo.jpg"
+  }
+}
+```
+
+### Responses
+
+#### 204: No Content
+
+Receiver accepted the event.

package/agent-docs/example-api/cedar/upload-manifest-1af17891.md

@@ -0,0 +1,101 @@
+---
+id: reference.cedar.uploadManifest
+title: Upload a manifest
+summary: POST /manifests
+type: api-reference
+area: api
+subarea: api-reference
+canonical: /example-api/cedar/upload-manifest-1af17891
+---
+
+# Upload a manifest
+
+> 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 > Cedar Parcel API · styling lab > Manifests > Upload a manifest
+
+**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/cedar-uploadmanifest-a03b1eb7fa7e30da2fd0dc705e6a279ad1234f27da77ea6a0649a95a8a4f5403.json).
+
+## POST /manifests
+
+Upload a manifest
+
+### Servers
+
+`https://sandbox.api.cedar-parcel.example/v1` — Sandbox
+
+`https://api.cedar-parcel.example/v1` — Production
+
+### Authentication
+
+Use one of these authentication options:
+
+**Bearer token**
+
+HTTP bearer (JWT).
+
+Short-lived service token.
+
+**API key**
+
+API key in header X-Parcel-Key.
+
+Long-lived account key.
+
+### Request body
+
+Required.
+
+#### multipart/form-data
+
+object
+
+2 properties
+
+- `manifest` `string` **required** 
+
+  format: binary
+
+  Dispatch data file.
+
+- `checksum` `string` **required** 
+
+  format: binary
+
+  Separate checksum file.
+
+### Example request
+
+```bash
+curl --request POST \
+  --url 'https://sandbox.api.cedar-parcel.example/v1/manifests' \
+  --header 'Authorization: Bearer YOUR_TOKEN' \
+  --form 'manifest=@YOUR_MANIFEST' \
+  --form 'checksum=@YOUR_CHECKSUM'
+```
+
+### Responses
+
+#### 202: Accepted
+
+`application/json`
+
+Upload accepted for validation.
+
+object
+
+2 properties
+
+- `jobId` `string` **always present** 
+
+- `status` `enum<string>` **always present**&#x20;
+
+  Available options: `"queued"`, `"validating"`

package/agent-docs/example-api/cedar.md

@@ -0,0 +1,39 @@
+---
+id: guide.cedar-parcel
+title: API reference styling lab
+summary: Inspect a synthetic API with complex schemas, filters, response
+  formats, and webhooks.
+type: overview
+area: api
+subarea: api-examples
+canonical: /example-api/cedar
+---
+
+# API reference styling lab
+
+> 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 > Cedar Parcel API · styling lab > API reference styling lab
+
+**Updated: 2026-10-25.**
+
+> Fictional API example. This page demonstrates documentation features; its operations do not describe a live service.
+
+The Cedar Parcel API is fictional. Its `.example` hosts do not accept requests, and its OpenAPI examples have not been executed. We keep it in the Shoalrun docs to check API reference layouts alongside other pages. It uses the same navigation, search, themes, and Markdown output.
+
+Use these pages to inspect the hardest layouts:
+
+- [Create a parcel enrollment](https://www.shoalrun.com/example-api/cedar/create-enrollment-7af3e5d2.md) shows four named request shapes with overlapping nested objects and required fields. In **Bulk dispatch**, `monthlyParcelEstimate` demonstrates an exclusive lower bound and schema-level examples, while `customMetadata` accepts any JSON value.
+- [List parcel records](https://www.shoalrun.com/example-api/cedar/list-parcels-0345fb5f.md) shows direct query filters, three response formats, and the new object, array, and number constraints: `minProperties`, `maxProperties`, `uniqueItems`, and `multipleOf`.
+- [Get a parcel](https://www.shoalrun.com/example-api/cedar/get-parcel-edee10e6.md) uses a path-specific server and no authentication.
+- [Upload a manifest](https://www.shoalrun.com/example-api/cedar/upload-manifest-1af17891.md) requires two binary upload fields.
+- [Get a parcel through the old route](https://www.shoalrun.com/example-api/cedar/get-legacy-parcel-6758d051.md) shows OpenAPI deprecation overriding an extension value.
+- [Parcel delivered event](https://www.shoalrun.com/example-api/cedar/parcel-delivered-7d1ba6db.md) shows an inbound OpenAPI 3.1 webhook with a nested `oneOf` proof.
+
+The source and standalone test project live at `framework/example-configs/reference-stress/` in the repository. The source is not copied into the built site; each operation publishes only its focused contract.
+
+## How it works for agents
+
+Every operation has a complete `.md` page and a focused OpenAPI contract. Schema fields remain in Markdown even when their HTML disclosure is closed. The site manifest and search index include these pages, and the reader's theme choice does not change what an agent can read.