chore: Add agent skills for working with docs

.github/doc-templates/concept.md

@@ -0,0 +1,99 @@
+# Concept page template
+
+A concept page is the home for one capability. The reader is past Get started; they want to understand what the capability is, when to use it, and how to do common operations on it. They might read top to bottom to learn, or jump to a specific section to do something.
+
+**Use for:** pages in the Concepts section, one per capability.  
+**Don't use for:** step-by-step new-user walkthroughs (tutorial), procedural how-tos spanning multiple capabilities (guide), or schema and rule lookups (reference).
+
+---
+
+## Skeleton
+
+```markdown
+---
+description: <One sentence summary, 120–160 chars. Used for SEO and AI retrieval. Required.>
+---
+
+# <Capability name>
+
+Two to four sentences. What the capability is, in plain language. The reader should leave this
+paragraph knowing what the feature does and roughly when they'd reach for it.
+
+Don't open with marketing. Open with the substance.
+If the capability has a roadmap item (workaround today, native support coming), say so here.
+
+## When to use <capability>
+
+OPTIONAL. Use when the reader has a decision to make: this vs an alternative, opt-in vs skip,
+etc. Skip if every user uses the capability the same way.
+
+Format: short paragraphs or a small decision table.
+
+## <Operation 1: action-shaped heading>
+
+One or two sentences on what this operation does and when the reader would do it.
+
+<command or action>
+
+<expected output or result>
+
+## <Operation 2: action-shaped heading>
+
+<as above>
+
+## Configuration
+
+OPTIONAL. Use when the capability has configuration knobs in scloud.yaml, environment variables,
+or CLI flags that aren't tied to a single operation. Link to the Reference page for the canonical
+lookup; this section is the readable explanation.
+
+## Cloud-specific behavior
+
+OPTIONAL. Use when Cloud handles this capability differently from self-hosted Serverpod and the
+difference matters to the reader.
+
+## Limits
+
+OPTIONAL. Use when the capability has hard limits the reader will hit or current limitations they
+should know about. Format: short list. Each item: the limit, what happens at the limit, what to
+do about it.
+
+## Troubleshooting
+
+OPTIONAL. Use only for 2–4 well-defined failure modes the reader will plausibly hit.
+Format: question-shaped headings. Each entry: cause, fix.
+
+## Related
+
+OPTIONAL but recommended.
+
+- [<Linked page>](path) — <one-line description>
+```
+
+---
+
+## Voice
+
+- **Mixed person.** Use "you" when telling the reader what they can do; no subject when describing the capability ("Logs are collected automatically"). Don't switch within a paragraph.
+- **Operations in imperative.** "Set a password," not "You should set a password."
+- **Action-shaped H2s.** "Set a password" beats "Password configuration".
+- **Honest about variants.** Name the variant in one sentence with a code example. Don't enumerate every flag — that's the CLI reference's job.
+
+## Length
+
+600–1,500 words plus code blocks. Under 400 words: consider folding into a related concept. Over 2,000 words: consider splitting.
+
+## Code samples
+
+If an operation has a primary form and a variant, show both in adjacent code blocks rather than commenting variants out.
+
+## Checklist before publishing
+
+- [ ] `description` frontmatter is present and reads well in isolation (120–160 chars).
+- [ ] Overview opens with what the capability is, in plain language. No marketing.
+- [ ] Roadmap status stated up front if relevant.
+- [ ] Operations are action-shaped headings, ordered by how often the reader needs them.
+- [ ] Code blocks are language-tagged; `title` attributes used for file content.
+- [ ] Optional sections present only when the capability has the content to justify them.
+- [ ] Related section is not padded.
+- [ ] No marketing language, no hedging, no speculative troubleshooting.

.github/doc-templates/guide.md

@@ -0,0 +1,92 @@
+# Guide page template
+
+A guide is a procedural how-to. The reader has a specific task to accomplish, often spanning multiple capabilities or involving an external system. They open the page mid-task, follow the steps, and close it with the task done.
+
+If a procedure fits inside a single capability, it belongs as an operation on that capability's concept page, not as a guide.
+
+**Use for:** pages in the Guides section.  
+**Don't use for:** new-user walkthroughs (tutorial), single-capability operations (concept page), or schema and rule lookups (reference).
+
+---
+
+## Skeleton
+
+```markdown
+---
+description: <One sentence summary, 120–160 chars. Used for SEO and AI retrieval. Required.>
+---
+
+# <Action-shaped page title>
+
+What this guide helps the reader accomplish, in plain language. One short paragraph. Tell them
+what they'll have at the end and roughly how long it will take.
+
+Don't open with "In this guide, you will learn..." Open with the task:
+"Deploy your Serverpod app from a GitHub Actions workflow."
+
+If the guide is about a workaround, say so up front and link to the roadmap status.
+
+## Before you start
+
+- <Prerequisite 1>
+- <Prerequisite 2>
+- <Prerequisite 3>
+
+## <Step 1: action-shaped heading>
+
+One or two sentences explaining what this step does and why.
+
+<command, configuration, or action>
+
+<expected output or result>
+
+## <Step 2: action-shaped heading>
+
+<as above>
+
+## Verify
+
+OPTIONAL but recommended where the result isn't obvious. Tell the reader how to confirm the
+procedure worked.
+
+## Troubleshooting
+
+OPTIONAL. Use only for 2–4 well-defined failure modes the reader will plausibly hit.
+Don't reproduce content covered by a dedicated failure-mode guide — link there instead.
+Format: question-shaped headings. Each entry: cause, fix.
+
+## Related
+
+OPTIONAL but recommended.
+
+- [<Linked page>](path) — <one-line description>
+```
+
+---
+
+## Voice
+
+- **Second person, present tense.** "You'll get a confirmation email."
+- **Imperative steps.** "Add the secret to your repository," not "You should add the secret."
+- **Action-shaped headings.** Every H2 names what the reader is doing. The page title is also action-shaped.
+- **Acknowledge workarounds.** If the guide depends on a third-party service or a temporary path, say so.
+
+## Length
+
+400–1,200 words plus code blocks. Over 1,500 words: ask whether it's actually two guides.
+
+## Branching
+
+Guides can branch where tutorials cannot. Use tabs or sub-sections when the reader genuinely has different valid paths. Don't manufacture branching where one clear path serves most readers.
+
+## Checklist before publishing
+
+- [ ] `description` frontmatter is present and reads well in isolation (120–160 chars).
+- [ ] Page title and section headings are action-shaped.
+- [ ] The guide is genuinely cross-cutting; single-capability content belongs on the concept page.
+- [ ] Workaround or third-party dependency stated up front if applicable.
+- [ ] Prerequisites are complete and accurate.
+- [ ] Code blocks are language-tagged; `title` attributes used for file content.
+- [ ] Screenshots match the current state of the UI (labels, buttons, and layout match what the guide describes).
+- [ ] Verify section present where the result isn't obvious.
+- [ ] No marketing language, no manufactured complexity, no rehashed concept content.

.github/doc-templates/reference.md

@@ -0,0 +1,88 @@
+# Reference page template
+
+A reference page is a lookup. The reader knows what they're looking for: a schema, a rule, a list of valid values, a parameter set. They open the page, find the answer, and close it. They're not reading top to bottom; they're scanning.
+
+**Use for:** pages in the Reference section — schemas, rules, exhaustive enumerations.  
+**Don't use for:** narrative capability explanations (concept), procedural how-tos (guide), or new-user walkthroughs (tutorial). The CLI reference is auto-generated and follows its own pattern.
+
+---
+
+## Skeleton
+
+```markdown
+---
+description: <One sentence summary, 120–160 chars. Used for SEO and AI retrieval. Required.>
+---
+
+# <Reference subject>
+
+One to three sentences. What this reference covers and when the reader needs it.
+Don't open with "This page documents..." Open with the substance.
+
+## <Lookup body>
+
+Format depends on the subject. Pick what makes the reader's lookup fastest:
+
+For a schema:
+  - Structured table or hierarchical list.
+  - Each entry: key name, type, required/optional, default, description.
+  - Group related keys under sub-headings.
+  - Show a complete example at the top or bottom.
+
+For rules:
+  - Lead with the rules as a bulleted list.
+  - Follow with valid and invalid examples.
+  - Document version selection logic or precedence explicitly.
+
+For enumerations:
+  - Table with one row per item.
+  - Columns are the attributes the reader will compare.
+  - Sort by what the reader is most likely to pick first.
+
+Avoid narrative paragraphs. Reference pages reward scanning; prose hides the answer.
+
+## Error messages
+
+OPTIONAL. Use when the subject produces specific error messages the reader will encounter.
+Format: each error gets a sub-heading with the verbatim message, followed by cause and fix.
+
+## Examples
+
+OPTIONAL. Use when the reader benefits from seeing the subject applied to several common cases.
+Omit if the lookup body already has sufficient examples inline.
+
+## Related
+
+OPTIONAL but recommended.
+
+- [<Linked page>](path) — <one-line description>
+```
+
+---
+
+## Voice
+
+- **Terse.** "Defaults to false" beats "This value defaults to false if you don't specify it."
+- **No hedging.** "Returns the deployment ID" not "Should return the deployment ID."
+- **No second person except in examples.** The body describes the subject; it doesn't address the reader.
+- **Verbatim accuracy.** Error messages, key names, and command syntax must match exactly what the system produces or accepts.
+
+## Length
+
+No fixed target — complete and no longer. A schema page might run 1,000–2,500 words; a rules page 200–400 words; an enumeration 300–800 words. Over 3,000 words: consider splitting by sub-topic.
+
+## Anchors
+
+Reference pages are linked to with anchor fragments more than any other page type. Keep H2 and H3 headings stable across rewrites; renaming them breaks inbound anchors silently.
+
+## Checklist before publishing
+
+- [ ] `description` frontmatter is present and reads well in isolation (120–160 chars).
+- [ ] Overview is brief (one to three sentences) and substantive (no marketing).
+- [ ] The lookup body uses the right format for the subject.
+- [ ] Every key, value, rule, or item is documented; nothing silently omitted.
+- [ ] Code blocks are language-tagged; `title` attributes used for complete file examples.
+- [ ] Error messages quote the exact text the system produces.
+- [ ] H2 and H3 headings are stable; no rewording of headings that have inbound anchors.
+- [ ] No narrative explanation, no best-practice commentary, no hedging.
+- [ ] Related section links to the paired concept page and any guides that use this subject.

.github/doc-templates/tutorial.md

@@ -0,0 +1,82 @@
+# Tutorial page template
+
+A tutorial is a teaching page. The reader is new to the product or the feature, and we walk them through a working example end to end. They finish having done something real, with a concrete result they can see.
+
+A tutorial is not a how-to. A how-to assumes the reader knows what they want to do; a tutorial assumes they're new and need the experience of using the feature once before they can do it on their own.
+
+**Use for:** pages in Get started, and any page that introduces a feature through a guided walkthrough.  
+**Don't use for:** procedures for readers who already know what they're doing (guide), conceptual explanations (concept), or schema and rule lookups (reference).
+
+---
+
+## Skeleton
+
+```markdown
+---
+description: <One sentence summary, 120–160 chars. Used for SEO and AI retrieval. Required.>
+---
+
+# <Page title>
+
+What the reader will do on this page, in plain language. One paragraph, two to four sentences.
+Tell them what they'll have at the end.
+
+Don't start with "In this tutorial, we will..." Start with the thing they'll do.
+Example: "Deploy a Serverpod app to Cloud and see it running on a public URL."
+
+## Before you start
+
+- <Prerequisite 1 — link to install page, or concrete state, or external account>
+- <Prerequisite 2>
+- <Prerequisite 3>
+
+## <Step 1: action-shaped heading>
+
+One or two sentences explaining what this step does and why.
+
+<command or action>
+
+<expected output or result>
+
+## <Step 2: action-shaped heading>
+
+<as above>
+
+## What you've done
+
+Two to four sentences. Recap what they accomplished, then point them to the next thing:
+a Concepts page to deepen understanding, or a Guide for the next task.
+```
+
+---
+
+## Voice
+
+- **Second person, present tense.** "You'll see the deployment status print to the terminal."
+- **Direct steps, not options.** One path through the feature. Variants belong in Concepts or Reference.
+- **Show real output.** Don't paraphrase. Trim long output but show the actual format.
+- **Action-shaped headings.** "Deploy your project" beats "Deployment".
+
+## Length
+
+400–800 words plus code blocks. Readable in 5–10 minutes, doable in 15–30 minutes. Shorter suggests it's a how-to; longer suggests it should be split.
+
+## Code samples
+
+- Use real values, not placeholders, where possible. `my-app` beats `your-project-name`.
+- One language per code block.
+- Always tag the language fence (`bash`, `dart`, `yaml`, etc.).
+- Use the `title` attribute when the block represents a specific file.
+
+## Checklist before publishing
+
+- [ ] The reader can complete the tutorial on a clean machine following only this page.
+- [ ] Every step has a verifiable result.
+- [ ] `description` frontmatter is present and reads well in isolation (120–160 chars).
+- [ ] Headings are action-shaped.
+- [ ] Prerequisites are complete and accurate.
+- [ ] Code blocks are language-tagged; `title` attributes used for file content.
+- [ ] Screenshots match the current state of the UI (labels, buttons, and layout match what the tutorial describes).
+- [ ] Admonitions used sparingly and at the right severity level.
+- [ ] No marketing language, no hedging, no concept dumps.
+- [ ] Length is in the 400–800 word target range (excluding code blocks).