gennady 0.6.0 → 0.7.0

package/dist/ai/directives/coding/svelte5-runes.xml

@@ -0,0 +1,248 @@
+<Svelte5RunesRules keywords="svelte5, runes, state, derived, effect, props, bindable, inspect, snippets" type="coding-rules" ver="2.0">
+  <Mission>
+    Canonical rules for writing Svelte 5 components using runes. Every execution-agent MUST use runes (`$state`, `$derived`, `$effect`, `$props`, `$bindable`, `$inspect`, `$effect.root`) as compiler keywords, not runtime function calls. Legacy Svelte 4 patterns (`export let`, `$:` reactive statements, `on:event` directives, `<slot>`, `createEventDispatcher`) are forbidden in new code.
+
+    **Base axiom:** runes are compile-time signals — the `$` prefix tells the Svelte compiler how to wire reactivity. They are not imports, not callable values, not React hooks. The component file is the only place a reading agent can recover this reactivity contract — so the file MUST stay self-describing: explicit runes, intent-named handlers, machine-friendly comments.
+
+    Scope: `.svelte`, `.svelte.js`, `.svelte.ts` files (compiler-aware). Out of scope: plain `.ts` modules (runes do not work there).
+  </Mission>
+
+  <Depends_On>
+    - ai/directives/coding/typescript-rules.xml
+  </Depends_On>
+
+  <Belief_State>
+    <Axiom id="AX_RUNES_ARE_COMPILER_KEYWORDS">
+      Runes are compiler directives prefixed with `$`, not runtime functions. They are never imported from any module, never assigned to variables, never passed as values. Reading `$state` / `$derived` / `$effect` as «function call» mental model leads to React-hook habits (dependency arrays, memoization wrappers) — none of which apply here.
+
+      Agent treating a rune as a value (`const s = $state; s(0)`) produces code that compiles to nothing useful and silently breaks reactivity.
+    </Axiom>
+
+    <Axiom id="AX_RUNES_LOCATION_RESTRICTION">
+      Runes appear ONLY inside Svelte compiler context: `.svelte` files, or `.svelte.js` / `.svelte.ts` modules. Using a rune in a plain `.ts` file produces a compile error; the rune does NOT silently degrade to a function call.
+
+      Cross-file shared reactive state belongs in a `.svelte.ts` module exporting runes-backed values, or in classic stores. Mixing the two for the same value is forbidden.
+    </Axiom>
+
+    <Axiom id="AX_LOCAL_RUNES_OVER_STORES_FOR_LOCAL_STATE">
+      Local component state uses `$state` / `$derived` / `$effect`. Classic stores (`writable`, `readable`, `derived` from `svelte/store`) remain available for cross-component shared state but MUST NOT be used as a substitute for local state when a rune suffices. A store introduces a subscription lifecycle that local runes do not need.
+
+      The `$store` auto-subscription syntax in templates is unchanged from Svelte 4 and remains supported.
+    </Axiom>
+
+    <Axiom id="AX_DERIVED_IS_PURE">
+      `$derived(expression)` and `$derived.by(() => ...)` MUST be pure: no side effects, no I/O, no logging, no mutation of other reactive state. Side effects belong in `$effect`. A `$derived` that mutates is a hidden cycle waiting to fire on every dependency change.
+    </Axiom>
+
+    <Axiom id="AX_EFFECT_OWNERSHIP_AND_CLEANUP">
+      `$effect(() => { ... })` runs after DOM updates; return a teardown function from the body when the effect allocates a resource (timer, subscription, listener, observer) — Svelte runs the teardown before the next run and on component destroy.
+
+      For effects outside a component context, use `$effect.root(() => { ... })` and dispose of its returned cleanup function explicitly. Forgetting the teardown function inside an effect that allocates is the classic source of leaked listeners and timers.
+    </Axiom>
+
+    <Axiom id="AX_PROPS_VIA_DESTRUCTURING">
+      Component props come from a SINGLE `$props()` destructuring call at the top of the script: `let { foo, bar = defaultValue, onSomething } = $props()`. Defaults inline in the destructuring. Optional callbacks declared as props, not via `createEventDispatcher`.
+
+      Multiple `$props()` calls in one component are forbidden — there is one props surface per component.
+    </Axiom>
+
+    <Axiom id="AX_BINDABLE_FOR_TWO_WAY">
+      Two-way bindable props are declared via `$bindable(initialValue)` inside the `$props()` destructuring (`let { value = $bindable('') } = $props()`). The parent then writes `bind:value={...}`. Without `$bindable` a prop is one-way and the parent cannot `bind:`.
+    </Axiom>
+
+    <Axiom id="AX_SNIPPETS_REPLACE_SLOTS">
+      Reusable template fragments use `{#snippet name(params)}...{/snippet}` and are invoked via `{@render name(params)}`. The Svelte 4 `<slot>` mechanism, `$$slots`, and slot props are forbidden in new components — they are removed concepts in the Svelte 5 mental model.
+    </Axiom>
+
+    <Axiom id="AX_EVENT_HANDLERS_AS_ATTRIBUTES">
+      DOM event handlers are written as attributes (`onclick={handler}`, `oninput={handler}`), NOT as `on:event` directives. Custom component events are passed as callback props (`onConfirm={...}`), NOT through `createEventDispatcher`.
+
+      `on:event` directives, `dispatch(...)`, and `createEventDispatcher` are forbidden — they belonged to the Svelte 4 event model.
+    </Axiom>
+
+    <Axiom id="AX_COMPONENT_STRUCTURE_FIXED">
+      A Svelte 5 component file has a fixed structure: an optional `<script module>` for module-scope exports (one max), an optional `<script>` for instance code (one max), the HTML template, and an optional `<style>`. Multiple instance scripts, top-level expressions outside `<script>`, and pre-script template content are forbidden.
+    </Axiom>
+
+    <Axiom id="AX_LEGACY_PATTERNS_FORBIDDEN">
+      Forbidden Svelte 4 patterns in new components: `export let prop`, `$:` reactive statements, `on:event` directives, `<slot>` and `$$slots`, `$$props` / `$$restProps`, `createEventDispatcher`, `dispatch`. Each has a Svelte 5 replacement (`$props()`, `$derived` / `$effect`, attribute handlers, `{#snippet}` + `{@render}`, callback props).
+    </Axiom>
+
+    <Axiom id="AX_INSPECT_IS_DEV_ONLY">
+      `$inspect(value)` is the debugging channel — it logs reactive changes during development and is stripped in production builds. It MUST NOT replace `logger.*` for runtime observability and MUST NOT be committed as the sole report channel for a contract-bearing state transition.
+    </Axiom>
+  </Belief_State>
+
+  <Definitions>
+    <Definition id="DEF_SVELTE_RUNE">
+      A Svelte 5 rune: a compiler directive prefixed with `$`. Recognized: `$state`, `$state.raw`, `$derived`, `$derived.by`, `$effect`, `$effect.pre`, `$effect.root`, `$effect.tracking`, `$props`, `$bindable`, `$inspect`, `$host`.
+    </Definition>
+    <Definition id="DEF_RUNES_FILE">
+      A file in which runes are valid syntax: `.svelte`, `.svelte.js`, `.svelte.ts`. Plain `.ts` is NOT a runes file.
+    </Definition>
+  </Definitions>
+
+  <Code_Patterns>
+    <Pattern id="PT_BASIC_COMPONENT_WITH_RUNES">
+      <Intent>Minimal component using `$props`, `$state`, `$derived`, `$effect`, and an attribute event handler.</Intent>
+      <Snippet language="svelte">
+        ```svelte
+        <!-- @file: Counter component demonstrating the core rune set. -->
+        <script lang="ts">
+          let { initial = 0, label = 'Count', onChange } = $props();
+          let count = $state(initial);
+          let doubled = $derived(count * 2);
+
+          $effect(() => {
+            onChange?.(count);
+          });
+
+          function increment() {
+            count += 1;
+          }
+        </script>
+
+        <button type="button" onclick={increment}>
+          {label}: {count} (x2: {doubled})
+        </button>
+        ```
+      </Snippet>
+      <Why>One `$props()` destructure with defaults; `$state` for the mutable value; `$derived` pure; `$effect` mediates the outgoing side-channel; attribute `onclick`, not `on:click`.</Why>
+    </Pattern>
+
+    <Pattern id="PT_BINDABLE_PROP">
+      <Intent>Two-way bindable prop for a form input.</Intent>
+      <Snippet language="svelte">
+        ```svelte
+        <script lang="ts">
+          let { value = $bindable(''), placeholder = '' } = $props();
+        </script>
+
+        <input bind:value placeholder={placeholder} />
+        ```
+      </Snippet>
+      <Why>`$bindable` only inside `$props()` destructure; parent can now use `<TextInput bind:value={form.email} />`.</Why>
+    </Pattern>
+
+    <Pattern id="PT_SNIPPET_AND_RENDER">
+      <Intent>Reusable template fragment via `{#snippet}` and `{@render}` — the Svelte 5 replacement for slots.</Intent>
+      <Snippet language="svelte">
+        ```svelte
+        {#snippet card(title, body)}
+          <article class="card">
+            <h2>{title}</h2>
+            <p>{body}</p>
+          </article>
+        {/snippet}
+
+        {@render card('Hello', 'World')}
+        ```
+      </Snippet>
+      <Why>Snippets are reactive and re-render when arguments change. No `<slot>`, no `$$slots`.</Why>
+    </Pattern>
+
+    <Pattern id="PT_EFFECT_WITH_TEARDOWN">
+      <Intent>`$effect` allocating a resource MUST return a teardown.</Intent>
+      <Snippet language="svelte">
+        ```svelte
+        <script lang="ts">
+          let { tickMs = 1000, onTick } = $props();
+
+          $effect(() => {
+            const handle = setInterval(() => onTick?.(), tickMs);
+            return () => clearInterval(handle);
+          });
+        </script>
+        ```
+      </Snippet>
+      <Why>Return value is the teardown — runs before next effect invocation and on destroy. Forgetting it leaks the interval.</Why>
+    </Pattern>
+  </Code_Patterns>
+
+  <Anti_Patterns>
+    <Anti_Pattern id="AP_EXPORT_LET_LEGACY">
+      <Bad>`export let userId: string; export let onConfirm: () => void;` at the top of a `<script>`.</Bad>
+      <Why_Bad>Svelte 4 prop syntax. Forbidden by `AX_LEGACY_PATTERNS_FORBIDDEN` and `AX_PROPS_VIA_DESTRUCTURING`. Bypasses the single `$props()` destructure that is the only authoritative props surface in Svelte 5; mixing it with `$props()` in the same component is undefined behaviour.</Why_Bad>
+      <Good>`let { userId, onConfirm } = $props();` — single destructure at the top of the script, defaults inline if needed.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_REACTIVE_DOLLAR_COLON">
+      <Bad>`$: doubled = count * 2;` and `$: console.log(count);` inside a `<script>`.</Bad>
+      <Why_Bad>Svelte 4 reactive statements (`AX_LEGACY_PATTERNS_FORBIDDEN`). The first form is a derivation (belongs in `$derived`), the second is a side effect (belongs in `$effect`). Mixing the two intents under one syntax was exactly why `$:` was retired.</Why_Bad>
+      <Good>`let doubled = $derived(count * 2);` for the derivation; `$effect(() => { logger.debug('[Counter] [state-changed]', { count }); });` for the side effect.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_ON_EVENT_DIRECTIVE">
+      <Bad>`<button on:click={increment}>` in the template; `createEventDispatcher` + `dispatch('confirm', payload)` for component output.</Bad>
+      <Why_Bad>Svelte 4 event model (`AX_EVENT_HANDLERS_AS_ATTRIBUTES`). `on:click` and `dispatch` are removed concepts in the Svelte 5 mental model; keeping them in new components fragments the project's event syntax and confuses tooling that targets the new model.</Why_Bad>
+      <Good>`<button type="button" onclick={increment}>` for DOM; `onConfirm?.(payload)` callback prop for component output (declared in `$props()`).</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_RUNES_IN_PLAIN_TS">
+      <Bad>`// utils.ts` containing `export const counter = $state(0);`.</Bad>
+      <Why_Bad>`utils.ts` is not a runes file (`AX_RUNES_LOCATION_RESTRICTION`). The Svelte compiler does not process it; `$state` is undefined at runtime and TypeScript reports it as an unknown identifier.</Why_Bad>
+      <Good>Rename to `utils.svelte.ts` so the compiler treats it as a runes module: `export const counter = $state(0);` then works. Importers stay unchanged.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_DERIVED_WITH_SIDE_EFFECT">
+      <Bad>`let label = $derived((() => { logger.info('recomputing'); return count > 0 ? 'positive' : 'non-positive'; })());`</Bad>
+      <Why_Bad>Side effect (logging) inside `$derived` (`AX_DERIVED_IS_PURE`). `$derived` re-runs whenever any tracked dependency changes; the side effect fires on every recomputation, producing log spam and obscuring real state transitions.</Why_Bad>
+      <Good>`let label = $derived(count > 0 ? 'positive' : 'non-positive');` for the pure derivation; `$effect(() => { logger.debug('[Component] [label-changed]', { label }); });` for the observability side effect.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_EFFECT_WITHOUT_TEARDOWN">
+      <Bad>`$effect(() => { const id = setInterval(poll, 1000); });` — no return value.</Bad>
+      <Why_Bad>Allocating effect without teardown (`AX_EFFECT_OWNERSHIP_AND_CLEANUP`). The interval keeps firing across re-runs and after component destroy, leaking handlers and producing ghost network traffic.</Why_Bad>
+      <Good>`$effect(() => { const id = setInterval(poll, 1000); return () => clearInterval(id); });` — the returned cleanup runs before the next effect invocation and on destroy.</Good>
+    </Anti_Pattern>
+  </Anti_Patterns>
+
+  <Verification_Hooks>
+    <Hook id="HOOK_SVELTE_CHECK">
+      <Purpose>Type-check Svelte components and `.svelte.ts` modules; flags legacy patterns the compiler refuses.</Purpose>
+      <Command>npx svelte-check --tsconfig ./tsconfig.json</Command>
+      <Expected>Exit 0; no errors or warnings.</Expected>
+    </Hook>
+    <Hook id="HOOK_NO_LEGACY_PROP_SYNTAX">
+      <Purpose>Smoke-grep for forbidden Svelte 4 prop syntax `export let` in `.svelte` files.</Purpose>
+      <Command>find . -name '*.svelte' -not -path '*/node_modules/*' -not -path '*/.svelte-kit/*' -print0 | xargs -0 grep -nE '^\s*export\s+let\s+' || true</Command>
+      <Expected>Empty output. Any match is a legacy prop declaration that must be migrated to `$props()` destructuring.</Expected>
+    </Hook>
+    <Hook id="HOOK_NO_LEGACY_REACTIVE">
+      <Purpose>Smoke-grep for forbidden `$:` reactive statements and `on:event` directives.</Purpose>
+      <Command>find . \( -name '*.svelte' -o -name '*.svelte.ts' -o -name '*.svelte.js' \) -not -path '*/node_modules/*' -not -path '*/.svelte-kit/*' -print0 | xargs -0 grep -nE '(^|\s)\$:\s|(\s|^)on:[a-z]+=' || true</Command>
+      <Expected>Empty output. Matches must migrate to `$derived` / `$effect` or attribute handlers.</Expected>
+    </Hook>
+    <Hook id="HOOK_NO_RUNES_IN_PLAIN_TS">
+      <Purpose>Detect runes used in plain `.ts` files (not `.svelte.ts`).</Purpose>
+      <Command>find . -name '*.ts' -not -name '*.svelte.ts' -not -name '*.d.ts' -not -path '*/node_modules/*' -not -path '*/.svelte-kit/*' -print0 | xargs -0 grep -nE '\$(state|derived|effect|props|bindable|inspect)\b' || true</Command>
+      <Expected>Empty output. Files containing runes must be renamed to `.svelte.ts`.</Expected>
+    </Hook>
+    <Hook id="HOOK_NO_CREATE_EVENT_DISPATCHER">
+      <Purpose>Detect forbidden `createEventDispatcher` imports.</Purpose>
+      <Command>find . \( -name '*.svelte' -o -name '*.ts' \) -not -path '*/node_modules/*' -not -path '*/.svelte-kit/*' -print0 | xargs -0 grep -n 'createEventDispatcher' || true</Command>
+      <Expected>Empty output. Replace with callback props declared through `$props()`.</Expected>
+    </Hook>
+  </Verification_Hooks>
+
+  <Reward_Criteria>
+    ✅ All reactive primitives use runes (`$state`, `$derived`, `$effect`, `$props`, `$bindable`) as compiler keywords.
+    ✅ Props consumed via a single `$props()` destructure at the top of the script; defaults inline; callback props for outgoing events.
+    ✅ DOM event handlers use attribute form (`onclick={...}`); custom events use callback props.
+    ✅ Reusable template fragments use `{#snippet}` + `{@render}`.
+    ✅ Effects allocating resources return their teardown function.
+    ✅ `$derived` expressions are pure — no logging, no mutation, no I/O.
+    ✅ Runes only appear in `.svelte`, `.svelte.js`, `.svelte.ts` files; cross-file reactive values live in `.svelte.ts`.
+    ✅ Classic stores reserved for genuine cross-component shared state; local state uses runes.
+
+    ❌ `export let prop` for prop declarations in new components.
+    ❌ `$:` reactive statements (derivation OR side effect).
+    ❌ `on:event` directives or `createEventDispatcher` / `dispatch`.
+    ❌ `<slot>`, `$$slots`, `$$props`, `$$restProps`.
+    ❌ Rune used in a plain `.ts` file (must be `.svelte.ts`).
+    ❌ Rune treated as a value (`const s = $state; s(0)`).
+    ❌ Side effects inside `$derived`; allocating `$effect` without teardown.
+    ❌ Multiple `$props()` destructures or multiple instance `<script>` blocks in one component.
+    ❌ `$inspect` left in committed code as the only report channel for a contract-bearing state transition.
+  </Reward_Criteria>
+</Svelte5RunesRules>

package/dist/ai/directives/coding/sveltekit-rules.xml

@@ -0,0 +1,247 @@
+<SvelteKitRules keywords="sveltekit, fullstack, routing, load-functions, form-actions, server-client-boundary, hooks, adapters, ssr" type="coding-rules" ver="2.0">
+  <Mission>
+    Canonical rules for building SvelteKit fullstack applications. Every execution-agent MUST respect the server/client boundary, fetch data via `load` functions, mutate via form `actions`, and use file-based routing.
+
+    **Base axiom:** SvelteKit's value comes from a hard server/client boundary expressed through file naming (`+page.server.ts` is server-only; `+page.ts` is universal; `.svelte` is the client component). A file's name is its contract — leaking a secret across that boundary is a one-edit security failure that lints often do not catch. So every authoring decision starts from «which boundary owns this concern?», not from «where is this convenient?».
+
+    Scope: routing structure, data flow (load + actions), server hooks, page options, adapters. Out of scope: rune-level component authoring (covered by `svelte5-runes`) and TS-level conventions (covered by `typescript-rules`).
+  </Mission>
+
+  <Depends_On>
+    - ai/directives/coding/typescript-rules.xml
+    - ai/directives/coding/svelte5-runes.xml
+  </Depends_On>
+
+  <Belief_State>
+    <Axiom id="AX_SK_ROUTING_IS_FILE_BASED">
+      Routes are declared by directory structure under `src/routes/`. A path like `src/routes/user/[id]/+page.svelte` exposes `/user/:id`. Manual route tables, parallel router libraries, or imperative `Router` mounting are forbidden — they fork the source of truth for which URL renders what.
+
+      Layout wrappers via `+layout.svelte` / `+layout.server.ts` / `+layout.ts`. Nested layouts compose; siblings do not.
+    </Axiom>
+
+    <Axiom id="AX_SK_SERVER_CLIENT_BOUNDARY">
+      The file name decides where the code runs:
+      - `+page.server.ts`, `+layout.server.ts`, `hooks.server.ts`, anything under `$lib/server/` — **server-only**. Allowed to read filesystem, talk to databases, use private env.
+      - `+page.ts`, `+layout.ts`, `.svelte` (instance script + template) — **universal/client**. MUST be safe to ship to the browser.
+
+      Private secrets (`$env/static/private`, `$env/dynamic/private`) MUST NOT be imported from universal/client files. The toolchain refuses such imports at build time — agent's job is to keep the import graph clean from the start, not to rely on the compile error as the only guardrail.
+    </Axiom>
+
+    <Axiom id="AX_SK_DATA_VIA_LOAD">
+      Data needed to render a route is fetched in `load()` — universal in `+page.ts` / `+layout.ts`, server-only in `+page.server.ts` / `+layout.server.ts`. The return shape becomes `data` on the page (`let { data } = $props()`).
+
+      Forbidden as default: calling `fetch` from a component `<script>` to populate initial state. Component-level fetch loses SSR, breaks invalidation, and bypasses the server's privileged access. Reserved exception: client-only progressive updates that have NO server data dependency.
+    </Axiom>
+
+    <Axiom id="AX_SK_MUTATIONS_VIA_ACTIONS">
+      State mutations from the browser go through form `actions` in `+page.server.ts`: `export const actions = { default: async ({ request, cookies, locals, fetch }) => { ... } }`. The page submits `<form method="POST" use:enhance>` — progressive enhancement gives a working flow even without JavaScript.
+
+      `fetch('/api/...', { method: 'POST' })` from a component to mutate state is forbidden as the default path. It re-implements what actions already give (CSRF, redirect, validation result) and reintroduces the server/client boundary problem one route at a time.
+    </Axiom>
+
+    <Axiom id="AX_SK_VALIDATION_AT_ACTION_BOUNDARY">
+      Form actions validate request input synchronously at the top, return `fail(status, payload)` on rejection. The payload is exposed as `form` on the page (`let { form } = $props()`) and re-renders the form with the offending fields preserved. Throwing arbitrary errors from an action surfaces as a 500 with no recoverable UI state — `fail()` is the contract channel.
+    </Axiom>
+
+    <Axiom id="AX_SK_HOOKS_OWN_CROSS_CUTTING">
+      Cross-cutting server concerns (auth, request enrichment, error reporting) live in `src/hooks.server.ts` via `handle({ event, resolve })`. Auth context is attached to `event.locals` and read downstream by `load` / `actions`. `handleError({ error, event })` is the single point that maps unhandled exceptions to the user-facing shape.
+
+      Client-side cross-cutting goes in `src/hooks.client.ts`. Per-route boilerplate (re-checking auth in every `load`) is forbidden — `event.locals` is the contract for «who is the caller».
+    </Axiom>
+
+    <Axiom id="AX_SK_PAGE_OPTIONS_PER_ROUTE">
+      Page-level toggles (`export const ssr`, `export const prerender`, `export const csr`, `export const trailingSlash`) live in the route's `+page.ts` / `+page.server.ts` / `+layout.ts`. They are NOT global config in `svelte.config.js`.
+
+      Forcing `ssr = false` globally turns a SvelteKit app into a single-page app and discards most of the framework's value; doing it per-route documents the trade-off where it applies.
+    </Axiom>
+
+    <Axiom id="AX_SK_FETCH_FROM_LOAD_USES_SDK_FETCH">
+      Inside `load` / `actions`, use the `fetch` provided by SvelteKit's event (`async ({ fetch }) => ...`), not the global `fetch`. The event-provided `fetch` propagates credentials, runs in-process for internal API routes, and inherits the user's request context. Using global `fetch` from a server `load` is a silent loss of context.
+    </Axiom>
+
+    <Axiom id="AX_SK_TYPES_FROM_GENERATED">
+      Route-specific types come from generated `./$types` modules: `PageServerLoad`, `Actions`, `PageLoad`, `LayoutData`, etc. Hand-rolling these types is forbidden — they drift the first time the route signature changes. `App.Locals`, `App.PageData`, `App.Error`, `App.Platform` are declared in `src/app.d.ts` and are the only place to extend per-app surfaces.
+    </Axiom>
+
+    <Axiom id="AX_SK_ADAPTER_CHOSEN_NOT_DEFAULTED">
+      Production deployment requires an explicit adapter choice (`@sveltejs/adapter-node`, `@sveltejs/adapter-static`, platform-specific, etc.) configured in `svelte.config.js`. `adapter-auto` is acceptable only for greenfield prototypes; a production project that has not committed to an adapter has not committed to a deployment shape.
+    </Axiom>
+
+    <Axiom id="AX_SK_PROJECT_LAYOUT">
+      Canonical layout: `src/routes/` for routes, `src/lib/` for shared client+server code, `src/lib/server/` for server-only code, `src/hooks.server.ts` / `src/hooks.client.ts` for hooks, `src/app.html` for the HTML shell, `src/app.d.ts` for ambient types, `static/` for unprocessed assets. The `$lib` alias points to `src/lib`; `$lib/server` is automatically server-only.
+    </Axiom>
+  </Belief_State>
+
+  <Definitions>
+    <Definition id="DEF_UNIVERSAL_LOAD">
+      A `load` function exported from `+page.ts` / `+layout.ts`. Runs on the server during SSR AND in the client during navigation. MUST stay safe to bundle for the browser — no private env, no Node-only APIs.
+    </Definition>
+    <Definition id="DEF_SERVER_LOAD">
+      A `load` function exported from `+page.server.ts` / `+layout.server.ts`. Runs ONLY on the server. Has access to `cookies`, `locals`, private env, filesystem.
+    </Definition>
+    <Definition id="DEF_FORM_ACTION">
+      A handler exported under `actions` in `+page.server.ts`. Receives `request`, `cookies`, `locals`, `fetch`. Returns success payload or `fail(status, payload)`; may `redirect(status, location)`.
+    </Definition>
+  </Definitions>
+
+  <Code_Patterns>
+    <Pattern id="PT_SERVER_LOAD">
+      <Intent>Server-only data fetch with typed return surface.</Intent>
+      <Snippet language="typescript">
+        ```typescript
+        // src/routes/products/[id]/+page.server.ts
+        import { error } from '@sveltejs/kit';
+        import type { PageServerLoad } from './$types';
+
+        export const load: PageServerLoad = async ({ params, fetch, locals }) => {
+          const response = await fetch(`/api/products/${params.id}`);
+          if (!response.ok) {
+            throw error(404, 'Product not found');
+          }
+          const product = await response.json();
+          return { product, viewer: locals.user };
+        };
+        ```
+      </Snippet>
+      <Why>SDK-provided `fetch` preserves request context; `locals.user` populated by `hooks.server.ts`; `error()` returns the framework's recoverable error shape.</Why>
+    </Pattern>
+
+    <Pattern id="PT_FORM_ACTION_WITH_FAIL">
+      <Intent>Form action with synchronous validation and `fail()` for recoverable rejection.</Intent>
+      <Snippet language="typescript">
+        ```typescript
+        // src/routes/checkout/+page.server.ts
+        import { fail, redirect } from '@sveltejs/kit';
+        import type { Actions } from './$types';
+
+        export const actions = {
+          default: async ({ request, locals }) => {
+            const data = await request.formData();
+            const email = data.get('email')?.toString().trim();
+            if (!email) {
+              return fail(400, { email: '', error: 'Email is required' });
+            }
+            await locals.checkout.placeOrder({ email });
+            throw redirect(303, '/checkout/done');
+          },
+        } satisfies Actions;
+        ```
+      </Snippet>
+      <Why>`fail()` re-renders the page with `form` populated; `redirect()` is the success channel; validation is synchronous and at the top.</Why>
+    </Pattern>
+
+    <Pattern id="PT_SERVER_HOOK_AUTH">
+      <Intent>Server hook injecting auth context into `event.locals`.</Intent>
+      <Snippet language="typescript">
+        ```typescript
+        // src/hooks.server.ts
+        import type { Handle } from '@sveltejs/kit';
+        import { decodeSession } from '$lib/server/session';
+
+        export const handle: Handle = async ({ event, resolve }) => {
+          const token = event.cookies.get('session');
+          event.locals.user = token ? await decodeSession(token) : null;
+          return resolve(event);
+        };
+        ```
+      </Snippet>
+      <Why>`$lib/server/session` is automatically server-only; `event.locals.user` becomes the single contract for «who is the caller» downstream.</Why>
+    </Pattern>
+
+    <Pattern id="PT_PAGE_CONSUMING_LOAD">
+      <Intent>Route page reading `data` from a server load via `$props()`.</Intent>
+      <Snippet language="svelte">
+        ```svelte
+        <!-- src/routes/products/[id]/+page.svelte -->
+        <script lang="ts">
+          import type { PageData } from './$types';
+          let { data }: { data: PageData } = $props();
+        </script>
+
+        <h1>{data.product.name}</h1>
+        <p>Viewer: {data.viewer?.email ?? 'anonymous'}</p>
+        ```
+      </Snippet>
+      <Why>Component receives `data` via `$props()` (single Svelte 5 destructure); the `PageData` type is generated by SvelteKit from the matching server load.</Why>
+    </Pattern>
+  </Code_Patterns>
+
+  <Anti_Patterns>
+    <Anti_Pattern id="AP_SK_COMPONENT_FETCH_FOR_INITIAL_DATA">
+      <Bad>Inside `+page.svelte`: `$effect(() => { fetch('/api/products').then(r => r.json()).then(items => products = items); });` to populate the initial product list.</Bad>
+      <Why_Bad>Component-level fetch for initial data (`AX_SK_DATA_VIA_LOAD`). Loses SSR (page renders empty, then flickers), bypasses framework `invalidate()` / `depends()`, runs in the browser only — server-side rendering benefit gone. Cannot use private credentials or `locals`.</Why_Bad>
+      <Good>Move fetch into `+page.server.ts`: `export const load: PageServerLoad = async ({ fetch }) => ({ products: await (await fetch('/api/products')).json() });`. Component reads `data.products` via `$props()`.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_SK_PRIVATE_ENV_IN_CLIENT">
+      <Bad>`+page.ts` (universal) starts with `import { DATABASE_URL } from '$env/static/private';`.</Bad>
+      <Why_Bad>Private env imported into a universal/client module (`AX_SK_SERVER_CLIENT_BOUNDARY`). Build refuses to bundle it; even if it slipped through (e.g., via dynamic require), the secret would be shipped to the browser bundle. Boundary violation is a security failure, not a stylistic one.</Why_Bad>
+      <Good>Move the consumer to `+page.server.ts` or `$lib/server/...`; expose only the derived value the client legitimately needs through the load return.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_SK_THROW_INSTEAD_OF_FAIL">
+      <Bad>In a form action: `if (!email) throw new Error('Email required');`</Bad>
+      <Why_Bad>Action throws instead of returning `fail()` (`AX_SK_VALIDATION_AT_ACTION_BOUNDARY`). Surfaces as a 500 with the framework's error page; the form loses its inputs; the user has no recoverable UI state. `fail()` is the contract channel for recoverable validation rejection.</Why_Bad>
+      <Good>`return fail(400, { email: '', error: 'Email is required' });` — page re-renders with `form.error` visible and inputs preserved.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_SK_GLOBAL_FETCH_IN_LOAD">
+      <Bad>Inside `+page.server.ts`: `const res = await fetch('http://localhost:3000/api/products');` (the global `fetch`).</Bad>
+      <Why_Bad>Global `fetch` from a server load (`AX_SK_FETCH_FROM_LOAD_USES_SDK_FETCH`). Loses request context (cookies, headers), forces a real network hop for internal API routes that SvelteKit would have resolved in-process, and hard-codes the origin.</Why_Bad>
+      <Good>Destructure the SDK-provided `fetch`: `export const load: PageServerLoad = async ({ fetch }) => { const res = await fetch('/api/products'); ... };`. Relative URLs resolve to the current origin; cookies propagate.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_SK_PAGE_OPTIONS_GLOBALIZED">
+      <Bad>`svelte.config.js` sets `kit: { prerender: { entries: ['*'] }, csr: false }` to disable SSR/CSR project-wide.</Bad>
+      <Why_Bad>Page options globalized into framework config (`AX_SK_PAGE_OPTIONS_PER_ROUTE`). Discards per-route trade-offs — a marketing landing page that benefits from prerender forces the same on dynamic dashboards. Hidden behavior at the framework level surprises every later contributor.</Why_Bad>
+      <Good>Per-route in the relevant `+page.ts`: `export const prerender = true;` for static pages; leave dynamic routes default.</Good>
+    </Anti_Pattern>
+  </Anti_Patterns>
+
+  <Verification_Hooks>
+    <Hook id="HOOK_SK_TYPECHECK">
+      <Purpose>Generate route types and run Svelte-aware type-check; catches private-env-in-client violations.</Purpose>
+      <Command>npx svelte-kit sync && npx svelte-check --tsconfig ./tsconfig.json</Command>
+      <Expected>Exit 0; no errors.</Expected>
+    </Hook>
+    <Hook id="HOOK_SK_BUILD">
+      <Purpose>Production build verifies SSR, adapter, and boundary violations the dev server tolerates.</Purpose>
+      <Command>npm run build</Command>
+      <Expected>Exit 0.</Expected>
+    </Hook>
+    <Hook id="HOOK_SK_NO_PRIVATE_ENV_IN_CLIENT">
+      <Purpose>Smoke-grep for private env imported from universal/client files.</Purpose>
+      <Command>find src -type f \( -name '*.svelte' -o -name '+page.ts' -o -name '+layout.ts' \) -print0 | xargs -0 grep -nE "\\\$env/(static|dynamic)/private" || true</Command>
+      <Expected>Empty output. Matches must move to `+page.server.ts` / `+layout.server.ts` / `$lib/server/`.</Expected>
+    </Hook>
+    <Hook id="HOOK_SK_NO_GLOBAL_FETCH_IN_LOAD">
+      <Purpose>Smoke-grep for likely global `fetch(` in server load files (manual review of matches).</Purpose>
+      <Command>find src/routes -type f \( -name '+page.server.ts' -o -name '+layout.server.ts' \) -print0 | xargs -0 grep -nE '(^|[^.])fetch\(' || true</Command>
+      <Expected>For each match: confirm it is the SDK-provided `fetch` destructured from the load event, not the global `fetch`.</Expected>
+    </Hook>
+    <Hook id="HOOK_SK_NO_CLIENT_FETCH_IN_COMPONENT">
+      <Purpose>Detect direct `fetch('/api/...')` calls inside `.svelte` files used to populate initial data.</Purpose>
+      <Command>find src/routes -name '*.svelte' -print0 | xargs -0 grep -nE "fetch\(['\"]/" || true</Command>
+      <Expected>Each match must be either an explicit progressive-update path with no server data dependency, or migrated to a `load` function.</Expected>
+    </Hook>
+  </Verification_Hooks>
+
+  <Reward_Criteria>
+    ✅ Data fetched via `load` (server or universal); component-level fetch reserved for genuine progressive updates.
+    ✅ Mutations go through form `actions` with `<form method="POST" use:enhance>`; recoverable rejection via `fail()`; success via `redirect()`.
+    ✅ Server/client boundary respected by file naming; private env imported only in server-only files.
+    ✅ SDK-provided `fetch` used inside `load` / `actions`; global `fetch` not used for in-app routes.
+    ✅ Cross-cutting auth/request enrichment in `hooks.server.ts`; downstream code reads `event.locals` only.
+    ✅ Page options (`ssr`, `prerender`, `csr`) per-route, not globalized.
+    ✅ Route types from `./$types`; ambient types in `src/app.d.ts`.
+    ✅ Explicit adapter chosen for production builds.
+
+    ❌ Component-level fetch to populate initial render data.
+    ❌ Private env (`$env/static/private`, `$env/dynamic/private`) imported in `+page.ts` / `+layout.ts` / `.svelte`.
+    ❌ Form action throwing arbitrary errors instead of returning `fail()`.
+    ❌ Global `fetch` used inside a load / action when the SDK `fetch` is available.
+    ❌ Page options globalized in `svelte.config.js`.
+    ❌ Hand-rolled route types; bypassing `App.Locals` / `App.PageData` for ambient extensions.
+    ❌ Production build relying on `adapter-auto`.
+  </Reward_Criteria>
+</SvelteKitRules>