@oaklandzoo/ostup 0.9.1 → 0.11.0

package/README.md

@@ -17,6 +17,21 @@ When you run this tool, it will:
 6. Create an `inputs/` folder inside the project where you can drop any
    prior materials (research, reference repos, screenshots, brand
    assets) you want the agent to have on hand
+7. If you ran `ostup brief` first (recommended), drop in **working code
+   for your profile**. The four industry profiles ship real Next.js
+   overlays: lead-gen (hero + services + contact form + Resend wiring),
+   booking (booking form + dates + email confirmation), saas-dashboard
+   (Better Auth + guarded dashboard + settings), blog (MDX posts + RSS
+   + sitemap). Your first deploy shows a working homepage and day-one
+   flow, not a blank Next.js welcome.
+8. Optionally pass `--private` to ship an **app-level default-deny**
+   project on Vercel Hobby: middleware blocks every request except
+   sign-in/up + audit-health, blob helpers default to `access: 'private'`,
+   image optimizer cannot proxy external URLs, rate limiting and audit
+   logging are wired. Run `ostup doctor --privacy <url>` after deploy to
+   verify. Toggle on/off an existing project with `ostup private add` /
+   `ostup private remove` (manifest at `.ostup/private.json` makes the
+   remove cleanly revertable).
 
 ## Quick Start
 

package/bin/cli.mjs

@@ -11,7 +11,7 @@ loadDotEnv();
 
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
-const SUBCOMMANDS = new Set(['init', 'update', 'brief', 'export-pro', 'doctor', 'bootstrap']);
+const SUBCOMMANDS = new Set(['init', 'update', 'brief', 'export-pro', 'doctor', 'bootstrap', 'private']);
 
 async function readPkg() {
   const raw = await readFile(resolve(PKG_ROOT, 'package.json'), 'utf8');
@@ -45,6 +45,10 @@ function parseArgs(argv) {
     else if (a === '--output') flags.output = argv[++i];
     else if (a.startsWith('--output=')) flags.output = a.slice('--output='.length);
     else if (a === '--white-label') flags.whiteLabel = true;
+    else if (a === '--private') flags.private = true;
+    else if (a === '--privacy') flags.privacy = true;
+    else if (a === '--url') flags.url = argv[++i];
+    else if (a.startsWith('--url=')) flags.url = a.slice('--url='.length);
     else if (a === '--no-log') flags.noLog = true;
     else if (a === '--skip-bootstrap') flags.skipBootstrap = true;
     else if (a === '--no-install') flags.noInstall = true;
@@ -78,6 +82,8 @@ function printHelp() {
       '  brief               Run the 10-question operator intake; write docs/brief.md + brief.json.',
       '  export-pro          Bundle brief + brand + content + initial PRD into a ZIP for client handoff.',
       '  doctor              Self-diagnosis: tool detection + auth + permissions + disk + Chrome. Read-only.',
+      '  doctor --privacy    Probe a deployed URL for default-deny enforcement (privacy mode).',
+      '  private add|remove|status   Apply, undo, or report on app-level privacy (default-deny middleware).',
       '  update              Refresh bundled templates from the pinned source.',
       '',
       'Flags for `ostup init`:',
@@ -89,6 +95,7 @@ function printHelp() {
       '  --ingest <path>     Copy operator materials from <path> into inputs/.',
       '  --brief <path>      Load a brief.json from <path> and write brief files + apply profile overlay.',
       '  --white-label       Strip OSTUP / Goodshin attribution from generated docs (Studio tier).',
+      '  --private           App-level default-deny: middleware, blob proxy, image-optimizer lock, audit + rate-limit, CLAUDE.md Part 20. Refused with --profile saas-dashboard.',
       '  --kit-only          Drop the markdown kit into a target dir, no GitHub or Vercel.',
       '  --config <path>     Read .ostup-config.yml from this path (kit-only mode).',
       '  --skip-bootstrap    Skip the in-CLI tool detection / install step (advanced).',
@@ -193,7 +200,7 @@ if (subcommand === 'export-pro') {
 if (subcommand === 'doctor') {
   const { runDoctor, printDoctorReport } = await import('../src/doctor.mjs');
   try {
-    const result = await runDoctor();
+    const result = await runDoctor({ flags });
     process.stdout.write(printDoctorReport(result));
     process.exit(result.failCount > 0 ? 1 : 0);
   } catch (err) {
@@ -202,6 +209,25 @@ if (subcommand === 'doctor') {
   }
 }
 
+if (subcommand === 'private') {
+  const action = subPositional[0] || 'status';
+  const { runPrivate } = await import('../src/private-cmd.mjs');
+  try {
+    await runPrivate({ action, flags, cwd: process.cwd() });
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`${err.message}\n`);
+    const userErrors = new Set([
+      'PRIVATE_SAAS_CONFLICT',
+      'PRIVATE_NOT_APPLIED',
+      'PRIVATE_ALREADY_APPLIED',
+      'PRIVATE_DIRTY',
+      'PRIVATE_UNKNOWN_ACTION',
+    ]);
+    process.exit(userErrors.has(err.code) ? 1 : 2);
+  }
+}
+
 if (subcommand === 'bootstrap') {
   const { runBootstrapStandalone } = await import('../src/bootstrap.mjs');
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oaklandzoo/ostup",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "Scaffolds a new repo with the Ostup Agent Kit pre-installed: slash commands, doc templates, and a clean working state.",
   "type": "module",
   "bin": {

package/scripts/verify-profile.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# verify-profile.sh: apply a profile overlay to a fresh temp dir and assert key files exist.
+#
+# Usage: bash scripts/verify-profile.sh <profile-name>
+#   profile-name: one of lead-gen, booking, saas-dashboard, blog
+#
+# This script does NOT run `next build` (that requires installing many deps and a
+# full Next.js scaffold). It verifies that the overlay APPLIES correctly and the
+# expected files land in the target directory. Full next-build verification is
+# the operator's job after `ostup init --brief`.
+
+set -euo pipefail
+
+PROFILE="${1:-}"
+if [[ -z "$PROFILE" ]]; then
+  echo "usage: $0 <profile-name>" >&2
+  echo "  profile-name: lead-gen | booking | saas-dashboard | blog" >&2
+  exit 2
+fi
+
+case "$PROFILE" in
+  lead-gen|booking|saas-dashboard|blog)
+    ;;
+  *)
+    echo "error: unknown profile '$PROFILE'. expected one of: lead-gen, booking, saas-dashboard, blog" >&2
+    exit 2
+    ;;
+esac
+
+OSTUP_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TEST_FILE="$OSTUP_ROOT/test/profile-$(echo "$PROFILE" | tr -d -)-overlay.test.mjs"
+
+# Map profile names to test file names: lead-gen -> profile-leadgen-overlay.test.mjs
+case "$PROFILE" in
+  lead-gen)        TEST_FILE="$OSTUP_ROOT/test/profile-leadgen-overlay.test.mjs" ;;
+  booking)         TEST_FILE="$OSTUP_ROOT/test/profile-booking-overlay.test.mjs" ;;
+  saas-dashboard)  TEST_FILE="$OSTUP_ROOT/test/profile-saas-overlay.test.mjs" ;;
+  blog)            TEST_FILE="$OSTUP_ROOT/test/profile-blog-overlay.test.mjs" ;;
+esac
+
+echo ">> verifying profile: $PROFILE"
+echo ">> running: node --test $TEST_FILE"
+cd "$OSTUP_ROOT"
+node --test "$TEST_FILE"
+
+echo ">> ok: $PROFILE overlay applies and asserts pass"

package/src/brief/profile-router.mjs

@@ -9,18 +9,11 @@ import { substitute } from '../substitute.mjs';
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 const TEMPLATES_ROOT = resolve(PKG_ROOT, 'templates');
 
-/**
- * Returns the absolute path to the profile's template overlay folder.
- * Returns null if the profile has no overlay (yet).
- */
 export function profileTemplatePath(profile) {
   const p = resolve(TEMPLATES_ROOT, 'profiles', profile);
   return existsSync(p) ? p : null;
 }
 
-/**
- * Recursively list every file in a directory, returning relative paths.
- */
 async function listFiles(dir, base = dir, out = []) {
   const entries = await readdir(dir, { withFileTypes: true });
   for (const entry of entries) {
@@ -34,19 +27,51 @@ async function listFiles(dir, base = dir, out = []) {
   return out;
 }
 
-/**
- * Apply a profile overlay to the target directory.
- * - Reads every file in templates/profiles/<profile>/
- * - Substitutes tokens
- * - Writes to <targetDir>/<relative-path>
- *
- * Skip rules:
- *   - .DS_Store
- *   - any path containing /node_modules/
- *
- * Files with name suffix `.additions` are appended to the existing file at the
- * destination (used for .env.example.additions). All others are written.
- */
+function mergeJsonObjects(target, source) {
+  const out = { ...target };
+  for (const key of Object.keys(source)) {
+    const sv = source[key];
+    const tv = out[key];
+    if (sv && typeof sv === 'object' && !Array.isArray(sv) && tv && typeof tv === 'object' && !Array.isArray(tv)) {
+      out[key] = { ...tv, ...sv };
+    } else {
+      out[key] = sv;
+    }
+  }
+  return out;
+}
+
+export async function mergePackageJsonAdditions(destPath, additionsText) {
+  let additions;
+  try {
+    additions = JSON.parse(additionsText);
+  } catch (err) {
+    throw new Error(`Invalid JSON in package.json.additions: ${err.message}`);
+  }
+  let existing = {};
+  if (existsSync(destPath)) {
+    const raw = await readFile(destPath, 'utf8');
+    try {
+      existing = JSON.parse(raw);
+    } catch (err) {
+      throw new Error(`Invalid JSON in target package.json at ${destPath}: ${err.message}`);
+    }
+  }
+  const merged = mergeJsonObjects(existing, additions);
+  await writeFile(destPath, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+}
+
+export async function mergeNextConfigAdditions(destPath, additionsText) {
+  const marker = '--- added by ostup profile overlay ---';
+  if (existsSync(destPath)) {
+    const existing = await readFile(destPath, 'utf8');
+    if (existing.includes(marker)) return;
+    await writeFile(destPath, existing + `\n// ${marker}\n` + additionsText, 'utf8');
+  } else {
+    await writeFile(destPath, `// next.config.mjs (created by ostup profile overlay)\n` + additionsText, 'utf8');
+  }
+}
+
 export async function applyProfileOverlay({ targetDir, profile, tokens, dryRun = false } = {}) {
   const overlayPath = profileTemplatePath(profile);
   if (!overlayPath) {
@@ -59,12 +84,19 @@ export async function applyProfileOverlay({ targetDir, profile, tokens, dryRun =
   const actions = [];
   for (const rel of filtered) {
     const src = join(overlayPath, rel);
-    const isAddition = rel.endsWith('.additions');
-    const dest = isAddition
-      ? join(targetDir, rel.replace(/\.additions$/, ''))
-      : join(targetDir, rel);
-
-    actions.push({ rel, src, dest, isAddition });
+    let kind = 'copy';
+    let dest = join(targetDir, rel);
+    if (rel.endsWith('package.json.additions')) {
+      kind = 'package-merge';
+      dest = join(targetDir, rel.replace(/\.additions$/, ''));
+    } else if (rel.endsWith('next.config.mjs.additions')) {
+      kind = 'next-config-merge';
+      dest = join(targetDir, rel.replace(/\.additions$/, ''));
+    } else if (rel.endsWith('.additions')) {
+      kind = 'append';
+      dest = join(targetDir, rel.replace(/\.additions$/, ''));
+    }
+    actions.push({ rel, src, dest, kind });
   }
 
   if (dryRun) {
@@ -75,9 +107,12 @@ export async function applyProfileOverlay({ targetDir, profile, tokens, dryRun =
     const raw = await readFile(a.src, 'utf8');
     const out = substitute(raw, tokens);
     await mkdir(dirname(a.dest), { recursive: true });
-    if (a.isAddition && existsSync(a.dest)) {
+    if (a.kind === 'package-merge') {
+      await mergePackageJsonAdditions(a.dest, out);
+    } else if (a.kind === 'next-config-merge') {
+      await mergeNextConfigAdditions(a.dest, out);
+    } else if (a.kind === 'append' && existsSync(a.dest)) {
       const existing = await readFile(a.dest, 'utf8');
-      // Append with a separator if not already present
       const sep = existing.endsWith('\n') ? '' : '\n';
       await writeFile(a.dest, existing + sep + '\n# --- added by ostup profile overlay ---\n' + out, 'utf8');
     } else {

package/src/doctor-privacy.mjs

@@ -0,0 +1,103 @@
+// doctor-privacy.mjs: HTTP probes for ostup doctor --privacy.
+// Auto-detects deployed URL from .vercel/project.json; --url overrides.
+
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const PROBE_PATHS = [
+  '/api/health',
+  '/api/contact',
+  '/api/booking/request',
+  '/api/account/settings',
+  '/api/blob/test.jpg',
+  '/uploads/test.jpg',
+  '/_next/image?url=https%3A%2F%2Fexample.com%2Ftest.jpg&w=64&q=75',
+  '/dashboard',
+  '/dashboard/settings',
+];
+
+const AUDIT_HEALTH_PATH = '/api/audit/health';
+
+export async function detectDeployedUrl(cwd = process.cwd()) {
+  const projectJson = join(cwd, '.vercel', 'project.json');
+  if (!existsSync(projectJson)) return null;
+  try {
+    const raw = await readFile(projectJson, 'utf8');
+    const data = JSON.parse(raw);
+    if (data.productionDomain) {
+      const host = String(data.productionDomain).replace(/^https?:\/\//, '');
+      return `https://${host}`;
+    }
+    if (data.production_alias) {
+      const host = String(data.production_alias).replace(/^https?:\/\//, '');
+      return `https://${host}`;
+    }
+    if (data.projectId) {
+      return null; // We could shell out to `vercel inspect`, but skip in v1.
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+async function probeOne(baseUrl, path, fetchImpl = fetch) {
+  const url = `${baseUrl.replace(/\/+$/, '')}${path}`;
+  try {
+    const res = await fetchImpl(url, {
+      method: 'GET',
+      redirect: 'manual',
+      headers: { 'user-agent': 'ostup-doctor-privacy/1.0' },
+    });
+    return { url, status: res.status, ok: res.status === 401 || res.status === 404 || res.status === 403 || (res.status >= 300 && res.status < 400) };
+  } catch (err) {
+    return { url, status: 0, ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+async function probeAuditHealth(baseUrl, fetchImpl = fetch) {
+  const url = `${baseUrl.replace(/\/+$/, '')}${AUDIT_HEALTH_PATH}`;
+  try {
+    const res = await fetchImpl(url, { method: 'GET', headers: { 'user-agent': 'ostup-doctor-privacy/1.0' } });
+    if (!res.ok) return { url, status: res.status, ok: false };
+    const body = await res.json().catch(() => null);
+    return { url, status: res.status, ok: body?.ok === true, body };
+  } catch (err) {
+    return { url, status: 0, ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+export async function runPrivacyChecks({ url, cwd = process.cwd(), report, fetchImpl = fetch } = {}) {
+  let baseUrl = url;
+  if (!baseUrl) baseUrl = await detectDeployedUrl(cwd);
+  if (!baseUrl) {
+    report('fail', 'privacy url', 'could not resolve deployed URL. Pass --url <vercel-url> or run from a Vercel-linked project dir.');
+    return;
+  }
+  report('ok', 'privacy url', baseUrl);
+
+  for (const p of PROBE_PATHS) {
+    const result = await probeOne(baseUrl, p, fetchImpl);
+    if (result.error) {
+      report('warn', `probe ${p}`, `network error: ${result.error}`);
+      continue;
+    }
+    if (result.ok) {
+      report('ok', `probe ${p}`, `${result.status} (denied as expected)`);
+    } else {
+      report('fail', `probe ${p}`, `${result.status} (expected 401/403/404/redirect; got 2xx)`);
+    }
+  }
+
+  const audit = await probeAuditHealth(baseUrl, fetchImpl);
+  if (audit.error) {
+    report('warn', 'probe audit-health', `network error: ${audit.error}`);
+  } else if (audit.ok) {
+    report('ok', 'probe audit-health', `${audit.status} (audit pipeline wired)`);
+  } else {
+    report('fail', 'probe audit-health', `${audit.status} (audit pipeline NOT wired)`);
+  }
+}
+
+export { PROBE_PATHS, AUDIT_HEALTH_PATH };

package/src/doctor.mjs

@@ -25,7 +25,7 @@ function runCapture(cmd) {
   }
 }
 
-export async function runDoctor() {
+export async function runDoctor({ flags = {} } = {}) {
   const findings = [];
   let okCount = 0;
   let failCount = 0;
@@ -38,6 +38,12 @@ export async function runDoctor() {
     else warnCount++;
   }
 
+  if (flags.privacy) {
+    const { runPrivacyChecks } = await import('./doctor-privacy.mjs');
+    await runPrivacyChecks({ url: flags.url, report });
+    return { findings, okCount, warnCount, failCount };
+  }
+
   // === Tool detection (shared with bootstrap) ===
   const detection = detectAll();
   for (const f of detection.found) {

package/src/mvp-flow.mjs

@@ -134,6 +134,16 @@ export async function runMvp({ flags = {}, cwd = process.cwd() } = {}) {
     }
   }
 
+  if (flags.private) {
+    const { applyPrivate } = await import('./private.mjs');
+    const profile = brief?.scaffold?.profile || null;
+    const priv = await applyPrivate({ targetDir, profile });
+    process.stdout.write(
+      `[private] applied default-deny. ${priv.touched.length} file(s) touched. ` +
+        `rate-limit backend: ${priv.useKvRateLimit ? 'kv' : 'in-memory'}\n`,
+    );
+  }
+
   await exec('git-init',  'git', ['init'], { cwd: targetDir });
   await exec('git-branch','git', ['branch', '-M', 'main'], { cwd: targetDir });
   await exec('git-add',   'git', ['add', '.'], { cwd: targetDir });

package/src/private-cmd.mjs

@@ -0,0 +1,35 @@
+// private-cmd.mjs: ostup private add|remove|status subcommand.
+
+import { applyPrivate, removePrivate, statusPrivate, PrivateError } from './private.mjs';
+
+export async function runPrivate({ action = 'status', flags = {}, cwd = process.cwd() } = {}) {
+  if (action === 'add') {
+    const result = await applyPrivate({ targetDir: cwd, force: !!flags.force });
+    process.stdout.write(
+      `[private] applied. ${result.touched.length} file(s) touched. ` +
+        `rate-limit backend: ${result.useKvRateLimit ? 'kv' : 'in-memory'}\n`,
+    );
+    process.stdout.write(`[private] manifest: .ostup/private.json (run 'ostup private remove' to undo)\n`);
+    return;
+  }
+  if (action === 'remove') {
+    const result = await removePrivate({ targetDir: cwd, force: !!flags.force });
+    process.stdout.write(`[private] removed. ${result.restored.length} file(s) reverted.\n`);
+    return;
+  }
+  if (action === 'status') {
+    const result = await statusPrivate({ targetDir: cwd });
+    if (!result.applied) {
+      process.stdout.write(`[private] not applied. Run 'ostup private add' to enable.\n`);
+      return;
+    }
+    process.stdout.write(`[private] applied at ${result.manifest.appliedAt}\n`);
+    process.stdout.write(`[private] rate-limit backend: ${result.manifest.useKvRateLimit ? 'kv' : 'in-memory'}\n`);
+    process.stdout.write(`[private] files under management:\n`);
+    for (const op of result.manifest.ops) {
+      process.stdout.write(`  ${op.kind === 'created' ? '+' : '~'} ${op.path}\n`);
+    }
+    return;
+  }
+  throw new PrivateError('PRIVATE_UNKNOWN_ACTION', `unknown action '${action}'. Use: add | remove | status`);
+}

package/src/private.mjs

@@ -0,0 +1,215 @@
+// private.mjs: applyPrivate post-processor. Lays down default-deny middleware,
+// blob proxy, audit + rate-limit libs, locked next.config, CLAUDE.md Part 20.
+// Captures original content of patched files for clean rollback by `ostup private remove`.
+
+import { readFile, writeFile, mkdir, rm } from 'node:fs/promises';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const PRIVATE_TEMPLATES = resolve(PKG_ROOT, 'templates', 'private');
+
+const SAAS_CONFLICT_MSG =
+  '--private is not compatible with the saas-dashboard profile. ' +
+  'saas-dashboard already provides Better Auth + a session-checking middleware.ts. ' +
+  'Layering default-deny on top creates two competing matchers.\n\n' +
+  'Pick one:\n' +
+  '  - Use --private alone for a generic single-user-protected app\n' +
+  '  - Use --profile saas-dashboard alone for the SaaS shell';
+
+export const PRIVATE_MANIFEST_PATH = '.ostup/private.json';
+
+class PrivateError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+function detectSaas(targetDir, profile) {
+  if (profile === 'saas-dashboard') return true;
+  const pkgPath = join(targetDir, 'package.json');
+  if (!existsSync(pkgPath)) return false;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+    return Boolean(deps['better-auth']);
+  } catch {
+    return false;
+  }
+}
+
+function plannedOperations(targetDir, useKvRateLimit) {
+  // Each op: { kind: 'create'|'patch', dest: <relative path>, src: <template relpath>|null, patcher?: fn }
+  const rateLimitSrc = useKvRateLimit ? 'lib-rate-limit-kv.ts' : 'lib-rate-limit-memory.ts';
+  return [
+    { kind: 'create', dest: 'middleware.ts', src: 'middleware.ts' },
+    { kind: 'create', dest: 'next.config.ts', src: 'next.config.ts' },
+    { kind: 'create', dest: 'app/api/blob/[...path]/route.ts', src: 'api-blob-proxy.ts' },
+    { kind: 'create', dest: 'app/api/audit/health/route.ts', src: 'api-audit-health.ts' },
+    { kind: 'create', dest: 'lib/audit.ts', src: 'lib-audit.ts' },
+    { kind: 'create', dest: 'lib/rate-limit.ts', src: rateLimitSrc },
+    { kind: 'patch', dest: 'CLAUDE.md', src: 'CLAUDE_PART_20.md', mode: 'append' },
+    { kind: 'patch', dest: 'app/layout.tsx', src: null, mode: 'layout-robots' },
+  ];
+}
+
+async function loadTemplate(rel) {
+  return readFile(join(PRIVATE_TEMPLATES, rel), 'utf8');
+}
+
+function patchLayoutRobots(body) {
+  // Inject `robots: { index: false, follow: false }` into the metadata export, if present.
+  // Idempotent: skip if already contains "robots:".
+  if (/robots\s*:/.test(body)) return body;
+  // Match: export const metadata: Metadata = {  ...  };
+  const re = /(export\s+const\s+metadata\s*:\s*Metadata\s*=\s*\{)([^}]*)(\})/;
+  if (!re.test(body)) return body;
+  return body.replace(re, (_full, open, inner, close) => {
+    const trimmed = inner.replace(/\s*$/, '');
+    const sep = trimmed.endsWith(',') ? '' : (trimmed.length > 0 ? ',' : '');
+    const insert = `${trimmed}${sep}\n  robots: { index: false, follow: false },\n`;
+    return `${open}${insert}${close}`;
+  });
+}
+
+function envMentions(targetDir, names) {
+  for (const file of ['.env', '.env.local', '.env.production', '.env.example']) {
+    const p = join(targetDir, file);
+    if (!existsSync(p)) continue;
+    try {
+      const body = readFileSync(p, 'utf8');
+      for (const n of names) {
+        if (new RegExp(`^${n}=`, 'm').test(body)) return true;
+      }
+    } catch {}
+  }
+  return false;
+}
+
+export async function applyPrivate({ targetDir, profile = null, force = false } = {}) {
+  if (detectSaas(targetDir, profile)) {
+    throw new PrivateError('PRIVATE_SAAS_CONFLICT', SAAS_CONFLICT_MSG);
+  }
+
+  const manifestPath = join(targetDir, PRIVATE_MANIFEST_PATH);
+  if (existsSync(manifestPath) && !force) {
+    throw new PrivateError(
+      'PRIVATE_ALREADY_APPLIED',
+      `${PRIVATE_MANIFEST_PATH} already exists. Run 'ostup private remove' first, or pass --force.`,
+    );
+  }
+
+  const useKv = envMentions(targetDir, ['KV_URL', 'KV_REST_API_URL']);
+  const ops = plannedOperations(targetDir, useKv);
+
+  const performed = [];
+
+  for (const op of ops) {
+    const destPath = join(targetDir, op.dest);
+
+    if (op.kind === 'create') {
+      if (existsSync(destPath) && !force) {
+        throw new PrivateError(
+          'PRIVATE_DIRTY',
+          `${op.dest} already exists; refusing to overwrite without --force.`,
+        );
+      }
+      const content = await loadTemplate(op.src);
+      await mkdir(dirname(destPath), { recursive: true });
+      await writeFile(destPath, content, 'utf8');
+      performed.push({ kind: 'created', path: op.dest });
+    } else if (op.kind === 'patch') {
+      if (!existsSync(destPath)) {
+        // Patching a missing file is a soft-skip (e.g. no app/layout.tsx exists).
+        continue;
+      }
+      const prior = await readFile(destPath, 'utf8');
+      let next;
+      if (op.mode === 'append') {
+        const addition = await loadTemplate(op.src);
+        if (prior.includes('# PART 20: PRIVACY DEFAULT-DENY')) {
+          continue;
+        }
+        next = prior + addition;
+      } else if (op.mode === 'layout-robots') {
+        next = patchLayoutRobots(prior);
+        if (next === prior) continue;
+      } else {
+        continue;
+      }
+      await writeFile(destPath, next, 'utf8');
+      performed.push({ kind: 'patched', path: op.dest, prior });
+    }
+  }
+
+  await mkdir(dirname(manifestPath), { recursive: true });
+  await writeFile(
+    manifestPath,
+    JSON.stringify(
+      {
+        appliedAt: new Date().toISOString(),
+        useKvRateLimit: useKv,
+        ops: performed,
+      },
+      null,
+      2,
+    ) + '\n',
+    'utf8',
+  );
+
+  return { applied: true, touched: performed.map((p) => p.path), useKvRateLimit: useKv };
+}
+
+export async function removePrivate({ targetDir, force = false } = {}) {
+  const manifestPath = join(targetDir, PRIVATE_MANIFEST_PATH);
+  if (!existsSync(manifestPath)) {
+    throw new PrivateError('PRIVATE_NOT_APPLIED', `${PRIVATE_MANIFEST_PATH} not found; nothing to remove.`);
+  }
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+  const restored = [];
+
+  // Walk in reverse so dependent files come back in the right order.
+  for (const op of [...manifest.ops].reverse()) {
+    const p = join(targetDir, op.path);
+    if (op.kind === 'created') {
+      if (existsSync(p)) {
+        await rm(p, { force: true });
+        restored.push({ kind: 'deleted', path: op.path });
+      }
+    } else if (op.kind === 'patched') {
+      if (!existsSync(p)) {
+        if (!force) {
+          throw new PrivateError(
+            'PRIVATE_DIRTY',
+            `${op.path} is gone; cannot restore. Re-add the file or pass --force to skip.`,
+          );
+        }
+        continue;
+      }
+      // Optional: integrity check against prior. Skipped in v1.
+      await writeFile(p, op.prior, 'utf8');
+      restored.push({ kind: 'restored', path: op.path });
+    }
+  }
+
+  await rm(manifestPath, { force: true });
+  // Best-effort: remove empty .ostup/ dir.
+  try {
+    await rm(join(targetDir, '.ostup'), { recursive: false });
+  } catch {}
+
+  return { restored: restored.map((r) => r.path) };
+}
+
+export async function statusPrivate({ targetDir } = {}) {
+  const manifestPath = join(targetDir, PRIVATE_MANIFEST_PATH);
+  if (!existsSync(manifestPath)) {
+    return { applied: false, manifest: null };
+  }
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+  return { applied: true, manifest };
+}
+
+export { PrivateError };