diff --git a/packages/create-gen-app-test/src/__tests__/__snapshots__/cached-template.test.ts.snap b/packages/create-gen-app-test/src/__tests__/__snapshots__/cached-template.test.ts.snap
index 668769c..bd4cf99 100644
--- a/packages/create-gen-app-test/src/__tests__/__snapshots__/cached-template.test.ts.snap
+++ b/packages/create-gen-app-test/src/__tests__/__snapshots__/cached-template.test.ts.snap
@@ -2,61 +2,42 @@
 
 exports[`cached template integration tests first clone with variable replacement should snapshot created directory structure 1`] = `
 [
-  "module/",
-  "module/README.md",
-  "module/__tests__/",
-  "module/__tests__/basic.test.ts",
-  "module/jest.config.js",
-  "module/package.json",
-  "workspace/",
-  "workspace/.eslintrc.json",
-  "workspace/.github/",
-  "workspace/.github/run-tests.yaml",
-  "workspace/.gitignore",
-  "workspace/.prettierrc.json",
-  "workspace/.vscode/",
-  "workspace/.vscode/settings.json",
-  "workspace/LICENSE",
-  "workspace/Makefile",
-  "workspace/README.md",
-  "workspace/bin/",
-  "workspace/bin/install.sh",
-  "workspace/docker-compose.yml",
-  "workspace/launchql.json",
-  "workspace/lerna.json",
-  "workspace/package.json",
-  "workspace/pnpm-workspace.yaml",
-  "workspace/tsconfig.json",
+  "LICENSE",
+  "README.md",
+  "__tests__/",
+  "__tests__/basic.test.ts",
+  "jest.config.js",
+  "package.json",
 ]
 `;
 
 exports[`cached template integration tests first clone with variable replacement should snapshot package.json files if they exist 1`] = `
 {
-  "module/package.json": {
-    "author": "____fullName____ <____email____>",
+  "package.json": {
+    "author": "Test User test <tester-test@example.com>",
     "bugs": {
-      "url": "https://github.com/____username____/____repoName____/issues",
+      "url": "https://github.com/Test User test/Test User test/issues",
     },
-    "description": "____moduleDesc____",
+    "description": "Test Module test",
     "devDependencies": {
       "pgsql-test": "^2.13.2",
     },
-    "homepage": "https://github.com/____username____/____repoName____",
+    "homepage": "https://github.com/Test User test/Test User test",
     "keywords": [],
-    "license": "____license____",
-    "name": "____packageIdentifier____",
+    "license": "MIT",
+    "name": "integration-test",
     "pnpm": {
       "overrides": {
         "graphql": "14.7.0",
       },
     },
     "publishConfig": {
-      "access": "____access____",
+      "access": "public",
       "directory": "dist",
     },
     "repository": {
       "type": "git",
-      "url": "https://github.com/____username____/____repoName____",
+      "url": "https://github.com/Test User test/Test User test",
     },
     "scripts": {
       "lint": "eslint . --fix",
@@ -65,108 +46,47 @@ exports[`cached template integration tests first clone with variable replacement
     },
     "version": "0.0.1",
   },
-  "workspace/package.json": {
-    "author": "____fullName____ <____email____>",
-    "devDependencies": {
-      "@types/jest": "^29.5.14",
-      "@types/node": "^22.10.2",
-      "@typescript-eslint/eslint-plugin": "^8.15.0",
-      "@typescript-eslint/parser": "^8.15.0",
-      "eslint": "^9.13.0",
-      "eslint-config-prettier": "^10.1.1",
-      "eslint-plugin-simple-import-sort": "^12.1.1",
-      "eslint-plugin-unused-imports": "^4.3.0",
-      "jest": "^29.7.0",
-      "lerna": "^8.2.4",
-      "pgsql-test": "^2.13.2",
-      "prettier": "^3.3.3",
-      "ts-jest": "^29.2.5",
-      "ts-node": "^10.9.2",
-      "typescript": "^5.6.3",
-    },
-    "license": "SEE LICENSE IN LICENSE",
-    "name": "____moduleName____",
-    "pnpm": {
-      "overrides": {
-        "graphql": "14.7.0",
-      },
-    },
-    "private": true,
-    "publishConfig": {
-      "access": "restricted",
-    },
-    "repository": {
-      "type": "git",
-      "url": "https://github.com/____username____/____moduleName____",
-    },
-    "scripts": {
-      "lint": "pnpm -r run lint",
-    },
-    "version": "0.0.1",
-    "workspaces": [
-      "packages/*",
-    ],
-  },
 }
 `;
 
 exports[`cached template integration tests second clone from cache should snapshot created directory structure from cache 1`] = `
 [
-  "module/",
-  "module/README.md",
-  "module/__tests__/",
-  "module/__tests__/basic.test.ts",
-  "module/jest.config.js",
-  "module/package.json",
-  "workspace/",
-  "workspace/.eslintrc.json",
-  "workspace/.github/",
-  "workspace/.github/run-tests.yaml",
-  "workspace/.gitignore",
-  "workspace/.prettierrc.json",
-  "workspace/.vscode/",
-  "workspace/.vscode/settings.json",
-  "workspace/LICENSE",
-  "workspace/Makefile",
-  "workspace/README.md",
-  "workspace/bin/",
-  "workspace/bin/install.sh",
-  "workspace/docker-compose.yml",
-  "workspace/launchql.json",
-  "workspace/lerna.json",
-  "workspace/package.json",
-  "workspace/pnpm-workspace.yaml",
-  "workspace/tsconfig.json",
+  "LICENSE",
+  "README.md",
+  "__tests__/",
+  "__tests__/basic.test.ts",
+  "jest.config.js",
+  "package.json",
 ]
 `;
 
 exports[`cached template integration tests second clone from cache should snapshot package.json files from cached template 1`] = `
 {
-  "module/package.json": {
-    "author": "____fullName____ <____email____>",
+  "package.json": {
+    "author": "Test User cached <tester-cached@example.com>",
     "bugs": {
-      "url": "https://github.com/____username____/____repoName____/issues",
+      "url": "https://github.com/Test User cached/Test User cached/issues",
     },
-    "description": "____moduleDesc____",
+    "description": "Test Module cached",
     "devDependencies": {
       "pgsql-test": "^2.13.2",
     },
-    "homepage": "https://github.com/____username____/____repoName____",
+    "homepage": "https://github.com/Test User cached/Test User cached",
     "keywords": [],
-    "license": "____license____",
-    "name": "____packageIdentifier____",
+    "license": "MIT",
+    "name": "integration-cached",
     "pnpm": {
       "overrides": {
         "graphql": "14.7.0",
       },
     },
     "publishConfig": {
-      "access": "____access____",
+      "access": "public",
       "directory": "dist",
     },
     "repository": {
       "type": "git",
-      "url": "https://github.com/____username____/____repoName____",
+      "url": "https://github.com/Test User cached/Test User cached",
     },
     "scripts": {
       "lint": "eslint . --fix",
@@ -175,47 +95,5 @@ exports[`cached template integration tests second clone from cache should snapsh
     },
     "version": "0.0.1",
   },
-  "workspace/package.json": {
-    "author": "____fullName____ <____email____>",
-    "devDependencies": {
-      "@types/jest": "^29.5.14",
-      "@types/node": "^22.10.2",
-      "@typescript-eslint/eslint-plugin": "^8.15.0",
-      "@typescript-eslint/parser": "^8.15.0",
-      "eslint": "^9.13.0",
-      "eslint-config-prettier": "^10.1.1",
-      "eslint-plugin-simple-import-sort": "^12.1.1",
-      "eslint-plugin-unused-imports": "^4.3.0",
-      "jest": "^29.7.0",
-      "lerna": "^8.2.4",
-      "pgsql-test": "^2.13.2",
-      "prettier": "^3.3.3",
-      "ts-jest": "^29.2.5",
-      "ts-node": "^10.9.2",
-      "typescript": "^5.6.3",
-    },
-    "license": "SEE LICENSE IN LICENSE",
-    "name": "____moduleName____",
-    "pnpm": {
-      "overrides": {
-        "graphql": "14.7.0",
-      },
-    },
-    "private": true,
-    "publishConfig": {
-      "access": "restricted",
-    },
-    "repository": {
-      "type": "git",
-      "url": "https://github.com/____username____/____moduleName____",
-    },
-    "scripts": {
-      "lint": "pnpm -r run lint",
-    },
-    "version": "0.0.1",
-    "workspaces": [
-      "packages/*",
-    ],
-  },
 }
 `;
diff --git a/packages/create-gen-app-test/src/__tests__/cached-template.test.ts b/packages/create-gen-app-test/src/__tests__/cached-template.test.ts
index 0eed514..709709c 100644
--- a/packages/create-gen-app-test/src/__tests__/cached-template.test.ts
+++ b/packages/create-gen-app-test/src/__tests__/cached-template.test.ts
@@ -4,9 +4,10 @@ import * as path from 'path';
 
 import { appstash, resolve } from 'appstash';
 
-import { createFromCachedTemplate, TemplateCache } from '../index';
+import { createFromTemplate, CacheManager, GitCloner } from '../index';
+import { buildAnswers, TEST_REPO, TEST_TEMPLATE } from '../test-utils/integration-helpers';
 
-const DEFAULT_TEMPLATE_URL = 'https://github.com/launchql/pgpm-boilerplates';
+const DEFAULT_TEMPLATE_URL = TEST_REPO;
 
 describe('cached template integration tests', () => {
   let testOutputDir: string;
@@ -35,25 +36,36 @@ describe('cached template integration tests', () => {
 
   describe('cache functionality', () => {
     let sharedCachePath: string;
-    let templateCache: TemplateCache;
+    let cacheManager: CacheManager;
 
     beforeAll(() => {
-      templateCache = new TemplateCache({
-        enabled: true,
+      cacheManager = new CacheManager({
         toolName: testCacheTool,
       });
     });
 
     it('should return null when cache does not exist for new URL', () => {
       const nonExistentUrl = 'https://github.com/nonexistent/repo-test-123456';
-      const cachedRepo = templateCache.get(nonExistentUrl);
+      const cacheKey = cacheManager.createKey(nonExistentUrl);
+      const cachedRepo = cacheManager.get(cacheKey);
       expect(cachedRepo).toBeNull();
     });
 
     it('should clone repository to cache', () => {
-      const cachePath = templateCache.set(DEFAULT_TEMPLATE_URL);
+      // Use GitCloner + CacheManager to clone and cache
+      const gitCloner = new GitCloner();
+      const normalizedUrl = gitCloner.normalizeUrl(DEFAULT_TEMPLATE_URL);
+      const cacheKey = cacheManager.createKey(normalizedUrl);
+
+      // Clone to cache directory
+      const cachePath = path.join(cacheManager.getReposDir(), cacheKey);
+      gitCloner.clone(normalizedUrl, cachePath, { depth: 1 });
+
+      // Register in cache manager
+      cacheManager.set(cacheKey, cachePath);
       sharedCachePath = cachePath;
 
+      // Verify cache was created correctly
       expect(fs.existsSync(cachePath)).toBe(true);
       expect(fs.existsSync(path.join(cachePath, '.git'))).toBe(false);
 
@@ -62,7 +74,11 @@ describe('cached template integration tests', () => {
     }, 60000);
 
     it('should retrieve cached repository', () => {
-      const cachedRepo = templateCache.get(DEFAULT_TEMPLATE_URL);
+      const gitCloner = new GitCloner();
+      const normalizedUrl = gitCloner.normalizeUrl(DEFAULT_TEMPLATE_URL);
+      const cacheKey = cacheManager.createKey(normalizedUrl);
+      const cachedRepo = cacheManager.get(cacheKey);
+
       expect(cachedRepo).not.toBeNull();
       expect(cachedRepo).toBe(sharedCachePath);
       expect(fs.existsSync(cachedRepo!)).toBe(true);
@@ -76,16 +92,13 @@ describe('cached template integration tests', () => {
     beforeAll(async () => {
       firstOutputDir = fs.mkdtempSync(path.join(os.tmpdir(), 'first-clone-'));
 
-      firstCloneResult = await createFromCachedTemplate({
+      firstCloneResult = await createFromTemplate({
         templateUrl: DEFAULT_TEMPLATE_URL,
         outputDir: firstOutputDir,
-        answers: {
-          PROJECT_NAME: 'test-project',
-          AUTHOR: 'Test Author',
-          DESCRIPTION: 'A test project',
-          MODULE_NAME: 'testmodule'
-        },
-        cacheTool: testCacheTool
+        answers: buildAnswers('test'),
+        toolName: testCacheTool,
+        noTty: true,
+        fromPath: TEST_TEMPLATE
       });
     }, 60000);
 
@@ -128,11 +141,15 @@ describe('cached template integration tests', () => {
     });
 
     it('should verify template cache was created', () => {
-      const templateCache = new TemplateCache({
-        enabled: true,
+      // Verify cache was created by createFromTemplate
+      const cacheManager = new CacheManager({
         toolName: testCacheTool,
       });
-      const cachedRepo = templateCache.get(DEFAULT_TEMPLATE_URL);
+      const gitCloner = new GitCloner();
+      const normalizedUrl = gitCloner.normalizeUrl(DEFAULT_TEMPLATE_URL);
+      const cacheKey = cacheManager.createKey(normalizedUrl);
+      const cachedRepo = cacheManager.get(cacheKey);
+
       expect(cachedRepo).not.toBeNull();
       expect(fs.existsSync(cachedRepo!)).toBe(true);
     });
@@ -143,28 +160,24 @@ describe('cached template integration tests', () => {
     let secondOutputDir: string;
 
     beforeAll(async () => {
-      await createFromCachedTemplate({
+      await createFromTemplate({
         templateUrl: DEFAULT_TEMPLATE_URL,
         outputDir: fs.mkdtempSync(path.join(os.tmpdir(), 'warmup-')),
-        answers: {
-          PROJECT_NAME: 'warmup',
-          MODULE_NAME: 'warmup'
-        },
-        cacheTool: testCacheTool
+        answers: buildAnswers('warmup'),
+        toolName: testCacheTool,
+        noTty: true,
+        fromPath: TEST_TEMPLATE
       });
 
       secondOutputDir = fs.mkdtempSync(path.join(os.tmpdir(), 'second-clone-'));
 
-      secondCloneResult = await createFromCachedTemplate({
+      secondCloneResult = await createFromTemplate({
         templateUrl: DEFAULT_TEMPLATE_URL,
         outputDir: secondOutputDir,
-        answers: {
-          PROJECT_NAME: 'cached-project',
-          AUTHOR: 'Cached Author',
-          DESCRIPTION: 'A cached test project',
-          MODULE_NAME: 'cachedmodule'
-        },
-        cacheTool: testCacheTool
+        answers: buildAnswers('cached'),
+        toolName: testCacheTool,
+        noTty: true,
+        fromPath: TEST_TEMPLATE
       });
     }, 60000);
 
diff --git a/packages/create-gen-app-test/src/cli.ts b/packages/create-gen-app-test/src/cli.ts
index 5496817..b5b36ec 100644
--- a/packages/create-gen-app-test/src/cli.ts
+++ b/packages/create-gen-app-test/src/cli.ts
@@ -6,16 +6,20 @@ import * as path from "path";
 import { Inquirerer, ListQuestion } from "inquirerer";
 import minimist, { ParsedArgs } from "minimist";
 
-import { cloneRepo, createGen } from "create-gen-app";
+import { CacheManager, GitCloner, checkNpmVersion } from "create-gen-app";
+import { createFromTemplate } from './index';
 
 const DEFAULT_REPO = "https://github.com/launchql/pgpm-boilerplates.git";
 const DEFAULT_PATH = ".";
 const DEFAULT_OUTPUT_FALLBACK = "create-gen-app-output";
+const DEFAULT_TOOL_NAME = "create-gen-app-test";
+const DEFAULT_TTL = 604800000; // 1 week
+const DEFAULT_TTL_DAYS = DEFAULT_TTL / (24 * 60 * 60 * 1000);
 
-// Use require for package.json to avoid module resolution issues
-const createGenPackageJson = require("create-gen-app/package.json");
-const PACKAGE_VERSION =
-  (createGenPackageJson as { version?: string }).version ?? "0.0.0";
+// Import package.json for version
+import * as createGenPackageJson from "create-gen-app/package.json";
+const PACKAGE_NAME = createGenPackageJson.name ?? "@launchql/cli";
+const PACKAGE_VERSION = createGenPackageJson.version ?? "0.0.0";
 
 const RESERVED_ARG_KEYS = new Set([
   "_",
@@ -37,6 +41,10 @@ const RESERVED_ARG_KEYS = new Set([
   "v",
   "no-tty",
   "n",
+  "clear-cache",
+  "c",
+  "ttl",
+  "no-ttl",
 ]);
 
 export interface CliResult {
@@ -58,9 +66,11 @@ export async function runCli(
       h: "help",
       v: "version",
       n: "no-tty",
+      c: "clear-cache",
+      // no alias for ttl to keep it explicit
     },
-    string: ["repo", "branch", "path", "template", "output"],
-    boolean: ["force", "help", "version", "no-tty"],
+    string: ["repo", "branch", "path", "template", "output", "ttl"],
+    boolean: ["force", "help", "version", "no-tty", "clear-cache", "no-ttl"],
     default: {
       repo: DEFAULT_REPO,
       path: DEFAULT_PATH,
@@ -77,19 +87,74 @@ export async function runCli(
     return;
   }
 
+  // Check for updates
+  try {
+    const versionCheck = await checkNpmVersion(PACKAGE_NAME, PACKAGE_VERSION);
+    if (versionCheck.isOutdated && versionCheck.latestVersion) {
+      console.warn(
+        `\n⚠️  New version available: ${versionCheck.currentVersion} → ${versionCheck.latestVersion}`
+      );
+      console.warn(`   Run: npm install -g ${PACKAGE_NAME}@latest\n`);
+    }
+  } catch {
+    // Silently ignore version check failures
+  }
+
+  const ttl = resolveTtlOption(args);
+
+  // Initialize modules
+  const cacheManager = new CacheManager({
+    toolName: DEFAULT_TOOL_NAME,
+    ttl,
+  });
+
+  // Handle --clear-cache
+  if (args["clear-cache"]) {
+    console.log("Clearing cache...");
+    cacheManager.clearAll();
+    console.log("✨ Cache cleared successfully!");
+    return;
+  }
+
+  const gitCloner = new GitCloner();
+
   if (!args.output && args._[0]) {
     args.output = args._[0];
   }
 
-  let tempDir: string | null = null;
-  try {
+  // Get or clone template
+  const normalizedUrl = gitCloner.normalizeUrl(args.repo);
+  const cacheKey = cacheManager.createKey(normalizedUrl, args.branch);
+
+  let templateDir: string;
+  const cachedPath = cacheManager.get(cacheKey);
+  const expiredMetadata = cacheManager.checkExpiration(cacheKey);
+
+  if (expiredMetadata) {
+    console.warn(
+      `⚠️  Cached template expired (last updated: ${new Date(expiredMetadata.lastUpdated).toLocaleString()})`
+    );
+    console.log('Updating cache...');
+    cacheManager.clear(cacheKey);
+  }
+
+  if (cachedPath && !expiredMetadata) {
+    console.log(`Using cached template from ${cachedPath}`);
+    templateDir = cachedPath;
+  } else {
     console.log(`Cloning template from ${args.repo}...`);
     if (args.branch) {
       console.log(`Using branch ${args.branch}`);
     }
-    tempDir = await cloneRepo(args.repo, { branch: args.branch });
+    const tempDest = path.join(cacheManager.getReposDir(), cacheKey);
+    gitCloner.clone(normalizedUrl, tempDest, { branch: args.branch, depth: 1 });
+    cacheManager.set(cacheKey, tempDest);
+    templateDir = tempDest;
+    console.log('Template cached for future runs');
+  }
 
-    const selectionRoot = path.join(tempDir, args.path);
+  try {
+    const selectionRoot = path.join(templateDir, args.path);
     if (
       !fs.existsSync(selectionRoot) ||
       !fs.statSync(selectionRoot).isDirectory()
@@ -146,21 +211,22 @@ export async function runCli(
       args["no-tty"] ?? (args as Record<string, unknown>).noTty
     );
 
-    await createGen({
+    // Use the createFromTemplate function which will use the same cache
+    await createFromTemplate({
       templateUrl: args.repo,
-      fromBranch: args.branch,
+      branch: args.branch,
       fromPath,
       outputDir,
-      argv: answerOverrides,
+      answers: answerOverrides,
       noTty,
+      toolName: DEFAULT_TOOL_NAME,
+      ttl,
     });
 
     console.log(`\n✨ Done! Project ready at ${outputDir}`);
     return { outputDir, template: selectedTemplate };
-  } finally {
-    if (tempDir && fs.existsSync(tempDir)) {
-      fs.rmSync(tempDir, { recursive: true, force: true });
-    }
+  } catch (error) {
+    throw error;
   }
 }
 
@@ -178,12 +244,18 @@ Options:
   -t, --template <name>    Template folder to use (will prompt if omitted)
   -o, --output <dir>       Output directory (defaults to ./<template>)
   -f, --force              Overwrite the output directory if it exists
+  -c, --clear-cache        Clear the template cache and exit
+      --ttl <ms>           Set cache TTL in milliseconds (flag alone uses 1 week)
+      --no-ttl             Disable TTL (cache never expires)
   -v, --version            Show CLI version
   -n, --no-tty             Disable TTY mode for prompts
   -h, --help               Show this help message
 
 You can also pass variable overrides, e.g.:
   node cli --template module --PROJECT_NAME my-app
+
+Cache is stored at: ~/.${DEFAULT_TOOL_NAME}/cache/repos
+TTL: none by default; use --ttl to enable (default ${DEFAULT_TTL_DAYS} days when flag provided)
 `);
 }
 
@@ -254,3 +326,26 @@ if (require.main === module) {
     process.exitCode = 1;
   });
 }
+
+function resolveTtlOption(args: ParsedArgs): number | undefined {
+  const disableTtl = Boolean(args["no-ttl"] ?? (args as Record<string, unknown>).noTtl);
+  if (disableTtl) {
+    return undefined;
+  }
+
+  if (args.ttl === undefined) {
+    return undefined;
+  }
+
+  // Support --ttl with no value to use the default 1-week TTL
+  if (args.ttl === true) {
+    return DEFAULT_TTL;
+  }
+
+  const ttlMs = Number(args.ttl);
+  if (Number.isNaN(ttlMs) || ttlMs < 0) {
+    throw new Error("TTL must be a non-negative number of milliseconds");
+  }
+
+  return ttlMs === 0 ? undefined : ttlMs;
+}
diff --git a/packages/create-gen-app-test/src/index.ts b/packages/create-gen-app-test/src/index.ts
index fe6db8d..b0718bf 100644
--- a/packages/create-gen-app-test/src/index.ts
+++ b/packages/create-gen-app-test/src/index.ts
@@ -1,63 +1,105 @@
-import { replaceVariables, extractVariables, TemplateCache } from 'create-gen-app';
+import * as path from 'path';
+import { CacheManager } from 'create-gen-app';
+import { GitCloner } from 'create-gen-app';
+import { Templatizer } from 'create-gen-app';
 
-export interface CachedTemplateOptions {
+// Configuration constants (top-most layer owns defaults)
+const DEFAULT_TOOL_NAME = 'pgpm';
+
+export interface CreateFromTemplateOptions {
   templateUrl: string;
   outputDir: string;
-  answers: Record<string, any>;
-  cacheTool?: string;
+  answers?: Record<string, any>;
+  toolName?: string;
   branch?: string;
   ttl?: number;
-  maxAge?: number;
+  baseDir?: string;
+  fromPath?: string;
+  noTty?: boolean;
 }
 
-export interface CachedTemplateResult {
+export interface CreateFromTemplateResult {
   outputDir: string;
   cacheUsed: boolean;
+  cacheExpired: boolean;
   cachePath?: string;
 }
 
 /**
- * Create project from cached template using the shared TemplateCache
- * @param options - Options for creating from cached template
- * @returns Result with output directory and cache information
+ * Create a project from a template with caching support
+ * Orchestrates CacheManager + GitCloner + Templatizer
  */
-export async function createFromCachedTemplate(options: CachedTemplateOptions): Promise<CachedTemplateResult> {
-  const { templateUrl, outputDir, answers, cacheTool = 'mymodule', branch, ttl, maxAge } = options;
-
-  const templateCache = new TemplateCache({
-    enabled: true,
-    toolName: cacheTool,
+export async function createFromTemplate(
+  options: CreateFromTemplateOptions
+): Promise<CreateFromTemplateResult> {
+  const {
+    templateUrl,
+    outputDir,
+    answers = {},
+    toolName = DEFAULT_TOOL_NAME,
+    branch,
     ttl,
-    maxAge,
-  });
+    baseDir,
+    fromPath,
+    noTty = false,
+  } = options;
+
+  // 1. Initialize modules
+  const cacheManager = new CacheManager({ toolName, ttl, baseDir });
+  const gitCloner = new GitCloner();
+  const templatizer = new Templatizer();
+
+  // 2. Create cache key
+  const normalizedUrl = gitCloner.normalizeUrl(templateUrl);
+  const cacheKey = cacheManager.createKey(normalizedUrl, branch);
 
+  // 3. Check cache + expiration
   let templateDir: string;
   let cacheUsed = false;
-  let cachePath: string | undefined;
+  let cacheExpired = false;
 
-  const cachedRepo = templateCache.get(templateUrl, branch);
+  const cachedPath = cacheManager.get(cacheKey);
+  const expiredMetadata = cacheManager.checkExpiration(cacheKey);
 
-  if (cachedRepo) {
-    console.log(`Using cached template from ${cachedRepo}`);
-    templateDir = cachedRepo;
+  if (expiredMetadata) {
+    // Cache exists but expired - warn user then auto-update
+    console.warn(
+      `⚠️  Cached template expired (last updated: ${new Date(expiredMetadata.lastUpdated).toLocaleString()})`
+    );
+    console.log('Updating cache...');
+    cacheManager.clear(cacheKey);
+    cacheExpired = true;
+  }
+
+  if (cachedPath && !expiredMetadata) {
+    console.log(`Using cached template: ${cachedPath}`);
+    templateDir = cachedPath;
     cacheUsed = true;
-    cachePath = cachedRepo;
   } else {
-    console.log(`Cloning template to cache from ${templateUrl}`);
-    templateDir = templateCache.set(templateUrl, branch);
-    cachePath = templateDir;
+    // 4. Clone to cache
+    console.log(`Cloning ${normalizedUrl}...`);
+    const tempDest = path.join(cacheManager.getReposDir(), cacheKey);
+
+    gitCloner.clone(normalizedUrl, tempDest, { branch, depth: 1 });
+    cacheManager.set(cacheKey, tempDest);
+
+    templateDir = tempDest;
+    console.log('Template cached for future runs');
   }
 
-  const extractedVariables = await extractVariables(templateDir);
+  // 5. Process template
+  console.log('Processing template...');
+  await templatizer.process(templateDir, outputDir, { argv: answers, noTty, fromPath });
 
-  await replaceVariables(templateDir, outputDir, extractedVariables, answers);
+  console.log(`✨ Project created at ${outputDir}`);
 
   return {
     outputDir,
     cacheUsed,
-    cachePath
+    cacheExpired,
+    cachePath: templateDir,
   };
 }
 
-// Re-export TemplateCache for convenience
-export { TemplateCache } from 'create-gen-app';
+// Re-export components for external use
+export { CacheManager, GitCloner, Templatizer } from 'create-gen-app';
diff --git a/packages/create-gen-app/README.md b/packages/create-gen-app/README.md
index 751e06f..989dad2 100644
--- a/packages/create-gen-app/README.md
+++ b/packages/create-gen-app/README.md
@@ -22,10 +22,10 @@ A TypeScript-first library for cloning template repositories, asking the user fo
 
 - Clone any Git repo (or GitHub `org/repo` shorthand) and optionally select a branch + subdirectory
 - Extract template variables from filenames and file contents using the safer `____variable____` convention
-- Merge auto-discovered variables with `.questions.{json,js}` (questions win, including `ignore` patterns)
+- Merge auto-discovered variables with `.questions.{json,js}` (questions win)
 - Interactive prompts powered by `inquirerer`, with flexible override mapping (`argv` support) and non-TTY mode for CI
 - License scaffolding: choose from MIT, Apache-2.0, ISC, GPL-3.0, BSD-3-Clause, Unlicense, or MPL-2.0 and generate a populated `LICENSE`
-- Built-in template caching powered by `appstash`, so repeat runs skip `git clone` (configurable via `cache` options)
+- Built-in template caching powered by `appstash`, so repeat runs skip `git clone` (configurable via `cache` options; TTL is opt-in)
 
 ## Installation
 
@@ -37,51 +37,66 @@ npm install create-gen-app
 
 ## Library Usage
 
-```typescript
-import * as os from "os";
-import * as path from "path";
-
-import { createGen } from "create-gen-app";
-
-await createGen({
-  templateUrl: "https://github.com/user/template-repo",
-  fromBranch: "main",
-  fromPath: "templates/module",
-  outputDir: "./my-new-project",
-  argv: {
-    USERFULLNAME: "Jane Dev",
-    USEREMAIL: "jane@example.com",
-    MODULENAME: "awesome-module",
-    LICENSE: "MIT",
-  },
-  noTty: true,
-  cache: {
-    // optional: override tool/baseDir (defaults to pgpm + ~/.pgpm)
-    toolName: "pgpm",
-    baseDir: path.join(os.tmpdir(), "create-gen-cache"),
-  },
-});
-```
+`create-gen-app` provides a modular set of classes to handle template cloning, caching, and processing.
 
-### Template Caching
+### Core Components
 
-`create-gen-app` caches repositories under `~/.pgpm/cache/repos/<hash>` by default (using [`appstash`](https://github.com/hyperweb-io/dev-utils/tree/main/packages/appstash)). The first run clones & stores the repo, subsequent runs re-use the cached directory.
+- **CacheManager**: Handles local caching of git repositories with TTL (Time-To-Live) support.
+- **GitCloner**: Handles cloning git repositories.
+- **Templatizer**: Handles variable extraction, user prompting, and template generation.
 
-- Disable caching with `cache: false` or `cache: { enabled: false }`
-- Override the tool name or base directory with `cache: { toolName, baseDir }`
-- For tests/CI, point `baseDir` to a temporary folder so the suite does not touch the developer’s real home directory:
+### Example: Orchestration
 
-```ts
-const tempBase = fs.mkdtempSync(path.join(os.tmpdir(), "create-gen-cache-"));
+Here is how you can combine these components to create a full CLI pipeline (similar to `create-gen-app-test`):
 
-await createGen({
-  ...options,
-  cache: { baseDir: tempBase, toolName: "pgpm-test-suite" },
-});
+```typescript
+import * as path from "path";
+import { CacheManager, GitCloner, Templatizer } from "create-gen-app";
+
+async function main() {
+  const repoUrl = "https://github.com/user/template-repo";
+  const outputDir = "./my-new-project";
+
+  // 1. Initialize components
+  const cacheManager = new CacheManager({
+    toolName: "my-cli", // ~/.my-cli/cache
+    // ttl is optional; omit to keep cache forever, or set (e.g., 1 week) to enable expiration
+    // ttl: 604800000,
+  });
+  const gitCloner = new GitCloner();
+  const templatizer = new Templatizer();
+
+  // 2. Resolve template path (Cache or Clone)
+  const normalizedUrl = gitCloner.normalizeUrl(repoUrl);
+  const cacheKey = cacheManager.createKey(normalizedUrl);
+  
+  // Check cache
+  let templateDir = cacheManager.get(cacheKey);
+  const isExpired = cacheManager.checkExpiration(cacheKey);
+
+  if (!templateDir || isExpired) {
+    console.log("Cloning template...");
+    if (isExpired) cacheManager.clear(cacheKey);
+    
+    // Clone to a temporary location managed by CacheManager
+    const tempDest = path.join(cacheManager.getReposDir(), cacheKey);
+    await gitCloner.clone(normalizedUrl, tempDest, { depth: 1 });
+    
+    // Register and update cache
+    cacheManager.set(cacheKey, tempDest);
+    templateDir = tempDest;
+  }
+
+  // 3. Process Template
+  await templatizer.process(templateDir, outputDir, {
+    argv: {
+      PROJECT_NAME: "my-app",
+      LICENSE: "MIT"
+    }
+  });
+}
 ```
 
-The cache directory never mutates the template, so reusing the same cached repo across many runs is safe.
-
 ### Template Variables
 
 Variables should be wrapped in four underscores on each side:
@@ -97,13 +112,12 @@ export const projectName = "____projectName____";
 export const author = "____fullName____";
 ```
 
-### Custom Questions & Ignore Rules
+### Custom Questions
 
 Create a `.questions.json`:
 
 ```json
 {
-  "ignore": ["__tests__", "docs/drafts"],
   "questions": [
     {
       "name": "____fullName____",
@@ -133,11 +147,21 @@ No code changes are needed; the generator discovers templates at runtime and wil
 
 ## API Overview
 
-- `createGen(options)` – full pipeline (clone → extract → prompt → replace)
-- `cloneRepo(url, { branch })` – clone to a temp dir
-- `normalizeCacheOptions(cache)` / `prepareTemplateDirectory(...)` – inspect or reuse cached template repos
-- `extractVariables(dir)` – parse file/folder names + content for variables, load `.questions`
-- `promptUser(extracted, argv, noTty)` – run interactive questions with override alias deduping
-- `replaceVariables(templateDir, outputDir, extracted, answers)` – copy files, rename paths, render licenses
+### CacheManager
+- `new CacheManager(config)`: Initialize with `toolName` and optional `ttl`.
+- `get(key)`: Get path to cached repo if exists.
+- `set(key, path)`: Register a path in the cache.
+- `checkExpiration(key)`: Check if a cache entry is expired.
+- `clear(key)`: Remove a specific cache entry.
+- `clearAll()`: Clear all cached repos.
+- When `ttl` is `undefined`, cache entries never expire. Provide a TTL (ms) only when you want automatic invalidation.
+- Advanced: if you already own an appstash instance, pass `dirs` to reuse it instead of letting CacheManager create its own.
+
+### GitCloner
+- `clone(url, dest, options)`: Clone a repo to a destination.
+- `normalizeUrl(url)`: Normalize a git URL for consistency.
+
+### Templatizer
+- `process(templateDir, outputDir, options)`: Run the full template generation pipeline (extract -> prompt -> replace).
 
-See `packages/create-gen-app-test/dev/README.md` for the local development helper script (`pnpm --filter create-gen-app-test dev`).
+See `packages/create-gen-app-test` for a complete reference implementation.
diff --git a/packages/create-gen-app/__tests__/cache.test.ts b/packages/create-gen-app/__tests__/cache.test.ts
deleted file mode 100644
index 809575f..0000000
--- a/packages/create-gen-app/__tests__/cache.test.ts
+++ /dev/null
@@ -1,150 +0,0 @@
-import * as fs from "fs";
-import * as os from "os";
-import * as path from "path";
-
-import { createGen } from "../src";
-import {
-  TEST_BRANCH,
-  TEST_REPO,
-  TEST_TEMPLATE,
-  buildAnswers,
-  cleanupWorkspace,
-  createTempWorkspace,
-} from "../test-utils/integration-helpers";
-
-jest.setTimeout(180_000);
-
-describe("template caching (appstash)", () => {
-  let tempBaseDir: string;
-  const cacheTool = `pgpm-cache-${Date.now()}`;
-
-  beforeEach(() => {
-    tempBaseDir = fs.mkdtempSync(path.join(os.tmpdir(), "create-gen-cache-"));
-  });
-
-  afterEach(() => {
-    if (fs.existsSync(tempBaseDir)) {
-      fs.rmSync(tempBaseDir, { recursive: true, force: true });
-    }
-  });
-
-  it("reuses cached repositories across runs when cache is enabled", async () => {
-    const cacheOptions = {
-      toolName: cacheTool,
-      baseDir: tempBaseDir,
-      enabled: true,
-    };
-
-    const firstWorkspace = createTempWorkspace("cache-first");
-    const firstAnswers = buildAnswers("cache-first");
-
-    try {
-      await createGen({
-        templateUrl: TEST_REPO,
-        fromBranch: TEST_BRANCH,
-        fromPath: TEST_TEMPLATE,
-        outputDir: firstWorkspace.outputDir,
-        argv: firstAnswers,
-        noTty: true,
-        cache: cacheOptions,
-      });
-    } finally {
-      cleanupWorkspace(firstWorkspace);
-    }
-
-    const repoCacheDir = path.join(tempBaseDir, `.${cacheTool}`, "cache", "repos");
-    expect(fs.existsSync(repoCacheDir)).toBe(true);
-    const cachedEntries = fs.readdirSync(repoCacheDir);
-    expect(cachedEntries.length).toBeGreaterThan(0);
-
-    const secondWorkspace = createTempWorkspace("cache-second");
-    const secondAnswers = buildAnswers("cache-second");
-    const logSpy = jest.spyOn(console, "log").mockImplementation(() => undefined);
-
-    try {
-      await createGen({
-        templateUrl: TEST_REPO,
-        fromBranch: TEST_BRANCH,
-        fromPath: TEST_TEMPLATE,
-        outputDir: secondWorkspace.outputDir,
-        argv: secondAnswers,
-        noTty: true,
-        cache: cacheOptions,
-      });
-
-      expect(
-        logSpy.mock.calls.some(([message]) =>
-          typeof message === "string" && message.includes("Using cached repository")
-        )
-      ).toBe(true);
-    } finally {
-      logSpy.mockRestore();
-      cleanupWorkspace(secondWorkspace);
-    }
-  });
-
-  it("invalidates cache when TTL expires", async () => {
-    const shortTtl = 1000; // 1 second
-    const cacheOptions = {
-      toolName: `${cacheTool}-ttl`,
-      baseDir: tempBaseDir,
-      enabled: true,
-      ttl: shortTtl,
-    };
-
-    const firstWorkspace = createTempWorkspace("ttl-first");
-    const firstAnswers = buildAnswers("ttl-first");
-    const logSpy = jest.spyOn(console, "log").mockImplementation(() => undefined);
-
-    try {
-      await createGen({
-        templateUrl: TEST_REPO,
-        fromBranch: TEST_BRANCH,
-        fromPath: TEST_TEMPLATE,
-        outputDir: firstWorkspace.outputDir,
-        argv: firstAnswers,
-        noTty: true,
-        cache: cacheOptions,
-      });
-
-      expect(
-        logSpy.mock.calls.some(([message]) =>
-          typeof message === "string" && message.includes("Caching repository")
-        )
-      ).toBe(true);
-    } finally {
-      cleanupWorkspace(firstWorkspace);
-    }
-
-    // Wait for TTL to expire
-    await new Promise((resolve) => setTimeout(resolve, shortTtl + 200));
-
-    logSpy.mockClear();
-    const secondWorkspace = createTempWorkspace("ttl-second");
-    const secondAnswers = buildAnswers("ttl-second");
-
-    try {
-      await createGen({
-        templateUrl: TEST_REPO,
-        fromBranch: TEST_BRANCH,
-        fromPath: TEST_TEMPLATE,
-        outputDir: secondWorkspace.outputDir,
-        argv: secondAnswers,
-        noTty: true,
-        cache: cacheOptions,
-      });
-
-      // Should re-cache since TTL expired
-      expect(
-        logSpy.mock.calls.some(([message]) =>
-          typeof message === "string" && message.includes("Caching repository")
-        )
-      ).toBe(true);
-    } finally {
-      logSpy.mockRestore();
-      cleanupWorkspace(secondWorkspace);
-    }
-  });
-});
-
-
diff --git a/packages/create-gen-app/__tests__/create-gen-flow.test.ts b/packages/create-gen-app/__tests__/create-gen-flow.test.ts
deleted file mode 100644
index 5303ba6..0000000
--- a/packages/create-gen-app/__tests__/create-gen-flow.test.ts
+++ /dev/null
@@ -1,57 +0,0 @@
-import * as fs from "fs";
-import * as path from "path";
-
-import { createGen } from "../src";
-import {
-  TEST_BRANCH,
-  TEST_REPO,
-  TEST_TEMPLATE,
-  buildAnswers,
-  cleanupWorkspace,
-  createTempWorkspace,
-} from "../test-utils/integration-helpers";
-
-jest.setTimeout(180_000);
-
-describe("createGen integration (GitHub templates)", () => {
-  it("clones the default repo and generates the module template", async () => {
-    const workspace = createTempWorkspace("flow");
-
-    try {
-      const answers = buildAnswers("flow");
-      const result = await createGen({
-        templateUrl: TEST_REPO,
-        fromBranch: TEST_BRANCH,
-        fromPath: TEST_TEMPLATE,
-        outputDir: workspace.outputDir,
-        argv: answers,
-        noTty: true,
-      });
-
-      expect(result).toBe(workspace.outputDir);
-
-      const packageJsonPath = path.join(workspace.outputDir, "package.json");
-      expect(fs.existsSync(packageJsonPath)).toBe(true);
-
-      const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
-      expect(pkg.name).toBe(answers.PACKAGE_IDENTIFIER);
-      expect(pkg.license).toBe(answers.LICENSE);
-      expect(pkg.author).toContain(answers.USERFULLNAME);
-
-      const questionsJsonPath = path.join(
-        workspace.outputDir,
-        ".questions.json"
-      );
-      expect(fs.existsSync(questionsJsonPath)).toBe(false);
-
-      const licensePath = path.join(workspace.outputDir, "LICENSE");
-      expect(fs.existsSync(licensePath)).toBe(true);
-      const licenseContent = fs.readFileSync(licensePath, "utf8");
-      expect(licenseContent).toContain(answers.USERFULLNAME);
-      expect(licenseContent).toContain("MIT License");
-    } finally {
-      cleanupWorkspace(workspace);
-    }
-  });
-});
-
diff --git a/packages/create-gen-app/__tests__/create-gen.test.ts b/packages/create-gen-app/__tests__/create-gen.test.ts
index 76e0322..fda728b 100644
--- a/packages/create-gen-app/__tests__/create-gen.test.ts
+++ b/packages/create-gen-app/__tests__/create-gen.test.ts
@@ -3,10 +3,7 @@ import * as os from "os";
 import * as path from "path";
 import { execSync } from "child_process";
 
-import { cloneRepo } from "../src/clone";
-import { extractVariables } from "../src/extract";
-import { promptUser } from "../src/prompt";
-import { ExtractedVariables } from "../src/types";
+import { extractVariables, promptUser, replaceVariables, ExtractedVariables, GitCloner } from "../src/index";
 
 jest.mock("child_process", () => {
   return {
@@ -424,7 +421,6 @@ module.exports = {
         author: "Jane Smith",
       };
 
-      const { replaceVariables } = require("../src/replace");
       await replaceVariables(
         testTempDir,
         testOutputDir,
@@ -450,7 +446,6 @@ module.exports = {
         projectName: "myproject",
       };
 
-      const { replaceVariables } = require("../src/replace");
       await replaceVariables(
         testTempDir,
         testOutputDir,
@@ -476,7 +471,6 @@ module.exports = {
         moduleName: "auth",
       };
 
-      const { replaceVariables } = require("../src/replace");
       await replaceVariables(
         testTempDir,
         testOutputDir,
@@ -498,7 +492,6 @@ module.exports = {
       fs.writeFileSync(path.join(testTempDir, "README.md"), "Regular file");
 
       const extractedVariables = await extractVariables(testTempDir);
-      const { replaceVariables } = require("../src/replace");
       await replaceVariables(
         testTempDir,
         testOutputDir,
@@ -523,7 +516,6 @@ module.exports = {
         name: "Alice",
       };
 
-      const { replaceVariables } = require("../src/replace");
       await replaceVariables(
         testTempDir,
         testOutputDir,
@@ -539,27 +531,29 @@ module.exports = {
     });
   });
 
-  describe("cloneRepo", () => {
+  describe("GitCloner", () => {
     const execSyncMock = execSync as jest.MockedFunction<typeof execSync>;
+    let gitCloner: GitCloner;
 
     beforeEach(() => {
+      gitCloner = new GitCloner();
       execSyncMock.mockReset();
       execSyncMock.mockImplementation(() => undefined);
     });
 
-    it("clones default branch when no branch provided", async () => {
-      const tempDir = await cloneRepo("https://github.com/example/repo.git");
+    it("clones default branch when no branch provided", () => {
+      const tempDir = path.join(testTempDir, "clone-test");
+      gitCloner.clone("https://github.com/example/repo.git", tempDir);
       const command = execSyncMock.mock.calls[0][0] as string;
       expect(command).toContain(
-        "git clone --depth 1 https://github.com/example/repo.git"
+        "git clone --single-branch --depth 1 https://github.com/example/repo.git"
       );
       expect(command.trim().endsWith(tempDir)).toBe(true);
-      expect(fs.existsSync(tempDir)).toBe(true);
-      fs.rmSync(tempDir, { recursive: true, force: true });
     });
 
-    it("clones a specific branch when provided", async () => {
-      const tempDir = await cloneRepo("https://github.com/example/repo.git", {
+    it("clones a specific branch when provided", () => {
+      const tempDir = path.join(testTempDir, "clone-branch-test");
+      gitCloner.clone("https://github.com/example/repo.git", tempDir, {
         branch: "dev",
       });
       const command = execSyncMock.mock.calls[0][0] as string;
@@ -567,7 +561,6 @@ module.exports = {
         "git clone --branch dev --single-branch --depth 1 https://github.com/example/repo.git"
       );
       expect(command.trim().endsWith(tempDir)).toBe(true);
-      fs.rmSync(tempDir, { recursive: true, force: true });
     });
   });
 
diff --git a/packages/create-gen-app/__tests__/template-cache.test.ts b/packages/create-gen-app/__tests__/template-cache.test.ts
deleted file mode 100644
index ec4c78a..0000000
--- a/packages/create-gen-app/__tests__/template-cache.test.ts
+++ /dev/null
@@ -1,270 +0,0 @@
-import * as fs from "fs";
-import * as os from "os";
-import * as path from "path";
-
-import { TemplateCache } from "../src/template-cache";
-
-const TEST_REPO = "https://github.com/launchql/pgpm-boilerplates";
-
-describe("TemplateCache", () => {
-  let tempBaseDir: string;
-  const cacheTool = `test-cache-${Date.now()}`;
-
-  beforeEach(() => {
-    tempBaseDir = fs.mkdtempSync(path.join(os.tmpdir(), "template-cache-test-"));
-  });
-
-  afterEach(() => {
-    if (fs.existsSync(tempBaseDir)) {
-      fs.rmSync(tempBaseDir, { recursive: true, force: true });
-    }
-  });
-
-  describe("basic cache operations", () => {
-    it("should return null for non-existent cache", () => {
-      const cache = new TemplateCache({
-        enabled: true,
-        toolName: cacheTool,
-        baseDir: tempBaseDir,
-      });
-
-      const result = cache.get("https://github.com/test/repo");
-      expect(result).toBeNull();
-    });
-
-    it("should store and retrieve a cached template", () => {
-      const cache = new TemplateCache({
-        enabled: true,
-        toolName: cacheTool,
-        baseDir: tempBaseDir,
-      });
-
-      const cachedPath = cache.set(TEST_REPO);
-      expect(fs.existsSync(cachedPath)).toBe(true);
-
-      const retrievedPath = cache.get(TEST_REPO);
-      expect(retrievedPath).toBe(cachedPath);
-    }, 60000);
-
-    it("should handle branches correctly", () => {
-      const cache = new TemplateCache({
-        enabled: true,
-        toolName: cacheTool,
-        baseDir: tempBaseDir,
-      });
-
-      const mainPath = cache.set(TEST_REPO);
-      const mainRetrieved = cache.get(TEST_REPO);
-
-      expect(mainRetrieved).toBe(mainPath);
-    }, 60000);
-
-    it("should clear specific cached template", () => {
-      const cache = new TemplateCache({
-        enabled: true,
-        toolName: cacheTool,
-        baseDir: tempBaseDir,
-      });
-
-      const cachedPath = cache.set(TEST_REPO);
-      expect(cache.get(TEST_REPO)).toBe(cachedPath);
-
-      cache.clear(TEST_REPO);
-      expect(cache.get(TEST_REPO)).toBeNull();
-    }, 60000);
-
-    it("should clear all cached templates", () => {
-      const cache = new TemplateCache({
-        enabled: true,
-        toolName: cacheTool,
-        baseDir: tempBaseDir,
-      });
-
-      cache.set(TEST_REPO);
-      cache.clearAll();
-
-      expect(cache.get(TEST_REPO)).toBeNull();
-    }, 60000);
-  });
-
-  describe("TTL functionality", () => {
-    it("should respect TTL and invalidate expired cache", async () => {
-      const shortTtl = 1000; // 1 second
-      const cache = new TemplateCache({
-        enabled: true,
-        toolName: cacheTool,
-        baseDir: tempBaseDir,
-        ttl: shortTtl,
-      });
-
-      const cachedPath = cache.set(TEST_REPO);
-      expect(cache.get(TEST_REPO)).toBe(cachedPath);
-
-      // Wait for TTL to expire
-      await new Promise((resolve) => setTimeout(resolve, shortTtl + 100));
-
-      // Cache should be expired and return null
-      const result = cache.get(TEST_REPO);
-      expect(result).toBeNull();
-    }, 65000);
-
-    it("should work with maxAge alias", () => {
-      const cache = new TemplateCache({
-        enabled: true,
-        toolName: cacheTool,
-        baseDir: tempBaseDir,
-        maxAge: 5000,
-      });
-
-      const config = cache.getConfig();
-      expect(config.ttl).toBe(5000);
-    });
-
-    it("should prioritize ttl over maxAge when both are provided", () => {
-      const cache = new TemplateCache({
-        enabled: true,
-        toolName: cacheTool,
-        baseDir: tempBaseDir,
-        ttl: 3000,
-        maxAge: 5000,
-      });
-
-      const config = cache.getConfig();
-      expect(config.ttl).toBe(3000);
-    });
-
-    it("should not expire cache when TTL is not set", async () => {
-      const cache = new TemplateCache({
-        enabled: true,
-        toolName: cacheTool,
-        baseDir: tempBaseDir,
-      });
-
-      const cachedPath = cache.set(TEST_REPO);
-      expect(cache.get(TEST_REPO)).toBe(cachedPath);
-
-      // Wait a bit
-      await new Promise((resolve) => setTimeout(resolve, 100));
-
-      // Cache should still be valid
-      const result = cache.get(TEST_REPO);
-      expect(result).toBe(cachedPath);
-    }, 60000);
-  });
-
-  describe("metadata operations", () => {
-    it("should store and retrieve metadata", () => {
-      const cache = new TemplateCache({
-        enabled: true,
-        toolName: cacheTool,
-        baseDir: tempBaseDir,
-      });
-
-      cache.set(TEST_REPO);
-      const metadata = cache.getMetadata(TEST_REPO);
-
-      expect(metadata).not.toBeNull();
-      expect(metadata?.templateUrl).toBe(TEST_REPO);
-      expect(metadata?.timestamp).toBeDefined();
-      expect(metadata?.gitUrl).toBeDefined();
-    }, 60000);
-
-    it("should return null metadata for non-existent cache", () => {
-      const cache = new TemplateCache({
-        enabled: true,
-        toolName: cacheTool,
-        baseDir: tempBaseDir,
-      });
-
-      const metadata = cache.getMetadata("https://github.com/test/nonexistent");
-      expect(metadata).toBeNull();
-    });
-
-    it("should list all cached templates", () => {
-      const cache = new TemplateCache({
-        enabled: true,
-        toolName: cacheTool,
-        baseDir: tempBaseDir,
-      });
-
-      cache.set(TEST_REPO);
-
-      const list = cache.listAll();
-      expect(list.length).toBeGreaterThan(0);
-      expect(list[0]).toHaveProperty("templateUrl");
-      expect(list[0]).toHaveProperty("timestamp");
-      expect(list[0]).toHaveProperty("expired");
-      expect(list[0].expired).toBe(false);
-    }, 60000);
-
-    it("should mark expired templates in list", async () => {
-      const cache = new TemplateCache({
-        enabled: true,
-        toolName: cacheTool,
-        baseDir: tempBaseDir,
-        ttl: 500,
-      });
-
-      cache.set(TEST_REPO);
-
-      // Wait for expiration
-      await new Promise((resolve) => setTimeout(resolve, 600));
-
-      const list = cache.listAll();
-      expect(list.length).toBeGreaterThan(0);
-      expect(list[0].expired).toBe(true);
-    }, 61000);
-  });
-
-  describe("disabled cache", () => {
-    it("should return null when cache is disabled", () => {
-      const cache = new TemplateCache(false);
-
-      expect(cache.isEnabled()).toBe(false);
-      expect(cache.get(TEST_REPO)).toBeNull();
-    });
-
-    it("should throw error when trying to set with disabled cache", () => {
-      const cache = new TemplateCache({ enabled: false });
-
-      expect(() => cache.set(TEST_REPO)).toThrow("Cache is disabled");
-    });
-
-    it("should not error when clearing disabled cache", () => {
-      const cache = new TemplateCache(false);
-
-      expect(() => cache.clear(TEST_REPO)).not.toThrow();
-      expect(() => cache.clearAll()).not.toThrow();
-    });
-  });
-
-  describe("configuration", () => {
-    it("should use default tool name when not provided", () => {
-      const cache = new TemplateCache({
-        enabled: true,
-        baseDir: tempBaseDir,
-      });
-
-      const config = cache.getConfig();
-      expect(config.toolName).toBe("pgpm");
-    });
-
-    it("should use custom tool name", () => {
-      const customTool = "my-custom-tool";
-      const cache = new TemplateCache({
-        enabled: true,
-        toolName: customTool,
-        baseDir: tempBaseDir,
-      });
-
-      const config = cache.getConfig();
-      expect(config.toolName).toBe(customTool);
-    });
-
-    it("should enable cache by default", () => {
-      const cache = new TemplateCache({});
-
-      expect(cache.isEnabled()).toBe(true);
-    });
-  });
-});
diff --git a/packages/create-gen-app/__tests__/ttl-expiration.test.ts b/packages/create-gen-app/__tests__/ttl-expiration.test.ts
new file mode 100644
index 0000000..d112fa9
--- /dev/null
+++ b/packages/create-gen-app/__tests__/ttl-expiration.test.ts
@@ -0,0 +1,59 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { CacheManager } from '../src/cache/cache-manager';
+import { GitCloner } from '../src/git/git-cloner';
+
+describe('TTL expiration', () => {
+  it('invalidates cache when TTL expires', async () => {
+    const testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ttl-test-'));
+    const cacheManager = new CacheManager({
+      toolName: 'test-ttl',
+      ttl: 1000, // 1 second
+      baseDir: testDir,
+    });
+
+    const gitCloner = new GitCloner();
+    const testRepo = 'https://github.com/launchql/pgpm-boilerplates';
+
+    try {
+      // First clone - cache miss
+      const cacheKey = cacheManager.createKey(testRepo);
+      const tempDest = path.join(cacheManager.getReposDir(), cacheKey);
+
+      console.log(`Cloning test repository to ${tempDest}...`);
+      gitCloner.clone(testRepo, tempDest, { depth: 1 });
+      cacheManager.set(cacheKey, tempDest);
+
+      // Verify cache hit
+      const cachedPath = cacheManager.get(cacheKey);
+      expect(cachedPath).toBe(tempDest);
+      expect(fs.existsSync(cachedPath as string)).toBe(true);
+
+      // Verify not expired yet
+      const notExpired = cacheManager.checkExpiration(cacheKey);
+      expect(notExpired).toBeNull();
+
+      // Wait for expiration
+      console.log('Waiting 1.1 seconds for TTL to expire...');
+      await new Promise(resolve => setTimeout(resolve, 1100));
+
+      // Check expiration
+      const expiredMeta = cacheManager.checkExpiration(cacheKey);
+      expect(expiredMeta).not.toBeNull();
+      expect(expiredMeta!.lastUpdated).toBeDefined();
+      expect(expiredMeta!.key).toBe(cacheKey);
+
+      // Get should return null for expired
+      const expiredGet = cacheManager.get(cacheKey);
+      expect(expiredGet).toBeNull();
+
+      console.log('TTL expiration test passed!');
+    } finally {
+      // Cleanup
+      if (fs.existsSync(testDir)) {
+        fs.rmSync(testDir, { recursive: true, force: true });
+      }
+    }
+  }, 65000); // 65 second timeout
+});
diff --git a/packages/create-gen-app/create-gen-app-test/APACHE-2.0.txt b/packages/create-gen-app/create-gen-app-test/APACHE-2.0.txt
deleted file mode 100644
index ddcd1dd..0000000
--- a/packages/create-gen-app/create-gen-app-test/APACHE-2.0.txt
+++ /dev/null
@@ -1,18 +0,0 @@
-Apache License
-Version 2.0, January 2004
-http://www.apache.org/licenses/
-
-Copyright (c) {{YEAR}} {{AUTHOR}}{{EMAIL_LINE}}
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-
diff --git a/packages/create-gen-app/create-gen-app-test/BSD-3-CLAUSE.txt b/packages/create-gen-app/create-gen-app-test/BSD-3-CLAUSE.txt
deleted file mode 100644
index 3bd6c3b..0000000
--- a/packages/create-gen-app/create-gen-app-test/BSD-3-CLAUSE.txt
+++ /dev/null
@@ -1,28 +0,0 @@
-BSD 3-Clause License
-
-Copyright (c) {{YEAR}} {{AUTHOR}}{{EMAIL_LINE}}
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-1. Redistributions of source code must retain the above copyright notice,
-   this list of conditions and the following disclaimer.
-2. Redistributions in binary form must reproduce the above copyright notice,
-   this list of conditions and the following disclaimer in the documentation
-   and/or other materials provided with the distribution.
-3. Neither the name of the copyright holder nor the names of its contributors
-   may be used to endorse or promote products derived from this software
-   without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
diff --git a/packages/create-gen-app/create-gen-app-test/GPL-3.0.txt b/packages/create-gen-app/create-gen-app-test/GPL-3.0.txt
deleted file mode 100644
index 5341495..0000000
--- a/packages/create-gen-app/create-gen-app-test/GPL-3.0.txt
+++ /dev/null
@@ -1,18 +0,0 @@
-GNU GENERAL PUBLIC LICENSE
-Version 3, 29 June 2007
-
-Copyright (c) {{YEAR}} {{AUTHOR}}{{EMAIL_LINE}}
-
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License
-along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
diff --git a/packages/create-gen-app/create-gen-app-test/ISC.txt b/packages/create-gen-app/create-gen-app-test/ISC.txt
deleted file mode 100644
index 9daa3b5..0000000
--- a/packages/create-gen-app/create-gen-app-test/ISC.txt
+++ /dev/null
@@ -1,16 +0,0 @@
-ISC License
-
-Copyright (c) {{YEAR}} {{AUTHOR}}{{EMAIL_LINE}}
-
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted, provided that the above
-copyright notice and this permission notice appear in all copies.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
-WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
-ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
-WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
-OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
-CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-
diff --git a/packages/create-gen-app/create-gen-app-test/LICENSE b/packages/create-gen-app/create-gen-app-test/LICENSE
deleted file mode 100644
index 8969999..0000000
--- a/packages/create-gen-app/create-gen-app-test/LICENSE
+++ /dev/null
@@ -1,21 +0,0 @@
-The MIT License (MIT)
-
-Copyright (c) 2025 Interweb, Inc. <developers@interweb.co>
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
diff --git a/packages/create-gen-app/create-gen-app-test/MIT.txt b/packages/create-gen-app/create-gen-app-test/MIT.txt
deleted file mode 100644
index d113b91..0000000
--- a/packages/create-gen-app/create-gen-app-test/MIT.txt
+++ /dev/null
@@ -1,22 +0,0 @@
-The MIT License (MIT)
-
-Copyright (c) {{YEAR}} {{AUTHOR}}{{EMAIL_LINE}}
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
diff --git a/packages/create-gen-app/create-gen-app-test/MPL-2.0.txt b/packages/create-gen-app/create-gen-app-test/MPL-2.0.txt
deleted file mode 100644
index c785b35..0000000
--- a/packages/create-gen-app/create-gen-app-test/MPL-2.0.txt
+++ /dev/null
@@ -1,8 +0,0 @@
-Mozilla Public License Version 2.0
-
-Copyright (c) {{YEAR}} {{AUTHOR}}{{EMAIL_LINE}}
-
-This Source Code Form is subject to the terms of the Mozilla Public
-License, v. 2.0. If a copy of the MPL was not distributed with this
-file, You can obtain one at https://mozilla.org/MPL/2.0/.
-
diff --git a/packages/create-gen-app/create-gen-app-test/README.md b/packages/create-gen-app/create-gen-app-test/README.md
deleted file mode 100644
index 751e06f..0000000
--- a/packages/create-gen-app/create-gen-app-test/README.md
+++ /dev/null
@@ -1,143 +0,0 @@
-# create-gen-app
-
-<p align="center" width="100%">
-    <img height="90" src="https://raw.githubusercontent.com/hyperweb-io/dev-utils/refs/heads/main/docs/img/inquirerer.svg" />
-</p>
-
-<p align="center" width="100%">
-
-  <a href="https://github.com/hyperweb-io/dev-utils/actions/workflows/ci.yml">
-    <img height="20" src="https://github.com/hyperweb-io/dev-utils/actions/workflows/ci.yml/badge.svg" />
-  </a>
-  <a href="https://github.com/hyperweb-io/dev-utils/blob/main/LICENSE">
-    <img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/>
-  </a>
-  <a href="https://www.npmjs.com/package/create-gen-app"><img height="20" src="https://img.shields.io/npm/dt/create-gen-app"></a>
-  <a href="https://www.npmjs.com/package/create-gen-app"><img height="20" src="https://img.shields.io/github/package-json/v/hyperweb-io/dev-utils?filename=packages%2Fcreate-gen-app%2Fpackage.json"></a>
-</p>
-
-A TypeScript-first library for cloning template repositories, asking the user for variables, and generating a new project with sensible defaults.
-
-## Features
-
-- Clone any Git repo (or GitHub `org/repo` shorthand) and optionally select a branch + subdirectory
-- Extract template variables from filenames and file contents using the safer `____variable____` convention
-- Merge auto-discovered variables with `.questions.{json,js}` (questions win, including `ignore` patterns)
-- Interactive prompts powered by `inquirerer`, with flexible override mapping (`argv` support) and non-TTY mode for CI
-- License scaffolding: choose from MIT, Apache-2.0, ISC, GPL-3.0, BSD-3-Clause, Unlicense, or MPL-2.0 and generate a populated `LICENSE`
-- Built-in template caching powered by `appstash`, so repeat runs skip `git clone` (configurable via `cache` options)
-
-## Installation
-
-```bash
-npm install create-gen-app
-```
-
-> **Note:** The published package is API-only. An internal CLI harness used for integration testing now lives in `packages/create-gen-app-test/`.
-
-## Library Usage
-
-```typescript
-import * as os from "os";
-import * as path from "path";
-
-import { createGen } from "create-gen-app";
-
-await createGen({
-  templateUrl: "https://github.com/user/template-repo",
-  fromBranch: "main",
-  fromPath: "templates/module",
-  outputDir: "./my-new-project",
-  argv: {
-    USERFULLNAME: "Jane Dev",
-    USEREMAIL: "jane@example.com",
-    MODULENAME: "awesome-module",
-    LICENSE: "MIT",
-  },
-  noTty: true,
-  cache: {
-    // optional: override tool/baseDir (defaults to pgpm + ~/.pgpm)
-    toolName: "pgpm",
-    baseDir: path.join(os.tmpdir(), "create-gen-cache"),
-  },
-});
-```
-
-### Template Caching
-
-`create-gen-app` caches repositories under `~/.pgpm/cache/repos/<hash>` by default (using [`appstash`](https://github.com/hyperweb-io/dev-utils/tree/main/packages/appstash)). The first run clones & stores the repo, subsequent runs re-use the cached directory.
-
-- Disable caching with `cache: false` or `cache: { enabled: false }`
-- Override the tool name or base directory with `cache: { toolName, baseDir }`
-- For tests/CI, point `baseDir` to a temporary folder so the suite does not touch the developer’s real home directory:
-
-```ts
-const tempBase = fs.mkdtempSync(path.join(os.tmpdir(), "create-gen-cache-"));
-
-await createGen({
-  ...options,
-  cache: { baseDir: tempBase, toolName: "pgpm-test-suite" },
-});
-```
-
-The cache directory never mutates the template, so reusing the same cached repo across many runs is safe.
-
-### Template Variables
-
-Variables should be wrapped in four underscores on each side:
-
-```
-____projectName____/
-  src/____moduleName____.ts
-```
-
-```typescript
-// ____moduleName____.ts
-export const projectName = "____projectName____";
-export const author = "____fullName____";
-```
-
-### Custom Questions & Ignore Rules
-
-Create a `.questions.json`:
-
-```json
-{
-  "ignore": ["__tests__", "docs/drafts"],
-  "questions": [
-    {
-      "name": "____fullName____",
-      "type": "text",
-      "message": "Enter author full name",
-      "required": true
-    },
-    {
-      "name": "____license____",
-      "type": "list",
-      "message": "Choose a license",
-      "options": ["MIT", "Apache-2.0", "ISC", "GPL-3.0"]
-    }
-  ]
-}
-```
-
-Or `.questions.js` for dynamic logic. Question names can use `____var____` or plain `VAR`; they'll be normalized automatically.
-
-### License Templates
-
-`create-gen-app` ships text templates in `licenses-templates/`. To add another license, drop a `.txt` file matching the desired key (e.g., `BSD-2-CLAUSE.txt`) with placeholders:
-
-- `{{YEAR}}`, `{{AUTHOR}}`, `{{EMAIL_LINE}}`
-
-No code changes are needed; the generator discovers templates at runtime and will warn if a `.questions` option doesn’t have a matching template.
-
-## API Overview
-
-- `createGen(options)` – full pipeline (clone → extract → prompt → replace)
-- `cloneRepo(url, { branch })` – clone to a temp dir
-- `normalizeCacheOptions(cache)` / `prepareTemplateDirectory(...)` – inspect or reuse cached template repos
-- `extractVariables(dir)` – parse file/folder names + content for variables, load `.questions`
-- `promptUser(extracted, argv, noTty)` – run interactive questions with override alias deduping
-- `replaceVariables(templateDir, outputDir, extracted, answers)` – copy files, rename paths, render licenses
-
-See `packages/create-gen-app-test/dev/README.md` for the local development helper script (`pnpm --filter create-gen-app-test dev`).
diff --git a/packages/create-gen-app/create-gen-app-test/UNLICENSE.txt b/packages/create-gen-app/create-gen-app-test/UNLICENSE.txt
deleted file mode 100644
index 157f6bf..0000000
--- a/packages/create-gen-app/create-gen-app-test/UNLICENSE.txt
+++ /dev/null
@@ -1,22 +0,0 @@
-This is free and unencumbered software released into the public domain.
-
-Anyone is free to copy, modify, publish, use, compile, sell, or
-distribute this software, either in source code form or as a compiled
-binary, for any purpose, commercial or non-commercial, and by any means.
-
-In jurisdictions that recognize copyright laws, the author or authors
-of this software dedicate any and all copyright interest in the
-software to the public domain. We make this dedication for the benefit
-of the public at large and to the detriment of our heirs and
-successors. We intend this dedication to be an overt act of
-relinquishment in perpetuity of all present and future rights to this
-software under copyright law.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
-OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-OTHER DEALINGS IN THE SOFTWARE.
-
diff --git a/packages/create-gen-app/create-gen-app-test/package.json b/packages/create-gen-app/create-gen-app-test/package.json
deleted file mode 100644
index 6ef5aa6..0000000
--- a/packages/create-gen-app/create-gen-app-test/package.json
+++ /dev/null
@@ -1,39 +0,0 @@
-{
-  "name": "create-gen-app",
-  "version": "0.1.7",
-  "author": "Dan Lynch <pyramation@gmail.com>",
-  "description": "Clone and customize template repositories with variable replacement",
-  "main": "index.js",
-  "module": "esm/index.js",
-  "types": "index.d.ts",
-  "homepage": "https://github.com/hyperweb-io/dev-utils",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public",
-    "directory": "dist"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/hyperweb-io/dev-utils"
-  },
-  "bugs": {
-    "url": "https://github.com/hyperweb-io/dev-utils/issues"
-  },
-  "scripts": {
-    "copy": "copyfiles -f ../../LICENSE README.md package.json \"licenses-templates/**/*\" dist",
-    "clean": "makage clean",
-    "prepublishOnly": "npm run build",
-    "build": "npm run clean && tsc && tsc -p tsconfig.esm.json && npm run copy",
-    "test": "jest",
-    "test:watch": "jest --watch"
-  },
-  "dependencies": {
-    "appstash": "workspace:*",
-    "inquirerer": "workspace:*"
-  },
-  "devDependencies": {
-    "copyfiles": "^2.4.1",
-    "makage": "0.1.5"
-  },
-  "keywords": []
-}
\ No newline at end of file
diff --git a/packages/create-gen-app/src/cache.ts b/packages/create-gen-app/src/cache.ts
deleted file mode 100644
index 81c803b..0000000
--- a/packages/create-gen-app/src/cache.ts
+++ /dev/null
@@ -1,62 +0,0 @@
-import * as fs from "fs";
-
-import { CacheOptions } from "./types";
-import { cloneRepo } from "./clone";
-import { TemplateCache } from "./template-cache";
-
-export interface TemplateSource {
-  templateDir: string;
-  cacheUsed: boolean;
-  cleanup: () => void;
-}
-
-interface PrepareTemplateArgs {
-  templateUrl: string;
-  branch?: string;
-  cache: CacheOptions | false;
-}
-
-export async function prepareTemplateDirectory(args: PrepareTemplateArgs): Promise<TemplateSource> {
-  const { templateUrl, branch, cache } = args;
-
-  const templateCache = new TemplateCache(cache);
-
-  if (!templateCache.isEnabled()) {
-    const tempDir = await cloneRepo(templateUrl, { branch });
-    return {
-      templateDir: tempDir,
-      cacheUsed: false,
-      cleanup: () => cleanupDir(tempDir),
-    };
-  }
-
-  // Try to get from cache
-  const cachedPath = templateCache.get(templateUrl, branch);
-  if (cachedPath) {
-    return {
-      templateDir: cachedPath,
-      cacheUsed: true,
-      cleanup: () => {},
-    };
-  }
-
-  // Cache miss or expired - clone and cache
-  const cachePath = templateCache.set(templateUrl, branch);
-
-  return {
-    templateDir: cachePath,
-    cacheUsed: false,
-    cleanup: () => {},
-  };
-}
-
-function cleanupDir(dir: string): void {
-  if (fs.existsSync(dir)) {
-    fs.rmSync(dir, { recursive: true, force: true });
-  }
-}
-
-// Re-export TemplateCache for external use
-export { TemplateCache } from "./template-cache";
-
-
diff --git a/packages/create-gen-app/src/cache/cache-manager.ts b/packages/create-gen-app/src/cache/cache-manager.ts
new file mode 100644
index 0000000..7b20390
--- /dev/null
+++ b/packages/create-gen-app/src/cache/cache-manager.ts
@@ -0,0 +1,238 @@
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { appstash, resolve as resolveAppstash, AppStashResult } from 'appstash';
+import { CacheManagerConfig, CacheMetadata, CacheEntryInfo } from './types';
+
+export class CacheManager {
+  private config: CacheManagerConfig;
+  private dirs: AppStashResult;
+  private reposDir: string;
+  private metadataDir: string;
+
+  constructor(config: CacheManagerConfig) {
+    // Validate required toolName
+    if (!config.toolName) {
+      throw new Error('CacheManager requires toolName parameter');
+    }
+
+    this.config = {
+      toolName: config.toolName,
+      baseDir: config.baseDir,
+      ttl: config.ttl,
+      dirs: config.dirs,
+    };
+
+    this.dirs =
+      config.dirs ??
+      appstash(this.config.toolName, {
+        ensure: true,
+        baseDir: this.config.baseDir,
+      });
+
+    this.reposDir = resolveAppstash(this.dirs, 'cache', 'repos');
+    this.metadataDir = resolveAppstash(this.dirs, 'cache', 'metadata');
+
+    this.ensureDirectories();
+  }
+
+  /**
+   * Public accessor for the repos cache directory path.
+   */
+  getReposDir(): string {
+    return this.reposDir;
+  }
+
+  /**
+   * Public accessor for the metadata cache directory path.
+   */
+  getMetadataDir(): string {
+    return this.metadataDir;
+  }
+
+  /**
+   * Public accessor for resolved appstash directories.
+   */
+  getAppstashDirs(): AppStashResult {
+    return this.dirs;
+  }
+
+  /**
+   * Get cached directory path if exists and not expired
+   * Returns null if not cached or expired
+   */
+  get(key: string): string | null {
+    const cachePath = this.getCachePath(key);
+
+    if (!fs.existsSync(cachePath)) {
+      return null;
+    }
+
+    // Check expiration - if expired, return null
+    const expired = this.checkExpiration(key);
+    if (expired) {
+      return null;
+    }
+
+    return cachePath;
+  }
+
+  /**
+   * Store directory in cache with metadata
+   * Does NOT perform cloning - just registers the directory
+   */
+  set(key: string, sourcePath: string): string {
+    const cachePath = this.getCachePath(key);
+
+    // Write metadata with current timestamp
+    const metadata: CacheMetadata = {
+      key,
+      identifier: sourcePath,
+      lastUpdated: Date.now(),
+    };
+
+    fs.writeFileSync(
+      this.getMetadataPath(key),
+      JSON.stringify(metadata, null, 2)
+    );
+
+    return cachePath;
+  }
+
+  /**
+   * Check if cache entry is expired based on TTL
+   * Returns null if no metadata or not expired, returns metadata if expired
+   */
+  checkExpiration(key: string): CacheMetadata | null {
+    const metadata = this.getMetadata(key);
+
+    if (!metadata) {
+      return null;
+    }
+
+    if (this.isExpired(metadata)) {
+      return metadata;
+    }
+
+    return null;
+  }
+
+  /**
+   * Clear specific cache entry
+   */
+  clear(key: string): void {
+    const cachePath = this.getCachePath(key);
+    const metadataPath = this.getMetadataPath(key);
+
+    if (fs.existsSync(cachePath)) {
+      fs.rmSync(cachePath, { recursive: true, force: true });
+    }
+
+    if (fs.existsSync(metadataPath)) {
+      fs.rmSync(metadataPath, { force: true });
+    }
+  }
+
+  /**
+   * Clear all cache entries
+   */
+  clearAll(): void {
+    if (fs.existsSync(this.reposDir)) {
+      fs.rmSync(this.reposDir, { recursive: true, force: true });
+      fs.mkdirSync(this.reposDir, { recursive: true });
+    }
+
+    if (fs.existsSync(this.metadataDir)) {
+      fs.rmSync(this.metadataDir, { recursive: true, force: true });
+      fs.mkdirSync(this.metadataDir, { recursive: true });
+    }
+  }
+
+  /**
+   * List all cache entries with expiration status
+   */
+  listAll(): CacheEntryInfo[] {
+    if (!fs.existsSync(this.metadataDir)) {
+      return [];
+    }
+
+    const results: CacheEntryInfo[] = [];
+    const files = fs.readdirSync(this.metadataDir);
+
+    for (const file of files) {
+      if (!file.endsWith('.json')) {
+        continue;
+      }
+
+      const metadataPath = path.join(this.metadataDir, file);
+      try {
+        const metadata = JSON.parse(
+          fs.readFileSync(metadataPath, 'utf-8')
+        ) as CacheMetadata;
+
+        results.push({
+          ...metadata,
+          path: this.getCachePath(metadata.key),
+          expired: this.isExpired(metadata),
+        });
+      } catch {
+        // Skip corrupted metadata
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Get metadata for a cache entry
+   */
+  getMetadata(key: string): CacheMetadata | null {
+    const metadataPath = this.getMetadataPath(key);
+
+    if (!fs.existsSync(metadataPath)) {
+      return null;
+    }
+
+    try {
+      return JSON.parse(
+        fs.readFileSync(metadataPath, 'utf-8')
+      ) as CacheMetadata;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Create a cache key from identifier (e.g., git URL + branch)
+   */
+  createKey(identifier: string, variant?: string): string {
+    const input = variant ? `${identifier}#${variant}` : identifier;
+    return crypto.createHash('md5').update(input).digest('hex');
+  }
+
+  private ensureDirectories(): void {
+    if (!fs.existsSync(this.reposDir)) {
+      fs.mkdirSync(this.reposDir, { recursive: true });
+    }
+    if (!fs.existsSync(this.metadataDir)) {
+      fs.mkdirSync(this.metadataDir, { recursive: true });
+    }
+  }
+
+  private isExpired(metadata: CacheMetadata): boolean {
+    if (!this.config.ttl) {
+      return false;
+    }
+
+    const age = Date.now() - metadata.lastUpdated;
+    return age > this.config.ttl;
+  }
+
+  private getCachePath(key: string): string {
+    return path.join(this.reposDir, key);
+  }
+
+  private getMetadataPath(key: string): string {
+    return path.join(this.metadataDir, `${key}.json`);
+  }
+}
diff --git a/packages/create-gen-app/src/cache/types.ts b/packages/create-gen-app/src/cache/types.ts
new file mode 100644
index 0000000..a475fb8
--- /dev/null
+++ b/packages/create-gen-app/src/cache/types.ts
@@ -0,0 +1,25 @@
+import { AppStashResult } from 'appstash';
+
+export interface CacheManagerConfig {
+  toolName: string;
+  baseDir?: string;
+  ttl?: number;
+  /**
+   * Optional pre-resolved appstash directories owned by the caller.
+   * When provided, CacheManager will use these instead of creating its own.
+   */
+  dirs?: AppStashResult;
+}
+
+export interface CacheMetadata {
+  key: string;
+  identifier: string;
+  variant?: string;
+  lastUpdated: number;
+  source?: string;
+}
+
+export interface CacheEntryInfo extends CacheMetadata {
+  path: string;
+  expired: boolean;
+}
diff --git a/packages/create-gen-app/src/clone.ts b/packages/create-gen-app/src/clone.ts
deleted file mode 100644
index 5d48ad4..0000000
--- a/packages/create-gen-app/src/clone.ts
+++ /dev/null
@@ -1,65 +0,0 @@
-import { execSync } from "child_process";
-import * as fs from "fs";
-import * as os from "os";
-import * as path from "path";
-
-export interface CloneOptions {
-  branch?: string;
-}
-
-/**
- * Clone a repository to a temporary directory
- * @param url - Repository URL (GitHub or any git URL)
- * @returns Path to the cloned repository
- */
-export async function cloneRepo(
-  url: string,
-  options: CloneOptions = {}
-): Promise<string> {
-  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "create-gen-"));
-  const { branch } = options;
-
-  try {
-    const gitUrl = normalizeGitUrl(url);
-    const branchArgs = branch ? ` --branch ${branch} --single-branch` : "";
-    const depthArgs = " --depth 1"; // use shallow clone for speed; remove if future features need full history
-
-    execSync(`git clone${branchArgs}${depthArgs} ${gitUrl} ${tempDir}`, {
-      stdio: "inherit",
-    });
-
-    const gitDir = path.join(tempDir, ".git");
-    if (fs.existsSync(gitDir)) {
-      fs.rmSync(gitDir, { recursive: true, force: true });
-    }
-
-    return tempDir;
-  } catch (error) {
-    if (fs.existsSync(tempDir)) {
-      fs.rmSync(tempDir, { recursive: true, force: true });
-    }
-    const errorMessage = error instanceof Error ? error.message : String(error);
-    throw new Error(`Failed to clone repository: ${errorMessage}`);
-  }
-}
-
-/**
- * Normalize a URL to a git-cloneable format
- * @param url - Input URL
- * @returns Normalized git URL
- */
-export function normalizeGitUrl(url: string): string {
-  if (
-    url.startsWith("git@") ||
-    url.startsWith("https://") ||
-    url.startsWith("http://")
-  ) {
-    return url;
-  }
-
-  if (/^[\w-]+\/[\w-]+$/.test(url)) {
-    return `https://github.com/${url}.git`;
-  }
-
-  return url;
-}
diff --git a/packages/create-gen-app/src/git/git-cloner.ts b/packages/create-gen-app/src/git/git-cloner.ts
new file mode 100644
index 0000000..de38cb1
--- /dev/null
+++ b/packages/create-gen-app/src/git/git-cloner.ts
@@ -0,0 +1,119 @@
+import { execSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { GitCloneOptions, GitCloneResult } from './types';
+
+export class GitCloner {
+  /**
+   * Clone a git repository to a destination
+   * @param url - Repository URL (will be normalized)
+   * @param destination - Target directory path
+   * @param options - Clone options (branch, depth)
+   * @returns Clone result with normalized URL and destination
+   */
+  clone(
+    url: string,
+    destination: string,
+    options?: GitCloneOptions
+  ): GitCloneResult {
+    const normalizedUrl = this.normalizeUrl(url);
+
+    // Clean destination if exists
+    if (fs.existsSync(destination)) {
+      fs.rmSync(destination, { recursive: true, force: true });
+    }
+
+    this.executeClone(normalizedUrl, destination, options);
+    this.removeGitDir(destination);
+
+    return {
+      destination,
+      normalizedUrl,
+      branch: options?.branch,
+    };
+  }
+
+  /**
+   * Clone to a temporary directory
+   * @param url - Repository URL
+   * @param options - Clone options
+   * @returns Clone result with temp directory path
+   */
+  cloneToTemp(url: string, options?: GitCloneOptions): GitCloneResult {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'create-gen-'));
+    return this.clone(url, tempDir, options);
+  }
+
+  /**
+   * Normalize a URL to git-cloneable format
+   * Handles: org/repo -> https://github.com/org/repo.git
+   */
+  normalizeUrl(url: string): string {
+    // Already a full URL
+    if (
+      url.startsWith('git@') ||
+      url.startsWith('https://') ||
+      url.startsWith('http://')
+    ) {
+      return url;
+    }
+
+    // org/repo shorthand
+    if (/^[\w-]+\/[\w-]+$/.test(url)) {
+      return `https://github.com/${url}.git`;
+    }
+
+    return url;
+  }
+
+  /**
+   * Validate git URL format
+   */
+  validateUrl(url: string): boolean {
+    const normalized = this.normalizeUrl(url);
+    return (
+      normalized.startsWith('git@') ||
+      normalized.startsWith('https://') ||
+      normalized.startsWith('http://')
+    );
+  }
+
+  /**
+   * Remove .git directory from cloned repo
+   */
+  removeGitDir(directory: string): void {
+    const gitDir = path.join(directory, '.git');
+    if (fs.existsSync(gitDir)) {
+      fs.rmSync(gitDir, { recursive: true, force: true });
+    }
+  }
+
+  private executeClone(
+    url: string,
+    destination: string,
+    options?: GitCloneOptions
+  ): void {
+    const branch = options?.branch;
+    const depth = options?.depth ?? 1;
+    const singleBranch = options?.singleBranch ?? true;
+
+    const branchArgs = branch ? ` --branch ${branch}` : '';
+    const singleBranchArgs = singleBranch ? ' --single-branch' : '';
+    const depthArgs = ` --depth ${depth}`;
+
+    const command = `git clone${branchArgs}${singleBranchArgs}${depthArgs} ${url} ${destination}`;
+
+    try {
+      execSync(command, { stdio: 'inherit' });
+    } catch (error) {
+      // Clean up on failure
+      if (fs.existsSync(destination)) {
+        fs.rmSync(destination, { recursive: true, force: true });
+      }
+
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to clone repository: ${errorMessage}`);
+    }
+  }
+}
diff --git a/packages/create-gen-app/src/git/types.ts b/packages/create-gen-app/src/git/types.ts
new file mode 100644
index 0000000..8a4ebda
--- /dev/null
+++ b/packages/create-gen-app/src/git/types.ts
@@ -0,0 +1,17 @@
+export interface GitCloneOptions {
+  branch?: string;
+  depth?: number;
+  singleBranch?: boolean;
+}
+
+export interface GitCloneResult {
+  destination: string;
+  normalizedUrl: string;
+  branch?: string;
+}
+
+export interface GitUrlValidation {
+  isValid: boolean;
+  normalized?: string;
+  error?: string;
+}
diff --git a/packages/create-gen-app/src/index.ts b/packages/create-gen-app/src/index.ts
index cd39f0d..dd9ff9d 100644
--- a/packages/create-gen-app/src/index.ts
+++ b/packages/create-gen-app/src/index.ts
@@ -1,85 +1,45 @@
 import * as fs from "fs";
 import * as path from "path";
 
-import { prepareTemplateDirectory, TemplateCache } from "./cache";
-import { extractVariables } from "./extract";
-import { promptUser } from "./prompt";
-import { replaceVariables } from "./replace";
+import { extractVariables } from "./template/extract";
+import { promptUser } from "./template/prompt";
+import { replaceVariables } from "./template/replace";
 import { CreateGenOptions } from "./types";
 
-export * from "./cache";
-export * from "./clone";
-export * from "./extract";
-export * from "./prompt";
-export * from "./replace";
+// Export new modular classes
+export * from "./cache/cache-manager";
+export * from "./cache/types";
+export * from "./git/git-cloner";
+export * from "./git/types";
+export * from "./template/templatizer";
+export * from "./template/types";
+export * from "./utils/npm-version-check";
+export * from "./utils/types";
+
+// Export template processing functions
+export * from "./template/extract";
+export * from "./template/prompt";
+export * from "./template/replace";
+
+// Export shared types
 export * from "./types";
-export * from "./template-cache";
+
+// DEPRECATED: Legacy exports for backward compatibility (will be removed in future)
+// Use CacheManager, GitCloner, and Templatizer classes instead
+export { extractVariables, promptUser, replaceVariables };
 
 /**
+ * @deprecated This function is deprecated and will be removed in the next major version.
+ * Use the modular approach with CacheManager, GitCloner, and Templatizer classes instead.
+ * See create-gen-app-test package for an example of the new orchestration pattern.
+ *
  * Create a new project from a template repository
  * @param options - Options for creating the project
  * @returns Path to the generated project
  */
 export async function createGen(options: CreateGenOptions): Promise<string> {
-  const {
-    templateUrl,
-    outputDir,
-    argv = {},
-    noTty = false,
-    fromBranch,
-    fromPath,
-    cache,
-  } = options;
-
-  console.log(`Preparing template from ${templateUrl}...`);
-  const templateSource = await prepareTemplateDirectory({
-    templateUrl,
-    branch: fromBranch,
-    cache,
-  });
-
-  const cacheEnabled = cache !== false && (cache?.enabled !== false);
-  if (cacheEnabled) {
-    console.log(
-      templateSource.cacheUsed
-        ? "Using cached repository"
-        : "Caching repository for future runs..."
-    );
-  } else {
-    console.log("Cloning repository without cache...");
-  }
-
-  const normalizedPath = fromPath ? path.normalize(fromPath) : ".";
-  const templateRoot =
-    normalizedPath && normalizedPath !== "."
-      ? path.join(templateSource.templateDir, normalizedPath)
-      : templateSource.templateDir;
-
-  try {
-    if (!fs.existsSync(templateRoot)) {
-      throw new Error(
-        `Template path "${fromPath}" does not exist in repository ${templateUrl}.`
-      );
-    }
-    console.log("Extracting template variables...");
-    const extractedVariables = await extractVariables(templateRoot);
-
-    console.log(`Found ${extractedVariables.fileReplacers.length} file replacers`);
-    console.log(`Found ${extractedVariables.contentReplacers.length} content replacers`);
-    if (extractedVariables.projectQuestions) {
-      console.log(`Found ${extractedVariables.projectQuestions.questions.length} project questions`);
-    }
-
-    console.log("Prompting for variable values...");
-    const answers = await promptUser(extractedVariables, argv, noTty);
-
-    console.log(`Generating project in ${outputDir}...`);
-    await replaceVariables(templateRoot, outputDir, extractedVariables, answers);
-
-    console.log("Project created successfully!");
-
-    return outputDir;
-  } finally {
-    templateSource.cleanup();
-  }
+  throw new Error(
+    'createGen() has been deprecated. Please use CacheManager, GitCloner, and Templatizer classes for modular template processing. ' +
+    'See create-gen-app-test package for the new orchestration pattern.'
+  );
 }
diff --git a/packages/create-gen-app/src/template-cache.ts b/packages/create-gen-app/src/template-cache.ts
deleted file mode 100644
index ce4bbde..0000000
--- a/packages/create-gen-app/src/template-cache.ts
+++ /dev/null
@@ -1,292 +0,0 @@
-import { execSync } from "child_process";
-import * as crypto from "crypto";
-import * as fs from "fs";
-import * as path from "path";
-
-import { appstash, resolve as resolveAppstash } from "appstash";
-
-import { CacheOptions } from "./types";
-import { normalizeGitUrl } from "./clone";
-
-const DEFAULT_TOOL = "pgpm";
-
-interface CacheMetadata {
-  templateUrl: string;
-  branch?: string;
-  timestamp: number;
-  gitUrl: string;
-}
-
-export interface TemplateCacheConfig {
-  enabled: boolean;
-  toolName: string;
-  baseDir?: string;
-  ttl?: number;
-}
-
-/**
- * Manages template repository caching with TTL support
- */
-export class TemplateCache {
-  private config: TemplateCacheConfig;
-  private reposDir: string;
-  private metadataDir: string;
-
-  constructor(options?: CacheOptions | false) {
-    this.config = this.normalizeConfig(options);
-
-    if (this.config.enabled) {
-      const dirs = appstash(this.config.toolName, {
-        ensure: true,
-        baseDir: this.config.baseDir,
-      });
-
-      this.reposDir = resolveAppstash(dirs, "cache", "repos");
-      this.metadataDir = resolveAppstash(dirs, "cache", "metadata");
-
-      if (!fs.existsSync(this.reposDir)) {
-        fs.mkdirSync(this.reposDir, { recursive: true });
-      }
-      if (!fs.existsSync(this.metadataDir)) {
-        fs.mkdirSync(this.metadataDir, { recursive: true });
-      }
-    } else {
-      this.reposDir = "";
-      this.metadataDir = "";
-    }
-  }
-
-  private normalizeConfig(options?: CacheOptions | false): TemplateCacheConfig {
-    if (options === false) {
-      return {
-        enabled: false,
-        toolName: DEFAULT_TOOL,
-      };
-    }
-
-    const { enabled, toolName, baseDir, ttl, maxAge } = options ?? {};
-
-    return {
-      enabled: enabled !== false,
-      toolName: toolName ?? DEFAULT_TOOL,
-      baseDir,
-      ttl: ttl ?? maxAge,
-    };
-  }
-
-  /**
-   * Get cached template if it exists and is not expired
-   */
-  get(templateUrl: string, branch?: string): string | null {
-    if (!this.config.enabled) {
-      return null;
-    }
-
-    const key = this.createCacheKey(templateUrl, branch);
-    const cachePath = path.join(this.reposDir, key);
-    const metadataPath = path.join(this.metadataDir, `${key}.json`);
-
-    if (!fs.existsSync(cachePath)) {
-      return null;
-    }
-
-    if (this.config.ttl && fs.existsSync(metadataPath)) {
-      try {
-        const metadata = JSON.parse(
-          fs.readFileSync(metadataPath, "utf-8")
-        ) as CacheMetadata;
-
-        if (this.isExpired(metadata)) {
-          this.clear(templateUrl, branch);
-          return null;
-        }
-      } catch (error) {
-        // If metadata is corrupted, treat as expired
-        this.clear(templateUrl, branch);
-        return null;
-      }
-    }
-
-    return cachePath;
-  }
-
-  /**
-   * Cache a template repository
-   */
-  set(templateUrl: string, branch?: string): string {
-    if (!this.config.enabled) {
-      throw new Error("Cache is disabled");
-    }
-
-    const key = this.createCacheKey(templateUrl, branch);
-    const cachePath = path.join(this.reposDir, key);
-    const metadataPath = path.join(this.metadataDir, `${key}.json`);
-
-    // Clone the repository
-    this.cloneInto(templateUrl, cachePath, branch);
-
-    // Write metadata
-    const metadata: CacheMetadata = {
-      templateUrl,
-      branch,
-      timestamp: Date.now(),
-      gitUrl: normalizeGitUrl(templateUrl),
-    };
-
-    fs.writeFileSync(metadataPath, JSON.stringify(metadata, null, 2));
-
-    return cachePath;
-  }
-
-  /**
-   * Clear a specific cached template
-   */
-  clear(templateUrl: string, branch?: string): void {
-    if (!this.config.enabled) {
-      return;
-    }
-
-    const key = this.createCacheKey(templateUrl, branch);
-    const cachePath = path.join(this.reposDir, key);
-    const metadataPath = path.join(this.metadataDir, `${key}.json`);
-
-    if (fs.existsSync(cachePath)) {
-      fs.rmSync(cachePath, { recursive: true, force: true });
-    }
-
-    if (fs.existsSync(metadataPath)) {
-      fs.rmSync(metadataPath, { force: true });
-    }
-  }
-
-  /**
-   * Clear all cached templates
-   */
-  clearAll(): void {
-    if (!this.config.enabled) {
-      return;
-    }
-
-    if (fs.existsSync(this.reposDir)) {
-      fs.rmSync(this.reposDir, { recursive: true, force: true });
-      fs.mkdirSync(this.reposDir, { recursive: true });
-    }
-
-    if (fs.existsSync(this.metadataDir)) {
-      fs.rmSync(this.metadataDir, { recursive: true, force: true });
-      fs.mkdirSync(this.metadataDir, { recursive: true });
-    }
-  }
-
-  /**
-   * Check if cache metadata is expired
-   */
-  isExpired(metadata: CacheMetadata): boolean {
-    if (!this.config.ttl) {
-      return false;
-    }
-
-    const age = Date.now() - metadata.timestamp;
-    return age > this.config.ttl;
-  }
-
-  /**
-   * Get cache metadata for a template
-   */
-  getMetadata(templateUrl: string, branch?: string): CacheMetadata | null {
-    if (!this.config.enabled) {
-      return null;
-    }
-
-    const key = this.createCacheKey(templateUrl, branch);
-    const metadataPath = path.join(this.metadataDir, `${key}.json`);
-
-    if (!fs.existsSync(metadataPath)) {
-      return null;
-    }
-
-    try {
-      return JSON.parse(fs.readFileSync(metadataPath, "utf-8")) as CacheMetadata;
-    } catch {
-      return null;
-    }
-  }
-
-  /**
-   * List all cached templates with their metadata
-   */
-  listAll(): Array<CacheMetadata & { key: string; expired: boolean }> {
-    if (!this.config.enabled) {
-      return [];
-    }
-
-    if (!fs.existsSync(this.metadataDir)) {
-      return [];
-    }
-
-    const results: Array<CacheMetadata & { key: string; expired: boolean }> = [];
-    const files = fs.readdirSync(this.metadataDir);
-
-    for (const file of files) {
-      if (!file.endsWith(".json")) {
-        continue;
-      }
-
-      const metadataPath = path.join(this.metadataDir, file);
-      try {
-        const metadata = JSON.parse(
-          fs.readFileSync(metadataPath, "utf-8")
-        ) as CacheMetadata;
-
-        results.push({
-          ...metadata,
-          key: path.basename(file, ".json"),
-          expired: this.isExpired(metadata),
-        });
-      } catch {
-        // Skip corrupted metadata
-      }
-    }
-
-    return results;
-  }
-
-  private createCacheKey(templateUrl: string, branch?: string): string {
-    const gitUrl = normalizeGitUrl(templateUrl);
-    return crypto
-      .createHash("md5")
-      .update(`${gitUrl}#${branch ?? "default"}`)
-      .digest("hex");
-  }
-
-  private cloneInto(
-    templateUrl: string,
-    destination: string,
-    branch?: string
-  ): void {
-    if (fs.existsSync(destination)) {
-      fs.rmSync(destination, { recursive: true, force: true });
-    }
-
-    const gitUrl = normalizeGitUrl(templateUrl);
-    const branchArgs = branch ? ` --branch ${branch} --single-branch` : "";
-    const depthArgs = " --depth 1";
-
-    execSync(`git clone${branchArgs}${depthArgs} ${gitUrl} ${destination}`, {
-      stdio: "inherit",
-    });
-
-    const gitDir = path.join(destination, ".git");
-    if (fs.existsSync(gitDir)) {
-      fs.rmSync(gitDir, { recursive: true, force: true });
-    }
-  }
-
-  isEnabled(): boolean {
-    return this.config.enabled;
-  }
-
-  getConfig(): TemplateCacheConfig {
-    return { ...this.config };
-  }
-}
diff --git a/packages/create-gen-app/src/extract.ts b/packages/create-gen-app/src/template/extract.ts
similarity index 99%
rename from packages/create-gen-app/src/extract.ts
rename to packages/create-gen-app/src/template/extract.ts
index 6ea2366..512248a 100644
--- a/packages/create-gen-app/src/extract.ts
+++ b/packages/create-gen-app/src/template/extract.ts
@@ -6,7 +6,7 @@ import {
   ExtractedVariables,
   FileReplacer,
   Questions,
-} from "./types";
+} from "../types";
 
 const PLACEHOLDER_BOUNDARY = "____";
 
diff --git a/packages/create-gen-app/src/prompt.ts b/packages/create-gen-app/src/template/prompt.ts
similarity index 99%
rename from packages/create-gen-app/src/prompt.ts
rename to packages/create-gen-app/src/template/prompt.ts
index c2c77ad..a9ee9f0 100644
--- a/packages/create-gen-app/src/prompt.ts
+++ b/packages/create-gen-app/src/template/prompt.ts
@@ -1,6 +1,6 @@
 import { Inquirerer, Question } from "inquirerer";
 
-import { ExtractedVariables } from "./types";
+import { ExtractedVariables } from "../types";
 
 const PLACEHOLDER_BOUNDARY = "____";
 
diff --git a/packages/create-gen-app/src/replace.ts b/packages/create-gen-app/src/template/replace.ts
similarity index 97%
rename from packages/create-gen-app/src/replace.ts
rename to packages/create-gen-app/src/template/replace.ts
index 994fa34..f00f2c6 100644
--- a/packages/create-gen-app/src/replace.ts
+++ b/packages/create-gen-app/src/template/replace.ts
@@ -3,8 +3,8 @@ import * as path from 'path';
 import { Transform } from 'stream';
 import { pipeline } from 'stream/promises';
 
-import { ExtractedVariables } from './types';
-import { renderLicense, isSupportedLicense } from './licenses';
+import { ExtractedVariables } from '../types';
+import { renderLicense, isSupportedLicense } from '../licenses';
 
 /**
  * Replace variables in all files in the template directory
@@ -162,7 +162,7 @@ async function replaceInFile(
   }
   
   const replaceTransform = new Transform({
-    transform(chunk: Buffer, encoding, callback) {
+    transform(chunk: Buffer, _encoding, callback) {
       let content = chunk.toString();
       
       for (const replacer of extractedVariables.contentReplacers) {
diff --git a/packages/create-gen-app/src/template/templatizer.ts b/packages/create-gen-app/src/template/templatizer.ts
new file mode 100644
index 0000000..dbdba72
--- /dev/null
+++ b/packages/create-gen-app/src/template/templatizer.ts
@@ -0,0 +1,102 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { ExtractedVariables } from '../types';
+import { extractVariables } from './extract';
+import { promptUser } from './prompt';
+import { replaceVariables } from './replace';
+import { ProcessOptions, TemplatizerResult } from './types';
+
+export class Templatizer {
+  constructor() {
+    // Pure template processor - no configuration needed
+  }
+
+  /**
+   * Process a local template directory (extract + prompt + replace)
+   * @param templateDir - Local directory path (MUST be local, NOT git URL)
+   * @param outputDir - Output directory for generated project
+   * @param options - Processing options (argv overrides, noTty)
+   * @returns Processing result
+   */
+  async process(
+    templateDir: string,
+    outputDir: string,
+    options?: ProcessOptions
+  ): Promise<TemplatizerResult> {
+    this.validateTemplateDir(templateDir);
+
+    // Handle subdirectory within template
+    const actualTemplateDir = options?.fromPath
+      ? path.join(templateDir, options.fromPath)
+      : templateDir;
+
+    this.validateTemplateDir(actualTemplateDir);
+
+    // Extract variables
+    const variables = await this.extract(actualTemplateDir);
+
+    // Prompt for values
+    const answers = await this.prompt(
+      variables,
+      options?.argv,
+      options?.noTty
+    );
+
+    // Replace variables
+    await this.replace(actualTemplateDir, outputDir, variables, answers);
+
+    return {
+      outputDir,
+      variables,
+      answers,
+    };
+  }
+
+  /**
+   * Extract variables from template directory
+   */
+  async extract(templateDir: string): Promise<ExtractedVariables> {
+    return extractVariables(templateDir);
+  }
+
+  /**
+   * Prompt user for variables
+   */
+  async prompt(
+    extracted: ExtractedVariables,
+    argv?: Record<string, any>,
+    noTty?: boolean
+  ): Promise<Record<string, any>> {
+    return promptUser(extracted, argv ?? {}, noTty ?? false);
+  }
+
+  /**
+   * Replace variables in template
+   */
+  async replace(
+    templateDir: string,
+    outputDir: string,
+    extracted: ExtractedVariables,
+    answers: Record<string, any>
+  ): Promise<void> {
+    return replaceVariables(templateDir, outputDir, extracted, answers);
+  }
+
+  /**
+   * Validate template directory exists and has content
+   */
+  validateTemplateDir(templateDir: string): void {
+    if (!fs.existsSync(templateDir)) {
+      throw new Error(`Template directory does not exist: ${templateDir}`);
+    }
+
+    if (!fs.statSync(templateDir).isDirectory()) {
+      throw new Error(`Template path is not a directory: ${templateDir}`);
+    }
+
+    const entries = fs.readdirSync(templateDir);
+    if (entries.length === 0) {
+      throw new Error(`Template directory is empty: ${templateDir}`);
+    }
+  }
+}
diff --git a/packages/create-gen-app/src/template/types.ts b/packages/create-gen-app/src/template/types.ts
new file mode 100644
index 0000000..5c4aa81
--- /dev/null
+++ b/packages/create-gen-app/src/template/types.ts
@@ -0,0 +1,13 @@
+import { ExtractedVariables } from '../types';
+
+export interface ProcessOptions {
+  argv?: Record<string, any>;
+  noTty?: boolean;
+  fromPath?: string;
+}
+
+export interface TemplatizerResult {
+  outputDir: string;
+  variables: ExtractedVariables;
+  answers: Record<string, any>;
+}
diff --git a/packages/create-gen-app/src/utils/npm-version-check.ts b/packages/create-gen-app/src/utils/npm-version-check.ts
new file mode 100644
index 0000000..06fec5e
--- /dev/null
+++ b/packages/create-gen-app/src/utils/npm-version-check.ts
@@ -0,0 +1,67 @@
+import { execSync } from 'child_process';
+import { VersionCheckResult } from './types';
+
+/**
+ * Check if current package version is outdated compared to npm registry
+ * @param packageName - Package name to check
+ * @param currentVersion - Current version string
+ * @returns Version comparison result
+ */
+export async function checkNpmVersion(
+  packageName: string,
+  currentVersion: string
+): Promise<VersionCheckResult> {
+  try {
+    const latestVersion = execSync(
+      `npm view ${packageName} version`,
+      { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] }
+    ).trim();
+
+    const isOutdated = compareVersions(currentVersion, latestVersion) < 0;
+
+    return {
+      currentVersion,
+      latestVersion,
+      isOutdated,
+    };
+  } catch (error) {
+    return {
+      currentVersion,
+      latestVersion: null,
+      isOutdated: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * Compare two semver version strings
+ * Returns: -1 if v1 < v2, 0 if equal, 1 if v1 > v2
+ */
+export function compareVersions(v1: string, v2: string): number {
+  const parts1 = v1.split('.').map(Number);
+  const parts2 = v2.split('.').map(Number);
+
+  for (let i = 0; i < Math.max(parts1.length, parts2.length); i++) {
+    const p1 = parts1[i] || 0;
+    const p2 = parts2[i] || 0;
+    if (p1 < p2) return -1;
+    if (p1 > p2) return 1;
+  }
+  return 0;
+}
+
+/**
+ * Print version warning to console if outdated
+ */
+export function warnIfOutdated(
+  packageName: string,
+  result: VersionCheckResult
+): void {
+  if (result.isOutdated && result.latestVersion) {
+    console.warn(
+      `\n⚠️  New version available: ${result.currentVersion} → ${result.latestVersion}`
+    );
+    console.warn(`   Run: npm install -g ${packageName}@latest\n`);
+  }
+}
diff --git a/packages/create-gen-app/src/utils/types.ts b/packages/create-gen-app/src/utils/types.ts
new file mode 100644
index 0000000..cf949f8
--- /dev/null
+++ b/packages/create-gen-app/src/utils/types.ts
@@ -0,0 +1,6 @@
+export interface VersionCheckResult {
+  currentVersion: string;
+  latestVersion: string | null;
+  isOutdated: boolean;
+  error?: string;
+}