first commit

.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,34 @@
+---
+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.
+6. After addressing review comments, reply to the thread describing what was done, then resolve it. See `thread-N.md` files for ready-to-use commands.
+
+## 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

.agents/skills/pr-status-triage/local-repro.md

@@ -0,0 +1,30 @@
+# Local Reproduction Guide
+
+## Match CI Job Mode
+
+- Dev-mode failures: use `pnpm test-dev-turbo` or `pnpm test-dev-webpack` based on job mode.
+- Start-mode failures: use `pnpm test-start-turbo` or `pnpm test-start-webpack`.
+
+## Match CI Environment Variables
+
+Read the job environment variables from `pr-status` output and mirror them locally.
+
+Key variables to watch:
+
+- `IS_WEBPACK_TEST=1` forces webpack mode.
+- `NEXT_SKIP_ISOLATE=1` skips package isolation and can hide module-resolution issues.
+
+## Isolation Rule
+
+When validating module-resolution, entrypoint-export, or internal require-path fixes, rerun without `NEXT_SKIP_ISOLATE=1`.
+
+## One-Run Log Analysis
+
+Capture once, analyze multiple times:
+
+```bash
+HEADLESS=true pnpm test-dev-turbo test/path/to/test.ts > /tmp/test-output.log 2>&1
+grep "●" /tmp/test-output.log
+grep -A5 "Error:" /tmp/test-output.log
+tail -5 /tmp/test-output.log
+```

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

@@ -0,0 +1,44 @@
+# CI Triage Workflow
+
+## Prioritization Order
+
+1. Build failures
+2. Lint failures
+3. Type failures
+4. Test failures
+5. Review comments (after CI blockers)
+
+## Failure Handling Rules
+
+- Investigate each failing job as if it is caused by the current changes.
+- Do not assume flakiness by default.
+- If the job output has a "Known Flaky Tests" section, use it as historical context, not as automatic dismissal.
+
+## Common Patterns
+
+- `rust check / build`:
+  - Run `cargo fmt -- --check`
+  - Fix with `cargo fmt`
+- `lint / build`:
+  - Run `pnpm prettier --write <file>`
+  - Run the repo lint command if needed
+- test failures:
+  - Run the exact failing test file locally
+  - Match dev vs start mode to the CI job
+
+## Resolving Review Threads
+
+After addressing a review comment (e.g., making the requested code change):
+
+1. Reply to the thread describing what action was taken:
+   ```bash
+   node scripts/pr-status.js reply-thread <threadNodeId> "Done -- <description of changes>"
+   ```
+2. Then resolve the thread:
+   ```bash
+   node scripts/pr-status.js resolve-thread <threadNodeId>
+   ```
+
+The ready-to-use commands with the correct thread IDs are at the bottom of each `thread-N.md` file in `scripts/pr-status/`.
+
+**Important:** Always reply with a description of the actions taken before resolving. This gives the reviewer context about what changed.

.agents/skills/react-vendoring/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: react-vendoring
+description: >
+  React vendoring and react-server layer boundaries. Use when editing
+  entry-base.ts, $$compiled.internal.d.ts, compiled/react* packages,
+  or taskfile.js copy_vendor_react. Covers the entry-base.ts boundary
+  (all react-server-dom-webpack/* imports must go through it), vendored
+  React channels, type declarations, Turbopack remap to
+  react-server-dom-turbopack, ComponentMod access patterns, and ESLint
+  suppression for guarded requires.
+---
+
+# React Vendoring
+
+Use this skill for changes touching vendored React, `react-server-dom-webpack/*`, or react-server layer boundaries.
+
+## App Router Vendoring
+
+React is NOT resolved from `node_modules` for App Router. It's vendored into `packages/next/src/compiled/` during `pnpm build` (task: `copy_vendor_react()` in `taskfile.js`). Pages Router resolves React from `node_modules` normally.
+
+- **Two channels**: stable (`compiled/react/`) and experimental (`compiled/react-experimental/`). The runtime bundle webpack config aliases to the correct channel via `makeAppAliases({ experimental })`.
+
+## `entry-base.ts` Boundary
+
+Only `entry-base.ts` is compiled in rspack's `(react-server)` layer. ALL imports from `react-server-dom-webpack/*` (Flight server/static APIs) must go through `entry-base.ts`. Other files like `stream-ops.node.ts` or `app-render.tsx` must access Flight APIs via the `ComponentMod` parameter (which is the `entry-base.ts` module exposed through the `app-page.ts` build template).
+
+Direct imports from `react-server-dom-webpack/server.node` or `react-server-dom-webpack/static` in files outside `entry-base.ts` will fail at runtime with "The react-server condition must be enabled". Dev mode may mask this error, but production workers fail immediately.
+
+## Type Declarations
+
+`packages/next/types/$$compiled.internal.d.ts` contains `declare module` blocks for vendored React packages. When adding new APIs (e.g. `renderToPipeableStream`, `prerenderToNodeStream`), you must add type declarations here. The bare specifier types (e.g. `declare module 'react-server-dom-webpack/server'`) are what source code in `src/` imports against.
+
+## Adding Node.js-Only React APIs
+
+These exist in `.node` builds but not in the type definitions. Steps:
+
+1. Add type declarations to `$$compiled.internal.d.ts`.
+2. Export the API from `entry-base.ts` behind a `process.env` guard.
+3. Access it via `ComponentMod` in other files.
+
+```typescript
+// In entry-base.ts (react-server layer) only:
+/* eslint-disable import/no-extraneous-dependencies */
+export let renderToPipeableStream: ... | undefined
+if (process.env.__NEXT_USE_NODE_STREAMS) {
+  renderToPipeableStream = (
+    require('react-server-dom-webpack/server.node') as typeof import('react-server-dom-webpack/server.node')
+  ).renderToPipeableStream
+} else {
+  renderToPipeableStream = undefined
+}
+/* eslint-enable import/no-extraneous-dependencies */
+
+// In other files, access via ComponentMod:
+ComponentMod.renderToPipeableStream!(payload, clientModules, opts)
+```
+
+## ESLint Practical Rule
+
+For guarded runtime `require()` blocks that need `import/no-extraneous-dependencies` suppression, prefer scoped block disable/enable. If using `eslint-disable-next-line`, the comment must be on the line immediately before the `require()` call, NOT before the `const` declaration. When the `const` and `require()` are on different lines, this is error-prone.
+
+## Turbopack Remap
+
+`react-server-dom-webpack/*` is silently remapped to `react-server-dom-turbopack/*` by Turbopack's import map. Code says "webpack" everywhere, but Turbopack gets its own bindings at runtime. This affects debugging: stack traces and error messages will reference the turbopack variant.
+
+## Related Skills
+
+- `$flags` - flag wiring (config/schema/define-env/runtime env)
+- `$dce-edge` - DCE-safe require patterns and edge constraints
+- `$runtime-debug` - reproduction and verification workflow

.agents/skills/runtime-debug/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: runtime-debug
+description: >
+  Debug and verification workflow for runtime-bundle and module-resolution
+  regressions. Use when diagnosing unexpected module inclusions, bundle
+  size regressions, or CI failures related to NEXT_SKIP_ISOLATE, nft.json
+  traces, or runtime bundle selection (module.compiled.js). Covers CI env
+  mirroring, full stack traces via __NEXT_SHOW_IGNORE_LISTED, route trace
+  inspection, and webpack stats diffing.
+---
+
+# Runtime Debug
+
+Use this skill when reproducing runtime-bundle, module-resolution, or user-bundle inclusion regressions.
+
+## Local Repro Discipline
+
+- Mirror CI env vars when reproducing CI failures.
+- Key variables: `IS_WEBPACK_TEST=1` forces webpack (turbopack is default), `NEXT_SKIP_ISOLATE=1` skips packing next.js.
+- For module-resolution validation, always rerun without `NEXT_SKIP_ISOLATE=1`.
+
+## Stack Trace Visibility
+
+Set `__NEXT_SHOW_IGNORE_LISTED=true` to disable the ignore-list filtering in dev server error output. By default, Next.js collapses internal frames to `at ignore-listed frames`, which hides useful context when debugging framework internals. Defined in `packages/next/src/server/patch-error-inspect.ts`.
+
+## User-Bundle Regression Guardrail
+
+When user `next build` starts bundling internal Node-only helpers unexpectedly:
+
+1. Inspect route trace artifacts (`.next/server/.../page.js.nft.json`).
+2. Inspect traced server chunks for forbidden internals (e.g. `next/dist/server/stream-utils/node-stream-helpers.js`, `node:stream/promises`).
+3. Add a `test-start-webpack` assertion that reads the route trace and traced server chunks, and fails on forbidden internals. This validates user-project bundling (not publish-time runtime bundling).
+
+## Bundle Tracing / Inclusion Proof
+
+To prove what user bundling includes, emit webpack stats from the app's `next.config.js`:
+
+```js
+// next.config.js
+module.exports = {
+  webpack(config) {
+    config.profile = true
+    return config
+  },
+}
+```
+
+Then use `stats.toJson({ modules: true, chunks: true, reasons: true })` and diff `webpack-stats-server.json` between modes. This gives concrete inclusion reasons (e.g. which module required `node:stream/promises`) and is more reliable than analyzer HTML alone.
+
+## Related Skills
+
+- `$flags` - flag wiring (config/schema/define-env/runtime env)
+- `$dce-edge` - DCE-safe require patterns and edge constraints
+- `$react-vendoring` - entry-base boundaries and vendored React