From 07b7f1922ccc15fb1354b045ba70ca2c74deeb65 Mon Sep 17 00:00:00 2001
From: Rin Oliver <roliver@macstadium.com>
Date: Wed, 13 May 2026 11:16:18 -0500
Subject: [PATCH 1/2] docs: add MCP documentation pointer to SKILL.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 orka3-cli/SKILL.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/orka3-cli/SKILL.md b/orka3-cli/SKILL.md
index c9f2a08..2d43fe6 100644
--- a/orka3-cli/SKILL.md
+++ b/orka3-cli/SKILL.md
@@ -178,3 +178,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.

From 6336261c63120c5ff2c8089bdcae5ea1f047b5e0 Mon Sep 17 00:00:00 2001
From: Rin Oliver <roliver@macstadium.com>
Date: Mon, 22 Jun 2026 15:00:29 -0500
Subject: [PATCH 2/2] update skill references for Orka 3.6 and 3.6.2

- Add UDP/TCP protocol suffix to vm deploy --ports flag
- Update orka3 version output to include Upgrade Service versions
- Add ENABLE_RECONCILIATION and MANAGE_RUNNER_SCALE_SETS env vars to GHA reference
- Note ECDSA key support and restart reconciliation behavior in GHA reference
- Add bridge networking note to Packer reference
- Update VM Tools note to reflect automated GHCR updates
- Add VM network isolation note to SKILL.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 orka3-cli/SKILL.md                                  | 2 ++
 orka3-cli/references/commands/config-commands.md    | 2 ++
 orka3-cli/references/commands/vm-commands.md        | 3 ++-
 orka3-cli/references/integrations/github-actions.md | 8 ++++++--
 orka3-cli/references/integrations/packer.md         | 4 ++++
 orka3-cli/references/workflows/image-workflows.md   | 5 +++--
 6 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/orka3-cli/SKILL.md b/orka3-cli/SKILL.md
index 2d43fe6..eb65702 100644
--- 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
diff --git a/orka3-cli/references/commands/config-commands.md b/orka3-cli/references/commands/config-commands.md
index 80a1c3f..c3f7f6d 100644
--- 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
index 36055db..f5c3c60 100644
--- 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
index 9544eb0..a111ef3 100644
--- 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
index f30e6ee..55b36cf 100644
--- 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
index 4c71e73..b7f4174 100644
--- 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