Add cohesive gateway registration commands

projects/privacy-guard/AGENTS.md

@@ -33,10 +33,10 @@ Run focused tests while working and `make check` before handoff.
 - `src/privacy_guard/engines/`: engine contract, registry, and built-in implementations
 - `src/privacy_guard/config.py`: policy action and ordered stage configuration
 - `src/privacy_guard/request_processor.py`: stage execution and policy disposition
-- `src/privacy_guard/cli.py`: command parsing, discovery, gateway setup,
-  configuration-schema output, and server adapter
+- `src/privacy_guard/cli.py`: command parsing, discovery, gateway registration
+  management, configuration-schema output, and server adapter
 - `src/privacy_guard/gateway_config.py`: safe OpenShell gateway TOML
-  registration updates
+  registration management
 - `src/privacy_guard/logging.py`: package-scoped standard-library logging configuration
 - `src/privacy_guard/base.py`: package-wide strict immutable domain-model base
 - `src/privacy_guard/string_validators.py`: shared string validators and field types

projects/privacy-guard/README.md

@@ -98,20 +98,23 @@ UTF-8, and oversized catalogs are rejected.
 ```bash
 uv run privacy-guard engines
 uv run privacy-guard configuration-schema
-uv run privacy-guard configure-gateway --host-ip YOUR_HOST_IPV4
+uv run privacy-guard add-gateway-registration --host-ip YOUR_HOST_IPV4
+uv run privacy-guard remove-gateway-registration --name privacy-guard
 uv run privacy-guard serve \
   --listen 0.0.0.0:50051 \
   --timeout-seconds 4
 ```
 
-`configure-gateway` adds or updates a Privacy Guard registration in the
+`add-gateway-registration` adds or updates a Privacy Guard registration in the
 OpenShell gateway TOML. Its registration name must match the policy's
 `middleware` field. Restart the gateway after changing registrations.
+`remove-gateway-registration` removes one registration by name while preserving
+unrelated gateway settings.
 
 The processing timeout is one bound shared by every stage. It defaults to 1
-second and cannot exceed 30 seconds. `configure-gateway` writes a five-second
+second and cannot exceed 30 seconds. `add-gateway-registration` writes a five-second
 OpenShell middleware timeout, so use a shorter processing timeout or edit the
-registration to provide more headroom. Rerunning `configure-gateway` restores
+registration to provide more headroom. Rerunning `add-gateway-registration` restores
 the five-second value.
 
 Use a trusted registry factory for custom engines:

projects/privacy-guard/docs/index.md

@@ -98,7 +98,7 @@ configuration:
 
 ```bash
 cd projects/privacy-guard/examples/regex-engine
-uv run privacy-guard configure-gateway \
+uv run privacy-guard add-gateway-registration \
   --host-ip YOUR_HOST_IPV4 \
   --name privacy-guard-regex
 ```

projects/privacy-guard/docs/operations.md

@@ -91,7 +91,7 @@ Replace `YOUR_HOST_IPV4` with the address you selected. Then add or update the
 gateway registration:
 
 ```bash
-uv run privacy-guard configure-gateway \
+uv run privacy-guard add-gateway-registration \
   --host-ip YOUR_HOST_IPV4 \
   --name privacy-guard \
   --port 50051
@@ -106,11 +106,22 @@ The command writes to:
 Use `--config PATH` to write a different gateway TOML. Existing unrelated
 gateway settings are preserved.
 
-`configure-gateway` writes a five-second OpenShell middleware timeout. The
+Remove a registration by name when it is no longer needed:
+
+```bash
+uv run privacy-guard remove-gateway-registration \
+  --name privacy-guard
+```
+
+This command uses the same default config path and accepts `--config PATH`.
+It leaves unrelated registrations and gateway settings unchanged. Restart the
+gateway after a registration is removed.
+
+`add-gateway-registration` writes a five-second OpenShell middleware timeout. The
 four-second processing timeout above leaves one second for queueing,
 configuration validation, processor preparation, and transport overhead. If
 you select a longer processing timeout, edit the generated registration to add
-headroom. Rerunning `configure-gateway` restores the timeout to five seconds.
+headroom. Rerunning `add-gateway-registration` restores the timeout to five seconds.
 
 The registration name must match the policy's `middleware` field:
 
@@ -135,7 +146,8 @@ brew services start openshell
 systemctl --user start openshell-gateway
 ```
 
-The gateway reads the default configuration that `configure-gateway` updated.
+The gateway reads the default configuration that `add-gateway-registration`
+updated.
 
 ## Verify connectivity
 
@@ -245,15 +257,37 @@ port must be between 1 and 65535.
 
 ## Shutdown and cleanup
 
-Stop Privacy Guard with `Ctrl-C`. Delete test sandboxes explicitly:
+Delete test sandboxes explicitly, then stop Privacy Guard with `Ctrl-C`:
 
 ```bash
 openshell sandbox delete SANDBOX_NAME
 ```
 
-The gateway continues to run in the background. Verify its connection:
+When the registration is no longer needed, stop the gateway before removing
+it. Replace `REGISTRATION_NAME` with the name passed to
+`add-gateway-registration`:
 
 ```bash
+# macOS with Homebrew
+brew services stop openshell
+
+# Linux with a Debian or RPM package
+systemctl --user stop openshell-gateway
+
+uv run privacy-guard remove-gateway-registration \
+  --name REGISTRATION_NAME
+```
+
+Restart the gateway with the command for your system, then verify its
+connection:
+
+```bash
+# macOS with Homebrew
+brew services start openshell
+
+# Linux with a Debian or RPM package
+systemctl --user start openshell-gateway
+
 openshell status
 ```
 

projects/privacy-guard/docs/reference/limits-and-failures.md

@@ -57,7 +57,7 @@ privacy-guard serve --timeout-seconds 4
 
 OpenShell's middleware timeout must be longer than the Privacy Guard processing
 timeout. Include headroom for worker queueing, configuration validation, and
-processor preparation. `configure-gateway` writes a five-second OpenShell
+processor preparation. `add-gateway-registration` writes a five-second OpenShell
 timeout, so edit that registration before using a processing timeout of five
 seconds or longer.
 

projects/privacy-guard/examples/custom-engine/README.md

@@ -119,7 +119,7 @@ the address you selected, then update the default gateway configuration:
 
 ```bash
 cd projects/privacy-guard/examples/custom-engine
-uv run privacy-guard configure-gateway \
+uv run privacy-guard add-gateway-registration \
   --host-ip YOUR_HOST_IPV4 \
   --name privacy-guard-custom-engine
 ```
@@ -193,10 +193,30 @@ Exit Claude and delete the sandbox:
 openshell sandbox delete privacy-guard-custom-engine
 ```
 
-Stop Privacy Guard with `Ctrl-C`. The gateway continues to run in the
-background. Verify its connection:
+Stop Privacy Guard with `Ctrl-C`, then stop the gateway before removing the
+example registration:
 
 ```bash
+# macOS with Homebrew
+brew services stop openshell
+
+# Linux with a Debian or RPM package
+systemctl --user stop openshell-gateway
+
+uv run privacy-guard remove-gateway-registration \
+  --name privacy-guard-custom-engine
+```
+
+Restart the gateway with the command for your system, then verify its
+connection:
+
+```bash
+# macOS with Homebrew
+brew services start openshell
+
+# Linux with a Debian or RPM package
+systemctl --user start openshell-gateway
+
 openshell status
 ```
 

projects/privacy-guard/examples/regex-engine/README.md

@@ -68,7 +68,7 @@ the address you selected, then update the default gateway configuration:
 
 ```bash
 cd projects/privacy-guard/examples/regex-engine
-uv run privacy-guard configure-gateway \
+uv run privacy-guard add-gateway-registration \
   --host-ip YOUR_HOST_IPV4 \
   --name privacy-guard-regex
 ```
@@ -140,10 +140,30 @@ Exit Claude and delete the sandbox:
 openshell sandbox delete privacy-guard-regex
 ```
 
-Stop Privacy Guard with `Ctrl-C`. The gateway continues to run in the
-background. Verify its connection:
+Stop Privacy Guard with `Ctrl-C`, then stop the gateway before removing the
+example registration:
 
 ```bash
+# macOS with Homebrew
+brew services stop openshell
+
+# Linux with a Debian or RPM package
+systemctl --user stop openshell-gateway
+
+uv run privacy-guard remove-gateway-registration \
+  --name privacy-guard-regex
+```
+
+Restart the gateway with the command for your system, then verify its
+connection:
+
+```bash
+# macOS with Homebrew
+brew services start openshell
+
+# Linux with a Debian or RPM package
+systemctl --user start openshell-gateway
+
 openshell status
 ```
 

projects/privacy-guard/src/privacy_guard/cli.py

@@ -18,8 +18,10 @@
 from privacy_guard.gateway_config import (
     MAX_MIDDLEWARE_REGISTRATION_NAME_BYTES,
     GatewayConfigError,
+    GatewayConfigRemoval,
     GatewayConfigUpdate,
     default_gateway_config_path,
+    remove_gateway_config,
     update_gateway_config,
     validate_middleware_name,
 )
@@ -30,8 +32,8 @@
 app = typer.Typer(
     name="privacy-guard",
     help=(
-        "Run Privacy Guard, configure a local OpenShell gateway, and inspect "
-        "installed entity-processing engines."
+        "Run Privacy Guard, manage local OpenShell gateway registrations, and "
+        "inspect installed entity-processing engines."
     ),
     no_args_is_help=True,
     add_completion=False,
@@ -127,8 +129,8 @@ def serve(
         raise typer.Exit(code=1) from None
 
 
-@app.command("configure-gateway")
-def configure_gateway(
+@app.command("add-gateway-registration")
+def add_gateway_registration(
     host_ip: Annotated[
         str,
         typer.Option(
@@ -201,7 +203,10 @@ def configure_gateway(
             port=port,
         )
     except GatewayConfigError as error:
-        typer.echo(f"Could not configure the OpenShell gateway: {error}", err=True)
+        typer.echo(
+            f"Could not add or update the OpenShell gateway registration: {error}",
+            err=True,
+        )
         raise typer.Exit(code=1) from None
 
     action = {
@@ -218,6 +223,59 @@ def configure_gateway(
     )
 
 
+@app.command("remove-gateway-registration")
+def remove_gateway_registration(
+    name: Annotated[
+        str,
+        typer.Option(
+            help=(
+                "Gateway registration name to remove. OpenShell allows "
+                f"1-{MAX_MIDDLEWARE_REGISTRATION_NAME_BYTES} ASCII bytes."
+            ),
+        ),
+    ],
+    config: Annotated[
+        Path | None,
+        typer.Option(
+            help=(
+                "Gateway TOML to update. Defaults to "
+                "`$OPENSHELL_GATEWAY_CONFIG` when set, otherwise `gateway.toml` "
+                "under `$XDG_CONFIG_HOME/openshell`."
+            ),
+        ),
+    ] = None,
+) -> None:
+    """Remove a named registration from an OpenShell gateway TOML file."""
+    try:
+        validated_name = validate_middleware_name(name)
+    except GatewayConfigError as error:
+        raise typer.BadParameter(
+            str(error),
+            param_hint="--name",
+        ) from None
+
+    config_path = config or default_gateway_config_path()
+    try:
+        result = remove_gateway_config(
+            config_path,
+            middleware_name=validated_name,
+        )
+    except GatewayConfigError as error:
+        typer.echo(
+            f"Could not remove the OpenShell gateway registration: {error}",
+            err=True,
+        )
+        raise typer.Exit(code=1) from None
+
+    if result is GatewayConfigRemoval.REMOVED:
+        typer.echo(f"Removed {validated_name} from {config_path}")
+        typer.echo(
+            "Next: restart the OpenShell gateway so it unloads this registration."
+        )
+    else:
+        typer.echo(f"No registration named {validated_name} found in {config_path}")
+
+
 @app.command("configuration-schema")
 def configuration_schema(context: typer.Context) -> None:
     """Print the policy configuration JSON Schema for the installed engines."""