feat: add ACP registry metadata for Zed

website/docs/developer-guide/acp-internals.md

@@ -24,12 +24,15 @@ Key implementation files:
 ```text
 hermes acp / hermes-acp / python -m acp_adapter
   -> acp_adapter.entry.main()
+  -> parse --version / --check / --setup before server startup
   -> load ~/.hermes/.env
   -> configure stderr logging
   -> construct HermesACPAgent
   -> acp.run_agent(agent, use_unstable_protocol=True)
 ```
 
+The Zed ACP Registry path launches the same adapter through `npx @nousresearch/hermes-agent-acp@<version>`, which delegates to `uvx --from 'hermes-agent[acp]==<version>' hermes-acp`.
+
 Stdout is reserved for ACP JSON-RPC transport. Human-readable logs go to stderr.
 
 ## Major components
@@ -146,7 +149,7 @@ Instead it reuses Hermes' runtime resolver:
 - `acp_adapter/auth.py`
 - `hermes_cli/runtime_provider.py`
 
-So ACP advertises and uses the currently configured Hermes provider/credentials.
+So ACP advertises and uses the currently configured Hermes provider/credentials. It also always advertises a terminal setup auth method (`hermes-setup`, args `--setup`) so first-run registry clients can open Hermes' interactive model/provider configuration before starting a normal ACP session.
 
 ## Working directory binding
 

website/docs/user-guide/features/acp.md

@@ -45,6 +45,14 @@ This installs the `agent-client-protocol` dependency and enables:
 - `hermes-acp`
 - `python -m acp_adapter`
 
+For Zed registry installs, Zed launches Hermes through the official ACP Registry entry. That entry uses the npm launcher package `@nousresearch/hermes-agent-acp`, which runs:
+
+```bash
+uvx --from 'hermes-agent[acp]==<version>' hermes-acp
+```
+
+Make sure `uv` or `uvx` is available on `PATH` before using the registry install path.
+
 ## Launching the ACP server
 
 Any of the following starts Hermes in ACP mode:
@@ -63,6 +71,13 @@ python -m acp_adapter
 
 Hermes logs to stderr so stdout remains reserved for ACP JSON-RPC traffic.
 
+For non-interactive checks:
+
+```bash
+hermes acp --version
+hermes acp --check
+```
+
 ## Editor setup
 
 ### VS Code
@@ -90,7 +105,19 @@ If you want to define Hermes manually, add it through VS Code settings under `ac
 
 ### Zed
 
-Example settings snippet:
+Zed v0.221.x and newer installs external agents through the official ACP Registry.
+
+1. Open the Agent Panel.
+2. Click **Add Agent**, or run the `zed: acp registry` command.
+3. Search for **Hermes Agent**.
+4. Install it and start a new Hermes external-agent thread.
+
+Prerequisites:
+
+- Configure Hermes provider credentials first with `hermes model`, or set them in `~/.hermes/.env` / `~/.hermes/config.yaml`.
+- Install `uv` so the registry launcher can run `uvx --from 'hermes-agent[acp]==<version>' hermes-acp`.
+
+For local development before the registry entry is available, use a custom agent server in Zed settings:
 
 ```json
 {
@@ -98,9 +125,9 @@ Example settings snippet:
     "hermes-agent": {
       "type": "custom",
       "command": "hermes",
-      "args": ["acp"],
-    },
-  },
+      "args": ["acp"]
+    }
+  }
 }
 ```
 
@@ -114,18 +141,23 @@ Use an ACP-compatible plugin and point it at:
 
 ## Registry manifest
 
-The ACP registry manifest lives at:
+The source copy of Hermes' official ACP Registry metadata lives at:
 
 ```text
 acp_registry/agent.json
+acp_registry/icon.svg
 ```
 
-It advertises a command-based agent whose launch command is:
+The upstream registry PR copies those files into the top-level `hermes-agent/` directory in `agentclientprotocol/registry`.
+
+The registry entry uses an `npx` distribution:
 
 ```text
-hermes acp
+npx @nousresearch/hermes-agent-acp@<version>
 ```
 
+The launcher then runs `hermes-acp` from the matching Python package version.
+
 ## Configuration and credentials
 
 ACP mode uses the same Hermes configuration as the CLI:
@@ -135,7 +167,7 @@ ACP mode uses the same Hermes configuration as the CLI:
 - `~/.hermes/skills/`
 - `~/.hermes/state.db`
 
-Provider resolution uses Hermes' normal runtime resolver, so ACP inherits the currently configured provider and credentials.
+Provider resolution uses Hermes' normal runtime resolver, so ACP inherits the currently configured provider and credentials. Hermes also advertises a terminal auth method (`--setup`) for first-run registry clients; this opens Hermes' interactive model/provider setup.
 
 ## Session behavior
 
@@ -171,29 +203,36 @@ On timeout or error, the approval bridge denies the request.
 
 Check:
 
-- the editor is pointed at the correct `acp_registry/` path
-- Hermes is installed and on your PATH
-- the ACP extra is installed (`pip install -e '.[acp]'`)
+- In Zed, open the ACP Registry with `zed: acp registry` and search for **Hermes Agent**.
+- For manual/local development, verify the custom `agent_servers` command points to `hermes acp`.
+- Hermes is installed and on your PATH.
+- The ACP extra is installed (`pip install -e '.[acp]'`).
+- `uv` or `uvx` is installed if launching from the official Zed registry entry.
 
 ### ACP starts but immediately errors
 
 Try these checks:
 
 ```bash
+hermes acp --version
+hermes acp --check
 hermes doctor
 hermes status
-hermes acp
 ```
 
 ### Missing credentials
 
-ACP mode does not have its own login flow. It uses Hermes' existing provider setup. Configure credentials with:
+ACP mode uses Hermes' existing provider setup. Configure credentials with:
 
 ```bash
 hermes model
 ```
 
-or by editing `~/.hermes/.env`.
+or by editing `~/.hermes/.env`. Registry clients can also trigger Hermes' terminal auth flow, which runs the same interactive provider/model setup.
+
+### Zed registry launcher cannot find uv
+
+Install `uv` from the official uv installation docs, then retry the Hermes Agent thread from Zed.
 
 ## See also