@podosoft/podokit 0.5.1 → 0.7.0

package/README.md

@@ -47,10 +47,16 @@ Options:
                      - base                  : minimal npm workspace
   --dir <path>     Target directory (default: ./<name>)
   --pm <name>      Package manager: npm | pnpm | yarn (default: npm)
+  --no-ai          Skip AI agent guidance (AGENTS.md, CLAUDE.md, editor rules)
   -y, --yes        Skip prompts and accept defaults
   -h, --help       Show help
 ```
 
+Generated projects include agent guidance for AI coding tools — an
+[`AGENTS.md`](https://agents.md) (the open standard), a `CLAUDE.md` that imports
+it, `.cursor`/`.github` pointers, and Claude Code skills under `.claude/skills/`.
+Modules extend `AGENTS.md` as you add them. Use `--no-ai` to skip.
+
 Examples:
 
 ```bash

package/dist/add.d.ts

@@ -2,8 +2,15 @@ interface Injection {
     file: string;
     marker: string;
     text: string;
+    /** Skip (instead of failing) if the target file or marker is absent. */
+    optional?: boolean;
 }
+/** Highest `module.manifest.json` schema version this CLI understands. A package
+ *  module declaring a higher version is rejected rather than mis-applied. */
+export declare const SUPPORTED_MANIFEST_VERSION = 1;
 export interface ModuleManifest {
+    /** Manifest schema version. Absent (bundled modules) means "same as the CLI". */
+    manifestVersion?: number;
     name: string;
     description: string;
     requires?: string[];
@@ -14,6 +21,11 @@ export interface ModuleManifest {
     env?: string[];
     inject?: Injection[];
     instructions?: string[];
+    /** App-relative globs this module's files should own (durably user-editable,
+     *  never touched by `podo update`). Merged into the project's ownedGlobs so
+     *  they survive lock recompute. Use for public presentation pages a consumer
+     *  restyles, while keeping the module's `$lib` logic managed. */
+    ownedGlobs?: string[];
 }
 export interface AddOptions {
     projectRoot: string;
@@ -27,9 +39,19 @@ export interface AddResult {
     instructions: string[];
     /** Required modules that were auto-added because they were missing. */
     added: string[];
+    /** ownedGlobs declared by this module and every module it pulled in. */
+    ownedGlobs: string[];
 }
-/** List modules available under `modulesDir` (each has a module.manifest.json). */
-export declare function listModules(modulesDir: string): {
+/**
+ * Resolve a module's directory by name: first the bundled `modulesDir`, then a
+ * node-resolvable npm package `@podosoft/podokit-module-<name>` installed in the
+ * project (or a fully-qualified `@scope/pkg` name). Returns null if not found.
+ */
+export declare function resolveModuleDir(name: string, modulesDir: string, projectRoot: string): string | null;
+/** List modules available to a project: the bundled ones under `modulesDir` plus,
+ *  when `projectRoot` is given, any `@podosoft/podokit-module-*` packages installed
+ *  in it. Bundled names take precedence on a clash. */
+export declare function listModules(modulesDir: string, projectRoot?: string): {
     name: string;
     description: string;
 }[];

package/dist/add.js

@@ -1,21 +1,69 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_MANIFEST_VERSION = void 0;
+exports.resolveModuleDir = resolveModuleDir;
 exports.listModules = listModules;
 exports.addModule = addModule;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const node_module_1 = require("node:module");
 const podokit_template_engine_1 = require("@podosoft/podokit-template-engine");
 const lockfile_1 = require("./lockfile");
-/** List modules available under `modulesDir` (each has a module.manifest.json). */
-function listModules(modulesDir) {
-    if (!(0, node_fs_1.existsSync)(modulesDir))
-        return [];
-    return (0, node_fs_1.readdirSync)(modulesDir)
-        .filter((name) => (0, node_fs_1.existsSync)((0, node_path_1.join)(modulesDir, name, "module.manifest.json")))
-        .map((name) => {
-        const manifest = readManifest((0, node_path_1.join)(modulesDir, name));
-        return { name, description: manifest.description };
-    });
+/** 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;
+const PACKAGE_PREFIX = "@podosoft/podokit-module-";
+/**
+ * Resolve a module's directory by name: first the bundled `modulesDir`, then a
+ * node-resolvable npm package `@podosoft/podokit-module-<name>` installed in the
+ * project (or a fully-qualified `@scope/pkg` name). Returns null if not found.
+ */
+function resolveModuleDir(name, modulesDir, projectRoot) {
+    const bundled = (0, node_path_1.join)(modulesDir, name);
+    if ((0, node_fs_1.existsSync)((0, node_path_1.join)(bundled, "module.manifest.json")))
+        return bundled;
+    const pkg = name.includes("/") ? name : `${PACKAGE_PREFIX}${name}`;
+    try {
+        const req = (0, node_module_1.createRequire)((0, node_path_1.join)(projectRoot, "package.json"));
+        return (0, node_path_1.dirname)(req.resolve(`${pkg}/module.manifest.json`));
+    }
+    catch {
+        return null;
+    }
+}
+function assertManifestVersion(name, manifest) {
+    if ((manifest.manifestVersion ?? exports.SUPPORTED_MANIFEST_VERSION) > exports.SUPPORTED_MANIFEST_VERSION) {
+        throw new Error(`Module "${name}" needs a newer PodoKit (manifest v${manifest.manifestVersion}, this CLI supports v${exports.SUPPORTED_MANIFEST_VERSION}). Update @podosoft/podokit.`);
+    }
+}
+/** List modules available to a project: the bundled ones under `modulesDir` plus,
+ *  when `projectRoot` is given, any `@podosoft/podokit-module-*` packages installed
+ *  in it. Bundled names take precedence on a clash. */
+function listModules(modulesDir, projectRoot) {
+    const out = new Map();
+    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);
+            }
+        }
+    }
+    if (projectRoot) {
+        const scope = (0, node_path_1.join)(projectRoot, "node_modules", "@podosoft");
+        if ((0, node_fs_1.existsSync)(scope)) {
+            for (const dir of (0, node_fs_1.readdirSync)(scope)) {
+                if (!dir.startsWith("podokit-module-"))
+                    continue;
+                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));
+                if (!out.has(manifest.name))
+                    out.set(manifest.name, manifest.description);
+            }
+        }
+    }
+    return [...out].map(([name, description]) => ({ name, description }));
 }
 function readManifest(moduleDir) {
     return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(moduleDir, "module.manifest.json"), "utf8"));
@@ -40,10 +88,10 @@ function appendEnv(projectRoot, lines) {
 }
 /** Heuristic: is `module` already applied to the project? */
 function isApplied(projectRoot, modulesDir, module) {
-    const manifestPath = (0, node_path_1.join)(modulesDir, module, "module.manifest.json");
-    if (!(0, node_fs_1.existsSync)(manifestPath))
+    const moduleDir = resolveModuleDir(module, modulesDir, projectRoot);
+    if (!moduleDir)
         return false;
-    const manifest = JSON.parse((0, node_fs_1.readFileSync)(manifestPath, "utf8"));
+    const manifest = readManifest(moduleDir);
     const firstInject = manifest.inject?.[0];
     if (firstInject) {
         const target = (0, node_path_1.join)(projectRoot, firstInject.file);
@@ -58,17 +106,19 @@ function isApplied(projectRoot, modulesDir, module) {
  */
 function addModule(options) {
     const result = applyModule(options.projectRoot, options.module, options.modulesDir, new Set());
-    // Record the module (and any auto-added requirements) and refresh the lock.
-    (0, lockfile_1.recordModules)(options.projectRoot, [...result.added, result.module], options.podokitVersion);
+    // Record the module (and any auto-added requirements), fold in the modules'
+    // declared ownedGlobs, and refresh the lock.
+    (0, lockfile_1.recordModules)(options.projectRoot, [...result.added, result.module], options.podokitVersion, result.ownedGlobs);
     return result;
 }
 function applyModule(projectRoot, module, modulesDir, applied) {
-    const moduleDir = (0, node_path_1.join)(modulesDir, module);
-    if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(moduleDir, "module.manifest.json"))) {
-        const available = listModules(modulesDir).map((m) => m.name);
+    const moduleDir = resolveModuleDir(module, modulesDir, projectRoot);
+    if (!moduleDir) {
+        const available = listModules(modulesDir, projectRoot).map((m) => m.name);
         throw new Error(`Unknown module "${module}".${available.length ? ` Available: ${available.join(", ")}.` : ""}`);
     }
     const manifest = readManifest(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.`);
@@ -76,11 +126,13 @@ function applyModule(projectRoot, module, modulesDir, applied) {
     applied.add(module);
     // 0) apply required modules first (auto-add if missing)
     const added = [];
+    const ownedGlobs = [...(manifest.ownedGlobs ?? [])];
     for (const required of manifest.requires ?? []) {
         if (applied.has(required) || isApplied(projectRoot, modulesDir, required))
             continue;
         const result = applyModule(projectRoot, required, modulesDir, applied);
         added.push(required, ...result.added);
+        ownedGlobs.push(...result.ownedGlobs);
     }
     const appName = projectName(projectRoot);
     const vars = { projectName: appName };
@@ -109,10 +161,15 @@ function applyModule(projectRoot, module, modulesDir, applied) {
     for (const injection of manifest.inject ?? []) {
         const target = (0, node_path_1.join)(projectRoot, injection.file);
         if (!(0, node_fs_1.existsSync)(target)) {
+            if (injection.optional)
+                continue;
             throw new Error(`Cannot wire module: ${injection.file} not found.`);
         }
-        (0, node_fs_1.writeFileSync)(target, (0, podokit_template_engine_1.insertAtMarker)((0, node_fs_1.readFileSync)(target, "utf8"), injection.marker, injection.text));
+        const content = (0, node_fs_1.readFileSync)(target, "utf8");
+        if (injection.optional && !content.includes(injection.marker))
+            continue;
+        (0, node_fs_1.writeFileSync)(target, (0, podokit_template_engine_1.insertAtMarker)(content, injection.marker, injection.text));
     }
     const instructions = (manifest.instructions ?? []).map((line) => line.replace(/<app>/g, appName));
-    return { module, instructions, added };
+    return { module, instructions, added, ownedGlobs };
 }

package/dist/assemble.js

@@ -47,7 +47,10 @@ function applyModuleToTree(tree, moduleDir, vars) {
     // 4) inject wiring at markers
     for (const injection of manifest.inject ?? []) {
         const target = injection.file;
-        setText(tree, target, (0, podokit_template_engine_1.insertAtMarker)(textOf(tree, target), injection.marker, injection.text));
+        const content = textOf(tree, target);
+        if (injection.optional && !content.includes(injection.marker))
+            continue;
+        setText(tree, target, (0, podokit_template_engine_1.insertAtMarker)(content, injection.marker, injection.text));
     }
 }
 /** Assemble the project tree for a template + ordered modules, in memory. */

package/dist/create.d.ts

@@ -14,6 +14,8 @@ export interface CreateOptions {
     packageManager?: PackageManager;
     /** PodoKit version stamped into the lockfile. Defaults to the CLI version. */
     podokitVersion?: string;
+    /** Include AI agent guidance (AGENTS.md, CLAUDE.md, editor rules). Defaults to true. */
+    ai?: boolean;
 }
 export interface CreateResult {
     projectDir: string;

package/dist/create.js

@@ -9,6 +9,8 @@ const podokit_template_engine_1 = require("@podosoft/podokit-template-engine");
 const templates_1 = require("./templates");
 Object.defineProperty(exports, "DEFAULT_TEMPLATE", { enumerable: true, get: function () { return templates_1.DEFAULT_TEMPLATE; } });
 const lockfile_1 = require("./lockfile");
+/** AI agent guidance files, removed when scaffolding with `--no-ai`. */
+const AI_ARTIFACTS = ["AGENTS.md", "CLAUDE.md", ".claude", ".cursor", ".github/copilot-instructions.md"];
 const NAME_PATTERN = /^[a-z0-9](?:[a-z0-9-._]*[a-z0-9])?$/i;
 /** Validate a project name: no path separators, npm-friendly characters. */
 function assertValidName(name) {
@@ -42,6 +44,10 @@ function create(options) {
     }
     const vars = { projectName: name, packageManager };
     (0, podokit_template_engine_1.copyTemplate)(templateDir, projectDir, vars);
+    if (options.ai === false) {
+        for (const artifact of AI_ARTIFACTS)
+            (0, node_fs_1.rmSync)((0, node_path_1.join)(projectDir, artifact), { recursive: true, force: true });
+    }
     (0, lockfile_1.initLockfile)(projectDir, {
         template,
         packageManager,

package/dist/eject.js

@@ -21,7 +21,15 @@ function eject(projectRoot, paths) {
             result.ejected.push(path);
         }
     }
-    if (result.ejected.length)
+    if (result.ejected.length) {
         (0, lockfile_1.writeFilesLock)(projectRoot, lock);
+        // Persist ejected paths into the manifest's ownedGlobs so they stay owned
+        // across the next add/update, which rebuilds every tier from ownedGlobs.
+        const manifest = (0, lockfile_1.readManifest)(projectRoot);
+        if (manifest) {
+            manifest.ownedGlobs = (0, lockfile_1.mergeOwnedGlobs)(manifest.ownedGlobs, result.ejected);
+            (0, lockfile_1.writeManifest)(projectRoot, manifest);
+        }
+    }
     return result;
 }

package/dist/index.d.ts

@@ -10,6 +10,7 @@ interface ParsedArgs {
     apply: boolean;
     yes: boolean;
     help: boolean;
+    ai: boolean;
 }
 export declare function parseArgs(argv: string[]): ParsedArgs;
 export {};

package/dist/index.js

@@ -26,6 +26,7 @@ Options:
   --template <t> Template to scaffold (see below)
   --dir <path>   Target directory (default: ./<name>)
   --pm <name>    Package manager: npm | pnpm | yarn (default: npm)
+  --no-ai        Skip AI agent guidance (AGENTS.md, CLAUDE.md, editor rules)
   -y, --yes      Skip prompts and accept defaults
   -h, --help     Show this help
 
@@ -38,7 +39,7 @@ Example:
   cd my-app && npx @podosoft/podokit add auth
 `;
 function parseArgs(argv) {
-    const parsed = { help: false, yes: false, apply: false };
+    const parsed = { help: false, yes: false, apply: false, ai: true };
     const positionals = [];
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
@@ -48,6 +49,9 @@ function parseArgs(argv) {
         else if (arg === "-y" || arg === "--yes") {
             parsed.yes = true;
         }
+        else if (arg === "--no-ai") {
+            parsed.ai = false;
+        }
         else if (arg === "--apply") {
             parsed.apply = true;
         }
@@ -85,7 +89,7 @@ async function main(argv) {
     if (args.command === "add") {
         const moduleName = args.name;
         if (!moduleName) {
-            const available = (0, add_1.listModules)(modulesDir);
+            const available = (0, add_1.listModules)(modulesDir, process.cwd());
             const list = available.length
                 ? available.map((m) => `  ${m.name}  ${m.description}`).join("\n")
                 : "  (none available)";
@@ -242,6 +246,7 @@ async function main(argv) {
             template: resolved.template,
             targetDir: args.dir,
             packageManager: resolved.packageManager,
+            ai: args.ai,
         });
         const relPath = (0, node_path_1.relative)(process.cwd(), result.projectDir) || ".";
         const rel = relPath.startsWith("..") ? result.projectDir : relPath;

package/dist/lib.d.ts

@@ -0,0 +1,14 @@
+export { create } from "./create";
+export type { CreateOptions, CreateResult } from "./create";
+export { TEMPLATES, DEFAULT_TEMPLATE, TEMPLATE_NAMES, isKnownTemplate } from "./templates";
+export type { TemplateInfo } from "./templates";
+export { listModules, addModule } from "./add";
+export type { ModuleManifest, AddOptions, AddResult } from "./add";
+export { status, diff, doctor, SUPPORTED_FRAMEWORKS } from "./inspect";
+export type { StatusReport, DoctorFinding } from "./inspect";
+export { planUpdate, summarize } from "./update";
+export type { UpdatePlan, FileChange } from "./update";
+/** Absolute path to the templates bundled in this installed package. */
+export declare function builtinTemplatesDir(): string;
+/** Absolute path to the modules bundled in this installed package. */
+export declare function builtinModulesDir(): string;

package/dist/lib.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.summarize = exports.planUpdate = exports.SUPPORTED_FRAMEWORKS = exports.doctor = exports.diff = exports.status = exports.addModule = exports.listModules = exports.isKnownTemplate = exports.TEMPLATE_NAMES = exports.DEFAULT_TEMPLATE = exports.TEMPLATES = exports.create = void 0;
+exports.builtinTemplatesDir = builtinTemplatesDir;
+exports.builtinModulesDir = builtinModulesDir;
+// Library entry point: the reusable functions behind the `podo` CLI, for other
+// packages (e.g. @podosoft/podokit-mcp) to call without spawning the binary.
+const node_path_1 = require("node:path");
+var create_1 = require("./create");
+Object.defineProperty(exports, "create", { enumerable: true, get: function () { return create_1.create; } });
+var templates_1 = require("./templates");
+Object.defineProperty(exports, "TEMPLATES", { enumerable: true, get: function () { return templates_1.TEMPLATES; } });
+Object.defineProperty(exports, "DEFAULT_TEMPLATE", { enumerable: true, get: function () { return templates_1.DEFAULT_TEMPLATE; } });
+Object.defineProperty(exports, "TEMPLATE_NAMES", { enumerable: true, get: function () { return templates_1.TEMPLATE_NAMES; } });
+Object.defineProperty(exports, "isKnownTemplate", { enumerable: true, get: function () { return templates_1.isKnownTemplate; } });
+var add_1 = require("./add");
+Object.defineProperty(exports, "listModules", { enumerable: true, get: function () { return add_1.listModules; } });
+Object.defineProperty(exports, "addModule", { enumerable: true, get: function () { return add_1.addModule; } });
+var inspect_1 = require("./inspect");
+Object.defineProperty(exports, "status", { enumerable: true, get: function () { return inspect_1.status; } });
+Object.defineProperty(exports, "diff", { enumerable: true, get: function () { return inspect_1.diff; } });
+Object.defineProperty(exports, "doctor", { enumerable: true, get: function () { return inspect_1.doctor; } });
+Object.defineProperty(exports, "SUPPORTED_FRAMEWORKS", { enumerable: true, get: function () { return inspect_1.SUPPORTED_FRAMEWORKS; } });
+var update_1 = require("./update");
+Object.defineProperty(exports, "planUpdate", { enumerable: true, get: function () { return update_1.planUpdate; } });
+Object.defineProperty(exports, "summarize", { enumerable: true, get: function () { return update_1.summarize; } });
+/** Absolute path to the templates bundled in this installed package. */
+function builtinTemplatesDir() {
+    return (0, node_path_1.join)(__dirname, "templates");
+}
+/** Absolute path to the modules bundled in this installed package. */
+function builtinModulesDir() {
+    return (0, node_path_1.join)(__dirname, "templates", "modules");
+}

package/dist/lockfile.d.ts

@@ -72,9 +72,14 @@ export interface InitLockOptions {
 }
 /** Write the initial `.podokit/` lockfile for a freshly created project. */
 export declare function initLockfile(projectRoot: string, options: InitLockOptions): void;
+/** Union two glob lists, preserving order and dropping duplicates. Used to fold
+ *  module-declared and ejected owned paths into the project's `ownedGlobs`, which
+ *  is the durable source of truth `computeFilesLock` re-reads on every recompute. */
+export declare function mergeOwnedGlobs(existing: string[], add: string[]): string[];
 /**
  * Record applied modules in the manifest and recompute the files.lock. Modules
  * already present are left in place (idempotent); the lock always reflects disk.
- * No-op on projects without a manifest (pre-lockfile projects; see `podo adopt`).
+ * `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, moduleNames: string[], version?: string): void;
+export declare function recordModules(projectRoot: string, moduleNames: string[], version?: string, ownedGlobs?: string[]): void;

package/dist/lockfile.js

@@ -14,6 +14,7 @@ exports.computeFilesLock = computeFilesLock;
 exports.readFilesLock = readFilesLock;
 exports.computeDrift = computeDrift;
 exports.initLockfile = initLockfile;
+exports.mergeOwnedGlobs = mergeOwnedGlobs;
 exports.recordModules = recordModules;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
@@ -44,6 +45,23 @@ const WALK_IGNORE = new Set([
 exports.DEFAULT_OWNED_GLOBS = [
     "apps/web/src/routes/**",
     "apps/web/src/lib/components/ui/**",
+    // Owned Nest DI extension slot — override providers here; update never touches it.
+    "apps/api/src/app.extensions.ts",
+    // AI agent guidance — yours to customize; update never touches it.
+    "AGENTS.md",
+    "CLAUDE.md",
+    ".claude/**",
+    ".cursor/**",
+    ".github/copilot-instructions.md",
+    ".mcp.json",
+    // Containerized dev-environment scaffolding: users tweak ports/services, so
+    // updates never overwrite these.
+    "compose.dev.yaml",
+    "Dockerfile.dev",
+    ".dockerignore",
+    ".devcontainer/**",
+    ".env.docker",
+    "infra/traefik/**",
 ];
 const TEXT_EXT = /\.(json|md|ts|tsx|js|mjs|cjs|css|html|yml|yaml|txt|env|svelte|gitignore|example)$/i;
 function podokitDir(projectRoot) {
@@ -171,12 +189,27 @@ function initLockfile(projectRoot, options) {
     writeManifest(projectRoot, manifest);
     writeFilesLock(projectRoot, computeFilesLock(projectRoot, ownedGlobs));
 }
+/** Union two glob lists, preserving order and dropping duplicates. Used to fold
+ *  module-declared and ejected owned paths into the project's `ownedGlobs`, which
+ *  is the durable source of truth `computeFilesLock` re-reads on every recompute. */
+function mergeOwnedGlobs(existing, add) {
+    const seen = new Set(existing);
+    const out = [...existing];
+    for (const glob of add) {
+        if (seen.has(glob))
+            continue;
+        seen.add(glob);
+        out.push(glob);
+    }
+    return out;
+}
 /**
  * Record applied modules in the manifest and recompute the files.lock. Modules
  * already present are left in place (idempotent); the lock always reflects disk.
- * No-op on projects without a manifest (pre-lockfile projects; see `podo adopt`).
+ * `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, moduleNames, version) {
+function recordModules(projectRoot, moduleNames, version, ownedGlobs) {
     const manifest = readManifest(projectRoot);
     if (!manifest)
         return;
@@ -188,6 +221,8 @@ function recordModules(projectRoot, moduleNames, version) {
         manifest.modules.push({ name, order: manifest.modules.length, addedWith: stampedWith });
         known.add(name);
     }
+    if (ownedGlobs?.length)
+        manifest.ownedGlobs = mergeOwnedGlobs(manifest.ownedGlobs, ownedGlobs);
     writeManifest(projectRoot, manifest);
     writeFilesLock(projectRoot, computeFilesLock(projectRoot, manifest.ownedGlobs));
 }

package/dist/templates/base/AGENTS.md

@@ -0,0 +1,30 @@
+# AGENTS.md — {{projectName}}
+
+Guidance for AI coding agents (Claude Code, Codex, Cursor, Copilot, …). Generated
+by [PodoKit](https://github.com/podosoft-dev/podokit).
+
+## Project overview
+
+A minimal npm-workspace starter. Build it up from here — add features with the
+`podo` CLI (`podo add <module>`; run `podo add` with no argument to list them).
+
+## Commands
+
+```bash
+npm install
+npm run dev      # runs workspace dev scripts
+npm run build
+npm run lint     # type-check
+npm test
+```
+
+## Code style
+
+- TypeScript `strict`. **No `any`** (use `unknown` + narrowing), no `@ts-ignore`.
+- Explicit function return types. Conventional Commits, imperative mood, no emojis.
+
+## PodoKit tooling
+
+This project is managed by the `podo` CLI; `.podokit/` records how it was
+assembled (do not edit by hand). Use `podo status`/`podo diff` to see your local
+edits and `podo update` to pull in improvements without losing your work.

package/dist/templates/base/CLAUDE.md

@@ -0,0 +1,6 @@
+# CLAUDE.md
+
+Agent guidance for this project lives in [AGENTS.md](./AGENTS.md). It is imported
+below so Claude Code loads the same rules the other AI tools read.
+
+@AGENTS.md

package/dist/templates/fullstack-nest-svelte/AGENTS.md

@@ -0,0 +1,79 @@
+# AGENTS.md — {{projectName}}
+
+Guidance for AI coding agents (Claude Code, Codex, Cursor, Copilot, …) working in
+this repository. It was generated by [PodoKit](https://github.com/podosoft-dev/podokit).
+Follow it so your changes match the project's conventions.
+
+## Project overview
+
+A full-stack TypeScript monorepo (npm workspaces):
+
+- `apps/api` — **NestJS** backend (`{{projectName}}-api`), TypeORM + PostgreSQL, Swagger at `/api-docs`.
+- `apps/web` — **SvelteKit** frontend (`{{projectName}}-web`), Tailwind v4 + shadcn-svelte + typesafe-i18n.
+- `infra/` — Docker Compose (PostgreSQL/Redis) and example k3s manifests.
+- `.podokit/` — PodoKit's generation lockfile (see "PodoKit tooling" below). Do not edit by hand.
+
+## Setup & commands
+
+```bash
+npm install
+cp .env.example .env
+docker compose -f infra/docker/docker-compose.yml up -d   # PostgreSQL (+ Redis)
+npm run dev        # api on http://localhost:5002, web on http://localhost:5001
+```
+
+- **Ports: web = 5001, api = 5002.** The web app reaches the API only through its
+  SvelteKit server proxy (`/api/*`), never with a direct browser `fetch`.
+- Build: `npm run build`  ·  Type-check/lint: `npm run lint`  ·  Unit tests: `npm test`
+- Per workspace: `npm run build -w {{projectName}}-api` / `-w {{projectName}}-web`.
+- DB migrations (TypeORM): `npm run migration:run -w {{projectName}}-api`.
+- e2e (Playwright, ships in `tests/`): `npm run test:e2e`.
+
+**Always** verify a change by building the affected workspace (and `svelte-check`
+for web) before considering it done. UI changes need a Playwright test; API
+changes need an e2e/unit test.
+
+## Code style
+
+### TypeScript (both apps)
+- `strict` mode. **No `any`** — use `unknown` + narrowing. **No `@ts-ignore`/`@ts-expect-error`** and no `eslint-disable`.
+- Explicit function return types. DTOs use `class-validator` decorators.
+- Keep `noUnusedLocals`, `noUnusedParameters`, `noImplicitReturns`, `noUncheckedIndexedAccess`.
+
+### Svelte 5 (web)
+- **Runes only**: `$state()`, `$derived()`, `$effect()`, `$props()`. **Never** use `$:` (deprecated).
+- Reactive stores go in `.svelte.ts` files; don't destructure a getter-exported rune (it loses reactivity) — wrap in `$derived`.
+
+### UI — Tailwind + shadcn-svelte (web)
+- Prefer **shadcn-svelte components** over raw HTML (`<button>`, `<input>`, `<select>`, …).
+- **Do not edit `src/lib/components/ui/**`** (the shadcn primitives). Customize in a separate wrapper.
+- Tailwind v4 (CSS-first, no `tailwind.config`). Use semantic classes: `bg-background`, `text-foreground`, `border-border`. Dark mode via `mode-watcher`. Responsive (`sm:`/`md:`/`lg:`).
+
+### i18n & errors
+- **Every user-facing string goes through i18n** (`src/lib/i18n/messages.ts`) — no hardcoded text. Add keys to **all** locales at once.
+- The backend returns a stable **error envelope**: `{ success: false, error: { code, message, statusCode, path, timestamp, details? } }`. Throw `AppException("SOME_CODE", ...)` on the backend; **branch on `error.code`, not the message,** on the frontend.
+- Logging is structured; no emojis/icons. Start messages with an action verb.
+
+## PodoKit tooling & file ownership
+
+This project is managed by the `podo` CLI. Files have an ownership tier recorded
+in `.podokit/files.lock` — respect it:
+
+- **owned** (your code: `apps/web/src/routes/**`, your components/services, `apps/api/src/app.extensions.ts`, and this `AGENTS.md`) — edit freely. To add or override Nest providers/modules, use `app.extensions.ts` (spread into `AppModule` after the module-wired providers, so a same-token override wins) rather than editing `app.module.ts`.
+- **assembled** (e.g. `apps/api/src/app.module.ts`, `auth.ts`) — contain `// podokit:begin:… / …:end` fenced regions that the toolkit recomputes. Edit outside the fences only; **never hand-edit inside the fences**.
+- **managed** (bootstrap/config like `main.ts`) — the toolkit may update these; avoid gratuitous edits.
+
+Useful commands:
+
+- `podo add <module>` — add a feature (auth, admin-dashboard, redis, bullmq, …). It wires itself into the app; run `podo add` with no argument to list modules.
+- `podo status` / `podo diff` — see your local edits vs. what PodoKit generated.
+- `podo update` — pull in template/module improvements (3-way merges your edits; never touches owned files).
+
+## Commit conventions
+
+Conventional Commits (`feat|fix|docs|refactor|test|chore`), imperative mood,
+≤50-char subject, no trailing period, no emojis. One logical change per commit.
+
+<!-- podokit:begin:agents-modules -->
+<!-- Module-specific guidance is injected here by `podo add`. -->
+<!-- podokit:end:agents-modules -->

package/dist/templates/fullstack-nest-svelte/CLAUDE.md

@@ -0,0 +1,6 @@
+# CLAUDE.md
+
+Agent guidance for this project lives in [AGENTS.md](./AGENTS.md). It is imported
+below so Claude Code loads the same rules the other AI tools read.
+
+@AGENTS.md

package/dist/templates/fullstack-nest-svelte/Dockerfile.dev

@@ -0,0 +1,25 @@
+# Development image for the PodoKit monorepo (web + api).
+# Dependencies and source are baked in; `docker compose watch` syncs your
+# edits into the running container so the native file watchers fire.
+FROM node:22-bookworm-slim
+
+# git for the toolchain (editors, AI agents); build tools for native modules.
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends git python3 make g++ ca-certificates \
+  && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Install workspace dependencies (cached unless a package.json changes).
+# NB: the host package-lock.json is intentionally NOT copied — a lockfile
+# generated on macOS/Windows prunes platform-specific optional deps and can drop
+# packages (e.g. @swc/cli) on linux. Resolving fresh in-container avoids that.
+COPY package.json ./
+COPY apps/api/package.json ./apps/api/package.json
+COPY apps/web/package.json ./apps/web/package.json
+RUN npm install
+
+# Baked source (kept in sync during development by `docker compose watch`).
+COPY . .
+
+EXPOSE 5001 5002

package/dist/templates/fullstack-nest-svelte/apps/api/package.json

@@ -3,7 +3,7 @@
   "version": "0.0.0",
   "private": true,
   "scripts": {
-    "dev": "nest start --watch",
+    "dev": "nest start --watch --builder swc",
     "build": "nest build",
     "start": "node dist/main",
     "lint": "tsc -p tsconfig.json --noEmit",
@@ -40,7 +40,9 @@
     "supertest": "^7.0.0",
     "ts-jest": "^29.2.5",
     "ts-node": "^10.9.2",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "@swc/core": "^1.7.0",
+    "@swc/cli": "^0.4.0"
   },
   "jest": {
     "moduleFileExtensions": [