From 17b6e5bb91a386d41c189e963b8daaac49c0686c Mon Sep 17 00:00:00 2001
From: Evgeny Boger <boger@wirenboard.com>
Date: Sat, 30 May 2026 11:37:12 +0000
Subject: [PATCH] v0.1.16: bump for --publish / --auto-publish / --allow-egress
 + AGENTS.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Workspace version bump for the merged
`worktree-vm-network-investigation` branch (Lima-style host ← guest
port mirroring + per-launch egress policy hole-punching).

New AGENTS.md captures the conventions I keep forgetting:
- bump workspace version after every feature merge
- merge submodule before superproject when both move
- don't relocate build output to tmpfs
- don't `rm -rf` inline from tool calls (use scripts)
- commit-message style on this branch is multi-paragraph Why/How

README now points at AGENTS.md alongside PLAN.md / ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 AGENTS.md  | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 Cargo.lock |  2 +-
 Cargo.toml |  2 +-
 README.md  |  3 +++
 4 files changed, 69 insertions(+), 2 deletions(-)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..fe955d9
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,64 @@
+# AGENTS.md — conventions for coding agents working on this repo
+
+Things that aren't obvious from the code and that I keep forgetting to
+tell you. Read once, then act on them silently.
+
+## After merging a feature branch, bump the workspace version
+
+Every merge into `rewrite-microsandbox` ships with a
+`workspace.package.version` bump in the root `Cargo.toml` and a
+follow-up `vX.Y.Z: bump for <feature>` commit. Skipping this leaves
+the next release boundary ambiguous and means downstream
+`agent-vm --version` lies about what's in the binary.
+
+Convention (look at `git log --oneline | grep "^[a-f0-9]* v"`):
+
+```
+git merge --no-ff <feature-branch>     # produces "Merge ...: ..."
+$EDITOR Cargo.toml                     # version = "0.1.N+1"
+git commit -am "v0.1.N+1: bump for <one-line feature>"
+```
+
+`Cargo.lock` will need refreshing — run a build after the bump to
+update it, then commit the lock alongside the version bump if it
+moved (it always does).
+
+## Submodule merges go first
+
+`vendor/microsandbox` is a submodule with its own branches. When a
+worktree changes both the agent-vm code and the vendored microsandbox
+code, merge inside the submodule **before** merging the superproject —
+otherwise the superproject merge will conflict on the gitlink and
+you'll have to redo the submodule merge anyway. Pattern:
+
+1. `cd vendor/microsandbox && git merge --no-ff <subm-feature-branch>`
+2. `cd ../.. && git add vendor/microsandbox` (bumps the gitlink)
+3. `git merge --no-ff <agent-vm-feature-branch>`
+   (resolves the gitlink conflict to the merge SHA from step 1)
+
+If the feature branch lives in a separate git worktree, the
+submodule branches in that worktree's `.git/modules/...` are not
+visible from the main worktree. Push them across with
+`git -C <worktree>/vendor/microsandbox push <main-worktree>/.git/modules/vendor/microsandbox <branch>:<branch>`
+before attempting the submodule merge.
+
+## Don't relocate build output to `/tmp` or `/dev/shm`
+
+If a build is too big, slow, or runs out of inodes, fix the root
+cause. Don't sidestep by pointing `CARGO_TARGET_DIR` at tmpfs — that
+loses everything on reboot, masks real disk pressure, and the next
+agent will spend an hour relinking from cold.
+
+## Don't `rm -rf` state directories from the assistant turn
+
+Claude Code prompts on every `rm -rf` and it's painful. The repo
+ships `/tmp/clean-state.sh` for state cleanup — use it, or write a
+new short script if it doesn't cover your case. Inline `rm -rf` in
+tool calls is a UX papercut for the human, not a safety win.
+
+## When in doubt about scope, read the prior commit messages
+
+Commits on this branch use a multi-paragraph "Why / How" style with
+real examples (often live e2e output). Match the style; don't write
+single-line commits for non-trivial changes. The commit body is
+where future-you (or future-me) recovers the reasoning.
diff --git a/Cargo.lock b/Cargo.lock
index 359f79d..d251ad2 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -21,7 +21,7 @@ dependencies = [
 
 [[package]]
 name = "agent-vm"
-version = "0.1.15"
+version = "0.1.16"
 dependencies = [
  "anyhow",
  "base64",
diff --git a/Cargo.toml b/Cargo.toml
index c768ef1..4d5d290 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -6,7 +6,7 @@ members = ["crates/agent-vm"]
 exclude = ["vendor/microsandbox"]
 
 [workspace.package]
-version = "0.1.15"
+version = "0.1.16"
 edition = "2024"
 license = "MIT"
 repository = "https://github.com/wirenboard/agent-vm"
diff --git a/README.md b/README.md
index 264437a..58dc2c9 100644
--- a/README.md
+++ b/README.md
@@ -171,3 +171,6 @@ exit aborts the launch.
 - [PLAN.md](PLAN.md) — phased roadmap, what's done, what's deferred.
 - [ARCHITECTURE.md](ARCHITECTURE.md) — design notes; why things look
   the way they do.
+- [AGENTS.md](AGENTS.md) — conventions for coding agents (Claude
+  Code, Codex, etc.) working on this repo: post-merge version bump,
+  submodule-merge ordering, what not to do.