Docs: README for every AI tool, MCP usage, new commands; changelog 0.2.0

This commit is contained in:
CRTkafa 2026-10-10 21:03:10 +08:00
parent e0a284d678
commit 2a183d984c
2 changed files with 146 additions and 23 deletions

View file

@ -1,5 +1,30 @@
# Changelog # Changelog
## 0.2.0 · 2026-10-10
Works with any AI coding tool now, plus the release and review side of shipping.
- **One source, many tools**: skills stay plain Agent Skills (`name` + `description` only); `tools/gen-adapters.ts`
writes the Claude Code plugin + `.mcp.json`, Codex plugin, Gemini CLI extension + `GEMINI.md`, `AGENTS.md`,
`.github/copilot-instructions.md` and a Cursor rule. CI fails when they are stale. Shared agent rules in
`docs/agents-core.md`.
- **`storebound mcp`**: stdio MCP server (2025-11-25), one tool per command, write tools dry run by default, nothing
public or irreversible exposed. No SDK, still zero runtime dependencies.
- **`storebound install --agent claude|codex|cursor|copilot|windsurf|gemini|opencode`**: skills + MCP entry into a
game project, idempotent, never touches other entries, `--dry`.
- New commands: `validate` (read-only readiness report for both stores, ordered blockers, exit 1),
`apple release --phased on|pause|resume|complete` and `--manual-release`, `apple status --wait-review`
(exit 0 / 1 / 7), `apple next-build`, `apple encryption`, `play rollout --fraction|--halt|--resume|--complete`,
`play next-version-code`, `check --aso`, `whats-new --since <tag>`, `privacy-manifest --ios <path>`, `version`.
- New skills: review-rejections, portfolio-originality, release-management, store-preflight, privacy-manifest,
export-compliance, aso-basics, whats-new.
- Updated skills: select builds by explicit number, first availability record UI fallback, phased + manual release
by default, IAP versions in review submissions (API 4.4.1, reported, verify), privacy manifest cross-links, tool-neutral
CLI instructions.
- Fix: Apple IAP description limit is 45 characters (App Store Connect Help), not 55.
- Config: `apple.usesNonExemptEncryption`, `apple.screenshotTypes`, `ads.appAdsTxt`.
- `bun run ci`: adapters check, tests, typecheck, secrets / personal data scrub.
## 0.1.0 · 2026-10-10 ## 0.1.0 · 2026-10-10
First public cut, extracted from the scripts I used to ship my own game. First public cut, extracted from the scripts I used to ship my own game.

144
README.md
View file

@ -6,30 +6,31 @@ the "first IAP must ship with a version" dance, data safety CSVs that silently n
each fix down as code or as a checklist. It works for me, so I open-sourced it. Friends, use it too. each fix down as code or as a checklist. It works for me, so I open-sourced it. Friends, use it too.
It is not a product. No dashboard, no account, no telemetry. A small Bun CLI that talks to the official store APIs, It is not a product. No dashboard, no account, no telemetry. A small Bun CLI that talks to the official store APIs,
plus Claude Code skills that walk you (or Claude) through the parts that are still clicks in a web console. plus Agent Skills that walk you (or your AI coding tool, whichever it is) through the parts that are still clicks in a
web console, and an MCP server so agents can call the CLI safely.
· CRTkafa · CRTkafa
## What is in the box ## What is in the box
- **`storebound` CLI** (Bun + TypeScript, zero runtime dependencies): store listings, in-app products with regional - **`storebound` CLI** (Bun + TypeScript, zero runtime dependencies): store listings, in-app products with regional
prices, Play Data safety, AAB releases, App Store versions / screenshots / age rating / review details, icons from prices, Play Data safety, AAB releases and staged rollouts, App Store versions / screenshots / age rating / review
one artwork, and a screenshot renderer (captioned scenes, device frames, 14+ languages incl. RTL and CJK). details / phased release / export compliance, readiness reports for both stores, release notes from git, ASO and
- **Claude Code skills**: ordered steps for each job, which steps are API and which are UI-only (with the exact privacy manifest checks, icons from one artwork, and a screenshot renderer (captioned scenes, device frames, 14+
console navigation), the gotchas, and how to verify. languages incl. RTL and CJK).
- **Agent Skills** (`skills/<name>/SKILL.md`, the open format Claude Code, Codex, Gemini CLI, Cursor, Copilot,
Windsurf, OpenCode and others read): ordered steps for each job, which steps are API and which are UI-only (with the
exact console navigation), the gotchas, and how to verify.
- **MCP server** (`storebound mcp`): the CLI as tools for any MCP-capable AI tool, dry run by default.
- **Templates**: config, listing copy, screenshot copy, Data safety CSV, App Privacy answers, Play declarations, - **Templates**: config, listing copy, screenshot copy, Data safety CSV, App Privacy answers, Play declarations,
a studio-wide privacy policy page. a studio-wide privacy policy page.
It is not tied to one AI tool. The skills are plain Markdown, the CLI is a normal command, and one generator
(`tools/gen-adapters.ts`) writes the small adapter files each tool wants from the same sources.
## Install ## Install
As a Claude Code plugin (skills + the `storebound` command on Claude's PATH): The CLI in your game repo (needs [Bun](https://bun.sh) 1.1+):
```
/plugin marketplace add https://git.crt.fyi/CRT/storebound.git
/plugin install storebound@crtkafa
```
As a CLI in your game repo (needs [Bun](https://bun.sh) 1.1+):
```sh ```sh
bun add -d git+https://git.crt.fyi/CRT/storebound.git bun add -d git+https://git.crt.fyi/CRT/storebound.git
@ -39,18 +40,59 @@ bunx storebound help
Extra tools some commands use: `ffmpeg` (icons, screenshots), `cwebp` (optional), `playwright` in your project for Extra tools some commands use: `ffmpeg` (icons, screenshots), `cwebp` (optional), `playwright` in your project for
screenshots (`bun add -d playwright`; it uses Playwright's Chromium or your installed Chrome). screenshots (`bun add -d playwright`; it uses Playwright's Chromium or your installed Chrome).
### Your AI tool
Pick yours. Every route gives the agent the same skills and the same MCP tools.
| tool | install |
|---|---|
| Claude Code | `/plugin marketplace add https://git.crt.fyi/CRT/storebound.git` then `/plugin install storebound@crtkafa` (skills, MCP server, `storebound` on PATH). Or per project: `bunx storebound install --agent claude` |
| OpenAI Codex | `bunx storebound install --agent codex` (skills in `.agents/skills`, MCP in `.codex/config.toml`; Codex reads that file for trusted projects). The repo is also a Codex plugin (`.codex-plugin/plugin.json`, skills only) |
| Gemini CLI | `gemini extensions install https://git.crt.fyi/CRT/storebound.git` (skills, MCP server, `GEMINI.md`). Or `bunx storebound install --agent gemini` |
| Cursor | `bunx storebound install --agent cursor` (skills in `.agents/skills`, `.cursor/mcp.json`); the repo's `.cursor/rules/storebound.mdc` is an agent-requested rule you can copy |
| VS Code / GitHub Copilot | `bunx storebound install --agent copilot` (skills in `.github/skills`, `.vscode/mcp.json`) |
| Windsurf (Devin Desktop) | `bunx storebound install --agent windsurf` (skills in `.agents/skills`, MCP in your global `mcp_config.json`) |
| OpenCode | `bunx storebound install --agent opencode` (skills in `.opencode/skills`, `opencode.json`) |
| anything that reads `AGENTS.md` | copy or link `AGENTS.md` (rules + skill index) and use the CLI |
`install` takes several agents at once (`--agent codex,cursor`), `--dry` to preview, `--no-skills` / `--no-mcp`,
and `--command "<cmd>"` to choose how the MCP server starts. It only adds or updates the `storebound` entry and our own
skill folders; everything else in those files stays as it is, and re-running it is safe.
## MCP server
`storebound mcp` speaks MCP over stdio (spec revision 2025-11-25; tools only). It runs each tool as a CLI call in the
project directory (the server's working directory, or `STOREBOUND_PROJECT`) and returns the output.
- One tool per command: `check`, `check_aso`, `validate`, `apple_status`, `apple_next_build`, `play_status`,
`play_next_version_code`, `privacy_manifest` (read-only), and `whats_new`, `play_listing`, `play_images`,
`play_products`, `play_data_safety`, `play_release_testing`, `apple_bundle`, `apple_iap`, `apple_iap_review`,
`apple_listing`, `apple_screenshots`, `apple_appinfo`, `apple_review_details`, `apple_encryption`,
`apple_phased_release`, `icons` (write).
- Every write tool has `dry_run`, **default true**. Annotations say what is read-only, destructive (replaces data),
idempotent and network-bound.
- **Not exposed, on purpose**: submitting for review, releasing a version, production releases, resuming or completing
a rollout or phased release, canceling a submission, deleting anything. Those stay terminal commands that ask for
confirmation (`apple release --manual-release`, `play rollout`, `apple status --cancel-submission`).
- No MCP SDK: the server is ~150 lines of newline-delimited JSON-RPC (initialize, ping, tools/list, tools/call,
cancellation), so storebound keeps zero runtime dependencies.
Manual config for a tool that `install` does not know: command `bunx` with args `["storebound", "mcp"]` (or the
absolute path of `bin/storebound` plus `mcp`).
## Quick start ## Quick start
```sh ```sh
bunx storebound init # storebound.config.ts, store/*.md, store/shots/copy.json, privacy policy, .storebound/ (gitignored) bunx storebound init # storebound.config.ts, store/*.md, store/shots/copy.json, privacy policy, .storebound/ (gitignored)
# edit storebound.config.ts and the store/ files # edit storebound.config.ts and the store/ files
bunx storebound check # offline: config, copy limits, data safety, files bunx storebound check # offline: config, copy limits, data safety, files
bunx storebound validate # read-only: what still blocks a submission on each store, in fix order
bunx storebound play listing --dry bunx storebound play listing --dry
bunx storebound apple iap --dry bunx storebound apple iap --dry
``` ```
Or just ask Claude: "ship my game to Google Play" / "set up the in-app purchases on both stores" / "make store Or just ask your agent: "ship my game to Google Play" / "set up the in-app purchases on both stores" / "make store
screenshots in 5 languages", and the matching skill kicks in. screenshots in 5 languages" / "why was my update rejected", and the matching skill kicks in.
## Credentials (never in the repo) ## Credentials (never in the repo)
@ -71,21 +113,33 @@ can run in the background with a log (`storebound play images > .storebound/imag
| command | API / local | what | | command | API / local | what |
|---|---|---| |---|---|---|
| `init` | local | copy the templates, gitignore `.storebound/` | | `init` | local | copy the templates, gitignore `.storebound/` |
| `check` | local | validate config, copy limits, data safety, products, files | | `install --agent <tool>` | local | skills + MCP entry for an AI tool (see above) |
| `mcp` | local | stdio MCP server wrapping the commands |
| `check` | local | validate config, copy limits, data safety, products, files; warns on untranslated release notes |
| `check --aso` | local | keyword audit: App Store keyword field rules, Play stuffing / claims (exit 1 on errors) |
| `validate [--apple] [--play]` | API, read-only | readiness report with ordered blockers; exit 1 while any blocker is left |
| `whats-new [--since <tag>]` | local | draft player-facing release notes from git log into both listing files |
| `privacy-manifest --ios <path>` | local | PrivacyInfo.xcprivacy, required-reason APIs, SDKs without manifests |
| `play products` | API | one-time products via `monetization.onetimeproducts`: regional prices from `convertRegionPrices` + your overrides, activate | | `play products` | API | one-time products via `monetization.onetimeproducts`: regional prices from `convertRegionPrices` + your overrides, activate |
| `play listing` | API | app details + title / short / full description per language | | `play listing` | API | app details + title / short / full description per language |
| `play images` | API | icon, feature graphic, phone / 7" / 10" screenshots, one edit per language | | `play images` | API | icon, feature graphic, phone / 7" / 10" screenshots, one edit per language |
| `play data-safety` | API | Data safety form (CSV import); `--csv` to write the file | | `play data-safety` | API | Data safety form (CSV import); `--csv` to write the file |
| `play release <aab>` | API | upload + tracks (`--internal completed --production draft`), release notes from the listing | | `play release <aab>` | API | upload + tracks (`--internal completed --production draft`, `--production inProgress --fraction 0.05`), release notes from the listing |
| `play rollout` | API | `--fraction x`, `--halt`, `--resume`, `--complete` on a staged rollout (asks first, except halt) |
| `play next-version-code` | API, read-only | next free versionCode (prints just the number) |
| `play status` | API | tracks, listings, products | | `play status` | API | tracks, listings, products |
| `apple bundle` | API | register the bundle id, find the app record | | `apple bundle` | API | register the bundle id, find the app record |
| `apple iap` | API | IAPs, localizations, price schedules (USA base + overrides), availability | | `apple iap` | API | IAPs, localizations, price schedules (USA base + overrides), availability |
| `apple iap-review` | API | IAP review screenshots + states | | `apple iap-review` | API | IAP review screenshots + states |
| `apple listing --version x.y.z [--build N]` | API | version, build, name / subtitle / description / keywords / promo per locale | | `apple listing --version x.y.z [--build N]` | API | version (manual release), the build with exactly that number, name / subtitle / description / keywords / promo per locale |
| `apple screenshots` | API | 6.9" + 6.5" screenshots per locale (MD5-idempotent) | | `apple screenshots` | API | 6.9" + 6.5" screenshots per locale (MD5-idempotent) |
| `apple appinfo` | API | categories, age rating, content rights, Free, all territories | | `apple appinfo` | API | categories, age rating, content rights, Free, all territories |
| `apple review-details` | API | App Review contact + notes | | `apple review-details` | API | App Review contact + notes |
| `apple status` | API | versions, builds, IAPs, review submissions (`--cancel-submission <id>`) | | `apple encryption` | API | export compliance answer for builds, from `apple.usesNonExemptEncryption` (never guessed) |
| `apple release --phased on\|pause\|resume\|complete` | API | phased release (resume / complete ask first) |
| `apple release --manual-release` | API | release an approved version (asks first) |
| `apple next-build` | API, read-only | next safe build number (prints just the number) |
| `apple status` | API | versions, builds, IAPs, review submissions; `--wait-review` (exit 0 approved, 1 rejected, 7 timeout); `--cancel-submission <id>` |
| `icons` | local | App Store 1024 (no alpha), Play 512, web, Capacitor sources, Android legacy launcher icons | | `icons` | local | App Store 1024 (no alpha), Play 512, web, Capacitor sources, Android legacy launcher icons |
| `shots capture` | local | raw frames from your running game | | `shots capture` | local | raw frames from your running game |
| `shots fonts` | local | font subsets for your copy (Noto for CJK / Arabic / Cyrillic / Devanagari ...) | | `shots fonts` | local | font subsets for your copy (Noto for CJK / Arabic / Cyrillic / Devanagari ...) |
@ -100,9 +154,11 @@ Scripted: almost everything listed above. Still clicks (the skills give the exac
declarations (privacy policy, ads, IARC content rating, target audience, advertising ID, sign-in details, declarations (privacy policy, ads, IARC content rating, target audience, advertising ID, sign-in details,
government / financial / health), countries for production, and **Send for review** on a draft app's first release. government / financial / health), countries for production, and **Send for review** on a draft app's first release.
- **App Store**: creating the app record, App Privacy labels (+ Publish), TestFlight group setup, adding first IAPs to - **App Store**: creating the app record, App Privacy labels (+ Publish), TestFlight group setup, adding first IAPs to
the submission ("Add for Review" on the IAP page), and **Submit for Review**. the submission ("Add for Review" on the IAP page), encryption declarations when the answer is "yes", sometimes the
very first availability record, and **Submit for Review**.
Public or irreversible steps are left to you on purpose. The skills tell Claude to ask before any of them. Public or irreversible steps are left to you on purpose. The skills tell every agent to ask before any of them
(`docs/agents-core.md`), and the MCP server does not offer them.
## Skills ## Skills
@ -110,21 +166,63 @@ Public or irreversible steps are left to you on purpose. The skills tell Claude
|---|---| |---|---|
| `play-first-release` | Google Play from zero to "In review" | | `play-first-release` | Google Play from zero to "In review" |
| `appstore-first-release` | App Store from API key to "Waiting for review", incl. xcodebuild with the API key | | `appstore-first-release` | App Store from API key to "Waiting for review", incl. xcodebuild with the API key |
| `release-management` | updates: Apple phased + manual release, Play staged rollout, halt / pause (not a rollback), review wait |
| `store-preflight` | run and read `check`, `check --aso`, `validate`, `privacy-manifest` before submitting |
| `review-rejections` | triage a rejection (fix / clarify / push back / appeal), reply template, the guidelines games hit |
| `portfolio-originality` | Guideline 4.3 gate for studios shipping many similar games |
| `store-iap-setup` | in-app products on both stores, prices, testers, the first-IAP-with-version rule | | `store-iap-setup` | in-app products on both stores, prices, testers, the first-IAP-with-version rule |
| `store-screenshots` | capture, copy, fonts, render, upload | | `store-screenshots` | capture, copy, fonts, render, upload |
| `app-icons` | one artwork to every icon, adaptive / legacy launcher pitfalls | | `app-icons` | one artwork to every icon, adaptive / legacy launcher pitfalls |
| `store-declarations` | Data safety, App Privacy, IARC, target audience, ads / advertising ID | | `store-declarations` | Data safety, App Privacy, IARC, target audience, ads / advertising ID |
| `export-compliance` | encryption answer, Info.plist key, declarations; never exempt by default |
| `privacy-manifest` | PrivacyInfo.xcprivacy, required-reason APIs, SDK manifests (ITMS-91053 / 91061) |
| `privacy-policy` | one studio-wide policy page with a per-game services table | | `privacy-policy` | one studio-wide policy page with a per-game services table |
| `aso-basics` | keyword field, subtitle, cross-localization, Play placement without stuffing |
| `whats-new` | player-facing release notes from git, localized, within store limits |
| `ads-levelplay-checks` | LevelPlay / Unity Ads ids, adapters, app-ads.txt, SKAdNetwork, no-fill | | `ads-levelplay-checks` | LevelPlay / Unity Ads ids, adapters, app-ads.txt, SKAdNetwork, no-fill |
## Agent support: formats and what is not verified
Checked against each tool's own docs in October 2026:
- **Agent Skills**: frontmatter is only `name` (lowercase-hyphen, equals the folder) and `description`; the generator
fails if a skill adds anything else.
- **Claude Code**: plugin manifest + root `.mcp.json` with `${CLAUDE_PLUGIN_ROOT}`; `claude plugin validate .` passes.
- **Codex**: `.codex-plugin/plugin.json` with `"skills": "./skills/"` (Codex's scaffold format). Not verified: whether
Codex starts the root `.mcp.json` from a plugin and expands `${CLAUDE_PLUGIN_ROOT}` there, so use
`install --agent codex` for the MCP server. OpenAI also documents a newer portable root `plugin.json`; not shipped yet.
- **Gemini CLI**: `gemini-extension.json` with `${extensionPath}${/}`, `GEMINI.md` as context, `skills/` inside the
extension. Google now points unpaid users to Antigravity CLI; not tested there. The `.gemini/skills` folder used by
`install --agent gemini` is not verified (the extension route is).
- **Windsurf**: the current docs name `~/.config/devin/mcp_config.json`; `install` keeps using
`~/.codeium/windsurf/mcp_config.json` when that file already exists (older installs).
- **MCP**: built for 2025-11-25 (also answers clients asking for 2025-06-18 / 2025-03-26 / 2024-11-05). The newer
stateless 2026-07-28 revision (`server/discover`, per-request `_meta`) is not implemented yet; clients that speak
both still work with a 2025-11-25 server.
- **Apple IAP description**: 45 characters (App Store Connect Help, "In-app purchase information"); an older App Store
marketing page says 55. storebound checks 45.
## Develop ## Develop
```sh ```sh
bun install bun install
bun test # pure parts: config validation, copy parsing, CSV, prices, fonts, args bun run ci # adapters fresh (gen-adapters --check), tests, typecheck, secrets / personal data scrub
bun run typecheck bun tools/gen-adapters.ts # after editing skills/*/SKILL.md or docs/agents-core.md
``` ```
`skills/*/SKILL.md` and `docs/agents-core.md` are the single source; `AGENTS.md`, `GEMINI.md`, the plugin manifests,
`.github/copilot-instructions.md` and `.cursor/rules/storebound.mdc` are generated and committed, and CI fails when
they are stale.
## Thanks / idea sources
Some of the new skills were sparked by other people's open work. I wrote my own text; the ideas deserve the credit:
- [rorkai/app-store-connect-cli-skills](https://github.com/rorkai/app-store-connect-cli-skills) (MIT): App Store Connect
workflow ideas.
- [rshankras/claude-code-apple-skills](https://github.com/rshankras/claude-code-apple-skills) (MIT): Apple platform and
App Store topic ideas.
## Credits ## Credits
Built with Bun and plain `fetch` against the Google Play Developer API v3 and the App Store Connect API. Screenshot Built with Bun and plain `fetch` against the Google Play Developer API v3 and the App Store Connect API. Screenshot