b2c-app-builder 0.221.39

package/knowledge/engineering/technical-documentation-ste100.md

@@ -0,0 +1,89 @@
+# Technical Documentation In Simplified Technical English (ASD-STE100)
+
+Use this register before you write or edit any of these files:
+
+- `docs/architecture.md` or `docs/validators.md`
+- This skill's own `SKILL.md`
+- Technical instruction blocks inside the public `README.md` (commands, flags, schemas)
+- Narrative README copy stays with `no-slop-writing.md`
+- Any `knowledge/*.md` reference file except `knowledge/words/`
+- A maintainer-authored engineering spec inside this repository
+- An ADR or a runbook
+- An API or config reference inside this repository
+
+This is the flat, literal register. Its job is prose that a reader parses correctly on one pass, not prose that persuades or entertains.
+
+This section does not cover three files a launched business receives as templates: `engineering/TECH_SPEC.md`, `engineering/ENGINEERING_PLAN.md`, and `engineering/PRODUCTION_READINESS.md`. The templates live under `examples/workspace/business/engineering/` and under `workspace-template/`. Every file with these three names in this repository today is one of those templates, not a maintainer document. §2 states this exclusion in full.
+
+## 1. Boundary With `no-slop-writing.md` (Read First)
+
+This repo already has one writing-quality standard: [`no-slop-writing.md`](../words/no-slop-writing.md). That standard is voice-**preserving**: it cuts AI-slop filler but keeps the brand's or the skill's own character. ASD-STE100 is voice-**flattening** instead: one meaning per word, active voice, simple tense, short sentences, no idiom, no character. Apply both standards to the same sentence and you get contradictory edits.
+
+To avoid that collision, the two files split the repo's documentation by file, never by a vague genre label:
+
+- `no-slop-writing.md` alone governs the repo's public front door: root `README.md`, `CONTRIBUTING.md`, `.github/SECURITY.md`, `.github/CODE_OF_CONDUCT.md`, root `AGENTS.md`, and root `CLAUDE.md`. `no-slop-writing.md` §2 calls this set the "third surface," and `check:no-slop` enforces it. Do not apply ASD-STE100 as a blanket rewrite of these six files.
+- This file alone governs the technical documentation named in the trigger paragraph above, including `SKILL.md`.
+- The public README is mixed. Apply `no-slop-writing.md` to narrative. Apply this file by judgment to technical examples. `check:documentation-ste100` does not scan README. Do not expand a 20-word ceiling across the whole front door.
+- Founder-facing copy, marketing copy, and brand voice stay with `no-slop-writing.md` and its channel-specific sections. Never apply ASD-STE100 there: it does not cover text where voice, nuance, or persuasion is the point.
+
+Some documents straddle both standards — for example, a `README.md` with a narrative introduction and a technical API section. Apply `no-slop-writing.md` to the narrative part and this file to the technical part. `no-slop-writing.md` §8 uses the same split for legally required text inside persuasive copy.
+
+## 2. Scope
+
+This file governs technical, procedural, and reference documentation authored inside this repository:
+
+- Architecture docs and validator or gate references
+- This skill's own knowledge base
+- A maintainer-authored engineering spec inside this repository
+- ADRs and runbooks
+- API or config references
+
+This file does not extend to documentation the skill generates for a launched business. Three exclusions: the `examples/workspace/business/engineering/{TECH_SPEC,ENGINEERING_PLAN,PRODUCTION_READINESS}.md` templates, their `workspace-template/` counterparts, and a launched business's own `AGENTS.md` or `CLAUDE.md`. That is a separate, later decision, not covered here.
+
+## 3. Core Rewrite Rules
+
+Full rule set and worked examples: the `asd-ste100` skill (`~/.claude/skills/asd-ste100/SKILL.md` on a maintainer machine). This table is the condensed version for day-to-day drafting.
+
+| Rule                         | Do                                                                        | Don't                                                                          |
+| ---------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| One word, one meaning        | Pick one verb for one action and reuse it every time                      | Rotate synonyms for the same idea ("check" / "verify" / "confirm")             |
+| Active voice                 | "The gate blocks the merge."                                              | "The merge is blocked (by the gate)."                                          |
+| Simple tenses only           | "The validator read the file."                                            | "The validator has read the file."                                             |
+| One instruction per sentence | "Open the file. Read line 3."                                             | "Open the file and read line 3, then check if it matches."                     |
+| Sentence length              | Keep instructions and procedures at 20 words or fewer                     | Long compound or subordinate-clause sentences                                  |
+| Noun clusters                | 3 words or fewer stacked as a noun phrase                                 | 4 or more words stacked ("catalog reference graph node loadWhen trigger text") |
+| No ellipsis                  | Keep the subject, verb, and article explicit                              | Drop words to save space                                                       |
+| Lists for sequences          | Use a numbered or bulleted list for 3 or more steps                       | Bury a sequence inside one prose sentence                                      |
+| Domain terms                 | Keep necessary technical nouns, but define an unfamiliar one on first use | Use jargon without ever defining it                                            |
+
+## 4. Self-Check Before Committing
+
+- Does every sentence have one reading, not two?
+- Does every verb use active voice and a simple tense?
+- Is every instruction sentence 20 words or fewer?
+- Would a reader outside this repo's context still parse each sentence correctly on the first read?
+- Did the edit keep every fact, condition, and scope qualifier from the original, with no silently dropped precision?
+
+A rewrite can drop required precision: a safety condition, a scope qualifier, a number. When that risk appears, keep the longer phrasing instead and note why nearby. Do not cut precision just to hit the word count.
+
+## 5. What This Does Not Govern
+
+- Founder-facing copy, marketing copy, and brand voice — `no-slop-writing.md`.
+- The repo's public front door (root `README.md`/`CONTRIBUTING.md`/`.github/SECURITY.md`/`.github/CODE_OF_CONDUCT.md`/`AGENTS.md`/`CLAUDE.md`) — `no-slop-writing.md` §2. README technical examples keep exact commands. Do not run this file's 20-word scan on the whole README.
+- Code comments — normal engineering documentation standards, per `no-slop-writing.md` §8.
+- Legally required text (privacy policy, terms, disclosures) — `privacy-terms.md`.
+
+## 6. Enforcement Status
+
+Every workflow node with a `loadWhen` that covers §2's files loads this file before drafting. A second layer sits on top: `check:documentation-ste100` (`checks/validation/business/engineering/check-technical-docs-ste100.ts`). This script checks two rules from §3 by machine, without judgment. Rule one: sentence length. Rule two: present-perfect tense, a `has`, `have`, or `had` plus a past-participle shape.
+
+The checker cannot tell an instruction sentence from a reference sentence. So it applies §3's 20-word ceiling to every sentence in a governed file, not only to instructions and procedures. That is a stricter, blanket version of the authored rule, never a looser one. The other rules in §3 stay judgment-only: one word per meaning, active voice, and noun-cluster length. `no-slop-rules.ts` documents the same limit for the sibling standard, for the same reason. A regex would punish good writing as often as it catches bad writing.
+
+The gate runs at two tiers, the same split `check-no-slop.ts` uses for its own front door.
+
+- **Error** tier applies today to one file only: this reference, the one file it can currently guarantee compliant.
+- **Warning** tier applies to the rest of the governed surface: `docs/architecture.md`, `docs/validators.md`, and every `knowledge/**/*.md` file outside `knowledge/words/`. That directory keeps `no-slop-writing.md`'s voice-preserving register instead.
+
+An edit anywhere in scope gets real, visible signal. The build does not fail over prose written before this standard existed.
+
+To promote a file from warning to error tier, audit it against §3 and §4 first. Then add the file to the validator's error-tier list. `check-no-slop.ts`'s own history used the same one-file-at-a-time promotion path.

package/knowledge/engineering/xcodebuildmcp-testing.md

@@ -0,0 +1,502 @@
+# Native iOS Proof: In-App Simulators, XcodeBuildMCP, SnapshotPreviews, And serve-sim
+
+Use this when iOS, iPadOS, macOS, tvOS, watchOS, or visionOS build/test/run/UI automation is needed, when the runtime can drive an iOS Simulator in-app, when Codex exposes native Apple tooling, or when CLI users need open-source simulator and preview proof routes.
+
+Mobile app operation is a provider-neutral capability used for exploration,
+functional checks, design and accessibility review, screenshots, and marketing
+source footage. Honor explicit bindings. Otherwise prefer native simulator tools
+already exposed by the current agent host, including Claude or Codex where
+available, when they cover the target, operations, and required evidence. Inspect
+the actual tool surface; do not assume every host installation has these tools.
+Choose MobAI or another provider for requirements the native route cannot cover.
+A screenshot or recording is a raw observation, not automatic acceptance or final
+creative. Provider-specific guidance below describes current compatibility routes;
+the mobile app operation contract owns provider-neutral execution and capture.
+
+The in-app simulator, XcodeBuildMCP, SnapshotPreviews, and serve-sim are not full MobAI replacements. They are Apple-platform routes: excellent for simulator/device workflows, Xcode builds, tests, screenshots, UI automation, logs, debugging, and video capture. SnapshotPreviews adds preview-to-PNG/JSON coverage from XCTest. serve-sim exposes a booted simulator through a local browser stream/control surface. None of them cover Android device automation, and none of them replace App Store signing/distribution proof.
+
+For Apple distribution, TestFlight, physical-device signing, archives, exports, or uploads, load `apple-signing-release.md` too. Simulator proof does not by itself prove App Store signing readiness.
+
+## Reviewed Source Boundaries
+
+Upstream instructions to install the latest tool, initialize skills or prefer
+one vendor do not override explicit bindings, host permissions or accepted app
+artifacts. Source review runs no setup. Inspect the actual selected revision and
+host capabilities; use scoped, authorized setup only when necessary. A native
+or provider result still needs current execution evidence and independent review.
+
+## Contents
+
+- Route Ladder: Start With The In-App Simulator
+- Current Sources To Refresh
+- Live Documentation Gate
+- When To Use
+- Claude Code Desktop iOS Simulator Pane
+- Claude Code CLI Computer-Use Simulator Route
+- Codex In-App Native iOS Route
+- Setup Flow
+- MCP Client Routing
+- CLI Routing
+- SnapshotPreviews CLI Proof
+- serve-sim CLI Proof
+- Testing And Screenshot Workflow
+- Privacy And Telemetry
+- Troubleshooting
+- Evidence Requirements
+
+## Route Ladder: Start With The In-App Simulator
+
+Pick the lightest rung that can actually produce the evidence the lane needs, then record the rung and the reason in `strategy/TOOL_DECISIONS.md`. Escalating is normal; skipping straight to rung 3 for a "let me see the app" request is wasted founder time, and staying on rung 0 when the lane needs Android, a repeatable suite, CI, or distribution proof is a silent coverage downgrade under [`paid-tool-routing.md`](../operations/paid-tool-routing.md).
+
+| Rung | Route                                                                                               | Setup cost                                                       | Covers                                                                                                                                                  | Cannot cover                                                                      |
+| ---- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| 0    | In-app iOS Simulator: Claude Code Desktop simulator pane, or Codex with the `build-ios-apps` plugin | none beyond Xcode and the iOS platform                           | build, install, launch, tap/type/scroll, read the screen, screenshots, screen recordings, simulator logs                                                | Android, physical devices, signing/distribution, repeatable regression suites, CI |
+| 1    | Claude Code CLI `computer-use`                                                                      | enable one built-in MCP server, grant two macOS permissions      | the same simulator work from a terminal session                                                                                                         | rung 0's gaps, plus it holds a machine-wide screen-control lock                   |
+| 2    | XcodeBuildMCP MCP tools or CLI                                                                      | install plus `xcodebuildmcp setup`                               | scripted and CI Apple builds, tests, UI automation, logs, video, deterministic project discovery, **physical Apple devices over USB/Wi-Fi**             | Android, distribution readiness                                                   |
+| 3    | SnapshotPreviews                                                                                    | XCTest target wiring                                             | deterministic preview PNG/JSON coverage for SwiftUI/UIKit/AppKit previews                                                                               | runtime E2E, navigation, provider behavior                                        |
+| 3    | serve-sim                                                                                           | `serve-sim` (already bundled in Codex's `build-ios-apps` plugin) | a booted simulator visible and controllable at a browser URL, for remote-Mac or CLI agents                                                              | provider proof, distribution readiness                                            |
+| 4    | MobAI                                                                                               | desktop app, bridge, and tier selection                          | iOS **and Android**, `.mob` suites, AI test generation/healing, performance gates, CI, multi-device runs, polished demo recording, LLDB-style debugging | App Store signing/distribution                                                    |
+
+The rungs are a rough cost order, not a strict hierarchy. serve-sim is the clearest example: on the Codex side it is not an extra install at all, because the `build-ios-apps` plugin's simulator-browser skill shells out to it — check what the runtime already bundles before treating a rung as an escalation.
+
+The two capability deltas that decide most escalations are concrete, not stylistic: the in-app simulator drives **simulated devices only** (XcodeBuildMCP and MobAI reach physical hardware), and it has **no Android path at all** (only MobAI, or the repo's own emulator/ADB tooling, does). Everything else at rung 0 — build, launch, tap, type, screenshot, record, read logs — is real proof.
+
+Rung 0 and rung 4 answer different questions. Rung 0 answers "is this screen right, right now" in one turn. MobAI answers "does this journey still pass on iOS and Android next week" and owns the demo-video and performance-gate lanes. A launch package that needs both should use both; `mobai-toolbelt.md` stays the reference for everything at rung 4.
+
+Rung 0 is unavailable in cloud, SSH, and container sessions, because the agent is not running on the Mac that owns the simulators. When the current session cannot reach a local Mac, say so plainly and route to rung 2/4 on a machine that can, or record the device proof as blocked — do not narrate a simulator run that did not happen.
+
+## Current Sources To Refresh
+
+Refresh these before implementation because in-app simulator gates, XcodeBuildMCP versions, tool names, and client snippets change:
+
+- Claude Code Desktop iOS Simulator pane: `https://code.claude.com/docs/en/desktop-ios-simulator`
+- Claude Code CLI computer use: `https://code.claude.com/docs/en/computer-use`
+- Codex iOS Simulator debugging loop: `https://learn.chatgpt.com/use-cases/ios-simulator-bug-debugging`
+- Codex native development collection: `https://learn.chatgpt.com/use-cases/collections/native-development`
+- Codex Build iOS Apps plugin: `https://github.com/openai/plugins/tree/main/plugins/build-ios-apps`
+- GitHub: `https://github.com/getsentry/XcodeBuildMCP`
+- Installation: `https://xcodebuildmcp.com/docs/installation`
+- Setup: `https://xcodebuildmcp.com/docs/setup`
+- MCP clients: `https://xcodebuildmcp.com/docs/clients`
+- CLI usage: `https://xcodebuildmcp.com/docs/cli`
+- Configuration: `https://xcodebuildmcp.com/docs/configuration`
+- Tools reference: `https://xcodebuildmcp.com/docs/tools`
+- Workflows: `https://xcodebuildmcp.com/docs/workflows`
+- Troubleshooting: `https://xcodebuildmcp.com/docs/troubleshooting`
+- Privacy: `https://xcodebuildmcp.com/docs/privacy`
+- Skills: `https://xcodebuildmcp.com/docs/skills`
+- Local skill when installed: `xcodebuildmcp-cli`
+- SnapshotPreviews: `https://github.com/getsentry/SnapshotPreviews`
+- serve-sim: `https://github.com/EvanBacon/serve-sim`
+- Apple testing overview: `https://developer.apple.com/documentation/xcode/testing`
+- Apple test plans: `https://developer.apple.com/documentation/xcode/organizing-tests-to-improve-feedback`
+- Apple accessibility audits: `https://developer.apple.com/documentation/accessibility/performing-accessibility-audits-for-your-app`
+- Apple localization testing: `https://developer.apple.com/documentation/xcode/testing-localizations-when-running-your-app`
+- Apple performance tests: `https://developer.apple.com/documentation/xcode/writing-and-running-performance-tests`
+
+## Live Documentation Gate
+
+Before installation, setup, client configuration, CLI commands, tool names, privacy settings, skills, or screenshot/test proof, refresh the official docs above and the local CLI help when available. Do not treat this reference, the local `xcodebuildmcp-cli` skill, old transcripts, or project memory as version authority.
+
+Record in `engineering/PRODUCTION_READINESS.md` or `SCREENSHOTS.md`:
+
+- docs checked date
+- docs URLs used
+- official docs version/tag when shown
+- for the in-app simulator: the agent surface and app version, the plan/policy gate, the session type (local, not cloud/SSH), and the simulated device plus OS
+- installed version or install route: Homebrew, npm/npx, or existing binary
+- `xcodebuildmcp --help`, `xcodebuildmcp tools`, or MCP tool-list snapshot
+- SnapshotPreviews package URL/version/commit when used
+- serve-sim package version or `serve-sim` resolution when used
+- Xcode version, macOS version, simulator/device runtime, project/workspace, scheme, and configuration
+- command or tool-name differences between live docs, CLI help, MCP tools, and local skills
+
+When docs, CLI help, and MCP tool names disagree:
+
+- official docs plus the installed CLI help decide CLI syntax
+- exposed MCP tool schemas decide MCP tool-call names
+- local skill examples are only orientation
+- record the chosen command/tool route and mismatch in proof docs
+
+If current official docs or CLI help cannot be reached, mark setup as `blocked: docs refresh needed` or `provisional: docs unavailable`. Do not use memory-only command names for launch proof.
+
+## When To Use
+
+Use the in-app simulator (rung 0) first when:
+
+- the founder wants to see the app running, check a screen, walk a flow, or reproduce a bug
+- the session is local on a Mac with Xcode and the iOS platform installed
+- one-turn visual/interaction feedback is the point, not a stored regression suite
+- an implementation change needs a same-session "did this actually work" check before it is written up
+
+Use XcodeBuildMCP after the founder confirms the fallback when:
+
+- MobAI is intended but not available in the runtime
+- the task is Apple-platform only
+- the app needs scripted or CI simulator build/run/test proof
+- UI automation, accessibility tree snapshots, screenshots, videos, or logs are needed
+- LLDB/debugging or crash/log triage is needed
+- the repo needs deterministic Xcode project discovery and session defaults
+
+Do not silently switch from MobAI to XcodeBuildMCP or to the in-app simulator. Use `paid-tool-routing.md` first: an easier route that drops Android, suite repeatability, CI, or performance gates is a coverage decision, not a convenience.
+
+Do not treat SnapshotPreviews or serve-sim as distribution proof. SnapshotPreviews proves deterministic preview rendering and exports; serve-sim proves a booted simulator can be observed/controlled through a browser stream. Production-readiness still needs runtime app flow proof, backend/provider proof, signing proof when distribution is in scope, and founder-only gates.
+
+For Android:
+
+- use MobAI if available and approved
+- otherwise use Android emulator/ADB/UIAutomator/Appium-style project tooling if the repo already uses it
+- mark Android device proof blocked if no equivalent exists
+
+## Claude Code Desktop iOS Simulator Pane
+
+Refresh `https://code.claude.com/docs/en/desktop-ios-simulator` before quoting gates or shortcuts; the pane is in public beta and its version and plan gates move.
+
+The pane streams a live iOS Simulator next to the conversation. It drives the simulator directly rather than through screen control, so it never takes over the founder's screen or hides other windows.
+
+Gates to confirm before promising it (2026-07-25 docs basis):
+
+- Claude Code Desktop on macOS, Claude Desktop v1.24012.0 or later
+- Pro, Max, or Team plan; not available on Enterprise
+- Xcode installed with the iOS platform, so simulator devices exist
+- a **local** session — cloud and SSH sessions run on a machine that cannot reach the Mac's simulators
+- not disabled by a user settings toggle, the `disableMobileSimulatorTools` managed setting (managed settings only, JSON boolean `true`, not overridable in-app; the pane stays usable for the founder's own taps), or the `requireCoworkFullVmSandbox` policy key (disables the pane and the agent's simulator tools entirely)
+
+The docs do not publish tool names for the simulator tools. Describe the route by what it did — built, launched, tapped, screenshotted — and never invent a tool identifier to make proof look more precise than it is.
+
+**Rung 0 is a do-it action, not a proposal.** "Can you run it and show me the new screen?" is answered by running it and showing the screen, not by describing the route you would take and asking whether to start — that is the Autopilot Run Contract's "do not stop with instructions", and it bites hardest here because this is the one route with no setup to negotiate. Skip the pre-work a heavier rung would need: no tool install, no tier choice, no `check:skill-version` gate (a one-screen look is not the "substantial launch/design/store/revenue/build work" that gate covers), and no repo archaeology beyond finding the scheme. Build, run, capture, report. Contract follow-ups — the onboarding review-prompt placement, the analytics catalog, `SCREENSHOTS.md` — come after the founder has seen the screen, not before.
+
+There is no command or setting that opens the pane. Ask for the outcome and it opens when the app launches:
+
+```text
+Build the app and run it in the simulator to check the onboarding flow.
+```
+
+```text
+Run it on the iPhone SE simulator and tap through signup; screenshot each step.
+```
+
+Naming a device in the request targets that device. Once the session has a simulator attached or has edited Swift files, the session toolbar's **Views** menu also exposes an **iOS Simulator** entry with **Attach simulator** and a device picker.
+
+Operating notes:
+
+- Each device belongs to the session that launched it; up to 4 panes per session; devices Claude booted shut down on quit, on archive, or 10 minutes after detach, while devices the founder booted are never shut down automatically.
+- The founder can drive the same device: tap/swipe by click-drag, **Cmd+Shift+H** home, **Cmd+L** lock, **Cmd+Up/Down** volume, **Cmd+Right** rotate, **Cmd+S** screenshot, **Cmd+R** screen recording. Captures land on the Desktop; copy them into the repo before citing them as evidence.
+- Agent and founder share one device, so founder taps change the state the agent sees. While the **Claude is using this device** badge is showing, hold off.
+- Frame rate, resolution, and encoding controls change the stream, not the app; lower them before blaming the app for jank.
+
+Consent and privacy, which the launch package must respect:
+
+- The first use of a device asks for consent, once per device, covering control and screenshots.
+- **Screenshots of the device are sent to Anthropic and retained under normal conversation retention.** Use fixture or sandbox accounts only. Never sign a device the agent drives into a real founder, customer, store, bank, or provider account, and keep production credentials off it. Record the fixture-account decision in `engineering/PRODUCTION_READINESS.md`.
+- Two actions follow the session permission mode instead of the one-time consent: opening a URL on the device (a deep-link or Safari test can carry data off the device) and building the app (`xcodebuild` runs the project's build scripts on the Mac). Treat a deep-link test as a scoped action worth naming, not a silent step.
+- Claude drives simulated devices only. It cannot control a physical iPhone or iPad; physical-device runs stay a founder action from Xcode, with results described or screenshotted into the conversation.
+
+## Claude Code CLI Computer-Use Simulator Route
+
+Refresh `https://code.claude.com/docs/en/computer-use` first. From the CLI there is no pane: Claude reaches the Simulator through computer use, controlling it on screen the way a person would.
+
+Gates (2026-07-25 docs basis): macOS only, Pro or Max plan (not Team, not Enterprise), an interactive session (not `-p`), and claude.ai authentication rather than a third-party model provider.
+
+Enable it once per project:
+
+1. Run `/mcp`, select the built-in `computer-use` server, choose **Enable**.
+2. Grant the macOS **Accessibility** and **Screen Recording** permissions when prompted; Screen Recording may require restarting the session.
+3. Approve the Simulator app when the per-session app-approval prompt appears.
+
+Then state the flow, for example: `Open the iOS Simulator, launch the app, tap through the onboarding screens, and tell me if any screen takes more than a second to load.`
+
+Costs to weigh against rung 0: computer use holds a machine-wide lock until the session exits, hides other apps while it works, and downscales every screenshot. It is the right rung when the founder is already in a terminal session; it is not better proof than the pane.
+
+## Codex In-App Native iOS Route
+
+Refresh `https://learn.chatgpt.com/use-cases/ios-simulator-bug-debugging` and the plugin repo before quoting the setup.
+
+Codex's in-app simulator loop is XcodeBuildMCP plus the `build-ios-apps` plugin (`https://github.com/openai/plugins/tree/main/plugins/build-ios-apps`), which wraps the iOS debugger agent workflow: discover the project/workspace and schemes, find or boot a simulator, build, install, launch, relaunch with log capture, resolve bundle IDs, read the accessibility hierarchy, screenshot, tap/type/scroll/gesture, stream simulator logs, attach LLDB, set breakpoints, and inspect stack frames and variables. The plugin bundles a set of skills beyond the debugger — simulator-in-browser mirroring (which shells out to `serve-sim`), SwiftUI preview browsing, performance tracing, memory-leak triage, App Intents, and SwiftUI refactor/pattern skills — so check the plugin's own skill list before installing serve-sim or a tracing tool separately. A parallel `build-macos-apps` plugin exists for macOS targets. No plan or subscription gate is documented for the plugin; XcodeBuildMCP must be configured with the simulator, UI automation, debugging, and logging workflows.
+
+Prerequisites the docs name: an Xcode project or workspace with configured schemes, a booted simulator or the ability to boot one, and test credentials/fixtures when the flow needs an account.
+
+When Codex exposes native Apple/XcodeBuildMCP tools, prefer those tools over shell commands: tool schemas define the current command surface and keep simulator/build/log state visible in the agent runtime.
+
+Required sequence:
+
+1. Call `session_show_defaults` before the first build, run, or test.
+2. If project/workspace, scheme, and simulator defaults are set, call `build_run_sim`, `test_sim`, screenshot, UI snapshot, or log tools directly.
+3. Use discovery tools only when defaults are missing, wrong, or stale.
+4. Do not manually boot/open Simulator as a prerequisite for `build_run_sim`; the tool handles that where supported.
+5. Read the accessibility hierarchy before interacting, and prefer stable labels over raw coordinates.
+6. Keep one concrete bug per debugging session with clear repro steps and expected behavior, let the loop own the full reproduce-patch-verify cycle rather than hand-driving intermediate steps, and ask for the screenshot, log, or stack trace alongside the fix. Critical patches still get human review.
+7. Record the exposed tool names, project/workspace, scheme, simulator/device, OS/runtime, build configuration, screenshots/log paths, and any fallback in `engineering/PRODUCTION_READINESS.md`.
+
+In-app native iOS proof — Claude pane or Codex plugin — can satisfy Apple simulator implementation proof when paired with the relevant backend/provider proof. It does not replace MobAI for Android coverage, App Store signing readiness, archive/export/upload proof, TestFlight proof, or founder approval gates.
+
+## Setup Flow
+
+Refresh the Live Documentation Gate first. Preferred install options below are examples from current docs, not permanent requirements:
+
+```bash
+brew tap getsentry/xcodebuildmcp
+brew install xcodebuildmcp
+```
+
+or:
+
+```bash
+npm install -g "xcodebuildmcp@<reviewed-version>"
+xcodebuildmcp --help
+```
+
+Verify the environment using the current docs:
+
+```bash
+xcodebuildmcp-doctor # selected compatible installation, not an implicit latest download
+```
+
+or:
+
+```bash
+xcodebuildmcp-doctor
+```
+
+Run setup in the project root:
+
+```bash
+xcodebuildmcp setup
+```
+
+The setup wizard creates or updates `.xcodebuildmcp/config.yaml` with enabled workflows, project/workspace path, scheme, configuration, simulator defaults, and debug options. Commit this config only when it contains repo-safe defaults and no secrets.
+
+Record whether setup used Homebrew, npm/npx, an existing binary, or an MCP client-managed `npx` command. If `xcodebuildmcp upgrade` or another update route is needed, use the current official docs before running it.
+
+## MCP Client Routing
+
+When MCP tools are exposed, prefer the tools over raw shell.
+
+Important sequence:
+
+1. Call `session_show_defaults` before the first XcodeBuildMCP build, run, or test in a session.
+2. If project/workspace, scheme, and simulator defaults are set, call `build_run_sim` or the relevant one-shot tool directly.
+3. Use discovery tools only when defaults are missing or wrong.
+4. Do not manually boot/open Simulator as a prerequisite for `build_run_sim`; the tool handles it where needed.
+5. Enable only required workflows to control tool-list context: simulator by default, then device, debugging, ui-automation, swift-package, macos, coverage, or xcode-ide when needed.
+
+Current client snippets include:
+
+- Claude Code: `claude mcp add XcodeBuildMCP -- npx -y "xcodebuildmcp@<reviewed-version>" mcp`
+- Codex CLI: `codex mcp add XcodeBuildMCP -- npx -y "xcodebuildmcp@<reviewed-version>" mcp`
+- Codex config: `[mcp_servers.XcodeBuildMCP]` with `command = "npx"` and `args = ["-y", "xcodebuildmcp@<reviewed-version>", "mcp"]`
+
+If Codex or Xcode agent tools time out, current docs recommend raising `tool_timeout_sec`.
+
+## CLI Routing
+
+Use the CLI when MCP tools are not exposed or when scripting/CI is simpler. Load the local `xcodebuildmcp-cli` skill when available, but let live docs and local `--help` override stale examples.
+
+Discovery:
+
+```bash
+xcodebuildmcp --help
+xcodebuildmcp tools
+xcodebuildmcp simulator --help
+xcodebuildmcp ui-automation --help
+```
+
+Common commands:
+
+```bash
+xcodebuildmcp setup
+xcodebuildmcp simulator build --scheme MyApp --project-path ./MyApp.xcodeproj --simulator-name "iPhone 17 Pro"
+xcodebuildmcp simulator build-and-run --scheme MyApp --project-path ./MyApp.xcodeproj
+xcodebuildmcp simulator test --scheme MyApp --project-path ./MyApp.xcodeproj --simulator-name "iPhone 17 Pro"
+xcodebuildmcp simulator record-video --simulator-id <UDID> --output-path ./session.mp4
+xcodebuildmcp ui-automation snapshot-ui --simulator-id <UDID>
+xcodebuildmcp ui-automation screenshot --simulator-id <UDID> --return-format path
+```
+
+Use `--json` for complex arguments and `--output jsonl` for long-running operations that should stream machine-readable progress.
+
+If the CLI shows commands such as `simulator build-and-run` while an MCP tool or local skill uses names such as `build_run_sim`, do not mix the forms. Use CLI names only in shell commands and MCP tool names only in MCP calls.
+
+## SnapshotPreviews CLI Proof
+
+Use SnapshotPreviews when a SwiftUI/UIKit/AppKit app has Xcode previews and CLI/CI needs deterministic visual proof without writing one-off screenshot tests. SnapshotPreviews is preview coverage: it exercises previews through XCTest, exports PNG and JSON sidecars, and can feed Sentry Snapshots or another visual diffing service. It is not runtime E2E proof and does not prove navigation, network, entitlement, analytics, or provider behavior.
+
+Refreshed source summary:
+
+- Repository URL in docs: `https://github.com/EmergeTools/SnapshotPreviews`; the requested GitHub location is `https://github.com/getsentry/SnapshotPreviews`.
+- Link the XCTest target to `SnapshottingTests`.
+- Create a test class inheriting from `SnapshotTest` for PNG/JSON snapshot export, or `PreviewLayoutTest` for preview rendering checks without PNGs.
+- Set `TEST_RUNNER_SNAPSHOTS_EXPORT_DIR` on `xcodebuild test` to write the images and sidecars to disk.
+
+Example shape, after refreshing the repository README and local Xcode/project details:
+
+```bash
+TEST_RUNNER_SNAPSHOTS_EXPORT_DIR="$PWD/snapshot-images" \
+xcodebuild test \
+  -scheme MyApp \
+  -sdk iphonesimulator \
+  -destination 'platform=iOS Simulator,name=iPhone 15 Pro'
+```
+
+Record in `engineering/PRODUCTION_READINESS.md`:
+
+- package URL/version/commit
+- target and test class: `SnapshotTest` or `PreviewLayoutTest`
+- preview module filter, excluded previews, fixtures, and deterministic-data controls
+- export directory such as `snapshot-images`
+- PNG/JSON output paths and diff/upload result if Sentry Snapshots is used
+- limitation: preview-only coverage; does not replace runtime E2E, provider proof, or App Store signing readiness
+
+SnapshotPreviews is especially useful before screenshot composition because it catches broken SwiftUI preview states and can generate reusable UI evidence for component states. It is not a substitute for raw real-app captures for App Store screenshots unless the asset is explicitly a preview/component proof and the limitation is recorded.
+
+## serve-sim CLI Proof
+
+The reviewed package README requires macOS, Xcode command-line tools and an
+Apple Silicon host. Check the selected release's requirements before promising
+Intel support. Xcode-specific keyboard behavior and host accessibility settings
+need separate inspection. Select a single simulator explicitly. A stream may
+contain sensitive data; use synthetic accounts and a scoped local endpoint.
+LAN/tunnel exposure, webcam capture, injected camera helpers and host permission
+changes require separate authorization and are not part of screenshot adoption.
+
+Use serve-sim when CLI users need a booted iOS Simulator visible and controllable through a browser surface, especially for Codex CLI, Claude Code, Cursor, or remote Mac flows where the agent needs a URL instead of a local Simulator window.
+
+Refreshed source summary:
+
+- Run the explicitly selected, already installed `serve-sim` executable; the default preview is `http://localhost:3200`. An unpinned `npx` download is not a version selection.
+- Requires macOS with Xcode command line tools (`xcrun simctl`) and Node.js 18+.
+- Works with any booted iOS Simulator and does not require app instrumentation.
+- Streams simulator framebuffer through MJPEG plus a WebSocket control channel and forwards simulator logs to the browser UI.
+- CLI supports gestures, button presses, typing, rotation, CoreAnimation debug flags, memory warnings, and camera injection.
+
+Common commands from the current README:
+
+```bash
+# Examples after selecting the compatible executable and one target.
+serve-sim "<selected-device>"
+serve-sim --detach "<selected-device>"
+serve-sim --list "<selected-device>"
+# Do not stop other simulator sessions; cleanup must target this run.
+serve-sim type "Hello, world!" -d "<selected-udid>"
+serve-sim button home -d "<selected-udid>"
+```
+
+Record in `engineering/PRODUCTION_READINESS.md` or `SCREENSHOTS.md`:
+
+- package/version or `serve-sim` resolution
+- simulator/device name or UDID and proof it was booted
+- preview URL/port such as `http://localhost:3200`
+- browser screenshot/video/log capture path
+- actions run through `serve-sim gesture`, `serve-sim button`, `serve-sim type`, or camera injection when used
+- limitation: browser-visible simulator proof does not replace backend/provider proof, MobAI Android proof, App Store signing, archive/export/upload, or TestFlight proof
+
+If serve-sim is used for app-preview or store screenshot source footage, keep raw simulator captures separate from final composed assets and still run the store screenshot validator. Generated art can support the frame, but real app UI must remain visible and truthful.
+
+## Testing And Screenshot Workflow
+
+For production-readiness proof: 0. Pick the rung from the Route Ladder. For a single flow check on a local Mac, ask the in-app simulator to run the app and skip steps 1 and 2 entirely — that is the whole point of rung 0.
+
+1. Run doctor and setup if the environment is new.
+2. Confirm session defaults or CLI config.
+3. Build and run the app on the target simulator/device.
+4. Run unit and UI tests where available.
+5. Use UI automation snapshots before gestures.
+
+Before calling native engineering done, complete the launch-critical matrix in `engineering/PRODUCTION_READINESS.md`: a named prerelease `.xctestplan`; unit/integration/UI/performance targets; device/OS/locale and light/dark/Dynamic Type variants; accessibility audit; permission allowed/denied; offline/error/retry; deep-link/notification/background/foreground/interruption paths; StoreKit local plus sandbox/TestFlight entitlement/restore/refund state; performance budgets; and Release-configuration physical-device coverage or a named blocker. Record existing `.xcresult`, screenshot/video, log, metrics JSON, and provider-correlation paths. A tool invocation or simulator compile is not journey proof. 6. Capture screenshots/video only after the target state is reached. 7. Use SnapshotPreviews for preview coverage when previews exist, and record that it is preview-only coverage. 8. Use serve-sim when a browser-visible simulator/control surface is useful for CLI agents or remote Mac workflows. 9. Pair device proof with backend/provider proof: database, RevenueCat, Stripe, PostHog, Resend, Sentry, or store-console evidence when in scope. 10. Record command/tool output paths, simulator/device, OS, scheme, build config, account fixture, and result in `engineering/PRODUCTION_READINESS.md` and `SCREENSHOTS.md`.
+
+### Test Triage Protocol
+
+When UI tests crash with signal kill, time out, or flake, escalate in order — do not loop the full suite on a crashing run:
+
+1. **Unit tests first**, in isolation (`-only-testing:<Scheme>Tests`). A clean unit run proves logic but NOT paywall entitlement, RevenueCat offering load, or attribution persistence.
+2. **Short isolated UI tests second.** Keep each XCUITest interaction under ~20s of wall-clock; longer sequences hit `signal kill` from simulator memory pressure.
+3. **Full suite last**, once — only after units + isolated UI pass.
+4. **A green suite is not contract proof.** If the suite passes while RevenueCat returns zero packages, the paywall shows "Purchases unavailable", or PostHog person properties lack `self_reported_source`, open a `test-suite-green-contracts-unproven` failure card and require backend/provider proof before any paywall/attribution-ready claim.
+
+**120s MCP tool timeout — manual fallback.** XcodeBuildMCP MCP tools time out at ~120s; post-clean-cache builds exceed it. When `test_sim`/`build_run_sim` times out: `build_sim` (build only) → `install_app_sim` (built `.app`) → `launch_app_sim` → `get_simulator_logs`/`tail_logs`. Record the fallback route in `engineering/PRODUCTION_READINESS.md`.
+
+**xcresulttool syntax (Xcode 16 / 26).** Read test summaries with `xcresulttool get test-results summary --path <bundle.xcresult>`; refresh `xcresulttool --help` before scripting result parsing.
+
+For App Store screenshot work:
+
+- in-app simulator captures (pane **Cmd+S**/**Cmd+R**, or the Codex screenshot tool) are valid raw real-app UI; copy them off the Desktop into the repo's raw capture directory and record the device, OS, locale, and fixture account
+- use real app UI from XcodeBuildMCP captures when MobAI is not approved/available
+- compose final screenshots through `DESIGN.md` tokens and screenshot HTML
+- keep raw captures separate from final upload assets
+- map each final image to Apple display wells and Google device classes
+- a simulator capture is a simulated device: confirm the display well's pixel dimensions before upload rather than assuming the pane's stream resolution matches Apple's required size
+
+## Privacy And Telemetry
+
+Current XcodeBuildMCP docs state that it uses Sentry for internal runtime error telemetry only. They state that project build/test failures, tool inputs/outputs, environment variables, source code, build artifacts, certificates, and provisioning profiles are not sent.
+
+Opt out when the launch/privacy posture requires it:
+
+```bash
+export XCODEBUILDMCP_SENTRY_DISABLED=true
+```
+
+or add:
+
+```yaml
+sentryDisabled: true
+```
+
+to `.xcodebuildmcp/config.yaml`.
+
+Record the telemetry decision in `strategy/TOOL_DECISIONS.md` or `engineering/PRODUCTION_READINESS.md`.
+
+## Troubleshooting
+
+In-app simulator (rung 0), before escalating:
+
+- the pane not opening usually means the request was not phrased as running the app; restate it explicitly ("run the app in the iOS Simulator and tap through the signup flow")
+- confirm Xcode and the iOS Simulator work standalone by launching Apple's Simulator app
+- "no simulators were found" means Xcode has no iOS runtime: install it from Xcode's settings or run `xcodebuild -downloadPlatform iOS`
+- check the desktop app version against the current docs gate, and check whether an organization policy (`disableMobileSimulatorTools`, `requireCoworkFullVmSandbox`) disabled the simulator tools
+- a cloud, SSH, or container session cannot reach a local simulator at all; that is a routing fact, not a bug to retry
+
+Current XcodeBuildMCP docs recommend:
+
+- run `xcodebuildmcp-doctor` or the MCP `doctor` tool
+- confirm Xcode and Command Line Tools are installed
+- verify required workflows in `.xcodebuildmcp/config.yaml`
+- check simulator/device availability and permissions
+- enable workflows such as `["simulator", "device", "debugging", "ui-automation"]` when tools are missing
+- use a `zsh -lc` wrapper and known `PATH` for Xcode/Codex agent environments that cannot find `npx`
+- open Xcode and configure signing when device builds fail with signing errors
+- restart stale simulators or the XcodeBuildMCP daemon when stateful tools get stuck
+
+Do not flatten these into "Xcode is broken". Record the exact doctor finding and next action.
+
+## Evidence Requirements
+
+`engineering/PRODUCTION_READINESS.md` should include:
+
+- in-app simulator route when used: the agent surface and app version, the plan/policy gate cleared, that it was a local session (not cloud or SSH), the simulated device and OS, the fixture/sandbox account used instead of a real account, the exported screenshot/recording paths now committed in the repo, and the coverage this route does not provide (no Android, no physical device, no distribution readiness)
+- Codex in-app native iOS route when used: `session_show_defaults`, exposed MCP tool names, project/workspace, scheme, simulator/device, and screenshot/log/test paths
+- XcodeBuildMCP version or install route
+- docs refreshed date, official docs URLs, and docs version/tag when shown
+- CLI/help or `xcodebuildmcp tools` snapshot used to choose commands
+- any local skill/docs mismatch and the selected command/tool route
+- doctor status or blocker
+- MCP or CLI route
+- enabled workflows
+- project/workspace, scheme, simulator/device, OS, configuration
+- command/tool names and outcomes
+- logs, screenshots, videos, UI snapshots, and test result paths
+- SnapshotPreviews package URL/version/commit, `SnapshotTest` or `PreviewLayoutTest` target, `TEST_RUNNER_SNAPSHOTS_EXPORT_DIR`, exported PNG/JSON paths, and preview-only limitation when used
+- serve-sim package/version, booted simulator/device, preview URL/port, gesture/type/button commands, stream/log evidence paths, and limitation when used
+- backend/provider proof paired to app actions
+- Apple signing proof when distribution is in scope: Team ID, `DEVELOPMENT_TEAM`, bundle ID/App ID, app record, signing style, local signing identity class, provisioning strategy, archive/export/upload/TestFlight status, and any `store/APPLE_SIGNING.md` blocker
+- telemetry decision
+- remaining blocked flows
+
+`SCREENSHOTS.md` should include:
+
+- raw capture path
+- final composition path
+- device/display well
+- headline/copy overlay and App Icon/App Preview route when store creative is in scope
+- locale, theme, fixture, screen path
+- upload readiness