@voltro/cli 0.16.0 → 0.17.0

package/templates/agent-docs/templates/appshells.md

@@ -39,7 +39,7 @@ apps/acme/web/                          # dir named by the app, not the template
 
 ## The page
 
-`src/pages/index.page.tsx` is plain JSX with the two static-render exports:
+`src/pages/page.tsx` is plain JSX with the two static-render exports:
 
 ```tsx
 export const renderMode  = 'static' as const   // pre-render at build time
@@ -59,7 +59,7 @@ export default function Index() {
       </section>
       <section>
         <h2>Ready to start?</h2>
-        <p>Edit <code>src/pages/index.page.tsx</code> to make it yours.</p>
+        <p>Edit <code>src/pages/page.tsx</code> to make it yours.</p>
       </section>
     </main>
   )
@@ -80,7 +80,7 @@ export default island(SignupForm, { name: 'SignupForm', hydrate: 'visible' })
 ```
 
 ```tsx
-// src/pages/index.page.tsx
+// src/pages/page.tsx
 export const interactive = 'islands' as const   // was 'none'
 import SignupForm from '../components/SignupForm.island'
 // … render <SignupForm /> somewhere in the page …
@@ -185,7 +185,7 @@ If your final product is going to be a:
 
 _A documentation site with a catch-all docs router and build-time static pre-rendering of every page via getStaticPaths._
 
-A documentation-site starter. `src/pages/docs/[...slug].page.tsx` is a catch-all router; `getStaticPaths` enumerates every doc URL at build time so `voltro build` pre-renders them all into a static site you can deploy anywhere. Template id: **`frontend-docs`**.
+A documentation-site starter. `src/pages/docs/[...slug]/page.tsx` is a catch-all router; `getStaticPaths` enumerates every doc URL at build time so `voltro build` pre-renders them all into a static site you can deploy anywhere. Template id: **`frontend-docs`**.
 
 The starter ships a tiny in-file `DOCS` array as stub content. Replace it with a real loader (a markdown reader, a CMS query, a database fetch) — the page component's contract stays the same.
 
@@ -215,7 +215,7 @@ apps/acme/docs/                         # dir named by the app, not the template
 
 ## The catch-all renderer
 
-`src/pages/docs/[...slug].page.tsx` is the whole engine. It declares:
+`src/pages/docs/[...slug]/page.tsx` is the whole engine. It declares:
 
 ```tsx
 export const renderMode  = 'static' as const   // pre-render at build
@@ -418,7 +418,7 @@ No rpc client, no loader, no `apis:` entry, no `@voltro/ui-shadcn` dependency. T
 The page exports `renderMode = 'spa'`, which tells `voltro build` not to pre-render it: the client renders it on load. Use this when the whole page is interactive AND its state lives in the browser — an SSR'd first paint would just be discarded on hydration, so rendering it on the server buys nothing.
 
 ```tsx
-// src/pages/index.page.tsx — a pure client-side SPA (a bill splitter)
+// src/pages/page.tsx — a pure client-side SPA (a bill splitter)
 import type { ReactNode } from 'react'
 import { useEffect, useState } from 'react'
 
@@ -603,7 +603,7 @@ The full reference for these modes lives in the [render modes guide](/docs/routi
 `index.tsx` exports `renderMode = 'ssr'`. Its loader runs SERVER-SIDE on EVERY request under `voltro start` — the timestamp and nonce change on each refresh, and the loader can read the incoming request to personalise the HTML before it's sent. There is no caching: the response carries `x-voltro-rendered-by: ssr`.
 
 ```tsx
-// src/pages/index.page.tsx
+// src/pages/page.tsx
 import type { ReactNode } from 'react'
 import { useLoaderData, useServerRequest, type LoaderFn, type PageMeta } from '@voltro/web'
 
@@ -646,7 +646,7 @@ Use SSR for anything that varies per request: a logged-in dashboard, a page that
 `feed.tsx` takes the SAME render path as SSR, but `voltro start` CACHES the HTML and serves the cached copy to every request within the `revalidate` window. After the window expires the next request re-renders and replaces the cache — cache hits return in well under a millisecond. `tenantAware: true` folds the `x-tenant` request header into the cache key, so tenant A's render is never served to tenant B:
 
 ```tsx
-// src/pages/feed.page.tsx
+// src/pages/feed/page.tsx
 import type { ReactNode } from 'react'
 import { useLoaderData, type LoaderFn, type PageMeta } from '@voltro/web'
 
@@ -685,7 +685,7 @@ The loader's `headers` is populated server-side (lowercased keys) — that's how
 `feed-swr.tsx` is the same ISR page plus a `staleWhileRevalidate` window. When `revalidate` expires, instead of blocking the next visitor on a fresh render, the cache serves the STALE HTML immediately AND kicks off a background re-render. The visitor never waits; the cache catches up out-of-band. Beyond `revalidate + staleWhileRevalidate` the next request blocks on a fresh render, like a cold MISS:
 
 ```tsx
-// src/pages/feed-swr.page.tsx
+// src/pages/feed-swr/page.tsx
 import type { ReactNode } from 'react'
 import { useLoaderData, type LoaderFn, type PageMeta } from '@voltro/web'
 
@@ -878,10 +878,10 @@ export const posts: ReadonlyArray<Post> = [
 
 ## SSG dynamic routes — `getStaticPaths` + `loader` + per-post `meta`
 
-A dynamic route like `src/pages/blog/[slug].page.tsx` matches infinitely many URLs. To pre-render it statically the build needs to know WHICH slugs exist — that is what `getStaticPaths` answers, by mapping over the content source. For each enumerated `params` the build runs the `loader` (server-side, at build time) and renders one HTML file. The `meta` export is a FUNCTION of the loader data, so each post gets its own correct `<title>` / `<description>` baked into the HTML — exactly what you want for SEO and social cards.
+A dynamic route like `src/pages/blog/[slug]/page.tsx` matches infinitely many URLs. To pre-render it statically the build needs to know WHICH slugs exist — that is what `getStaticPaths` answers, by mapping over the content source. For each enumerated `params` the build runs the `loader` (server-side, at build time) and renders one HTML file. The `meta` export is a FUNCTION of the loader data, so each post gets its own correct `<title>` / `<description>` baked into the HTML — exactly what you want for SEO and social cards.
 
 ```tsx
-// src/pages/blog/[slug].page.tsx
+// src/pages/blog/[slug]/page.tsx
 import type { ReactNode } from 'react'
 import { useLoaderData, notFound, type LoaderFn, type PageMeta } from '@voltro/web'
 import { posts, type Post } from '../../content/posts'
@@ -972,7 +972,7 @@ export default island(ReadingProgress, { name: 'ReadingProgress', hydrate: 'load
 The index at `/` is pure content: a list of posts with no interactivity. It declares `interactive: 'none'`, which makes the framework strip EVERY `<script>` it would otherwise emit — the HTML ships with no JS bundle at all. It reads the same content source the `[slug]` page + `getStaticPaths` use:
 
 ```tsx
-// src/pages/index.page.tsx
+// src/pages/page.tsx
 import type { ReactNode } from 'react'
 import type { PageMeta } from '@voltro/web'
 import { posts } from '../content/posts'
@@ -1106,10 +1106,10 @@ The serverless function lives next to the web app but is a separate deploy artif
 
 ## The static page + the island form
 
-`src/pages/index.page.tsx` is `renderMode: 'static'` (pre-rendered, servable from a CDN) and `interactive: 'islands'` — so only the `<ContactForm>` island hydrates; the headline + copy ship as inert HTML with no React lifecycle:
+`src/pages/page.tsx` is `renderMode: 'static'` (pre-rendered, servable from a CDN) and `interactive: 'islands'` — so only the `<ContactForm>` island hydrates; the headline + copy ship as inert HTML with no React lifecycle:
 
 ```tsx
-// src/pages/index.page.tsx
+// src/pages/page.tsx
 import type { ReactNode } from 'react'
 import type { PageMeta } from '@voltro/web'
 import ContactForm from '../components/ContactForm.island'
@@ -1358,7 +1358,7 @@ apps/demo/web/
 ├── README.md
 └── src/pages/
     ├── layout.tsx                 # root shell (header + <main>)
-    └── index.page.tsx                  # the reactive page — useSubscription + useMutation
+    └── page.tsx                  # the reactive page — useSubscription + useMutation
 ```
 
 ## The `apis` wiring
@@ -1390,7 +1390,7 @@ The `package` resolves the api workspace package; its port is auto-discovered fr
 ## The reactive loop
 
 ```tsx
-// src/pages/index.page.tsx
+// src/pages/page.tsx
 import { useMutation, useSubscription } from '@voltro/client'
 
 const TENANT = 'acme'
@@ -1418,7 +1418,7 @@ The subscription builder also exposes `revision`, `emittedAt`, `error`, and `pen
 
 ## Pairing with a different api
 
-This page is wired to api-backend's `notes` domain. To point it at your own api, change `apis.app.package` in `app.config.ts`, then swap the rpc tags + the row type in `src/pages/index.page.tsx` to match your descriptors. The hook shapes are identical for any api.
+This page is wired to api-backend's `notes` domain. To point it at your own api, change `apis.app.package` in `app.config.ts`, then swap the rpc tags + the row type in `src/pages/page.tsx` to match your descriptors. The hook shapes are identical for any api.
 
 ## When to use
 
@@ -1533,7 +1533,7 @@ export const withLocalePrefix = (path: string, locale: string): string =>
 Each page has a one-line **mirror** under `src/pages/[locale]/`. The mirror re-exports the bare page verbatim (the component reads its locale from the URL via the layout's provider) and uses `getStaticPaths` to enumerate the *non-default* locales — which is what tells `voltro build` to emit the `/de/...` HTML. Without the mirror, only the default-locale URL is built.
 
 ```tsx
-// src/pages/[locale]/index.page.tsx — the entire file
+// src/pages/[locale]/page.tsx — the entire file
 import { SUPPORTED_LOCALES, DEFAULT_LOCALE } from '../../lib/locale'
 
 export { default } from '../index'
@@ -1550,7 +1550,7 @@ export const getStaticPaths = async (): Promise<Array<{ params: { locale: string
 The body of each page is localised automatically (the SSG pipeline wraps every variant in the right catalog's provider). The document head is NOT — unless you export `meta` as a **function of `{ locale }`**. The framework drives `locale` from `params.locale` on the `[locale]` route (and `defaultLocale` on the bare path), so each variant bakes the right `<title>` / `<meta description>` into its HTML — exactly what you want for SEO and social cards. A plain `meta` object would leave the head English on `/de`.
 
 ```tsx
-// src/pages/index.page.tsx
+// src/pages/page.tsx
 import { T, useT, useLocale } from '@voltro/i18n'
 import { getCatalog } from '../lib/locale'
 
@@ -1662,7 +1662,7 @@ The `[locale]` mirrors pick it up automatically — `getStaticPaths` reads `SUPP
 
 ## Anti-patterns
 
-- **Forgetting the `[locale]` mirror for a new page.** Create `src/pages/foo.page.tsx` AND a one-line mirror `src/pages/[locale]/foo.page.tsx`. Without the mirror, only the default-locale URL is emitted — `/de/foo` 404s.
+- **Forgetting the `[locale]` mirror for a new page.** Create `src/pages/foo/page.tsx` AND a one-line mirror `src/pages/[locale]/foo/page.tsx`. Without the mirror, only the default-locale URL is emitted — `/de/foo` 404s.
 - **Exporting `meta` as a plain object.** The body localises, but the `<title>` / `<meta description>` stay English on `/de`. Export `meta` as a function of `{ locale }` and read the catalog via `getCatalog(locale)`.
 - **Skipping `defineLocale<typeof en>()` for a non-base catalog.** Plain `defineCatalog(...)` compiles but loses the parity check — the one feature that stops translations drifting. Always run non-base locales through `defineLocale<typeof en>()`.
 - **Angle brackets in catalog strings.** react-intl's ICU parser treats `<tag>` as a rich-text element and fails (`FORMAT_ERROR`) if there's no matching close tag. Write "page titles", not "`<title>` tags", in a message.
@@ -1759,7 +1759,7 @@ export default function DashboardLayout({ children }) {
 The gate must run **per request** — it reads the request's cookie and may redirect. A `static` page is pre-rendered once at build time with no per-visitor render, so it can't redirect per-visitor; in fact `voltro build` **rejects** a `RedirectError` thrown during static pre-render. So the authed pages declare `renderMode: 'ssr'`:
 
 ```tsx
-// src/pages/dashboard/index.page.tsx
+// src/pages/dashboard/page.tsx
 export const renderMode = 'ssr' as const
 export const meta = { title: 'Overview' }
 export default function Overview() { /* … */ }
@@ -1884,7 +1884,7 @@ export default {
 `query` is present ONLY server-side (`ssr` / `isr`). It invokes the api's rpc directly over `POST /rpc`, **forwarding the request's session cookie** so the same Subject + tenant resolve as the WebSocket path. A streaming query is drained to its FIRST snapshot — here, the current notes for this tenant. `meta` reads the result, so the `<title>` reflects real data in the server-rendered HTML:
 
 ```tsx
-// src/pages/index.page.tsx
+// src/pages/page.tsx
 import { useLoaderData, type LoaderFn, type PageMeta } from '@voltro/web'
 import { useSubscription } from '@voltro/client'
 
@@ -1994,7 +1994,7 @@ const entities = manifest ? deriveEntityAdmins(manifest) : []
 ## Per-entity CRUD
 
 ```tsx
-// src/pages/admin/[entity].page.tsx (abridged)
+// src/pages/admin/[entity]/page.tsx (abridged)
 const canCreate = useCan(spec.createScope)         // <table>:create
 {spec.createTag && canCreate ? (
   <AutoForm api="app" mutation={spec.createTag} submitLabel={`Add ${spec.table}`} />
@@ -2041,7 +2041,7 @@ apps/acme/web/
 
 ## Make it yours
 
-Everything under `src/pages/admin/` is yours. Swap the cookie gate (`lib/auth.ts`) + demo scopes (`lib/admin.ts`) for real auth; replace the generic `[entity].page.tsx` with a hand-built page for any entity that needs more than CRUD.
+Everything under `src/pages/admin/` is yours. Swap the cookie gate (`lib/auth.ts`) + demo scopes (`lib/admin.ts`) for real auth; replace the generic `[entity]/page.tsx` with a hand-built page for any entity that needs more than CRUD.
 
 ## When to use frontend-admin vs. the other web templates
 

package/templates/agent-docs/whats-new.md

@@ -1,4 +1,4 @@
-# What's new in 0.15.0
+# What's new in 0.16.0
 
 Read this FIRST when a task touches an area you have not worked in recently.
 It is the cheapest way to notice that the framework grew the thing you were
@@ -7,125 +7,61 @@ workaround for something that shipped two versions ago.
 
 BREAKING entries name a codemod; run `voltro update` to apply it.
 
-### ⚠ BREAKING
-
-- **@voltro/cli** — **A rename now carries the ALIASED importers, not only the relative ones.**
-
-  An app's web build stopped compiling after `voltro update`: 84 relative imports were rewritten correctly, 163 aliased ones across 88 files were not, and `tsc` reported 249 errors on names that no longer existed. Nothing in the codemod's output hinted that a whole class of import had been skipped.
-
-  Two independent halves, and each alone leaves the imports stale:
-
-  - The codemod's ts-morph project was built with **no `baseUrl` and no `paths`**, so `@/components/link` resolved to nothing. It now gets the compiler's own shape — the raw `paths`, not the pre-resolved Vite table, because a `paths` target is relative to `baseUrl` by definition and an absolute one does not resolve. - `SourceFile.move()` rewrites relative specifiers and **nothing else**, which is correct on its own terms: ts-morph cannot know whether the alias mapping or the file is meant to change. So the codemods now rewrite the aliased ones themselves, narrowly — only specifiers that RESOLVED to the moved file, and only the trailing stem, which needs no alias table and so cannot disagree with one. The run reports how many it rewrote.
-
-  **A file an exact `paths` entry names is left alone and reported.** Renaming `link.tsx` while `"@/link": ["src/components/link.tsx"]` points at it leaves the mapping resolving to nothing — and the same path is usually repeated in a vite/vitest alias table no codemod owns. One app hit this and then saw a taxonomy violation reported on a file the codemod had itself created.
-
-  **`page/unsuffixed-in-pages` is now an error, not a warning.** The comment justifying the warning contradicted the scanner it described: that bucket is already narrowed to a default export nothing imports, which is what an unmigrated page looks like and what a co-located component never does. The failure it names is invisible everywhere else — an unmigrated route simply 404s, with a clean `tsc` and a green suite. One app finished a migration with 51 of them. `codemod: none`: the rename it asks for already ships as `0.14.0/03_pages-suffix`, and nothing about a user's SOURCE changes here — what changes is that `voltro check` now fails on a route that does not route.
-- **@voltro/protocol, @voltro/client, @voltro/web** — **`errorTag` moves from `@voltro/client` to `@voltro/protocol`.**
-
-  It reads the `_tag` that `toRpc` writes, so it now lives beside `toRpc` — one file owning both ends of that contract. Where it used to live had a cost invisible from inside the framework: an app's shared error handler sat in a package that pulled only `@voltro/i18n`, and reading a tag would have meant depending on the entire client package for seven lines. They declined, and kept parsing message strings with a regex — the exact outcome the helper exists to prevent.
-
-  `@voltro/web` re-exports the client surface, so it loses the symbol too — the same codemod covers an app that imported it from there.
-
-  Not re-exported from `@voltro/client`: two import paths for one helper is how the next reader learns the wrong one. The transform codemod repoints the import, preserving an alias (`errorTag as tagOf`) and the type-only form, and merges into an existing `@voltro/protocol` import rather than adding a second.
-
-  While moving it, its doc comment gained the thing that matters at the call site and was only implied before: **`instanceof` does not hold on the client.** What arrives there was decoded from JSON and never constructed, so match on the tag, not on the class. One team read the old wording as a promise that `instanceof` works and was right to say so.
-
 ### Added
 
-- **@voltro/protocol, @voltro/cli** — **An auth strategy reaches the app's DataStore, on `input.store`.**
-
-  ```ts
-  const sessionStrategy: AuthStrategy = {
-    id: 'db-session',
-    resolve: async ({ headers, store }) => {
-      if (store === undefined) return { kind: 'skip' }        // still booting
-      const [row] = await store.query(sessions.byToken(headers.authorization))
-      return row ? { kind: 'matched', subject: toSubject(row) } : { kind: 'skip' }
-    },
-  }
-  ```
-
-  Without it, a DB-backed strategy — a session row, an API-key record, a PAT table — had to open a SECOND connection path beside the framework's, to the same database the request store opens a moment later. One adopter's `auth/db.ts` is 105 lines of exactly that: a second `ManagedRuntime` plus a `MysqlClient`, load-bearing for their session lookup and their ApiKeyStore. Every DB-backed OIDC / SAML / PAT integration rebuilds it, which is what made this a framework gap rather than an app's problem.
-
-  It is the **same value** `auth.resolveScopes` already receives, through the **same lazy getter** — one ref, two consumers, rather than each caller reaching for the store its own way. That is deliberate: `voltro dev` builds the store AFTER the auth chain and `voltro serve` builds it BEFORE, so a value captured at config time would be `undefined` forever in dev and correct in production. The getter is read ONCE per request, not once per strategy.
+- **@voltro/protocol, @voltro/runtime, @voltro/cli, @voltro/database** — **A plugin HTTP route reaches the app's DataStore, on `req.store`** — and `voltro db apply` finally honours `VOLTRO_DESTRUCTIVE_OK`.
 
-  `store` is `undefined` only while the store is still being built, and on an app with no store — a strategy should `skip` rather than throw. It is the BOOT store, not a request-scoped one: strategies resolve before a request store exists.
+  ### `PluginHttpRouteRequest.store`
 
-  **Not narrowed to a read-only surface**, and the reason is worth stating: the narrower type would be the better guarantee, `DataStore` is the driver SPI, and giving strategies a different type from the one `resolveScopes` gets would put two views of one object in the same file. A strategy that writes during subject resolution is a design mistake; the type system is not going to catch it for you. Read users / sessions / keys, do not run domain writes.
+  The same seam as `AuthStrategyInput.store`, one layer over, and the same report produced it. An adopter's `auth/db.ts` has five consumers: two are auth strategies and collapsed onto `input.store` exactly as designed; three are plugin HTTP routes and could not, so the second `ManagedRuntime` + `MysqlClient` stayed for them.
 
-### Fixed
-
-- **@voltro/cli** — `voltro dev` terminates when its dev server does, instead of living forever.
-
-  The supervisor never watched its child die. `runChild` was an `Effect.acquireUseRelease` whose `use` was `Effect.never`, so `proc.on('exit')` existed ONLY in the release path — and that path runs when the fiber is interrupted (a restart, a signal), never when the child exits by itself. Two more places assumed the same thing: `runSupervisor` was typed `Effect<never>`, and `dev.ts` returned `new Promise(() => {})` after starting it.
-
-  So a boot that aborted — an unreachable database, a refused migration, a failed env gate — left the child dead and the supervisor waiting for a file change that nobody was there to make. Measured, not inferred: one developer machine carried 15 such `voltro dev` process pairs, `ppid=1`, the oldest 7 days old, every one a boot that had failed against a remote database. They hold a watcher and a terminal-less process each; in CI the same shape keeps a runner busy after the job "finished".
-
-  `use` now awaits the child (`awaitChildExit`) and the supervisor races that against the watch loop, so whichever happens first decides. A restart still does NOT end it — `stopChild` interrupts the fiber, so the deferred is never completed on that path. A child killed by a signal reports `code: null`, which is reported as a failure rather than a clean 0.
-
-  What a self-exit MEANS then depends on whether anyone is watching, because the two failure modes pull in opposite directions:
-
-  - **Interactive** (stdout is a TTY) — a crashed boot is something you are about to fix, so the supervisor says so and keeps watching. The next save restarts it, which is what every other dev server does; stopping would throw away the watcher mid-edit and make you retype the command. - **Non-interactive** — nobody is going to fix anything. `voltro dev` exits with the child's code, so a failed boot is a failed command. This is the case that produced the invisible processes, and the one CI actually waits on.
+  Login is the sharpest case and it is not exotic: it MUST write (the session row), it cannot be an rpc mutation because it is what mints the cookie, and it is a documented first-class pattern — `@voltro/plugin-auth` ships `handleSignIn` / `handleSignUp` and the reference consumer mounts them on this surface. Every app that does so needed a store the route contract did not give it.
 
-  A CLEAN exit always stops, watched or not. `VOLTRO_DEV_KEEP_ALIVE=1|0` forces the answer for what the TTY check cannot see — a CI runner with a TTY allocated, or a wrapper that pipes output while a human still watches it — and cannot keep a clean exit alive, which would turn a deliberate shutdown into a hang.
+  It is the BOOT store, through the same lazy getter the auth chain reads — one ref, three consumers now — and `undefined` while it is still being built, so a route should answer rather than throw. It is **not tenant-scoped**: a route serves raw HTTP with no resolved Subject, so a route reading tenant-owned rows must derive and apply that scope itself. That is the price of the surface being raw, and the reason an rpc procedure stays the better home for anything that can be one.
 
-  Pinned against REAL child processes, because the defect was an Effect that never settled — a stubbed `once('exit')` that resolves is exactly what would have passed while the bug shipped.
-- **@voltro/database** — **A user-facing message that names an API must have one — now checked in CI.**
+  ### `db apply` honours `VOLTRO_DESTRUCTIVE_OK`
 
-  The sibling of the claimed-wiring check. That one asserts a doc comment's claimed caller exists; this one asserts a message's claimed API exists. Same failure shape, worse audience: a doc comment is read by somebody browsing, a refusal by somebody already blocked and looking for the sanctioned way out.
+  The table-list opt-in shipped on the auto-migrate path only. `voltro db apply` computes its own plan and checked `summary.blocked` directly; its module contained no occurrence of the variable at all. So an app's staging migration Job — running the sanctioned `db apply --plan` form — had **no route through an intentional, declared, `lossy`-classified table drop**, and the release note's own example was a command that ignored the variable it set.
 
-  It exists for a reported bug that nothing could have caught. The drop-table refusal offered, as its FIRST option, *"chain `.dropped()` on it"* — tables have no such marker, only columns do. Doc SAMPLES are typechecked; message strings are not, and cannot be. Three of one release's reported defects lived in that blind spot.
+  Both forms now route through the same helper as the boot gate: every blocked op must be `lossy`, a named scope unblocks only the tables it names, anything still blocked refuses the whole plan. The applier receives the UNBLOCKED plan — passing the still-blocked one would have it refuse a second time, which is the exact bug `unblockLossy` was written for.
 
-  Three rules, each with an unambiguous answer, because a noisy gate is skipped and then costs more than it saves:
+  Worth naming, because it is a boundary of the message-API gate added last release: the variable exists, is spelled correctly, and IS read — by a different command than the one printing it. *"The named API exists"* and *"the named API is reachable from here"* are different claims, and only the first is checkable from a string.
 
-  - a `VOLTRO_*` variable a message tells you to **set** must be read somewhere, - a `` `.method()` `` a message tells you to **chain** must be a callable MEMBER of a published type, - a `--flag` in a `voltro …` instruction must be parsed.
-
-  The member rule is the one that took two attempts. The first version asked "does this name exist in the public surface" and the motivating bug **passed it**: `dropped` is exported, as a free `dropped()` you write as a column's value. A dotted claim is a claim about something chainable, so a free function and a `readonly dropped?: boolean` data property are both correctly rejected now.
-
-  **It immediately found a second instance nobody had reported** — the drop-COLUMN refusal also said "chain `.dropped()`", one level down from the reported one, and the real spelling is `<column>: dropped()` as the field's value. Close enough to guess from, which is why it survived.
-
-  Ships with a `--selftest` that runs first in CI, for the reason the changelog gate has one: a check that has quietly stopped detecting anything still prints green, and green is read as evidence.
-- **@voltro/database** — **Two migration refusals sent people the wrong way** — the worst place for a bad hint, because whoever reads one is already blocked and looking for the sanctioned way out.
-
-  **The drop-table refusal recommended an API that does not exist.** Its first option was *"add it to your declared set + chain `.dropped()` on it"*. There is no table-level `dropped()` — only the column marker. The recommendation was also the conceptually RIGHT one, which is what made it expensive: the two options that do work are both worse, so a reader picks the one they cannot follow.
-
-  There is now a real per-table answer: **`VOLTRO_DESTRUCTIVE_OK` accepts a table list**, not just `1`. `VOLTRO_DESTRUCTIVE_OK=old_things` acknowledges the data loss for that table and leaves every other lossy op in the plan blocked. `1` still means all of them — which is rarely what somebody means, and was previously the only way to say anything. A user with one intended drop and three other lossy ops had to acknowledge all four or hand-write a `DROP TABLE` migration, the path 0.14.0's own upgrade note warns against.
-
-  The message also states why there is deliberately no table marker: a dropped COLUMN leaves a slot worth documenting in the declaration; a dropped TABLE leaves nothing, so the marker would be a dead entry you must remember to delete.
+### Fixed
 
-  **The drop-column refusal never mentioned `renamedFrom`.** It offered "chain `.dropped()`" or "restore the field" — and followed literally on a rename, the first costs exactly the data the user was trying to keep. When the plan drops AND adds columns on the same table, the message now leads with *"did you rename one?"* and names both sides. The evidence was in the plan the whole time.
+- **@voltro/cli, @voltro/database** — **`voltro update --codemods-only` crashed on a file deleted but not staged** — a regression introduced by 0.15.0's own git-based enumeration.
 
-  Finding that required fixing a second thing: the footer read only the BLOCKED operations, and an `add-column` is `safe`. The counterpart of a rename was never in the list it was looking at.
-- **@voltro/cli** — **0.14.0's taxonomy codemod renamed two kinds of file it should not have, and a repo that already upgraded carries the damage with a green build.** Both were found by adopters running it on real projects; both are silent — the rename succeeds, the imports are rewritten, nothing throws.
+  `git ls-files --cached` reads the INDEX, and the index still holds a path that is already gone from disk until the deletion is staged. `addSourceFileAtPath` then threw ENOENT, surfacing as a raw ts-morph stack rather than as anything a reader could act on.
 
-  **A framework primitive was treated as an undeclared file.** `health.route.tsx` → `health.route.component.tsx`, five times in one app. The codemod kept its OWN list of "suffixes that already carry a contract" instead of reading `fileConventions.ts`, and `.route.` was not on it — the exact drift that module exists to prevent, reproduced inside a file that imports from it. The list is gone; the registry answers now, and it gained `ROUTE_PATTERN` plus a `carriesFrameworkConvention()` every consumer shares.
+  The state is not exotic — it is what an ordinary mid-work tree looks like, and `--dry-run` is documented as allowed on a dirty tree, which is exactly where an unstaged deletion lives. The command was unusable in the state it explicitly permits. Paths that are gone are now filtered out: there is nothing to rewrite and nothing to report.
 
-  The root cause underneath was worse than a missing entry: `export default defineRestRoute({...})` resolved to the placeholder name `Default`, which starts with a capital, and was counted as a COMPONENT on that basis. A default export is now only evidence of a component when the exported thing is callable — so a convention nobody has registered yet is safe too.
+  **A failing DDL statement now travels with the error, not only to stderr.** A soft-drop aborted a boot with a bare `SqlError: Failed to execute statement` — no statement, no table, no operation. The applier wrote the detail with `process.stderr.write` inside a `tapError` and re-raised the ORIGINAL error, so the detail was lost whenever the process aborted before the stream flushed, or whenever the caller rendered the error rather than the console. `migrate.ts` already carried it in the error for file-based migrations; the planner-driven applier did not, so **which path failed decided whether you could see what failed.**
+- **@voltro/cli** — **`voltro update --codemods-only` refused in the one state it exists for.**
 
-  **A file with no exports was called a type file.** `test-setup.ts` → `test-setup.types.ts`, while `vitest.config.ts` still named `./test-setup.ts` as a **string**. Not an import, so nothing rewrote it and nothing failed: that suite would have run without its setup and stayed green. Five more went the same way — a registry module, two migration runners, a `.register.ts`, and a code generator whose `export` tokens live inside template strings.
+  The clean-tree guard ran before the repair path, so the command whose entire job is finishing an interrupted upgrade refused whenever the tree was dirty. An adopter reported it twice; the second time their tree carried uncommitted work **from the previous upgrade**, so they bumped four manifests by hand and ran the install themselves — the outcome `voltro update` exists to prevent, reached through its own guard.
 
-  `*.types.ts` promises "zero runtime exports", and that promise only means something for a file that exports TYPES. Zero of everything promises nothing, and renames a module whose whole purpose is being imported for effect — where the filename is often the only reference there is. It now requires at least one exported type.
+  `--force` was always available and is the wrong answer: it is documented as "not recommended", so it reads as an escape hatch rather than as the sanctioned route through a state we explicitly support.
 
-  **The shipped codemod undoes both**, and can only reach files whose content proves the suffix was wrong: a `.component.` on a name that already carries a framework convention, and a `.types.` on a file that exports nothing at all. It also prints the one thing it cannot fix — references by PATH rather than by import (a vitest `setupFiles`, a tsconfig `include`, a Docker `COPY`) were strings on the way out and are strings on the way back.
-- **@voltro/cli** — Three ways `voltro update` failed on a real adopter's host, none of which we could have found ourselves — each needs a machine we do not have.
+  `--codemods-only` now **warns** instead of refusing, saying the codemod diff will be mixed in with the existing changes and pointing at `--dry-run` / `--only`. The full update still refuses — bump, install and rewrite in one pass on top of unrelated changes is a diff nobody can read — and its refusal now names the repair path.
 
-  **The install could not run here, and the refusal left the tree half-upgraded.** Their install runs in a container against its own store. `voltro update` ran the package manager on the host anyway; pnpm refused (it wanted to remove `node_modules` and had no TTY to ask) and exited — after the version bumps were already written and before any codemod ran. That is the state this command's own documentation calls the worst one to be in, and it was reachable by design.
+### Internal (no consumer-facing effect)
 
-  `--no-install` now writes the bump and stops, saying plainly that the tree is half-upgraded and naming both remaining steps. The install-failed message points at it too. Note what this is not: a compatibility flag. It is a mode for a host where the install is somebody else's job, and it ends by telling you the job is not done.
+- **@voltro/cli** — The admin-import rejection cases share ONE booted server, and report their phase timings.
 
-  **The codemod scan exhausted a 12 GB heap, and said nothing about why.** The crash was a bare V8 out-of-memory stack. The scan pruned the directories WE know about — `node_modules`, `dist`, `.turbo` — which cannot cover a project's own heavy ignored trees (a build cache, a data dump, a virtualenv).
+  Two release gates have now failed on that single test line, with two different symptoms and neither an auth defect: first a **400** — this server rejects a request whose body framing broke BEFORE routing, so `gate()` never ran — and then, after the body was removed, a **120-second timeout**. A bare `Test timed out` cannot say whether the boot, the request or the close is what hung, which is why the second failure taught us nothing the first hadn't.
 
-  Inside a git repository the scan now asks git: `git ls-files --cached --others --exclude-standard` is exactly "files this project considers its own", and a codemod rewrites source — source that git ignores is not source we may rewrite. It also removes the traversal, so there is nothing left to exhaust memory on. Outside a repo the walk remains, now with a ceiling that REPORTS which directory to exclude instead of dying namelessly.
+  This file was standing up SIX real `serveApi` instances, each with its own socket and Effect layer, on a machine already running every other package's suite under `turbo --concurrency=2`. The two rejection cases assert nothing about the store, so they now share one boot, and the assertion carries `boot=…ms absent=…ms wrong=…ms` — a future failure names the slow phase instead of just the line number.
 
-  **"not a Voltro app" was the wrong conclusion.** Said of a directory containing an `app.config.ts`, it sends the reader looking for the wrong problem. Three web apps in a workspace inherited from another tool had their `@voltro/*` dependencies in an ancestor `package.json` — the apps ARE Voltro apps; only the declaration lives elsewhere. With an `app.config.ts` present the message now says that, and names the two ways forward.
+  No product code changed.
+- **@voltro/cli** — The admin-import rejection tests stop uploading an archive they never needed.
 
-  **A monorepo may keep ONE root `package.json`** with its apps carrying only an `app.config.ts`. Running `voltro update` inside such an app used to say "no package.json at <dir>" — true, and useless. It now recognises the layout, says it is supported, and prints the command with the root already filled in.
-- **@voltro/cli** — **`voltro update --only <id>`**, and a summary that stops contradicting itself.
+  A release gate failed with `expected 400 to be 401` on `401 without a Bearer token` and did not reproduce in five later runs. It was not an auth defect and not load-flake in the usual sense: measured against a live server on that path, an honest no-auth request answers **401**, a body-less one answers **401**, and one whose `Content-Length` lies — or whose chunked framing ends early — answers **400**, because the HTTP layer rejects broken framing BEFORE routing. `gate()` is the handler's first statement, so when it never runs there is no 401 to give.
 
-  `--only` runs just the named codemods (repeatable or comma-separated; ids are what `--dry-run` prints). The ask behind it: two of three codemods were load-bearing for one app — without them, 52 type errors and 51 routes that 404 — while the third was elective, and the repairing tool refuses on a dirty tree, so there was no way to take the necessary half first.
+  Those two tests were POSTing the full packed bundle to assert an authorization property that is decided without reading the body at all. The archive proved nothing and made a multi-KB upload a precondition of an auth assertion. They now send no body, which is both flake-free and the sharper claim; the assertions carry the response body so a future mismatch names the responder instead of printing a bare status.
 
-  It is deliberately NOT a `--required` flag over a REQUIRED/OPTIONAL axis on each codemod. "Required" would have to mean *this app does not run without it*, and that is a property of the app: `03_pages-suffix` is unavoidable for a project with pages and irrelevant to an api-only one. Marking it on the codemod would encode a guess as a contract. An unknown id is an error listing the ids that ARE available — "it did nothing" and "you typed it wrong" otherwise look identical.
+  No product code changed — the endpoint's behaviour is unaltered.
+- **@voltro/cli** — The admin-import auth test reports WHO answered, not just that the number was wrong.
 
-  **The summary counted only edited files, and renames vanished from it.** The before-snapshot is keyed by PATH, so a moved file has no entry under its new one: a pass that renamed 238 files and edited 9 importers reported `(9 files)`, understating the change by a factor of 26 in the line a user plans around. Moves are now paired by content and reported separately — `(238 renamed, 9 edited)`.
+  It failed once under full-gate load with `expected 400 to be 401`, and did not reproduce in four subsequent runs (the file alone, the integration group alone, two full suites, a second full gate). The bare status made the log useless: `gate()` is the first statement in `handleAdminImport` and always 401s an absent token, so a 400 proves the request never reached that handler — but nothing in the failure said which handler DID answer.
 
-  **A dry run no longer speaks in the past tense.** It printed `✓ <id> — <title>`, the same line a real run prints. Now `·` and `[would apply]`.
+  The assertion now carries the response body and the target URL, so the next occurrence names the responder instead of costing an afternoon. No product code changed; the endpoint's behaviour is unaltered.

package/templates/apps/api-ai/package.json

@@ -11,16 +11,16 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/ai": "0.16.0",
-    "@voltro/cli": "0.16.0",
-    "@voltro/database": "0.16.0",
-    "@voltro/env": "0.16.0",
-    "@voltro/protocol": "0.16.0",
-    "@voltro/runtime": "0.16.0",
+    "@voltro/ai": "0.17.0",
+    "@voltro/cli": "0.17.0",
+    "@voltro/database": "0.17.0",
+    "@voltro/env": "0.17.0",
+    "@voltro/protocol": "0.17.0",
+    "@voltro/runtime": "0.17.0",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.16.0",
+    "@voltro/testing": "0.17.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

package/templates/apps/api-auth/package.json

@@ -12,17 +12,17 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.16.0",
-    "@voltro/database": "0.16.0",
-    "@voltro/env": "0.16.0",
-    "@voltro/plugin-auth": "0.16.0",
-    "@voltro/protocol": "0.16.0",
-    "@voltro/runtime": "0.16.0",
-    "@voltro/sql-postgres": "0.16.0",
+    "@voltro/cli": "0.17.0",
+    "@voltro/database": "0.17.0",
+    "@voltro/env": "0.17.0",
+    "@voltro/plugin-auth": "0.17.0",
+    "@voltro/protocol": "0.17.0",
+    "@voltro/runtime": "0.17.0",
+    "@voltro/sql-postgres": "0.17.0",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.16.0",
+    "@voltro/testing": "0.17.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

package/templates/apps/api-backend/package.json

@@ -12,16 +12,16 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.16.0",
-    "@voltro/database": "0.16.0",
-    "@voltro/env": "0.16.0",
-    "@voltro/plugin-multitenancy": "0.16.0",
-    "@voltro/protocol": "0.16.0",
-    "@voltro/runtime": "0.16.0",
+    "@voltro/cli": "0.17.0",
+    "@voltro/database": "0.17.0",
+    "@voltro/env": "0.17.0",
+    "@voltro/plugin-multitenancy": "0.17.0",
+    "@voltro/protocol": "0.17.0",
+    "@voltro/runtime": "0.17.0",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.16.0",
+    "@voltro/testing": "0.17.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

package/templates/apps/api-backend-deactivation/package.json

@@ -12,16 +12,16 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.16.0",
-    "@voltro/database": "0.16.0",
-    "@voltro/env": "0.16.0",
-    "@voltro/plugin-deactivation": "0.16.0",
-    "@voltro/protocol": "0.16.0",
-    "@voltro/runtime": "0.16.0",
+    "@voltro/cli": "0.17.0",
+    "@voltro/database": "0.17.0",
+    "@voltro/env": "0.17.0",
+    "@voltro/plugin-deactivation": "0.17.0",
+    "@voltro/protocol": "0.17.0",
+    "@voltro/runtime": "0.17.0",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.16.0",
+    "@voltro/testing": "0.17.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

package/templates/apps/api-backend-mail/package.json

@@ -12,18 +12,18 @@
   "dependencies": {
     "@react-email/components": "^1.0.12",
     "@react-email/render": "^1.4.0",
-    "@voltro/cli": "0.16.0",
-    "@voltro/database": "0.16.0",
-    "@voltro/env": "0.16.0",
-    "@voltro/plugin-mail": "0.16.0",
-    "@voltro/plugin-multitenancy": "0.16.0",
-    "@voltro/protocol": "0.16.0",
-    "@voltro/runtime": "0.16.0",
+    "@voltro/cli": "0.17.0",
+    "@voltro/database": "0.17.0",
+    "@voltro/env": "0.17.0",
+    "@voltro/plugin-mail": "0.17.0",
+    "@voltro/plugin-multitenancy": "0.17.0",
+    "@voltro/protocol": "0.17.0",
+    "@voltro/runtime": "0.17.0",
     "effect": "^3.21.2",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.16.0",
+    "@voltro/testing": "0.17.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

package/templates/apps/api-backend-mariadb/package.json

@@ -12,18 +12,18 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.16.0",
-    "@voltro/database": "0.16.0",
-    "@voltro/env": "0.16.0",
-    "@voltro/plugin-multitenancy": "0.16.0",
-    "@voltro/plugin-storage": "0.16.0",
-    "@voltro/protocol": "0.16.0",
-    "@voltro/runtime": "0.16.0",
-    "@voltro/sql-mysql": "0.16.0",
+    "@voltro/cli": "0.17.0",
+    "@voltro/database": "0.17.0",
+    "@voltro/env": "0.17.0",
+    "@voltro/plugin-multitenancy": "0.17.0",
+    "@voltro/plugin-storage": "0.17.0",
+    "@voltro/protocol": "0.17.0",
+    "@voltro/runtime": "0.17.0",
+    "@voltro/sql-mysql": "0.17.0",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.16.0",
+    "@voltro/testing": "0.17.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }