t1k:marketing:store:asc-setup
| Field | Value |
|---|---|
| Module | store |
| Version | 0.14.9 |
| Effort | high |
| Tools | — |
How to invoke
Section titled “How to invoke”/t1k:marketing:store:asc-setupSet Up Store — Auto
Section titled “Set Up Store — Auto”Every The1Studio title shares the same store setup except for its name, its bundle ID, and its ASO copy. This skill holds the shared part once and takes a small per-game file for the rest.
A per-game file is about 12 lines. Everything else is inherited.
Executed by
Section titled “Executed by”Per-game values (name, bundle ID, ASO copy) and the decision to commit are judgment and stay on
a reasoning tier (routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”).
Only the read-only runs of scripts/store-auto.cjs / scripts/asc-engine.cjs are cheap-tier:
| Step | Agent |
|---|---|
Run store-auto.cjs resolve --config <file> and report the merged base + per-game config | t1k-fact-fetcher — a local merge with no network call; the work is running the script and relaying its output |
Run asc-engine.cjs store --manifest <file> --emit-diff and report the diff (legacy --config: store-auto.cjs run WITHOUT --confirm) | t1k-metrics-reporter — preview only, it writes nothing to App Store Connect |
Stays reasoning-tier: writing the per-game file, every --confirm run (it edits a live App Store
Connect app), the ATT/App Privacy checklist, and the manual Console-only steps.
What is BASE vs PER-GAME
Section titled “What is BASE vs PER-GAME”Base — templates/studio-base.json | Per-game — your file |
|---|---|
copyright {{YEAR}} TheOneGameStudio | app name |
| support / marketing / privacy / privacy-choices URLs | bundle ID, SKU |
releaseType: AFTER_APPROVAL | subtitle, keywords |
contentRights: DOES_NOT_USE_THIRD_PARTY_CONTENT | description, promo text |
primaryCategory: GAMES (+ simulation/casual) | subcategories, if different |
| age rating — 25 fields, resolves to 4+ | screenshots |
| App Privacy — 6 data types | version string |
| App Review contact — name, phone, email | demo account, if the title has one |
{{YEAR}} is substituted at run time, so the copyright never goes stale.
Anything in the per-game file overrides the base; a deep merge, so you override
one subcategory without restating the block.
Prerequisite — credentials
Section titled “Prerequisite — credentials”App Store Connect → Users and Access → Integrations → Team Keys. Role App
Manager or higher; a Developer-role key cannot see the app and returns an
empty filter[bundleId] rather than a 403.
| Env var | Value |
|---|---|
ASC_ISSUER_ID | UUID at the top of the Integrations page |
ASC_KEY_ID | 10-char id on the key’s row |
ASC_PRIVATE_KEY | absolute path to AuthKey_XXXXXXXXXX.p8 |
The .p8 downloads exactly once. Store it mode 600, outside any git repo.
Workflow for a new app
Section titled “Workflow for a new app”The path with an approval is the manifest path: one store-manifest/1 file per app
(t1k-marketing-store-manifest), ONE engine entry, one diff, one hash.
set -a; source ~/.config/t1k/ads.env; set +a
# 1. read-only: print the plan. stdout is exactly ONE store-diff/1 JSON document, logs go to stderrbun <skill>/scripts/asc-engine.cjs store --manifest stores/mygame/store-manifest.json --emit-diff > asc.diff.jsonjq -r .stateFingerprint,.requestsSha256 asc.diff.json # what was looked at, what would be sent
# 2. a human approves the diff (the gate skill does this). storeDiffHash = sha256 of that one canonical line:HASH=$(tr -d '\n' < asc.diff.json | sha256sum | cut -d' ' -f1)bun <skill>/scripts/asc-engine.cjs store --manifest stores/mygame/store-manifest.json --confirm --expect-diff-hash "$HASH"store is the ONLY command in manifest mode. In order it: creates the version if the manifest’s
stores.asc.versionString has none, pushes listings, settings (categories, age rating, copyright,
releaseType, contentRights, URLs), App Review details and screenshots. It reads ALL before-state first
(GET only; the read phase is enforced GET-only at run time), prints path: before -> after per
change, and returns before any write when --confirm is absent. With --confirm it recomputes the
diff, requires its hash to equal --expect-diff-hash (otherwise exit 3, nothing written) and then
sends the very request list the hash covers. It prints one store-applied/1 document on stdout
(applied = the ops completed; the ASC apply is not atomic, a stop leaves a prefix and exits 1).
| Exit | Meaning |
|---|---|
| 0 | ok (a preview and --emit-diff too) |
| 1 | error: any API error (including an empty-bodied 5xx), an ambiguous or non-editable target, a mid-run 409 |
| 2 | usage or policy: an old subcommand, --config, any flag outside --manifest --emit-diff --confirm --expect-diff-hash --help --quiet --verbose, --confirm without --expect-diff-hash, bundleid/clone |
| 3 | --expect-diff-hash does not match what the store looks like now: re-plan |
Under --manifest the old subcommands (apply, screenshots, reviewdetails, plan, run) exit 2
(“use store”). bundleid and clone are not gate-enabled: they exit 2 under --manifest and
only run with --config, where a bare --confirm still works and is announced as ungated.
store-auto.cjs resolve --manifest <file> and privacy --manifest <file> stay available (read-only).
The diff names every effect, not just fields: /$effect/createVersion, /$effect/replaceSet/<locale>/<display>
(screenshots; delete-then-upload, nonAtomic), skipped ops for values the engine will not send
(whatsNew on a first release, URLs with no primary-locale localization, a missing age-rating
declaration, an empty screenshot directory), unsupported for manifest iap items that list asc
(no command), manual for App Privacy. A password is <env:NAME>, unverifiable, never a value.
Targets are picked deterministically and recorded in targets: the appInfo not
READY_FOR_DISTRIBUTION (two of them is exit 1), the version whose versionString equals the
manifest’s (none: a create-version op, unless ANOTHER editable version exists: exit 1 naming both versions, since Apple allows one editable version and the create would 409; one in a non-editable state: exit 1; one WAITING_FOR_REVIEW:
every op writing to it is inReview).
Legacy --config path (deprecated, kept working)
Section titled “Legacy --config path (deprecated, kept working)”resolve, plan, apply, run, screenshots, reviewdetails, bundleid, clone with --config still work,
warn on stderr and are not gated. run’s preview prints the settings diff (GET only) and never creates a
version; run covers settings + App Review details only. Commands and examples:
references/legacy-config-path.md.
App Review details
Section titled “App Review details”run covers this too, but it is worth knowing on its own. App Review reads a
contact block per version — one appStoreReviewDetails record, holding the
four contact fields, the optional demo account, and free-text notes for the
reviewer. The base carries the studio contact, so a title that needs nothing
special gets it for free:
# preview: live -> config, field by field. writes nothing.bun <skill>/scripts/asc-engine.cjs reviewdetails --config <resolved># write only what differsbun <skill>/scripts/asc-engine.cjs reviewdetails --config <resolved> --confirm
# contact block of another app's most recent version that has one.# copies contact fields ONLY — never the demo credentials, never notes.bun <skill>/scripts/asc-engine.cjs reviewdetails --config <resolved> --from <appleId>A demo password never lives in a config file. Config files are committed. Name an env var instead, and export it before the run:
"reviewDetails": { "demoAccountRequired": true, "demoAccountName": "qa@the1studio.org", "demoAccountPasswordEnv": "MYGAME_DEMO_PASSWORD"}The engine reads $MYGAME_DEMO_PASSWORD and refuses to run if it is unset —
rather than sending an empty password and leaving you to find out at review.
It also refuses outright if it finds a literal demoAccountPassword in the
config.
The two things no API can do
Section titled “The two things no API can do”1. Creating the app record. There is no POST /v1/apps — GET and PATCH only.
Do it at appstoreconnect.apple.com → + → New App. SKU is permanent;
Bundle ID locks at first submission.
2. App Privacy. No endpoint exists — verified, not assumed: the app resource
exposes 41 relationships and none is privacy-shaped, and /v1/appDataUsages,
/v1/appDataUsagesPublishState and /v1/appDataUsageCategories all return
404 "resource does not exist". store-auto.cjs privacy prints the exact
declaration to tick in the Console instead of pretending to push it.
ATT — read this before publishing a privacy label
Section titled “ATT — read this before publishing a privacy label”The base declares all six data types used for tracking. That obliges the
build to show the App Tracking Transparency prompt (ATTrackingManager). A label
that says tracking with a build that never prompts is rejected on the mismatch.
If a title genuinely ships no ad SDKs, override appPrivacy in its game file
rather than declaring data it does not collect — an inaccurate privacy label is
grounds for removal, not just rejection.
Hard rules
Section titled “Hard rules”whatsNewis rejected on a first version.409 STATE_ERROR— release notes need a prior release to describe, and the PATCH is atomic, so it takes description, keywords and promo text down with it. The engine detects a never-released app and skips the field. It starts applying at version 2.- ES256 must be raw R‖S, not DER. Node’s default
crypto.signemits DER and Apple answers a bare401with no body. The engine passesdsaEncoding: 'ieee-p1363'. nameandsubtitlelive onappInfoLocalizations; everything else lives onappStoreVersionLocalizations. Two objects, two PATCHes — the usual reason a “successful” apply leaves the subtitle unchanged.appStoreAgeRatingis derived, not settable. The base holds the 25 input fields; sending the resolved rating back is a 409.- Screenshot upload is replace-all per locale per display type. The engine deletes the existing set first, so an interrupted run leaves it empty, not stale. Re-run it.
APP_IPHONE_67covers both 6.7” and 6.9”. There is no_69enum.- A preview never creates a version.
editableVersionwith its create flag set POSTs/v1/appStoreVersions, so every command tiescreatetoBoolean(argv.confirm)(applySettings,screenshots,reviewdetails;applyreturns to its plan before reaching it).storenever calls it: a missing version is acreate-versionop in the diff and a request only after the hash gate. A literal create flag set to true anywhere turnsstore-auto-preview-readonly.test.cjsred. - An HTTP error always fails, even with an empty body.
parse()once returned{}for any empty body, so a 5xx GET read as “no items” and a failedPATCH/DELETEread as success. An empty body is success only for a 2xx; everything else throws and the command exits 1. - One appInfo, one version, for every command.
plan,apply,run,cloneandstoreshare one pick (pickAppInfo,pickVersioninasc-engine.cjs); the oldinfos[0]inplan/applyand “first editable in API order” made two commands write to different records. engine.scriptSha256coversasc-engine.cjs,asc-store.cjs,store-auto.cjsand the manifest skill files they load (the static listENGINE_FILESinasc-store.cjs, guarded by a test). A newrequireof a kit file must be added there, orasc-store.test.cjsfails; a module update changes the hash and a pending apply exits 3 (engine changed): re-plan.- Token lifetime is capped at 20 minutes. The engine mints 19 and re-mints on demand, so a long screenshot upload does not die partway.
- A missing app reports as “no app record”, not 403.
filter[bundleId]returns empty both when the app does not exist and when the key’s role cannot see it; the API cannot distinguish them, so the error names both causes. - App Review details are per VERSION, so a new version may need the pass again.
One
appStoreReviewDetailsrecord exists perappStoreVersion. Whether Apple carries a previous version’s block forward when a new version is created is not verified here —reviewdetailsprints the live state either way, so run the preview and read it rather than assuming. If it shows all=, nothing to do; if it shows a pending POST, it did not carry over. - Apple does not always return a stored demo password. The engine reports the
live value as unknown rather than
=in that case, because an absent value is not a match — a=there would be a green that proves nothing. - The studio contact block is the base’s; a game overrides only what differs.
reviewDetailsdeep-merges like every other block, so one game can changecontactEmailand inherit the rest.
Keeping the base current
Section titled “Keeping the base current”The base was derived from a live, shipping app and verified field-by-field. When
the studio changes a shared fact — a new privacy URL, a different copyright
entity — change templates/studio-base.json and every future app inherits it.
Existing apps do not update retroactively; re-run run --confirm per app.
Related
Section titled “Related”references/api-surface.md— every endpoint, automatable vs manual- the studio-local play-console-setup skill — the Android half