@orqint/cli 0.1.0 → 0.2.0

package/README.md

@@ -1,100 +1,96 @@
 # Orqint
 
-CLI orchestration for Cursor-native `think` / `plan` workflows. See [docs/PRD/PRD.md](docs/PRD/PRD.md).
+CLI orchestration for Cursor-native `think` / `plan` workflows (prepare in the CLI → work in Cursor → apply JSON back). Deep product spec: [docs/PRD/PRD.md](docs/PRD/PRD.md).
 
-**Maintainers:** CLI source lives under [`packages/cli/`](packages/cli/README.md). Root folder [`orqint/`](orqint/core/) holds **project state** (`memory.json`, etc.) for this repo only, not TypeScript sources. Full map: [docs/Repository-layout.md](docs/Repository-layout.md).
+## Use Orqint in your project
 
-## Prerequisites
-
-- Node.js (LTS)
-- [pnpm](https://pnpm.io/installation) (for developing this repo)
-- [npm](https://www.npmjs.com/) (ships with Node; used by `npx` and `orqint update`)
-
-## Run with `npx` (no global install)
-
-After the package is **published to npm** (see below):
+You need [Node.js](https://nodejs.org/) (LTS). From your **project root**:
 
 ```bash
-npx --yes @orqint/cli@latest version
 npx --yes @orqint/cli@latest init
 ```
 
-Check for updates (queries the registry):
+1. **`init`** creates the `orqint/` layout (`memory.json`, prompts, handoff folder, etc.).
+2. It also installs **user assets** when missing: **`AGENTS.md`**, **`ORQINT.md`**, and **`.cursor/rules/orqint-workflow.mdc`** (so Cursor can help with handoffs). Existing files are **not** overwritten — use **`orqint init --force-user-assets`** only if you want to refresh those from the package.
+3. Open **`ORQINT.md`** in your repo for the short workflow (commands and tables).
 
-```bash
-npx --yes @orqint/cli@latest update
-```
+### After `npm update @orqint/cli` (safe template refresh)
 
-Run the latest published CLI via npx (recommended when a newer version exists):
+Orqint records a **lock** at **`orqint/core/user-assets.lock.json`** for each managed file it wrote. **`orqint sync-assets`** replaces those files from the **installed** package only when the file on disk still matches the lock (so your edits are never silently overwritten). It does **not** reset **`memory.json`**.
 
 ```bash
-npx --yes @orqint/cli@latest <command>
+npm update @orqint/cli
+orqint sync-assets
 ```
 
-`orqint update --install <args>` re-invokes `npx @orqint/cli@latest <args>` for you when a newer version is available.
-
-### Publish (maintainers)
-
-From this repo, with an npm login that can publish to the `@orqint` scope:
+If your global `orqint` is older than the package you want, run the latest CLI and sync in one step:
 
 ```bash
-npm run build
-npm publish
+orqint update --install sync-assets
 ```
 
-The package is scoped as `@orqint/cli`; `publishConfig.access` is `public` so `npm publish` does not require extra flags.
+(Uses `npx @orqint/cli@latest sync-assets`. On Windows, Node runs this with `shell: true` so `npx` resolves like other npm commands.)
 
-## Install the `orqint` command (this machine)
+- **`orqint sync-assets --dry-run`** — print what would happen.
+- **`orqint sync-assets --migrate`** — one-shot: replace all managed templates from the current package and write the lock (for projects created before the lockfile existed).
+- **`orqint sync-assets --force`** — overwrite all managed files and refresh the lock (same files as **`init --force-user-assets`**, without touching memory).
 
-From the **root of this repository**:
+**Teams:** commit **`orqint/core/user-assets.lock.json`** so everyone shares the same “managed vs customized” baseline. Without it, `sync-assets` stays conservative for files that exist but have no lock entry until someone runs **`--migrate`** once.
+
+Other commands (after init):
 
 ```bash
-pnpm run cli:install
+npx --yes @orqint/cli@latest update
+npx --yes @orqint/cli@latest <command>
 ```
 
-This installs dependencies, builds `dist/`, and runs `pnpm link --global` so `orqint` is on your PATH.
+`orqint init --brownfield` can seed hints from your `package.json` / `README.md`. `orqint init --force` resets **Orqint runtime** (e.g. `memory.json`) and does **not** replace your root `AGENTS.md` / `ORQINT.md` / Cursor rules unless you also pass **`--force-user-assets`**.
 
-On Windows (no `bash`), use:
+---
 
-```bash
-pnpm run cli:install:pnpm
-```
+## Maintainers — this repository
 
-If `orqint` is not found, add pnpm’s global bin directory to your PATH (run `pnpm bin -g` to see it).
+CLI source: [`packages/cli/`](packages/cli/README.md). Root [`orqint/`](orqint/core/) is **project state** for dogfooding (not TypeScript sources). Shipped **user-facing** files for npm live under **`user-assets/`** (see [user-assets/FOR_MAINTAINERS.md](user-assets/FOR_MAINTAINERS.md)). Layout map: [docs/Repository-layout.md](docs/Repository-layout.md).
 
-**Shell alternative (same steps):**
+### Prerequisites (development)
 
-```bash
-bash scripts/setup-cli.sh
-```
+- Node.js (LTS)
+- [pnpm](https://pnpm.io/installation)
+- npm (for `npx` and `orqint update`)
 
-## Update after pulling changes
+### Publish
 
 ```bash
-pnpm run cli:upgrade
+npm run build
+npm publish
 ```
 
-Or:
+Scoped package **`@orqint/cli`**; `publishConfig.access` is `public`.
+
+### Install `orqint` globally from this clone
 
 ```bash
-bash scripts/update-cli.sh
+pnpm run cli:install
 ```
 
-`cli:upgrade` runs `git pull --rebase` (when this folder is a git repo), then reinstalls and rebuilds. Your global link keeps pointing at this folder, so you immediately get the new build.
+Windows (no bash): `pnpm run cli:install:pnpm`. If `orqint` is not on PATH, see `pnpm bin -g`.
 
-After you `git pull` yourself (or without git), you can run:
+Shell alternative: `bash scripts/setup-cli.sh`
+
+### Update after pulling
 
 ```bash
-pnpm run cli:upgrade:pnpm
+pnpm run cli:upgrade
 ```
 
-## Use in a test project
+Or `pnpm run cli:upgrade:pnpm` without `git pull` inside the script.
+
+### Test project (local build)
 
-1. Build / install CLI as above.
-2. Open an empty folder in Cursor.
-3. Run `orqint init`, then follow [AGENTS.md](AGENTS.md) and [docs/orqint-cursor-starter.md](docs/orqint-cursor-starter.md).
+1. Build / link CLI as above.
+2. In a throwaway folder: `orqint init`, then follow **[user-assets/ORQINT.md](user-assets/ORQINT.md)** (same text users get) and [docs/orqint-cursor-starter.md](docs/orqint-cursor-starter.md).
 
-## Use without global install
+### Run CLI without global install (this repo)
 
 ```bash
 pnpm run build

package/dist/orqint/commands/init.d.ts

@@ -1,5 +1,6 @@
 export type InitOptions = {
     force?: boolean;
+    forceUserAssets?: boolean;
     brownfield?: boolean;
     migrateLegacy?: boolean;
 };

package/dist/orqint/commands/init.js

@@ -37,6 +37,7 @@ exports.runInit = runInit;
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs-extra"));
 const paths_1 = require("../engine/paths");
+const user_assets_1 = require("../engine/user-assets");
 const memory_1 = require("../utils/memory");
 const logger_1 = require("../utils/logger");
 async function runInit(cwd, opts) {
@@ -59,6 +60,14 @@ async function runInit(cwd, opts) {
     await fs.ensureDir(path.join(root, ".handoff"));
     await fs.ensureDir((0, paths_1.orqintSpecDir)(cwd));
     await fs.ensureDir((0, paths_1.orqintArchiveDir)(cwd));
+    const { copiedPaths: userAssetsCopied } = await (0, user_assets_1.applyUserAssetsInit)(cwd, {
+        forceUserAssets: !!opts.forceUserAssets,
+    });
+    if (userAssetsCopied.length > 0) {
+        (0, logger_1.log)("info", "init_next_step", {
+            hint: "Open ORQINT.md in your project root for the workflow overview.",
+        });
+    }
     let memory = (0, memory_1.ensureDefaults)(JSON.parse(JSON.stringify(memory_1.EMPTY_MEMORY)));
     if (opts.brownfield) {
         memory = await seedFromRepo(cwd, memory);

package/dist/orqint/commands/sync-assets.d.ts

@@ -0,0 +1,6 @@
+export type SyncAssetsCliOptions = {
+    force: boolean;
+    migrate: boolean;
+    dryRun: boolean;
+};
+export declare function runSyncAssets(cwd: string, opts: SyncAssetsCliOptions): Promise<void>;

package/dist/orqint/commands/sync-assets.js

@@ -0,0 +1,75 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSyncAssets = runSyncAssets;
+const fs = __importStar(require("fs-extra"));
+const paths_1 = require("../engine/paths");
+const user_assets_1 = require("../engine/user-assets");
+async function runSyncAssets(cwd, opts) {
+    const memPath = (0, paths_1.memoryJsonPath)(cwd);
+    if (!(await fs.pathExists(memPath))) {
+        throw new Error(`No Orqint project here (missing ${memPath}). Run: orqint init`);
+    }
+    const result = await (0, user_assets_1.applyUserAssetsSync)(cwd, {
+        force: opts.force,
+        migrate: opts.migrate,
+        dryRun: opts.dryRun,
+    });
+    const byPathWould = new Map(result.wouldDo.map((w) => [w.path, w.action]));
+    const skipReason = new Map(result.skippedPaths.map((s) => [s.path, s.reason]));
+    const copiedSet = new Set(result.copiedPaths);
+    for (const { to: relTo } of user_assets_1.USER_ASSET_MANIFEST) {
+        if (opts.dryRun) {
+            const action = byPathWould.get(relTo);
+            if (action === "copy") {
+                console.error(`[dry-run] Would update ${relTo}`);
+            }
+            else {
+                const r = skipReason.get(relTo) ?? "no change";
+                console.error(`[dry-run] Would leave ${relTo} unchanged (${r})`);
+            }
+            continue;
+        }
+        if (copiedSet.has(relTo)) {
+            console.error(`Updated ${relTo}`);
+        }
+        else {
+            const r = skipReason.get(relTo);
+            if (r) {
+                console.error(`Left ${relTo} unchanged (${r})`);
+            }
+        }
+    }
+}

package/dist/orqint/commands/update.js

@@ -35,6 +35,11 @@ function fetchLatestFromNpm(name) {
  * Check npm registry for a newer version; optionally re-invoke via npx @latest.
  */
 function runUpdate(meta, install, forwardArgs) {
+    /** Subcommand after `--install` (e.g. `sync-assets`): always run via npx @latest so templates track the published CLI even when this binary already matches npm. */
+    if (install && forwardArgs.length > 0) {
+        const r = (0, child_process_1.spawnSync)("npx", ["--yes", `${meta.name}@latest`, ...forwardArgs], { stdio: "inherit", shell: process.platform === "win32" });
+        process.exit(r.status === null ? 1 : r.status);
+    }
     const latest = fetchLatestFromNpm(meta.name);
     if (!latest) {
         console.error(`Could not read latest version from npm for "${meta.name}".`);

package/dist/orqint/engine/paths.d.ts

@@ -1,5 +1,6 @@
 export declare function orqintRoot(cwd: string): string;
 export declare function memoryJsonPath(cwd: string): string;
+export declare function userAssetsLockPath(cwd: string): string;
 export declare function handoffDir(cwd: string): string;
 export declare function promptsDir(cwd: string): string;
 export declare function orqintSpecDir(cwd: string): string;

package/dist/orqint/engine/paths.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.orqintRoot = orqintRoot;
 exports.memoryJsonPath = memoryJsonPath;
+exports.userAssetsLockPath = userAssetsLockPath;
 exports.handoffDir = handoffDir;
 exports.promptsDir = promptsDir;
 exports.orqintSpecDir = orqintSpecDir;
@@ -46,6 +47,9 @@ function orqintRoot(cwd) {
 function memoryJsonPath(cwd) {
     return path.join(orqintRoot(cwd), "core", "memory.json");
 }
+function userAssetsLockPath(cwd) {
+    return path.join(orqintRoot(cwd), "core", "user-assets.lock.json");
+}
 function handoffDir(cwd) {
     return path.join(orqintRoot(cwd), ".handoff");
 }

package/dist/orqint/engine/user-assets.d.ts

@@ -0,0 +1,46 @@
+/** Installed package root (contains `user-assets/` next to `dist/`). */
+export declare function packageRootDir(): string;
+/** Paths relative to package root → relative to consumer cwd. */
+export declare const USER_ASSET_MANIFEST: {
+    from: string;
+    to: string;
+}[];
+export type UserAssetsLockFile = {
+    version: number;
+    cliVersionWhenWritten: string;
+    assets: Record<string, {
+        sha256: string;
+    }>;
+};
+export declare function lockKeyForDest(relTo: string): string;
+export declare function sha256OfFile(absPath: string): Promise<string>;
+export declare function sha256OfBuffer(buf: Buffer): string;
+export declare function readUserAssetsLock(cwd: string): Promise<UserAssetsLockFile | null>;
+export declare function writeUserAssetsLock(cwd: string, lock: UserAssetsLockFile): Promise<void>;
+export type UserAssetApplyResult = {
+    copiedPaths: string[];
+    skippedPaths: {
+        path: string;
+        reason: string;
+    }[];
+    wouldDo: {
+        path: string;
+        action: "copy" | "skip";
+    }[];
+};
+export type InitAssetOptions = {
+    forceUserAssets: boolean;
+};
+/**
+ * Init: copy missing assets (or all if forceUserAssets); update lock only for paths written.
+ */
+export declare function applyUserAssetsInit(cwd: string, opts: InitAssetOptions): Promise<UserAssetApplyResult>;
+export type SyncAssetOptions = {
+    force: boolean;
+    migrate: boolean;
+    dryRun: boolean;
+};
+/**
+ * Sync: safe update from package when on-disk file still matches lock; migrate/force overwrite all.
+ */
+export declare function applyUserAssetsSync(cwd: string, opts: SyncAssetOptions): Promise<UserAssetApplyResult>;

package/dist/orqint/engine/user-assets.js

@@ -0,0 +1,234 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.USER_ASSET_MANIFEST = void 0;
+exports.packageRootDir = packageRootDir;
+exports.lockKeyForDest = lockKeyForDest;
+exports.sha256OfFile = sha256OfFile;
+exports.sha256OfBuffer = sha256OfBuffer;
+exports.readUserAssetsLock = readUserAssetsLock;
+exports.writeUserAssetsLock = writeUserAssetsLock;
+exports.applyUserAssetsInit = applyUserAssetsInit;
+exports.applyUserAssetsSync = applyUserAssetsSync;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs-extra"));
+const crypto_1 = require("crypto");
+const paths_1 = require("./paths");
+const package_meta_1 = require("../package-meta");
+const logger_1 = require("../utils/logger");
+/** Installed package root (contains `user-assets/` next to `dist/`). */
+function packageRootDir() {
+    return path.join(__dirname, "..", "..", "..");
+}
+/** Paths relative to package root → relative to consumer cwd. */
+exports.USER_ASSET_MANIFEST = [
+    { from: path.join("user-assets", "AGENTS.md"), to: "AGENTS.md" },
+    { from: path.join("user-assets", "ORQINT.md"), to: "ORQINT.md" },
+    {
+        from: path.join("user-assets", "cursor-rules", "orqint-workflow.mdc"),
+        to: path.join(".cursor", "rules", "orqint-workflow.mdc"),
+    },
+];
+function lockKeyForDest(relTo) {
+    return relTo.split(path.sep).join("/");
+}
+function sha256OfFile(absPath) {
+    return fs.readFile(absPath).then((buf) => (0, crypto_1.createHash)("sha256").update(buf).digest("hex"));
+}
+function sha256OfBuffer(buf) {
+    return (0, crypto_1.createHash)("sha256").update(buf).digest("hex");
+}
+async function readUserAssetsLock(cwd) {
+    const p = (0, paths_1.userAssetsLockPath)(cwd);
+    if (!(await fs.pathExists(p))) {
+        return null;
+    }
+    try {
+        const raw = await fs.readJson(p);
+        if (raw &&
+            typeof raw === "object" &&
+            typeof raw.version === "number" &&
+            raw.assets &&
+            typeof raw.assets === "object") {
+            return raw;
+        }
+    }
+    catch {
+        (0, logger_1.log)("warn", "user_assets_lock_read_failed", { path: p });
+    }
+    return null;
+}
+async function writeUserAssetsLock(cwd, lock) {
+    const p = (0, paths_1.userAssetsLockPath)(cwd);
+    await fs.ensureDir(path.dirname(p));
+    await fs.writeJson(p, lock, { spaces: 2 });
+}
+/**
+ * Init: copy missing assets (or all if forceUserAssets); update lock only for paths written.
+ */
+async function applyUserAssetsInit(cwd, opts) {
+    const pkgRoot = packageRootDir();
+    const result = {
+        copiedPaths: [],
+        skippedPaths: [],
+        wouldDo: [],
+    };
+    const lock = (await readUserAssetsLock(cwd)) ?? {
+        version: 1,
+        cliVersionWhenWritten: "",
+        assets: {},
+    };
+    const meta = (0, package_meta_1.readPackageMeta)();
+    for (const { from: relFrom, to: relTo } of exports.USER_ASSET_MANIFEST) {
+        const from = path.join(pkgRoot, relFrom);
+        const to = path.join(cwd, relTo);
+        const key = lockKeyForDest(relTo);
+        if (!(await fs.pathExists(from))) {
+            (0, logger_1.log)("warn", "user_asset_bundled_missing", { from });
+            result.skippedPaths.push({ path: relTo, reason: "missing in package" });
+            continue;
+        }
+        const destExists = await fs.pathExists(to);
+        const shouldCopy = opts.forceUserAssets || !destExists;
+        if (!shouldCopy) {
+            (0, logger_1.log)("info", "init_user_asset_skipped_exists", { file: relTo });
+            result.skippedPaths.push({ path: relTo, reason: "already exists" });
+            continue;
+        }
+        await fs.ensureDir(path.dirname(to));
+        await fs.copy(from, to, { overwrite: opts.forceUserAssets });
+        const hash = await sha256OfFile(to);
+        lock.assets[key] = { sha256: hash };
+        lock.cliVersionWhenWritten = meta.version;
+        lock.version = 1;
+        (0, logger_1.log)("info", "init_user_asset_copied", { file: relTo });
+        result.copiedPaths.push(relTo);
+    }
+    if (result.copiedPaths.length > 0) {
+        await writeUserAssetsLock(cwd, lock);
+    }
+    return result;
+}
+/**
+ * Sync: safe update from package when on-disk file still matches lock; migrate/force overwrite all.
+ */
+async function applyUserAssetsSync(cwd, opts) {
+    const pkgRoot = packageRootDir();
+    const result = {
+        copiedPaths: [],
+        skippedPaths: [],
+        wouldDo: [],
+    };
+    let lock = await readUserAssetsLock(cwd);
+    const meta = (0, package_meta_1.readPackageMeta)();
+    for (const { from: relFrom, to: relTo } of exports.USER_ASSET_MANIFEST) {
+        const from = path.join(pkgRoot, relFrom);
+        const to = path.join(cwd, relTo);
+        const key = lockKeyForDest(relTo);
+        if (!(await fs.pathExists(from))) {
+            result.skippedPaths.push({ path: relTo, reason: "missing in package" });
+            continue;
+        }
+        const bundledBuf = await fs.readFile(from);
+        const bundledHash = sha256OfBuffer(bundledBuf);
+        const destExists = await fs.pathExists(to);
+        let shouldCopy = false;
+        let skipReason = "";
+        if (opts.force || opts.migrate) {
+            shouldCopy = true;
+        }
+        else if (!destExists) {
+            shouldCopy = true;
+        }
+        else if (!lock || !lock.assets[key]) {
+            shouldCopy = false;
+            skipReason =
+                "file exists but not in lock (run: orqint sync-assets --migrate once, or --force)";
+        }
+        else {
+            const diskHash = await sha256OfFile(to);
+            if (diskHash !== lock.assets[key].sha256) {
+                shouldCopy = false;
+                skipReason = "you edited this file; left unchanged";
+            }
+            else if (diskHash === bundledHash) {
+                shouldCopy = false;
+                skipReason = "already up to date";
+            }
+            else {
+                shouldCopy = true;
+            }
+        }
+        if (opts.dryRun) {
+            result.wouldDo.push({
+                path: relTo,
+                action: shouldCopy ? "copy" : "skip",
+            });
+            if (!shouldCopy) {
+                result.skippedPaths.push({
+                    path: relTo,
+                    reason: skipReason || "no change",
+                });
+            }
+            continue;
+        }
+        if (!shouldCopy) {
+            result.skippedPaths.push({
+                path: relTo,
+                reason: skipReason || "no change",
+            });
+            continue;
+        }
+        await fs.ensureDir(path.dirname(to));
+        await fs.writeFile(to, bundledBuf);
+        const newHash = sha256OfBuffer(bundledBuf);
+        if (!lock) {
+            lock = {
+                version: 1,
+                cliVersionWhenWritten: meta.version,
+                assets: {},
+            };
+        }
+        lock.assets[key] = { sha256: newHash };
+        lock.cliVersionWhenWritten = meta.version;
+        lock.version = 1;
+        result.copiedPaths.push(relTo);
+        (0, logger_1.log)("info", "user_asset_sync_copied", { file: relTo });
+    }
+    if (!opts.dryRun && lock && result.copiedPaths.length > 0) {
+        await writeUserAssetsLock(cwd, lock);
+    }
+    return result;
+}

package/dist/orqint/index.js

@@ -40,6 +40,7 @@ const think_1 = require("./commands/think");
 const plan_1 = require("./commands/plan");
 const package_meta_1 = require("./package-meta");
 const update_1 = require("./commands/update");
+const sync_assets_1 = require("./commands/sync-assets");
 function printHelp() {
     const { name, version } = (0, package_meta_1.readPackageMeta)();
     console.log(`${name} ${version} — Phase 1 (Cursor-native)
@@ -49,13 +50,15 @@ No model API keys in this tool: use Cursor on the generated handoff files, then
 Commands:
   orqint version | --version | -V
   orqint update [--install] [<args>...]   check npm; --install runs npx ${name}@latest <args>
-  orqint init [--brownfield] [--migrate-legacy] [--force]
+  orqint sync-assets [--force] [--dry-run] [--migrate]   refresh AGENTS/ORQINT/rules from package when safe
+  orqint init [--brownfield] [--migrate-legacy] [--force] [--force-user-assets]
   orqint think prepare "<intent>" [--override key=value ...]
   orqint think apply --file <path>
   orqint plan prepare [--force]
   orqint plan apply --file <path> [--force]
 
 Examples:
+  orqint update --install sync-assets   run latest CLI then sync templates (good after npm update)
   orqint init --brownfield
   orqint think prepare "Build a task dashboard" --override mobile_first=true
   orqint think apply --file orqint/.handoff/think.response.json
@@ -124,10 +127,23 @@ async function main() {
             (0, update_1.runUpdate)((0, package_meta_1.readPackageMeta)(), install, rest);
             return;
         }
+        if (cmd === "sync-assets") {
+            const args = argv.slice(1);
+            const force = takeFlag(args, "--force");
+            const migrate = takeFlag(args, "--migrate");
+            const dryRun = takeFlag(args, "--dry-run");
+            if (args.length > 0) {
+                throw new Error(`Unknown arguments: ${args.join(" ")}`);
+            }
+            await (0, sync_assets_1.runSyncAssets)(cwd, { force, migrate, dryRun });
+            process.exit(0);
+        }
         if (cmd === "init") {
             const args = argv.slice(1);
+            const forceUserAssets = takeFlag(args, "--force-user-assets");
             await (0, init_1.runInit)(cwd, {
                 force: takeFlag(args, "--force"),
+                forceUserAssets,
                 brownfield: takeFlag(args, "--brownfield"),
                 migrateLegacy: takeFlag(args, "--migrate-legacy"),
             });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@orqint/cli",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "CLI orchestration for Cursor-native think/plan workflows (Orqint)",
 	"keywords": [
 		"orqint",
@@ -21,7 +21,9 @@
 	"files": [
 		"dist",
 		"README.md",
-		"AGENTS.md"
+		"user-assets/AGENTS.md",
+		"user-assets/ORQINT.md",
+		"user-assets/cursor-rules/orqint-workflow.mdc"
 	],
 	"scripts": {
 		"prepublishOnly": "npm run build",

package/{AGENTS.md → user-assets/AGENTS.md}

@@ -10,17 +10,11 @@
 
 - Follow the JSON schema embedded in each handoff.
 - Honor `memory.override` from the sliced context.
-- No OpenAI (or other) API keys in the Orqint CLI; intelligence for `think`/`plan` runs here in Cursor.
+- No OpenAI (or other) API keys in the Orqint CLI; intelligence for `think`/`plan` runs in Cursor on the handoff files.
 
 ## Source of truth
 
 - **Canonical:** `orqint/core/memory.json`
 - **Derived:** `orqint-spec/`
 
-## Developing the Orqint CLI (this repository)
-
-- TypeScript: `packages/cli/src/`
-- Prompt templates to edit: `packages/cli/prompts/` (built into `dist/orqint/prompts/`)
-- **npm `version`:** bump per [docs/PRD/PRD.md](docs/PRD/PRD.md) §17 before each publish; see `.cursor/rules/orqint-versioning.mdc`.
-
-See [docs/Repository-layout.md](docs/Repository-layout.md), [docs/PRD/PRD.md](docs/PRD/PRD.md), and `.cursor/rules/orqint-workflow.mdc`.
+See **ORQINT.md** in this repository for commands and `init` options. Package: [@orqint/cli on npm](https://www.npmjs.com/package/@orqint/cli).

package/user-assets/ORQINT.md

@@ -0,0 +1,53 @@
+# Orqint — Cursor workflow (your project)
+
+Orqint drives **prepare → run in Cursor → apply**: the CLI writes handoff files; you run the Agent in Cursor on those files; you save **strict JSON** responses; the CLI merges into `orqint/core/memory.json`. No API keys are required in the CLI.
+
+## After `orqint init`
+
+- **Canonical state:** `orqint/core/memory.json`
+- **Derived docs:** `orqint-spec/`
+- **Handoffs:** `orqint/.handoff/`
+
+Read **`AGENTS.md`** in this repository for the short agent checklist (think/plan flow and rules). If `init` added **`.cursor/rules/orqint-workflow.mdc`**, Cursor can use it when you work in handoff files.
+
+## Commands (Phase 1)
+
+Use `npx @orqint/cli` or a local/global `orqint` binary the same way.
+
+| Step | Command |
+| --- | --- |
+| Think handoff | `orqint think prepare "<your intent>"` |
+| In Cursor | Open `orqint/.handoff/think.md`, run the Agent, write valid JSON to e.g. `orqint/.handoff/think.response.json` |
+| Merge think | `orqint think apply --file orqint/.handoff/think.response.json` |
+| Plan handoff | `orqint plan prepare` |
+| In Cursor | Same pattern → `orqint/.handoff/plan.response.json` |
+| Merge plan | `orqint plan apply --file orqint/.handoff/plan.response.json` |
+| Refresh templates after package update | `orqint sync-assets` (see below) |
+
+Follow the JSON schema embedded in each handoff file. Honor `memory.override` when the sliced context includes it.
+
+## Keeping `AGENTS.md`, `ORQINT.md`, and Cursor rules up to date
+
+After **`npm update @orqint/cli`**, run **`orqint sync-assets`**. Orqint updates each managed file **only if** it still matches what Orqint last wrote (tracked in **`orqint/core/user-assets.lock.json`**). If you edited a file, Orqint **leaves it alone** and tells you. **`memory.json`** is not changed.
+
+One-liner with the **latest** published CLI (useful if your global `orqint` is old):
+
+```bash
+orqint update --install sync-assets
+```
+
+- **`--dry-run`** — show actions only.
+- **`--migrate`** — once per old project: replace all managed templates from the package and create/update the full lock.
+- **`--force`** — overwrite every managed file and refresh the lock (power users).
+
+Commit **`orqint/core/user-assets.lock.json`** with the repo so teammates share the same baseline.
+
+## Optional flags (`init`)
+
+- `orqint init --brownfield` — seed `memory.json` hints from `package.json` / `README.md` when present.
+- `orqint init --force` — re-initialize **Orqint runtime** (e.g. `memory.json`, layout). Does **not** overwrite existing **`AGENTS.md`**, **`ORQINT.md`**, or **`.cursor/rules/orqint-workflow.mdc`** in your project.
+- `orqint init --force-user-assets` — refresh those Orqint-shipped files from the package (overwrites the paths above). Use when you want the latest templates from your installed CLI version. Prefer **`sync-assets`** for routine updates after `npm update` (does not reset memory).
+
+## Package reference
+
+Published CLI: [@orqint/cli on npm](https://www.npmjs.com/package/@orqint/cli).

package/user-assets/cursor-rules/orqint-workflow.mdc

@@ -0,0 +1,18 @@
+---
+description: Orqint think/plan handoffs — Cursor agent rules (user project)
+globs: orqint/.handoff/**
+alwaysApply: false
+---
+
+# Orqint (Phase 1)
+
+When the user works with **Orqint handoffs** (`orqint/.handoff/think.md`, `plan.md`):
+
+1. **Read** the handoff file they open; it contains sliced memory, the prompt template, and the **exact JSON schema** for your reply.
+2. **Output only JSON** matching that schema (no markdown fences unless they ask to save to `.json` — the file on disk must be parseable JSON).
+3. **Respect `memory.override`** (and any human overrides in the handoff): they override model defaults (e.g. no_supabase, mobile_first).
+4. **Open questions:** at most **3–5** high-value questions in `open_questions` when confidence is low.
+5. **Do not** invent API keys or ask the user to put secrets in the repo; Orqint does not use CLI-side model APIs.
+6. After you produce JSON, the user runs `orqint think apply --file ...` or `orqint plan apply --file ...` — remind them if they forget.
+
+For step-by-step usage, see **ORQINT.md** in the project root.