feat(devcontainer): add devc CLI helper and devcontainer skill doc

- install.sh: devc CLI (up/shell/build/stop/self-install) adapted from
  trailofbits/devcontainer-setup skill pattern
- skills/devcontainer.md: documents design decisions, local workflow,
  how to add tools, and devcontainers/ci future migration plan

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: castrojo

.devcontainer/install.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# devc — CLI helper for the testhub devcontainer
+# Adapted from trailofbits/devcontainer-setup (https://skills.sh/trailofbits/skills/devcontainer-setup)
+#
+# Usage:
+#   .devcontainer/install.sh self-install   # install `devc` to ~/.local/bin
+#   devc up                                 # start the devcontainer
+#   devc shell                              # open a shell in the running container
+#   devc build <app>                        # run `just loop <app>` inside the container
+#   devc stop                               # stop the devcontainer
+
+set -euo pipefail
+
+WORKSPACE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCRIPT_PATH="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/install.sh"
+
+case "${1:-help}" in
+  self-install)
+    mkdir -p "$HOME/.local/bin"
+    ln -sf "$SCRIPT_PATH" "$HOME/.local/bin/devc"
+    echo "✓ devc installed to ~/.local/bin/devc"
+    echo "  Make sure ~/.local/bin is on your PATH"
+    ;;
+
+  up)
+    echo "Starting devcontainer..."
+    devcontainer up --workspace-folder "$WORKSPACE_DIR"
+    ;;
+
+  shell)
+    devcontainer exec --workspace-folder "$WORKSPACE_DIR" bash
+    ;;
+
+  build)
+    APP="${2:-}"
+    if [[ -z "$APP" ]]; then
+      echo "Usage: devc build <app>" >&2
+      exit 1
+    fi
+    devcontainer exec --workspace-folder "$WORKSPACE_DIR" just loop "$APP"
+    ;;
+
+  stop)
+    # devcontainer CLI doesn't have stop; find and stop the container
+    CONTAINER=$(docker ps --filter "label=devcontainer.local_folder=$WORKSPACE_DIR" -q | head -1)
+    if [[ -z "$CONTAINER" ]]; then
+      echo "No running devcontainer found for $WORKSPACE_DIR" >&2
+      exit 1
+    fi
+    docker stop "$CONTAINER"
+    echo "✓ devcontainer stopped"
+    ;;
+
+  help|*)
+    echo "Usage: devc <command>"
+    echo ""
+    echo "Commands:"
+    echo "  self-install   Install devc to ~/.local/bin"
+    echo "  up             Start the devcontainer"
+    echo "  shell          Open a shell in the running container"
+    echo "  build <app>    Run \`just loop <app>\` inside the container"
+    echo "  stop           Stop the running container"
+    ;;
+esac

skills/devcontainer.md

@@ -0,0 +1,66 @@
+# Devcontainer
+
+Adapted from [trailofbits/devcontainer-setup](https://skills.sh/trailofbits/skills/devcontainer-setup).
+
+## Overview
+
+The devcontainer uses `ghcr.io/flathub-infra/flatpak-github-actions:gnome-49` — the same
+image CI uses for `compile-oci`. This gives full local/CI parity: same tools, same runtime,
+same `flatpak-builder` version.
+
+**Open in VS Code:** "Reopen in Container"  
+**CLI helper:** `.devcontainer/install.sh self-install` → adds `devc` command to PATH
+
+## Key design decisions
+
+| Decision | Reason |
+|---|---|
+| Same gnome-49 image as CI | Local/CI parity; no drift |
+| `SOURCE_DATE_EPOCH=0` in containerEnv | Deterministic builds match CI |
+| `postCreateCommand` installs just + yq | These are not in base image; versions pinned to match CI |
+| No Dockerfile | Base image is immutable infra-managed; avoid drift by not layering |
+| `.flatpak-builder/` not in a volume | It lives in the workspace (bind mount) so it persists naturally |
+
+## Persistent volumes (from Trail of Bits pattern)
+
+Named volumes survive container rebuilds. Format:
+
+```json
+"mounts": [
+  "source={{PROJECT_SLUG}}-<purpose>-${devcontainerId},target=<path>,type=volume"
+]
+```
+
+Currently no extra volumes are needed — workspace bind mount covers `.flatpak-builder/`
+cache and OSTree repos. Add volumes if any of these move outside the workspace.
+
+## Local build workflow
+
+```bash
+# Build one app locally (same as CI compile-oci, no ghcr.io push)
+just loop <app>
+
+# Build all apps locally
+just loop-all
+
+# Run full build + push to ghcr.io (requires GITHUB_TOKEN with packages:write)
+just build <app>
+```
+
+## Adding new tools to the devcontainer
+
+1. If the tool has a `just install-tools-*` recipe, add it to `postCreateCommand`
+2. If not, add an `apt-get install` or `curl` step — do NOT modify the base image
+3. Pin versions to match CI (check `.github/workflows/build.yml`)
+
+## `devcontainers/ci` in CI (future work)
+
+The goal is to replace the bare `container:` stanza in `compile-oci` with
+`devcontainers/ci@v0.3` so this `devcontainer.json` becomes the single source of truth.
+
+**Blocker:** `flatpak/flatpak-github-actions/flatpak-builder@v6` is a GitHub Action that
+cannot be called from inside `devcontainers/ci`'s `runCmd`. Migration requires replacing
+it with direct `flatpak-builder` commands + manual ccache wiring in a Justfile recipe.
+
+See `skills/pipeline.md` → "devcontainers/ci for compile-oci (future work)" for the
+full migration plan.