@gallopsystems/agent-skills 1.5.0 → 1.6.0

package/plugins/vue-nuxt/skills/vue-nuxt/composables.md

@@ -0,0 +1,95 @@
+# Authoring a composable
+
+How to *write* a composable's reactive surface. The **decision** of composable vs
+plain util lives in `nuxt-nitro-api/composables-utils.md` (logic that touches Vue
+reactivity/lifecycle → composable; pure transform → util). This file is the
+Vue-shaped mechanics: argument shape, what to return, and cleanup.
+
+## Accept ref-or-getter-or-value; normalize with `toValue`
+
+A reactive input should accept a plain value, a `ref`, **or** a getter — typed
+`MaybeRefOrGetter<T>` and read through `toValue()` inside the effect. Don't branch
+on `isRef`/`unref`, and don't read `.value` once at the top (that snapshots and
+loses reactivity):
+
+```ts
+import { toValue, type MaybeRefOrGetter } from 'vue'
+
+export function useDoubled(input: MaybeRefOrGetter<number>) {
+  // re-reads through toValue on every recompute → tracks input if it's reactive
+  return computed(() => toValue(input) * 2)   // caller passes 3, ref(3), or () => count.value
+}
+```
+
+`toValue(x)` returns `x` for a plain value, `x.value` for a ref, `x()` for a
+getter. This is the VueUse-shaped contract and the single biggest "make a
+composable ergonomic" move — callers shouldn't have to wrap a literal in `ref()`
+just to call you.
+
+## Return a plain object of refs — not `reactive()`
+
+Return refs/computeds in a **plain object**. A caller destructures the result, and
+a plain object of refs survives destructuring; a `reactive()` return does not (the
+properties detach into plain values). See [reactivity.md](./reactivity.md) for the
+`ref`-over-`reactive` rule this mirrors.
+
+```ts
+export function usePager(total: MaybeRefOrGetter<number>) {
+  const page = ref(1)
+  const atEnd = computed(() => page.value >= toValue(total))
+  return { page, atEnd }            // ✅ const { page } = usePager(n) stays reactive
+  // ❌ return reactive({ page, atEnd })  → const { page } = … is a dead number
+}
+```
+
+## Thin composable: pure core, reactive shell
+
+Keep business logic in plain functions (no Vue import — trivially unit-testable,
+no Nuxt context needed) and let the composable be a thin reactive wrapper that
+wires that logic to `ref`/`computed`. This is "functional core, imperative shell"
+applied to composables, and it matters here specifically: plain `*.test.ts` files
+**don't** get Nuxt's auto-import context (see [auto-imports.md](./auto-imports.md)),
+so pure functions test without `mountSuspended`.
+
+```ts
+// core.ts — pure, no Vue, unit-test directly
+export const clampPage = (p: number, total: number) => Math.min(Math.max(p, 1), total)
+
+// usePager.ts — thin shell
+export function usePager(total: MaybeRefOrGetter<number>) {
+  const page = ref(1)
+  return { page, go: (p: number) => (page.value = clampPage(p, toValue(total))) }
+}
+```
+
+## Clean up with `onScopeDispose` — not only `onUnmounted`
+
+A composable that starts a listener/timer/observer must tear it down. Inside a
+composable, register cleanup with **`onScopeDispose`** rather than `onUnmounted`:
+it fires on component unmount too, but *also* works when the composable runs in a
+detached `effectScope()` (a shared singleton, a manually-stopped scope) where
+there's no component instance and `onUnmounted` would silently no-op.
+
+```ts
+export function useNow(intervalMs = 1000) {
+  const now = ref(Date.now())
+  const id = setInterval(() => (now.value = Date.now()), intervalMs)
+  onScopeDispose(() => clearInterval(id))   // fires on unmount OR scope.stop()
+  return { now }
+}
+```
+
+For a composable that itself creates watchers/computeds you want to dispose as a
+unit (a store you stand up and tear down by hand), wrap them in an
+**`effectScope()`** and stop the whole scope at once:
+
+```ts
+const scope = effectScope()
+scope.run(() => { /* watchers/computeds created here */ })
+// later: scope.stop()  → disposes every effect created inside, and runs onScopeDispose
+```
+
+`useTemplateRef`, `MaybeRefOrGetter`, and the "return refs" rule together let a
+composable own DOM refs and reactive inputs internally instead of demanding the
+caller thread them in — see [reactivity.md](./reactivity.md) and
+[component-authoring.md](./component-authoring.md).

package/plugins/vue-nuxt/skills/vue-nuxt/reactivity.md

@@ -0,0 +1,133 @@
+# Reactivity gotchas
+
+Derivation, prop sync, DOM measurement, remounting, and cleanup. For the
+`watch`-vs-`computed` decision and the `watch` smell catalog, see
+[watch.md](./watch.md).
+
+## Keep computed getters pure
+
+A `computed` getter derives and returns — nothing else. Mutating another ref/Set,
+firing an async request, or touching the DOM inside a getter makes it
+order-dependent, can re-trigger itself, and is undebuggable. Move side effects to
+a `watch` or an event handler. (And never mutate a computed's *return* value —
+it's a read-only snapshot; update the source state instead.)
+
+## Mutate a ref's object in place — don't reassign
+
+When a ref's object is bound to `v-model` inputs, update it **in place**;
+reassigning a fresh literal swaps the proxied target the template tracks, and
+later programmatic writes to the old reference are lost:
+
+```ts
+// ❌ form.value = { ...next }      // swaps the tracked proxy
+// ✅
+Object.assign(form.value, next)     // or per-key assignment
+```
+
+## Default to `ref`; reach for `reactive` rarely
+
+`ref` is the default for all state. Use `reactive` only to **group** tightly
+related fields or to wrap a non-Vue object (`Map`/`Set`). `reactive`'s traps are
+why: it loses reactivity when **destructured** (the keys become plain values —
+`toRefs` to recover) and when **reassigned wholesale** (the proxy identity swaps).
+A `ref` has neither problem — `.value` is always the live cell.
+
+```ts
+const state = reactive({ count: 0 })
+const { count } = state          // ❌ plain number now, not reactive
+const { count } = toRefs(state)  // ✅ if you must destructure a reactive
+// Rule: default ref(); reactive() only to group state or wrap Map/Set.
+```
+
+## Template refs: prefer `useTemplateRef`
+
+To reach a DOM element or child component, use **`useTemplateRef('name')`** (Vue
+3.5 / Nuxt 4) — pass the string that matches `ref="name"` in the template. It
+self-documents that the value is an element/component handle, infers the type, and
+lets a composable own the ref internally. The legacy "declare `const el =
+ref(null)` whose variable name must match `ref="el"`" form still works but is
+fragile to rename drift — prefer `useTemplateRef` in new code.
+
+```ts
+const input = useTemplateRef('input')          // <input ref="input">
+onMounted(() => input.value?.focus())
+// v-for: useTemplateRef returns an ARRAY, and its order is NOT guaranteed —
+// key/sort yourself rather than trusting index alignment.
+```
+
+## DOM-measured computeds need a re-measure signal
+
+DOM size isn't reactive, so a `computed` reading live geometry
+(`offsetLeft`/`offsetWidth`) won't recompute on resize or a breakpoint flip. Add
+an explicit version ref and bump it from a `ResizeObserver`:
+
+```ts
+const container = useTemplateRef('container')   // <div ref="container">
+const layoutVersion = ref(0)
+let ro: ResizeObserver | null = null
+onMounted(() => { ro = new ResizeObserver(() => layoutVersion.value++); ro.observe(container.value!) })
+onBeforeUnmount(() => ro?.disconnect())
+
+const indicator = computed(() => {
+  void layoutVersion.value          // subscribe to re-measure
+  const b = buttons.value[active.value]
+  return b ? { left: `${b.offsetLeft}px`, width: `${b.offsetWidth}px` } : { left: '0px', width: '0px' }
+})
+```
+
+Measure conditionally-mounted elements only **after `await nextTick()`** (and hold
+them via a null-guarded template ref) — right after toggling `visible`, the
+element isn't laid out and a sync `getBoundingClientRect()` reads 0.
+
+## React to prop changes with a watch on a getter
+
+Props aren't directly watchable — watch a getter, and seed local state with
+`{ immediate: true }`:
+
+```ts
+watch(() => props.thing, (next) => { local.value = next }, { immediate: true })
+```
+
+The legitimate prop→local case is **owning an editable draft**: a parent owns
+server data via `useFetch` (keep `refresh`), passes it as a prop; the child clones
+it into a local draft (`structuredClone(toRaw(prop))`), re-syncs on a watch of the
+prop, and emits `@saved`/`@updated` so the parent re-fetches. Copy into local
+state — never mutate the prop. (A bare `local = ref(props.x)` + sync watch with no
+emit-back is the `prop-sync` smell — use `defineModel`; see [v-model.md](./v-model.md).)
+
+## Remount on identity change with `:key`
+
+```vue
+<UserDetail :key="route.params.id" :id="route.params.id" />
+```
+
+Bind `:key` to the **identifying value** so the component remounts cleanly when
+identity changes. Do NOT abuse an incrementing `:key="bump++"` to force a data
+re-pull — that destroys child state/scroll; use a watcher or `refresh()` instead.
+When a *full remount* genuinely is the goal (reset all of a child's internal
+state), bumping `:key` is the right tool — and `$forceUpdate()` is the wrong one
+(it re-renders but skips computeds and bypasses the reactivity graph; if you
+"need" it, you have a reactivity bug to fix instead).
+
+## Always pair setup with teardown
+
+Anything started in `onMounted` — `addEventListener`, `setInterval`,
+`ResizeObserver`, `MutationObserver` — must be torn down in
+`onUnmounted`/`onBeforeUnmount` (`removeEventListener`, `clearInterval`,
+`disconnect`). Keep the handle in a module-scope `let` so teardown can reach it.
+Inside a **composable**, register teardown with `onScopeDispose` instead so it
+also fires for a detached `effectScope` — see [composables.md](./composables.md).
+
+## `shallowRef` for large or wholesale-replaced data
+
+Deep reactivity has a cost: `ref`/`reactive` recursively proxy every nested
+property. For a large list, a third-party class instance (a `Map`, an editor/map
+object you drive imperatively), or data you always **replace wholesale** rather
+than mutate, use `shallowRef` (or `shallowReactive`) — only `.value` reassignment
+triggers, nested mutation does not.
+
+```ts
+const rows = shallowRef<Row[]>([])
+rows.value = [...rows.value, next]   // ✅ replace .value — triggers
+// rows.value.push(next)             // ❌ no trigger under shallowRef (use triggerRef if you must mutate)
+```

package/plugins/vue-nuxt/skills/vue-nuxt/slots.md

@@ -0,0 +1,139 @@
+# Slots & reusability
+
+Slots are how a component accepts **markup** from its caller. Reach for a slot
+whenever a component is a *container* for caller-provided content — cards, panels,
+menus, layouts, list rows, buttons.
+
+## Slots beat props for markup and open-endedness
+
+A prop can carry a string, but not a chunk of markup, and it forces you to
+pre-plan every variant. If a `<Button>` takes `type: 'primary' | 'secondary'`, a
+caller can't add a third look without you editing `Button`. A slot is
+open-ended — the caller passes whatever they need:
+
+```vue
+<!-- ❌ prop must anticipate every case -->
+<Button label="Save" type="primary" />
+<!-- ✅ slot accepts any content -->
+<Button @click="save">Save <Spinner v-if="saving" /></Button>
+```
+
+Rule of thumb: **prop for data, slot for markup.** If you find yourself adding a
+prop just to toggle a bit of caller-specific UI, that UI belongs in a slot.
+
+## Named slots + the `#` shorthand
+
+```vue
+<!-- Card.vue -->
+<template>
+  <article>
+    <header><slot name="header" /></header>
+    <slot />                <!-- default slot -->
+    <footer><slot name="footer" /></footer>
+  </article>
+</template>
+
+<!-- caller -->
+<Card>
+  <template #header><h2>Title</h2></template>   <!-- #header == v-slot:header -->
+  Body content goes in the default slot.
+  <template #footer><Button>OK</Button></template>
+</Card>
+```
+
+## Fallback (default) content
+
+Content between the `<slot>` tags renders when the caller provides nothing:
+
+```vue
+<slot name="empty">No results yet.</slot>
+```
+
+## Scoped slots — the mental model
+
+A scoped slot is **a function the parent supplies that returns markup; the child
+calls it with data.** The child exposes values by binding them on `<slot>`; the
+caller receives them via the slot prop:
+
+```vue
+<!-- List.vue — child owns iteration, caller owns each row's markup -->
+<template>
+  <ul>
+    <li v-for="item in items" :key="item.id">
+      <slot :item="item" :index="index" />   <!-- expose data to the slot -->
+    </li>
+  </ul>
+</template>
+
+<!-- caller -->
+<List :items="invoices">
+  <template #default="{ item }">
+    <strong>{{ item.number }}</strong> — {{ item.total }}
+  </template>
+</List>
+```
+
+This is the core reusability move: the child encapsulates *logic* (fetching,
+iterating, state) while the caller decides *presentation*.
+
+## Typing & inspecting slots (Composition API)
+
+- **Type** the slots a component accepts with `defineSlots` (compile-time only,
+  like `defineProps`):
+
+  ```ts
+  defineSlots<{
+    default(props: { item: Invoice; index: number }): any
+    header(): any
+  }>()
+  ```
+
+- **Inspect** which slots the caller actually passed with `useSlots()` — use it to
+  avoid rendering an empty wrapper:
+
+  ```vue
+  <script setup lang="ts">
+  const slots = useSlots()
+  </script>
+  <template>
+    <!-- only render the styled footer wrapper if a footer slot was given -->
+    <footer v-if="slots.footer" class="border-t p-4"><slot name="footer" /></footer>
+  </template>
+  ```
+
+  (In a template you can also test `$slots.footer` directly.) Without the guard
+  you ship an empty `<footer>` whose padding/border still affects layout.
+
+## Forwarding & splitting slots
+
+- **Forward** a slot through a wrapper so the inner component receives it:
+
+  ```vue
+  <Inner>
+    <template v-for="(_, name) in $slots" #[name]="scope">
+      <slot :name="name" v-bind="scope" />
+    </template>
+  </Inner>
+  ```
+
+- **Split** one incoming slot into two render positions by branching with `v-if`
+  on a condition, each `<slot>` keeping its own fallback.
+
+## Slot transitions need keyed content
+
+Wrapping a `<slot>` in `<Transition>` only animates if the slotted content is
+**keyed**, so Vue can tell one state from the next:
+
+```vue
+<Transition name="fade" mode="out-in">
+  <component :is="current" :key="current" />
+</Transition>
+```
+
+## Reusable ≠ big
+
+Small components are worth extracting too. A three-line `OverflowMenu` that always
+pairs the same trigger icon + a11y wiring is worth a component: every use stays
+identical, and a change happens in one place. Extract the genuinely shared
+surface; leave caller-specific chrome in the caller (see the "what to extract"
+note in [component-authoring.md](./component-authoring.md)).

package/plugins/vue-nuxt/skills/vue-nuxt/template-idioms.md

@@ -0,0 +1,142 @@
+# Template & vue-tsc idioms
+
+Smaller Vue-shaped template patterns and the compile errors they prevent.
+
+## Never two handlers of the same event on one element
+
+Two `@keyup.*` (or two `@keydown.*`) modifier handlers on one element both compile
+to a single `onKeyup` object property → vue-tsc fails with **TS1117 "duplicate
+property"**, and only one wires up at runtime. Use a single handler and branch:
+
+```vue
+<!-- ❌ <input @keyup.enter="submit" @keyup.esc="cancel" /> -->
+<input @keyup="onKey" />
+<!-- function onKey(e) { if (e.key === 'Enter') submit(); else if (e.key === 'Escape') cancel() } -->
+```
+
+## Scoped-CSS reach: `:deep()`, `:slotted()`, `:global()`
+
+Scoped CSS adds a data attribute that only matches the component's own elements.
+Three pseudo-selectors reach past that boundary:
+
+```vue
+<style scoped>
+.prose :deep(table) { @apply w-full; } /* child/3rd-party-rendered HTML (markdown, rich text) */
+:slotted(p) { @apply mt-2; }            /* content the PARENT passed into a <slot> */
+:global(body) { @apply antialiased; }   /* escape scope to a global rule */
+</style>
+```
+
+`:deep()` for descendants the component renders dynamically, `:slotted()` for
+slot content the caller supplied (scoped styles don't reach it by default), and
+`:global()` for the occasional global rule without a second `<style>` block.
+
+## Click-outside: match a unique marker class
+
+Scope document click-outside detection to a **purpose-named marker class** added
+solely for it — never `target.closest('.relative.flex')` or other structural
+Tailwind selectors that silently match unrelated elements:
+
+```vue
+<div class="send-menu relative …">
+<!-- if (!e.target.closest('.send-menu')) close() -->
+```
+
+## `<NuxtLink>` and a thin `app.vue`
+
+Use `<NuxtLink to="…">` for internal navigation (client routing + prefetch), not a
+raw `<a>`. Keep `app.vue` a thin shell — `<NuxtLayout><NuxtPage /></NuxtLayout>`
+plus app-global hosts (a `<Toast />`, a confirm dialog). `NuxtLink`/`NuxtLayout`/
+`NuxtPage` are auto-imported.
+
+## Per-page `<head>` with `useHead`
+
+Set the document title/head reactively and SSR-safely with `useHead` in
+`<script setup>` — never `document.title`. Set a default in `app.vue` and override
+per page:
+
+```ts
+useHead({ title: 'Invoices' })            // page
+// app.vue: useHead({ titleTemplate: (t) => (t ? `${t} · Acme` : 'Acme') })
+```
+
+## Reset a file input after reading it
+
+`<input type="file">` won't re-fire `change` for the same file twice — clear it
+after handling so re-selecting the same file works:
+
+```ts
+function onFile(e: Event) { const t = e.target as HTMLInputElement; /* …read t.files… */ t.value = '' }
+```
+
+## Status → label/severity lookup
+
+Map enums to labels/severities with a small `Record` lookup + `||` fallback,
+called as a plain function (functions, not `computed`, when they take a per-row
+argument):
+
+```ts
+const SEV: Record<Status, string> = { paid: 'success', overdue: 'danger' }
+const sev = (s: Status) => SEV[s] || 'secondary'
+```
+
+## `v-bind` same-name shorthand
+
+When a bound attribute matches the variable name (Vue 3.4+), drop the value —
+`:src` expands to `:src="src"`. Terser, and worth recognizing when reading code:
+
+```vue
+<img :src :alt />   <!-- ≡ :src="src" :alt="alt" -->
+```
+
+## `useId()` for stable, SSR-safe element IDs
+
+Wiring `<label for>` / `aria-describedby` needs an ID that's stable across SSR and
+hydration — a hand-rolled counter or `Math.random()` causes a hydration mismatch.
+`useId()` (Vue 3.5, auto-imported) gives an app-unique, hydration-stable ID:
+
+```ts
+const id = useId()   // <label :for="id">Email</label> <input :id :aria-describedby="`${id}-help`">
+```
+
+## `<Teleport>` overlays out to `body`
+
+Render modals/dropdowns/toasts to `<body>` so they escape a parent's
+`overflow: hidden`, `z-index`, or `transform` stacking context (the usual cause of
+a dialog clipped inside a scrolling panel):
+
+```vue
+<Teleport to="body"><div class="modal">…</div></Teleport>
+```
+
+`<Teleport>` is auto-imported. (Volt/PrimeVue overlays already teleport
+internally; this is for your own hand-rolled overlays.)
+
+## `<KeepAlive>` caches toggled-component state
+
+Wrap a dynamic `<component>`/`v-if` swap in `<KeepAlive>` to preserve a toggled
+child's state (a half-filled form, scroll position) instead of remounting it.
+Teardown gotcha: a cached component fires `onActivated`/`onDeactivated`, **not**
+`onMounted`/`onUnmounted` — put pause/resume logic there, not in the mount hooks:
+
+```vue
+<KeepAlive :include="['EditForm']"><component :is="currentTab" /></KeepAlive>
+```
+
+## `v-memo` / `v-once` for expensive render subtrees
+
+Declarative render-skipping for big lists/tables. `v-once` renders a subtree once
+and never updates it; `v-memo="[deps]"` skips a `v-for` row's re-render unless a
+dep changes. Reach for these only when a large grid actually shows up in a profile
+— not by default.
+
+```vue
+<div v-for="row in rows" :key="row.id" v-memo="[row.id === selectedId]">…</div>
+```
+
+## One-off caveats (not general conventions)
+
+These surfaced once each — apply only if they bite, don't treat as rules:
+
+- **Confirm which motion library is installed** before animating: `motion-v` uses the component API (`<motion.div :initial :animate>`), while `@vueuse/motion` uses the `v-motion` directive (`:visible-once`). They're different packages.
+- **A parent's `whitespace-nowrap`** (common on table `th`/`td`) is inherited by a child tooltip/popover and forces it onto one overflowing line — reset with `whitespace-normal break-words` on the bubble.

package/plugins/vue-nuxt/skills/vue-nuxt/v-model.md

@@ -0,0 +1,106 @@
+# `v-model` on components
+
+Two sanctioned patterns for two-way binding. Default to `defineModel` for new
+code; the computed-proxy is for forwarding an existing component's model.
+
+## `defineModel` — preferred (Vue 3.4+ / Nuxt 4)
+
+```ts
+const model = defineModel<boolean>()                              // parent: v-model
+const visible = defineModel<boolean>('visible', { required: true }) // parent: v-model:visible
+```
+
+Read/write `model.value` directly — no `props` + `emit` boilerplate. Give
+non-primitive models a factory default like any prop.
+
+**Named models** give one component multiple independent two-way bindings:
+
+```ts
+const years = defineModel<string>('years')
+const months = defineModel<string>('months')
+// parent: <DurationInput v-model:years="y" v-model:months="m" />
+```
+
+**Transform on the boundary with `get`/`set`.** For a component's *own* model,
+`defineModel` takes `get`/`set` transformers directly — no separate writable
+`computed` needed (reserve that for forwarding *someone else's* model, below):
+
+```ts
+const model = defineModel<string>({ get: (v) => v.toUpperCase(), set: (v) => v.trim() })
+```
+
+**Custom `v-model` modifiers** (`v-model.capitalize`) arrive via the
+`[model, modifiers]` tuple:
+
+```ts
+const [model, modifiers] = defineModel<string>({
+  set: (v) => (modifiers.capitalize ? v[0].toUpperCase() + v.slice(1) : v),
+})
+```
+
+## The computed-proxy — for forwarding an existing model
+
+When you wrap a component that already has its own `v-model` (a Volt/PrimeVue
+`Dialog`'s `visible`, say), or you need a named local handle or a value
+transform, use a writable `computed` over `props` + `emit`:
+
+```ts
+const props = defineProps<{ visible: boolean }>()
+const emit = defineEmits<{ 'update:visible': [v: boolean] }>()
+const visible = computed({ get: () => props.visible, set: (v) => emit('update:visible', v) })
+//   <Dialog v-model:visible="visible" />
+```
+
+A `computed({ get, set })` transforms a *forwarded* value shape (date string ↔
+`Date`) before writing back — for a component's **own** model, prefer
+`defineModel`'s `get`/`set` (above) over a separate computed. Either way, do NOT
+reach for two mirror `watch`es to do this; that's the `prop-sync` smell (see
+[watch.md](./watch.md)).
+
+## Mutually-exclusive paired fields
+
+When setting one field must clear its sibling, expose **two** typed `update:`
+events and bind the inner widget with `:modelValue` + `@update:modelValue` (NOT
+`v-model`) so your handler can emit one update and null the other in the same tick:
+
+```ts
+const emit = defineEmits<{ 'update:years': [v: string | null]; 'update:months': [v: string | null] }>()
+function setYears(v: string) { emit('update:years', v); emit('update:months', null) }
+```
+
+A single `v-model` can't express "set A, clear B" atomically.
+
+## Controlled / uncontrolled: work standalone OR be parent-driven
+
+For a component that should manage its own state **unless** a parent supplies the
+value (a toggle that works alone but a parent can override), detect whether the
+control prop was passed and fall back to internal state per render:
+
+```ts
+const props = defineProps<{ open?: boolean }>()        // undefined ⇒ uncontrolled
+const emit = defineEmits<{ 'update:open': [v: boolean] }>()
+const internal = ref(false)
+const controlled = computed(() => props.open !== undefined)
+const open = computed(() => (controlled.value ? props.open! : internal.value))
+function toggle() {
+  if (controlled.value) emit('update:open', !props.open)
+  else internal.value = !internal.value
+}
+```
+
+This relies on `undefined` meaning "unset", so the control prop must **not** be a
+bare `boolean` (the Boolean-casting trap coerces absent → `false`; see
+[component-authoring.md](./component-authoring.md)) — type it `boolean | undefined`
+and give it no `withDefaults` default.
+
+## Reset / lazy-load on open
+
+To reset transient state or lazy-load when a dialog opens, **watch the bound
+flag** (it covers every close path — overlay click, ESC, programmatic) — see the
+"re-seed local state on dialog open" case in [watch.md](./watch.md).
+
+## Consistency caveat
+
+A repo with hundreds of `props`+`emit`+`computed` `v-model`s and zero
+`defineModel` means matching the manual pattern in that file. Introduce
+`defineModel` deliberately, not as a drive-by in an otherwise-consistent file.