@refactco/refact-os 1.5.0

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+Notable changes to the refact-os standard and scaffolder.
+
+**Staying current:** a consumer repo updates with `npm run refact:update` (or `npx github:refactco/refact-os init`). That refreshes the package-managed `agent/` payload, **prunes** skills this package has removed or renamed (safe — only skills the package previously shipped, never your own), regenerates `.cursor/` + `.claude/`, and flags `agent/AGENTS.md` drift for a manual merge. The version it last applied is recorded in `.refact-os.json` under `_scaffold.version`, and `init` prints the `old → new` transition so you can scan the entries below for anything needing manual action. Run `npm run refact:validate` afterward.
+
+## 1.5.0
+
+### Changed
+- **Published to npm as the scoped public package [`@refactco/refact-os`](https://www.npmjs.com/package/@refactco/refact-os).** Install/run with `npx @refactco/refact-os init` (no more `github:` specifier required). Added the publish metadata (`license: MIT`, `repository`, `keywords`, `engines: node >=18`, `publishConfig.access: public`) and an MIT `LICENSE`.
+- **Removed the `postinstall` auto-scaffold.** Scaffolding is now always explicit via `init`. A postinstall that writes to the install directory is a trust/security red flag for a public package (and breaks under `--ignore-scripts`); dropping it also removes the double-scaffold that ran on `npx … init`. `bin/postinstall.js` is gone; the package-root + `isAllowedTarget` guards live in `bin/refact-os.js`.
+
+## 1.4.4
+
+### Fixed
+- **`sync` no longer deletes foreign (non-refact-os) Cursor/Claude skills.** Adapter generation used to wipe `.cursor/skills/` and `.claude/skills/` wholesale and rebuild them from `agent/skills/`, which destroyed any skill pack placed there by another tool (e.g. a third-party WordPress skills bundle with no `agent/` source). It now *reconciles* the skills dir: it mirrors each `agent/` skill, prunes only skills refact-os itself previously generated (tracked in a per-surface `.refact-os-owned.json` manifest), and leaves foreign skills untouched. Other adapter subdirs (`hooks/`, `scripts/`, `references/`) are still fully owned and replaced.
+
+## 1.4.3
+
+### Changed
+- **`refact-os init` mentions now show a runnable form too.** Follow-up to 1.4.2: the remaining bare `refact-os init …` directives in the `adopt`, `setup-project`, and `refact` skills now use `npx github:refactco/refact-os init …` (bootstrap/greenfield, where nothing is installed yet) or `npx refact-os init …` (inside an already-scaffolded repo). The conceptual "don't run `refact-os init|migrate|sync`" rule in `adopt` is left as-is.
+
+## 1.4.2
+
+### Changed
+- **Docs/skills now show the runnable command form.** Scaffolded `README.md`, `agent/AGENTS.md`, `agent/CLAUDE.md`, and skills (`adopt`, `update-package`, `setup-nextjs-app`) — plus `validate` remediation messages and generated-file headers — say `npm run refact:sync` / `npm run refact:validate` (and `npx refact-os sync company`) instead of the bare `refact-os …`. The bare binary isn't on a shell's PATH, so an agent pasting it got `command not found` and hand-mirrored the payload; the npm-script form runs as-is. Added a short "Tooling" note to `AGENTS.md`/`README.md` explaining the `refact-os` devDependency and the `npm install` / `npx` fallback.
+
+### Fixed
+- **Brownfield repos can now opt into overlays.** An explicit `--overlay <name>` (e.g. `--overlay code`) is applied even on a brownfield/adopted repo — copying only the overlay's `agent/` payload (skills/hooks), never its convention/structure files (`wp-cli.yml.example`) or directories. Previously brownfield skipped overlays entirely, so an adopted repo had no clean way to add a skill-pack without `--seed`. Type-derived overlays still apply on greenfield only.
+
+## 1.4.1
+
+### Changed
+- **Brownfield `init` is leaner.** It now also skips `.env.example` (a convention file, like the `docs/` seed) — an existing repo keeps its own env conventions, and `/adopt` adds what's actually needed. Greenfield still gets `.env.example`.
+
+## 1.4.0
+
+### Added
+- **Default Claude permission allowlist.** Scaffolded repos now ship a shared, committed `.claude/settings.json` with `permissions.allow` for `git commit`, `git push`, and `gh pr create`, so agents don't re-prompt for the common commit/push/PR flow. It's generated from `agent/claude-hooks.json` and **merged** on every sync — the managed allow rules are unioned in, and any allow/deny/ask rules you add are preserved. Personal overrides belong in `.claude/settings.local.json` (now gitignored).
+  - Note: this is Claude Code only. Cursor's command allowlist (`~/.cursor/permissions.json` → `terminalAllowlist`) is **global per-user with no per-project override**, so it can't be scaffolded into a repo — set it once on your machine.
+  - Posture: pair this with branch protection on `main` (the agent already won't push to `main` per the `AGENTS.md` hard rule). Claude's permission allowlist is a prompt convenience, not a security boundary.
+
+## 1.3.0
+
+### Added
+- **Team-sync upgrades.** Scaffold now stamps `_scaffold.version` and `_scaffold.shippedSkills` into `.refact-os.json`. On the next update, skills the package shipped before but no longer ships (removed or renamed) are pruned from the consumer's `agent/skills/`; user-authored skills are never in the manifest, so they're never touched. The CLI reports the version transition and any pruned skills.
+- **Brownfield `init`.** An existing (non-empty) repo now receives only the agent layer (base skills incl. `adopt`, root pointers, config, adapters) — no `docs/` seed, no `apps/`, no type overlays imposed over your structure. Run `/adopt` to plan the transition. The decision is recorded (`_scaffold.brownfield`) and sticky; `--seed` forces the full scaffold.
+- **Standard (`docs/agent-first-repo-best-practices.md`).** New sections: *Latent vs. Deterministic Work*, *Keep The Harness Narrow*, the *process-not-content* skill-reuse test, the resolver doctrine (frontmatter is the routing table), and the *diarization* (`synthesize-subject-brief`) earned pattern.
+- **Enforcement.** `project-status` moved its counting into `scripts/scan-status.mjs` (run-and-interpret); the generated skill index now carries the full resolver slice (`when_not_to_use`, `next_skills`, …) and is drift-checked on the full slice; warn-level frontmatter-quality lint (missing `next_skills` key, near-empty/paragraph-length descriptions).
+
+### Changed
+- **Project type `other` renamed to `blank`** (legacy `other` is still accepted on input and migrated to `blank`, so existing configs keep working).
+- **Type resolution.** Detection is now only a *suggestion* for the prompt default — never silently committed. An explicit (`--type`) or interactive choice is authoritative and **replaces** the stack (so picking a type can downgrade away from a detected one).
+
+### Fixed
+- `init` no longer silently commits a detected type (e.g. from a stray `wp-content/` dir) and applies its overlay before the user is asked.
+
+## 1.2.0 and earlier
+
+See git history (`git log`) — versioned changelog entries start at 1.3.0.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Refact
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,162 @@
+# refact-os
+
+`refact-os` sets up a project so AI coding agents (Cursor, Claude Code) can work in it reliably. It drops in a fixed folder layout (the **substrate**) plus a set of agent **skills** (the **move set**) — all generated from one source of truth.
+
+> The full standard is written up in [`docs/agent-first-repo-best-practices.md`](./docs/agent-first-repo-best-practices.md). Read it before changing what gets scaffolded.
+
+You only ever edit one canonical folder, `agent/`. The tool generates the tool-specific folders (`.cursor/`, `.claude/`) from it — you never edit those by hand.
+
+## Get started
+
+> refact-os is **not** on the public npm registry. You install it straight from GitHub.
+
+Create a project and scaffold it:
+
+```bash
+mkdir my-project && cd my-project
+npx github:refactco/refact-os init
+```
+
+Choose the project type up front (skips the prompt):
+
+```bash
+npx github:refactco/refact-os init --type nextjs           # or: wordpress, blank
+npx github:refactco/refact-os init --type wordpress,nextjs  # hybrid: apply both overlays
+```
+
+`init` adapts to the repo. An **empty** repo gets the full scaffold (substrate seed + skills + overlays). An **existing** repo gets **only the agent layer** (skills, including `adopt`) so it never imposes folders over your structure — then `/adopt` plans the transition. Force the full scaffold on a non-empty repo with `--seed`. See the **Bringing an existing repo** note under [Commands](#commands) below.
+
+## Run it inside your project (npm)
+
+After `init`, your `package.json` gets a `refact-os` dev-dependency and ready-made scripts. From then on you use plain **npm** — no more typing the long `npx github:…`:
+
+```jsonc
+"scripts": {
+  "refact:sync":     "refact-os sync",      // rebuild .cursor/ + .claude/ after editing agent/
+  "refact:validate": "refact-os validate",  // check the project follows the standard
+  "refact:migrate":  "refact-os migrate",   // move an old layout to the current one
+  "refact:update":   "refact-os init"       // pull the latest refact-os files
+}
+```
+
+Install once, then run the scripts:
+
+```bash
+npm install
+npm run refact:sync
+npm run refact:update   # when you want to refresh the agent/ files
+```
+
+A normal `npm install` is **safe** — it will not overwrite your files. Refreshing only happens when you explicitly run `npm run refact:update`.
+
+**Staying current as the standard evolves.** `npm run refact:update` (= `refact-os init`) refreshes the package-managed `agent/` payload (new + edited skills/hooks/scripts), **prunes** skills the package has since removed or renamed (only ones it previously shipped — never your own), regenerates `.cursor/` + `.claude/`, and prints the version transition (`old → new`). The version last applied is recorded in `.refact-os.json` (`_scaffold.version`); scan [CHANGELOG.md](./CHANGELOG.md) for anything needing manual action, then run `npm run refact:validate`. Your `agent/AGENTS.md` is never overwritten — if the upstream contract template changed, the update flags it so you can merge by hand.
+
+## Project types
+
+| Type | Command | Extra skills it adds |
+|---|---|---|
+| Next.js | `init --type nextjs` | `setup-nextjs-app`, `nextjs-dev`, `setup-vercel-deploy`, `setup-netlify-deploy` |
+| WordPress | `init --type wordpress` | `wp-env`, `install-wp-skills`, `setup-kinsta-deploy` |
+| Both (hybrid) | `init --type wordpress,nextjs` | both overlay skill sets |
+| Blank | `init --type blank` | base skills only — the catch-all for repos that start small and grow |
+
+Each runnable app lives in its own folder under `apps/` (e.g. `apps/web/`, `apps/wordpress/`). After scaffolding, ask the agent for the flow you need:
+
+```txt
+/refact setup nextjs app
+/refact wp-env setup
+/refact setup vercel deploy
+```
+
+The detailed steps live in the overlay skills, so you don't have to remember them.
+
+## Commands
+
+```bash
+refact-os init      [--target <dir>] [--type <types>] [--overlay <name>] [--no-force]
+refact-os sync      [--target <dir>]                     # regenerate .cursor/ + .claude/ from agent/
+refact-os sync company [--target <dir>]                  # pull company context into docs/context/company/
+refact-os validate  [--target <dir>]                     # check structure + skills against the spec
+refact-os migrate   [--target <dir>]                     # move an older layout into the current one
+```
+
+- **`init`** — scaffold a project. An **empty** repo gets the thin seed + base `agent/` skills + type overlays + adapters; an **existing** repo gets only the agent layer (then run `/adopt`). `--seed` forces the full scaffold on a non-empty repo; `--no-force` never overwrites existing files.
+- **`sync`** — after editing `agent/`, regenerate `.cursor/` and `.claude/`. Never edit those by hand.
+- **`validate`** — checks the required folders/files exist, every skill declares its resolver frontmatter (the fields the agent routes on — `name`, `pattern`, `description`, `when_to_use`, `when_not_to_use`, `next_skills`), the generated skill index isn't stale, and the adapters are in sync.
+- **`migrate`** — moves an old-layout repo into the current one and tops up the `package.json` scripts. Safe: it never overwrites an existing file, and merges old chat folders into the new location.
+- **`sync company`** — pulls Refact's shared company context (brand, team, pitch) from `refactco/refact-operation` into `docs/context/company/`. Re-syncable, so it never drifts permanently. Source + SHA are recorded in `.refact-os.json`.
+
+**Bringing an existing repo to the standard:** just run `npx github:refactco/refact-os init`. It detects that the repo isn't empty and adds **only the agent layer** — the skills (including `adopt`), root pointers, config, and adapters — *without* dropping a `docs/` seed or `apps/` over your existing structure, and without applying type overlays. Then run the **`adopt`** skill (`/adopt`): it surveys the repo, writes a phased transition plan to `docs/task/open/`, and reconciles your structure with the standard — asking before anything ambiguous — until `refact-os validate` is green. (Pass `--seed` if you actually want the full greenfield scaffold on a non-empty repo.)
+
+## What gets generated
+
+```
+<project-root>/
+├── AGENTS.md  CLAUDE.md         ← thin pointers to agent/
+├── README.md  package.json  .env.example  .gitignore  .refact-os.json
+├── agent/                       ← CANONICAL (the source of truth — you edit here)
+│   ├── AGENTS.md                ← the engagement contract (kept if it already exists)
+│   ├── CLAUDE.md
+│   ├── hooks.json  hooks/  scripts/  references/
+│   ├── agent-surface-map.json   ← generated map of canonical → adapters
+│   └── skills/                  ← the skill catalog (ingest-input, open-ticket, …)
+├── docs/                        ← your working docs
+│   ├── index.md  decisions.md
+│   ├── sources/raw/{email,call-transcripts,agent-transcripts}/   ← inbound material
+│   ├── context/{project,people,open-decisions,learnings}.md      ← curated knowledge
+│   ├── task/{open,closed}/                                        ← work tracking
+│   └── deliverables/                                              ← finished output
+├── apps/                        ← your product code (apps/web, apps/wordpress, …)
+├── .cursor/                     ← GENERATED from agent/ (do not edit)
+└── .claude/                     ← GENERATED from agent/ (do not edit)
+```
+
+`agent/` is the source of truth. `.cursor/` and `.claude/` are throwaway copies — change `agent/` and run `npm run refact:sync`.
+
+The generated `.claude/settings.json` ships a shared, team-wide **permission allowlist** (`git commit`, `git push`, `gh pr create`) so agents don't re-prompt for the common commit/push/PR flow — edit the source in `agent/claude-hooks.json`, and put personal tweaks in the gitignored `.claude/settings.local.json`. (Claude Code only — Cursor's allowlist is global per-user at `~/.cursor/permissions.json` with no per-repo option.)
+
+## Skills
+
+Skills live in `agent/skills/<name>/SKILL.md`. They are loaded lazily: the agent reads each skill's short resolver frontmatter (`name`, `pattern`, `description`, `when_to_use`, `when_not_to_use`, `next_skills`) to decide what to use, and only opens the full skill when it picks it.
+
+The base is deliberately thin — only what *every* repo needs (an internal ops or research repo with no codebase and no customer deliverables still wants all of it):
+
+| Skill | What it does |
+|---|---|
+| `ingest-input` | Classify + save any inbound material to `docs/sources/raw/`. The entry point for new input. |
+| `open-ticket` / `close-ticket` | Track work in `docs/task/`. |
+| `update-canonical-record` | Make a careful, cited edit to the project's main truth file. |
+| `extract-learnings` | Capture non-obvious learnings into `docs/context/`. |
+| `adopt` | Bring an existing, non-conformant repo up to the standard (survey → phased plan → reconcile). |
+| `refact` | The `/refact …` command router that dispatches to the operational skills. |
+
+Refact operational skills, also in base (run via `/refact <action>`, or picked on their own): `setup-project`, `update-package`, `import-chat-history`, `process-docs`, `project-status`, `git-it`, `sync-asana`.
+
+Everything else ships as an **overlay**, applied only when the project needs it — so a repo with no code and no deliverables never sees code or delivery skills:
+
+- **`code`** — `code-development`, `add-codebase`. Auto-applied for `wordpress`/`nextjs` (they always have code); opt in elsewhere with `--overlay code`.
+- **`client`** — `create-deliverable` + the `docs/deliverables/` folder. Opt in with `--overlay client` on client-facing engagements.
+- **`wordpress`** (`--type wordpress`) — `wp-env`, `install-wp-skills`, `setup-kinsta-deploy`.
+- **`nextjs`** (`--type nextjs`) — `setup-nextjs-app`, `nextjs-dev`, `setup-vercel-deploy`, `setup-netlify-deploy`.
+
+Engagement-shaped skills (`draft-quote`, `draft-proposal`, `draft-email`, `design-asset`, …) are **not** pre-shipped — add them when a real engagement needs them.
+
+## Repository layout (this package)
+
+```
+bin/refact-os.js     # CLI: init | sync | validate | migrate (no postinstall — scaffolding is always explicit)
+lib/
+  scaffold.js        # copies templates/base into the target, then generates adapters
+  adapters.js        # generate .cursor/ + .claude/ from agent/
+  validate.js        # check structure + skill frontmatter
+  migrate.js         # old layout → current layout
+  project-utils.js   # project-type detection; package.json scripts + dev-dependency
+  refact-config.js   # .refact-os.json (stack: types/hosting/runtime/environments, Asana id)
+templates/base/      # the payload copied into every project (universal + Refact tooling)
+templates/overlays/  # overlays applied on top of base: code/, client/, wordpress/, nextjs/
+docs/agent-first-repo-best-practices.md   # the spec this tool implements
+```
+
+Published package contents: `bin/`, `lib/`, `templates/`, `README.md` (see `package.json` `files`).
+
+For this scaffolder's own agent map, see [`AGENTS.md`](./AGENTS.md).

package/bin/refact-os.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+const os = require("os");
+const path = require("path");
+const { scaffoldProject } = require("../lib/scaffold");
+const { generateAdapters } = require("../lib/adapters");
+const { validateRepo } = require("../lib/validate");
+const { migrateRepo } = require("../lib/migrate");
+const { syncCompany } = require("../lib/company");
+const { ensurePackageScripts } = require("../lib/project-utils");
+
+const COMMANDS = ["init", "sync", "validate", "migrate"];
+
+// The refact-os package's own root. Commands must never operate on it — running
+// `npm run init` / `npx refact-os init` inside this repo would otherwise scaffold
+// the scaffolder into itself.
+const PACKAGE_ROOT = path.resolve(__dirname, "..");
+
+function isAllowedTarget(target) {
+  if (!target) return false;
+  if (target === "/") return false;
+  const home = os.homedir();
+  if (target === home) return false;
+  if (target === path.dirname(home)) return false;
+  if (target === PACKAGE_ROOT) return false;
+  return true;
+}
+
+function parseArgs(argv) {
+  const args = { command: "init", sub: undefined, target: process.cwd(), projectType: undefined, overlays: [], force: true, seed: false };
+  const raw = [...argv];
+  if (raw[0] && !raw[0].startsWith("-")) args.command = raw.shift();
+  if (raw[0] && !raw[0].startsWith("-")) args.sub = raw.shift();
+  while (raw.length > 0) {
+    const token = raw.shift();
+    if (token === "--type") args.projectType = raw.shift();
+    else if (token === "--overlay") args.overlays.push(raw.shift());
+    else if (token === "--target") args.target = raw.shift();
+    else if (token === "--no-force") args.force = false;
+    else if (token === "--seed") args.seed = true;
+  }
+  return args;
+}
+
+async function runScaffold(args, { force }) {
+  const result = await scaffoldProject(args.target, {
+    projectType: args.projectType,
+    overlays: args.overlays,
+    force,
+    seed: args.seed,
+    interactive: process.stdin.isTTY,
+  });
+  console.log(`Scaffolded ${result.filesWritten} files in ${result.target}`);
+  console.log(`Stack types: ${(result.projectTypes && result.projectTypes.length ? result.projectTypes : [result.projectType]).join(", ")}`);
+  console.log(`Adapters generated: ${result.adapters.tools.join(", ") || "none"}`);
+  console.log(`Config: ${result.configPath}`);
+  console.log(`.gitignore: ${result.gitignoreStatus}`);
+  if (result.prevVersion && result.prevVersion !== result.version) {
+    console.log(`Updated refact-os ${result.prevVersion} → ${result.version} — see the package CHANGELOG.md for what changed.`);
+  } else {
+    console.log(`refact-os version: ${result.version}`);
+  }
+  if (result.prunedSkills && result.prunedSkills.length > 0) {
+    console.log(`Pruned ${result.prunedSkills.length} skill(s) removed upstream: ${result.prunedSkills.join(", ")}`);
+  }
+  if (result.brownfield) {
+    console.log("");
+    console.log("Existing repo detected — added the agent layer only (no docs/ seed or apps/, no type overlays).");
+    console.log("Next: run the `adopt` skill (/adopt) to plan the transition, or re-run with `--seed` to scaffold the full structure anyway.");
+  }
+  if (result.missingFields && result.missingFields.length > 0) {
+    console.log(`Missing metadata (re-asked on next /refact run): ${result.missingFields.join(", ")}`);
+  }
+  if (result.contractChanged) {
+    console.log("");
+    console.log("⚠  agent/AGENTS.md template changed upstream. Your copy was preserved (skipIfExists).");
+    console.log("   Review templates/base/agent/AGENTS.md in the installed package and merge by hand.");
+  }
+  if (result.packageStatus && result.packageStatus.scriptsAdded.length > 0) {
+    console.log(`Added npm scripts: ${result.packageStatus.scriptsAdded.join(", ")}`);
+  }
+  if (result.packageStatus && result.packageStatus.depsAdded && result.packageStatus.depsAdded.length > 0) {
+    console.log(`Added devDependencies: ${result.packageStatus.depsAdded.join(", ")}`);
+  }
+}
+
+function runValidate(target) {
+  const report = validateRepo(target);
+  for (const w of report.warnings) console.log(`  warn: ${w}`);
+  for (const e of report.errors) console.error(`  error: ${e}`);
+  if (report.ok) {
+    console.log(`✓ valid — ${report.skillCount} skill(s), ${report.warnings.length} warning(s).`);
+    return 0;
+  }
+  console.error(`✗ ${report.errors.length} error(s), ${report.warnings.length} warning(s).`);
+  return 1;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!COMMANDS.includes(args.command)) {
+    console.error(`Unknown command "${args.command}". Use one of: ${COMMANDS.join(" | ")}`);
+    process.exit(1);
+  }
+  const target = path.resolve(args.target);
+  if (!isAllowedTarget(target)) {
+    console.error(`Refusing to operate on '${target}'. Pass --target <dir> or cd into a project directory first.`);
+    process.exit(1);
+  }
+
+  switch (args.command) {
+    case "init":
+      await runScaffold({ ...args, target }, { force: args.force });
+      break;
+    case "sync": {
+      if (args.sub === "company") {
+        const r = syncCompany(target, {});
+        console.log(`Synced ${r.fileCount} company file(s) to ${r.dest}/ from ${r.source} (${r.sourcePath}) @ ${r.sha.slice(0, 8)}`);
+      } else if (args.sub && args.sub !== "adapters") {
+        console.error(`Unknown sync target "${args.sub}". Use: refact-os sync [adapters|company]`);
+        process.exit(1);
+      } else {
+        const result = generateAdapters(target, {});
+        console.log(`Adapters synced from agent/: ${result.tools.join(", ") || "none"}`);
+      }
+      break;
+    }
+    case "migrate": {
+      const result = migrateRepo(target);
+      for (const m of result.moved) console.log(`moved: ${m.from} -> ${m.to}${m.merged ? ` (merged ${m.merged} file${m.merged === 1 ? "" : "s"})` : ""}`);
+      for (const s of result.skipped) console.log(`skipped: ${s.from} (${s.skipped})`);
+      const pkg = ensurePackageScripts(target);
+      if (pkg.scriptsAdded && pkg.scriptsAdded.length > 0) console.log(`package.json scripts added: ${pkg.scriptsAdded.join(", ")}`);
+      if (pkg.depsAdded && pkg.depsAdded.length > 0) console.log(`package.json devDependencies added: ${pkg.depsAdded.join(", ")}`);
+      console.log(`Migrated ${result.moved.length} path(s). Run \`refact-os init\` to lay down the agent/ payload, then \`refact-os validate\`.`);
+      break;
+    }
+    case "validate":
+      process.exit(runValidate(target));
+      break;
+    default:
+      break;
+  }
+}
+
+// Only run when invoked directly (e.g. `node bin/refact-os.js` or via the bin
+// shim) — never on `require()`, so importing this file can't trigger a scaffold.
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  });
+}
+
+module.exports = { main, parseArgs };