@repo-os/repoos 0.5.65 → 0.5.66

package/dist/.build-info.json

@@ -1,5 +1,5 @@
 {
-  "hash": "5139d67402c747817a7237d45bbdf3dc259350732a389c4dc4f1037533e74fc0",
-  "version": "0.5.65",
+  "hash": "90878be478d9457133036cf01bb56796b507ad255d1afc5321c1fb61bcec65a7",
+  "version": "0.5.66",
   "devUi": false
 }

package/dist/.build-stamp.json

@@ -1,3 +1,3 @@
 {
-  "generatedAt": "2026-10-05T04:53:51.934Z"
+  "generatedAt": "2026-10-06T02:22:31.964Z"
 }

package/dist/cli/help.js

@@ -8,6 +8,7 @@
  * usage line lives in per-command help rather than inline.
  */
 import { readVersion } from "../core/version.js";
+import { PRIORITIES, TASK_TYPES } from "../core/types.js";
 import { c } from "./colors.js";
 import { table, termWidth, visibleWidth, wrap } from "./layout.js";
 /** Commands whose own argument parser already handles `--help`. */
@@ -18,8 +19,9 @@ const GROUPS = [
         commands: [
             {
                 name: "init",
-                usage: "init [name]",
+                usage: "init [name|--dir <path>] [--new --description <text>|--description-file <path>|- --areas a,b --commit|--no-commit --launch|--no-launch --json] [--docs-from <dir|file|.zip>] [--starter vision|codebase] [--force]",
                 desc: "Scaffold work/, repoos.toml, AGENTS.md; guided flow for a new project",
+                flags: "new-project (--new/--yes): --description · --description-file · --areas · --layout · --commit/--no-commit · --launch/--no-launch · --preview-stub/--no-preview-stub · --dir · --force · --json. Any init: --docs-from <dir|file|.zip> · --starter vision|codebase · --force. Existing-repo init takes none of the new-project flags.",
             },
             {
                 name: "upgrade",
@@ -46,15 +48,21 @@ const GROUPS = [
             { name: "show", usage: "show <id>", desc: "Show a task's full spec" },
             {
                 name: "new",
-                usage: 'new "<title>" [--ai --type <t> --area <a> --priority <p> --body <b>]',
+                usage: `new "<title>" [--ai --type ${TASK_TYPES.join("|")} --area <a> --priority ${PRIORITIES.join("|")} --body <b>]`,
                 desc: "Create a task",
-                flags: "--ai --type --area --priority --body",
+                flags: `--ai · --type · --area · --priority · --body`,
             },
             {
                 name: "new-doc",
                 usage: 'new-doc "<desc>"',
                 desc: "Create a document from a description via the PM agent",
             },
+            {
+                name: "docs",
+                usage: "docs <import|scaffold> [path] [--force] [--dry-run]",
+                desc: "Import an existing doc set, or scaffold starter project docs",
+                flags: "--force · --dry-run",
+            },
             {
                 name: "note",
                 usage: 'note <id> "<text>"',
@@ -66,11 +74,17 @@ const GROUPS = [
                 desc: "Move a task to a new status — never merges code",
                 flags: '--note "..." · --force-not-merged',
             },
+            {
+                name: "rm",
+                usage: "rm <id> --yes",
+                desc: "Delete a task file from the repo (same as the UI Delete button)",
+                flags: "--yes",
+            },
             {
                 name: "update",
                 usage: "update <id> [flags]",
                 desc: "Edit a task's metadata or body",
-                flags: "--title --area --priority --type --body --branch --assigned-to",
+                flags: `--title · --area · --priority ${PRIORITIES.join("|")} · --type ${TASK_TYPES.join("|")} · --body · --branch · --assigned-to`,
             },
             {
                 name: "index",
@@ -171,6 +185,10 @@ const GROUPS = [
 const EXAMPLES = [
     { cmd: "repoos init" },
     { cmd: "repoos init myproject", comment: "guided new-project flow outside a git repo" },
+    {
+        cmd: 'repoos init myproject --new --description "A tiny social app" --areas web,api --no-launch',
+        comment: "non-interactive new project (no TTY, e.g. an agent)",
+    },
     {
         cmd: 'repoos new "Add company dashboard" --ai --type feature --area web,server --priority p1',
     },

package/dist/cli/index.js

@@ -4,8 +4,8 @@
  * Dependency-free arg routing — no commander/yargs needed for Stage 1.
  */
 import { cmdInit } from "../commands/init.js";
-import { cmdList, cmdShow, cmdMv, cmdUpdate, cmdNew, cmdIndex, cmdNote, } from "../commands/tasks.js";
-import { cmdNewDoc } from "../commands/docs.js";
+import { cmdList, cmdShow, cmdMv, cmdRm, cmdUpdate, cmdNew, cmdIndex, cmdNote, } from "../commands/tasks.js";
+import { cmdDocs, cmdNewDoc } from "../commands/docs.js";
 import { cmdGc } from "../commands/gc.js";
 import { cmdOutline } from "../commands/outline.js";
 import { cmdCheck } from "../commands/check.js";
@@ -152,6 +152,10 @@ function main() {
         case "note":
             cmdNote(rest);
             break;
+        case "rm":
+        case "delete":
+            cmdRm(rest);
+            break;
         case "update":
             cmdUpdate(rest);
             break;
@@ -162,6 +166,9 @@ function main() {
         case "new-doc":
             void cmdNewDoc(rest);
             break;
+        case "docs":
+            void cmdDocs(rest);
+            break;
         case "index":
         case "reindex":
             cmdIndex(rest);

package/dist/commands/check.js

@@ -43,6 +43,7 @@ import { extractFailedTests } from "../core/check-failure-summary.js";
 import { envToRunContext, getCheckStore, localMachineName, } from "../core/check-store.js";
 import { mainCheckoutRoot } from "../core/git.js";
 import { Logger } from "../core/logger.js";
+import { boardRootForEngineerRemote, boardTaskAbsPath, commitWipCheckpointForRemoteGate, isManagedEngineerCheck, runEngineerRemoteSelfCheckGate, } from "../server/engineer-remote-self-check.js";
 import { createRemoteValidator } from "../server/remote-validation.js";
 import { runRemotePreReviewGate, standaloneCliCanUseRemote, remoteValidationAlreadyAttempted, uncommittedFilesBlockingRemoteGate, shouldRunCliRemotePreReviewGate, } from "../server/pre-review-remote-gate.js";
 /**
@@ -1391,7 +1392,10 @@ async function stepTests(ctx) {
     // A full unscoped run is ~10min healthy and can legitimately reach ~25min on
     // a slow box; a too-tight cap SIGTERMs a green suite (exit 143). Vitest's own
     // per-test timeout fails a genuine hang fast — this is the outer backstop.
-    const timeoutMs = changedRef ? 300_000 : 1_500_000;
+    // Scoped runs still execute the full wrapped suite (main pass + boot-timing);
+    // on a laptop that legitimately finishes in ~5–6 minutes, a 300s cap SIGTERMs
+    // a green run (exit 143) — see AGENTS.md debugging-check-failures.
+    const timeoutMs = changedRef ? 420_000 : 1_500_000;
     const res = await runCommand({ command, cwd: ctx.cwd, timeoutMs, env });
     if (res.status === "passed") {
         return {
@@ -1811,7 +1815,7 @@ export async function cmdCheck(argv = []) {
     }
     if (cfg.remoteValidation?.enabled &&
         !standaloneCliCanUseRemote(cfg) &&
-        !changedRef &&
+        !isManagedEngineerCheck(process.env) &&
         !opts.localTestsOnly &&
         !remoteValidationAlreadyAttempted(process.env)) {
         console.log(c.dim("  · remote validation: the Hetzner runner is owned by the server, so a standalone " +
@@ -1819,15 +1823,26 @@ export async function cmdCheck(argv = []) {
     }
     let runRemoteGate = shouldRunCliRemotePreReviewGate(cfg, { ...opts, changedRef }, process.env);
     if (runRemoteGate) {
-        // The runner tests a bundle of HEAD. Uncommitted work would be skipped by it
-        // and then unverified locally (tests are skipped after a remote pass), so
-        // test the working tree locally instead and say why.
         const uncommitted = await uncommittedFilesBlockingRemoteGate(repoRoot, cfg);
         if (uncommitted.length > 0) {
-            runRemoteGate = false;
-            const shown = uncommitted.slice(0, 5).join(", ");
-            console.log(c.yellow(`  ⚠ uncommitted changes (${shown}${uncommitted.length > 5 ? ", …" : ""}) — the remote ` +
-                "gate tests committed HEAD only, so running the full local gate on the working tree instead\n"));
+            if (isManagedEngineerCheck(process.env)) {
+                const taskId = process.env.REPOOS_TASK_ID.trim();
+                const wipErr = await commitWipCheckpointForRemoteGate(repoRoot, cfg, taskId);
+                if (wipErr) {
+                    runRemoteGate = false;
+                    console.log(c.yellow(`  ⚠ uncommitted changes — could not commit a WIP checkpoint (${wipErr}); ` +
+                        "running the full local gate on the working tree instead\n"));
+                }
+                else {
+                    console.log(c.dim("  · uncommitted work committed as a WIP checkpoint so the remote runner tests this tree\n"));
+                }
+            }
+            else {
+                runRemoteGate = false;
+                const shown = uncommitted.slice(0, 5).join(", ");
+                console.log(c.yellow(`  ⚠ uncommitted changes (${shown}${uncommitted.length > 5 ? ", …" : ""}) — the remote ` +
+                    "gate tests committed HEAD only, so running the full local gate on the working tree instead\n"));
+            }
         }
     }
     // The plan never runs when the remote gate fails, so the normal end-of-run
@@ -1858,83 +1873,98 @@ export async function cmdCheck(argv = []) {
     };
     if (runRemoteGate) {
         heading("Remote validation");
-        const logger = new Logger({ root: repoRoot });
-        let remoteValidator;
-        try {
-            remoteValidator = createRemoteValidator(cfg, logger);
-        }
-        catch (e) {
-            const msg = `remote validation init failed: ${e.message}`;
-            if (!cfg.remoteValidation?.fallbackToLocal) {
-                console.log(c.red(`\n  ✗ ${msg}\n`));
-                persistRemoteFailure(msg, "", new Date());
-                // The runner never dispatched, so nothing else will record this
-                // failed remote attempt in the history (#0564). Record it here —
-                // machine unknown (no host was ever chosen), remote half only.
-                recordRunHistoryRow({
-                    root: checkStoreRoot,
-                    cacheDir: cfg.cacheDir,
-                    scope: "full",
-                    startedAt: new Date().toISOString(),
-                    durationMs: 0,
-                    outcome: "fail",
-                    failedStep: "remote-validation",
-                    skippedSteps: [],
-                    detail: msg,
-                });
+        const managed = isManagedEngineerCheck(process.env);
+        const taskId = process.env.REPOOS_TASK_ID?.trim() || "pre-review";
+        const remoteStartedAt = new Date();
+        let remoteOutput = "";
+        const prevStoreRoot = process.env.REPOOS_CHECK_STORE_ROOT;
+        process.env.REPOOS_CHECK_STORE_ROOT = checkStoreRoot;
+        const applyRemoteGateOutcome = (gate) => {
+            if (gate.kind === "fail") {
+                console.log(c.red(`\n  ✗ ${gate.detail}\n`));
+                persistRemoteFailure(gate.detail, remoteOutput, remoteStartedAt);
                 process.exit(1);
             }
-            console.log(c.yellow(`  ⚠ ${msg} — running the full local gate\n`));
-        }
-        if (remoteValidator) {
-            // Route the runner's own history rows (recordRemoteRunHistory reads
-            // this env) to the resolved store root for THIS dispatch only, then
-            // restore — a process-wide export here would leak into the check
-            // plan's child processes (the test suite's own check-store fixtures
-            // record via the same env and would land in the live store).
-            const prevStoreRoot = process.env.REPOOS_CHECK_STORE_ROOT;
-            process.env.REPOOS_CHECK_STORE_ROOT = checkStoreRoot;
-            try {
-                const taskId = process.env.REPOOS_TASK_ID?.trim() || "pre-review";
-                const remoteStartedAt = new Date();
-                let remoteOutput = "";
-                // Which gate is calling (#0564): a caller-supplied task id means this is
-                // a pre-review pass for that task; otherwise a bare CLI run.
-                const { phase: runPhase } = envToRunContext(process.env);
-                const gate = await runRemotePreReviewGate({
-                    config: cfg,
-                    remoteValidator,
+            if (gate.kind === "local-only" && gate.skipTests) {
+                process.env.REPOOS_SKIP_TESTS = "1";
+                console.log(c.green("  ✔ remote gate passed — running local guards only\n"));
+            }
+            else if (gate.kind === "local-only") {
+                console.log(c.yellow("  ⚠ remote unavailable — running the full local gate\n"));
+            }
+        };
+        try {
+            if (managed) {
+                const boardRoot = boardRootForEngineerRemote(repoRoot);
+                const gateConfig = loadConfig(boardRoot);
+                const taskAbsPath = /^\d+$/.test(taskId) ? boardTaskAbsPath(gateConfig, taskId) : undefined;
+                const gate = await runEngineerRemoteSelfCheckGate({
+                    worktreeConfig: cfg,
                     worktreePath: repoRoot,
                     taskId,
-                    phase: runPhase,
+                    taskAbsPath,
                     onChunk: (chunk) => {
                         remoteOutput += chunk;
                         process.stdout.write(chunk);
                     },
                 });
-                // Await the teardown: the failure path below exits the process, and an
-                // un-awaited async runner delete would be cut off mid-request, leaking a
-                // warm VM that no idle timer survives the exit to reap.
-                await remoteValidator.dispose().catch(() => { });
-                if (gate.kind === "fail") {
-                    console.log(c.red(`\n  ✗ ${gate.detail}\n`));
-                    persistRemoteFailure(gate.detail, remoteOutput, remoteStartedAt);
-                    process.exit(1);
+                applyRemoteGateOutcome(gate);
+            }
+            else {
+                const logger = new Logger({ root: repoRoot });
+                let remoteValidator;
+                try {
+                    remoteValidator = createRemoteValidator(cfg, logger);
                 }
-                if (gate.kind === "local-only" && gate.skipTests) {
-                    process.env.REPOOS_SKIP_TESTS = "1";
-                    console.log(c.green("  ✔ remote gate passed — running local guards only\n"));
+                catch (e) {
+                    const msg = `remote validation init failed: ${e.message}`;
+                    if (!cfg.remoteValidation?.fallbackToLocal) {
+                        console.log(c.red(`\n  ✗ ${msg}\n`));
+                        persistRemoteFailure(msg, "", new Date());
+                        recordRunHistoryRow({
+                            root: checkStoreRoot,
+                            cacheDir: cfg.cacheDir,
+                            scope: "full",
+                            startedAt: new Date().toISOString(),
+                            durationMs: 0,
+                            outcome: "fail",
+                            failedStep: "remote-validation",
+                            skippedSteps: [],
+                            detail: msg,
+                        });
+                        process.exit(1);
+                    }
+                    console.log(c.yellow(`  ⚠ ${msg} — running the full local gate\n`));
                 }
-                else if (gate.kind === "local-only") {
-                    console.log(c.yellow("  ⚠ remote unavailable — running the full local gate\n"));
+                if (remoteValidator) {
+                    try {
+                        const { phase: runPhase } = envToRunContext(process.env);
+                        const gate = await runRemotePreReviewGate({
+                            config: cfg,
+                            remoteValidator,
+                            worktreePath: repoRoot,
+                            taskId,
+                            phase: runPhase,
+                            onChunk: (chunk) => {
+                                remoteOutput += chunk;
+                                process.stdout.write(chunk);
+                            },
+                        });
+                        await remoteValidator.dispose().catch(() => { });
+                        applyRemoteGateOutcome(gate);
+                    }
+                    catch (e) {
+                        await remoteValidator.dispose().catch(() => { });
+                        throw e;
+                    }
                 }
             }
-            finally {
-                if (prevStoreRoot === undefined)
-                    delete process.env.REPOOS_CHECK_STORE_ROOT;
-                else
-                    process.env.REPOOS_CHECK_STORE_ROOT = prevStoreRoot;
-            }
+        }
+        finally {
+            if (prevStoreRoot === undefined)
+                delete process.env.REPOOS_CHECK_STORE_ROOT;
+            else
+                process.env.REPOOS_CHECK_STORE_ROOT = prevStoreRoot;
         }
     }
     const runStartedAt = new Date();

package/dist/commands/docs-io.d.ts

@@ -0,0 +1,19 @@
+import { type DocsImportResult } from "../core/project-docs.js";
+/** Print an import result (shared by `docs import` and `init --docs-from`). */
+export declare function reportDocsImport(result: DocsImportResult, dryRun: boolean): void;
+/**
+ * Copy a doc set into a repo's docsDir and report it. Never throws: a bad
+ * source prints a clear error and returns false, so init still completes with
+ * the scaffold it already wrote.
+ */
+export declare function importDocsInto(root: string, docsDir: string, source: string, opts?: {
+    force?: boolean;
+    dryRun?: boolean;
+}): boolean;
+/** Write the opt-in starter skeleton into docsDir and report it. */
+export declare function scaffoldDocsInto(root: string, docsDir: string): void;
+/** Resolve a repo's docsDir from the current working directory. */
+export declare function currentDocsDir(): {
+    root: string;
+    docsDir: string;
+};

package/dist/commands/docs-io.js

@@ -0,0 +1,66 @@
+/**
+ * Shared CLI helpers for the opt-in project-docs flow (#0673). Both
+ * `repoos docs ...` and `repoos init --docs-from` use these, so the reporting
+ * lives here rather than in either command and init never has to import the
+ * PM-agent-backed `docs.ts`.
+ */
+import { join } from "node:path";
+import { findRepoRoot, loadConfig } from "../core/config.js";
+import { expandHome, importProjectDocs, scaffoldStarterDocs, } from "../core/project-docs.js";
+import { c } from "../cli/colors.js";
+/** Print an import result (shared by `docs import` and `init --docs-from`). */
+export function reportDocsImport(result, dryRun) {
+    const verb = dryRun ? "would copy" : "copied";
+    if (result.note)
+        console.log(c.dim("  " + result.note));
+    for (const e of result.created)
+        console.log("  " + c.green(verb + " ") + e.path);
+    for (const e of result.overwritten)
+        console.log("  " + c.yellow("overwrote ") + e.path + c.dim(" (--force)"));
+    for (const e of result.skipped)
+        console.log("  " + c.dim("exists  " + e.path));
+    const total = result.created.length + result.overwritten.length;
+    if (total === 0 && result.skipped.length === 0) {
+        console.log(c.dim("  nothing to copy"));
+    }
+    else {
+        console.log("  " + c.dim(`${total} file${total === 1 ? "" : "s"} ${verb}`));
+    }
+    if (result.skipped.length > 0 && !dryRun) {
+        console.log(c.dim("  Re-run with --force to overwrite the existing files."));
+    }
+}
+/**
+ * Copy a doc set into a repo's docsDir and report it. Never throws: a bad
+ * source prints a clear error and returns false, so init still completes with
+ * the scaffold it already wrote.
+ */
+export function importDocsInto(root, docsDir, source, opts = {}) {
+    const expanded = expandHome(source.trim());
+    try {
+        const result = importProjectDocs(expanded, join(root, docsDir), opts);
+        reportDocsImport(result, opts.dryRun === true);
+        return true;
+    }
+    catch (err) {
+        console.error(c.red("  " + err.message));
+        return false;
+    }
+}
+/** Write the opt-in starter skeleton into docsDir and report it. */
+export function scaffoldDocsInto(root, docsDir) {
+    const result = scaffoldStarterDocs(join(root, docsDir));
+    for (const f of result.created)
+        console.log("  " + c.green("created ") + f);
+    for (const f of result.skipped)
+        console.log("  " + c.dim("exists  " + f));
+    if (result.created.length === 0) {
+        console.log(c.dim(`  ${docsDir}/ already has the starter files.`));
+    }
+}
+/** Resolve a repo's docsDir from the current working directory. */
+export function currentDocsDir() {
+    const root = findRepoRoot(process.cwd());
+    const config = loadConfig(root);
+    return { root, docsDir: config.docsDir };
+}

package/dist/commands/docs.d.ts

@@ -1,2 +1,11 @@
 /** `repoos new-doc "<description>"` or `repoos new-doc --path docs/foo.md --content-file x.md` */
 export declare function cmdNewDoc(args: string[]): Promise<void>;
+/**
+ * `repoos docs import <dir|file|.zip> [--force] [--dry-run]`
+ * `repoos docs scaffold`
+ *
+ * Opt-in helpers around `docsDir` (#0673): copy an existing doc set, or write a
+ * minimal starter skeleton. Neither runs on its own, and scaffold never
+ * overwrites — an existing file is left exactly as it was.
+ */
+export declare function cmdDocs(args: string[]): Promise<void>;

package/dist/commands/docs.js

@@ -6,6 +6,7 @@ import { createDocument, createFreeformDocument, docFreeformPrompt, parseGenerat
 import { loadConfig } from "../core/config.js";
 import { c } from "../cli/colors.js";
 import { resolvePmAgent, runPrompt, recordOneShotSession } from "../server/agents.js";
+import { currentDocsDir, importDocsInto, scaffoldDocsInto } from "./docs-io.js";
 /** `repoos new-doc "<description>"` or `repoos new-doc --path docs/foo.md --content-file x.md` */
 export async function cmdNewDoc(args) {
     const flags = {};
@@ -68,3 +69,51 @@ export async function cmdNewDoc(args) {
         process.exitCode = 1;
     }
 }
+/**
+ * `repoos docs import <dir|file|.zip> [--force] [--dry-run]`
+ * `repoos docs scaffold`
+ *
+ * Opt-in helpers around `docsDir` (#0673): copy an existing doc set, or write a
+ * minimal starter skeleton. Neither runs on its own, and scaffold never
+ * overwrites — an existing file is left exactly as it was.
+ */
+export async function cmdDocs(args) {
+    const [sub, ...rest] = args;
+    if (sub === "import") {
+        let force = false;
+        let dryRun = false;
+        const positional = [];
+        for (const a of rest) {
+            if (a === "--force")
+                force = true;
+            else if (a === "--dry-run")
+                dryRun = true;
+            else
+                positional.push(a);
+        }
+        const source = positional.join(" ").trim();
+        if (!source) {
+            console.error(c.red("  Usage: repoos docs import <dir|file|.zip> [--force] [--dry-run]"));
+            process.exitCode = 1;
+            return;
+        }
+        const { root, docsDir } = currentDocsDir();
+        if (!importDocsInto(root, docsDir, source, { force, dryRun }))
+            process.exitCode = 1;
+        return;
+    }
+    if (sub === "scaffold") {
+        if (rest.includes("--force")) {
+            console.error(c.red("  repoos docs scaffold never overwrites — remove a file you want rebuilt, then re-run."));
+            process.exitCode = 1;
+            return;
+        }
+        const { root, docsDir } = currentDocsDir();
+        scaffoldDocsInto(root, docsDir);
+        return;
+    }
+    console.error(c.red("  Usage: repoos docs <import|scaffold> ..."));
+    console.error(c.dim("    repoos docs import <dir|file|.zip> [--force] [--dry-run]"));
+    console.error(c.dim("    repoos docs scaffold"));
+    process.exitCode = 1;
+}

package/dist/commands/init.d.ts

@@ -29,6 +29,34 @@ export declare function areaVocabularyTomlAddition(areas: string[], previewStub:
 type ScaffoldLayout = string;
 /** Which starter task to seed beyond 0001 — a blank project or an existing repo. */
 type ScaffoldKind = "new" | "existing";
+/**
+ * Which starter body to seed. `vision` is the new-project starter (flesh out
+ * the product vision); `codebase` is the existing-repo one (read the code and
+ * propose docs + a backlog). Selected by the repo's content for the
+ * non-guided path, overridable via `--starter vision|codebase`.
+ */
+export type StarterChoice = "vision" | "codebase";
+/**
+ * True when a single repo-relative path represents real project content, as
+ * opposed to RepoOS's scaffold or generic boilerplate. Pure, so the starter
+ * decision is unit-testable without a filesystem.
+ */
+export declare function isMeaningfulRepoPath(relPath: string): boolean;
+/**
+ * Decide which starter to seed from the repo's content: a repo with no
+ * meaningful source files is effectively empty (a fresh `git init`, a README,
+ * or only RepoOS's own scaffold), so it gets the product-vision starter; once
+ * there is code to read, it gets the read-the-codebase starter.
+ *
+ * Uses only the path list, so callers can stop walking as soon as they find
+ * something meaningful.
+ */
+export declare function repoHasMeaningfulContent(relPaths: string[]): boolean;
+/**
+ * Walk a repo's tree and report whether it holds any meaningful content.
+ * Prunes heavy/generated directories and stops at the first real file.
+ */
+export declare function detectMeaningfulRepoContent(root: string): boolean;
 /**
  * True when the canary counter lives directly inside the root-level `.repoos/`
  * runtime directory (cacheDir of ".repoos", or a cacheDir nested under it).
@@ -38,9 +66,22 @@ export declare function scaffoldInto(root: string, description: string, layout?:
 /** Areas collected at init time (#0583) — real `[[areas]]` rows when given. */
 areas?: string[], 
 /** When true, scaffold commented `[[preview.targets]]` stubs for those areas. */
-previewStub?: boolean): {
+previewStub?: boolean, 
+/**
+ * Force which starter body to seed. Omitted, a fresh install inside an
+ * existing repo picks by content: an effectively empty repo gets the
+ * product-vision starter, a repo with real source gets read-the-codebase.
+ */
+starter?: StarterChoice): {
     created: string[];
     skipped: string[];
+    starter: StarterChoice;
+};
+/** Split `--docs-from <path>` / `--force` off an init argument list. */
+export declare function parseDocsFromArgs(args: string[]): {
+    positional: string[];
+    docsFrom: string | null;
+    force: boolean;
 };
 /**
  * Validate a user-supplied namespace string. Returns null when the input means
@@ -49,5 +90,48 @@ previewStub?: boolean): {
  * distinguishes valid from error by checking `result.startsWith("!")`.
  */
 export declare function validateNamespace(input: string): string;
+/**
+ * Answers to the guided new-project flow, whether they came from interactive
+ * prompts or from CLI flags. Keeping one record means the interactive and
+ * non-interactive paths run the exact same scaffolding code — only where the
+ * answers come from differs.
+ */
+interface NewProjectOptions {
+    /** Parsed from `--new`/`--yes`; required to run non-interactively. */
+    nonInteractive: boolean;
+    /** Positional name or `--dir`; empty = the current directory. */
+    projectDir: string;
+    description: string;
+    areas: string[];
+    /** `--layout` (`repoos` default, `/` for root, or a namespace path). */
+    layout: ScaffoldLayout;
+    /** `--preview-stub` / `--no-preview-stub`; only meaningful with areas. */
+    previewStub: boolean;
+    commit: boolean;
+    launch: boolean;
+    force: boolean;
+    json: boolean;
+    /** `--docs-from` import source; interactive flow prompts when absent (#0673). */
+    docsFrom: string | null;
+}
+/**
+ * Parse the `repoos init` argument vector. Returns the shared options record
+ * plus an error string (prefixed `!`) when a flag is malformed. `--dir` is an
+ * alias for the positional name; both name a subdirectory under the cwd.
+ */
+export declare function parseInitFlags(args: string[], tty: boolean): {
+    options: NewProjectOptions;
+    error: string | null;
+};
+/**
+ * Parse `--starter vision|codebase` (also `--starter=vision`) out of `args`,
+ * returning the choice (or `undefined` when absent) and the remaining args with
+ * the flag removed, so downstream parsing never mistakes it for a project name.
+ * An unknown value is rejected loudly rather than silently falling back.
+ */
+export declare function parseStarterOption(args: string[]): {
+    starter?: StarterChoice;
+    rest: string[];
+};
 export declare function cmdInit(args: string[]): Promise<void>;
 export {};