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

package/templates/explanation.mdx

@@ -0,0 +1,76 @@
+---
+# EXPLANATION TEMPLATE. Resolve every TODO before publication.
+# Stable identity. Links and relationships use it even when a file or URL changes.
+# Never change it after publishing.
+id: explanation.example
+
+# Name the concept or question, such as "How parcel tracking works".
+# Use sentence case, 60 characters or fewer, without a final period.
+title: Example
+
+# One sentence of 160 characters or fewer stating what the reader will understand.
+# Good: "Understand how tracking events describe a parcel's journey."
+# Replace the derived draft summary before publication.
+summary: Draft summary
+
+# Optional search and link-preview detail. Remove if the summary is sufficient.
+description: "[[TODO: Add context in two sentences, or delete this field.]]"
+
+# Explanation develops understanding. Use how-to for tasks, tutorial for exercises,
+# and reference for exact facts.
+type: explanation
+
+# Stable URL path: lowercase words separated by hyphens, starting with /.
+slug: /explanations/example
+
+# Must match an enabled publication in project config.
+channel: production
+version: current
+language: en
+
+# One to three existing topic labels used by the project.
+tags:
+  - "[[TODO: One lowercase topic label, such as parcels.]]"
+
+# Optional card icon: a valid Lucide icon name.
+card: { icon: lightbulb }
+
+# OPTIONAL FIELDS. Uncomment only with valid project values.
+# audiences: [developers]
+# readerFilters: { audience: [developer] }
+# subjectLifecycle: beta
+# tocDepth: 2
+# layout: wide
+
+# Scaffold always writes draft. Publish only after resolving placeholders and
+# reviewing the explanation against evidence.
+access: { policy: draft }
+---
+
+[[TODO: Write the introduction as one paragraph of 150 words or fewer. Put no heading above it. Name the concept, the question this page answers, and the knowledge the reader already needs. Explain why understanding it helps. Do not promise a task or prescribe a sequence of actions.]]
+
+## Context
+
+[[TODO: Explain the problem or background that makes this concept useful. State the scope and assumptions. Link to a tutorial or how-to when readers need practical experience first.]]
+
+## [[TODO: Name the central concept or question]]
+
+[[TODO: Develop the explanation from familiar ideas to unfamiliar ones. Explain why the system behaves this way and how its parts relate. Use a concrete parcel example, analogy, or supported diagram where it clarifies the idea. Distinguish facts from assumptions. Add topic headings as needed; do not turn this into numbered task steps or a field catalog.]]
+
+## Tradeoffs and alternatives
+
+[[TODO: OPTIONAL SECTION. Keep it when understanding requires comparing approaches. Explain the reasons for the design, relevant history and constraints, its limitations, and when another approach makes sense. Identify whose perspective or judgment a claim represents, and consider counterexamples. Delete this heading and text otherwise. Link to reference material for exact limits.]]
+
+## Common misconceptions
+
+[[TODO: OPTIONAL SECTION. Keep it when readers often confuse related concepts. Explain the distinction and its practical consequence. Delete this heading and text otherwise.]]
+
+## HTML, Markdown, and agents
+
+[[TODO: OPTIONAL SECTION. Keep it when the explanation uses components or discusses representation differences. Say what HTML shows, what the Markdown twin contains, and what an agent can read. Delete this heading and text otherwise.]]
+
+## Related reading
+
+[[TODO: Add relationships to a tutorial for learning by doing, a how-to for a concrete task, or a reference for exact facts. Delete this paragraph after configuring the relationships; delete the whole section if none apply.]]
+
+<RelatedReading />

package/templates/guide.mdx

@@ -0,0 +1,175 @@
+---
+# GUIDE TEMPLATE. Delete every comment line (starting with #) before you publish.
+# Search the file for TODO and resolve every placeholder in double square brackets.
+# A page with a placeholder left cannot be published.
+#
+# Scaffold filled in id, title, summary, type, slug, channel, version, language, and access from
+# the command line, the file path, and your config. Rewrite title, summary, and slug for the reader.
+# The order below is deliberate: identity, then publication, then card, then optional fields,
+# then the publishing switch last.
+
+# Stable identity. Links, cards, navigation, and relationships use it, so it can outlive
+# a renamed file or a changed URL. Scaffold derived it from the file path. Shorten it if you like,
+# to lowercase words separated by dots or hyphens, such as guide.retry-payment.
+# Never change it after publishing.
+id: guide.example
+
+# The page heading and the browser tab title. Start with a verb that names the task:
+# "Retry a failed payment", not "Payment retries" or "How to retry a payment".
+# Sentence case, 60 characters or fewer, no final period.
+# Scaffold derived a placeholder title from the file name. Rewrite it.
+title: Example
+
+# One sentence of 160 characters or fewer that says what the reader can do after this guide.
+# It appears on cards, in search results, and as the default link preview text.
+# Good: "Retry a failed payment without charging the customer twice."
+# Bad: "This guide covers payment retries." (It says what the page is, not what the reader gets.)
+# Scaffold wrote a draft summary that blocks publishing. Replace it.
+summary: Draft summary
+
+# Optional longer text for search and link previews. Two sentences at most, about 300 characters.
+# Add detail the summary leaves out, such as the prerequisite or the API version. Do not repeat the summary.
+# Delete this field if you have nothing to add.
+description: "[[TODO: Two sentences that add detail to the summary, or delete this field.]]"
+
+# The page kind. Leave this as guide. Use the reference or tutorial template for other kinds.
+type: guide
+
+# The URL path. Start with /. Use lowercase words separated by hyphens, and keep it stable.
+# Good: /guides/retry-payment. Avoid dates, version numbers, and the words "how-to" or "guide".
+slug: /guides/example
+
+# The publication this page belongs to. It must match an enabled entry in publications.enabled.
+# A page in a channel, version, or language that is not enabled is skipped without a warning.
+channel: production
+version: current
+language: en
+
+# Topic labels that help collections find this page. One to three, lowercase, short.
+# Use labels your team already uses. Do not invent one for a single page.
+tags:
+  - "[[TODO: One lowercase topic label, such as payments. Add a line for each extra label.]]"
+
+# How this page looks when another page links to it with a card. The icon is a Lucide name in
+# lowercase, such as book-open, credit-card, or terminal. Browse the names at lucide.dev/icons.
+# An unknown name fails the build. To add a short label above the card title, or card text that
+# replaces the summary on cards only, add eyebrow or description: card: { icon: book-open, eyebrow: Payments guide }
+card: { icon: book-open }
+
+# ---------------------------------------------------------------------------------------------
+# OPTIONAL FIELDS. Uncomment one only when the rule in its comment applies.
+# ---------------------------------------------------------------------------------------------
+#
+# API TASKS ONLY. Stable operation IDs from your apis config that this guide uses.
+# Adds a "Related documentation" list here and on each operation's reference page.
+# Scaffold fills this field when you pass --operation. IDs that do not exist fail the build.
+# operations: [payments.create]
+#
+# API TASKS ONLY. API reference page IDs to link from this guide and back. Guides only.
+# Use page IDs (reference.create-payment), not operation IDs (payments.create).
+# relatedApiReferences: [reference.create-payment]
+#
+# Who this page is for, shown as badges. Free text unless your config defines an audience
+# reader view, in which case use its choice IDs. Uncomment only if your site uses audiences.
+# audiences: [developers]
+#
+# Reader-view marks for pages that appear only in some views. Use only IDs from readerFilters.facets.
+# The product, area, and subarea fields set a single choice for a facet with the same name.
+# readerFilters: { audience: [developer] }
+# product: payments
+# area: reporting
+# subarea: settlements
+#
+# Status of the feature or API this guide covers: beta, in-development, or deprecated.
+# It shows a badge in navigation and the page header. Leave it out for a stable feature.
+# subjectLifecycle: beta
+#
+# Editorial state of this document, such as needs-review. Free text. It is kept but never shown.
+# lifecycle: needs-review
+#
+# Deepest heading level in the on-page table of contents. Use 0 to hide it, or 2 through 6.
+# The default is 3. Set 2 for a long page with many small subsections.
+# tocDepth: 2
+#
+# Page width. wide drops the "On this page" column for wide tables and diagrams.
+# The default is docs. landing is for home pages, so do not use it on a guide.
+# layout: wide
+#
+# A local .png or .jpg, 1200 by 630 pixels, that replaces the generated link-preview image.
+# The path is relative to this file.
+# image: ./images/retry-payment.png
+#
+# Overrides for the browser title and meta description. Only title and description are supported.
+# seo:
+#   title: Retry a failed payment | Example API
+#   description: Retry a payment with the same idempotency key.
+#
+# Literal text for one output only. Keys: card, pageHeader, search, htmlDescription, socialCard.
+# displayText:
+#   socialCard: Retry a failed payment without charging twice.
+#
+# A named Markdown-header profile from your config, or a mapping that overrides the header.
+# markdownMetadata: minimal
+#
+# Values for snippets used on this page. They override project variables.
+# variables: { product: Payments sandbox }
+
+# Publishing control. Scaffold sets draft, which keeps the page out of the site. Change to
+# { policy: public } only after every TODO is resolved and the steps have been run end to end.
+access: { policy: draft }
+---
+
+[[TODO: Write the introduction as one paragraph of 150 words or fewer. Put no heading above it. Say what the reader will be able to do, who this guide is for, and where it stops. Use two sentences: "This guide shows you how to [outcome]. It is for [reader role] who [starting situation]." Add one sentence naming what the guide does not cover and where to go for that. Do not explain background the reader already has, and do not list the sections that follow.]]
+
+## Prerequisites
+
+[[TODO: OPTIONAL SECTION. Keep it only if the reader must have something before step one. Delete this heading and text if they need nothing. List each requirement as one bullet: what it is, how to get it (link by document ID), and how to check they have it. Example: "An API key with the payments write scope. See the authentication guide. Run the whoami request to confirm it works." Name exact versions and permissions. Keep each bullet to two sentences. Put one requirement per bullet.]]
+
+- [[TODO: First requirement, with a link and a check.]]
+- [[TODO: API TASKS ONLY, delete otherwise. Name the credential and permission the reader needs, and link to setup. Never paste a real key, token, or secret. Use a placeholder such as YOUR_API_KEY.]]
+- [[TODO: API TASKS ONLY, delete otherwise. State the environment (sandbox or production), the API version, and the publication channel these steps use.]]
+
+## Considerations
+
+[[TODO: OPTIONAL SECTION. Keep it only if the reader should weigh something before starting. Delete this heading and text if nothing applies. Use it for a cost, a side effect, an action that cannot be undone, or a case where a different approach fits better. Write one bullet for each, and start each with the consequence in bold. Example: "**This charges the customer.** Use a sandbox key while you test." Link to the better guide when one exists. Do not repeat requirements from Prerequisites.]]
+
+- [[TODO: First consideration. Bold consequence first, then what to do about it.]]
+- [[TODO: API TASKS ONLY, delete otherwise. State any side effect, cost, rate limit, or call that cannot be reversed.]]
+- [[TODO: When another guide is a better fit, say so and link to it by document ID.]]
+
+## [[TODO: Name the task with a verb, such as "Retry a failed payment"]]
+
+[[TODO: PROCEDURE. All numbered steps live here, before any reference material. Write one sentence saying what the steps produce. Then number every action. Each step has one action, the exact input (a value, a field, a menu path), and the result the reader should see. Start each step with a verb. Explain a field only if it is not obvious, in one clause. Show input the reader can copy, using safe example values. Split into several headings at a natural break if there are more than about eight steps.]]
+
+1. [[TODO: First action. Include the exact input and where to find it.]]
+2. [[TODO: Second action. Show the exact command, request, or menu path. Explain any field that is not obvious.]]
+3. [[TODO: Say what the reader should now see: a status code, a response field, a message, or a screen state.]]
+
+```sh
+[[TODO: API TASKS ONLY, delete this block otherwise. Replace with one runnable request that uses safe values, and show the expected response after it. Use YOUR_API_KEY style placeholders. Never include a real key, token, or customer record.]]
+```
+
+## Check the result
+
+[[TODO: Give one check that proves the task worked, independent of the last step. Name what to look at (a response field, an event, a screen), the exact value that means success, and what a different value means. Two to four sentences.]]
+
+## Troubleshooting
+
+[[TODO: List the two to four failures readers are most likely to hit while doing these steps. Use one bullet for each. Give the symptom in the reader's words or the exact error text. Then give the cause in one sentence, and the recovery step. If the fix is long, link to a troubleshooting page instead of writing it here.]]
+
+- [[TODO: First likely failure. Symptom, cause, recovery.]]
+- [[TODO: API TASKS ONLY, delete otherwise. Say whether retrying is safe, and which key or identifier the reader must reuse.]]
+
+## Reference
+
+[[TODO: OPTIONAL SECTION. Keep it only for facts the steps above use but do not teach: option lists, limits, formats, defaults. Delete this heading and text if a reference page already covers it, and link to that page instead. This section always comes after all procedure and troubleshooting. Use tables, one fact per row. If it grows beyond about 300 words, move it to a reference page and link to it.]]
+
+## HTML, Markdown, and agents
+
+[[TODO: OPTIONAL SECTION. Keep it when the page uses a component or describes behavior that differs between HTML and Markdown or affects what an agent reads. Delete this heading and text otherwise. Describe what HTML shows or lets a reader do, what the Markdown twin contains, and what that means for an agent. Name the useful .md page, documents.json entry, or focused contract when relevant. Describe actual behavior in two to five sentences.]]
+
+## Related reading
+
+[[TODO: Add relationship entries for this page to your relationships config, then delete this paragraph. Each entry names this page's ID as "from", the related page's ID as "to", a type, and a reason. Types: prerequisite, next-step, reference, advanced, see-also, not-confused-with. If this page has no natural related pages, delete this whole section.]]
+
+<RelatedReading />

package/templates/how-to.mdx

@@ -0,0 +1,171 @@
+---
+# HOW-TO TEMPLATE. Delete every comment line (starting with #) before you publish.
+# Search the file for TODO and resolve every placeholder in double square brackets.
+# A page with a placeholder left cannot be published.
+#
+# Scaffold filled in id, title, summary, type, slug, channel, version, language, and access from
+# the command line, the file path, and your config. Rewrite title, summary, and slug for the reader.
+# The order below is deliberate: identity, then publication, then card, then optional fields,
+# then the publishing switch last.
+
+# Stable identity. Links, cards, navigation, and relationships use it, so it can outlive
+# a renamed file or a changed URL. Scaffold derived it from the file path. Shorten it if you like,
+# to lowercase words separated by dots or hyphens, such as how-to.track-parcel.
+# Never change it after publishing.
+id: how-to.example
+
+# The page heading and the browser tab title. Start with a verb that names the task:
+# "Retry a failed enrollment" or "How to retry an enrollment", not "Enrollment retries".
+# Sentence case, 60 characters or fewer, no final period.
+# Scaffold derived a placeholder title from the file name. Rewrite it.
+title: Example
+
+# One sentence of 160 characters or fewer that says what the reader can do after this how-to.
+# It appears on cards, in search results, and as the default link preview text.
+# Good: "Retry a failed enrollment without creating duplicate enrollments."
+# Bad: "This how-to covers enrollment retries." (It says what the page is, not what the reader gets.)
+# Scaffold wrote a draft summary that blocks publishing. Replace it.
+summary: Draft summary
+
+# Optional longer text for search and link previews. Two sentences at most, about 300 characters.
+# Add detail the summary leaves out, such as the prerequisite or the API version. Do not repeat the summary.
+# Delete this field if you have nothing to add.
+description: "[[TODO: Two sentences that add detail to the summary, or delete this field.]]"
+
+# The page kind. Leave this as how-to. Use tutorial for learning, reference for facts, or explanation for understanding.
+type: how-to
+
+# The URL path. Start with /. Use lowercase words separated by hyphens, and keep it stable.
+# Good: /how-tos/retry-enrollment. Avoid dates, version numbers, and redundant page-kind words.
+slug: /how-tos/example
+
+# The publication this page belongs to. It must match an enabled entry in publications.enabled.
+# A page in a channel, version, or language that is not enabled is skipped without a warning.
+channel: production
+version: current
+language: en
+
+# Topic labels that help collections find this page. One to three, lowercase, short.
+# Use labels your team already uses. Do not invent one for a single page.
+tags:
+  - "[[TODO: One lowercase topic label, such as parcels. Add a line for each extra label.]]"
+
+# How this page looks when another page links to it with a card. The icon is a Lucide name in
+# lowercase, such as book-open, package, or terminal. Browse the names at lucide.dev/icons.
+# An unknown name fails the build. To add a short label above the card title, or card text that
+# replaces the summary on cards only, add eyebrow or description: card: { icon: book-open, eyebrow: Parcels how-to }
+card: { icon: book-open }
+
+# ---------------------------------------------------------------------------------------------
+# OPTIONAL FIELDS. Uncomment one only when the rule in its comment applies.
+# ---------------------------------------------------------------------------------------------
+#
+# API TASKS ONLY. Stable operation IDs from your apis config that this how-to uses.
+# Adds a "Related documentation" list here and on each operation's reference page.
+# Scaffold fills this field when you pass --operation. IDs that do not exist fail the build.
+# operations: [parcels.create]
+#
+# API TASKS ONLY. API reference page IDs to link from this how-to and back. How-tos only.
+# Use page IDs (reference.create-parcel), not operation IDs (parcels.create).
+# relatedApiReferences: [reference.create-parcel]
+#
+# Who this page is for, shown as badges. Free text unless your config defines an audience
+# reader view, in which case use its choice IDs. Uncomment only if your site uses audiences.
+# audiences: [developers]
+#
+# Reader-view marks for pages that appear only in some views. Use only IDs from readerFilters.facets.
+# The product, area, and subarea fields set a single choice for a facet with the same name.
+# readerFilters: { audience: [developer] }
+# product: parcels
+# area: reporting
+# subarea: delivery
+#
+# Status of the feature or API this how-to covers: beta, in-development, or deprecated.
+# It shows a badge in navigation and the page header. Leave it out for a stable feature.
+# subjectLifecycle: beta
+#
+# Editorial state of this document, such as needs-review. Free text. It is kept but never shown.
+# lifecycle: needs-review
+#
+# Deepest heading level in the on-page table of contents. Use 0 to hide it, or 2 through 6.
+# The default is 3. Set 2 for a long page with many small subsections.
+# tocDepth: 2
+#
+# Page width. wide drops the "On this page" column for wide tables and diagrams.
+# The default is docs. landing is for home pages, so do not use it on a how-to.
+# layout: wide
+#
+# A local .png or .jpg, 1200 by 630 pixels, that replaces the generated link-preview image.
+# The path is relative to this file.
+# image: ./images/retry-enrollment.png
+#
+# Overrides for the browser title and meta description. Only title and description are supported.
+# seo:
+#   title: Retry a failed enrollment | Example API
+#   description: Retry a parcel with the same idempotency key.
+#
+# Literal text for one output only. Keys: card, pageHeader, search, htmlDescription, socialCard.
+# displayText:
+#   socialCard: Retry a failed enrollment without creating duplicates.
+#
+# A named Markdown-header profile from your config, or a mapping that overrides the header.
+# markdownMetadata: minimal
+#
+# Values for snippets used on this page. They override project variables.
+# variables: { product: Parcels sandbox }
+
+# Publishing control. Scaffold sets draft, which keeps the page out of the site. Change to
+# { policy: public } only after every TODO is resolved and the steps have been run end to end.
+access: { policy: draft }
+---
+
+[[TODO: Write the introduction as one paragraph of 150 words or fewer. Put no heading above it. Say what the reader will be able to do, who this how-to is for, and where it stops. Use two sentences: "This how-to shows you how to [outcome]. It is for [reader role] who [starting situation]." Add one sentence naming what the how-to does not cover and where to go for that. Do not explain background the reader already has, and do not list the sections that follow.]]
+
+## Prerequisites
+
+[[TODO: OPTIONAL SECTION. Keep it only if the reader must have something before step one. Delete this heading and text if they need nothing. List each requirement as one bullet: what it is, how to get it (link by document ID), and how to check they have it. Example: "An API key with the parcels write scope. See the authentication how-to. Run the whoami request to confirm it works." Name exact versions and permissions. Keep each bullet to two sentences. Put one requirement per bullet.]]
+
+- [[TODO: First requirement, with a link and a check.]]
+- [[TODO: API TASKS ONLY, delete otherwise. Name the credential and permission the reader needs, and link to setup. Never paste a real key, token, or secret. Use a placeholder such as YOUR_API_KEY.]]
+- [[TODO: API TASKS ONLY, delete otherwise. State the environment (sandbox or production), the API version, and the publication channel these steps use.]]
+
+## Considerations
+
+[[TODO: OPTIONAL SECTION. Keep it only if the reader should weigh something before starting. Delete this heading and text if nothing applies. Use it for a cost, a side effect, an action that cannot be undone, or a case where a different approach fits better. Write one bullet for each, and start each with the consequence in bold. Example: "**This creates a parcel enrollment.** Use a sandbox key while you test." Link to the better how-to when one exists. Do not repeat requirements from Prerequisites.]]
+
+- [[TODO: First consideration. Bold consequence first, then what to do about it.]]
+- [[TODO: API TASKS ONLY, delete otherwise. State any side effect, cost, rate limit, or call that cannot be reversed.]]
+- [[TODO: When another how-to is a better fit, say so and link to it by document ID.]]
+
+## [[TODO: Name the task with a verb, such as "Retry a failed enrollment"]]
+
+[[TODO: PROCEDURE. Keep the guidance focused on the reader's task. Assume the reader knows the tools; link to tutorials for learning and references for complete option lists. Write one sentence saying what the steps produce. Then number every action. Each step has one action, the exact input (a value, a field, a menu path), and the result the reader should see. Start each step with a verb. Explain a field only if it is not obvious, in one clause. Show input the reader can copy, using safe example values. Use a sequence that follows the reader's work. When real situations require a choice, give a condition and the action for each branch; allow readers to adapt values to their own situation.]]
+
+1. [[TODO: First action. Include the exact input and where to find it.]]
+2. [[TODO: Second action. Show the exact command, request, or menu path. Explain any field that is not obvious.]]
+3. [[TODO: Say what the reader should now see: a status code, a response field, a message, or a screen state.]]
+
+```sh
+[[TODO: API TASKS ONLY, delete this block otherwise. Replace with one runnable request that uses safe values, and show the expected response after it. Use YOUR_API_KEY style placeholders. Never include a real key, token, or customer record.]]
+```
+
+## Check the result
+
+[[TODO: Give one check that proves the task worked, independent of the last step. Name what to look at (a response field, an event, a screen), the exact value that means success, and what a different value means. Two to four sentences.]]
+
+## Troubleshooting
+
+[[TODO: List the two to four failures readers are most likely to hit while doing these steps. Use one bullet for each. Give the symptom in the reader's words or the exact error text. Then give the cause in one sentence, and the recovery step. If the fix is long, link to a troubleshooting page instead of writing it here.]]
+
+- [[TODO: First likely failure. Symptom, cause, recovery.]]
+- [[TODO: API TASKS ONLY, delete otherwise. Say whether retrying is safe, and which key or identifier the reader must reuse.]]
+
+## HTML, Markdown, and agents
+
+[[TODO: OPTIONAL SECTION. Keep it when the page uses a component or describes behavior that differs between HTML and Markdown or affects what an agent reads. Delete this heading and text otherwise. Describe what HTML shows or lets a reader do, what the Markdown twin contains, and what that means for an agent. Name the useful .md page, documents.json entry, or focused contract when relevant. Describe actual behavior in two to five sentences.]]
+
+## Related reading
+
+[[TODO: Add relationship entries for this page to your relationships config, then delete this paragraph. Each entry names this page's ID as "from", the related page's ID as "to", a type, and a reason. Types: prerequisite, next-step, reference, advanced, see-also, not-confused-with. If this page has no natural related pages, delete this whole section.]]
+
+<RelatedReading />

package/templates/ingredient.mdx

@@ -0,0 +1,53 @@
+---
+# INGREDIENT TEMPLATE. Delete these comments and resolve every [[TODO: ...]] prompt before using it in a published recipe.
+# Scaffold fills id, title, summary, type, slug, publication, and access from the command and config.
+# An ingredient is one reusable action or check. A recipe combines ingredients for a customer goal.
+
+# Stable identity for this ingredient. Keep it after recipes start using it.
+id: ingredient.example
+
+# Name the action or check, such as "Configure webhook delivery".
+title: Do one reusable step
+
+# One sentence describing what this ingredient contributes to a recipe.
+summary: Draft ingredient for one reusable step.
+
+# Leave this page kind as ingredient.
+type: ingredient
+
+# Stable lowercase URL path before publication prefixes. Start with /.
+slug: /ingredients/example
+
+# These values must match the recipe publication when assembled by `recipe draft`.
+channel: production
+version: current
+language: en
+
+# Optional handoff metadata for `recipe draft`. Names identify values; descriptions
+# and checks are instructions, not executed code. Uncomment and adapt when needed.
+# workflow: { inputs: { parcelId: "Existing parcel ID" }, outputs: { trackingStatus: "Returned tracking status" }, prerequisites: ["Have a parcel lookup key"], check: "The response contains the requested parcel ID." }
+
+# Optional: stable configured API operation IDs used by this ingredient.
+# operations: [notifications.send-email]
+
+# Keep draft access while validating this step and any recipes using it.
+access: { policy: draft }
+---
+
+[[TODO: State what this ingredient contributes and when a recipe needs it.]]
+
+## Inputs
+
+[[TODO: Name the exact values and starting state needed for this step.]]
+
+## Action
+
+[[TODO: Give the exact action, with commands or UI labels readers can follow.]]
+
+## Output
+
+[[TODO: Name the value or state that the next ingredient can use.]]
+
+## Check it worked
+
+[[TODO: Give one observable check for this ingredient. The complete recipe also needs an end-to-end check.]]

package/templates/recipe.mdx

@@ -0,0 +1,76 @@
+---
+# RECIPE TEMPLATE. Delete these comments and resolve every [[TODO: ...]] prompt before publishing.
+# Scaffold fills id, title, summary, type, slug, publication, and access from the command and config.
+# A recipe is a specialized how-to for one customer goal. Write it directly or combine ingredients. Use a tutorial for a learning path.
+
+# Stable identity used by links, cards, navigation, and relationships. Keep it after publication.
+# Short lowercase words separated by dots or hyphens work well, such as recipe.send-welcome-email.
+id: recipe.example
+
+# Name the customer goal as an action, such as "Send a welcome email".
+# Scaffold derives a starting title from the file name. Rewrite it for readers.
+title: Achieve one customer goal
+
+# One sentence describing what the reader can accomplish. Replace the draft summary.
+# Cards, search results, and link previews use this by default.
+summary: Draft recipe for one customer goal.
+
+# Leave this page kind as recipe. A cookbook can collect pages with this type.
+type: recipe
+
+# Stable lowercase URL path before publication prefixes. Start with /.
+slug: /recipes/example
+
+# These values must identify an enabled publication. Scaffold chooses the project defaults
+# unless you pass --channel, --version, or --language.
+channel: production
+version: current
+language: en
+
+# Optional: stable operation IDs used by this recipe. Pass --operation to scaffold, or add
+# the IDs after checking apis.*.operations in config. Delete this field for a non-API recipe.
+# operations: [notifications.send-email]
+
+# Optional: reuse the project's topic tags when a collection filters recipes by tag.
+# tags: [notifications]
+
+# Optional: override card text or give this page a known Lucide icon.
+# card: { icon: chef-hat, eyebrow: Recipe }
+
+# Drafts stay out of the published site. Change to public only after testing the steps,
+# replacing TODOs, and checking the HTML and Markdown outputs.
+access: { policy: draft }
+---
+
+[[TODO: Name the customer goal, the result, and when to use this recipe.]]
+
+## Before you start
+
+[[TODO: List the credentials, tools, files, and starting state needed for the task. If composing ingredients, combine their requirements. Remove duplicates.]]
+
+## Ingredients
+
+1. [[TODO: OPTIONAL SECTION. Keep this list only when composing reusable ingredients. Name the first ingredient and its input and output. Delete this whole section for a directly authored recipe.]]
+2. [[TODO: Add the next ingredient. Check that the previous output provides its required input.]]
+
+## Do it
+
+[[TODO: Write the complete actions needed for the customer goal. If using ingredients, include the values passed between them. Assume practical competence, give conditional actions for relevant cases, and link out for background and complete reference facts. Do not make readers assemble the instructions themselves.]]
+
+## Check it worked
+
+[[TODO: State one observable end-to-end success value, the command or screen that shows it, and the first thing to inspect if it does not match. Verify the full recipe yourself.]]
+
+## If it fails
+
+[[TODO: OPTIONAL SECTION. Add a likely failure, its symptom, and a recovery step. Delete this section when there is no useful task-specific advice.]]
+
+## HTML, Markdown, and agents
+
+[[TODO: OPTIONAL SECTION. Keep this only when the recipe uses a component or has different HTML and Markdown behavior. Delete it otherwise.]]
+
+## Related reading
+
+[[TODO: Add useful relationships in config/relationships.yaml, then delete this prompt. Delete this whole section if there are no related pages.]]
+
+<RelatedReading />