verity-framework 0.1.0 → 0.2.1

package/README.md

@@ -2,29 +2,92 @@
 
 **Prompt to production, proven.**
 
-Verity is a CI/CD-native, GitHub-native, production-lifecycle AI software delivery framework — a clean-room successor to [spec-driven-devops](https://www.npmjs.com/package/spec-driven-devops) 1.4 for projects that go *beyond MVP* into real, operated production.
+Most AI coding tools stop when the code is written — leaving you to find out later whether it runs, deploys, or actually works. **Verity keeps going.** It carries a project from an idea all the way to software that is tested, deployed, and **proven working in front of a real user** — and then keeps it running.
 
-Most AI coding tools stop when the code is written. Verity keeps going until the software is tested, deployed, and **proven working in front of a user**. It runs a project as a sequence of specialized AI roles (architect, builder, reviewer, release operator, verifier…) that hand work off through clear contracts, with GitHub as the source of truth.
+It does that by running your project as a sequence of specialized AI roles — a vision assistant, an architect, a builder, a reviewer, a release operator, a verifier, and more — that hand work to each other through clear contracts, with **GitHub as the single source of truth**. It's CI/CD-native and GitHub-native by design, built for projects going *beyond a prototype* into real, operated production. (Verity is a clean-room successor to [spec-driven-devops](https://www.npmjs.com/package/spec-driven-devops) 1.4.)
 
-> **Status: design complete, pre-implementation.** This repo currently tracks the design. Implementation begins with Verity's own *walking skeleton* — see [`docs/walking-skeleton-plan.md`](docs/walking-skeleton-plan.md).
+> 📦 On npm as [`verity-framework`](https://www.npmjs.com/package/verity-framework) · works with **Claude Code** and **OpenCode**.
 
-## Subsystems
-- **Relay** — role orchestration + the stream loop + dependency engine
-- **Shipyard** — CI/CD spine + Release/Deploy Operator + runtime truth (`STATUS.md`)
-- **Ledger** — GitHub-derived state engine (no stale files)
-- **Gate** — review + security + the quality gates
-- **Verify** — live "observably-works" verification
+## What makes it different
 
-## Docs
-- [`docs/framework-spec.md`](docs/framework-spec.md) — the build-ready architecture spec
-- [`docs/roles-spec.md`](docs/roles-spec.md) — working log + full rationale (all 14 roles)
-- [`docs/interview-findings.md`](docs/interview-findings.md) — forensic interview of the real build that drove the design
-- [`docs/brand.md`](docs/brand.md) — naming / positioning
-- [`docs/features/helper-bot.md`](docs/features/helper-bot.md) — drop-in feature #1
-- [`docs/walking-skeleton-plan.md`](docs/walking-skeleton-plan.md) — the first implementation slice
+- **"Done" means proven, not written.** Every change is reviewed, deployed, and driven like a real user before it counts as finished.
+- **The AI decides; a deterministic tool records.** The `verity` CLI is the "notebook" that never forgets — it holds the rules and the official state, so a forgetful model (or a brand-new chat) can always pick up exactly where things left off.
+- **State is read from GitHub, never a file that drifts.** A merged PR *is* "built"; a tag *is* "released." Nothing to hand-maintain, nothing to lie about.
+- **Specialist roles with real handoffs** beat one mega-prompt trying to do everything.
 
-## Package
-`verity-framework` (npm) · CLI binary: `verity` · Node ≥16 · host deps: `git`, `gh`
+## How it works
 
-## License
-MIT
+A Verity project moves through three arcs:
+
+1. **Bootstrap** *(once)* — name the project, create the repo, design the architecture, choose where it deploys, and prove the whole build→ship pipeline on a tiny end-to-end "walking skeleton."
+2. **Stream** *(the loop)* — every feature flows through the same short cycle: **plan → build → review → merge**, riding that proven pipeline.
+3. **Operate** *(continuous)* — cut releases, deploy, **verify on the live app**, and keep it healthy.
+
+Five subsystems carry that out:
+
+| Subsystem | Job |
+|---|---|
+| **Relay** | Orchestrates the roles, the stream loop, and the dependency engine |
+| **Shipyard** | The CI/CD spine — releases, deploys, the deployment-methods catalog, and runtime truth (`STATUS.md`) |
+| **Ledger** | Derives state from GitHub, so nothing goes stale |
+| **Gate** | Review, security, and the quality gates |
+| **Verify** | Live "observably-works" verification |
+
+## Install
+
+**Prerequisites:** a GitHub account · Node ≥16 · `git` and the GitHub CLI (`gh`) installed **and signed in** (run `gh auth login` once — installing `gh` is not the same as being authenticated).
+
+```bash
+# preflight — all three should answer without error:
+node -v && git --version && gh auth status
+
+# install, then connect it to your assistant:
+npm i -g verity-framework
+verity install --claude        # or: --opencode
+```
+
+Then, in your AI assistant, start a project with `/verity:vision`. The [interactive guides](#guides) walk through it step by step.
+
+## Deployment methods
+
+Verity makes **where your app deploys a deliberate choice**, not an accident. Left alone, an AI agent picks a host by whatever happens to be wired into its environment — suggesting Render.com, say, just because a Render tool is installed. The deployment-methods catalog fixes that: the **Architect** reads your saved targets and works with you to choose one (recording it as an ADR), and if none are configured yet it asks how you want to deploy and offers suggestions.
+
+It's **two files, two scopes** — and crucially, no secrets ever touch git:
+
+| | Global catalog | Per-app access |
+|---|---|---|
+| **Path** | `~/.verity/deployment-methods.md` | `.verity/deploy-access.md` |
+| **Scope** | You, across *every* project | One app |
+| **Holds** | The deploy targets you *can* use | How to reach *this* app's host |
+| **Created** | At `verity install` — seeded once, never overwritten | Written by the Architect, per app |
+| **In git?** | No (lives in your home dir) | **No — gitignored.** A committed, secret-free pointer tells teammates who lack it to ask the project admin |
+
+> 🔒 Both files reference credential **locations** — a key file like `~/.ssh/prod.pem`, an SSO profile, a secret-store entry — never an actual key, password, or token. The per-app file is shared out-of-band, so nothing sensitive lands in git history. (Same rule as `STATUS.md`.)
+
+The global catalog ships with two worked examples (AWS EC2 over SSH, and a local-network server). Edit it to describe your real targets:
+
+```bash
+verity deployment list           # your targets (this is what the Architect reads)
+verity deployment show aws-ec2   # one target's details
+verity deployment edit           # open the catalog in $EDITOR
+verity deployment path           # where the catalog lives
+```
+
+When the Architect picks a target it sets up the per-app access file — `verity deployment init-access` gitignores the real file and commits the "ask the admin" pointer — then writes `.verity/deploy-access.md` with how to reach this app's host. From there, `/verity:ship` deploys to that target. (`verity deployment access` tells a teammate whether they have the file, and who to ask if not.)
+
+## Guides
+
+Interactive, beginner-friendly, and fully self-contained — clone or download the repo and open them in any browser (no server or internet needed):
+
+- [**Overview**](docs/verity-overview.html) — what Verity is and the mental model, no jargon assumed
+- [**Usage**](docs/verity-usage.html) — install + command-by-command recipes + pro tips (Claude Code / OpenCode toggle)
+- [**Flows**](docs/verity-flows.html) — start-from-scratch vs. add-to-an-existing-project, side by side ([editable `.drawio`](docs/verity-flows.drawio))
+- [**Command reference**](docs/commands.md) — all 13 `/verity:*` roles and what each one does
+- [**Explainer kit**](docs/explainer-kit.md) — a briefing for an AI to describe Verity to humans (podcast / deck / talk)
+
+## Reference
+
+- **Package:** `verity-framework` · CLI binary `verity` · Node ≥16 · host deps `git`, `gh`
+- **Design docs:** [framework spec](docs/framework-spec.md) · [roles spec](docs/roles-spec.md) · [the interview that drove the design](docs/interview-findings.md) · [brand / positioning](docs/brand.md) · [walking-skeleton plan](docs/walking-skeleton-plan.md)
+- **Contributing:** [`CONTRIBUTING.md`](CONTRIBUTING.md) — local setup, the test/lint checks, project layout, and conventions
+- **License:** MIT

package/commands/verity/architect.md

@@ -34,24 +34,44 @@ and the walking-skeleton definition handed to /verity:plan.
    ```
    Then fill in Context / Decision / Alternatives considered / Consequences.
 
-3. **Freeze the core contracts** (wire/JWT/schema between components) — additive-only
+3. **Choose the deployment target.** Read the user's global catalog of where they can
+   deploy, and pick a target for THIS app — never assume one (don't reach for a host
+   just because its MCP/CLI happens to be installed):
+   ```bash
+   verity deployment list      # ~/.verity/deployment-methods.md (locations, not secrets)
+   ```
+   - Work with the user to choose a method; record the choice as an ADR.
+   - If `hasConfigured` is false (only the shipped examples remain), ASK how they want
+     to deploy and offer suggestions (managed PaaS, a VM over SSH, a local/LAN server…),
+     then help them add it: `verity deployment edit`.
+   - Set up the per-app access file (committed pointer + gitignore — no secrets in git):
+     ```bash
+     verity deployment init-access
+     ```
+     Then WRITE `.verity/deploy-access.md` with how to reach this app's host —
+     credential **locations** only (key files, SSO profiles, secret-store entries),
+     never raw secrets. That file is gitignored and shared out-of-band; teammates who
+     lack it are pointed at the project admin. The Release/Deploy Operator (`/verity:ship`)
+     consumes this target when it builds `deploy.sh`.
+
+4. **Freeze the core contracts** (wire/JWT/schema between components) — additive-only
    thereafter; a breaking change is a NEW contract, never an edit:
    ```bash
    verity contract new <seam-name>
    ```
 
-4. Offer the **drop-in feature catalog**. For each feature the user wants, note that
+5. Offer the **drop-in feature catalog**. For each feature the user wants, note that
    its stages will fold into the plan:
    ```bash
    verity feature list
    verity feature show <id>
    ```
 
-5. Define the **walking skeleton** (Stage 0): the thinnest end-to-end slice that
+6. Define the **walking skeleton** (Stage 0): the thinnest end-to-end slice that
    compiles, runs, passes one real test, goes green in CI, and deploys. This blocks
    all feature stages and proves the spine.
 
-6. Hand off to **/verity:plan** (Intake/Planner) to decompose the design + accepted
+7. Hand off to **/verity:plan** (Intake/Planner) to decompose the design + accepted
    features into the initial thin backlog of stages.
 
 Runtime note: if `verity` is not on PATH, use `node "$HOME/.claude/verity/bin/verity.cjs" ...`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verity-framework",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Verity — a CI/CD-native, GitHub-native, production-lifecycle AI software delivery framework.",
   "keywords": ["verity", "ai", "ci-cd", "github", "devops", "agent", "framework"],
   "author": "Sean Mahoney",

package/verity/bin/lib/deployment.cjs

@@ -0,0 +1,230 @@
+// Verity deployment methods (framework-spec.md — deployment-target feature).
+//
+// TWO scopes, deliberately separate:
+//
+//   1. GLOBAL catalog — `~/.verity/deployment-methods.md`. Your private inventory
+//      of where you CAN deploy (one per machine/user, reused across every project).
+//      Seeded at `verity install`, edited with `verity deployment edit`, read by the
+//      Architect with `verity deployment list`. Holds credential LOCATIONS, never
+//      secret values. NOT in any repo.
+//
+//   2. PER-PROJECT access file — `.verity/deploy-access.md`. Written by the Architect
+//      for ONE app: how to reach THAT app's host. Gitignored + shared out-of-band; a
+//      secret-free pointer (`.verity/deploy-access.README.md`) IS committed so a
+//      teammate without the file is told to get it from the project admin.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const identity = require('./identity.cjs');
+const { render } = require('./core.cjs');
+
+const TEMPLATES_DIR = path.join(__dirname, '..', '..', 'templates');
+
+const ACCESS_FILE = '.verity/deploy-access.md'; // gitignored real file
+const ACCESS_POINTER = '.verity/deploy-access.README.md'; // committed pointer
+
+function readTemplate(name) {
+  return fs.readFileSync(path.join(TEMPLATES_DIR, name), 'utf8');
+}
+
+// --- GLOBAL catalog -------------------------------------------------------
+
+// User-global, harness-independent, and OUTSIDE the install dir (which `verity
+// install` clobbers on every reinstall). VERITY_HOME / opts.home override for tests.
+function homeDir(opts = {}) {
+  return opts.home || process.env.VERITY_HOME || path.join(os.homedir(), '.verity');
+}
+
+function globalPath(opts = {}) {
+  return path.join(homeDir(opts), 'deployment-methods.md');
+}
+
+// Seed the catalog only if absent — NEVER clobber the user's edits.
+function ensure(opts = {}) {
+  const p = globalPath(opts);
+  if (fs.existsSync(p)) {
+    return { created: false, path: p };
+  }
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, readTemplate('deployment-methods.md.tmpl'));
+  return { created: true, path: p };
+}
+
+// Each method is a `## <id> — <Title>` section; `- **status:** <x>` tags it.
+// status defaults to `active` when a user adds a method without one; the shipped
+// samples are `example` so the Architect can tell "real option" from "placeholder".
+function parseMethods(text) {
+  const methods = [];
+  let cur = null;
+  for (const line of String(text).split('\n')) {
+    const head = line.match(/^##\s+([a-z0-9][a-z0-9-]*)\s+—\s+(.+)$/);
+    if (head) {
+      if (cur) {
+        methods.push(cur);
+      }
+      cur = { id: head[1], title: head[2].trim(), status: 'active', content: line };
+      continue;
+    }
+    if (cur) {
+      cur.content += `\n${line}`;
+      const st = line.match(/^-\s+\*\*status:\*\*\s*(.+)$/i);
+      if (st) {
+        cur.status = st[1].trim().toLowerCase();
+      }
+    }
+  }
+  if (cur) {
+    methods.push(cur);
+  }
+  return methods;
+}
+
+function list(opts = {}) {
+  const { path: p } = ensure(opts);
+  const methods = parseMethods(fs.readFileSync(p, 'utf8')).map((m) => ({
+    id: m.id,
+    title: m.title,
+    status: m.status,
+  }));
+  const configured = methods.filter((m) => m.status !== 'example');
+  return { path: p, methods, configured, hasConfigured: configured.length > 0 };
+}
+
+function show(id, opts = {}) {
+  if (!id) {
+    throw new Error('show requires a method id');
+  }
+  const { path: p } = ensure(opts);
+  const method = parseMethods(fs.readFileSync(p, 'utf8')).find((m) => m.id === id);
+  if (!method) {
+    throw new Error(`no such deployment method: ${id}`);
+  }
+  return method;
+}
+
+// Open the catalog in $EDITOR when run interactively; otherwise just report the
+// path (the agent edits via its own Write tool, not an interactive editor).
+function edit(opts = {}) {
+  const { path: p } = ensure(opts);
+  const editor = opts.editor || process.env.VISUAL || process.env.EDITOR || 'nano';
+  const isTTY = opts.isTTY !== undefined ? opts.isTTY : Boolean(process.stdout.isTTY);
+  if (!isTTY) {
+    return { path: p, editor, opened: false, hint: `open it: ${editor} ${p}` };
+  }
+  const run = opts.spawn || ((cmd, a) => spawnSync(cmd, a, { stdio: 'inherit' }));
+  run(editor, [p]);
+  return { path: p, editor, opened: true };
+}
+
+// --- PER-PROJECT access ---------------------------------------------------
+
+function adminFor(cwd) {
+  try {
+    const { manifest } = identity.get(cwd);
+    return manifest.owner || manifest.name || manifest.slug || '(project admin)';
+  } catch (_e) {
+    return '(project admin — lock identity first)';
+  }
+}
+
+// Add a line to the project .gitignore if not already present. Returns whether the
+// file changed (idempotent).
+function ensureIgnored(cwd, line) {
+  const gi = path.join(cwd, '.gitignore');
+  const text = fs.existsSync(gi) ? fs.readFileSync(gi, 'utf8') : '';
+  if (text.split('\n').some((l) => l.trim() === line)) {
+    return false;
+  }
+  const prefix = text.length && !text.endsWith('\n') ? '\n' : '';
+  fs.writeFileSync(gi, `${text}${prefix}${line}\n`);
+  return true;
+}
+
+// Set up the committed pointer + gitignore for a project's access file. Does NOT
+// write the real access file — the Architect writes that with real host detail.
+function initAccess(cwd) {
+  fs.mkdirSync(path.join(cwd, '.verity'), { recursive: true });
+  const admin = adminFor(cwd);
+  const ignored = ensureIgnored(cwd, ACCESS_FILE);
+
+  const pointer = path.join(cwd, ACCESS_POINTER);
+  let pointerCreated = false;
+  if (!fs.existsSync(pointer)) {
+    fs.writeFileSync(pointer, render(readTemplate('deploy-access-pointer.md.tmpl'), { admin }));
+    pointerCreated = true;
+  }
+
+  return {
+    accessFile: ACCESS_FILE,
+    accessPath: path.join(cwd, ACCESS_FILE),
+    pointer: ACCESS_POINTER,
+    pointerCreated,
+    gitignoreUpdated: ignored,
+    admin,
+    next: `Write ${ACCESS_FILE} with how to reach this app's host — credential LOCATIONS only.`,
+  };
+}
+
+// Report whether THIS machine has the (gitignored) access file; if not, name the
+// admin to request it from.
+function accessStatus(cwd) {
+  const present = fs.existsSync(path.join(cwd, ACCESS_FILE));
+  const admin = adminFor(cwd);
+  return {
+    present,
+    accessFile: ACCESS_FILE,
+    pointerPresent: fs.existsSync(path.join(cwd, ACCESS_POINTER)),
+    admin,
+    message: present
+      ? `${ACCESS_FILE} is present.`
+      : `${ACCESS_FILE} not found — request it from the project admin: ${admin}.`,
+  };
+}
+
+function dispatch(args, flags) {
+  const verb = args[0];
+  const cwd = flags.cwd || process.cwd();
+  const opts = { home: flags.home };
+  if (verb === 'list') {
+    return list(opts);
+  }
+  if (verb === 'show') {
+    return show(args[1], opts);
+  }
+  if (verb === 'path') {
+    const p = globalPath(opts);
+    return { path: p, raw: p };
+  }
+  if (verb === 'ensure') {
+    return ensure(opts);
+  }
+  if (verb === 'edit') {
+    return edit(opts);
+  }
+  if (verb === 'init-access') {
+    return initAccess(cwd);
+  }
+  if (verb === 'access') {
+    return accessStatus(cwd);
+  }
+  throw new Error(
+    `unknown deployment verb: ${verb || '(none)'} — use list|show|path|edit|ensure|init-access|access`,
+  );
+}
+
+module.exports = {
+  homeDir,
+  globalPath,
+  ensure,
+  parseMethods,
+  list,
+  show,
+  edit,
+  initAccess,
+  accessStatus,
+  dispatch,
+  ACCESS_FILE,
+  ACCESS_POINTER,
+};

package/verity/bin/lib/install.cjs

@@ -7,8 +7,17 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 
+const deployment = require('./deployment.cjs');
+
 const PKG_ROOT = path.join(__dirname, '..', '..', '..');
 
+// Part of setup: seed the user-global deployment-methods catalog (NEVER clobbered).
+// It lives in the user's home (~/.verity), independent of the harness target dir.
+function seedDeploymentMethods(opts) {
+  const seed = deployment.ensure({ home: opts.home });
+  return { ...seed, label: `${seed.path}${seed.created ? '' : ' (existing)'}` };
+}
+
 function commandFiles(srcCommands) {
   return fs.readdirSync(srcCommands).filter((n) => n.endsWith('.md'));
 }
@@ -38,7 +47,11 @@ function installClaude(opts = {}) {
   copyInternals(target);
   installed.push('verity/');
 
-  return { harness: 'claude', target, installed };
+  // 3. Seed the global deployment-methods catalog (setup step).
+  const deploymentMethods = seedDeploymentMethods(opts);
+  installed.push(deploymentMethods.label);
+
+  return { harness: 'claude', target, installed, deploymentMethods };
 }
 
 // --- OpenCode adapter ---
@@ -85,17 +98,20 @@ function installOpenCode(opts = {}) {
   copyInternals(target);
   installed.push('verity/');
 
-  return { harness: 'opencode', target, installed };
+  const deploymentMethods = seedDeploymentMethods(opts);
+  installed.push(deploymentMethods.label);
+
+  return { harness: 'opencode', target, installed, deploymentMethods };
 }
 
 function dispatch(_args, flags) {
   if (flags.opencode) {
-    return installOpenCode({ target: flags.target });
+    return installOpenCode({ target: flags.target, home: flags.home });
   }
   if (flags.codex || flags.gemini) {
     throw new Error('only the claude and opencode adapters are implemented so far');
   }
-  return installClaude({ target: flags.target });
+  return installClaude({ target: flags.target, home: flags.home });
 }
 
 module.exports = {

package/verity/bin/lib/release.cjs

@@ -75,18 +75,34 @@ function changelogFrom(commits, version) {
   return lines.join('\n').trim();
 }
 
+// Prepend a changelog section, returning a rollback that restores the file to its
+// exact prior state (content, or non-existence) — so a later failure can undo it.
 function prependChangelog(cwd, section) {
   const p = path.join(cwd, 'CHANGELOG.md');
+  const existedBefore = fs.existsSync(p);
+  const before = existedBefore ? fs.readFileSync(p, 'utf8') : null;
   const header = '# Changelog';
-  const existing = fs.existsSync(p) ? fs.readFileSync(p, 'utf8').replace(header, '').trim() : '';
+  const existing = before ? before.replace(header, '').trim() : '';
   const body = `${header}\n\n${section}\n\n${existing}`.trim();
   fs.writeFileSync(p, `${body}\n`);
+  return () => {
+    if (existedBefore) {
+      fs.writeFileSync(p, before);
+    } else {
+      fs.rmSync(p, { force: true });
+    }
+  };
 }
 
 function run(cmd, args) {
   execFileSync(cmd, args, { stdio: 'inherit' });
 }
 
+// A release has three side effects (tag, changelog edit, push) that must be
+// all-or-nothing: a half-done release leaves either a dirty CHANGELOG.md with no
+// tag, or a local tag that never pushed. We order them cheap-and-reversible-first
+// (tag → changelog → push) and roll back the earlier steps if a later one throws.
+// The git runner is injectable (opts.run) so partial failure is unit-testable.
 function cut(cwd, opts = {}) {
   const tags = opts.tags || gitTags(cwd);
   const previous = ledger.latestTag(tags);
@@ -94,14 +110,34 @@ function cut(cwd, opts = {}) {
   const tag = `v${version}`;
   const commits = opts.commits || commitsSince(cwd, previous);
   const changelog = changelogFrom(commits, version);
-  if (!opts.dryRun) {
-    prependChangelog(cwd, changelog);
-    run('git', ['-C', cwd, 'tag', tag]);
-    if (opts.push !== false) {
-      run('git', ['-C', cwd, 'push', 'origin', tag]);
+  const result = { version, tag, previous, changelog, commitCount: commits.length };
+  if (opts.dryRun) {
+    return { ...result, applied: false };
+  }
+
+  const exec = opts.run || run;
+  exec('git', ['-C', cwd, 'tag', tag]); // step 1 — if this throws, nothing changed yet
+
+  let restoreChangelog;
+  try {
+    restoreChangelog = prependChangelog(cwd, changelog); // step 2
+  } catch (err) {
+    exec('git', ['-C', cwd, 'tag', '-d', tag]); // roll back step 1
+    throw err;
+  }
+
+  if (opts.push !== false) {
+    try {
+      exec('git', ['-C', cwd, 'push', 'origin', tag]); // step 3
+    } catch (err) {
+      restoreChangelog(); // roll back step 2
+      exec('git', ['-C', cwd, 'tag', '-d', tag]); // roll back step 1
+      throw new Error(
+        `release push failed — rolled back tag ${tag} and CHANGELOG.md, working tree is clean. Original error: ${err.message}`,
+      );
     }
   }
-  return { version, tag, previous, changelog, commitCount: commits.length, applied: !opts.dryRun };
+  return { ...result, applied: true };
 }
 
 function current(cwd) {

package/verity/bin/lib/smoke.cjs

@@ -78,9 +78,36 @@ function buildScript(baseUrl, flow) {
   return lines.join('\n');
 }
 
-function defaultProbe(cwd) {
+function resolvableFrom(pkg, cwd) {
+  try {
+    require.resolve(pkg, { paths: [cwd, process.cwd()] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function onPath(bin, pathDirs) {
+  const exts = process.platform === 'win32' ? ['.cmd', '.exe', '.bat', ''] : [''];
+  return pathDirs.some((d) => exts.some((e) => fs.existsSync(path.join(d, bin + e))));
+}
+
+// Capability probe — is a headless browser usable here? Checks three honest sources
+// so we don't false-skip when the tool is installed in a non-local layout:
+//   1. the project's local node_modules/.bin
+//   2. resolvable as a package from cwd (hoisted / monorepo / npm-linked global)
+//   3. a CLI on PATH (a globally-installed playwright)
+// Pure (no execution). If none match it returns unavailable, and runSmoke degrades
+// to a non-pass — never a false green. Callers can bypass detection entirely by
+// injecting opts.probe / opts.driver into runSmoke (e.g. a project-specific runner).
+function defaultProbe(cwd, env = process.env) {
+  const pathDirs = (env.PATH || '').split(path.delimiter).filter(Boolean);
   for (const bin of ['playwright', 'puppeteer']) {
-    if (fs.existsSync(path.join(cwd, 'node_modules', '.bin', bin))) {
+    if (
+      fs.existsSync(path.join(cwd, 'node_modules', '.bin', bin)) ||
+      resolvableFrom(bin, cwd) ||
+      onPath(bin, pathDirs)
+    ) {
       return { available: true, tool: bin };
     }
   }

package/verity/bin/verity.cjs

@@ -26,6 +26,7 @@ const map = require('./lib/map.cjs');
 const recovery = require('./lib/recovery.cjs');
 const golive = require('./lib/golive.cjs');
 const smoke = require('./lib/smoke.cjs');
+const deployment = require('./lib/deployment.cjs');
 
 function parseArgs(argv) {
   const positional = [];
@@ -154,6 +155,9 @@ const COMMANDS = {
   smoke(rest, flags) {
     return smoke.dispatch(rest, flags);
   },
+  deployment(rest, flags) {
+    return deployment.dispatch(rest, flags);
+  },
 };
 
 function main() {

package/verity/templates/deploy-access-pointer.md.tmpl

@@ -0,0 +1,13 @@
+# Deployment access — obtain from the project admin
+
+This project deploys to a specific host. The access details live in
+`.verity/deploy-access.md`, which is **intentionally gitignored** — it is never
+committed, so no host or credential detail ever lands in git history.
+
+**If you do not have `.verity/deploy-access.md` on your machine, request it from the
+project admin: {{admin}}.** They maintain it and share it out-of-band (not through
+this repo).
+
+Maintainers: write or update the real file with `/verity:architect`, or by hand.
+Keep it to credential *locations* (key files, SSO profiles, secret-store entries) —
+never raw secrets.

package/verity/templates/deployment-methods.md.tmpl

@@ -0,0 +1,32 @@
+# Your Verity deployment methods
+
+> **Global to YOU, across every project.** This is your private inventory of the
+> places you *can* deploy to. The Architect (`/verity:architect`) reads it with
+> `verity deployment list` and works with you to choose a target for each app.
+>
+> ⚠️ **Reference credential LOCATIONS, never paste secrets.** Point at a key file,
+> an SSO profile, or a secret-store entry — never an actual key, password, or token.
+> This file lives at `~/.verity/deployment-methods.md`; it is NOT in any repo, but
+> treat it as sensitive anyway.
+>
+> Edit it any time with `verity deployment edit` (or open the path printed by
+> `verity deployment path`). Add one `## <id> — <Title>` section per method, and set
+> `- **status:** active` once it is real (the two below are `example` — replace or
+> delete them).
+
+## aws-ec2 — AWS EC2 over SSH (example — edit or delete)
+- **status:** example
+- **provider:** AWS
+- **host:** `<ec2-public-dns-or-elastic-ip>`
+- **user:** `ubuntu`
+- **access:** `ssh -i ~/.ssh/<your-key>.pem ubuntu@<host>` — key *location* only
+- **notes:** region `<e.g. us-east-1>`; the security group must allow your IP on
+  ports 22 (SSH) and 443 (HTTPS).
+
+## local-server — Local network server (example — edit or delete)
+- **status:** example
+- **provider:** self-hosted (LAN)
+- **host:** `<hostname-or-10.0.0.x>`
+- **user:** `<you>`
+- **access:** `ssh <user>@<host>` over the local network / VPN
+- **notes:** only reachable on the LAN or while connected to the VPN — not public.

package/verity/templates/gitignore.tmpl

@@ -7,3 +7,6 @@ dist/
 !.env.*.example
 # Verity's derived state cache — never authoritative (framework-spec §5)
 .verity-cache/
+# Per-app deployment access (host + credential locations) — shared out-of-band,
+# never committed. The committed pointer (.verity/deploy-access.README.md) stays.
+.verity/deploy-access.md