wcz-layout 9.4.2 → 9.4.3

package/skills/client-db/SKILL.md

@@ -3,12 +3,14 @@ name: client-db
 description: "Use when: creating or modifying TanStack DB collections, live queries, optimistic collection writes, subset loading, collection preloading."
 ---
 
+> Mechanics (`createCollection`, `queryCollectionOptions`, the live-query builder, `createOptimisticAction`) are covered by TanStack's own skills — load `@tanstack/db#db-core/live-queries`, `#db-core/mutations-optimistic`, and `@tanstack/react-db` for the API details. This skill adds only the wcz-layout conventions on top.
+
 ## Rules
 
 - Use `eager` syncMode for top-level collections, `on-demand` for child/relational data.
 - Use `useLiveQuery` for list/grid pages and `useLiveSuspenseQuery` for detail components wrapped in suspense.
 - For mutations use `createOptimisticAction` — mirror the server mutation in `onMutate`, then call the server function and `collection.utils.refetch()` in `mutationFn`.
-- Use `meta.loadSubsetOptions` for relational subset loading.
+- For on-demand subset loading, convert `meta.loadSubsetOptions` with `fromTanDb()` (from `agnostic-query/tanstack-db`) before passing it to the server fn, and set `autoIndex: "eager"` with `defaultIndexType: BasicIndex` (from `@tanstack/react-db`).
 
 ## File Placement
 
@@ -34,15 +36,20 @@ export const librariesCollection = createCollection(
   }),
 );
 
-// src/db-collections/<feature>.ts
+// src/db-collections/<feature>.ts — child/relational (on-demand)
+import { BasicIndex } from "@tanstack/react-db";
+import { fromTanDb } from "agnostic-query/tanstack-db";
+
 export const bookCollection = createCollection(
   queryCollectionOptions({
     queryKey: ["books"],
-    queryFn: ({ meta }) => selectBooks({ data: meta?.loadSubsetOptions }),
+    queryFn: ({ meta }) => selectBooks({ data: fromTanDb(meta?.loadSubsetOptions) }),
     getKey: ({ id }) => id,
     schema: BookSchema,
     queryClient: queryClient,
     syncMode: "on-demand",
+    autoIndex: "eager",
+    defaultIndexType: BasicIndex,
   }),
 );
 

package/skills/data-grid/SKILL.md

@@ -1,142 +1,142 @@
----
-name: data-grid
-description: "Use when: building or configuring MUI X DataGrid tables, editable columns, toolbar actions, row selection, or TanStack DB-backed grids."
----
-
-## Rules
-
-- Wrap DataGrid in `Fullscreen` when it is the only content on the page.
-- Type columns as `Array<GridColDef<RowType>>` with the row interface.
-- Use translation for all `headerName` values.
-- Use `rows`, `columns`, `showToolbar`, `loading`, `ignoreDiacritics`, `cellSelection`, and `disableRowSelectionOnClick` on grids.
-- For enums use `type: "singleSelect"` with `{ value, label }` options array used from enumObject.
-- For editable columns, pair `editable: true` with `renderHeader: EditableColumnHeader`.
-- Use `EditableColumnHeader`, and router button/grid action components from `wcz-layout/components` when they fit.
-- Always set `valueFormatter: (value) => dayjs(value).format("L LT")` for columns type `dateTime` or `format("L")` for columns type `date`.
-
-## File Placement
-
-```
-@mui/x-data-grid-premium        — GridColDef, DataGridPremium
-src/db-collections/             - TanStack DB collections to get data
-@tanstack/react-db              - useLiveQuery, useLiveSuspenseQuery
-src/server/actions/             - server functions and enums
-wcz-layout/components           - EditableColumnHeader, Fullscreen
-wcz-layout/hooks                - useTranslation
-```
-
-## Examples
-
-```tsx
-// src/routes/<feature>s/index.tsx
-const { t } = useTranslation();
-const { confirm, alert } = useDialogs();
-const navigate = useNavigate();
-const [cellSelectionModel, setCellSelectionModel] = useState<GridCellSelectionModel>({});
-
-const { data, isLoading } = useLiveQuery((q) =>
-  q.from({ feature: featureCollection }).orderBy(({ feature }) => feature.name, "asc"),
-);
-
-const columns: Array<GridColDef<Feature>> = [
-  {
-    field: "name",
-    headerName: t("Feature.Name"),
-    width: 200,
-    editable: true,
-    renderHeader: EditableColumnHeader,
-  },
-  {
-    field: "status",
-    headerName: t("Feature.Status"),
-    width: 200,
-    type: "singleSelect",
-    valueOptions: featureStatusEnum.enumValues.map((status) => ({
-      value: status,
-      label: t(`FeatureStatus.${status}`),
-    })),
-  },
-];
-
-const handleOnDelete = createOptimisticAction<Array<string>>({
-  onMutate: (ids) => {
-    ids.forEach((id) => {
-      featureCollection.delete(id);
-    });
-  },
-  mutationFn: async (ids) => {
-    deleteFeatures({ data: ids });
-    await featureCollection.utils.refetch();
-  },
-});
-
-return (
-  <Fullscreen>
-    <DataGridPremium
-      rows={data}
-      columns={columns}
-      showToolbar
-      loading={isLoading}
-      ignoreDiacritics
-      onRowDoubleClick={({ row }) => navigate({ to: "/features/$id", params: { id: row.id } })}
-      cellSelection
-      disableRowSelectionOnClick
-      cellSelectionModel={cellSelectionModel}
-      onCellSelectionModelChange={(newModel) => setCellSelectionModel(newModel)}
-      slots={{ toolbar: DataGridToolbar }}
-      slotProps={{
-        toolbar: {
-          title: t("Feature.Features"),
-          actions: [
-            <Tooltip key="create" title={t("Create")}>
-              <RouterIconButton to="/features/create">
-                <Add fontSize="small" />
-              </RouterIconButton>
-            </Tooltip>,
-            Object.keys(cellSelectionModel).length === 1 && (
-              <Tooltip key="edit" title={t("Edit")}>
-                <RouterIconButton
-                  to="/features/edit/$id"
-                  params={{ id: Object.keys(cellSelectionModel)[0].toString() }}
-                >
-                  <Edit fontSize="small" />
-                </RouterIconButton>
-              </Tooltip>
-            ),
-            Object.keys(cellSelectionModel).length > 0 && (
-              <Tooltip key="delete" title={t("Delete")}>
-                <IconButton
-                  onClick={async () => {
-                    const confirmed = await confirm(
-                      t("DeleteConfirmation", { count: Object.keys(cellSelectionModel).length }),
-                    );
-                    if (confirmed) {
-                      try {
-                        const transaction = handleOnDelete(
-                          Object.keys(cellSelectionModel).map((id) => id.toString()),
-                        );
-                        await transaction.isPersisted.promise;
-                        setCellSelectionModel({});
-                      } catch (error) {
-                        if (error instanceof Error) await alert(error.message);
-                      }
-                    }
-                  }}
-                >
-                  <Badge
-                    badgeContent={Object.keys(cellSelectionModel).length}
-                    invisible={Object.keys(cellSelectionModel).length <= 1}
-                    color="error"
-                  >
-                    <Delete fontSize="small" />
-                  </Badge>
-                </IconButton>
-              </Tooltip>
-            ),
-          ],
-        },
-      }}
-    />
-  </Fullscreen>
-);
-```
+---
+name: data-grid
+description: "Use when: building or configuring MUI X DataGrid tables, editable columns, toolbar actions, row selection, or TanStack DB-backed grids."
+---
+
+## Rules
+
+- Wrap DataGrid in `Fullscreen` when it is the only content on the page.
+- Type columns as `Array<GridColDef<RowType>>` with the row interface.
+- Use translation for all `headerName` values.
+- Use `rows`, `columns`, `showToolbar`, `loading`, `ignoreDiacritics`, `cellSelection`, and `disableRowSelectionOnClick` on grids.
+- For enums use `type: "singleSelect"` with `{ value, label }` options array used from enumObject.
+- For editable columns, pair `editable: true` with `renderHeader: EditableColumnHeader`.
+- Use `EditableColumnHeader`, and router button/grid action components from `wcz-layout/components` when they fit.
+- Always set `valueFormatter: (value) => dayjs(value).format("L LT")` for columns type `dateTime` or `format("L")` for columns type `date`.
+
+## File Placement
+
+```
+@mui/x-data-grid-premium        — GridColDef, DataGridPremium
+src/db-collections/             - TanStack DB collections to get data
+@tanstack/react-db              - useLiveQuery, useLiveSuspenseQuery
+src/server/actions/             - server functions and enums
+wcz-layout/components           - EditableColumnHeader, Fullscreen
+wcz-layout/hooks                - useTranslation
+```
+
+## Examples
+
+```tsx
+// src/routes/<feature>s/index.tsx
+const { t } = useTranslation();
+const { confirm, alert } = useDialogs();
+const navigate = useNavigate();
+const [cellSelectionModel, setCellSelectionModel] = useState<GridCellSelectionModel>({});
+
+const { data, isLoading } = useLiveQuery((q) =>
+  q.from({ feature: featureCollection }).orderBy(({ feature }) => feature.name, "asc"),
+);
+
+const columns: Array<GridColDef<Feature>> = [
+  {
+    field: "name",
+    headerName: t("Feature.Name"),
+    width: 200,
+    editable: true,
+    renderHeader: EditableColumnHeader,
+  },
+  {
+    field: "status",
+    headerName: t("Feature.Status"),
+    width: 200,
+    type: "singleSelect",
+    valueOptions: featureStatusEnum.enumValues.map((status) => ({
+      value: status,
+      label: t(`FeatureStatus.${status}`),
+    })),
+  },
+];
+
+const handleOnDelete = createOptimisticAction<Array<string>>({
+  onMutate: (ids) => {
+    ids.forEach((id) => {
+      featureCollection.delete(id);
+    });
+  },
+  mutationFn: async (ids) => {
+    deleteFeatures({ data: ids });
+    await featureCollection.utils.refetch();
+  },
+});
+
+return (
+  <Fullscreen>
+    <DataGridPremium
+      rows={data}
+      columns={columns}
+      showToolbar
+      loading={isLoading}
+      ignoreDiacritics
+      onRowDoubleClick={({ row }) => navigate({ to: "/features/$id", params: { id: row.id } })}
+      cellSelection
+      disableRowSelectionOnClick
+      cellSelectionModel={cellSelectionModel}
+      onCellSelectionModelChange={(newModel) => setCellSelectionModel(newModel)}
+      slots={{ toolbar: DataGridToolbar }}
+      slotProps={{
+        toolbar: {
+          title: t("Feature.Features"),
+          actions: [
+            <Tooltip key="create" title={t("Create")}>
+              <RouterIconButton to="/features/create">
+                <Add fontSize="small" />
+              </RouterIconButton>
+            </Tooltip>,
+            Object.keys(cellSelectionModel).length === 1 && (
+              <Tooltip key="edit" title={t("Edit")}>
+                <RouterIconButton
+                  to="/features/edit/$id"
+                  params={{ id: Object.keys(cellSelectionModel)[0].toString() }}
+                >
+                  <Edit fontSize="small" />
+                </RouterIconButton>
+              </Tooltip>
+            ),
+            Object.keys(cellSelectionModel).length > 0 && (
+              <Tooltip key="delete" title={t("Delete")}>
+                <IconButton
+                  onClick={async () => {
+                    const confirmed = await confirm(
+                      t("DeleteConfirmation", { count: Object.keys(cellSelectionModel).length }),
+                    );
+                    if (confirmed) {
+                      try {
+                        const transaction = handleOnDelete(
+                          Object.keys(cellSelectionModel).map((id) => id.toString()),
+                        );
+                        await transaction.isPersisted.promise;
+                        setCellSelectionModel({});
+                      } catch (error) {
+                        if (error instanceof Error) await alert(error.message);
+                      }
+                    }
+                  }}
+                >
+                  <Badge
+                    badgeContent={Object.keys(cellSelectionModel).length}
+                    invisible={Object.keys(cellSelectionModel).length <= 1}
+                    color="error"
+                  >
+                    <Delete fontSize="small" />
+                  </Badge>
+                </IconButton>
+              </Tooltip>
+            ),
+          ],
+        },
+      }}
+    />
+  </Fullscreen>
+);
+```

package/skills/notifications/SKILL.md

@@ -8,8 +8,8 @@ description: "Use when: displaying success, error, warning, or informational fee
 - Use `useNotification()` for lightweight non-blocking user feedback.
 - Always use translation; add new keys for feature-specific messages.
 - Notifications are automatically queued by the provider and shown one at a time.
-- `autoHideDuration` defaults to 5000 ms; override it (up to 10000 ms) only for messages that need more reading time.
-- Use `severity: "success" | "info" | "warning" | "error"` consistently with the outcome.
+- `autoHideDuration` defaults to 5000 ms and is not capped by the library; keep overrides reasonable (~10000 ms) for messages that need more reading time.
+- Use `severity: "success" | "info" | "warning" | "error"` consistently with the outcome. Severity is optional — omitting it renders a plain snackbar (no colored `Alert`).
 - Use notifications for lightweight feedback; dialogs when the user must decide or acknowledge.
 
 ## File Placement

package/skills/routing/SKILL.md

@@ -3,9 +3,11 @@ name: routing
 description: "Use when: creating or modifying TanStack Router routes, feature folders, navigation, permissions, loaders, suspense flows, or route-scoped components/hooks."
 ---
 
+> Mechanics (`createFileRoute`, `beforeLoad`, `redirect`, `loader`, preloading, `pendingComponent`) are covered by TanStack's own skills — load `@tanstack/router-core#router-core/auth-and-guards`, `#router-core/data-loading`, and `#router-core/navigation` for the API details. This skill adds only the wcz-layout conventions on top.
+
 ## Rules
 
-- Always include `requirePermission("all")` in the route's `beforeLoad` function to enforce access control unless the route is meant to be public.
+- Include the `requirePermission(<permissionKey>)` function in the route's `beforeLoad` to enforce access control — pass a key defined in your app's `src/lib/auth/permissions.ts`; omit it only for intentionally public routes.
 - Use `Route.useRouteContext()` to access the authenticated user. User can be `null` if the route doesn't include `requirePermission`.
 - Use the route `loader` option to preload db collections. Preload only root-level collections.
 - Create a `pendingComponent` for routes that suspend or preload meaningful data.
@@ -15,6 +17,7 @@ description: "Use when: creating or modifying TanStack Router routes, feature fo
 - Colocate route-specific components/hooks inside `routes/<feature>/-components` or `-hooks`.
 - Root-level `components/` and `hooks/` are only for code shared across multiple routes.
 - After creating a new route, add or ask for a navigation item with a unique icon from `@mui/icons-material` in `src/routes/__root.tsx`.
+- For navigation and redirects, always use the type-safe router components from `wcz-layout/components` (`RouterButton`, `RouterIconButton`, `RouterLink`, `RouterFab`, `RouterTab`, `RouterListItemButton`, `RouterGridActionsCellItem`) rather than raw MUI with a manual `href` — they wrap `createLink`, so `to`/`params`/`search` are type-checked.
 
 ## Base Project Structure
 
@@ -64,7 +67,7 @@ import { requirePermission, uuidv7 } from "wcz-layout/utils";
 // src/routes/features/create.tsx
 export const Route = createFileRoute("/features/create")({
   component: RouteComponent,
-  beforeLoad: requirePermission("all"),
+  beforeLoad: requirePermission("admin"),
   pendingComponent: FeatureSkeleton,
   loader: () => {
     featureCollection.preload();
@@ -119,10 +122,11 @@ const navigation: Navigation = [
   },
 ];
 
-// Routes are public by default. Protect a route by adding requirePermission to
-// its beforeLoad — it redirects to login when signed out, then checks the group.
+// Routes are public unless guarded. By convention, protect every route by adding
+// requirePermission to its beforeLoad (omit only for intentionally public routes) —
+// it redirects to login when signed out, then checks the permission group.
 export const Route = createFileRoute("/feature-name")({
   component: RouteComponent,
-  beforeLoad: requirePermission("all"),
+  beforeLoad: requirePermission("admin"),
 });
 ```

package/skills/server-functions/SKILL.md

@@ -3,13 +3,15 @@ name: server-functions
 description: "Use when: creating or modifying TanStack Start server functions, REST routes, middleware, validation, database transactions, external service calls, or permission checks."
 ---
 
+> Mechanics (`createServerFn`, `.validator`, `createMiddleware`, `createHandlers`) are covered by TanStack's own skills — load `@tanstack/start-client-core#start-core/server-functions`, `#start-core/middleware`, and `#start-core/server-routes` for the API details. This skill adds only the wcz-layout middleware conventions on top.
+
 ## Rules
 
 - Before generating code, clarify whether the feature should be exposed as public REST API routes or implemented as internal TanStack Start server functions (recommended), and what permission should be required for access.
 - If permission is unknown, use `"all"`.
 - Every server function MUST include `authorizationMiddleware` — server functions are callable RPC endpoints, so a route-level `requirePermission` in `beforeLoad` only hides the UI and does not protect them.
-- Follow the chain order for server functions: `validator` → `middleware` → `handler`.
-- In middleware, always follow this order: `validationMiddleware` → `authorizationMiddleware` → `databaseMiddleware` (reject unauthorized callers before opening a DB transaction).
+- Follow the chain order for server functions: `middleware` → `validator` → `handler`.
+- `authorizationMiddleware` MUST be the LAST middleware in the array so its `context.user` (a non-null `User`) is the value that reaches the handler — `databaseMiddleware` re-derives `user` as nullable, so putting it after would widen the type back to `User | null`. Order: `[databaseMiddleware, authorizationMiddleware(<key>)]`. In REST routes, `validationMiddleware` also comes before `authorizationMiddleware`.
 - Use `validationMiddleware` only in REST API routes. Server functions use `.validator()`.
 - `databaseMiddleware` wraps the handler in a DB transaction and sets `app.user_name` so audit triggers can record who made the change.
 - Reuse schemas from `src/lib/schemas/`.
@@ -31,28 +33,28 @@ src/lib/auth/permissions.ts     — permission keys
 ```ts
 // src/server/actions/<feature>.ts
 export const selectFeatures = createServerFn()
-  .middleware([authorizationMiddleware("all"), databaseMiddleware])
+  .middleware([databaseMiddleware, authorizationMiddleware("all")])
   .handler(async ({ context }) => {
     return await context.db.select().from(featureTable);
   });
 
 export const insertFeature = createServerFn({ method: "POST" })
+  .middleware([databaseMiddleware, authorizationMiddleware("admin")])
   .validator(FeatureSchema)
-  .middleware([authorizationMiddleware("admin"), databaseMiddleware])
   .handler(async ({ data, context }) => {
     await context.db.insert(featureTable).values(data);
   });
 
 export const updateFeature = createServerFn({ method: "POST" })
+  .middleware([databaseMiddleware, authorizationMiddleware("admin")])
   .validator(FeatureSchema)
-  .middleware([authorizationMiddleware("admin"), databaseMiddleware])
   .handler(async ({ data, context }) => {
     await context.db.update(featureTable).set(data).where(eq(featureTable.id, data.id));
   });
 
 export const deleteFeature = createServerFn({ method: "POST" })
+  .middleware([databaseMiddleware, authorizationMiddleware("admin")])
   .validator(FeatureSchema.pick({ id: true }))
-  .middleware([authorizationMiddleware("admin"), databaseMiddleware])
   .handler(async ({ data, context }) => {
     await context.db.delete(featureTable).where(eq(featureTable.id, data.id));
   });
@@ -60,21 +62,18 @@ export const deleteFeature = createServerFn({ method: "POST" })
 // src/routes/api/<feature>s/index.ts
 export const Route = createFileRoute("/api/features/")({
   server: {
+    middleware: [databaseMiddleware],
     handlers: ({ createHandlers }) =>
       createHandlers({
         GET: {
-          middleware: [authorizationMiddleware("all"), databaseMiddleware],
+          middleware: [authorizationMiddleware("all")],
           handler: async ({ context }) => {
             const items = await context.db.select().from(featureTable);
             return Response.json(items);
           },
         },
         POST: {
-          middleware: [
-            validationMiddleware(FeatureSchema),
-            authorizationMiddleware("admin"),
-            databaseMiddleware,
-          ],
+          middleware: [validationMiddleware(FeatureSchema), authorizationMiddleware("admin")],
           handler: async ({ context }) => {
             const [response] = await context.db
               .insert(featureTable)
@@ -90,7 +89,7 @@ export const Route = createFileRoute("/api/features/")({
 // src/routes/api/<feature>s/$id.ts
 export const Route = createFileRoute("/api/features/$id")({
   server: {
-    middleware: [authorizationMiddleware("admin"), databaseMiddleware],
+    middleware: [databaseMiddleware, authorizationMiddleware("admin")],
     handlers: ({ createHandlers }) =>
       createHandlers({
         PUT: {

package/skills/services/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: services
-description: "Use when: integrating file, approval, PeopleSoft, email, or attendance services into your workflow."
+description: "Use when: working with file, approval, employee or email services into your workflow."
 ---
 
 ## Info
@@ -9,7 +9,8 @@ You can read about each service in the links below. Services are categorized as
 
 - **Client exports** — Contains `queryOptions` and `mutationOptions`; use for data fetching/mutations on the client with React Query.
 - **Server exports** — Server functions; prefer calling mutations inside other server functions or database transactions.
-- All mutation options take `{ queryClient }` so they can invalidate related queries.
+- Invalidating mutation options take `{ queryClient }` so they can invalidate related queries; read-only ones (e.g. `downloadFileMutationOptions()`, `openFileMutationOptions()`) don't require it.
+- Access `queryClient` with `Route.useRouteContext()` in a route file, or `useRouteContext({ from: "path" })` in a component.
 - To read about a service, open the linked file in the **File** column directly.
 
 ## Import Paths

package/skills/services/docs/approval.md

@@ -163,8 +163,8 @@ const ApprovalSchema = z.object({
   createdBy: z.custom<ApprovalEmployee>(),
   updated: z.date().optional(),
   updatedBy: z.custom<ApprovalEmployee>().optional(),
-  approvalFlows: z.array(ApprovalFlow).min(1),
-  currentApprovers: z.array(ApprovalEmployee),
+  approvalFlows: z.array(z.custom<ApprovalFlow>()).min(1),
+  currentApprovers: z.array(z.custom<ApprovalEmployee>()),
   coRequestors: z.array(ApprovalCoRequestorSchema).optional(),
 });
 

package/skills/services/docs/file.md

@@ -68,14 +68,41 @@ const UploadFileMetaSchema = z.object({
 ## Examples
 
 ```ts
-import { fileMetasQueryOptions, uploadFileMutationOptions } from "wcz-layout/data/client";
+import { fileMetasQueryOptions, fileQueryOptions, uploadFileMutationOptions } from "wcz-layout/data/client";
+import { Dropzone, FileViewer } from "wcz-layout/components";
+import { useInView } from "wcz-layout/hooks";
 
-const queryClient = useQueryClient();
+// fetch metas + fetch first file
+const { ref, inView } = useInView();
 
-const { data: files = [] } = useQuery(fileMetasQueryOptions({ appName, subId }));
+const { data: fileMetas = [] } = useQuery({
+  ...fileMetasQueryOptions({ appName: packageJson.name, subId }),
+  enabled: inView,
+});
+
+const { data: file } = useQuery({
+  ...fileQueryOptions({ appName: packageJson.name, id: fileMetas[0]?.id ?? "" }),
+  enabled: !!fileMetas[0],
+});
 
 // upload
 const [progress, setProgress] = useState(0);
-const { mutate: upload, isPending } = useMutation(uploadFileMutationOptions({ queryClient }));
-upload({ appName, subId, file, setProgress });
+const { mutateAsync: uploadFile } = useMutation(uploadFileMutationOptions({ queryClient }));
+
+// Dropzone
+const onDrop = async (acceptedFiles: File[]) => {
+  await Promise.allSettled(
+    acceptedFiles.map((file) =>
+      uploadFile({ appName: packageJson.name, subId, file, setProgress }),
+    ),
+  );
+  setUploadProgress(0);
+};
+
+<Dropzone onDrop={onDrop} progress={progress} />
+
+// File Viewer - no manual fetch metas needed (default)
+<FileViewer appName={packageJson.name} subId={subId}>
+  {(component) => <component.Grid />} // or component.List
+</FileViewer>
 ```

package/skills/start/steps/04-database-setup.md

@@ -1,6 +1,6 @@
 # Database Setup
 
-> Values written to `.env.local` here are temporary when the project uses Vault: the Vault Setup step moves them into the Vault `default` secret (only `DATABASE_URL` stays in `.env.local`, for drizzle-studio).
+> Create `.env.local` if it does not exist, then preserve its existing keys when setting database values. Values written here are temporary when the project uses Vault: the Vault Setup step moves them into the Vault `default` secret. Both `DATABASE_URL` and `DATABASE_SCHEMA` stay in `.env.local` — drizzle-kit (`db:studio`, `db:generate`) reads both.
 
 ## User Input
 
@@ -34,6 +34,8 @@ docker run --name <project-name>-postgres -e POSTGRES_PASSWORD=<password> -d -p
 - **Success** → continue.
 - **Error** → stop and show the full error to the user.
 
-5. Update `.env.local` → set `DATABASE_URL=postgres://postgres:<password>@localhost:<PORT>/postgres`.
+5. Update `.env.local`:
+   - Set `DATABASE_URL=postgres://postgres:<password>@localhost:<PORT>/postgres`.
+   - Set `DATABASE_SCHEMA=public`.
 6. Output exactly:
    > ✅ Local Postgres database created successfully on port [PORT]

package/skills/start/steps/06-vault-setup.md

@@ -1,6 +1,6 @@
 # Vault Setup
 
-Never print user-provided secret values into chat, files, or logs — reference only the env keys and where each value lives. The one value the AI generates itself is `SESSION_SECRET`: a fresh 64-char hex string via `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`. The template ships only `VITE_MUI_LICENSE_KEY` in `.env`; all project configuration goes into the gitignored `.env.local` created in this step.
+Never print user-provided secret values into chat, files, or logs — reference only the env keys and where each value lives. The one value the AI generates itself is `SESSION_SECRET`: a fresh 64-char hex string via `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`. The template ships only `VITE_MUI_LICENSE_KEY` in `.env`; all project configuration goes into the gitignored `.env.local`, which may have been created by an earlier setup step and is normalized in this step.
 
 ## User Input
 
@@ -21,23 +21,23 @@ Output:
 > 2. In your app's root path, create a secret named exactly `harborvault`: toggle 'JSON' mode, then copy-paste the JSON values from another app's `harborvault` secret and save.
 > 3. Open your app's `default` secret, click 'Edit' (toggle 'View as JSON'), fill in these keys, then save. Provide user this in JSON to copy-paste — empty string values, except `SESSION_SECRET`, which you pre-fill with a freshly generated value:
 >
-> | Key                     | Value source                                                    |
-> | ----------------------- | --------------------------------------------------------------- |
-> | `ENTRA_CLIENT_ID`       | the Entra ID step                                               |
-> | `ENTRA_TENANT_ID`       | same for all Wistron apps — copy from another project           |
-> | `ENTRA_CLIENT_SECRET`   | your Entra ID application                                       |
-> | `SESSION_SECRET`        | already pre-filled in the JSON — generated by the AI            |
-> | `DATABASE_SCHEMA`       | the database step                                               |
-> | `DATABASE_AUTO_MIGRATE` | `true` unless you manage migrations manually                    |
-> | `DATABASE_URL`          | the database step                                               |
+> | Key                     | Value source                                          |
+> | ----------------------- | ----------------------------------------------------- |
+> | `ENTRA_CLIENT_ID`       | the Entra ID step                                     |
+> | `ENTRA_TENANT_ID`       | same for all Wistron apps — copy from another project |
+> | `ENTRA_CLIENT_SECRET`   | your Entra ID application                             |
+> | `SESSION_SECRET`        | already pre-filled in the JSON — generated by the AI  |
+> | `DATABASE_SCHEMA`       | the database step                                     |
+> | `DATABASE_AUTO_MIGRATE` | `true` unless you manage migrations manually          |
+> | `DATABASE_URL`          | the database step                                     |
 >
 > When finished, type 'done'.
 
 Wait for "done".
 
-### Part 2 — Create `.env.local`
+### Part 2 — Normalize `.env.local`
 
-Rewrite `.env.local` so it contains **only** the keys below. Never fill in secret values yourself — keep values empty except `DATABASE_URL`, where you keep the value if the database step already set one:
+Rewrite `.env.local` so it contains **only** the keys below. Never fill in secret values yourself — keep values empty except `DATABASE_URL` and `DATABASE_SCHEMA`, where you keep the values if the database step already set them (drizzle-kit reads both):
 
 ```dotenv
 VAULT_ADDRESS=
@@ -46,6 +46,7 @@ VAULT_USERNAME=
 VAULT_PASSWORD=
 
 DATABASE_URL=
+DATABASE_SCHEMA=
 ```
 
 Then ask the user to fill in the empty values directly in `.env.local` (not in chat) and type 'done'. Wait for "done".