geneseed 5.4.0 → 5.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (191) hide show
  1. package/CHANGELOG.md +51 -0
  2. package/README.md +31 -1
  3. package/SHIPPED.md +1 -1
  4. package/adapters/bob/README.md +12 -1
  5. package/adapters/opencode/README.md +2 -1
  6. package/adapters/opencode/plugins/geneseed-context.js +71 -10
  7. package/adapters/opencode/plugins/geneseed-guard.js +101 -19
  8. package/adapters/opencode/plugins/geneseed-learn.js +641 -6
  9. package/bin/geneseed-cli.mjs +3 -0
  10. package/bin/geneseed-hook.mjs +2 -1
  11. package/docs/concepts/agents.md +13 -1
  12. package/docs/concepts/enforcement-table.md +1 -1
  13. package/docs/concepts/foreman-mode.md +22 -3
  14. package/docs/concepts/hook-gates.md +1 -1
  15. package/docs/concepts/hooks.md +22 -5
  16. package/docs/concepts/host-matrix.md +2 -2
  17. package/docs/concepts/hosts.md +1 -1
  18. package/docs/concepts/shared-tier.md +1 -1
  19. package/docs/concepts/skills.md +21 -1
  20. package/docs/concepts/themes.md +1 -1
  21. package/docs/extending.md +11 -2
  22. package/docs/guides/install-clone.md +18 -0
  23. package/docs/guides/install-scripted.md +8 -2
  24. package/docs/guides/install.md +19 -1
  25. package/docs/guides/upgrade.md +1 -1
  26. package/docs/reference/env-context.md +1 -1
  27. package/docs/reference/environment.md +1 -1
  28. package/docs/reference/plugin-learn.md +4 -0
  29. package/docs/reference/profiles.md +226 -0
  30. package/docs/token-footprint.md +9 -4
  31. package/docs/understand/design-choices-engineering.md +1 -1
  32. package/docs/web-ui.md +3 -1
  33. package/harness.config.json +1 -1
  34. package/js/README.md +9 -2
  35. package/js/build/args.mjs +4 -3
  36. package/js/build/catalog.mjs +11 -1
  37. package/js/build/driver.mjs +42 -11
  38. package/js/build/emit-claude.mjs +24 -1
  39. package/js/build/emit-opencode.mjs +3 -0
  40. package/js/build/export.mjs +12 -17
  41. package/js/build/generate.mjs +2 -1
  42. package/js/build/notes-migrate.mjs +99 -0
  43. package/js/build/profile.mjs +14 -6
  44. package/js/build/render.mjs +34 -10
  45. package/js/build/source.mjs +85 -2
  46. package/js/cli-table.json +164 -4
  47. package/js/hosts/agent-runs.mjs +205 -0
  48. package/js/hosts/done-checks.mjs +3 -1
  49. package/js/hosts/hooks-done.mjs +91 -16
  50. package/js/hosts/hooks-learn.mjs +85 -0
  51. package/js/hosts/hooks-prims.mjs +39 -1
  52. package/js/hosts/hooks.mjs +10 -4
  53. package/js/hosts/hosts.mjs +10 -0
  54. package/js/hosts/installs.mjs +25 -1
  55. package/js/hosts/link.mjs +45 -10
  56. package/js/hosts/native.mjs +42 -5
  57. package/js/hosts/opencode.mjs +1 -1
  58. package/js/hosts/settings.mjs +72 -0
  59. package/js/hosts/spec-feedback.mjs +538 -0
  60. package/js/hosts/usage.mjs +67 -8
  61. package/js/inspect/agent-scores.mjs +118 -0
  62. package/js/inspect/checks-authoring.mjs +2 -1
  63. package/js/inspect/checks-build.mjs +20 -4
  64. package/js/inspect/checks-repo.mjs +27 -2
  65. package/js/inspect/cost.mjs +6 -5
  66. package/js/inspect/diff.mjs +25 -5
  67. package/js/inspect/doctor.mjs +4 -0
  68. package/js/inspect/status.mjs +3 -1
  69. package/js/inspect/validate.mjs +1 -0
  70. package/js/lib/machine-dir.mjs +8 -0
  71. package/js/lib/paths.mjs +4 -1
  72. package/js/maintain/profile-scope.mjs +145 -0
  73. package/js/maintain/profiles.mjs +486 -0
  74. package/js/maintain/setup.mjs +409 -15
  75. package/js/maintain/uninstall.mjs +4 -1
  76. package/js/maintain/update.mjs +1 -1
  77. package/js/web/actions.mjs +28 -38
  78. package/js/web/api.mjs +7 -2
  79. package/js/web/handler.mjs +8 -0
  80. package/js/web/jobs.mjs +5 -4
  81. package/js/web/profiles-api.mjs +201 -0
  82. package/js/web/routes.mjs +5 -0
  83. package/package.json +2 -1
  84. package/profiles/autonomous.json +14 -0
  85. package/profiles/corporate.json +14 -0
  86. package/profiles/guillaume-claude-global.json +16 -0
  87. package/profiles/mentor.json +13 -0
  88. package/profiles/minimal.json +15 -0
  89. package/profiles/starter.json +14 -0
  90. package/src/AGENT.md.tmpl +1 -1
  91. package/src/agents/_self-improvement.md +15 -7
  92. package/src/agents/_template.md +4 -2
  93. package/src/agents/advocate.md +1 -1
  94. package/src/agents/architect.md +1 -1
  95. package/src/agents/developer.md +10 -3
  96. package/src/agents/devops-engineer.md +7 -6
  97. package/src/agents/docker-expert.md +1 -1
  98. package/src/agents/docs.md +1 -1
  99. package/src/agents/empiricist.md +1 -1
  100. package/src/agents/explorer.md +4 -2
  101. package/src/agents/framer.md +1 -1
  102. package/src/agents/historian.md +1 -1
  103. package/src/agents/kubernetes-specialist.md +4 -2
  104. package/src/agents/memory-curator.md +1 -1
  105. package/src/agents/operator.md +1 -1
  106. package/src/agents/performance.md +1 -1
  107. package/src/agents/pragmatist.md +1 -1
  108. package/src/agents/react-engineer.md +1 -1
  109. package/src/agents/react-reviewer.md +1 -1
  110. package/src/agents/researcher.md +1 -1
  111. package/src/agents/reviewer.md +10 -3
  112. package/src/agents/security.md +1 -1
  113. package/src/agents/skeptic.md +1 -1
  114. package/src/agents/spring-boot-engineer.md +4 -4
  115. package/src/agents/spring-reviewer.md +5 -3
  116. package/src/agents/spring-security.md +1 -1
  117. package/src/agents/steward.md +1 -1
  118. package/src/agents/tester.md +4 -2
  119. package/src/agents/user-advocate.md +1 -1
  120. package/src/agents/visionary.md +1 -1
  121. package/src/memory/README.md +12 -2
  122. package/src/modes/foreman.md +23 -10
  123. package/src/skill-descriptions.json +63 -0
  124. package/src/skills/_self-improvement.md +42 -26
  125. package/src/skills/_template.md +3 -1
  126. package/src/skills/brainstorm.md +35 -22
  127. package/src/skills/codebase-design.md +2 -2
  128. package/src/skills/daydream/VENDOR.md +6 -0
  129. package/src/skills/diagram-design/SKILL.md +12 -7
  130. package/src/skills/diagram-design/VENDOR.md +23 -14
  131. package/src/skills/diagram-design/references/layout-budget.md +7 -1
  132. package/src/skills/diagram-design/references/onboarding.md +1 -1
  133. package/src/skills/diagram-design/references/primitives-core.md +1 -1
  134. package/src/skills/diagram-design/references/semantic-patterns.md +1 -1
  135. package/src/skills/diagram-design/references/style-guide.md +1 -1
  136. package/src/skills/diagram-design/references/type-dependency.md +69 -0
  137. package/src/skills/diagram-design/references/type-event-modeling.md +36 -0
  138. package/src/skills/diagram-design/references/type-requirement-traceability.md +45 -0
  139. package/src/skills/diagram-design/references/type-sbgn.md +80 -0
  140. package/src/skills/diagram-design/references/type-scatter.md +1 -1
  141. package/src/skills/diagram-design/references/type-steps.md +180 -0
  142. package/src/skills/diagram-design/references/type-unit-grid.md +63 -0
  143. package/src/skills/explain-changes/VENDOR.md +5 -1
  144. package/src/skills/geneseed-code-review.md +2 -1
  145. package/src/skills/parallel-agents.md +12 -1
  146. package/src/skills/pipeline.md +3 -3
  147. package/src/skills/plan.md +5 -4
  148. package/src/skills/react-view-transitions/AGENTS.md +26 -26
  149. package/src/skills/react-view-transitions/SKILL.md +1 -1
  150. package/src/skills/react-view-transitions/VENDOR.md +19 -4
  151. package/src/skills/release.md +7 -2
  152. package/src/skills/rule/approve.md +2 -1
  153. package/src/skills/skill-forge.md +5 -3
  154. package/src/skills/spring-boot/cloud.md +19 -1
  155. package/src/skills/spring-boot/logging.md +5 -3
  156. package/src/skills/spring-boot/web.md +27 -2
  157. package/src/skills/spring-boot.md +4 -2
  158. package/src/skills/spring-data-jpa.md +18 -4
  159. package/src/skills/spring-testing.md +4 -0
  160. package/src/skills/token-report/VENDOR.md +5 -1
  161. package/src/upstreams.json +6 -6
  162. package/themes/README.md +3 -1
  163. package/web/dist/assets/{ActiveLoops-BJJN3P-V.js → ActiveLoops-DOJCPPPc.js} +1 -1
  164. package/web/dist/assets/{Activity-D2kOc3yi.js → Activity-bUSPM3Dl.js} +1 -1
  165. package/web/dist/assets/{ActivityDetail-By3xOr21.js → ActivityDetail-AHRoXeFN.js} +1 -1
  166. package/web/dist/assets/{Bonsai-CBWDTBA4.js → Bonsai-B5XY9pid.js} +1 -1
  167. package/web/dist/assets/{CopyButton-BVbpriMB.js → CopyButton-C0wwRR9H.js} +1 -1
  168. package/web/dist/assets/{Dashboard-CIJLPHM9.js → Dashboard-DPAA96EI.js} +2 -2
  169. package/web/dist/assets/{Docs-CiRRIELs.js → Docs-CpGDq165.js} +1 -1
  170. package/web/dist/assets/{Factories-DhyK0O8d.js → Factories-cNhETa5Q.js} +1 -1
  171. package/web/dist/assets/{GreenhouseView-DW3PgTPy.js → GreenhouseView-DO3ADmT9.js} +1 -1
  172. package/web/dist/assets/Installs-D3dDyq10.js +3 -0
  173. package/web/dist/assets/{JournalView-O65qEWfp.js → JournalView--W-Lw_V9.js} +1 -1
  174. package/web/dist/assets/{Kits-C5U-yT6Z.js → Kits-ChfehxY6.js} +1 -1
  175. package/web/dist/assets/Laws-CNxYmV36.js +4 -0
  176. package/web/dist/assets/{LibRows-D6-CVa3K.js → LibRows-CiPvsRYB.js} +1 -1
  177. package/web/dist/assets/{Library-CzPlerd6.js → Library-BxQvbwVU.js} +1 -1
  178. package/web/dist/assets/{Loops-CqNF_-nS.js → Loops-DAblKkyq.js} +1 -1
  179. package/web/dist/assets/{OperatorHudView-BNr8K5qj.js → OperatorHudView-QtSaSyYm.js} +1 -1
  180. package/web/dist/assets/{Personal-DeDb9e8O.js → Personal-DxSGv638.js} +1 -1
  181. package/web/dist/assets/{Settings-B8MPN_AD.js → Settings-CgTbhvRv.js} +1 -1
  182. package/web/dist/assets/{Tabs-DJzAez4h.js → Tabs-Cf4X1hdz.js} +1 -1
  183. package/web/dist/assets/api-CZ-x0iWG.js +1 -0
  184. package/web/dist/assets/{controls-D4wmg_pl.js → controls-CK7qHA8H.js} +1 -1
  185. package/web/dist/assets/{index-BL3P-9Rg.js → index-B_pTwZra.js} +4 -4
  186. package/web/dist/assets/index-CzfImiYb.css +1 -0
  187. package/web/dist/index.html +3 -3
  188. package/web/dist/assets/Installs-B6nlo-Ly.js +0 -3
  189. package/web/dist/assets/Laws-CuTw_XNf.js +0 -4
  190. package/web/dist/assets/api-DLDVY3K-.js +0 -1
  191. package/web/dist/assets/index-CRWqKxfY.css +0 -1
@@ -44,7 +44,7 @@ Reserve directional slides for hierarchical navigation (list → detail) and ord
44
44
  ## Availability
45
45
 
46
46
  - **Next.js:** Do **not** install `react@canary` — the App Router already bundles React canary internally. `ViewTransition` works out of the box. `npm ls react` may show a stable-looking version; this is expected.
47
- - **Without Next.js:** Install `react@canary react-dom@canary` (`ViewTransition` is not in stable React).
47
+ - **Without Next.js:** Use stable `react` and `react-dom` 19.3 or newer (`ViewTransition` and `addTransitionType` became stable in React 19.3). Earlier stable React versions do not include these APIs.
48
48
  - Browser support: Chromium 125+ (React needs the v2 object form of `startViewTransition`), Firefox 144+, Safari 18.2+. Graceful degradation on unsupported browsers.
49
49
 
50
50
  ---
@@ -363,7 +363,7 @@ For each shared element (`name` prop), note every navigation where a pair forms
363
363
 
364
364
  ## Step 2: Add CSS Recipes
365
365
 
366
- Choose the animation pattern from the audit and this skill's guidance, then copy only the applicable sections from [css-recipes.md](css-recipes.md). Always include reduced motion. Add live-root, persistent-element, backdrop, or floating-element rules only when the audit found those surfaces.
366
+ Choose the animation pattern from the audit and this skill's guidance, then copy only the applicable sections from [css-recipes.md](references/css-recipes.md). Always include reduced motion. Add live-root, persistent-element, backdrop, or floating-element rules only when the audit found those surfaces.
367
367
 
368
368
  Customize timing after the structure works. Keep ordinary crossfades opacity-only; scope blur to a specific shared morph when it is intentional.
369
369
 
@@ -375,7 +375,7 @@ For every persistent element identified in Step 1, add a `viewTransitionName` st
375
375
  <header style={{ viewTransitionName: "site-header" }}>...</header>
376
376
  ```
377
377
 
378
- Then add the [Persistent Element Isolation](css-recipes.md#persistent-element-isolation) CSS (prevents the element from animating during page transitions). If the element uses `backdrop-blur` or `backdrop-filter`, use the [Backdrop-Blur Workaround](css-recipes.md#backdrop-blur-workaround) instead.
378
+ Then add the [Persistent Element Isolation](references/css-recipes.md#persistent-element-isolation) CSS (prevents the element from animating during page transitions). If the element uses `backdrop-blur` or `backdrop-filter`, use the [Backdrop-Blur Workaround](references/css-recipes.md#backdrop-blur-workaround) instead.
379
379
 
380
380
  If a Suspense fallback mirrors a persistent control (e.g., a skeleton search input), give both the real control and the skeleton the same `viewTransitionName` so they morph in place.
381
381
 
@@ -410,7 +410,7 @@ Then wrap each **page component** (not layout) in a type-keyed `<ViewTransition>
410
410
  </ViewTransition>
411
411
  ```
412
412
 
413
- The `nav-forward` and `nav-back` CSS classes from [Directional Navigation](css-recipes.md#directional-navigation) produce horizontal slides. For simpler apps where directional motion isn't needed, a bare `<ViewTransition default="none">` wrapper with `enter="fade-in"` / `exit="fade-out"` works too.
413
+ The `nav-forward` and `nav-back` CSS classes from [Directional Navigation](references/css-recipes.md#directional-navigation) produce horizontal slides. For simpler apps where directional motion isn't needed, a bare `<ViewTransition default="none">` wrapper with `enter="fade-in"` / `exit="fade-out"` works too.
414
414
 
415
415
  Extract this into a reusable component so every page doesn't repeat the verbose type map:
416
416
 
@@ -460,7 +460,7 @@ This example uses `slide-down` / `slide-up` for directional vertical motion. For
460
460
  - Always use `default="none"` on the content `<ViewTransition>` to prevent re-animation on revalidation or unrelated transitions.
461
461
  - Use simple string props (not type maps) on Suspense `<ViewTransition>`s — Suspense resolves fire as separate transitions with no type, so type-keyed props won't match.
462
462
  - A fallback/content `share` pair morphs between snapshots. Use it only when that interpolation is desired and does not distort layout or geometry.
463
- - If the same element appears in **both** the fallback and the content (a title, a heading), it flickers on reveal — an opacity dip. Render it **outside** the `<Suspense>` boundary (or pin it), so it isn't in both. See [Suspense reveal flicker](patterns.md#suspense-reveal-flicker).
463
+ - If the same element appears in **both** the fallback and the content (a title, a heading), it flickers on reveal — an opacity dip. Render it **outside** the `<Suspense>` boundary (or pin it), so it isn't in both. See [Suspense reveal flicker](references/patterns.md#suspense-reveal-flicker).
464
464
 
465
465
  ## Step 6: Add Shared Element Transitions
466
466
 
@@ -478,9 +478,9 @@ For every shared visual element identified in Step 1, add matching named `<ViewT
478
478
  </ViewTransition>
479
479
  ```
480
480
 
481
- The `share="morph"` class uses the [Shared Element Morph](css-recipes.md#shared-element-morph) recipe (controlled duration + motion blur). For a simpler cross-fade, use `share="auto"` (browser default).
481
+ The `share="morph"` class uses the [Shared Element Morph](references/css-recipes.md#shared-element-morph) recipe (controlled duration + motion blur). For a simpler cross-fade, use `share="auto"` (browser default).
482
482
 
483
- When list items contain shared elements, compose both patterns with two nested `<ViewTransition>` layers — an outer keyed VT for list identity and an inner named VT for the cross-route pair. See [Composing Shared Elements with List Identity](../SKILL.md#composing-shared-elements-with-list-identity).
483
+ When list items contain shared elements, compose both patterns with two nested `<ViewTransition>` layers — an outer keyed VT for list identity and an inner named VT for the cross-route pair. See [Composing Shared Elements with List Identity](SKILL.md#composing-shared-elements-with-list-identity).
484
484
 
485
485
  **Rules:**
486
486
  - Names must be globally unique — use prefixes like `photo-${id}`.
@@ -497,9 +497,9 @@ Walk through every row in the navigation map from Step 1 and confirm:
497
497
  - Do persistent elements stay static (not sliding with page content)?
498
498
  - Do Suspense reveals animate independently from directional navigations?
499
499
 
500
- If any path produces no animation or competing animations, use the symptom-driven [troubleshooting guide](troubleshooting.md).
500
+ If any path produces no animation or competing animations, use the symptom-driven [troubleshooting guide](references/troubleshooting.md).
501
501
 
502
- For Next.js-specific implementation steps (`transitionTypes` on `<Link>`, prefetch behavior, and same-route dynamic segments), see [nextjs.md](nextjs.md).
502
+ For Next.js-specific implementation steps (`transitionTypes` on `<Link>`, prefetch behavior, and same-route dynamic segments), see [nextjs.md](references/nextjs.md).
503
503
 
504
504
  ---
505
505
 
@@ -621,10 +621,10 @@ Use `key` when content identity changes (state resets). Omit for cross-fades (ta
621
621
 
622
622
  ## Isolate Elements from Parent Animations
623
623
 
624
- Pull an element out of the animated `root` snapshot by giving it its own `view-transition-name`. **`view-transition-name: none` is a no-op** — it's the CSS default, so the element stays in `root` (a common flicker bug). Use a real, unique name, then neutralize with `<ViewTransition default="none">` (no CSS) or CSS (needed for `z-index`/`display` control — see [css-recipes.md](css-recipes.md#persistent-element-isolation)).
624
+ Pull an element out of the animated `root` snapshot by giving it its own `view-transition-name`. **`view-transition-name: none` is a no-op** — it's the CSS default, so the element stays in `root` (a common flicker bug). Use a real, unique name, then neutralize with `<ViewTransition default="none">` (no CSS) or CSS (needed for `z-index`/`display` control — see [css-recipes.md](references/css-recipes.md#persistent-element-isolation)).
625
625
 
626
626
  - **Persistent chrome** (nav, sidebar, player bar): `<nav style={{ viewTransitionName: 'persistent-nav' }}>` + isolation CSS. `<ViewTransition default="none">` works too, but its auto-name can't take `z-index`/backdrop `display:none` — hand-name when you need those.
627
- - **Floating elements** (popovers, menus): left open, they're captured in `root` and flicker on settle. Real name + isolation ([Floating Element Isolation](css-recipes.md#floating-element-isolation-popovers-menus-tooltips-control-clusters)). A static name is fine if only one is mounted (`unmountOnHide`); native top-layer (`popover`/`<dialog>`) settle-flicker is a browser limit.
627
+ - **Floating elements** (popovers, menus): left open, they're captured in `root` and flicker on settle. Real name + isolation ([Floating Element Isolation](references/css-recipes.md#floating-element-isolation-popovers-menus-tooltips-control-clusters)). A static name is fine if only one is mounted (`unmountOnHide`); native top-layer (`popover`/`<dialog>`) settle-flicker is a browser limit.
628
628
  - **Naming an interactive element has a cost:** named participants are skipped by hit-testing while a transition runs ([csswg#10930](https://github.com/w3c/csswg-drafts/issues/10930)) — clicks and hover fall through to whatever is beneath. Portal named popovers/menus; rendered inline in a clickable row, mid-transition clicks activate the row and read as outside-clicks that close the popover.
629
629
  - **Third-party floating components** (toast libraries, portals you don't render): put the name on an always-mounted wrapper you own — `<div style={{ viewTransitionName: 'toaster' }} className="pointer-events-none fixed inset-0">`. Library containers often unmount when empty, so naming them directly leaves the group unpinned exactly when a toast appears mid-transition. Name a dialog's backdrop separately from its panel so each pins independently.
630
630
 
@@ -641,7 +641,7 @@ Don't put a manual `viewTransitionName` on the root DOM node inside `<ViewTransi
641
641
 
642
642
  ## Sliding Indicator (tabs)
643
643
 
644
- One shared-name indicator rendered under the **active** tab morphs between positions on change (slide the group, disable old/new — see [Sliding Indicator](css-recipes.md#sliding-indicator-tab-underline--segmented-pill)). Render it only under the active tab so exactly one element holds `indicatorName`; use a distinct `indicatorName` per tab strip. Trigger the state change inside `startTransition` so the move animates. Whatever owns `active` drives it — local state here, routing in Next (see [Routing-Driven Tabs](nextjs.md#routing-driven-tabs)).
644
+ One shared-name indicator rendered under the **active** tab morphs between positions on change (slide the group, disable old/new — see [Sliding Indicator](references/css-recipes.md#sliding-indicator-tab-underline--segmented-pill)). Render it only under the active tab so exactly one element holds `indicatorName`; use a distinct `indicatorName` per tab strip. Trigger the state change inside `startTransition` so the move animates. Whatever owns `active` drives it — local state here, routing in Next (see [Routing-Driven Tabs](references/nextjs.md#routing-driven-tabs)).
645
645
 
646
646
  ```tsx
647
647
  import { useState, useTransition, ViewTransition } from 'react';
@@ -668,7 +668,7 @@ export function Tabs({ tabs, indicatorName = 'tab-indicator' }) {
668
668
  }
669
669
  ```
670
670
 
671
- Because the state change is a transition, if the newly-active tab renders suspending content the whole update — indicator **and** `aria-current` — waits for it to commit, and the strip feels dead on click. Give the controls an immediate value with `useOptimistic` (drive `aria-current` from it) so feedback is instant while the content streams. The routing variant ([Routing-Driven Tabs](nextjs.md#routing-driven-tabs)) does exactly this: optimistic `aria-current`, committed `active` for the bar.
671
+ Because the state change is a transition, if the newly-active tab renders suspending content the whole update — indicator **and** `aria-current` — waits for it to commit, and the strip feels dead on click. Give the controls an immediate value with `useOptimistic` (drive `aria-current` from it) so feedback is instant while the content streams. The routing variant ([Routing-Driven Tabs](references/nextjs.md#routing-driven-tabs)) does exactly this: optimistic `aria-current`, committed `active` for the bar.
672
672
 
673
673
  ## Layout Displacement Morph
674
674
 
@@ -719,7 +719,7 @@ function AnimatedCollapse({ open, children }) {
719
719
  </Activity>
720
720
  ```
721
721
 
722
- Only reach for Activity when there's state worth preserving — a stateless element (e.g. the sliding indicator above) gains nothing from it. In Next.js, layout-hosted chrome already persists across navigations without Activity (see [nextjs.md](nextjs.md#layout-level-viewtransition)).
722
+ Only reach for Activity when there's state worth preserving — a stateless element (e.g. the sliding indicator above) gains nothing from it. In Next.js, layout-hosted chrome already persists across navigations without Activity (see [nextjs.md](references/nextjs.md#layout-level-viewtransition)).
723
723
 
724
724
  ## Exclude Elements with `useOptimistic`
725
725
 
@@ -790,9 +790,9 @@ The `types` array (second argument) lets you vary animation based on transition
790
790
 
791
791
  **Scrolling hangs while a transition animates:** the `::view-transition` overlay is `position: fixed` and its snapshots don't scroll — a browser limitation, not fixable in React (skipping snaps to the end). Keep reveal durations short; for scroll-driven UI use gesture transitions (experimental `useSwipeTransition`, if available).
792
792
 
793
- **Open popover flickers when a background transition settles:** it's captured in `root`. Give it a real `view-transition-name` + isolation (not `none`) — see [Isolate Elements from Parent Animations](patterns.md#isolate-elements-from-parent-animations).
793
+ **Open popover flickers when a background transition settles:** it's captured in `root`. Give it a real `view-transition-name` + isolation (not `none`) — see [Isolate Elements from Parent Animations](references/patterns.md#isolate-elements-from-parent-animations).
794
794
 
795
- **Popover closes or goes dead when clicked mid-transition:** named participants are skipped by hit-testing while a transition runs; clicks land on what's beneath and read as outside-clicks. Portal the popover (see [Isolate Elements from Parent Animations](patterns.md#isolate-elements-from-parent-animations)); brief dead clicks during the transition remain — that's the price of the name.
795
+ **Popover closes or goes dead when clicked mid-transition:** named participants are skipped by hit-testing while a transition runs; clicks land on what's beneath and read as outside-clicks. Portal the popover (see [Isolate Elements from Parent Animations](references/patterns.md#isolate-elements-from-parent-animations)); brief dead clicks during the transition remain — that's the price of the name.
796
796
 
797
797
  **Shared morph silently not firing:** `share` resolved to `none`. Either the VT has `default="none"` with no explicit `share` prop, or `share` is type-keyed and the navigation never adds the type — the link needs `transitionTypes` (or `addTransitionType` in the transition).
798
798
 
@@ -800,7 +800,7 @@ The `types` array (second argument) lets you vary animation based on transition
800
800
 
801
801
  **An enter animation runs even though Suspense never showed its fallback:** The content-side VT became the topmost entering subtree during navigation. At that call site, add a host DOM element immediately outside `Suspense`. The host suppresses the nested enter during warm navigation but remains mounted so the VT can enter on a later fallback-to-content reveal. Keep the host outside `Suspense`, not inside the reusable crossfade; do nothing when a direct host already exists.
802
802
 
803
- **Section below a list teleports instead of gliding:** it's outside any activated boundary, its VT has `default="none"` (which disables `update`), or it isn't an immediate sibling of the changing content. See [Layout Displacement Morph](patterns.md#layout-displacement-morph).
803
+ **Section below a list teleports instead of gliding:** it's outside any activated boundary, its VT has `default="none"` (which disables `update`), or it isn't an immediate sibling of the changing content. See [Layout Displacement Morph](references/patterns.md#layout-displacement-morph).
804
804
 
805
805
  **`router.back()` and browser back/forward skip the directional slide:** traversals carry no transition types, so type-keyed maps resolve to `default` — untyped shared-element morphs still apply. Use `router.push()` for typed animations.
806
806
 
@@ -820,7 +820,7 @@ The `types` array (second argument) lets you vary animation based on transition
820
820
 
821
821
  **Hash fragments cause scroll jumps:** Navigate without hash; scroll programmatically after navigation.
822
822
 
823
- **Backdrop-blur flickers:** Use the [Backdrop-Blur Workaround](css-recipes.md#backdrop-blur-workaround).
823
+ **Backdrop-blur flickers:** Use the [Backdrop-Blur Workaround](references/css-recipes.md#backdrop-blur-workaround).
824
824
 
825
825
  **`border-radius` lost during transitions:** Apply `border-radius` directly to the captured element.
826
826
 
@@ -1050,7 +1050,7 @@ The `::view-transition` overlay captures all pointer events. React shrinks it to
1050
1050
  }
1051
1051
  ```
1052
1052
 
1053
- Trade-offs: clicks can hit live elements under still-moving snapshots, and it only helps **unnamed** content — named participants are skipped by hit-testing for the transition's duration, no CSS override ([csswg#10930](https://github.com/w3c/csswg-drafts/issues/10930)). Weigh that before naming interactive elements; portal named popovers (see [Isolate Elements from Parent Animations](patterns.md#isolate-elements-from-parent-animations)).
1053
+ Trade-offs: clicks can hit live elements under still-moving snapshots, and it only helps **unnamed** content — named participants are skipped by hit-testing for the transition's duration, no CSS override ([csswg#10930](https://github.com/w3c/csswg-drafts/issues/10930)). Weigh that before naming interactive elements; portal named popovers (see [Isolate Elements from Parent Animations](references/patterns.md#isolate-elements-from-parent-animations)).
1054
1054
 
1055
1055
  ---
1056
1056
 
@@ -1155,13 +1155,13 @@ Read the current [Next.js View Transitions guide](https://nextjs.org/docs/app/gu
1155
1155
 
1156
1156
  Because every link click is a transition, any VT with `default="auto"` fires on **every** navigation — use `default="none"` to prevent competing animations.
1157
1157
 
1158
- For unexpected or broken animation behavior, see [troubleshooting.md](troubleshooting.md).
1158
+ For unexpected or broken animation behavior, see [troubleshooting.md](references/troubleshooting.md).
1159
1159
 
1160
1160
  ---
1161
1161
 
1162
1162
  ## Next.js Implementation Additions
1163
1163
 
1164
- When following [implementation.md](implementation.md), apply these additions:
1164
+ When following [implementation.md](references/implementation.md), apply these additions:
1165
1165
 
1166
1166
  **Step 4:** Use `transitionTypes` on `<Link>` — see [The `transitionTypes` Prop](#the-transitiontypes-prop-on-nextlink). If the animation depends on dynamic destination content, also see [When Content Must Be Ready](#when-content-must-be-ready).
1167
1167
 
@@ -1171,11 +1171,11 @@ When following [implementation.md](implementation.md), apply these additions:
1171
1171
 
1172
1172
  ## Layout-Level ViewTransition
1173
1173
 
1174
- **Do NOT add a layout-level VT wrapping `{children}` if pages have their own VTs.** A nested VT skips its own enter/exit only when it mounts or unmounts *as one unit* with a parent VT, which is exactly what a layout VT wrapping `{children}` causes — page-level enter/exit will silently not work. Remove the layout VT entirely. Nesting is otherwise fine and sometimes required: a child VT inside a *persistent* parent VT fires enter/exit normally, and two nested boundaries are the intended shape for [shared elements inside list items](../SKILL.md#composing-shared-elements-with-list-identity).
1174
+ **Do NOT add a layout-level VT wrapping `{children}` if pages have their own VTs.** A nested VT skips its own enter/exit only when it mounts or unmounts *as one unit* with a parent VT, which is exactly what a layout VT wrapping `{children}` causes — page-level enter/exit will silently not work. Remove the layout VT entirely. Nesting is otherwise fine and sometimes required: a child VT inside a *persistent* parent VT fires enter/exit normally, and two nested boundaries are the intended shape for [shared elements inside list items](SKILL.md#composing-shared-elements-with-list-identity).
1175
1175
 
1176
1176
  A bare `<ViewTransition>` in layout works only if pages have **no** VTs of their own.
1177
1177
 
1178
- **Layouts persist across navigations** — `enter`/`exit` only fire on initial mount, not on route changes. Don't use type-keyed maps in layouts. Because layouts persist, chrome hosted in one (nav, sidebar, player) keeps its state across navigations for free — no `Activity` needed. Reserve `Activity` for in-page show/hide (see [Composing with Activity](patterns.md#composing-with-activity)).
1178
+ **Layouts persist across navigations** — `enter`/`exit` only fire on initial mount, not on route changes. Don't use type-keyed maps in layouts. Because layouts persist, chrome hosted in one (nav, sidebar, player) keeps its state across navigations for free — no `Activity` needed. Reserve `Activity` for in-page show/hide (see [Composing with Activity](references/patterns.md#composing-with-activity)).
1179
1179
 
1180
1180
  ---
1181
1181
 
@@ -1260,15 +1260,15 @@ function SortControl() {
1260
1260
  }
1261
1261
  ```
1262
1262
 
1263
- List items wrapped in `<ViewTransition key={item.id}>` will animate reorder. This is the server-component alternative to the client-side [Searchable Grid](patterns.md#searchable-grid-with-usedeferredvalue) pattern.
1263
+ List items wrapped in `<ViewTransition key={item.id}>` will animate reorder. This is the server-component alternative to the client-side [Searchable Grid](references/patterns.md#searchable-grid-with-usedeferredvalue) pattern.
1264
1264
 
1265
- For immediate control feedback while the route commits, use `useOptimistic` for the button state but keep the animated list tied to the committed sort value. See [Exclude Elements with `useOptimistic`](patterns.md#exclude-elements-with-useoptimistic).
1265
+ For immediate control feedback while the route commits, use `useOptimistic` for the button state but keep the animated list tied to the committed sort value. See [Exclude Elements with `useOptimistic`](references/patterns.md#exclude-elements-with-useoptimistic).
1266
1266
 
1267
1267
  ---
1268
1268
 
1269
1269
  ## Routing-Driven Tabs
1270
1270
 
1271
- The generalized sliding indicator ([Sliding Indicator](patterns.md#sliding-indicator-tabs)) driven by navigation instead of local state: tabs are `<Link>`s, `active` comes from the URL (a server prop), and `useOptimistic` slides the indicator instantly while the route commits. Key the mounted indicator to committed `active` so the bar lands where navigation actually settles.
1271
+ The generalized sliding indicator ([Sliding Indicator](references/patterns.md#sliding-indicator-tabs)) driven by navigation instead of local state: tabs are `<Link>`s, `active` comes from the URL (a server prop), and `useOptimistic` slides the indicator instantly while the route commits. Key the mounted indicator to committed `active` so the bar lands where navigation actually settles.
1272
1272
 
1273
1273
  ```tsx
1274
1274
  'use client';
@@ -44,7 +44,7 @@ Reserve directional slides for hierarchical navigation (list → detail) and ord
44
44
  ## Availability
45
45
 
46
46
  - **Next.js:** Do **not** install `react@canary` — the App Router already bundles React canary internally. `ViewTransition` works out of the box. `npm ls react` may show a stable-looking version; this is expected.
47
- - **Without Next.js:** Install `react@canary react-dom@canary` (`ViewTransition` is not in stable React).
47
+ - **Without Next.js:** Use stable `react` and `react-dom` 19.3 or newer (`ViewTransition` and `addTransitionType` became stable in React 19.3). Earlier stable React versions do not include these APIs.
48
48
  - Browser support: Chromium 125+ (React needs the v2 object form of `startViewTransition`), Firefox 144+, Safari 18.2+. Graceful degradation on unsupported browsers.
49
49
 
50
50
  ---
@@ -1,6 +1,6 @@
1
1
  # Vendored skill — react-view-transitions
2
2
 
3
- This folder is a third-party skill vendored **verbatim** (the frontmatter lines below aside) into Geneseed, not a
3
+ This folder is a third-party skill vendored into Geneseed with the deviations listed below, not a
4
4
  Geneseed-authored skill. It rides along in the rendered bundle and is exempt from
5
5
  Geneseed's authoring gates (token, dead-link, hermeticity, skill counts) — it is
6
6
  listed in the generator's `VENDORED_SKILL_DIRS`.
@@ -10,14 +10,16 @@ listed in the generator's `VENDORED_SKILL_DIRS`.
10
10
  - **Credit:** {{CREDIT:react-view-transitions:skills/react-view-transitions}}
11
11
 
12
12
  The licence is MIT, declared in the upstream repo README's `## License`. Upstream ships no LICENSE
13
- file (neither at the pinned commit nor on `main`; re-checked at 063bee94), so there is no license text to carry here
13
+ file (neither at the pinned commit nor on `main`; re-checked at 1a2c79d4), so there is no license text to carry here
14
14
  and the entry's `licenseFile` is null; the README's declaration is the whole grant.
15
15
 
16
16
  The skill follows the [Agent Skills](https://agentskills.io/) format (`SKILL.md` +
17
17
  `references/`). Its internal links point at the upstream project's own files; do not
18
- "fix" them to Geneseed paths — that is why the folder is gate-exempt. To update,
18
+ "fix" them to Geneseed paths — that is why the folder is gate-exempt. Deviation 4 below only
19
+ repoints links that miss a sibling file of this folder. To update,
19
20
  re-copy the upstream folder (new or removed files included, e.g. `references/troubleshooting.md`), re-apply the deviations below, and bump the entry's `commit`
20
- in `src/upstreams.json`.
21
+ in `src/upstreams.json`. Afterwards every relative link in every `.md` here must resolve to a
22
+ file inside this folder.
21
23
 
22
24
  **Deviation 1:** upstream's frontmatter says `name: vercel-react-view-transitions`;
23
25
  here it is `name: react-view-transitions`. The Agent Skills format requires the name to
@@ -29,6 +31,13 @@ here it is `` `ViewTransition` ``. The Agent Skills spec forbids XML tags in a d
29
31
  `checkBuild`'s description arm reports one for every first-party skill — the tag would be the
30
32
  only one left in any install's catalogue.
31
33
 
34
+ **Deviation 4:** upstream's `AGENTS.md` is compiled from `SKILL.md` and the `references/` files,
35
+ and keeps the references' sibling-relative links, which miss at the folder root. In `AGENTS.md`
36
+ only, `](<name>.md` becomes `](references/<name>.md` for `<name>` in `css-recipes`,
37
+ `implementation`, `nextjs`, `patterns` and `troubleshooting` (any `#anchor` kept), and
38
+ `](../SKILL.md` becomes `](SKILL.md`. Links already written `](references/…` are left alone.
39
+ The other files keep upstream's links byte for byte: they already resolve.
40
+
32
41
  **Deliberately not copied:** upstream's `README.md` (the repo-facing readme: install
33
42
  command and folder tree, nothing an agent reads). `AGENTS.md`, upstream's compiled
34
43
  all-in-one copy, IS kept — `SKILL.md`'s closing section points the agent at it.
@@ -36,3 +45,9 @@ all-in-one copy, IS kept — `SKILL.md`'s closing section points the agent at it
36
45
  `SKILL.md`'s frontmatter also carries `disable-model-invocation: true`, which upstream lacks: the
37
46
  skill is user-only (`/react-view-transitions`), so its description stays out of the model's always-on catalogue —
38
47
  it is the largest skill and serves one stack. Re-apply it on update.
48
+
49
+ **Deviation 3, at emit time:** the emit replaces `SKILL.md`'s `description:` with the skill's
50
+ line in `src/skill-descriptions.json` (at most 80 characters: the host's skill listing has a
51
+ budget) and keeps the description written here as the first body line, a blockquote
52
+ (`vendoredWithCatalogueLine`, `js/hosts/native.mjs`). This file is not changed; nothing to
53
+ re-apply on update.
@@ -2,7 +2,8 @@
2
2
 
3
3
  > {{DESC_RELEASE}}
4
4
 
5
- **Trigger:** cutting a release — a version bump, a changelog entry, and a tag.
5
+ **Trigger:** the user asks to cut or publish a release — a version bump, a changelog entry,
6
+ and a tag. Finished work is not that ask: never start a release unasked.
6
7
 
7
8
  ## Procedure
8
9
  1. Decide the version from the changes since the last tag, following the project's
@@ -18,9 +19,13 @@
18
19
  4. Commit the version bump and changelog as one focused commit on a release branch,
19
20
  through the [commit {{SKILL}}](commit.md) ({{LAW:one-intent-one-act}}), and land it on
20
21
  the main branch through a pull request with green checks ({{DOCTRINE:consent-before-push}}).
22
+ Land that pull request by arming the forge's auto-merge (`gh pr merge --squash --auto`);
23
+ never `--admin`, never a direct push to main.
21
24
  5. Tag the release (annotated, matching the version). Tagging and publishing are
22
25
  **outward-facing** and need the user's explicit acceptance ({{LAW:deletion-is-deliberate}}).
23
- 6. With that acceptance, push the tag; trigger or verify the publish/release pipeline.
26
+ 6. With that acceptance, push the tag; trigger or verify the publish/release pipeline. Wait
27
+ on it with its own watch (`gh run watch --exit-status`) or the host's monitor, never a
28
+ sleep-then-poll loop.
24
29
 
25
30
  ## Done when
26
31
  - Version, changelog, and tag all name the same number, and the release is pushed
@@ -29,7 +29,8 @@ that is gone was decided.
29
29
  - A `Rule from` block whose rule the shared file now holds word for word needs no decision.
30
30
  Skip it: the next fold of that host clears it.
31
31
  3. **Decide one item at a time.** Show the item, then ask. "Later" leaves the block and the row as
32
- they are. For each decision, write in this order: the target file, the ledger row, the draft.
32
+ they are. Approval names the items or says approve; a remark about where rules live is not
33
+ approval, so ask again and write nothing. For each decision, write in this order: the target file, the ledger row, the draft.
33
34
  A stop between the writes leaves the rule in force, and step 2 or the next fold finishes it.
34
35
 
35
36
  ### A `Rule from <host>` block
@@ -5,7 +5,7 @@
5
5
  {{CREDIT:mattpocock-skills:skills/productivity/writing-for-agents/SKILL.md}}
6
6
 
7
7
  **Trigger:** a task has repeated and no {{SKILL}} covers it; a {{SKILL}}'s
8
- notes in `{{PATH_NOTES}}/skill-notes/` hold a correction worth making; the user says "make this a
8
+ notes in `{{PATH_NOTES}}/skill-notes/` or `{{PATH_PROJECT_NOTES}}/skill-notes/` hold a correction worth making; the user says "make this a
9
9
  skill", "write a skill for…", "fix the trigger of…"; or two {{SKILLS}} keep
10
10
  disambiguating against each other and should merge. Meta by nature: it edits the
11
11
  apparatus, so every step ends in the user's assent ({{LAW:one-intent-one-act}}, {{LAW:deletion-is-deliberate}}).
@@ -38,7 +38,9 @@ apparatus, so every step ends in the user's assent ({{LAW:one-intent-one-act}},
38
38
  says *when*, in the words a user would actually say and the situations the model
39
39
  would actually meet — the emitted `description:` is purpose + trigger, and it is
40
40
  the only text the host matches a task against. It is loaded every turn: one phrase per
41
- distinct case it catches, never synonyms of one case. Then the numbered procedure (each
41
+ distinct case it catches, never synonyms of one case. In the Geneseed source repo the
42
+ description is instead the skill's line in `src/skill-descriptions.json`: purpose and
43
+ trigger in at most 80 characters, because the host drops long descriptions first. Then the numbered procedure (each
42
44
  step an action with a verification), and a **Done when** that a stranger could
43
45
  check. Then cut every sentence the model would obey untold, and every restatement of
44
46
  what a config file or `--help` already says. Keep it to one coherent domain; a "Requires:" line only for a hard external
@@ -58,7 +60,7 @@ apparatus, so every step ends in the user's assent ({{LAW:one-intent-one-act}},
58
60
  `{{DIR_SKILLS}}/`, one row in AGENT.md §4's table, then `geneseed doctor` — it fails
59
61
  if the table and the files disagree. In the *Geneseed source repo* the cost is the
60
62
  full satellite set (`docs/extending.md` §3): the file, the §4 row, `DESC_<NAME>` in
61
- every theme, `SKILL_CLASS`, a `registry.json` row, the README enumeration, then
63
+ every theme, its `src/skill-descriptions.json` line, `SKILL_CLASS`, a `registry.json` row, the README enumeration, then
62
64
  `doctor --all` and the suites. A skill that bundles a script or several files is a
63
65
  folder skill (`<name>/SKILL.md` + `VENDOR.md`), listed in `VENDORED_SKILL_DIRS`.
64
66
  Text adapted from outside gets a `src/upstreams.json` entry and a `CREDIT` token (docs/extending.md §3, in the Geneseed source repo).
@@ -78,7 +78,7 @@ spring:
78
78
  The `CircuitBreaker` filter needs a Spring Cloud CircuitBreaker starter (for example the reactor-Resilience4j one) on the classpath. Gateway is WebFlux; do not put it in the same module as a Spring MVC service.
79
79
 
80
80
  ## Observability
81
- - Health: `/actuator/health/liveness` and `/actuator/health/readiness` are on by default (`management.endpoint.health.probes.enabled=false` disables them); point the Kubernetes probes at those. Expose only what you need (`management.endpoints.web.exposure.include`), and protect the rest.
81
+ - Health: `/actuator/health/liveness` and `/actuator/health/readiness` are on by default (`management.endpoint.health.probes.enabled=false` disables them); point the Kubernetes probes at those, and permit `/actuator/health/**` in the security chain. Expose only what you need (`management.endpoints.web.exposure.include`), and protect the rest. `management.endpoint.health.show-components: always` with `show-details: when-authorized` tells an anonymous caller which component is down without leaking hosts or versions.
82
82
  - Metrics: add `micrometer-registry-prometheus` and expose `prometheus`.
83
83
  - Traces over OTLP: add `org.springframework.boot:spring-boot-starter-opentelemetry` and configure `management.opentelemetry.tracing.export.otlp.endpoint` (the old `management.otlp.tracing.*` keys are not the Boot 4 names). Boot samples 10% by default; set `management.tracing.sampling.probability: 1.0` only where the volume allows.
84
84
  - Custom spans: `Observation.createNotStarted("order.process", registry).lowCardinalityKeyValue(...).observe(() -> ...)` (Micrometer Observation, unchanged by Boot 4 as far as the docs show).
@@ -99,5 +99,23 @@ Add a short Kubernetes `preStop` sleep so the endpoint leaves the load balancer
99
99
  - GraalVM native: fast start and low memory, at the cost of build time and reflection hints; adopt it deliberately, not by default.
100
100
  - Use whatever CI the project already has; do not introduce a new one.
101
101
 
102
+ ## Local dependencies
103
+ Give each Docker Compose dependency a healthcheck, and make the services that need it wait with `depends_on: { <dep>: { condition: service_healthy } }`; `docker compose up -d --wait` then also returns only once everything is usable. Write a shell check as `["CMD-SHELL", "<script>"]`, never `["CMD", "bash", "-c", "<script>"]`: Podman splits that array on spaces and reports the service healthy before it starts.
104
+
102
105
  ## Kubernetes manifest essentials
103
106
  Liveness and readiness probes on the actuator paths, a startup probe for slow starts, resource requests and limits, `runAsNonRoot`, config from ConfigMap and Secret. For TLS, let the platform terminate it (Ingress plus cert-manager) or mount the certificate and use an SSL bundle ([spring-boot/security.md](security.md)).
107
+
108
+ No committed manifest names a cluster, host, registry, namespace or secret value: no `namespace:` (it comes from `-n`), the image is a bare name (Skaffold `--default-repo`), Secrets are referenced by name and created out of band.
109
+
110
+ Dependencies deployed in the same namespace get the same three probes, or a redeploy routes traffic to a pod that is not ready:
111
+ - PostgreSQL: `pg_isready -h 127.0.0.1` (over TCP: during the first `initdb` the server listens only on its socket), a fast startup probe; data on a PVC with `strategy: Recreate`, or every redeploy starts empty.
112
+ - Keycloak: `KC_HEALTH_ENABLED=true`, then `/health/started`, `/health/ready`, `/health/live` on management port 9000, not 8080.
113
+
114
+ Prove a new probe can fail: watch the service start and see Warning events before it is up (`kubectl get events --field-selector type=Warning`), with no restarts in the pods that depend on it.
115
+
116
+ ## One set of manifests for several platforms
117
+ When one service deploys to a local cluster, plain Kubernetes and OpenShift, use Kustomize overlays (deployed with Skaffold or `kubectl -k`):
118
+ - `deploy/base` is plain Kubernetes, valid anywhere; `deploy/overlays/<platform>` adds only what that platform needs (Routes on OpenShift, Ingresses elsewhere); environment overlays with hosts and TLS stay out of git.
119
+ - Stay within the kustomize 3.8 features that Skaffold, `kubectl -k` and `oc -k` all support (`resources`, `patches`, generators); no `labels`, `replacements` or `components`.
120
+ - Selectors stay `app: <name>`: a selector cannot change after the first deploy.
121
+ - CI runs `kustomize build` on every overlay, so a broken patch fails the build, not the deploy.
@@ -41,8 +41,9 @@ log.error("Payment failed for order {}", order.id(), e); //
41
41
  ```
42
42
  - Placeholders, never string concatenation. Guard only genuinely expensive arguments with `isDebugEnabled()`.
43
43
  - Pass the exception as the final argument; do not log `e.getMessage()` alone.
44
- - Log an exception once, where it is handled, not at every layer it passes through.
45
- - Never log secrets, tokens, passwords or personal data; log identifiers.
44
+ - Log an exception once, where the flow ends (the exception handler, listener or job), not at every layer it passes through: a lower layer wraps it with context and rethrows, without logging. Expected business errors (404, validation) are `WARN` or `DEBUG` without a stack trace; only unexpected failures are `ERROR` with the throwable.
45
+ - For fields a log platform should filter on, use the SLF4J 2 fluent API: `log.atError().addKeyValue("orderId", id).setCause(e).log("Order processing failed")`. Boot's structured formats write each pair as a JSON field.
46
+ - Never log secrets, tokens, passwords, `Authorization` or `Cookie` headers, card data or personal data; log identifiers. A record prints every component in `toString()`: log its id, not the record, when it carries personal data. No full request or response bodies in production.
46
47
  - Lombok's `@Slf4j` is fine where the project uses Lombok; otherwise declare the logger as above.
47
48
 
48
49
  | Level | Meaning |
@@ -76,7 +77,7 @@ class MdcFilter extends OncePerRequestFilter {
76
77
  }
77
78
  ```
78
79
 
79
- MDC is thread-local, so it does not follow work handed to another thread (virtual or platform). For executor tasks, copy the context with a `TaskDecorator` (`MDC.getCopyOfContextMap()` before, `MDC.setContextMap(...)` inside the task, `MDC.clear()` in `finally`) and register it on the executor you use; check that Boot applies it to your executor in the version you run.
80
+ MDC is thread-local, so it does not follow work handed to another thread (virtual or platform). For executor tasks, copy the context with a `TaskDecorator` (`MDC.getCopyOfContextMap()` before, `MDC.setContextMap(...)` inside the task, `MDC.clear()` in `finally`) and register it on the executor you use; check that Boot applies it to your executor in the version you run. `CompletableFuture.supplyAsync(...)` without an executor runs on the common pool and loses MDC: always pass the Spring executor.
80
81
 
81
82
  Useful fields for incident analysis: `requestId`, user or tenant id, and a duration on slow-path logs. Keep them to identifiers, not payloads.
82
83
 
@@ -86,4 +87,5 @@ Useful fields for incident analysis: `requestId`, user or tenant id, and a durat
86
87
  | JSON console | `logging.structured.format.console: logstash` |
87
88
  | Per-package level | `logging.level.com.example.orders: DEBUG` |
88
89
  | Correlate a request | MDC `requestId` set in a filter |
90
+ | One event's fields as JSON | `log.atInfo().addKeyValue("k", v).log("msg")` |
89
91
  | Follow one request in JSON logs | `jq 'select(.requestId == "abc")' app.log` (field name depends on MDC key and format) |
@@ -36,6 +36,8 @@ class UserController {
36
36
 
37
37
  Version the path (`/api/v1`). Use GET for reads, POST/PUT/PATCH/DELETE for state changes; never change state on GET.
38
38
 
39
+ Paged lists return Spring Data's `org.springframework.data.web.PagedModel` (`{content, page}`; not the HATEOAS class of the same name): the JSON of `Page`/`PageImpl` is not a stable format and Spring Data warns when it serializes one. To get that shape for every `Page`, set `spring.data.web.pageable.serialization-mode: via-dto`, not `@EnableSpringDataWebSupport(pageSerializationMode = VIA_DTO)` on the application class: `@WebMvcTest` then registers the web support twice and fails. Cap the page size (`spring.data.web.pageable.max-page-size: 100`).
40
+
39
41
  ## DTOs and validation
40
42
  Records for request and response. Constraints sit on the record components (`jakarta.validation.constraints`); `@Valid` on the controller parameter triggers them. Put the entity-to-DTO mapping in a static factory or a mapper, not in the controller.
41
43
 
@@ -46,7 +48,7 @@ public record UserCreateRequest(
46
48
  @Min(18) Integer age) {}
47
49
  ```
48
50
 
49
- A custom constraint is an annotation with `@Constraint(validatedBy = ...)` plus a `ConstraintValidator`; the validator may be a Spring bean and inject a repository. A uniqueness check in a validator is advisory only; the database constraint is the truth, so also handle `DataIntegrityViolationException` (409).
51
+ A custom constraint is an annotation with `@Constraint(validatedBy = ...)` plus a `ConstraintValidator`; the validator may be a Spring bean and inject a repository. A rule across two fields (a date range) is a class-level constraint that reports on one field (`context.buildConstraintViolationWithTemplate(...).addPropertyNode("to")`), so a client can show it next to the input. A uniqueness check in a validator is advisory only; the database constraint is the truth, so also handle `DataIntegrityViolationException` (409).
50
52
 
51
53
  ## Errors: Problem Details
52
54
  Enable RFC 9457 responses for Spring's own exceptions:
@@ -73,10 +75,31 @@ class ApiExceptionHandler extends ResponseEntityExceptionHandler {
73
75
  ProblemDetail conflict(DataIntegrityViolationException ex) {
74
76
  return ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT, "Resource already exists");
75
77
  }
78
+
79
+ @ExceptionHandler(ObjectOptimisticLockingFailureException.class)
80
+ ProblemDetail staleVersion(ObjectOptimisticLockingFailureException ex) {
81
+ return ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT, "Record was changed by someone else; reload and retry");
82
+ }
83
+
84
+ @ExceptionHandler(PropertyReferenceException.class) // ?sort=unknownProperty
85
+ ProblemDetail badSort(PropertyReferenceException ex) {
86
+ return ProblemDetail.forStatusAndDetail(HttpStatus.BAD_REQUEST, "Unknown sort property: " + ex.getPropertyName());
87
+ }
88
+
89
+ @ExceptionHandler({AccessDeniedException.class, AuthenticationException.class})
90
+ void security(RuntimeException ex) {
91
+ throw ex; // back to Spring Security: 403/401, not 500
92
+ }
93
+
94
+ @ExceptionHandler(Exception.class)
95
+ ProblemDetail unexpected(Exception ex) {
96
+ logger.error("Unexpected error", ex); // logged here, never returned
97
+ return ProblemDetail.forStatusAndDetail(HttpStatus.INTERNAL_SERVER_ERROR, "Unexpected server error");
98
+ }
76
99
  }
77
100
  ```
78
101
 
79
- A domain exception can carry its own problem by extending `ErrorResponseException`. Never put stack traces or SQL text in `detail`; log the exception server-side and return a generic message for the catch-all 500.
102
+ A domain exception can carry its own problem by extending `ErrorResponseException`; a plain `ResponseStatusException(NOT_FOUND, ...)` also renders as Problem Details with no extra handler. Never put stack traces, SQL text or an unexpected exception's message in `detail`. A catch-all on `Exception` also catches method-security failures, so rethrow `AccessDeniedException` and `AuthenticationException` before it, as above. To answer a duplicate with the field at fault, read `getConstraintName()` from the cause, `org.hibernate.exception.ConstraintViolationException`, and name constraints explicitly in migrations so that name is stable. Deleting a record that others still reference answers 409; it never cascades.
80
103
 
81
104
  ## Outbound HTTP
82
105
  Blocking calls use `RestClient`; build it from the injected `RestClient.Builder` so Boot's customizers (timeouts, SSL, observability) apply.
@@ -109,4 +132,6 @@ Prefer one bean over scattered annotations. With Spring Security on the classpat
109
132
  | Bad input | `@Valid` -> 400 Problem Details |
110
133
  | Missing resource | 404 via your exception handler |
111
134
  | Duplicate | 409 from the DB constraint |
135
+ | Stale update | 409 from `ObjectOptimisticLockingFailureException` |
136
+ | Unknown `sort` property | 400 from `PropertyReferenceException` |
112
137
  | Slow upstream | `spring.http.clients.connect-timeout` / `read-timeout` |
@@ -21,7 +21,9 @@ Target stack: Spring Boot 4 / Spring Framework 7 / Spring Security 7 / Hibernate
21
21
  - DTOs are records. JPA entities are not records. Never return an entity from a controller.
22
22
  - `@Valid` on every request body; `@Transactional(readOnly = true)` on read services, `@Transactional` on mutating methods.
23
23
  - Typed config: `@ConfigurationProperties` records instead of scattered `@Value`.
24
- - Errors: one `@RestControllerAdvice`, Problem Details responses.
24
+ - Errors: one `@RestControllerAdvice`, Problem Details responses; the catch-all 500 never returns the exception message.
25
+ - List endpoints return `PagedModel`, never `Page`/`PageImpl` (their JSON is not a stable format).
26
+ - Relational database: the migration tool owns the schema, Hibernate only validates it (the spring-data-jpa skill).
25
27
  - Blocking outbound HTTP: `RestClient`, or an `@HttpExchange` interface. `WebClient` only for reactive or streaming code. Do not mix blocking and reactive in one call path.
26
28
  - Jakarta namespaces only (`jakarta.persistence`, `jakarta.validation`, `jakarta.servlet`).
27
29
  - Secrets from the environment or mounted files, never committed config.
@@ -52,6 +54,6 @@ Removed or renamed in Boot 4 (do not write them): `@MockBean` and `@SpyBean`, `C
52
54
  - **Logging and structured logs** -> read [spring-boot/logging.md](spring-boot/logging.md) and follow it.
53
55
 
54
56
  ## Done when
55
- - The project's build and tests pass, read from real output; no deprecated Boot 2/3 idiom was introduced; every new endpoint validates input and has a negative test.
57
+ - The project's clean build and tests pass, read from real output (`./mvnw clean verify`: classes the IDE compiled into `target` can hide `javac` errors), with the integration tests run, not skipped (the spring-testing skill); no deprecated Boot 2/3 idiom was introduced; every new endpoint validates input and has a negative test.
56
58
 
57
59
  <!-- INCLUDE: skills/_self-improvement.md -->
@@ -17,7 +17,9 @@ Target stack: Spring Boot 4, Hibernate 7, Jakarta Persistence (`jakarta.persiste
17
17
  | N+1 SELECTs | `@EntityGraph(attributePaths = "books")` or `JOIN FETCH`; as a mitigation only, `hibernate.default_batch_fetch_size` (batch fetching mitigates N+1, it does not solve it) |
18
18
  | `LazyInitializationException` | fetch what the use case needs inside the transaction (graph / `JOIN FETCH`) or return a DTO; do not flip associations to `EAGER` |
19
19
  | Slow list endpoints | `Pageable` (`Slice` when no total is needed), interface or record projections, indexes |
20
- | Lost updates | `@Version` (optimistic); `@Lock(LockModeType.PESSIMISTIC_WRITE)` only for hot rows |
20
+ | Lost updates | `@Version` (optimistic); `@Lock(LockModeType.PESSIMISTIC_WRITE)` only for hot rows; across HTTP requests compare the client's version explicitly (see Transactions) |
21
+ | 500 after a successful update of a relation | `LazyInitializationException` on a proxy: make the write `@Transactional` and map the response inside it |
22
+ | Entity lost from a `HashSet` after persist | `equals`/`hashCode` on a generated id: use a natural key, or a constant `hashCode` |
21
23
  | Slow read-only service | `@Transactional(readOnly = true)` on the class, override on writes |
22
24
  | Transaction ignored | self-invocation bypasses the proxy: call through another bean |
23
25
 
@@ -39,7 +41,9 @@ public class Author {
39
41
  - Every to-one and to-many is `LAZY`; decide fetching per query, not on the mapping.
40
42
  - `@SoftDelete(strategy = ...)` takes `ACTIVE`, `DELETED`, or `TIMESTAMP`; the default stores a deleted flag.
41
43
  - `GenerationType.UUID` generates the id in Java; `IDENTITY` and `SEQUENCE` need the database.
42
- - Equality on entities: id-based with a stable hash, or business key. Never include lazy collections in `equals`/`toString`.
44
+ - Equality on entities: a business key (`@NaturalId`), or id-based `equals` with a constant `hashCode` (for example `return 31;`) so the hash does not change when the id is assigned on persist. Use `instanceof`, not `getClass()`, in `equals`, and read the other side through `getId()`, not the field, so Hibernate proxies compare equal. Never include lazy collections in `equals`/`toString`.
45
+ - Bidirectional associations: helper methods (`addBook`/`removeBook`) keep both sides in sync. No cascade on the `@ManyToOne` side; `@ManyToMany` is a `Set` (a `List` deletes and re-inserts the whole join table) with `PERSIST`/`MERGE` only, never `REMOVE` or `ALL`. A link that carries data is its own entity.
46
+ - Audit timestamps are `Instant`, not `LocalDateTime`.
43
47
 
44
48
  ## Repositories and projections
45
49
 
@@ -58,18 +62,28 @@ public interface AuthorRepository extends JpaRepository<Author, UUID> {
58
62
  ```
59
63
 
60
64
  - Interface projections are built from tuple queries; DTO records need an all-args constructor and no column aliases in `@Query` JPQL.
61
- - Bulk `@Modifying` queries bypass the persistence context: `clearAutomatically = true` or reload.
65
+ - Bulk `@Modifying` queries bypass the persistence context, callbacks, cascades and `@Version`: `flushAutomatically = true` writes pending changes first, `clearAutomatically = true` detaches stale entities after; increment the version in the query (`set a.version = a.version + 1`) when concurrent writers rely on it.
66
+ - A `LIKE` built from user input escapes `%`, `_` and `\` (with `cb.like(expr, pattern, '\\')`), or `q=%` matches everything.
62
67
  - Return DTOs from the web layer, never entities.
63
68
 
64
69
  ## Transactions and open-in-view
65
70
 
66
71
  - Put `@Transactional` on service methods, not repositories or controllers.
67
72
  - `spring.jpa.open-in-view` defaults to `true` in a web app (the EntityManager stays open through view rendering). Set it to `false` and fetch explicitly; it hides N+1 otherwise.
73
+ - With open-in-view off, a write that loads outside a transaction and then calls `save` merges a detached entity: a newly set `@ManyToOne` becomes an uninitialized proxy, and mapping the response throws after the commit. Load, change, save and map in one `@Transactional` method; read paths fetch the relation with `@EntityGraph`.
74
+ - Optimistic locking over HTTP: the client sends the `version` it read and the service compares it, then throws `ObjectOptimisticLockingFailureException` (409). Setting the version on a managed entity does not work, as Hibernate ignores it. Do not wrap `save()` in a `try/catch` inside the transaction: the `UPDATE` runs at flush or commit, after the block. Return the new version with `saveAndFlush`.
68
75
  - Detect N+1: `spring.jpa.show-sql=true` is enough for a quick look; assert query counts in a `@DataJpaTest` for regressions.
69
76
 
70
77
  ## Migrations
71
78
 
72
- Schema is owned by migrations, not `ddl-auto`: `spring.jpa.hibernate.ddl-auto=validate` (or `none`) with Flyway or Liquibase, whichever the project already uses. In Boot 4 add the starter (`spring-boot-starter-flyway`), not just the Flyway core jar, or auto-configuration does not apply; Postgres and MySQL also need `flyway-database-postgresql` / `flyway-mysql`. Migration files are immutable once merged; add a new one.
79
+ Schema is owned by migrations, not `ddl-auto`: `spring.jpa.hibernate.ddl-auto=validate` (or `none`) with Flyway or Liquibase, whichever the project already uses. In Boot 4 add the starter (`spring-boot-starter-flyway`), not just the Flyway core jar, or auto-configuration does not apply; Postgres and MySQL also need `flyway-database-postgresql` / `flyway-mysql`. No persistence or NoSQL only: no migration tool at all.
80
+
81
+ - Migration files are immutable once applied; every change is a new `V<n>__<description>.sql`, shipped in the same commit as the entity change.
82
+ - Numeric database-generated ids are standard identity columns (`GENERATED BY DEFAULT AS IDENTITY`, `AUTO_INCREMENT` on MySQL), not `SERIAL`/`BIGSERIAL`.
83
+ - Name constraints and indexes (`pk_`, `uk_`, `fk_`, `ck_`, `ix_`) and index every foreign key column; the exception handler maps a unique violation by that name.
84
+ - A new `NOT NULL` column gets a `DEFAULT` or a backfill. Column defaults match entity defaults; validation rules get a matching `CHECK`.
85
+ - A database that predates the tool: export its schema as `V1`, or `spring.flyway.baseline-on-migrate: true`.
86
+ - Integration tests run the real migrations on the production engine and assert none is pending (`flyway.info().pending()` empty).
73
87
 
74
88
  ## Outbox, saga, CQRS
75
89
 
@@ -42,6 +42,8 @@ class UserControllerTests {
42
42
 
43
43
  `MockMvcTester` is AssertJ-based (`assertThat(mvc.get().uri(...)).hasStatusOk()`); do not mix it with the `expectStatus()` chain, which belongs to the other clients. Security: `@WithMockUser` still works on slices; `@Import` your security config.
44
44
 
45
+ `@WebMvcTest` creates no services or repositories: every bean the controller injects needs a `@MockitoBean`, including a repository newly added to an existing controller. Assert error bodies as Problem Details fields (`$.status`, `$.title`; `$.errors[*].field` only when your handler adds an `errors` extension), never on message texts.
46
+
45
47
  ## Full-server test
46
48
 
47
49
  ```java
@@ -82,6 +84,8 @@ class AuthorRepositoryTests { /* ... */ }
82
84
  - The default `replace = NON_TEST` already keeps a `@ServiceConnection` data source; `replace = NONE` is only needed for a non-test `DataSource` you defined yourself.
83
85
  - Where `@ServiceConnection` has no support for the container, use `@Testcontainers` + `@Container static` + `@DynamicPropertySource` to register the properties.
84
86
  - Share one container configuration across tests so the context cache is reused.
87
+ - `@Testcontainers(disabledWithoutDocker = true)` skips the class silently when no daemon answers: check the test report shows the integration tests as run. With Podman, point `DOCKER_HOST` at the Podman socket and set `TESTCONTAINERS_RYUK_DISABLED=true`.
88
+ - Beyond CRUD, the integration tests cover what a mocked slice cannot see: all migrations applied, a DB `CHECK` rejecting a bad row, none -> A, A -> B and A -> none for each relation a client can change, a stale `version` answering 409, a referenced delete answering 409 with the row still there.
85
89
 
86
90
  ## Rules
87
91
 
@@ -15,7 +15,11 @@ Consequences of riding this mechanism (deliberate):
15
15
  - exempt from the flat-skill authoring gates (theme DESC tokens, dead-link,
16
16
  hermeticity, skill counts) — the SKILL.md here carries its own frontmatter
17
17
  `description` and blockquote purpose line instead;
18
- - listed in AGENT.md's folder-skills section, not the main skills table.
18
+ - listed in AGENT.md's folder-skills section, not the main skills table;
19
+ - at emit time the `description:` of `SKILL.md` is replaced with the skill's line in
20
+ `src/skill-descriptions.json` (at most 80 characters: the host's skill listing has a budget),
21
+ and the description written here is kept as the first body line, a blockquote
22
+ (`vendoredWithCatalogueLine`, `js/hosts/native.mjs`).
19
23
 
20
24
  The script supports all four emitted hosts, with exact usage on each.
21
25
  If a host changes its session storage layout, fix the corresponding finder or