docs: update user guides for tmux ssh flow

Author: acmore

docs/command-reference.md

@@ -17,15 +17,17 @@
 - `okdev validate`
 - `okdev up [--wait-timeout 3m] [--dry-run]`
   - Reconciles Pod/PVC resources, updates SSH config, initializes managed forwarding/sync, then exits.
+  - `--tmux`: enable persistent interactive shells by setting tmux mode on the sidecar.
   - `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 "..."]`
+- `okdev ssh [--setup-key] [--user root] [--cmd "..."] [--no-tmux]`
   - Targets merged `okdev-sidecar` (`sshd` + Syncthing).
   - Maintains managed host alias in `~/.ssh/config` as `okdev-<session>`.
+  - `--no-tmux`: bypass tmux for this SSH session when tmux mode is enabled.
 - `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/quickstart.md

@@ -44,17 +44,25 @@ Use an explicit session name when running multiple environments for the same rep
 ./bin/okdev up --session serving-main-alice
 ```
 
+Enable persistent interactive shells backed by tmux:
+
+```bash
+./bin/okdev up --tmux
+```
+
 `okdev up` performs one-step setup:
 - ensures Pod/PVC state
 - writes managed `~/.ssh/config` host entry (`okdev-<session>`)
 - starts managed SSH/forwarding bootstrap
 - starts background Syncthing sync when enabled
+- exits after setup (no attach mode)
 
 ## Access and Data Movement
 
 ```bash
 ./bin/okdev connect
 ./bin/okdev ssh --setup-key
+./bin/okdev ssh
 ./bin/okdev sync --mode up
 ./bin/okdev ports
 
@@ -71,6 +79,9 @@ Notes:
 - `spec.sync.exclude` applies local ignore patterns; `spec.sync.remoteExclude` applies remote-only ignores.
 - SSH target is always the merged `okdev-sidecar` container (`sshd` on `22`).
 - `spec.ports` are rendered as SSH `LocalForward` entries.
+- Local runtime state/logs are stored under `~/.okdev/` (not in the project working directory).
+- Use `ssh okdev-<session>` for direct SSH. For tmux-backed interactive sessions, force TTY (`ssh -tt okdev-<session>`).
+- Use `okdev ssh --no-tmux` to bypass tmux for a single connection.
 - SSH keepalive can be tuned with:
   - `spec.ssh.keepAliveIntervalSeconds` (default `10`)
   - `spec.ssh.keepAliveTimeoutSeconds` (default `15`, must be `>= interval`)

docs/troubleshooting.md

@@ -34,6 +34,15 @@
 - If local bind conflicts occur, use `okdev ssh --local-port <port>`.
 - Verify managed entry exists in `~/.ssh/config`:
   - `Host okdev-<session>`
+- For tmux-enabled sessions, use interactive TTY mode:
+  - `okdev ssh` or `ssh -tt okdev-<session>`
+- To bypass tmux for one connection:
+  - `okdev ssh --no-tmux`
 - For unstable links, increase:
   - `spec.ssh.keepAliveIntervalSeconds`
   - `spec.ssh.keepAliveTimeoutSeconds`
+
+## Local State Files
+
+- okdev stores local runtime state in `~/.okdev/` (locks, logs, SSH metadata, sync state).
+- If behavior looks stale after upgrades, inspect and clean targeted files under `~/.okdev/` instead of deleting project files.