[pull] canary from vercel:canary

.agents/skills/README.md

@@ -0,0 +1,115 @@
+# Skills Authoring Guide
+
+Skills are on-demand context files that Claude loads when relevant. They extend `AGENTS.md` with deep-dive workflows, code templates, and verification steps.
+
+## When to Create a Skill
+
+Create a skill when content is:
+- **Too detailed for AGENTS.md** (code templates, multi-step workflows, diagnostic procedures)
+- **Only relevant for specific tasks** (not every session needs it)
+- **Self-contained enough to load independently**
+
+Do NOT create a skill for:
+- One-liner rules or guardrails (keep those in AGENTS.md)
+- Content every agent session needs (that's what AGENTS.md is for)
+- Simple facts without actionable steps
+
+## File Structure
+
+```
+.agents/skills/
+├── my-skill/
+│   └── SKILL.md          # Required: frontmatter + content
+│   └── workflow.md        # Optional: supplementary files
+│   └── examples.md        # Optional: referenced from SKILL.md
+└── README.md              # This file
+```
+
+## SKILL.md Format
+
+```yaml
+---
+name: my-skill
+description: >
+  What this skill covers and when to use it. Include key file names,
+  concepts, and trigger phrases so Claude can match user intent to this
+  skill. This is the primary field Claude uses for auto-activation.
+---
+```
+
+### Supported Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Skill name, used for `$name` references and `/name` slash commands |
+| `description` | Yes | What the skill does and when to use it. **This is how Claude decides to auto-load the skill.** Include file names, concepts, and keywords. |
+| `argument-hint` | No | Hint for expected arguments in autocomplete |
+| `user-invocable` | No | Set to `false` to hide from `/` slash command menu |
+| `disable-model-invocation` | No | Set to `true` to prevent Claude from auto-triggering this skill |
+| `allowed-tools` | No | Tools Claude can use without permission when this skill is active |
+| `model` | No | Model override for this skill |
+| `context` | No | Set to `fork` for isolated subagent execution |
+| `agent` | No | Subagent type to use with `context: fork` |
+| `hooks` | No | Hooks scoped to this skill's lifecycle |
+
+Only use fields from this table. Unknown fields are ignored by Claude Code.
+
+### Writing Good Descriptions
+
+The `description` is the single most important field. Claude uses it to decide when to auto-load the skill. Include:
+
+- **What the skill covers** (the topic)
+- **When to use it** (the trigger scenario)
+- **Key file names** mentioned in the skill (e.g. `config-shared.ts`, `entry-base.ts`)
+- **Key concepts/keywords** a user or agent might mention (e.g. "DCE", "feature flag", "vendored React")
+
+```yaml
+# Bad: too vague, won't match well
+description: Helps with flags.
+
+# Good: specific, includes file names and keywords
+description: >
+  How to add or modify Next.js experimental feature flags end-to-end.
+  Use when editing config-shared.ts, config-schema.ts, define-env-plugin.ts,
+  next-server.ts, export/worker.ts, or module.compiled.js.
+```
+
+## Content Guidelines
+
+### Relationship to AGENTS.md
+
+AGENTS.md holds **always-loaded guardrails** (one-liner rules every session needs). Skills hold **deep-dive content** loaded on demand.
+
+- AGENTS.md should have a one-liner version of any critical rule
+- Skills expand on those rules with verification steps, code examples, and context
+- AGENTS.md points to skills via `$skill-name` references
+- Skills should not duplicate AGENTS.md content; they should go deeper
+
+### Structure a Skill for Action
+
+Skills should tell the agent what to **do**, not just what to **know**:
+
+- Lead with a clear "Use this skill when..." statement
+- Include step-by-step procedures where applicable
+- Add code templates ready to adapt
+- End with verification commands
+- Cross-reference related skills with a "Related Skills" section
+
+### Naming
+
+- Use short, descriptive names scoped to the topic: `flags`, `dce-edge`, `react-vendoring`
+- No repo-name prefix (skills are already scoped to this repo by being in `.agents/skills/`)
+- Use hyphens for multi-word names
+
+### Supplementary Files
+
+For complex skills, split into a hub SKILL.md + detail files:
+
+```
+pr-status-triage/
+├── SKILL.md         # Overview + quick commands
+├── workflow.md      # Detailed prioritization and patterns
+└── local-repro.md   # CI env matching guide
+```
+
+Reference detail files from SKILL.md with relative links. Keep SKILL.md scannable as an entry point.

.agents/skills/authoring-skills/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: authoring-skills
+description: >
+  How to create and maintain agent skills in .agents/skills/. Use when
+  creating a new SKILL.md, writing skill descriptions, choosing frontmatter
+  fields, or deciding what content belongs in a skill vs AGENTS.md.
+  Covers the supported spec fields, description writing, naming conventions,
+  and the relationship between always-loaded AGENTS.md and on-demand skills.
+user-invocable: false
+---
+
+# Authoring Skills
+
+Use this skill when creating or modifying agent skills in `.agents/skills/`.
+
+## When to Create a Skill
+
+Create a skill when content is:
+
+- Too detailed for AGENTS.md (code templates, multi-step workflows, diagnostic procedures)
+- Only relevant for specific tasks (not needed every session)
+- Self-contained enough to load independently
+
+Keep in AGENTS.md instead when:
+
+- It's a one-liner rule or guardrail every session needs
+- It's a general-purpose gotcha any agent could hit
+
+## File Structure
+
+```
+.agents/skills/
+└── my-skill/
+    ├── SKILL.md          # Required: frontmatter + content
+    ├── workflow.md        # Optional: supplementary detail
+    └── examples.md        # Optional: referenced from SKILL.md
+```
+
+## Supported Frontmatter Fields
+
+```yaml
+---
+name: my-skill # Required. Used for $name references and /name commands.
+description: > # Required. How Claude decides to auto-load the skill.
+  What this covers and when to use it. Include file names and keywords.
+argument-hint: '<pr-number>' # Optional. Hint for expected arguments.
+user-invocable: false # Optional. Set false to hide from / menu.
+disable-model-invocation: true # Optional. Set true to prevent auto-triggering.
+allowed-tools: [Bash, Read] # Optional. Tools allowed without permission.
+model: opus # Optional. Model override.
+context: fork # Optional. Isolated subagent execution.
+agent: Explore # Optional. Subagent type (with context: fork).
+---
+```
+
+Only use fields from this list. Unknown fields are silently ignored.
+
+## Writing Descriptions
+
+The `description` is the primary matching surface for auto-activation. Include:
+
+1. **What the skill covers** (topic)
+2. **When to use it** (trigger scenario)
+3. **Key file names** the skill references (e.g. `config-shared.ts`)
+4. **Keywords** a user or agent might mention (e.g. "feature flag", "DCE")
+
+```yaml
+# Too vague - won't auto-trigger reliably
+description: Helps with flags.
+
+# Good - specific files and concepts for matching
+description: >
+  How to add or modify Next.js experimental feature flags end-to-end.
+  Use when editing config-shared.ts, config-schema.ts, define-env-plugin.ts.
+```
+
+## Content Conventions
+
+### Structure for Action
+
+Skills should tell the agent what to **do**, not just what to **know**:
+
+- Lead with "Use this skill when..."
+- Include step-by-step procedures
+- Add code templates ready to adapt
+- End with verification commands
+- Cross-reference related skills in a "Related Skills" section
+
+### Relationship to AGENTS.md
+
+| AGENTS.md (always loaded)               | Skills (on demand)                                                     |
+| --------------------------------------- | ---------------------------------------------------------------------- |
+| One-liner guardrails                    | Step-by-step workflows                                                 |
+| "Keep require() behind if/else for DCE" | Full DCE pattern with code examples, verification commands, edge cases |
+| Points to skills via `$name`            | Expands on AGENTS.md rules                                             |
+
+When adding a skill, also add a one-liner summary to the relevant AGENTS.md section with a `$skill-name` reference.
+
+### Naming
+
+- Short, descriptive, topic-scoped: `flags`, `dce-edge`, `react-vendoring`
+- No repo prefix (already scoped by `.agents/skills/`)
+- Hyphens for multi-word names
+
+### Supplementary Files
+
+For complex skills, use a hub + detail pattern:
+
+```
+pr-status-triage/
+├── SKILL.md         # Overview, quick commands, links to details
+├── workflow.md      # Prioritization and patterns
+└── local-repro.md   # CI env matching
+```

.agents/skills/dce-edge/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: dce-edge
+description: >
+  DCE-safe require() patterns and edge runtime constraints. Use when writing
+  conditional require() calls, guarding Node-only imports (node:stream etc.),
+  or editing define-env-plugin.ts / app-render / stream-utils for edge builds.
+  Covers if/else branching for webpack DCE, TypeScript definite assignment,
+  the NEXT_RUNTIME vs real feature flag distinction, and forcing flags false
+  for edge in define-env.ts.
+---
+
+# DCE + Edge
+
+Use this skill when changing conditional `require()` paths, Node-only imports, or edge/runtime branching.
+
+## DCE-Safe `require()` Pattern
+
+Webpack only DCEs a `require()` when it sits inside the dead branch of an `if/else` whose condition DefinePlugin can evaluate at compile time.
+
+```ts
+// CORRECT - webpack can eliminate the dead branch
+if (process.env.__NEXT_USE_NODE_STREAMS) {
+  require('node:stream')
+} else {
+  // web path
+}
+```
+
+What does NOT work:
+
+- **Early-return/throw guards**: webpack doesn't do control-flow analysis for throws/returns, so the `require()` is still traced.
+- **Bare `if` without `else`**: works for inline `node:*` specifiers but NOT for `require('./some-module')` that pulls a new file into the module graph.
+
+Always test edge changes with `pnpm test-start-webpack` on `test/e2e/app-dir/app/standalone.test.ts` (has edge routes), not with `NEXT_SKIP_ISOLATE=1` which skips the full webpack compilation.
+
+## TypeScript + DCE Interaction
+
+Use `if/else` (not two independent `if` blocks) when assigning a variable conditionally on `process.env.X`. TypeScript cannot prove exhaustiveness across `if (flag) { x = a }; if (!flag) { x = b }` and will error with "variable used before being assigned". The `if/else` pattern satisfies both TypeScript (definite assignment) and webpack DCE.
+
+## Compile-Time Switcher Pattern
+
+Platform-specific code (node vs web) can use a single `.ts` switcher module that conditionally `require()`s either `.node.ts` or `.web.ts` into a typed variable, then re-exports the shared runtime API as named exports. Keep the branch as `if/else` so DefinePlugin can dead-code-eliminate the unused `require()`. Keep shared types canonical in `.node.ts`, with `.web.ts` importing them via `import type` and the switcher re-exporting types as needed. Examples: `stream-ops.ts` and `debug-channel-server.ts`.
+
+## `NEXT_RUNTIME` Is Not a Feature Flag
+
+In user-project webpack server compilers, `process.env.NEXT_RUNTIME` is inlined to `'nodejs'`. Guarding Node-only `require('node:*')` paths with `NEXT_RUNTIME === 'nodejs'` does **not** prune anything. For feature-gated codepaths, guard on the real feature define (e.g. `process.env.__NEXT_USE_NODE_STREAMS`).
+
+## Edge Runtime Constraints
+
+Edge routes do NOT use pre-compiled runtime bundles. They are compiled by the user's webpack/Turbopack, so `define-env.ts` controls DCE. Feature flags that gate `node:*` imports must be forced to `false` for edge builds in `define-env.ts` (`isEdgeServer ? false : flagValue`), otherwise webpack will try to resolve `node:stream` etc. and fail.
+
+## `app-page.ts` Template Gotchas
+
+- `app-page.ts` is a build template compiled by the user's bundler. Any `require()` in this file is traced by webpack/turbopack at `next build` time. You cannot require internal modules with relative paths because they won't be resolvable from the user's project. Instead, export new helpers from `entry-base.ts` and access them via `entryBase.*` in the template.
+- Template helpers should stay out of `RenderResult`. If `app-page.ts` needs a Node-stream-only utility, prefer a small dedicated helper module in `server/stream-utils/` (with DCE-safe `if/else` + `require()`).
+
+## Verification
+
+- Validate edge bundling regressions with `pnpm test-start-webpack test/e2e/app-dir/app/standalone.test.ts`
+- For module-resolution/build-graph fixes, verify without `NEXT_SKIP_ISOLATE=1`
+
+## Related Skills
+
+- `$flags` - flag wiring (config/schema/define-env/runtime env)
+- `$react-vendoring` - entry-base boundaries and vendored React
+- `$runtime-debug` - reproduction and verification workflow

.agents/skills/flags/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: flags
+description: >
+  How to add or modify Next.js experimental feature flags end-to-end.
+  Use when editing config-shared.ts, config-schema.ts, define-env-plugin.ts,
+  next-server.ts, export/worker.ts, or module.compiled.js. Covers type
+  declaration, zod schema, build-time injection, runtime env plumbing,
+  and the decision between runtime env-var branching vs separate bundle variants.
+---
+
+# Feature Flags
+
+Use this skill when adding or changing framework feature flags in Next.js internals.
+
+## Required Wiring
+
+All flags need: `config-shared.ts` (type) → `config-schema.ts` (zod). If the flag is consumed in user-bundled code (client components, edge routes, `app-page.ts` template), also add it to `define-env.ts` for build-time injection. Runtime-only flags consumed exclusively in pre-compiled bundles can skip `define-env.ts`.
+
+## Where the Flag Is Consumed
+
+**Client/bundled code only** (e.g. `__NEXT_PPR` in client components): `define-env.ts` is sufficient. Webpack/Turbopack replaces `process.env.X` at the user's build time.
+
+**Pre-compiled runtime bundles** (e.g. code in `app-render.tsx`): The flag must also be set as a real `process.env` var at runtime, because `app-render.tsx` runs from pre-compiled bundles where `define-env.ts` doesn't reach. Two approaches:
+
+- **Runtime env var**: Set in `next-server.ts` + `export/worker.ts`. Both code paths stay in one bundle. Simple but increases bundle size.
+- **Separate bundle variant**: Add DefinePlugin entry in `next-runtime.webpack-config.js` (scoped to `bundleType === 'app'`), new taskfile tasks, update `module.compiled.js` selector, and still set env var in `next-server.ts` + `export/worker.ts` for bundle selection. Eliminates dead code but adds build complexity.
+
+For runtime flags, also add the field to the `NextConfigRuntime` Pick type in `config-shared.ts`.
+
+## Runtime-Bundle Model
+
+- Runtime bundles are built by `next-runtime.webpack-config.js` (rspack) via `taskfile.js` bundle tasks.
+- Bundle selection occurs at runtime in `src/server/route-modules/app-page/module.compiled.js` based on `process.env` vars.
+- Variants: `{turbo/webpack} × {experimental/stable/nodestreams/experimental-nodestreams} × {dev/prod}` = up to 16 bundles per route type.
+- `define-env.ts` affects user bundling, not pre-compiled runtime internals.
+- `process.env.X` checks in `app-render.tsx` are either replaced by DefinePlugin at runtime-bundle-build time, or read as actual env vars at server startup. They are NOT affected by the user's defines from `define-env.ts`.
+- **Gotcha**: DefinePlugin entries in `next-runtime.webpack-config.js` must be scoped to the correct `bundleType` (e.g. `app` only, not `server`) to avoid replacing assignment targets in `next-server.ts`.
+
+## Related Skills
+
+- `$dce-edge` - DCE-safe require patterns and edge constraints
+- `$react-vendoring` - entry-base boundaries and vendored React
+- `$runtime-debug` - reproduction and verification workflow

.agents/skills/pr-status-triage/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: pr-status-triage
+description: >
+  Triage CI failures and PR review comments using scripts/pr-status.js.
+  Use when investigating failing CI jobs, flaky tests, or PR review feedback.
+  Covers blocker-first prioritization (build > lint > types > tests),
+  CI env var matching for local reproduction, and the Known Flaky Tests
+  distinction.
+---
+
+# PR Status Triage
+
+Use this skill when the user asks about PR status, CI failures, or review comments in the Next.js monorepo.
+
+## Workflow
+
+1. Run `node scripts/pr-status.js` (or `node scripts/pr-status.js <number>`).
+2. Read generated files in `scripts/pr-status/`.
+3. Prioritize blocking jobs first: build, lint, types, then test jobs.
+4. Treat failures as real until disproven; check the "Known Flaky Tests" section before calling anything flaky.
+5. Reproduce locally with the same mode and env vars as CI.
+
+## Quick Commands
+
+```bash
+node scripts/pr-status.js
+node scripts/pr-status.js <number>
+```
+
+## Detailed References
+
+- [workflow.md](./workflow.md) - prioritization and common failure patterns
+- [local-repro.md](./local-repro.md) - mode/env matching and isolation guidance