geneseed 4.9.3 → 4.10.0

package/src/skills/react-view-transitions/references/patterns.md

@@ -1,5 +1,7 @@
 # Patterns and Guidelines
 
+Use the official [React `<ViewTransition>` reference](https://react.dev/reference/react/ViewTransition) for API mechanics. This file collects reusable implementation patterns and failure modes from production apps.
+
 ## Searchable Grid with `useDeferredValue`
 
 `useDeferredValue` makes filter updates a transition, activating `<ViewTransition>`:
@@ -114,38 +116,74 @@ Use `key` when content identity changes (state resets). Omit for cross-fades (ta
 
 ## Isolate Elements from Parent Animations
 
-### Persistent Layout Elements
+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)).
+
+- **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.
+- **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.
+- **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.
+- **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.
 
-Persistent elements (headers, navbars, sidebars) get captured in the page's transition snapshot. Fix with `viewTransitionName`:
+## Suspense reveal flicker
+
+An element rendered in **both** the fallback and the content flickers (opacity dip) on reveal — it fades against itself. Not a morph. **Fix: render it outside the `<Suspense>` boundary** (mount once, above it), or pin it with a `view-transition-name`.
 
 ```jsx
-<nav style={{ viewTransitionName: "persistent-nav" }}>{/* ... */}</nav>
+<h1>{title}</h1>
+<Suspense fallback={<BodySkeleton />}><Body /></Suspense>
 ```
 
-Then add the persistent element isolation CSS from `css-recipes.md`. For `backdrop-blur`/`backdrop-filter`, use the backdrop-blur workaround from `css-recipes.md`.
+Don't put a manual `viewTransitionName` on the root DOM node inside `<ViewTransition>` — React's auto-name overrides it.
 
-### Floating Elements
+## Sliding Indicator (tabs)
 
-Give popovers/tooltips their own `viewTransitionName`:
+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)).
 
-```jsx
-<SelectPopover style={{ viewTransitionName: 'popover' }}>{options}</SelectPopover>
+```tsx
+import { useState, useTransition, ViewTransition } from 'react';
+
+export function Tabs({ tabs, indicatorName = 'tab-indicator' }) {
+  const [active, setActive] = useState(tabs[0].value);
+  const [, startTransition] = useTransition();
+  return (
+    <nav>
+      {tabs.map(t => (
+        <button key={t.value} type="button"
+          aria-current={active === t.value ? 'page' : undefined}
+          onClick={() => startTransition(() => setActive(t.value))}>
+          <span>{t.label}</span>
+          {active === t.value && (
+            <ViewTransition name={indicatorName} share="tab-underline">
+              <span className="active-underline" aria-hidden />
+            </ViewTransition>
+          )}
+        </button>
+      ))}
+    </nav>
+  );
+}
 ```
 
-Global fix: see persistent element isolation in `css-recipes.md`.
+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.
 
-## Shared Controls Between Skeleton and Content
+## Layout Displacement Morph
 
-Give matching controls in fallback and content the same `viewTransitionName`:
+Only content inside an activated boundary animates position — everything else teleports to its new layout spot. When a list grows or shrinks, wrap the sibling content below it so it glides instead of jumping:
 
 ```jsx
-// Fallback
-<input disabled placeholder="Search..." style={{ viewTransitionName: 'search-input' }} />
-// Content
-<input placeholder="Search..." style={{ viewTransitionName: 'search-input' }} />
+<FavoritesList />              {/* rows enter/exit */}
+<ViewTransition>               {/* bare: update enabled */}
+  <section>
+    <h2>You Might Also Like</h2>
+    <Recommendations />
+  </section>
+</ViewTransition>
 ```
 
-Don't put manual `viewTransitionName` on the root DOM node inside `<ViewTransition>` — React's auto-generated name overrides it.
+The section — heading included — morphs as one group when rows above are added or removed. Nothing inside the section changed; the *displacement* is the update.
+
+- React only measures boundaries that are direct children of nodes along the changed path — a VT buried under an extra wrapper element won't activate. Place the boundary as a direct sibling of the changing content.
+- Sometimes the better fix is no morph at all: pad fixed-size lists to a constant slot count with invisible fillers so the grid never changes height and nothing below it moves.
+- `default="none"` disables exactly this morph — it turns off `update`. Named/shared elements get `default="none"`; displaced siblings and keyed list items stay bare or set `update="auto"`.
 
 ## Reusable Animated Collapse
 
@@ -164,7 +202,9 @@ function AnimatedCollapse({ open, children }) {
 <AnimatedCollapse open={open}><SectionContent /></AnimatedCollapse>
 ```
 
-## Preserve State with Activity
+## Composing with Activity
+
+`Activity` is orthogonal to view transitions: it preserves the state of a hidden subtree, `ViewTransition` animates it. Compose them for an in-page show/hide (drawer, panel, tab body) that keeps its scroll/form state while it animates in and out:
 
 ```jsx
 <Activity mode={isVisible ? 'visible' : 'hidden'}>
@@ -174,6 +214,8 @@ function AnimatedCollapse({ open, children }) {
 </Activity>
 ```
 
+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)).
+
 ## Exclude Elements with `useOptimistic`
 
 `useOptimistic` values update before the transition snapshot, excluding them from animation. Use for controls (labels); use committed state for animated content:
@@ -200,7 +242,7 @@ function cycleSort() {
 
 ## View Transition Events
 
-Imperative control via `onEnter`, `onExit`, `onUpdate`, `onShare`. Always return a cleanup function. `onShare` takes precedence over `onEnter`/`onExit`.
+Imperative control via `onEnter`, `onExit`, `onUpdate`, `onShare`. Return a cleanup function to cancel your animation when the transition finishes. `onShare` takes precedence over `onEnter`/`onExit`.
 
 ```jsx
 <ViewTransition
@@ -230,33 +272,3 @@ The `types` array (second argument) lets you vary animation based on transition
 | Route transition (slide) | 150–250ms |
 | Suspense reveal (skeleton → content) | 200–400ms |
 | Shared element morph | 300–500ms |
-
----
-
-## Troubleshooting
-
-**VT not activating:** Ensure `<ViewTransition>` comes before any DOM node. Ensure state update is inside `startTransition`.
-
-**"Two ViewTransition components with the same name":** Names must be globally unique. Use IDs: `name={`hero-${item.id}`}`.
-
-**`router.back()` and browser back/forward skip animation:** Use `router.push()` with an explicit URL instead. See SKILL.md "router.back() and Browser Back Button."
-
-**`flushSync` skips animations:** Use `startTransition` instead.
-
-**Only updates animate (no enter/exit):** Without `<Suspense>`, React treats swaps as updates. Conditionally render the VT itself, or wrap in `<Suspense>`.
-
-**Layout VT prevents page VTs from animating:** Nested VTs never fire enter/exit inside a parent VT. If your layout has a VT wrapping `{children}`, page-level enter/exit will silently not work. Remove the layout VT.
-
-**List reorder not animating with `useOptimistic`:** Optimistic values resolve before snapshot. Use committed state for list order.
-
-**TS error "Property 'default' is missing":** Type-keyed objects require a `default` key.
-
-**Hash fragments cause scroll jumps:** Navigate without hash; scroll programmatically after navigation.
-
-**Backdrop-blur flickers:** Use the backdrop-blur workaround from `css-recipes.md`.
-
-**`border-radius` lost during transitions:** Apply `border-radius` directly to the captured element.
-
-**Skeleton controls slide away:** Give matching controls the same `viewTransitionName`.
-
-**Batching:** Multiple updates during animation are batched. A→B→C→D becomes B→D.

package/src/skills/react-view-transitions/references/troubleshooting.md

@@ -0,0 +1,47 @@
+# Troubleshooting
+
+**VT not activating:** Ensure `<ViewTransition>` comes before any DOM node and the state update is inside `startTransition`. A raw `viewTransitionName` only isolates an element; it does not activate a React view transition.
+
+**"Two ViewTransition components with the same name":** Names must be globally unique. Use IDs such as `name={`hero-${item.id}`}`. If a reusable component appears in multiple surfaces at once, move the name to the specific consumer or make it conditional.
+
+**Unrelated content crossfades:** A bare VT uses the browser crossfade for every trigger. Set `default="none"` and opt in only to the triggers that boundary should handle.
+
+**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).
+
+**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).
+
+**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.
+
+**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).
+
+**Shared morph competes with a page fade:** A fading page exit dissolves the source while it is morphing. Remove that exit or use motion that preserves the shared element's continuity.
+
+**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.
+
+**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).
+
+**`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.
+
+**`flushSync` skips animations:** Use `startTransition` instead.
+
+**Only updates animate (no enter/exit):** Without `<Suspense>`, React treats swaps as updates. Conditionally render the VT itself, or wrap in `<Suspense>`.
+
+**Suspense reveal does not animate:** Suspense resolves in a separate transition without navigation types. Use string `enter`/`exit` props rather than a type map.
+
+**Layout VT prevents page VTs from animating:** Nested VTs skip their own enter/exit when they mount or unmount as one unit with a parent VT. Keep route boundaries in pages, not a layout wrapping `{children}`. React has experimental upstream `parentEnter`/`parentExit` work ([PR #36690](https://github.com/facebook/react/pull/36690)), but those props are not currently available in the Next.js client runtime; do not recommend them in a Next.js app unless the installed runtime and docs explicitly include them.
+
+**Same-route content does not animate with `update`:** Nested VTs can own the mutation before an outer boundary sees it. For a real identity change, use `key` with a stable `name` and `share` instead.
+
+**List reorder not animating with `useOptimistic`:** Optimistic values resolve before snapshot. Use committed state for list order.
+
+**TS error "Property 'default' is missing":** Type-keyed objects require a `default` key.
+
+**Hash fragments cause scroll jumps:** Navigate without hash; scroll programmatically after navigation.
+
+**Backdrop-blur flickers:** Use the [Backdrop-Blur Workaround](css-recipes.md#backdrop-blur-workaround).
+
+**`border-radius` lost during transitions:** Apply `border-radius` directly to the captured element.
+
+**Skeleton controls slide away:** Give matching controls the same `viewTransitionName`.
+
+**Batching:** Multiple updates during animation are batched. A→B→C→D becomes B→D.

package/src/skills/research.md

@@ -2,6 +2,8 @@
 
 > {{DESC_RESEARCH}}
 
+{{CREDIT:mattpocock-skills:skills/engineering/research/SKILL.md}}
+
 **Trigger:** a question needs current, external, or wide-ranging facts that are neither
 in this repository nor in the model's own knowledge. They are gathered and verified from
 the open web.

package/src/skills/review-response.md

@@ -2,6 +2,8 @@
 
 > {{DESC_REVIEW_RESPONSE}}
 
+{{CREDIT:superpowers:skills/receiving-code-review/SKILL.md}}
+
 **Trigger:** review feedback has arrived — from a human or another agent — and is about
 to be acted on; or the user wants a review criterion recorded ("add a review rule…",
 "reviews should always check…").

package/src/skills/rule.md

@@ -3,6 +3,8 @@
 > {{DESC_RULE}}
 <!-- aliases: consolidate-memory -->
 
+{{CREDIT:mattpocock-skills-2509:skills/engineering/retro/SKILL.md}}
+
 **Trigger:** the user says "always…", "never…", "from now on…" or "remember that…". Anything the user wants to outlive this session counts: a standing rule ("make that a
 rule") or a durable fact ("note that…", "keep in mind…"). Also fires when a
 `feedback` {{MEMORY}} lesson keeps recurring and deserves promotion, or when

package/src/skills/ship.md

@@ -2,6 +2,8 @@
 
 > {{DESC_SHIP}}
 
+{{CREDIT:mattpocock-skills-2509:skills/engineering/pr/SKILL.md}}
+
 **Trigger:** the change is committed and verified, and it is time to open a pull
 request or merge the branch.
 

package/src/skills/skill-forge.md

@@ -40,6 +40,7 @@ apparatus, so every step ends in the user's assent ({{LAW:one-intent-one-act}},
    every theme, `SKILL_CLASS`, a `registry.json` row, the README enumeration, then
    `doctor --all` and the suites. A skill that bundles a script or several files is a
    folder skill (`<name>/SKILL.md` + `VENDOR.md`), listed in `VENDORED_SKILL_DIRS`.
+   Text adapted from outside gets a `src/upstreams.json` entry and a `CREDIT` token (docs/extending.md §3, in the Geneseed source repo).
 5. **Merge or retire honestly.** When two skills fold into one: keep the best steps of
    each, rewrite the exit so the survivor routes to what the retired one led to, and
    remove the retired file and *every* reference to it (table row, sibling links, theme

package/src/skills/spring-boot/cloud.md

@@ -0,0 +1,103 @@
+# {{SKILL}}: spring-boot — cloud-native
+
+{{CREDIT:piomin-spring-boot:skills/spring-boot/references/cloud.md}}
+
+Configuration, outbound clients, resilience, observability and packaging for a service that runs on Kubernetes or similar. Spring Cloud components (Config, Eureka, Gateway, LoadBalancer) ship in a release train tied to a Boot line: pick the train from the Spring Cloud supported-versions table, never mix trains. On Kubernetes, native service discovery and ConfigMaps often replace Eureka and Config Server; reach for those only when the platform lacks them.
+
+## Config and secrets
+```yaml
+spring:
+  config:
+    import: "optional:configtree:/run/secrets/"
+```
+A Config Tree reads each mounted file as one property, so secrets stay out of environment variables and `/proc`. Mount the Kubernetes Secret read-only at that path.
+
+## Declarative HTTP clients
+Replace OpenFeign with an `@HttpExchange` interface. Boot registers groups; the URL and timeouts come from properties.
+
+```java
+@HttpExchange("/users")
+public interface UserClient {
+    @GetExchange("/{id}")
+    UserResponse get(@PathVariable Long id);
+
+    @PostExchange
+    UserResponse create(@RequestBody UserCreateRequest request);
+}
+
+@SpringBootApplication
+@ImportHttpServices(group = "users", types = UserClient.class)
+public class App { }
+```
+
+```yaml
+spring:
+  http:
+    serviceclient:
+      users:
+        base-url: "http://user-service"
+        read-timeout: 2s
+```
+
+Without Boot's group support, build one by hand with `HttpServiceProxyFactory.builderFor(RestClientAdapter.create(restClient)).build().createClient(UserClient.class)`.
+
+## Resilience
+Framework 7 ships retry and concurrency limits in core. Enable them once, then annotate:
+
+```java
+@Configuration
+@EnableResilientMethods
+class ResilienceConfig { }
+
+@Retryable(includes = IOException.class, maxRetries = 3, delay = 200, multiplier = 2, maxDelay = 2000)
+public Quote fetch(String id) { ... }
+
+@ConcurrencyLimit(10)
+public void sendNotification() { ... }
+```
+
+Retry only idempotent calls. Circuit breaking: at the edge, use the Gateway `CircuitBreaker` filter; in-service, Resilience4j is still the common choice but its annotation and property names were not re-verified for Boot 4 here, so check its current docs before copying old config.
+
+## Gateway
+Spring Cloud Gateway's reactive server uses the `spring.cloud.gateway.server.webflux.*` prefix in current releases (older guides show `spring.cloud.gateway.*`). Prefer YAML routes over the Java DSL for simple cases.
+
+```yaml
+spring:
+  cloud:
+    gateway:
+      server:
+        webflux:
+          routes:
+            - id: users
+              uri: lb://user-service
+              predicates: [Path=/api/users/**]
+              filters:
+                - CircuitBreaker=usersBreaker
+```
+
+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.
+
+## Observability
+- 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.
+- Metrics: add `micrometer-registry-prometheus` and expose `prometheus`.
+- 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.
+- Custom spans: `Observation.createNotStarted("order.process", registry).lowCardinalityKeyValue(...).observe(() -> ...)` (Micrometer Observation, unchanged by Boot 4 as far as the docs show).
+
+## Lifecycle
+```yaml
+server:
+  shutdown: graceful
+spring:
+  lifecycle:
+    timeout-per-shutdown-phase: 30s
+```
+Add a short Kubernetes `preStop` sleep so the endpoint leaves the load balancer before the JVM stops accepting work. Keep the pod's termination grace period longer than the shutdown phase timeout.
+
+## Images
+- No Dockerfile needed: `./mvnw spring-boot:build-image` builds an OCI image with Cloud Native Buildpacks (Paketo). With the native profile: `./mvnw -Pnative spring-boot:build-image`. Bind `build-image-no-fork` to `package` to build in CI.
+- If you do write a Dockerfile: multi-stage, JRE-only runtime image, non-root user, `-XX:MaxRAMPercentage` instead of a fixed heap.
+- GraalVM native: fast start and low memory, at the cost of build time and reflection hints; adopt it deliberately, not by default.
+- Use whatever CI the project already has; do not introduce a new one.
+
+## Kubernetes manifest essentials
+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)).

package/src/skills/spring-boot/java-modern.md

@@ -0,0 +1,71 @@
+# {{SKILL}}: spring-boot — modern Java in Spring code
+
+{{CREDIT:piomin-spring-boot:skills/java-modern/SKILL.md}}
+
+{{CREDIT:piomin-spring-boot:skills/code-quality/SKILL.md}}
+
+Java 21+ features and where they pay off in a Spring Boot codebase, plus the null-safety and Optional habits that prevent most runtime NPEs. This is a language reference for writing Spring code, not a review procedure.
+
+## Where each feature fits
+| Feature | Use for | Avoid when |
+|---------|---------|------------|
+| Records | DTOs, `@ConfigurationProperties`, value objects, events | JPA entities (Hibernate needs a no-arg constructor and mutable state), types needing inheritance |
+| Sealed interfaces | Closed result and event hierarchies | Types that third parties must extend |
+| Pattern-matching `switch` | Handling sealed types exhaustively, replacing `instanceof` chains | Plain equality checks |
+| Virtual threads | Blocking I/O at high concurrency (`spring.threads.virtual.enabled: true`) | CPU-bound work |
+| Text blocks | JPQL, SQL, JSON fixtures in tests | One-line strings |
+| Sequenced collections | `getFirst()`, `getLast()`, `reversed()` on ordered collections | Unordered sets and maps |
+
+## Records
+```java
+@ConfigurationProperties(prefix = "app.notification")
+public record MailProperties(boolean enabled, String sender, Duration connectTimeout, Backoff backoff) {
+    public record Backoff(int attempts, Duration pause) {}
+}
+```
+Register with `@ConfigurationPropertiesScan` or `@EnableConfigurationProperties`. Constraint annotations on record components work with `@Validated` on the properties class.
+
+## Sealed results and exhaustive switch
+```java
+public sealed interface PaymentResult permits Paid, Declined, Pending {}
+public record Paid(String transactionId, BigDecimal amount) implements PaymentResult {}
+public record Declined(String code, String message) implements PaymentResult {}
+public record Pending(String reference) implements PaymentResult {}
+
+String describe(PaymentResult result) {
+    return switch (result) {
+        case Paid p -> "Paid: " + p.transactionId();
+        case Declined d -> "Declined: " + d.message();
+        case Pending p -> "Pending: " + p.reference();
+    };
+}
+```
+No `default` branch on a sealed switch: adding a subtype then fails the build at every switch that must handle it. Use guards (`case Order o when o.total().signum() > 0 ->`) sparingly; a guard-heavy switch is usually a rules table in disguise.
+
+Prefer a sealed result over an exception for expected outcomes (declined, not found); keep exceptions for the unexpected.
+
+## Virtual threads
+One property moves request handling and `@Async` work to virtual threads, so blocking JDBC and `RestClient` calls scale without reactive code. Pitfalls: a `synchronized` block that holds a monitor across blocking I/O pins the carrier thread on older JDKs (use `ReentrantLock`; Java 24+ lessens this), and thread-locals (MDC, security context) do not follow work onto another thread. Bound pools that guard scarce resources (the DB connection pool still limits real concurrency). Keep WebFlux for streaming, SSE or backpressure.
+
+## Null safety and Optional
+Spring Framework 7 and Boot 4 annotate their APIs with JSpecify (`@NullMarked`, `@Nullable`); use the same in your own packages so the compiler or IDE can check callers.
+
+```java
+// repository lookups: return Optional, decide at the edge
+User user = repository.findById(id).orElseThrow(() -> new ResourceNotFoundException("User " + id));
+
+// derive without unwrapping
+String label = Optional.ofNullable(user.getNickname()).map(String::toUpperCase).orElse("");
+```
+
+Habits:
+- `Optional` is a return type, not a field, parameter or collection element. Never `Optional.get()` without a prior check; use `orElseThrow`.
+- Return an empty collection, never `null`.
+- Do not catch `Exception` broadly or swallow it; wrap with the cause (`new ProcessingException("...", e)`) and log once, where it is handled.
+- Open resources with try-with-resources.
+- Chained calls on values that can be null (`a.getB().getC()`) need a guard or `Optional` mapping.
+
+## Quick rules
+- DTO or config -> record. Entity -> normal class.
+- Closed set of outcomes -> sealed interface plus exhaustive switch.
+- Blocking service -> virtual threads, not WebFlux.

package/src/skills/spring-boot/logging.md

@@ -0,0 +1,89 @@
+# {{SKILL}}: spring-boot — logging
+
+{{CREDIT:piomin-spring-boot:skills/logging-patterns/SKILL.md}}
+
+SLF4J through Spring Boot's logging, with structured (JSON) output where logs are machine-read. Structured output is a good default for deployed environments and CI because fields parse directly (`jq`, log platforms, an AI assistant reading logs); keep readable text for local development.
+
+## Structured logging (built in)
+No extra dependency. Pick a format per target:
+
+```yaml
+logging:
+  structured:
+    format:
+      console: logstash   # also: ecs, gelf
+```
+
+`logging.structured.format.file` does the same for file output. A custom Logback or Log4j2 config must use Boot's structured encoder or layout (`StructuredLogEncoder` / `StructuredLogLayout` fed by `CONSOLE_LOG_STRUCTURED_FORMAT`), or the property has no effect.
+
+Profile split so developers keep readable logs:
+
+```yaml
+---
+spring:
+  config:
+    activate:
+      on-profile: "!local"
+logging:
+  structured:
+    format:
+      console: logstash
+```
+
+Run locally with the `local` profile for plain text. With Micrometer Tracing present, Boot adds `[traceId-spanId]` to every log line by default; change the format with `logging.pattern.correlation`. Whether they appear as JSON fields depends on the format; confirm in a real log line.
+
+## Writing log statements
+```java
+private static final Logger log = LoggerFactory.getLogger(OrderService.class);
+
+log.info("Order created id={} customer={}", order.id(), order.customerId()); // parameterized
+log.error("Payment failed for order {}", order.id(), e);                      // exception last, stack trace kept
+```
+- Placeholders, never string concatenation. Guard only genuinely expensive arguments with `isDebugEnabled()`.
+- Pass the exception as the final argument; do not log `e.getMessage()` alone.
+- Log an exception once, where it is handled, not at every layer it passes through.
+- Never log secrets, tokens, passwords or personal data; log identifiers.
+- Lombok's `@Slf4j` is fine where the project uses Lombok; otherwise declare the logger as above.
+
+| Level | Meaning |
+|-------|---------|
+| ERROR | Something failed and needs attention |
+| WARN | Unexpected but handled (fallback used, retry succeeded) |
+| INFO | Business events (order created, job finished) |
+| DEBUG | Technical detail (queries, outbound calls) |
+| TRACE | Verbose internals |
+
+## MDC for correlation
+MDC attaches key-value context to every log line written by the current thread. Set it at the edge in a filter and always clear it in `finally`.
+
+```java
+@Component
+@Order(Ordered.HIGHEST_PRECEDENCE)
+class MdcFilter extends OncePerRequestFilter {
+    @Override
+    protected void doFilterInternal(HttpServletRequest req, HttpServletResponse res, FilterChain chain)
+            throws ServletException, IOException {
+        String header = req.getHeader("X-Request-Id");
+        // client-supplied: accept only a short, safe value
+        String id = header != null && header.matches("[A-Za-z0-9-]{1,64}") ? header : UUID.randomUUID().toString();
+        MDC.put("requestId", id);
+        try {
+            chain.doFilter(req, res);
+        } finally {
+            MDC.remove("requestId");
+        }
+    }
+}
+```
+
+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.
+
+Useful fields for incident analysis: `requestId`, user or tenant id, and a duration on slow-path logs. Keep them to identifiers, not payloads.
+
+## Quick reference
+| Need | Use |
+|------|-----|
+| JSON console | `logging.structured.format.console: logstash` |
+| Per-package level | `logging.level.com.example.orders: DEBUG` |
+| Correlate a request | MDC `requestId` set in a filter |
+| Follow one request in JSON logs | `jq 'select(.requestId == "abc")' app.log` (field name depends on MDC key and format) |

package/src/skills/spring-boot/security.md

@@ -0,0 +1,112 @@
+# {{SKILL}}: spring-boot — security
+
+{{CREDIT:piomin-spring-boot:skills/spring-boot/references/security.md}}
+
+Spring Security 7. Default posture for an API: a stateless OAuth2 resource server that validates JWTs issued by an identity provider. Do not write your own token issuer, JWT filter or password store unless the task is explicitly to build an authorization server; that code is where the security bugs live.
+
+## Resource server
+Properties first (Boot builds the decoder from them):
+
+```yaml
+spring:
+  security:
+    oauth2:
+      resourceserver:
+        jwt:
+          issuer-uri: https://auth.example.com
+          audiences:
+            - orders-api
+```
+
+```java
+@Configuration
+@EnableWebSecurity
+@EnableMethodSecurity
+class SecurityConfig {
+
+    @Bean
+    SecurityFilterChain api(HttpSecurity http) throws Exception {
+        http
+            .cors(Customizer.withDefaults())
+            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+            .authorizeHttpRequests(auth -> auth
+                .requestMatchers("/actuator/health/**").permitAll()
+                .requestMatchers("/api/admin/**").hasRole("ADMIN")
+                .anyRequest().authenticated())
+            .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()));
+        return http.build();
+    }
+}
+```
+
+- Lambda DSL only; `.and()` chaining and `authorizeRequests` are gone in Security 7.
+- Disabling CSRF is acceptable only for a stateless, bearer-token API with no cookie-based session. If any endpoint authenticates with a cookie, keep CSRF on.
+- `cors(Customizer.withDefaults())` picks up a `CorsConfigurationSource` bean; define that bean with explicit origins.
+- Default JWT algorithm trust is RS256 only; widen it deliberately if the provider signs otherwise.
+
+## Mapping claims to authorities
+The default converter maps the `scope` claim to `SCOPE_` authorities. For roles in another claim:
+
+```java
+@Bean
+JwtAuthenticationConverter jwtAuthenticationConverter() {
+    var authorities = new JwtGrantedAuthoritiesConverter();
+    authorities.setAuthoritiesClaimName("roles");
+    authorities.setAuthorityPrefix("ROLE_");
+    var converter = new JwtAuthenticationConverter();
+    converter.setJwtGrantedAuthoritiesConverter(authorities);
+    return converter;
+}
+```
+
+Wire it with `oauth2.jwt(jwt -> jwt.jwtAuthenticationConverter(jwtAuthenticationConverter()))`.
+
+## Validate audience
+An issuer check alone accepts any token that issuer minted for any API. The `audiences` property in the YAML above makes Boot require the `aud` claim. Define your own `JwtDecoder` bean only when you need custom validators; it replaces the property-driven decoder, audiences included.
+
+## Method security
+`@EnableMethodSecurity` turns on `@PreAuthorize` and `@PostAuthorize`. Authorize in the service layer, next to the data, not only on URL patterns. The legacy Access API (`AccessDecisionManager`, voters) moved to the separate `spring-security-access` module; `@Secured` still works via `@EnableMethodSecurity(securedEnabled = true)`, but prefer `@PreAuthorize`.
+
+```java
+@PreAuthorize("hasRole('ADMIN') or #ownerId == authentication.name")
+public Order find(String ownerId, Long id) { ... }
+```
+
+## Testing
+Use the `jwt()` request post processor with MockMvc (`SecurityMockMvcRequestPostProcessors.jwt()`; default token has `scope=read`), or `@WithMockUser` for method security. Always test the 401 (no token) and 403 (wrong authority) paths, not only success.
+
+## TLS with SSL bundles
+Configure server and client TLS with SSL bundles (named key material). Reloading works only when the consuming component supports it (Tomcat and Netty servers) and only through the file watcher, so the material must be on the file system with a `file:` location; a `classpath:` bundle cannot reload.
+
+```yaml
+spring:
+  ssl:
+    bundle:
+      pem:
+        server:
+          reload-on-update: true
+          keystore:
+            certificate: "file:/etc/ssl/app/tls.crt"
+            private-key: "file:/etc/ssl/app/tls.key"
+server:
+  ssl:
+    bundle: server
+```
+
+Tune detection with `spring.ssl.bundle.watch.file.quiet-period` (default 10s). Apply a bundle to an outbound `RestClient` with the `RestClientSsl` helper (it replaces any request factory you set earlier; use a separate `client` bundle with a `truststore` for the upstream, not the server's keystore bundle), or build a factory when you need more than SSL:
+
+```java
+RestClient client(RestClient.Builder builder, RestClientSsl ssl) {
+    return builder.baseUrl("https://internal-service").apply(ssl.fromBundle("client")).build();
+}
+// more than SSL:
+// var settings = HttpClientSettings.ofSslBundle(bundles.getBundle("client")).withReadTimeout(Duration.ofSeconds(5));
+// builder.requestFactory(ClientHttpRequestFactoryBuilder.detect().build(settings))
+```
+
+## Checklist
+- HTTPS everywhere outside local dev; secrets from env or mounted files ([spring-boot/cloud.md](cloud.md) covers config trees).
+- Validate issuer and audience; keep token lifetimes short; never log tokens.
+- Passwords (if you must store any): `PasswordEncoder` from `PasswordEncoderFactories`/BCrypt, never a plain hash.
+- Rate-limit authentication endpoints at the gateway or proxy.
+- Ask the `spring-security` agent for review (it hands the generic audit to `security`) when the change touches authentication or authorization.