macstadium · celanthe · May 13, 2026 · Jun 22, 2026
diff --git a/orka3-cli/SKILL.md b/orka3-cli/SKILL.md
@@ -27,6 +27,8 @@ Orka virtualizes macOS on physical Mac hardware. The CLI (`orka3`) manages VMs,
 
 **Kubernetes upgrade resilience (v3.6+)** — Most orka3 commands continue working during k8s control-plane upgrades. Only `login` and `vm push` require the API server; expect failures for those two until the upgrade completes.
 
+**VM network isolation (v3.6+, Apple Silicon only)** — MacStadium can configure per-cluster allow/deny rules by CIDR block to restrict VM network access. Configured by support, not via CLI. Contact support@macstadium.com to set up.
+
 ## Quick CLI Guide
 
 ### Setup
@@ -178,3 +180,5 @@ Quick command syntax is above. Load references for complete workflows, detailed
 | GitHub Actions (ephemeral runners) | `references/integrations/github-actions.md` |
 | Buildkite (ephemeral/permanent agents) | `references/integrations/buildkite.md` |
 | TeamCity cloud agent plugin | `references/integrations/teamcity.md` |
+
+If you need full Orka documentation beyond what's in this skill, it's available via MCP at `https://docs.macstadium.com/mcp`. Prefer the skill contents first for CLI tasks.
diff --git a/orka3-cli/references/commands/config-commands.md b/orka3-cli/references/commands/config-commands.md
@@ -145,3 +145,5 @@ orka3 version [flags]
 **Output Includes:**
 - CLI build information
 - Compatibility with Orka cluster
+- Upgrade Service operator version (v3.6+)
+- Upgrade Service agent version per node (v3.6+)
diff --git a/orka3-cli/references/commands/vm-commands.md b/orka3-cli/references/commands/vm-commands.md
@@ -38,7 +38,7 @@ orka3 vm deploy [<NAME>] --config <TEMPLATE> [flags]
 - `--generate-name` - Generate unique name with suffix
 - `--scheduler string` - Scheduler: 'default' or 'most-allocated'
 - `--metadata stringToString` - Custom metadata (key1=value1,key2=value2)
-- `-p, --ports strings` - Port mapping (NODE_PORT:VM_PORT)
+- `-p, --ports strings` - Port mapping (NODE_PORT:VM_PORT[/tcp|/udp]); protocol defaults to TCP if omitted
 - `--timeout int` - Deployment timeout in minutes (default: 10)
 - `-n, --namespace string` - Target namespace
 - `-o, --output string` - Output format: json|wide
@@ -72,6 +72,7 @@ orka3 vm deploy --image sonoma:latest --namespace orka-test
 # Advanced deployments
 orka3 vm deploy --image sonoma:latest --metadata 'foo=1,baz=https://example.com'
 orka3 vm deploy --image sonoma:latest --ports 9000:4000,9001:4001
+orka3 vm deploy --image sonoma:latest --ports 9000:4000/udp,9001:4001/tcp
 
 # Intel-only deployments
 orka3 vm deploy --image emptydisk.img --iso ventura.iso

diff --git a/orka3-cli/references/integrations/github-actions.md b/orka3-cli/references/integrations/github-actions.md
@@ -16,6 +16,8 @@ Image: `ghcr.io/macstadium/orka-github-runner:<tag>`
 
 A Docker-based controller that listens for GitHub Actions workflow runs and spins up ephemeral Orka VMs to execute them. Uses GitHub runner scale sets (similar to ARC). Each job gets a fresh VM; the VM is deleted after the job completes.
 
+The integration tracks in-flight VM deployments to prevent over-provisioning when multiple jobs start simultaneously. On restart, it reconciles existing VMs (adopting running ones, cleaning up failed/finished ones) and reuses the existing runner scale set so in-progress jobs continue uninterrupted.
+
 ## Prerequisites
 
 - GitHub App (not a PAT). Instructions: `docs/github-app-setup-steps.md` in the repo.
@@ -53,7 +55,7 @@ docker run -v /path/to/.env:/.env ghcr.io/macstadium/orka-github-runner:<tag>
 |----------|----------|-------------|
 | `GITHUB_APP_ID` | Yes | GitHub App ID |
 | `GITHUB_APP_INSTALLATION_ID` | Yes | GitHub App installation ID |
-| `GITHUB_APP_PRIVATE_KEY_PATH` or `GITHUB_APP_PRIVATE_KEY` | Yes | Private key file path or contents (PKCS#1 RSA format) |
+| `GITHUB_APP_PRIVATE_KEY_PATH` or `GITHUB_APP_PRIVATE_KEY` | Yes | Private key file path or contents (PKCS#1 RSA or ECDSA format) |
 | `GITHUB_URL` | Yes | Repo or org URL, e.g. `https://github.com/myorg` |
 | `ORKA_URL` | Yes | Orka API URL, e.g. `http://10.221.188.20` |
 | `ORKA_TOKEN` | Yes | Service account token |
@@ -66,6 +68,8 @@ docker run -v /path/to/.env:/.env ghcr.io/macstadium/orka-github-runner:<tag>
 | `LOG_LEVEL` | No | `info` (default), `debug`, `warning`, `error` |
 | `ENABLE_METRICS` | No | Expose Prometheus metrics at `/metrics` on `METRICS_ADDR` |
 | `METRICS_ADDR` | No | Default `:8080` |
+| `ENABLE_RECONCILIATION` | No | Reconcile existing VMs on restart instead of ignoring them (default: `True`) |
+| `MANAGE_RUNNER_SCALE_SETS` | No | Reuse existing runner scale set on restart (default: `True`) |
 
 ## Auth
 
@@ -84,7 +88,7 @@ orka3 sa token <name> --no-expiration
 
 ## Private key format
 
-GitHub App private keys must be in PKCS#1 RSA format. If needed, convert:
+GitHub App private keys must be in PKCS#1 RSA or ECDSA format (ECDSA support added in Orka 3.6). If needed, convert an RSA key:
 
 ```bash
 ssh-keygen -p -m pem -f /path/to/private-key.pem

diff --git a/orka3-cli/references/integrations/packer.md b/orka3-cli/references/integrations/packer.md
@@ -93,6 +93,10 @@ The repo includes example templates in `examples/` (Sequoia and Tahoe, 90 GB and
 
 **Known fix (PR #84, pending merge):** The examples had two bugs — Homebrew requires Xcode CLT to be installed first (the templates skipped this step), and the `brew shellenv` eval line was missing a closing `)` so PATH was never set in `.zprofile`. Both are fixed in PR #84. Until it merges, the existing example templates will fail Homebrew installation.
 
+## Bridge networking
+
+Bridge networking (introduced in Orka 3.5) is supported by the Packer plugin as of Orka 3.6. No plugin config change is needed — the plugin works transparently with bridge-networked clusters.
+
 ## Gotchas
 
 - **VPN required.** Packer must have network connectivity to the Orka endpoint. If running locally, connect via VPN first.

diff --git a/orka3-cli/references/workflows/image-workflows.md b/orka3-cli/references/workflows/image-workflows.md
@@ -31,8 +31,9 @@ orka3 vm list base-config --output wide
 #    - Configure settings
 #    - Install/upgrade Orka VM Tools:
 #      brew install orka-vm-tools  # or brew upgrade orka-vm-tools
-#      Note: Base images from ghcr.io/macstadium/orka-images (3.6+) already include
-#      the current VM Tools version. Skip this step if using a current base image.
+#      Note: Base images from ghcr.io/macstadium/orka-images are automatically kept
+#      current with VM Tools on each Orka release (3.6+). Skip this step if using a
+#      current GHCR base image. Only needed for custom images not derived from one.
 
 # 5. Save as new image (preserves original)
 orka3 vm save base-config my-configured-sonoma