reffy-cli 1.4.1 → 1.5.0

package/README.md

@@ -65,42 +65,20 @@ reffy diagram render --input .reffy/reffyspec/specs/auth/spec.md --format ascii
 reffy diagram render --input .reffy/reffyspec/specs/auth/spec.md --format svg --output .reffy/artifacts/auth-spec.svg
 ```
 
-## Remote Backend Helper
-
-Reffy includes a Paseo helper bridge at `scripts/reffy-remote-backend-demo.mjs`.
-
-The helper:
-
-- loads `.env` automatically when present
-- reads `project_id` and `workspace_name` from `.reffy/manifest.json`
-- provisions or links a Paseo `reffyRemoteBackend` actor
-- imports the local `.reffy/` workspace
-
-Expected environment variables:
-
-- `PASEO_ENDPOINT` - required unless already exported in the shell
-- `PASEO_POD_NAME` - optional existing pod override
-- `PASEO_ACTOR_ID` - optional existing actor override
-
-Examples:
-
-```bash
-npm run remote:backend:demo
-reffy remote init --provision
-reffy remote push
-```
-
 ## Remote Sync
 
 Reffy can publish the local `.reffy/` workspace to a Paseo-backed remote actor and inspect it later with native CLI commands.
 
 The current remote flow is:
 
-1. Reffy reads `project_id` and `workspace_name` from `.reffy/manifest.json`.
-2. Reffy connects to Paseo using `PASEO_ENDPOINT` or `--endpoint`.
-3. `reffy remote init --provision` creates a pod and actor when needed, then writes local linkage state to `.reffy/state/remote.json`.
-4. `reffy remote push` publishes the local workspace to that linked actor with `replace_missing=true` by default, so remote reflects local.
-5. `reffy remote status|ls|cat` inspects the linked remote workspace using the saved linkage state unless you override it.
+1. Reffy reads `project_id` and `workspace_ids` from `.reffy/manifest.json`.
+2. You select one workspace projection to act on. Reffy infers the selection when `workspace_ids` has exactly one entry; otherwise pass `--workspace-id <id>`.
+3. Reffy connects to Paseo using `PASEO_ENDPOINT` or `--endpoint`.
+4. `reffy remote init --provision` creates a pod and a `reffyRemoteBackend.v2` actor for the selected workspace id when needed, then writes local linkage state to `.reffy/state/remote.json`.
+5. `reffy remote push` publishes the full local `.reffy/` tree to the selected projection through `/workspaces/{workspace_id}/...` with `replace_missing=true` by default, scoped to that workspace id.
+6. `reffy remote status|ls|cat` inspects the selected workspace projection using the saved linkage state unless you override it.
+
+One backend actor can serve multiple workspace projections for the same source `project_id`: Reffy stores one target per `workspace_id` in `.reffy/state/remote.json`, and the backend isolates documents and locks by `(workspace_id, path)`.
 
 ### Minimal connection requirement
 
@@ -124,8 +102,9 @@ Optional overrides:
 
 - `PASEO_POD_NAME` if you want to reuse an existing Paseo pod
 - `PASEO_ACTOR_ID` if you want to reuse an existing backend actor
+- `--workspace-id <id>` (or `PASEO_WORKSPACE_ID` for the helper script) when the manifest lists more than one `workspace_ids`
 
-Reffy does not require separate `REFFY_PROJECT_ID` or `REFFY_WORKSPACE_NAME` values for the normal case because those come from `.reffy/manifest.json`.
+Reffy does not require separate `REFFY_PROJECT_ID` values for the normal case because source identity comes from `.reffy/manifest.json`.
 
 ### Saved remote linkage
 
@@ -133,11 +112,21 @@ After `reffy remote init`, Reffy stores the local pointer to the linked backend
 
 - `.reffy/state/remote.json`
 
-That file contains the connection tuple Reffy uses to reach the backend:
+That file maps each selected `workspace_id` to the backend target Reffy should use for that projection:
 
-- `endpoint`
-- `pod_name`
-- `actor_id`
+```json
+{
+  "version": 2,
+  "provider": "paseo",
+  "endpoint": "https://paseo.example",
+  "targets": {
+    "my-project": { "pod_name": "...", "actor_id": "...", "last_imported_at": "..." },
+    "portfolio-alpha": { "pod_name": "...", "actor_id": "..." }
+  }
+}
+```
+
+Multiple targets can share the same `pod_name` and `actor_id` — the backend addresses each projection separately through `/workspaces/{workspace_id}/...`.
 
 This file is local runtime state. It is not part of the synced remote workspace and is intentionally excluded from `reffy remote push`.
 
@@ -156,9 +145,9 @@ reffy remote cat .reffy/manifest.json
 
 `reffy remote status` is the primary diagnostic command for this flow. It reports:
 
-- the saved linkage being used
-- the local manifest identity
-- the remote workspace identity
+- the saved linkage being used for the selected workspace id
+- the local manifest identity (source `project_id` and selected `workspace_id`)
+- the remote identity returned from v2 (`source.actor_type`, `source.version`, `source.project_id`, `workspace.workspace_id`)
 - remote document counts when reachable
 
 `reffy remote push` reports:
@@ -173,7 +162,7 @@ That makes the default prune/import behavior auditable without dropping to direc
 
 ## Manifest Contract
 
-Reffy keeps workspace metadata in `.reffy/manifest.json`. New managed manifests include both core timestamps and workspace identity:
+Reffy keeps workspace metadata in `.reffy/manifest.json`. New managed manifests separate stable source identity (`project_id`) from plural workspace membership (`workspace_ids`):
 
 ```json
 {
@@ -181,12 +170,21 @@ Reffy keeps workspace metadata in `.reffy/manifest.json`. New managed manifests
   "created_at": "2026-04-18T00:00:00.000Z",
   "updated_at": "2026-04-18T00:00:00.000Z",
   "project_id": "my-project",
-  "workspace_name": "my-project",
+  "workspace_ids": ["my-project"],
   "artifacts": []
 }
 ```
 
-Older v1 manifests without `project_id` and `workspace_name` still validate. Running `reffy init` migrates managed manifests by adding those fields with deterministic defaults derived from the repository name.
+A single `.reffy/` tree can belong to more than one planning workspace:
+
+```json
+{
+  "project_id": "my-project",
+  "workspace_ids": ["my-project", "portfolio-alpha", "nuveris-cross-project-planning"]
+}
+```
+
+Running `reffy init` populates `project_id` and `workspace_ids` with deterministic defaults derived from the repository name for any managed manifest that is missing them.
 
 ## Using Reffy With ReffySpec
 

package/dist/cli.js

@@ -5,11 +5,12 @@ import path from "node:path";
 import { renderDiagram } from "./diagram.js";
 import { runDoctor } from "./doctor.js";
 import { loadDotEnvIfPresent } from "./env.js";
+import { ensureGitignoreEntries } from "./gitignore.js";
 import { archivePlanningChange } from "./plan-archive.js";
 import { createPlanScaffold } from "./plan.js";
 import { DEFAULT_PLANNING_RELATIVE_DIR, looksLikePlanningDir, resolveCanonicalPlanningPath } from "./planning-paths.js";
 import { listPlanningChanges, showPlanningChange, validatePlanningChange } from "./plan-runtime.js";
-import { assertRemoteIdentity, collectWorkspaceDocuments, describeRemoteLinkage, ensureRemoteInit, extractWorkspaceIdentity, mergeRemoteConfig, PaseoRemoteClient, readRemoteConfig, requireWorkspaceIdentity, resolveRemoteConfigPath, updateRemoteConfigMetadata, validateImportResult, } from "./remote.js";
+import { assertRemoteIdentity, collectWorkspaceDocuments, describeRemoteLinkage, ensureRemoteInit, extractWorkspaceIdentity, PaseoRemoteClient, readRemoteConfig, requireWorkspaceIdentity, resolveRemoteConfigPath, resolveRemoteTarget, resolveSelectedWorkspaceId, updateRemoteConfigMetadata, validateImportResult, } from "./remote.js";
 import { DEFAULT_REFS_DIRNAME, detectWorkspaceState, looksLikeRefsDir } from "./refs-paths.js";
 import { prepareCanonicalPlanningLayout } from "./planning-workspace.js";
 import { ReferencesStore } from "./storage.js";
@@ -484,16 +485,17 @@ function planUsage() {
 function remoteUsage() {
     return [
         "Usage:",
-        "  reffy remote init [--repo PATH] [--output text|json] [--endpoint URL] [--pod-name NAME] [--actor-id ID] [--provision] [--env-file PATH]",
-        "  reffy remote status [--repo PATH] [--output text|json] [--endpoint URL] [--pod-name NAME] [--actor-id ID] [--env-file PATH]",
-        "  reffy remote push [--repo PATH] [--output text|json] [--endpoint URL] [--pod-name NAME] [--actor-id ID] [--env-file PATH]",
-        "  reffy remote ls [--repo PATH] [--output text|json] [--prefix PATH] [--endpoint URL] [--pod-name NAME] [--actor-id ID] [--env-file PATH]",
-        "  reffy remote cat <path> [--repo PATH] [--output text|json] [--endpoint URL] [--pod-name NAME] [--actor-id ID] [--env-file PATH]",
+        "  reffy remote init [--repo PATH] [--output text|json] [--workspace-id ID] [--endpoint URL] [--pod-name NAME] [--actor-id ID] [--provision] [--env-file PATH]",
+        "  reffy remote status [--repo PATH] [--output text|json] [--workspace-id ID] [--endpoint URL] [--pod-name NAME] [--actor-id ID] [--env-file PATH]",
+        "  reffy remote push [--repo PATH] [--output text|json] [--workspace-id ID] [--endpoint URL] [--pod-name NAME] [--actor-id ID] [--env-file PATH]",
+        "  reffy remote ls [--repo PATH] [--output text|json] [--workspace-id ID] [--prefix PATH] [--endpoint URL] [--pod-name NAME] [--actor-id ID] [--env-file PATH]",
+        "  reffy remote cat <path> [--repo PATH] [--output text|json] [--workspace-id ID] [--endpoint URL] [--pod-name NAME] [--actor-id ID] [--env-file PATH]",
         "",
         "Options:",
+        "  --workspace-id ID Selected workspace projection. Required when the manifest has multiple workspace_ids; otherwise inferred.",
         "  --endpoint URL    Paseo base URL. Defaults to saved config or PASEO_ENDPOINT/.env.",
-        "  --pod-name NAME   Paseo pod name. Defaults to saved config or PASEO_POD_NAME/.env.",
-        "  --actor-id ID     Paseo actor id. Defaults to saved config or PASEO_ACTOR_ID/.env.",
+        "  --pod-name NAME   Paseo pod name. Defaults to saved target for the selected workspace id or PASEO_POD_NAME/.env.",
+        "  --actor-id ID     Paseo actor id. Defaults to saved target for the selected workspace id or PASEO_ACTOR_ID/.env.",
         "  --provision       Create missing pod/actor during `remote init`.",
         "  --prefix PATH     Prefix filter for `remote ls`.",
         "  --env-file PATH   Dotenv file to load before resolving env-backed options. Defaults to .env.",
@@ -757,6 +759,18 @@ function parseRemoteArgs(argv) {
             args.prefix = arg.split("=", 2)[1];
             continue;
         }
+        if (arg === "--workspace-id") {
+            const value = argv[i + 1];
+            if (!value)
+                throw new Error("--workspace-id requires a value");
+            args.workspaceId = value;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--workspace-id=")) {
+            args.workspaceId = arg.split("=", 2)[1];
+            continue;
+        }
         if (arg === "--provision") {
             args.provision = true;
             continue;
@@ -777,7 +791,8 @@ function getRemotePositionalArgs(argv) {
             arg === "--pod-name" ||
             arg === "--actor-id" ||
             arg === "--env-file" ||
-            arg === "--prefix") {
+            arg === "--prefix" ||
+            arg === "--workspace-id") {
             i += 1;
             continue;
         }
@@ -788,6 +803,7 @@ function getRemotePositionalArgs(argv) {
             arg.startsWith("--actor-id=") ||
             arg.startsWith("--env-file=") ||
             arg.startsWith("--prefix=") ||
+            arg.startsWith("--workspace-id=") ||
             arg === "--json" ||
             arg === "--provision") {
             continue;
@@ -808,30 +824,48 @@ function printSection(title, values) {
         console.log(`- ${value}`);
     }
 }
-async function resolveRemoteContext(args) {
+async function resolveRemoteContext(args, opts = {}) {
     await loadDotEnvIfPresent(args.repoRoot, args.envFile ?? ".env");
     const store = new ReferencesStore(args.repoRoot);
-    const identity = requireWorkspaceIdentity(await store.getWorkspaceIdentity());
-    const savedConfig = await readRemoteConfig(args.repoRoot);
+    const identityInfo = await store.getWorkspaceIdentity();
+    const workspaceId = resolveSelectedWorkspaceId(identityInfo, args.workspaceId);
+    const identity = requireWorkspaceIdentity(identityInfo, workspaceId);
+    let savedConfig = null;
+    let replacedLegacy = false;
+    try {
+        savedConfig = await readRemoteConfig(args.repoRoot);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (opts.tolerateLegacyV1Config && message.includes("legacy v1 single-target shape")) {
+            replacedLegacy = true;
+        }
+        else {
+            throw error;
+        }
+    }
     const overrideValues = {
         endpoint: args.endpoint ?? process.env.PASEO_ENDPOINT,
         pod_name: args.podName ?? process.env.PASEO_POD_NAME,
         actor_id: args.actorId ?? process.env.PASEO_ACTOR_ID,
     };
-    const mergedConfig = mergeRemoteConfig(savedConfig, overrideValues);
+    const resolvedTarget = resolveRemoteTarget(savedConfig, workspaceId, overrideValues);
     const hasOverrides = Boolean(overrideValues.endpoint || overrideValues.pod_name || overrideValues.actor_id);
-    const linkageSource = mergedConfig
-        ? savedConfig && !hasOverrides
+    const savedHasTarget = Boolean(savedConfig?.targets?.[workspaceId]);
+    const linkageSource = resolvedTarget
+        ? savedHasTarget && !hasOverrides
             ? "saved_config"
             : "cli_or_env_overrides"
         : "unconfigured";
     return {
         store,
         identity,
+        workspaceId,
         configPath: resolveRemoteConfigPath(args.repoRoot),
         savedConfig,
-        mergedConfig,
+        resolvedTarget,
         linkageSource,
+        replacedLegacy,
     };
 }
 async function main() {
@@ -893,8 +927,8 @@ async function main() {
         const parsed = parseRemoteArgs(remoteArgs);
         try {
             if (subcommand === "init") {
-                const { identity, configPath } = await resolveRemoteContext(parsed);
-                const endpoint = parsed.endpoint ?? process.env.PASEO_ENDPOINT;
+                const { identity, workspaceId, configPath, savedConfig, replacedLegacy } = await resolveRemoteContext(parsed, { tolerateLegacyV1Config: true });
+                const endpoint = parsed.endpoint ?? process.env.PASEO_ENDPOINT ?? savedConfig?.endpoint;
                 if (!endpoint) {
                     throw new Error("Remote init requires --endpoint or PASEO_ENDPOINT (optionally loaded from .env)");
                 }
@@ -904,7 +938,9 @@ async function main() {
                     actorId: parsed.actorId ?? process.env.PASEO_ACTOR_ID,
                     provision: parsed.provision,
                     identity,
+                    existingConfig: savedConfig,
                 });
+                const gitignore = await ensureGitignoreEntries(parsed.repoRoot, [".reffy/state/"]);
                 const payload = {
                     status: "ok",
                     command: "remote",
@@ -912,44 +948,61 @@ async function main() {
                     provider: result.config.provider,
                     config_path: configPath,
                     endpoint: result.config.endpoint,
-                    pod_name: result.config.pod_name,
-                    actor_id: result.config.actor_id,
+                    workspace_id: workspaceId,
+                    pod_name: result.target.pod_name,
+                    actor_id: result.target.actor_id,
                     created_pod: result.created_pod,
                     created_actor: result.created_actor,
                     project_id: identity.project_id,
-                    workspace_name: identity.workspace_name,
                     linkage_mode: result.created_pod || result.created_actor ? "provisioned" : "existing",
+                    configured_workspace_ids: Object.keys(result.config.targets).sort(),
+                    replaced_legacy_v1_config: replacedLegacy,
+                    gitignore_path: gitignore.path,
+                    gitignore_added: gitignore.added,
                 };
                 if (output === "json") {
                     printResult(output, payload);
                 }
                 else {
+                    if (replacedLegacy) {
+                        console.log("Replacing legacy v1 remote linkage with v2 target map");
+                    }
                     console.log("Remote linkage ready");
                     console.log(`Config: ${payload.config_path}`);
                     console.log(`Endpoint: ${payload.endpoint}`);
+                    console.log(`Workspace id: ${payload.workspace_id}`);
                     console.log(`Pod: ${payload.pod_name}`);
                     console.log(`Actor: ${payload.actor_id}`);
                     console.log(`Project identity: ${payload.project_id}`);
-                    console.log(`Workspace name: ${payload.workspace_name}`);
                     console.log(`Created pod: ${payload.created_pod ? "yes" : "no"}`);
                     console.log(`Created actor: ${payload.created_actor ? "yes" : "no"}`);
                     console.log(`Linkage mode: ${payload.linkage_mode}`);
+                    console.log(`Configured workspace ids: ${payload.configured_workspace_ids.join(", ")}`);
+                    if (payload.gitignore_added.length > 0) {
+                        console.log(`Updated .gitignore: ${payload.gitignore_added.join(", ")}`);
+                    }
                 }
                 return 0;
             }
             const context = await resolveRemoteContext(parsed);
-            if (!context.mergedConfig) {
-                throw new Error(`Remote linkage is not configured. Run \`reffy remote init\` or provide endpoint, pod name, and actor id. Expected config path: ${context.configPath}`);
+            if (!context.resolvedTarget) {
+                throw new Error(`Remote linkage is not configured for workspace_id "${context.workspaceId}". Run \`reffy remote init --workspace-id ${context.workspaceId}\` or provide endpoint, pod name, and actor id. Expected config path: ${context.configPath}`);
             }
-            const client = new PaseoRemoteClient(context.mergedConfig);
+            const client = new PaseoRemoteClient(context.resolvedTarget);
+            const linkageLabel = describeRemoteLinkage({
+                endpoint: context.resolvedTarget.endpoint,
+                pod_name: context.resolvedTarget.pod_name,
+                actor_id: context.resolvedTarget.actor_id,
+                workspace_id: context.workspaceId,
+            });
             if (subcommand === "status") {
                 let workspace;
                 try {
-                    workspace = await client.getWorkspace();
+                    workspace = await client.getWorkspace(context.workspaceId);
                 }
                 catch (error) {
                     const message = error instanceof Error ? error.message : String(error);
-                    throw new Error(`Remote status failed using ${describeRemoteLinkage(context.mergedConfig)}: ${message}`);
+                    throw new Error(`Remote status failed using ${linkageLabel}: ${message}`);
                 }
                 assertRemoteIdentity(workspace, context.identity);
                 const remoteIdentity = extractWorkspaceIdentity(workspace);
@@ -958,18 +1011,21 @@ async function main() {
                     command: "remote",
                     subcommand: "status",
                     config_path: context.configPath,
-                    provider: context.mergedConfig.provider,
-                    endpoint: context.mergedConfig.endpoint,
-                    pod_name: context.mergedConfig.pod_name,
-                    actor_id: context.mergedConfig.actor_id,
+                    provider: "paseo",
+                    endpoint: context.resolvedTarget.endpoint,
+                    workspace_id: context.workspaceId,
+                    pod_name: context.resolvedTarget.pod_name,
+                    actor_id: context.resolvedTarget.actor_id,
                     linkage_source: context.linkageSource,
                     local_identity: context.identity,
                     remote_identity: {
                         project_id: remoteIdentity.project_id,
-                        workspace_name: remoteIdentity.workspace_name,
+                        workspace_id: remoteIdentity.workspace_id,
+                        actor_type: remoteIdentity.actor_type,
+                        backend_version: remoteIdentity.backend_version,
                     },
                     document_count: remoteIdentity.document_count,
-                    last_imported_at: context.savedConfig?.last_imported_at ?? null,
+                    last_imported_at: context.resolvedTarget.last_imported_at ?? null,
                     workspace,
                 };
                 if (output === "json") {
@@ -979,11 +1035,12 @@ async function main() {
                     console.log("Remote workspace reachable");
                     console.log(`Config: ${payload.config_path}`);
                     console.log(`Endpoint: ${payload.endpoint}`);
+                    console.log(`Workspace id: ${payload.workspace_id}`);
                     console.log(`Pod: ${payload.pod_name}`);
                     console.log(`Actor: ${payload.actor_id}`);
                     console.log(`Linkage source: ${payload.linkage_source}`);
-                    console.log(`Local identity: ${payload.local_identity.project_id}/${payload.local_identity.workspace_name}`);
-                    console.log(`Remote identity: ${String(payload.remote_identity.project_id)}/${String(payload.remote_identity.workspace_name)}`);
+                    console.log(`Local identity: ${payload.local_identity.project_id}/${payload.local_identity.workspace_id}`);
+                    console.log(`Remote identity: ${String(payload.remote_identity.project_id)}/${String(payload.remote_identity.workspace_id)} (${String(payload.remote_identity.actor_type)} ${String(payload.remote_identity.backend_version)})`);
                     console.log(`Remote document count: ${String(payload.document_count ?? "unknown")}`);
                     console.log(`Last imported at: ${String(payload.last_imported_at ?? "never")}`);
                 }
@@ -993,33 +1050,35 @@ async function main() {
                 const documents = await collectWorkspaceDocuments(parsed.repoRoot);
                 let importResult;
                 try {
-                    importResult = validateImportResult(await client.importWorkspace(documents, true));
+                    importResult = validateImportResult(await client.importWorkspace(context.workspaceId, documents, true));
                 }
                 catch (error) {
                     const message = error instanceof Error ? error.message : String(error);
-                    throw new Error(`Remote push failed using ${describeRemoteLinkage(context.mergedConfig)}: ${message}`);
+                    throw new Error(`Remote push failed using ${linkageLabel}: ${message}`);
                 }
                 let workspace;
                 try {
-                    workspace = await client.getWorkspace();
+                    workspace = await client.getWorkspace(context.workspaceId);
                 }
                 catch (error) {
                     const message = error instanceof Error ? error.message : String(error);
-                    throw new Error(`Remote push could not verify remote state using ${describeRemoteLinkage(context.mergedConfig)}: ${message}`);
+                    throw new Error(`Remote push could not verify remote state using ${linkageLabel}: ${message}`);
                 }
                 assertRemoteIdentity(workspace, context.identity);
                 const importedAt = new Date().toISOString();
-                await updateRemoteConfigMetadata(parsed.repoRoot, { last_imported_at: importedAt });
+                await updateRemoteConfigMetadata(parsed.repoRoot, context.workspaceId, {
+                    last_imported_at: importedAt,
+                });
                 const payload = {
                     status: "ok",
                     command: "remote",
                     subcommand: "push",
-                    endpoint: context.mergedConfig.endpoint,
-                    pod_name: context.mergedConfig.pod_name,
-                    actor_id: context.mergedConfig.actor_id,
+                    endpoint: context.resolvedTarget.endpoint,
+                    workspace_id: context.workspaceId,
+                    pod_name: context.resolvedTarget.pod_name,
+                    actor_id: context.resolvedTarget.actor_id,
                     linkage_source: context.linkageSource,
                     project_id: context.identity.project_id,
-                    workspace_name: context.identity.workspace_name,
                     local_document_count: documents.length,
                     imported: importResult.imported,
                     created: importResult.created,
@@ -1035,6 +1094,7 @@ async function main() {
                 else {
                     console.log("Remote push complete");
                     console.log(`Endpoint: ${payload.endpoint}`);
+                    console.log(`Workspace id: ${payload.workspace_id}`);
                     console.log(`Pod: ${payload.pod_name}`);
                     console.log(`Actor: ${payload.actor_id}`);
                     console.log(`Linkage source: ${payload.linkage_source}`);
@@ -1052,11 +1112,11 @@ async function main() {
             if (subcommand === "ls") {
                 let snapshot;
                 try {
-                    snapshot = await client.getSnapshot(parsed.prefix);
+                    snapshot = await client.getSnapshot(context.workspaceId, parsed.prefix);
                 }
                 catch (error) {
                     const message = error instanceof Error ? error.message : String(error);
-                    throw new Error(`Remote ls failed using ${describeRemoteLinkage(context.mergedConfig)}: ${message}`);
+                    throw new Error(`Remote ls failed using ${linkageLabel}: ${message}`);
                 }
                 const paths = (snapshot.documents ?? [])
                     .map((document) => (typeof document.path === "string" ? document.path : ""))
@@ -1066,9 +1126,10 @@ async function main() {
                     status: "ok",
                     command: "remote",
                     subcommand: "ls",
-                    endpoint: context.mergedConfig.endpoint,
-                    pod_name: context.mergedConfig.pod_name,
-                    actor_id: context.mergedConfig.actor_id,
+                    endpoint: context.resolvedTarget.endpoint,
+                    workspace_id: context.workspaceId,
+                    pod_name: context.resolvedTarget.pod_name,
+                    actor_id: context.resolvedTarget.actor_id,
                     linkage_source: context.linkageSource,
                     prefix: parsed.prefix ?? null,
                     paths,
@@ -1096,22 +1157,23 @@ async function main() {
                 }
                 let document;
                 try {
-                    document = await client.getDocument(documentPath);
+                    document = await client.getDocument(context.workspaceId, documentPath);
                 }
                 catch (error) {
                     const message = error instanceof Error ? error.message : String(error);
-                    throw new Error(`Remote cat failed using ${describeRemoteLinkage(context.mergedConfig)}: ${message}`);
+                    throw new Error(`Remote cat failed using ${linkageLabel}: ${message}`);
                 }
                 if (!document.document) {
-                    throw new Error(`Remote document not found using ${describeRemoteLinkage(context.mergedConfig)}: ${documentPath}`);
+                    throw new Error(`Remote document not found using ${linkageLabel}: ${documentPath}`);
                 }
                 const payload = {
                     status: "ok",
                     command: "remote",
                     subcommand: "cat",
-                    endpoint: context.mergedConfig.endpoint,
-                    pod_name: context.mergedConfig.pod_name,
-                    actor_id: context.mergedConfig.actor_id,
+                    endpoint: context.resolvedTarget.endpoint,
+                    workspace_id: context.workspaceId,
+                    pod_name: context.resolvedTarget.pod_name,
+                    actor_id: context.resolvedTarget.actor_id,
                     linkage_source: context.linkageSource,
                     document: document.document,
                 };

package/dist/gitignore.d.ts

@@ -0,0 +1,4 @@
+export declare function ensureGitignoreEntries(repoRoot: string, entries: string[]): Promise<{
+    path: string;
+    added: string[];
+}>;

package/dist/gitignore.js

@@ -0,0 +1,31 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+function normalizeLines(content) {
+    return content
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+}
+export async function ensureGitignoreEntries(repoRoot, entries) {
+    const gitignorePath = path.join(repoRoot, ".gitignore");
+    const current = await fs.readFile(gitignorePath, "utf8").catch(() => "");
+    const existing = new Set(normalizeLines(current));
+    const added = [];
+    for (const entry of entries) {
+        const normalized = entry.trim();
+        if (!normalized || existing.has(normalized))
+            continue;
+        existing.add(normalized);
+        added.push(normalized);
+    }
+    if (added.length === 0) {
+        return { path: gitignorePath, added };
+    }
+    const nextLines = current.length > 0 ? current.replace(/\s*$/, "").split(/\r?\n/) : [];
+    if (nextLines.length > 0 && nextLines[nextLines.length - 1] !== "") {
+        nextLines.push("");
+    }
+    nextLines.push(...added);
+    await fs.writeFile(gitignorePath, `${nextLines.join("\n")}\n`, "utf8");
+    return { path: gitignorePath, added };
+}

package/dist/index.d.ts

@@ -3,5 +3,6 @@ export { MANIFEST_VERSION, allowedKindExtensions, validateManifest } from "./man
 export { runDoctor } from "./doctor.js";
 export { createPlanScaffold } from "./plan.js";
 export { loadDotEnvIfPresent, parseDotEnv } from "./env.js";
-export { collectWorkspaceDocuments, ensureRemoteInit, extractWorkspaceIdentity, mergeRemoteConfig, PaseoRemoteClient, readRemoteConfig, resolveRemoteConfigPath, toCanonicalRemotePath, writeRemoteConfig, } from "./remote.js";
+export { ensureGitignoreEntries } from "./gitignore.js";
+export { collectWorkspaceDocuments, ensureRemoteInit, extractWorkspaceIdentity, PaseoRemoteClient, readRemoteConfig, resolveRemoteConfigPath, resolveRemoteTarget, resolveSelectedWorkspaceId, toCanonicalRemotePath, writeRemoteConfig, } from "./remote.js";
 export { listSpecs, showSpec } from "./spec-runtime.js";

package/dist/index.js

@@ -3,5 +3,6 @@ export { MANIFEST_VERSION, allowedKindExtensions, validateManifest } from "./man
 export { runDoctor } from "./doctor.js";
 export { createPlanScaffold } from "./plan.js";
 export { loadDotEnvIfPresent, parseDotEnv } from "./env.js";
-export { collectWorkspaceDocuments, ensureRemoteInit, extractWorkspaceIdentity, mergeRemoteConfig, PaseoRemoteClient, readRemoteConfig, resolveRemoteConfigPath, toCanonicalRemotePath, writeRemoteConfig, } from "./remote.js";
+export { ensureGitignoreEntries } from "./gitignore.js";
+export { collectWorkspaceDocuments, ensureRemoteInit, extractWorkspaceIdentity, PaseoRemoteClient, readRemoteConfig, resolveRemoteConfigPath, resolveRemoteTarget, resolveSelectedWorkspaceId, toCanonicalRemotePath, writeRemoteConfig, } from "./remote.js";
 export { listSpecs, showSpec } from "./spec-runtime.js";

package/dist/manifest.d.ts

@@ -1,7 +1,11 @@
 import type { Manifest } from "./types.js";
 export declare const MANIFEST_VERSION = 1;
 export declare function allowedKindExtensions(): Record<string, string[]>;
-export declare function deriveManifestIdentity(repoRoot: string): Required<Pick<Manifest, "project_id" | "workspace_name">>;
+export interface ManifestIdentityDefaults {
+    project_id: string;
+    workspace_ids: string[];
+}
+export declare function deriveManifestIdentity(repoRoot: string): ManifestIdentityDefaults;
 export declare function createManifest(repoRoot: string, now?: string): Manifest;
 export declare function normalizeManifest(raw: unknown, repoRoot: string): Manifest;
 export declare function inferArtifactType(filePath: string): {

package/dist/manifest.js

@@ -13,6 +13,7 @@ const KIND_EXTENSIONS = {
     file: [],
 };
 const PROJECT_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const WORKSPACE_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const FALLBACK_WORKSPACE_ID = "reffy-workspace";
 function isObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -25,11 +26,22 @@ function isIsoDate(value) {
 function isProjectId(value) {
     return typeof value === "string" && PROJECT_ID_PATTERN.test(value);
 }
+function isWorkspaceId(value) {
+    return typeof value === "string" && WORKSPACE_ID_PATTERN.test(value);
+}
 function isWorkspaceName(value) {
     return (typeof value === "string" &&
         value.trim().length > 0 &&
         !/[\\/\r\n\t]/.test(value));
 }
+function slugifyWorkspaceId(value) {
+    const slug = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return slug.length > 0 ? slug : null;
+}
 function slugifyIdentity(value) {
     return value
         .trim()
@@ -51,18 +63,33 @@ export function deriveManifestIdentity(repoRoot) {
     const identity = candidate || FALLBACK_WORKSPACE_ID;
     return {
         project_id: identity,
-        workspace_name: identity,
+        workspace_ids: [identity],
     };
 }
 export function createManifest(repoRoot, now = new Date().toISOString()) {
+    const defaults = deriveManifestIdentity(repoRoot);
     return {
         version: MANIFEST_VERSION,
         created_at: now,
         updated_at: now,
-        ...deriveManifestIdentity(repoRoot),
+        project_id: defaults.project_id,
+        workspace_ids: defaults.workspace_ids,
         artifacts: [],
     };
 }
+function normalizeWorkspaceIds(raw, fallback) {
+    const explicit = Array.isArray(raw.workspace_ids)
+        ? raw.workspace_ids.filter((entry) => typeof entry === "string" && entry.trim().length > 0)
+        : null;
+    if (explicit && explicit.length > 0) {
+        return Array.from(new Set(explicit.map((entry) => entry.trim())));
+    }
+    if (typeof raw.workspace_name === "string" && raw.workspace_name.trim().length > 0) {
+        const migrated = slugifyWorkspaceId(raw.workspace_name) ?? raw.workspace_name.trim();
+        return [migrated];
+    }
+    return [...fallback];
+}
 export function normalizeManifest(raw, repoRoot) {
     const now = new Date().toISOString();
     const defaults = deriveManifestIdentity(repoRoot);
@@ -71,7 +98,8 @@ export function normalizeManifest(raw, repoRoot) {
             version: 0,
             created_at: now,
             updated_at: now,
-            ...defaults,
+            project_id: defaults.project_id,
+            workspace_ids: defaults.workspace_ids,
             artifacts: raw,
         };
     }
@@ -79,12 +107,13 @@ export function normalizeManifest(raw, repoRoot) {
         return createManifest(repoRoot, now);
     }
     const artifacts = Array.isArray(raw.artifacts) ? raw.artifacts : [];
+    const workspaceIds = normalizeWorkspaceIds(raw, defaults.workspace_ids);
     return {
         version: typeof raw.version === "number" ? raw.version : MANIFEST_VERSION,
         created_at: typeof raw.created_at === "string" ? raw.created_at : now,
         updated_at: typeof raw.updated_at === "string" ? raw.updated_at : now,
         project_id: typeof raw.project_id === "string" ? raw.project_id : defaults.project_id,
-        workspace_name: typeof raw.workspace_name === "string" ? raw.workspace_name : defaults.workspace_name,
+        workspace_ids: workspaceIds,
         artifacts,
     };
 }
@@ -183,8 +212,32 @@ export async function validateManifest(manifestPath, artifactsDir) {
     if (raw.project_id !== undefined && !isProjectId(raw.project_id)) {
         errors.push("project_id must be a non-empty kebab-case string");
     }
-    if (raw.workspace_name !== undefined && !isWorkspaceName(raw.workspace_name)) {
-        errors.push("workspace_name must be a non-empty string without path separators or control characters");
+    if (raw.workspace_ids !== undefined) {
+        if (!Array.isArray(raw.workspace_ids) || raw.workspace_ids.length === 0) {
+            errors.push("workspace_ids must be a non-empty array of kebab-case strings when provided");
+        }
+        else {
+            const seen = new Set();
+            raw.workspace_ids.forEach((entry, index) => {
+                if (!isWorkspaceId(entry)) {
+                    errors.push(`workspace_ids[${index}] must be a non-empty kebab-case string`);
+                    return;
+                }
+                if (seen.has(entry)) {
+                    errors.push(`workspace_ids[${index}] duplicates "${entry}"`);
+                    return;
+                }
+                seen.add(entry);
+            });
+        }
+    }
+    if (raw.workspace_name !== undefined) {
+        if (!isWorkspaceName(raw.workspace_name)) {
+            errors.push("workspace_name must be a non-empty string without path separators or control characters");
+        }
+        else if (raw.workspace_ids === undefined) {
+            warnings.push("workspace_name is deprecated; migrate to workspace_ids");
+        }
     }
     if (!Array.isArray(raw.artifacts)) {
         errors.push("artifacts must be an array");

package/dist/remote.d.ts

@@ -1,9 +1,21 @@
-import type { RemoteDocument, RemoteImportResult, RemoteLinkConfig, RemoteWorkspaceSummary } from "./types.js";
-export declare const REMOTE_CONFIG_VERSION = 1;
+import type { RemoteDocument, RemoteImportResult, RemoteLinkConfig, RemoteTarget, RemoteWorkspaceSummary } from "./types.js";
+export declare const REMOTE_CONFIG_VERSION = 2;
 export declare const REMOTE_PROVIDER = "paseo";
+export declare const REMOTE_BACKEND_ACTOR_TYPE = "reffyRemoteBackend";
+export declare const REMOTE_BACKEND_VERSION = "v2";
 export interface WorkspaceIdentity {
     project_id: string;
-    workspace_name: string;
+    workspace_id: string;
+}
+export interface ManifestIdentityLike {
+    project_id?: string;
+    workspace_ids?: string[];
+}
+export interface ResolvedRemoteTarget {
+    endpoint: string;
+    pod_name: string;
+    actor_id: string;
+    last_imported_at?: string;
 }
 export interface EnsureRemoteInitOptions {
     endpoint: string;
@@ -11,9 +23,11 @@ export interface EnsureRemoteInitOptions {
     actorId?: string;
     provision: boolean;
     identity: WorkspaceIdentity;
+    existingConfig: RemoteLinkConfig | null;
 }
 export interface EnsureRemoteInitResult {
     config: RemoteLinkConfig;
+    target: RemoteTarget;
     created_pod: boolean;
     created_actor: boolean;
 }
@@ -24,24 +38,39 @@ export interface ValidatedImportResult {
     deleted: number;
 }
 export declare function resolveRemoteConfigPath(repoRoot: string): string;
+export declare function resolveSelectedWorkspaceId(identity: ManifestIdentityLike, override: string | undefined): string;
+export declare function requireWorkspaceIdentity(identity: ManifestIdentityLike, selectedWorkspaceId: string): WorkspaceIdentity;
 export declare function readRemoteConfig(repoRoot: string): Promise<RemoteLinkConfig | null>;
 export declare function writeRemoteConfig(repoRoot: string, config: RemoteLinkConfig): Promise<string>;
-export declare function updateRemoteConfigMetadata(repoRoot: string, patch: Partial<Pick<RemoteLinkConfig, "last_imported_at">>): Promise<RemoteLinkConfig | null>;
-export declare function mergeRemoteConfig(stored: RemoteLinkConfig | null, overrides: Partial<Pick<RemoteLinkConfig, "endpoint" | "pod_name" | "actor_id">>): RemoteLinkConfig | null;
-export declare function describeRemoteLinkage(config: Pick<RemoteLinkConfig, "endpoint" | "pod_name" | "actor_id">): string;
+export declare function updateRemoteConfigMetadata(repoRoot: string, workspaceId: string, patch: Partial<Pick<RemoteTarget, "last_imported_at">>): Promise<RemoteLinkConfig | null>;
+export declare function resolveRemoteTarget(stored: RemoteLinkConfig | null, workspaceId: string, overrides: {
+    endpoint?: string;
+    pod_name?: string;
+    actor_id?: string;
+}): ResolvedRemoteTarget | null;
+export declare function describeRemoteLinkage(linkage: {
+    endpoint: string;
+    pod_name: string;
+    actor_id: string;
+    workspace_id: string;
+}): string;
 export declare class PaseoRemoteClient {
     private readonly config;
-    constructor(config: Pick<RemoteLinkConfig, "endpoint" | "pod_name" | "actor_id">);
+    constructor(config: {
+        endpoint: string;
+        pod_name: string;
+        actor_id: string;
+    });
     createPod(): Promise<string>;
     createActor(identity: WorkspaceIdentity): Promise<string>;
-    getWorkspace(): Promise<RemoteWorkspaceSummary>;
-    importWorkspace(documents: RemoteDocument[], replaceMissing?: boolean): Promise<RemoteImportResult>;
-    getSnapshot(prefix?: string): Promise<{
+    getWorkspace(workspaceId: string): Promise<RemoteWorkspaceSummary>;
+    importWorkspace(workspaceId: string, documents: RemoteDocument[], replaceMissing?: boolean): Promise<RemoteImportResult>;
+    getSnapshot(workspaceId: string, prefix?: string): Promise<{
         documents?: Array<{
             path?: string;
         }>;
     }>;
-    getDocument(documentPath: string): Promise<{
+    getDocument(workspaceId: string, documentPath: string): Promise<{
         document?: {
             path?: string;
             content?: string;
@@ -50,13 +79,11 @@ export declare class PaseoRemoteClient {
     }>;
 }
 export declare function ensureRemoteInit(repoRoot: string, options: EnsureRemoteInitOptions): Promise<EnsureRemoteInitResult>;
-export declare function requireWorkspaceIdentity(identity: {
-    project_id?: string;
-    workspace_name?: string;
-}): WorkspaceIdentity;
 export declare function extractWorkspaceIdentity(summary: RemoteWorkspaceSummary): {
     project_id?: string | null;
-    workspace_name?: string | null;
+    workspace_id?: string | null;
+    actor_type?: string | null;
+    backend_version?: string | null;
     document_count?: number | null;
 };
 export declare function assertRemoteIdentity(summary: RemoteWorkspaceSummary, identity: WorkspaceIdentity): void;

package/dist/remote.js

@@ -1,8 +1,10 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { resolveRefsDir } from "./refs-paths.js";
-export const REMOTE_CONFIG_VERSION = 1;
+export const REMOTE_CONFIG_VERSION = 2;
 export const REMOTE_PROVIDER = "paseo";
+export const REMOTE_BACKEND_ACTOR_TYPE = "reffyRemoteBackend";
+export const REMOTE_BACKEND_VERSION = "v2";
 const REMOTE_STATE_DIR = path.join("state");
 const REMOTE_CONFIG_FILE = "remote.json";
 function isObject(value) {
@@ -17,6 +19,39 @@ function normalizeSeparators(value) {
 export function resolveRemoteConfigPath(repoRoot) {
     return path.join(resolveRefsDir(repoRoot), REMOTE_STATE_DIR, REMOTE_CONFIG_FILE);
 }
+export function resolveSelectedWorkspaceId(identity, override) {
+    const workspaceIds = (identity.workspace_ids ?? [])
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    if (override !== undefined) {
+        const trimmed = override.trim();
+        if (!trimmed) {
+            throw new Error("--workspace-id requires a non-empty value");
+        }
+        if (workspaceIds.length > 0 && !workspaceIds.includes(trimmed)) {
+            throw new Error(`Selected workspace id "${trimmed}" is not a member of manifest.workspace_ids: ${workspaceIds.join(", ") || "(none)"}`);
+        }
+        return trimmed;
+    }
+    if (workspaceIds.length === 0) {
+        throw new Error("Remote sync requires .reffy/manifest.json to define workspace_ids. Run `reffy init` or add at least one workspace id.");
+    }
+    if (workspaceIds.length === 1) {
+        return workspaceIds[0];
+    }
+    throw new Error(`Manifest has multiple workspace_ids (${workspaceIds.join(", ")}); pass --workspace-id to select a target projection.`);
+}
+export function requireWorkspaceIdentity(identity, selectedWorkspaceId) {
+    const project_id = identity.project_id?.trim();
+    if (!project_id) {
+        throw new Error("Remote sync requires .reffy/manifest.json to define project_id");
+    }
+    const workspace_id = selectedWorkspaceId.trim();
+    if (!workspace_id) {
+        throw new Error("Remote sync requires a selected workspace_id");
+    }
+    return { project_id, workspace_id };
+}
 export async function readRemoteConfig(repoRoot) {
     const configPath = resolveRemoteConfigPath(repoRoot);
     const raw = await fs.readFile(configPath, "utf8").catch(() => null);
@@ -32,28 +67,43 @@ export async function readRemoteConfig(repoRoot) {
     if (!isObject(parsed)) {
         throw new Error(`Remote config at ${configPath} must be an object`);
     }
-    if (parsed.version !== REMOTE_CONFIG_VERSION) {
-        throw new Error(`Remote config at ${configPath} must use version ${String(REMOTE_CONFIG_VERSION)}`);
-    }
     if (parsed.provider !== REMOTE_PROVIDER) {
         throw new Error(`Remote config at ${configPath} must use provider "${REMOTE_PROVIDER}"`);
     }
     if (!isNonEmptyString(parsed.endpoint)) {
         throw new Error(`Remote config at ${configPath} must define endpoint`);
     }
-    if (!isNonEmptyString(parsed.pod_name)) {
-        throw new Error(`Remote config at ${configPath} must define pod_name`);
+    if (parsed.version === 1) {
+        throw new Error(`Remote config at ${configPath} uses the legacy v1 single-target shape. Run \`reffy remote init --provision\` against the v2 backend to reinitialize, then repush with \`reffy remote push\`.`);
     }
-    if (!isNonEmptyString(parsed.actor_id)) {
-        throw new Error(`Remote config at ${configPath} must define actor_id`);
+    if (parsed.version !== REMOTE_CONFIG_VERSION) {
+        throw new Error(`Remote config at ${configPath} must use version ${String(REMOTE_CONFIG_VERSION)}`);
+    }
+    if (!isObject(parsed.targets)) {
+        throw new Error(`Remote config at ${configPath} must define targets as an object keyed by workspace_id`);
+    }
+    const targets = {};
+    for (const [workspaceId, entry] of Object.entries(parsed.targets)) {
+        if (!isObject(entry)) {
+            throw new Error(`Remote config at ${configPath} has invalid target for workspace_id "${workspaceId}"`);
+        }
+        if (!isNonEmptyString(entry.pod_name)) {
+            throw new Error(`Remote config target "${workspaceId}" must define pod_name`);
+        }
+        if (!isNonEmptyString(entry.actor_id)) {
+            throw new Error(`Remote config target "${workspaceId}" must define actor_id`);
+        }
+        targets[workspaceId] = {
+            pod_name: entry.pod_name.trim(),
+            actor_id: entry.actor_id.trim(),
+            last_imported_at: isNonEmptyString(entry.last_imported_at) ? entry.last_imported_at.trim() : undefined,
+        };
     }
     return {
         version: REMOTE_CONFIG_VERSION,
         provider: REMOTE_PROVIDER,
         endpoint: parsed.endpoint.trim(),
-        pod_name: parsed.pod_name.trim(),
-        actor_id: parsed.actor_id.trim(),
-        last_imported_at: isNonEmptyString(parsed.last_imported_at) ? parsed.last_imported_at.trim() : undefined,
+        targets,
     };
 }
 export async function writeRemoteConfig(repoRoot, config) {
@@ -62,38 +112,40 @@ export async function writeRemoteConfig(repoRoot, config) {
     await fs.writeFile(configPath, JSON.stringify(config, null, 2), "utf8");
     return configPath;
 }
-export async function updateRemoteConfigMetadata(repoRoot, patch) {
+export async function updateRemoteConfigMetadata(repoRoot, workspaceId, patch) {
     const existing = await readRemoteConfig(repoRoot);
     if (!existing)
         return null;
+    const target = existing.targets[workspaceId];
+    if (!target)
+        return null;
     const next = {
         ...existing,
-        ...patch,
+        targets: {
+            ...existing.targets,
+            [workspaceId]: { ...target, ...patch },
+        },
     };
     await writeRemoteConfig(repoRoot, next);
     return next;
 }
-export function mergeRemoteConfig(stored, overrides) {
-    if (!stored && !overrides.endpoint && !overrides.pod_name && !overrides.actor_id) {
-        return null;
-    }
+export function resolveRemoteTarget(stored, workspaceId, overrides) {
     const endpoint = overrides.endpoint ?? stored?.endpoint;
-    const pod_name = overrides.pod_name ?? stored?.pod_name;
-    const actor_id = overrides.actor_id ?? stored?.actor_id;
+    const target = stored?.targets?.[workspaceId];
+    const pod_name = overrides.pod_name ?? target?.pod_name;
+    const actor_id = overrides.actor_id ?? target?.actor_id;
     if (!endpoint || !pod_name || !actor_id) {
         return null;
     }
     return {
-        version: REMOTE_CONFIG_VERSION,
-        provider: REMOTE_PROVIDER,
         endpoint,
         pod_name,
         actor_id,
-        last_imported_at: stored?.last_imported_at,
+        last_imported_at: target?.last_imported_at,
     };
 }
-export function describeRemoteLinkage(config) {
-    return `endpoint=${config.endpoint} pod=${config.pod_name} actor=${config.actor_id}`;
+export function describeRemoteLinkage(linkage) {
+    return `endpoint=${linkage.endpoint} pod=${linkage.pod_name} actor=${linkage.actor_id} workspace=${linkage.workspace_id}`;
 }
 async function http(url, init = {}) {
     const headers = new Headers(init.headers ?? {});
@@ -114,6 +166,9 @@ async function httpJson(url, init = {}) {
 function actorBase(config) {
     return `${config.endpoint}/pods/${config.pod_name}/actors/${config.actor_id}`;
 }
+function workspaceBase(config, workspaceId) {
+    return `${actorBase(config)}/workspaces/${encodeURIComponent(workspaceId)}`;
+}
 export class PaseoRemoteClient {
     config;
     constructor(config) {
@@ -131,12 +186,12 @@ export class PaseoRemoteClient {
             method: "POST",
             body: JSON.stringify({
                 config: {
-                    actorType: "reffyRemoteBackend",
-                    version: "v1",
+                    actorType: REMOTE_BACKEND_ACTOR_TYPE,
+                    version: REMOTE_BACKEND_VERSION,
                     schema: { type: "object" },
                     params: {
                         project_id: identity.project_id,
-                        workspace_name: identity.workspace_name,
+                        workspace_ids: [identity.workspace_id],
                         default_lock_ttl_seconds: 120,
                         max_snapshot_documents: 1000,
                     },
@@ -148,11 +203,11 @@ export class PaseoRemoteClient {
         }
         return result.actorId.trim();
     }
-    async getWorkspace() {
-        return await httpJson(`${actorBase(this.config)}/workspace`);
+    async getWorkspace(workspaceId) {
+        return await httpJson(workspaceBase(this.config, workspaceId));
     }
-    async importWorkspace(documents, replaceMissing = true) {
-        return await httpJson(`${actorBase(this.config)}/workspace/import`, {
+    async importWorkspace(workspaceId, documents, replaceMissing = true) {
+        return await httpJson(`${workspaceBase(this.config, workspaceId)}/import`, {
             method: "POST",
             body: JSON.stringify({
                 documents,
@@ -160,27 +215,29 @@ export class PaseoRemoteClient {
             }),
         });
     }
-    async getSnapshot(prefix) {
+    async getSnapshot(workspaceId, prefix) {
         const query = prefix ? `?prefix=${encodeURIComponent(prefix)}` : "";
-        return await httpJson(`${actorBase(this.config)}/workspace/snapshot${query}`);
+        return await httpJson(`${workspaceBase(this.config, workspaceId)}/snapshot${query}`);
     }
-    async getDocument(documentPath) {
-        return await httpJson(`${actorBase(this.config)}/workspace/documents?path=${encodeURIComponent(documentPath)}`);
+    async getDocument(workspaceId, documentPath) {
+        return await httpJson(`${workspaceBase(this.config, workspaceId)}/documents?path=${encodeURIComponent(documentPath)}`);
     }
 }
 export async function ensureRemoteInit(repoRoot, options) {
     let created_pod = false;
     let created_actor = false;
-    let podName = options.podName?.trim() || "";
-    let actorId = options.actorId?.trim() || "";
-    if (!options.endpoint.trim()) {
+    const endpoint = options.endpoint.trim();
+    if (!endpoint) {
         throw new Error("Remote init requires an endpoint");
     }
+    const priorTarget = options.existingConfig?.targets[options.identity.workspace_id] ?? null;
+    let podName = options.podName?.trim() || priorTarget?.pod_name || "";
+    let actorId = options.actorId?.trim() || priorTarget?.actor_id || "";
     if (!podName && !options.provision) {
         throw new Error("Remote init requires --pod-name unless --provision is set");
     }
     const baseClient = new PaseoRemoteClient({
-        endpoint: options.endpoint.trim(),
+        endpoint,
         pod_name: podName || "pending-pod",
         actor_id: actorId || "pending-actor",
     });
@@ -193,44 +250,49 @@ export async function ensureRemoteInit(repoRoot, options) {
             throw new Error("Remote init requires --actor-id unless --provision is set");
         }
         const client = new PaseoRemoteClient({
-            endpoint: options.endpoint.trim(),
+            endpoint,
             pod_name: podName,
             actor_id: "pending-actor",
         });
         actorId = await client.createActor(options.identity);
         created_actor = true;
     }
+    const nextTarget = {
+        pod_name: podName,
+        actor_id: actorId,
+        last_imported_at: priorTarget?.last_imported_at,
+    };
     const config = {
         version: REMOTE_CONFIG_VERSION,
         provider: REMOTE_PROVIDER,
-        endpoint: options.endpoint.trim(),
-        pod_name: podName,
-        actor_id: actorId,
+        endpoint,
+        targets: {
+            ...(options.existingConfig?.targets ?? {}),
+            [options.identity.workspace_id]: nextTarget,
+        },
     };
     await writeRemoteConfig(repoRoot, config);
-    return { config, created_pod, created_actor };
-}
-export function requireWorkspaceIdentity(identity) {
-    const project_id = identity.project_id?.trim();
-    const workspace_name = identity.workspace_name?.trim();
-    if (!project_id || !workspace_name) {
-        throw new Error("Remote sync requires .reffy/manifest.json to define project_id and workspace_name");
-    }
-    return { project_id, workspace_name };
+    return { config, target: nextTarget, created_pod, created_actor };
 }
 export function extractWorkspaceIdentity(summary) {
+    const source = isObject(summary.source) ? summary.source : {};
     const workspace = isObject(summary.workspace) ? summary.workspace : {};
     const stats = isObject(summary.stats) ? summary.stats : {};
     return {
-        project_id: typeof workspace.project_id === "string" ? workspace.project_id : null,
-        workspace_name: typeof workspace.workspace_name === "string" ? workspace.workspace_name : null,
+        project_id: typeof source.project_id === "string" ? source.project_id : null,
+        workspace_id: typeof workspace.workspace_id === "string" ? workspace.workspace_id : null,
+        actor_type: typeof source.actor_type === "string" ? source.actor_type : null,
+        backend_version: typeof source.version === "string" ? source.version : null,
         document_count: typeof stats.document_count === "number" ? stats.document_count : null,
     };
 }
 export function assertRemoteIdentity(summary, identity) {
     const remote = extractWorkspaceIdentity(summary);
-    if (remote.project_id !== identity.project_id || remote.workspace_name !== identity.workspace_name) {
-        throw new Error(`Remote identity mismatch: local=${identity.project_id}/${identity.workspace_name} remote=${String(remote.project_id)}/${String(remote.workspace_name)}`);
+    if (!remote.workspace_id) {
+        throw new Error("Remote response did not include a workspace.workspace_id envelope. This likely means the linked actor is a legacy v1 backend. Reinitialize the target against reffyRemoteBackend.v2 (`reffy remote init --provision --workspace-id <id>`) and repush with `reffy remote push`.");
+    }
+    if (remote.project_id !== identity.project_id || remote.workspace_id !== identity.workspace_id) {
+        throw new Error(`Remote identity mismatch: local=${identity.project_id}/${identity.workspace_id} remote=${String(remote.project_id)}/${String(remote.workspace_id)}`);
     }
 }
 export function validateImportResult(result) {

package/dist/storage.d.ts

@@ -12,7 +12,7 @@ export declare class ReferencesStore {
     listArtifacts(): Promise<Artifact[]>;
     getWorkspaceIdentity(): Promise<{
         project_id?: string;
-        workspace_name?: string;
+        workspace_ids?: string[];
     }>;
     getArtifact(artifactId: string): Promise<Artifact | null>;
     getArtifactPath(artifact: Artifact): string;

package/dist/storage.js

@@ -51,7 +51,7 @@ export class ReferencesStore {
         const manifest = await this.readManifest();
         return {
             project_id: manifest.project_id,
-            workspace_name: manifest.workspace_name,
+            workspace_ids: manifest.workspace_ids ? [...manifest.workspace_ids] : undefined,
         };
     }
     async getArtifact(artifactId) {

package/dist/types.d.ts

@@ -17,16 +17,21 @@ export interface Manifest {
     created_at: string;
     updated_at: string;
     project_id?: string;
+    workspace_ids?: string[];
+    /** Deprecated v1 field retained only as migration input. */
     workspace_name?: string;
     artifacts: Artifact[];
 }
+export interface RemoteTarget {
+    pod_name: string;
+    actor_id: string;
+    last_imported_at?: string;
+}
 export interface RemoteLinkConfig {
     version: number;
     provider: "paseo";
     endpoint: string;
-    pod_name: string;
-    actor_id: string;
-    last_imported_at?: string;
+    targets: Record<string, RemoteTarget>;
 }
 export interface RemoteDocument {
     path: string;
@@ -41,6 +46,7 @@ export interface RemoteImportResult {
     deleted?: number;
 }
 export interface RemoteWorkspaceSummary {
+    source?: Record<string, unknown>;
     workspace?: Record<string, unknown>;
     stats?: Record<string, unknown>;
 }

package/dist/workspace.js

@@ -1,6 +1,6 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { deriveManifestIdentity, normalizeManifest } from "./manifest.js";
+import { normalizeManifest } from "./manifest.js";
 import { DEFAULT_REFS_DIRNAME, LEGACY_REFS_DIRNAME, detectWorkspaceState, resolveCanonicalRefsDir, } from "./refs-paths.js";
 async function pathExists(targetPath) {
     try {
@@ -30,11 +30,13 @@ async function ensureCanonicalStructure(repoRoot) {
                 const raw = JSON.parse(rawText);
                 if (raw && typeof raw === "object" && !Array.isArray(raw)) {
                     const record = raw;
-                    const defaults = deriveManifestIdentity(repoRoot);
-                    const missingIdentity = record.project_id === undefined || record.workspace_name === undefined;
-                    if (missingIdentity) {
+                    const missingProjectId = record.project_id === undefined;
+                    const missingWorkspaceIds = !Array.isArray(record.workspace_ids) || record.workspace_ids.length === 0;
+                    const needsMigration = missingProjectId || missingWorkspaceIds;
+                    if (needsMigration) {
                         const nextManifest = normalizeManifest(raw, repoRoot);
                         nextManifest.updated_at = new Date().toISOString();
+                        delete nextManifest.workspace_name;
                         await fs.writeFile(manifestPath, JSON.stringify(nextManifest, null, 2), "utf8");
                     }
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reffy-cli",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Planning system for AI assisted development.",
   "keywords": [
     "reffy",
@@ -35,7 +35,6 @@
     "prepare": "npm run build",
     "dev": "tsx watch src/cli.ts",
     "check": "tsc --noEmit",
-    "remote:backend:demo": "node scripts/reffy-remote-backend-demo.mjs",
     "test": "npm run build && vitest run --coverage",
     "test:watch": "vitest"
   },