chore: sync fork with upstream (v2.5.5, #321–#429)

.agents/skills/prepare-pr/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: prepare-pr
+description: Prepare, create, or update a PokeTokenBar pull request with an English Conventional Commits title, the repository PR template, and mandatory images for visible UI changes. Use for requests such as "PR 올려줘", "PR 만들어줘", "PR 본문 작성", "PR 수정", "create PR", or "update PR" in this repository.
+---
+
+# Prepare a PokeTokenBar PR
+
+Use this repository's title and template rules even when a personal PR skill is
+also active. The shared instructions live here; Claude Code discovers them via
+`.claude/skills/prepare-pr`, and Codex via `.agents/skills/prepare-pr`.
+Run commands from the repository root. Paths below are relative to that root.
+
+## Title and body
+
+Read `CONTRIBUTING.md` and `.github/PULL_REQUEST_TEMPLATE.md` before preparing or
+updating the PR. Resolve the actual target repository and base branch, then read
+the complete `base...HEAD` diff and `base..HEAD` commit range. Do not summarize
+only the last commit or use unrelated work already on the branch as new work.
+
+Write the title and body in English. Use a Conventional Commits title such as
+`fix(home): retain idle usage history` or `docs: require UI images in PRs`.
+Choose a type and optional scope that describe the final change; do not copy a
+ticket prefix or a personal skill's title convention over repository rules.
+
+Start the body from the current template. Fill `Summary`, select the actual
+`Type of change`, and retain the template's checklist. Check an item only when
+the performed work supports it; leave tests unchecked if they were not run or
+added, and explain why when relevant. Report actual validation and limitations.
+Keep the body in a UTF-8 file and pass it with `gh ... --body-file`.
+
+## Mandatory UI images
+
+Decide whether the full diff changes visible UI. Inspect changes outside
+`Sources/PokeTokenBar/UI/` too: data, localization, resources, and settings can
+change what users see. A change inside that directory triggers the local image
+check; an outside change with visible effects needs `--ui-changes`. For changes
+inside the UI directory that have no visible effect (such as comments or an
+equivalent refactor), inspect the full diff and use `--no-ui-changes '<reason>'`.
+Never use this declaration to excuse missing images for a visible change.
+
+For every affected screen or state, embed images directly in `UI changes`:
+
+- Existing screens: before and after images of the relevant state.
+- New screens: explain that no previous screen exists and embed the new screen.
+- Removed screens: show the previous screen and the resulting replacement or
+  parent screen after removal.
+
+If images are not ready, create them yourself as part of preparing the PR.
+Reuse accurate existing images or capture the app; when capture is impractical,
+render the relevant UI locally or draw it based on the actual change. Inspect
+the result and attach it. Do not stop, ask the user to provide images, or request
+separate permission merely because no image already exists. An authorized PR
+creation/update includes producing and attaching its required UI images; a
+local title/body preparation request keeps the generated images local too.
+
+Actual app screenshots, local renders of production UI, and images drawn to
+illustrate the changed UI are all accepted. Label them `App screenshot`,
+`Sample-data render`, or `Illustration / mockup` as appropriate. Reuse existing
+images only if they accurately depict the relevant version and state. Show the
+change, not an unrelated app overview. Keep comparable data, language, theme,
+and dimensions where practical. Inspect the generated images before using them;
+an illustration demonstrates the design, not proof that the app was tested.
+
+Existing local render harnesses can help when the running app is difficult to
+capture. Create a temporary output directory, then use the relevant harness:
+
+```sh
+PTB_SCREENSHOT_DIR=<existing-dir> swift test --filter ScreenshotGenTests
+PTB_ZERO_USAGE_SCREENSHOT_DIR=<existing-dir> swift test --filter ZeroUsageHomeRenderingTests
+PTB_COLLECTION_SCREENSHOT_DIR=<existing-dir> swift test --filter CollectionReadabilityRenderingTests
+```
+
+Read the selected harness before using its output. Some AppKit controls and
+scroll views do not render faithfully in tests; capture the running app when
+those details are the change being demonstrated. Capture/render the base and
+head separately when no accurate before image exists; do not reset the user's
+working tree to obtain a before image. Do not regenerate release screenshots
+merely to prepare a PR.
+
+Use Markdown images such as `![After — sample-data render](https://...)` in the
+template's Before/After table, without code formatting or four-space indentation.
+Local paths and ordinary hyperlinks do not embed
+usable images on GitHub. Upload through GitHub's PR editor when available, or
+use an existing accessible image URL. If committing images is appropriate,
+use a GitHub raw URL at their exact pushed commit and inspect the images for
+private data and this repository's asset restrictions first. Do not publish
+images to an unrelated host or change global tools/settings for this task.
+
+Text alone never satisfies the UI requirement, including draft PRs. A missing
+image or failure of one capture/upload method is not a publication blocker:
+try the suitable available generation and attachment alternatives above.
+Keep publication pending only when a concrete failure (such as unavailable
+GitHub authentication, a network failure, or no usable attachment route) still
+prevents completion. Then report what was attempted, the remaining blocker,
+and the specific user action needed, retaining the prepared title/body/images.
+Do not remove `UI changes` to bypass missing images. Remove that section only
+when no visible UI changes exist.
+
+## Check and publish
+
+Run the shared local checker against the chosen base ref and the body file:
+
+```sh
+python3 scripts/check-pr.py --base <base-ref> --title '<title>' --body-file <body-file>
+```
+
+Add `--ui-changes` for visible changes outside the UI directory. Use `--head`
+when checking a revision other than `HEAD`. Fix all reported failures before
+publishing. The checker verifies structure and image URL syntax; additionally
+verify that each URL displays the intended image on GitHub, that all affected
+states are covered, and that the English wording and checked claims are true.
+It does not build/test the app or prove that a remote image exists.
+
+Publish only when the user's request authorizes PR creation/update. A request
+to prepare a title/body authorizes local preparation only. Use `gh pr create`
+or `gh pr edit` with the checked title and body file; preserve unrelated existing
+PR metadata. Never force-push to make the workflow succeed. If push succeeds
+but PR publication fails, report the pushed branch and missing/unchanged PR.
+After publication, read back the title and body and inspect the image rendering
+on GitHub. In Codex, attach a created or updated PR using the app's PR attachment
+tool when available; Claude Code returns its URL. Report actual completion and
+any unresolved limitation.

.claude/skills/prepare-pr

@@ -0,0 +1 @@
+../../.agents/skills/prepare-pr

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,4 +1,4 @@
-<!-- Write the PR title and this description in English (see CONTRIBUTING.md). -->
+<!-- Use an English Conventional Commits title, e.g. fix(home): retain idle usage history. Write this description in English (see CONTRIBUTING.md). -->
 
 ## Summary
 
@@ -15,11 +15,20 @@
 ## UI changes
 
 <!--
-When this PR changes anything under `Sources/PokeTokenBar/UI/`, describe the
-before/after below. Images (screenshots or GIFs) are welcome but optional — a
-clear text description is fine. The canonical app screenshots in `assets/` are
-regenerated at release, so they don't need updating per PR. Remove this section
-only if there are no UI changes.
+Every visible UI change requires embedded images here, including changes caused
+outside `Sources/PokeTokenBar/UI/`. Use actual screenshots, local renders of the
+production UI, or clearly labeled illustrations of the changed UI. Label renders
+using sample data and illustrations explicitly. Existing images are acceptable
+only when they show the relevant version and state.
+Include before/after images for an existing screen. For a new screen, explain
+that no previous screen exists and include its image. Text alone is insufficient.
+If images are missing, generate and attach them; coding agents do this as part
+of the authorized PR work. Try suitable capture/render/illustration and upload
+alternatives before keeping publication pending for a concrete remaining blocker.
+Use image URLs that
+render on GitHub, not local file paths. The canonical app screenshots in `assets/`
+are regenerated at release, so they don't need updating per PR. Remove this
+section only if there is no visible UI change.
 -->
 
 | Before | After |
@@ -29,7 +38,7 @@ only if there are no UI changes.
 ## Checklist
 
 - [ ] `swift build` and `swift test` pass locally
-- [ ] PR title and description are written in English
-- [ ] UI changes are described above (before/after — images optional)
+- [ ] PR title follows Conventional Commits and title/description are written in English
+- [ ] UI changes include embedded images (before/after for existing screens; image of a new screen), or there is no visible UI change
 - [ ] No copyrighted assets, secrets, or private tooling references are committed (see [CONTRIBUTING](../CONTRIBUTING.md))
 - [ ] Tests were added or updated for this change

.gitignore

@@ -30,7 +30,10 @@ docs/*
 !docs/reference/
 
 # Agent worktrees / local state
-.claude/
+.claude/*
+!.claude/skills/
+.claude/skills/*
+!.claude/skills/prepare-pr
 .worktrees/
 
 # Local-only review-gate opt-out (not published)

AGENTS.md

@@ -4,7 +4,11 @@ Read `CLAUDE.md` for the repository's contribution, testing, and release instruc
 
 ## Pull requests
 
-Before creating or updating a PR, read `.github/PULL_REQUEST_TEMPLATE.md` and use its sections and checklist in the description. Fill in the type of change and the actual validation results. For UI changes, include the before/after comparison; remove the UI section only when there are no UI changes. Mark checklist items complete only when supported by the work performed. Keep the PR title and description in English.
+When creating, preparing, or updating a PR, use `.agents/skills/prepare-pr/SKILL.md`. This repository's rules take precedence over a personal PR skill's default title or body format.
+
+Use an English Conventional Commits title and fill out `.github/PULL_REQUEST_TEMPLATE.md` with the actual changes and validation results. Mark checklist items complete only when supported by the work performed.
+
+Every PR with a visible UI change must embed images in `UI changes`: actual screenshots, local renders of the production UI, or clearly labeled illustrations of the changed UI are accepted. Include before/after images for an existing screen; for a new screen, explain that no previous screen exists and include its image. Text alone does not satisfy this requirement. If images are missing, the agent must produce and attach them as part of the authorized PR work without asking the user to supply them. Try suitable generation and attachment alternatives before declaring a blocker. Keep publication pending only when a concrete failure still prevents completion, and report the attempted methods and required user action. Remove `UI changes` only when there is no visible UI change.
 
 ## Pull Requests and Remotes
 - **Always target the forked repository (`cte13/PokeTokenBar-iOS`) for pull requests.**

CLAUDE.md

@@ -45,6 +45,22 @@
 - **커밋 메시지도 영어 기본.** 스쿼시 전 브랜치 커밋 목록도 PR 리뷰어에게 노출되므로 영어로 쓴다.
 - 범위 밖(추후): 코드 주석·이 `CLAUDE.md` 본문의 영어 전환. README/랜딩은 이미 en/ko/ja 다국어 유지.
 
+## PR 작성
+
+PR 생성·준비·갱신 시 `.agents/skills/prepare-pr/SKILL.md`를 사용한다. 개인 PR skill의
+기본 양식보다 이 저장소 규칙이 우선이다. 제목은 영어 Conventional Commits 형식으로,
+본문은 `.github/PULL_REQUEST_TEMPLATE.md`의 섹션·체크리스트에 맞춰 작성한다.
+
+화면이 달라지는 PR은 `UI changes`에 **이미지를 반드시 삽입**한다. 실제 스크린샷,
+프로덕션 UI의 로컬 렌더링, 변경 UI를 그린 이미지 모두 허용한다. 샘플 데이터 렌더링과
+일러스트는 그 사실을 명시한다. 기존 화면은 전후 이미지, 신규 화면은 이전 화면이 없다는
+설명과 신규 이미지가 필요하다. 텍스트만으로 대체하지 않는다. 이미지가 없으면 에이전트가
+직접 캡처·렌더링·그리기로 만들고 첨부한다. 이미지 미준비만으로 사용자에게 요청하거나
+PR을 보류하지 않는다. 적절한 생성·첨부 대안을 시도한 뒤에도 인증·네트워크·도구 문제로
+완료할 수 없을 때만 시도 결과와 필요한 사용자 조치를 알리고 게시를 보류한다.
+Claude Code는 `.claude/skills/prepare-pr`의 symlink를 통해
+동일한 skill을 인식하고, Codex는 `.agents/skills/prepare-pr`를 사용한다.
+
 ## 릴리스 (자연어 트리거)
 
 사용자가 **버전 배포를 자연어로 요청**하면 — 예: "배포해줘", "릴리스 올려줘", "패치 배포",

CONTRIBUTING.ja.md

@@ -19,12 +19,14 @@
 本プロジェクトは Swift Package です。リポジトリのルートから:
 
 ```bash
-swift build      # アプリターゲットをコンパイル
-swift test       # 全テストスイートを実行
+swift build             # アプリターゲットをコンパイル
+./scripts/test-gate.sh   # 全テストを実行し、ロジックコアのカバレッジを検証
 ```
 
-CI はすべてのプルリクエストで `swift build` と `swift test` を実行します。まず
-ローカルで両方が通ることを確認してください。
+CI もすべてのプルリクエストで同じコマンドを実行します。テストゲートは
+`swift test --enable-code-coverage` を実行し、デフォルトでロジックコアの行カバレッジ
+75% 以上を要求します。PR を提出する前に、ローカルで両方を実行してください。
+開発中に特定のテストだけを確認する場合は `swift test --filter <TestCase>` を使ってください。
 
 ## 貢献ワークフロー
 
@@ -47,11 +49,21 @@ CI はすべてのプルリクエストで `swift build` と `swift test` を実
 
 - [Conventional Commits](https://www.conventionalcommits.org/) スタイルを使用:
   `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:` など。
-- プルリクエストテンプレートを記入してください。
-- **UI の変更**（`Sources/PokeTokenBar/UI/` 配下のすべて）は、PR で before/after を
-  説明してください。スクリーンショットや GIF は歓迎ですが任意です — 明確なテキスト説明で
-  十分です。正式な `assets/` スクリーンショットは PR ごとではなくリリース時に
+- 英語の PR タイトル（例: `fix(home): retain idle usage history`）を使い、テンプレートの
+  該当するセクションとチェックリストを記入してください。
+- **画面が変わるすべての PR** は `UI changes` に画像を埋め込む必要があります。
+  UI ディレクトリ外に起因する変更も対象です。実際のスクリーンショット、本番 UI の
+  ローカルレンダリング、変更した UI のイラストを使用できます。サンプルデータの
+  レンダリングとイラストはその旨を明記してください。既存画面には変更前後の画像、
+  新規画面には画像と以前の画面がない旨の説明が必要です。テキストだけでは代用できません。
+  画像がない場合、コーディングエージェントは許可された PR 作業の一環として生成・添付します。
+  適切な生成・添付の代替手段を試し、それでも具体的な障害で完了できない場合に限り公開を
+  保留してください。正式な `assets/` スクリーンショットは PR ごとではなくリリース時に
   再生成されます。
+- コーディングエージェントは `.agents/skills/prepare-pr/` の共通 skill を使用します。
+  `.claude/skills/prepare-pr` も同じ skill を参照します。公開前のローカルチェック:
+  `python3 scripts/check-pr.py --base origin/main --title 'docs: clarify PR requirements' --body-file /tmp/pr-body.md`。
+  UI ディレクトリ外の画面変更には `--ui-changes` を追加してください。
 
 ## コード規約
 
@@ -61,8 +73,11 @@ CI はすべてのプルリクエストで `swift build` と `swift test` を実
 - **使用量ソースの追加**（新しい AI CLI）= `UsageProvider` プロトコル
   (`Sources/PokeTokenBar/Core/UsageProvider.swift`) を新しい型ひとつで実装し、
   `UsageStore.init` のデフォルト `providers:` 配列
-  (`Sources/PokeTokenBar/Core/UsageStore.swift`) に登録します。触れる必要があるのは
-  この2箇所だけです。
+  (`Sources/PokeTokenBar/Core/UsageStore.swift`) に登録します。この2箇所は基本の追加先であり、
+  変更が2ファイルに限定されるわけではありません。ソースに応じて、リーダー、共有キャッシュとの連携、
+  カスタムスキャンパス、テストも追加・更新してください。
+  [プロバイダー拡張ガイド](docs/reference/provider-extension.md)と
+  [プロバイダー貢献チェックリスト](https://github.com/chattymin/PokeTokenBar/issues/115)に従ってください。
 - **汎用的な動作はすべてのプロバイダーにわたって集計する必要があります**（今日/週/月の
   合計、消費ペースの段階、コンパニオンのリズム）。汎用的な計算を特定のプロバイダーに結び付けたり、
   汎用パスに `providerID == "..."` のリテラル分岐を追加したりしないでください。