@zaaxch/tailframe 3.0.0 → 4.0.0

package/src/new.mjs

@@ -66,15 +66,17 @@ if (!fs.existsSync(parent) || !fs.statSync(parent).isDirectory()) fail(`Parent d
 if (fs.existsSync(root) && fs.readdirSync(root).length) fail(`Refusing to overwrite non-empty directory: ${root}`);
 
 const title = options.name.split("-").map((part) => part[0].toUpperCase() + part.slice(1)).join(" ");
-const svc = `${options.name}-svc`;
-const ui = `${options.name}-ui`;
+const svc = "apps/service";
+const ui = "apps/ui";
+const servicePackage = `@${options.name}/service`;
+const uiPackage = `@${options.name}/ui`;
 const databaseName = options.name.replaceAll("-", "_");
 const postgres = options.db === "postgres";
 const mongoApplicationUser = `${options.name}-app`;
 const mongoBackupUser = `${options.name}-backup`;
 const files = {};
 const add = (relative, content) => { files[relative] = content.endsWith("\n") ? content : `${content}\n`; };
-// Generated repositories depend on the published toolkit rather than copying a validator, and they
+// Generated products depend on the published toolkit rather than copying a validator, and they
 // pin the exact contract version they were generated against.
 const contractVersion = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 const serviceProfiles = [
@@ -84,6 +86,11 @@ const serviceProfiles = [
 	...(options.worker ? ["worker"] : []),
 	...(options.ui ? ["ui-host"] : [])
 ];
+const uiProfiles = [...(options.auth === "firebase" ? ["firebase"] : []), "notifications"];
+const apps = [
+	{ kind: "service", path: svc, profiles: serviceProfiles },
+	...(options.ui ? [{ kind: "ui", path: ui, profiles: uiProfiles }] : [])
+];
 const prettierConfig = {
 	useTabs: true,
 	tabWidth: 4,
@@ -105,92 +112,102 @@ const gitAttributes = `* text=auto eol=lf
 
 add(".prettierrc.json", JSON.stringify(prettierConfig, null, "\t"));
 add(".gitattributes", gitAttributes);
+add("package.json", JSON.stringify({
+	name: options.name,
+	version: "0.1.0",
+	private: true,
+	packageManager: "pnpm@11.22.0",
+	scripts: {
+		dev: "pnpm -r --parallel --stream --if-present dev",
+		build: "pnpm -r --if-present build",
+		test: "pnpm -r --if-present test",
+		"type-check": "pnpm -r --if-present type-check",
+		"format:check": "pnpm -r --if-present format:check",
+		"validate:architecture": "tailframe validate .",
+		"sync:architecture": "tailframe sync --check ."
+	},
+	devDependencies: { "@zaaxch/tailframe": contractVersion }
+}, null, "\t"));
+add("pnpm-workspace.yaml", `packages:
+  - "apps/*"
+injectWorkspacePackages: true
+allowBuilds:
+  "@firebase/util": true
+  esbuild: true
+  protobufjs: true
+  unrs-resolver: true
+`);
+add("tailframe.json", configSource({ apps, contractVersion }));
 
 const repos = [[svc, "Express/TypeScript API and background runtime."]];
 if (options.ui) repos.push([ui, "Vue/Vite customer interface."]);
 
-add("AGENTS.md", `# ${title} repository guidance
+add("AGENTS.md", `# ${title} product guidance
 
 ## Sources of truth
 
 - Treat implementation and tests as the source of truth for current behavior.
-- Product documentation may establish intent but is not proof of implemented behavior.
-- Do not claim functionality works merely because a type, route, UI control, configuration key, placeholder, or planning entry exists.
+- Treat \`tailframe.json\` and the root pnpm workspace as the product architecture and dependency boundary.
+- Read the nearest application \`AGENTS.md\` before changing files under \`apps/\`.
 
 ## Product boundary
 
-The product domain is not yet defined. Do not invent domain entities, workflows, claims, roles, or integrations. Add product-specific guidance only after an explicit decision or implementation establishes it.
+The product domain is not yet defined. Do not invent domain entities, workflows, claims, roles, or integrations.
 
 ## Repository map
 
-This project root contains separate repositories. Do not assume that a convention from one repository applies to another.
+- \`apps/service/\`  Express/TypeScript API and background runtime.
+${options.ui ? "- \`apps/ui/\`  Vue/Vite customer interface.\n" : ""}- The product root owns Git history, the pnpm lockfile, Tailframe metadata, orchestration, CI, and deployment.
 
-${repos.map(([name, description]) => `- \`${name}/\` — ${description} Read \`${name}/AGENTS.md\` before editing it.`).join("\n")}
+## Cross-application changes
 
-## Cross-repository changes
-
-1. Read each applicable child \`AGENTS.md\`.
-2. Inspect the nearest working implementation in each repository.
-3. Keep shared contracts aligned across all affected clients and services.
-4. Validate each repository with its own scripts.
-5. Do not claim end-to-end behavior from changes or static checks in only one repository.
+1. Read the root and applicable application guidance.
+2. Keep shared wire contracts aligned across service and UI.
+3. Run focused checks while iterating and product-root checks before handoff.
+4. Do not claim end-to-end behavior from changes or static checks in only one application.
 
 ## Module workflow
 
-- Use the local \`new-module\` skill whenever creating or extending a domain module, public operation, persisted entity, or client capability module.
-- This applies when work affects one repository, multiple repositories, or one phase of a feature whose backend and clients will be implemented separately.
-- Do not wait for a task to become cross-repository before using the skill.
-- Create architecture files with \`tailframe generate\` in the affected repository; the skill orchestrates the work, the CLI creates the files.
+- Use the local \`new-module\` skill whenever creating or extending a domain module, public operation, persisted entity, or client capability.
+- Create architecture files with \`tailframe generate --app service|ui\` from the product root.
 
 ## Code-change guidelines
 
-- Keep changes small and focused and avoid unrelated refactoring.
-- Modify existing structures when they fit the requirement.
-- Preserve unrelated worktree changes.
-- Confirm every committed change belongs to the requested scope.
+- Keep changes focused and preserve unrelated worktree changes.
+- Do not create nested repositories or package-manager boundaries under \`apps/\`.
 
 ## GitHub workflow
 
 - Use \`gh\` for GitHub interactions when it supports the action.
-- Inspect existing issues and pull requests before proposing duplicates.
 - Never mutate GitHub state without explicit authorization.
-- Verify external mutations with a read-only follow-up.
 
 ## GitHub authentication and sandboxing
 
-- All \`gh\`, AWS/ECR, and Docker commands must run outside the sandbox. Request approval before the first attempt; do not try them inside the sandbox first.
-- Docker commands include \`docker\`, \`docker compose\`, \`docker exec\`, and package scripts whose purpose is to invoke Docker.
-- AWS/ECR commands include \`aws ecr\` authentication and package scripts that build or push ECR images.
-- Never print, log, commit, or include GitHub tokens in command output.
-- Keep mutation approvals separate from read-only GitHub access.
-
-## Starting work from a GitHub issue
-
-Resolve and read the issue and comments, load applicable guidance, inspect worktree state and related work, determine scope and validation, preserve unrelated changes, and use an isolated branch for implementation. Starting implementation does not authorize changing issue metadata. Report the issue, repositories, branch, scope, checks, preserved changes, and blockers.
+- All \`gh\`, AWS/ECR, and Docker commands must run outside the sandbox. Request approval before the first attempt.
+- Never print, log, commit, or include credentials or tokens in command output.
 `);
-
 add(".agents/skills/new-module/SKILL.md", `---
 name: new-module
-description: Create or extend a domain-colocated module in one repository or across the optional service and UI repositories using explicit use cases, separate trusted request context, module-owned repository ports and persistence adapters, HTTP validation, and focused tests. Use for backend capabilities, HTTP operations, persisted entities, queries, commands, jobs, workers, frontend capability modules, or phased work where a client is implemented later.
+description: Create or extend a domain-colocated module in the service and optional UI applications in one product repository using explicit use cases, separate trusted request context, module-owned repository ports and persistence adapters, HTTP validation, and focused tests. Use for backend capabilities, HTTP operations, persisted entities, queries, commands, jobs, workers, frontend capability modules, or phased work where a client is implemented later.
 ---
 
 # New module
 
 Use this workflow for any new domain capability or operation. Add only the layers earned by actual behavior.
 
-1. Identify the module, requested operations, entry points, and repositories in scope. Classify every intended file with the applicable AGENTS.md placement table before writing. Do not assume full CRUD.
+1. Identify the module, requested operations, entry points, and applications in scope. Classify every intended file with the applicable AGENTS.md placement table before writing. Do not assume full CRUD.
 2. Read the root and every applicable child \`AGENTS.md\`.
 3. Inspect the nearest working module and tests.
-4. Create architecture files only with the tailframe CLI: \`tailframe generate\` creates service modules, use cases, http files, ports, adapters, identifiers, integrations, UI modules, and the closed UI shell catalog on canonical paths with canonical names. Service module generation also registers the new use case and mounts or extends its single route factory through deterministic composition-file edits. Hand-creating architecture files or editing generated shell-catalog implementations is a conformance violation; inspect the generated diff and complete only the remaining behavior-specific checklist.
-5. Colocate product capability behavior under \`src/modules/<module>\` in both the service and UI. Never substitute \`features\` or global \`apis\`, \`views\`, \`services\`, \`stores\`, or \`types\` directories. UI \`app/stores\` is closed to generated \`auth.store.ts\`, \`notification.store.ts\`, and \`theme.store.ts\`; \`app/public\` is closed to generated \`ThemeToggle.vue\`. Never create \`src/modules/theme\`, \`src/modules/auth\`, or \`src/modules/notification\`. Product records, current-user domain records, selections, filters, and workflows stay in their owning module. Start backend modules with \`use-cases/\`, \`http/\`, and tests; add \`domain/\` or \`persistence/\` only when required. Add only the UI module directories earned by the capability.
+4. Create architecture files only with the tailframe CLI: \`tailframe generate --app <service|ui>\` creates canonical service and UI architecture files. Hand-creating architecture files or editing generated shell-catalog implementations is a conformance violation; inspect the generated diff and complete only the behavior-specific checklist.
+5. Colocate product capability behavior under \`src/modules/<module>\` in both the service and UI. Never substitute \`features\` or global \`apis\`, \`views\`, \`services\`, \`stores\`, or \`types\` directories. UI \`app/stores\` is closed to generated \`auth.store.ts\`, \`notification.store.ts\`, and \`theme.store.ts\`; \`app/public\` is closed to generated \`ThemeToggle.vue\`. Never create \`src/modules/theme\`, \`src/modules/auth\`, or \`src/modules/notification\`. Product records, current-user domain records, selections, filters, and workflows stay in their owning module; when the service exposes a user capability, its current-user record belongs to a UI \`user\` module. Start backend modules with \`use-cases/\`, \`http/\`, and tests; add \`domain/\` or \`persistence/\` only when required. Add only the UI module directories earned by the capability.
 6. Define use cases as \`execute(context, input)\`. Keep trusted \`RequestContext\` separate from client input.
 7. Put ownership, RBAC, entitlements, and domain policies in use-case or domain code, not client bodies or route metadata.
 8. Define repository contracts in the owning module and implement them in persistence adapters.
-9. For persisted capabilities, prefer branded, domain-owned string IDs at domain and repository-port boundaries; generate the module's identifier file with \`tailframe generate identifiers <module> <NameId...>\`. Keep MongoDB \`ObjectId\` conversion inside MongoDB persistence adapters, using persistence-only document types rather than \`any\` to bypass the boundary.
+9. For persisted capabilities, prefer branded, domain-owned string IDs at domain and repository-port boundaries; generate identifiers with \`tailframe generate --app service identifiers <module> <NameId...>\`. Keep MongoDB \`ObjectId\` conversion inside MongoDB persistence adapters.
 10. Let HTTP routes, jobs, workers, scheduled tasks, and CLIs invoke use cases directly; do not call one entry point from another.
 11. Keep operation names, payloads, authentication, response contracts, and client types synchronized. A service module may import another only through a named file directly under the provider's use-cases directory. A UI module may import another only through a named file directly under the provider's public directory. Both graphs must remain acyclic. UI modules may import only the generated auth/notification/theme app stores and \`ThemeToggle\` from app; every other app path is private.
 12. Verify generated container and route wiring, then add only dependency construction, client, navigation, worker, or process registration earned by real behavior. Route module views directly from \`app/router.ts\`. App views and shell components consume product modules only through named module \`public/\` entries; they never import module views or other internals.
-13. Run npm run validate:architecture in every affected repository, then run focused type checks and tests. Report repositories, operations, entry points, checks, placement decisions, and gaps.
+13. Run \`pnpm validate:architecture\` from the product root, then run focused type checks and tests. Report applications, operations, entry points, checks, placement decisions, and gaps.
 
 Do not create empty architectural layers, speculative operations, or mandatory controllers. Do not claim behavior from static files, weaken trusted context or persistence ownership, or change unrelated background behavior.
 `);
@@ -209,19 +226,18 @@ const svcDeps = {
 const svcDevDeps = {
 	"@types/cors": "^2.8.17", "@types/express": "^5.0.1", "@types/jest": "^30.0.0", "@types/node": "^22.13.14", "@types/supertest": "^7.2.1",
 	...(postgres ? { "@types/pg": "^8.15.5" } : {}),
-	"@zaaxch/tailframe": contractVersion,
 	jest: "^30.0.0", nodemon: "^3.1.9", prettier: "3.5.3", "ts-jest": "^29.4.11", "ts-node": "^10.9.2",
 	"tsc-alias": "^1.8.16", "tsconfig-paths": "^4.2.0", typescript: "^5.8.2", supertest: "^7.2.2"
 };
 add(`${svc}/package.json`, JSON.stringify({
-	name: svc, version: "0.1.0", private: true, main: "dist/server.js",
+	name: servicePackage, version: "0.1.0", private: true, main: "dist/server.js", files: ["dist"],
 	engines: { node: ">=22.13.0" },
 		scripts: {
 		dev: "nodemon --legacy-watch --exec ts-node -r tsconfig-paths/register src/server.ts",
 		...(options.worker ? { "dev:worker": "nodemon --legacy-watch --exec ts-node -r tsconfig-paths/register src/worker.ts" } : {}),
 		build: "tsc && tsc-alias", start: "node dist/server.js",
 		...(options.worker ? { worker: "node dist/worker.js" } : {}),
-		test: "npm run test:unit && npm run test:integration", "test:unit": "jest --selectProjects unit --runInBand", "test:integration": "jest --selectProjects integration --runInBand", "validate:architecture": "tailframe validate .", "sync:architecture": "tailframe sync --check .", format: "prettier --write src/", "format:check": "prettier --check src/",
+		test: "pnpm test:unit && pnpm test:integration", "test:unit": "jest --selectProjects unit --runInBand", "test:integration": "jest --selectProjects integration --runInBand", "validate:architecture": "tailframe validate ../.. --app service", "sync:architecture": "tailframe sync --check ../..", format: "prettier --write src/", "format:check": "prettier --check src/",
 		"schema:apply": "node dist/app/cli/applySchema.js", "schema:apply:dev": "ts-node -r tsconfig-paths/register src/app/cli/applySchema.ts",
 		"test:db:up": "docker compose -f docker-compose.test.yml up -d", "test:db:down": "docker compose -f docker-compose.test.yml down -v",
 		"docker:dev": "docker compose -f docker-compose.dev.yml up",
@@ -229,7 +245,6 @@ add(`${svc}/package.json`, JSON.stringify({
 		"docker:push": "bash scripts/build_and_push.sh"
 	}, dependencies: svcDeps, devDependencies: svcDevDeps
 }, null, "\t"));
-add(`${svc}/tailframe.json`, configSource({ kind: "service", profiles: serviceProfiles, contractVersion }));
 add(`${svc}/tsconfig.json`, JSON.stringify({
 	compilerOptions: { target: "ES2022", module: "commonjs", rootDir: "src", outDir: "dist", strict: true, esModuleInterop: true, experimentalDecorators: true, emitDecoratorMetadata: true, baseUrl: ".", paths: { "@/*": ["src/*"] }, skipLibCheck: true },
 	include: ["src/**/*.ts"]
@@ -249,7 +264,7 @@ const dbEnv = postgres
 	: "MONGODB_URI=mongodb://localhost:27017/?replicaSet=rs0&directConnection=true\nMONGODB_DB_NAME=" + databaseName;
 add(`${svc}/.env.example`, `NODE_ENV=development\nPORT=3000\nCORS_ORIGIN=https://localhost:5173\n${dbEnv}\n${options.auth === "firebase" ? "FIREBASE_PROJECT_ID=\n" : ""}${options.redis ? "REDIS_URL=redis://localhost:6379\n" : ""}`);
 add(`${svc}/.env.infrastructure.example`, `ECR_IMAGE=<account>.dkr.ecr.<region>.amazonaws.com/${options.name}
-IMAGE_TAG=<service-sha>${options.ui ? "_<ui-sha>" : ""}
+IMAGE_TAG=<product-sha>
 APP_ENV_FILE=/opt/${options.name}/shared/.env.production
 ${postgres ? `POSTGRES_DATA_DIR=/opt/${options.name}/shared/postgres/data
 POSTGRES_ROOT_PASSWORD=<uri-safe-random-value>
@@ -476,7 +491,7 @@ These conventions apply to \`${svc}\`. This service is a modular monolith organi
 | --- | --- |
 | Product rule, query, command, or policy | \`src/modules/<module>/use-cases\` or \`domain\` |
 | Repository port | Owning module's \`use-cases/ports\` |
-| MongoDB implementation | Owning module's \`persistence\` |
+| Database implementation | Owning module's \`persistence\` |
 | Express route or request schema | Owning module's \`http\` |
 | Vendor or external-system adapter | \`src/platform/integrations/<provider>\` |
 | Database, Redis, authentication, or HTTP mechanism | \`src/platform\` |
@@ -510,11 +525,13 @@ Product vocabulary stays in the module that owns its meaning; never move it into
 - Define repository contracts under the owning module's \`use-cases/ports\`.
 - Implement database-specific adapters under that module's \`persistence/\` directory.
 - For persisted capabilities, prefer branded, domain-owned string IDs in module types and repository ports. A technology-neutral \`Brand<Value, Tag>\` helper MAY be defined when a real module needs distinct ID types; do not create product entities or concrete ID types in the scaffold.
-- Repository ports and use cases MUST NOT expose database identifier types. Persistence adapters SHOULD define persistence-only document types and MUST NOT use \`any\` to bypass the domain/persistence distinction. MongoDB \`ObjectId\` conversion belongs inside the MongoDB persistence adapter.
+- Repository ports and use cases MUST NOT expose database identifier types. Persistence adapters SHOULD define persistence-only storage types and MUST NOT use \`any\` to bypass the domain/persistence distinction. Conversion between domain and database representations belongs inside the database persistence adapter.
 - Add appropriate schema or validation, indexes, initialization or migrations, and focused tests.
 
 ## Project-specific persistence
-This service uses MongoDB. Module-owned MongoDB adapters own collection access, persistence-only document types, and conversion of branded module string IDs to and from ObjectId inside the adapter, along with queries, projections, validators, and indexes. Do not use any to bypass the domain/persistence distinction.
+${postgres
+	? "This service uses PostgreSQL. Module-owned PostgreSQL adapters own table access, persistence-only row types, queries, projections, transactions, and conversion to domain types. Keep schema definitions and migrations with the owning module's persistence implementation, and never expose database types or use any to bypass repository ports."
+	: "This service uses MongoDB. Module-owned MongoDB adapters own collection access, persistence-only document types, and conversion of branded module string IDs to and from ObjectId inside the adapter, along with queries, projections, validators, and indexes. Do not use any to bypass the domain/persistence distinction."}
 
 ## Queries and commands
 - Commands enforce invariants and change state.
@@ -530,24 +547,20 @@ This service uses MongoDB. Module-owned MongoDB adapters own collection access,
 ${options.ui ? "- In production, serve the compiled UI from `dist/public` with a non-API SPA fallback. Never return the SPA for `/api` requests." : ""}
 
 ## Production image
-The ECR build targets \`linux/amd64\`. ${options.ui ? "Its default immutable tag is `<service-sha>_<ui-sha>` and production Compose requires that exact tag." : "Its default immutable tag is `<service-sha>` and production Compose requires that exact tag."} The runtime image contains production dependencies only and runs as the Node user.${options.ui && options.auth === "firebase" ? ` The build requires \`${ui}/.env.production\` and mounts it as a BuildKit secret only while Vite compiles the browser bundle; it is not copied into the final image.` : ""}
+The ECR build targets \`linux/amd64\`. ${options.ui ? "Its default immutable tag is `<product-sha>` and production Compose requires that exact tag." : "Its default immutable tag is `<product-sha>` and production Compose requires that exact tag."} The runtime image contains production dependencies only and runs as the Node user.${options.ui && options.auth === "firebase" ? ` The build requires \`${ui}/.env.production\` and mounts it as a BuildKit secret only while Vite compiles the browser bundle; it is not copied into the final image.` : ""}
 
 ## Production deployment
 Only service \`main\` pushes or manual workflow dispatch deploy; UI pushes never trigger deployment. GitHub Actions may replace files under \`/opt/${options.name}/current\` and MUST NOT replace persistent configuration, credentials, keyfiles, or data under \`/opt/${options.name}/shared\`. Keep Node runtime behavior in the shared service \`.env.production\`, Compose interpolation and infrastructure credentials in \`.env.infrastructure\`, and fixed topology wiring in Compose \`environment:\`. The optional UI build-time \`.env.production\` is a separate ephemeral file. Do not run deployment until the host and GitHub production environment have been bootstrapped according to \`docs/production-deployment.md\`.
 
 ## Tests and validation
-Run \`npm run validate:architecture\` and \`npm run format:check\` after changing files or imports. The generated service also includes unit tests and Mongo-backed integration tests. Run \`npm run test:db:up\`, \`npm test\`, and \`npm run test:db:down\` for the full service check. Test use cases, policies, Mongo repository adapters, and HTTP boundaries where behavior lives. Every public operation needs success and error-envelope coverage; authenticated operations need trusted-identity coverage; persisted capabilities need Mongo ownership/query coverage; UI-enabled services must verify that \`/api\` paths never fall through to the SPA. All AWS/ECR and Docker commands, including \`npm run docker:push\`, must run outside the sandbox from the first attempt.
+Run \`pnpm validate:architecture\` and \`pnpm format:check\` after changing files or imports. The generated service also includes unit tests and ${postgres ? "PostgreSQL-backed" : "Mongo-backed"} integration tests. Run focused service database tests through pnpm for the full service check. Test use cases, policies, ${postgres ? "PostgreSQL" : "Mongo"} repository adapters, and HTTP boundaries where behavior lives. Every public operation needs success and error-envelope coverage; authenticated operations need trusted-identity coverage; persisted capabilities need ${postgres ? "PostgreSQL" : "Mongo"} ownership/query coverage; UI-enabled services must verify that \`/api\` paths never fall through to the SPA. All AWS/ECR and Docker commands, including the service \`docker:push\` script, must run outside the sandbox from the first attempt.
 `);
 
 if (options.ui) {
 const uiDeps = { "@tailwindcss/vite": "^4.1.18", "@vueuse/core": "^14.3.0", axios: "^1.9.0", pinia: "^3.0.1", primevue: "^4.2.5", vue: "^3.5.13", "vue-router": "^4.5.0", ...(options.auth === "firebase" ? { firebase: "^11.0.0" } : {}) };
-const uiDevDeps = { "@tsconfig/node22": "^22.0.1", "@zaaxch/tailframe": contractVersion, "@types/node": "^22.13.14", "@vitejs/plugin-vue": "^5.2.3", "@vue/test-utils": "^2.4.10", "@vue/tsconfig": "^0.7.0", jsdom: "^29.1.1", "npm-run-all2": "^7.0.2", prettier: "3.5.3", typescript: "~5.8.0", vite: "^6.2.4", vitest: "^4.1.7", "vue-tsc": "^2.2.8" };
-add(`${ui}/package.json`, JSON.stringify({ name: ui, version: "0.1.0", private: true, type: "module", scripts: { dev: "vite --host 0.0.0.0", build: "run-p type-check \"build-only {@}\" --", "build-only": "vite build", "type-check": "vue-tsc --build", test: "vitest run", "test:watch": "vitest", "validate:architecture": "tailframe validate .", "sync:architecture": "tailframe sync --check .", format: "prettier --write src/", "format:check": "prettier --check src/" }, dependencies: uiDeps, devDependencies: uiDevDeps }, null, "\t"));
-add(`${ui}/tailframe.json`, configSource({
-	kind: "ui",
-	profiles: [...(options.auth === "firebase" ? ["firebase"] : []), "notifications"],
-	contractVersion
-}));
+const uiDevDeps = { "@tsconfig/node22": "^22.0.1", "@types/node": "^22.13.14", "@vitejs/plugin-vue": "^5.2.3", "@vue/test-utils": "^2.4.10", "@vue/tsconfig": "^0.7.0", jsdom: "^29.1.1", "npm-run-all2": "^7.0.2", prettier: "3.5.3", typescript: "~5.8.0", vite: "^6.2.4", vitest: "^4.1.7", "vue-tsc": "^2.2.8" };
+add(`${ui}/package.json`, JSON.stringify({ name: uiPackage, version: "0.1.0", private: true, type: "module", scripts: { dev: "vite --host 0.0.0.0", build: "run-p type-check \"build-only {@}\" --", "build-only": "vite build", "type-check": "vue-tsc --build", test: "vitest run", "test:watch": "vitest", "validate:architecture": "tailframe validate ../.. --app ui", "sync:architecture": "tailframe sync --check ../..", format: "prettier --write src/", "format:check": "prettier --check src/" }, dependencies: uiDeps, devDependencies: uiDevDeps }, null, "\t"));
+
 add(`${ui}/.prettierrc.json`, JSON.stringify(prettierConfig, null, "\t"));
 add(`${ui}/.gitattributes`, gitAttributes);
 add(`${ui}/tsconfig.json`, JSON.stringify({ files: [], references: [{ path: "./tsconfig.app.json" }, { path: "./tsconfig.node.json" }] }, null, "\t"));
@@ -589,6 +602,7 @@ if (options.auth === "firebase") add(`${ui}/src/app/configureHttp.ts`, configure
 add(`${ui}/src/platform/config.ts`, `export const apiBaseUrl = \`\${window.location.origin}/api/v1\`;`);
 add(`${ui}/src/modules/health/api/health.api.ts`, healthApiSource);
 add(`${ui}/src/modules/health/views/HealthView.vue`, `<script setup lang="ts">
+import Button from "primevue/button";
 import { ref } from "vue";
 import { isServiceError } from "@/core/errors";
 import { getReadiness } from "@/modules/health/api/health.api";
@@ -616,14 +630,14 @@ async function checkReadiness() {
 		<p class="font-bold uppercase tracking-[0.12em] text-emerald-800">Architecture reference</p>
 		<h1 class="m-0 text-5xl font-bold sm:text-7xl">${title}</h1>
 		<p>The product domain is intentionally undefined.</p>
-		<button
+		<Button
 			type="button"
+			:label="loading ? 'Checking…' : 'Check readiness'"
 			class="self-start rounded-full bg-emerald-800 px-4 py-3 text-white disabled:opacity-60"
 			:disabled="loading"
+			:loading="loading"
 			@click="checkReadiness"
-		>
-			{{ loading ? "Checking…" : "Check readiness" }}
-		</button>
+		/>
 		<p v-if="status" role="status">Service status: {{ status }}</p>
 		<p v-if="error" role="alert">{{ error }}</p>
 	</main>
@@ -652,7 +666,7 @@ These conventions apply to \`${ui}/src\`. Inspect the nearest working module bef
 - Use \`src/platform\` for Axios, Firebase, browser APIs, and other technical adapters.
 - Use \`src/modules/<module>\` for every product capability. Never substitute \`src/features\` or global \`apis\`, \`views\`, \`services\`, \`stores\`, or \`types\` directories.
 - These are the only UI architecture roots. Keep \`src/core\` flat. Shared capability code belongs to the module that owns it. \`src/app/stores\` is closed to generated \`auth.store.ts\`, \`notification.store.ts\`, and \`theme.store.ts\`; \`src/app/public\` is closed to generated \`ThemeToggle.vue\`. Do not edit their implementations; only the generated theme storage key varies. Internal shell components remain private under \`src/app/components\`.
-- Never create \`src/modules/theme\`, \`src/modules/auth\`, or \`src/modules/notification\`. Product records, current-user domain records, selections, filters, workflows, and module API calls always belong to the owning product module.
+- Never create \`src/modules/theme\`, \`src/modules/auth\`, or \`src/modules/notification\`. Product records, current-user domain records, selections, filters, workflows, and module API calls always belong to the owning product module. When the service exposes a user capability, its current-user record belongs to a UI \`user\` module rather than whichever consumer happens to use fields from the response.
 
 ## Change placement
 | Change | Canonical owner |
@@ -685,7 +699,8 @@ Keep local state local. Use Pinia only for state shared across routes or unrelat
 Keep all product state in the owning module. The auth/notification/theme stores, NotificationHost, and ThemeToggle are Tailframe-owned generated sources shared byte-for-byte across projects apart from the explicit theme storage key.
 
 ## UI behavior
-Reuse Vue, PrimeVue, Tailwind, loading, error, and accessibility conventions. Provide explicit loading, empty, error, and authorization states.
+- Prefer PrimeVue for standard interactive controls and overlays when an appropriate component exists. Use native HTML for semantic structure, links, and genuinely custom interactions; use Tailwind for layout and composition.
+- Reuse Vue, PrimeVue, Tailwind, loading, error, and accessibility conventions. Provide explicit loading, empty, error, and authorization states.
 
 ## Styling
 - Prefer Tailwind utility classes in Vue templates over custom selectors and component-scoped CSS.
@@ -693,74 +708,44 @@ Reuse Vue, PrimeVue, Tailwind, loading, error, and accessibility conventions. Pr
 - Keep \`src/app/styles.css\` limited to Tailwind imports, theme tokens, and true global base behavior.
 
 ## Production packaging
-The UI runs through Vite in development but has no production container. The service's multi-stage Dockerfile builds this repository and copies its output into \`dist/public\`; Express serves it with SPA fallback. AWS ECR stores the combined \`linux/amd64\` production image under the default immutable \`<service-sha>_<ui-sha>\` tag, and production Compose requires that exact tag.${options.auth === "firebase" ? ` Provide \`${ui}/.env.production\` before a production build; the service build mounts it as a required BuildKit secret only while Vite compiles the browser bundle and does not copy it into the final image.` : ""}
+The UI runs through Vite in development but has no production container. The service's multi-stage Dockerfile builds this application and copies its output into \`dist/public\`; Express serves it with SPA fallback. AWS ECR stores the combined \`linux/amd64\` production image under the default immutable \`<product-sha>\` tag, and production Compose requires that exact tag.${options.auth === "firebase" ? ` Provide \`${ui}/.env.production\` before a production build; the service build mounts it as a required BuildKit secret only while Vite compiles the browser bundle and does not copy it into the final image.` : ""}
 
 ## Product language
 The product domain is undefined. Do not invent entities, workflows, roles, claims, navigation, or customer-facing promises.
 
 ## Validation
-Run \`npm run validate:architecture\` and \`npm run format:check\`, then add focused Vitest coverage and run type-check, build, and \`npm test\` as applicable. Use \`npm run test:watch\` only for interactive development.
+Run \`pnpm validate:architecture\` and \`pnpm format:check\`, then add focused Vitest coverage and run type-check, build, and \`pnpm test\` as applicable. Use \`pnpm test:watch\` only for interactive development.
 `);
 }
 
-add(`${svc}/Dockerfile`, options.ui ? `FROM node:22.13-bookworm AS service-build
-WORKDIR /app/service
-COPY ${svc}/package*.json ./
-RUN npm ci
-COPY ${svc}/ ./
-RUN npm run build
-
-FROM node:22.13-bookworm AS service-production-dependencies
-WORKDIR /app/service
-COPY ${svc}/package*.json ./
-RUN npm ci --omit=dev && npm cache clean --force
-
-FROM node:22.13-bookworm AS ui-build
-WORKDIR /app/ui
-COPY ${ui}/package*.json ./
-RUN npm ci
-COPY ${ui}/ ./
-${options.auth === "firebase" ? "RUN --mount=type=secret,id=ui_env,target=/app/ui/.env.production,required=true npm run build" : "RUN npm run build"}
+add(`${svc}/Dockerfile`, `FROM node:22.13-bookworm AS build
+RUN corepack enable
+WORKDIR /workspace
+COPY package.json pnpm-workspace.yaml pnpm-lock.yaml ./
+COPY apps/service/package.json apps/service/package.json
+${options.ui ? "COPY apps/ui/package.json apps/ui/package.json\n" : ""}RUN pnpm install --frozen-lockfile
+COPY apps/service apps/service
+${options.ui ? "COPY apps/ui apps/ui\n" : ""}RUN pnpm --filter ${servicePackage} build
+${options.ui ? (options.auth === "firebase" ? `RUN --mount=type=secret,id=ui_env,target=/workspace/apps/ui/.env.production,required=true pnpm --filter ${uiPackage} build` : `RUN pnpm --filter ${uiPackage} build`) + "\n" : ""}RUN pnpm --filter ${servicePackage} --prod deploy /prod/service
 
 FROM node:22.13-bookworm-slim
 WORKDIR /app
 ENV NODE_ENV=production
-COPY --from=service-build /app/service/dist ./dist
-COPY --from=service-build /app/service/package*.json ./
-COPY --from=service-production-dependencies /app/service/node_modules ./node_modules
-COPY --from=ui-build /app/ui/dist ./dist/public
-USER node
-EXPOSE 3000
-CMD ["node", "dist/server.js"]
-` : `FROM node:22.13-bookworm AS build
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci
-COPY . .
-RUN npm run build
-
-FROM node:22.13-bookworm AS production-dependencies
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci --omit=dev && npm cache clean --force
-
-FROM node:22.13-bookworm-slim
-WORKDIR /app
-ENV NODE_ENV=production
-COPY --from=build /app/dist ./dist
-COPY --from=build /app/package*.json ./
-COPY --from=production-dependencies /app/node_modules ./node_modules
-USER node
+COPY --from=build /prod/service ./
+${options.ui ? "COPY --from=build /workspace/apps/ui/dist ./dist/public\n" : ""}USER node
 EXPOSE 3000
 CMD ["node", "dist/server.js"]
 `);
 add(`${svc}/Dockerfile.dev`, `FROM node:22.13-alpine
-WORKDIR /app
-COPY package*.json ./
-RUN npm install
-COPY . .
+RUN corepack enable
+WORKDIR /workspace
+COPY package.json pnpm-workspace.yaml pnpm-lock.yaml ./
+COPY apps/service/package.json apps/service/package.json
+RUN pnpm install --frozen-lockfile
+COPY apps/service apps/service
+WORKDIR /workspace/apps/service
 EXPOSE 3000
-CMD ["npm", "run", "dev"]
+CMD ["pnpm", "dev"]
 `);
 add(`${svc}/scripts/build_and_push.sh`, `#!/usr/bin/env bash
 set -euo pipefail
@@ -768,54 +753,44 @@ set -euo pipefail
 : "\${AWS_ACCOUNT_ID:?Set AWS_ACCOUNT_ID}"
 : "\${AWS_REGION:?Set AWS_REGION}"
 
-SVC_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
-BUILD_CONTEXT="${options.ui ? `$(cd "\${SVC_DIR}/.." && pwd)` : `\${SVC_DIR}`}"
-${options.ui ? `UI_DIR="\${BUILD_CONTEXT}/${ui}"
-SVC_SHA="$(git -C "\${SVC_DIR}" rev-parse --short HEAD)"
-UI_SHA="$(git -C "\${UI_DIR}" rev-parse --short HEAD)"` : `SVC_SHA="$(git -C "\${SVC_DIR}" rev-parse --short HEAD)"`}
-
+SERVICE_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
+PRODUCT_ROOT="$(cd "\${SERVICE_DIR}/../.." && pwd)"
+PRODUCT_SHA="$(git -C "\${PRODUCT_ROOT}" rev-parse --short HEAD)"
 ECR_REPOSITORY="\${ECR_REPOSITORY:-${options.name}}"
-IMAGE_TAG="\${IMAGE_TAG:-${options.ui ? `\${SVC_SHA}_\${UI_SHA}` : `\${SVC_SHA}`}}"
+IMAGE_TAG="\${IMAGE_TAG:-\${PRODUCT_SHA}}"
 REGISTRY="\${AWS_ACCOUNT_ID}.dkr.ecr.\${AWS_REGION}.amazonaws.com"
 IMAGE="\${REGISTRY}/\${ECR_REPOSITORY}:\${IMAGE_TAG}"
-DOCKERFILE="\${SVC_DIR}/Dockerfile"
-${options.ui && options.auth === "firebase" ? `UI_ENV_FILE="\${UI_ENV_FILE:-\${UI_DIR}/.env.production}"` : ""}
+DOCKERFILE="\${SERVICE_DIR}/Dockerfile"
+${options.ui && options.auth === "firebase" ? `UI_ENV_FILE="\${UI_ENV_FILE:-\${PRODUCT_ROOT}/apps/ui/.env.production}"` : ""}
 
 aws ecr get-login-password --region "\${AWS_REGION}" |
 	docker login --username AWS --password-stdin "\${REGISTRY}"
 
-docker build --platform linux/amd64${options.ui && options.auth === "firebase" ? ` --secret "id=ui_env,src=\${UI_ENV_FILE}"` : ""} --file "\${DOCKERFILE}" --tag "\${IMAGE}" "\${BUILD_CONTEXT}"
+docker build --platform linux/amd64${options.ui && options.auth === "firebase" ? ` --secret "id=ui_env,src=\${UI_ENV_FILE}"` : ""} --file "\${DOCKERFILE}" --tag "\${IMAGE}" "\${PRODUCT_ROOT}"
 docker push "\${IMAGE}"
 
 echo "Pushed \${IMAGE}"
 `);
-
-const workflowUiCheckout = options.ui ? `
-      - name: Checkout UI dependency
-        uses: actions/checkout@v6
-        with:
-          repository: \${{ github.repository_owner }}/${ui}
-          ref: main
-          ssh-key: \${{ secrets.UI_REPO_SSH_KEY }}
-          path: ${ui}
-` : "";
+const workflowUiPath = options.ui ? '      - "apps/ui/**"\n' : "";
 const workflowUiEnvironment = options.ui && options.auth === "firebase" ? `
       - name: Write UI production environment
         env:
           UI_ENV_PRODUCTION: \${{ secrets.UI_ENV_PRODUCTION }}
         run: |
-          printf '%s\\n' "$UI_ENV_PRODUCTION" > ${ui}/.env.production
+          printf '%s\\n' "$UI_ENV_PRODUCTION" > apps/ui/.env.production
 ` : "";
-const workflowTagResolution = options.ui ? `
-          ui_sha="$(git -C ${ui} rev-parse --short HEAD)"
-          echo "tag=\${svc_sha}_\${ui_sha}" >> "$GITHUB_OUTPUT"` : `
-          echo "tag=\${svc_sha}" >> "$GITHUB_OUTPUT"`;
-add(`${svc}/.github/workflows/deploy.yml`, `name: Build and deploy
+add(".github/workflows/deploy.yml", `name: Build and deploy
 
 on:
   push:
     branches:
       - main
+    paths:
+      - "apps/service/**"
+${workflowUiPath}      - "package.json"
+      - "pnpm-workspace.yaml"
+      - "pnpm-lock.yaml"
+      - ".github/workflows/deploy.yml"
   workflow_dispatch:
 
 permissions:
@@ -840,15 +815,14 @@ jobs:
       DEPLOY_USER: \${{ vars.DEPLOY_USER }}
 
     steps:
-      - name: Checkout service
+      - name: Checkout product
         uses: actions/checkout@v6
-        with:
-          path: ${svc}
-${workflowUiCheckout}${workflowUiEnvironment}
+${workflowUiEnvironment}
       - name: Resolve immutable image
         id: image
         run: |
-          svc_sha="$(git -C ${svc} rev-parse --short HEAD)"${workflowTagResolution}
+          product_sha="$(git rev-parse --short HEAD)"
+          echo "tag=\${product_sha}" >> "$GITHUB_OUTPUT"
           echo "registry=\${AWS_ACCOUNT_ID}.dkr.ecr.\${AWS_REGION}.amazonaws.com" >> "$GITHUB_OUTPUT"
           echo "image=\${AWS_ACCOUNT_ID}.dkr.ecr.\${AWS_REGION}.amazonaws.com/\${ECR_REPOSITORY}" >> "$GITHUB_OUTPUT"
 
@@ -859,10 +833,9 @@ ${workflowUiCheckout}${workflowUiEnvironment}
           aws-region: \${{ vars.AWS_REGION }}
 
       - name: Build and push image
-        working-directory: ${svc}
         env:
           IMAGE_TAG: \${{ steps.image.outputs.tag }}
-        run: ./scripts/build_and_push.sh
+        run: apps/service/scripts/build_and_push.sh
 
       - name: Configure deployment SSH
         env:
@@ -885,11 +858,11 @@ ${workflowUiCheckout}${workflowUiEnvironment}
           ssh -i ~/.ssh/${options.name}-deploy "\${DEPLOY_USER}@\${DEPLOY_HOST}" \\
             "install -m 755 -d /opt/${options.name}/current/deploy/mongo"
           scp -i ~/.ssh/${options.name}-deploy \\
-            ${svc}/docker-compose.yml \\
-            ${svc}/scripts/deploy_remote.sh \\
+            apps/service/docker-compose.yml \\
+            apps/service/scripts/deploy_remote.sh \\
             "\${DEPLOY_USER}@\${DEPLOY_HOST}:/opt/${options.name}/current/"
           scp -i ~/.ssh/${options.name}-deploy \\
-            ${svc}/deploy/mongo/10-create-users.js \\
+            apps/service/deploy/mongo/10-create-users.js \\
             "\${DEPLOY_USER}@\${DEPLOY_HOST}:/opt/${options.name}/current/deploy/mongo/"
           ssh -i ~/.ssh/${options.name}-deploy "\${DEPLOY_USER}@\${DEPLOY_HOST}" \\
             "chmod 755 /opt/${options.name}/current/deploy_remote.sh"
@@ -899,7 +872,6 @@ ${workflowUiCheckout}${workflowUiEnvironment}
           ssh -i ~/.ssh/${options.name}-deploy "\${DEPLOY_USER}@\${DEPLOY_HOST}" \\
             "/opt/${options.name}/current/deploy_remote.sh '\${{ steps.image.outputs.tag }}' '\${{ steps.image.outputs.image }}'"
 `);
-
 add(`${svc}/scripts/deploy_remote.sh`, `#!/usr/bin/env bash
 set -euo pipefail
 
@@ -951,9 +923,9 @@ add(`${svc}/docs/production-deployment.md`, `# Production deployment
 
 ## Delivery model
 
-GitHub Actions checks out ${svc}${options.ui ? ` and ${ui}` : ""}${options.ui ? " as sibling build inputs" : ""}, builds one
-non-root production image, tags it ${options.ui ? "`<service-sha>_<ui-sha>`" : "`<service-sha>`"}, pushes it to ECR, and installs only deployment artifacts on the host.
-Only service \`main\` pushes and manual dispatch trigger this workflow; UI pushes never deploy.
+GitHub Actions checks out the product once, builds one
+non-root production image, tags it \`<product-sha>\`, pushes it to ECR, and installs only deployment artifacts on the host.
+Changes to the service, optional UI, root workspace/lock configuration, or deployment files on product \`main\`, plus manual dispatch, trigger this workflow.
 
 The host separates replaceable artifacts from persistent state:
 
@@ -981,7 +953,7 @@ Actions may replace \`current/\` and must never replace \`shared/\`. The server
   \`.env.infrastructure.example\` and replace every placeholder.
 - Compose \`environment:\` owns fixed production wiring: \`NODE_ENV\`, internal database/cache URLs, and mounted
   credential paths.
-${options.ui && options.auth === "firebase" ? `- The UI repository's build-time \`.env.production\` comes from the GitHub \`UI_ENV_PRODUCTION\` secret and is unrelated to the service runtime file above.
+${options.ui && options.auth === "firebase" ? `- The UI application's build-time \`.env.production\` comes from the GitHub \`UI_ENV_PRODUCTION\` secret and is unrelated to the service runtime file above.
 ` : ""}
 Do not inject \`.env.infrastructure\` into Node. Make both host environment files root-owned and mode \`0600\`.
 
@@ -1009,8 +981,7 @@ Configure these variables:
 
 Configure these secrets:
 
-${options.ui ? `- \`UI_REPO_SSH_KEY\`: read-only deploy key for \`${ui}\`.
-` : ""}${options.ui && options.auth === "firebase" ? `- \`UI_ENV_PRODUCTION\`: Vite/Firebase build-time environment.
+${options.ui && options.auth === "firebase" ? `- \`UI_ENV_PRODUCTION\`: Vite/Firebase build-time environment.
 ` : ""}- \`DEPLOY_SSH_PRIVATE_KEY\`: dedicated host deployment key.
 - \`DEPLOY_SSH_KNOWN_HOSTS\`: pinned host key.
 
@@ -1323,7 +1294,6 @@ for (const [relative, content] of Object.entries(ownedSources({ kind: "service",
 	add(`${svc}/${relative}`, content);
 }
 if (options.ui) {
-	const uiProfiles = [...(options.auth === "firebase" ? ["firebase"] : []), "notifications"];
 	for (const [relative, content] of Object.entries(ownedSources({ kind: "ui", profiles: uiProfiles }))) {
 		add(`${ui}/${relative}`, content);
 	}
@@ -1336,10 +1306,8 @@ for (const [relative, content] of Object.entries(files)) {
 	if (relative.endsWith(".sh")) fs.chmodSync(destination, 0o755);
 }
 
-for (const repository of [svc, ...(options.ui ? [ui] : [])]) {
-	const result = runSync(path.join(root, repository), "write", contractVersion);
-	if (result.errors.length) fail(result.errors.join("\n"));
-}
+const syncResult = runSync(root, "write", contractVersion);
+if (syncResult.errors.length) fail(syncResult.errors.join("\n"));
 
-return { root, name: options.name, database: options.db, authentication: options.auth, ui: options.ui, redis: options.redis, worker: options.worker, repositories: [svc, ...(options.ui ? [ui] : [])], files: Object.keys(files).length };
+return { root, name: options.name, database: options.db, authentication: options.auth, ui: options.ui, redis: options.redis, worker: options.worker, applications: [svc, ...(options.ui ? [ui] : [])], files: Object.keys(files).length };
 }