docs: improve manifest and quickstart structure

Author: acmore

docs/config-manifest.md

@@ -43,11 +43,24 @@ spec: {}
 - `idleTimeoutMinutes` (`int`, default from template): reserved for lifecycle policy.
 - `shareable` (`bool`): marks intent for team sharing workflows.
 
-Validation:
+### Example
+
+```yaml
+spec:
+  session:
+    defaultNameTemplate: "{{ .Repo }}-{{ .Branch }}-{{ .User }}"
+    ttlHours: 72
+    idleTimeoutMinutes: 120
+    shareable: true
+```
+
+### Validation
+
 - `ttlHours >= 0`
 - `idleTimeoutMinutes >= 0`
 
-Context precedence:
+### Context Precedence
+
 - `--context` CLI flag (highest)
 - `spec.kubeContext` from manifest
 - active kubeconfig current-context (default client behavior)
@@ -59,7 +72,31 @@ Context precedence:
 - Define storage source with standard `VolumeSource` (for example `emptyDir`, `persistentVolumeClaim`, `ephemeral`, `configMap`, `secret`).
 - Mount points are defined with standard Kubernetes `volumeMounts` in `spec.podTemplate.spec.containers[*].volumeMounts`.
 
-Workspace behavior:
+### Example
+
+```yaml
+spec:
+  volumes:
+    - name: workspace
+      persistentVolumeClaim:
+        claimName: team-workspace
+    - name: datasets
+      persistentVolumeClaim:
+        claimName: shared-datasets
+  podTemplate:
+    spec:
+      containers:
+        - name: dev
+          volumeMounts:
+            - name: workspace
+              mountPath: /workspace
+            - name: datasets
+              mountPath: /data
+              readOnly: true
+```
+
+### Workspace Behavior
+
 - If a `workspace` volume is not provided, okdev injects:
   - `name: workspace`
   - `emptyDir: {}`
@@ -79,20 +116,54 @@ Workspace behavior:
   - `autoInstall` (`bool`, default: `true`)
   - `image` (`string`, default: `ghcr.io/acmore/okdev:<okdev-version>` with `edge` fallback)
 
-Validation:
+### Example
+
+```yaml
+spec:
+  sync:
+    engine: syncthing
+    syncthing:
+      version: v1.29.7
+      autoInstall: true
+    paths:
+      - .:/workspace
+    exclude:
+      - .git/
+      - node_modules/
+      - .venv/
+    remoteExclude:
+      - ".cache/"
+```
+
+### Validation
+
 - `engine` must be `syncthing`
 - each `paths[]` entry must be `local:remote`
 - currently at most one `paths[]` entry
 
 ## `spec.ports`
 
-Each item:
+### Each Item
 
 - `name` (`string`, optional)
 - `local` (`int`, required): local listening port
 - `remote` (`int`, required): remote target port in dev environment
 
-Validation:
+### Example
+
+```yaml
+spec:
+  ports:
+    - name: app
+      local: 8080
+      remote: 8080
+    - name: tensorboard
+      local: 6006
+      remote: 6006
+```
+
+### Validation
+
 - `local` and `remote` must be `1..65535`
 - `local` ports must be unique
 
@@ -105,7 +176,21 @@ Validation:
 - `keepAliveIntervalSeconds` (`int`, default: `10`)
 - `keepAliveTimeoutSeconds` (`int`, default: `10`)
 
-Validation:
+### Example
+
+```yaml
+spec:
+  ssh:
+    user: root
+    privateKeyPath: ~/.okdev/ssh/id_ed25519
+    autoDetectPorts: true
+    persistentSession: true
+    keepAliveIntervalSeconds: 30
+    keepAliveTimeoutSeconds: 90
+```
+
+### Validation
+
 - `keepAliveIntervalSeconds > 0`
 - `keepAliveTimeoutSeconds > 0`
 - `keepAliveTimeoutSeconds >= keepAliveIntervalSeconds`
@@ -115,22 +200,64 @@ Validation:
 - `postCreate` (`string`, optional): command executed once after environment creation.
 - `preStop` (`string`, optional): command executed before pod termination.
 
+### Example
+
+```yaml
+spec:
+  lifecycle:
+    postCreate: uv sync --dev
+    preStop: pkill -f my-dev-server || true
+```
+
 ## `spec.sidecar`
 
 - `image` (`string`, required)
 
-Recommended:
+### Example
+
+```yaml
+spec:
+  sidecar:
+    image: ghcr.io/acmore/okdev:v0.2.16
+```
+
+### Recommended
+
 - use release-aligned tag, for example `ghcr.io/acmore/okdev:v0.2.0`
 
 ## `spec.podTemplate`
 
-Direct PodSpec overlay:
+### Direct PodSpec Overlay
 
 - `metadata.labels` (`map[string]string`, optional)
 - `spec` (`k8s PodSpec`, optional)
 
 Use this to define the dev container image, resources, extra sidecars, env vars, and scheduling settings.
 
+### Example
+
+```yaml
+spec:
+  podTemplate:
+    spec:
+      containers:
+        - name: dev
+          image: nvidia/cuda:12.4.1-devel-ubuntu22.04
+          command: ["sleep", "infinity"]
+          env:
+            - name: HF_HOME
+              value: /workspace/.cache/huggingface
+          resources:
+            requests:
+              cpu: "8"
+              memory: 32Gi
+              nvidia.com/gpu: "1"
+            limits:
+              cpu: "16"
+              memory: 64Gi
+              nvidia.com/gpu: "1"
+```
+
 ## Example Manifest
 
 ```yaml

docs/quickstart.md

@@ -27,12 +27,14 @@ okdev version
 ./bin/okdev init --template gpu
 ```
 
-Configuration discovery order:
+## Configuration Discovery
+
 1. `-c, --config <path>`
 2. `.okdev.yaml`
 3. `okdev.yaml`
 
-Kubernetes context precedence:
+## Kubernetes Context
+
 1. `--context`
 2. `spec.kubeContext` in manifest
 3. active kube context from your kubeconfig
@@ -43,19 +45,20 @@ Kubernetes context precedence:
 ./bin/okdev up
 ```
 
-Use an explicit session name when running multiple environments for the same repo:
+### Named Sessions
 
 ```bash
 ./bin/okdev up --session serving-main-alice
 ```
 
-Tmux-backed persistent shells are enabled by default. Disable them for a pod with:
+### Disable Tmux
 
 ```bash
 ./bin/okdev up --no-tmux
 ```
 
-`okdev up` performs one-step setup:
+### What `okdev up` Does
+
 - ensures Pod/PVC state
 - writes managed `~/.ssh/config` host entry (`okdev-<session>`)
 - starts managed SSH/forwarding bootstrap
@@ -78,7 +81,8 @@ Tmux-backed persistent shells are enabled by default. Disable them for a pod wit
 ./bin/okdev sync --background
 ```
 
-Notes:
+## Notes
+
 - Local Syncthing is auto-installed when `sync.engine=syncthing`.
 - `okdev up` starts background sync in bidirectional mode by default.
 - Default sidecar image (syncthing + okdev-sshd binary) follows binary version: `ghcr.io/<owner>/okdev:<okdev-version>` (`edge` for dev builds).
@@ -92,9 +96,7 @@ Notes:
 - The managed SSH host entry uses tighter proxy keepalive settings than the general CLI defaults so hung `ssh okdev-<session>` sessions fail fast instead of freezing indefinitely.
 - Proxy health diagnostics are written to `~/.okdev/logs/okdev.log`, not printed into the SSH client session.
 - Tmux uses a built-in okdev profile (history/mouse/vi-copy/status) and keeps the default command prefix (`Ctrl-b`).
-- SSH keepalive can be tuned with:
-  - `spec.ssh.keepAliveIntervalSeconds` (default `30`)
-  - `spec.ssh.keepAliveTimeoutSeconds` (default `90`, must be `>= interval`)
+- SSH keepalive can be tuned with `spec.ssh.keepAliveIntervalSeconds` (default `30`) and `spec.ssh.keepAliveTimeoutSeconds` (default `90`, must be `>= interval`).
 
 ## Preview Mode (No Cluster Mutations)
 

docs/release.md

@@ -8,7 +8,7 @@
 - `MINOR`: backward-compatible features.
 - `PATCH`: backward-compatible fixes.
 
-Tag format:
+### Tag Format
 
 - `vX.Y.Z` (example: `v0.2.1`)
 
@@ -22,23 +22,17 @@ git tag v0.1.0
 git push origin v0.1.0
 ```
 
-3. GitHub Actions `Release` workflow builds binaries for:
-   - `linux/amd64`
-   - `linux/arm64`
-   - `darwin/amd64`
-   - `darwin/arm64`
-4. Workflow publishes assets:
-   - `okdev_<os>_<arch>.tar.gz`
-   - `checksums.txt`
+3. GitHub Actions `Release` workflow builds binaries for `linux/amd64`, `linux/arm64`, `darwin/amd64`, and `darwin/arm64`.
+4. Workflow publishes `okdev_<os>_<arch>.tar.gz` assets plus `checksums.txt`.
 
 ## Sidecar image tags
 
-Sidecar image tags are aligned with the `okdev` release tag:
+### Published Tags
 
 - release `vX.Y.Z` publishes:
-  - `ghcr.io/acmore/okdev:vX.Y.Z` (sidecar runtime: syncthing + okdev-sshd binary)
+  `ghcr.io/acmore/okdev:vX.Y.Z` (sidecar runtime: syncthing + okdev-sshd binary)
 - dev/main pushes publish:
-  - `ghcr.io/acmore/okdev:edge`
+  `ghcr.io/acmore/okdev:edge`
 
 Default sidecar image resolution uses the running `okdev` binary version, with `edge` fallback for dev builds.
 
@@ -48,7 +42,7 @@ Default sidecar image resolution uses the running `okdev` binary version, with `
 curl -fsSL https://raw.githubusercontent.com/acmore/okdev/main/scripts/install.sh | sh
 ```
 
-Install specific version:
+### Install Specific Version
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/acmore/okdev/main/scripts/install.sh | sh -s -- v0.1.0