myagentmemory 0.4.13 → 0.4.15

package/docs/official-plugin-bootstrap.md

@@ -0,0 +1,337 @@
+# Official plugin bootstrap and host contract
+
+## Status
+
+Accepted design on 2026-08-16 and revised on 2026-08-17. The public core implements host types, loopback email activation, live catalog and artifact retrieval, Ed25519 release verification, bounded package validation, transactional install, bundle health checks, paid-command dispatch, and SessionStart hook dispatch. The free plan grants a configurable number of agent sessions per normalized email and UTC day; durable account authentication, payment, renewal, and account management remain deferred.
+
+The public `agentmemory` repository and `myagentmemory` npm package remain the free, MIT-licensed core. The public bootstrap client and host contracts are also MIT-licensed. Official commercial implementations and browser assets are built and distributed separately from the private `agent-memory-plugin` workspace under their own terms. Pricing, the billing provider, device limits, offline-grace duration, and Enterprise contract terms are intentionally not decided here. The temporary beta currently uses allowlisted `*.agentmemory.paperpilot.me` service origins; changing those origins is a public-client release change.
+
+## Decision
+
+The public core will provide a small bootstrap and host surface for signed first-party plugins. It will not contain paid implementations, browser assets, commercial entitlement logic, or a general third-party marketplace.
+
+The primary user command is:
+
+```bash
+agent-memory plugin install
+```
+
+`plugin install` is an idempotent reconcile operation:
+
+| Local state | Entitlement state | Result |
+| --- | --- | --- |
+| Plugin absent | Active or grace | Install the compatible signed bundle |
+| Plugin older than the selected release | Active or grace | Upgrade atomically |
+| Plugin current | Active or grace | Report that it is current |
+| Any | Missing | Start loopback email activation in an interactive terminal |
+| Any | Expired | Direct the user to renewal; leave core available |
+| Incompatible bundle | Any | Leave the current version untouched and explain the required core version |
+
+An absent plugin cannot activate itself. The public bootstrap collects an email locally, obtains a server-issued usage credential and short-lived artifact grant, and verifies the release and artifact. The credential is persisted only after the service accepts activation. After installation, the public host reconstructs the free account-metered capability policy in core code and checks required capabilities before commands and hooks. Signed long-lived entitlements can extend this credential when authentication and payment ship.
+
+## Ownership boundary
+
+The public core owns:
+
+- CLI discovery and bootstrap commands;
+- an allowlisted control-plane client;
+- credential-store and signed-entitlement persistence abstractions;
+- signed catalog and artifact verification;
+- transactional install, upgrade, rollback, and uninstall;
+- a versioned, permission-checked plugin host API;
+- command dispatch to an activated official bundle;
+- helpful unavailable-command messages when an official capability is absent.
+
+The commercial distribution owns:
+
+- the proprietary plugin runtime and implementations;
+- Session Intelligence and Web Console assets;
+- entitlement interpretation beyond the public signed-claim format;
+- paid command, hook, worker, and web-server behavior;
+- the authenticated website, billing integration, entitlement ledger, and artifact service;
+- signed release production and commercial notices.
+
+Core memory operations must continue to work when the service is unreachable, a plugin is absent, an entitlement expires, or an upgrade fails.
+
+## Alternatives rejected for v1
+
+- **Put the bootstrap inside the commercial plugin:** impossible when the plugin is not installed and unable to repair a broken installation.
+- **Ship a separate permanent Pro CLI:** duplicates command parsing and core behavior and makes it unclear which `agent-memory` binary owns user data.
+- **Bundle paid code in the public package behind an entitlement flag:** exposes the paid implementation under the public artifact and license boundary.
+- **Open a checkout page from npm/Homebrew postinstall:** unreliable in non-interactive environments and surprising for users who requested only the core.
+- **Use a general remote marketplace immediately:** expands code-loading, sandbox, trust, dependency, and moderation scope before the first-party boundary is proven.
+- **Pass license keys as CLI arguments or environment values:** exposes reusable credentials through shell history, process inspection, CI logs, or inherited environments.
+
+## CLI contract
+
+### Bootstrap commands
+
+```text
+agent-memory plugin
+agent-memory plugin list
+agent-memory plugin status
+agent-memory plugin install [--channel stable] [--no-browser] [--yes]
+agent-memory plugin update [--channel stable]
+agent-memory plugin uninstall [--yes]
+agent-memory plugin manage [--no-browser]
+```
+
+- `plugin` with no subcommand prints a discovery summary and the next relevant command.
+- `list` reports known official plugins and whether each is installed and available. It does not download artifacts or inspect memory.
+- `status` is read-only. It reports the installed bundle, selected channel, compatibility, entitlement state, and update availability.
+- `install` authenticates when necessary, then installs, upgrades, or reports current state.
+- `update` requires an existing installation and never starts a new purchase implicitly.
+- `uninstall` removes executable plugin material and the active receipt. It preserves core memory, plugin state, and the permission-restricted activation credential.
+- `manage` remains unavailable until authenticated account and billing management exists.
+
+Installed plugins contribute top-level commands such as `recall`, `learn`, `worker`, and `web`. Bootstrap command names are reserved by the core and cannot be replaced by a plugin.
+
+The current private compatibility CLI uses `plugin install` and `plugin uninstall` for skill files only. During migration, those meanings move to `install-skills --plugin-only` and `uninstall-skills --plugin-only`; the bootstrap command names above become authoritative.
+
+### Discovery behavior
+
+After a successful interactive `agent-memory init`, the core may print one informational line:
+
+```text
+Optional: AgentMemory Pro adds session recall and a local Web Console.
+Run: agent-memory plugin install
+```
+
+Top-level help includes an `Optional official plugins` section. Human-readable `status` may include the same recommendation while no official plugin is installed. Routine `context`, `read`, `write`, `search`, and scratchpad commands never show commercial prompts.
+
+The core must not open a browser during package installation, `init`, `help`, `status`, or any normal memory operation. A browser may open only after an explicit interactive `plugin install`. `--no-browser`, non-interactive execution, and `--json` fail closed with `auth_required` when no activation record exists.
+
+### Machine-readable output
+
+Every bootstrap command supports `--json` and emits one JSON document with a versioned envelope:
+
+```json
+{
+  "schemaVersion": 1,
+  "command": "plugin.install",
+  "ok": true,
+  "result": "installed",
+  "bundle": {
+    "id": "agentmemory.pro",
+    "previousVersion": null,
+    "version": "1.0.0",
+    "channel": "stable"
+  },
+  "entitlement": {
+    "plan": "pro",
+    "state": "active",
+    "capabilities": {
+      "learning": { "enabled": true },
+      "web-console": { "enabled": true }
+    },
+    "expiresAt": "2027-08-16T00:00:00Z",
+    "offlineUntil": "2026-09-15T00:00:00Z"
+  },
+  "nextAction": null
+}
+```
+
+`result` is one of `not_installed`, `installed`, `upgraded`, `current`, `update_available`, `uninstalled`, `auth_required`, `renewal_required`, or `unavailable`. Failures use `ok: false` plus a stable `error.code` and redacted `error.message`. Output must never contain access tokens, download credentials, signed entitlement contents, local memory paths, or URLs containing bearer credentials.
+
+## Free activation flow
+
+1. `agent-memory plugin install` starts an HTTP server bound to `127.0.0.1` on an ephemeral port.
+2. The CLI prints and opens a nonce-bearing local URL. The page accepts one email address with bounded input, an exact Host and nonce path, same-origin browser request validation, restrictive response headers, and a five-minute deadline.
+3. Submission returns a completion page but does not create a local credential yet.
+4. The waiting CLI sends the email plus core, installed-bundle, platform, architecture, release-channel, and consent-version fields to the private control plane. Its activation database stores none of the user's memory, session content, queries, repository paths, raw agent session identifiers, IP address, or user-agent string.
+5. The service normalizes the email, stores only a hash of a random usage credential, and returns the credential, a free account-metered entitlement, and a short-lived object-bound artifact grant. Only then does the CLI atomically write a mode-0600 activation record.
+6. The CLI verifies the Ed25519-signed release plus package digest and limits, imports it for health checks, and atomically activates the receipt.
+7. Each paid SessionStart hook reserves one opaque operation against the email's UTC-day allowance, commits after useful hook work, and releases on failure. Exhaustion skips paid hook work without affecting public-core context.
+
+Email ownership is not verified in this free flow. Authentication, payment, renewal, account management, and signed paid entitlements are not implemented yet.
+
+## Future authentication and purchase flow
+
+1. The bootstrap inspects the local install receipt and signed entitlement without loading plugin code.
+2. If no usable entitlement or account credential exists, it requests a short-lived device authorization.
+3. The CLI prints a verification URL and user code and, for an interactive request, attempts to open the URL.
+4. The website authenticates the user and offers AgentMemory Pro or an Enterprise contact/organization path.
+5. Successful payment or organization assignment updates the server-side entitlement ledger.
+6. The CLI polls within the server-provided interval and deadline. On success, it receives a signed entitlement and a short-lived artifact grant.
+7. Installation continues in the same command without asking the user to copy a license key.
+
+Canceling, timing out, or failing payment leaves the machine unchanged. Authentication credentials are never accepted through command-line arguments. The first release should use an operating-system credential store when available and an explicit, permission-restricted fallback when it is not. Credential persistence and fallback behavior must be disclosed before launch.
+
+An Enterprise administrator may pre-provision an organization entitlement or managed installation policy. Enterprise automation must accept a license-file path or managed credential reference, not a raw secret on the command line.
+
+## Control-plane boundary
+
+The service exposes:
+
+- `POST /v1/plugin/access` for a free account-metered entitlement, a usage credential, and a short-lived artifact grant;
+- `POST /v1/plugin/sessions/reserve|commit|release` for atomic daily allowance enforcement;
+- `GET /v1/plugin/releases` for an Ed25519-signed release selected from the private R2 catalog;
+- `GET|HEAD /v1/artifacts/download` for the exact content-addressed object authorized by the bearer grant.
+
+The access request contains the submitted email plus the bounded core, bundle, platform, architecture, release-channel, and consent-version fields described above. Session metering sends only a random operation ID and bearer credential; D1 associates those values with a normalized email and UTC-day counter. Application payloads contain no memory content, search query, session content, path, repository name, raw agent session identifier, qmd data, IP address, or user-agent string. The activation database stores neither IP addresses nor user-agent strings. Future authenticated service responsibilities include:
+
+- create and poll a device authorization;
+- read the authenticated principal's effective entitlement;
+- fetch a signed release catalog;
+- mint a short-lived artifact download grant;
+- return the account-management URL;
+- support Enterprise organization assignment without consumer checkout.
+
+The bootstrap may send only:
+
+- a random installation identifier;
+- core version, plugin-host API version, platform, and architecture;
+- requested bundle ID, installed bundle version, and release channel;
+- a pseudonymous license or organization identifier;
+- protocol nonces, opaque quota operation IDs, and authentication material required for the request.
+
+It must never send memory contents, search queries, session contents, raw agent session identifiers, working-directory names, repository names, filesystem paths, or qmd data. The bounded allowance counter is authorization state, not general product telemetry.
+
+Production builds use an allowlisted HTTPS origin. Development endpoint overrides must be explicit, must not silently affect production builds, and must never weaken TLS verification.
+
+## Signed entitlement contract
+
+The server issues a signed, versioned entitlement containing the minimum claims needed for offline activation:
+
+```json
+{
+  "schemaVersion": 1,
+  "licenseId": "lic_pseudonymous_id",
+  "plan": "pro",
+  "features": ["session-intelligence", "web-console"],
+  "capabilities": {
+    "learning": { "enabled": true },
+    "web-console": { "enabled": true }
+  },
+  "channel": "stable",
+  "issuedAt": "2026-08-16T00:00:00Z",
+  "refreshAfter": "2026-08-23T00:00:00Z",
+  "expiresAt": "2027-08-16T00:00:00Z",
+  "offlineUntil": "2026-09-15T00:00:00Z"
+}
+```
+
+It contains no name, email address, billing details, memory identifier, or filesystem information. Plan identifiers (`free`, `trial`, `pro`, `team`, or `enterprise`) are commercial policy; `active`, `grace`, `missing`, and `expired` are separate locally derived verification states and are never inferred from the plan name. Enterprise may satisfy all `pro` capability requirements while adding organization-scoped policy claims.
+
+Capabilities authorize individual commands, hooks, workers, and local API routes. A capability may carry a positive device-local daily quota. The signed policy configures the limit, while usage remains in a crash-safe local ledger; quota accounting does not add product telemetry to the bootstrap protocol. A plan never implicitly enables a capability, and an active entitlement with a disabled or absent capability fails closed for that operation.
+
+The exact signed-envelope format, key custody, rotation procedure, and grace duration remain launch decisions. Verification keys are pinned by the public core, support overlap during rotation, and never come from the downloaded artifact being verified.
+
+## Release catalog and artifact contract
+
+The signed catalog selects an artifact by bundle ID, channel, core compatibility, plugin-host API compatibility, platform, and architecture. Each release describes at least:
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "agentmemory.pro",
+  "version": "1.0.0",
+  "channel": "stable",
+  "core": ">=0.5.0 <1.0.0",
+  "pluginApi": 1,
+  "platform": "any",
+  "architecture": "any",
+  "sha256": "hex-encoded archive digest",
+  "size": 123456,
+  "entrypoint": "bundle/index.js",
+  "plugins": ["agentmemory.session-intelligence", "agentmemory.web-console"]
+}
+```
+
+The archive contains compiled commercial code, plugin manifests, contributed skills, commercial license text, preserved public-core notices, and third-party notices. It must not depend on npm lifecycle scripts, download dependencies during activation, or include real credentials. Archive paths, symlinks, expanded size, file count, and permissions are validated before extraction.
+
+## Transactional installation
+
+The machine-wide user installation is independent of `AGENT_MEMORY_DIR`, which selects a memory store. The default install root is `~/.agent-memory/system/plugins`; the dedicated non-secret `AGENT_MEMORY_PLUGIN_DIR` setting may override it for managed deployment and tests.
+
+An install or upgrade must:
+
+1. acquire a bounded installation lock;
+2. inspect the current receipt without executing plugin code;
+3. authenticate and resolve a compatible signed catalog entry;
+4. download to a newly created staging directory;
+5. verify catalog signature, artifact digest, archive limits, manifest, and compatibility;
+6. extract without path traversal or link traversal;
+7. load only the declared entry point for a bounded health check;
+8. atomically switch the active-version receipt;
+9. install declared skills and hooks only after successful activation;
+10. preserve the previous known-good version for rollback and remove abandoned staging data.
+
+Failure before activation leaves the previous version active. Failure immediately after activation restores the previous receipt. Concurrent installers do not interleave. The core never invokes package-manager lifecycle scripts or elevates privileges.
+
+Uninstall removes executable versions, the active receipt, contributed skills, and managed hooks. It does not remove `MEMORY.md`, daily logs, topics, scratchpad items, source session logs, plugin-created review data, or billing state. A separate future purge command would require explicit scope and confirmation.
+
+## Plugin host API v1
+
+The implementation will expose equivalent TypeScript types from the public package. This document is authoritative until those types ship:
+
+```ts
+export interface AgentMemoryPluginBundleV1 {
+	apiVersion: 1;
+	manifest: AgentMemoryBundleManifestV1;
+	plugins: readonly AgentMemoryPluginV1[];
+}
+
+export interface AgentMemoryPluginV1 {
+	manifest: AgentMemoryPluginManifestV1;
+	activate(host: AgentMemoryPluginHostV1): Promise<void>;
+	healthCheck(host: AgentMemoryPluginHostV1): Promise<{ ok: boolean; message?: string }>;
+}
+
+export interface AgentMemoryPluginHostV1 {
+	apiVersion: 1;
+	coreVersion: string;
+	registerCommand(command: PluginCommandV1): void;
+	registerSessionStartHook(hook: PluginSessionStartHookV1): void;
+	getStateDirectory(): string;
+	getEntitlement(): Promise<PluginEntitlementStatusV1>;
+	redactSecrets(value: string): string;
+	writeMemory(request: PluginMemoryWriteV1): Promise<PluginMemoryWriteResultV1>;
+	correctMemory(request: PluginMemoryCorrectionV1): Promise<PluginMemoryCorrectionResultV1>;
+	scheduleSearchRefresh(reason: string): void;
+}
+```
+
+The final exported contract must define the referenced request, result, command, hook, manifest, entitlement-status, permission, cancellation, and structured-error types. Commercial manifests are plan-neutral: they declare `entitlement: "commercial"`, their provided capabilities, and the `requiredCapability` for each guarded command or hook. The loader validates every bundled plugin first, then creates a host instance scoped to that plugin's manifest. Host methods enforce its declared permissions. Plugins receive only derived entitlement state, capability grants, quota policy, and time bounds through host APIs, never raw signed claims or commercial credentials.
+
+Installed bundles are trusted, signed first-party JavaScript loaded into the AgentMemory process. Manifest permissions constrain host APIs; they are not an operating-system sandbox and do not remove the bundle's ambient Node.js process or filesystem authority. This contract does not approve arbitrary third-party plugin loading. State-directory isolation prevents accidental host-API crossover, not malicious code running in the same process.
+
+Activation order is: verify artifact, verify entitlement, validate every manifest, resolve required dependencies, create permission-scoped host adapters, activate plugins, then register commands and hooks. Registered-but-unavailable dependencies do not satisfy `requires`.
+
+## Runtime entitlement behavior
+
+The core reloads local entitlement state before every commercial command or compatibility alias and checks its exact required capability before dispatch. Plugin-owned hooks, worker starts, Web Console launches, and commercial API routes must perform the same check through `host.getEntitlement()`. A long-running plugin process must recheck through that host API at a bounded interval and respond safely to expiration or capability removal. Browser-session authorization remains separate from commercial entitlement and never contains subscription credentials.
+
+When entitlement is in grace, paid capabilities continue locally and status explains when grace ends. When expired or invalid, new paid work fails closed with a renewal action; core memory remains available and no user data is deleted.
+
+## Compatibility and updates
+
+- Core and bundle versions follow semantic versioning.
+- The integer plugin-host API changes only for incompatible host-contract revisions.
+- A bundle declares both a core range and a host API version.
+- `plugin install` and `plugin update` choose the newest compatible release in the selected channel, not merely the newest release.
+- Updates occur only after an explicit install/update command or a future separately approved policy. No background auto-download is part of v1.
+- A newer incompatible release is reported without replacing the current working version.
+
+## Security and release gates
+
+Before launch, automated tests must demonstrate:
+
+- public `myagentmemory` package contents contain no paid code, SPA assets, private source maps, commercial credentials, or private release configuration;
+- missing, active, grace, expired, malformed, wrong-audience, and wrong-signature entitlements fail as specified;
+- absent, current, outdated, interrupted, corrupt, incompatible, and concurrent installation paths are deterministic and recoverable;
+- archive traversal, symlink traversal, oversized archives, digest mismatch, unknown signing keys, and unauthorized commands fail closed;
+- all paid entry points enforce entitlement while every core memory operation remains available;
+- `--json` remains parseable and secret-free and non-interactive use never opens a browser;
+- install, update, rollback, and uninstall work on supported macOS, Linux, and Windows environments.
+
+## Deferred work
+
+This contract does not approve:
+
+- arbitrary third-party plugin loading or a public marketplace;
+- remote execution of plugin code;
+- silent or package-postinstall browser prompts;
+- background commercial telemetry or transmission of memory data;
+- pricing, seat counts, device limits, or a billing vendor;
+- Enterprise readiness claims before SSO, policy, retention, audit, DLP, and managed deployment are implemented and tested.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "myagentmemory",
-	"version": "0.4.13",
+	"version": "0.4.15",
 	"description": "agentmemory (agent-memory) is persistent memory for coding agents (Claude Code, OpenAI Codex, Cursor, Agent) with qmd-powered semantic search across daily logs, long-term memory, and scratchpad",
 	"main": "./dist/core.js",
 	"types": "./dist/core.d.ts",
@@ -8,10 +8,26 @@
 		".": {
 			"types": "./dist/core.d.ts",
 			"default": "./dist/core.js"
+		},
+		"./plugin-bootstrap": {
+			"types": "./dist/plugin-bootstrap.d.ts",
+			"default": "./dist/plugin-bootstrap.js"
+		},
+		"./plugin-host": {
+			"types": "./dist/plugin-host.d.ts",
+			"default": "./dist/plugin-host.js"
+		},
+		"./completions": {
+			"types": "./dist/completions.d.ts",
+			"default": "./dist/completions.js"
+		},
+		"./hooks": {
+			"types": "./dist/hooks.d.ts",
+			"default": "./dist/hooks.js"
 		}
 	},
 	"bin": {
-		"agent-memory": "./dist/cli.js"
+		"agent-memory": "dist/cli.js"
 	},
 	"type": "module",
 	"engines": {
@@ -56,6 +72,21 @@
 		"dist/cli.js",
 		"dist/core.d.ts",
 		"dist/core.js",
+		"dist/cli-spec.d.ts",
+		"dist/cli-spec.js",
+		"dist/completions.d.ts",
+		"dist/completions.js",
+		"dist/hooks.d.ts",
+		"dist/hooks.js",
+		"dist/plugin-bootstrap.d.ts",
+		"dist/plugin-bootstrap.js",
+		"dist/plugin-host.d.ts",
+		"dist/plugin-host.js",
+		"dist/plugin-runtime.d.ts",
+		"dist/plugin-runtime.js",
+		"dist/plugin-service.d.ts",
+		"dist/plugin-service.js",
+		"docs/official-plugin-bootstrap.md",
 		"README.md",
 		"LICENSE"
 	],
@@ -69,6 +100,7 @@
 		"build:lib": "tsc -p tsconfig.build.json",
 		"build:cli": "bun build src/cli.ts --compile --outfile dist/agent-memory --define __VERSION__=\"'$(node -p \"require('./package.json').version\")'\"",
 		"eval:feedback": "bun eval/run.ts",
+		"prepare": "npm run build:lib",
 		"prepack": "npm run build:lib",
 		"lint": "biome check .",
 		"test": "bun test test/unit.test.ts",
@@ -85,6 +117,7 @@
 		"typescript": "^5.9.3"
 	},
 	"overrides": {
+		"esbuild": "^0.28.1",
 		"rimraf": "^6.1.3",
 		"glob": "^13.0.3"
 	}

package/src/cli-spec.ts

@@ -0,0 +1,236 @@
+export type CliValueKind = "directory" | "file" | "number" | "value";
+
+export interface CliOptionSpec {
+	description: string;
+	value?: {
+		label: string;
+		kind: CliValueKind;
+	};
+}
+
+export const COMMANDS = [
+	"context",
+	"write",
+	"read",
+	"scratchpad",
+	"search",
+	"distil",
+	"sync",
+	"init",
+	"status",
+	"install-skills",
+	"uninstall-skills",
+	"install-hooks",
+	"uninstall-hooks",
+	"completion",
+	"plugin",
+	"version",
+	"help",
+] as const;
+
+export const PLUGIN_COMMANDS = ["list", "status", "install", "update", "uninstall", "manage"] as const;
+
+export const WORKER_ACTIONS = [] as const;
+export const SCRATCHPAD_ACTIONS = ["add", "done", "undo", "clear_done", "list"] as const;
+
+export const COMMAND_DESCRIPTIONS: Record<(typeof COMMANDS)[number], string> = {
+	context: "build context from scratchpad, logs, topics, and long-term memory",
+	write: "append or overwrite a daily, topic, or long-term memory entry",
+	read: "read daily, topic, scratchpad, or long-term memory",
+	scratchpad: "add, complete, reopen, list, or clear persistent checklist items",
+	search: "search indexed memory with keyword, semantic, or deep qmd modes",
+	distil: "rebuild a compact MEMORY.md index from logs and topics",
+	sync: "update the qmd index and semantic embeddings",
+	init: "create memory storage and configure qmd when available",
+	status: "show memory paths, file counts, qmd, and embedding health",
+	"install-skills": "install core instructions for detected agents",
+	"uninstall-skills": "remove core instructions from detected agents",
+	"install-hooks": "install automatic SessionStart indexing and context hooks",
+	"uninstall-hooks": "remove only SessionStart hooks managed by agent-memory",
+	completion: "install or print Bash, Zsh, Fish, or PowerShell completion",
+	plugin: "index, recall, learn from, and evaluate prior agent sessions",
+	version: "print the installed agent-memory version",
+	help: "show top-level, command, or nested plugin help",
+};
+
+export const PLUGIN_COMMAND_DESCRIPTIONS: Record<(typeof PLUGIN_COMMANDS)[number], string> = {
+	list: "list optional official plugins and local availability",
+	status: "show the installed bundle and entitlement state",
+	install: "authenticate if needed, then install or upgrade the official bundle",
+	update: "upgrade an existing official bundle when a compatible release exists",
+	uninstall: "remove official plugin executables while preserving user data",
+	manage: "open the AgentMemory account and billing website",
+};
+
+export const WORKER_ACTION_DESCRIPTIONS: Record<(typeof WORKER_ACTIONS)[number], string> = {};
+
+export const SCRATCHPAD_ACTION_DESCRIPTIONS: Record<(typeof SCRATCHPAD_ACTIONS)[number], string> = {
+	add: "add a new open checklist item; requires --text",
+	done: "complete the first open substring match; requires --text",
+	undo: "reopen the first completed substring match; requires --text",
+	clear_done: "remove every completed checklist item",
+	list: "show checklist items and completion counts",
+};
+
+export const GLOBAL_OPTIONS = ["--dir", "--json", "--help", "--version", "-h", "-V"] as const;
+
+export const COMMAND_OPTIONS: Record<string, readonly string[]> = {
+	context: ["--query", "--no-search"],
+	write: ["--content", "--target", "--mode", "--topic", "--date", "--source-uri"],
+	read: ["--target", "--date", "--topic"],
+	scratchpad: ["--text"],
+	search: ["--query", "--mode", "--limit"],
+	distil: ["--dry-run"],
+	sync: [],
+	init: [],
+	status: ["--probe"],
+	"install-skills": [],
+	"uninstall-skills": [],
+	"install-hooks": ["--yes", "--all", "--only"],
+	"uninstall-hooks": ["--only"],
+	completion: ["--stdout"],
+	version: [],
+	help: [],
+};
+
+export const PLUGIN_COMMAND_OPTIONS: Record<string, readonly string[]> = {
+	list: [],
+	status: ["--channel"],
+	install: ["--channel", "--no-browser", "--yes"],
+	update: ["--channel"],
+	uninstall: ["--yes"],
+	manage: ["--no-browser"],
+};
+
+export const WORKER_ACTION_OPTIONS: Record<string, readonly string[]> = {};
+
+export const SCRATCHPAD_ACTION_OPTIONS: Record<string, readonly string[]> = {
+	add: ["--text"],
+	done: ["--text"],
+	undo: ["--text"],
+	clear_done: [],
+	list: [],
+};
+
+export const OPTION_SPECS: Record<string, CliOptionSpec> = {
+	"--dir": { description: "override the active memory directory", value: { label: "directory", kind: "directory" } },
+	"--json": { description: "emit command-specific structured JSON" },
+	"--help": { description: "show help for the selected command" },
+	"--version": { description: "print the installed version and exit" },
+	"-h": { description: "show help for the selected command" },
+	"-V": { description: "print the installed version and exit" },
+	"--query": { description: "memory search or context-retrieval query", value: { label: "text", kind: "value" } },
+	"--no-search": { description: "build context without invoking qmd" },
+	"--content": { description: "memory entry content to persist", value: { label: "text", kind: "value" } },
+	"--target": { description: "memory destination or collection to read", value: { label: "target", kind: "value" } },
+	"--mode": { description: "write behavior or qmd search strategy", value: { label: "mode", kind: "value" } },
+	"--topic": { description: "topic name used to resolve a topic file", value: { label: "name", kind: "value" } },
+	"--date": { description: "daily-log date in YYYY-MM-DD form", value: { label: "date", kind: "value" } },
+	"--source-uri": {
+		description: "optional provenance URI stored with an entry",
+		value: { label: "uri", kind: "value" },
+	},
+	"--text": { description: "checklist item text or substring to match", value: { label: "text", kind: "value" } },
+	"--limit": { description: "maximum number of search or recall results", value: { label: "number", kind: "number" } },
+	"--dry-run": { description: "preview generated memory without writing MEMORY.md" },
+	"--probe": { description: "run a live semantic query to verify embeddings" },
+	"--since": { description: "metrics reporting window in days", value: { label: "days", kind: "number" } },
+	"--port": {
+		description: "web-console port; use 0 to select an available port",
+		value: { label: "number", kind: "number" },
+	},
+	"--state": { description: "override the plugin state root", value: { label: "directory", kind: "directory" } },
+	"--with-plugin": { description: "include both the core and optional plugin skills" },
+	"--plugin-only": { description: "operate only on the optional plugin skill" },
+	"--yes": { description: "apply eligible hook changes without confirmation" },
+	"--all": { description: "apply eligible hook changes without confirmation" },
+	"--only": {
+		description: "restrict hook changes to comma-separated agent keys",
+		value: { label: "agents", kind: "value" },
+	},
+	"--stdout": { description: "print the completion script without installing it" },
+	"--channel": {
+		description: "select the official release channel",
+		value: { label: "channel", kind: "value" },
+	},
+	"--no-browser": { description: "print account URLs instead of opening a browser" },
+	"--scope": {
+		description: "search globally or only in the current workspace",
+		value: { label: "scope", kind: "value" },
+	},
+	"--cwd": {
+		description: "restrict session operations to a working directory",
+		value: { label: "directory", kind: "directory" },
+	},
+	"--context": {
+		description: "surrounding events included with each recall hit",
+		value: { label: "number", kind: "number" },
+	},
+	"--pi": { description: "override the Pi session root", value: { label: "directory", kind: "directory" } },
+	"--codex": { description: "override the Codex session root", value: { label: "directory", kind: "directory" } },
+	"--claude": {
+		description: "override the Claude Code session root",
+		value: { label: "directory", kind: "directory" },
+	},
+	"--host": {
+		description: "session host (pi/codex/claude) or web loopback bind address",
+		value: { label: "host", kind: "value" },
+	},
+	"--max-per-host": {
+		description: "maximum session files read from each host",
+		value: { label: "number", kind: "number" },
+	},
+	"--recent": {
+		description: "most recently modified session files refreshed per host",
+		value: { label: "number", kind: "number" },
+	},
+	"--interval": {
+		description: "watch polling interval in milliseconds",
+		value: { label: "milliseconds", kind: "number" },
+	},
+	"--once": { description: "run one watch iteration and exit" },
+	"--lines": {
+		description: "number of recent worker log entries to return",
+		value: { label: "number", kind: "number" },
+	},
+	"--threshold": {
+		description: "minimum repeated evidence required for a candidate",
+		value: { label: "number", kind: "number" },
+	},
+	"--output": { description: "also write the report to this file", value: { label: "file", kind: "file" } },
+	"--replay": { description: "back up and rebuild derived learning layers" },
+	"--journal": {
+		description: "override the experience journal directory",
+		value: { label: "directory", kind: "directory" },
+	},
+	"--candidates-dir": {
+		description: "override the candidate ledger directory",
+		value: { label: "directory", kind: "directory" },
+	},
+	"--decisions-dir": {
+		description: "override the decision ledger directory",
+		value: { label: "directory", kind: "directory" },
+	},
+	"--auto-dir": {
+		description: "override the materialized auto-memory directory",
+		value: { label: "directory", kind: "directory" },
+	},
+	"--agent": { description: "internal SessionStart host key", value: { label: "agent", kind: "value" } },
+	"--token": { description: "internal session-worker lease token", value: { label: "token", kind: "value" } },
+	"--uninstall": { description: "use install-skills compatibility uninstall mode" },
+};
+
+export const SHELL_DESCRIPTIONS: Record<string, string> = {
+	bash: "generate or install Bash completion",
+	zsh: "generate or install Zsh completion",
+	fish: "generate or install Fish completion",
+	powershell: "generate or install PowerShell completion",
+};
+
+export function optionDescription(option: string): string {
+	return OPTION_SPECS[option]?.description ?? option;
+}
+
+export function optionTakesValue(option: string): boolean {
+	return OPTION_SPECS[option]?.value !== undefined;
+}