refactor(python): rename navigator module to openshell and migrate config to gateway paths (#220)

Author: drew

.env.example

@@ -13,7 +13,7 @@
 
 # Default gateway name used by `openshell` commands in this repo when `--gateway`
 # is not provided. Usually matches CLUSTER_NAME.
-#OPENSHELL_CLUSTER=openshell-c
+#OPENSHELL_GATEWAY=openshell-c
 
 # ---------- Ports ----------
 

.gitattributes

@@ -2,9 +2,9 @@
 # diffs, stats, and language detection.
 
 # Generated Python protobuf stubs
-python/navigator/_proto/*_pb2.py linguist-generated
-python/navigator/_proto/*_pb2_grpc.py linguist-generated
-python/navigator/_proto/*_pb2.pyi linguist-generated
+python/openshell/_proto/*_pb2.py linguist-generated
+python/openshell/_proto/*_pb2_grpc.py linguist-generated
+python/openshell/_proto/*_pb2.pyi linguist-generated
 
 # Generated Rust protobuf code (excludes hand-written mod.rs)
 crates/navigator-core/src/proto/navigator.*.rs linguist-generated

.gitignore

@@ -96,8 +96,8 @@ dmypy.json
 cython_debug/
 
 # Generated Python protobuf stubs (keep package marker)
-python/navigator/_proto/*
-!python/navigator/_proto/__init__.py
+python/openshell/_proto/*
+!python/openshell/_proto/__init__.py
 
 # =============================================================================
 # IDE / Editor

TESTING.md

@@ -13,7 +13,7 @@ mise run ci            # Everything: lint, compile checks, and tests
 ```
 crates/*/src/          # Inline #[cfg(test)] modules
 crates/*/tests/        # Rust integration tests
-python/navigator/      # Python unit tests (*_test.py suffix)
+python/openshell/      # Python unit tests (*_test.py suffix)
 e2e/python/            # Python E2E tests (test_*.py prefix)
 e2e/rust/              # Rust CLI E2E tests
 ```
@@ -49,7 +49,7 @@ mise run test:rust     # cargo test --workspace
 ## Python Unit Tests
 
 Python unit tests use the `*_test.py` suffix convention (not `test_*` prefix)
-and live alongside the source in `python/navigator/`. They use mock-based
+and live alongside the source in `python/openshell/`. They use mock-based
 patterns with fake gRPC stubs:
 
 ```python
@@ -167,4 +167,4 @@ The harness (`e2e/rust/src/harness/`) provides:
 
 | Variable | Purpose |
 |---|---|
-| `OPENSHELL_CLUSTER` | Override active cluster name for E2E tests |
+| `OPENSHELL_GATEWAY` | Override active gateway name for E2E tests |

architecture/README.md

@@ -238,7 +238,7 @@ The CLI is the primary way users interact with the platform. It provides command
 - **Provider management** (`openshell provider`): Create, update, list, and delete external service credentials.
 - **Inference management** (`openshell cluster inference`): Configure cluster-level inference by specifying a provider and model. The gateway resolves endpoint and credential details from the named provider record.
 
-The CLI resolves which cluster to operate on through a priority chain: explicit `--gateway` flag, then the `OPENSHELL_CLUSTER` environment variable, then the active cluster set by `openshell gateway select`. It supports TLS client certificates for mutual authentication with the gateway.
+The CLI resolves which gateway to operate on through a priority chain: explicit `--gateway` flag, then the `OPENSHELL_GATEWAY` environment variable, then the active gateway set by `openshell gateway select`. It supports TLS client certificates for mutual authentication with the gateway.
 
 ## How Users Get Started
 

architecture/build-containers.md

@@ -72,7 +72,7 @@ The sandbox container runs inside each sandbox pod. It contains the sandbox supe
 
 - Multi-user isolation: `supervisor` (runs the sandbox supervisor) and `sandbox` (runs the restricted agent process).
 - Policy files are mounted at `/var/navigator/policy.rego` (rules) and `/var/navigator/data.yaml` (data) when running in file-based policy mode.
-- The Python SDK is copied directly into the venv's site-packages at `/app/.venv/lib/python3.12/site-packages/navigator/`.
+- The Python SDK is copied directly into the venv's site-packages at `/app/.venv/lib/python3.12/site-packages/openshell/`.
 
 ### Gateway Image (`openshell/server`)
 

architecture/gateway-deploy-connect.md

@@ -12,8 +12,8 @@ When any CLI command needs to talk to the gateway, it resolves the target throug
 
 1. `--gateway-endpoint <URL>` flag (direct URL, reusing stored metadata when the gateway is known).
 2. `--cluster <NAME>` / `-g <NAME>` flag.
-3. `OPENSHELL_CLUSTER` environment variable.
-4. Active cluster from `~/.config/openshell/active_cluster`.
+3. `OPENSHELL_GATEWAY` environment variable.
+4. Active gateway from `~/.config/openshell/active_gateway`.
 
 Resolution loads `ClusterMetadata` from disk to get the `gateway_endpoint` URL and `auth_mode`. When `--gateway-endpoint` is used, the CLI still tries to match the URL to stored metadata so edge auth tokens and TLS bundles continue to resolve by cluster name.
 

architecture/tui.md

@@ -10,14 +10,14 @@ The TUI is a subcommand of the OpenShell CLI, so it inherits all your existing c
 openshell term                   # launch against the active gateway
 nav term                         # dev alias (builds from source)
 nav term --gateway prod          # target a specific gateway
-OPENSHELL_CLUSTER=prod nav term  # same thing, via environment variable
+OPENSHELL_GATEWAY=prod nav term  # same thing, via environment variable
 ```
 
 Gateway resolution follows the same priority as the rest of the CLI:
 
 1. `--gateway` flag (if provided)
-2. `OPENSHELL_CLUSTER` environment variable
-3. Active gateway from `~/.config/openshell/active_cluster`
+2. `OPENSHELL_GATEWAY` environment variable
+3. Active gateway from `~/.config/openshell/active_gateway`
 
 No separate configuration files or authentication are needed.
 

crates/navigator-cli/src/tls.rs

@@ -113,7 +113,7 @@ fn tls_dir_for_gateway(name: &str) -> Option<PathBuf> {
 ///
 /// Used when no gateway name is set (e.g., `SshProxy` which receives a raw URL).
 fn default_tls_dir(server: &str) -> Option<PathBuf> {
-    let mut name = std::env::var("OPENSHELL_GATEWAY_NAME")
+    let mut name = std::env::var("OPENSHELL_GATEWAY")
         .ok()
         .filter(|value| !value.trim().is_empty());
 

crates/navigator-cli/tests/mtls_integration.rs

@@ -347,13 +347,9 @@ async fn cli_requires_client_cert_for_https() {
     let addr = run_server(server_cert, server_key, ca_cert.clone()).await;
 
     let dir = tempdir().unwrap();
-    let cluster_name = dir
-        .path()
-        .file_name()
-        .unwrap()
-        .to_string_lossy()
-        .to_string();
-    let _env = EnvVarGuard::set("OPENSHELL_CLUSTER_NAME", &cluster_name);
+    // Point XDG_CONFIG_HOME at the isolated temp dir so that default_tls_dir
+    // cannot discover real client certs from the developer's machine.
+    let _xdg_env = EnvVarGuard::set("XDG_CONFIG_HOME", &dir.path().to_string_lossy());
     let ca_path = dir.path().join("ca.crt");
     std::fs::write(&ca_path, ca_cert).unwrap();