# Set up PICO Space Pro for the Space Program

Revision: 2026-10-08. Resolve current official releases when executing; historical versions are not installation pins. This document is the complete setup prompt, including recovery guidance and the interactive solar system smoke test.

## 1. Goal and source recovery

Set up this computer so I can develop native Kotlin spatial apps for PICO Space Pro (Project Swan). Install and verify the tools, integrate them with the active coding-agent host, and finish with the interactive solar system below visibly running in the latest stable PICO Emulator. You may install required tools and use shell, official downloads, browser and computer use in Android Studio. Explain progress briefly for someone new to XR development.

When retrieving these instructions, use the current, unpinned raw URL below. If you already have the complete document, continue without fetching it again:

`https://picospaceprogram.com/setup/native-kotlin.md`

If the in-app web tool fails, try a shell HTTP client with redirects (curl or PowerShell), then open `https://picospaceprogram.com/setup/native-kotlin.md` through the browser/computer-use tools. Treat this URL as the canonical current source; do not fall back to the former GitHub Gist or a historical copy without explicit user approval. Record the source URL, retrieval time, document revision (if stated), and SHA-256 checksum. Verify the title “Set up PICO Space Pro for the Space Program”, the MCP `query_graph` check and the full smoke-test verification requirements. Save the complete retrieved source and metadata locally. Never invent missing text. If every permitted retrieval method fails, summarize attempts and ask for a paste or attachment, retaining completed work.

Read the entire document before taking installation actions. On later runs, use the current canonical URL contents and current official release metadata rather than relying on an older local copy. Preserve completed work and reconcile changes at a safe checkpoint.

### Host platform: macOS and Windows

Detect the operating system, CPU architecture, available shell and current official support before choosing downloads or commands. Run the native supported toolchain for that host. Do not assume that Windows on ARM, WSL, a virtual machine or every macOS architecture is supported; check current PICO requirements and explain any concrete blocker before large downloads.

On Windows:

- Use PowerShell or another supported native shell with its actual syntax. Use Windows paths, correctly quote spaces, and resolve user/profile/cache locations from the environment instead of copying Unix paths. Run the Gradle wrapper as `gradlew.bat` (for example, `& .\gradlew.bat assembleDebug` in PowerShell). Resolve the actual npm/CLI executable or `.cmd` shim and verify its version.
- Use current official Windows Studio, Node, Editor and Emulator distributions for the detected architecture. Verify current PICO CPU, memory, GPU/driver and hardware virtualization requirements. Inspect the required Windows hypervisor/virtualization configuration through supported checks; do not disable security features, enable conflicting hypervisors or change firmware settings speculatively.
- Explain required administrator/UAC, firewall, firmware or Windows-feature actions specifically. Do not run everything elevated. If a Windows feature or driver change requires a reboot, save the checkpoint first, explain how to reopen the agent and project, then verify the change after restart.
- Set environment variables with native syntax and scope. Launch Studio with the saved environment or configure the IDE explicitly; an already-running GUI process may retain stale values. Create a Windows `.ps1` or `.cmd` launcher with quoted paths and supported execution. Do not weaken system-wide PowerShell execution policy to run it.
- Inspect actual PICO, npm, Android and Gradle directories under the selected root and Windows profile. Verify supported storage/relocation behavior; do not assume macOS layouts or symlink semantics. Release tool-owned file handles through supported shutdown before replacing files; preserve user content and avoid arbitrary process termination.
- Diagnose TLS using the failing runtime's trust configuration. A macOS/Homebrew CA-file recovery example is not a Windows certificate prescription. Use trusted certificates and supported configuration without disabling TLS verification.

On macOS, use the supported native shell, architecture-specific distributions, actual app-bundle/JDK paths and an appropriate launcher. Apply the same consent, preservation and restart rules.

The solar system implementation and acceptance criteria are identical across supported hosts. The reference workflow was verified on macOS; Windows remains untested until a Windows run completes the same smoke test. Record the actual host and results rather than implying cross-platform verification.

## 2. Installation location and consent

Before any large download, ask once: “Where would you like to install your Space Program tools and projects?” List writable internal and connected external drives and available space. Recommend a `SpaceProgram` folder on a suitable drive and allow a custom folder. Wait for the choice. Reuse a choice already supplied by the user in the active session. For an existing setup, inspect its saved state and reuse its selected root instead of assuming a new location or reinstalling.

Check the selected volume is mounted, writable and supports required filesystem features. Check current official PICO host requirements before downloading gigabytes. Check space on both the chosen and system volumes, allowing for downloads, extraction, caches, builds and virtual-device growth. Never format a drive or overwrite an existing installation/project.

Present applicable Google/PICO terms and request explicit acceptance if it has not already been supplied for that agreement. Retain recorded acceptance across restarts. An ordinary “continue” is not legal acceptance. Do not conceal acceptance behind automatic flags. Complete subsequent routine authorized work automatically; ask only for missing choices or unavoidable license, OS permission, authentication or restart actions. Perform terminal work yourself.

## 3. Resolve releases at execution time

### Public pico-cli: check for newer stable releases

- Use the official public `@picoxr/pico-cli` package. At the start of every new setup/update run, query public npm metadata and release tags. For example, inspect `npm view @picoxr/pico-cli dist-tags versions engines --json --registry=https://registry.npmjs.org` with a supported Node/npm runtime. Consult official PICO release information to resolve stable versus preview ambiguity. Discover any installed CLI update-check command with help before using it as additional evidence.
- Select the newest official stable public release available then. Do not cap it at 0.5.0, 0.6.0 or any historical major version. If the latest tag is a prerelease, inspect published versions and official release notes to choose the newest stable release. Do not select a preview solely because its version is higher.
- Compare installed and selected versions semantically. This setup request authorizes installing/updating to the selected stable version in a private tools directory under the chosen root. Preserve other CLI installations. Resolve once for this run and install that exact resolved version for reproducibility; resolve again on later runs. On resuming a long run, recheck releases and update at a safe checkpoint if needed, then repeat affected help/health checks.
- Verify the executable actually used, its absolute path, reported version, registry/channel, metadata source and lookup time. Installation output alone is insufficient. If lookup fails, try another official route; if still blocked, mark latest-release verification pending. Never report an installed release as latest without evidence.
- If Node is missing/incompatible, install a supported Node LTS from its official distribution under the chosen root. Check the selected CLI's current engine requirements and published checksums where provided.

### Compatible Android and PICO tools

Resolve the latest stable PICO Emulator for this host architecture and region from PICO's official feed. Record and explicitly use that exact release for the dedicated virtual device. An older installed emulator is not a substitute for latest-release verification. Reuse an existing matching healthy device and preserve older devices/data.

Resolve Android Studio against the current PICO Spatial plugin's documented compatibility, selecting the newest supported stable IDE within that range. The previous setup used Narwhal 4 build 2025.1.4.8; that is historical evidence, not a permanent pin. Obtain archives/checksums from Google and preserve existing IDE installations. Do not automatically accept IDE, AGP, Kotlin or Gradle upgrade suggestions.

Install the compatible PICO Spatial IDE plugin, Spatial Editor, template and Spatial SDK line for the selected stable emulator. Follow current official compatibility guidance; individual patch versions need not match. Default to Global outside mainland China; ask if region/channel cannot be determined. Never use a private registry for this public setup.

Use Studio's bundled JDK when compatible. Install Android platforms, sources, build tools and any NDK required by the compatible template; the prior template required Platform/Sources 35. Keep compatible template Gradle/AGP/Kotlin versions. An IDE cloud-services warning alone does not establish a local Gradle/PICO blocker: verify the required functions.

## 4. Paths, environment and health

Put supported Studio/JDK, Node/CLI, downloads, Android SDK, Gradle cache, projects, PICO knowledge/tool payloads and emulator data under the chosen root. Configure `ANDROID_HOME`, consistent `ANDROID_SDK_ROOT` where required, `GRADLE_USER_HOME`, absolute `PICO_HOME`, and private npm prefix/cache before provisioning. Discover the installed CLI's actual storage behavior. Some payloads/state may remain in `~/.pico`, `~/.pico-cli` or `~/Library/PICO`; report real paths and sizes. Do not assume environment variables relocate managed AVDs.

Use supported relocation settings first. Older CLI staging rejected symlinks in `~/.pico-cli`; inspect current behavior before considering a link. Do not move/replace existing directories, caches, links, profiles, SDKs or AVDs without checking ownership and preserving them. Verify cold boot and real paths after supported relocation. Never change `HOME`/`CODEX_HOME` or move the whole profile.

Create an environment launcher under the chosen root and launch Studio with it: GUI apps may not inherit terminal variables. Configure SDK, Gradle cache and JDK consistently. Handle spaces with proper argument quoting and verify actual commands. Keep necessary small discovery files/host registration in supported profile locations. For OS-protected actions, explain the specific required permission/action and use the supported route.

Use `pico-env-doctor` before dependent CLI/MCP/emulator execution, when available. Discover installed CLI help and each selected command's help before invoking it. Do not copy historical flags unquestioningly. Inspect root/module doctors and repair concrete failures through supported operations, including an outdated Primer helper; recheck after each repair. Distinguish optional performance dependencies and unrelated scope warnings from core failures. Examine PARTIAL findings rather than assuming failure or success. CLI setup alone does not complete Android installation.

## 5. Host integration and MCP checkpoint

Configure the agent host actually running this local session through current supported setup/plugin tooling. Discover host IDs, flags and scope. Preserve unrelated registrations/settings; where host lists replace existing lists, include existing entries. Prefer the scope compatible with the active Desktop host. Project-local CLI registration does not prove global Desktop activation.

Verify BOTH `pico-dev-knowledge` and `pico-spatial-editor` are registered and enabled in the effective host configuration. INSIDE this active chat, discover the knowledge server and execute a small read-only `query_graph` call. Confirm Editor tools or the supported gateway are loaded/callable with a read-only status request; do not launch Editor merely for registration testing.

Record separately: effective registration/enabled state; loaded/callable in this chat; CLI-side doctor health. A green terminal knowledge doctor cannot replace in-chat `query_graph`. Align knowledge to the project's SDK major.minor through supported tooling; do not silently upgrade an existing app's SDK to fix knowledge alignment.

If configuration/plugin changes require a host restart or new session, checkpoint first and explain the specific action once. After restart, rediscover tools and repeat in-chat checks before marking MCP complete. If dynamic tool refresh leaves stale schemas, use a supported gateway when available or request reload; do not run host slash commands in the shell. Continue independent CLI/build work while MCP activation is explicitly pending.

For GUI-only setup, use computer use to complete Studio's first-run wizard, select the SDK path, install the correct Global/CN PICO Spatial plugin, restart Studio as required and verify the installed plugin version and project sync.

## 6. Restarts, blockers and recovery

After each stage save `<chosen-root>/setup-state.json` and `SETUP-RESUME.md`: root, source/revision, actual versions/paths, completed verified steps, acceptance records, project/device, active workflow ID/task/revision, last error, evidence locations and exact next action. Store no secrets. Do not let an early checkpoint from another root override later verified completion.

Before requesting a restart, state which app must restart, why, and how to resume. Example: “PICO MCP registration changed. Quit and reopen Codex, return to this chat, and say continue. Your installation is saved at <root>; I will check query_graph next.” Studio plugin installation may require only Studio to restart. A full computer reboot requires a concrete OS/tool reason. Keep project/emulator running when safe. Elapsed time is not proof of restart: verify resulting state. Reuse completed verified downloads and existing acceptance.

Use bounded operations with visible progress and concise updates. Inspect causes before retrying; avoid repeating ineffective repairs. Try independent permitted retrieval methods for ordinary network failures. For genuine blockers, explain the exact error, completed work, supported remedy and minimal user action. Continue unaffected work. If automatic approval review rejects an action, identify it and the stated reason; use a permitted alternative where possible.

Recheck these observed caveats against future tool versions:

- Start/resume workflows with the absolute app project working directory and absolute input paths where supported. Workers can inherit the calling directory and otherwise search the wrong workspace.
- Read status/help and resume the actual handoff task/revision. Do not mutate workflow stores or resume terminal runs; start a linked follow-up run when appropriate. Do not use `--no-agent` as a generic bypass for required agent work.
- Preserve raw and structured output. Some versions append a schema notice after JSON; do not parse the whole stream blindly or discard warnings.
- If Editor HTTPS fails while system HTTP clients succeed, diagnose the exact bundled runtime's CA lookup. A prior runtime referenced a missing Homebrew CA path; using `SSL_CERT_FILE` with an existing trusted system CA bundle fixed it. Keep TLS verification enabled and pass required environment to every workflow start/resume. Never disable verification, edit vendor binaries or print auth tokens.
- Failed Editor workflows may retain session ownership. Use supported inspection/cleanup/resume; do not delete locks or kill arbitrary processes. Preserve authored content before switching workspaces.
- Verify export paths: a prior pack command wrote into Editor Build despite the target option. Place the bundle and its scene/provenance sidecars together in app assets and keep truthful export provenance.
- Browser security restrictions differ from ordinary fetch failures. Do not evade a prohibited local preview through localhost, another browser or indirect execution. Explain the required skill/check and offer a permitted alternative/manual review. Obtain explicit approval when the skill requires approval for a substitute, and record what was actually checked.
- If Editor lacks required orthographic capture, first check for a supported compatible release/remedy. If unavailable, request an explicit alternative such as emulator review. Never call perspective capture orthographic or claim the unavailable gate passed. Record direct/unmanaged export honestly.

## 7. Solar system smoke-test app

Use `<chosen-root>/projects/SpaceProgramHello`, project `SpaceProgramHello`, package `com.example.spaceprogramhello`, and dedicated device `SpaceProgram_Smoke`. Preserve/extend any existing project. For a new project, establish the supported first runnable scaffold, then implement this experience in a Mixed Stage. Scaffold success is intermediate; the final smoke test is the solar system.

Apply relevant installed workflows: `spatial-design-to-app` for the visible app, Designer for its accepted design package, onboarding for a new scaffold, Editor for Editor-owned scenes, app-development/scene integration for exported assets, SpatialUI design style for Compose, and emulator usage for validation. Follow project guidance. Resolve required decisions about unavailable gates before claiming alternative delivery.

### Required experience

- A stylized Sun and eight individually addressable, colored 3D planets: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus and Neptune. Include continuous animated orbits, thin orbit guides and Saturn's ring.
- Clicking a planet selects/highlights it, pauses orbits and updates a nearby readable 2D information panel. Include eight native planet-name buttons as an alternative selection route.
- Show name, description, diameter, year length and distance from the Sun with units. Verify facts against an authoritative source such as NASA's planetary fact sheet and bundle them locally; require no runtime network/login. Label sizes, distances and timing as illustrative.
- Include Pause/Resume and Clear selection. Clear removes selection and resumes motion. Choosing another planet replaces prior selection and facts. Keep button and 3D interaction behavior consistent.
- Use SpatialUI inside `PicoTheme`, native controls/feedback and documented compatible APIs; no Material/Material3. Inspect current SDK source when components are unavailable; do not invent native Card or gesture APIs. Use a documented noninteractive surface proxy where needed with explicit ownership and named color tokens.
- Preserve Editor hierarchy and co-locate bundle, `.scenes.json` and provenance sidecars in app assets. Give planets stable IDs and appropriate collision/interaction components. Use documented frame updates; dispose entities/subscriptions with the view lifecycle. Keep domain orbit calculations separate from local facts and immutable UI state/events.

### Layout and rendered review

Check actual Stage coordinates: the delivered app used a floor origin and +Y upward. Do not place eye-level content at Y≈0 assuming an eye-relative origin. As a starting reference only, its orrery center was (-0.45, 1.38, -2.4)m with 25° tilt; the panel was at (0.75, 1.7, -2.2)m, 560×720dp and scale 1.8. Adapt to current runtime/camera and inspect rendering.

Keep the whole scene and panel visible, text readable, edges unclipped and facts scrollable as needed. Compensate collision sizing for imported scale. Boot completion is not scene readiness: wait for scene load and inspect a fresh screenshot. A room-only initial frame does not pass.

## 8. Build, interaction verification and evidence

Build debug APK with the Gradle wrapper and compatible JDK; repair ordinary build errors. Create/reuse the dedicated device on the resolved latest stable emulator, start visibly, wait for boot/ADB readiness, explicitly target it, install the intended package and launch its declared activity. Open the project in Studio, complete supported sync/run configuration, and leave emulator open with app visible.

Smoke-test verification must cover ALL of these:

1. Debug APK builds, intended package is installed on selected device, declared activity launches.
2. Process remains alive for at least 60 seconds after scene readiness with no app fatal crash in observed logs.
3. Fresh inspected screenshot shows Sun, eight planets, guides, Saturn's ring and readable controls. Two time-separated captures show orbital motion while running.
4. Select at least two different planets; verify corresponding facts/highlight replace prior selection and selection pauses motion. Exercise direct 3D selection and name buttons where input access allows; record any route not tested.
5. Verify Pause stops motion, Resume restarts it, and Clear removes selection and resumes. Inspect selected facts for clipping/scrolling.
6. Complete applicable build, architecture, style, design and scene validators and the verification/tests required by the adopted workflow. Record warnings, failures, unavailable checks and approved substitutes separately. Another green validator cannot prove an unavailable original gate passed.
7. Record in-chat MCP `query_graph` success and Editor visibility separately from app success.

Use supported spatial input automation if available. `adb input tap x y`/shell taps do not reliably test spatial rays/windows. If spatial pointer automation is unavailable, complete independent checks, leave app visible and guide the user: “Click Earth; confirm Earth's facts appear and orbits pause. Click Mars; confirm facts change. Try Resume, Pause and Clear.” Wait for results and distinguish human-confirmed from automated evidence. One confirmation of facts/pause does not prove every control or the direct 3D route; report remaining checks precisely.

Save APK location, screenshots, relevant logs, facts sources, exact version list, install paths, workflow receipts/provenance and a concise report under `<chosen-root>/evidence`. Record each criterion and evidence, including manual results. Leave project guidance and an environment-aware launcher to reopen Studio, correct emulator and app. Preserve recovery files; avoid wiping device data for ordinary startup issues.

## 9. Completion

Finish briefly with what passed, where tools/projects/evidence live, what must remain on system drive, actual versions and any remaining manual action. Say “Ready to build” only after the solar system smoke test passes. State Desktop MCP activation separately. Identify approved alternatives and pending checks honestly; do not collapse partial success into full verification.

### Leave the experience open and invite the next prompt

After all required smoke-test checks pass, leave the Emulator running with the solar system app open and visible. Keep the saved project ready to continue. Do not stop the app or Emulator as routine cleanup.

End with this encouragement, followed by the five examples below:

“Your first PICO Space Pro spatial app is running. The Emulator and solar system are still open—try selecting a planet! **Now you try creating something fun.** Paste one of these into this chat:”

- “Build a mini bowling game with a ball, colourful pins, a score panel, and a button to reset the lane.”
- “Create a floating art gallery with colourful 3D sculptures I can select and rotate, plus a panel to change their colours.”
- “Make a cosy focus timer with a growing 3D garden, a duration picker, and Start, Pause and Reset buttons.”
- “Build a spatial memory game with floating cards: let me select two at a time, find matching pairs, and keep score.”
- “Create a tiny music playground where selecting colourful floating shapes plays different notes and makes them glow.”

Give the actual saved project location. These examples deliberately explore new experiences unrelated to the solar system. Follow-up work should reuse the installed native PICO OS 6 Spatial SDK toolchain and selected installation root, use SpatialUI inside PicoTheme for panels, and rebuild/redeploy to the running Emulator. Create each chosen experience in a new sibling project without overwriting the solar system or other existing projects. Check current supported APIs and input capabilities before implementing; these examples are invitations, not claims that the features have already been built or tested. Do not implement any example until the user chooses or supplies a follow-up prompt.

If verification is incomplete, keep any running app visible and explain the exact pending check first. Do not use the full-success wording or imply a blocked setup is complete.
