feat(labs): one command, one page — scripts/labs, REPO.md and the labs-workflow skill

The labs workflow read as a sequence of scripts to remember; this collapses it:

- `scripts/labs <verb>`: apply, status, export, check, bump <ref> [--commit|--pr],
  upstream <n>.. [--push], port <pr> [--push], run <cmd>, test.
- `apply` marks the labs gitlink skip-worktree, so git status, `git add -u` and
  `git commit -a` leave the permanently-ahead submodule alone and a bare
  `git add labs` is a no-op; the pin moves only with bump. The pre-commit guard
  reads the index with --ignore-submodules=none so a deliberately staged patch
  commit is still refused.
- `apply` installs a post-commit hook in labs/ that re-exports the series, so
  the .patch files cannot lag the checkout (the marker commit and the tooling's
  own commits opt out).
- `--push` on upstream/port runs the printed push and gh pr create; `bump
  --commit` records gitlink, foundry locks and series in one commit, `--pr`
  pushes it as labs-bump/<short> and opens the PR, listing the patches
  upstream absorbed.
- REPO.md: the cross-repository workflow (foundation, private, labs) on one
  page; the `labs-workflow` skill points at it; CLAUDE.md and the README point
  at both. Lifecycle test covers the hidden gitlink, the auto-export hook and
  bump --commit.

Author: Adam Domurad

.claude/skills/labs-workflow/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: labs-workflow
+description: Work across the foundation (aztec-packages), aztec-packages-private and the labs repo (aztec-node) — changing labs from the foundation as patches, upstreaming or porting to aztec-node, bumping the labs pin, private/public prototyping and release testing. Use when a task touches labs/, labs-patches/, the submodule pin, an aztec-node PR, or the private repo.
+---
+
+Read `REPO.md` at the repo root first; it is the whole workflow on one page. Everything goes through `scripts/labs <verb>`:
+
+| Verb | Use |
+|---|---|
+| `apply` / `status` / `export` / `check` | series on the checkout; `status` lists unexported commits |
+| `upstream <n>... [--push]` | one aztec-node PR from the named patches (batch what belongs together) |
+| `port <pr> [--push]` | replay a labs-only aztec-packages PR onto aztec-node main |
+| `bump <ref> [--commit\|--pr]` | move the pin, re-apply, commit gitlink + foundry locks + patches, open the PR |
+| `run <cmd>` | a command inside labs/ with the right environment |
+
+Rules that prevent real mistakes:
+- Never stage the `labs` gitlink by hand; the pin moves only with `bump`. The pre-commit hook refuses a gitlink that points at a patch or marker commit.
+- Commits inside `labs/` re-export the series; commit the regenerated `labs-patches/*.patch` in the foundation PR.
+- A PR that mixes foundation and labs files is not ported; split it.
+- Private prototypes with no private content go into the private repo's `public-next`, never `next`.

CLAUDE.md

@@ -53,11 +53,11 @@ Follow Conventional Commits: `fix:`, `feat:`, `chore:`, `refactor:`, `docs:`, `t
 </commits_and_prs>
 
 <git_staging>
-When staging files, prefer `git add -u` or name specific files rather than `git add -A` or `git add .`. The aggregate flags will pick up unrelated untracked working directories (e.g. personal scratch projects at the repo root) and quietly stage them. `git add -u` and `git commit -a` also stage the `labs` gitlink whenever the patch series is applied (`git status` shows ` M labs`); unstage it with `git restore --staged labs` (see `<labs_submodule_patches>`).
+When staging files, prefer `git add -u` or name specific files rather than `git add -A` or `git add .`. The aggregate flags will pick up unrelated untracked working directories (e.g. personal scratch projects at the repo root) and quietly stage them. The `labs` gitlink is skip-worktree while the patch series is applied, so `git add -u`/`git commit -a` leave it alone (see `<labs_submodule_patches>`).
 </git_staging>
 
 <labs_submodule_patches>
-`labs/` (the aztec-node submodule) carries the foundation's patch series from `labs-patches/*.patch`, applied with `git am` by `labs-patches/bootstrap.sh apply` (run by the root bootstrap, the git hooks and `make labs-patched`), so `labs/` HEAD normally sits ahead of the recorded gitlink. Never `git add labs` by hand — that records a patch commit that does not exist upstream; move the pin with `labs-patches/bootstrap.sh bump <ref>`. To change a patch, commit inside `labs/` on top of the applied series and run `labs-patches/bootstrap.sh export`, then commit the regenerated `.patch` files. To send patches to aztec-node, `labs-patches/bootstrap.sh upstream <n>...` prepares one branch with the named patches and prints the push/PR commands. To port a whole aztec-packages PR to aztec-node (a v5 PR in the in-tree layout, or a `next` PR that only changes `labs-patches/*.patch`), `scripts/labs_port_pr.sh <pr>` checks the PR touches nothing but the labs half, replays it 3-way onto aztec-node `main` in a `port/pr-<n>` branch of `labs/`'s repository, and prints the push/PR commands; mixed PRs are refused, not split. See `labs-patches/README.md`.
+The cross-repository workflow (foundation ↔ labs ↔ private) is on one page in `REPO.md`; `scripts/labs <verb>` drives it. `labs/` (the aztec-node submodule) carries the foundation's patch series from `labs-patches/*.patch`, applied with `git am` by `labs-patches/bootstrap.sh apply` (run by the root bootstrap, the git hooks and `make labs-patched`), so `labs/` HEAD normally sits ahead of the recorded gitlink. The gitlink is marked skip-worktree by `apply`, so `git status`/`git add -u` ignore it and a bare `git add labs` is a no-op; the pin moves only with `scripts/labs bump <ref>`. To change a patch, commit inside `labs/` on top of the applied series — the series re-exports itself on commit — then commit the regenerated `.patch` files. To send patches to aztec-node, `labs-patches/bootstrap.sh upstream <n>...` prepares one branch with the named patches and prints the push/PR commands. To port a whole aztec-packages PR to aztec-node (a v5 PR in the in-tree layout, or a `next` PR that only changes `labs-patches/*.patch`), `scripts/labs_port_pr.sh <pr>` checks the PR touches nothing but the labs half, replays it 3-way onto aztec-node `main` in a `port/pr-<n>` branch of `labs/`'s repository, and prints the push/PR commands; mixed PRs are refused, not split. See `labs-patches/README.md`.
 
 The tooling, all in `labs-patches/bootstrap.sh` (foundation-owned; only the `.patch` contents ever go upstream):
 
@@ -66,8 +66,10 @@ The tooling, all in `labs-patches/bootstrap.sh` (foundation-owned; only the `.pa
 | `apply` | Checks out the gitlink (`update = none` submodule) and `git am`s the series with a fixed committer identity, so the applied SHAs are identical everywhere. Idempotent; refuses to drop `labs/` commits that are not in the series (`LABS_PATCHES_FORCE=1` overrides); stashes uncommitted edits. |
 | `export` | Regenerates `*.patch` from the commits above the gitlink, skipping marker commits. Run it after committing inside `labs/`. |
 | `check` | Applies the committed series to the gitlink in a temporary worktree; CI runs it. |
-| `bump <ref>` | Fetches an aztec-node ref, stages the new gitlink and re-applies; refuses on unexported work. |
-| `upstream <n>... [--branch <name>]` | Creates a branch in `labs/`'s repository with the named patches (in series order) applied under your own identity, and prints the push and `gh pr create` commands. Batch the patches that belong together; one PR per patch is not required. |
+| `bump <ref> [--commit\|--pr]` | Fetches an aztec-node ref, stages the new gitlink, keeps the foundry locks in step and re-applies; refuses on unexported work; `--commit`/`--pr` record and open the bump. |
+| `upstream <n>... [--branch <name>] [--push]` | Creates a branch in `labs/`'s repository with the named patches (in series order) applied under your own identity; prints or (`--push`) runs the push and `gh pr create`. Batch the patches that belong together. |
+| `port <pr> [--push]` | `scripts/labs_port_pr.sh`: replays a labs-only aztec-packages PR onto aztec-node `main`. |
+| `run <cmd>` | `scripts/labs_env.sh`: a command inside `labs/` with the right environment. |
 | `status` | Base, checkout, series, whether it is applied, and unexported commits. |
 | `commit-use-local` | Commits the build's manifest rewrite as the marker commit (`labs-patches: use-local rewrite (never exported)`), staging only `package.json`/`yarn.lock`/`Nargo.toml`/`fnd-hashes`. Called by the build, not by hand. |
 | `check_staged` | The `pre-commit` hook: rejects a staged gitlink that is a series or marker commit. |

REPO.md

@@ -0,0 +1,63 @@
+# Working across aztec-packages, aztec-packages-private and aztec-node
+
+Three repositories: **public** `AztecProtocol/aztec-packages` (the foundation; releases are cut here), **private** `aztec-packages-private` (same tree plus embargoed work; `public-next` mirrors public `next`; releases go only to the internal Artifact Registry), **labs** `aztec-labs-eng/aztec-node` (node, PXE/wallets, aztec-nr, docs, playground, spartan; consumes the foundation through published `@aztec-foundation/*` packages and bb/nargo release binaries).
+
+The foundation builds labs from the `labs/` submodule against its own tree, so a foundation change is tested against labs before it ships. Foundation-side changes to labs are **patches** (`labs-patches/*.patch`) applied on top of the pinned submodule commit. One command drives all of it: `scripts/labs`.
+
+## Build and test
+
+```
+./bootstrap.sh          # applies the labs series; labs/ HEAD sits above the gitlink and git ignores that
+make fast               # foundation + labs against this tree
+make fast-labs          # labs only: yarn-project (+tests, e2e), aztec-nr, noir-contracts, snapshots
+make labs-full          # + docs, spartan, playground, claude tests, benches
+scripts/labs run <cmd>  # any command inside labs/ with the right environment
+```
+
+Labs cache keys follow the foundation tree (`labs/labs-aztec-toolchain/fnd-hashes`, committed by the build as a marker commit); tests that only run from a labs checkout (compose/web3signer/ha e2e, playground browser tests, docs examples) are skipped here and belong to labs CI.
+
+## Change labs from the foundation
+
+```
+scripts/labs apply                 # (already done by bootstrap) patched labs/ checkout
+cd labs && <edit> && git commit    # the series re-exports itself on commit
+git add labs-patches && git commit # the .patch files are what your PR carries
+scripts/labs upstream 4 5 --push   # one aztec-node PR for the patches that belong together
+```
+
+Batch patches that are independent of a foundation version bump; a patch that needs one waits for that release. When the aztec-node PR lands, the next `bump` drops the patch from the series. `scripts/labs status` shows unexported commits; `apply` never discards them (`LABS_PATCHES_FORCE=1` is the last resort).
+
+## Port a whole PR to labs
+
+```
+scripts/labs port 24800 --push     # a v5 PR in the in-tree layout, or a next PR that only changes labs-patches/*.patch
+```
+
+The diff must touch only the labs half (in-tree `yarn-project/`, `noir-projects/labs/`, `docs/`, `playground/`, `spartan/`, `aztec-up/`, `release-image/`, `labs-aztec-toolchain/`, or `labs-patches/*.patch`); anything else is refused with the files listed. It is replayed 3-way onto aztec-node `main` (already-landed hunks become no-ops); remaining conflicts are committed with markers and listed, foundation-path references flagged. v5 PRs get the `port-to-aztec-node` label automatically; a person runs this.
+
+## Take labs changes in
+
+```
+scripts/labs bump main --pr        # move the pin, re-apply the series, commit gitlink + foundry locks + patches, open the PR
+```
+
+`bump` refuses on unexported work and lists the patches upstream absorbed. If a patch no longer applies: fix it in `labs/` (`git am --3way` conflicts), commit, and the series re-exports. Labs takes foundation changes through releases (`labs-aztec-toolchain` pins) and, immediately, through foundation CI building the submodule.
+
+## Public ↔ private
+
+- `public-next` (private repo) is a force-mirror of public `next`; a merge into private `next` follows. When that merge conflicts, AztecBot opens a raw-merge PR plus a resolution PR on top: land resolution into raw, raw into `next`.
+- Prototype a private-only mechanism without private content: branch from `public-next`, cherry-pick the public PRs, open the PR **into `public-next`**, label `ci-release-pr`.
+- Port private work to public by cherry-picking onto a public branch with `--author`; public → private is the mirror.
+- `ci-release-pr` on any PR tags its head and runs the full release flow: public → real npm (trusted publishing, no tokens) / GitHub / crates prereleases at `0.0.1-commit.<sha>`; private → Artifact Registry only (`GCP_PRIVATE_NPM_DEPLOY`). The build log is attached to the run as the `ci-logs` artifact.
+
+## If this happens
+
+| Situation | Do |
+|---|---|
+| a bb/noir/circuit change must reach labs code | build, `make fast-labs` |
+| `apply`: a patch does not apply | fix in `labs/`, commit (auto-export) |
+| `apply`: commits would be lost | `scripts/labs export`, or `git -C labs reset`, or `LABS_PATCHES_FORCE=1` |
+| CI red in a labs test | run the `/tmp/test_cmds` line from the root, or `scripts/labs run <cmd>` |
+| labs tests say `disabled-cache` locally | by design; per-package hashes resolve in CI only |
+| labs-only PR on a v5 line | `scripts/labs port <pr> --push` |
+| the private `public-next → next` merge is stuck | land the AztecBot pair |

labs-patches/README.md

@@ -1,5 +1,7 @@
 # labs-patches
 
+The one-page workflow is `REPO.md` at the repo root; `scripts/labs <verb>` is the entry point for everything below.
+
 The foundation's changes to the labs repo, kept as a `git format-patch` series that is applied on top of the `labs/` submodule (aztec-node) every time it is checked out.
 
 `labs/` is pinned to an upstream commit (the gitlink). `bootstrap.sh apply` checks that commit out and runs `git am` over `*.patch` in name order, so the patches become real commits in the submodule and `labs/` HEAD sits ahead of the gitlink. It is idempotent and runs from the root `bootstrap.sh`, the `post-merge`/`post-checkout` hooks and `make labs-patched`, so a fresh clone, a pull and a build all land on the same patched tree. It never discards commits that are not in the series: if the base or the series changed under work in progress, it stops and asks you to `export` or drop it (`LABS_PATCHES_FORCE=1` discards them — a last resort, not a workflow). Uncommitted tracked edits in `labs/` are stashed (`git -C labs stash list`) rather than reset when a re-apply is needed.