From 846958d79e1615c5f41e637cc46661334c44304f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?andr=C3=A9s=20gonz=C3=A1lez?= <andres.gonzalez79@gmail.com>
Date: Thu, 14 May 2026 16:22:19 +0200
Subject: [PATCH 1/6] :books: Change slogan at Help Center footer (#9554)

---
 docs/_includes/layouts/base.njk | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/_includes/layouts/base.njk b/docs/_includes/layouts/base.njk
index 076acbffec..97fc32e20b 100644
--- a/docs/_includes/layouts/base.njk
+++ b/docs/_includes/layouts/base.njk
@@ -84,7 +84,7 @@
               <path d="M68.318 0L31.941 51.237v28.961L.286 95.255 0 95.121v188.952l123.419 58.309 7.542 3.56 7.542-3.56 123.418-58.309V95.121l-.232.11-31.665-15.062V51.237l-1.107-1.559L193.645 0l-36.38 51.237v.05l-26.47-37.281L104.528 51l-.939-1.322L68.318 0zm6.437 29.762l14.07 19.816H47.811L61.72 29.995l13.036-.233zm125.324 0l14.072 19.816h-41.012l13.903-19.583 13.037-.233zM137.23 43.77l14.07 19.813h-41.008L124.195 44l13.035-.23zM43.923 59.564h19.452v65.497l-19.452-9.19V59.564zm29.438 0h19.354v79.356l-19.354-9.142V59.564zm95.89 0h19.45v70.146l-19.45 9.188V59.564zm29.435 0h19.352v56.285l-19.352 9.142V59.564zM106.4 73.57h19.451v81.004l-19.451-9.19V73.57zm29.438 0h19.352v71.971l-19.352 9.145V73.57zm924.624 7.15l-.096 36.464-19.553-.134v14.857h19.61v78.333c0 5.705.445 10.996 1.348 15.873l.009.042.007.044c1.107 4.982 2.979 9.326 5.65 12.95 2.692 3.654 6.295 6.463 10.645 8.36 4.437 2.11 9.836 3.096 16.17 3.096 2.887 0 6.193-.47 9.981-1.373a90.691 90.691 0 0011.285-3.492l2.202-.84-4.751-14.248-2.492 1.15c-4.84 2.098-9.583 3.667-14.656 3.695-4.087 0-7.299-.587-9.651-1.6-2.245-1.215-3.98-2.738-5.298-4.629-1.375-2.15-2.385-4.622-3.025-7.463-.491-3.143-.748-6.645-.748-10.518v-79.38h36.342v-14.844H1077.1V80.72h-16.637zM230.02 95.096l17.126 7.002-17.126 8.09V95.095zm-198.08.025v15.09l-17.122-8.09 17.122-7zm802.504 18.8l.001.002v.002c-8.243 0-16.244 2.03-23.884 6.031l-.01.007-.012.006c-6.172 3.312-11.324 6.77-16.74 10.856l-.096-13.762H777.61v187.141h16.414V237.31c5.379 3.67 10.692 6.85 15.895 9.163l.026.01.027.014c6.529 2.72 12.96 4.108 19.247 4.108 7.652 0 14.986-1.557 21.917-4.658l.013-.005.015-.008c7.106-3.28 13.324-7.946 18.592-13.941l-.005.002c5.456-6.184 9.708-13.62 12.762-22.242 3.073-8.675 4.585-18.459 4.585-29.319 0-19.865-4.26-35.933-13.01-47.97l-.003-.006c-8.818-12.304-22.34-18.537-39.64-18.537zm-397.499.002v.002c-8.243 0-16.244 2.03-23.884 6.031l-.01.007-.012.006c-6.172 3.312-11.324 6.772-16.74 10.858l-.096-13.764H380.11v187.143h16.414v-66.894c5.379 3.67 10.692 6.848 15.895 9.16l.026.014.028.012c6.528 2.72 12.958 4.11 19.246 4.11 7.652 0 14.986-1.558 21.917-4.659l.013-.007.015-.006c7.106-3.28 13.324-7.946 18.592-13.941l-.005.001c5.456-6.183 9.708-13.618 12.762-22.241 3.073-8.675 4.585-18.459 4.585-29.32 0-19.864-4.26-35.933-13.01-47.97l-.003-.005c-8.817-12.304-22.338-18.537-39.639-18.537zm267.246 0v.002c-9.113 0-17.375 2.306-24.569 6.91-5.873 3.616-11.564 8.222-17.142 13.445l.115-17.217h-15.765v130.406h16.417v-94.62c7.284-7.373 13.843-14.357 19.506-17.917l.02-.014.02-.013c5.715-3.756 11.989-5.61 19.046-5.61 9.77 0 16.07 2.884 19.925 8.59l.022.032.024.033c4.045 5.6 6.332 14.962 6.332 28.107v81.412h16.415v-82.984c0-16.688-3.059-29.35-9.668-37.847-6.622-8.515-17.134-12.715-30.698-12.715zm-134.972.002c-7.331 0-14.503 1.659-21.42 4.93l-.01.006c-6.764 3.11-12.876 7.682-18.298 13.647l-.002.002c-5.287 5.833-9.533 12.995-12.76 21.425l-.01.022-.007.022c-3.075 8.501-4.593 18.028-4.593 28.548s1.518 20.049 4.593 28.55l.009.029.013.03c3.233 8.263 7.572 15.42 13.018 21.412l.015.012.011.015c5.453 5.817 11.854 10.299 19.133 13.392l.009.004.01.004c7.447 3.087 15.367 4.63 23.687 4.63 9.459 0 17.36-1.32 23.714-4.118l.013-.007c6.178-2.648 11.843-5.48 16.994-8.5l2.03-1.188-7.144-13.493L605.93 225c-4.517 3.346-8.972 5.427-14.335 7.44-5.093 1.803-11.373 2.728-17.93 2.728-6.832 0-12.9-.649-18.294-3.095-5.45-2.645-10.123-6.175-14.083-10.62-3.792-4.625-6.783-10.087-8.96-16.446l-.001-.006c-1.93-5.795-2.945-12.072-3.3-18.708h90.5c0-2.558.246-5.015.255-7.163v-4.706c0-18.854-4.374-33.79-13.39-44.463-8.998-10.65-21.63-16.035-37.171-16.035v-.001zm397.808 0c-7.818 0-15.318 1.554-22.418 4.649-7.104 3.096-13.407 7.576-18.85 13.383l-.014.014-.016.015c-5.295 5.843-9.541 13.1-12.768 21.704l-.005.012-.006.015c-3.077 8.506-4.59 18.12-4.59 28.81 0 10.69 1.513 20.305 4.59 28.811l.011.03.013.03c3.23 8.254 7.475 15.324 12.753 21.148l.015.013.014.016c5.444 5.807 11.746 10.285 18.85 13.381 7.1 3.096 14.602 4.65 22.42 4.65 7.819 0 15.32-1.554 22.42-4.65 7.27-3.093 13.585-7.575 18.863-13.396 5.465-5.832 9.724-12.922 12.783-21.196 3.258-8.514 4.863-18.14 4.863-28.837 0-10.692-1.604-20.315-4.86-28.826-3.054-8.614-7.31-15.885-12.787-21.731-5.279-5.82-11.592-10.303-18.862-13.396-7.1-3.095-14.6-4.65-22.418-4.65h-.001zm-951.946 5.004l108.337 51.178v155.59L15.082 274.519v-155.59zm231.755 0v155.59l-108.334 51.178v-155.59l108.334-51.178zm322.641 9.842h.002c10.75 0 18.852 3.647 25.038 11.134l.005.011.008.011c5.748 6.807 8.88 17.511 9.22 32.04h-74.538c.78-6.15 2.074-11.798 4.1-16.723 2.515-5.69 5.586-10.488 9.203-14.438 3.8-3.96 7.955-6.882 12.506-8.833l.033-.016.033-.015c4.566-2.12 9.33-3.171 14.39-3.171zm-134.36.26v.002c6.826 0 12.488 1.325 17.114 3.878l.03.014.029.017c4.685 2.423 8.428 5.844 11.349 10.387l.012.019.011.016c2.936 4.404 5.096 9.763 6.438 16.137l.006.031.009.03c1.52 6.416 2.287 13.372 2.287 20.874 0 8.323-1.104 15.91-3.285 22.787l-.007.019-.006.018c-2.02 6.733-4.856 12.468-8.492 17.261-3.63 4.786-7.952 8.447-13.028 11.067-5.06 2.611-10.479 3.91-16.39 3.91-4.471 0-9.768-1.132-15.842-3.494-5.688-2.212-12.01-7.647-18.827-13.056v-69.463c7.23-6.16 13.974-12.007 20.127-15.245l.009-.004.011-.007c6.52-3.51 12.647-5.198 18.444-5.198zm397.497 0l.002.002c6.827 0 12.489 1.325 17.115 3.878l.03.014.029.017c4.685 2.423 8.428 5.844 11.348 10.387l.013.019.011.016c2.936 4.404 5.096 9.763 6.438 16.137l.006.031.009.03c1.52 6.416 2.287 13.372 2.287 20.874 0 8.323-1.104 15.91-3.285 22.787l-.01.019-.005.018c-2.02 6.733-4.856 12.468-8.492 17.261-3.63 4.786-7.952 8.447-13.028 11.067-5.059 2.611-10.479 3.91-16.39 3.91-4.47 0-9.768-1.132-15.842-3.494-5.687-2.212-12.01-7.647-18.827-13.056v-69.463c7.23-6.16 13.974-12.007 20.127-15.245l.01-.005.01-.006c6.52-3.51 12.647-5.198 18.444-5.198zm134.414 0v.002c5.911 0 11.331 1.3 16.39 3.91l.044.02.04.021c5.223 2.448 9.595 6.004 13.206 10.765l.027.038.03.035c3.798 4.624 6.797 10.183 8.981 16.736 2.17 6.51 3.272 13.824 3.272 21.969 0 7.965-1.1 15.19-3.272 21.707-2.184 6.553-5.183 12.11-8.981 16.734l-.017.022-.014.022c-3.614 4.6-8.012 8.182-13.272 10.814-5.064 2.448-10.505 3.671-16.434 3.671-5.921 0-11.358-1.221-16.417-3.664-5.087-2.63-9.503-6.226-13.304-10.849-3.629-4.624-6.548-10.191-8.734-16.75-2.173-6.517-3.274-13.742-3.274-21.707 0-8.145 1.103-15.458 3.274-21.97 2.188-6.565 5.11-12.138 8.745-16.766l.003-.004.004-.007c3.801-4.79 8.2-8.364 13.255-10.81l.03-.015.027-.013c5.059-2.611 10.48-3.911 16.391-3.911z"></path>
             </svg>
           </a>
-          <span>Design as code</span>
+          <span>Full-Stack Design</span>
         </div>
         <ul class="footer-block">
           <li class="footer-block--title">Product</li>

From c62ce866a8cbf676c66957dfcf98e9120921b958 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?andr=C3=A9s=20gonz=C3=A1lez?= <andres.gonzalez79@gmail.com>
Date: Thu, 14 May 2026 16:23:13 +0200
Subject: [PATCH 2/6] :books: Change sentence at MCP docs (#9568)

---
 docs/mcp/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/mcp/index.md b/docs/mcp/index.md
index d473eff10c..e0d31fe6ce 100644
--- a/docs/mcp/index.md
+++ b/docs/mcp/index.md
@@ -109,7 +109,7 @@ Because **remote MCP** does not expose local file-system access:
 
 ## Quick start
 
-If you just want to try Penpot MCP quickly, follow this path for the **hosted (remote) MCP server**.
+If you just want to try Penpot AI workflows quickly through the MCP, follow this path for the **hosted (remote) MCP server**.
 
 ### Remote MCP in 5 steps
 

From 1dea84b7b1e3500461c12b92a67508836e555d0a Mon Sep 17 00:00:00 2001
From: Andrey Antukh <niwi@niwi.nz>
Date: Fri, 15 May 2026 10:19:29 +0200
Subject: [PATCH 3/6] :books: Update mcp readme

---
 mcp/README.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/mcp/README.md b/mcp/README.md
index 07fa01ac26..97d97c97e1 100644
--- a/mcp/README.md
+++ b/mcp/README.md
@@ -4,7 +4,7 @@
 
 Penpot integrates a LLM layer built on the Model Context Protocol
 (MCP) via Penpot's Plugin API to interact with a Penpot design
-file. Penpot's MCP server enables LLMs to perfom data queries,
+file. Penpot's MCP server enables LLMs to perform data queries,
 transformation and creation operations.
 
 Penpot's MCP Server is unlike any other you've seen. You get
@@ -270,7 +270,6 @@ The Penpot MCP server can be configured using environment variables.
 | `PENPOT_MCP_SERVER_PORT`           | Port for the HTTP/SSE server                                               | `4401`       |
 | `PENPOT_MCP_WEBSOCKET_PORT`        | Port for the WebSocket server (plugin connection)                          | `4402`       |
 | `PENPOT_MCP_REPL_PORT`             | Port for the REPL server (development/debugging)                           | `4403`       |
-| `PENPOT_MCP_SERVER_ADDRESS`        | Hostname or IP address via which clients can reach the MCP server          | `localhost`  |
 | `PENPOT_MCP_REMOTE_MODE`           | Enable remote mode (disables file system access). Set to `true` to enable. | `false`      |
 
 ### Logging Configuration

From 27ac0b74697b15199f3629800a665a5e89824965 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?andr=C3=A9s=20gonz=C3=A1lez?= <andres.gonzalez79@gmail.com>
Date: Fri, 15 May 2026 10:53:43 +0200
Subject: [PATCH 4/6] :bug: Unify layout creation telemetry for plugins and MCP
 (#9654)

* :bug: Unify layout creation telemetry for plugins and MCP

* :books: Update changelog for version 2.15.4

Signed-off-by: Andrey Antukh <niwi@niwi.nz>

---------

Signed-off-by: Andrey Antukh <niwi@niwi.nz>
Co-authored-by: Andrey Antukh <niwi@niwi.nz>
---
 CHANGES.md                          | 6 ++++++
 frontend/src/app/plugins/shape.cljs | 4 ++--
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index b37c175a45..c34b2ade88 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,5 +1,11 @@
 # CHANGELOG
 
+## 2.15.4 (Unreleased)
+
+### :bug: Bugs fixed
+
+- Emit `create-shape-layout` for flex/grid layout creation from plugins and MCP (same event as workspace) [Github #9652](https://github.com/penpot/penpot/issues/9652)
+
 ## 2.15.3
 
 ### :bug: Bugs fixed
diff --git a/frontend/src/app/plugins/shape.cljs b/frontend/src/app/plugins/shape.cljs
index 0aeb837589..2725a58e9f 100644
--- a/frontend/src/app/plugins/shape.cljs
+++ b/frontend/src/app/plugins/shape.cljs
@@ -1017,7 +1017,7 @@
                  :else
                  (do (st/emit!
                       (dwsl/create-layout-from-id id :flex :from-frame? true :calculate-params? false)
-                      (se/event plugin-id "create-layout" :layout "flex"))
+                      (se/event plugin-id "create-shape-layout" :layout "flex"))
                      (flex/flex-layout-proxy plugin-id file-id page-id id)))))
 
            :addGridLayout
@@ -1032,7 +1032,7 @@
 
                  :else
                  (do (st/emit! (dwsl/create-layout-from-id id :grid :from-frame? true :calculate-params? false))
-                     (se/event plugin-id "create-layout" :layout "grid")
+                     (se/event plugin-id "create-shape-layout" :layout "grid")
                      (grid/grid-layout-proxy plugin-id file-id page-id id)))))
 
            ;; Make masks for groups

From fe7656718021d7e96146742795dd47386e2fca99 Mon Sep 17 00:00:00 2001
From: Andrey Antukh <niwi@niwi.nz>
Date: Fri, 15 May 2026 11:51:49 +0200
Subject: [PATCH 5/6] :paperclip: Backport opencode skills from staging

---
 .opencode/skills/taiga/SKILL.md | 110 ++++++++++++++++++++++++++++++++
 opencode.json                   |   4 --
 2 files changed, 110 insertions(+), 4 deletions(-)
 create mode 100644 .opencode/skills/taiga/SKILL.md
 delete mode 100644 opencode.json

diff --git a/.opencode/skills/taiga/SKILL.md b/.opencode/skills/taiga/SKILL.md
new file mode 100644
index 0000000000..890c965c03
--- /dev/null
+++ b/.opencode/skills/taiga/SKILL.md
@@ -0,0 +1,110 @@
+---
+name: taiga
+description: Fetch information from Taiga public API for the Penpot project (id 345963) — issues, user stories, and tasks, without authentication.
+metadata: {"clawdbot":{"requires":{"bins":["python3"]}}}
+---
+
+# Taiga API Skill
+
+Fetch information from Taiga public API for the **Penpot** project
+(project id: `345963`, slug: `penpot`).
+
+**No authentication required** — only public project data is accessed.
+
+## Prerequisites
+
+- `python3` — the `tools/taiga.py` CLI script is self-contained (stdlib only)
+
+## Quick Start
+
+The easiest way is to use the bundled Python script:
+
+```bash
+# Pass a Taiga URL directly
+python3 tools/taiga.py https://tree.taiga.io/project/penpot/issue/13714
+
+# Or use "<type> <ref>" syntax
+python3 tools/taiga.py us 14128
+python3 tools/taiga.py task 13648
+
+# Add --json for raw output
+python3 tools/taiga.py --json issue 13714
+
+# See full usage
+python3 tools/taiga.py --help
+```
+
+## URL Pattern Reference
+
+Taiga web URLs follow these patterns:
+
+| Type | Web URL Pattern |
+|------|----------------|
+| Issue | `https://tree.taiga.io/project/penpot/issue/<REF>` |
+| User Story | `https://tree.taiga.io/project/penpot/us/<REF>` |
+| Task | `https://tree.taiga.io/project/penpot/task/<REF>` |
+
+To extract the **type** and **ref** from a URL:
+- `issue/13714` → type=`issue`, ref=`13714`
+- `us/14128` → type=`us`, ref=`14128`
+- `task/13648` → type=`task`, ref=`13648`
+
+## Python Script Reference
+
+The `tools/taiga.py` script wraps the Taiga API into a single convenient CLI
+with sensible defaults.
+
+### Usage
+
+```
+python3 tools/taiga.py <taiga-url>
+python3 tools/taiga.py <type> <ref>
+python3 tools/taiga.py [--json] <taiga-url>
+python3 tools/taiga.py [--json] <type> <ref>
+```
+
+### Examples
+
+```bash
+# By URL (recommended — no need to think about type/ref)
+python3 tools/taiga.py https://tree.taiga.io/project/penpot/issue/13714
+
+# By type and ref
+python3 tools/taiga.py us 14128
+python3 tools/taiga.py task 13648
+
+# Raw JSON output
+python3 tools/taiga.py --json issue 13714
+```
+
+### Output
+
+The script prints a clean, structured summary:
+
+```text
+User Story #11964 — 🔴 [DESIGN TOKENS] Typography Composite Input
+================================
+Status:     Defining
+Milestone:  design-systems-sprint-26
+Points:     3 role(s)
+Assignee:   Natacha Menjibar
+Author:     Natacha Menjibar
+Created:    2025-09-01
+Tags:       iop-design-tokens
+URL:        https://tree.taiga.io/project/penpot/us/11964
+================================
+<full description text, unmodified>
+```
+
+The fields section includes type-specific information:
+- **Issues:** Status, Type ID, Severity ID, Priority ID
+- **User Stories:** Status, Milestone, Points
+- **Tasks:** Status, Milestone, Parent US
+
+## Reference
+
+- API docs: https://docs.taiga.io/api.html
+- Taiga instance: https://tree.taiga.io
+- API base: https://api.taiga.io/api/v1
+- Penpot project id: `345963`
+- Penpot project slug: `penpot`
diff --git a/opencode.json b/opencode.json
deleted file mode 100644
index 6376bc70e5..0000000000
--- a/opencode.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
-  "$schema": "https://opencode.ai/config.json",
-  "instructions": ["AGENTS.md"]
-}

From 6cc36e4fccc76be3cc942e943f9cdec03893d44e Mon Sep 17 00:00:00 2001
From: Andrey Antukh <niwi@niwi.nz>
Date: Fri, 15 May 2026 11:56:30 +0200
Subject: [PATCH 6/6] :paperclip: Backport more changes for opencode

---
 .opencode/skills/update-changelog/SKILL.md | 155 ++++++++++++---------
 1 file changed, 93 insertions(+), 62 deletions(-)

diff --git a/.opencode/skills/update-changelog/SKILL.md b/.opencode/skills/update-changelog/SKILL.md
index 889e77c3e6..5752b65aa3 100644
--- a/.opencode/skills/update-changelog/SKILL.md
+++ b/.opencode/skills/update-changelog/SKILL.md
@@ -7,7 +7,7 @@ description: Update the project CHANGES.md with issues from a given GitHub miles
 
 Update `CHANGES.md` with entries for all issues and PRs in a given GitHub
 milestone. Each entry references the user-facing issue (not the PR) as the
-primary link, with the fix PR on a sub-line.
+primary link, with the fix PR inline on the same line.
 
 ## When to Use
 
@@ -19,7 +19,8 @@ primary link, with the fix PR on a sub-line.
 ## Prerequisites
 
 - `gh` CLI authenticated (`gh auth status`)
-- Read access to the penpot/penpot repository
+- Python 3.8+
+- `tools/gh.py` helper script available
 
 ## Workflow
 
@@ -28,58 +29,64 @@ primary link, with the fix PR on a sub-line.
 The version is typically a semver string like `2.15.3`. Confirm with the user
 if not specified.
 
-### 2. Fetch all issues and PRs in the milestone
+### 2. Fetch all issues in the milestone
 
-Find the milestone number:
+Use the helper script. It uses GraphQL for efficient single-pass fetching
+(closing PRs are included in the same query — no N+1):
 
 ```bash
-gh api repos/penpot/penpot/milestones --paginate \
-  --jq '.[] | select(.title=="<VERSION>") | {number: .number, title: .title, open_issues: .open_issues, closed_issues: .closed_issues}'
+# All closed issues (default)
+python3 tools/gh.py issues "2.16.0"
+
+# Include open issues too
+python3 tools/gh.py issues "2.16.0" --state all
+
+# Exclude entries that should not go in the changelog
+python3 tools/gh.py issues "2.16.0" --exclude "release blocker,no changelog"
 ```
 
-Then fetch all items:
+**Label exclusion rules:**
+- `release blocker` — Internal release-blocking bugs not relevant to end users
+- `no changelog` — Chore/refactor work that doesn't need a changelog entry
+
+The script outputs JSON with each entry containing `number`, `title`, `state`,
+`labels`, and `closing_prs` (the PRs that fix each issue).
+
+### 3. Identify missing entries (optional)
+
+If updating from an existing `CHANGES.md`, find issues in the milestone that
+are NOT yet referenced in the changelog:
 
 ```bash
-MILESTONE_NUMBER=<NUMBER>
-gh api "repos/penpot/penpot/issues?milestone=$MILESTONE_NUMBER&state=all&per_page=100" \
-  --jq '.[] | {number: .number, title: .title, state: .state, labels: [.labels[].name], pull_request: .pull_request != null}'
+python3 tools/gh.py issues "2.16.0" --exclude "release blocker,no changelog" --compare CHANGES.md
 ```
 
-### 3. Identify issue ↔ PR relationships
+This returns a filtered JSON array with only the missing issues.
 
-For each item, determine the relationship:
+### 4. Fetch additional PR details when needed
 
-- **Issue** (`pull_request: false`): This is the user-facing issue. It
-  becomes the primary link in the changelog.
-- **PR** (`pull_request: true`): Check if it has `Fixes #<NUMBER>` in its
-  body to find which issue it closes.
-
-To find the linked issue for a PR:
+When you need more context for specific PRs (e.g. to find the PR author for
+community contribution attribution, or to read the PR body for
+"Fixes/Closes #NNN" patterns):
 
 ```bash
-gh pr view <PR_NUMBER> --repo penpot/penpot \
-  --json body,closingIssuesReferences --jq '{closingIssues: [.closingIssuesReferences[].number]}'
+# One or more PR numbers
+python3 tools/gh.py prs 9179 9204 9311
+
+# From a file
+python3 tools/gh.py prs --file prs.txt
+
+# From stdin
+cat prs.txt | python3 tools/gh.py prs --stdin
 ```
 
-**Only closed issues are included.** An issue must have `state: "closed"` to
-appear in the changelog. Open/unresolved issues are omitted, even if they are
-tracked in the milestone.
+The `prs` command returns JSON with `number`, `title`, `body`, `state`,
+`merged_at`, `author`, `labels`, and `closing_issues`. PRs are fetched in
+batches of 50 via GraphQL to stay within API limits.
 
-**Pairing rules:**
+### 5. Categorize entries
 
-| Pattern | Changelog format |
-|---------|-----------------|
-| Closed issue + one or more PRs fix it | Primary link = issue, sub-line with PRs comma-separated |
-| PR exists with no linked issue | If a corresponding closed issue exists in the same milestone, link the issue. Otherwise, skip the entry (the issue must be the changelog unit). |
-| Closed issue with no fix PR in milestone | Link the issue directly, without a PR sub-line. |
-
-### 4. Categorize entries
-
-Check the labels on each issue/PR:
-
-```bash
-gh issue view <NUMBER> --repo penpot/penpot --json labels --jq '[.labels[].name]'
-```
+Check the labels on each issue to determine which section it belongs to:
 
 | Label / Title prefix | Changelog section |
 |----------------------|-------------------|
@@ -90,19 +97,32 @@ gh issue view <NUMBER> --repo penpot/penpot --json labels --jq '[.labels[].name]
 **Community contribution attribution:** If the issue or its fix PR has the
 `community contribution` label, add an attribution `(by @<github_username>)`
 on the changelog entry line, **before** the GitHub issue/PR references.
-Fetch the author:
+
+The attribution should reference the **PR author**, not the issue author.
+The `prs` subcommand includes the `author` field — use that:
 
 ```bash
-gh issue view <NUMBER> --repo penpot/penpot --json author --jq '.author.login'
+python3 tools/gh.py prs <PR_NUMBER> | python3 -c "import sys,json; print(json.load(sys.stdin)[0]['author'])"
 ```
 
 Placement in the entry line:
 ```markdown
-- Fix description of the bug (by @username) [Github #<ISSUE>](...)
-  (PR: [#<PR>](...))
+- Fix description of the bug (by @username) [#<ISSUE>](...) (PR: [#<PR>](...))
 ```
 
-### 5. Read the current CHANGES.md
+**Only closed issues are included.** An issue must have `state: "closed"` to
+appear in the changelog. Open/unresolved issues are omitted, even if they are
+tracked in the milestone.
+
+**Pairing rules:**
+
+| Pattern | Changelog format |
+|---------|-----------------|
+| Closed issue + one or more PRs fix it | Primary link = issue, PR inline comma-separated |
+| PR exists with no linked issue | If a corresponding closed issue exists in the same milestone, link the issue. Otherwise, skip the entry (the issue must be the changelog unit). |
+| Closed issue with no fix PR in milestone | Link the issue directly, without a PR reference. |
+
+### 6. Read the current CHANGES.md
 
 Read the top of `CHANGES.md` to understand the existing format and find the
 insertion point (newest version goes at the top, after the `# CHANGELOG`
@@ -115,30 +135,29 @@ Key format rules from the existing file:
 
 ### :bug: Bugs fixed
 
-- Fix description of the bug [Github #<ISSUE>](https://github.com/penpot/penpot/issues/<ISSUE>)
-  (PR: [#<PR>](https://github.com/penpot/penpot/pull/<PR>))
-- Fix another bug (by @contributor) [Github #<ISSUE>](https://github.com/penpot/penpot/issues/<ISSUE>)
-  (PR: [#<PR>](https://github.com/penpot/penpot/pull/<PR>))
+- Fix description of the bug [#<ISSUE>](https://github.com/penpot/penpot/issues/<ISSUE>) (PR: [#<PR>](https://github.com/penpot/penpot/pull/<PR>))
+- Fix another bug (by @contributor) [#<ISSUE>](https://github.com/penpot/penpot/issues/<ISSUE>) (PR: [#<PR>](https://github.com/penpot/penpot/pull/<PR>))
 
 ### :sparkles: New features & Enhancements
 
-- Add new feature description [Github #<ISSUE>](https://github.com/penpot/penpot/issues/<ISSUE>)
-  (PR: [#<PR>](https://github.com/penpot/penpot/pull/<PR>))
+- Add new feature description [#<ISSUE>](https://github.com/penpot/penpot/issues/<ISSUE>) (PR: [#<PR>](https://github.com/penpot/penpot/pull/<PR>))
 ```
 
 Format details:
 - Entries start with `- ` followed by a short description in imperative mood
 - Primary link is **always the issue** (user-facing artifact)
-- PR references are on an indented sub-line: `  (PR: [#<N>](<url>))`
-  If an issue has multiple fix PRs, they are comma-separated on one line:
-  `  (PR: [#<N>](<url>), [#<M>](<url>))`
+- PR references are inline on the same line: `(PR: [#<N>](<url>))`
+  If an issue has multiple fix PRs, they are comma-separated:
+  `(PR: [#<N>](<url>), [#<M>](<url>))`
 - The description should describe the fix/feature from the user's perspective
-- Community contributions get `(by @<username>)` **before** the GitHub link
+- Community contributions get `(by @<username>)` **before** the issue link
 - Sections are separated by a blank line between the last entry and the next
   section title
 - Only include a section if there are entries for it
+- When an entry already exists in an earlier version section, it must be removed
+  from the current version to avoid duplicates
 
-### 6. Build the description text
+### 7. Build the description text
 
 Derive the description from the issue title, not the PR title. Strip leading
 emoji prefixes (`:bug:`, `:sparkles:`, `:tada:`) and focus on the
@@ -152,13 +171,13 @@ Examples:
 | `Comment content is not sanitized before rendering, enabling stored XSS` | `Sanitize comment content on rendering` |
 | `Custom uploaded font family names are not sanitized` | `Sanitize font family names on custom uploaded fonts` |
 
-### 7. Insert the section into CHANGES.md
+### 8. Insert the section into CHANGES.md
 
 Insert the new version section right after the `# CHANGELOG` header (before
 the previous version entry). Use the `edit` tool with enough context to make
 a unique match.
 
-### 8. Verify
+### 9. Verify
 
 Read the top of `CHANGES.md` and confirm:
 - The version header is correct
@@ -174,17 +193,15 @@ Read the top of `CHANGES.md` and confirm:
 
 ### :bug: Bugs fixed
 
-- <fix description> [Github #<ISSUE>](https://github.com/penpot/penpot/issues/<ISSUE>)
-  (PR: [#<PR>](https://github.com/penpot/penpot/pull/<PR>))
-- <fix description> (by @contributor) [Github #<ISSUE>](https://github.com/penpot/penpot/issues/<ISSUE>)
-  (PR: [#<PR>](https://github.com/penpot/penpot/pull/<PR>))
+- <fix description> [#<ISSUE>](https://github.com/penpot/penpot/issues/<ISSUE>) (PR: [#<PR>](https://github.com/penpot/penpot/pull/<PR>))
+- <fix description> (by @contributor) [#<ISSUE>](https://github.com/penpot/penpot/issues/<ISSUE>) (PR: [#<PR>](https://github.com/penpot/penpot/pull/<PR>))
 ```
 
 ## Key Principles
 
 - **Issue = changelog unit.** The primary link always points to the
   user-facing issue, not the implementation PR.
-- **PR = implementation detail.** Reference the PR on a sub-line so readers
+- **PR = implementation detail.** Reference the PR inline so readers
   can find the code changes.
 - **Latest version first.** New sections are inserted at the top of the
   changelog, below the `# CHANGELOG` header.
@@ -192,10 +209,24 @@ Read the top of `CHANGES.md` and confirm:
   what broke and what was fixed, not internal implementation details.
 - **Community attribution.** When the issue or fix PR has the
   `community contribution` label, add `(by @<username>)` on the entry line
-  between the description and the GitHub link.
+  between the description and the issue link. Use the **PR author** (not the
+  issue author) for the attribution.
 - **Only closed issues.** An issue must have `state: "closed"` to appear in
   the changelog. Open unresolved issues are omitted.
+- **Excluded labels.** Issues with `release blocker` or `no changelog` labels
+  must be excluded from the changelog.
 - **Multiple PRs per issue.** If multiple PRs fix the same issue, list them
-  comma-separated on the same sub-line: `(PR: [#A](url), [#B](url))`.
+  comma-separated inline: `(PR: [#A](url), [#B](url))`.
+- **Duplicate removal.** If an entry already exists in a prior version section,
+  remove it from the current version. Check for text-level duplicates (after
+  stripping links and attributions) across version sections.
+- **Taiga references.** If a changelog entry references a Taiga URL
+  (`tree.taiga.io`), attempt to find a corresponding GitHub issue via the
+  Taiga description text or by searching GitHub PRs that reference the Taiga
+  URL. Replace the Taiga reference with the GitHub issue link and add the PR
+  reference if applicable.
 - **Re-fetch before editing.** Milestones can change — always re-fetch issues
   before making edits, don't rely on cached data.
+- **Use `tools/gh.py`.** Prefer the helper script over raw `gh api` calls for
+  milestone issue listing and PR detail fetching. It handles GraphQL
+  pagination, batching, and label filtering automatically.