@aibyzero/byz 0.1.1 → 0.1.2

package/workflows/cm-plugin/docs//351/207/215/346/236/204/346/265/201/347/250/213/350/256/276/350/256/241/refactor-flow.spec.json

@@ -0,0 +1,223 @@
+{
+  "layout": "graph",
+  "direction": "right",
+  "style": "default",
+  "animation": "flow",
+  "canvas": {
+    "fps": 20,
+    "frames": 60
+  },
+  "title": {
+    "prefix": "cm-workflow",
+    "highlight": "重构流程总体设计",
+    "subtitle": "小闭环纪律 × Anthropic 迁移方法论 —— 修规则,不修产物"
+  },
+  "nodes": [
+    {
+      "id": "req",
+      "label": "重构诉求",
+      "icon": "ingest",
+      "icon_style": "illustrated",
+      "color": "#48e0c2"
+    },
+    {
+      "id": "route",
+      "label": "分流门",
+      "kind": "decision"
+    },
+    {
+      "id": "fix",
+      "label": "/cm-plugin:fix",
+      "icon": "tool-call",
+      "body": "缺陷闭环(不夹带修复)",
+      "color": "#ff7ab6"
+    },
+    {
+      "id": "prd",
+      "label": "/cm-plugin:prd --change",
+      "kind": "terminal",
+      "accent": "muted"
+    },
+    {
+      "id": "g0",
+      "label": "G0 可行性",
+      "icon": "human",
+      "icon_style": "illustrated",
+      "body": "动机量化·不重构合法",
+      "color": "#f4b64e"
+    },
+    {
+      "id": "judge",
+      "label": "判官自验证",
+      "icon": "guardrail",
+      "icon_style": "hero",
+      "icon_size": "hero",
+      "body": "原码必绿·坏码必红",
+      "color": "#7bb8ff"
+    },
+    {
+      "id": "scale",
+      "label": "规模门",
+      "kind": "decision"
+    },
+    {
+      "id": "lite",
+      "label": "轻量道·小闭环",
+      "icon": "loop",
+      "icon_style": "illustrated",
+      "body": "基线→重构→等价 一次跑完",
+      "color": "#48e0c2"
+    },
+    {
+      "id": "rule",
+      "label": "规则手册",
+      "icon": "plan",
+      "icon_style": "hero",
+      "icon_size": "hero",
+      "body": "分歧即入册·依赖图定序",
+      "color": "#b78bff"
+    },
+    {
+      "id": "pilot",
+      "label": "压力测试",
+      "icon": "sandbox",
+      "icon_style": "illustrated",
+      "body": "试点产物可弃·只留修订",
+      "color": "#f4b64e"
+    },
+    {
+      "id": "fan",
+      "label": "批量执行",
+      "icon": "subagent",
+      "icon_style": "illustrated",
+      "body": "队列=磁盘·配置禁令",
+      "color": "#b78bff"
+    },
+    {
+      "id": "mech",
+      "label": "机械裁决",
+      "icon": "compare",
+      "icon_style": "illustrated",
+      "body": "裁判价格定位",
+      "color": "#7bb8ff"
+    },
+    {
+      "id": "eq",
+      "label": "行为等价",
+      "icon": "score",
+      "icon_style": "illustrated",
+      "body": "全绿+差分一致",
+      "color": "#48e0c2"
+    },
+    {
+      "id": "rev",
+      "label": "审查凭证",
+      "icon": "audit",
+      "icon_style": "illustrated",
+      "body": "对抗审查·凭证落盘",
+      "color": "#ff7ab6"
+    },
+    {
+      "id": "done",
+      "label": "收口",
+      "icon": "checkpoint",
+      "icon_style": "illustrated",
+      "body": "档案·METRICS·缺陷转/cm-plugin:fix",
+      "accent": "green"
+    }
+  ],
+  "edges": [
+    {
+      "from": "req",
+      "to": "route"
+    },
+    {
+      "from": "route",
+      "to": "fix",
+      "label": "有缺陷"
+    },
+    {
+      "from": "route",
+      "to": "prd",
+      "label": "要改行为"
+    },
+    {
+      "from": "route",
+      "to": "g0",
+      "label": "结构问题·行为保持"
+    },
+    {
+      "from": "g0",
+      "to": "judge",
+      "label": "人签核"
+    },
+    {
+      "from": "judge",
+      "to": "scale",
+      "label": "无判官不开工"
+    },
+    {
+      "from": "scale",
+      "to": "lite",
+      "label": "单文件"
+    },
+    {
+      "from": "scale",
+      "to": "rule",
+      "label": "跨模块批量"
+    },
+    {
+      "from": "lite",
+      "to": "rev",
+      "label": "同款审查纪律"
+    },
+    {
+      "from": "rule",
+      "to": "pilot"
+    },
+    {
+      "from": "pilot",
+      "to": "fan",
+      "label": "规则定稿·人签核"
+    },
+    {
+      "from": "fan",
+      "to": "mech"
+    },
+    {
+      "from": "mech",
+      "to": "eq"
+    },
+    {
+      "from": "eq",
+      "to": "rev"
+    },
+    {
+      "from": "rev",
+      "to": "done"
+    },
+    {
+      "from": "pilot",
+      "to": "rule",
+      "kind": "loop",
+      "label": "修订排队·批间应用",
+      "accent": "purple"
+    },
+    {
+      "from": "mech",
+      "to": "rule",
+      "kind": "loop",
+      "label": "三次重复=规则bug·重生成",
+      "accent": "amber"
+    },
+    {
+      "from": "eq",
+      "to": "fan",
+      "kind": "loop",
+      "label": "行为差异=回滚重做",
+      "accent": "pink"
+    }
+  ],
+  "footer": "门在阶段之间,签核=踢下一阶段 | 纪律写进配置,不写进请求 | 判官没被验证过,就不配当判官",
+  "signature": "@cm-workflow"
+}

package/workflows/cm-plugin/package.json

@@ -0,0 +1,33 @@
+{
+	"name": "@aibyzero/cm-plugin-workflow",
+	"version": "0.5.0",
+	"description": "Spec-driven workflow for Chrome extension development",
+	"private": true,
+	"type": "module",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/kingxiaozhe/cm-plugin-workflow.git"
+	},
+	"keywords": [
+		"pi-package",
+		"coding-agent",
+		"chrome-extension",
+		"workflow",
+		"skills"
+	],
+	"files": [
+		"VERSION",
+		"README.md",
+		"LICENSE",
+		"agents",
+		"commands",
+		"docs",
+		"skills",
+		"templates"
+	],
+	"pi": {
+		"skills": ["./skills"],
+		"prompts": ["./commands"]
+	}
+}

package/workflows/cm-plugin/skills/cm-plugin-backend-engineer/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: cm-plugin-backend-engineer
+description: 后端 API 工程师 Skill，执行服务端 API 层开发（路由、业务逻辑、鉴权中间件、缓存、队列），自动适配语言和框架
+---
+
+# cm-plugin-backend-engineer — 后端 API 工程师
+
+执行服务端 API 层开发任务。自动识别语言和框架。
+
+## 职责边界
+
+- **管**：路由/控制器、业务逻辑、鉴权与权限中间件、缓存策略、消息队列、数据库 schema 与 migration、对外接口说明；扩展场景下的专属关注：**扩展侧调用的 CORS 允许来源（`chrome-extension://{id}`）与鉴权方案（扩展里无传统 cookie 会话，走 token）**、API 密钥代理层（密钥只在服务端）
+- **不管**：扩展本体代码（→ cm-plugin-extension-engineer）、测试补全与 E2E（→ cm-plugin-qa-engineer）
+
+## 触发条件
+
+由 `/cm-plugin:ai` 自动调用，当 task 涉及后端 API 开发时触发。
+
+## 工作流程
+
+### 1. 识别技术栈
+
+自动检测，不做硬编码假设：
+
+- **语言/运行时**：Node.js / Python / Go / Java / Rust
+- **框架**：Express / Fastify / Hono / NestJS / FastAPI / Django / Gin / Spring 等
+- **鉴权方案**：JWT / Session / OAuth2 / BetterAuth 等（读现有中间件与依赖判断）
+- **接口风格**：REST / GraphQL / tRPC / gRPC（读路由与已有接口定义判断）
+
+### 2. 读取上下文
+
+- `.claude/rules/backend-api.md`、`.claude/rules/security.md`（如存在）
+- design.md 中的**接口契约**——本 skill 的最高约束
+- 现有路由组织、错误处理约定、中间件链
+
+### 3. 契约纪律（本 skill 核心）
+
+design.md 的接口契约是前后端并行的生命线，执行**三级协议**：
+
+1. **执行者只报不改**：实现中发现契约不合理或不完整 → **不得静默偏离、不得直接修改 design.md**，将偏差和理由写入完成汇报的「契约相关」栏
+2. **主流程小改留痕**：字段增补等小偏差由主流程更新 design.md 并标注版本（对齐 `[CHANGED]` 惯例）
+3. **大改必须问人**：偏差影响**已完成任务**所依赖的契约（会引发返工）→ 强制暂停人工确认
+
+实现完成后逐条核对：路径、方法、请求/响应字段、错误码与契约一致。
+
+### 4. 开发
+
+**接口实现：**
+
+- 遵循项目已有的路由组织和分层（controller/service/repository 等按项目实际）
+- 错误处理统一：错误码、错误体结构跟随项目约定，无约定则建立一处并全局复用
+- 输入验证在边界层完成，校验库跟随项目已有选择
+- 幂等性：写操作考虑重复提交（幂等键/去重），支付类接口强制
+
+**鉴权与权限：**
+
+- 复用项目已有的鉴权中间件，不另起炉灶
+- 权限检查靠近资源（handler 层），不散落各处
+- 敏感操作留审计日志
+
+**性能与可靠性**（以下为默认值，`.claude/rules/` 有规定时**以 rules 为准**）：
+
+- 外部调用必须有超时，默认 5s
+- 列表接口必须分页，默认页大小 20
+- 高频读考虑缓存、写路径考虑队列削峰——是否引入新基础设施以 design.md 为准，不擅自添加
+
+### 5. 安全检查
+
+- 密钥/连接串一律环境变量，绝不硬编码
+- 注入防护：参数化查询、模板转义（与 database skill 双保险）
+- 鉴权绕过自查：逐条核对本次新增路由是否漏挂鉴权中间件
+- 日志不输出密码、token、证件号等敏感字段
+
+### 6. 验证
+
+```bash
+# 根据项目实际命令执行
+npm run lint && npm run typecheck
+npm run build
+```
+
+启动服务，对本 task 涉及的接口逐个实测（curl/httpie）：正常流 + 至少一个异常流（4xx）。
+
+## 常见坑
+
+| 问题 | 处理 |
+| ---- | ---- |
+| 新路由漏挂鉴权中间件 | 按路由分组统一挂载，逐条核对本次新增路由 |
+| 外部调用无超时导致雪崩 | 统一封装 HTTP client，强制超时与重试上限 |
+| 错误体结构不一致，前端难处理 | 全局错误处理器统一出口，禁止 handler 内裸造错误体 |
+| 时间/时区序列化不一致 | 统一 UTC + ISO 8601 出参，入参解析集中处理 |
+| 阻塞事件循环（大 JSON / 同步加密） | 大计算移 worker 或队列，序列化分页 |
+| 分页游标与排序不稳定 | 排序键唯一化（时间戳+id），游标编码含排序上下文 |
+
+## 输出
+
+- 创建/修改的文件列表
+- 验证结果（lint / build / 接口实测）
+- **契约实现情况**：逐条列出实现的接口，标注与 design.md 的偏差（无偏差则写"完全一致"）
+- 需要其他工种配合的事项（如前端可替换 mock 的接口清单、需要数据库配合的字段）

package/workflows/cm-plugin/skills/cm-plugin-devops-engineer/NOTICE.md

@@ -0,0 +1,14 @@
+# NOTICE — 第三方收编素材
+
+本 skill 的 `references/` 下两个文件收编自外部开源仓库：
+
+- 来源：[quangpl/browser-extension-skills](https://github.com/quangpl/browser-extension-skills)（MIT License, Copyright (c) 2026 quangpl）
+- 收编日期：2026-07-18
+- 文件与改动：
+
+| 本仓库文件 | 上游文件 | 改动 |
+| ---- | ---- | ---- |
+| `references/cws-submission-checklist.md` | `skills/extension-publish/references/submission-checklist.md` | 仅重命名，内容未改动 |
+| `references/cws-ci-cd.md` | `skills/extension-publish/references/ci-cd-automation.md` | 仅重命名，内容未改动 |
+
+上游许可为 MIT，允许再分发；本文件即为许可与来源声明的履约载体。

package/workflows/cm-plugin/skills/cm-plugin-devops-engineer/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: cm-plugin-devops-engineer
+description: 发布/运维工程师 Skill，执行扩展打包、商店提审准备、配套后端部署、冒烟验证与发布记录；商店提审与生产发布强制人工确认
+---
+
+# cm-plugin-devops-engineer — 发布/运维工程师
+
+执行打包、发布与部署任务，把审查通过的代码送到用户手里并验证。**把关型角色：串行执行，不做 agent。**
+
+发布对象有两类，通道完全不同：**扩展本体**（打包 zip → Chrome Web Store 提审，结果异步）和**配套后端**（常规服务端部署，如有）。
+
+## 触发条件
+
+- `/cm-plugin:ai` N3 派发**打包/发布/部署类任务**时触发（由 /cm-plugin:prd 模板生成）
+- N8 收尾时编制**发布待决清单**（只编制，不执行）
+
+## 三条硬闸（不可违反）
+
+1. **无回滚预案的发布不执行**——扩展本体的"回滚"很特殊：商店不支持一键回滚旧版，预案 = 保留上一版可提审的打包产物 + 明确降版重提流程；后端照常写清代码与迁移回退
+2. **Chrome Web Store 提审（含权限变更的版本更新）与生产后端部署强制人工确认**；本地打包、内测分发（unlisted / trusted testers）及 staging 后端可自动
+3. **新开或变更基础设施强制人工确认**：新商店开发者账号、新域名与证书、新数据库/实例、付费套餐变更。常规发布到**已有通道**不触发此闸
+
+## 工作流程
+
+### 1. 识别发布栈
+
+自动检测，不做硬编码假设：
+
+- **扩展本体**：脚手架（WXT `wxt zip` / Plasmo `plasmo package` / 自建 zip 脚本）、目标商店（Chrome Web Store；含 Edge Add-ons / Firefox AMO 时通道分列）、是否配置 CI 自动打包
+- **配套后端**（如有）：Docker/K8s / Serverless / 静态托管 / 传统主机，检测 Dockerfile / serverless.yml / vercel.json / wrangler.toml / CI 配置
+- **CI/CD**：识别已有流水线（bootstrap T-003 所建），优先复用而非另建
+
+### 2. 发布前检查（全部通过才执行）
+
+- [ ] 回滚预案已写明（硬闸 1，含上一版产物的留存位置）
+- [ ] **版本号已递增**且 manifest 版本与 package.json / 发布记录一致
+- [ ] **权限 diff 核对**：对比上一发布版 manifest——新增 permission / host_permission 逐项有用途理由；有权限扩张 → 显式标注"本次提审将触发商店重点审核"，走硬闸 2 人工确认
+- [ ] **商店合规自查**（提审前最后一道）：单一用途描述与实际功能一致、隐私政策链接有效且覆盖实际收集的数据项、无远程代码、商店素材（截图/描述）与当前版本一致——发现问题回流 `cm-plugin-qa-engineer` 商店合规检查单逐项过
+- [ ] **提审材料齐备**：按 `references/cws-submission-checklist.md`（MIT 收编素材，见 NOTICE.md）逐项核对——manifest 字段上限（name ≤45 字符 / description ≤132 字符）、图标四尺寸、截图规格（1280×800 或 640×400 精确尺寸）、敏感权限逐项 justification、Privacy practices 数据披露表
+- [ ] 构建产物来自已通过 N4 审查的代码（不发布未审查内容）
+- [ ] 后端（如有）：环境变量核对、迁移先备份点先兼容后清理、**后端先于扩展发布**（老版本扩展会在商店审核期继续调用线上 API，接口只能加不能破坏）
+
+### 3. 执行发布
+
+- **扩展本体**：用脚手架既有打包命令出 zip → 本地以解包形式加载 zip 解出的产物做最终冒烟 → 内测通道（unlisted / trusted testers）可直接分发；**公开提审过硬闸 2**，人确认后上传并提交审核
+- **商店无 staging 轨道**——staging 对应物 = 第二个 unlisted 的 extension ID（`main` 分支推 staging ID，打 tag 才发生产 ID）；CI 自动上传用 `chrome-webstore-upload-cli`，凭证配置、双轨 GitHub Actions 模板与灰度发布（trustedTesters target）见 `references/cws-ci-cd.md`（bootstrap T-003 搭 CI 时直接取用）
+- **后端**：用项目既有部署命令/流水线部署 staging，不发明新方式
+- 动作与输出全程记录（时间、版本/commit、通道、执行的迁移）
+
+### 4. 冒烟验证
+
+- 打包产物在干净浏览器 profile 加载：manifest 无报错、service worker 注册、本次 feature 关键流程各走一次
+- 后端（如有）：健康检查 + 本 feature 关键接口正常流
+- **失败处理（3 轮上限）**：冒烟不过 → 不提审/执行回滚 → 失败项按 bug 回流开发。**最多 3 轮，3 轮不过暂停问人**
+
+### 5. 发布记录落盘
+
+追加到 `{SPECS_DIR}/RELEASES.md`（审计链延伸到商店与线上）：
+
+```markdown
+## {日期} — {feature 名} → {通道}
+- 版本: {manifest version + commit sha；NO_GIT 模式记打包时间戳 + no-git 备注}
+- 通道: {本地内测 / unlisted / Chrome Web Store 提审 / 后端 staging / 后端生产}
+- 权限 diff: {新增/移除的权限及理由，无则"无变化"}
+- 迁移: {后端 migration 列表，无则"无"}
+- 冒烟: {通过 / 第 N 轮通过}
+- 商店审核状态: {未提审 / 审核中(提交时间) / 已过审 / 被拒(原因)}
+- 回滚预案: {上一版产物位置 + 后端回退命令}
+```
+
+## 商店审核期纪律（提审后）
+
+- 审核结果异步（数小时到数周），**作为待决项跟踪，不阻塞后续 feature 开发**
+- **被拒处理**：拒审邮件里的违规码先对照 `cm-plugin-qa-engineer` 的 `references/cws-violation-codes.md` 定性，原因原文记入 RELEASES.md → 按 bug 回流正常任务流程修复 → 修完提交申诉（Developer Dashboard，注明改动点，典型 1-3 个工作日）；权限类拒审必须回到 /cm-plugin:prd 层面重新确认权限方案，不得在发布层"换个说法再试"
+- 审核期内不叠加提交新版本（会重置排队），紧急修复除外并记录理由
+
+## 发布待决清单（N8 调用，只编制不执行）
+
+```markdown
+# 发布待决清单 — {日期}
+- 已通过验证待提审的版本: {manifest version + 包含的 feature 列表}
+- 权限 diff 与提审风险: {权限扩张项及理由；无则"无——常规审核"}
+- 商店材料就绪情况: {描述/截图/隐私政策/单一用途说明 各项状态}
+- {如有后端} 生产部署清单: {迁移顺序含备份点、新增环境变量 key 列表}
+- 回滚预案位置: {上一版产物路径 + 后端回退命令}
+```
+
+商店提审与生产部署由**人**决策触发；人下达指令后按本 skill 流程执行（硬闸 1 仍然生效）。
+
+## 上线后验证（发布执行完毕的强制收尾）
+
+发布"执行完"不等于"活着"——结果追加 RELEASES.md：
+
+- **过审后**：从商店真实安装（或更新到）新版本，按本次 feature 的波及面清单逐项冒烟；重点验证**老用户升级路径**（存量 chrome.storage 数据在新 schema 下正常）
+- 后端生产发布 → 真实域名关键流验证
+- 记录格式：`线上验证: 通过({N}项) / 异常({具体项})`——异常立即执行回滚预案并按 bug 回流
+- **不做上线后验证的发布记录视为未完成**
+
+## 凭证纪律
+
+- 商店 API 凭证（client_id/refresh_token）与服务器凭证只从环境变量 / 密钥管理读取
+- **不得要求用户在对话中粘贴密钥，不得将凭证写入任何文件或日志**
+
+## 常见坑
+
+| 问题 | 处理 |
+| ---- | ---- |
+| 提审被拒第一大原因：权限缺理由或过宽 | 发布前权限 diff 核对，扩张项提前过人工确认 |
+| 商店审核期扩展旧版仍在调新后端 | 后端接口只加不破坏；破坏性变更等商店过审铺开后再清理 |
+| zip 里带了 sourcemap/开发文件 | 打包用脚手架官方命令，产物列表过一眼再上传 |
+| 版本号忘递增导致上传被拒 | 发布前检查含版本号核对，CI 里加校验 |
+| 升级后老用户数据"丢失" | storage schema 变更必须带迁移逻辑，上线后验证含升级路径 |
+| 隐私政策链接失效/未覆盖新收集项 | 商店合规自查逐项对照实际数据流 |
+
+## 输出
+
+- 发布结果（通道、版本、权限 diff、迁移执行情况）
+- 冒烟与上线后验证结果（通过项 / 失败项及处理）
+- RELEASES.md 追加记录
+- 需人工决策的事项（商店提审、生产部署、基础设施变更）

package/workflows/cm-plugin/skills/cm-plugin-devops-engineer/references/cws-ci-cd.md

@@ -0,0 +1,139 @@
+# CI/CD Automation
+
+## chrome-webstore-upload Setup
+
+### Install
+
+```bash
+npm install --save-dev chrome-webstore-upload-cli
+# or global
+npm install -g chrome-webstore-upload-cli
+```
+
+### Get API Credentials
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com)
+2. Create project → Enable **Chrome Web Store API**
+3. Create OAuth 2.0 Client ID (Desktop app type)
+4. Download `client_id` and `client_secret`
+5. Get refresh token (one-time):
+
+```bash
+npx chrome-webstore-upload-cli get-refresh-token \
+  --client-id $CLIENT_ID \
+  --client-secret $CLIENT_SECRET
+```
+
+6. Store all three as CI secrets: `CWS_CLIENT_ID`, `CWS_CLIENT_SECRET`, `CWS_REFRESH_TOKEN`
+
+---
+
+## GitHub Actions Workflow
+
+```yaml
+# .github/workflows/publish.yml
+name: Publish to Chrome Web Store
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+
+      - name: Build extension
+        run: npm run build
+
+      - name: Package extension
+        run: |
+          cd dist
+          zip -r ../extension.zip . --exclude "*.map"
+
+      - name: Upload to Chrome Web Store
+        run: |
+          npx chrome-webstore-upload-cli upload \
+            --source extension.zip \
+            --extension-id ${{ secrets.CWS_EXTENSION_ID }} \
+            --client-id ${{ secrets.CWS_CLIENT_ID }} \
+            --client-secret ${{ secrets.CWS_CLIENT_SECRET }} \
+            --refresh-token ${{ secrets.CWS_REFRESH_TOKEN }}
+
+      - name: Publish to users
+        run: |
+          npx chrome-webstore-upload-cli publish \
+            --extension-id ${{ secrets.CWS_EXTENSION_ID }} \
+            --client-id ${{ secrets.CWS_CLIENT_ID }} \
+            --client-secret ${{ secrets.CWS_CLIENT_SECRET }} \
+            --refresh-token ${{ secrets.CWS_REFRESH_TOKEN }}
+```
+
+---
+
+## Versioning Automation
+
+Auto-bump version from git tag:
+
+```bash
+# scripts/bump-version.sh
+TAG=${GITHUB_REF#refs/tags/v}   # e.g., "1.2.3"
+jq --arg v "$TAG" '.version = $v' manifest.json > tmp.json
+mv tmp.json manifest.json
+```
+
+Add to workflow before build step:
+
+```yaml
+- name: Bump version from tag
+  run: bash scripts/bump-version.sh
+```
+
+---
+
+## Staging vs Production Tracks
+
+Chrome Web Store has no staging track — use separate extension IDs:
+
+| Track | Extension ID | Visibility |
+|-------|-------------|------------|
+| Staging | `$STAGING_EXT_ID` | Unlisted |
+| Production | `$PROD_EXT_ID` | Public |
+
+Workflow strategy:
+
+```yaml
+on:
+  push:
+    branches: [main]    # → upload to staging (unlisted)
+    tags: ['v*']        # → upload + publish to production
+```
+
+Use `--trusted-testers` flag or `unlisted` visibility for staging builds.
+
+---
+
+## Rollout Control
+
+Publish to percentage of users (via API, not CLI):
+
+```bash
+curl -X POST \
+  "https://www.googleapis.com/chromewebstore/v1.1/items/$EXT_ID/publish" \
+  -H "Authorization: Bearer $ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"target": "trustedTesters"}'
+# target: "default" = all users, "trustedTesters" = testers only
+```