refactor(cli): remove kubeconfig port, add doctor llm-help, update debug docs (#252)

Author: drew

.agents/skills/debug-navigator-cluster/SKILL.md

@@ -497,8 +497,11 @@ openshell gateway destroy                               # Destroy permanently
 # Deploy to remote host
 openshell gateway start --remote user@host --ssh-key ~/.ssh/id_rsa --name remote-cluster
 
-# Set up kubectl access
-openshell gateway tunnel --name remote-cluster
+# View gateway container logs
+openshell doctor logs --name remote-cluster
+
+# Run kubectl inside the remote gateway container
+openshell doctor exec --name remote-cluster -- kubectl get pods -A
 
 # Get cluster info
 openshell gateway info --name remote-cluster

.agents/skills/openshell-cli/SKILL.md

@@ -29,7 +29,6 @@ openshell
 │   ├── stop [opts]
 │   ├── destroy [opts]
 │   ├── info [--name]
-│   ├── tunnel [opts]
 │   └── select [name]
 ├── status
 ├── inference
@@ -62,6 +61,9 @@ openshell
 │   ├── list [opts]
 │   ├── update <name> --type [opts]
 │   └── delete <name>...
+├── doctor
+│   ├── logs [--name] [-n] [--tail] [--remote] [--ssh-key]
+│   └── exec [--name] [--remote] [--ssh-key] -- <command...>
 ├── term
 ├── completions <shell>
 └── ssh-proxy [opts]
@@ -82,9 +84,6 @@ Provision or start a cluster (local or remote).
 | `--ssh-key <PATH>` | none | SSH private key for remote deployment |
 | `--port <PORT>` | 8080 | Host port mapped to gateway |
 | `--gateway-host <HOST>` | none | Override gateway host in metadata |
-| `--kube-port [PORT]` | none | Expose K8s control plane on host port |
-| `--update-kube-config` | false | Write kubeconfig into `~/.kube/config` |
-| `--get-kubeconfig` | false | Print kubeconfig to stdout |
 | `--recreate` | false | Destroy and recreate from scratch if a gateway already exists (skips interactive prompt) |
 
 ### `openshell gateway stop`
@@ -103,26 +102,47 @@ Destroy a cluster and all its state. Same flags as `stop`.
 
 ### `openshell gateway info`
 
-Show deployment details: endpoint, kubeconfig path, kube port, remote host.
+Show deployment details: endpoint and remote host.
 
 | Flag | Description |
 |------|-------------|
 | `--name <NAME>` | Cluster name (defaults to active) |
 
-### `openshell gateway tunnel`
+### `openshell gateway select [name]`
 
-Print or start an SSH tunnel for kubectl access to a remote cluster.
+Set the active gateway. Writes to `~/.config/openshell/active_gateway`. When called without arguments, lists all provisioned gateways with the active one marked with `*`.
 
-| Flag | Description |
-|------|-------------|
-| `--name <NAME>` | Cluster name (defaults to active) |
-| `--remote <USER@HOST>` | SSH destination |
-| `--ssh-key <PATH>` | SSH private key |
-| `--print-command` | Only print the SSH command, don't execute |
+---
 
-### `openshell gateway select [name]`
+## Doctor Commands
 
-Set the active gateway. Writes to `~/.config/openshell/active_gateway`. When called without arguments, lists all provisioned gateways with the active one marked with `*`.
+### `openshell doctor logs`
+
+Fetch logs from the gateway Docker container.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--name <NAME>` | active gateway | Gateway name |
+| `-n, --lines <N>` | all | Number of log lines to return |
+| `--tail` | false | Stream live logs (follow mode) |
+| `--remote <USER@HOST>` | auto-resolved | SSH destination for remote gateways |
+| `--ssh-key <PATH>` | none | SSH private key for remote gateways |
+
+### `openshell doctor exec -- <COMMAND...>`
+
+Run a command inside the gateway container with KUBECONFIG pre-configured.
+Launches an interactive `docker exec` session (tunnelled over SSH for remote gateways).
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--name <NAME>` | active gateway | Gateway name |
+| `--remote <USER@HOST>` | auto-resolved | SSH destination for remote gateways |
+| `--ssh-key <PATH>` | none | SSH private key for remote gateways |
+
+Examples:
+- `openshell doctor exec -- kubectl get pods -A`
+- `openshell doctor exec -- k9s`
+- `openshell doctor exec -- sh` (interactive shell)
 
 ---
 

.agents/skills/openshell-cli/cli-reference.md

@@ -34,8 +34,8 @@
 
 ## Bootstrap Crate Details
 - `docker.rs`: `ensure_container()` sets ~12 env vars (REGISTRY_*, IMAGE_*, PUSH_IMAGE_REFS, etc.)
-- `runtime.rs`: Polling params: kubeconfig 30x2s, health 180x2s, mTLS 90x2s
-- `metadata.rs`: Metadata at `clusters/{name}_metadata.json` (flat), kubeconfig/mTLS at `clusters/{name}/` (nested)
+- `runtime.rs`: Polling params: health 180x2s, mTLS 90x2s
+- `metadata.rs`: Metadata at `gateways/{name}/metadata.json` (nested), mTLS at `gateways/{name}/mtls/` (nested)
 - `push.rs`: Uses `ctr` (not `k3s ctr`) with k3s containerd socket, `k8s.io` namespace
 - IMPORTANT: `ClusterHandle::destroy()` does NOT remove metadata; only CLI `cluster_admin_destroy()` in run.rs does
 - `ensure_image()`: Local-only refs (no `/`) get error with build instructions, not a Docker Hub pull attempt

.claude/agent-memory/arch-doc-writer/MEMORY.md

@@ -20,9 +20,3 @@
 # Host port mapped to the k3s NodePort (30051) where the OpenShell gateway
 # listens.  The CLI connects here.  Must be unique per cluster.
 #GATEWAY_PORT=8080
-
-# Expose the Kubernetes control plane on this host port (maps to 6443
-# inside the container).  Leave unset to skip the binding — this is the
-# default and allows multiple clusters to coexist without port conflicts.
-# Set this only when you need direct kubectl access to the cluster.
-#KUBE_PORT=6443

.env.example

@@ -51,6 +51,24 @@ openshell --help
 openshell sandbox create -- codex
 ```
 
+### Cluster debugging helpers
+
+Two additional scripts in `scripts/bin/` provide gateway-aware wrappers for cluster debugging:
+
+| Script | What it does |
+|--------|-------------|
+| `kubectl` | Runs `kubectl` inside the active gateway's k3s container via `openshell doctor exec` |
+| `k9s` | Runs `k9s` inside the active gateway's k3s container via `openshell doctor exec` |
+
+These work for both local and remote gateways (SSH is handled automatically). Examples:
+
+```bash
+kubectl get pods -A
+kubectl logs -n navigator statefulset/navigator
+k9s
+k9s -n navigator
+```
+
 ## Main Tasks
 
 These are the primary `mise` tasks for day-to-day development:

CONTRIBUTING.md

@@ -232,7 +232,7 @@ For more detail, see [Policy Language](security-policy.md).
 
 The CLI is the primary way users interact with the platform. It provides commands organized into four groups:
 
-- **Gateway management** (`openshell gateway`): Deploy, stop, destroy, and inspect clusters. Supports both local and remote (SSH) targets. Includes a tunnel command for accessing the Kubernetes API on remote clusters.
+- **Gateway management** (`openshell gateway`): Deploy, stop, destroy, and inspect clusters. Supports both local and remote (SSH) targets.
 - **Sandbox management** (`openshell sandbox`): Create sandboxes (with optional file upload and provider auto-discovery), connect to sandboxes via SSH, and delete sandboxes.
 - **Top-level commands**: `openshell status` (cluster health), `openshell logs` (sandbox logs), `openshell forward` (port forwarding), `openshell policy` (sandbox policy management).
 - **Provider management** (`openshell provider`): Create, update, list, and delete external service credentials.

Cargo.lock

@@ -359,7 +359,7 @@ After building, the script:
 1. Resolves the local registry address (defaults to `127.0.0.1:5000/navigator`). In CI, uses `$CI_REGISTRY_IMAGE`.
 2. Ensures a local Docker registry container (`navigator-local-registry`) is running on port 5000 (creates one if needed).
 3. Pushes prebuilt local component images (server, sandbox) to the local registry via `cluster-push-component.sh`.
-4. Runs `nav gateway start --name <CLUSTER_NAME> --update-kube-config` to create or update the cluster container.
+4. Runs `nav gateway start --name <CLUSTER_NAME>` to create or update the cluster container.
 
 ### Environment Variables
 

architecture/README.md

@@ -97,7 +97,6 @@ openshell/
   clusters/
     <name>_metadata.json                  # ClusterMetadata JSON
     <name>/
-      kubeconfig                          # rewritten kubeconfig for kubectl
       mtls/                               # mTLS bundle (when TLS enabled)
         ca.crt                            # cluster CA certificate
         tls.crt                           # client certificate