@iwsdk/create 1.1.0 → 1.2.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. package/README.md +68 -16
  2. package/dist/cli.js +7917 -3404
  3. package/dist/guidance/{agents → files}/.agents/skills/iwsdk-build-model/SKILL.md +1 -0
  4. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-compose-scene/SKILL.md +3 -2
  5. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-debug/SKILL.md +1 -0
  6. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-depth-occlusion/SKILL.md +1 -0
  7. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-dev/SKILL.md +1 -0
  8. package/dist/guidance/{agents → files}/.agents/skills/iwsdk-dev/references/api-reference.md +8 -1
  9. package/dist/guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +96 -0
  10. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-dev/references/iterate.md +16 -7
  11. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-dev/references/planner.md +9 -5
  12. package/dist/guidance/{agents → files}/.agents/skills/iwsdk-glasses-test/SKILL.md +1 -0
  13. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-grab/SKILL.md +1 -0
  14. package/dist/guidance/{agents → files}/.agents/skills/iwsdk-hosting/SKILL.md +3 -1
  15. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-native-xr-test/SKILL.md +17 -1
  16. package/dist/guidance/files/.agents/skills/iwsdk-offline/SKILL.md +217 -0
  17. package/dist/guidance/files/.agents/skills/iwsdk-offline/assets/offline.ts.template +99 -0
  18. package/dist/guidance/files/.agents/skills/iwsdk-offline/assets/sw.js.template +241 -0
  19. package/dist/guidance/files/.agents/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
  20. package/dist/guidance/files/.agents/skills/iwsdk-offline/references/build-step.md +71 -0
  21. package/dist/guidance/files/.agents/skills/iwsdk-offline/references/page.md +70 -0
  22. package/dist/guidance/files/.agents/skills/iwsdk-offline/references/service-worker.md +107 -0
  23. package/dist/guidance/files/.agents/skills/iwsdk-offline/references/testing.md +57 -0
  24. package/dist/guidance/{agents → files}/.agents/skills/iwsdk-physics/SKILL.md +1 -0
  25. package/dist/guidance/{agents → files}/.agents/skills/iwsdk-physics/references/tuning-and-config.md +1 -0
  26. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-physics/references/workflows.md +9 -3
  27. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-pwa-packaging/SKILL.md +13 -1
  28. package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +1 -1
  29. package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +30 -0
  30. package/dist/guidance/{agents → files}/.agents/skills/iwsdk-ray/SKILL.md +1 -0
  31. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-ui/SKILL.md +17 -7
  32. package/dist/guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
  33. package/dist/guidance/{claude → files}/.claude/agents/iwsdk-project-code-reviewer.md +1 -0
  34. package/dist/guidance/{claude → files}/.claude/rules/assets-and-manifest.md +3 -0
  35. package/dist/guidance/{claude → files}/.claude/rules/ecs-api.md +1 -0
  36. package/dist/guidance/{claude → files}/.claude/rules/scene-json.md +1 -0
  37. package/dist/guidance/{claude → files}/.claude/rules/uikitml.md +1 -0
  38. package/dist/guidance/{claude → files}/.claude/settings.json +9 -3
  39. package/dist/guidance/{claude → files}/.claude/skills/iwsdk-build-model/SKILL.md +1 -0
  40. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-compose-scene/SKILL.md +3 -2
  41. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-debug/SKILL.md +1 -0
  42. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-depth-occlusion/SKILL.md +1 -0
  43. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-dev/SKILL.md +1 -0
  44. package/dist/guidance/{claude → files}/.claude/skills/iwsdk-dev/references/api-reference.md +8 -1
  45. package/dist/guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +96 -0
  46. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-dev/references/iterate.md +16 -7
  47. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-dev/references/planner.md +9 -5
  48. package/dist/guidance/{claude → files}/.claude/skills/iwsdk-glasses-test/SKILL.md +1 -0
  49. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-grab/SKILL.md +1 -0
  50. package/dist/guidance/{claude → files}/.claude/skills/iwsdk-hosting/SKILL.md +3 -1
  51. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-native-xr-test/SKILL.md +17 -1
  52. package/dist/guidance/files/.claude/skills/iwsdk-offline/SKILL.md +217 -0
  53. package/dist/guidance/files/.claude/skills/iwsdk-offline/assets/offline.ts.template +99 -0
  54. package/dist/guidance/files/.claude/skills/iwsdk-offline/assets/sw.js.template +241 -0
  55. package/dist/guidance/files/.claude/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
  56. package/dist/guidance/files/.claude/skills/iwsdk-offline/references/build-step.md +71 -0
  57. package/dist/guidance/files/.claude/skills/iwsdk-offline/references/page.md +70 -0
  58. package/dist/guidance/files/.claude/skills/iwsdk-offline/references/service-worker.md +107 -0
  59. package/dist/guidance/files/.claude/skills/iwsdk-offline/references/testing.md +57 -0
  60. package/dist/guidance/{claude → files}/.claude/skills/iwsdk-physics/SKILL.md +1 -0
  61. package/dist/guidance/{claude → files}/.claude/skills/iwsdk-physics/references/tuning-and-config.md +1 -0
  62. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-physics/references/workflows.md +9 -3
  63. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-pwa-packaging/SKILL.md +13 -1
  64. package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +1 -1
  65. package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +30 -0
  66. package/dist/guidance/{claude → files}/.claude/skills/iwsdk-ray/SKILL.md +1 -0
  67. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-ui/SKILL.md +17 -7
  68. package/dist/guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
  69. package/dist/guidance/{cursor → files}/.cursor/rules/assets-and-manifest.mdc +3 -0
  70. package/dist/guidance/{cursor → files}/.cursor/rules/ecs-api.mdc +1 -0
  71. package/dist/guidance/{cursor → files}/.cursor/rules/scene-json.mdc +1 -0
  72. package/dist/guidance/{cursor → files}/.cursor/rules/uikitml.mdc +1 -0
  73. package/dist/guidance/{copilot → files}/.github/instructions/assets-and-manifest.instructions.md +2 -1
  74. package/dist/guidance/{copilot → files}/.github/instructions/ecs-api.instructions.md +1 -0
  75. package/dist/guidance/{copilot → files}/.github/instructions/scene-json.instructions.md +1 -0
  76. package/dist/guidance/{copilot → files}/.github/instructions/uikitml.instructions.md +1 -0
  77. package/dist/guidance/{common → files}/AGENTS.md +107 -27
  78. package/dist/guidance/{scoped-agents → files}/public/scenes/AGENTS.md +2 -0
  79. package/dist/guidance/{scoped-agents → files}/public/ui/AGENTS.md +2 -0
  80. package/dist/guidance/{scoped-agents → files}/src/AGENTS.md +2 -0
  81. package/dist/guidance/manifest.json +954 -0
  82. package/dist/template/common/.codex/config.toml +2 -0
  83. package/package.json +5 -5
  84. package/scripts/verify-release-ready.mjs +1 -2
  85. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-build-model/agents/openai.yaml +0 -0
  86. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +0 -0
  87. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +0 -0
  88. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +0 -0
  89. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +0 -0
  90. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/image-intake.md +0 -0
  91. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +0 -0
  92. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/scene-format.md +0 -0
  93. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/scene-review.md +0 -0
  94. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/text-intake.md +0 -0
  95. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-hosting/references/existing-hosts.md +0 -0
  96. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-hosting/references/vercel.md +0 -0
  97. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-physics/references/component-reference.md +0 -0
  98. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +0 -0
  99. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +0 -0
  100. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +0 -0
  101. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-build-model/agents/openai.yaml +0 -0
  102. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +0 -0
  103. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +0 -0
  104. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +0 -0
  105. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +0 -0
  106. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/image-intake.md +0 -0
  107. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +0 -0
  108. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/scene-format.md +0 -0
  109. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/scene-review.md +0 -0
  110. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/text-intake.md +0 -0
  111. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-hosting/references/existing-hosts.md +0 -0
  112. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-hosting/references/vercel.md +0 -0
  113. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-physics/references/component-reference.md +0 -0
  114. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +0 -0
  115. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +0 -0
  116. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +0 -0
  117. /package/dist/guidance/{claude → files}/CLAUDE.md +0 -0
  118. /package/dist/{guidance/codex → template/common-js}/.codex/config.toml +0 -0
@@ -80,6 +80,12 @@ it on the headset after sideloading (step 4).
80
80
  `index.html` ships `<link rel="icon" href="data:," />` and no manifest link, so
81
81
  the app is not installable until step 3 adds them.
82
82
 
83
+ **Optional: launch offline.** The TWA loads `<DOMAIN>` over the network, so with
84
+ no connection an installed app shows an error page instead of the app. If it
85
+ must launch offline, add an offline copy with the `iwsdk-offline` skill before
86
+ packaging: one online launch then keeps the release on the device. Keep the
87
+ manifest's `start_url` and `scope` inside the service worker's scope.
88
+
83
89
  Then confirm the app itself is sound before wrapping it — `npm run --if-present typecheck`,
84
90
  and `npm run build` producing a `dist/` you have actually loaded. Packaging a
85
91
  broken build wastes a full round trip through hosting, signing, and upload.
@@ -191,6 +197,10 @@ retry the identical command. Tool download, auth, and flag reference:
191
197
  | App logic, assets, styling, manifest text, icons, asset links | republish `<DOMAIN>`; installed TWA picks it up next launch |
192
198
  | Package id, app name, launcher icon, version, **app mode**, signing | rebuild the APK and re-upload |
193
199
 
200
+ With an offline copy (`iwsdk-offline`), a republished release installs in the
201
+ background during a launch and takes over when the app is idle, or on the
202
+ launch after that.
203
+
194
204
  ## Security
195
205
 
196
206
  The keystore and the app secret never go near `public/` or `dist/`. After every
@@ -213,6 +223,8 @@ updated — only replaced by a new Store entry.
213
223
  | [`references/store-upload.md`](references/store-upload.md) | Step 5 — `ovr-platform-util`, auth, channels, the DDA blocker |
214
224
  | [`references/troubleshooting.md`](references/troubleshooting.md) | Anything installed but misbehaving — stuck loading, URL bar, will-not-launch |
215
225
 
216
- Getting the app online is the `iwsdk-hosting` skill. Building the app itself is
226
+ Getting the app online is the `iwsdk-hosting` skill, and keeping it working
227
+ offline is `iwsdk-offline`. Building the app itself is
217
228
  `iwsdk-planner` and the other `iwsdk-*` skills — do not re-derive IWSDK
218
229
  patterns here.
230
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=2fbb9b9e9245162fa8cdb51e0a1396dde89b3d459ad5bcc29b45b92ade7a0022 name=iwsdk-pwa-packaging (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -34,7 +34,7 @@ it is served at `/manifest.webmanifest` with no further wiring.
34
34
  | Field | Why it matters here |
35
35
  | ----- | ------------------- |
36
36
  | `name` / `short_name` | `short_name` is the launcher label; keep it under ~12 characters or it truncates |
37
- | `start_url` / `scope` | must match the hosting path — `/` at an origin root, `/<path>/` on a subpath deployment |
37
+ | `start_url` / `scope` | must match the hosting path — `/` at an origin root, `/<path>/` on a subpath deployment; with an offline copy (`iwsdk-offline`), both must also sit inside the service worker's scope |
38
38
  | `display` | `standalone` for both modes; `browser` forces a URL bar |
39
39
  | `background_color` | painted before first frame — match the app's clear color or launch flashes white |
40
40
  | `theme_color` | colors the custom tab bar on a 2D panel; add `theme_color_dark` if the app is dark-first |
@@ -10,6 +10,8 @@ symptoms, so start there.
10
10
  | Opens with a browser URL bar | `horizonOSAppMode: "2D"` on an immersive app | [App mode](#app-mode-failures) |
11
11
  | Opens flat, no URL bar, never enters VR | auto-enter code missing or not firing | [App mode](#app-mode-failures) |
12
12
  | Blank / white / error page | the origin is unreachable from the device | [Origin](#origin-failures) |
13
+ | Error page only when the headset is offline | no offline copy, or the app never launched online | [Offline](#offline-failures) |
14
+ | Old version after a web redeploy | an offline copy waiting for an idle moment or the next launch | [Offline](#offline-failures) |
13
15
 
14
16
  Before diagnosing, establish which layer is wrong. A **web** bug is fixed by
15
17
  republishing `<DOMAIN>`; a **native** bug needs a new APK and a new upload.
@@ -116,6 +118,34 @@ to `/<path>/` and republish. The scaffolded `base: './'` handles the bundle
116
118
  paths already, so if bundles load and only `public/` assets 404, look for a
117
119
  publish that missed those files.
118
120
 
121
+ ## Offline failures
122
+
123
+ These apply only when the site keeps an offline copy (`iwsdk-offline`).
124
+
125
+ ### Error page only when the headset is offline
126
+
127
+ The device has no copy to serve. Usually one of:
128
+
129
+ - **No offline copy** — the site registers no service worker. Add one with
130
+ `iwsdk-offline`.
131
+ - **The app never launched online** since the copy was added. The copy is made
132
+ on the first online launch.
133
+ - **`start_url` or `scope` sits outside the worker's scope**, so the launch
134
+ misses the copy. Serve `sw.js` from the root of that scope.
135
+
136
+ Confirm the worker is live and uncached:
137
+
138
+ ```bash
139
+ curl -sI https://<DOMAIN>/sw.js | grep -iE '^(HTTP|cache-control)' # want 200, no-cache
140
+ ```
141
+
142
+ ### Old version after a web redeploy
143
+
144
+ Expected for one launch: the new release installs in the background during a
145
+ launch and takes over when the app is idle, or on the launch after that. If it
146
+ never arrives, `sw.js` is being cached — serve it with `Cache-Control: no-cache`
147
+ and purge the CDN.
148
+
119
149
  ## Packaging failures
120
150
 
121
151
  ### bubblewrap hangs or exits without doing anything
@@ -67,3 +67,4 @@ When the request names an artifact path, save it directly with
67
67
  context and then add a copy step.
68
68
  Stop when the real input and resulting named state are proven, leaving all
69
69
  buttons released.
70
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=ec23dce5226ca91367042de7907fb3664c055a1ceb737fede2fd6710eab1f37f name=iwsdk-ray (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -186,8 +186,8 @@ views independently when both modes matter.
186
186
  ## Verify with a bounded loop
187
187
 
188
188
  Typecheck after the complete first slice, then start or reuse one managed
189
- session. If no command-ready session exists, run `npx @iwsdk/cli dev up --open`
190
- once. Do not call `dev --help`, separately call `dev open`, restart a healthy
189
+ session. If no command-ready session exists, run `npx @iwsdk/cli dev up` once,
190
+ with the `--ai-mode` that AGENTS.md's session rule picks. Do not call `dev --help`, separately call `dev open`, restart a healthy
191
191
  session, start a second browser, or build a custom UIKit renderer.
192
192
 
193
193
  1. Run `npx @iwsdk/cli ui assets --raw` once to confirm registration.
@@ -256,17 +256,26 @@ it.
256
256
 
257
257
  When the request asks for a poke (near touch) on a control, press it with the
258
258
  emulated hand's index fingertip by its element ID. The panel entity needs
259
- `PokeInteractable`:
259
+ `PokeInteractable`. Its `hand` field (`"both"`, the default, `"left"` or
260
+ `"right"`) limits which hand can poke it, for example a wrist menu that only
261
+ the other hand should press:
260
262
 
261
263
  ```bash
262
264
  npx @iwsdk/cli xr set-input-mode --input-json '{"mode":"hand"}'
263
265
  npx @iwsdk/cli xr run-sequence --input-json '{"device":"hand-right","steps":[{"target":"Btn_Action","press":{}}]}' --timeout 45000
264
266
  ```
265
267
 
266
- The press clicked when `presses[0].contactMs` is below 800; at 800 or more a
267
- slow headless frame held the touch too long, so run the press once more. Confirm
268
- the state change with `ui inspect`. `xr list-targets` lists the element IDs that
269
- can be pressed.
268
+ A press result reports contact, not a click: a `presses[0].contactMs` of 800 or
269
+ less does not prove the control clicked, because the fingertip can touch the
270
+ panel or a neighbouring control instead. Verify the click by the state it
271
+ changes, with `ui inspect` on the control or a query of the app state it
272
+ drives, and press once more if nothing changed. A contact of more than 800 ms
273
+ never clicks. A slow headless frame can hold the touch that long. So can a
274
+ press on a control out of reach: the body walks to it during the press (a
275
+ contact of seconds). Walk to such a control in a step of its own before the
276
+ press:
277
+ `"steps":[{"body":{"stepTo":"Btn_Action"}},{"target":"Btn_Action","press":{}}]`.
278
+ `xr list-targets` lists the element IDs that can be pressed.
270
279
 
271
280
  The commands in this section are the supported path. Do not call broad
272
281
  `iwsdk`, `ui`, `browser`, `ecs`, or `xr` help. If a shown command fails, use its
@@ -323,3 +332,4 @@ The final visual check must confirm:
323
332
  Finish with a passing typecheck and production build, no UIKit parser/resource
324
333
  errors, and concise runtime evidence. Remove temporary preview files or camera
325
334
  workarounds that are not deliverables.
335
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=9b79caeeedded4cb53e69688c7e5006daa1187c951a333ef06cbdb3063f062a2 name=iwsdk-ui (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -0,0 +1,74 @@
1
+ ---
2
+ name: iwsdk-upgrade
3
+ description: Upgrade an IWSDK app to a newer IWSDK release and prove it still works. Use when the user asks to upgrade, update or bump IWSDK or any @iwsdk/* package, when iwsdk dev up reports guidance updated from an older release, or when errors appear right after an IWSDK version change.
4
+ argument-hint: '[target version, default latest]'
5
+ ---
6
+
7
+ # Upgrade IWSDK
8
+
9
+ An upgrade has three parts: move the packages, apply what changed between the
10
+ two releases, and show that the app behaves as it did before. Do them in that
11
+ order.
12
+
13
+ ## 1. Record the baseline first
14
+
15
+ Before changing any version, check `git status`, make sure the user's work is
16
+ saved or committed (do not commit unless the user allowed it), and record how
17
+ the app behaves now: run its typecheck and build scripts with the project's
18
+ package manager (for example `npm run typecheck` and `npm run build`).
19
+
20
+ Write down every error, then start the dev server and save the browser log and
21
+ a runtime screenshot. Older apps often have errors that predate the upgrade;
22
+ without a baseline you cannot tell them from new ones, and proving it later
23
+ costs a full reinstall.
24
+
25
+ ## 2. Move the packages
26
+
27
+ ```bash
28
+ npx @iwsdk/cli@latest upgrade --dry-run
29
+ npx @iwsdk/cli@latest upgrade
30
+ ```
31
+
32
+ Always run it with `@latest`, even if the project has an older `@iwsdk/cli`:
33
+ the newest CLI carries every migration guide. For a specific release, add
34
+ `--to <version>` (`npx @iwsdk/cli@<version> upgrade` works only for releases
35
+ that include the `upgrade` command). It sets every `@iwsdk/*` package to the release, installs
36
+ with the project's package manager, aligns the `three` alias and an existing
37
+ `@types/three` with `@iwsdk/core`, refreshes this guidance, and writes to `.iwsdk/migrations/`:
38
+
39
+ - one `iwsdk-migrate-*/SKILL.md` for each release boundary that needs code
40
+ changes;
41
+ - `release-notes.md` with every change between the two versions.
42
+
43
+ It also checks `iwsdk.config.json` against the new release and lists settings
44
+ that no longer validate. Packages it reports as "not part of the IWSDK release"
45
+ were left as declared; remove one only if a migration guide says it was
46
+ retired. In a monorepo it installs with the workspace's package manager; if a
47
+ workspace-level override pins `three`, it tells you to change it.
48
+
49
+ If the user asked for a plain package-manager bump instead, do that, then run
50
+ `npx @iwsdk/cli@latest agents sync`; `iwsdk dev up` also refreshes unedited
51
+ guidance.
52
+
53
+ ## 3. Apply what changed
54
+
55
+ 1. Follow each migration guide in `.iwsdk/migrations/`, oldest first, before
56
+ other work.
57
+ 2. Read the major and minor entries in `release-notes.md` and check whether
58
+ the app uses what they change (renamed settings, new required versions,
59
+ changed defaults).
60
+ 3. Fix each `iwsdk.config.json` issue the upgrade listed.
61
+ 4. Re-read the `iwsdk-agent-guidance` block in `AGENTS.md`: it now describes
62
+ the new release. Do not hand-edit guidance files; an edited file stops
63
+ receiving updates.
64
+
65
+ ## 4. Prove it
66
+
67
+ Run the same checks as the baseline and compare. Report new errors and fix
68
+ them; report baseline errors separately as existing. A clean typecheck and
69
+ build do not show that the app renders: confirm the runtime screenshot and an
70
+ error-free browser log, and enter XR when the app is an XR app.
71
+
72
+ The upgrade is done when every migration guide is applied, the comparison
73
+ shows no new errors, and the user knows which existing errors remain.
74
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=5ccb37dbe152b3611496740e89bc8e42c8d59dfed8be7512635d877924b79988 name=iwsdk-upgrade (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -518,3 +518,4 @@ Only report issues you're confident about:
518
518
 
519
519
  [Brief summary of overall code quality and key recommendations]
520
520
  ```
521
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=976bd24f6ae91d050ed7bef71cdfb4cfab1fc41e4718d2042d9618860cb1161e name=iwsdk-project-code-reviewer.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -2,6 +2,8 @@
2
2
  paths:
3
3
  - "src/assets.ts"
4
4
  - "src/assets.js"
5
+ - "src/iwsdk/assets.ts"
6
+ - "src/iwsdk/assets.js"
5
7
  - "src/scene-assets/**"
6
8
  ---
7
9
 
@@ -55,3 +57,4 @@ mesh lowers to one `InstancedMesh`.
55
57
  Start assets at `castShadow: false` and opt in only for grounded focal masses.
56
58
  Don't build contact-shadow blob cards or `ShadowMaterial` catcher planes here: put
57
59
  `ContactShadow` or `ShadowCatcher` node components on the scene nodes instead.
60
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=9c0abbe2f1b3cc83f826ac6a5c24f0088375757ec17bfb970301a3c32b940a44 name=assets-and-manifest.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -100,3 +100,4 @@ buttons. Browser controls live at `world.input.keyboard` and
100
100
  `world.visibilityState` reports `NonImmersive`, `Visible`, `VisibleBlurred` —
101
101
  pause simulation on blur. `world.camera.position` is local to `world.player`; use
102
102
  `getWorldPosition()` when logic needs the true viewer position.
103
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=56f1044b9936f279404ef715676b734a119ef495824d5916737f3a00579acc64 name=ecs-api.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -69,3 +69,4 @@ back. Render each changed module before the root.
69
69
 
70
70
  For composing a scene rather than editing one, use the `iwsdk-compose-scene`
71
71
  skill — it owns the intake, review and stop-rule procedure this file does not.
72
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=d507943047667757a27a1b58cff203b0e3d1bdc646b0f5998cf0851840dde550 name=scene-json.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -63,3 +63,4 @@ can.
63
63
  For the authoring procedure — isolated preview, placement, editing, wiring
64
64
  runtime behavior, and the completion checklist — use the `iwsdk-ui` skill rather
65
65
  than improvising. This file is the format reference it relies on.
66
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=101e26d6362ef8867f020086e5edae81ae70c45a11e53339171da8591f41f1a6 name=uikitml.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -9,16 +9,22 @@
9
9
  "Skill(iwsdk-compose-scene)",
10
10
  "Skill(iwsdk-debug)",
11
11
  "Skill(iwsdk-depth-occlusion)",
12
+ "Skill(iwsdk-dev)",
12
13
  "Skill(iwsdk-glasses-test)",
13
14
  "Skill(iwsdk-grab)",
14
15
  "Skill(iwsdk-hosting)",
15
16
  "Skill(iwsdk-native-xr-test)",
17
+ "Skill(iwsdk-offline)",
16
18
  "Skill(iwsdk-physics)",
17
19
  "Skill(iwsdk-pwa-packaging)",
18
- "Skill(iwsdk-dev)",
19
20
  "Skill(iwsdk-ray)",
20
- "Skill(iwsdk-ui)"
21
+ "Skill(iwsdk-ui)",
22
+ "Skill(iwsdk-upgrade)"
21
23
  ]
22
24
  },
23
- "enabledMcpjsonServers": ["iwsdk-runtime", "iwsdk-reference", "metavr"]
25
+ "enabledMcpjsonServers": [
26
+ "iwsdk-runtime",
27
+ "iwsdk-reference",
28
+ "metavr"
29
+ ]
24
30
  }
@@ -309,3 +309,4 @@ Hand `iwsdk-compose-scene`:
309
309
 
310
310
  Do not compensate for a model-local defect with a scene transform. Do not start scene
311
311
  lighting or camera iteration until the model passes isolated review.
312
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=95fc72ddf1f3915aa71a839558a3ce051b803214b25ad8c594e882068a3d7917 name=iwsdk-build-model (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -122,8 +122,8 @@ npx @iwsdk/cli scene state --raw
122
122
  `iwsdk dev up` starts the server in the background and launches the configured
123
123
  managed editor browser. It can return while that browser is still starting; use
124
124
  `iwsdk runtime wait` or inspect `iwsdk runtime status` before browser-backed
125
- commands. Do not edit `vite.config.ts` to change browser mode as an ad hoc
126
- startup workaround.
125
+ commands. Pass the `--ai-mode` that AGENTS.md's session rule picks; do not edit
126
+ `vite.config.ts` to change browser mode as an ad hoc startup workaround.
127
127
 
128
128
  `scene_render_file` renders a file without replacing the editor's active document,
129
129
  but it still uses the managed editor browser for manifest evaluation and WebGL.
@@ -274,3 +274,4 @@ components, schema errors, image reconstruction, or ambiguous composition eviden
274
274
  When the Fast Path does not apply, read and follow
275
275
  [extended-workflow.md](references/extended-workflow.md). Do not load that reference
276
276
  for a routine scene assembled from known manifest assets.
277
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=e6feb83023b2ddbe9a3cceea3b0deda0fe8beb9743d4af6b8e0a89ea31e61b93 name=iwsdk-compose-scene (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -71,3 +71,4 @@ established from the measured state.
71
71
  Make at most one focused correction. Stop when the original symptom no longer
72
72
  reproduces and the measured state agrees with the intended behavior. Call
73
73
  `ecs_resume` before finishing and leave input buttons released.
74
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=7dd8250ca95e23b6f0696a86a3dfcb2d038ac730a7578118fb21290c6169c3f0 name=iwsdk-debug (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -85,3 +85,4 @@ not alter the project camera or render extra authored angles to manufacture an
85
85
  occlusion view; stage the requested nodes once, then judge the live AR capture.
86
86
  Do not inspect framework source when the build, registered-system query, entity
87
87
  components, and console warnings already establish the failing layer.
88
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=819e3f213766f12b567fa8ffd5e343f1a17f83973642067d82ebd7c5dee1dbe3 name=iwsdk-depth-occlusion (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -43,3 +43,4 @@ Observable workspace state wins over wording:
43
43
 
44
44
  iwsdk-dev does not add another implementation phase. The selected playbook owns
45
45
  the work, evidence budget, specialist routing, verification, and stopping rule.
46
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=58d4ce27ef04658c338d8bb0883b0718ba52037bd043fcc5f80783550bc20673 name=iwsdk-dev (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -461,7 +461,8 @@ PhysicsShapeType.Auto; // Auto-detect from Three.js geometry
461
461
 
462
462
  **Teleporting / re-posing an existing body:** use the live physics system rather than
463
463
  removing and re-adding components. It updates Havok and the Object3D immediately and
464
- clears velocity by default:
464
+ clears velocity by default. The pose is parent-relative unless you pass
465
+ `{ space: 'world' }`:
465
466
 
466
467
  ```typescript
467
468
  const physics = world.getSystem(PhysicsSystem);
@@ -1387,6 +1388,12 @@ const texture = AssetManager.getTexture('myTexture');
1387
1388
  const audio = AssetManager.getAudio('mySound');
1388
1389
  ```
1389
1390
 
1391
+ **Render loop (headless automation):** `world.renderMode` is `'continuous'`
1392
+ (default) or `'on-demand'`. On demand, systems still run every frame but only
1393
+ frames asked for are drawn: `await world.requestRender(frames)` or
1394
+ `const release = world.holdRender()` (draw every frame until `release()`).
1395
+ Headless dev sessions switch it on for you; shipped apps keep `'continuous'`.
1396
+
1390
1397
  **Runtime loading (on-demand):**
1391
1398
 
1392
1399
  ```typescript
@@ -0,0 +1,96 @@
1
+ # Headless rendering (no GPU)
2
+
3
+ Read this when the managed session is headless (`--ai-mode agent` or
4
+ `--headless`), the host has no GPU, or a result depends on frame rate, frame
5
+ timing, or which frame a screenshot shows.
6
+
7
+ ## What headless sessions do
8
+
9
+ A headless managed session renders **on demand**. Every ECS system, input,
10
+ physics and UI update still runs on every frame, but the app draws a frame only
11
+ when a tool needs pixels. Without a GPU every draw is software-rasterized, so
12
+ this keeps the app at the browser's frame rate (60 fps) instead of a few frames
13
+ per second.
14
+
15
+ - `browser screenshot` draws a fresh frame first. Screenshots always show the
16
+ current state, in the browser view and in XR. In emulated AR, the synthetic
17
+ room behind the app draws with it, so the two always match.
18
+ - `scene render-stats` draws one fresh frame before it reads the stats.
19
+ `browser profile`, runtime evidence and `browser run` scripts draw every
20
+ frame while they run. A profile first draws three warm-up frames, so
21
+ one-time first-draw costs (shader compilation, texture uploads) stay out of
22
+ its numbers.
23
+ - Headed sessions, including collaborate mode, always draw every frame.
24
+ - To draw every frame in a headless session, start it with
25
+ `IWSDK_DEV_RENDER_MODE=continuous`.
26
+
27
+ ## Check state, then look
28
+
29
+ Prove behavior with ECS state (`ecs query`, `ecs find`, `ecs snapshot`,
30
+ `ecs diff`). These need no pixels and see every frame. Take a screenshot only
31
+ for visual claims.
32
+
33
+ ## Capture an exact frame
34
+
35
+ ```bash
36
+ npx @iwsdk/cli ecs pause --input-json '{}'
37
+ npx @iwsdk/cli ecs step --input-json '{"count":1}'
38
+ npx @iwsdk/cli browser screenshot --input-json '{}' --output-file artifacts/frame.png
39
+ npx @iwsdk/cli ecs resume --input-json '{}'
40
+ ```
41
+
42
+ A screenshot draws without advancing the simulation, so it shows exactly the
43
+ paused frame.
44
+
45
+ To see motion, capture a filmstrip: exact simulation frames at offsets 0, K,
46
+ 2K, … in one contact-sheet image.
47
+
48
+ ```bash
49
+ npx @iwsdk/cli browser filmstrip --count 6 --every 5 --output-file artifacts/fall.png
50
+ ```
51
+
52
+ ## Switch the render mode at runtime
53
+
54
+ The `RuntimeSettings` component controls the render mode. It exists only at
55
+ runtime and is never saved into scene files.
56
+
57
+ ```bash
58
+ npx @iwsdk/cli ecs find --input-json '{"withComponents":["RuntimeSettings"]}'
59
+ npx @iwsdk/cli ecs set-component --input-json '{"entityIndex":<index>,"componentId":"RuntimeSettings","field":"renderMode","value":"continuous"}'
60
+ ```
61
+
62
+ Without a GPU, continuous drawing drops the app to a few frames per second, so
63
+ set it back to `"on-demand"` when done.
64
+
65
+ ## Do not
66
+
67
+ - Judge performance from headless frame rates. Profile instead, which draws
68
+ every frame while it runs, or measure on a device:
69
+ `npx @iwsdk/cli browser profile --input-json '{"action":"start","mode":"rendering"}'`,
70
+ exercise the scene, then
71
+ `npx @iwsdk/cli browser profile --input-json '{"action":"stop"}'`.
72
+ - Trust the frame times of a profile that reports a `render-warmup-timeout`
73
+ interruption (the app did not draw its warm-up frames in the time the start
74
+ allowed, at most 5 seconds) or `render-loop-stopped` (the app drew nothing
75
+ for 30 or more animation frames in a row while the profile held rendering:
76
+ its render loop stopped, before the profile or during it, or stalled). The
77
+ usual cause is an uncaught error in a frame, which stops the render loop;
78
+ check `npx @iwsdk/cli browser logs`. After a warm-up timeout, the first
79
+ frames may also just be very slow. Fix the error, or profile again.
80
+ - Trust the frame times of a profile that reports
81
+ `render-warmup-skipped-budget` (less than a second of the command's time
82
+ was left for the warm-up) or `render-mode-unavailable`. It sampled without
83
+ warm-up frames, so its numbers may include first-draw costs. Profile again.
84
+ - Expect a frame to change between screenshots if the scene did not change.
85
+ - Restart into headed mode to "fix" a stale view; screenshots already draw a
86
+ fresh frame.
87
+
88
+ ## Limits
89
+
90
+ - App code that reads pixels from the canvas itself (for example
91
+ `canvas.toDataURL()`) must draw and read in the same task (call
92
+ `renderer.render()`, then read), or create the renderer with
93
+ `preserveDrawingBuffer: true`. `await world.requestRender()` resolves after
94
+ the frame is presented, when the drawing buffer may already be cleared. See
95
+ the render loop API: `world.renderMode`, `world.requestRender(frames)` and
96
+ `world.holdRender()`.
@@ -87,11 +87,16 @@ the output bounded. The existing scaffold rules are already in context:
87
87
  3. Implement the smallest complete vertical delta, including state/UI feedback
88
88
  and recovery when the request needs them.
89
89
  4. Run one batched typecheck and fix errors together.
90
- 5. Start the managed runtime directly with
91
- `npx @iwsdk/cli dev up --headless --timeout 45000`.
90
+ 5. Start the managed runtime directly in the mode AGENTS.md's session rule
91
+ picks: `npx @iwsdk/cli dev up --ai-mode agent --timeout 45000`, or
92
+ `--ai-mode collaborate` when the user is watching. Headless sessions draw
93
+ only when a tool needs pixels; read references/headless-rendering.md before
94
+ relying on frame rate, frame timing, or which frame a screenshot shows.
92
95
  6. Exercise the changed path with real user input and query only the named state
93
96
  needed to prove it. Direct ECS mutation may prepare/reset a scenario but is
94
- not interaction proof.
97
+ not interaction proof. If the state you need to prepare lives in a plain
98
+ object outside ECS, move it into a component as part of the change rather
99
+ than editing constants temporarily or enabling browser automation.
95
100
  7. Run one focused regression smoke for the preserved behavior most likely to
96
101
  have been affected.
97
102
  8. Run the production build and stop.
@@ -149,14 +154,18 @@ npx @iwsdk/cli xr run-sequence --input-json '{"device":"hand-right","steps":[{"t
149
154
  npx @iwsdk/cli xr run-sequence --input-json '{"device":"hand-right","steps":[{"pinch":0,"duration":0.15}]}'
150
155
  ```
151
156
 
152
- Query `Grabbed` between the grab and the release. A press result whose
153
- `presses[0].contactMs` is 800 or more did not click. Slow headless frames can
154
- stretch a press that far, so run that press once more before changing code.
157
+ Query `Grabbed` between the grab and the release. A press result reports
158
+ contact, not a click: confirm the click by the state it changes (`ui inspect`
159
+ on the control, or the app state it drives). A `presses[0].contactMs` of more
160
+ than 800 never clicks. A stalled frame can stretch a press that far, so run
161
+ that press once more before changing code. A control out of reach stretches it
162
+ too, because the body walks to it during the press: walk first, with
163
+ `{"body":{"stepTo":"Btn_Action"}}` as a step of its own, then press.
155
164
 
156
165
  If a scene/source/UI edit happens after the managed runtime started and live
157
166
  state becomes stale, do not call `scene open`, repeatedly poll `dev status`, or
158
167
  loop on browser reload. Run one
159
- `npx @iwsdk/cli dev restart --headless --timeout 60000`, then resume the named-state
168
+ `npx @iwsdk/cli dev restart --ai-mode <the session's current mode> --timeout 60000`, then resume the named-state
160
169
  check. One failed restart may be diagnosed once; do not enter a recovery loop.
161
170
 
162
171
  Do not perform a full product replay when the edit affects one bounded path.
@@ -184,7 +184,9 @@ the same question.
184
184
  Build the smallest structure that covers the whole contract:
185
185
 
186
186
  1. native scene assets and deliberate hero/panel framing;
187
- 2. component schemas and explicit authored values;
187
+ 2. component schemas and explicit authored values, including game state such
188
+ as score, lives, phase and timers, so verification can jump to any state
189
+ with `ecs set-component` instead of playing there or scripting the page;
188
190
  3. interaction/state systems;
189
191
  4. UIKitML and runtime control wiring;
190
192
  5. visible state feedback.
@@ -205,13 +207,15 @@ physics, deployment, and interactions with meaningful failure modes need
205
207
  broader scenarios and stronger evidence.
206
208
 
207
209
  After the coherent vertical slice typechecks, start one managed dev session
208
- and keep it alive while iterating. The developer owns headed versus headless
209
- mode: announce a proposed mode change before restarting rather than silently
210
- replacing their visible collaboration window. Do not start an untouched or
210
+ and keep it alive while iterating. Pick headed or headless with the session
211
+ rule in AGENTS.md (headless unless the user wants to watch) and announce a later
212
+ mode change before restarting rather than silently replacing a visible window. Do not start an untouched or
211
213
  knowingly non-typechecking app. Exercise the real paths rather than inferring
212
214
  behavior from code. Confirm `npx @iwsdk/cli xr status` is active before making pose,
213
215
  controller/hand alignment, or immersive-interaction claims; a flat screenshot
214
- outside XR cannot prove them.
216
+ outside XR cannot prove them. Headless sessions draw only when a tool needs
217
+ pixels; read references/headless-rendering.md before relying on frame rate,
218
+ frame timing, or which frame a screenshot shows.
215
219
 
216
220
  Verify:
217
221
 
@@ -279,3 +279,4 @@ synthetic `fov: 90`. Keep using step 3 for framing.
279
279
  - `[iwsdk][gaze]` console lines and other errors;
280
280
  - for a headset run, its serial, which Quest mode was used, and whether the
281
281
  page was paired.
282
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=86e1e324dd71e8dd832b5d446e6bdc03bb5150cf5128c0650838cf6227b79817 name=iwsdk-glasses-test (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -72,3 +72,4 @@ to model context does not satisfy a requested file deliverable.
72
72
 
73
73
  Stop once the requested grab/move/release path and final state are proven. Leave
74
74
  the controller released and the XR session in the state the user requested.
75
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=ad099acb82205620cb9cce44f245f40baf7e6808038d7d94ff9d873f316473d2 name=iwsdk-grab (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -174,4 +174,6 @@ trip:
174
174
  | [`references/existing-hosts.md`](references/existing-hosts.md) | Route B — per-host publish recipes and their gotchas |
175
175
 
176
176
  Packaging the hosted app into a signed Quest APK is the `iwsdk-pwa-packaging`
177
- skill; this skill only gets it online.
177
+ skill, and keeping an offline copy on the device — with the `sw.js` cache
178
+ headers that copy needs — is `iwsdk-offline`. This skill only gets it online.
179
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=360be8c5297e0b33bdbdf82188b95dbbcfc586b00d0c0840a21094eb9745e21d name=iwsdk-hosting (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: iwsdk-native-xr-test
3
- description: Test an IWSDK app in a real Quest immersive session while controlling headset and controller poses through the IWSDK CLI. Use when the user asks to run, automate, or debug an app on a connected Quest rather than in desktop IWER emulation.
3
+ description: Drive an IWSDK app in a real Quest immersive session while you control headset and controller poses through the IWSDK CLI. Use when you will automate, script-test, or debug an app on a connected Quest. Not for the user trying the app by hand; native control takes over their head pose and controllers, so give them a plain dev session instead.
4
4
  argument-hint: '[test scenario]'
5
5
  ---
6
6
 
@@ -14,6 +14,17 @@ override poses and input for the test.
14
14
 
15
15
  The requested scenario is in `$ARGUMENTS`.
16
16
 
17
+ ## Not for hands-on testing
18
+
19
+ Use this skill only when you drive the headset. If the user wants to put the
20
+ headset on and try the app themselves, do not start native control and do not
21
+ give them a pairing URL. A `--native-xr-control` session overrides the head pose
22
+ and controllers of every Quest Browser page it serves, even after the pairing
23
+ token is removed from the URL; the page shows an "Agent-controlled page"
24
+ notice saying so. Restart without the flag and hand over a plain URL as described in
25
+ AGENTS.md. If a native-control test is running when the user asks to try the
26
+ app, finish or stop it, clean up as in step 6, then do the same.
27
+
17
28
  ## Safety and scope
18
29
 
19
30
  - Use only public Android platform tools and IWSDK commands. Do not depend on a
@@ -244,3 +255,8 @@ Report:
244
255
  - before/after evidence for the requested behavior;
245
256
  - console errors or capability notes;
246
257
  - confirmation that the reverse route and dev session were removed.
258
+
259
+ If the user wants to try the app in the headset afterwards, start a plain
260
+ session (`npx @iwsdk/cli dev up` with the session's `--ai-mode`, without
261
+ `--native-xr-control`) and give them the plain URL from `dev status`.
262
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=931a8822463f2bb6652cbbf2b7571db92e5331af44b598890057319b0177939b name=iwsdk-native-xr-test (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->