From 0a25abe95ee6f5412ebea2645d7ab0d0e6d6d39c Mon Sep 17 00:00:00 2001
From: fullsend-code
 <278716306+fullsend-ai-coder[bot]@users.noreply.github.com>
Date: Tue, 15 Sep 2026 16:13:17 +0000
Subject: [PATCH 1/2] docs: add CI & Packaging section to AGENTS.md

Add a new CI & Packaging section to AGENTS.md documenting that
the verify-plugin-export.yaml workflow installs the packed
tarball via npm install -g, so package.json dependencies must
use npm-compatible version specifiers. This gives the review
agent context to flag Yarn-specific protocols (patch:, portal:,
workspace:) that would break npm installation.

Closes #209

Assisted-by: claude-opus-4-6
---
 AGENTS.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 670e90f..4a77ab6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -39,6 +39,17 @@
 - Structured CLI errors: `src/commands/intent-based-actions/intent-errors.ts`
 - Repeatable `key=value` and JSON input parsing: `src/commands/intent-based-actions/kv.ts`
 
+## CI & Packaging
+
+- The `verify-plugin-export.yaml` workflow builds the CLI with `yarn pack`,
+  then installs the resulting tarball via `npm install -g`. Dependencies in
+  `package.json` must therefore use npm-compatible version specifiers — do not
+  use Yarn-specific protocols (`patch:`, `portal:`, `workspace:`) in the
+  `dependencies` or `devDependencies` fields.
+- The Verify workflow runs against 9 plugin workspaces (adoption-insights,
+  bulk-import, extensions, global-header, homepage, orchestrator, quickstart,
+  scorecard, theme) from the `rhdh-plugin-export-overlays` repo.
+
 ## PR Conventions
 
 - PR titles must follow [Conventional Commits](https://www.conventionalcommits.org/) — enforced by CI (`pr-semantic.yaml`)

From 99f9c7ee16d2e64036e7f9f60314afba9c93d895 Mon Sep 17 00:00:00 2001
From: fullsend-fix <278716306+fullsend-ai-coder[bot]@users.noreply.github.com>
Date: Tue, 15 Sep 2026 16:34:33 +0000
Subject: [PATCH 2/2] fix: tighten devDependencies constraint in CI & Packaging
 docs

Clarify that the npm-compatible version specifier requirement applies to
the `dependencies` field (which `npm install -g` resolves). Note
`devDependencies` as a best-practice recommendation rather than a
CI-breaking hard constraint, since global tarball installs do not
resolve devDependencies.

Addresses #210

Assisted-by: claude-sonnet-4-6
---
 AGENTS.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index 4a77ab6..d906875 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -45,7 +45,9 @@
   then installs the resulting tarball via `npm install -g`. Dependencies in
   `package.json` must therefore use npm-compatible version specifiers — do not
   use Yarn-specific protocols (`patch:`, `portal:`, `workspace:`) in the
-  `dependencies` or `devDependencies` fields.
+  `dependencies` field. Avoiding them in `devDependencies` is also recommended
+  for consistency, though only `dependencies` are resolved during the CI
+  install step.
 - The Verify workflow runs against 9 plugin workspaces (adoption-insights,
   bulk-import, extensions, global-header, homepage, orchestrator, quickstart,
   scorecard, theme) from the `rhdh-plugin-export-overlays` repo.