From 96dace38cfd4efb3d0ec31ea50e5c55db7015254 Mon Sep 17 00:00:00 2001
From: Cristian Greco <cristianrgreco@gmail.com>
Date: Tue, 10 Mar 2026 09:43:29 +0000
Subject: [PATCH 1/2] Document monorepo workflow and safe gh PR body handling

---
 AGENTS.md | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index b54e42f0b..5ea8b6b68 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,7 +21,7 @@ It captures practical rules that prevent avoidable CI and PR churn.
 ## Permission and Escalation
 
 - `npm install` requires escalated permissions for outbound network access to npm registries.
-- `npm test` commands should b`e run with escalation so tests can access the Docker socket.
+- `npm test` commands should be run with escalation so tests can access the Docker socket.
 
 ### Escalation hygiene
 
@@ -75,4 +75,14 @@ It captures practical rules that prevent avoidable CI and PR churn.
 
 ## Practical Note
 
+- This repository is an npm workspaces monorepo:
+  - root package: `testcontainers-monorepo`
+  - workspaces: `packages/testcontainers` and `packages/modules/*`
+  - shared lockfile: root `package-lock.json` (workspace installs update this single file)
+- When changing one workspace dependency, prefer targeted commands to reduce lockfile churn:
+  - `npm install -w @testcontainers/<module>`
+  - `npm uninstall -w @testcontainers/<module> <package>`
+  - targeted tests via `npm run test -- <path-to-spec>`
 - Recheck `package-lock.json` after `npm install` for unrelated drift and revert unrelated changes.
+- When creating/editing PR descriptions with `gh`, do not inline backticks in shell command arguments.
+  - Prefer `--body-file <path>` with a heredoc-written file to avoid shell command substitution.

From 98c21cd48daf323b1c16f6fbbd593a733805c44b Mon Sep 17 00:00:00 2001
From: Cristian Greco <cristianrgreco@gmail.com>
Date: Tue, 10 Mar 2026 09:44:56 +0000
Subject: [PATCH 2/2] Reorganize AGENTS guidance for monorepo and PR body
 safety

---
 AGENTS.md | 24 +++++++++++++-----------
 1 file changed, 13 insertions(+), 11 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 5ea8b6b68..edcf633d9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -5,6 +5,16 @@
 This is a working guide for contributors and coding agents in this repository.
 It captures practical rules that prevent avoidable CI and PR churn.
 
+## Repository Layout
+
+- This repository is an npm workspaces monorepo.
+  - root package: `testcontainers-monorepo`
+  - workspaces: `packages/testcontainers` and `packages/modules/*`
+  - shared lockfile: root `package-lock.json` (workspace installs update this single file)
+- For workspace-scoped dependency changes, prefer targeted commands to reduce lockfile churn:
+  - `npm install -w @testcontainers/<module>`
+  - `npm uninstall -w @testcontainers/<module> <package>`
+
 ## Development Expectations
 
 - If a public API changes, update the relevant docs in the same PR.
@@ -41,6 +51,8 @@ It captures practical rules that prevent avoidable CI and PR churn.
    - If signing fails (for example, passphrase/key issues), stop and ask the user to resolve signing, then retry.
 8. Push branch. Ask for explicit user permission before any force push.
 9. Open PR against `main` using a human-readable title (no `feat(...)` / `fix(...)` prefixes).
+   - When using `gh` to create/edit PR descriptions, prefer `--body-file <path>` over inline `--body`.
+   - This avoids shell command substitution issues when the body contains backticks.
 10. Add labels for both change type and semantic version impact.
 11. Ensure PR body includes:
     - summary of changes
@@ -73,16 +85,6 @@ It captures practical rules that prevent avoidable CI and PR churn.
 - docs-only change: `documentation` + usually `patch`
 - dependency update: `dependencies` + impact label based on user-facing effect
 
-## Practical Note
+## Lockfile Hygiene
 
-- This repository is an npm workspaces monorepo:
-  - root package: `testcontainers-monorepo`
-  - workspaces: `packages/testcontainers` and `packages/modules/*`
-  - shared lockfile: root `package-lock.json` (workspace installs update this single file)
-- When changing one workspace dependency, prefer targeted commands to reduce lockfile churn:
-  - `npm install -w @testcontainers/<module>`
-  - `npm uninstall -w @testcontainers/<module> <package>`
-  - targeted tests via `npm run test -- <path-to-spec>`
 - Recheck `package-lock.json` after `npm install` for unrelated drift and revert unrelated changes.
-- When creating/editing PR descriptions with `gh`, do not inline backticks in shell command arguments.
-  - Prefer `--body-file <path>` with a heredoc-written file to avoid shell command substitution.