@popoverai/dotrequirements 0.27.3 → 0.28.0

package/README.md

@@ -124,37 +124,41 @@ Link your local environment to an existing project (when you already have a proj
 dotreq link
 ```
 
-### `dotreq pull`
+### `dotreq diff`
 
-Sync requirements from dot•requirements cloud to local `.requirements/` files.
+Show how the repo and the cloud differ, read-only. Each document gets a verdict (in sync, additions in repo, additions in cloud, conflict, only in repo, only in cloud, invalid file).
 
 ```bash
-dotreq pull
-dotreq pull --project <project-id>
-dotreq pull --document <document-id>
-dotreq pull --share <token>
+dotreq diff
+dotreq diff auth.requirements.md   # detail for one or more documents
+dotreq diff --exit-code            # exit 1 on any drift (for CI)
 ```
 
-**First-time setup with a share token:**
+### `dotreq sync`
 
-If a team member shares a pull command with you, you can pull requirements without creating an account:
+Reconcile the repo and the cloud. With no flags, both sides contribute their additions and nothing contested is touched.
 
 ```bash
-npx @popoverai/dotrequirements@latest pull --share drt_abc123...
+dotreq sync                        # both sides contribute (additive, safe)
+dotreq sync --cloud-contributes    # bring the cloud's additions down only
+dotreq sync --repo-contributes     # send the repo's additions up only
+dotreq sync --repo-wins            # repo is authoritative (may delete in cloud)
+dotreq sync --cloud-wins           # cloud is authoritative (may delete locally)
+dotreq sync --yes                  # skip the deletion confirmation
 ```
 
-This gives you read-only access to view requirements. To push changes or report coverage, run `dotreq link` afterward.
+Additive modes never delete; a `--wins` mode can, and lists every document it will permanently delete before writing.
 
-### `dotreq push`
+**First-time setup with a share token:**
 
-Push local requirements to dot•requirements cloud.
+If a team member shares a sync command with you, you can sync requirements down without creating an account:
 
 ```bash
-dotreq push
-dotreq push .requirements/auth.requirements.md
-dotreq push --yes  # Skip confirmation
+npx @popoverai/dotrequirements@latest sync --share drt_abc123...
 ```
 
+This gives you read-only access to view requirements. To contribute changes or report coverage, run `dotreq link` afterward.
+
 ### `dotreq validate`
 
 Validate requirements files against the schema.
@@ -608,24 +612,24 @@ See [MARKDOWN_SCHEMA.md](https://github.com/PopoverAI/dotrequirements/blob/main/
 
 ## AI Assistant Integration
 
-AI coding assistants use the CLI verbs directly — no MCP server to install or configure. `dotreq ai-setup` writes the requirements-driven workflow guidance into your assistant's context file (CLAUDE.md / AGENTS.md), which tells the agent when to explore, validate, style-review, and push. For chat apps (Claude, ChatGPT), use the dot•requirements remote connector instead.
+AI coding assistants use the CLI verbs directly — no MCP server to install or configure. `dotreq ai-setup` writes the requirements-driven workflow guidance into your assistant's context file (CLAUDE.md / AGENTS.md), which tells the agent when to explore, validate, style-review, and sync. For chat apps (Claude, ChatGPT), use the dot•requirements remote connector instead.
 
 > The local MCP server shipped by earlier versions is retired. `dotreq ai-setup` removes stale MCP registrations; `dotreq mcp` now exits with a pointer to this migration.
 
 ### CI/CD Mode
 
-For CI/CD environments (GitHub Actions, etc.), use the global `--auth-from-env` flag so cloud commands read credentials from environment variables instead of `project-settings.json`:
+In CI/CD environments (GitHub Actions, etc.) where no `.requirements/project-settings.json` is present, the CLI authenticates from environment variables automatically — no flag required — and prints a notice to stderr:
 
 ```bash
-dotreq --auth-from-env push
-dotreq --auth-from-env style-check .requirements/auth.requirements.md --source cloud
+dotreq sync --repo-contributes
+dotreq style-check .requirements/auth.requirements.md --source cloud
 ```
 
 Required environment variables:
 - `DOTREQ_PROJECT_ID` — Your project slug
 - `DOTREQ_PROJECT_SECRET` — Your project secret
 
-**Important:** Without `--auth-from-env`, these environment variables are ignored. This explicit opt-in prevents credential conflicts between local and CI environments.
+**Important:** A settings file on disk always wins over these environment variables, so a local checkout is never overridden by an ambient environment. The environment is used only when no settings file is found.
 
 See the [CI/CD Integration docs](https://docs.dotrequirements.io/tools/ai/ci-cd) for complete examples.
 

package/dist/cli.js

@@ -5,8 +5,10 @@ import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { acceptanceTestCommand } from "./commands/acceptance-test.js";
 import { aiSetupCommand } from "./commands/ai-setup.js";
+import { pullAlias, pushAlias } from "./commands/aliases.js";
 import { registerCodebaseToSpec } from "./commands/codebase-to-spec/index.js";
 import { createRequirementDocumentCommand } from "./commands/create-requirement-document.js";
+import { diffCommand } from "./commands/diff.js";
 import { finalizeCommand } from "./commands/finalize.js";
 import { getCommand } from "./commands/get.js";
 import { initCommand } from "./commands/init.js";
@@ -14,17 +16,16 @@ import { linkCommand } from "./commands/link.js";
 import { listCommand } from "./commands/list.js";
 import { mcpCommand } from "./commands/mcp.js";
 import { prepareCommand } from "./commands/prepare.js";
-import { pullCommand } from "./commands/pull.js";
-import { pushCommand } from "./commands/push.js";
 import { reportCommand } from "./commands/report.js";
 import { requirementsForCommand } from "./commands/requirements-for.js";
 import { reviewTestCommand } from "./commands/review-test.js";
 import { searchCommand } from "./commands/search.js";
 import { styleCheckCommand } from "./commands/style-check.js";
+import { syncCliAction } from "./commands/sync.js";
 import { testsForCommand } from "./commands/tests-for.js";
 import { validateCommand } from "./commands/validate.js";
 import { loadEnvFile } from "./utils/env.js";
-import { setAuthFromEnv } from "./utils/project-settings.js";
+import { setPreferEnvCredentials } from "./utils/project-settings.js";
 // Read version from package.json
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -57,13 +58,14 @@ program
     .name("dotrequirements")
     .description("Requirements tracking CLI with test harness")
     .version(VERSION)
-    // AUTHZ-6: explicit CI/CD credential injection — with this flag, cloud
-    // commands read DOTREQ_PROJECT_ID / DOTREQ_PROJECT_SECRET instead of
-    // project-settings.json; without it those variables are ignored.
-    .option("--auth-from-env", "Read cloud credentials from DOTREQ_PROJECT_ID and DOTREQ_PROJECT_SECRET (CI/CD)")
+    // SYNC-ALIAS-1.3: deprecated — environment fallback is automatic now (AUTHZ-6),
+    // but invocations already in users' CI pass this flag; keep its original
+    // semantics (env replaces file discovery) rather than hard-erroring.
+    .option("--auth-from-env", "Deprecated: environment credentials are now used automatically when no settings file is present")
     .hook("preAction", (thisCommand) => {
     if (thisCommand.opts().authFromEnv) {
-        setAuthFromEnv(true);
+        process.stderr.write("Note: --auth-from-env is deprecated — the CLI now authenticates from DOTREQ_PROJECT_ID / DOTREQ_PROJECT_SECRET automatically when no settings file is present.\n");
+        setPreferEnvCredentials(true);
     }
 });
 program
@@ -82,18 +84,38 @@ program
     .option("--create", "Create a new project (implies --yes)")
     .option("-n, --name <name>", "Project name for --create or rename")
     .action(wrapCommand(linkCommand));
+program
+    .command("diff [scope...]")
+    .description("Show how the repo and the cloud differ (read-only)")
+    .option("-s, --share <token>", "Read-only share token (no setup required)")
+    .option("-p, --project <id>", "Override the project slug")
+    .option("--exit-code", "Exit 1 when any document is not in sync (for CI)")
+    .action(wrapCommand(diffCommand));
+program
+    .command("sync [scope...]")
+    .description("Reconcile the repo and the cloud")
+    .option("--cloud-contributes", "Apply only the cloud's additions locally")
+    .option("--repo-contributes", "Apply only the repo's additions to the cloud")
+    .option("--cloud-wins", "Cloud is authority: the repo matches it (may delete)")
+    .option("--repo-wins", "Repo is authority: the cloud matches it (may delete)")
+    .option("-s, --share <token>", "Read-only share token (no setup required)")
+    .option("-p, --project <id>", "Override the project slug")
+    .option("-y, --yes", "Skip the deletion confirmation prompt")
+    .action(wrapCommand(syncCliAction));
+// Deprecated aliases into `sync`, kept for commands already in the wild
+// (SYNC-ALIAS-1). Each prints a deprecation notice naming its new spelling.
 program
     .command("pull")
-    .description("Sync requirements from cloud to local .requirements/ files")
+    .description("Deprecated: use `sync --cloud-contributes`")
     .option("-p, --project <id>", "Project ID to sync")
     .option("-d, --document <id>", "Specific document ID to sync")
     .option("-s, --share <token>", "Read-only share token for quick onboarding (no setup required)")
-    .action(wrapCommand(pullCommand));
+    .action(wrapCommand(pullAlias));
 program
     .command("push [file]")
-    .description("Push local requirements from .requirements/ to cloud")
+    .description("Deprecated: use `sync --repo-contributes`")
     .option("-y, --yes", "Skip confirmation prompt")
-    .action(wrapCommand(pushCommand));
+    .action(wrapCommand(pushAlias));
 program
     .command("validate")
     .description("Validate requirements files in .requirements/")

package/dist/commands/aliases.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Deprecated `push` / `pull` verbs, kept as aliases into `dotreq sync` for the
+ * commands already in the wild — distributed `pull --share` onboarding
+ * commands, users' CI pipelines, ai-setup-installed guidance (SYNC-ALIAS-1).
+ * Each prints a deprecation notice naming its new spelling. First-party code
+ * calls `sync` directly; only these aliases remain.
+ */
+interface PullAliasOptions {
+    project?: string;
+    document?: string;
+    share?: string;
+}
+/** `dotreq pull` → `dotreq sync --cloud-contributes` (SYNC-ALIAS-1.0). */
+export declare function pullAlias(options: PullAliasOptions): Promise<void>;
+interface PushAliasOptions {
+    yes?: boolean;
+}
+/** `dotreq push [file]` → `dotreq sync --repo-contributes [scope]` (SYNC-ALIAS-1.1).
+ *
+ * Deliberately safer than the push it shadows: old push overwrote a diverged
+ * cloud document after a y/N (or silently with --yes); the alias flags it as a
+ * conflict instead and exits non-zero. The notice teaches both halves of the
+ * migration, since --repo-contributes alone doesn't reproduce the overwrite. */
+export declare function pushAlias(file: string | undefined, options: PushAliasOptions): Promise<void>;
+export {};
+//# sourceMappingURL=aliases.d.ts.map

package/dist/commands/aliases.js

@@ -0,0 +1,31 @@
+/**
+ * Deprecated `push` / `pull` verbs, kept as aliases into `dotreq sync` for the
+ * commands already in the wild — distributed `pull --share` onboarding
+ * commands, users' CI pipelines, ai-setup-installed guidance (SYNC-ALIAS-1).
+ * Each prints a deprecation notice naming its new spelling. First-party code
+ * calls `sync` directly; only these aliases remain.
+ */
+import { syncCliAction } from "./sync.js";
+/** `dotreq pull` → `dotreq sync --cloud-contributes` (SYNC-ALIAS-1.0). */
+export async function pullAlias(options) {
+    console.warn("Note: `dotreq pull` is deprecated. Use `dotreq sync --cloud-contributes`.");
+    const scope = options.document ? [options.document] : [];
+    await syncCliAction(scope, {
+        cloudContributes: true,
+        share: options.share,
+        project: options.project,
+    });
+}
+/** `dotreq push [file]` → `dotreq sync --repo-contributes [scope]` (SYNC-ALIAS-1.1).
+ *
+ * Deliberately safer than the push it shadows: old push overwrote a diverged
+ * cloud document after a y/N (or silently with --yes); the alias flags it as a
+ * conflict instead and exits non-zero. The notice teaches both halves of the
+ * migration, since --repo-contributes alone doesn't reproduce the overwrite. */
+export async function pushAlias(file, options) {
+    console.warn("Note: `dotreq push` is deprecated. Use `dotreq sync --repo-contributes` — " +
+        "or `dotreq sync <file> --repo-wins` where push would have overwritten a cloud-side change.");
+    const scope = file ? [file] : [];
+    await syncCliAction(scope, { repoContributes: true, yes: options.yes });
+}
+//# sourceMappingURL=aliases.js.map

package/dist/commands/diff.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `dotreq diff` — read-only comparison of the repo and the cloud (DIFF-*).
+ *
+ * With no scope it lists a verdict per document; scoped to documents it unfolds
+ * the detail one level. Exits 0 regardless of verdicts unless `--exit-code` is
+ * passed, which makes any non-in-sync document exit 1 (the CI drift gate).
+ */
+import { type SyncAuthOptions } from "./sync-common.js";
+interface DiffOptions extends SyncAuthOptions {
+    exitCode?: boolean;
+}
+export declare function diffCommand(scope: string[], options: DiffOptions): Promise<void>;
+export {};
+//# sourceMappingURL=diff.d.ts.map

package/dist/commands/diff.js

@@ -0,0 +1,62 @@
+/**
+ * `dotreq diff` — read-only comparison of the repo and the cloud (DIFF-*).
+ *
+ * With no scope it lists a verdict per document; scoped to documents it unfolds
+ * the detail one level. Exits 0 regardless of verdicts unless `--exit-code` is
+ * passed, which makes any non-in-sync document exit 1 (the CI drift gate).
+ */
+import { acquireCloudSnapshot, acquireLocalSnapshot, compareSnapshots, filterByScope, formatUnitDetail, formatVerdictLine, resolutionHint, } from "../sync/index.js";
+import { brand } from "../utils/brand.js";
+import { resolveCloudAuth } from "./sync-common.js";
+export async function diffCommand(scope, options) {
+    const workspaceRoot = process.cwd();
+    const auth = resolveCloudAuth(options);
+    const [local, cloud] = await Promise.all([
+        acquireLocalSnapshot(workspaceRoot),
+        acquireCloudSnapshot(auth),
+    ]);
+    const comparison = compareSnapshots(local, cloud);
+    const { documents, unmatched } = filterByScope(comparison, scope, workspaceRoot);
+    for (const token of unmatched) {
+        console.log(`No document matched scope "${token}".`);
+    }
+    // A CI gate pointed at a scope that matches nothing must not report green —
+    // the gate's premise (these documents exist to compare) is broken.
+    if (options.exitCode && unmatched.length > 0) {
+        process.exitCode = 1;
+    }
+    // DIFF-2: any scope argument means document-scope → verbose. No scope means
+    // project-scope → verdict list.
+    const verbose = scope.length > 0;
+    const notInSync = documents.filter((d) => d.verdict !== "in_sync");
+    // DIFF-1.2: don't list every document when everything is in sync.
+    if (notInSync.length === 0 && documents.length > 0) {
+        console.log(`✓ Repo and ${brand} cloud are in sync (${documents.length} document(s)).`);
+        return;
+    }
+    if (documents.length === 0) {
+        console.log("No documents to compare.");
+        return;
+    }
+    console.log(`\n=== Repo vs ${brand} cloud ===\n`);
+    for (const doc of documents) {
+        console.log(formatVerdictLine(doc));
+        if (doc.verdict === "invalid_file" && doc.error) {
+            console.log(`      ${doc.error}`);
+        }
+        if (verbose && doc.details && doc.details.length > 0) {
+            for (const detail of doc.details) {
+                console.log(formatUnitDetail(detail));
+            }
+        }
+        if (doc.verdict === "conflict") {
+            console.log(`      ${resolutionHint(doc)}`);
+        }
+    }
+    console.log();
+    // DIFF-6: exit non-zero on drift only when asked (the CI gate).
+    if (options.exitCode && notInSync.length > 0) {
+        process.exitCode = 1;
+    }
+}
+//# sourceMappingURL=diff.js.map

package/dist/commands/init.js

@@ -14,7 +14,7 @@ import { getOrCreateProjectSecret, promptExpiryDays, selectProject, } from "../u
 import { findProjectRoot, writeProjectSettings, } from "../utils/project-settings.js";
 import { promptChoice, promptConfirm } from "../utils/prompts.js";
 import { aiSetupCommand } from "./ai-setup.js";
-import { pullCommand } from "./pull.js";
+import { syncCommand } from "./sync.js";
 export async function initCommand(options = {}) {
     try {
         console.log(`Initializing ${brand} project...\n`);
@@ -299,8 +299,8 @@ async function connectExistingProjectFlow(cwd, client, team) {
     ensureGitignore(cwd);
     console.log("✓ Updated .gitignore\n");
     // INIT-6.2: Pull existing requirements from cloud
-    console.log("Pulling requirements from cloud...");
-    await pullCommand({ project: projectId });
+    console.log("Syncing requirements from cloud...");
+    await syncCommand([], { cloudContributes: true, project: projectId });
     console.log(`\n✓ Successfully connected to project: ${selectedProject.projectName}`);
     console.log(`  Project ID: ${projectId}`);
     // INIT-6.3: Show guidance
@@ -401,8 +401,8 @@ async function inviteFlow(cwd, token) {
     ensureGitignore(cwd);
     console.log("✓ Updated .gitignore\n");
     // Pull existing requirements from cloud
-    console.log("Pulling requirements from cloud...");
-    await pullCommand({ project: projectId });
+    console.log("Syncing requirements from cloud...");
+    await syncCommand([], { cloudContributes: true, project: projectId });
     console.log(`\n✓ Successfully connected to project: ${selectedProject.projectName}`);
     console.log(`  Project ID: ${projectId}`);
     // Show guidance

package/dist/commands/link.d.ts

@@ -17,7 +17,7 @@ export interface LinkCommandOptions extends LinkFlags {
  * - LINK-9: Creates the cloud project when chosen
  * - LINK-10/11/12: Non-interactive mode for AI-driven setup
  * - LINK-13: Non-interactive success includes share artifacts (team-invite
- *   URL + read-only pull command) so one "yes" puts the spec in front of
+ *   URL + read-only sync command) so one "yes" puts the spec in front of
  *   the team
  */
 export declare function linkCommand(options?: LinkCommandOptions): Promise<void>;

package/dist/commands/link.js

@@ -11,7 +11,7 @@ import { getOrCreateProjectSecret, promptExpiryDays, selectTeam, } from "../util
 import { findProjectRoot, readProjectSettings, writeProjectSettings, } from "../utils/project-settings.js";
 import { promptChoice, promptConfirm } from "../utils/prompts.js";
 import { hasCapacity, isNonInteractive, resolveProject, resolveProjectName, resolveTeam, } from "./link-resolution.js";
-import { pullCommand } from "./pull.js";
+import { syncCommand } from "./sync.js";
 /**
  * Link command - connect or reconnect local project to cloud, creating the
  * cloud project when needed. Link owns the "upgrade local to cloud"
@@ -28,7 +28,7 @@ import { pullCommand } from "./pull.js";
  * - LINK-9: Creates the cloud project when chosen
  * - LINK-10/11/12: Non-interactive mode for AI-driven setup
  * - LINK-13: Non-interactive success includes share artifacts (team-invite
- *   URL + read-only pull command) so one "yes" puts the spec in front of
+ *   URL + read-only sync command) so one "yes" puts the spec in front of
  *   the team
  */
 export async function linkCommand(options = {}) {
@@ -68,8 +68,8 @@ async function runNonInteractiveLink(options) {
             if (outcome.inviteUrl) {
                 console.log(`  Invite a teammate (web): ${outcome.inviteUrl}`);
             }
-            if (outcome.sharePullCommand) {
-                console.log(`  Share read-only to an IDE: ${outcome.sharePullCommand}`);
+            if (outcome.shareSyncCommand) {
+                console.log(`  Share read-only to an IDE: ${outcome.shareSyncCommand}`);
             }
         }
         if (outcome.status === "decision_needed") {
@@ -135,6 +135,7 @@ async function runNonInteractiveLink(options) {
                         projectName: match.projectName,
                         renamed: false,
                         settingsPath,
+                        signedInAs: oauthResult.email,
                         ...artifacts,
                     });
                     return;
@@ -189,6 +190,7 @@ async function runNonInteractiveLink(options) {
                 projectName: name,
                 renamed: false,
                 settingsPath,
+                signedInAs: oauthResult.email,
                 ...artifacts,
             });
             return;
@@ -227,6 +229,7 @@ async function runNonInteractiveLink(options) {
             projectName,
             renamed,
             settingsPath,
+            signedInAs: oauthResult.email,
             ...artifacts,
         });
     }
@@ -262,7 +265,7 @@ async function mintShareArtifacts(client, teamId, projectId) {
         const share = (await client.mutation(api.projectSecrets.mutations.ensureShareToken, 
         // biome-ignore lint/suspicious/noExplicitAny: CLI workspace doesn't import convex's branded Id type; the runtime value is a plain string the server validates.
         { target: { type: "project", id: projectId } }));
-        artifacts.sharePullCommand = `npx -y @popoverai/dotrequirements@latest pull --share ${share.token}`;
+        artifacts.shareSyncCommand = `npx -y @popoverai/dotrequirements@latest sync --share ${share.token}`;
     }
     catch {
         // LINK-13.3: connection already succeeded — omit rather than fail
@@ -402,8 +405,11 @@ async function runInteractiveLink(options) {
         // LINK-7: Optionally pull requirements
         const shouldPull = await promptConfirm("Pull requirements from cloud now?", true);
         if (shouldPull) {
-            console.log("\nPulling requirements...");
-            await pullCommand({ project: projectSlugOrId });
+            console.log("\nSyncing requirements...");
+            await syncCommand([], {
+                cloudContributes: true,
+                project: projectSlugOrId,
+            });
         }
         // LINK-7.2: Success message
         console.log(`\n✓ Successfully linked to project: ${projectName}`);

package/dist/commands/sync-common.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared plumbing for `dotreq diff` and `dotreq sync`: resolving cloud
+ * credentials (project settings / environment / share token) into the
+ * comparator's CloudAuth.
+ */
+import type { CloudAuth } from "../sync/index.js";
+export interface SyncAuthOptions {
+    /** Read-only share token: authenticates without project settings. */
+    share?: string;
+    /** Override the project slug (otherwise from settings/environment). */
+    project?: string;
+}
+/**
+ * Resolve the cloud credentials for a diff/sync run. A share token authenticates
+ * on its own (SHARE-TOKEN-CLI-1.1) and carries no slug — the read-only wrapper
+ * resolves the project from the token, and being read-only it can never write
+ * back (SHARE-TOKEN-CLI-1.3). Otherwise credentials come from the settings file
+ * or the environment (AUTHZ-6).
+ */
+export declare function resolveCloudAuth(opts: SyncAuthOptions): CloudAuth;
+//# sourceMappingURL=sync-common.d.ts.map

package/dist/commands/sync-common.js

@@ -0,0 +1,24 @@
+/**
+ * Shared plumbing for `dotreq diff` and `dotreq sync`: resolving cloud
+ * credentials (project settings / environment / share token) into the
+ * comparator's CloudAuth.
+ */
+import { getProjectCredentials } from "../utils/project-settings.js";
+/**
+ * Resolve the cloud credentials for a diff/sync run. A share token authenticates
+ * on its own (SHARE-TOKEN-CLI-1.1) and carries no slug — the read-only wrapper
+ * resolves the project from the token, and being read-only it can never write
+ * back (SHARE-TOKEN-CLI-1.3). Otherwise credentials come from the settings file
+ * or the environment (AUTHZ-6).
+ */
+export function resolveCloudAuth(opts) {
+    if (opts.share) {
+        return { projectSecret: opts.share };
+    }
+    const creds = getProjectCredentials();
+    return {
+        projectSlug: opts.project ?? creds.projectId,
+        projectSecret: creds.projectSecret,
+    };
+}
+//# sourceMappingURL=sync-common.js.map

package/dist/commands/sync.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `dotreq sync` — reconcile the repo and the cloud under a direction/authority
+ * mode (SYNC-MODE-*). The daily gesture is the unmarked form; flags narrow
+ * direction (`--cloud-contributes` / `--repo-contributes`) or assign authority
+ * (`--repo-wins` / `--cloud-wins`).
+ */
+import { type SyncAuthOptions } from "./sync-common.js";
+interface SyncOptions extends SyncAuthOptions {
+    cloudContributes?: boolean;
+    repoContributes?: boolean;
+    cloudWins?: boolean;
+    repoWins?: boolean;
+    yes?: boolean;
+}
+/** How a sync run ended, for the caller to translate into an exit code. */
+export type SyncRunResult = "clean" | "trouble" | "cancelled";
+/**
+ * The CLI entry point: exits non-zero on unresolved trouble (SYNC-MODE-1.5,
+ * SYNC-FAIL-1/4). `init`/`link` call `syncCommand` directly instead — their
+ * success is linking/onboarding, and a conflict in one spec file must not fail
+ * the whole command (the report lines still print).
+ */
+export declare function syncCliAction(scope: string[], options: SyncOptions): Promise<void>;
+export declare function syncCommand(scope: string[], options: SyncOptions): Promise<SyncRunResult>;
+export {};
+//# sourceMappingURL=sync.d.ts.map