chore(next): commit the managed agent block and untrack next-env.d.ts

.gitignore

@@ -71,6 +71,12 @@ test.db
 .next/
 out/
 
+# Generated by `next dev`, `next build`, and `next typegen`; its import path
+# differs between dev and production builds, so committing it only creates churn.
+# Next.js docs: "next-env.d.ts is managed by Next.js ... Add it to .gitignore"
+# (nextjs.org/docs/app/api-reference/config/typescript, next CLI reference).
+next-env.d.ts
+
 # Database
 *.db
 *.db-journal

AGENTS.md

@@ -264,143 +264,153 @@
 # Check production deployment
 gh api repos/d-oit/do-knowledge-studio/deployments --jq '.[] | select(.environment == "Production")'
 
 # Verify build passes locally
 pnpm run build
 ```
 
 ### Common Vercel Failure Causes
 
 | Cause | Symptom | Fix |
 |-------|---------|-----|
 | Node.js version too old | Build fails with syntax errors | Ensure `engines.node >= 20` in package.json |
 | Missing `vercel.json` | Vercel uses wrong build command | Add vercel.json with explicit config |
 | `pnpm-lock.yaml` out of date | Install fails | Run `pnpm install` and commit lockfile |
 | TypeScript errors | Build fails | Run `pnpm run typecheck` before pushing |
 | Missing dependencies | Import errors | Run `pnpm install` and commit changes |
 | Major dependency bump (breaking API) | Type errors in build only | Run `./scripts/verify-deps.sh` after any dependabot merge |
 | TypeScript major bump (deprecations) | TSconfig option deprecated | Add `"ignoreDeprecations": "6.0"` to tsconfig.base.json |
 
 ### Dependency Upgrade Rules
 
 When merging dependabot PRs or manually bumping dependencies:
 
 1. **Always run `./scripts/verify-deps.sh`** after any dependency version change.
 2. **Major version bumps** (semver X.0.0) require checking the changelog for breaking API changes — do not auto-merge.
 3. **TypeScript major bumps** may deprecate tsconfig options — check `pnpm run typecheck` output for deprecation warnings treated as errors.
 4. **UI library major bumps** (shadcn primitives, react-resizable-panels, radix) may rename exports — check `pnpm run build` for type errors.
 5. **After merging any dependabot PR**, immediately run the full quality workflow including `pnpm run build` and push a fix if needed.
 
 ## Learnings (session-distilled)
 
 - **gitleaks-action v3+ requires a paid `GITLEAKS_LICENSE` secret** — pin
   v2.x (e.g. v2.3.9) for license-free scanning. A failing license gate
   masks real scan results; re-run the scan after unblocking and extend
   `.gitleaks.toml` allowlists (full-history scans surface deleted test
   files — allowlist by path pattern).
 - **yamllint applies `line-length` (120) and `new-line-at-end-of-file`
   inside `run: |` block scalars and `.github/workflow-templates/`
   files** — pre-push check: `awk 'length > 120'` on all
   `.yml`/`.yaml`, verify trailing newline via `tail -c 1`.
 - **Branch rule `required_review_thread_resolution` blocks merges even
   with all checks green** — resolve OwlWatch/DeepSource threads via
   GraphQL `resolveReviewThread` before merging; they are merge gates,
   not noise. Check threads via GraphQL `pullRequest.reviewThreads` or
   `pulls/<n>/comments` — issue comments and `reviewDecision` do NOT
   reveal them, and resolving flips `BLOCKED` → `CLEAN` instantly
   (LESSON-026/030). **Outdated threads block too**: `isOutdated: true`
   threads still count toward the gate while `isResolved: false`, and
   the staleness ladder (plans/098) can fail on PR #692 even after the
   empty-commit nudge — resolve *every* thread regardless of the
   outdated flag (verified 2026-08-16, PR #692).
 - **DeepSource `.deepsource.toml` suppressions do not reliably prevent
   check failures** — new module-scope helpers trip JS-0067 (use
   `const fn = () => {}`, never `function`) and inline branches can push
   exported functions over the JS-R1005 complexity threshold; fix at
   code level (extract helpers, keep complexity < 6) before pushing.
 - **A BLOCKED merge state with all-green `gh pr checks` may hide an
   in-flight check run on the head commit** — before declaring staleness,
   diff `commits/{sha}/check-runs` (the real source of truth), then the
   staleness ladder (ruleset verify, threads, nudge, close/reopen) and
   `--admin` only with explicit approval. The
   `pr-merge-state-diagnoser.yml` workflow automates this diagnosis.
 - **Codacy (the sole required status check) can be entirely MISSING
   from a head — a transient delay, not a broken integration** —
   diagnose BLOCKED-with-all-green via `commits/{sha}/check-runs`;
   nudge with an empty-commit push and it analyzes every later push.
   Its known false-positive patterns (`detect-object-injection` on
   constant lookups, "always falsy" on TS non-nullables,
   void-expression arrows) are fixed at code level (exhaustive
   switches, bounds/presence checks, braces) — `.codacy.yml`
   suppressions do not cover new PR code (LESSON-031, plans/123,
   plans/112).
 - **GitNexus/DeepSource re-post stale positional findings as NEW unresolved threads on every push** — the same fixed finding reappears with a fresh thread id (observed 4× on PR #758), and `required_review_thread_resolution` turns each re-post into a merge blocker. Verify the working tree is fixed (locals confirm), reply with evidence, resolve via GraphQL `resolveReviewThread`, and stop pushing until CI demands it. Long-term fix: switch both integrations to check-summary-only reporting (LESSON-034).
 - See `agents-docs/LESSONS.md` (LESSON-024..034) and
   `plans/116-ci-workflow-learnings-2026-08-11.md` for full detail.
 
 ## Skills
 
 - Canonical skills live in `.agents/skills/`.
 - Refresh symlinks with `./scripts/setup-skills.sh`.
 - Load only the skills needed for the task to limit context usage.
 - Prefer existing skills and existing `agents-docs/` guidance before inventing a new workflow.
 
 ### Available Skills
 
 | Skill | Description | Category |
 |-------|-------------|----------|
 | `accessibility-auditor` | Audit web applications for WCAG 2.2 compliance, screen reade | Security |
 | `agent-browser` | Browser automation CLI for AI agents. Use when the user need | workflow |
 | `agent-coordination` | Coordinate multiple agents for software development across a | Coordination |
 | `agents-md` | Create AGENTS.md files with production-ready best practices. | General |
 | `anti-ai-slop` | Avoid generic AI aesthetic in UI/UX design and copy | General |
 | `api-design-first` | Design and document RESTful APIs using design-first principl | API Development |
 | `architecture-diagram` | Generate or update a project architecture SVG diagram by sca | General |
 | `atomic-commit` | Atomic git workflow - validates, commits, pushes, creates PR | General |
 | `cicd-pipeline` | Design and implement CI/CD pipelines with GitHub Actions, Gi | DevOps |
 | `cloudflare-worker-api` | > | workflow |
 | `codacy` | Use Codacy static analysis CLIs to query PR analysis, triage | Quality |
 | `code-quality` | Review and improve code quality across any programming langu | Quality |
 | `code-review-assistant` | Automated code review with PR analysis, change summaries, an | General |
 | `codeberg-api` | >- | API Development |
 | `database-devops` | Database design, migration, and DevOps automation with safet | DevOps |
 | `database-schema-migrations` | > | workflow |
 | `do-web-doc-resolver` | Python resolver for URLs and queries into compact, LLM-ready | Documentation |
 | `docs-hook` | Lightweight git hook integration for updating agents-docs wi | Documentation |
 | `document-rendering-and-locators` | > | workflow |
 | `dogfood` | Systematically explore and test a web application to find bu | quality |
 | `git-github-workflow` | Unified atomic git workflow with GitHub integration - commit | General |
 | `github-readme` | Create human-focused GitHub README.md files with 2026 best p | Documentation |
 | `github-workflow` | Complete GitHub workflow automation - push, create branch/PR | General |
 | `goap-agent` | Invoke for complex multi-step tasks requiring intelligent pl | Coordination |
 | `impeccable` | Design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize frontend interfaces. Covers UX review, visual hierarchy, typography, spacing, layout, color, motion, responsive behavior, theming, and anti-patterns.
 | General |
 | `intent-classifier` | Classify user intents and route to appropriate skills, comma | Coordination |
 | `iterative-refinement` | Execute iterative refinement workflows with validation loops | General |
 | `jules` | > | General |
 | `jules-implement` | > | General |
 | `learn` | Extract non-obvious session learnings into scoped AGENTS.md  | knowledge-management |
 | `local-chat-policy` | Guidelines for ensuring chat functionality prioritizes local | General |
 | `memory-context` | Retrieve semantically relevant past learnings and analysis o | General |
 | `migration-refactoring` | Automate complex code migrations and refactorings with safet | Migration |
 | `parallel-execution` | Execute multiple independent tasks simultaneously using para | Coordination |
 | `privacy-first` | > | Security |
 | `pwa-offline-sync` | > | workflow |
 | `reader-ui-ux` | > | workflow |
 | `secure-invite-and-access` | > | workflow |
 | `security-code-auditor` | Perform security audits on code to identify vulnerabilities, | Security |
 | `self-fix-loop` | Self-learning fix loop - commit, push, monitor CI, auto-fix  | General |
 | `shell-script-quality` | Lint and test shell scripts using ShellCheck and BATS. Use w | Quality |
 | `skill-creator` | Create new skills, modify and improve existing skills, and m | Meta |
 | `skill-evaluator` | Reusable skill for evaluating other skills with structure ch | Meta |
 | `static-analysis-suppression` | Suppress false-positive Codacy/DeepSource/ESLint blockers on PRs with code-level, config-level, or admin-merge fixes. Follows decision tree: fix code before suppressing config before admin override. | Quality |
 | `stitch-design` | > | General |
 | `task-decomposition` | Break down complex tasks into atomic, actionable goals with  | Coordination |
 | `test-runner` | Execute tests, analyze results, and diagnose failures across | Quality |
 | `testdata-builders` | > | quality |
 | `testing-strategy` | Design comprehensive testing strategies with modern techniqu | Quality |
 | `triz-analysis` | Run a systematic TRIZ contradiction audit against a codebase | analysis |
 | `triz-solver` | Systematic problem-solving using TRIZ (Theory of Inventive P | innovation-problem-solving |
 | `turso-db` | Use this skill for Turso (LibSQL/Limbo) database development | DevOps |
 | `ui-ux-optimize` | > | UI/UX |
 | `validation-checklist` | Maintain high data quality and schema adherence within the k | Quality |
 | `web-search-researcher` | Research topics using web search to find accurate, current i | Research |
+
+<!-- BEGIN:nextjs-agent-rules -->
+
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
+
+This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
+
+<!-- END:nextjs-agent-rules -->

package.json

@@ -13,7 +13,7 @@
     "build": "next build",
     "start": "next start",
     "lint": "eslint .",
-    "typecheck": "tsc --noEmit -p tsconfig.app.json",
+    "typecheck": "next typegen && tsc --noEmit -p tsconfig.app.json",
     "propagate:version": "bash scripts/propagate-version.sh",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",

plans/150-next-generated-files-official-practice-2026-09-24.md

@@ -0,0 +1,105 @@
+# Plan 150 — Next.js Generated Files: Official Practice for the Agent Block and `next-env.d.ts` (2026-09-24)
+
+**Type**: tooling hygiene (vendor-documented), no product change
+**Scope**: `AGENTS.md`, `.gitignore`, `package.json` (`typecheck`), `next-env.d.ts` (untracked)
+**Source**: Next.js 16.3 documentation, verified against the installed package
+
+## 1. Problem
+
+Two tracked files churn on every development command, so the tree is dirty after
+any `pnpm dev` or `pnpm build`:
+
+| File | What happens | How often |
+|---|---|---|
+| `AGENTS.md` | `next dev` appends its managed agent-rules block when it detects an agent and none is present | every `next dev` start |
+| `next-env.d.ts` | import path flips between `.next/dev/types/…` (dev) and `.next/types/…` (build) | every regenerating command |
+
+Both are files Next.js owns, so the question is what Next.js actually recommends —
+not what looks tidy.
+
+## 2. What the official docs say
+
+### Agent rules block — commit it
+
+[`nextjs.org/docs/app/guides/ai-agents`](https://nextjs.org/docs/app/guides/ai-agents):
+
+> On Next.js 16.3 or later, run `next dev`. When an AI coding agent is detected in
+> the environment and no managed block is present, Next.js auto-generates
+> `AGENTS.md` and `CLAUDE.md` at the project root. Existing `AGENTS.md` or
+> `CLAUDE.md` files are upserted, so content outside the managed block is
+> preserved. … Add your own project-specific instructions outside the markers, and
+> they're preserved when Next.js updates the managed block.
+
+The block's own text states the recommendation: *"Removing it from a diff only
+re-creates the uncommitted change; committing it with your work keeps the tree
+clean."*
+
+There is an opt-out — `agentRules: false` in `next.config.ts` — but the docs argue
+against it: *"We believe leaving auto-generation on is a good default. Benchmark
+results on nextjs.org/evals show agents do better when they read the bundled
+docs."* This repository relies on agents reading version-matched guidance, so the
+block stays.
+
+### `next-env.d.ts` — gitignore it, generate it on demand
+
+[`nextjs.org/docs/app/api-reference/config/typescript`](https://nextjs.org/docs/app/api-reference/config/typescript):
+
+> `next-env.d.ts` is managed by Next.js. Its contents are an implementation detail
+> and may change over time. Add it to `.gitignore`.
+
+[`nextjs.org/docs/app/api-reference/cli/next`](https://nextjs.org/docs/app/api-reference/cli/next):
+
+> Additionally, `next typegen` generates a `next-env.d.ts` file. We recommend
+> adding `next-env.d.ts` to your `.gitignore` file. … To ensure `next-env.d.ts` is
+> present before type-checking run `next typegen`.
+
+The Next.js team confirmed the same in
+[vercel/next.js#58877](https://github.com/vercel/next.js/issues/58877), including
+this exact dev-vs-production flip: *"Because `next-env.d.ts` depends on the last
+ran command, I added it to `.gitignore`. Doing so was impractical in the past
+because `next typegen` did not exist."*
+
+## 3. Change
+
+1. **`AGENTS.md`** — the managed block is committed, byte-identical to what the
+   generator writes. It was produced by calling Next's own `writeAgentFiles()`
+   (the function `next dev` calls) rather than transcribed, so
+   `hasCurrentAgentRules()` returns `true` and `next dev` skips the write
+   entirely.
+2. **`.gitignore`** — `next-env.d.ts` added, with the doc citation in a comment.
+3. **`next-env.d.ts`** — untracked (`git rm --cached`); still generated on demand
+   by `next dev`, `next build`, and `next typegen`.
+4. **`package.json`** — `typecheck` becomes `next typegen && tsc --noEmit -p
+   tsconfig.app.json`, per the CLI reference. It also keeps `.next/types` route
+   types fresh for editors, which the root `tsconfig.json` includes.
+
+Deliberately **not** changed: `agentRules: false` (docs recommend against), and the
+`lint`/`test` scripts (neither needs the generated file — verified by deleting it
+and running both).
+
+## 4. Verification
+
+| Check | Result |
+|---|---|
+| `hasCurrentAgentRules(repo)` before / after committing the block | `false` → `true` |
+| `writeAgentFiles(repo)` | `{"agentsMd":"updated","claudeMd":"skipped"}` — then a re-run reports `unchanged` |
+| `git status` after `next dev` writes nothing | clean (no `AGENTS.md`, no `next-env.d.ts`) |
+| `git check-ignore -v next-env.d.ts` | `.gitignore:78` |
+| `pnpm run typecheck` with the file deleted | regenerates via `next typegen` (0.95 s), tsc exit 0 |
+| `pnpm run lint` with the file deleted | exit 0 (eslint does not need it) |
+| `pnpm exec vitest run` type-tested files without the file | 146 passed, no type errors |
+| **Fresh-checkout simulation** (`git worktree add`, shared `node_modules`, no `.next`, no `next-env.d.ts`) | `typecheck` ✓, `lint` ✓, `hasCurrentAgentRules` ✓, full gate ✓ |
+| `./scripts/quality_gate.sh`, `pnpm run build` | ✓ green |
+
+The fresh-checkout run is the one that matters for CI: the quality-gate job starts
+from a clone with neither file present, and it now regenerates what it needs
+instead of relying on a committed artifact.
+
+## 5. Follow-ups
+
+1. **Vercel** runs `next build`, which writes its own `next-env.d.ts` — no change
+   needed, but the next production deploy is the confirmation (plans/098's
+   staleness lesson applies: verify the deployed commit, not the PR).
+2. **`semantic-search.spec.ts` load sensitivity** (plans/149 §6.1) — unchanged.
+3. **DeepSource quota** (plans/141 §1) — account-level, needs the maintainer.
+4. **ESLint 10 workaround** (plans/140 §2) — blocked upstream.