@popoverai/dotrequirements 0.32.0 → 0.33.0

package/dist/cli.js

@@ -25,8 +25,10 @@ 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 { commandErrorMessage } from "./utils/command-error.js";
 import { loadEnvFile } from "./utils/env.js";
 import { setPreferEnvCredentials } from "./utils/project-settings.js";
+import { enableVersionMessages, formatVersionMessages, markVersionMessagesShown, versionMessages, } from "./version-messages.js";
 // Read version from package.json
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -34,6 +36,20 @@ const packageJson = JSON.parse(readFileSync(join(__dirname, "../package.json"),
 const VERSION = packageJson.version;
 // Load environment variables from .env.local if it exists
 loadEnvFile();
+// CLI-MSG-1: a run that reaches the cloud hears what it has to say to this
+// version.
+enableVersionMessages();
+/**
+ * The cloud's messages for this version, after the command's own output. On
+ * stderr, so a command's piped output stays clean.
+ */
+async function printVersionMessages() {
+    const messages = await versionMessages();
+    if (messages.length > 0) {
+        console.error(`${formatVersionMessages(messages)}\n`);
+    }
+    markVersionMessagesShown();
+}
 /**
  * Wrap command handlers to catch errors and display them cleanly
  * without showing stack traces to users
@@ -44,14 +60,11 @@ function wrapCommand(fn) {
             await fn(...args);
         }
         catch (error) {
-            if (error instanceof Error) {
-                console.error(`\nError: ${error.message}\n`);
-            }
-            else {
-                console.error(`\nError: ${String(error)}\n`);
-            }
+            console.error(`\nError: ${commandErrorMessage(error)}\n`);
+            await printVersionMessages();
             process.exit(1);
         }
+        await printVersionMessages();
     };
 }
 const program = new Command();

package/dist/cloud.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The one way into the dotrequirements cloud. Every place the CLI reaches the
+ * cloud asks here for the address, so the first use in a run is visible — the
+ * version-message check (CLI-MSG-1) starts there.
+ */
+/** The web app, home of the hosted AI endpoints and publishing. */
+export declare const DEFAULT_API_BASE_URL = "https://app.dotrequirements.io";
+/** The Convex backend's address, for a ConvexHttpClient or its HTTP API. */
+export declare function convexUrl(): string;
+/** The web app's address; `DOTREQUIREMENTS_API_URL` overrides it. */
+export declare function webApiUrl(): string;
+/** Run `callback` the first time this process reaches the cloud. */
+export declare function whenCloudFirstUsed(callback: () => void): void;
+//# sourceMappingURL=cloud.d.ts.map

package/dist/cloud.js

@@ -0,0 +1,34 @@
+/**
+ * The one way into the dotrequirements cloud. Every place the CLI reaches the
+ * cloud asks here for the address, so the first use in a run is visible — the
+ * version-message check (CLI-MSG-1) starts there.
+ */
+/** The Convex backend every user's CLI talks to. */
+const CONVEX_URL = "https://data.dotrequirements.io";
+/** The web app, home of the hosted AI endpoints and publishing. */
+export const DEFAULT_API_BASE_URL = "https://app.dotrequirements.io";
+let onFirstUse = null;
+let used = false;
+function noteUse() {
+    if (used)
+        return;
+    used = true;
+    onFirstUse?.();
+}
+/** The Convex backend's address, for a ConvexHttpClient or its HTTP API. */
+export function convexUrl() {
+    noteUse();
+    return CONVEX_URL;
+}
+/** The web app's address; `DOTREQUIREMENTS_API_URL` overrides it. */
+export function webApiUrl() {
+    noteUse();
+    return process.env.DOTREQUIREMENTS_API_URL ?? DEFAULT_API_BASE_URL;
+}
+/** Run `callback` the first time this process reaches the cloud. */
+export function whenCloudFirstUsed(callback) {
+    onFirstUse = callback;
+    if (used)
+        callback();
+}
+//# sourceMappingURL=cloud.js.map

package/dist/commands/create-requirement-document.js

@@ -1,9 +1,9 @@
+import { convexUrl } from "../cloud.js";
 import { getProjectContext } from "../requirements/cloud-ai.js";
 import { loadAllRequirements } from "../requirements/index.js";
 import { generateStyleGuide } from "../requirements/style-guide.js";
 import { readLocalStyleGuide } from "../requirements/style-guide-file.js";
 import { findProjectRoot, getProjectCredentials, } from "../utils/project-settings.js";
-const CONVEX_URL = "https://data.dotrequirements.io";
 export async function createRequirementDocumentCommand(filePath) {
     const workspaceRoot = process.cwd();
     // CLI-CREATE-DOC-1.1 / .2: discover existing patterns from the workspace.
@@ -24,7 +24,7 @@ export async function createRequirementDocumentCommand(filePath) {
     if (projectRoot) {
         try {
             const { projectId, projectSecret } = getProjectCredentials(workspaceRoot);
-            const contextData = await getProjectContext(projectId, projectSecret, CONVEX_URL);
+            const contextData = await getProjectContext(projectId, projectSecret, convexUrl());
             customStyleGuidance = contextData?.requirementsStyleContext ?? null;
         }
         catch {

package/dist/commands/init.js

@@ -1,12 +1,13 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { ConvexHttpClient } from "convex/browser";
-import { getConvexUrl } from "../config.js";
+import { convexUrl } from "../cloud.js";
 import { api } from "../convex.js";
 import { generateStyleGuideBody } from "../requirements/style-guide.js";
 import { generateExampleRequirements } from "../templates/example-requirements.js";
 import { generateRequirementsReadme } from "../templates/requirements-readme.js";
 import { brand } from "../utils/brand.js";
+import { commandErrorMessage } from "../utils/command-error.js";
 import { ensureGitignore } from "../utils/gitignore.js";
 import { executeOAuthFlow } from "../utils/oauth-flow.js";
 import { detectProjectName } from "../utils/project-name.js";
@@ -69,7 +70,7 @@ export async function initCommand(options = {}) {
         }
     }
     catch (error) {
-        console.error(`\n✗ Error: ${error instanceof Error ? error.message : String(error)}`);
+        console.error(`\n✗ Error: ${commandErrorMessage(error)}`);
         // INIT-11: Network error guidance
         if (error instanceof Error && error.message.includes("fetch")) {
             console.error("\nCheck your internet connection and try again.");
@@ -130,7 +131,7 @@ async function authenticatedFlow(cwd, options) {
         return false;
     }
     // Set up authenticated client using the session token
-    const client = new ConvexHttpClient(getConvexUrl());
+    const client = new ConvexHttpClient(convexUrl());
     client.setAuth(oauthResult.accessToken);
     // INIT-18: Select team
     const selectedTeam = await selectTeam(client);
@@ -216,9 +217,9 @@ async function selectTeam(client) {
  */
 async function chooseProjectAction(client, teamId) {
     // INIT-7.3: Check if team has existing projects the user can access
-    const projectsWithSecrets = (await client.query(api.projectSecrets.queries.listOwnSecretsForTeam, 
+    const projectsWithSecrets = (await client.query(api.projectSecrets.queries.listOwnForTeam, 
     // biome-ignore lint/suspicious/noExplicitAny: CLI workspace doesn't import convex's branded Id<"teams"> type; the runtime value is a plain string the convex server validates.
-    { target: { type: "team", id: teamId } }));
+    { teamId: teamId }));
     if (projectsWithSecrets.length === 0) {
         // No existing projects, only offer create
         const confirmed = await promptConfirm("This team has no projects. Create a new one?", true);
@@ -315,7 +316,7 @@ async function connectExistingProjectFlow(cwd, client, team) {
  */
 async function inviteFlow(cwd, token) {
     // MEMBERSHIP-18.0: Validate token before auth (no auth needed for this query)
-    const client = new ConvexHttpClient(getConvexUrl());
+    const client = new ConvexHttpClient(convexUrl());
     console.log("Validating invite token...");
     const inviteInfo = await client.query(api.teamInvites.queries.getInviteInfo, {
         token,

package/dist/commands/link.js

@@ -1,15 +1,17 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { ConvexHttpClient } from "convex/browser";
-import { getConvexUrl } from "../config.js";
+import { convexUrl } from "../cloud.js";
 import { api } from "../convex.js";
 import { WEB_APP_URL } from "../push/index.js";
 import { brand } from "../utils/brand.js";
+import { commandErrorMessage } from "../utils/command-error.js";
 import { ensureGitignore } from "../utils/gitignore.js";
 import { executeOAuthFlow } from "../utils/oauth-flow.js";
 import { getOrCreateProjectSecret, promptExpiryDays, selectTeam, } from "../utils/project-selector.js";
 import { findProjectRoot, readProjectSettings, writeProjectSettings, } from "../utils/project-settings.js";
 import { promptChoice, promptConfirm } from "../utils/prompts.js";
+import { markVersionMessagesShown, versionMessages, } from "../version-messages.js";
 import { hasCapacity, isNonInteractive, resolveProject, resolveProjectName, resolveTeam, } from "./link-resolution.js";
 import { syncCommand } from "./sync.js";
 /**
@@ -47,10 +49,13 @@ async function runNonInteractiveLink(options) {
     if (options.json) {
         console.log = (...args) => console.error(...args);
     }
+    // CLI-MSG-1.1: the JSON result carries the cloud's messages, so it is
+    // printed once the command is done and they are in.
+    let jsonOutcome = null;
     const finish = (outcome) => {
         console.log = originalLog;
         if (options.json) {
-            originalLog(JSON.stringify(outcome));
+            jsonOutcome = outcome;
         }
         else if (outcome.status === "decision_needed") {
             console.log(`\n${outcome.message}`);
@@ -101,7 +106,7 @@ async function runNonInteractiveLink(options) {
         }
         // LINK-3 / LINK-10.7: browser auth is the only human step
         const oauthResult = await executeOAuthFlow();
-        const client = new ConvexHttpClient(getConvexUrl());
+        const client = new ConvexHttpClient(convexUrl());
         client.setAuth(oauthResult.accessToken);
         await client.mutation(api.teams.mutations.ensureDefaultTeam, {});
         const teams = (await client.query(api.teams.queries.listForUserWithUsage));
@@ -201,12 +206,9 @@ async function runNonInteractiveLink(options) {
         if (projectResolution.rename) {
             const newName = resolveProjectName(options, readPackageName(cwd), path.basename(cwd));
             try {
-                await client.mutation(api.projects.mutations.update, {
-                    target: {
-                        type: "project",
-                        // 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.
-                        id: projectResolution.project.projectId,
-                    },
+                await client.mutation(api.projects.mutations.updateProject, {
+                    // 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.
+                    projectId: projectResolution.project.projectId,
                     name: newName,
                 });
                 projectName = newName;
@@ -234,13 +236,17 @@ async function runNonInteractiveLink(options) {
         });
     }
     catch (error) {
-        finish({
-            status: "error",
-            message: error instanceof Error ? error.message : String(error),
-        });
+        finish({ status: "error", message: commandErrorMessage(error) });
     }
     finally {
         console.log = originalLog;
+        // Here, not after the block: every outcome above returns from inside
+        // `try`. Assigned inside `finish`, which TypeScript can't follow.
+        const outcome = jsonOutcome;
+        if (outcome) {
+            originalLog(JSON.stringify({ ...outcome, messages: await versionMessages() }));
+            markVersionMessagesShown();
+        }
     }
 }
 /**
@@ -253,18 +259,18 @@ async function runNonInteractiveLink(options) {
 async function mintShareArtifacts(client, teamId, projectId) {
     const artifacts = {};
     try {
-        const invite = (await client.mutation(api.teamInvites.mutations.createInvite, 
+        const invite = (await client.mutation(api.teamInvites.mutations.createInviteLink, 
         // 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: "team", id: teamId } }));
+        { teamId: teamId }));
         artifacts.inviteUrl = `${WEB_APP_URL}/invite/${invite.token}`;
     }
     catch {
         // LINK-13.3: admin-gated — omit the invite URL for non-admin members
     }
     try {
-        const share = (await client.mutation(api.projectSecrets.mutations.ensureShareToken, 
+        const share = (await client.mutation(api.projectSecrets.mutations.ensureProjectShareToken, 
         // 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 } }));
+        { projectId: projectId }));
         artifacts.shareSyncCommand = `npx -y @popoverai/dotrequirements@latest sync --share ${share.token}`;
     }
     catch {
@@ -273,9 +279,9 @@ async function mintShareArtifacts(client, teamId, projectId) {
     return artifacts;
 }
 async function listProjects(client, teamId) {
-    const projects = (await client.query(api.projectSecrets.queries.listOwnSecretsForTeam, 
+    const projects = (await client.query(api.projectSecrets.queries.listOwnForTeam, 
     // 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: "team", id: teamId } }));
+    { teamId: teamId }));
     return projects.map((p) => ({
         projectId: p.projectId,
         projectName: p.projectName,
@@ -349,7 +355,7 @@ async function runInteractiveLink(options) {
             return;
         }
         // Set up authenticated client using the session token
-        const client = new ConvexHttpClient(getConvexUrl());
+        const client = new ConvexHttpClient(convexUrl());
         client.setAuth(oauthResult.accessToken);
         // LINK-4: Select team
         const selectedTeam = await selectTeam(client);
@@ -417,7 +423,7 @@ async function runInteractiveLink(options) {
         console.log("\nDocumentation: https://docs.dotrequirements.io/getting-started");
     }
     catch (error) {
-        console.error(`\n✗ Error: ${error instanceof Error ? error.message : String(error)}`);
+        console.error(`\n✗ Error: ${commandErrorMessage(error)}`);
         // LINK-8: Network error guidance
         if (error instanceof Error && error.message.includes("fetch")) {
             console.error("\nCheck your internet connection and try again.");

package/dist/commands/report.js

@@ -1,9 +1,10 @@
+import { convexUrl } from "../cloud.js";
 import { findRequirementsDir, readCoverageCache } from "../harness/cache.js";
 import { formatUnrecordedNotice } from "../harness/reportingStatus.js";
 import { getProjectCoverage, getRequirementCoverage, } from "../requirements/cloud-coverage.js";
 import { buildLocalReport, } from "../requirements/coverage.js";
 import { findProjectRoot, getProjectCredentials, } from "../utils/project-settings.js";
-const CONVEX_URL = "https://data.dotrequirements.io";
+import { markVersionMessagesShown, versionMessages, } from "../version-messages.js";
 export async function reportCommand(options) {
     const source = options.source ?? "local";
     const format = options.format ?? "console";
@@ -52,24 +53,28 @@ export async function reportCommand(options) {
     if (options.requirement) {
         // REPORT-CLOUD-1.7: --branch/--since apply to the requirement-scoped
         // output too, not just the project-wide report
-        const record = await getRequirementCoverage(options.requirement, projectId, projectSecret, CONVEX_URL, {
+        const record = await getRequirementCoverage(options.requirement, projectId, projectSecret, convexUrl(), {
             branch: options.branch,
             sinceTimestamp: options.since,
         });
         console.log(printCloudRequirement(record, format, {
             branch: options.branch,
             since: options.since,
-        }));
+        }, format === "json" ? await versionMessages() : []));
+        if (format === "json")
+            markVersionMessagesShown();
         return;
     }
-    const record = await getProjectCoverage(projectId, projectSecret, CONVEX_URL, {
+    const record = await getProjectCoverage(projectId, projectSecret, convexUrl(), {
         branch: options.branch,
         sinceTimestamp: options.since,
     });
     console.log(printCloudProject(record, format, {
         branch: options.branch,
         since: options.since,
-    }));
+    }, format === "json" ? await versionMessages() : []));
+    if (format === "json")
+        markVersionMessagesShown();
 }
 function printLocalReport(report, format) {
     switch (format) {
@@ -122,9 +127,10 @@ function formatLocalMarkdown(report) {
     }
     return out;
 }
-function printCloudRequirement(record, format, filters) {
+function printCloudRequirement(record, format, filters, messages = []) {
     if (format === "json") {
-        return JSON.stringify({ source: "cloud", requirement: record }, null, 2);
+        // CLI-MSG-1.1: the cloud's messages for this version travel in the JSON.
+        return JSON.stringify({ source: "cloud", requirement: record, messages }, null, 2);
     }
     if (!record.lastTestedAt) {
         // REPORT-CLOUD-1.7: with filters in play, an empty record means nothing
@@ -168,9 +174,16 @@ function printCloudRequirement(record, format, filters) {
     }
     return lines.join("\n");
 }
-function printCloudProject(record, format, filters) {
+function printCloudProject(record, format, filters, messages = []) {
     if (format === "json") {
-        return JSON.stringify({ source: "cloud", filters, summary: cloudSummary(record), ...record }, null, 2);
+        // CLI-MSG-1.1: the cloud's messages for this version travel in the JSON.
+        return JSON.stringify({
+            source: "cloud",
+            filters,
+            summary: cloudSummary(record),
+            ...record,
+            messages,
+        }, null, 2);
     }
     const summary = cloudSummary(record);
     const filterNote = formatCloudFilters(filters);

package/dist/commands/review-test.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { DEFAULT_API_BASE_URL, fetchReviewTestFeedback, } from "../requirements/cloud-ai.js";
+import { webApiUrl } from "../cloud.js";
+import { fetchReviewTestFeedback } from "../requirements/cloud-ai.js";
 import { findRequirementsInFile } from "../requirements/grep.js";
 import { formatRequirementTree, getRequirementTree, loadAllRequirements, } from "../requirements/index.js";
 import { getProjectCredentials } from "../utils/project-settings.js";
@@ -145,7 +146,7 @@ async function runCloudReview(params) {
             `(${error instanceof Error ? error.message : String(error)})`);
     }
     // CLI-REVIEW-3.0 / .1 / .3: dispatch to the hosted endpoint
-    const apiBaseUrl = process.env.DOTREQUIREMENTS_API_URL ?? DEFAULT_API_BASE_URL;
+    const apiBaseUrl = webApiUrl();
     let feedback;
     let quotaWarning;
     try {

package/dist/commands/style-check.js

@@ -1,11 +1,11 @@
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { DEFAULT_API_BASE_URL, fetchStyleCheckFeedback, getProjectContext, } from "../requirements/cloud-ai.js";
+import { convexUrl, webApiUrl } from "../cloud.js";
+import { fetchStyleCheckFeedback, getProjectContext, } from "../requirements/cloud-ai.js";
 import { filterRequirementsByKeys, loadAllRequirements, } from "../requirements/index.js";
 import { generateStyleGuideBody } from "../requirements/style-guide.js";
 import { readLocalStyleGuide } from "../requirements/style-guide-file.js";
 import { findProjectRoot, getProjectCredentials, } from "../utils/project-settings.js";
-const CONVEX_URL = "https://data.dotrequirements.io";
 /**
  * Judgment instructions for test-file style review in local mode. Mirrors the
  * hosted test-style rubric (PROMPT-STYLE-TESTS-*): requirement() usage,
@@ -123,7 +123,7 @@ async function emitStyleMaterials(params) {
             if (projectRoot) {
                 try {
                     const { projectId, projectSecret } = getProjectCredentials(workspaceRoot);
-                    const contextData = await getProjectContext(projectId, projectSecret, CONVEX_URL);
+                    const contextData = await getProjectContext(projectId, projectSecret, convexUrl());
                     customStyleGuidance = contextData?.requirementsStyleContext ?? null;
                 }
                 catch {
@@ -170,7 +170,7 @@ async function runCloudStyleCheck(params) {
             `(${error instanceof Error ? error.message : String(error)})`);
     }
     // CLI-STYLE-3.0 / .1 / .3: dispatch to the hosted endpoint
-    const apiBaseUrl = process.env.DOTREQUIREMENTS_API_URL ?? DEFAULT_API_BASE_URL;
+    const apiBaseUrl = webApiUrl();
     let feedback;
     let quotaWarning;
     try {

package/dist/convex.d.ts

@@ -17,15 +17,13 @@
 export declare const api: {
     documents: {
         queries: {
-            exportForCli: import("convex/server").FunctionReference<"query", "public", any, any, string | undefined>;
-            exportProjectForCli: import("convex/server").FunctionReference<"query", "public", any, any, string | undefined>;
-            checkDocumentsExist: import("convex/server").FunctionReference<"query", "public", any, any, string | undefined>;
+            exportDocument: import("convex/server").FunctionReference<"query", "public", any, any, string | undefined>;
+            exportProject: import("convex/server").FunctionReference<"query", "public", any, any, string | undefined>;
+            exportProjectForShare: import("convex/server").FunctionReference<"query", "public", any, any, string | undefined>;
         };
         mutations: {
-            create: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
-            update: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
-            deleteForCli: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
-            setAttachmentsForSync: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
+            deleteForSync: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
+            syncAttachments: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
         };
         saveWithRequirements: {
             saveWithRequirements: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
@@ -39,7 +37,7 @@ export declare const api: {
     projects: {
         mutations: {
             create: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
-            update: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
+            updateProject: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
         };
     };
     teams: {
@@ -55,19 +53,19 @@ export declare const api: {
             getInviteInfo: import("convex/server").FunctionReference<"query", "public", any, any, string | undefined>;
         };
         mutations: {
-            createInvite: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
+            createInviteLink: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
             acceptInvite: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
         };
     };
     projectSecrets: {
         queries: {
             getOwnSecret: import("convex/server").FunctionReference<"query", "public", any, any, string | undefined>;
-            listOwnSecretsForTeam: import("convex/server").FunctionReference<"query", "public", any, any, string | undefined>;
+            listOwnForTeam: import("convex/server").FunctionReference<"query", "public", any, any, string | undefined>;
         };
         mutations: {
-            ensureOwnSecret: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
+            ensureOwn: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
             revokeOwnSecret: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
-            ensureShareToken: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
+            ensureProjectShareToken: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
         };
     };
     lib: {

package/dist/convex.js

@@ -21,17 +21,16 @@ const action = (name) => makeFunctionReference(name);
 export const api = {
     documents: {
         queries: {
-            exportForCli: query("documents/queries:exportForCli"),
-            exportProjectForCli: query("documents/queries:exportProjectForCli"),
-            checkDocumentsExist: query("documents/queries:checkDocumentsExist"),
+            exportDocument: query("documents/queries:exportDocument"),
+            exportProject: query("documents/queries:exportProject"),
+            // SHARE-TOKEN-3: the same export for a read-only share token
+            exportProjectForShare: query("documents/queries:exportProjectForShare"),
         },
         mutations: {
-            create: mutation("documents/mutations:create"),
-            update: mutation("documents/mutations:update"),
             // SYNC-MODE-3: delete a cloud document from the CLI (repo-wins)
-            deleteForCli: mutation("documents/mutations:deleteForCli"),
+            deleteForSync: mutation("documents/mutations:deleteForSync"),
             // ATTACH-10.2: attachment-only sync — a metadata patch, never a publish
-            setAttachmentsForSync: mutation("documents/mutations:setAttachmentsForSync"),
+            syncAttachments: mutation("documents/mutations:syncAttachments"),
         },
         // SYNC-ARCH-1: Save document with requirements derivation
         saveWithRequirements: {
@@ -46,7 +45,7 @@ export const api = {
     projects: {
         mutations: {
             create: mutation("projects/mutations:create"),
-            update: mutation("projects/mutations:update"),
+            updateProject: mutation("projects/mutations:updateProject"),
         },
     },
     teams: {
@@ -62,7 +61,7 @@ export const api = {
             getInviteInfo: query("teamInvites/queries:getInviteInfo"),
         },
         mutations: {
-            createInvite: mutation("teamInvites/mutations:createInvite"),
+            createInviteLink: mutation("teamInvites/mutations:createInviteLink"),
             // Joins the team and reconciles paid-team seats via a scheduled sync
             // (POLAR-SEATS-3). Replaced the deleted polar:acceptTeamInvite action.
             acceptInvite: mutation("teamInvites/mutations:acceptInvite"),
@@ -71,12 +70,12 @@ export const api = {
     projectSecrets: {
         queries: {
             getOwnSecret: query("projectSecrets/queries:getOwnSecret"),
-            listOwnSecretsForTeam: query("projectSecrets/queries:listOwnSecretsForTeam"),
+            listOwnForTeam: query("projectSecrets/queries:listOwnForTeam"),
         },
         mutations: {
-            ensureOwnSecret: mutation("projectSecrets/mutations:ensureOwnSecret"),
+            ensureOwn: mutation("projectSecrets/mutations:ensureOwn"),
             revokeOwnSecret: mutation("projectSecrets/mutations:revokeOwnSecret"),
-            ensureShareToken: mutation("projectSecrets/mutations:ensureShareToken"),
+            ensureProjectShareToken: mutation("projectSecrets/mutations:ensureProjectShareToken"),
         },
     },
     lib: {

package/dist/harness/finalize.js

@@ -11,8 +11,10 @@
  */
 import { execSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { convexUrl } from "../cloud.js";
 import { canonicalRequirementPath } from "../schema/index.js";
 import { getProjectInfo } from "../utils/project-settings.js";
+import { enableVersionMessages, formatVersionMessages, markVersionMessagesShown, versionMessages, } from "../version-messages.js";
 import { cleanupTestRunId, clearCoverageReportFailure, deleteTrackingFile, findProjectRoot, findRequirementsDir, getTestRunId, needsReporting, readCoverageCache, readLookupCache, readTrackingEntries, recordCoverageReplayed, recordCoverageReported, recordCoverageReportFailure, updateCoverageCache, } from "./cache.js";
 import { formatFailureNotice, formatUnrecordedNotice, refusalReason, } from "./reportingStatus.js";
 import { toProjectRelativePath } from "./tracking.js";
@@ -130,10 +132,6 @@ function printLocalReport(testedKeys, lookup, options) {
         console.log(report);
     }
 }
-/**
- * Production Convex deployment URL
- */
-const CONVEX_URL = "https://data.dotrequirements.io";
 /**
  * Record a reporting attempt that did not reach the cloud, so later runs and
  * `dotreq report` keep saying so (COVERAGE-REPORT-3), and hand the reason back
@@ -190,18 +188,18 @@ const REPORT_TIMEOUT_MS = 15_000;
  */
 async function postCoverage(credentials, report) {
     // Note: projectId from env is always a slug (e.g., "reduced-cephalopod-288"),
-    // not a Convex ID. Use projectSlug field for authentication and slug for target.
-    const response = await fetch(`${CONVEX_URL}/api/mutation`, {
+    // not a Convex ID. It names the project both to authenticate and as the report's project.
+    const response = await fetch(`${convexUrl()}/api/mutation`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
-            path: "testCoverage/mutations:recordCoverage",
+            path: "testCoverage/mutations:record",
             args: {
                 projectAuth: {
                     projectSlug: credentials.projectId,
                     projectSecret: credentials.projectSecret,
                 },
-                target: { type: "project", slug: credentials.projectId },
+                project: credentials.projectId,
                 branch: report.branch,
                 context: report.context,
                 runId: report.runId,
@@ -528,6 +526,9 @@ export async function finalize(options = {}) {
         count: 0,
     };
     if (shouldReportToCloud) {
+        // CLI-MSG-1.4: a run that reports to the cloud hears what it has to say
+        // to this version.
+        enableVersionMessages();
         cloudResult = await reportToConvex(projectRoot, testRunId, aggregated, showCloudStatus, context);
     }
     // Read once, after reporting has had its say, for both the report header and
@@ -551,6 +552,13 @@ export async function finalize(options = {}) {
                 (recordedThisRun ? null : coverageCache?.lastFailure)),
         });
     }
+    // CLI-MSG-1.4: the summary closes with the cloud's messages for this
+    // version — ahead of the notice below, which keeps the last word.
+    const messages = await versionMessages();
+    if (messages.length > 0) {
+        console.error(`${formatVersionMessages(messages)}\n`);
+    }
+    markVersionMessagesShown();
     // COVERAGE-REPORT-2.1, -3.0: the run's last word is whether coverage
     // recorded. Written to stderr so it cannot be silenced by a quiet run or
     // swallowed by a caller parsing stdout — a failure nobody sees is the whole

package/dist/harness/reportingStatus.js

@@ -5,6 +5,7 @@
  * COVERAGE-REPORT-2 / -3 (the run says coverage did not record, and keeps
  * saying it until it does).
  */
+import { userFacingMessage } from "../utils/command-error.js";
 /**
  * Shown when a refusal carries nothing a developer could act on
  * (COVERAGE-REPORT-1.2). The raw `errorMessage` is deliberately not used in its
@@ -19,17 +20,7 @@ export const REFUSAL_WITHOUT_REASON = "the cloud refused the report without givi
  * ConvexError's data is either a plain string or an object carrying `message`.
  */
 export function refusalReason(response) {
-    const data = response.errorData;
-    if (typeof data === "string" && data.trim()) {
-        return data;
-    }
-    if (data && typeof data === "object" && "message" in data) {
-        const { message } = data;
-        if (typeof message === "string" && message.trim()) {
-            return message;
-        }
-    }
-    return REFUSAL_WITHOUT_REASON;
+    return userFacingMessage(response.errorData) ?? REFUSAL_WITHOUT_REASON;
 }
 const MONTHS = [
     "January",

package/dist/requirements/cloud-ai.d.ts

@@ -7,12 +7,6 @@
  * throws on failure). Surface-specific concerns (error formatting, exit
  * codes, MCP tool responses) live in the callers.
  */
-/**
- * Default base URL for the hosted AI endpoints (`/api/style-check`,
- * `/api/review-test`). Overridable via the `apiBaseUrl` argument or
- * the `DOTREQUIREMENTS_API_URL` environment variable in callers.
- */
-export declare const DEFAULT_API_BASE_URL = "https://app.dotrequirements.io";
 export interface StyleCheckParams {
     apiBaseUrl: string;
     projectId: string;

package/dist/requirements/cloud-ai.js

@@ -7,12 +7,6 @@
  * throws on failure). Surface-specific concerns (error formatting, exit
  * codes, MCP tool responses) live in the callers.
  */
-/**
- * Default base URL for the hosted AI endpoints (`/api/style-check`,
- * `/api/review-test`). Overridable via the `apiBaseUrl` argument or
- * the `DOTREQUIREMENTS_API_URL` environment variable in callers.
- */
-export const DEFAULT_API_BASE_URL = "https://app.dotrequirements.io";
 /**
  * POST to `/api/style-check`. Returns the feedback (and any quota warning)
  * on success; throws an Error with the underlying failure reason on a
@@ -73,16 +67,13 @@ export async function getProjectContext(projectId, projectSecret, convexUrl) {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({
-                path: "projects/queries:get",
+                path: "projects/queries:getProject",
                 args: {
                     projectAuth: {
                         projectSlug: projectId,
                         projectSecret,
                     },
-                    target: {
-                        type: "project",
-                        slug: projectId,
-                    },
+                    project: projectId,
                 },
                 format: "json",
             }),

package/dist/requirements/cloud-coverage.js

@@ -19,10 +19,10 @@ export async function getRequirementCoverage(requirementKey, projectId, projectS
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
-            path: "testCoverage/queries:getRequirementCoverage",
+            path: "testCoverage/queries:requirementCoverage",
             args: {
                 projectAuth: { projectSlug: projectId, projectSecret },
-                target: { type: "project", slug: projectId },
+                project: projectId,
                 requirementKey,
             },
             format: "json",
@@ -68,10 +68,10 @@ export async function getProjectCoverage(projectId, projectSecret, convexUrl, op
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
-            path: "testCoverage/queries:getProjectCoverage",
+            path: "testCoverage/queries:projectCoverage",
             args: {
                 projectAuth: { projectSlug: projectId, projectSecret },
-                target: { type: "project", slug: projectId },
+                project: projectId,
                 branch: options?.branch,
                 sinceTimestamp: options?.sinceTimestamp,
             },

package/dist/sync/execute.js

@@ -10,10 +10,11 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { ConvexHttpClient } from "convex/browser";
-import { getConvexUrl } from "../config.js";
+import { convexUrl } from "../cloud.js";
 import { api } from "../convex.js";
 import { parseFilesForPushIndividually, WEB_APP_URL } from "../push/core.js";
 import { composeMarkdownWithTitle, splitLeadingH1, writeRequirementsFile, } from "../schema/index.js";
+import { commandErrorMessage } from "../utils/command-error.js";
 import { cloudAttachmentRemovals, resolveAttachments } from "./attachments.js";
 import { resolveLocalPath } from "./local-files.js";
 import { publishToCloud } from "./publish.js";
@@ -46,7 +47,7 @@ function emptyOutcome() {
  */
 export async function executePlan(plan, cloud, auth, workspaceRoot, mode) {
     const outcome = emptyOutcome();
-    const client = new ConvexHttpClient(getConvexUrl());
+    const client = new ConvexHttpClient(convexUrl());
     const cloudById = new Map(cloud.documents.map((d) => [d.documentId, d]));
     const requirementsDir = path.join(workspaceRoot, ".requirements");
     const usedPaths = new Set();
@@ -83,14 +84,14 @@ export async function executePlan(plan, cloud, auth, workspaceRoot, mode) {
             await syncResidualAttachments(client, auth, doc, action, outcome, mode);
         }
         catch (err) {
-            outcome.errors.push({ name, error: errorDisplayMessage(err) });
+            outcome.errors.push({ name, error: commandErrorMessage(err) });
         }
     }
     return outcome;
 }
 /**
  * Attachment-only operations for whatever the body action didn't cover.
- * The push goes through setAttachmentsForSync — a metadata patch, never the
+ * The push goes through syncAttachments — a metadata patch, never the
  * publish path, so naming a link cannot displace anyone's working document.
  */
 async function syncResidualAttachments(client, auth, doc, action, outcome, mode) {
@@ -110,12 +111,11 @@ async function syncResidualAttachments(client, auth, doc, action, outcome, mode)
         if (!auth.projectSlug) {
             throw new Error("Cannot sync attachments without project credentials.");
         }
-        await client.mutation(api.documents.mutations.setAttachmentsForSync, {
+        await client.mutation(api.documents.mutations.syncAttachments, {
             projectAuth: {
                 projectSlug: auth.projectSlug,
                 projectSecret: auth.projectSecret,
             },
-            target: { type: "project", slug: auth.projectSlug },
             documentId: doc.documentId,
             attachments: res.cloudFinal,
             // Compare-and-set: the resolution was computed from the snapshot's
@@ -161,17 +161,6 @@ async function syncResidualAttachments(client, auth, doc, action, outcome, mode)
         outcome.attachmentWrites++;
     }
 }
-/**
- * Servers throw ConvexError({kind, message}) for expected failures; production
- * redacts the Error message to "Server Error" but preserves error.data.
- * Surface the human-readable message rather than the blob.
- */
-function errorDisplayMessage(err) {
-    const data = err.data;
-    if (data && typeof data.message === "string")
-        return data.message;
-    return err instanceof Error ? err.message : String(err);
-}
 async function cloudWrite(auth, doc, cloudById, outcome, mode) {
     if (!auth.projectSlug || !doc.filePath) {
         throw new Error("Cannot write to the cloud without project credentials.");
@@ -361,12 +350,11 @@ async function cloudDelete(client, auth, doc, outcome) {
     if (!auth.projectSlug || !doc.documentId) {
         throw new Error("Cannot delete from the cloud without project credentials.");
     }
-    await client.mutation(api.documents.mutations.deleteForCli, {
+    await client.mutation(api.documents.mutations.deleteForSync, {
         projectAuth: {
             projectSlug: auth.projectSlug,
             projectSecret: auth.projectSecret,
         },
-        target: { type: "project", slug: auth.projectSlug },
         documentId: doc.documentId,
     });
     outcome.cloudDeleted++;

package/dist/sync/publish.js

@@ -11,7 +11,7 @@
  * repo unable to push. Recoverable rather than lossy — see
  * docs/working/publishing-and-unpublished-changes.md.
  */
-import { DEFAULT_API_BASE_URL } from "../requirements/cloud-ai.js";
+import { webApiUrl } from "../cloud.js";
 /**
  * POST to `/api/publish`. Returns the saved document; throws with the server's
  * own message on failure, which is what Jaime reads in the sync output.
@@ -21,7 +21,7 @@ import { DEFAULT_API_BASE_URL } from "../requirements/cloud-ai.js";
  * apply next time.
  */
 export async function publishToCloud(params) {
-    const apiBaseUrl = process.env.DOTREQUIREMENTS_API_URL ?? DEFAULT_API_BASE_URL;
+    const apiBaseUrl = webApiUrl();
     const response = await fetch(`${apiBaseUrl}/api/publish`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },

package/dist/sync/snapshot.d.ts

@@ -1,7 +1,7 @@
 /**
  * Snapshot acquisition for the comparator — kept separate from comparison so
  * the comparator stays a pure function (compare.ts). The local half reads the
- * workspace; the cloud half is one exportProjectForCli query.
+ * workspace; the cloud half is one export query.
  */
 import type { CloudSnapshot, LocalDocument, LocalSnapshot } from "./types.js";
 /**
@@ -22,9 +22,9 @@ export interface CloudAuth {
     projectSecret: string;
 }
 /**
- * Build the cloud snapshot with one exportProjectForCli query. A share token is
- * passed as the projectSecret with no slug (the read-only wrapper resolves the
- * project from the token) — the read-only path never writes back.
+ * Build the cloud snapshot with one export query: the project's own, with a
+ * project secret, or the share endpoint, with a bare share token (the token
+ * names the project) — the read-only path never writes back.
  */
 export declare function acquireCloudSnapshot(auth: CloudAuth): Promise<CloudSnapshot>;
 //# sourceMappingURL=snapshot.d.ts.map

package/dist/sync/snapshot.js

@@ -1,12 +1,12 @@
 /**
  * Snapshot acquisition for the comparator — kept separate from comparison so
  * the comparator stays a pure function (compare.ts). The local half reads the
- * workspace; the cloud half is one exportProjectForCli query.
+ * workspace; the cloud half is one export query.
  */
 import * as fs from "node:fs";
 import { ConvexHttpClient } from "convex/browser";
 import YAML from "yaml";
-import { getConvexUrl } from "../config.js";
+import { convexUrl } from "../cloud.js";
 import { api } from "../convex.js";
 import { findRequirementsFiles } from "../requirements/index.js";
 import { splitLeadingH1, validateMetadata } from "../schema/index.js";
@@ -120,18 +120,23 @@ export async function acquireLocalSnapshot(workspaceRoot, filePaths) {
     return { documents: paths.map(readLocalDocument) };
 }
 /**
- * Build the cloud snapshot with one exportProjectForCli query. A share token is
- * passed as the projectSecret with no slug (the read-only wrapper resolves the
- * project from the token) — the read-only path never writes back.
+ * Build the cloud snapshot with one export query: the project's own, with a
+ * project secret, or the share endpoint, with a bare share token (the token
+ * names the project) — the read-only path never writes back.
  */
 export async function acquireCloudSnapshot(auth) {
-    const client = new ConvexHttpClient(getConvexUrl());
-    const projectAuth = auth.projectSlug
-        ? { projectSlug: auth.projectSlug, projectSecret: auth.projectSecret }
-        : { projectSecret: auth.projectSecret };
-    const result = (await client.query(api.documents.queries.exportProjectForCli, {
-        projectAuth,
-    }));
+    const client = new ConvexHttpClient(convexUrl());
+    const result = (await (auth.projectSlug
+        ? client.query(api.documents.queries.exportProject, {
+            projectAuth: {
+                projectSlug: auth.projectSlug,
+                projectSecret: auth.projectSecret,
+            },
+            project: auth.projectSlug,
+        })
+        : client.query(api.documents.queries.exportProjectForShare, {
+            shareToken: auth.projectSecret,
+        })));
     return {
         projectName: result.projectName,
         projectSlug: result.projectSlug,

package/dist/sync/types.d.ts

@@ -34,7 +34,7 @@ export interface LocalDocument {
     parseError?: string;
 }
 /**
- * One published document as it exists in the cloud, from exportProjectForCli.
+ * One published document as it exists in the cloud, from the project export.
  */
 export interface CloudDocument {
     documentId: string;

package/dist/templates/example-requirements.js

@@ -26,8 +26,8 @@ HOWTO-1: How to use dotrequirements
     2.0. Nesting → You can keep nesting. Label references don't need to be nested: requirement('HOWTO-1.nesting').
     2.1. Several words → Reference multi-word labels using kebab-case. Label references are never case sensitive: requirement('HOWTO-1.several-words')
   3. → While you _can_ write your requirements longhand in this format, there are a number of better ways.
-    3.0. MCP → The dotrequirements MCP equips an AI assistant to develop requirements with you
-    3.1. Your current tools → Dotrequirements has a composer for Jira, Confluence, and Notion
+    3.0. Coding assistants → Run \`dotreq ai-setup\` and your coding assistant develops requirements with you
+    3.1. Chat → Connect Claude or ChatGPT to dot•requirements and write specs in the conversation
     3.2. Our composer → You can use our requirements composer at app.dotrequirements.io
   4. Have fun → Especially in the time you get back from having a more stable, transparent, and AI-friendly codebase
 \`\`\`

package/dist/templates/example-requirements.ts

@@ -29,8 +29,8 @@ HOWTO-1: How to use dotrequirements
     2.0. Nesting → You can keep nesting. Label references don't need to be nested: requirement('HOWTO-1.nesting').
     2.1. Several words → Reference multi-word labels using kebab-case. Label references are never case sensitive: requirement('HOWTO-1.several-words')
   3. → While you _can_ write your requirements longhand in this format, there are a number of better ways.
-    3.0. MCP → The dotrequirements MCP equips an AI assistant to develop requirements with you
-    3.1. Your current tools → Dotrequirements has a composer for Jira, Confluence, and Notion
+    3.0. Coding assistants → Run \`dotreq ai-setup\` and your coding assistant develops requirements with you
+    3.1. Chat → Connect Claude or ChatGPT to dot•requirements and write specs in the conversation
     3.2. Our composer → You can use our requirements composer at app.dotrequirements.io
   4. Have fun → Especially in the time you get back from having a more stable, transparent, and AI-friendly codebase
 \`\`\`

package/dist/utils/command-error.d.ts

@@ -0,0 +1,19 @@
+/**
+ * What a failed command tells Sam (ERR-6).
+ *
+ * Production Convex replaces the message of every server error with
+ * "[Request ID: …] Server Error" and keeps only a ConvexError's `data`, which
+ * is where the backend puts the sentence written for users. So a refusal is
+ * read from its data; a server failure that carries none becomes a fixed
+ * sentence with its request ID; anything else is an error raised on Sam's
+ * machine, whose own message is already meant to be read.
+ */
+/**
+ * The user-facing message a ConvexError's data carries, if any: the data is
+ * either a plain string or an object with a `message`. Mirrors
+ * `packages/web/lib/convex-error.ts`.
+ */
+export declare function userFacingMessage(data: unknown): string | undefined;
+/** The text to print for an error that ended a command. */
+export declare function commandErrorMessage(error: unknown): string;
+//# sourceMappingURL=command-error.d.ts.map

package/dist/utils/command-error.js

@@ -0,0 +1,44 @@
+/**
+ * What a failed command tells Sam (ERR-6).
+ *
+ * Production Convex replaces the message of every server error with
+ * "[Request ID: …] Server Error" and keeps only a ConvexError's `data`, which
+ * is where the backend puts the sentence written for users. So a refusal is
+ * read from its data; a server failure that carries none becomes a fixed
+ * sentence with its request ID; anything else is an error raised on Sam's
+ * machine, whose own message is already meant to be read.
+ */
+/**
+ * The user-facing message a ConvexError's data carries, if any: the data is
+ * either a plain string or an object with a `message`. Mirrors
+ * `packages/web/lib/convex-error.ts`.
+ */
+export function userFacingMessage(data) {
+    if (typeof data === "string" && data.trim())
+        return data;
+    if (data && typeof data === "object" && "message" in data) {
+        const { message } = data;
+        if (typeof message === "string" && message.trim())
+            return message;
+    }
+    return undefined;
+}
+const SERVER_ERROR = /\bServer Error\b/;
+const REQUEST_ID = /Request ID: ([\w-]+)/;
+/** The text to print for an error that ended a command. */
+export function commandErrorMessage(error) {
+    if (error && typeof error === "object" && "data" in error) {
+        const message = userFacingMessage(error.data);
+        if (message)
+            return message;
+    }
+    const raw = error instanceof Error ? error.message : String(error);
+    if (SERVER_ERROR.test(raw)) {
+        const requestId = REQUEST_ID.exec(raw)?.[1];
+        return requestId
+            ? `Something went wrong in dotrequirements' cloud (request ID ${requestId}). Try again, and if it keeps happening, email support@dotrequirements.io with the request ID.`
+            : "Something went wrong in dotrequirements' cloud. Try again, and if it keeps happening, email support@dotrequirements.io.";
+    }
+    return raw;
+}
+//# sourceMappingURL=command-error.js.map

package/dist/utils/oauth-flow.js

@@ -6,7 +6,7 @@
  */
 import { randomBytes } from "node:crypto";
 import { ConvexHttpClient } from "convex/browser";
-import { getConvexUrl } from "../config.js";
+import { convexUrl } from "../cloud.js";
 import { api } from "../convex.js";
 import { openBrowserWithFallback } from "./browser-launch.js";
 import { startCallbackServer } from "./oauth-callback-server.js";
@@ -58,7 +58,7 @@ export async function executeOAuthFlow() {
     }
     console.log("Authentication successful, exchanging code for tokens...");
     // Exchange authorization code for tokens via Convex action (server-side WorkOS call)
-    const client = new ConvexHttpClient(getConvexUrl());
+    const client = new ConvexHttpClient(convexUrl());
     const result = await client.action(api.lib.authActions.exchangeAuthorizationCode, {
         code,
         codeVerifier,

package/dist/utils/project-selector.js

@@ -43,9 +43,9 @@ export async function selectTeam(client) {
  */
 export async function selectProject(client, teamId) {
     console.log("\nFetching projects...\n");
-    const projectsWithSecrets = (await client.query(api.projectSecrets.queries.listOwnSecretsForTeam, 
+    const projectsWithSecrets = (await client.query(api.projectSecrets.queries.listOwnForTeam, 
     // biome-ignore lint/suspicious/noExplicitAny: CLI workspace doesn't import convex's branded Id<"teams"> type; the runtime value is a plain string the convex server validates.
-    { target: { type: "team", id: teamId } }));
+    { teamId: teamId }));
     if (projectsWithSecrets.length === 0) {
         console.log("No projects found in this team.");
         console.log('Use "dotrequirements init" to create a new project.\n');
@@ -79,9 +79,9 @@ export async function selectProject(client, teamId) {
  *                     Free tier always gets 30 days regardless of this parameter.
  */
 export async function getOrCreateProjectSecret(client, projectId, expiryDays) {
-    const result = (await client.mutation(api.projectSecrets.mutations.ensureOwnSecret, {
+    const result = (await client.mutation(api.projectSecrets.mutations.ensureOwn, {
         // biome-ignore lint/suspicious/noExplicitAny: CLI workspace doesn't import convex's branded Id<"projects"> type; the runtime value is a plain string the convex server validates.
-        target: { type: "project", id: projectId },
+        projectId: projectId,
         expiryDays,
     }));
     return result;

package/dist/version-messages.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What the cloud has to say to this CLI version (CLI-MSG-1, CLI-MSG-3).
+ *
+ * Once enabled, the first cloud use in a run asks the cloud for this
+ * version's messages, alongside the command's own work. At the end the
+ * command takes them: text commands print them after their output, JSON
+ * commands carry them in their JSON. Asking never changes the command: a
+ * failed, unreadable or slow answer means no messages.
+ */
+/** How long a finished command waits for the cloud's answer (CLI-MSG-3.2). */
+export declare const MESSAGE_WAIT_MS = 1000;
+/** Ask the cloud for this version's messages on the run's first cloud use. */
+export declare function enableVersionMessages(): void;
+/**
+ * The messages for this version, waiting at most `waitMs` for the cloud's
+ * answer; empty when the run never reached the cloud or they were already
+ * shown. Asking twice waits once.
+ */
+export declare function versionMessages(waitMs?: number): Promise<string[]>;
+/**
+ * Record that this run's messages reached the user, once they are actually
+ * printed, so `wrapCommand` doesn't print them again after a JSON command
+ * carried them — and does print them if that command failed first.
+ */
+export declare function markVersionMessagesShown(): void;
+/** The messages as text, for a command's human-readable output. */
+export declare function formatVersionMessages(messages: string[]): string;
+//# sourceMappingURL=version-messages.d.ts.map

package/dist/version-messages.js

@@ -0,0 +1,87 @@
+/**
+ * What the cloud has to say to this CLI version (CLI-MSG-1, CLI-MSG-3).
+ *
+ * Once enabled, the first cloud use in a run asks the cloud for this
+ * version's messages, alongside the command's own work. At the end the
+ * command takes them: text commands print them after their output, JSON
+ * commands carry them in their JSON. Asking never changes the command: a
+ * failed, unreadable or slow answer means no messages.
+ */
+import { convexUrl, whenCloudFirstUsed } from "./cloud.js";
+import { getOwnPackage } from "./utils/own-package.js";
+/** How long a finished command waits for the cloud's answer (CLI-MSG-3.2). */
+export const MESSAGE_WAIT_MS = 1_000;
+let pending = null;
+let abort = null;
+let shown = false;
+async function askCloud(signal) {
+    try {
+        const response = await fetch(`${convexUrl()}/api/query`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                path: "cliMessages/queries:forVersion",
+                args: { version: getOwnPackage().version },
+                format: "json",
+            }),
+            signal,
+        });
+        if (!response.ok)
+            return [];
+        const body = (await response.json());
+        const messages = body.status === "success" ? body.value?.messages : null;
+        return Array.isArray(messages)
+            ? messages.filter((m) => typeof m === "string" && !!m)
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Ask the cloud for this version's messages on the run's first cloud use. */
+export function enableVersionMessages() {
+    whenCloudFirstUsed(() => {
+        if (pending)
+            return;
+        const controller = new AbortController();
+        abort = controller;
+        // Asked just after the command's own first request goes out, so the
+        // command's work is never queued behind the question.
+        pending = new Promise((resolve) => {
+            queueMicrotask(() => resolve(askCloud(controller.signal)));
+        });
+    });
+}
+/**
+ * The messages for this version, waiting at most `waitMs` for the cloud's
+ * answer; empty when the run never reached the cloud or they were already
+ * shown. Asking twice waits once.
+ */
+export async function versionMessages(waitMs = MESSAGE_WAIT_MS) {
+    if (shown || !pending)
+        return [];
+    let timer;
+    const late = new Promise((resolve) => {
+        timer = setTimeout(() => resolve([]), waitMs);
+    });
+    const messages = await Promise.race([pending, late]);
+    clearTimeout(timer);
+    // Whatever came back is the answer: a slow one must neither keep the
+    // process alive after the command nor be waited for a second time.
+    abort?.abort();
+    pending = Promise.resolve(messages);
+    return messages;
+}
+/**
+ * Record that this run's messages reached the user, once they are actually
+ * printed, so `wrapCommand` doesn't print them again after a JSON command
+ * carried them — and does print them if that command failed first.
+ */
+export function markVersionMessagesShown() {
+    shown = true;
+}
+/** The messages as text, for a command's human-readable output. */
+export function formatVersionMessages(messages) {
+    return messages.map((message) => `\n${message}`).join("\n");
+}
+//# sourceMappingURL=version-messages.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popoverai/dotrequirements",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Requirements as testable, human-readable data — CLI and test harness for spec-driven development with AI coding agents",
   "type": "module",
   "bin": {

package/dist/config.d.ts

@@ -1,5 +0,0 @@
-/**
- * Get the Convex deployment URL
- */
-export declare function getConvexUrl(): string;
-//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -1,12 +0,0 @@
-/**
- * Production Convex deployment URL
- * All users connect to the same backend
- */
-const CONVEX_URL = "https://data.dotrequirements.io";
-/**
- * Get the Convex deployment URL
- */
-export function getConvexUrl() {
-    return CONVEX_URL;
-}
-//# sourceMappingURL=config.js.map