synomem 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -3,6 +3,70 @@
 All notable changes will be documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and releases follow Semantic Versioning.
 
+## [0.6.0] - 2026-09-07
+
+### Added
+
+- Local workspace isolation is now real. A local workspace used to be a
+  `--workspace` label with nothing behind it — only `events` carried
+  `workspace_id`, reads never filtered on it, and several tables had no such
+  column at all. A local workspace is now a separate SQLite database in its
+  own home, the safer design given SQLite has no row-level security: on
+  Postgres a query that forgets to filter by workspace returns nothing
+  instead of another workspace's rows, and separate files make the local
+  equivalent of that mistake unwritable rather than merely unlikely.
+- A directory can now be bound to a local workspace: `synomem workspace use
+<name> [--as <actor>]` writes `.synomem/config.json`, found by walking up
+  from the working directory the same way `.git` or `.nvmrc` is. Every command
+  and every stdio MCP server started in that directory afterward resolves the
+  workspace — and, unless overridden per launch, the default actor — with no
+  flag repeated. This is what makes several harnesses opened in the same
+  repository share one workspace while each still writes as its own actor:
+  `--workspace`, `SYNOMEM_WORKSPACE`, and `--home` all still win outright, in
+  that order, over the project file, and each harness's own `--agent-id` or
+  `--actor-id` always wins over the file's default actor.
+- `synomem_agent_archive` and `synomem_agent_restore` MCP tools, closing the
+  gap where the CLI could archive or restore an agent identity but MCP could
+  not. Gated by a new `allowAgentArchiveViaMcp` capability
+  (`SYNOMEM_ALLOW_AGENT_ARCHIVE_VIA_MCP`), off by default and mirroring
+  `agentCreationViaMcp` exactly, so runtime agents cannot silently disable
+  each other unless an operator opts in.
+
+### Fixed
+
+- An agent created before handles existed (schema 7) made every write in its
+  workspace fail with `UNSUPPORTED_EVENT`: its stored `agent.created` event
+  carries an id and no handle, and the compatibility check that runs before
+  each write refused the whole event stream on that missing field. The reader
+  now widens to accept it — the id is the correct handle for those records —
+  rather than the append-only log being rewritten.
+- Renaming an agent's handle left its old projection directory behind,
+  stranding `NOTES.md`, the one file in there that belongs to the reader
+  rather than to Synomem and that a rebuild will never delete. The directory
+  is now moved to the new handle before projections are regenerated, so
+  hand-written notes arrive intact instead of being stranded.
+
+## [0.5.3] - 2026-09-07
+
+### Documentation
+
+- 0.5.2 said the inbox "does not include posts or todos", which implied notes
+  were in it. They are not. The inbox holds kudos, memos and tasks and nothing
+  else, because it answers one question -- what is another actor waiting on
+  this agent for -- and nobody waits on an agent's own knowledge, its own
+  reminders, or an announcement addressed to everyone. The Skill, the examples
+  and the `synomem_inbox` description now say what it contains rather than
+  listing exclusions and getting the list wrong.
+- `synomem_list` and `synomem_get` still described four record kinds out of
+  six. `synomem_list` now also says that posts and todos are reachable only
+  through it, and that an empty inbox is not the same as nothing to look at.
+
+### Tests
+
+- The inbox contract is pinned by a test, since the Skill and the MCP tool
+  descriptions both state it and neither can check it. Confirmed to fail when a
+  kind is added to the `pending` filter.
+
 ## [0.5.2] - 2026-09-07
 
 ### Documentation

package/README.md

@@ -38,9 +38,9 @@ Synomem gives humans and AI agents durable ways to coordinate beyond a disappear
 Traditional AI memory layers resemble an isolated file cabinet for one model. Synomem turns memory
 into a shared, transactional canvas: independently operating agents can retain private knowledge,
 deliver durable context, delegate work with consent, track commitments, and recognize good
-collaboration through one auditable protocol. V1 provides that substrate locally; its interfaces are
-designed so the same agent identities and semantics can later cross machines through an explicitly
-configured service.
+collaboration through one auditable protocol. The same agent identities and semantics work on one
+machine or across many: the local backend keeps everything on disk, and Synomem Cloud keeps it in a
+hosted workspace reached over HTTPS.
 
 One append-only event store powers the TypeScript library, `synomem` CLI, actor-bound stdio MCP
 server, compact change feeds, and readable Markdown projections. On the local backend that store is
@@ -85,7 +85,7 @@ Everything below works the same on both backends.
 
 ```bash
 export SYNOMEM_HOME="$(mktemp -d)/.synomem"
-synomem init
+synomem config init --backend local --yes
 synomem agent create codex --name "Codex"
 synomem agent create gracie --name "Gracie"
 
@@ -243,23 +243,41 @@ are `claude`, `codex`, `hermes`, `openclaw`, `cursor`, and `grok`; `grokbot` ali
 
 ## Storage
 
+This is the local backend. On Synomem Cloud the canonical store is a hosted Postgres workspace and
+nothing below is written to this machine.
+
 ```text
 ~/.synomem/
-├── synomem/
-│   ├── config.json
-│   └── synomem.sqlite3
-└── <agent-id>/
+├── config.json
+├── synomem.sqlite3
+├── credentials/
+│   └── installation.json   # only when an access key is stored in a file
+└── <handle>/               # one directory per agent, named by handle
     ├── profile.json
     ├── WINS.md
     ├── MEMORY.md
     ├── TASKS.md
-    ├── inbox/{kudos,memos,tasks}/
-    └── NOTES.md
+    ├── NOTES.md
+    └── inbox/{kudos,memos,tasks}/<record-id>.md
 ```
 
+The home IS the storage directory: `config.json` and the database sit directly in it, with no
+nested `synomem/` level.
+
+Agent directories are named by HANDLE, because they exist to be read. The canonical agent ID is
+what stored events reference, so renaming an agent leaves its history untouched.
+
+Renaming moves the whole directory, `NOTES.md` included. That file is yours rather than Synomem's,
+so a rebuild will never delete it — which is exactly why the rename moves the directory instead of
+regenerating it somewhere new and leaving your notes behind.
+
 SQLite events are canonical and append-only. Markdown and current-state tables are rebuildable
-projections. `NOTES.md` is human-owned and is never overwritten; canonical agent notes project to
-`MEMORY.md`.
+projections — run `synomem rebuild` to regenerate them, and `synomem projection status` to see
+whether they currently match the events. Posts and todos project no files: a post belongs to the
+whole workspace rather than to one agent's directory, and a todo is private to its owner.
+
+`NOTES.md` is human-owned and is never overwritten; canonical agent notes project to `MEMORY.md`.
+Each projection can be turned off individually, in which case its file is not written at all.
 
 Override the root with `SYNOMEM_HOME`, `--home`, or the library's `home` option. Use
 `synomem backup` for a consistent snapshot and JSON or JSONL export for recovery. Never synchronize

package/dist/cli.d.ts

@@ -38,6 +38,6 @@ export interface CliDependencies {
         planId?: string;
     }) => Promise<ImportPreview | ImportResult>;
 }
-export declare function createCli(io?: CliIo, serviceFactory?: SynomemServiceFactory, dependencies?: CliDependencies): Command;
+export declare function createCli(io?: CliIo, serviceFactory?: SynomemServiceFactory, dependencies?: CliDependencies, argv?: string[]): Command;
 export declare function runCli(argv?: string[], io?: CliIo, serviceFactory?: SynomemServiceFactory, dependencies?: CliDependencies): Promise<number>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAKA,OAAO,EAAE,OAAO,EAA0B,MAAM,WAAW,CAAC;AAmB5D,OAAO,EAAmB,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAA0C,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAIhG,OAAO,EAA4C,KAAK,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE9F,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AASrB,OAAO,KAAK,EACV,aAAa,EASd,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAkB,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE1E,MAAM,WAAW,KAAK;IACpB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,sBAAsB,CAAC,EAAE,CAAC,OAAO,EAAE;QACjC,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,aAAa,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,eAAe,EAAE,eAAe,CAAC;KAClC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAKpB,sBAAsB,CAAC,EAAE,CAAC,OAAO,EAAE;QACjC,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;KACrB,KAAK,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvC,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IAC7D,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE;QACvB,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,aAAa,CAAC;QACrB,MAAM,EAAE,YAAY,CAAC;QACrB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,KAAK,OAAO,CAAC,aAAa,GAAG,YAAY,CAAC,CAAC;CAC7C;AAkND,wBAAgB,SAAS,CACvB,EAAE,GAAE,KAAiB,EACrB,cAAc,GAAE,qBAAgD,EAChE,YAAY,GAAE,eAAoB,GACjC,OAAO,CA62ET;AAED,wBAAsB,MAAM,CAC1B,IAAI,WAAe,EACnB,EAAE,GAAE,KAAiB,EACrB,cAAc,GAAE,qBAAgD,EAChE,YAAY,GAAE,eAAoB,GACjC,OAAO,CAAC,MAAM,CAAC,CAqBjB"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAKA,OAAO,EAAE,OAAO,EAA0B,MAAM,WAAW,CAAC;AAyB5D,OAAO,EAAmB,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAA0C,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAIhG,OAAO,EAA4C,KAAK,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE9F,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AASrB,OAAO,KAAK,EACV,aAAa,EASd,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAkB,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE1E,MAAM,WAAW,KAAK;IACpB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,sBAAsB,CAAC,EAAE,CAAC,OAAO,EAAE;QACjC,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,aAAa,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,eAAe,EAAE,eAAe,CAAC;KAClC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAKpB,sBAAsB,CAAC,EAAE,CAAC,OAAO,EAAE;QACjC,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;KACrB,KAAK,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvC,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IAC7D,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE;QACvB,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,aAAa,CAAC;QACrB,MAAM,EAAE,YAAY,CAAC;QACrB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,KAAK,OAAO,CAAC,aAAa,GAAG,YAAY,CAAC,CAAC;CAC7C;AA+QD,wBAAgB,SAAS,CACvB,EAAE,GAAE,KAAiB,EACrB,cAAc,GAAE,qBAAgD,EAChE,YAAY,GAAE,eAAoB,EAClC,IAAI,GAAE,MAAM,EAAiB,GAC5B,OAAO,CA8/ET;AAED,wBAAsB,MAAM,CAC1B,IAAI,WAAe,EACnB,EAAE,GAAE,KAAiB,EACrB,cAAc,GAAE,qBAAgD,EAChE,YAAY,GAAE,eAAoB,GACjC,OAAO,CAAC,MAAM,CAAC,CAqBjB"}

package/dist/cli.js

@@ -9,6 +9,8 @@ import { cloudApiUrl } from './cloud.js';
 import { resolveHome } from './config.js';
 import { assertInteractive, confirmPlan, credentialFingerprint, credentialStoreChoices, environmentInstructions, readAccessToken, runConfigWizard, writeCredentialFile, } from './configure.js';
 import { discoverBoundWorkspace, discoverOrganizations, workspaceChoices } from './discover.js';
+import { DEFAULT_WORKSPACE, listLocalWorkspaces, localWorkspaceHome } from './workspaces.js';
+import { findProjectSelection, resolveWorkspaceSelection, writeProjectSelection, } from './project.js';
 import { defaultPromptIo } from './prompt.js';
 import { credentialReference, OsCredentialStore } from './credentials.js';
 import { asSynomemError, SynomemError } from './errors.js';
@@ -61,11 +63,19 @@ function actor(kind, id, displayName) {
  * backend binds the credential to one actor, so SYNOMEM_ACTOR_ID/KIND/NAME must be able to
  * override them or those commands cannot authenticate.
  */
-function defaultActor(env, fallbackKind, fallbackId) {
-    const id = env.SYNOMEM_ACTOR_ID?.trim();
+function defaultActor(env, fallbackKind, fallbackId, 
+/** `--actor`, which outranks the environment: it is said on this invocation. */
+override) {
+    const id = override?.trim() || env.SYNOMEM_ACTOR_ID?.trim();
     if (!id)
         return actor(fallbackKind, fallbackId);
-    return actor(env.SYNOMEM_ACTOR_KIND?.trim() || fallbackKind, id, env.SYNOMEM_ACTOR_NAME?.trim());
+    const kind = override?.trim()
+        ? // An explicit --actor names an agent unless told otherwise; the historical
+            // fallbacks here are `system`/`cli`, which is not what somebody means when
+            // they name one.
+            env.SYNOMEM_ACTOR_KIND?.trim() || 'agent'
+        : env.SYNOMEM_ACTOR_KIND?.trim() || fallbackKind;
+    return actor(kind, id, env.SYNOMEM_ACTOR_NAME?.trim());
 }
 function taskDue(options) {
     if (options.dueDate && options.dueAt)
@@ -148,9 +158,28 @@ function showRecord(record) {
 function output(io, json, value, human) {
     io.stdout(json ? `${JSON.stringify(value, null, 2)}\n` : `${human}\n`);
 }
-function globals(command) {
-    return command.optsWithGlobals();
+/**
+ * The resolved global options for a command.
+ *
+ * `--workspace` is turned into a home HERE, before any service exists, which is
+ * the whole reason it costs nothing downstream: a local workspace is a separate
+ * database in its own home, and choosing one is choosing a home. Nothing in the
+ * domain, the commands, or the MCP tools learns that a workspace was selected.
+ *
+ * On a remote backend the name means a hosted workspace instead, which
+ * `backend use remote --workspace` already handles; passing both here would be
+ * two different answers to the same question, so it is refused.
+ */
+/** `parent child`, so a subcommand name cannot be confused with another's. */
+function commandPath(command) {
+    const parent = command.parent?.name();
+    return parent && parent !== 'synomem' ? `${parent} ${command.name()}` : command.name();
 }
+/**
+ * Commands where `--workspace` names a HOSTED workspace being configured,
+ * rather than a local one to act in.
+ */
+const CONFIGURES_BACKEND = new Set(['config init', 'backend use', 'remote import']);
 async function withService(serviceFactory, home, configuredActor, operation) {
     const client = serviceFactory({ ...(home ? { home } : {}), actor: configuredActor });
     await client.init();
@@ -195,8 +224,77 @@ function listInput(options) {
         offset: Number(options.offset),
     };
 }
-export function createCli(io = defaultIo, serviceFactory = configuredServiceFactory, dependencies = {}) {
+/**
+ * The value `--actor` should supply to commands that name an actor.
+ *
+ * Read from argv directly, before the commands are built, because Commander
+ * evaluates option defaults at DECLARATION time: a `--as` declared without one
+ * is required, and a `--as` declared with one is already satisfied. Supplying
+ * it here is a single change point instead of a fallback threaded through
+ * twenty action bodies, and `--as` still wins when both are given because an
+ * explicitly passed option overrides its default.
+ */
+function actorDefault(argv, env) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === '--actor')
+            return argv[index + 1]?.trim() || undefined;
+        if (argument.startsWith('--actor='))
+            return argument.slice('--actor='.length).trim() || undefined;
+    }
+    if (env.SYNOMEM_ACTOR_ID?.trim())
+        return env.SYNOMEM_ACTOR_ID.trim();
+    /*
+     * Last, the project's own binding. `workspace use --as` exists so a
+     * repository can settle both questions once — which workspace, and as whom —
+     * and a command run there needs neither flag afterwards.
+     */
+    try {
+        return findProjectSelection()?.actor;
+    }
+    catch {
+        // A malformed project file is reported by the resolver when the command
+        // actually runs, with the path in the message. Failing here would turn it
+        // into an error before any command had been parsed.
+        return undefined;
+    }
+}
+export function createCli(io = defaultIo, serviceFactory = configuredServiceFactory, dependencies = {}, argv = process.argv) {
     const env = dependencies.env ?? process.env;
+    const actingDefault = actorDefault(argv, env);
+    const globals = (command) => {
+        const options = command.optsWithGlobals();
+        if (CONFIGURES_BACKEND.has(commandPath(command)))
+            return options;
+        /*
+         * Resolution runs even with no `--workspace`, because a project's
+         * `.synomem/config.json` selects one without anybody passing a flag — that is
+         * the whole point of it. `--home` still wins outright: it names a home
+         * directly rather than a workspace within one.
+         */
+        if (!options.home) {
+            const selection = resolveWorkspaceSelection({
+                ...(options.workspace ? { flag: options.workspace } : {}),
+                ...(options.actor ? { actorFlag: options.actor } : {}),
+                env,
+            });
+            return { ...options, home: selection.home, actor: selection.actor ?? options.actor };
+        }
+        if (!options.workspace)
+            return options;
+        /*
+         * One flag, one meaning — "which workspace" — resolved differently by the
+         * handful of commands that CONFIGURE a backend rather than act inside one.
+         * For those, the value is a hosted workspace ID to be written to the config,
+         * so it is passed through raw and they read `workspace`. Everywhere else it
+         * names a local workspace, which is a home.
+         *
+         * These commands used to declare their own `--workspace`, which does not
+         * work: Commander gives a duplicated long flag to the parent, so the
+         * subcommand never received it at all.
+         */
+        return { ...options, home: localWorkspaceHome(options.workspace, options.home) };
+    };
     const credentialStore = dependencies.credentialStore ?? new OsCredentialStore();
     const oauthLogin = dependencies.oauthLogin ?? loginWithOAuth;
     const discoverWorkspace = dependencies.discoverBoundWorkspace ?? discoverBoundWorkspace;
@@ -224,9 +322,86 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
         .description('Local-first communication, memory, recognition, and task infrastructure for agents')
         .version(packageVersion())
         .option('--home <path>', 'storage root (defaults to SYNOMEM_HOME or ~/.synomem)')
+        // A local workspace is its own database under the root, so this selects a
+        // home. On a remote backend the hosted workspace is chosen by
+        // `backend use remote --workspace` instead.
+        .option('--workspace <name>', 'local workspace to act in (see `synomem workspace list`)')
+        .option('--actor <id>', 'act as this agent (overrides SYNOMEM_ACTOR_ID)')
         .option('--json', 'emit stable machine-readable JSON', false)
         .showSuggestionAfterError()
         .configureOutput({ writeOut: io.stdout, writeErr: io.stderr });
+    /*
+     * Local workspaces.
+     *
+     * Each is a separate database in its own home, which is what makes the
+     * isolation real: SQLite has no row-level security, so a shared file would
+     * rest on every query remembering to filter, with nothing to catch a miss.
+     * Separate files mean cross-workspace leakage is not something anybody can
+     * write by accident.
+     */
+    const workspaceCommand = program
+        .command('workspace')
+        .description('Work in a separate local store, isolated from the others');
+    workspaceCommand
+        .command('list')
+        .description('List the local workspaces on this machine')
+        .action((_options, command) => {
+        const global = globals(command);
+        // Read from disk, so nothing is listed that does not exist.
+        const workspaces = listLocalWorkspaces(global.home);
+        // Which one is in effect here, and what decided it — a flag, the
+        // environment, a project file, or nothing.
+        const selection = resolveWorkspaceSelection({ env });
+        const human = workspaces
+            .map((workspace) => `${workspace.name === DEFAULT_WORKSPACE ? '*' : ' '} ${workspace.name.padEnd(24)} ${workspace.initialized ? workspace.home : `${workspace.home} (not initialized)`}`)
+            .join('\n');
+        output(io, global.json, { workspaces, active: selection.workspace ?? DEFAULT_WORKSPACE, source: selection.source }, [
+            human,
+            '',
+            `Acting in: ${selection.workspace ?? DEFAULT_WORKSPACE}  (from ${selection.source})`,
+            '',
+            'Bind a directory with `synomem workspace use <name>`, or pass --workspace once.',
+            'A local workspace is a separate store on this machine; a hosted workspace is shared,',
+            'and is selected with `backend use remote --workspace`.',
+        ].join('\n'));
+    });
+    workspaceCommand
+        .command('use <name>')
+        .description('Bind this directory to a workspace, for every session opened here')
+        .option('--as <actor-id>', 'also always write as this agent', actingDefault)
+        .action((name, options, command) => {
+        const global = globals(command);
+        // Validated by resolving it, so a name that could never work is refused
+        // before a file claiming it is written.
+        const home = localWorkspaceHome(name, undefined);
+        const path = writeProjectSelection(process.cwd(), {
+            workspace: name,
+            ...(options.as ? { actor: options.as } : {}),
+        });
+        output(io, global.json, { path, workspace: name, home, ...(options.as ? { actor: options.as } : {}) }, [
+            `Wrote ${path}`,
+            '',
+            `Every Synomem command and MCP server started in this directory now acts in ${name}${options.as ? ` as ${options.as}` : ''}, with no flag.`,
+            `Records live in ${home} — nothing is stored in this directory.`,
+            '',
+            'Commit it to share the choice with the repository, or ignore it to keep it yours.',
+        ].join('\n'));
+    });
+    workspaceCommand
+        .command('create <name>')
+        .description('Create a local workspace and initialize its store')
+        .action(async (name, _options, command) => {
+        const global = globals(command);
+        const home = localWorkspaceHome(name, global.home);
+        if (readSynomemConfig(home)) {
+            throw new SynomemError('INVALID_INPUT', `Workspace already exists: ${name}`);
+        }
+        writeSynomemBackend({ kind: 'local' }, home);
+        // Opening it once creates the database, so `list` does not report a
+        // workspace that exists in name only.
+        await withClient(home, defaultActor(env, 'system', 'cli'), async () => undefined);
+        output(io, global.json, { name, home }, `Created workspace ${name} at ${home}.\nAct in it with --workspace ${name}.`);
+    });
     const remoteCommand = program.command('remote').description('Administer a remote workspace');
     /*
      * The browser counterpart to an access key naming its own workspace.
@@ -449,7 +624,6 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
         .description('Configure Synomem without prompting')
         .option('--backend <kind>', 'local or remote')
         .option('--auth <method>', 'browser or access-key')
-        .option('--workspace <id>', 'remote workspace ID')
         .option('--credential-store <where>', 'auto, keychain, file, or environment', 'auto')
         // The token is read from stdin, never taken as an argument: an argument is
         // kept by the shell history and visible in the process list.
@@ -463,7 +637,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
         const backend = options.backend;
         // An access key names its own workspace, so --workspace is only
         // required when there is no key to ask.
-        if (backend === 'remote' && !options.workspace && !options.accessTokenStdin) {
+        if (backend === 'remote' && !global.workspace && !options.accessTokenStdin) {
             throw new SynomemError('INVALID_INPUT', 'Remote setup requires --workspace, or --access-token-stdin so the key can name its own.');
         }
         const token = options.accessTokenStdin ? await readAccessToken(promptIo) : undefined;
@@ -477,7 +651,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
                 ? {
                     serviceUrl: cloudApiUrl(env),
                     auth: options.auth ?? 'access-key',
-                    workspaceId: options.workspace,
+                    workspaceId: global.workspace,
                     credentialStore: options.credentialStore,
                 }
                 : {}),
@@ -594,13 +768,12 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
         // never ask for a service address, because a person has no way to tell a
         // real one from a phished one.
         .option('--url <url>', 'internal: alternate HTTPS origin')
-        .option('--workspace <id>', 'remote workspace ID')
         .action((kind, options, command) => {
         const global = globals(command);
         if (kind !== 'local' && kind !== 'remote') {
             throw new SynomemError('INVALID_INPUT', 'Backend kind must be local or remote.');
         }
-        if (kind === 'remote' && !options.workspace) {
+        if (kind === 'remote' && !global.workspace) {
             throw new SynomemError('INVALID_INPUT', 'Remote backend selection requires --workspace.');
         }
         const config = writeSynomemBackend(kind === 'local'
@@ -608,7 +781,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
             : {
                 kind: 'remote',
                 baseUrl: options.url ?? cloudApiUrl(env),
-                workspaceId: options.workspace,
+                workspaceId: global.workspace,
             }, global.home);
         output(io, global.json, { backend: config.backend }, `Selected ${config.backend.kind} Synomem backend.`);
     });
@@ -1066,7 +1239,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     postCommand
         .command('create')
         .description('Publish a post the whole workspace can read')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
         .requiredOption('--title <title>')
         .requiredOption('--body <body>')
@@ -1085,7 +1258,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     postCommand
         .command('list')
         .description('List posts in this workspace')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
         .option('--limit <n>', 'default 10, maximum 50')
         .action(async (options, command) => {
@@ -1099,7 +1272,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     postCommand
         .command('show <post-id>')
         .description('Show one post with its acknowledgements')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
         .action(async (postId, options, command) => {
         const global = globals(command);
@@ -1114,7 +1287,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     postCommand
         .command('acknowledge <post-id>')
         .description('Say you have seen a post')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
         .option('--note <text>', 'optional context for the author')
         .action(async (postId, options, command) => {
@@ -1128,7 +1301,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     postCommand
         .command('roster <post-id>')
         .description('Who has acknowledged a post, and who has not')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
         .action(async (postId, options, command) => {
         const global = globals(command);
@@ -1153,7 +1326,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     postCommand
         .command('archive <post-id>')
         .description('Archive a post you wrote')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
         .option('--reason <text>')
         .action(async (postId, options, command) => {
@@ -1165,7 +1338,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     kudosCommand
         .command('give <recipient>')
         .description('Give specific, evidence-based kudos to an agent')
-        .requiredOption('--from <actor-id>', 'stable ID of the giver')
+        .requiredOption('--from <actor-id>', 'stable ID of the giver (defaults to --actor)', actingDefault)
         .requiredOption('--actor-kind <kind>', 'human, agent, or system')
         .option('--actor-name <display-name>')
         .requiredOption('--title <title>')
@@ -1258,7 +1431,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     const memoCommand = program.command('memo').description('Send and manage durable messages');
     memoCommand
         .command('send <recipient>')
-        .requiredOption('--from <actor-id>')
+        .requiredOption('--from <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
         .option('--actor-name <name>')
         .requiredOption('--subject <subject>')
@@ -1319,7 +1492,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
         .description('Retain and revise agent-owned knowledge');
     noteCommand
         .command('create')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'agent or human', 'agent')
         .option('--owner <agent-id>')
         .requiredOption('--title <title>')
@@ -1358,7 +1531,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     });
     noteCommand
         .command('revise <note-id>')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'agent or human', 'agent')
         .requiredOption('--expected-version <number>')
         .option('--title <title>')
@@ -1379,7 +1552,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     });
     noteCommand
         .command('archive <note-id>')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'agent or human', 'agent')
         .option('--idempotency-key <key>')
         .action(async (id, options, command) => {
@@ -1395,7 +1568,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
         .description('Create and manage your own private reminders');
     todoCommand
         .command('create')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
         .requiredOption('--title <title>')
         .option('--details <text>', 'private working detail')
@@ -1419,7 +1592,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     });
     todoCommand
         .command('list')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
         .option('--status <status>')
         .option('--limit <number>', 'maximum results', '10')
@@ -1437,7 +1610,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     });
     todoCommand
         .command('show <todo-id>')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
         .action(async (id, options, command) => {
         const global = globals(command);
@@ -1447,7 +1620,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     for (const operation of ['complete', 'reopen', 'cancel', 'archive']) {
         todoCommand
             .command(`${operation} <todo-id>`)
-            .requiredOption('--as <actor-id>')
+            .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
             .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
             .option('--note <text>')
             .option('--reason <text>')
@@ -1485,7 +1658,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     const taskCommand = program.command('task').description('Create and manage agent tasks');
     taskCommand
         .command('create <assignee>')
-        .requiredOption('--from <actor-id>')
+        .requiredOption('--from <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
         .requiredOption('--title <title>')
         .option('--description <text>')
@@ -1531,7 +1704,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     });
     taskCommand
         .command('update <task-id>')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'agent or human', 'agent')
         .requiredOption('--expected-version <number>')
         .option('--title <title>')
@@ -1561,7 +1734,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     for (const operation of ['accept', 'reject', 'complete', 'reopen', 'cancel']) {
         const command_ = taskCommand
             .command(`${operation} <task-id>`)
-            .requiredOption('--as <actor-id>')
+            .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
             .option('--actor-kind <kind>', 'agent or human', 'agent')
             .option('--note <text>')
             .option('--reason <text>')
@@ -1637,7 +1810,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     kudosCommand
         .command('revoke <kudos-id>')
         .description('Record a revocation while preserving history')
-        .requiredOption('--as <actor-id>')
+        .requiredOption('--as <actor-id>', 'actor to act as (defaults to --actor)', actingDefault)
         .option('--actor-kind <kind>', 'human, agent, or system', 'human')
         .requiredOption('--reason <reason>')
         .option('--administrative', 'mark as an administrative revocation', false)
@@ -1779,7 +1952,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     return program;
 }
 export async function runCli(argv = process.argv, io = defaultIo, serviceFactory = configuredServiceFactory, dependencies = {}) {
-    const program = createCli(io, serviceFactory, dependencies);
+    const program = createCli(io, serviceFactory, dependencies, argv);
     program.exitOverride();
     try {
         await program.parseAsync(argv);