Merge branch 'canary' into mischnic/scope-hoisting-pure-enum

Author: DRoet

.claude/skills/update-docs/SKILL.md .agents/skills/update-docs/SKILL.md.claude/skills/update-docs/SKILL.md renamed to .agents/skills/update-docs/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: write-api-reference
+description: |
+  Produces API reference documentation for Next.js APIs: functions, components, file conventions, directives, and config options.
+
+  **Auto-activation:** User asks to write, create, or draft an API reference page. Also triggers on paths like `docs/01-app/03-api-reference/`, or keywords like "API reference", "props", "parameters", "returns", "signature".
+
+  **Input sources:** Next.js source code, existing API reference pages, or user-provided specifications.
+
+  **Output type:** A markdown (.mdx) API reference page with YAML frontmatter, usage example, reference section, behavior notes, and examples.
+agent: Plan
+context: fork
+---
+
+# Writing API Reference Pages
+
+## Goal
+
+Produce an API reference page that documents a single API surface (function, component, file convention, directive, or config option). The page should be concise, scannable, and example-driven.
+
+Each page documents **one API**. If the API has sub-methods (like `cookies.set()`), document them on the same page. If two APIs are independent, they get separate pages.
+
+## Structure
+
+Identify which category the API belongs to, then follow the corresponding template.
+
+### Categories
+
+1. **Function** (`cookies`, `fetch`, `generateStaticParams`): signature, params/returns, methods table, examples
+2. **Component** (`Link`, `Image`, `Script`): props summary table, individual prop docs, examples
+3. **File convention** (`page`, `layout`, `route`): definition, code showing the convention, props, behavior, examples
+4. **Directive** (`use client`, `use cache`): definition, usage, serialization/boundary rules, reference
+5. **Config option** (`basePath`, `images`, etc.): definition, config code, behavioral sections
+
+### Template
+
+````markdown
+---
+title: {API name}
+description: {API Reference for the {API name} {function|component|file convention|directive|config option}.}
+---
+
+{One sentence defining what it does and where it's used.}
+
+```tsx filename="path/to/file.tsx" switcher
+// Minimal working usage
+```
+
+```jsx filename="path/to/file.js" switcher
+// Same example in JS
+```
+
+## Reference
+
+{For functions: methods/params table, return type.}
+{For components: props summary table, then `#### propName` subsections.}
+{For file conventions: `### Props` with `#### propName` subsections.}
+{For directives: usage rules and serialization constraints.}
+{For config: options table or individual option docs.}
+
+### {Subsection name}
+
+{Description + code example + table of values where applicable.}
+
+## Good to know
+
+- {Default behavior or implicit effects.}
+- {Caveats, limitations, or version-specific notes.}
+- {Edge cases the developer should be aware of.}
+
+## Examples
+
+### {Example name}
+
+{Brief context, 1-2 sentences.}
+
+```tsx filename="path/to/file.tsx" switcher
+// Complete working example
+```
+
+```jsx filename="path/to/file.js" switcher
+// Same example in JS
+```
+
+## Version History
+
+| Version  | Changes         |
+| -------- | --------------- |
+| `vX.Y.Z` | {What changed.} |
+````
+
+**Category-specific notes:**
+
+- **Functions**: Lead with the function signature and `await` if async. Document methods in a table if the return value has methods (like `cookies`). Document options in a separate table if applicable.
+- **Components**: Start with a props summary table (`| Prop | Example | Type | Required |`). Then document each prop under `#### propName` with description, code example, and value table where useful.
+- **File conventions**: Show the default export signature with TypeScript types. Document each prop (`params`, `searchParams`, etc.) under `#### propName` with a route/URL/value example table.
+- **Directives**: No `## Reference` section. Use `## Usage` instead, showing correct placement. Document serialization constraints and boundary rules.
+- **Config options**: Show the `next.config.ts` snippet. Use subsections for each behavioral aspect.
+
+## Rules
+
+1. **Lead with what it does.** First sentence defines the API. No preamble.
+2. **Show working code immediately.** A minimal usage example appears right after the opening sentence, before `## Reference`.
+3. **Use `switcher` for tsx/jsx pairs.** Always include both. Always include `filename="path/to/file.ext"`.
+4. **Use `highlight={n}` for key lines.** Highlight the line that demonstrates the API being documented.
+5. **Tables for simple APIs, subsections for complex ones.** If a prop/param needs only a type and one-line description, use a table row. If it needs a code example or multiple values, use a `####` subsection.
+6. **Behavior section uses `> **Good to know**:`or`## Good to know`.** Use the blockquote format for brief notes (1-3 bullets). Use the heading format for longer sections. Not "Note:" or "Warning:".
+7. **Examples section uses `### Example Name` subsections.** Each example solves one specific use case.
+8. **Version History table at the end.** Include when the API has changed across versions. Omit for new APIs.
+9. **No em dashes.** Use periods, commas, or parentheses instead.
+10. **Mechanical, observable language.** Describe what happens, not how it feels. "Returns an object" not "gives you an object".
+11. **Link to related docs with relative paths.** Use `/docs/app/...` format.
+12. **No selling or justifying.** No "powerful", "easily", "simply". State what the API does.
+
+| Don't                                                   | Do                                                                                          |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| "This powerful function lets you easily manage cookies" | "`cookies` is an async function that reads HTTP request cookies in Server Components"       |
+| "You can conveniently access..."                        | "Returns an object containing..."                                                           |
+| "The best way to handle navigation"                     | "`<Link>` extends the HTML `<a>` element to provide prefetching and client-side navigation" |
+
+## Workflow
+
+1. **Ask for reference material.** Ask the user if they have any RFCs, PRs, design docs, or other context that should inform the doc.
+2. **Identify the API category** (function, component, file convention, directive, config).
+3. **Research the implementation.** Read the source code to understand params, return types, edge cases, and defaults.
+4. **Check e2e tests.** Search `test/` for tests exercising the API to find real usage patterns, edge cases, and expected behavior.
+5. **Check existing related docs** for linking opportunities and to avoid duplication.
+6. **Write using the appropriate category template.** Follow the rules above.
+7. **Review against the rules.** Verify: one sentence opener, immediate code example, correct `switcher`/`filename` usage, tables vs subsections, "Good to know" format, no em dashes, mechanical language.
+
+## References
+
+Read these pages in `docs/01-app/03-api-reference/` before writing. They demonstrate the patterns above.
+
+- `04-functions/cookies.mdx` - Function with methods table, options table, and behavior notes
+- `03-file-conventions/page.mdx` - File convention with props subsections and route/URL/value tables
+- `02-components/link.mdx` - Component with props summary table and detailed per-prop docs
+- `01-directives/use-client.mdx` - Directive with usage section and serialization rules
+- `04-functions/fetch.mdx` - Function with troubleshooting section and version history

…-docs/references/CODE-TO-DOCS-MAPPING.md …-docs/references/CODE-TO-DOCS-MAPPING.md.claude/skills/update-docs/references/CODE-TO-DOCS-MAPPING.md renamed to .agents/skills/update-docs/references/CODE-TO-DOCS-MAPPING.md .claude/skills/update-docs/references/CODE-TO-DOCS-MAPPING.md renamed to .agents/skills/update-docs/references/CODE-TO-DOCS-MAPPING.md

@@ -0,0 +1,116 @@
+---
+name: write-guide
+description: |
+  Generates technical guides that teach real-world use cases through progressive examples.
+
+  **Auto-activation:** User asks to write, create, or draft a guide or tutorial. Also use when converting feature documentation, API references, or skill knowledge into step-by-step learning content.
+
+  **Input sources:** Feature skills, API documentation, existing code examples, or user-provided specifications.
+
+  **Output type:** A markdown guide with YAML frontmatter, introduction, 2-4 progressive steps, and next steps section.
+agent: Plan
+context: fork
+---
+
+# Writing Guides
+
+## Goal
+
+Produce a technical guide that teaches a real-world use case through progressive examples. Concepts are introduced only when the reader needs them.
+
+Each guide solves **one specific problem**. Not a category of problems. If the outline has 5+ steps or covers multiple approaches, split it.
+
+## Structure
+
+Every guide follows this arc: introduction, example setup, 2-5 progressive steps, next steps.
+
+Each step follows this loop: working code → new requirement → friction → explanation → resolution → observable proof.
+
+Sections: introduction (no heading, 2 paragraphs max), `## Example` (what we're building + source link), `### Step N` (action-oriented titles, 2-4 steps), `## Next steps` (summary + related links).
+
+Headings should tell a story on their own. If readers only saw the headings, they'd understand the guide's takeaway.
+
+### Template
+
+````markdown
+---
+title: {Action-oriented, e.g., "Building X" or "How to Y"}
+description: {One sentence}
+nav_title: {Short title for navigation}
+---
+
+{What the reader will accomplish and why it matters. The friction and how this approach resolves it. 2 paragraphs max.}
+
+## Example
+
+As an example, we'll build {what we're building}.
+
+We'll start with {step 1}, then {step 2}, and {step 3}.
+
+{Source code link.}
+
+### Step 1: {Action-oriented title}
+
+{Brief context, 1-2 sentences.}
+
+```tsx filename="path/to/file.tsx"
+// Minimal working code
+```
+
+{Explain what happens.}
+
+{Introduce friction: warning, limitation, or constraint.}
+
+{Resolution: explain the choice, apply the fix.}
+
+{Verify the fix with observable proof.}
+
+### Step 2: {Action-oriented title}
+
+{Same pattern: context → code → explain → friction → resolution → proof.}
+
+### Step 3: {Action-oriented title}
+
+{Same pattern.}
+
+## Next steps
+
+You now know how to {summary}.
+
+Next, learn how to:
+
+- [Related guide 1]()
+- [Related guide 2]()
+````
+
+### Workflow
+
+1. **Research**: Check available skills for relevant features. Read existing docs for context and linking opportunities.
+2. **Plan**: Outline sections. Verify scope (one problem, 2-4 steps). Each step needs a friction point and resolution.
+3. **Write**: Follow the template above. Apply the rules below.
+4. **Review**: Re-read the rules, verify, then present.
+
+## Rules
+
+1. **Progressive disclosure.** Start with the smallest working example. Introduce complexity only when the example breaks. Name concepts at the moment of resolution, after the reader has felt the problem. Full loop: working → new requirement → something breaks → explain why → name the fix → apply → verify with proof → move on.
+2. **Show problems visually.** Console errors, terminal output, build warnings, slow-loading pages. "If we refresh the page, we can see the component blocks the response."
+3. **Verify resolutions with observable proof.** Before/after comparisons, browser reloads, terminal output. "If we refresh the page again, we can see it loads instantly."
+4. **One friction point per step.** If a step has multiple friction points, split it.
+5. **Minimal code blocks.** Only the code needed for the current step. Collapse unchanged functions with `function Header() {}`.
+6. **No em dashes.** Use periods, commas, or parentheses instead.
+7. **Mechanical, observable language.** Describe what happens, not how it feels.
+8. **No selling, justifying, or comparing.** No "the best way," no historical context, no framework comparisons.
+
+| Don't                                                | Do                                                       |
+| ---------------------------------------------------- | -------------------------------------------------------- |
+| "creates friction in the pipeline"                   | "blocks the response"                                    |
+| "needs dynamic information"                          | "depends on request-time data"                           |
+| "requires dynamic processing"                        | "output can't be known ahead of time"                    |
+| "The component blocks the response — causing delays" | "The component blocks the response. This causes delays." |
+
+## References
+
+Read these guides in `docs/01-app/02-guides/` before writing. They demonstrate the patterns above.
+
+- `public-static-pages.mdx` — intro → example → 3 progressive steps → next steps. Concepts named at point of resolution. Problems shown with build output.
+- `forms.mdx` — progressive feature building without explicit "Step" labels. Each section adds one capability.

…pdate-docs/references/DOC-CONVENTIONS.md …pdate-docs/references/DOC-CONVENTIONS.md.claude/skills/update-docs/references/DOC-CONVENTIONS.md renamed to .agents/skills/update-docs/references/DOC-CONVENTIONS.md .claude/skills/update-docs/references/DOC-CONVENTIONS.md renamed to .agents/skills/update-docs/references/DOC-CONVENTIONS.md

@@ -4,3 +4,4 @@ examples/
 .claude/
 AGENTS.md
 CLAUDE.md
+packages/next/dist/docs/

.agents/skills/write-api-reference/SKILL.md

@@ -3,6 +3,7 @@
     "attacks",
     "color",
     "dead",
+    "dirty",
     "execute",
     "executed",
     "executes",

.agents/skills/write-guide/SKILL.md

@@ -0,0 +1,23 @@
+id: no-context-format
+snapshots:
+  foo.bar().context(format!("{} failed", name)):
+    fixed: foo.bar().with_context(|| format!("{} failed", name))
+    labels:
+    - source: foo.bar().context(format!("{} failed", name))
+      style: primary
+      start: 0
+      end: 45
+  'foo.context(format!("error: {}", msg))':
+    fixed: 'foo.with_context(|| format!("error: {}", msg))'
+    labels:
+    - source: 'foo.context(format!("error: {}", msg))'
+      style: primary
+      start: 0
+      end: 38
+  foo.context(format!("simple message")):
+    fixed: foo.with_context(|| format!("simple message"))
+    labels:
+    - source: foo.context(format!("simple message"))
+      style: primary
+      start: 0
+      end: 38

.alexignore

@@ -0,0 +1,41 @@
+id: no-context-turbofmt
+snapshots:
+  foo.bar().context(turbofmt!("{} failed", name)):
+    fixed: foo.bar().with_context(|| turbofmt!("{} failed", name))
+    labels:
+    - source: foo.bar().context(turbofmt!("{} failed", name))
+      style: primary
+      start: 0
+      end: 47
+  foo.bar().context(turbofmt!("{} failed", name).await?):
+    labels:
+    - source: foo.bar().context(turbofmt!("{} failed", name).await?)
+      style: primary
+      start: 0
+      end: 54
+  'foo.context(turbofmt!("error: {}", msg))':
+    fixed: 'foo.with_context(|| turbofmt!("error: {}", msg))'
+    labels:
+    - source: 'foo.context(turbofmt!("error: {}", msg))'
+      style: primary
+      start: 0
+      end: 40
+  'foo.context(turbofmt!("error: {}", msg).await?)':
+    labels:
+    - source: 'foo.context(turbofmt!("error: {}", msg).await?)'
+      style: primary
+      start: 0
+      end: 47
+  foo.context(turbofmt!("simple message")):
+    fixed: foo.with_context(|| turbofmt!("simple message"))
+    labels:
+    - source: foo.context(turbofmt!("simple message"))
+      style: primary
+      start: 0
+      end: 40
+  foo.context(turbofmt!("simple message").await?):
+    labels:
+    - source: foo.context(turbofmt!("simple message").await?)
+      style: primary
+      start: 0
+      end: 47

.alexrc

@@ -0,0 +1,18 @@
+id: no-context-format
+valid:
+  - 'foo.context("static string")'
+  - 'foo.with_context(|| format!("error: {}", msg))'
+  - 'foo.context(msg)'
+invalid:
+  - 'foo.context(format!("error: {}", msg))'
+  - 'foo.context(format!("simple message"))'
+  - 'foo.bar().context(format!("{} failed", name))'
+---
+id: no-context-turbofmt
+valid:
+  - 'foo.context("static string")'
+  - 'foo.context(msg)'
+invalid:
+  - 'foo.context(turbofmt!("error: {}", msg).await?)'
+  - 'foo.context(turbofmt!("simple message").await?)'
+  - 'foo.bar().context(turbofmt!("{} failed", name).await?)'