diff --git a/README.md b/README.md
index e18e51a..200bcd0 100644
--- a/README.md
+++ b/README.md
@@ -123,6 +123,20 @@ catalog/
 `.lock.yml` files are marked `linguist-generated` and `merge=ours` in `.gitattributes` to prevent spurious merge conflicts.
 </details>
 
+## Publishing
+
+_Maintainers only._ Steps to ship a new plugin version:
+
+1. **Bump the version** in `.claude-plugin/plugin.json`. Follow semver: patch for bug fixes, minor for new skills or catalog entries, major for breaking changes to skill names or the marketplace URL. Update the status line at the top of this README (`> **Status**: vX.Y.Z`).
+
+2. **Create a GitHub release** tagged `vX.Y.Z`. The release description is the changelog — include what changed, any upgrade notes, and credit contributors.
+
+The marketplace URL is stable and points to `main`, so users who have already added the marketplace pick up the new version automatically on their next `claude` session (no re-install needed).
+
+To update the external directory listings this plugin appears in, follow each directory's own submission process:
+- [claude-plugins.dev](https://claude-plugins.dev)
+- [ClaudePluginHub](https://claudepluginhub.com)
+
 ## Credits
 
 Built on two open-source projects from the [GitHub Next](https://githubnext.com) team:
diff --git a/catalog/agent-team/README.md b/catalog/agent-team/README.md
index 5490837..bf051f1 100644
--- a/catalog/agent-team/README.md
+++ b/catalog/agent-team/README.md
@@ -111,7 +111,20 @@ Then apply the OAuth token tweak to each `.lock.yml` per [`skills/install-workfl
 
 - **Concurrency**: each workflow uses `concurrency: group: agent-team-issue-${issue_number}` so only one role runs at a time per issue.
 - **Max iterations**: default 3 (reviewer kickback → implementer). The counter lives on the `iteration` input passed through the dispatch chain, bumped exclusively by the reviewer on kickback.
-- **Input propagation**: planner / implementer / reviewer must fail loudly if required `workflow_dispatch` inputs are missing. Do not rely on label search or recent-activity inference as a fallback.
+- **Input propagation**: planner / implementer / reviewer fail loudly if required `workflow_dispatch` inputs are missing or arrive as unresolved template literals — they never infer a missing value from labels, recent activity, or search results. When triggered, the agent adds `state:blocked` to the issue and posts: `🛑 agent-team: workflow_dispatch inputs were not propagated. Re-dispatch with valid inputs.`
+
+  To recover: clear `state:blocked`, then manually dispatch the blocked stage with explicit inputs:
+
+  ```bash
+  # Unblock the planner (re-run from planning stage)
+  gh workflow run planner-agent.lock.yml --field issue_number=<N> --field iteration=<N>
+
+  # Unblock the implementer
+  gh workflow run implementer-agent.lock.yml --field issue_number=<N> --field iteration=<N> [--field pr_number=<N>]
+
+  # Unblock the reviewer
+  gh workflow run reviewer-agent.lock.yml --field pr_number=<N> --field issue_number=<N> --field iteration=<N>
+  ```
 - **Non-UI only**: no screenshot capture. Reviewer validates via tests/CI status + reading the diff.
 - **Cost**: a single task can easily spend 4× the tokens of a monolithic workflow. Set `timeout-minutes` conservatively and monitor the first few runs.
 - **No auto-merge**: the reviewer approves but never merges. Humans merge.