@magoz/provision 0.0.0-stage → 0.1.0

package/dist/shared/env-file.js

@@ -0,0 +1,54 @@
+import { Effect, Redacted } from 'effect';
+import { readPrivately, writePrivately } from './private-file.js';
+/** Parses `KEY=value` lines; blank lines and comments are skipped, matching quotes are removed. */
+export const parseEnvFile = (content) => {
+    const entries = new Map();
+    for (const raw of content.split('\n')) {
+        const line = raw.trim();
+        if (line.length === 0 || line.startsWith('#'))
+            continue;
+        const index = line.indexOf('=');
+        if (index <= 0)
+            continue;
+        let value = line.slice(index + 1).trim();
+        if (value.length >= 2 &&
+            ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'")))) {
+            value = value.slice(1, -1);
+        }
+        entries.set(line.slice(0, index).trim(), value);
+    }
+    return entries;
+};
+export const envKeyPattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const declares = (line, key) => line.startsWith(`${key}=`);
+const readLines = (file) => readPrivately(file).pipe(Effect.map(content => (content === undefined ? [] : content.split('\n'))));
+/** Whether `file` exists and declares every key. */
+export const hasEnvKeys = (file, keys) => readPrivately(file).pipe(Effect.map(content => {
+    if (content === undefined)
+        return false;
+    const lines = content.split('\n');
+    return keys.every(key => lines.some(line => declares(line, key)));
+}));
+/**
+ * Replaces `keys` in `file`, keeping every other line. The only place redacted values are
+ * unwrapped for writing.
+ */
+export const writeEnvKeys = (file, values) => Effect.gen(function* () {
+    const existing = yield* readLines(file);
+    const keys = values.map(([key]) => key);
+    const kept = existing.filter(line => !keys.some(key => declares(line, key)));
+    while (kept.at(-1)?.trim() === '')
+        kept.pop();
+    const rendered = values.map(([key, value]) => `${key}=${Redacted.value(value)}`);
+    yield* writePrivately(file, `${[...kept, ...rendered].join('\n')}\n`);
+});
+/** Removes `keys` from `file`; a missing file is left alone. */
+export const removeEnvKeys = (file, keys) => Effect.gen(function* () {
+    const content = yield* readPrivately(file);
+    if (content === undefined)
+        return;
+    const kept = content.split('\n').filter(line => !keys.some(key => declares(line, key)));
+    const body = kept.join('\n').trimEnd();
+    yield* writePrivately(file, body.length > 0 ? `${body}\n` : '');
+});

package/dist/shared/git.js

@@ -0,0 +1,48 @@
+import { Data, Effect, FileSystem, Option, Path } from 'effect';
+import { capture } from './process.js';
+export class WorkspaceError extends Data.TaggedError('WorkspaceError') {
+}
+export class SecretPathError extends Data.TaggedError('SecretPathError') {
+}
+/** Trimmed stdout of a git command, or `None` when it fails or cannot run. */
+export const gitOutput = (cwd, args) => capture('git', ['-C', cwd, ...args]).pipe(Effect.map(result => result.exitCode === 0 ? Option.some(result.stdout.trim()) : Option.none()), Effect.orElseSucceed(() => Option.none()));
+export const gitSucceeds = (cwd, args) => capture('git', ['-C', cwd, ...args]).pipe(Effect.map(result => result.exitCode === 0), Effect.orElseSucceed(() => false));
+export const repositoryFromRemote = (url) => /[:/]([^/:]+\/[^/]+?)(?:\.git)?\/?$/.exec(url.trim())?.[1];
+/** Resolves and validates a Git checkout root; anything outside Git is refused. */
+export const resolveWorkspace = (requested) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const fs = yield* FileSystem.FileSystem;
+    const candidate = path.resolve(Option.getOrElse(requested, () => process.cwd()));
+    const isDirectory = yield* fs.stat(candidate).pipe(Effect.map(info => info.type === 'Directory'), Effect.orElseSucceed(() => false));
+    if (!isDirectory) {
+        return yield* new WorkspaceError({ message: `not a directory: ${candidate}` });
+    }
+    const inside = yield* gitOutput(candidate, ['rev-parse', '--is-inside-work-tree']);
+    if (Option.getOrElse(inside, () => '') !== 'true') {
+        return yield* new WorkspaceError({ message: `not inside a git worktree: ${candidate}` });
+    }
+    const top = yield* gitOutput(candidate, ['rev-parse', '--show-toplevel']);
+    const root = path.resolve(Option.getOrElse(top, () => candidate));
+    const remote = yield* gitOutput(root, ['remote', 'get-url', 'origin']);
+    const repository = Option.match(remote, {
+        onNone: () => path.basename(root),
+        onSome: url => repositoryFromRemote(url) ?? path.basename(root)
+    });
+    return { root, repository };
+});
+/**
+ * Secrets may only be written to a path Git will never track. This is the guardrail that makes
+ * automatic provisioning safe.
+ */
+export const ensureIgnored = (root, file) => Effect.gen(function* () {
+    if (yield* gitSucceeds(root, ['ls-files', '--error-unmatch', '--', file])) {
+        return yield* new SecretPathError({
+            message: `refusing to write secrets: ${file} is tracked by git`
+        });
+    }
+    if (!(yield* gitSucceeds(root, ['check-ignore', '-q', '--', file]))) {
+        return yield* new SecretPathError({
+            message: `refusing to write secrets: ${file} is not git-ignored\nadd it to .gitignore first`
+        });
+    }
+});

package/dist/shared/output.js

@@ -0,0 +1,10 @@
+import { Console } from 'effect';
+/** Prints a flat report: pretty JSON with `--json`, otherwise aligned `key  value` lines. */
+export const report = (json, payload) => {
+    if (json)
+        return Console.log(JSON.stringify(payload, null, 2));
+    const width = Math.max(0, ...Object.keys(payload).map(key => key.length));
+    return Console.log(Object.entries(payload)
+        .map(([key, value]) => `${key.padEnd(width)}  ${String(value)}`)
+        .join('\n'));
+};

package/dist/shared/private-file.js

@@ -0,0 +1,63 @@
+import { randomBytes } from 'node:crypto';
+import * as NodeFs from 'node:fs/promises';
+import { Data, Effect, Predicate } from 'effect';
+export class PrivateFileError extends Data.TaggedError('PrivateFileError') {
+}
+const isMissing = (cause) => Predicate.hasProperty(cause, 'code') && cause.code === 'ENOENT';
+/** Fails when `file` is a symbolic link (dangling links included); a missing path is fine. */
+export const ensureNotSymlink = (file) => Effect.tryPromise({
+    try: async () => {
+        try {
+            if ((await NodeFs.lstat(file)).isSymbolicLink())
+                throw new Error('symbolic link');
+        }
+        catch (cause) {
+            if (isMissing(cause))
+                return;
+            throw cause;
+        }
+    },
+    catch: () => new PrivateFileError({
+        reason: 'symbolic-link',
+        message: `refusing symbolic-link path: ${file}`
+    })
+});
+/**
+ * Atomically replaces `file` with `content`, mode `0600` from the first byte. The temporary file is
+ * created exclusively next to the target and removed if anything fails.
+ */
+export const writePrivately = (file, content) => Effect.gen(function* () {
+    yield* ensureNotSymlink(file);
+    const temporary = `${file}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+    yield* Effect.tryPromise({
+        try: async () => {
+            try {
+                await NodeFs.writeFile(temporary, content, { flag: 'wx', mode: 0o600 });
+                await NodeFs.chmod(temporary, 0o600);
+                await NodeFs.rename(temporary, file);
+            }
+            catch (cause) {
+                await NodeFs.rm(temporary, { force: true }).catch(() => undefined);
+                throw cause;
+            }
+        },
+        catch: () => new PrivateFileError({ reason: 'io', message: `private atomic write failed: ${file}` })
+    });
+});
+/** Reads `file`, refusing symbolic links; a missing file reads as `undefined`. */
+export const readPrivately = (file) => Effect.gen(function* () {
+    yield* ensureNotSymlink(file);
+    return yield* Effect.tryPromise({
+        try: async () => {
+            try {
+                return await NodeFs.readFile(file, 'utf8');
+            }
+            catch (cause) {
+                if (isMissing(cause))
+                    return undefined;
+                throw cause;
+            }
+        },
+        catch: () => new PrivateFileError({ reason: 'io', message: `cannot read ${file}` })
+    });
+});

package/dist/shared/process.js

@@ -0,0 +1,55 @@
+import { Context, Data, Effect, Layer, Stream } from 'effect';
+import { ChildProcess, ChildProcessSpawner } from 'effect/process';
+export class ProcessError extends Data.TaggedError('ProcessError') {
+    get message() {
+        return this.exitCode === undefined
+            ? `${this.command}: could not be started`
+            : `${this.command}: exited with ${this.exitCode}`;
+    }
+}
+export class ProcessRunner extends Context.Service()('provision/ProcessRunner') {
+}
+const notStarted = (command) => () => new ProcessError({ command, exitCode: undefined });
+export const makeProcessRunner = Effect.gen(function* () {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    return ProcessRunner.of({
+        capture: (command, args, options = {}) => Effect.scoped(Effect.gen(function* () {
+            const handle = yield* spawner.spawn(ChildProcess.make(command, args, {
+                cwd: options.cwd,
+                ...(options.env === undefined ? {} : { env: options.env, extendEnv: true }),
+                stdin: options.interactive === true
+                    ? 'inherit'
+                    : options.input === undefined
+                        ? 'ignore'
+                        : Stream.make(new TextEncoder().encode(options.input)),
+                stdout: 'pipe',
+                stderr: options.interactive === true ? 'inherit' : 'pipe'
+            }));
+            const [stdout, stderr, exitCode] = yield* Effect.all([
+                Stream.mkString(Stream.decodeText(handle.stdout)),
+                options.interactive === true
+                    ? Effect.succeed('')
+                    : Stream.mkString(Stream.decodeText(handle.stderr)),
+                handle.exitCode
+            ], { concurrency: 3 });
+            return { exitCode, stdout, stderr };
+        })).pipe(Effect.mapError(notStarted(command))),
+        inherit: (command, args, options = {}) => Effect.scoped(Effect.gen(function* () {
+            const handle = yield* spawner.spawn(ChildProcess.make(command, args, {
+                cwd: options.cwd,
+                ...(options.env === undefined ? {} : { env: options.env, extendEnv: true }),
+                stdin: 'inherit',
+                stdout: 'inherit',
+                stderr: 'inherit'
+            }));
+            return yield* handle.exitCode;
+        })).pipe(Effect.mapError(notStarted(command)), Effect.flatMap(exitCode => exitCode === 0 ? Effect.void : Effect.fail(new ProcessError({ command, exitCode }))))
+    });
+});
+export const ProcessRunnerLive = Layer.effect(ProcessRunner, makeProcessRunner);
+export const capture = (command, args, options) => Effect.gen(function* () {
+    return yield* (yield* ProcessRunner).capture(command, args, options);
+});
+export const inherit = (command, args, options) => Effect.gen(function* () {
+    return yield* (yield* ProcessRunner).inherit(command, args, options);
+});

package/dist/shared/repo-config.js

@@ -0,0 +1,104 @@
+import { posix } from 'node:path';
+import { Data, Effect, FileSystem, Path, Predicate, Schema } from 'effect';
+/** Factory steps in execution order. `--only` and `provision.factory.steps` select a subset. */
+export const factorySteps = [
+    'vercel',
+    'neon',
+    'r2',
+    'upstash',
+    'resend',
+    'reports',
+    'secrets',
+    'domain'
+];
+/**
+ * How the Neon development project provides the parent branch for disposable databases:
+ * - `empty-baseline`: the factory owns the `<repo>-dev` project and its protected, empty default
+ *   `baseline` branch; `setup` migrates. `provision db` attests this before every mutation;
+ * - `existing-branch`: the repository maintains its own development data and branch.
+ *
+ * Undeclared (`undefined`): `provision db` skips the attestation; `provision factory` treats it as
+ * `empty-baseline`.
+ */
+export const sandboxParentModes = ['empty-baseline', 'existing-branch'];
+export class RepoConfigError extends Data.TaggedError('RepoConfigError') {
+}
+const SetupCommand = Schema.Trimmed.check(Schema.isNonEmpty());
+const ProvisionInput = Schema.Struct({
+    appDir: Schema.optionalKey(Schema.NonEmptyString),
+    setup: Schema.optionalKey(Schema.Array(SetupCommand)),
+    factory: Schema.optionalKey(Schema.Struct({
+        steps: Schema.optionalKey(Schema.NonEmptyArray(Schema.Literals(factorySteps)).check(Schema.isUnique())),
+        neon: Schema.optionalKey(Schema.Struct({
+            sandboxParent: Schema.optionalKey(Schema.Literals(sandboxParentModes))
+        }))
+    }))
+});
+const PackageJson = Schema.Struct({
+    provision: Schema.optionalKey(Schema.Unknown),
+    provisionEnv: Schema.optionalKey(Schema.Unknown),
+    worktree: Schema.optionalKey(Schema.Unknown)
+});
+const decodePackageJson = Schema.decodeUnknownEffect(Schema.fromJsonString(PackageJson));
+const decodeProvision = Schema.decodeUnknownEffect(ProvisionInput, {
+    onExcessProperty: 'error',
+    errors: 'all'
+});
+const decodeLegacy = Schema.decodeUnknownEffect(Schema.Struct({
+    appDir: Schema.optionalKey(Schema.UndefinedOr(Schema.NonEmptyString)),
+    setup: Schema.optionalKey(Schema.UndefinedOr(Schema.Array(SetupCommand)))
+}));
+const configError = (message) => new RepoConfigError({ message });
+export const normalizeAppDir = (appDir) => {
+    if (appDir.includes('\\') || posix.isAbsolute(appDir))
+        return undefined;
+    const normalized = posix.normalize(appDir).replace(/\/+$/, '');
+    if (normalized === '' || normalized === '..' || normalized.startsWith('../'))
+        return undefined;
+    return normalized;
+};
+export const defaultRepoConfig = {
+    appDir: '.',
+    setup: [],
+    factory: { steps: factorySteps, neon: { sandboxParent: undefined } }
+};
+/** Parses root `package.json` text into a resolved {@link RepoConfig}. */
+export const parseRepoConfig = (packageJsonText) => Effect.gen(function* () {
+    const packageJson = yield* decodePackageJson(packageJsonText).pipe(Effect.mapError(cause => configError(`invalid package.json: ${cause.message}`)));
+    // Transition: legacy keys still used by the `worktree` CLI are read as fallbacks.
+    const legacy = yield* decodeLegacy({
+        appDir: Predicate.hasProperty(packageJson.provisionEnv, 'appDir')
+            ? packageJson.provisionEnv.appDir
+            : undefined,
+        setup: Predicate.hasProperty(packageJson.worktree, 'setup')
+            ? packageJson.worktree.setup
+            : undefined
+    }).pipe(Effect.mapError(cause => configError(`invalid package.json "provisionEnv"/"worktree.setup": ${cause.message}`)));
+    const input = yield* decodeProvision(packageJson.provision ?? {}).pipe(Effect.mapError(cause => configError(`invalid package.json "provision": ${cause.message}`)));
+    const appDir = normalizeAppDir(input.appDir ?? legacy.appDir ?? '.');
+    if (appDir === undefined) {
+        return yield* configError('package.json "provision.appDir" must be a relative path inside the checkout');
+    }
+    const selected = input.factory?.steps;
+    return {
+        appDir,
+        setup: input.setup ?? legacy.setup ?? [],
+        factory: {
+            steps: selected === undefined
+                ? factorySteps
+                : factorySteps.filter(step => selected.includes(step)),
+            neon: { sandboxParent: input.factory?.neon?.sandboxParent }
+        }
+    };
+});
+/** Reads the checkout root's `package.json`; a checkout without one uses the defaults. */
+export const readRepoConfig = (checkoutRoot) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const file = path.join(checkoutRoot, 'package.json');
+    const exists = yield* fs.exists(file);
+    if (!exists)
+        return defaultRepoConfig;
+    const text = yield* fs.readFileString(file);
+    return yield* parseRepoConfig(text);
+}).pipe(Effect.catchTag('PlatformError', cause => Effect.fail(configError(`cannot read package.json: ${cause.message}`))));

package/dist/shared/sandbox-profile.js

@@ -0,0 +1,12 @@
+/**
+ * The sandbox database profile: written to the Vercel Development environment by
+ * `provision factory`, pulled into `.env.local` by `provision env`, and read by `provision db`.
+ * All three keys are required together.
+ */
+export const sandboxProfileKeys = [
+    'SANDBOX_DB_NEON_API_KEY',
+    'SANDBOX_DB_NEON_PROJECT_ID',
+    'SANDBOX_DB_PARENT_BRANCH_ID'
+];
+/** Env keys `provision db create` writes by default. */
+export const defaultDatabaseUrlKeys = ['DATABASE_URL', 'DATABASE_URL_UNPOOLED'];

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@magoz/provision",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Provision projects (factory), local checkouts (env), and disposable databases (db).",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/magoz/provision.git"
+  },
+  "bin": {
+    "provision": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "type": "module",
+  "scripts": {
+    "dev": "node src/cli.ts",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "oxlint --max-warnings 0",
+    "lint:fix": "oxlint --fix",
+    "format:check": "oxfmt --check .",
+    "format:fix": "oxfmt --write .",
+    "test": "vitest run",
+    "verify": "pnpm format:check && pnpm typecheck && pnpm lint && pnpm test && pnpm build",
+    "prepublishOnly": "pnpm verify"
+  },
+  "dependencies": {
+    "@effect/platform-node": "4.0.2",
+    "effect": "4.0.2"
+  },
+  "devDependencies": {
+    "@effect/vitest": "4.0.2",
+    "@types/node": "24.19.1",
+    "oxfmt": "0.72.0",
+    "oxlint": "1.87.0",
+    "typescript": "7.0.2",
+    "vitest": "5.0.3"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "packageManager": "pnpm@12.10.1"
+}

package/skills/provision/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: provision
+description: Use the provision CLI to make a checkout or worktree runnable (dependencies, Vercel link, env files, setup commands), manage disposable Neon databases for local checkouts, and prepare provision factory runs that create a project's provider resources. Use when a checkout needs env files or databases, when a repository's package.json has a "provision" key, or when the user mentions provision, factories, sandbox databases, or provisioning a new project.
+---
+
+# provision
+
+`provision` has three modes:
+
+- `provision env`: make a checkout runnable.
+- `provision db`: manage disposable Neon database branches for local checkouts.
+- `provision factory`: create a project's provider resources and write scoped keys to Vercel.
+
+Run `provision <mode> --help` for every flag. The repository's root `package.json` `provision` key
+configures it (`appDir`, `setup`, `factory.steps`).
+
+## What you may run, and what only the human may run
+
+| Command                                                           | Who                              |
+| ----------------------------------------------------------------- | -------------------------------- |
+| `provision env …`, `provision db …`, `provision contract`         | you                              |
+| `provision config list`, `provision config op-token status`       | you                              |
+| `provision factory …`, `provision config add/verify/op-token set` | **the human, in their terminal** |
+
+Commands that read a factory's 1Password item need the operator's **provision passphrase**, typed
+on the terminal. That passphrase is the human's approval for using admin keys.
+
+When you run one of them, `provision` detects the agent, changes nothing, and exits **4** with one
+JSON object on stderr:
+
+```json
+{
+  "status": "approval_required",
+  "reason": "…",
+  "hint": "…",
+  "next": [
+    "cd /home/acme/src/acme-app && /usr/local/bin/provision factory --domain app.acme.com --dry-run"
+  ]
+}
+```
+
+Give the human the `next` command verbatim, say in one or two sentences what it will do, and wait
+for them to paste the output. You may also skip the attempt and write the command yourself; use
+`/usr/local/bin/provision` when it exists, since a `provision` earlier on `PATH` could be a
+different binary.
+
+Agents are also detected for `provision env`, which then never prompts (as with
+`--non-interactive`).
+
+## Make a checkout or worktree runnable
+
+```bash
+provision env --repo <checkout> --database --non-interactive
+```
+
+This installs dependencies, links the Vercel project, pulls Development into `.env.local` and the
+`test` environment into `.env.test`, creates two disposable databases (`default` and `test`
+leases), and runs `package.json` `provision.setup` (usually migrations). Without `--database` the
+env files keep whatever database Vercel provides; prefer `--database` for anything that writes data.
+
+- **Exit 3** (`{"status":"vercel_link_required",…}` on stderr): the app is not linked and the
+  project is ambiguous. Rerun with `--source <already-linked checkout>` or
+  `--vercel-project <name>`; ask the human which project if you cannot tell.
+- **Setup failed**: env files and databases are kept. Fix the cause, then rerun the same command;
+  it resumes. `--skip-setup` skips setup on purpose.
+- **Existing env files**: refreshed from Vercel by default. `--env-conflict preserve` keeps them.
+- Never print `.env*` files or connection strings; they hold secrets. Check for a key with
+  `grep -c '^KEY=' .env.local` instead of reading values.
+
+## Add or change an environment variable
+
+Vercel is the source of truth. `provision env` rewrites `.env.local` and `.env.test` from Vercel on
+every run, so a value added only to a local file is lost. Add it to the Vercel project, then pull:
+
+```bash
+cd <checkout>   # linked to the project (.vercel/project.json)
+vercel env add <KEY> development               # local development only
+vercel env add <KEY> preview                   # repeat per environment as needed
+vercel env add <KEY> test                      # the custom e2e environment (.env.test)
+vercel env add <KEY> production --sensitive    # production secrets are Sensitive
+provision env --repo <checkout> --skip-install --skip-setup   # refresh the env files
+```
+
+Follow the project's convention: pre-production values (Development, Preview, `test`) and
+production values are separate, and production secrets are Sensitive. Development cannot hold
+Sensitive values.
+
+- **Secrets** (API keys, tokens): don't handle the value. Give the human the `vercel env add`
+  command; it prompts for the value. Never pass a secret with `--value` or put it in a file,
+  commit, or the chat.
+- **Non-secret config** (URLs, feature flags, thresholds): you may run
+  `vercel env add <KEY> <environment> --value <value> --yes` yourself.
+- **Variables `provision factory` manages** (`DATABASE_URL*`, `SANDBOX_DB_*`, `R2_*`, `QSTASH_*`,
+  `RESEND_API_KEY`, `REPORT_RECEIVER_*`, `BETTER_AUTH_SECRET`, `INTEGRATION_CREDENTIAL_ENCRYPTION_KEY`,
+  `CRON_SECRET`, `VAPID_*`, `AUTH_EMAIL_FROM`, `AI_PROVIDER_USAGE_ALERT_THRESHOLDS`,
+  `ALLOW_E2E_DATABASE_RESET`): don't edit them by hand. Have the human rerun the step, e.g.
+  `--only resend --on-existing overwrite` to rotate a key.
+- Deployments only see variables added before they were built; redeploy to pick up a change.
+
+## Disposable databases
+
+```bash
+provision db status  --worktree <checkout> --lease default --json   # exit 1: no lease
+provision db renew   --worktree <checkout> --lease default          # extend TTL (max 7d)
+provision db create  --worktree <checkout> --lease default          # create, or reuse a live lease
+provision db create  --worktree <checkout> --lease test \
+  --env-file .env.test --config-env-file .env.local                 # test lease writes .env.test
+provision db release --worktree <checkout> --lease default          # delete branch, drop env keys
+provision db release --worktree <checkout> --lease test
+provision db list --json
+```
+
+Release both leases before deleting a worktree. Branches expire on their own after their TTL;
+`provision db gc --dry-run` lists stale ones. A database whose TTL ran out is gone: rerun
+`provision env --repo <checkout> --database`, which recreates both leases and reruns setup.
+
+## Provision a new project (human runs it)
+
+Prerequisites: the GitHub repository exists under the factory's GitHub owner, there is a local
+checkout with that `origin`, and the factory is registered (`provision config list`).
+
+Prepare these for the human, in order:
+
+```bash
+# 1. Plan: reads providers, changes nothing
+/usr/local/bin/provision factory --checkout <checkout> --domain <production-host> --dry-run
+
+# 2. Apply
+/usr/local/bin/provision factory --checkout <checkout> --domain <production-host> \
+  --sender-name <App name> --email-from noreply@<verified-domain>
+
+# 3. Confirm idempotence: should print only "reusing" lines
+/usr/local/bin/provision factory --checkout <checkout> --domain <production-host> \
+  --sender-name <App name> --email-from noreply@<verified-domain> --on-existing reuse
+
+# 4. Local checkout (you can run this one)
+provision env --repo <checkout> --database
+```
+
+Reading the output: each step prints one block. `would …` is a dry-run plan, `exists:` /
+`reusing …` means nothing changed, `skipped:` means the factory lacks that provider, and
+`manual: …` is a follow-up the human must do by hand. Relay `manual:` lines to the human.
+
+QStash credentials are pasted by the human when `provision factory` asks for them (hidden input,
+written straight to Vercel). If they skipped it, give them
+`/usr/local/bin/provision factory --checkout <checkout> --domain <host> --only upstash --on-existing reuse`.
+Never ask the human to paste QStash values, or any other credential, into the chat.
+
+`--on-existing`: `ask` (default, prompts), `reuse` (change nothing that exists), `overwrite`
+(rotate keys and regenerate secrets: invalidates sessions and encrypted data; only on the human's
+explicit request), `abort`. Data (databases, buckets, teams) is never deleted or replaced.
+`--only <steps>` reruns a subset, e.g. `--only reports` after the factory gains a report receiver.
+
+## Never
+
+- Run a passphrase command in a way that gets around the approval: piping input, `script`,
+  `expect`, `tmux send-keys`, a pseudo-terminal, or unsetting agent variables such as `AI_AGENT`.
+- Ask the human for the passphrase, a 1Password token, or an admin key; set
+  `OP_SERVICE_ACCOUNT_TOKEN`; run `op`; or read `~/.config/provision/*.cred`.
+- Print `.env*` files, connection strings, or keys, or copy them into chat, commits, or logs.
+- Pass `--on-existing overwrite` unless the human asked to rotate: it invalidates sessions and
+  encrypted data.
+- Delete provider resources (Neon projects, R2 buckets, Upstash teams, Vercel projects) to "start
+  over"; `provision` reuses what exists.
+- Delete a worktree before `provision db release` for both leases.
+- Edit `~/.config/provision/` or the lease files under `~/.local/state/pi/sandbox-db/` by hand.
+
+## Exit codes
+
+`0` success; `1` negative result (for example no lease) or usage error; `2` failure, explained in
+one `provision <mode>: …` line on stderr; `3` `env` needs a Vercel link (JSON on stderr); `4` a
+human must run this command (JSON with `next` on stderr).