Semantics dev tooling

.devcontainer/Dockerfile

@@ -36,6 +36,15 @@ RUN curl -sSL \
     | tar xz -C /usr/local/bin stellar \
   && stellar --version
 
+# --- GitHub CLI (prebuilt) -------------------------------------------------
+# Used by `scripts/dev.sh pr` to open coordinated PRs across the semantics chain.
+ARG GH_CLI_VERSION=2.63.2
+RUN curl -sSL \
+      "https://github.com/cli/cli/releases/download/v${GH_CLI_VERSION}/gh_${GH_CLI_VERSION}_linux_amd64.tar.gz" \
+    | tar xz -C /usr/local --strip-components=1 \
+        "gh_${GH_CLI_VERSION}_linux_amd64/bin/gh" \
+  && gh --version
+
 # --- Nix prep --------------------------------------------------------------
 # Single-user Nix is installed under /nix as the `node` user (no systemd in the
 # container). Pre-create /nix with node ownership so the installer can write it.

.devcontainer/devcontainer.json

@@ -7,12 +7,13 @@
   "workspaceFolder": "/workspace",
   "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind",
   "mounts": [
-    "source=claude-code-config-${devcontainerId},target=/home/node/.claude,type=volume"
+    "source=claude-code-config-${devcontainerId},target=/home/node/.claude,type=volume",
+    "source=komet-ssh-${devcontainerId},target=/home/node/.ssh,type=volume"
   ],
   "containerEnv": {
     "CLAUDE_CONFIG_DIR": "/home/node/.claude"
   },
-  "postCreateCommand": "sudo chown -R node:node /home/node/.claude",
+  "postCreateCommand": "sudo chown -R node:node /home/node/.claude /home/node/.ssh && chmod 700 /home/node/.ssh",
   "customizations": {
     "vscode": {
       "extensions": [

.gitignore

@@ -1,4 +1,5 @@
 node_modules/
+.deps/
 dist/
 out/
 coverage/

CONTRIBUTING.md

@@ -31,6 +31,28 @@ Then:
 npm install
 ```
 
+### SSH keys in the devcontainer
+
+`~/.ssh` is a named Docker volume, so keys **persist across container rebuilds**
+— but the volume starts **empty** on first build, so add a key once. The volume
+lives outside `/workspace`, so keys can't be committed to the repo, and Docker
+excludes volumes from `docker commit` / image builds. (Anyone with root or
+`docker`-group access on the host can still read the volume, so prefer a
+passphrase or a dedicated, revocable key.)
+
+Inside the container, generate a key:
+
+```bash
+ssh-keygen -t ed25519 -C "you@example.com"   # writes ~/.ssh/id_ed25519[.pub]
+chmod 700 ~/.ssh
+chmod 600 ~/.ssh/id_ed25519
+chmod 644 ~/.ssh/id_ed25519.pub
+```
+
+Then add the **public** key (`~/.ssh/id_ed25519.pub`) to your GitHub account at
+<https://github.com/settings/ssh/new>. To reuse an existing host key instead,
+`docker cp` it into the container's `~/.ssh` and apply the same `chmod`.
+
 ## Everyday commands
 
 ```bash
@@ -46,6 +68,52 @@ extension loaded and the [`examples/`](examples/) workspace open. Pick a
 configuration from the Run and Debug view — the **Replay … with symbols**
 configs need no toolchain at all.
 
+## Changing the semantics (komet / wasm-semantics)
+
+The debugger consumes an upstream chain,
+`komet-node → komet → wasm-semantics`, but you rarely touch it. Pick your mode:
+
+**1. Just debugging (almost always).** Do nothing special — the devcontainer
+already has the `komet-node` binary (from `kup`). Press **F5**. You never need
+nix, uv, or any of the tooling below.
+
+**2. Changing the semantics and seeing it in the debugger.** Use the single
+front-end [`scripts/dev.sh`](scripts/dev.sh):
+
+```bash
+./scripts/dev.sh setup   # check out the chain into .deps/ and wire it up
+# …edit .deps/wasm-semantics or .deps/komet…
+./scripts/dev.sh build   # fast incremental rebuild
+./scripts/dev.sh use     # make it the debugger's komet-node, then press F5
+```
+
+**3. Upstreaming the change as PRs.** Once you have commits on a shared branch in
+the checkouts, `dev.sh pr open <branch>` opens a cross-linked PR in each
+repo (`pr status <branch>` / `--dry-run` to preview first).
+
+That's the whole developer surface. Everything else is plumbing the script drives
+for you:
+
+- You never run `nix`, `uv`, or `kdist` by hand — `setup`/`build` do.
+- **`.deps/`** (leading dot) is generated and gitignored — throwaway local
+  checkouts; delete it any time to reset. Not to be confused with the committed
+  `deps/` folders in komet/komet-node, which hold version pins (below).
+- This repo carries **no version-pin files**. The pins that connect the chain
+  (`deps/*_release`, `uv.lock`, flake inputs) live upstream in komet/komet-node
+  and are bumped by CI, not by you.
+
+<details><summary>Why it needs checkouts (background)</summary>
+
+The chain is pinned by **uv git dependencies**, not Nix flake inputs, so
+`kup --override` can't reach `komet`/`wasm-semantics`. `setup` therefore checks
+the repos out side-by-side (at the versions currently pinned, or `--tip` for
+latest) and wires them with uv **path sources** so an edit flows up the chain
+with no version bumps. `build`/`shell` are the fast inner loop (`kdist` caches
+per target, toolchain from komet-node's Nix dev shell); `use` does one Nix
+realize so the debugger gets the exact release build — doubling as a parity
+check. Revert with `kup install komet-node`.
+</details>
+
 ## Testing conventions
 
 - **Write tests first.** New behavior should arrive with a failing test that

examples/.vscode/settings.json

@@ -1,8 +1,3 @@
 {
-  // The nix-cached `komet-node` on $PATH in this devcontainer predates the fix
-  // for value-returning contract calls (it hardcoded a Void result and got stuck
-  // on any function returning a value). The fixed build lives in the uv venv, so
-  // point the extension at it here. Remove this once the nix cache ships the fix
-  // and plain `komet-node` on $PATH is current.
-  "soroban.kometNode.path": "/home/node/.komet-node/bin/komet-node"
+
 }