feat: add guided walkthrough with Codespaces support

.devcontainer/dev/devcontainer.json

@@ -0,0 +1,20 @@
+{
+  "name": "pgEdge Control Plane Development",
+  "image": "mcr.microsoft.com/devcontainers/go:1.25",
+  "features": {
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {}
+  },
+  "postCreateCommand": "go mod download",
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "terminal.integrated.defaultProfile.linux": "bash",
+        "go.lintTool": "golangci-lint"
+      },
+      "extensions": [
+        "golang.go",
+        "redhat.vscode-yaml"
+      ]
+    }
+  }
+}

.devcontainer/walkthrough/devcontainer.json

@@ -0,0 +1,23 @@
+{
+  "name": "pgEdge Control Plane Walkthrough",
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+  "hostRequirements": {
+    "cpus": 4
+  },
+  "features": {
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {}
+  },
+  "postCreateCommand": "bash .devcontainer/walkthrough/post-create.sh",
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "terminal.integrated.defaultProfile.linux": "bash",
+        "workbench.startupEditor": "none"
+      },
+      "extensions": [
+        "stateful.runme"
+      ]
+    }
+  },
+  "postAttachCommand": "code docs/walkthrough.md 2>/dev/null || true"
+}

.devcontainer/walkthrough/post-create.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "=== pgEdge Control Plane Walkthrough — Codespaces Setup ==="
+
+# Add the pgEdge repository
+echo "Adding pgEdge apt repository..."
+sudo curl -sSL https://apt.pgedge.com/repodeb/pgedge-release_latest_all.deb -o /tmp/pgedge-release.deb
+sudo dpkg -i /tmp/pgedge-release.deb
+
+# Install jq and the Postgres client
+echo "Installing jq and pgEdge Postgres client..."
+sudo apt-get update -qq
+sudo apt-get install -y -qq jq pgedge-postgresql-client-18
+# Run the prerequisites check
+echo ""
+bash examples/walkthrough/setup.sh
+
+echo ""
+echo "Setup complete!"
+echo "  Interactive Guide: bash examples/walkthrough/guide.sh"
+echo "  Walkthrough:       Open docs/walkthrough.md (Runme extension installed)"

.gitignore

@@ -15,6 +15,8 @@ bruno/test-scenarios/environments
 **/.claude/settings.local.json
 .idea
 
+docs/plans
+
 # build artifacts
 *-results.xml
 dist