feat(session): move local state to home and refine docs

Author: acmore

.gitignore

@@ -1,3 +1,6 @@
 /bin/
 *.test
 .DS_Store
+
+.stignore
+.okdev.yaml

docs/command-reference.md

@@ -2,30 +2,30 @@
 
 ## Global Flags
 
-- `-c, --config`: config file path
-- `--session`: session name override
-- `--owner`: owner identity override (default: `OKDEV_OWNER` or local `USER`)
+- `-c, --config`: configuration file path
+- `--session`: explicit session identifier
+- `--owner`: owner label override (default: `OKDEV_OWNER` or local `USER`)
 - `-n, --namespace`: namespace override
-- `--context`: kube context override
-- `--output text|json`: output format for list/status
-- `--verbose`: enable debug logging
+- `--context`: kubeconfig context override
+- `--output text|json`: output format (`list`, `status`)
+- `--verbose`: debug logging
 
 ## Commands
 
 - `okdev version`
 - `okdev init [--template basic|gpu|llm-stack] [--force]`
 - `okdev validate`
 - `okdev up [--wait-timeout 3m] [--dry-run]`
-  - prepares pod/workspace, SSH config, managed SSH+port-forwards, and background sync (when enabled), then exits
-  - `spec.ports` are applied via managed SSH `LocalForward` rules
+  - Reconciles Pod/PVC resources, updates SSH config, initializes managed forwarding/sync, then exits.
+  - `spec.ports` is materialized as SSH `LocalForward`.
 - `okdev down [--delete-pvc] [--dry-run]`
 - `okdev status [--all] [--all-users]`
 - `okdev list [--all-namespaces] [--all-users]`
 - `okdev use <session>`
 - `okdev connect [--shell /bin/bash] [--cmd "..."] [--no-tty]`
 - `okdev ssh [--setup-key] [--user root] [--cmd "..."]`
-  - SSH always targets the merged `okdev-sidecar` container (`sshd` + syncthing).
-  - `okdev` writes managed host aliases to `~/.ssh/config` as `okdev-<session>`.
+  - Targets merged `okdev-sidecar` (`sshd` + Syncthing).
+  - Maintains managed host alias in `~/.ssh/config` as `okdev-<session>`.
 - `okdev ports`
 - `okdev sync [--mode up|down|bi] [--background] [--dry-run]`
 - `okdev prune [--ttl-hours 72] [--all-namespaces] [--all-users] [--include-pvc] [--dry-run]`

docs/index.md

@@ -1,20 +1,21 @@
 # okdev
 
-Lightweight Kubernetes-native dev environments for AI infra engineering.
+`okdev` is a CRD-less CLI for Kubernetes development sessions.
+It provisions and operates dev environments from `.okdev.yaml` using standard Pod/PVC resources.
 
-## What You Get
+## Core Capabilities
 
-- PodSpec-first config via `.okdev.yaml`
-- Multi-session support per repo/branch/user
-- Shell/SSH access, sync, and port forwarding
-- Cross-machine reattach with cluster-native session identity
-- Syncthing-based sync engine
+- PodSpec-driven environment definition
+- Multi-session workflow per repo/branch/user
+- Session setup via `okdev up` (SSH config, managed forwards, sync bootstrap)
+- Syncthing-based workspace synchronization
+- Reattach from any machine with kube access
 
-## Read the Docs
+## Documentation
 
 - [Quickstart](quickstart.md)
 - [Command Reference](command-reference.md)
+- [Troubleshooting](troubleshooting.md)
 - [Design](okdev-design.md)
 - [Implementation Plan](okdev-implementation-plan.md)
 - [Release & Versioning](release.md)
-- [Troubleshooting](troubleshooting.md)

docs/okdev-design.md

@@ -2,20 +2,21 @@
 
 ## 1. Overview
 
-`okdev` is a lightweight, Kubernetes-native development environment tool for AI/LLM infra engineers.
+`okdev` is a Kubernetes-native CLI for development session orchestration, designed for AI/LLM infrastructure workflows.
 
 It intentionally avoids:
-- Okteto-style platform coupling and heavy cloud assumptions
-- DevPod-style UI dependency and single-machine-bound workflows
+- platform-coupled hosted control planes
+- UI-dependent workflows
+- machine-local session state as source of truth
 
-It centers on one idea:
-- **A Kubernetes PodSpec (with minimal okdev metadata) defines the full dev environment**
+Core model:
+- **A PodSpec plus minimal `okdev` metadata defines the development environment.**
 
 Design goals:
-- Simple CLI + Kubernetes API integration
-- Shareable dev sessions across machines and teammates
-- Works with existing clusters, namespaces, RBAC, and admission policies
-- Reproducible LLM infra dev stacks (GPU, model caches, large datasets, sidecars)
+- deterministic CLI behavior over Kubernetes APIs
+- cross-machine session reattachment
+- compatibility with existing namespace/RBAC/admission policy constraints
+- reproducible AI infra stacks (GPU, cache volumes, large data paths, sidecars)
 
 ---
 
@@ -57,22 +58,22 @@ Needs:
 ## 4. Product Principles
 
 1. **PodSpec-first**: no custom DSL required for core environment definition.
-2. **Stateless client**: source of truth lives in Git + cluster objects, not local hidden state.
+2. **Stateless control path**: source of truth is Git + cluster objects, not a proprietary control plane.
 3. **Kubernetes-native identity**: contexts, kubeconfig, namespaces, service accounts.
 4. **Explicit over implicit**: predictable commands and clear object ownership.
-5. **Low cognitive load**: a small command set that covers 80% of daily dev.
+5. **Operational simplicity**: small command surface with clear failure modes.
 
 ---
 
 ## 5. UX Summary
 
-Core flow:
+Execution flow:
 1. Developer adds `.okdev.yaml` to repo, embedding or referencing PodSpec.
 2. `okdev up` creates/resumes a dev session in a namespace.
-3. `okdev connect` opens terminal/SSH and optionally starts port forwards.
+3. `okdev up` configures SSH aliasing, managed forwards, and sync bootstrap.
 4. `okdev sync` mirrors local repo <-> pod workspace.
-5. Developer can leave and later reconnect from another machine via `okdev up`.
-6. `okdev down` stops session (or deletes, based on policy).
+5. Developer reconnects later from any machine with kube access via `okdev up` / `okdev ssh`.
+6. `okdev down` tears down runtime resources; PVC cleanup is explicit.
 
 ---
 
@@ -192,8 +193,8 @@ Notes:
 
 Avoiding a custom operator keeps setup simple and portable:
 - lower operational overhead
-- easier to adopt in locked-down enterprise clusters
-- fewer cluster-wide permissions
+- easier adoption in restricted enterprise clusters
+- avoids cluster-wide CRD/controller requirements
 
 A controller/operator can be added later for advanced fleet features.
 

docs/plans/2026-03-08-tmux-persistent-sessions-design.md

@@ -0,0 +1,63 @@
+# Tmux Persistent Shell Sessions
+
+## Problem
+
+SSH sessions die on network drops (kube port-forward instability, WiFi blips). The SSH protocol cannot resume a session on a new TCP connection. Users lose their shell state and must restart their work.
+
+## Solution
+
+Wrap interactive SSH sessions in tmux on the server side. On reconnect, users automatically reattach to their existing shell session. Controlled by config and CLI flag, off by default.
+
+## Design
+
+### Activation
+
+- Config field: `spec.ssh.persistentSession` (bool pointer, default false)
+- CLI flag: `okdev up --tmux` (overrides config)
+- Per-connection opt-out: `okdev ssh --no-tmux` (sends `OKDEV_NO_TMUX=1` env var via SSH)
+
+### Implementation
+
+The change is server-side in the sidecar's `nsenter-dev.sh` ForceCommand handler. No changes to Go SSH client code.
+
+1. `okdev up --tmux` sets env var `OKDEV_TMUX=1` on the sidecar container in the pod manifest
+2. `nsenter-dev.sh` checks `OKDEV_TMUX=1`, `OKDEV_NO_TMUX!=1`, and whether the session has a TTY
+3. If all conditions met: `exec nsenter ... tmux new-session -A -s okdev`
+4. Otherwise: bare shell or command as today
+
+### Interactive vs Non-Interactive Detection
+
+```bash
+if [ "$OKDEV_TMUX" = "1" ] && [ "$OKDEV_NO_TMUX" != "1" ] && [ -t 0 ]; then
+    exec nsenter ... tmux new-session -A -s okdev
+else
+    exec nsenter ... "$@"
+fi
+```
+
+### Session Naming
+
+Single `okdev` tmux session with multiple windows. `tmux new-session -A -s okdev` creates if missing, attaches if exists. New connections become new windows in the same session.
+
+### tmux Availability
+
+tmux must be installed in the sidecar image. If missing at runtime, fall back to bare shell with a warning to stderr.
+
+### Toggling
+
+Requires pod restart. `okdev up --tmux` enables, `okdev up` (without flag) disables. Consistent with other pod-level settings.
+
+## Components Modified
+
+- `internal/config/config.go` — add `PersistentSession *bool` to `SSHSpec`, wire defaults
+- `internal/cli/up.go` — add `--tmux` flag, merge with config value
+- Pod builder (wherever sidecar env vars are set) — set `OKDEV_TMUX=1` on sidecar container
+- `internal/cli/ssh.go` — add `--no-tmux` flag, send `OKDEV_NO_TMUX=1` env var
+- `infra/sidecar/entrypoint.sh` / `nsenter-dev.sh` — check env vars + TTY, wrap with tmux
+- Sidecar Dockerfile — install tmux
+
+## Out of Scope
+
+- Auto-reconnect for port forwards (separate feature)
+- Client-side changes to `OpenShell()`
+- Multi-user session isolation