synomem 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,55 @@ All notable changes will be documented here. The format follows
 
 ### Changed
 
+- **Agents have an opaque canonical ID and a separate handle.** `agent create
+<handle>` generates a ULID; the handle is what people type and can be renamed
+  with `agent rename` without orphaning the events written under the old name.
+  Events, rosters and statistics key on the canonical ID.
+- The home IS the storage directory. It was `<home>/synomem`, which produced
+  `~/.synomem/synomem` once the home moved — a path the layout rules out.
+- The default home is `~/.synomem`. There is no detection of or migration from
+  `~/.agents`, per the greenfield policy.
+- Projection directories are named by handle, since they exist to be read.
+
+### Added
+
+- **`synomem config`** — the onboarding wizard, with `configure` and `setup` as
+  aliases. It refuses to run without a terminal and names the deterministic
+  flags instead of blocking forever on a pipe.
+- **`synomem config init`** — the non-interactive equivalent, including
+  `--access-token-stdin` so an installation key is never passed as an argument
+  where the shell history and process list would keep it.
+- **`synomem config show`** — reports where a credential comes from, never the
+  credential.
+- **`synomem reset`** — lists every exact target before removing anything.
+  Installed skills and MCP registrations are left alone unless
+  `--integrations` is passed.
+- Synomem Cloud is implicit: `backend use remote` needs only `--workspace`.
+  `--url` remains for private deployments and stays out of the public docs.
+- A discriminated credential model, so an installation key is no longer treated
+  as a refreshable OAuth credential.
+- `agent rename`, `agent archive`, `agent restore`, and `agent alias add` /
+  `alias remove`, which add and remove aliases without replacing the set.
+- The MCP server reports the canonical actor rather than the requested name, so
+  a misconfigured runtime cannot appear to act as somebody it is not.
+
+### Schema
+
+- Version 7 adds `agents.handle` (backfilled from the ID, uniquely indexed) and
+  `agents.status`. Existing agents keep their name-shaped ID; only new agents
+  get a generated one.
+
+### Added
+
+- Posts: publication to everyone in a workspace, with per-actor acknowledgements
+  so an author can see who has responded. A post has no recipient and no
+  assignee — work for one actor is a memo or a task.
+- `post roster` answers who has acknowledged and who has not, counting agents
+  created after the post separately rather than listing them as outstanding.
+- Schema version 6 adds `post_acknowledgments`.
+
+### Changed
+
 - The MCP server binds to an agent with `--agent-id`, reading the display name and actor kind from
   the agent's profile. `synomem skill install --agent <id-or-alias>` resolves the agent before
   writing anything, records a runtime binding for each runtime it installs, and generates a

package/README.md

@@ -51,7 +51,7 @@ and opens no network listener.
 ```bash
 npm install --global synomem
 
-export SYNOMEM_HOME="$(mktemp -d)/.agents"
+export SYNOMEM_HOME="$(mktemp -d)/.synomem"
 synomem init
 synomem agent create codex --name "Codex"
 synomem agent create gracie --name "Gracie"
@@ -93,12 +93,12 @@ terminal-capable agent. The Synomem package contains the portable
 installer for the six named local harnesses.
 
 ```text
-Set up Synomem for this agent and runtime. Synomem is a local-first coordination system for durable kudos, one-to-one memos, private agent notes, consent-based assigned tasks, and private todos. It uses an append-only SQLite database under ~/.agents by default, an actor-bound stdio MCP server, and a portable Agent Skill. Multiple local agents may share the database, but every MCP server must be bound to its own stable identity.
+Set up Synomem for this agent and runtime. Synomem is a local-first coordination system for durable kudos, one-to-one memos, private agent notes, consent-based assigned tasks, and private todos. It uses an append-only SQLite database under ~/.synomem by default, an actor-bound stdio MCP server, and a portable Agent Skill. Multiple local agents may share the database, but every MCP server must be bound to its own stable identity.
 
 Work autonomously through the safe, reversible steps below. Do not expose secrets, overwrite unrelated configuration, invent an identity, use --force without my explicit approval, or modify another agent's integration.
 
 1. Verify Node.js 22.13+ and npm are available. Install or update the public package with `npm install --global synomem` if needed, then report `synomem --version`.
-2. Preserve an existing `SYNOMEM_HOME`; otherwise use the default ~/.agents. Run `synomem init`, then `synomem doctor`. Never point tests or experiments at another Synomem home.
+2. Preserve an existing `SYNOMEM_HOME`; otherwise use the default ~/.synomem. Run `synomem init`, then `synomem doctor`. Never point tests or experiments at another Synomem home.
 3. Run `synomem agent list`. Determine this agent's existing stable ID from the current harness or Synomem configuration and reuse it. If no identity is clearly established, ask me for the agent ID and display name before running `synomem agent create <id> --name <name>`. Never silently merge or rename identities.
 4. Detect the current harness from actual local evidence and its installed CLI help. Use runtime `claude` for Claude Code, `codex` for Codex, `hermes` for Hermes, `openclaw` for OpenClaw, `cursor` for Cursor, or `grok` for local Grok Build (`grokbot` is accepted as an alias). Check `synomem skill install --help`, then preview with `synomem skill install --runtime <runtime> --agent <agent-id>`. Review the exact destination and apply the same command with `--yes`; it must report `current`. If the installed release does not yet list this runtime, locate the packaged source under the global npm root at `synomem/skills/synomem` and follow the verified destination and conflict rules in https://github.com/Coaden/synomem/blob/main/docs/skill.md instead. Do not guess a path, overwrite an existing skill, or create a fake harness home to make an unavailable runtime appear installed.
 5. Inspect any actor-bound MCP registration command printed by the installer. Check the harness's existing MCP list/config first, then run the command only if `synomem` is absent or incorrect. Do not create duplicates. Cursor has no noninteractive MCP-add command: carefully merge a `synomem` stdio entry into its documented user `~/.cursor/mcp.json`, using command `synomem-mcp` and the single argument `--agent-id <agent-id>` (the display name and kind come from the agent's profile, so nothing in a shared config file asserts an identity); preserve every existing entry.
@@ -202,7 +202,7 @@ are `claude`, `codex`, `hermes`, `openclaw`, `cursor`, and `grok`; `grokbot` ali
 ## Storage
 
 ```text
-~/.agents/
+~/.synomem/
 ├── synomem/
 │   ├── config.json
 │   └── synomem.sqlite3

package/dist/backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAS5C,OAAO,EAAiC,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGlF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,KAAK,EAEV,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,EACd,MAAM,YAAY,CAAC;AAYpB,wBAAgB,iBAAiB,CAC/B,YAAY,CAAC,EAAE,MAAM,EACrB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,aAAa,GAAG,SAAS,CAQ3B;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,oBAAoB,EAC7B,YAAY,CAAC,EAAE,MAAM,GACpB,aAAa,CAef;AAED,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,oBAAyB,EAClC,GAAG,GAAE,MAAM,CAAC,UAAwB,wCAmBrC;AAED,eAAO,MAAM,wBAAwB,EAAE,qBACL,CAAC"}
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAS5C,OAAO,EAAiC,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGlF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,KAAK,EAEV,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,EACd,MAAM,YAAY,CAAC;AAkBpB,wBAAgB,iBAAiB,CAC/B,YAAY,CAAC,EAAE,MAAM,EACrB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,aAAa,GAAG,SAAS,CAQ3B;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,oBAAoB,EAC7B,YAAY,CAAC,EAAE,MAAM,GACpB,aAAa,CAef;AAED,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,oBAAyB,EAClC,GAAG,GAAE,MAAM,CAAC,UAAwB,wCAmBrC;AAED,eAAO,MAAM,wBAAwB,EAAE,qBACL,CAAC"}

package/dist/backend.js

@@ -9,9 +9,15 @@ import { environmentCredentialProvider, RemoteSynomemService } from './remote.js
 import { credentialReference, OsCredentialStore } from './credentials.js';
 import { StoredCredentialProvider } from './oauth.js';
 function configLocation(explicitHome) {
+    /*
+     * The home IS the storage directory. It used to be `<home>/synomem`, which
+     * made sense while the default home was `~/.agents` and Synomem was one
+     * tenant inside it. Now that the home is `~/.synomem`, that nesting produces
+     * `~/.synomem/synomem` — a path the layout explicitly rules out, and one that
+     * makes every documented path wrong by a level.
+     */
     const home = resolveHome(explicitHome);
-    const storageDirectory = join(home, 'synomem');
-    return { home, storageDirectory, configPath: join(storageDirectory, 'config.json') };
+    return { home, storageDirectory: home, configPath: join(home, 'config.json') };
 }
 export function readSynomemConfig(explicitHome, env = process.env) {
     const { home, storageDirectory, configPath } = configLocation(explicitHome);

package/dist/backend.js.map

@@ -1 +1 @@
-{"version":3,"file":"backend.js","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
+import { type PromptIo } from './prompt.js';
 import { type CredentialStore } from './credentials.js';
 import { type OAuthLoginOptions } from './oauth.js';
 import { type ImportBundle, type ImportPreview, type ImportResult } from './import.js';
@@ -10,6 +11,8 @@ export interface CliIo {
     stderr: (text: string) => void;
 }
 export interface CliDependencies {
+    /** Injected so the wizard can be driven by a test without a terminal. */
+    promptIo?: PromptIo;
     credentialStore?: CredentialStore;
     oauthLogin?: (options: OAuthLoginOptions) => Promise<void>;
     env?: NodeJS.ProcessEnv;

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;AAE5D,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,EAQd,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,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;IACpB,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,CA8qDT;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;AAkB5D,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,EAQd,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;IACpB,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,CAuqET;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

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, rmSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { Command, CommanderError, Option } from 'commander';
 import { configuredServiceFactory, readSynomemConfig, writeSynomemBackend } from './backend.js';
+import { cloudApiUrl } from './cloud.js';
+import { resolveHome } from './config.js';
+import { assertInteractive, confirmPlan, credentialFingerprint, credentialStoreChoices, environmentInstructions, readAccessToken, runConfigWizard, writeCredentialFile, } from './configure.js';
+import { defaultPromptIo } from './prompt.js';
 import { credentialReference, OsCredentialStore } from './credentials.js';
 import { asSynomemError, SynomemError } from './errors.js';
 import { atomicWriteFile } from './fs-utils.js';
@@ -194,6 +198,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
     const env = dependencies.env ?? process.env;
     const credentialStore = dependencies.credentialStore ?? new OsCredentialStore();
     const oauthLogin = dependencies.oauthLogin ?? loginWithOAuth;
+    const promptIo = dependencies.promptIo ?? defaultPromptIo();
     const verifyRemoteCredential = dependencies.verifyRemoteCredential ??
         (async (options) => {
             const remote = new RemoteSynomemService({
@@ -216,7 +221,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
         .name('synomem')
         .description('Local-first communication, memory, recognition, and task infrastructure for agents')
         .version(packageVersion())
-        .option('--home <path>', 'storage root (defaults to SYNOMEM_HOME or ~/.agents)')
+        .option('--home <path>', 'storage root (defaults to SYNOMEM_HOME or ~/.synomem)')
         .option('--json', 'emit stable machine-readable JSON', false)
         .showSuggestionAfterError()
         .configureOutput({ writeOut: io.stdout, writeErr: io.stderr });
@@ -292,6 +297,208 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
             output(io, options.json, { home: info.home, database: info.databasePath }, `Initialized Synomem at ${info.home}`);
         });
     });
+    /*
+     * `synomem config` is the canonical entry point. `configure` and `setup` are
+     * accepted because people reach for them, and a setup program that rejects
+     * the word somebody guessed is needlessly unhelpful.
+     */
+    const configCommand = program
+        .command('config')
+        .aliases(['configure', 'setup'])
+        .description('Set up Synomem, interactively or deterministically');
+    const applyPlan = async (plan, token, global) => {
+        const home = plan.home;
+        const config = writeSynomemBackend(plan.backend === 'local'
+            ? { kind: 'local' }
+            : {
+                kind: 'remote',
+                baseUrl: plan.serviceUrl ?? cloudApiUrl(env),
+                workspaceId: plan.workspaceId,
+            }, home);
+        let credentialLocation;
+        if (token) {
+            if (plan.credentialStore === 'environment') {
+                io.stdout(`${environmentInstructions(token)}\n`);
+                credentialLocation = 'environment';
+            }
+            else if (plan.credentialStore === 'file') {
+                credentialLocation = writeCredentialFile(home, token);
+            }
+            else {
+                // The platform store is the default, and a failure falls back to the
+                // restricted file rather than leaving the credential nowhere.
+                try {
+                    await credentialStore.set(`synomem:${plan.workspaceId}`, {
+                        kind: 'installation-key',
+                        accessToken: token,
+                    });
+                    credentialLocation = 'platform credential store';
+                }
+                catch {
+                    credentialLocation = writeCredentialFile(home, token);
+                }
+            }
+        }
+        // Diagnostics run before success is claimed: a configuration that cannot
+        // open its own database is not a finished setup.
+        const diagnostics = await withClient(home, defaultActor(env, 'system', 'cli'), (client) => client.doctor());
+        output(io, global.json, {
+            backend: config.backend,
+            home,
+            ...(credentialLocation ? { credentialSource: credentialLocation } : {}),
+            ...(token ? { credential: credentialFingerprint(token) } : {}),
+            healthy: diagnostics.healthy,
+        }, [
+            '',
+            'Synomem is ready.',
+            '',
+            `  Backend:  ${config.backend.kind === 'local' ? 'Local SQLite' : 'Synomem Cloud'}`,
+            `  Home:     ${home}`,
+            ...(config.backend.kind === 'remote'
+                ? [`  Service:  ${config.backend.baseUrl}`, `  Workspace: ${config.backend.workspaceId}`]
+                : []),
+            ...(credentialLocation ? [`  Credential: ${credentialLocation}`] : []),
+            `  Database: ${diagnostics.healthy ? 'Healthy' : 'Needs attention — run synomem doctor'}`,
+        ].join('\n'));
+    };
+    configCommand.action(async (_options, command) => {
+        const global = globals(command);
+        assertInteractive(promptIo);
+        const plan = await runConfigWizard(promptIo, {
+            ...(global.home ? { home: global.home } : {}),
+            env,
+        });
+        const token = plan.auth === 'access-key' ? await readAccessToken(promptIo) : undefined;
+        if (!(await confirmPlan(promptIo, plan))) {
+            output(io, global.json, { applied: false }, 'Nothing was changed.');
+            return;
+        }
+        await applyPlan(plan, token, global);
+    });
+    configCommand
+        .command('init')
+        .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.
+        .option('--access-token-stdin', 'read the installation access key from stdin', false)
+        .option('--yes', 'apply without confirming', false)
+        .action(async (options, command) => {
+        const global = globals(command);
+        if (options.backend !== 'local' && options.backend !== 'remote') {
+            throw new SynomemError('INVALID_INPUT', 'Pass --backend local or --backend remote.');
+        }
+        const backend = options.backend;
+        if (backend === 'remote' && !options.workspace) {
+            throw new SynomemError('INVALID_INPUT', 'Remote setup requires --workspace.');
+        }
+        const token = options.accessTokenStdin ? await readAccessToken(promptIo) : undefined;
+        if (backend === 'remote' && options.auth === 'access-key' && !token) {
+            throw new SynomemError('INVALID_INPUT', 'Access-key setup requires --access-token-stdin so the key is not passed as an argument.');
+        }
+        const plan = {
+            backend,
+            home: resolveHome(global.home),
+            ...(backend === 'remote'
+                ? {
+                    serviceUrl: cloudApiUrl(env),
+                    auth: options.auth ?? 'access-key',
+                    workspaceId: options.workspace,
+                    credentialStore: options.credentialStore,
+                }
+                : {}),
+        };
+        if (!options.yes) {
+            throw new SynomemError('INVALID_INPUT', 'Re-run with --yes to apply this configuration.');
+        }
+        await applyPlan(plan, token, global);
+    });
+    configCommand
+        .command('show')
+        .description('Show the current configuration without revealing secrets')
+        .action(async (_options, command) => {
+        const global = globals(command);
+        const home = resolveHome(global.home);
+        const config = readSynomemConfig(global.home, env);
+        const backend = config?.backend ?? { kind: 'local' };
+        const credentialSource = env.SYNOMEM_ACCESS_TOKEN
+            ? 'environment (SYNOMEM_ACCESS_TOKEN)'
+            : existsSync(join(home, 'credentials', 'installation.json'))
+                ? 'restricted file'
+                : 'platform credential store or none';
+        output(io, global.json, 
+        // Never the secret itself, only where it comes from.
+        { backend, home, credentialSource, stores: credentialStoreChoices().map((c) => c.value) }, [
+            `Backend:    ${backend.kind === 'local' ? 'Local SQLite' : 'Synomem Cloud'}`,
+            `Home:       ${home}`,
+            ...(backend.kind === 'remote'
+                ? [`Service:    ${backend.baseUrl}`, `Workspace:  ${backend.workspaceId}`]
+                : []),
+            `Credential: ${credentialSource}`,
+        ].join('\n'));
+    });
+    program
+        .command('reset')
+        .description('Remove Synomem configuration, database and credentials')
+        // Integrations are opt-in because they live in other tools' directories.
+        // Removing somebody's harness configuration as a side effect of resetting
+        // Synomem would be a surprise with no undo.
+        .option('--integrations', 'also remove installed skills and MCP registrations', false)
+        .option('--yes', 'apply the displayed plan', false)
+        .action(async (options, command) => {
+        const global = globals(command);
+        const home = resolveHome(global.home);
+        /*
+         * Every target is an exact path, listed before anything is touched. No
+         * recursive delete is ever derived from a variable that might be empty:
+         * a reset that computes `rm -rf $HOME/` from an unset home is the
+         * failure this shape exists to make impossible.
+         */
+        const targets = [
+            join(home, 'config.json'),
+            join(home, 'synomem.sqlite3'),
+            join(home, 'synomem.sqlite3-wal'),
+            join(home, 'synomem.sqlite3-shm'),
+            join(home, 'credentials', 'installation.json'),
+        ].filter((path) => existsSync(path));
+        const skillPlan = options.integrations ? uninstallSkill({ apply: false }) : undefined;
+        const skillTargets = skillPlan?.locations
+            // Installed Synomem-owned copies only; an unowned directory at
+            // the same path is not ours to remove.
+            .filter((location) => location.state === 'current' || location.state === 'stale')
+            .map((location) => location.target) ?? [];
+        if (!options.yes) {
+            output(io, global.json, { targets, skillTargets, applied: false }, [
+                'This will remove:',
+                ...(targets.length ? targets.map((path) => `  ${path}`) : ['  (nothing found)']),
+                ...(skillTargets.length ? ['', 'And these Synomem-owned skills:'] : []),
+                ...skillTargets.map((path) => `  ${path}`),
+                '',
+                ...(options.integrations
+                    ? []
+                    : ['Installed skills and MCP registrations are left alone.', '']),
+                'Run with --yes to continue.',
+            ].join('\n'));
+            return;
+        }
+        const removed = [];
+        for (const path of targets) {
+            rmSync(path, { force: true });
+            removed.push(path);
+        }
+        // Only ownership-stamped Synomem skills are removed, which uninstall
+        // already enforces — an unowned directory at the same path is left.
+        const skillResult = options.integrations ? uninstallSkill({ apply: true }) : undefined;
+        output(io, global.json, { removed, skills: skillResult?.locations ?? [] }, [
+            `Removed ${removed.length} file(s).`,
+            ...(skillResult
+                ? [`Skill locations processed: ${skillResult.locations.length}.`]
+                : ['Installed skills and MCP registrations were left alone.']),
+        ].join('\n'));
+    });
     const backendCommand = program
         .command('backend')
         .description('Inspect or select the canonical backend');
@@ -311,19 +518,27 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
         .command('use')
         .description('Select local or remote canonical state')
         .argument('<kind>', 'local or remote')
-        .option('--url <url>', 'remote HTTPS origin')
+        // --url is for development and private deployments. It stays out of the
+        // README, the public docs and the packaged skill: public onboarding must
+        // 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.url || !options.workspace)) {
-            throw new SynomemError('INVALID_INPUT', 'Remote backend selection requires --url and --workspace.');
+        if (kind === 'remote' && !options.workspace) {
+            throw new SynomemError('INVALID_INPUT', 'Remote backend selection requires --workspace.');
         }
         const config = writeSynomemBackend(kind === 'local'
             ? { kind: 'local' }
-            : { kind: 'remote', baseUrl: options.url, workspaceId: options.workspace }, global.home);
+            : {
+                kind: 'remote',
+                baseUrl: options.url ?? cloudApiUrl(env),
+                workspaceId: options.workspace,
+            }, global.home);
         output(io, global.json, { backend: config.backend }, `Selected ${config.backend.kind} Synomem backend.`);
     });
     const authCommand = program.command('auth').description('Inspect remote authentication');
@@ -419,20 +634,65 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
         .command('agent')
         .description('Create and inspect stable agent identities');
     agentCommand
-        .command('create <id>')
-        .description('Create a stable agent profile')
+        .command('create <handle>')
+        .description('Create an agent. The canonical ID is generated, not chosen.')
         .requiredOption('--name <display-name>', 'display name')
-        .option('--alias <id>', 'alias (repeatable)', collect, [])
+        .option('--alias <name>', 'alias (repeatable)', collect, [])
         .option('--description <text>')
-        .action(async (id, options, command) => {
+        .action(async (handle, options, command) => {
         const global = globals(command);
         const profile = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) => client.agents.create({
-            id,
+            handle,
             displayName: options.name,
             ...(options.alias.length ? { aliases: options.alias } : {}),
             ...(options.description ? { description: options.description } : {}),
         }));
-        output(io, global.json, profile, `Created ${profile.displayName} (${profile.id})`);
+        // Both are printed because both matter: the handle is what people type,
+        // the ID is what every event records and what MCP registration uses.
+        output(io, global.json, profile, `Created ${profile.displayName}\n\nHandle:   ${profile.handle}\nAgent ID: ${profile.id}`);
+    });
+    const aliasCommand = agentCommand
+        .command('alias')
+        .description('Add or remove discovery aliases without replacing the set');
+    aliasCommand
+        .command('add <agent> <alias...>')
+        .description('Add aliases, keeping the ones already there')
+        .action(async (agent, aliases, _options, command) => {
+        const global = globals(command);
+        const profile = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) => client.agents.addAliases(agent, aliases));
+        output(io, global.json, profile, `Aliases: ${(profile.aliases ?? []).join(', ') || 'none'}`);
+    });
+    aliasCommand
+        .command('remove <agent> <alias...>')
+        .description('Remove aliases, keeping the rest')
+        .action(async (agent, aliases, _options, command) => {
+        const global = globals(command);
+        const profile = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) => client.agents.removeAliases(agent, aliases));
+        output(io, global.json, profile, `Aliases: ${(profile.aliases ?? []).join(', ') || 'none'}`);
+    });
+    agentCommand
+        .command('rename <agent> <handle>')
+        .description('Change an agent handle. Its canonical ID never changes.')
+        .action(async (agent, handle, _options, command) => {
+        const global = globals(command);
+        const profile = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) => client.agents.update(agent, { handle }));
+        output(io, global.json, profile, `Handle:   ${profile.handle}\nAgent ID: ${profile.id} (unchanged)`);
+    });
+    agentCommand
+        .command('archive <agent>')
+        .description('Stop an agent acting, keeping its records and history')
+        .action(async (agent, _options, command) => {
+        const global = globals(command);
+        const profile = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) => client.agents.archive(agent));
+        output(io, global.json, profile, `Archived ${profile.handle} (${profile.id})`);
+    });
+    agentCommand
+        .command('restore <agent>')
+        .description('Let an archived agent act again')
+        .action(async (agent, _options, command) => {
+        const global = globals(command);
+        const profile = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) => client.agents.restore(agent));
+        output(io, global.json, profile, `Restored ${profile.handle} (${profile.id})`);
     });
     const skillCommand = program
         .command('skill')
@@ -528,7 +788,10 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
         const agents = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) => client.agents.list());
         const human = agents.length
             ? agents
-                .map((profile) => `${profile.id}  ${profile.displayName}${profile.aliases?.length ? `  aliases: ${profile.aliases.join(', ')}` : ''}`)
+                .map((profile) => 
+            // Handle first: it is what people type. The canonical ID
+            // follows because MCP registration needs it.
+            `${profile.handle}  ${profile.displayName}${profile.status === 'archived' ? '  [archived]' : ''}${profile.aliases?.length ? `  aliases: ${profile.aliases.join(', ')}` : ''}\n  ${profile.id}`)
                 .join('\n')
             : 'No agents configured.';
         output(io, global.json, { agents }, human);
@@ -539,7 +802,7 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
         .action(async (id, _options, command) => {
         const global = globals(command);
         const profile = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) => client.agents.get(id));
-        output(io, global.json, profile, `${profile.displayName} (${profile.id})\n${profile.description ?? 'No description.'}`);
+        output(io, global.json, profile, `${profile.displayName}\n\nHandle:   ${profile.handle}\nAgent ID: ${profile.id}\nStatus:   ${profile.status}\n\n${profile.description ?? 'No description.'}`);
     });
     agentCommand
         .command('update <id>')
@@ -636,6 +899,105 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
         const removed = await withClient(global.home, defaultActor(env, 'system', 'cli'), (client) => client.agents.unbindRuntime(bindingId));
         output(io, global.json, { removed }, removed ? `Removed binding ${bindingId}.` : `No binding ${bindingId}.`);
     });
+    const postCommand = program.command('post').description('Publish to everyone in the workspace');
+    postCommand
+        .command('create')
+        .description('Publish a post the whole workspace can read')
+        .requiredOption('--as <actor-id>')
+        .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
+        .requiredOption('--title <title>')
+        .requiredOption('--body <body>')
+        .option('--tag <tag>', 'repeatable', collect, [])
+        .option('--reply-to <post-id>')
+        .action(async (options, command) => {
+        const global = globals(command);
+        const result = await withClient(global.home, actor(options.actorKind, options.as), (client) => client.posts.create({
+            title: options.title,
+            body: options.body,
+            ...(options.tag.length ? { tags: options.tag } : {}),
+            ...(options.replyTo ? { replyTo: options.replyTo } : {}),
+        }));
+        output(io, global.json, result, `Published ${result.record.event.id}`);
+    });
+    postCommand
+        .command('list')
+        .description('List posts in this workspace')
+        .requiredOption('--as <actor-id>')
+        .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
+        .option('--limit <n>', 'default 10, maximum 50')
+        .action(async (options, command) => {
+        const global = globals(command);
+        const page = await withClient(global.home, actor(options.actorKind, options.as), (client) => client.posts.list(options.limit ? { limit: Number(options.limit) } : {}));
+        const human = page.items.length
+            ? page.items.map((item) => `${item.id}  ${item.title}`).join('\n')
+            : 'No posts yet.';
+        output(io, global.json, page, human);
+    });
+    postCommand
+        .command('show <post-id>')
+        .description('Show one post with its acknowledgements')
+        .requiredOption('--as <actor-id>')
+        .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
+        .action(async (postId, options, command) => {
+        const global = globals(command);
+        const record = await withClient(global.home, actor(options.actorKind, options.as), (client) => client.posts.get(postId));
+        const acks = record.acknowledgments.length
+            ? record.acknowledgments
+                .map((entry) => `  ${entry.actor.id}${entry.note ? ` — ${entry.note}` : ''}`)
+                .join('\n')
+            : '  none yet';
+        output(io, global.json, record, `${record.title}\n\n${record.body}\n\nAcknowledged by:\n${acks}`);
+    });
+    postCommand
+        .command('acknowledge <post-id>')
+        .description('Say you have seen a post')
+        .requiredOption('--as <actor-id>')
+        .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
+        .option('--note <text>', 'optional context for the author')
+        .action(async (postId, options, command) => {
+        const global = globals(command);
+        const record = await withClient(global.home, actor(options.actorKind, options.as), (client) => client.posts.acknowledge({
+            postId,
+            ...(options.note ? { note: options.note } : {}),
+        }));
+        output(io, global.json, record, `Acknowledged ${postId}`);
+    });
+    postCommand
+        .command('roster <post-id>')
+        .description('Who has acknowledged a post, and who has not')
+        .requiredOption('--as <actor-id>')
+        .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
+        .action(async (postId, options, command) => {
+        const global = globals(command);
+        const roster = await withClient(global.home, actor(options.actorKind, options.as), (client) => client.posts.roster(postId));
+        // "Outstanding" means no acknowledgement recorded — never that somebody
+        // has not read it, which this cannot know.
+        const lines = [
+            `Acknowledged (${roster.acknowledged.length}):`,
+            ...(roster.acknowledged.length
+                ? roster.acknowledged.map((entry) => `  ${entry.actor.id}`)
+                : ['  none yet']),
+            `No acknowledgement recorded (${roster.outstanding.length}):`,
+            ...(roster.outstanding.length
+                ? roster.outstanding.map((entry) => `  ${entry.id}`)
+                : ['  none']),
+        ];
+        if (roster.joinedSince > 0) {
+            lines.push(`${roster.joinedSince} agent(s) joined after this was posted.`);
+        }
+        output(io, global.json, roster, lines.join('\n'));
+    });
+    postCommand
+        .command('archive <post-id>')
+        .description('Archive a post you wrote')
+        .requiredOption('--as <actor-id>')
+        .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
+        .option('--reason <text>')
+        .action(async (postId, options, command) => {
+        const global = globals(command);
+        const record = await withClient(global.home, actor(options.actorKind, options.as), (client) => client.posts.archive({ postId, ...(options.reason ? { reason: options.reason } : {}) }));
+        output(io, global.json, record, `Archived ${postId}`);
+    });
     const kudosCommand = program.command('kudos').description('Give and manage agent recognition');
     kudosCommand
         .command('give <recipient>')
@@ -1141,12 +1503,13 @@ export function createCli(io = defaultIo, serviceFactory = configuredServiceFact
                 throw new SynomemError('INVALID_INPUT', 'Generated WINS.md files are available only with the local backend.');
             }
             const capabilities = await client.capabilities();
-            const path = join(info.home, profile.id, 'WINS.md');
+            // Projections are written under the handle, since they exist to be read.
+            const path = join(info.home, profile.handle, 'WINS.md');
             if (!existsSync(path)) {
                 const hint = capabilities.projections.writeWinsMarkdown
                     ? 'Run `synomem rebuild` to generate it.'
                     : 'Enable projection.writeWinsMarkdown and run `synomem rebuild`.';
-                throw new SynomemError('INVALID_INPUT', `No generated WINS.md exists for ${profile.id}. ${hint}`);
+                throw new SynomemError('INVALID_INPUT', `No generated WINS.md exists for ${profile.handle}. ${hint}`);
             }
             return { profile, path, content: readFileSync(path, 'utf8') };
         });