arcane-cli 0.14.0

package/dist/assets/.github/prompts/spell-create-pull-request.prompt.md

@@ -0,0 +1,170 @@
+---
+name: Spell — Create Pull Request
+description: Open a pull request for the current branch with an auto-generated title and description from commit history. Provider-agnostic (GitHub or Azure DevOps).
+argument-hint: '[--draft] [--reviewers <name,...>] [--target <branch>] [--docs-only]'
+agent: agent
+last_updated: 2026-07-05
+---
+
+## Executive Summary
+
+- This spell creates a pull request for the current feature branch — no manual title/description writing.
+- It auto-generates a Conventional-Commits title and a structured description from the commit log.
+- It is provider-agnostic: it detects GitHub vs Azure DevOps from the git remote and uses the right CLI.
+- The PR is the only path to `main` (direct pushes are blocked by policy). See `.arcane/governance/git-conventions.md`.
+
+---
+
+Create a pull request for the current branch.
+
+Context to consult:
+
+- `.arcane/governance/git-conventions.md` — PR requirements, branch policy, merge strategy (the no-squash rule).
+- `.arcane/governance/testing-standards.md` — coverage thresholds to cite in the description.
+
+Related spells:
+
+- `spell-commit-work` — land your work as Conventional-Commits commits before opening the PR.
+- `spell-ship` — the broader release flow that records the PR URL after this spell creates it.
+- `spell-address-review` — resolve reviewer feedback once the PR is open.
+
+## Arguments
+
+- `--draft` — create the PR as a draft (work-in-progress / early feedback).
+- `--reviewers <name,...>` — comma-separated reviewers. Optional.
+- `--target <branch>` — target branch (default `main`).
+- `--docs-only` — lightweight mode for documentation-only changes: prefixes `[docs]` in the title, skips test-evidence/review sections, and enables auto-complete/auto-merge where the provider supports it.
+
+## Step 0 — Guard checks
+
+> **🛑 AGENT-MANDATORY PRE-PR CHECKLIST — READ FIRST.** Before *any* PR-creation call (this spell, raw `az repos pr create`, raw `gh pr create`, the `create_pull_request` MCP tool, REST, web hook, or anything else):
+>
+> 1. `git fetch origin`
+> 2. `git rebase origin/<target-branch>` (default `main`) and resolve conflicts locally
+> 3. `git push --force-with-lease` if the branch was already on origin
+> 4. *Then* run the PR-creation call
+>
+> This rule is on the **agent**, not on the spell. Calling `az repos pr create` / `gh pr create` directly is **not** an escape hatch — it is a governance violation. See `.arcane/governance/git-conventions.md` → **🛑 Agent-mandatory pre-PR guard**.
+
+1. Run `git branch --show-current`. **STOP** if on `main`/`master` — you cannot PR the integration branch into itself. Also **STOP** if detached HEAD (empty output) — check out a named branch first.
+2. **Verify the target exists:** `git rev-parse --verify origin/<target>`. If it fails, `git fetch origin <target>`; if still missing, **STOP** and ask the user for the correct `--target`.
+3. **Ensure the branch is on origin (upstream):** if `git rev-parse --abbrev-ref --symbolic-full-name @{u}` fails, the branch was never pushed — run `git push -u origin <branch>`. The provider CLIs can only open a PR for a branch that exists on the remote.
+4. **STOP** if the branch has no commits ahead of the target: `git log origin/<target>..HEAD --oneline` is empty → nothing to PR.
+5. Check for an existing **open** PR for this branch (provider-specific, Step 2). If one exists, print its URL and stop — never create duplicates.
+6. **Mandatory rebase on target (governance guard):** `git fetch origin` then `git rebase origin/<target>`. On clean rebase, `git push --force-with-lease` (only if the branch existed remotely before the rebase). On conflicts: **STOP**, list conflicting files, ask the user to resolve; never push a branch that will produce a merge conflict on the target (see git-conventions "🛑 Agent-mandatory pre-PR guard"). This step is not optional and is not skippable by calling a different PR-creation tool.
+7. **Auto-suggest `--docs-only`** (only if not already passed): if every changed file vs target is documentation/session files (`*.md`, `TODO.md`, `DECISIONS.md`, `journal/**`, `IDEAS.md`, `FEEDBACK.md`), print a one-line hint suggesting `--docs-only` and proceed with the standard path.
+
+## Step 1 — Gather context
+
+```bash
+git branch --show-current
+git log origin/<target>..HEAD --format="%h %s" --reverse   # commit list
+git diff origin/<target>..HEAD --stat | tail -1            # files / insertions / deletions
+git remote get-url origin                                  # provider detection
+```
+
+## Step 2 — Detect provider
+
+| Remote URL contains | Provider |
+| --- | --- |
+| `github.com` | GitHub (`gh`) |
+| `dev.azure.com` / `visualstudio.com` | Azure DevOps (`az repos`) |
+| anything else | unknown — **STOP** and ask the user which provider/CLI to use |
+
+If the detected provider's CLI is missing or unauthenticated (`gh auth status` / `az account show` fails), **STOP** with a clear message — do not silently fall back to the other provider.
+
+Check for an existing **open** PR before creating (filter by state so a previously merged/closed PR for the same branch does not falsely block):
+
+- **GitHub:** `gh pr list --head <branch> --base <target> --state open --json url --jq '.[0].url'`
+- **Azure DevOps:** `az repos pr list --source-branch <branch> --target-branch <target> --status active --output json`
+
+If an open PR is found, print its URL and stop.
+
+## Step 3 — Build the title
+
+Format: `type(scope): summary`
+
+1. `type` = the majority commit type in the log (e.g. `feat`, `fix`, `chore`).
+2. `scope` = optional; derive from the dominant changed area if obvious, else omit the parens.
+3. `summary` = a concise one-line synthesis of the commits (≤ 72 chars per git-conventions), lowercase, imperative, no trailing period.
+4. With `--docs-only`, prepend `[docs] `.
+
+## Step 4 — Build the description
+
+Write the body to a **temp file** and pass it to the provider CLI by file reference — never pass multiline content as a shell argument (this avoids shell/PowerShell truncation, quoting, and newline-mangling). Resolve the scratch path with `git rev-parse --git-dir` (handles worktrees and non-default `.git` locations) and write to `<git-dir>/arcane-pr-body.md`. The `.git` directory is never committed, so the body file is safe and ignored. Delete it after a successful create (Step 6).
+
+Standard template:
+
+```markdown
+## Summary
+
+<1–3 sentences synthesized from the commits — not copied verbatim.>
+
+## Changes
+
+### Features
+- <feat summaries>
+### Fixes
+- <fix summaries>
+### Infrastructure / Chores
+- <chore/docs/ci/refactor summaries>
+
+> Omit empty sections.
+
+## Testing
+
+- <coverage / test status if known, else "See CI pipeline results.">
+```
+
+`--docs-only` template (skip Testing):
+
+```markdown
+## Summary
+<1–2 sentences on the doc changes.>
+
+## Changes
+- <changed files or sections>
+
+## Notes
+Documentation-only PR. No functional code changed.
+```
+
+## Step 5 — Create the PR
+
+- **GitHub:**
+  ```bash
+  gh pr create --title "<title>" --body-file <temp> --base <target> --head <branch> [--draft] [--reviewer <r1,r2>]
+  ```
+  With `--docs-only` and auto-merge enabled: `gh pr merge --auto <PR#>` (use the repo's configured merge method; do **not** force squash — see git-conventions).
+- **Azure DevOps:**
+  ```bash
+  az repos pr create --title "<title>" --description "@<temp>" --source-branch <branch> --target-branch <target> [--draft] [--reviewers "<r1> <r2>"]
+  ```
+  With `--docs-only`, add `--auto-complete`. Respect the repo merge strategy — never enable squash (see git-conventions).
+
+**Reviewers:** pass `--reviewers`/`--reviewer` values through as given. If a reviewer cannot be resolved by the provider, do **not** abort the create — let the PR be created and surface the unresolved name(s) in the Step 6 report so the user can add them manually.
+
+**Post-create verification (both providers):** read the PR back (`gh pr view <PR#> --json url,title,body` / `az repos pr show --id <PR#>`). If the title or description is empty or does not match the temp file, patch it (`gh pr edit` / `az repos pr update`) from the temp file, then re-verify once. This guards against silent body truncation/drop on either CLI.
+
+## Step 6 — Report
+
+```
+✓ PR created: <URL>
+  Title:     <title>
+  PR #:      <number>
+  Source → Target: <branch> → <target>
+  Reviewers: <list or "none assigned">
+```
+
+- If no reviewers were resolved (none passed, or names the provider could not match): `⚠ No reviewers assigned — add them in the PR or re-run with --reviewers`.
+- If `--draft`: note it was created as a draft.
+- Delete the body temp file (`<git-dir>/arcane-pr-body.md`) once the PR is confirmed created and verified.
+
+## Rules
+
+- Never create duplicate PRs — always check first (Step 2).
+- Never push directly to `main` — the PR is the only path.
+- Always write the description to a file before passing it to the provider CLI.
+- Respect the repo merge strategy in `.arcane/governance/git-conventions.md` — **do not squash** (it breaks per-commit attribution).
+- Print the PR URL clearly so it can be recorded by `spell-ship` / `spell-close-session`.
+- Never include secrets or tokens in the title or description.

package/dist/assets/.github/prompts/spell-document.prompt.md

@@ -0,0 +1,83 @@
+---
+name: Spell — Document
+description: Formalize valuable insights, analysis, or decisions from the current conversation into polished, permanent reference documents.
+argument-hint: Topics and output paths (e.g., "capability inventory → docs/capabilities.md")
+agent: agent
+---
+
+## Executive Summary
+
+- This spell extracts substantive analysis from the current conversation and structures it into formal, durable documents.
+- It bridges ephemeral chat context and lasting project documentation.
+- Use it when a session produces reference material that deserves a proper home (inventories, comparisons, rationale, guides).
+- For a quick one-line idea instead, use `spell-save-idea`. For session continuity, use `spell-close-session`.
+
+---
+
+Capture conversation insights and formalize them into well-structured documents.
+
+The user's input describes what to capture and where. If no argument was provided, ask what they want to capture and stop until they answer.
+
+**Before doing anything else, check that there is durable material to formalize.** Scan the conversation for substantive analysis, decisions, comparisons, or reference data. If the session holds nothing beyond small talk or trivial exchanges, say so plainly, suggest `spell-save-idea` for a quick capture instead, and stop — do not manufacture content to fill a document.
+
+## Step 1 — Parse the Request
+
+Identify:
+
+- **Topics** — what conversation insights to extract (e.g., "naming analysis", "architecture comparison").
+- **Target paths** — where to write (e.g., `docs/...`, `.arcane/governance/...`). If the user gives only topics, propose sensible paths from the project structure.
+- **Document type** — reference doc, decision record, analysis report, inventory, or guide.
+
+## Step 2 — Extract from Conversation
+
+Gather all relevant material from context: tables, structured data, analysis results, comparisons, conclusions, recommendations, metrics/counts, and reasoning chains. Do not leave valuable insight behind in the chat.
+
+## Step 3 — Structure into Documents
+
+For each target, produce a polished structure:
+
+- Title + metadata (clear heading, date, one-line context). Get the real date from the system (e.g., run `date`) rather than guessing.
+- Table of contents for documents longer than ~3 sections.
+- Proper sections with headers and logical flow.
+- Tables and lists formatted for readability.
+- Cross-references to related project files where relevant.
+- A short provenance note (e.g., _"Captured from a development session on YYYY-MM-DD."_) so future readers know its origin.
+
+Match the tone, frontmatter, and structure of files already in the target directory before inventing your own format.
+
+## Step 4 — Show Proposal
+
+Present before writing. For each target, check whether the file already exists and label it `(new)` or `(exists — will diff before writing)` so approval is informed, not blind:
+
+```
+## Document Proposal
+
+### 1. <path/to/file.md>  (new)
+- Type: <reference / analysis / inventory / guide>
+- Sections: <list>
+- Preview:
+  <first 10–15 lines>
+
+### 2. <another path>  (exists — will diff before writing)
+...
+
+Approve? (yes / edit / skip)
+```
+
+## Step 5 — Apply (after approval)
+
+1. Write each new document to its target path.
+2. If a target already exists, do not silently overwrite. Show a diff preview of the proposed change against the current file and confirm. Prefer merging the new content into the existing structure (append a section, update a table) over replacing the whole file, unless the user asked for a full rewrite. State which mode you are using before writing.
+3. Do NOT commit — leave that to `spell-commit-work`.
+4. Confirm what was written and where (path + new-vs-updated per file).
+
+## Rules
+
+- Only formalize material actually present in the conversation — do not invent, infer, or pad content to fill a section.
+- If nothing substantive is in the conversation, stop and route to `spell-save-idea` rather than producing an empty document.
+- Follow existing documentation patterns in the target directory.
+- Never overwrite an existing file without an explicit diff confirmation; prefer merging over clobbering.
+- Never include secrets, tokens, or credentials in a document.
+- Do not commit the changes — that is `spell-commit-work`'s job.
+
+> **Tip:** Run `spell-close-session` afterward to log the session, or `spell-commit-work` to commit the new documents.

package/dist/assets/.github/prompts/spell-dotnet-expert.prompt.md

@@ -0,0 +1,117 @@
+---
+name: Spell — .NET Expert
+description: Load .NET best practices and patterns for any development agent working on .NET projects
+argument-hint: Specific .NET topic or question (e.g., "Azure Functions isolated worker", "EF Core migrations")
+agent: agent
+---
+
+## Executive Summary
+
+- This prompt loads .NET expertise into any agent's context — no dedicated .NET agent needed, per your org's decision/security log if one exists.
+- Covers .NET 10, ASP.NET Core, Azure Functions (isolated worker), Entity Framework Core, and xUnit testing.
+- Use this when any dev agent is working on `{BUSINESS_NAME}` or other .NET projects. (`{BUSINESS_NAME}`: resolve from `.arcane.json` / the feature or PRD frontmatter; ask if unset.) For the dev-agent roster, reference [[agent-policies]] / [[naming-conventions]] rather than assuming specific personas.
+- Combines with `spell-implement` for .NET-specific autonomous development loops.
+
+---
+
+Load .NET expert context and assist with the specified topic.
+
+Context to apply:
+
+### .NET Project Standards
+
+- **Target Framework:** .NET 10 (latest LTS)
+- **API Pattern:** ASP.NET Core Minimal APIs (preferred) or Controllers (existing projects)
+- **Serverless:** Azure Functions v4 isolated worker model (NOT in-process)
+- **ORM:** Entity Framework Core with code-first migrations
+- **Testing:** xUnit + FluentAssertions + Moq (or NSubstitute)
+- **DI:** Built-in Microsoft.Extensions.DependencyInjection
+- **Logging:** Serilog with structured logging (JSON output)
+- **Configuration:** Options pattern (`IOptions<T>`) — never read config directly
+
+### Code Patterns
+
+```csharp
+// Minimal API pattern
+app.MapGet("/api/items/{id}", async (int id, IItemService service) =>
+{
+    var item = await service.GetByIdAsync(id);
+    return item is null ? Results.NotFound() : Results.Ok(item);
+});
+
+// Service registration
+builder.Services.AddScoped<IItemService, ItemService>();
+builder.Services.Configure<ItemOptions>(builder.Configuration.GetSection("Items"));
+
+// Azure Function (isolated worker)
+[Function("ProcessItem")]
+public async Task<HttpResponseData> Run(
+    [HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequestData req)
+{
+    var item = await req.ReadFromJsonAsync<ItemRequest>();
+    // Process...
+    var response = req.CreateResponse(HttpStatusCode.OK);
+    await response.WriteAsJsonAsync(result);
+    return response;
+}
+```
+
+### Testing Patterns
+
+```csharp
+// xUnit test with FluentAssertions
+public class ItemServiceTests
+{
+    [Fact]
+    public async Task GetById_WhenExists_ReturnsItem()
+    {
+        // Arrange
+        var mockRepo = new Mock<IItemRepository>();
+        mockRepo.Setup(r => r.GetByIdAsync(1))
+            .ReturnsAsync(new Item { Id = 1, Name = "Test" });
+        var service = new ItemService(mockRepo.Object);
+
+        // Act
+        var result = await service.GetByIdAsync(1);
+
+        // Assert
+        result.Should().NotBeNull();
+        result!.Name.Should().Be("Test");
+    }
+}
+```
+
+### Common Pitfalls to Avoid
+
+- **Don't use `HttpClient` directly** — use `IHttpClientFactory` with named/typed clients.
+- **Don't catch `Exception`** — catch specific types. Let unhandled exceptions bubble to middleware.
+- **Don't use `async void`** — always `async Task`. Exception: event handlers.
+- **Don't block on async** — never use `.Result` or `.Wait()`. Use `await`.
+- **Don't put business logic in controllers/endpoints** — use a service layer.
+- **Don't use `DateTime.Now`** — use `DateTimeOffset.UtcNow` or inject `TimeProvider`.
+- **Don't store secrets in appsettings.json** — use User Secrets (dev) or Azure Key Vault (prod).
+
+### NuGet Package Standards
+
+Always pin exact versions. Preferred packages:
+- `Microsoft.EntityFrameworkCore` — ORM
+- `Serilog.AspNetCore` — logging
+- `FluentValidation` — input validation
+- `Polly` — resilience and retry policies
+- `Mapster` or `AutoMapper` — object mapping
+- `Swashbuckle.AspNetCore` — OpenAPI/Swagger
+
+### Azure-Specific Patterns
+
+- Use Managed Identity for Azure service authentication (no connection strings with keys).
+- Use Azure Key Vault references in App Service/Functions configuration.
+- Use Application Insights for telemetry (`AddApplicationInsightsTelemetry()`).
+- Use Azure Storage Queue or Service Bus for async messaging (not HTTP callbacks).
+
+Workflow:
+
+1. **Identify the .NET topic** — what does the developer need help with?
+2. **Apply the patterns above** — use the standards as constraints.
+3. **Provide implementation guidance** — specific code, not just concepts.
+4. **Include tests** — every code suggestion includes corresponding xUnit tests.
+5. **Flag deviations** — if the existing codebase doesn't follow these patterns, note it but don't refactor without approval.

package/dist/assets/.github/prompts/spell-eas-ios-deploy.prompt.md

@@ -0,0 +1,183 @@
+---
+name: Spell — EAS iOS Deploy
+description: Ship an Expo/React Native app to TestFlight and the App Store via EAS Build + EAS Submit — initial one-time setup and every deploy after that
+argument-hint: What you need — "initial setup", "deploy" (cut + submit a new build), or a specific symptom (e.g. "capability sync failed", "build stuck")
+agent: agent
+---
+
+## Executive Summary
+
+- This prompt ships an Expo/React Native app to Apple TestFlight/App Store using **EAS Build + EAS
+  Submit** — Expo's cloud build service. No local Mac or Xcode install is required.
+- Covers two flows: **initial one-time setup** (Apple enrollment → credentials → first build →
+  first submit) and **repeat deployments** (the two-command loop you run for every release after that).
+- Produces a signed production build uploaded to App Store Connect, visible in TestFlight once Apple
+  finishes processing it, with the app's native build number bumped and committed to the repo.
+- **Not** a general CI/CD ship spell — see `spell-ship` for the branch-merge / backend-deploy
+  lifecycle. This spell is the mobile-app-store-specific leaf step, and it is scoped deliberately to
+  the **EAS Build/Submit** tech stack — it does not cover local Xcode builds, Xcode Cloud, or Fastlane.
+  A team on one of those instead needs a different spell; the steps below assume EAS.
+
+---
+
+Ship the app to TestFlight/App Store, or troubleshoot an EAS deploy issue, per the request in the
+prompt argument. If no argument was given, ask whether this is initial setup or a repeat deploy.
+
+### Placeholders
+
+Resolve each from `.arcane.json` / the project's `app.json` / `eas.json` / frontmatter; **ask the
+user rather than guessing or inventing a value** if any is unset. Never proceed with an unresolved
+placeholder still in a command you're about to run.
+
+| Placeholder | What it is | Where it lives once resolved |
+| --- | --- | --- |
+| `{APP_NAME}` | Display name shown on the App Store / home screen | `app.json` → `expo.name` |
+| `{BUNDLE_ID}` | iOS bundle identifier (and Android package, if shipping both) | `app.json` → `expo.ios.bundleIdentifier` |
+| `{APPLE_TEAM_ID}` | Apple Developer Team ID | `eas.json` → `submit.production.ios.appleTeamId` |
+| `{ASC_APP_ID}` | Numeric App Store Connect app ID | `eas.json` → `submit.production.ios.ascAppId` |
+| `{APPLE_ID_EMAIL}` | Apple ID used for the Developer/ASC account | `eas.json` → `submit.production.ios.appleId` |
+| `{EAS_PROJECT_ID}` | EAS/Expo project ID | `app.json` → `expo.extra.eas.projectId` |
+| `{EAS_ACCOUNT}` | EAS/Expo account or org slug the project lives under | `eas build`/`eas submit` output, or `eas whoami` |
+
+### Context files this spell reads
+
+- **`app.json`/`app.config.js`** (Expo config) — bundle identifier, current `version`, native
+  `buildNumber`, EAS project ID. If it doesn't exist, this isn't an Expo project — stop and say so.
+- **`eas.json`** — build + submit profiles. **If missing**, run `eas build:configure` first (it
+  scaffolds a starter `eas.json` interactively) before continuing with the steps below.
+- **Apple Developer Program membership** for `{APPLE_ID_EMAIL}` — must be an active, paid enrollment.
+  If you don't know whether it's active, ask the user to confirm at
+  developer.apple.com/account before starting initial setup — everything downstream depends on it.
+
+If **none** of these exist yet (a brand-new Expo project with no `eas.json` and no App Store Connect
+app record), start at **Phase A, step 1** — every step is written to work from that empty state.
+
+---
+
+## Phase A — Initial one-time setup
+
+Run once per app. Skip to Phase B if `eas.json` already has a `submit.production.ios` block and a
+first build has already reached TestFlight.
+
+1. **Confirm Apple Developer Program enrollment** is active for `{APPLE_ID_EMAIL}` (paid,
+   developer.apple.com/account). Nothing below works without it.
+2. **Create the App Store Connect app record** — appstoreconnect.apple.com → My Apps → "+" → New App.
+   Fill in `{APP_NAME}`, `{BUNDLE_ID}` (create a matching Identifier first if one doesn't exist yet),
+   a SKU, and user access. Capture the numeric app ID it's assigned — that's `{ASC_APP_ID}`.
+3. **Log in to EAS**: `npx eas-cli login` (skip if already authenticated — `eas whoami` confirms).
+4. **Configure `eas.json`** if it doesn't already have what's needed:
+   ```jsonc
+   {
+     "cli": { "appVersionSource": "local" },
+     "build": {
+       "production": { "channel": "production", "autoIncrement": true }
+     },
+     "submit": {
+       "production": {
+         "ios": {
+           "appleId": "{APPLE_ID_EMAIL}",
+           "ascAppId": "{ASC_APP_ID}",
+           "appleTeamId": "{APPLE_TEAM_ID}"
+         }
+       }
+     }
+   }
+   ```
+   `appVersionSource: "local"` + `autoIncrement: true` on the build profile means EAS bumps the
+   native build number in `app.json` for you on every build — no manual version-bump step, ever.
+5. **First build**: `eas build --platform ios --profile production`. On a project with no
+   credentials yet, EAS interactively generates everything it needs **remotely** — Distribution
+   Certificate, Provisioning Profile, and (if the app uses push) an APNs key. No local keychain, no
+   Mac. Confirm each prompt; let EAS manage the private key material — you should never need to see
+   or copy it.
+6. **First submit**: `eas submit --platform ios --profile production --latest`. First time through,
+   it also sets up an **App Store Connect API key** for non-interactive submits (EAS-managed is
+   simplest — pick that unless there's a reason to upload your own). Confirm the role it grants when
+   asked (App Manager is enough for build submission).
+7. **Confirm it landed**: App Store Connect → your app → TestFlight → iOS builds. Apple's binary
+   processing takes ~5–10 minutes after a successful `eas submit` before the build appears there.
+
+## Phase B — Repeat deployments
+
+The two-command loop for every release after Phase A:
+
+1. Land the code changes; typecheck/build clean locally first.
+2. `eas build --platform ios --profile production --non-interactive`
+   (add `EXPO_NO_CAPABILITY_SYNC=1` up front if you know a capability-sync failure is coming —
+   see **Known pitfalls** below).
+3. `eas submit --platform ios --profile production --latest --non-interactive`
+4. **Commit the build-number bump**: step 2's `autoIncrement` rewrote `app.json`'s native build
+   number locally — `git add`/`git commit` it so the repo matches the binary that just shipped.
+5. Confirm in TestFlight (same as Phase A step 7).
+
+Re-running either command is always safe: `eas build` reuses existing valid credentials rather than
+regenerating them (it only creates new ones when something actually changed, like a new capability),
+and re-running `eas submit` after a failed attempt is a normal retry, not a duplicate submission risk.
+
+## Known pitfalls (verified, not hypothetical)
+
+- **"Failed to patch capabilities: X ON, Y OFF"** — happens when the App Store Connect app record is
+  already linked to `{BUNDLE_ID}` and Apple rejects EAS's automatic capability sync. Fix: set
+  `EXPO_NO_CAPABILITY_SYNC=1` for the build command, **and** manually toggle the capability (Push
+  Notifications, Sign in with Apple, Associated Domains, whatever the app just added) on in the Apple
+  Developer console under Identifiers → `{BUNDLE_ID}` → Capabilities. EAS syncing capabilities and you
+  toggling them by hand are two ways to the same end state; when the app is already linked, only the
+  manual toggle works.
+- **"Command must be re-run to pick up new updates configuration"** — EAS auto-installed
+  `expo-updates` mid-build because the config needed it and it wasn't present. Just re-run the exact
+  same build command once; it picks up cleanly the second time.
+- **A brand-new entitlement was just added** (e.g. Associated Domains, Sign in with Apple) — confirm
+  the App ID capability is toggled on in the Apple Developer console *before* building. A successful
+  build with a fresh "Provisioning Profile ... Updated: N seconds ago" in the credentials output is
+  itself the confirmation that the new entitlement is correctly provisioned — if the capability isn't
+  on yet, the build will fail at the signing step instead.
+- **Apple "Internal Server Error"** during API key creation or submission — Apple's servers are
+  occasionally flaky. Retry the identical command; no code or config change needed.
+- **Build succeeds but nothing changed on-device** — before assuming the deploy is broken, rule out
+  the mundane cause first: the tester didn't force-quit and reopen the app after installing the new
+  TestFlight build (a backgrounded process can survive an update). Confirm the visible build/version
+  number inside the app (a settings screen, an About row) matches what you just shipped before
+  debugging further.
+
+## Acceptance checklist
+
+- [ ] `eas build` output ends with "Build finished" and an artifact URL.
+- [ ] `eas submit` output ends with "Submitted your app to Apple App Store Connect!"
+- [ ] App Store Connect → TestFlight → iOS builds shows the new build number (allow 5–10 min for
+      Apple's processing).
+- [ ] The `autoIncrement`-bumped build number in `app.json` is committed — `git status` is clean.
+- [ ] If an entitlement changed this deploy, it visibly works on a fresh install of the new build.
+
+## Cross-references
+
+- **`spell-ship`** — the surrounding branch-merge / backend-CI-CD lifecycle, if this app ships
+  alongside a paired backend. This spell is the mobile-store-specific leaf step; run it after
+  `spell-ship`'s checklist is green for anything the app depends on, not instead of it.
+- **`spell-dotnet-expert`** and other stack-expert spells — the sibling "load expertise into any
+  agent" pattern. This spell goes one step further: it doesn't just load context, it executes the
+  actual build/submit commands.
+- **`spell-bump`** — coordinate with it if the app's marketing `version` (not just the native build
+  number this spell auto-increments) also needs a bump before shipping.
+- **`spell-todo`** — if a pitfall or gap surfaces mid-deploy that shouldn't block shipping today,
+  capture it there rather than scope-creeping this deploy.
+
+## Rules
+
+- **Never guess a placeholder.** If `{BUNDLE_ID}`, `{APPLE_TEAM_ID}`, `{ASC_APP_ID}`, or
+  `{APPLE_ID_EMAIL}` is unresolved, ask — do not invent a value or proceed with a literal placeholder
+  string in a real command.
+- **Never handle real credential material.** You should never need to see, paste, or commit a
+  Distribution Certificate private key, an App Store Connect API private key (`.p8`), or any
+  password — EAS manages all of it remotely. If a step seems to require pasting one, stop; something
+  is set up wrong.
+- **Confirm before `eas submit`.** Submitting puts a real binary in front of Apple's review /
+  TestFlight testers — it's outward-facing and not something to undo casually. Say what you're about
+  to submit and to which environment before running it.
+- **Confirm before setting `EXPO_NO_CAPABILITY_SYNC=1`.** Explain why it's needed (it disables an
+  automatic sync that would otherwise silently turn a capability off) rather than setting it
+  silently.
+- **Never force-regenerate credentials** (revoke + recreate a Distribution Certificate or
+  Provisioning Profile) without explicit confirmation — revoking a certificate invalidates every
+  build ever signed with it, including ones already live.
+- **A backend/API prod deploy the app depends on is a separate, separately-confirmed action.** Do
+  not fold it into a mobile build/submit step just because they're related.