First round-trip

Once you're authorized, pick your next step based on the current folder:

• It has a .sandscape/ directory → it's already a Sandscape clone. Run sandscape pull, then work the core loop below.
• It's a game folder not yet on Sandscape (no .sandscape/) → import it with sandscape init.
• It's empty or unrelated → you probably want an existing project. Run sandscape list to see them, then sandscape clone <session_id> <dir>.

How this folder maps to the platform

The clone directory is the game's served root (generated_assets/ on the platform). Files can live anywhere under it — there's no required structure. The one special file is index.html at the root (the served entry point). Everything except the CLI-managed metadata round-trips to the platform verbatim.

These are CLI-managed — they're not game content, so don't push or edit them as game files:

• .sandscape/ — session id, versions, file manifest, and the durable design.
• CLAUDE.md / AGENTS.md — generated guides.
• .claude/, .agents/ — the skill and other tool config.

The durable game design (concept, style, assets, plan) lives in .sandscape/design.json — a good place to start to understand a project.

The core loop

1. sandscape pull — refresh from the platform before you start.
2. Edit files locally with your normal tools.
3. sandscape push — upload changed and new files.

Both pull and push are reject-on-divergence: they refuse rather than merge, so you resolve conflicts explicitly.

• On pull: if it refuses because the server advanced over a local edit, don't reach for --force without checking what you'd lose (see below).
• On push: if the server moved past your base_version, run sandscape pull first, then push again.

Asset generation runs on the platform

You can't generate AI assets (3D models, images, audio) locally — that runs on Sandscape, where it's coin-metered. To add or regenerate a generated asset, do it in the Sandscape web app, then sandscape pull to bring it down. You can freely edit code and hand-authored files locally and push them.

Progress output

Long operations (clone/pull/push) print per-file progress, and with --json emit {"event":"progress","done":N,"total":M,"path":"..."} lines — so you can tell "working" from "stalled" during big transfers.