@akms/mcp 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to `@akms/mcp`.
 
+## [0.4.0] - 2026-10-27
+
+### Changed
+
+- Ship setup and the Database, SSH, WSL and S3 servers as one `@akms/mcp` package. The only command is `akms-mcp`; server entries use `lib/db.js`, `lib/ssh.js`, `lib/wsl.js` and `lib/s3.js`.
+- Add a reviewed Migrate registry step that moves old direct paths and standard npx entries to `@akms/mcp`. Preserve launches waiting for the unified runtime; keep registry version 2.
+- Group every kind: each AI service gets one `akms_<kind>` entry per kind. Remove the per-connection layout and the switch between layouts; Migrate registry groups kinds an older setup listed one entry per connection, and a per-connection default.
+- Combine installation, updates and migration in Runtime. Show migration only when it can apply and display old/new package versions, list the upgrade steps while one is unfinished, offer **Update launch commands** only when a grouped entry no longer starts the installed runtime, and offer removal of unused legacy packages after checking client references; removal defaults to No.
+- Each kind's screen lists only its connections; Register, Sync and Runtime are in the main menu, which marks Runtime when an update or registry migration is available.
+- Consolidate user installation, security and upgrade guidance in README, with kind-specific configuration and tool guides under `docs/`.
+- The separate `@akms/mcp-db`, `@akms/mcp-ssh`, `@akms/mcp-wsl` and `@akms/mcp-s3` packages are superseded and will be deprecated. Existing legacy entries remain migration sources.
+
+Earlier kind-specific release histories: [Database](docs/db/CHANGELOG.md), [SSH](docs/ssh/CHANGELOG.md), [WSL](docs/wsl/CHANGELOG.md), [S3](docs/s3/CHANGELOG.md).
+
+## [0.3.2] - 2026-10-26
+
+### Changed
+
+- Point Sync review instructions to its current menu and name the services retaining old connection entries, grouping only identical retained lists.
+- Separate runtime waits from failed changes in Register and Sync. Group retained connection names, count saved connections separately from service entries, and show semantic colors only on interactive terminals without NO_COLOR.
+- Offer unimported connections directly from Sync and compare both saved and external settings before resolving an individual entry during session migration. Wide terminals show versions side by side; narrow terminals keep wrapped values.
+- Preserve existing terminal symbols and keep status words visible when colors are disabled.
+- Document the upgrade path from 0.2.x, including pending runtimes, differing imported settings, reconnecting clients, rollback and registry migration.
+
 ## [0.3.1] - 2026-10-26
 
 ### Verification

package/README.md

@@ -1,148 +1,139 @@
 # @akms/mcp
 
-An optional terminal helper for configuring AKMS Database, SSH, WSL and S3 connections. Each MCP also provides its own independent `register`, `config` and `sync` commands.
+MCP servers for PostgreSQL databases, SSH hosts, Windows Subsystem for Linux (WSL) and S3 buckets, with one setup menu and one shared connection catalog.
+
+Choose Claude Code, Codex, Claude Desktop and/or Cursor once. Connections you save are applied to every registered AI service. Each connection keeps its own credentials and access policy.
+
+Requires **Node.js 22+ and npm**. WSL runs on Windows with an installed Linux distribution.
+
+## Install and set up
 
 ```sh
-npx -y --prefer-online @akms/mcp@latest
+npx -y @akms/mcp@latest
 ```
 
-Requires **Node.js 22+ and npm**. WSL setup runs from Windows.
-
-```text
-? AKMS MCP · Connection setup
-❯ Database  PostgreSQL connections
-  SSH       Remote hosts
-  WSL       Local Linux distros · Windows
-  S3        AWS S3 and S3-compatible buckets
-  ────────────────────────
-  Register  Choose AI services once
-  Sync      Review and retry shared settings
-  Runtime   AKMS installation and direct launches
-  Updates   Check installed MCP releases
-  Quit
-
-↑↓ move · enter select · esc back
-```
+1. Open **Runtime** and choose **Install AKMS MCP**. This installs one runtime for all four kinds.
+2. Open **Register**, select the AI services you use, then choose **Apply registration** and confirm the review.
+3. Open **Database**, **SSH**, **WSL** or **S3**, add a connection and save it. The kind's screen contains its connections and a Back action; shared settings are in the main menu.
+4. Restart or reconnect your AI clients to load the saved connections.
+
+Add requires at least one registered service. Existing matching connections are imported when you apply registration; differing versions remain available for review in **Sync > Import existing connections**.
 
-Use **Register** to select Claude Code, Codex, Claude Desktop and/or Cursor once. Every menu remains available before registration; Add displays a Register instruction until at least one service is selected. Then choose a server type and save a connection: its package applies the entry to every registered service. Exiting its settings returns to this menu. **Sync** reviews differences and retries pending changes. Register and Sync run locally without installing a child MCP.
+You can open a kind's setup directly:
 
-**Runtime** installs or explicitly updates a selected MCP in `<AKMS_MCP_HOME or ~/.akms/mcp>/runtime`, and converts existing standard npx entries to direct Node launches after review. Connection values and credentials stay intact; custom commands and external client edits are preserved. Each standalone MCP has the same Runtime menu, so this helper is optional. Register/import legacy entries before conversion, then restart or reconnect the AI clients to replace their running npx processes.
+```sh
+npx -y @akms/mcp@latest db
+npx -y @akms/mcp@latest ssh
+npx -y @akms/mcp@latest wsl
+npx -y @akms/mcp@latest s3
+```
 
-## Install and run
+To install the setup command globally instead:
 
 ```sh
 npm install -g @akms/mcp@latest
 akms-mcp
 ```
 
-`akms-mcp config` and `akms-mcp setup` open the same menu. You can also jump straight into a setup screen:
+`akms-mcp setup` and `akms-mcp config` open the same main menu. `akms-mcp register` and `akms-mcp sync` open the shared registration and comparison screens. `--target codex` preselects Codex in Register; saves still apply to all registered services. Run `akms-mcp --help` for the command reference.
 
-```sh
-akms-mcp register
-akms-mcp db
-akms-mcp ssh
-akms-mcp wsl
-akms-mcp s3
-akms-mcp sync
-```
+The package exposes **one command, `akms-mcp`**. Database, SSH, WSL and S3 servers have separate entry files inside the same package; they do not need separate npm installations.
 
-Use `--help` for the command reference and `--version` for the launcher's version.
+## Choose a connection kind
 
-## Shared registration
+### Database
 
-### Startup checks and updates
+Query PostgreSQL directly or through an SSH tunnel. SQL goes through a PostgreSQL parser, with optional read-only mode, DDL restrictions, statement timeouts and result limits. See [Database connections, configuration and tools](docs/db.md).
 
-After saving a changed connection, applying Runtime launch commands, or updating from **Updates**, setup starts each distinct saved command once without shell interpolation. It sends MCP `initialize` and `tools/list`, then closes stdin; it does not invoke database, SSH, WSL or S3 tools. The check takes at most about 10 seconds per entry, plus bounded process cleanup. Results show the server version and tool count, or the exit code and masked stderr tail. Standard runtime script paths and spawn command paths stay visible for diagnosis. Session checks also verify a tool-name prefix for every saved connection. A failed check keeps the saved settings: fix it before restarting or reconnecting AI clients. Identical command/arguments/environment values share one check.
+### SSH
 
-Open **Updates** in the launcher or any package config menu to see installed and latest published runtime versions. Version lookup runs only when this screen opens or **Refresh versions** is chosen, with a short timeout; offline results show **Unavailable**. Update one runtime or all installed runtimes with newer releases; missing runtimes can be installed individually. Development links are displayed but never updated, and WSL is listed only on Windows. Updates use the same dedicated AKMS runtime directory and check that kind's saved connections afterward. Reconnect your AI clients to use the new runtime. The helper itself is not updated here.
+Run commands, keep working-directory sessions, and transfer files over SFTP. Configure a private key, password or SSH agent, optional jump hosts, host-key pinning and per-host command/path rules. See [SSH connections, configuration and tools](docs/ssh.md).
 
-Register confirmation defaults to **No** when deselecting a previously registered service; otherwise it defaults to **Yes**.
+### WSL
 
-### Session server mode
+Run commands and work with files in a registered Linux distribution and user on Windows. Command and file policies include additional protection for Windows paths mounted under `/mnt`. See [WSL connections, configuration and tools](docs/wsl.md).
 
-New catalogs start in version 2 with session mode enabled. Register your AI services, then add connections; setup creates each kind's session entry automatically. Existing version 1 catalogs keep individual mode until you approve **Migrate registry** or a per-kind **Runtime > Switch to session server** conversion (default No). Register/import their existing connections first. Each registered AI service gets one `akms_db`, `akms_ssh`, `akms_wsl` or `akms_s3` entry for that kind, running Node directly with `--catalog`. The helper package is optional. A client session still owns its own stdio process; connections of the same kind share that process.
+### S3
 
-The server reads its connections from the shared catalog at startup. Tools include the connection name, for example `production__db_query`; their arguments stay unchanged. Add/Edit/Remove updates the catalog; reconnect your clients to load changes. Removing the last connection removes the session entry. An invalid connection is excluded while valid ones remain available; `<kind>_catalog_status` reports the loaded/excluded names without credentials. No database, SSH, WSL or S3 connection opens just to list tools.
+List objects, inspect and edit UTF-8 content, and upload or download files in one bucket and optional key prefix. Supports AWS S3 and explicitly configured S3-compatible endpoints. See [S3 connections, configuration and tools](docs/s3.md).
 
-Converting an existing version 1 catalog upgrades it to version 2 and keeps the previous revision. Older setup packages stop without modifying version 2. New kinds in a new catalog also default to sessions; each kind's explicit rollback choice is retained. AKMS removes managed individual entries only after verifying the session entry; external edits stay for **Sync** review. Custom launch commands are retained in the catalog for rollback but are not executed in session mode.
+## Runtime and updates
 
-**Runtime > Switch back to per-connection entries** previews and restores the saved individual entries, including their credentials and launch commands. It removes the session entry after the replacements are verified. The registry stays version 2. **Reapply session launch command** updates paths after moving Node or the runtime. Restart/reconnect clients after either change.
+**Runtime** installs and updates the single `@akms/mcp` runtime. Choose **Check for updates**, then **Update to <version>** when a newer release is available. Opening the main menu does not query npm: **Update available <version>** means the installed runtime is older than the setup version already running. A linked development installation is shown as such and is never offered an update.
 
-Connection names use ASCII letters, digits, underscores or hyphens: DB up to 35 characters, SSH/WSL 30, S3 37. The four `akms_<kind>` names are reserved. These limits keep client-prefixed tool names within 64 characters; rename longer legacy entries before conversion.
+Runtime also contains **Migrate registry** when changes are ready to apply, **Update launch commands** when an `akms_<kind>` entry no longer starts the installed runtime (for example after Node moved), and **Remove old packages** when unused legacy installations can be removed. While an upgrade from the separate packages is unfinished, Runtime lists its steps (install, migrate, remove old packages) and marks each done, next or blocked.
 
-### Migrate an older registry
+The catalog directory is `~/.akms/mcp`, or `$AKMS_MCP_HOME` when set. Runtime installs below that directory:
 
-When a version 1 registry or a version 2 registry without a default-mode marker is opened, the helper and each config menu show **Registry update available** and **Migrate registry**. Select it to review the ordered format steps, every kind's current layout, per-service additions/removals, and settings kept for Sync. Approval defaults to **No**.
+| Platform | Runtime prefix | Package directory |
+| --- | --- | --- |
+| Windows | `<catalog>/runtime` | `<catalog>/runtime/node_modules/@akms/mcp` |
+| macOS / Linux | `<catalog>/runtime` | `<catalog>/runtime/lib/node_modules/@akms/mcp` |
 
-Migration upgrades v1 to v2, records `defaultMode: "catalog"`, and converts individual kinds through the existing session conversion rules. Kinds explicitly switched back to individual entries keep that choice. Already bundled kinds keep their launch commands; an unmarked v2 containing only bundles receives the marker without client-file changes. Missing runtimes leave existing entries in place for **Runtime** installation and **Sync**. Startup checks verify the affected session tools after approval.
+Saved MCP entries start Node directly with `lib/db.js`, `lib/ssh.js`, `lib/wsl.js` or `lib/s3.js`. npm installation runs during setup; an AI client's server connection does not keep an npm/npx wrapper running.
 
-One `registry.previous.json` revision covers the whole migration. Repeating migration on a current registry does nothing. Runtime still offers per-kind conversion and rollback. **Runtime > Use individual entries for new kinds** turns the future-kind default off, and **Start new kinds as session servers** turns it back on; existing kinds retain their modes. The explicit `individual` default is also current format, so turning it off does not trigger another migration notice.
+After saving changed settings or updating the runtime, setup checks MCP startup using `initialize` and `tools/list`. This check does not execute database, SSH, WSL or S3 tools. Fix any startup failures before reconnecting clients. Running processes keep their loaded code until restarted.
 
-### Catalog security
+## How connections appear in AI services
 
-The shared catalog is `~/.akms/mcp/registry.json`, or `$AKMS_MCP_HOME/registry.json`. It contains complete connection settings, including passwords and secret values **in plaintext**. In individual mode these values also appear in AI client entries. After successful session-mode conversion and resolution of any retained legacy entries, the catalog is the only active location for that kind's connection credentials; one previous-revision copy also contains them. This includes DB/SSH passwords and passphrases, and S3 static access keys and session tokens. SSH private-key settings store file paths, not the key files themselves.
+Connections are grouped by kind: each AI service gets one entry per kind. Six database connections appear as one `akms_db` entry and four SSH hosts as one `akms_ssh` entry. Each AI client session starts one process per kind. Passwords stay in the AKMS catalog; a service entry holds only the command that starts its server.
 
-On POSIX, new catalog files request mode `0600` and new catalog directories `0700`; existing permissions are not tightened. Windows uses inherited parent-directory ACLs (normally the user profile), not POSIX owner/group modes. Check access permissions when choosing a custom location.
+Each server reads a catalog snapshot at startup. Tools include the saved connection name, such as `pg_main__db_query` or `remote_main__ssh_exec`. Connections open lazily; listing tools does not connect to remote services. Call `db_catalog_status`, `ssh_catalog_status`, `wsl_catalog_status` or `s3_catalog_status` to inspect loaded and skipped connections without printing credentials. If the catalog is missing or invalid, a newly started server exposes its status tool so the problem remains visible.
 
-Keep both catalog files private: do not commit it, share it, copy it to another person or PC, paste its contents into chats/issues/AI conversations, or ask an AI agent to print it. Exclude it from cloud sync and shared backups, or protect those copies. Prefer SSH key authentication over passwords where possible. If exposed, change the affected passwords or rotate the affected keys/tokens, then update the connections through `config`.
+Connection names use ASCII letters, digits, underscores or hyphens: Database up to 35 characters, SSH/WSL up to 30, and S3 up to 37. The names `akms_db`, `akms_ssh`, `akms_wsl` and `akms_s3` are reserved.
 
-SSH blocks local uploads from and downloads into `.akms/mcp`. A custom `AKMS_MCP_HOME` outside that path is not protected as a whole: its `registry.json` and `registry.previous.json` are additionally blocked when the SSH process has that environment variable. Remote SSH paths have no catalog-specific block. WSL protects these paths through `/mnt/<drive>/`; native Linux paths have no catalog-specific block, and local Windows transfers depend on the installed SSH guard. The locked SSH 0.1.9 dependency does not block the catalog in those local transfers. Do not rely on these guards to keep the file private.
+## Register, compare and import
 
-Each successful catalog-changing operation atomically keeps one previous revision as **`registry.previous.json`** in the same directory. Internal application bookkeeping does not replace that pre-operation revision, and a no-op Sync leaves it unchanged. The copy requests the catalog's existing file permissions; Windows uses inherited ACLs. This is one revision, not a history.
+**Register** shares the service selection across all kinds. Newly registered services receive saved connections. Unregistering removes only AKMS-managed entries from that service and keeps the catalog.
 
-To recover, close configuration commands, preserve the current file if needed, and copy `registry.previous.json` over `registry.json` in that directory. Then reopen setup, review **Sync**, and reconnect clients. Recovery does not automatically revert client files.
+**Sync** compares saved settings with client settings and retries unfinished changes. Select an item to see the AKMS version beside the current service version, then choose which one to use. Secret values stay hidden in comparisons. Changes made outside setup remain intact until you approve a version.
 
-A running session keeps its startup snapshot. If `registry.json` is missing or invalid, a newly started session exposes only its status tool; its empty client entry cannot reconstruct credentials through Import. Restore the previous revision or enter the connections again. Individual mode still uses each entry's environment, so its existing client entries keep working and can be imported after registering services again.
+When Sync shows **Not yet imported**, choose **Import existing connections** on that screen. Review the versions and choose one, or use a new connection name to keep both. A runtime wait is shown separately from a failed write; retained entries identify the services in which they remain.
 
-Each standalone package can manage the catalog; the helper is optional. New services receive existing entries. Unregistering removes only AKMS-managed entries from that service and preserves the catalog.
+## Upgrading from 0.3.x to 0.4.0
 
-Register discovers earlier settings and imports matching copies together on Apply. Identical copies become one shared item. In session mode, managed individual entries are replaced after the session launch is verified. If a runtime is missing, install it from Runtime and run Sync; existing entries stay until then. Use **Import existing connections** to review differing versions or import remaining matching entries in a batch. Different versions require a choice before applying. Results summarize completed connections and list only items needing attention. Comparisons show changed fields, label description-only differences, and hide secret values. Partial failures retain successful writes; Sync offers retries and explicit resolution of client edits. `--target` preselects a service in registration; saves still apply to all registered services.
+Versions 0.3.x and earlier used the separate `@akms/mcp-db`, `@akms/mcp-ssh`, `@akms/mcp-wsl` and `@akms/mcp-s3` packages. Version 0.4.0 includes these servers in `@akms/mcp`.
 
-## Minimum working configuration
+1. Run `npx -y @akms/mcp@latest` to open the current setup.
+2. Open **Runtime**. The main menu marks it **Not installed** until the unified runtime is installed, then **Registry update available**. Choose **Install AKMS MCP** first when it is offered.
+3. Choose **Migrate registry** in Runtime when it is available. Review the old/new package versions, launch paths and proposed replacements, then approve the migration; its apply confirmation defaults to **No**.
+4. Applying the migration runs synchronization to rewrite managed client entries. Open **Sync** to resolve retained external edits or retry unfinished writes. A kind still listed one entry per connection is grouped into `akms_<kind>`, and the registry remains version 2.
+5. Open **Runtime > Remove old packages** when it is offered. It lists legacy packages only when the catalog and inspected client settings no longer use them. Removal is optional and defaults to **No**; finish migration and Sync before removing packages still in use.
+6. Restart or reconnect your AI clients to replace running servers.
+7. Call each kind's `*_catalog_status` tool and confirm its loaded connections.
 
-The launcher needs **no environment variables or MCP server entry**. With Node.js 22+, npm and access to your configured npm registry, run:
+The new target is `node .../node_modules/@akms/mcp/lib/<kind>.js --catalog`. Migrate registry moves old direct paths and standard npx entries, and groups connections still listed one entry each. A connection saved with a custom command is not started on its own any more; its settings load in the grouped entry. Externally edited entries require review. If installation is deferred or fails, old launches are kept; install from **Runtime**, then choose **Migrate registry** there.
 
-```sh
-npx -y --prefer-online @akms/mcp@latest
-```
+## Upgrading from 0.2.x
 
-Register at least one AI service, then choose a server and enter its connection values. The launcher opens the selected package's `config` menu; that package saves the connection in the shared local catalog and applies it to all registered AI services. Replace example names and credentials with your own. Each server package's README includes a **Minimum working configuration** section with a complete entry and its prerequisites.
+For clients with individual npx entries and no shared catalog:
 
-| Server | Minimum connection values | Prerequisites and defaults |
-|---|---|---|
-| Database | `DB_DRIVER=postgres`, `DB_HOST`, `DB_NAME`, `DB_USER`; `DB_PASSWORD` when password authentication is required | Reachable PostgreSQL database; port `5432`, TLS `require`. Set `DB_SSL=off` only for a database without TLS. Alternatively use `DB_DRIVER=postgres` with `DB_URL`. |
-| SSH | `SSH_HOST`, `SSH_USER`, plus `SSH_KEY` or `SSH_PASSWORD` | Reachable SSH server; port `22`. Omit both authentication fields only when the MCP process can use an SSH agent with an authorized key. |
-| WSL | `WSL_DISTRO` | Run the MCP client on Windows; the named distro must already be installed with `bash`. Uses the distro's default user. |
-| AWS S3 | `S3_BUCKET`, `S3_REGION`, `S3_AUTH=static`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` | Existing bucket and credentials permitted to access it; temporary credentials also need `S3_SESSION_TOKEN`. With an available AWS credential provider, omit the three static-auth fields. |
-| S3-compatible | `S3_BACKEND=compatible`, `S3_BUCKET`, `S3_ENDPOINT`, `S3_REGION`, `S3_AUTH=static`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` | Existing bucket, service endpoint, signing region and credentials. |
+1. Run `npx -y @akms/mcp@latest`, open **Runtime** and choose **Install AKMS MCP**.
+2. Open **Register**, select your services and apply. Matching copies become one shared connection; differing copies stay unchanged until you choose a version.
+3. Complete the offered comparison, or use **Sync > Import existing connections**. Review description-only differences too. Keep the connection name to replace its old entries, or choose a new name to keep both.
+4. Run **Sync** to finish pending changes. If **Registry update available** appears, review **Runtime > Migrate registry** as described above.
+5. Restart or reconnect clients, then check the appropriate `*_catalog_status` tools.
 
-For either S3 backend, `S3_LOCAL_ROOT` is needed only for local file upload/download; it must name an existing directory. Object listing, text reads/writes and deletion do not need it.
+If you register before installing the runtime, **Waiting for runtime** is a normal pending state. Existing entries stay until the replacement is ready. Install from **Runtime**, then use **Runtime > Migrate registry** if offered and **Sync** to finish. Installing the runtime alone does not finish the conversion.
 
-## Installed runtime setup
+Each client session owns its MCP processes. Start a fresh session or thread after upgrading, and close old sessions whose servers you want to stop.
 
-Choosing a server opens the installed AKMS runtime's `config` screen directly through Node, so setup and server execution use the same version. This path makes no npm calls and does not require registry access, including for linked development checkouts.
+## Catalog security and recovery
 
-If the runtime is missing, the launcher asks to install it (default **Yes**) into `<AKMS_MCP_HOME or ~/.akms/mcp>/runtime`, then opens that installed version. If installation fails, the reason is shown and a second question offers the latest setup through `npm exec` (default **No**). Only an explicit Yes uses that fallback: it checks npm's `latest` tag with fresh metadata and runs the exact returned version. A failed lookup does not open a cached setup release.
+The shared catalog is `~/.akms/mcp/registry.json`, or `$AKMS_MCP_HOME/registry.json`. It contains complete connection settings, including passwords and secret values **in plaintext**. Grouped AI client entries hold no connection credentials; manual or older entries that have not been imported still hold their own values. The previous revision, `registry.previous.json`, also contains saved credentials. SSH private-key settings store file paths, not the key files themselves.
 
-The MCP packages are **not dependencies** of this package. The managed runtime prefix is independent of Node versions, and saved connections use Node plus the runtime's `lib/cli.js` path. **Updates** checks published versions on demand; **Runtime** manages installations and conversion of existing launch commands. Saved MCP servers do not run npm or check for updates at startup. Updating a compatible MCP runtime does not require a new launcher release.
+On POSIX, new catalog files request mode `0600` and new catalog directories `0700`; existing permissions are not tightened. Windows uses inherited parent-directory ACLs. Check access permissions when choosing a custom location.
 
-| Selection | Package | Setup command |
-|---|---|---|
-| Database | `@akms/mcp-db` | `config` |
-| SSH | `@akms/mcp-ssh` | `config` |
-| WSL | `@akms/mcp-wsl` | `config` |
-| S3 | `@akms/mcp-s3` | `config` |
+**Keep both catalog files private:** do not commit them, share them, copy them to another person or PC, paste their contents into chats/issues/AI conversations, or ask an AI agent to print them. Exclude them from cloud sync and shared backups, or protect those copies. If exposed, change the affected passwords or rotate the affected keys/tokens, then update the saved connections.
 
-During local development, build the child package and run `npm install -g --prefix "<AKMS runtime directory>" "<checkout path>"`. The launcher opens that linked runtime directly. Linked runtime installations use the checkout and are protected from automatic replacement with a published release.
+SSH local-transfer guards block the standard `.akms/mcp` catalog tree and also protect the two catalog files at a custom `AKMS_MCP_HOME` when available to the process. WSL's Windows-path checks apply through `/mnt/<drive>/`; remote SSH paths and native Linux paths have no catalog-specific block. These guards do not replace filesystem permissions or private storage.
 
-The selected MCP owns its connection forms, validation and server execution. Service registration and sync code is included in each package and this optional helper. Entries saved for your AI client follow that MCP's own behavior.
+Each successful catalog-changing operation atomically keeps one pre-operation revision in **`registry.previous.json`**. Internal bookkeeping and a no-op Sync do not replace that revision. This is one previous revision, not a backup history.
 
-On an interactive terminal, connection menus, registration and comparisons use separate screens. Results and errors stay visible until Enter or Esc; returning to the menu shows current services and any connections needing attention. Piped commands keep plain output and need no extra answers. Sync labels the saved AKMS version and the current service version separately. Numbered choices show which service receives a value or whether it becomes the AKMS value for all registered services. Long values wrap, changed text is highlighted, and confirmation names the destinations.
+To recover, close setup commands, preserve the current file if needed, then copy `registry.previous.json` over `registry.json`. Reopen setup, review **Sync** and reconnect clients. Restoring the catalog does not automatically restore client files. A session entry contains no connection credentials, so Import cannot reconstruct a missing catalog from that entry alone.
 
 ## Terminal controls
 
-Use arrow keys and Enter, or number keys to move to a row. Esc returns to the previous menu; Esc at the main menu exits. The menu uses the same selection and rendering code as the SSH and WSL packages.
-
-Outside an interactive terminal, menus show numbers and accept a number, key or label. For scripted setup, the direct command is easiest: `akms-mcp db` passes stdin to the database setup screen.
+Use arrow keys and Enter to select; Esc goes back one level. Colors are disabled with `NO_COLOR` or when output is piped. Piped prompts use the same choices as numbered lists and accept a number, action key or label.
 
-See [development notes](./README_DEV.md) for build and test instructions.
+See [CHANGELOG.md](CHANGELOG.md) for release changes and [README_DEV.md](README_DEV.md) for contribution notes. Licensed under [MIT](LICENSE.md).