@podosoft/podokit 0.11.1 → 0.11.2

package/dist/add.d.ts

@@ -18,6 +18,9 @@ export interface ModuleManifest {
     dependencies?: Record<string, string>;
     devDependencies?: Record<string, string>;
     scripts?: Record<string, string>;
+    /** Extra package.json overlays keyed by app name. Use when a module's files
+     *  span more than its primary targetApp. */
+    packageOverlays?: Record<string, PackageOverlay>;
     env?: string[];
     inject?: Injection[];
     instructions?: string[];
@@ -29,7 +32,17 @@ export interface ModuleManifest {
     /** Paths that an existing app may explicitly hand back to this module with
      *  `podo add --adopt`. Broad app-owned route globs are never removed. */
     managedGlobs?: string[];
+    /** Module files that remain update-managed even when a broad default glob
+     *  (for example `.claude/**`) would otherwise classify them as owned. */
+    managedOverrides?: string[];
 }
+export interface PackageOverlay {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    scripts?: Record<string, string>;
+}
+/** Return the legacy targetApp package fields plus any additional app overlays. */
+export declare function modulePackageOverlays(manifest: ModuleManifest): Map<string, PackageOverlay>;
 export interface AddOptions {
     projectRoot: string;
     module: string;
@@ -46,6 +59,8 @@ export interface AddResult {
     added: string[];
     /** ownedGlobs declared by this module and every module it pulled in. */
     ownedGlobs: string[];
+    /** Managed exceptions declared by this module and its requirements. */
+    managedOverrides: string[];
     /** Existing owned presentation files intentionally left untouched. */
     preserved: string[];
     /** Paths explicitly adopted as module-managed files. */
@@ -75,6 +90,7 @@ export declare function listModules(modulesDir: string, projectRoot?: string): {
     name: string;
     description: string;
 }[];
+export declare function readModuleManifest(moduleDir: string): ModuleManifest;
 /**
  * Apply a module to an existing generated project: overlay files, merge the
  * target app's package.json dependencies and scripts, append env example lines,

package/dist/add.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SUPPORTED_MANIFEST_VERSION = void 0;
+exports.modulePackageOverlays = modulePackageOverlays;
 exports.resolveModuleDir = resolveModuleDir;
 exports.resolveModule = resolveModule;
 exports.listModules = listModules;
+exports.readModuleManifest = readModuleManifest;
 exports.addModule = addModule;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
@@ -13,6 +15,34 @@ const lockfile_1 = require("./lockfile");
 /** Highest `module.manifest.json` schema version this CLI understands. A package
  *  module declaring a higher version is rejected rather than mis-applied. */
 exports.SUPPORTED_MANIFEST_VERSION = 1;
+/** Return the legacy targetApp package fields plus any additional app overlays. */
+function modulePackageOverlays(manifest) {
+    const overlays = new Map();
+    const merge = (app, overlay) => {
+        const current = overlays.get(app) ?? {};
+        overlays.set(app, {
+            ...(current.dependencies || overlay.dependencies
+                ? { dependencies: { ...current.dependencies, ...overlay.dependencies } }
+                : {}),
+            ...(current.devDependencies || overlay.devDependencies
+                ? { devDependencies: { ...current.devDependencies, ...overlay.devDependencies } }
+                : {}),
+            ...(current.scripts || overlay.scripts
+                ? { scripts: { ...current.scripts, ...overlay.scripts } }
+                : {}),
+        });
+    };
+    if (manifest.dependencies || manifest.devDependencies || manifest.scripts) {
+        merge(manifest.targetApp, {
+            dependencies: manifest.dependencies,
+            devDependencies: manifest.devDependencies,
+            scripts: manifest.scripts,
+        });
+    }
+    for (const [app, overlay] of Object.entries(manifest.packageOverlays ?? {}))
+        merge(app, overlay);
+    return overlays;
+}
 const PACKAGE_PREFIX = "@podosoft/podokit-module-";
 /**
  * Resolve a module's directory by name: first the bundled `modulesDir`, then a
@@ -38,7 +68,7 @@ function resolveModule(name, modulesDir, projectRoot) {
     const dir = resolveModuleDir(name, modulesDir, projectRoot);
     if (!dir)
         return null;
-    const manifest = readManifest(dir);
+    const manifest = readModuleManifest(dir);
     const bundled = (0, node_path_1.join)(modulesDir, manifest.name);
     if (dir === bundled)
         return { dir, name: manifest.name };
@@ -66,7 +96,7 @@ function listModules(modulesDir, projectRoot) {
     if ((0, node_fs_1.existsSync)(modulesDir)) {
         for (const name of (0, node_fs_1.readdirSync)(modulesDir)) {
             if ((0, node_fs_1.existsSync)((0, node_path_1.join)(modulesDir, name, "module.manifest.json"))) {
-                out.set(name, readManifest((0, node_path_1.join)(modulesDir, name)).description);
+                out.set(name, readModuleManifest((0, node_path_1.join)(modulesDir, name)).description);
             }
         }
     }
@@ -79,7 +109,7 @@ function listModules(modulesDir, projectRoot) {
                 const manifestPath = (0, node_path_1.join)(scope, dir, "module.manifest.json");
                 if (!(0, node_fs_1.existsSync)(manifestPath))
                     continue;
-                const manifest = readManifest((0, node_path_1.join)(scope, dir));
+                const manifest = readModuleManifest((0, node_path_1.join)(scope, dir));
                 if (!out.has(manifest.name))
                     out.set(manifest.name, manifest.description);
             }
@@ -87,7 +117,7 @@ function listModules(modulesDir, projectRoot) {
     }
     return [...out].map(([name, description]) => ({ name, description }));
 }
-function readManifest(moduleDir) {
+function readModuleManifest(moduleDir) {
     return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(moduleDir, "module.manifest.json"), "utf8"));
 }
 function readJson(path) {
@@ -113,7 +143,7 @@ function isApplied(projectRoot, modulesDir, module) {
     const moduleDir = resolveModuleDir(module, modulesDir, projectRoot);
     if (!moduleDir)
         return false;
-    const manifest = readManifest(moduleDir);
+    const manifest = readModuleManifest(moduleDir);
     const firstInject = manifest.inject?.[0];
     if (firstInject) {
         const target = (0, node_path_1.join)(projectRoot, firstInject.file);
@@ -153,7 +183,7 @@ function addModule(options) {
             modulePaths: [...new Set(result.touched)],
             adoptedPaths: result.adopted,
         }
-        : undefined);
+        : undefined, result.managedOverrides);
     return result;
 }
 function applyModule(projectRoot, module, modulesDir, applied, adopt) {
@@ -163,16 +193,18 @@ function applyModule(projectRoot, module, modulesDir, applied, adopt) {
         throw new Error(`Unknown module "${module}".${available.length ? ` Available: ${available.join(", ")}.` : ""}`);
     }
     const moduleDir = resolved.dir;
-    const manifest = readManifest(moduleDir);
+    const manifest = readModuleManifest(moduleDir);
     assertManifestVersion(module, manifest);
-    const appPkgPath = (0, node_path_1.join)(projectRoot, "apps", manifest.targetApp, "package.json");
-    if (!(0, node_fs_1.existsSync)(appPkgPath)) {
-        throw new Error(`This does not look like a PodoKit project: ${(0, node_path_1.join)("apps", manifest.targetApp, "package.json")} not found. Run inside a generated project.`);
+    const requiredApps = new Set([manifest.targetApp, ...Object.keys(manifest.packageOverlays ?? {})]);
+    const missingApp = [...requiredApps].find((app) => !(0, node_fs_1.existsSync)((0, node_path_1.join)(projectRoot, "apps", app, "package.json")));
+    if (missingApp) {
+        throw new Error(`This does not look like a PodoKit project: ${(0, node_path_1.join)("apps", missingApp, "package.json")} not found. Run inside a generated project.`);
     }
     applied.add(module);
     // 0) apply required modules first (auto-add if missing)
     const added = [];
     const ownedGlobs = [...(manifest.ownedGlobs ?? [])];
+    const managedOverrides = [...(manifest.managedOverrides ?? [])];
     const preserved = [];
     const adopted = [];
     const touched = [];
@@ -182,6 +214,7 @@ function applyModule(projectRoot, module, modulesDir, applied, adopt) {
         const result = applyModule(projectRoot, required, modulesDir, applied, adopt);
         added.push(required, ...result.added);
         ownedGlobs.push(...result.ownedGlobs);
+        managedOverrides.push(...result.managedOverrides);
         preserved.push(...result.preserved);
         adopted.push(...result.adopted);
         touched.push(...result.touched);
@@ -202,18 +235,19 @@ function applyModule(projectRoot, module, modulesDir, applied, adopt) {
         adopted.push(...copied.adopted);
         touched.push(...copied.touched);
     }
-    // 2) merge dependencies and scripts into the target app
-    if (manifest.dependencies || manifest.devDependencies || manifest.scripts) {
+    // 2) merge dependencies and scripts into every declared app package
+    for (const [app, declaration] of modulePackageOverlays(manifest)) {
+        const appPkgPath = (0, node_path_1.join)(projectRoot, "apps", app, "package.json");
         const overlay = {};
-        if (manifest.dependencies)
-            overlay.dependencies = manifest.dependencies;
-        if (manifest.devDependencies)
-            overlay.devDependencies = manifest.devDependencies;
-        if (manifest.scripts)
-            overlay.scripts = manifest.scripts;
+        if (declaration.dependencies)
+            overlay.dependencies = declaration.dependencies;
+        if (declaration.devDependencies)
+            overlay.devDependencies = declaration.devDependencies;
+        if (declaration.scripts)
+            overlay.scripts = declaration.scripts;
         const merged = (0, podokit_template_engine_1.mergePackageJson)(readJson(appPkgPath), overlay);
         (0, node_fs_1.writeFileSync)(appPkgPath, `${JSON.stringify(merged, null, 2)}\n`);
-        touched.push(`apps/${manifest.targetApp}/package.json`);
+        touched.push(`apps/${app}/package.json`);
     }
     // 3) append env example lines
     if (manifest.env?.length) {
@@ -235,7 +269,16 @@ function applyModule(projectRoot, module, modulesDir, applied, adopt) {
         touched.push(injection.file);
     }
     const instructions = (manifest.instructions ?? []).map((line) => line.replace(/<app>/g, appName));
-    return { module: manifest.name, instructions, added, ownedGlobs, preserved, adopted, touched };
+    return {
+        module: manifest.name,
+        instructions,
+        added,
+        ownedGlobs,
+        managedOverrides,
+        preserved,
+        adopted,
+        touched,
+    };
 }
 function moduleRecord(module) {
     return {

package/dist/assemble.js

@@ -22,17 +22,17 @@ function applyModuleToTree(tree, moduleDir, vars) {
         for (const [path, file] of (0, podokit_template_engine_1.renderTemplate)(filesDir, vars))
             tree.set(path, file);
     }
-    // 2) merge dependencies/scripts into the target app's package.json
-    if (manifest.dependencies || manifest.devDependencies || manifest.scripts) {
-        const pkgPath = `apps/${manifest.targetApp}/package.json`;
+    // 2) merge dependencies/scripts into every declared app package.json
+    for (const [app, declaration] of (0, add_1.modulePackageOverlays)(manifest)) {
+        const pkgPath = `apps/${app}/package.json`;
         const base = JSON.parse(textOf(tree, pkgPath) || "{}");
         const overlay = {};
-        if (manifest.dependencies)
-            overlay.dependencies = manifest.dependencies;
-        if (manifest.devDependencies)
-            overlay.devDependencies = manifest.devDependencies;
-        if (manifest.scripts)
-            overlay.scripts = manifest.scripts;
+        if (declaration.dependencies)
+            overlay.dependencies = declaration.dependencies;
+        if (declaration.devDependencies)
+            overlay.devDependencies = declaration.devDependencies;
+        if (declaration.scripts)
+            overlay.scripts = declaration.scripts;
         setText(tree, pkgPath, `${JSON.stringify((0, podokit_template_engine_1.mergePackageJson)(base, overlay), null, 2)}\n`);
     }
     // 3) append env example lines (deduped)

package/dist/lockfile.d.ts

@@ -32,6 +32,8 @@ export interface PodokitManifest {
     modules: ManifestModule[];
     /** Globs whose files are user-owned and never touched by update. */
     ownedGlobs: string[];
+    /** Module-supplied globs that stay managed even inside a broad owned glob. */
+    managedOverrides?: string[];
 }
 export interface FileEntry {
     tier: Tier;
@@ -64,11 +66,11 @@ export declare function podokitVersion(): string;
 /** Match a POSIX relative path against a simple glob supporting `*` and `**`. */
 export declare function matchGlob(path: string, glob: string): boolean;
 /** Classify a file's ownership tier. See ADR-0010 priority order. */
-export declare function classifyTier(relPath: string, content: string | Buffer, ownedGlobs: string[]): Tier;
+export declare function classifyTier(relPath: string, content: string | Buffer, ownedGlobs: string[], managedOverrides?: string[]): Tier;
 /** List project files as POSIX-relative paths, skipping generated/vendored dirs. */
 export declare function walkFiles(projectRoot: string, prefix?: string): string[];
 /** Recompute the files.lock by hashing and classifying every project file. */
-export declare function computeFilesLock(projectRoot: string, ownedGlobs: string[]): FilesLock;
+export declare function computeFilesLock(projectRoot: string, ownedGlobs: string[], managedOverrides?: string[]): FilesLock;
 export declare function readFilesLock(projectRoot: string): FilesLock | null;
 export interface Drift {
     /** Managed/assembled files whose content differs from what PodoKit wrote. */
@@ -101,4 +103,4 @@ export declare function mergeOwnedGlobs(existing: string[], add: string[]): stri
  * `ownedGlobs` a module declares are merged into the manifest so its owned paths
  * survive every future recompute. No-op on projects without a manifest.
  */
-export declare function recordModules(projectRoot: string, moduleInputs: (string | ManifestModuleInput)[], version?: string, ownedGlobs?: string[], lockSnapshot?: RecordModulesLockSnapshot): void;
+export declare function recordModules(projectRoot: string, moduleInputs: (string | ManifestModuleInput)[], version?: string, ownedGlobs?: string[], lockSnapshot?: RecordModulesLockSnapshot, managedOverrides?: string[]): void;

package/dist/lockfile.js

@@ -114,7 +114,12 @@ function isTextPath(relPath) {
     return relPath.startsWith("dot-") || TEXT_EXT.test(relPath);
 }
 /** Classify a file's ownership tier. See ADR-0010 priority order. */
-function classifyTier(relPath, content, ownedGlobs) {
+function classifyTier(relPath, content, ownedGlobs, managedOverrides = []) {
+    const explicitlyOwned = ownedGlobs.some((glob) => !glob.includes("*") && matchGlob(relPath, glob));
+    if (explicitlyOwned)
+        return "owned";
+    if (managedOverrides.some((glob) => matchGlob(relPath, glob)))
+        return "managed";
     if (ownedGlobs.some((glob) => matchGlob(relPath, glob)))
         return "owned";
     if (isTextPath(relPath) && content.toString("utf8").includes(INJECTION_MARKER))
@@ -138,11 +143,14 @@ function walkFiles(projectRoot, prefix = "") {
     return out;
 }
 /** Recompute the files.lock by hashing and classifying every project file. */
-function computeFilesLock(projectRoot, ownedGlobs) {
+function computeFilesLock(projectRoot, ownedGlobs, managedOverrides = []) {
     const files = {};
     for (const rel of walkFiles(projectRoot).sort()) {
         const content = (0, node_fs_1.readFileSync)((0, node_path_1.join)(projectRoot, rel));
-        files[rel] = { tier: classifyTier(rel, content, ownedGlobs), outHash: (0, podokit_template_engine_1.hashContent)(content) };
+        files[rel] = {
+            tier: classifyTier(rel, content, ownedGlobs, managedOverrides),
+            outHash: (0, podokit_template_engine_1.hashContent)(content),
+        };
     }
     return { schemaVersion: exports.LOCK_SCHEMA_VERSION, files };
 }
@@ -185,6 +193,7 @@ function initLockfile(projectRoot, options) {
         answers: options.answers,
         modules: [],
         ownedGlobs,
+        managedOverrides: [],
     };
     writeManifest(projectRoot, manifest);
     writeFilesLock(projectRoot, computeFilesLock(projectRoot, ownedGlobs));
@@ -209,7 +218,7 @@ function mergeOwnedGlobs(existing, add) {
  * `ownedGlobs` a module declares are merged into the manifest so its owned paths
  * survive every future recompute. No-op on projects without a manifest.
  */
-function recordModules(projectRoot, moduleInputs, version, ownedGlobs, lockSnapshot) {
+function recordModules(projectRoot, moduleInputs, version, ownedGlobs, lockSnapshot, managedOverrides) {
     const manifest = readManifest(projectRoot);
     if (!manifest)
         return;
@@ -234,8 +243,11 @@ function recordModules(projectRoot, moduleInputs, version, ownedGlobs, lockSnaps
     }
     if (ownedGlobs?.length)
         manifest.ownedGlobs = mergeOwnedGlobs(manifest.ownedGlobs, ownedGlobs);
+    if (managedOverrides?.length) {
+        manifest.managedOverrides = mergeOwnedGlobs(manifest.managedOverrides ?? [], managedOverrides);
+    }
     writeManifest(projectRoot, manifest);
-    const computed = computeFilesLock(projectRoot, manifest.ownedGlobs);
+    const computed = computeFilesLock(projectRoot, manifest.ownedGlobs, manifest.managedOverrides ?? []);
     if (!lockSnapshot) {
         writeFilesLock(projectRoot, computed);
         return;

package/dist/remove.js

@@ -107,8 +107,11 @@ function removeModule(options) {
     manifest.modules = manifest.modules
         .filter((m) => m.name !== module)
         .map((m, i) => ({ ...m, order: i }));
+    const sharedManagedOverrides = new Set(others.flatMap((other) => other.manifest.managedOverrides ?? []));
+    const targetManagedOverrides = new Set(targetManifest.managedOverrides ?? []);
+    manifest.managedOverrides = (manifest.managedOverrides ?? []).filter((glob) => !targetManagedOverrides.has(glob) || sharedManagedOverrides.has(glob));
     (0, lockfile_1.writeManifest)(projectRoot, manifest);
-    (0, lockfile_1.writeFilesLock)(projectRoot, (0, lockfile_1.computeFilesLock)(projectRoot, manifest.ownedGlobs));
+    (0, lockfile_1.writeFilesLock)(projectRoot, (0, lockfile_1.computeFilesLock)(projectRoot, manifest.ownedGlobs, manifest.managedOverrides));
     return { module, removed, keptEdited, keptShared, unwired };
 }
 /** Remove now-empty directories left behind by a deleted file, up to the root. */
@@ -126,33 +129,33 @@ function pruneEmptyDirs(projectRoot, relDir) {
     }
 }
 function pruneAppPackage(projectRoot, target, others) {
-    if (!(target.dependencies || target.devDependencies || target.scripts))
-        return;
-    const appPkgPath = (0, node_path_1.join)(projectRoot, "apps", target.targetApp, "package.json");
-    if (!(0, node_fs_1.existsSync)(appPkgPath))
-        return;
-    const keep = (section) => new Set(others.flatMap((o) => Object.keys(o.manifest[section] ?? {})));
-    const pkg = readJson(appPkgPath);
-    let changed = false;
-    for (const section of ["dependencies", "devDependencies", "scripts"]) {
-        const declared = target[section];
-        const current = pkg[section];
-        if (!declared || !current)
+    for (const [app, declaration] of (0, add_1.modulePackageOverlays)(target)) {
+        const appPkgPath = (0, node_path_1.join)(projectRoot, "apps", app, "package.json");
+        if (!(0, node_fs_1.existsSync)(appPkgPath))
             continue;
-        const shared = keep(section);
-        for (const name of Object.keys(declared)) {
-            if (shared.has(name))
+        const keep = (section) => new Set(others.flatMap((other) => Object.keys((0, add_1.modulePackageOverlays)(other.manifest).get(app)?.[section] ?? {})));
+        const pkg = readJson(appPkgPath);
+        let changed = false;
+        for (const section of ["dependencies", "devDependencies", "scripts"]) {
+            const declared = declaration[section];
+            const current = pkg[section];
+            if (!declared || !current)
                 continue;
-            if (name in current) {
-                delete current[name];
-                changed = true;
+            const shared = keep(section);
+            for (const name of Object.keys(declared)) {
+                if (shared.has(name))
+                    continue;
+                if (name in current) {
+                    delete current[name];
+                    changed = true;
+                }
             }
+            if (current && Object.keys(current).length === 0)
+                delete pkg[section];
         }
-        if (current && Object.keys(current).length === 0)
-            delete pkg[section];
+        if (changed)
+            (0, node_fs_1.writeFileSync)(appPkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
     }
-    if (changed)
-        (0, node_fs_1.writeFileSync)(appPkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
 }
 function pruneEnvExample(projectRoot, target, others) {
     if (!target.env?.length)

package/dist/templates/fullstack-nest-svelte/apps/api/Dockerfile

@@ -20,6 +20,7 @@ RUN addgroup -S app && adduser -S app -G app
 COPY --from=build /app/node_modules ./node_modules
 COPY --from=deps /app/apps/api ./apps/api
 COPY --from=build /app/apps/api/dist ./apps/api/dist
+COPY --from=build /app/apps/api/scripts ./apps/api/scripts
 WORKDIR /app/apps/api
 USER app
 EXPOSE 3000

package/dist/templates/fullstack-nest-svelte/apps/api/scripts/.keep

@@ -0,0 +1 @@
+

package/dist/templates/fullstack-nest-svelte/compose.dev.yaml

@@ -83,6 +83,7 @@ services:
         # sync+restart is the stable, recommended approach; the web keeps instant
         # HMR via plain sync.
         - { action: sync+restart, path: ./apps/api/src, target: /app/apps/api/src }
+        - { action: sync, path: ./apps/api/scripts, target: /app/apps/api/scripts }
         - { action: rebuild, path: ./apps/api/package.json }
 
   worker:
@@ -105,6 +106,7 @@ services:
         # sync+restart is the stable, recommended approach; the web keeps instant
         # HMR via plain sync.
         - { action: sync+restart, path: ./apps/api/src, target: /app/apps/api/src }
+        - { action: sync, path: ./apps/api/scripts, target: /app/apps/api/scripts }
         - { action: rebuild, path: ./apps/api/package.json }
 
   postgres:

package/dist/templates/modules/admin-dashboard/files/apps/api/scripts/bootstrap-admin.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+
+import { pathToFileURL } from "node:url";
+
+const args = process.argv.slice(2);
+
+function has(flag) {
+  return args.includes(flag);
+}
+
+function required(name, value) {
+  if (!value?.trim()) throw new Error(`${name} is required.`);
+  return value.trim();
+}
+
+function usage() {
+  console.log(`Create or verify the initial PodoKit administrator.
+
+Usage:
+  npm run admin:bootstrap -w <app>-api
+  npm run admin:bootstrap -w <app>-api -- --dry-run
+  npm run admin:bootstrap -w <app>-api -- --check-only
+
+Required environment:
+  ADMIN_EMAILS               Allowed administrator emails (comma-separated)
+  ADMIN_BOOTSTRAP_EMAIL      Initial administrator email
+  ADMIN_BOOTSTRAP_PASSWORD   Initial administrator password
+
+Optional environment:
+  ADMIN_BOOTSTRAP_NAME       Display name (default: Administrator)
+
+AUTH_SETUP_ADMIN_EMAIL and AUTH_SETUP_ADMIN_PASSWORD work as fallbacks so the
+same ephemeral credentials can be reused by auth:configure.
+
+Options:
+  --dry-run                  Validate and print a redacted plan without writing
+  --check-only               Verify an existing administrator without creating
+`);
+}
+
+export function resolveBootstrapInput(env = process.env) {
+  const email = required(
+    "ADMIN_BOOTSTRAP_EMAIL",
+    env.ADMIN_BOOTSTRAP_EMAIL ?? env.AUTH_SETUP_ADMIN_EMAIL,
+  ).toLowerCase();
+  const password = required(
+    "ADMIN_BOOTSTRAP_PASSWORD",
+    env.ADMIN_BOOTSTRAP_PASSWORD ?? env.AUTH_SETUP_ADMIN_PASSWORD,
+  );
+  const name = required("ADMIN_BOOTSTRAP_NAME", env.ADMIN_BOOTSTRAP_NAME ?? "Administrator");
+  const adminEmails = new Set(
+    required("ADMIN_EMAILS", env.ADMIN_EMAILS)
+      .split(",")
+      .map((value) => value.trim().toLowerCase())
+      .filter(Boolean),
+  );
+
+  if (!adminEmails.has(email)) {
+    throw new Error("ADMIN_BOOTSTRAP_EMAIL must be listed in ADMIN_EMAILS.");
+  }
+  if (password.length < 8 || password.length > 128) {
+    throw new Error("ADMIN_BOOTSTRAP_PASSWORD must be between 8 and 128 characters.");
+  }
+
+  return { email, password, name };
+}
+
+function roles(value) {
+  return (value ?? "")
+    .split(",")
+    .map((role) => role.trim())
+    .filter(Boolean);
+}
+
+async function verifyExisting(dependencies, input, user) {
+  if (!roles(user.role).includes("admin")) {
+    throw new Error("The administrator email already exists without the admin role; no changes were made.");
+  }
+  if (user.signupApproved !== true) {
+    throw new Error("The administrator account is not approved; no changes were made.");
+  }
+  if (user.emailVerified !== true) {
+    throw new Error("The administrator email is not verified; no changes were made.");
+  }
+  if (!user.passwordHash || !(await dependencies.verifyPassword(user.passwordHash, input.password))) {
+    throw new Error("The administrator account already exists but the supplied password does not match; no changes were made.");
+  }
+}
+
+export async function bootstrapAdmin(dependencies, input, options = {}) {
+  const existing = await dependencies.findUser(input.email);
+
+  if (options.dryRun) {
+    return {
+      status: "planned",
+      action: existing ? "verify" : "create",
+      email: input.email,
+      name: input.name,
+      password: "<redacted>",
+    };
+  }
+
+  if (existing) {
+    await verifyExisting(dependencies, input, existing);
+    return { status: "existing", email: input.email };
+  }
+
+  if (options.checkOnly) {
+    throw new Error("The administrator account does not exist; no changes were made.");
+  }
+
+  await dependencies.createUser({
+    email: input.email,
+    password: input.password,
+    name: input.name,
+    role: "admin",
+    data: { emailVerified: true, signupApproved: true },
+  });
+
+  const created = await dependencies.findUser(input.email);
+  if (!created) throw new Error("The administrator account was not found after creation.");
+  await verifyExisting(dependencies, input, created);
+  return { status: "created", email: input.email };
+}
+
+async function main() {
+  if (has("--help") || has("-h")) {
+    usage();
+    return;
+  }
+
+  const input = resolveBootstrapInput();
+  // Load the auth graph before importing one of its dependencies directly.
+  // Concurrent ESM imports can ask Node to link the same Better Auth submodule
+  // through two graph roots and fail before the command reaches the database.
+  const { auth } = await import("../dist/auth/auth.js");
+  const { pool } = await import("../dist/auth/db.js");
+  const { verifyPassword } = await import("better-auth/crypto");
+
+  try {
+    const result = await bootstrapAdmin(
+      {
+        findUser: async (email) => {
+          const query = await pool.query(
+            `SELECT u.id,
+                    u.email,
+                    u.role,
+                    u."emailVerified" AS "emailVerified",
+                    u."signupApproved" AS "signupApproved",
+                    a.password AS "passwordHash"
+               FROM "user" AS u
+          LEFT JOIN "account" AS a
+                 ON a."userId" = u.id
+                AND a."providerId" = 'credential'
+              WHERE lower(u.email) = lower($1)
+              LIMIT 1`,
+            [email],
+          );
+          return query.rows[0] ?? null;
+        },
+        createUser: async (user) => auth.api.createUser({ body: user }),
+        verifyPassword: async (hash, password) => verifyPassword({ hash, password }),
+      },
+      input,
+      { dryRun: has("--dry-run"), checkOnly: has("--check-only") },
+    );
+
+    if (result.status === "planned") {
+      console.log("Validated administrator bootstrap plan.");
+      console.log(JSON.stringify(result, null, 2));
+    } else if (result.status === "created") {
+      console.log(`Created and verified administrator account ${result.email}.`);
+    } else {
+      console.log(`Verified existing administrator account ${result.email}.`);
+    }
+  } finally {
+    await pool.end();
+  }
+}
+
+const invokedPath = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
+if (invokedPath === import.meta.url) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}

package/dist/templates/modules/admin-dashboard/module.manifest.json

@@ -13,6 +13,13 @@
     "@types/qrcode": "^1.5.5",
     "@types/multer": "^1.4.12"
   },
+  "packageOverlays": {
+    "api": {
+      "scripts": {
+        "admin:bootstrap": "node scripts/bootstrap-admin.mjs"
+      }
+    }
+  },
   "env": [
     "# admin-dashboard: emails auto-promoted to the admin role on sign-up (comma-separated)",
     "ADMIN_EMAILS=admin@example.com"
@@ -42,7 +49,7 @@
       "file": "AGENTS.md",
       "marker": "<!-- podokit:end:agents-modules -->",
       "optional": true,
-      "text": "### admin-dashboard\n- Admin console lives at `/admin/*` (users, sessions, organizations, audit, settings, account). Emails in `ADMIN_EMAILS` become admins on sign-up. When sign-up approval is enabled, self-registered users stay pending until an administrator approves them on `/admin/users`; administrator-created users bypass the queue.\n- **Every list/table MUST use the shared `$lib/components/data-table.svelte` (`DataTable`)** \u2014 it gives sortable headers + a footer pagination. Add search/filters with `$lib/components/table-toolbar.svelte`. Never assemble `Table.Root`/`Table.Header`/`Table.Body` by hand.\n"
+      "text": "### admin-dashboard\n- Admin console lives at `/admin/*` (users, sessions, organizations, audit, settings, account). Set `ADMIN_EMAILS`, then create or verify the initial account with `npm run admin:bootstrap -w <app>-api`; never commit or persist `ADMIN_BOOTSTRAP_PASSWORD`. When sign-up approval is enabled, self-registered users stay pending until an administrator approves them on `/admin/users`; administrator-created users bypass the queue.\n- **Every list/table MUST use the shared `$lib/components/data-table.svelte` (`DataTable`)** \u2014 it gives sortable headers + a footer pagination. Add search/filters with `$lib/components/table-toolbar.svelte`. Never assemble `Table.Root`/`Table.Header`/`Table.Body` by hand.\n"
     },
     {
       "file": "apps/api/src/app.module.ts",
@@ -56,9 +63,9 @@
     }
   ],
   "instructions": [
-    "Set ADMIN_EMAILS in .env (comma-separated). Those emails become admins on sign-up.",
+    "Set ADMIN_EMAILS in .env (comma-separated). After building and migrating, inject ADMIN_BOOTSTRAP_EMAIL and ADMIN_BOOTSTRAP_PASSWORD for one command only, then run npm run admin:bootstrap -w <app>-api. The command creates a verified, approved admin or safely verifies an existing one.",
     "Re-run the auth migration to add the admin and sign-up approval columns:  npx @better-auth/cli migrate -y --config apps/api/src/auth/auth.ts",
-    "Start the app (npm run dev), open /signup, register an ADMIN_EMAILS address, then sign in.",
+    "Remove ADMIN_BOOTSTRAP_PASSWORD from the environment after bootstrap. Keep ADMIN_EMAILS so matching future sign-ups are promoted consistently.",
     "Admin pages: /admin/users (list, approve pending registrations, ban, set role, revoke sessions). Signed-in users manage their profile and security at /account; /admin/account remains available in the admin shell. Admin, account, authentication, maintenance, and API responses include X-Robots-Tag: noindex, nofollow by default.",
     "Password reset emails go through the mailer module (installed automatically with auth); in dev without SMTP they are logged to the API console. Configure SMTP in admin settings or via SMTP_* env for production."
   ]

package/dist/templates/modules/auth/files/dot-claude/skills/podokit-configure-auth/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: podokit-configure-auth
-description: Configure and verify PodoKit social OAuth providers, SMTP delivery, and the administrator sign-up approval policy. Use when enabling Google, Apple, or another Better Auth provider; calculating callback URLs; applying credentials through Admin Settings; configuring outbound mail; or diagnosing why a configured sign-in method is unavailable.
+description: Bootstrap and verify the initial PodoKit administrator, then configure social OAuth providers, SMTP delivery, and sign-up approval. Use when setting the first admin email/password; enabling Google, Apple, or another Better Auth provider; calculating callback URLs; applying credentials through Admin Settings; configuring outbound mail; or diagnosing unavailable sign-in methods.
 ---
 
 # Configure PodoKit authentication
@@ -12,6 +12,7 @@ Use the generated `auth:configure` command so credentials enter the encrypted `a
 - Read [references/google.md](references/google.md) for Google sign-in, including External audience requirements.
 - Read [references/apple.md](references/apple.md) for Apple sign-in and client-secret rotation.
 - Read [references/smtp.md](references/smtp.md) for Google Workspace SMTP relay and DNS authentication.
+- Read [references/bootstrap-admin.md](references/bootstrap-admin.md) before creating or repairing access to the first administrator.
 - Run the same generated command for other provider IDs. Confirm the provider appears in Admin Settings before applying it.
 
 ## Prepare the app
@@ -24,7 +25,8 @@ Use the generated `auth:configure` command so credentials enter the encrypted `a
    npm run migrate:all -w <app>-api
    ```
 
-4. Derive the default callback as `<BETTER_AUTH_URL>/api/auth/callback/<provider>`. Only set `OAUTH_REDIRECT_URI` when the provider requires an explicit override.
+4. Create or verify the initial administrator with `admin:bootstrap` before enabling mandatory email verification or other runtime authentication settings.
+5. Derive the default callback as `<BETTER_AUTH_URL>/api/auth/callback/<provider>`. Only set `OAUTH_REDIRECT_URI` when the provider requires an explicit override.
 
 ## Handle secrets safely
 
@@ -44,6 +46,17 @@ export OAUTH_CLIENT_SECRET
 export OAUTH_CLIENT_ID="provider-client-id"
 ```
 
+The bootstrap command accepts the same `AUTH_SETUP_ADMIN_EMAIL` and
+`AUTH_SETUP_ADMIN_PASSWORD` variables as fallbacks. Keep `ADMIN_EMAILS` in the
+deployment environment, run the bootstrap once, and reuse the ephemeral
+credentials for `auth:configure`:
+
+```bash
+export ADMIN_EMAILS="admin@example.com"
+npm run admin:bootstrap -w <app>-api -- --dry-run
+npm run admin:bootstrap -w <app>-api
+```
+
 Unset sensitive variables when finished:
 
 ```bash

package/dist/templates/modules/auth/files/dot-claude/skills/podokit-configure-auth/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "PodoKit Auth Setup"
-  short_description: "Configure social login, SMTP, and signup approval"
-  default_prompt: "Use $podokit-configure-auth to configure Google login, SMTP, and sign-up approval safely."
+  short_description: "Bootstrap admin and configure authentication safely"
+  default_prompt: "Use $podokit-configure-auth to bootstrap the first administrator, then configure Google login, SMTP, and sign-up approval safely."

package/dist/templates/modules/auth/files/dot-claude/skills/podokit-configure-auth/references/bootstrap-admin.md

@@ -0,0 +1,51 @@
+# Bootstrap the initial administrator
+
+Use the generated database-backed command after the API build and migrations.
+Do not create the first administrator through the public sign-up page.
+
+## Set the persistent allowlist
+
+Set `ADMIN_EMAILS` in the same deployment environment used by the API. Include
+the exact lowercase-normalized address selected for the initial administrator.
+Keep this value after bootstrap so future matching sign-ups retain the same role
+policy.
+
+## Inject credentials for one command
+
+Prefer the deployment secret manager or a hidden shell prompt. Do not put the
+password in a command argument, repository file, image layer, CI log, or
+long-lived Kubernetes Secret.
+
+```bash
+export ADMIN_BOOTSTRAP_EMAIL="admin@example.com"
+printf "Initial admin password: " >&2
+IFS= read -r -s ADMIN_BOOTSTRAP_PASSWORD
+printf "\n" >&2
+export ADMIN_BOOTSTRAP_PASSWORD
+```
+
+`AUTH_SETUP_ADMIN_EMAIL` and `AUTH_SETUP_ADMIN_PASSWORD` are accepted as
+fallbacks so the same ephemeral values can immediately configure OAuth and SMTP.
+
+## Preview, create, and verify
+
+```bash
+npm run admin:bootstrap -w <app>-api -- --dry-run
+npm run admin:bootstrap -w <app>-api
+npm run admin:bootstrap -w <app>-api -- --check-only
+```
+
+The create path writes `role=admin`, `emailVerified=true`, and
+`signupApproved=true`. A rerun never updates an existing row or resets a
+password. It succeeds only when the account still has the admin role, verified
+and approved flags, and the supplied password matches.
+
+Unset the password immediately after `auth:configure` or the verification step:
+
+```bash
+unset ADMIN_BOOTSTRAP_PASSWORD AUTH_SETUP_ADMIN_PASSWORD
+```
+
+If the command reports an existing mismatched account, stop. Recover it through
+an authenticated administrator or an audited operator procedure; do not delete,
+promote, verify, or reset the row automatically.

package/dist/templates/modules/auth/module.manifest.json

@@ -3,6 +3,9 @@
   "description": "Full authentication (better-auth): email/password, sessions, and \u2014 via config \u2014 OAuth and 2FA. Installs a global guard so the API is secure by default; health and /api/auth stay public.",
   "requires": ["mailer"],
   "targetApp": "api",
+  "managedOverrides": [
+    ".claude/skills/podokit-configure-auth/**"
+  ],
   "dependencies": {
     "@podosoft/podokit-auth": "^0.2.0",
     "@podosoft/podokit-contracts": "^0.2.0",

package/dist/templates/todo/apps/api/Dockerfile

@@ -20,6 +20,7 @@ RUN addgroup -S app && adduser -S app -G app
 COPY --from=build /app/node_modules ./node_modules
 COPY --from=deps /app/apps/api ./apps/api
 COPY --from=build /app/apps/api/dist ./apps/api/dist
+COPY --from=build /app/apps/api/scripts ./apps/api/scripts
 WORKDIR /app/apps/api
 USER app
 EXPOSE 3000

package/dist/templates/todo/apps/api/scripts/.keep

@@ -0,0 +1 @@
+

package/dist/templates/todo/compose.dev.yaml

@@ -83,6 +83,7 @@ services:
         # sync+restart is the stable, recommended approach; the web keeps instant
         # HMR via plain sync.
         - { action: sync+restart, path: ./apps/api/src, target: /app/apps/api/src }
+        - { action: sync, path: ./apps/api/scripts, target: /app/apps/api/scripts }
         - { action: rebuild, path: ./apps/api/package.json }
 
   worker:
@@ -105,6 +106,7 @@ services:
         # sync+restart is the stable, recommended approach; the web keeps instant
         # HMR via plain sync.
         - { action: sync+restart, path: ./apps/api/src, target: /app/apps/api/src }
+        - { action: sync, path: ./apps/api/scripts, target: /app/apps/api/scripts }
         - { action: rebuild, path: ./apps/api/package.json }
 
   postgres:

package/dist/update.js

@@ -20,6 +20,18 @@ function diskContent(projectRoot, path) {
     const abs = (0, node_path_1.join)(projectRoot, path);
     return (0, node_fs_1.existsSync)(abs) ? (0, node_fs_1.readFileSync)(abs) : null;
 }
+function targetManagedOverrides(projectRoot, templatesDir, modules, current = []) {
+    const overrides = new Set(current);
+    const modulesDir = (0, node_path_1.join)(templatesDir, "modules");
+    for (const module of modules) {
+        const resolved = (0, add_1.resolveModule)(module.packageName ?? module.name, modulesDir, projectRoot);
+        if (!resolved)
+            continue;
+        for (const glob of (0, add_1.readModuleManifest)(resolved.dir).managedOverrides ?? [])
+            overrides.add(glob);
+    }
+    return [...overrides];
+}
 /**
  * Build the update plan. `templatesDir` is the installed CLI's template set (the
  * new version); the lock records what PodoKit last wrote (to detect user edits).
@@ -36,15 +48,22 @@ function planUpdate(projectRoot, templatesDir) {
         modules: manifest.modules,
         projectRoot,
     });
+    const managedOverrides = targetManagedOverrides(projectRoot, templatesDir, manifest.modules, manifest.managedOverrides);
     const changes = [];
     const paths = new Set([...newTree.keys(), ...Object.keys(lock.files)]);
     for (const path of [...paths].sort()) {
         const locked = lock.files[path];
         const newText = treeText(newTree, path);
         const disk = diskContent(projectRoot, path);
-        // tier: prefer the lock; else classify the new file.
-        const tier = locked?.tier ??
-            (newText !== null ? (0, lockfile_1.classifyTier)(path, newText, manifest.ownedGlobs) : "managed");
+        // A newer module can explicitly take responsibility for a path that older
+        // projects classified under a broad owned glob (notably generated skills).
+        const managedByTarget = managedOverrides.some((glob) => (0, lockfile_1.matchGlob)(path, glob));
+        const tier = managedByTarget
+            ? "managed"
+            : locked?.tier ??
+                (newText !== null
+                    ? (0, lockfile_1.classifyTier)(path, newText, manifest.ownedGlobs, managedOverrides)
+                    : "managed");
         if (tier === "owned") {
             changes.push({ path, tier, action: "skip", note: "owned — never modified" });
             continue;
@@ -101,13 +120,15 @@ function writeFile(projectRoot, path, content) {
  * Files that are neither in the assembled tree nor explicitly owned stay out of
  * the lock instead of being accidentally adopted as managed files.
  */
-function updatedFilesLock(projectRoot, newTree, previous, ownedGlobs) {
-    const next = (0, lockfile_1.computeFilesLock)(projectRoot, ownedGlobs);
+function updatedFilesLock(projectRoot, newTree, previous, ownedGlobs, managedOverrides) {
+    const next = (0, lockfile_1.computeFilesLock)(projectRoot, ownedGlobs, managedOverrides);
     for (const [path, entry] of Object.entries(next.files)) {
         const newText = treeText(newTree, path);
         if (newText !== null) {
             if (entry.tier !== "owned") {
-                entry.tier = previous.files[path]?.tier ?? entry.tier;
+                if (!managedOverrides.some((glob) => (0, lockfile_1.matchGlob)(path, glob))) {
+                    entry.tier = previous.files[path]?.tier ?? entry.tier;
+                }
                 entry.outHash = (0, podokit_template_engine_1.hashContent)(newText);
             }
             continue;
@@ -149,6 +170,7 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
         modules,
         projectRoot,
     });
+    const managedOverrides = targetManagedOverrides(projectRoot, templatesDir, modules, manifest.managedOverrides);
     const oldTree = options.oldTemplatesDir
         ? (0, assemble_1.assembleProject)({
             templatesDir: options.oldTemplatesDir,
@@ -188,7 +210,7 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
     // Keep the assembled target as the managed baseline. A merged working file
     // intentionally remains drifted so a future update performs another 3-way
     // merge instead of treating the user's lines as clean generated output.
-    (0, lockfile_1.writeFilesLock)(projectRoot, updatedFilesLock(projectRoot, newTree, previousLock, manifest.ownedGlobs));
+    (0, lockfile_1.writeFilesLock)(projectRoot, updatedFilesLock(projectRoot, newTree, previousLock, manifest.ownedGlobs, managedOverrides));
     const modulesDir = (0, node_path_1.join)(templatesDir, "modules");
     const refreshedModules = manifest.modules.map((module) => {
         const resolved = (0, add_1.resolveModule)(module.packageName ?? module.name, modulesDir, projectRoot);
@@ -202,6 +224,7 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
     });
     (0, lockfile_1.writeManifest)(projectRoot, {
         ...manifest,
+        managedOverrides,
         modules: refreshedModules,
         podokitVersion: (0, lockfile_1.podokitVersion)(),
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "description": "An opinionated but extensible starter toolkit and CLI for full-stack TypeScript apps with NestJS, SvelteKit, TailwindCSS, shadcn-svelte, Docker, and k3s.",
   "license": "Apache-2.0",
   "repository": {