@abloatai/cli 0.45.0 → 0.47.0

package/dist/cli.cjs

@@ -3755,7 +3755,8 @@ async function confirmFromServer(opts) {
   }
 }
 async function nameProject(projectId, organizationId, opts) {
-  const listed = await listProjects(opts.apiKey, opts.url);
+  const namingKey = resolveOrgManagementKey() ?? opts.apiKey;
+  const listed = await listProjects(namingKey, opts.url);
   const match = listed.ok ? listed.projects.find((p2) => p2.id === projectId) : void 0;
   if (match) {
     return { id: match.id, slug: match.slug, name: match.name, isDefault: match.default };
@@ -4098,6 +4099,10 @@ async function loadSchema(schemaPath, exportName) {
 function maskKey(key) {
   return key ? `${key.slice(0, 12)}\u2026` : "(none)";
 }
+function schemaPushPlaneHint(code) {
+  if (code !== "test_database_not_registered") return null;
+  return `The key authenticated and already passed ${import_picocolors5.default.bold("schema:push")} authorization. This is a branch storage-provisioning error, not a key-scope error. Check the plane with ${import_picocolors5.default.bold("npx ablo branch status <branch>")}; a branch reported as hosted should not need a customer database.`;
+}
 function schemaGitState(schemaPath) {
   try {
     const out = (0, import_child_process.execFileSync)("git", ["status", "--porcelain", "--", schemaPath], {
@@ -4406,7 +4411,10 @@ async function push(argv) {
     const serverMsg = body.message ?? body.reason;
     console.error(import_picocolors5.default.red(`  Forbidden${code ? ` [${code}]` : ""}: ${serverMsg ?? "permission denied"}`));
     console.error(import_picocolors5.default.dim(`  Push used ${import_picocolors5.default.bold(maskKey(args.apiKey))} from ${describeKeySource(keySource)}.`));
-    if (code === "database_role_cannot_enforce_rls") {
+    const planeHint = schemaPushPlaneHint(code);
+    if (planeHint) {
+      console.error(import_picocolors5.default.dim(`  ${planeHint}`));
+    } else if (code === "database_role_cannot_enforce_rls") {
       console.error(
         import_picocolors5.default.dim(
           `  Your database role bypasses row-level security. Run ${import_picocolors5.default.bold("npx ablo migrate")} to create a scoped (NOBYPASSRLS) role and repoint DATABASE_URL, then re-push.`
@@ -4538,6 +4546,7 @@ async function requestRemoteValidation(input) {
     ok: true,
     reachable: verdict.reachable,
     ready: verdict.ready,
+    ...verdict.initial_snapshot !== void 0 ? { initialSnapshot: verdict.initial_snapshot } : {},
     ...verdict.reason !== void 0 ? { reason: verdict.reason } : {},
     failures: verdict.failures
   };
@@ -4565,8 +4574,13 @@ var init_remoteValidation = __esm({
       wal_level: () => `your database isn't set up to share changes as they happen yet`,
       publication: () => `none of your tables are shared with Ablo yet`,
       replication_role: () => `the login Ablo reads with can't follow your changes yet`,
-      replica_identity: (f) => withActual(`some shared tables don't record enough for Ablo to track edits and deletes`, f.actual),
+      replication_slot_capacity: (f) => withActual(`this database has no remaining change-stream capacity for this binding`, f.actual),
+      replica_identity: (f) => withActual(
+        `some shared tables don't record enough for Ablo to track edits and deletes`,
+        f.actual
+      ),
       table_select: (f) => withActual(`the login Ablo reads with can't read some shared tables`, f.actual),
+      snapshot_row_security: (f) => withActual(`row-level security hides historical rows from Ablo's initial load`, f.actual),
       write_role: () => `the login Ablo writes with isn't set up yet`,
       row_security: () => `the writer login isn't set to honor your row-level security`,
       database_privileges: () => `the writer login can still create things in your database`,
@@ -4666,7 +4680,7 @@ function quoteIdent(id) {
 function quoteLiteral(value) {
   return `'${value.replace(/'/g, "''")}'`;
 }
-function scopedSequenceGrant(tables, writeRole) {
+function scopedSequenceGrant(tables, writeRole, schema) {
   const names = tables.map(quoteLiteral).join(", ");
   return `DO $$
 DECLARE seq regclass;
@@ -4677,7 +4691,7 @@ BEGIN
     JOIN pg_class s ON s.oid = d.objid AND s.relkind = 'S'
     JOIN pg_class t ON t.oid = d.refobjid
     JOIN pg_namespace n ON n.oid = t.relnamespace
-    WHERE d.deptype IN ('a', 'i') AND n.nspname = 'public' AND t.relname IN (${names})
+    WHERE d.deptype IN ('a', 'i') AND n.nspname = ${quoteLiteral(schema)} AND t.relname IN (${names})
   LOOP
     EXECUTE format('GRANT USAGE, SELECT ON SEQUENCE %s TO ${quoteIdent(writeRole)}', seq);
   END LOOP;
@@ -4687,24 +4701,29 @@ function connectSetupSql(input) {
   const role = input.role && input.role.length > 0 ? input.role : import_footprint.ABLO_REPLICATION_ROLE;
   const writeRole = input.writeRole && input.writeRole.length > 0 ? input.writeRole : import_footprint.ABLO_WRITE_ROLE;
   const tables = input.tables ?? [];
-  const publicationTarget = tables.length > 0 ? `FOR TABLE ${tables.map(quoteIdent).join(", ")}` : "FOR ALL TABLES";
-  const tableList = tables.map(quoteIdent).join(", ");
+  const schema = input.schema ?? "public";
+  const publication = input.publication ?? import_footprint.ABLO_PUBLICATION;
+  const qualifiedTables = tables.map((table) => `${quoteIdent(schema)}.${quoteIdent(table)}`);
+  const publicationTarget = tables.length > 0 ? `FOR TABLE ${qualifiedTables.join(", ")}` : "FOR ALL TABLES";
+  const tableList = qualifiedTables.join(", ");
   const scoped = tables.length > 0;
-  const applicationGrant = scoped ? `GRANT SELECT, INSERT, UPDATE, DELETE ON TABLE ${tableList} TO ${quoteIdent(writeRole)};` : `GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO ${quoteIdent(writeRole)};`;
+  const applicationGrant = scoped ? `GRANT SELECT, INSERT, UPDATE, DELETE ON TABLE ${tableList} TO ${quoteIdent(writeRole)};` : `GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA ${quoteIdent(schema)} TO ${quoteIdent(writeRole)};`;
   const replicationReadGrants = scoped ? [`GRANT SELECT ON TABLE ${tableList} TO ${quoteIdent(role)};`] : [
-    `GRANT SELECT ON ALL TABLES IN SCHEMA public TO ${quoteIdent(role)};`,
-    `ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO ${quoteIdent(role)};`
+    `GRANT SELECT ON ALL TABLES IN SCHEMA ${quoteIdent(schema)} TO ${quoteIdent(role)};`,
+    `ALTER DEFAULT PRIVILEGES IN SCHEMA ${quoteIdent(schema)} GRANT SELECT ON TABLES TO ${quoteIdent(role)};`
   ];
-  const writerSequenceGrants = scoped ? [scopedSequenceGrant(tables, writeRole)] : [`GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO ${quoteIdent(writeRole)};`];
-  const ledger = (0, import_source2.idempotencyLedgerMigrations)().map((migration) => migration.up);
+  const writerSequenceGrants = scoped ? [scopedSequenceGrant(tables, writeRole, schema)] : [`GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA ${quoteIdent(schema)} TO ${quoteIdent(writeRole)};`];
+  const ledger = (0, import_source2.idempotencyLedgerMigrations)(schema).map((migration) => migration.up);
   return [
     // 1. Turn on logical decoding. Requires a restart (it's not reloadable).
     `ALTER SYSTEM SET wal_level = 'logical';`,
     // 2. Publish the tables Ablo should read.
-    `CREATE PUBLICATION ${quoteIdent(import_footprint.ABLO_PUBLICATION)} ${publicationTarget};`,
+    `CREATE PUBLICATION ${quoteIdent(publication)} ${publicationTarget};`,
     // 3. A least-privilege role: it can stream replication and SELECT the
-    // published tables, nothing more.
-    `CREATE ROLE ${quoteIdent(role)} WITH REPLICATION LOGIN PASSWORD '<password>';`,
+    // published tables, including the initial snapshot of RLS-protected tables.
+    // Logical decoding already exposes every published row independently of
+    // RLS; BYPASSRLS makes the ordinary SELECT snapshot match that same scope.
+    `CREATE ROLE ${quoteIdent(role)} WITH NOSUPERUSER BYPASSRLS NOCREATEDB NOCREATEROLE REPLICATION NOINHERIT LOGIN PASSWORD '<password>';`,
     ...replicationReadGrants,
     // 4. A distinct DML role: no replication, role administration, ownership,
     // schema creation, or DDL. It runs NOBYPASSRLS with row_security on, so on a
@@ -4725,20 +4744,20 @@ function connectSetupSql(input) {
 DO $$ BEGIN
   EXECUTE format('REVOKE TEMPORARY, CREATE ON DATABASE %I FROM PUBLIC', current_database());
 END $$;`,
-    `GRANT USAGE ON SCHEMA public TO ${quoteIdent(writeRole)};`,
+    `GRANT USAGE ON SCHEMA ${quoteIdent(schema)} TO ${quoteIdent(writeRole)};`,
     applicationGrant,
     ...writerSequenceGrants,
     ...scoped ? [] : [
       // "All tables" mode only: keep future tables/sequences writable so the
       // publication doesn't outgrow the grant.
-      `ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ${quoteIdent(writeRole)};`,
-      `ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT USAGE, SELECT ON SEQUENCES TO ${quoteIdent(writeRole)};`
+      `ALTER DEFAULT PRIVILEGES IN SCHEMA ${quoteIdent(schema)} GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ${quoteIdent(writeRole)};`,
+      `ALTER DEFAULT PRIVILEGES IN SCHEMA ${quoteIdent(schema)} GRANT USAGE, SELECT ON SEQUENCES TO ${quoteIdent(writeRole)};`
     ],
     // 5. Direct uses the durable replay ledger but deliberately no outbox.
     ...ledger,
-    `REVOKE ALL ON TABLE public.ablo_idempotency FROM PUBLIC;`,
-    `GRANT SELECT, INSERT, UPDATE ON TABLE public.ablo_idempotency TO ${quoteIdent(writeRole)};`,
-    `REVOKE DELETE ON TABLE public.ablo_idempotency FROM ${quoteIdent(writeRole)};`,
+    `REVOKE ALL ON TABLE ${quoteIdent(schema)}.${quoteIdent("ablo_idempotency")} FROM PUBLIC;`,
+    `GRANT SELECT, INSERT, UPDATE ON TABLE ${quoteIdent(schema)}.${quoteIdent("ablo_idempotency")} TO ${quoteIdent(writeRole)};`,
+    `REVOKE DELETE ON TABLE ${quoteIdent(schema)}.${quoteIdent("ablo_idempotency")} FROM ${quoteIdent(writeRole)};`,
     // The writer emits a transactional marker on your WAL so Ablo can correlate
     // the committed row back to the originating write and confirm it — this
     // EXECUTE grant is what makes that confirmation possible. Granted by lookup
@@ -4761,10 +4780,12 @@ BEGIN
 END $$;`
   ];
 }
-function reconcilePublicationPlan(current, desiredTables) {
-  const pub = quoteIdent(import_footprint.ABLO_PUBLICATION);
+function reconcilePublicationPlan(current, desiredTables, opts = {}) {
+  const pub = quoteIdent(opts.publication ?? import_footprint.ABLO_PUBLICATION);
+  const schema = opts.schema ?? "public";
+  const qualified = (table) => `${quoteIdent(schema)}.${quoteIdent(table)}`;
   const desiredAll = desiredTables.length === 0;
-  const target = desiredAll ? "FOR ALL TABLES" : `FOR TABLE ${desiredTables.map(quoteIdent).join(", ")}`;
+  const target = desiredAll ? "FOR ALL TABLES" : `FOR TABLE ${desiredTables.map(qualified).join(", ")}`;
   if (!current.exists) {
     return {
       sql: [`CREATE PUBLICATION ${pub} ${target};`],
@@ -4790,28 +4811,31 @@ function reconcilePublicationPlan(current, desiredTables) {
     return { sql: [], added: [], removed: [], recreated: false };
   }
   return {
-    sql: [`ALTER PUBLICATION ${pub} SET TABLE ${desiredTables.map(quoteIdent).join(", ")};`],
+    sql: [`ALTER PUBLICATION ${pub} SET TABLE ${desiredTables.map(qualified).join(", ")};`],
     added,
     removed,
     recreated: false
   };
 }
-async function readPublicationState(sql) {
+async function readPublicationState(sql, opts = {}) {
+  const publication = opts.publication ?? import_footprint.ABLO_PUBLICATION;
+  const schema = opts.schema ?? "public";
   const pubRows = await sql.unsafe(
     `SELECT puballtables FROM pg_publication WHERE pubname = $1`,
-    [import_footprint.ABLO_PUBLICATION]
+    [publication]
   );
   const pubRow = pubRows[0];
   if (!pubRow) return { exists: false, allTables: false, tables: [] };
   if (pubRow.puballtables) return { exists: true, allTables: true, tables: [] };
   const tableRows = await sql.unsafe(
-    `SELECT tablename FROM pg_publication_tables WHERE pubname = $1 AND schemaname = 'public' ORDER BY tablename`,
-    [import_footprint.ABLO_PUBLICATION]
+    `SELECT tablename FROM pg_publication_tables WHERE pubname = $1 AND schemaname = $2 ORDER BY tablename`,
+    [publication, schema]
   );
   return { exists: true, allTables: false, tables: tableRows.map((r2) => r2.tablename) };
 }
 async function probeReadiness(sql, opts = {}) {
   const publication = opts.publication ?? import_footprint.ABLO_PUBLICATION;
+  const schema = opts.schema ?? "public";
   const coordinated = opts.coordinatedTables && opts.coordinatedTables.length > 0 ? new Set(opts.coordinatedTables) : null;
   const items = [];
   const walRows = await sql.unsafe(
@@ -4843,7 +4867,7 @@ On Neon enable Logical Replication in the project (Console \u2192 Settings \u219
     }
   );
   const roleRows = await sql.unsafe(
-    `SELECT rolreplication, rolsuper FROM pg_roles WHERE rolname = current_user`
+    `SELECT rolreplication, rolsuper, rolbypassrls FROM pg_roles WHERE rolname = current_user`
   );
   const role = roleRows[0];
   const hasReplication = Boolean(role && (role.rolreplication || role.rolsuper));
@@ -4859,12 +4883,31 @@ On RDS: GRANT rds_replication TO <your_role>;`
     }
   );
   if (pubRows.length > 0) {
+    const rlsRows = await sql.unsafe(
+      `SELECT DISTINCT pt.tablename AS table_name
+         FROM pg_publication_tables pt
+         JOIN pg_namespace n ON n.nspname = pt.schemaname
+         JOIN pg_class c ON c.relnamespace = n.oid AND c.relname = pt.tablename
+        WHERE pt.pubname = $1 AND pt.schemaname = $2
+          AND row_security_active(c.oid)
+        ORDER BY table_name`,
+      [publication, schema]
+    );
+    const rlsRelevant = coordinated ? rlsRows.filter((row) => coordinated.has(row.table_name)) : rlsRows;
+    items.push(
+      rlsRelevant.length === 0 ? { ok: true, label: "the initial snapshot can read every published row" } : {
+        ok: false,
+        label: `${rlsRelevant.length} published table${rlsRelevant.length === 1 ? "" : "s"} hide historical rows behind RLS`,
+        fix: `ALTER ROLE current_user WITH BYPASSRLS;
+Logical replication already exposes every published row; this lets the ordinary initial SELECT read that same scope.`
+      }
+    );
     const badRows = await sql.unsafe(
       `SELECT c.relname AS table_name, c.relreplident
          FROM pg_publication_tables pt
          JOIN pg_class c ON c.relname = pt.tablename
          JOIN pg_namespace n ON n.oid = c.relnamespace AND n.nspname = pt.schemaname
-        WHERE pt.pubname = $1
+        WHERE pt.pubname = $1 AND pt.schemaname = $2
           AND (
             c.relreplident = 'n'
             OR (
@@ -4875,7 +4918,7 @@ On RDS: GRANT rds_replication TO <your_role>;`
               )
             )
           )`,
-      [publication]
+      [publication, schema]
     );
     const relevant = coordinated ? badRows.filter((row) => coordinated.has(row.table_name)) : badRows;
     items.push(
@@ -4883,7 +4926,7 @@ On RDS: GRANT rds_replication TO <your_role>;`
         ok: false,
         label: `${relevant.length} published table${relevant.length === 1 ? "" : "s"} cannot replicate UPDATE/DELETE`,
         fix: relevant.map(
-          (r2) => `${r2.table_name}: add a PRIMARY KEY, or ALTER TABLE ${quoteIdent(r2.table_name)} REPLICA IDENTITY FULL;`
+          (r2) => `${r2.table_name}: add a PRIMARY KEY, or ALTER TABLE ${quoteIdent(schema)}.${quoteIdent(r2.table_name)} REPLICA IDENTITY FULL;`
         ).join("\n")
       }
     );
@@ -4900,7 +4943,10 @@ async function registerDirectDataSource(opts) {
       connection: "direct",
       connectionString: opts.replicationUrl,
       writeConnectionString: opts.writeUrl,
-      route: opts.route
+      route: opts.route,
+      ...opts.schema ? { schema: opts.schema } : {},
+      ...opts.replicationSlot ? { replicationSlot: opts.replicationSlot } : {},
+      ...opts.publication ? { publication: opts.publication } : {}
     },
     responseSchema: import_wire3.datasourceSummarySchema
   });
@@ -4911,7 +4957,8 @@ async function registerDirectDataSource(opts) {
       `
   ${import_picocolors7.default.green("\u2713")} Registered${body.host ? ` ${import_picocolors7.default.dim(body.host)}` : ""}${body.id ? ` ${import_picocolors7.default.dim(`(${body.id})`)}` : ""} as a direct DataSource (${statusNote}).
   Your database is connected. Reads follow its replication stream; writes go through Ablo
-  and land in your own tables. Check the connection anytime with ${import_picocolors7.default.cyan("ablo connect check")}.
+  and land in your own tables. Rows that already exist load automatically \u2014 no manual
+  backfill or row updates. Check their progress with ${import_picocolors7.default.cyan("ablo connect check")}.
 `
     );
     return true;
@@ -5213,26 +5260,27 @@ function ownershipRemediation(blockers2, admin) {
   const unresolved = blockers2.filter((blocker) => !resolvedOwners.has(blocker.owner));
   return { inheritGrants, unresolved };
 }
-async function publishedTableBlockers(sql, tables) {
+async function publishedTableBlockers(sql, tables, schema = "public") {
   const scoped = tables.length > 0;
   const raw = await sql.unsafe(
     `SELECT format('%I.%I', n.nspname, c.relname) AS relation, ${OWNERSHIP_COLUMNS}
      ${OWNERSHIP_FROM}
       WHERE c.relkind = 'r'
-        AND n.nspname = 'public'
+        AND n.nspname = $${scoped ? "2" : "1"}
         AND c.relname <> 'ablo_idempotency'
         ${scoped ? "AND c.relname = ANY($1)" : ""}`,
-    scoped ? [tables] : []
+    scoped ? [tables, schema] : [schema]
   );
   return ownershipBlockers(import_zod3.z.array(ownedRelationRowSchema).parse(raw));
 }
-async function ledgerBlocker(sql) {
+async function ledgerBlocker(sql, schema = "public") {
   const raw = await sql.unsafe(
     `SELECT format('%I.%I', n.nspname, c.relname) AS relation, ${OWNERSHIP_COLUMNS}
      ${OWNERSHIP_FROM}
       WHERE c.relkind = 'r'
-        AND n.nspname = 'public'
-        AND c.relname = 'ablo_idempotency'`
+        AND n.nspname = $1
+        AND c.relname = 'ablo_idempotency'`,
+    [schema]
   );
   const rows = import_zod3.z.array(ownedRelationRowSchema).parse(raw);
   const row = rows[0];
@@ -5468,13 +5516,15 @@ function connectApplyPlan(input) {
   const role = input.role && input.role.length > 0 ? input.role : import_footprint.ABLO_REPLICATION_ROLE;
   const writeRole = input.writeRole && input.writeRole.length > 0 ? input.writeRole : import_footprint.ABLO_WRITE_ROLE;
   const tables = input.tables ?? [];
+  const schema = input.schema ?? "public";
+  const publication = input.publication ?? import_footprint.ABLO_PUBLICATION;
   const provider = input.provider ?? "generic";
-  const recipe = connectSetupSql({ tables, role, writeRole });
+  const recipe = connectSetupSql({ tables, role, writeRole, schema, publication });
   const isWal = (s) => s.startsWith("ALTER SYSTEM SET wal_level");
   const isPublication = (s) => s.startsWith("CREATE PUBLICATION");
   const isRoleCreate = (s) => s.startsWith("CREATE ROLE ");
   const grants = recipe.filter((s) => !isWal(s) && !isPublication(s) && !isRoleCreate(s));
-  const publicationTarget = tables.length > 0 ? `FOR TABLE ${tables.map(quoteIdent).join(", ")}` : "FOR ALL TABLES";
+  const publicationTarget = tables.length > 0 ? `FOR TABLE ${tables.map((table) => `${quoteIdent(schema)}.${quoteIdent(table)}`).join(", ")}` : "FOR ALL TABLES";
   const affectsOthers = effectsOnOthers({ grants, allTables: tables.length === 0 });
   const walStep = input.walAlreadyLogical ? [] : [
     provider === "generic" ? {
@@ -5489,10 +5539,10 @@ function connectApplyPlan(input) {
       sql: []
     }
   ];
-  const reconcile2 = input.existingPublication ? reconcilePublicationPlan(input.existingPublication, tables) : null;
+  const reconcile2 = input.existingPublication ? reconcilePublicationPlan(input.existingPublication, tables, { schema, publication }) : null;
   const publicationSql = reconcile2 ? reconcile2.sql : [
     `DO $$ BEGIN
-  CREATE PUBLICATION ${quoteIdent(import_footprint.ABLO_PUBLICATION)} ${publicationTarget};
+  CREATE PUBLICATION ${quoteIdent(publication)} ${publicationTarget};
 EXCEPTION WHEN duplicate_object THEN NULL;
 END $$;`
   ];
@@ -5517,14 +5567,19 @@ END $$;`
     {
       key: "replication-role",
       title: "Create the read-only login Ablo reads with",
-      detail: `${role} \u2014 it can follow your changes and read, nothing else`,
+      detail: `${role} \u2014 it can follow your changes and snapshot the same published rows, including through RLS`,
       sql: [
         idempotentRole(
           role,
-          "REPLICATION",
+          "NOSUPERUSER BYPASSRLS NOCREATEDB NOCREATEROLE REPLICATION NOINHERIT",
           input.credentials.replicationClause,
           input.rotate === true
-        )
+        ),
+        // Unlike a password, this is a required invariant rather than secret
+        // material owned by one plane. Re-assert it for an existing pre-snapshot
+        // role so `connect apply` repairs the exact upgrade gap that otherwise
+        // certifies an RLS-filtered empty snapshot as complete.
+        `ALTER ROLE ${quoteIdent(role)} WITH BYPASSRLS;`
       ]
     },
     {
@@ -5686,16 +5741,23 @@ async function locateExistingConnection(input) {
     method: "POST",
     baseUrl: input.apiUrl,
     apiKey: input.apiKey,
-    body: { connectionString: input.connectionString },
+    body: {
+      connectionString: input.connectionString,
+      ...input.schema ? { schema: input.schema } : {}
+    },
     responseSchema: import_wire6.datasourceLocationResponseSchema
   });
   if (!result.ok) return null;
-  return result.value.held;
+  if (result.value.held) return result.value.held;
+  return result.value.available === false ? { private: true } : null;
 }
 function alreadyConnectedElsewhere(held) {
   if (!held) return null;
+  if ("private" in held) {
+    return "This database schema is already connected to another Ablo organization. Ablo does not reveal that organization\u2019s project or branch.";
+  }
   const where = held.project ? `project ${held.project}, branch ${held.branch}` : `branch ${held.branch}`;
-  return `This database is already connected to ${where}. Ablo streams a database from one plane at a time, so registering it here would take the change stream over from the plane that has it.`;
+  return `This database schema is already connected to ${where}. A (database, schema) binding belongs to one plane at a time.`;
 }
 var import_wire6, import_schema5;
 var init_connectPreflight = __esm({
@@ -5844,12 +5906,18 @@ ${ambient}` : ""}`,
       )
     );
   }
-  const tables = args.tables;
   const coordinatedTables = await schemaDeclaredTables() ?? [];
+  const tables = args.tables.length > 0 ? args.tables : coordinatedTables;
+  if (tables.length === 0) {
+    throw new import_errors9.AbloValidationError(
+      `No mapped tables were found for schema ${args.schema}. Push the Ablo schema first, or pass --tables a,b,c. A project binding must enumerate its own schema-qualified tables; it cannot publish every table in a shared database.`,
+      { code: "cli_invalid_arguments" }
+    );
+  }
   if (args.tables.length === 0) {
     console.log(
       import_picocolors11.default.dim(
-        `  publishing every table${coordinatedTables.length > 0 ? `; readiness judged on the ${coordinatedTables.length} your schema declares` : ""} (${import_picocolors11.default.bold("--tables")} to publish only some)
+        `  publishing the ${tables.length} table${tables.length === 1 ? "" : "s"} declared by your Ablo schema in ${import_picocolors11.default.bold(args.schema)} (${import_picocolors11.default.bold("--tables")} to override)
 `
       )
     );
@@ -5864,8 +5932,28 @@ ${ambient}` : ""}`,
     console.log(`  ${import_picocolors11.default.yellow("!")} ${mismatch}
 `);
   }
+  const confirmed = connectTarget?.confirmed;
+  if (!confirmed?.branchId) {
+    throw new import_errors9.AbloConnectionError(
+      "Ablo could not confirm the branch this key targets, so it cannot derive an isolated database footprint safely. Check the API URL/key and re-run.",
+      { code: "cli_database_unreachable" }
+    );
+  }
+  const footprint = (0, import_footprint2.footprintNamesFor)({
+    organizationId: confirmed.organizationId,
+    branchId: confirmed.branchId,
+    ...confirmed.projectId ? { projectId: confirmed.projectId } : {}
+  });
+  const role = args.role === import_footprint.ABLO_REPLICATION_ROLE ? footprint.replicationRole : args.role;
+  const writeRole = args.writeRole === import_footprint.ABLO_WRITE_ROLE ? footprint.writeRole : args.writeRole;
+  const publication = footprint.publication;
   const heldElsewhere = alreadyConnectedElsewhere(
-    await locateExistingConnection({ apiUrl: apiBaseUrl(), apiKey, connectionString: adminUrl })
+    await locateExistingConnection({
+      apiUrl: apiBaseUrl(),
+      apiKey,
+      connectionString: adminUrl,
+      schema: args.schema
+    })
   );
   if (heldElsewhere) {
     console.error(`  ${import_picocolors11.default.yellow("!")} ${heldElsewhere}
@@ -5925,8 +6013,8 @@ ${ambient}` : ""}`,
     );
     process.exit(1);
   }
-  const ledger = await ledgerBlocker(admin).catch(() => null);
-  const foreignTables = await publishedTableBlockers(admin, tables).catch(() => []);
+  const ledger = await ledgerBlocker(admin, args.schema).catch(() => null);
+  const foreignTables = await publishedTableBlockers(admin, tables, args.schema).catch(() => []);
   const { inheritGrants, unresolved } = ownershipRemediation(
     [...ledger ? [ledger] : [], ...foreignTables],
     capability.rolname
@@ -5950,12 +6038,16 @@ ${ambient}` : ""}`,
     );
     process.exit(1);
   }
-  const existingPublication = await readPublicationState(admin).catch(
+  const existingPublication = await readPublicationState(admin, {
+    schema: args.schema,
+    publication
+  }).catch(
     () => ({ exists: false, allTables: false, tables: [] })
   );
-  const pubReconcile = reconcilePublicationPlan(existingPublication, tables);
-  const role = args.role && args.role.length > 0 ? args.role : import_footprint.ABLO_REPLICATION_ROLE;
-  const writeRole = args.writeRole && args.writeRole.length > 0 ? args.writeRole : import_footprint.ABLO_WRITE_ROLE;
+  const pubReconcile = reconcilePublicationPlan(existingPublication, tables, {
+    schema: args.schema,
+    publication
+  });
   const existingRoles = await presentRoles(admin, [role, writeRole]).catch(() => []);
   if (rotatePlane) {
     const refusal = rotateWithoutConnection({ rotating, ...rotatePlane, existingRoles });
@@ -5996,8 +6088,10 @@ ${ambient}` : ""}`,
   const writePassword = generateRolePassword();
   const buildPlan = (mode) => connectApplyPlan({
     tables,
-    role: args.role,
-    writeRole: args.writeRole,
+    role,
+    writeRole,
+    schema: args.schema,
+    publication,
     rotate: rotating,
     credentials: {
       replicationClause: passwordClause(replicationPassword, mode),
@@ -6011,7 +6105,7 @@ ${ambient}` : ""}`,
   const steps = buildPlan("scram-verifier");
   if (pubReconcile.removed.length > 0 || pubReconcile.recreated) {
     console.log(
-      `  ${import_picocolors11.default.yellow("!")} ${import_picocolors11.default.bold(import_footprint.ABLO_PUBLICATION)} already publishes a different set; reconciling to your ${import_picocolors11.default.bold("--tables")}:`
+      `  ${import_picocolors11.default.yellow("!")} ${import_picocolors11.default.bold(publication)} already publishes a different set; reconciling to your mapped tables:`
     );
     for (const t of pubReconcile.added) console.log(`      ${import_picocolors11.default.green("+")} ${t}`);
     for (const t of pubReconcile.removed)
@@ -6088,9 +6182,12 @@ ${ambient}` : ""}`,
   }
   const replicationProbe = await probeAsRole(
     replicationUrl,
-    (sql) => probeReadiness(sql, { coordinatedTables })
+    (sql) => probeReadiness(sql, { coordinatedTables, schema: args.schema, publication })
+  );
+  const writeProbe = await probeAsRole(
+    writeUrl,
+    (sql) => probeDirectWriteReadiness(sql, { schema: args.schema, publication })
   );
-  const writeProbe = await probeAsRole(writeUrl, probeDirectWriteReadiness);
   const refused = [
     ...replicationProbe.credentialRefused ? [role] : [],
     ...writeProbe.credentialRefused ? [writeRole] : []
@@ -6145,7 +6242,10 @@ ${ambient}` : ""}`,
     apiKey,
     replicationUrl,
     writeUrl,
-    route: args.route
+    route: args.route,
+    schema: args.schema,
+    replicationSlot: footprint.slot,
+    publication
   });
   process.off("SIGINT", onRotateInterrupt);
   process.off("SIGTERM", onRotateInterrupt);
@@ -6157,7 +6257,7 @@ ${ambient}` : ""}`,
   }
   process.exit(outcome.exitCode);
 }
-var import_picocolors11, import_errors9, ROTATE_STRANDED_CREDENTIALS_NOTICE;
+var import_picocolors11, import_errors9, import_footprint2, ROTATE_STRANDED_CREDENTIALS_NOTICE;
 var init_connectApply = __esm({
   "src/connectApply.ts"() {
     "use strict";
@@ -6166,6 +6266,7 @@ var init_connectApply = __esm({
     init_src();
     init_dist2();
     import_errors9 = require("@abloatai/transaction/errors");
+    import_footprint2 = require("@abloatai/transaction/footprint");
     init_connectSetup();
     init_connectOwnership();
     init_connect();
@@ -6189,6 +6290,7 @@ function parseConnectArgs(argv) {
   let register = false;
   let apply = false;
   let rotate = false;
+  let resnapshot = false;
   let url;
   let envFile;
   let yes = false;
@@ -6197,6 +6299,7 @@ function parseConnectArgs(argv) {
   let locate = false;
   let manual = false;
   let tables = [];
+  let schema = "public";
   let role = import_footprint.ABLO_REPLICATION_ROLE;
   let writeRole = import_footprint.ABLO_WRITE_ROLE;
   let route = "public-allowlist";
@@ -6216,6 +6319,9 @@ function parseConnectArgs(argv) {
       case "rotate":
         rotate = true;
         break;
+      case "resnapshot":
+        resnapshot = true;
+        break;
       case "scan":
         scan = true;
         break;
@@ -6224,7 +6330,7 @@ function parseConnectArgs(argv) {
         break;
       default:
         throw new import_errors10.AbloValidationError(
-          `unknown connect subcommand: ${lead} (expected register, deregister, check, apply, rotate, scan, locate)`,
+          `unknown connect subcommand: ${lead} (expected register, deregister, check, apply, rotate, resnapshot, scan, locate)`,
           { code: "cli_invalid_arguments" }
         );
     }
@@ -6254,6 +6360,9 @@ function parseConnectArgs(argv) {
         tables = value.split(",").map((t) => t.trim()).filter((t) => t.length > 0);
         break;
       }
+      case "--schema":
+        schema = argv[++i] ?? schema;
+        break;
       case "--role":
         role = argv[++i] ?? role;
         break;
@@ -6285,6 +6394,7 @@ function parseConnectArgs(argv) {
     register,
     apply,
     rotate,
+    resnapshot,
     url,
     envFile,
     yes,
@@ -6292,6 +6402,7 @@ function parseConnectArgs(argv) {
     scan,
     locate,
     tables,
+    schema,
     role,
     writeRole,
     route,
@@ -6302,7 +6413,8 @@ function printConnectRecipe(args) {
   const sql = connectSetupSql({
     tables: args.tables,
     role: args.role,
-    writeRole: args.writeRole
+    writeRole: args.writeRole,
+    schema: args.schema
   });
   console.log(
     `
@@ -6521,17 +6633,17 @@ async function probeDirectWriteReadiness(sql, opts = {}) {
   );
   return items;
 }
-async function auditTenantSyncInfra(sql) {
+async function auditTenantSyncInfra(sql, opts = {}) {
   const artifacts = [];
-  for (const artifact of import_footprint2.ABLO_FOOTPRINT) {
-    const key = artifact.kind === "table" || artifact.kind === "type" ? `public.${artifact.name}` : artifact.name;
-    const rows = await sql.unsafe(
-      FOOTPRINT_LOOKUP[artifact.kind],
-      [key]
-    );
+  for (const artifact of import_footprint3.ABLO_FOOTPRINT) {
+    const name = opts.names ? artifact.name === import_footprint.ABLO_PUBLICATION ? opts.names.publication : artifact.name === import_footprint3.ABLO_REPLICATION_SLOT ? opts.names.slot : artifact.name === import_footprint.ABLO_REPLICATION_ROLE ? opts.names.replicationRole : artifact.name === import_footprint.ABLO_WRITE_ROLE ? opts.names.writeRole : artifact.name : artifact.name;
+    const key = artifact.kind === "table" || artifact.kind === "type" ? `${artifact.retired ? "public" : opts.schema ?? "public"}.${name}` : name;
+    const rows = await sql.unsafe(FOOTPRINT_LOOKUP[artifact.kind], [
+      key
+    ]);
     artifacts.push({
       kind: artifact.kind,
-      name: artifact.name,
+      name,
       present: rows[0]?.present === true,
       purpose: artifact.purpose,
       ...artifact.hazard ? { hazard: artifact.hazard } : {},
@@ -6560,12 +6672,12 @@ function requireScopedUrl(kind, verb) {
   );
   process.exit(1);
 }
-async function probeAndReport(dbUrl, kind = "replication") {
+async function probeAndReport(dbUrl, kind = "replication", opts = {}) {
   const sql = src_default(dbUrl, { max: 1, prepare: false, connect_timeout: 10, onnotice: () => {
   } });
   let items;
   try {
-    items = kind === "replication" ? await probeReadiness(sql) : await probeDirectWriteReadiness(sql);
+    items = kind === "replication" ? await probeReadiness(sql, opts) : await probeDirectWriteReadiness(sql, opts);
   } catch (err) {
     await sql.end({ timeout: 2 }).catch(() => void 0);
     const dial = dialFailureReason(err);
@@ -6637,6 +6749,22 @@ ${ambient}` : ""}`,
     const { label, fix } = describeRemoteFailure(failure);
     printCheckItem({ ok: false, label, fix });
   }
+  if (result.initialSnapshot?.status === "complete") {
+    printCheckItem({ ok: true, label: "Rows that existed before connecting are loaded" });
+  } else if (result.initialSnapshot?.status === "loading") {
+    printCheckItem({
+      ok: false,
+      label: "Rows that existed before connecting are still loading",
+      fix: "No SQL or row-touch script is needed. Ablo snapshots published tables automatically; wait a moment, then rerun `ablo connect check`."
+    });
+  } else if (result.initialSnapshot?.status === "retrying") {
+    printCheckItem({
+      ok: false,
+      label: "Loading existing rows hit an error and Ablo is retrying",
+      fix: `${result.initialSnapshot.detail ?? "The replication worker reported an error."}
+No row updates are needed. Fix the reported connection or database issue, then rerun \`ablo connect check\`.`
+    });
+  }
   console.log();
   if (result.ready) {
     console.log(
@@ -6645,6 +6773,13 @@ ${ambient}` : ""}`,
     );
     process.exit(0);
   }
+  if ((result.initialSnapshot?.status === "loading" || result.initialSnapshot?.status === "retrying") && result.failures.length === 0) {
+    console.log(
+      `  ${import_picocolors12.default.yellow("\u2014")} Not ready yet ${import_picocolors12.default.dim(`\u2014 Ablo is loading existing rows. Re-run ${import_picocolors12.default.bold("ablo connect check")} shortly.`)}
+`
+    );
+    process.exit(1);
+  }
   const count = result.failures.length;
   console.log(
     `  ${import_picocolors12.default.red(`${count} item${count === 1 ? "" : "s"} to fix`)} ${import_picocolors12.default.dim(`\u2014 apply the fixes above, then re-run ${import_picocolors12.default.bold("ablo connect check")}.`)}
@@ -6672,11 +6807,11 @@ ${ambient}` : ""}`,
   );
   console.log(`  ${import_picocolors12.default.bold("Replication role")}
 `);
-  const replication = await probeAndReport(dbUrl, "replication");
+  const replication = await probeAndReport(dbUrl, "replication", { schema: args.schema });
   console.log(`
   ${import_picocolors12.default.bold("Direct-write role")}
 `);
-  const write = await probeAndReport(writeDbUrl, "write");
+  const write = await probeAndReport(writeDbUrl, "write", { schema: args.schema });
   const noDial = [
     replication.kind === "no-dial" ? `replication: ${replication.reason}` : null,
     write.kind === "no-dial" ? `write: ${write.reason}` : null
@@ -6704,17 +6839,35 @@ ${ambient}` : ""}`,
     apiKey,
     replicationUrl: dbUrl,
     writeUrl: writeDbUrl,
-    route: args.route
+    route: args.route,
+    schema: args.schema
   });
   process.exit(registered ? 0 : 1);
 }
-async function runScan() {
+async function runScan(args) {
   const dbUrl = requireScopedUrl("replication", "scan");
   const sql = src_default(dbUrl, { max: 1, prepare: false, onnotice: () => {
   } });
   let artifacts;
   try {
-    artifacts = await auditTenantSyncInfra(sql);
+    const apiKey = resolveRuntimeApiKey().key;
+    const target = apiKey ? await resolveTarget({ url: apiBaseUrl(), apiKey, keySource: "env" }).catch(() => null) : null;
+    const confirmed = target?.confirmed;
+    const names = confirmed?.branchId ? (0, import_footprint3.footprintNamesFor)({
+      organizationId: confirmed.organizationId,
+      branchId: confirmed.branchId,
+      ...confirmed.projectId ? { projectId: confirmed.projectId } : {}
+    }) : void 0;
+    const isolated = await auditTenantSyncInfra(sql, {
+      schema: args.schema,
+      ...names ? { names } : {}
+    });
+    const legacy = names ? await auditTenantSyncInfra(sql, { schema: args.schema }) : [];
+    artifacts = [...isolated, ...legacy].filter(
+      (artifact, index, all) => all.findIndex(
+        (candidate) => candidate.kind === artifact.kind && candidate.name === artifact.name
+      ) === index
+    );
   } catch (err) {
     const pg = err ?? {};
     await sql.end({ timeout: 2 });
@@ -6795,12 +6948,20 @@ ${ambient}` : ""}`,
     path: "/v1/datasources/locate",
     method: "POST",
     apiKey,
-    body: { connectionString: url },
+    body: { connectionString: url, schema: args.schema },
     responseSchema: import_wire7.datasourceLocationResponseSchema
   });
+  if (answer.available === false && !answer.held) {
+    console.log(
+      `  ${import_picocolors12.default.yellow("!")} ${import_picocolors12.default.bold(label)} schema ${import_picocolors12.default.bold(args.schema)} is connected to another organization.
+` + import_picocolors12.default.dim(`    Its project and branch are private. Use another schema or provider database URL.
+`)
+    );
+    return;
+  }
   if (!answer.held) {
     console.log(
-      `  ${import_picocolors12.default.green("\u2713")} No plane holds ${import_picocolors12.default.bold(label)} \u2014 ${import_picocolors12.default.bold("ablo connect apply")} can register it here.
+      `  ${import_picocolors12.default.green("\u2713")} No plane holds ${import_picocolors12.default.bold(`${label}/${args.schema}`)} \u2014 ${import_picocolors12.default.bold("ablo connect apply")} can register it here.
 `
     );
     return;
@@ -6811,13 +6972,50 @@ ${ambient}` : ""}`,
   );
   console.log(
     import_picocolors12.default.dim(
-      `    Ablo streams a database from one plane at a time. To move it, disconnect it there
+      `    Ablo binds one plane to each database schema. To move this schema, disconnect it there
     first \u2014 run `
     ) + import_picocolors12.default.cyan("ablo connect deregister") + import_picocolors12.default.dim(` with a key for that plane, then connect here.
 `) + import_picocolors12.default.dim(`    Confirm a candidate key first with `) + import_picocolors12.default.bold("ablo whoami --key-env <NAME>") + import_picocolors12.default.dim(`.
 `) + import_picocolors12.default.dim(`    Match the project id to a name with `) + import_picocolors12.default.bold("ablo projects list --json") + import_picocolors12.default.dim(".") + "\n"
   );
 }
+async function runResnapshot() {
+  const apiKey = resolveMutationApiKey();
+  if (!apiKey) {
+    throw new import_errors10.AbloAuthenticationError(
+      "No branch-bound secret key found. Set ABLO_API_KEY to the sk_ key for the branch to resnapshot.",
+      { code: "cli_api_key_missing" }
+    );
+  }
+  console.log(
+    `
+  ${brand("ablo")} ${import_picocolors12.default.dim("connect resnapshot")}  ${import_picocolors12.default.dim("reload existing rows")}
+`
+  );
+  const result = await requestControlPlane({
+    path: "/v1/datasources/resnapshot",
+    method: "POST",
+    apiKey,
+    body: {},
+    responseSchema: import_wire7.datasourceResnapshotResponseSchema
+  });
+  if (result.replication_slot?.released === false) {
+    console.log(`  ${import_picocolors12.default.yellow("\u2014")} Snapshot reset recorded, but the old slot is still active.`);
+    if (result.replication_slot.detail) console.log(`  ${import_picocolors12.default.dim(result.replication_slot.detail)}`);
+    if (result.replication_slot.remove_with) {
+      console.log(`  ${import_picocolors12.default.dim("Remove it with:")} ${import_picocolors12.default.bold(result.replication_slot.remove_with)}`);
+    }
+    console.log(`
+  Re-run ${import_picocolors12.default.bold("ablo connect resnapshot")} after releasing it.
+`);
+    process.exit(1);
+  }
+  console.log(
+    `  ${import_picocolors12.default.green("\u2713")} Fresh snapshot requested. The DataSource and credentials were kept.
+  ${import_picocolors12.default.dim(`Run ${import_picocolors12.default.bold("ablo connect check")} until the existing-row load is complete.`)}
+`
+  );
+}
 async function connect(argv) {
   if (argv[0] === "deregister") {
     const { disconnect: disconnect2 } = await Promise.resolve().then(() => (init_disconnect(), disconnect_exports));
@@ -6844,12 +7042,16 @@ async function connect(argv) {
     await runCheck();
     return;
   }
+  if (args.resnapshot) {
+    await runResnapshot();
+    return;
+  }
   if (args.register) {
     await runRegister(args);
     return;
   }
   if (args.scan) {
-    await runScan();
+    await runScan(args);
     return;
   }
   if (args.locate) {
@@ -6865,7 +7067,7 @@ async function connect(argv) {
   }
   printConnectRecipe(args);
 }
-var import_errors10, import_picocolors12, import_footprint2, import_wire7, FOOTPRINT_LOOKUP, CONNECT_USAGE;
+var import_errors10, import_picocolors12, import_footprint3, import_wire7, FOOTPRINT_LOOKUP, CONNECT_USAGE;
 var init_connect = __esm({
   "src/connect.ts"() {
     "use strict";
@@ -6873,12 +7075,13 @@ var init_connect = __esm({
     import_errors10 = require("@abloatai/transaction/errors");
     import_picocolors12 = __toESM(require_picocolors(), 1);
     init_src();
-    import_footprint2 = require("@abloatai/transaction/footprint");
+    import_footprint3 = require("@abloatai/transaction/footprint");
     init_dbRole();
     init_config();
     init_controlPlane();
     import_wire7 = require("@abloatai/transaction/wire");
     init_theme();
+    init_target();
     init_remoteValidation();
     init_connectSetup();
     FOOTPRINT_LOOKUP = {
@@ -6900,6 +7103,7 @@ var init_connect = __esm({
     npx ablo connect deregister           Disconnect this project's database \u2014 Ablo stops reading and writing it
     npx ablo connect check                Confirm the connected database is ready, from Ablo's side (needs only ABLO_API_KEY)
     npx ablo connect rotate               New passwords for both logins, then re-register
+    npx ablo connect resnapshot           Recreate only the slot and reload existing rows
     npx ablo connect scan                 List anything Ablo ever set up in your database (read-only, never drops)
     npx ablo connect locate               See which plane holds this database (read-only; nothing is changed)
 
@@ -6914,6 +7118,7 @@ var init_connect = __esm({
     --url <admin-conn>   Admin connection used once to set up (else DATABASE_URL); never stored
     --env-file <path>    Explicitly load DATABASE_URL and ABLO_API_KEY from this file
     --tables a,b,c       Publish only these tables (default: all tables)
+    --schema <name>      Bind this project to one database schema (default: public)
     --role <name>        Name the replication role (default: ablo_replicator)
     --write-role <name>  Name the DML role (default: ablo_writer)
     --route <route>      public-allowlist | privatelink | peering | vpn
@@ -283598,13 +283803,21 @@ function classifyKey(apiKey) {
     reason: `${import_picocolors15.default.bold("ABLO_API_KEY")} is not a secret Ablo key. Expected a branch-bound ${import_picocolors15.default.bold("sk_\u2026")} credential. Run ${import_picocolors15.default.bold("npx ablo dev")} to prepare a development branch.`
   };
 }
-function wireEnvLocal(apiKey, cwd = process.cwd()) {
+function wireEnvLocal(apiKey, cwd = process.cwd(), projectId, branchId) {
   const envPath = (0, import_path5.resolve)(cwd, ".env.local");
   const line = `ABLO_API_KEY=${apiKey}`;
+  const projectLine = projectId ? `ABLO_PROJECT_ID=${projectId}` : null;
+  const branchLine = branchId ? `ABLO_BRANCH_ID=${branchId}` : null;
   let action;
   if (!(0, import_fs7.existsSync)(envPath)) {
-    (0, import_fs7.writeFileSync)(envPath, `${line}
-`, { mode: 384 });
+    (0, import_fs7.writeFileSync)(
+      envPath,
+      `${line}
+${projectLine ? `${projectLine}
+` : ""}${branchLine ? `${branchLine}
+` : ""}`,
+      { mode: 384 }
+    );
     action = `Created ${import_picocolors15.default.bold(".env.local")} with ${import_picocolors15.default.bold("ABLO_API_KEY")}`;
   } else {
     const content = (0, import_fs7.readFileSync)(envPath, "utf8");
@@ -283620,6 +283833,24 @@ function wireEnvLocal(apiKey, cwd = process.cwd()) {
       (0, import_fs7.writeFileSync)(envPath, content.replace(/^ABLO_API_KEY=.*$/m, line));
       action = `Updated ${import_picocolors15.default.bold("ABLO_API_KEY")} in ${import_picocolors15.default.bold(".env.local")} ${import_picocolors15.default.dim(`(was ${existing.slice(0, 12)}\u2026)`)}`;
     }
+    if (projectLine) {
+      const next = (0, import_fs7.readFileSync)(envPath, "utf8");
+      if (/^ABLO_PROJECT_ID=.*$/m.test(next)) {
+        (0, import_fs7.writeFileSync)(envPath, next.replace(/^ABLO_PROJECT_ID=.*$/m, projectLine));
+      } else {
+        (0, import_fs7.appendFileSync)(envPath, `${next.endsWith("\n") || next.length === 0 ? "" : "\n"}${projectLine}
+`);
+      }
+    }
+    if (branchLine) {
+      const next = (0, import_fs7.readFileSync)(envPath, "utf8");
+      if (/^ABLO_BRANCH_ID=.*$/m.test(next)) {
+        (0, import_fs7.writeFileSync)(envPath, next.replace(/^ABLO_BRANCH_ID=.*$/m, branchLine));
+      } else {
+        (0, import_fs7.appendFileSync)(envPath, `${next.endsWith("\n") || next.length === 0 ? "" : "\n"}${branchLine}
+`);
+      }
+    }
   }
   const gitignorePath = (0, import_path5.resolve)(cwd, ".gitignore");
   const gitignore = (0, import_fs7.existsSync)(gitignorePath) ? (0, import_fs7.readFileSync)(gitignorePath, "utf8") : "";
@@ -283690,7 +283921,7 @@ async function runPush(schema, args) {
   }
   if (status2 === 403) {
     const serverSays = body.message ?? body.reason;
-    const hint = body.code === "database_role_cannot_enforce_rls" ? `Run ${import_picocolors15.default.bold("npx ablo migrate")} \u2014 it creates the scoped role for you (your DB credential never leaves this machine).` : `Schema authoring needs a branch-bound ${import_picocolors15.default.bold("sk_")} key with ${import_picocolors15.default.bold("schema:push")} \u2014 manage keys at ${import_picocolors15.default.cyan("https://abloatai.com")}.`;
+    const hint = schemaPushPlaneHint(body.code) ?? (body.code === "database_role_cannot_enforce_rls" ? `Run ${import_picocolors15.default.bold("npx ablo migrate")} \u2014 it creates the scoped role for you (your DB credential never leaves this machine).` : `Schema authoring needs a branch-bound ${import_picocolors15.default.bold("sk_")} key with ${import_picocolors15.default.bold("schema:push")} \u2014 manage keys at ${import_picocolors15.default.cyan("https://abloatai.com")}.`);
     return {
       ok: false,
       message: `${serverSays ?? "This key can't author schema (missing schema:push scope)."}
@@ -283750,8 +283981,10 @@ async function dev(argv, runtime = {}) {
   s.stop(first.message, first.ok ? 0 : 1);
   if (!first.ok) process.exit(1);
   if (runtime.branch) {
-    console.log(`
-  ${import_picocolors15.default.green("\u2713")} ${wireEnvLocal(args.apiKey)}`);
+    console.log(
+      `
+  ${import_picocolors15.default.green("\u2713")} ${wireEnvLocal(args.apiKey, process.cwd(), runtime.branch.projectId, runtime.branch.id)}`
+    );
     console.log(
       `  ${import_picocolors15.default.dim(`Temporary branch credential expires ${runtime.branch.expiresAt}; rerun ablo dev to rotate it.`)}`
     );
@@ -283926,6 +284159,7 @@ async function runBranchDev(argv, dependencies = {}) {
     apiKey: result.credential.api_key,
     branch: {
       id: result.branch.id,
+      projectId: result.branch.project_id,
       slug: result.branch.slug,
       expiresAt: result.credential.expires_at
     }
@@ -284200,6 +284434,7 @@ var COMMANDS = [
         { run: "connect", does: "Connect your database \u2014 shows the setup to run, or applies it for you" },
         { run: "connect apply", does: "Run that setup for you, from a one-time admin URL" },
         { run: "connect check", does: "Confirm your database is ready to share changes with Ablo" },
+        { run: "connect resnapshot", does: "Reload existing rows without deregistering or rotating credentials" },
         { run: "connect scan", does: "List anything Ablo ever set up in your database (read-only)" },
         { run: "connect locate", does: "See which plane holds a database before connecting it" },
         { run: "connect deregister", does: "Disconnect this project's database \u2014 Ablo stops reading and writing it" }
@@ -284738,7 +284973,9 @@ async function ping(apiUrl3) {
 }
 function formatConflict(conflict) {
   if (!conflict) return "";
-  const parts = import_schema8.participantKindSchema.options.flatMap((k3) => conflict[k3] ? [`${k3}:${conflict[k3]}`] : []);
+  const parts = import_schema8.participantKindSchema.options.flatMap(
+    (k3) => conflict[k3] ? [`${k3}:${conflict[k3]}`] : []
+  );
   return parts.length ? `{${parts.join(",")}}` : "";
 }
 function printTargetLines(target, localProject, storedOrganizationId, storedOrganizationSlug) {
@@ -284783,13 +285020,21 @@ async function status(args = []) {
   const cfg = readConfig();
   const mode = getMode();
   const runtimeKey = resolveRuntimeApiKey();
-  const target = runtimeKey.key ? await resolveTarget({ url: apiUrl3, apiKey: runtimeKey.key, keySource: runtimeKey.source ?? "stored" }) : null;
+  const target = runtimeKey.key ? await resolveTarget({
+    url: apiUrl3,
+    apiKey: runtimeKey.key,
+    keySource: runtimeKey.source ?? "stored"
+  }) : null;
   if (args.includes("--json")) {
     const entry = getKeyEntry(mode);
     const activeProject2 = getActiveProject();
     const pushed2 = await fetchPushedSchema(apiUrl3, runtimeKey.key);
     const reachableForJson = await ping(apiUrl3);
-    const dataSource2 = reachableForJson ? (await fetchRoutingState(apiUrl3, runtimeKey.key)).source : { kind: "unknown", detail: "unreachable" };
+    const routingForJson = reachableForJson ? await fetchRoutingState(apiUrl3, runtimeKey.key) : {
+      source: { kind: "unknown", detail: "unreachable" },
+      validation: null
+    };
+    const dataSource2 = routingForJson.source;
     const driftForJson = schemaDrift(await readLocalSchemaHash(), pushed2?.hash);
     const out = {
       // The locally-active project (`ablo projects use`); null = org-default.
@@ -284835,6 +285080,10 @@ async function status(args = []) {
       // form of the human verdict: a caller can gate on it in CI rather than
       // discovering the same facts from a failed request later.
       dataSource: dataSource2,
+      // Existing rows are copied into Ablo automatically after a direct source
+      // is connected. Agents can gate a read cutover on this field instead of
+      // probing for one row or inventing a row-touch backfill.
+      initialSnapshot: routingForJson.validation?.ok === true ? routingForJson.validation.initialSnapshot ?? null : null,
       drift: driftForJson,
       blockers: blockers({
         reachable: reachableForJson,
@@ -284868,7 +285117,9 @@ async function status(args = []) {
   );
   const management = getManagementKeyEntry();
   console.log(
-    `  ${import_picocolors19.default.dim("\u25CB")} ${"management".padEnd(12)}  ${management ? import_picocolors19.default.dim(`${management.apiKey.slice(0, 12)}\u2026${management.expiresAt ? ` \xB7 ${expiryLabel(management.expiresAt)}` : ""}`) : import_picocolors19.default.dim("\u2014 no key")}`
+    `  ${import_picocolors19.default.dim("\u25CB")} ${"management".padEnd(12)}  ${management ? import_picocolors19.default.dim(
+      `${management.apiKey.slice(0, 12)}\u2026${management.expiresAt ? ` \xB7 ${expiryLabel(management.expiresAt)}` : ""}`
+    ) : import_picocolors19.default.dim("\u2014 no key")}`
   );
   for (const { key: m2, label } of [
     { key: "sandbox", label: "legacy child" },
@@ -284901,7 +285152,9 @@ async function status(args = []) {
     const how = [...new Set(dataSource.connections)].join(" + ");
     const pooled = detectPoolerIn(dataSource.hosts);
     const unreachable = validation && !validation.ok ? validation.message : void 0;
-    console.log(`  ${import_picocolors19.default.dim("data")}    ${import_picocolors19.default.green("\u2713")} ${import_picocolors19.default.dim(`database connected to this plane (${how})`)}`);
+    console.log(
+      `  ${import_picocolors19.default.dim("data")}    ${import_picocolors19.default.green("\u2713")} ${import_picocolors19.default.dim(`database connected to this plane (${how})`)}`
+    );
     if (pooled) {
       console.log(
         `          ${import_picocolors19.default.yellow("\u26A0")} ${import_picocolors19.default.dim(
@@ -284912,12 +285165,27 @@ async function status(args = []) {
     if (unreachable) {
       console.log(`          ${import_picocolors19.default.red("\u2717")} ${import_picocolors19.default.dim(`Ablo could not reach it \u2014 ${unreachable}`)}`);
     }
+    if (validation?.ok && validation.initialSnapshot?.status === "loading") {
+      console.log(
+        `          ${import_picocolors19.default.yellow("\u25CC")} ${import_picocolors19.default.dim(
+          `loading rows that predate the connection \u2014 automatic; check with ${import_picocolors19.default.bold("ablo connect check")}`
+        )}`
+      );
+    } else if (validation?.ok && validation.initialSnapshot?.status === "retrying") {
+      console.log(
+        `          ${import_picocolors19.default.red("\u2717")} ${import_picocolors19.default.dim(
+          `loading existing rows is retrying${validation.initialSnapshot.detail ? ` \u2014 ${validation.initialSnapshot.detail}` : ""}`
+        )}`
+      );
+    }
   } else if (dataSource.kind === "none") {
     console.log(
       `  ${import_picocolors19.default.dim("data")}    ${import_picocolors19.default.red("\u2717 no database connected to this plane")} ${import_picocolors19.default.dim("\u2014 writes are held")}`
     );
   } else if (reachable) {
-    console.log(`  ${import_picocolors19.default.dim("data")}    ${import_picocolors19.default.yellow("?")} ${import_picocolors19.default.dim(`could not read the plane's databases (${dataSource.detail})`)}`);
+    console.log(
+      `  ${import_picocolors19.default.dim("data")}    ${import_picocolors19.default.yellow("?")} ${import_picocolors19.default.dim(`could not read the plane's databases (${dataSource.detail})`)}`
+    );
   }
   const pushed = reachable ? await fetchPushedSchema(apiUrl3, introspectKey) : null;
   if (reachable) {
@@ -284925,7 +285193,9 @@ async function status(args = []) {
       const when = pushed.pushedAt ? ` ${import_picocolors19.default.dim(`@ ${pushed.pushedAt.slice(0, 10)}`)}` : "";
       const ver = pushed.version != null ? ` ${import_picocolors19.default.dim(`(rev ${pushed.version})`)}` : "";
       const hashLabel = pushed.hash ? ` ${import_picocolors19.default.dim(`hash ${pushed.hash}`)}` : "";
-      console.log(`  ${import_picocolors19.default.dim("schema")}  ${import_picocolors19.default.bold(`${pushed.models.length} models pushed`)}${ver}${hashLabel}${when}`);
+      console.log(
+        `  ${import_picocolors19.default.dim("schema")}  ${import_picocolors19.default.bold(`${pushed.models.length} models pushed`)}${ver}${hashLabel}${when}`
+      );
       for (const m2 of pushed.models) {
         const tn = m2.typename === m2.key ? import_picocolors19.default.dim(`typename=${m2.typename}`) : import_picocolors19.default.yellow(`typename=${m2.typename}`);
         const conflict = formatConflict(m2.conflict);
@@ -284933,7 +285203,9 @@ async function status(args = []) {
         console.log(`          ${import_picocolors19.default.dim("\u2022")} ${m2.key.padEnd(14)} ${tn}${conflictStr2}`);
       }
     } else if (pushed && !pushed.active) {
-      console.log(`  ${import_picocolors19.default.dim("schema")}  ${import_picocolors19.default.yellow("none pushed")} ${import_picocolors19.default.dim(`(run ${import_picocolors19.default.bold("ablo push")} or ${import_picocolors19.default.bold("ablo dev")})`)}`);
+      console.log(
+        `  ${import_picocolors19.default.dim("schema")}  ${import_picocolors19.default.yellow("none pushed")} ${import_picocolors19.default.dim(`(run ${import_picocolors19.default.bold("ablo push")} or ${import_picocolors19.default.bold("ablo dev")})`)}`
+      );
     }
   }
   const drift = schemaDrift(await readLocalSchemaHash(), pushed?.hash);
@@ -284978,7 +285250,9 @@ init_target();
 init_readiness();
 function render(check2) {
   const mark = check2.state === "ok" ? import_picocolors20.default.green("\u2713") : check2.state === "fail" ? import_picocolors20.default.red("\u2717") : import_picocolors20.default.dim("\u2013");
-  console.log(`  ${mark} ${check2.label.padEnd(10)} ${check2.state === "fail" ? check2.detail : import_picocolors20.default.dim(check2.detail)}`);
+  console.log(
+    `  ${mark} ${check2.label.padEnd(10)} ${check2.state === "fail" ? check2.detail : import_picocolors20.default.dim(check2.detail)}`
+  );
   if (check2.fix) console.log(`    ${" ".repeat(11)}${import_picocolors20.default.dim(`\u2192 ${check2.fix}`)}`);
 }
 async function ping2(apiUrl3) {
@@ -285025,7 +285299,11 @@ async function doctor() {
       fix: "check your connection, then re-run `ablo doctor`"
     }
   );
-  const target = runtimeKey.key ? await resolveTarget({ url: apiUrl3, apiKey: runtimeKey.key, keySource: runtimeKey.source ?? "stored" }) : null;
+  const target = runtimeKey.key ? await resolveTarget({
+    url: apiUrl3,
+    apiKey: runtimeKey.key,
+    keySource: runtimeKey.source ?? "stored"
+  }) : null;
   const confirmed = target?.confirmed ?? null;
   if (confirmed) {
     const project = confirmed.project ? confirmed.project.isDefault ? "default" : confirmed.project.name === null ? `${confirmed.project.id} (unnamed \u2014 ${confirmed.project.unnamedReason ?? "the project list did not answer"})` : `${confirmed.project.slug} (${confirmed.project.id})` : "default";
@@ -285071,7 +285349,12 @@ async function doctor() {
       label: "schema",
       state: "ok",
       detail: `${pushed.models.length} models active${pushed.hash ? `, hash ${pushed.hash}` : ""}`
-    } : reachable && runtimeKey.key ? { label: "schema", state: "fail", detail: "none active for this key", fix: "run `ablo push`" } : { label: "schema", state: "skip", detail: "not determined" }
+    } : reachable && runtimeKey.key ? {
+      label: "schema",
+      state: "fail",
+      detail: "none active for this key",
+      fix: "run `ablo push`"
+    } : { label: "schema", state: "skip", detail: "not determined" }
   );
   const drift = schemaDrift(await readLocalSchemaHash(), pushed?.hash);
   if (drift) {
@@ -285084,7 +285367,21 @@ async function doctor() {
   }
   if (dataSource.kind === "connected" && validation) {
     checks.push(
-      validation.ok ? validation.ready ? { label: "database", state: "ok", detail: "reachable from Ablo, and ready to replicate" } : {
+      validation.ok ? validation.ready ? {
+        label: "database",
+        state: "ok",
+        detail: "reachable from Ablo, and ready to replicate"
+      } : validation.initialSnapshot?.status === "loading" && validation.failures.length === 0 ? {
+        label: "database",
+        state: "fail",
+        detail: "reachable; rows that predate the connection are still loading",
+        fix: "wait a moment and rerun `ablo doctor` \u2014 Ablo snapshots them automatically; do not update every row or write a manual backfill"
+      } : validation.initialSnapshot?.status === "retrying" && validation.failures.length === 0 ? {
+        label: "database",
+        state: "fail",
+        detail: `the initial row load is retrying${validation.initialSnapshot.detail ? ` \u2014 ${validation.initialSnapshot.detail}` : ""}`,
+        fix: "fix the reported connection or database issue, then rerun `ablo doctor`; no row-touch backfill is needed"
+      } : {
         label: "database",
         state: "fail",
         detail: `reachable, but not ready (${validation.failures.length} check${validation.failures.length === 1 ? "" : "s"} failing)`,
@@ -285114,7 +285411,9 @@ async function doctor() {
     console.log(
       `  ${import_picocolors20.default.red("\u2717")} ${import_picocolors20.default.bold(`${failed} problem${failed === 1 ? "" : "s"}`)}` + import_picocolors20.default.dim(skipped > 0 ? `, ${skipped} check${skipped === 1 ? "" : "s"} skipped` : "")
     );
-    console.log(import_picocolors20.default.dim("    Fix them in the order above \u2014 an earlier one often explains a later one."));
+    console.log(
+      import_picocolors20.default.dim("    Fix them in the order above \u2014 an earlier one often explains a later one.")
+    );
   } else if (skipped > 0) {
     console.log(
       `  ${import_picocolors20.default.yellow("?")} ${import_picocolors20.default.dim(`nothing is blocking a write, but ${skipped} check${skipped === 1 ? "" : "s"} could not be run`)}`
@@ -287047,6 +287346,8 @@ import { schema } from './schema';
 // via the session route and never touches the key.
 export const sync = Ablo({
   apiKey: process.env.ABLO_API_KEY,${authLine}
+  projectId: process.env.ABLO_PROJECT_ID,
+  branchId: process.env.ABLO_BRANCH_ID,
   schema,
 });
 
@@ -287072,7 +287373,7 @@ function generateEnv(storage, opts = {}) {
   const { includeApiKey = true } = opts;
   const databaseBlock = storage === "replication" ? "# Used by `npx ablo connect` to set up + register logical replication \u2014 the\n# DIRECT (un-pooled) endpoint. Ablo TAILS your WAL from here; it never writes.\n# The client never sees it; the browser never sees it. Your DB stays yours.\nDATABASE_URL=postgres://user:password@host:5432/db\n" : "# Used by ablo/data-source.ts (your DB endpoint) + `ablo migrate` \u2014 NOT the client.\n# Ablo never sees it; the browser never sees it. Your DB stays in your app.\nDATABASE_URL=postgres://user:password@host:5432/db\n";
   const webhookBlock = storage === "endpoint" ? "# Signing secret for the webhook receiver (app/api/ablo/webhooks/route.ts).\n# Ablo mints this when you register the endpoint's URL (POST /v1/webhook_endpoints\n# or the dashboard) and returns it once \u2014 paste it here.\nABLO_WEBHOOK_SECRET=whsec_your_endpoint_secret_here\n" : "";
-  const apiKeyBlock = includeApiKey ? "# Ablo: a branch-bound sk_ key (`npx ablo dev` wires a development branch for you)\nABLO_API_KEY=sk_your_key_here\n" : "";
+  const apiKeyBlock = includeApiKey ? "# Ablo: a branch-bound sk_ key (`npx ablo dev` wires both values for you).\n# Project + branch are assertions: the SDK rejects a key for another app or environment.\nABLO_API_KEY=sk_your_key_here\nABLO_PROJECT_ID=proj_your_project_id\nABLO_BRANCH_ID=br_your_branch_id\n" : "";
   return `${apiKeyBlock}${webhookBlock}${databaseBlock}`;
 }
 function generateDataSource(orm) {
@@ -287233,8 +287534,7 @@ export async function POST(req: Request): Promise<Response> {
 `;
 }
 function generateAgent() {
-  return `import Ablo from '@abloatai/ablo';
-import { schema } from './schema';
+  return `import { sync as ablo } from './sync';
 
 /**
  * An AI "teammate" that works the same synced tasks a human does.
@@ -287244,8 +287544,6 @@ import { schema } from './schema';
  * \`npx ablo logs\`. That's the whole idea: agents and people on one typed,
  * synced dataset.
  */
-const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
-
 async function main() {
   await ablo.ready();
 
@@ -287263,7 +287561,6 @@ async function main() {
     data: { priority: 10 },
     readAt: snap.stamp,
     onStale: 'reject',
-    wait: 'confirmed',
   });
   console.log('prioritized:', urgent.title);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/cli",
-  "version": "0.45.0",
+  "version": "0.47.0",
   "description": "The ablo command line: set up Ablo, connect your database, and push your schema from the terminal.",
   "license": "Apache-2.0",
   "type": "module",
@@ -30,10 +30,10 @@
     "directory": "packages/cli"
   },
   "dependencies": {
-    "@abloatai/transaction": "^0.45.0",
+    "@abloatai/transaction": "^0.47.0",
     "jiti": "^2.7.0",
     "zod": "^4.4.3",
-    "@abloatai/humans": "^0.45.0"
+    "@abloatai/humans": "^0.47.0"
   },
   "devDependencies": {
     "@clack/prompts": "^0.11.0",