docs: sync Marketplace action across locales + restore plugin version lockstep (#23)

Self-audit (2026-07-06) found PR #20-22 added the root action.yml
(GitHub Marketplace composite action) but only updated the English
README and left plugin.json version behind marketplace.json. Sync the
Marketplace action section to all 4 non-English READMEs (fenced
code/YAML kept byte-identical to the en base), add action.yml to the
§6 repo tree and a Marketplace Composite Action subsection in all 5
design.md files, describe the resulting three integration paths in
all 5 overview.md files and in the root CLAUDE.md, and bump
plugin.json to 2.1.1 to match marketplace.json.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: wei18

CLAUDE.md

@@ -4,9 +4,10 @@ Local dir is `repo-audit-action/`; the **published name is `wei18/upkeep`** —
 
 ## What this is
 
-An AI repo auditor that catches drift (stale docs, spec/code mismatch, orphaned assets, convention violations). Pipeline: **discovery → parallel reviewers → synthesis → HTML report**. Two entry points, one engine:
+An AI repo auditor that catches drift (stale docs, spec/code mismatch, orphaned assets, convention violations). Pipeline: **discovery → parallel reviewers → synthesis → HTML report**. Three entry points, one engine:
 
 - **CI**: reusable workflow `.github/workflows/audit.yml` (`on: workflow_call`) + composite actions under `.github/actions/`. Runs on the *caller's* checkout; Upkeep's code arrives via `uses: wei18/upkeep/.github/actions/<x>@<tag>`. Each reviewer is an independent matrix job. Upserts one tracking issue.
+- **Marketplace**: root `action.yml`, a composite action for the conventional `- uses: wei18/upkeep@<tag>` step syntax and a GitHub Marketplace listing. Same engine and inputs as the reusable workflow, but runs as a single job so reviewers execute sequentially instead of in parallel.
 - **Local**: `scripts/local-audit.sh <target>` — same flow, `claude -p` subprocesses, temp-dir intermediates via `--add-dir`. Never creates issues; prints the summary instead. `skills/upkeep-audit/SKILL.md` is a thin wrapper (clones engine to `~/.cache/upkeep`, runs script, summarizes). The CI workflow does **not** route through the skill.
 
 ## Hard invariants

docs/en/design.md

@@ -74,6 +74,10 @@ Key points:
 
 The same pipeline runs locally via `scripts/local-audit.sh <target>`: discovery → parallel `claude -p` reviewer subprocesses → synthesis → report. All intermediates (inventory, prompts, findings, synthesis) live in a `mktemp` work dir granted to Claude via `--add-dir` — nothing is written into the target repo. Local runs produce the same self-contained HTML report; instead of upserting a GitHub issue, the issue markdown is printed as the terminal summary. `skills/upkeep-audit/SKILL.md` is a thin Claude Code wrapper around the script: it maintains a clone in `~/.cache/upkeep`, runs the audit, and summarizes findings in chat. The skill is distributed three ways, all pointing at the same directory: as a Claude Code plugin (`.claude-plugin/marketplace.json` at the repo root lists `skills/upkeep-audit/` as a single-skill plugin named `upkeep`, installed via `/plugin install upkeep@upkeep`), via `npx skills add wei18/upkeep --skill upkeep-audit` (vercel-labs/skills flat layout), or by manual copy into `~/.claude/skills/`. Distribution is packaging only — the CI workflow remains a direct pipeline entry and does not route through the skill.
 
+### Marketplace Composite Action
+
+A third integration path packages the same engine as a composite action at the repo root (`action.yml`), giving callers the conventional `- uses: wei18/upkeep@v2` step syntax and a listing on the [GitHub Marketplace](https://github.com/marketplace). Because a composite action is a single job with no `strategy.matrix`, its `discovery` → `reviewer` (×7) → `synthesis` → `report` steps run sequentially instead of in parallel — same engine, same inputs, just slower on repos with many enabled reviewers. See `docs/why-reusable-workflow.md` for why the reusable workflow above remains the primary path. Distribution here is packaging only, same as the skill: `action.yml` calls the same `.github/actions/<x>@v2` sub-actions the reusable workflow uses.
+
 ---
 
 ## 2. Reviewer Team
@@ -216,6 +220,7 @@ Expected structure:
 
 ```
 repo-audit-action/                   # local directory (published name: Upkeep)
+├── action.yml                        # composite action (Marketplace listing): `uses: wei18/upkeep@v2`, sequential reviewer steps
 ├── .github/
 │   ├── workflows/audit.yml          # reusable workflow (on: workflow_call): jobs/matrix orchestration
 │   └── actions/                     # composite sub-actions (used by the workflow's jobs; carry Upkeep's own code)

docs/en/overview.md

@@ -8,7 +8,7 @@ Periodic human review catches some of it, but it requires keeping the full conte
 
 ## The pipeline: fan-out → synthesis → report
 
-Upkeep has two entry points that share one engine: a reusable `workflow_call` workflow for CI, and a local Claude Code skill / plugin (or plain script) for running on your machine. Either way the pipeline is the same five stages: Discovery, Consolidate, and Report are deterministic (no LLM); the parallel reviewers and Synthesis are the LLM-driven stages.
+Upkeep has three integration paths that share one engine: a reusable `workflow_call` workflow for CI, a Marketplace composite action (`- uses: wei18/upkeep@v2`, same engine and inputs, reviewers run sequentially instead of in parallel) for callers who want the conventional step syntax, and a local Claude Code skill / plugin (or plain script) for running on your machine. Either way the pipeline is the same five stages: Discovery, Consolidate, and Report are deterministic (no LLM); the parallel reviewers and Synthesis are the LLM-driven stages.
 
 **1. Discovery**
 

docs/ja/README.md

@@ -116,6 +116,44 @@ jobs:
 
 > まだ `@v1` をお使いですか？引き続き動作しますが凍結されています——タグを `@v2` に切り替えてください。インターフェースは同一です。
 
+### Marketplace action として使う場合
+
+おなじみの `- uses:` step 構文を使いたい場合や、Upkeep を
+[GitHub Marketplace](https://github.com/marketplace) に表示させたい場合は、
+**Upkeep Audit** action を代わりに使用してください——同じエンジン、同じ入力
+ですが、レビュアーは並列ではなく順番に実行されます（上記の reusable workflow
+が主要なパスである理由については
+[`docs/why-reusable-workflow.md`](why-reusable-workflow.md) を参照）：
+
+```yaml
+name: repo audit
+on:
+  schedule:
+    - cron: '0 3 * * 1'   # weekly, Monday 03:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+  id-token: write
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: wei18/upkeep@v2
+        with:
+          model: claude-opus-4-8               # optional
+          issue_label: audit                    # optional; default: audit
+          rubric_lang: en                       # optional; reviewer language: en | zh-TW
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+```
+
+上記と同じ要件です：`CLAUDE_CODE_OAUTH_TOKEN` という名前のリポジトリ secret
+（`claude setup-token` で生成）と `permissions` ブロック。step action は
+自身の permissions を宣言できないため、今回は job 自体に付与します。
+
 ## レビュアー
 
 | 名前 | デフォルト | チェック内容 |

docs/ja/design.md

@@ -74,6 +74,10 @@
 
 同じパイプラインは `scripts/local-audit.sh <target>` でローカルでも実行できる：discovery → 並列の `claude -p` レビュアーサブプロセス → synthesis → report。中間生成物（inventory、prompts、findings、synthesis）はすべて `mktemp` の作業ディレクトリに置かれ、`--add-dir` で Claude に許可される——対象リポジトリには何も書き込まない。ローカル実行でも同じセルフコンテインドな HTML レポートを生成する。GitHub issue の upsert は行わず、issue の markdown をターミナルサマリーとして出力する。`skills/upkeep-audit/SKILL.md` はこのスクリプトの薄い Claude Code ラッパーで、`~/.cache/upkeep` のクローンを維持し、監査を実行し、findings をチャットで要約する。この skill は 3 つの方法で配布され、いずれも同じディレクトリを指す：Claude Code plugin として（リポジトリルートの `.claude-plugin/marketplace.json` が `skills/upkeep-audit/` を `upkeep` という名前の single-skill plugin として登録し、`/plugin install upkeep@upkeep` でインストール）、`npx skills add wei18/upkeep --skill upkeep-audit` 経由（vercel-labs/skills のフラットレイアウト）、または `~/.claude/skills/` への手動コピー。配布はあくまでパッケージングであり——CI workflow は引き続き直接のパイプラインエントリのままで、skill を経由しない。
 
+### Marketplace Composite Action
+
+3 つ目の統合パスとして、同じエンジンをリポジトリルートの composite action（`action.yml`）としてパッケージ化し、おなじみの `- uses: wei18/upkeep@v2` step 構文と [GitHub Marketplace](https://github.com/marketplace) への掲載を可能にする。composite action は `strategy.matrix` を使えない単一 job であるため、その `discovery` → `reviewer`（×7）→ `synthesis` → `report` の各ステップは並列ではなく順番に実行される——エンジンと入力は同じだが、有効な reviewer が多いリポジトリでは実行が遅くなる。上記の reusable workflow が主要なパスであり続ける理由は `docs/why-reusable-workflow.md` を参照。ここでの配布も skill と同様にあくまでパッケージングであり、`action.yml` は reusable workflow が使うのと同じ `.github/actions/<x>@v2` サブアクションを呼び出している。
+
 ---
 
 ## 2. Reviewer チーム
@@ -216,6 +220,7 @@ report:
 
 ```
 repo-audit-action/                   # ローカルディレクトリ（公開名 Upkeep）
+├── action.yml                        # composite action（Marketplace 掲載用）：`uses: wei18/upkeep@v2`、reviewer ステップは順番に実行
 ├── .github/
 │   ├── workflows/audit.yml          # 再利用可能 workflow（on: workflow_call）：jobs/matrix オーケストレーション
 │   └── actions/                     # composite サブ action（workflow の job が uses で参照、Upkeep コードを内包）

docs/ja/overview.md

@@ -8,7 +8,7 @@
 
 ## パイプライン: ファンアウト → 統合 → レポート
 
-Upkeep には同一のエンジンを共有する2つのエントリーポイントがあります。CI 用の再利用可能な `workflow_call` workflow と、ローカルで実行する Claude Code skill / plugin（あるいは単なるスクリプト）です。いずれの場合もパイプラインは同じ5つのステージです。Discovery、Consolidate、Report は決定論的（LLM なし）であり、並列の reviewers と Synthesis が LLM 駆動のステージです。
+Upkeep には同一のエンジンを共有する3つの統合パスがあります。CI 用の再利用可能な `workflow_call` workflow、おなじみの step 構文を使いたい場合向けの Marketplace composite action（`- uses: wei18/upkeep@v2`。エンジンと入力は同じですが、reviewer は並列ではなく順番に実行されます）、そしてローカルで実行する Claude Code skill / plugin（あるいは単なるスクリプト）です。いずれの場合もパイプラインは同じ5つのステージです。Discovery、Consolidate、Report は決定論的（LLM なし）であり、並列の reviewers と Synthesis が LLM 駆動のステージです。
 
 **1. ディスカバリー**
 

docs/ko/README.md

@@ -116,6 +116,44 @@ jobs:
 
 > 아직 `@v1`을 사용 중인가요? 계속 동작하지만 동결되었습니다 — 태그를 `@v2`로 바꾸세요. 인터페이스는 동일합니다.
 
+### 또는 Marketplace action으로
+
+익숙한 `- uses:` step 문법을 선호하거나 Upkeep을
+[GitHub Marketplace](https://github.com/marketplace)에 노출하고 싶다면?
+대신 **Upkeep Audit** action을 사용하세요 — 동일한 엔진, 동일한 입력이지만
+리뷰어가 병렬이 아니라 차례로 실행됩니다(위 reusable workflow가 기본
+경로인 이유는 [`docs/why-reusable-workflow.md`](why-reusable-workflow.md)
+참조):
+
+```yaml
+name: repo audit
+on:
+  schedule:
+    - cron: '0 3 * * 1'   # weekly, Monday 03:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+  id-token: write
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: wei18/upkeep@v2
+        with:
+          model: claude-opus-4-8               # optional
+          issue_label: audit                    # optional; default: audit
+          rubric_lang: en                       # optional; reviewer language: en | zh-TW
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+```
+
+위와 동일한 요구 사항입니다: `CLAUDE_CODE_OAUTH_TOKEN`라는 이름의 저장소
+secret(`claude setup-token`으로 생성)과 `permissions` 블록. step action은
+자체적으로 permissions를 선언할 수 없으므로, 이번에는 job 자체에 지정합니다.
+
 ## 리뷰어
 
 | 이름 | 기본값 | 검사 항목 |

docs/ko/design.md

@@ -74,6 +74,10 @@
 
 동일한 파이프라인을 `scripts/local-audit.sh <target>`로 로컬에서 실행할 수 있다: discovery → 병렬 `claude -p` 리뷰어 서브프로세스 → synthesis → report. 모든 중간 산출물(inventory, prompts, findings, synthesis)은 `mktemp` 작업 디렉터리에 두고 `--add-dir`로 Claude에 권한을 부여한다 — 대상 저장소에는 아무것도 쓰지 않는다. 로컬 실행도 동일한 self-contained HTML 리포트를 생성하며, GitHub 이슈를 upsert하는 대신 이슈 markdown을 터미널 요약으로 출력한다. `skills/upkeep-audit/SKILL.md`는 이 스크립트의 얇은 Claude Code 래퍼로, `~/.cache/upkeep` 클론을 유지하고 감사를 실행한 뒤 findings를 채팅으로 요약한다. 이 skill은 세 가지 방식으로 배포되며 모두 동일한 디렉터리를 가리킨다: Claude Code plugin으로(저장소 루트의 `.claude-plugin/marketplace.json`이 `skills/upkeep-audit/`을 `upkeep`이라는 이름의 single-skill plugin으로 등록하며 `/plugin install upkeep@upkeep`으로 설치), `npx skills add wei18/upkeep --skill upkeep-audit`을 통해(vercel-labs/skills 플랫 레이아웃), 또는 `~/.claude/skills/`에 수동 복사. 배포는 패키징일 뿐이며 — CI workflow는 여전히 직접적인 파이프라인 진입점으로, skill을 거치지 않는다.
 
+### Marketplace Composite Action
+
+세 번째 통합 경로는 동일한 엔진을 저장소 루트의 composite action(`action.yml`)으로 패키징하여, 익숙한 `- uses: wei18/upkeep@v2` step 문법과 [GitHub Marketplace](https://github.com/marketplace) 등재를 가능하게 한다. composite action은 `strategy.matrix`를 사용할 수 없는 단일 job이므로, `discovery` → `reviewer`(×7) → `synthesis` → `report` 각 step이 병렬이 아니라 순차적으로 실행된다 — 엔진과 입력은 동일하지만, 활성화된 리뷰어가 많은 저장소에서는 더 느려진다. 위 reusable workflow가 여전히 기본 경로인 이유는 `docs/why-reusable-workflow.md`를 참조. 여기서의 배포 역시 skill과 마찬가지로 패키징일 뿐이다: `action.yml`은 reusable workflow가 사용하는 것과 동일한 `.github/actions/<x>@v2` 서브 action을 호출한다.
+
 ---
 
 ## 2. Reviewer 팀
@@ -216,6 +220,7 @@ report:
 
 ```
 repo-audit-action/                   # 로컬 디렉터리（발행명 Upkeep）
+├── action.yml                        # composite action（Marketplace 등재용）: `uses: wei18/upkeep@v2`, reviewer step 순차 실행
 ├── .github/
 │   ├── workflows/audit.yml          # 재사용 가능한 workflow（on: workflow_call）: jobs/matrix 편성
 │   └── actions/                     # composite 서브 action（workflow의 job uses에서 참조, Upkeep 코드 포함）

docs/ko/overview.md

@@ -8,7 +8,7 @@
 
 ## 파이프라인: fan-out → 종합 → 보고
 
-Upkeep에는 동일한 엔진을 공유하는 두 개의 진입점이 있습니다. CI용 재사용 가능한 `workflow_call` workflow와, 로컬에서 실행하는 Claude Code skill / plugin(또는 순수 스크립트)입니다. 어느 쪽이든 파이프라인은 동일한 다섯 단계입니다. Discovery, Consolidate, Report는 결정적(LLM 없음)이며, 병렬 reviewers와 Synthesis가 LLM 기반 단계입니다.
+Upkeep에는 동일한 엔진을 공유하는 세 가지 통합 경로가 있습니다. CI용 재사용 가능한 `workflow_call` workflow, 익숙한 step 문법을 선호하는 경우를 위한 Marketplace composite action(`- uses: wei18/upkeep@v2`, 동일한 엔진과 입력이지만 reviewer가 병렬이 아니라 차례로 실행됨), 그리고 로컬에서 실행하는 Claude Code skill / plugin(또는 순수 스크립트)입니다. 어느 쪽이든 파이프라인은 동일한 다섯 단계입니다. Discovery, Consolidate, Report는 결정적(LLM 없음)이며, 병렬 reviewers와 Synthesis가 LLM 기반 단계입니다.
 
 **1. 탐색(Discovery)**
 

docs/zh-CN/README.md

@@ -116,6 +116,43 @@ jobs:
 
 > 还在用 `@v1`？它仍可运行但已冻结——把 tag 换成 `@v2` 即可。接口完全相同。
 
+### 或作为 Marketplace action
+
+偏好熟悉的 `- uses:` step 语法，或想让 Upkeep 出现在
+[GitHub Marketplace](https://github.com/marketplace)？改用 **Upkeep Audit**
+action——同一套引擎、同样的输入参数，但审查器会依次执行，而非并行执行（原因见
+[`docs/why-reusable-workflow.md`](why-reusable-workflow.md)，说明为何上面的
+reusable workflow 才是主要路径）：
+
+```yaml
+name: repo audit
+on:
+  schedule:
+    - cron: '0 3 * * 1'   # weekly, Monday 03:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+  id-token: write
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: wei18/upkeep@v2
+        with:
+          model: claude-opus-4-8               # optional
+          issue_label: audit                    # optional; default: audit
+          rubric_lang: en                       # optional; reviewer language: en | zh-TW
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+```
+
+与上方相同的要求：一个名为 `CLAUDE_CODE_OAUTH_TOKEN` 的仓库 secret（通过
+`claude setup-token` 生成）以及 `permissions` 块，现在放在 job 本身上，因为
+step action 无法自行声明权限。
+
 ## 审查器
 
 | 名称 | 默认状态 | 检查内容 |