{"id":47306,"plugin_id":"plugin_asdk_app_6accab1016088191b19230b3c7ecaec4","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-10-24T13:32:57.973Z","digest":"dd1c22ffbccea75dfe8eb5cae69bb3512e44a2901dc680132320c45d9eed4739","against":null,"payload":{"description":"Block out, edit, check and render 3D staging scenes on the local machine with the topview-3d-cli command: simple primitive props, built-in mannequin characters, static library poses, story cameras plus a bird's-eye layout camera, numerical checks and PNG renders; building and rendering run offline in a project directory. After the renders it offers an image or video generation from the frames, run only once the user confirms. Use when the user asks to stage, block out, lay out or storyboard a scene in 3D; place people, props or cameras; pose characters; check framing, grounding, spacing or collisions; render views of a scene as a reference for video generation; or works in a directory that contains `.topview-3d/`. Also use when a topview-3d-cli command fails or topview-3d-cli still has to be installed. The Codex plugin is shown as Topview 3D Builder. Change the 3D scene only with topview-3d-cli. After a scene is built, open the local Studio in the In-App Browser to view it, not to edit it.\n","included_files":[{"relative_path":"references/add-character.md","size_in_bytes":2108},{"relative_path":"references/add-prop.md","size_in_bytes":5698},{"relative_path":"references/asset-selection.md","size_in_bytes":2573},{"relative_path":"references/camera.md","size_in_bytes":9608},{"relative_path":"references/checks.md","size_in_bytes":9701},{"relative_path":"references/doctor-browser.md","size_in_bytes":9598},{"relative_path":"references/edit.md","size_in_bytes":7373},{"relative_path":"references/generate.md","size_in_bytes":18593},{"relative_path":"references/layout.md","size_in_bytes":7329},{"relative_path":"references/pose.md","size_in_bytes":11014},{"relative_path":"references/state-intent.md","size_in_bytes":3800},{"relative_path":"references/video-prompt.md","size_in_bytes":12178}],"name":"topview-3d-cli","skill_md_contents":"---\nname: topview-3d-cli\ndescription: >\n Block out, edit, check and render 3D staging scenes on the local machine with the topview-3d-cli command:\n simple primitive props, built-in mannequin characters, static library poses, story cameras plus a\n bird's-eye layout camera, numerical checks and PNG renders; building and rendering run offline in a\n project directory. After the renders it offers an image or video generation from the frames, run only\n once the user confirms.\n Use when the user asks to stage, block out, lay out or storyboard a scene in 3D; place people,\n props or cameras; pose characters; check framing, grounding, spacing or collisions; render views\n of a scene as a reference for video generation; or works in a directory that contains\n `.topview-3d/`. Also use when a topview-3d-cli command fails or topview-3d-cli still has to be installed.\n The Codex plugin is shown as Topview 3D Builder. Change the 3D scene only with topview-3d-cli.\n After a scene is built, open the local Studio in the In-App Browser to view it, not to edit it.\n---\n\n# topview-3d-cli\n\n`topview-3d-cli` edits and renders a local director project: a directory with a `.topview-3d/` folder. The\ngoal is an abstract, physically consistent staging reference for video generation: simple shapes,\ncorrect scale and support, clear blocking, one world seen from several static cameras. Character\npositions come first, then plausibility and camera continuity, then composition. Fine visual detail\nis not a goal; a phone can be a slab. Respond in the user's language.\n\nScope in this version: primitive props, the four built-in characters (Child, Youth, Female, Man),\n121 static poses, static cameras and root keyframes. There is **no motion library**: never promise\nwalk cycles or other body animation. To suggest movement, give the character a fitting static pose\n(for example a walking stride) and, only when the user asks for movement, add\n`transform.position` / `transform.rotation` keyframes (see `references/edit.md`). Preserve existing\nanimation and editorial data rather than extending them.\n\n## Step 1: check the environment\n\nRun this before anything else in a session:\n\n```bash\ntopview-3d-cli doctor --json\n```\n\nIt always exits 0; gate on the top-level `ok`. When `ok` is false, read each failing\n`checks..hint` and follow `references/doctor-browser.md`:\n\n- **`topview-3d-cli` not found:** it is installed once per machine, in an environment every project\n shares. Look there before installing anything: `~/.local/share/topview-3d-cli/venv/bin/topview-3d-cli`\n on macOS and Linux, `$env:LOCALAPPDATA\\topview-3d-cli\\venv\\Scripts\\topview-3d-cli.exe` on Windows.\n When it exists and its `doctor --json` reports the `cliVersion` of this skill's pin,\n `topview-3d-cli==0.1.8`, use that path for every command.\n Otherwise install it once as `references/doctor-browser.md` describes (Installing topview-3d-cli).\n Never create a virtual environment inside the user's project or workspace, and do not use\n `pip install --user`.\n- **`node` fails:** Node.js 20.6 or newer (with npm) is required; ask the user to install it.\n- **Checkout:** when the folder that holds this skill also has `agent/` and `editor/` (plugin installs\n are checkouts), install by running its `scripts/install.sh` (or `install.ps1` on Windows) once. It\n puts the CLI into the shared environment and installs the renderer and Studio's Next.js together.\n Do not install only the renderer package.\n- **`playwright` or `chromium` fails:** run `topview-3d-cli browser ensure` once (it downloads the pinned\n Chromium into the user cache).\n- **Rendering fails inside an agent sandbox** although `doctor` passes: the sandbox blocks the\n browser, not topview-3d-cli. Say so, ask the user to approve running the render command outside the\n sandbox, and keep working on everything that does not need a browser. Never build a substitute\n renderer (image libraries, SVG, hand-drawn frames).\n\n## CLI contract\n\n- Every command prints one JSON object on stdout. Failures print `{\"ok\": false, \"code\", \"error\"}`\n on stderr, with `details` (such as the failing `index`) when available. Exit 0 is success, 2 is\n invalid input, including an id that names no existing node, asset, pose or camera (fix the\n input), 1 is a command that could not\n be carried out (conflict, missing dependency, renderer failure).\n- Spec files are JSON objects; `-` reads stdin. Write them to a temporary file first.\n- Validate before writing: `--dry-run` on `document apply`, `node batch` and `pose batch`, and\n `topview-3d-cli evaluate plan.json` for a plan's numbers. Nothing is written when a command fails.\n- Pass `expectedSceneSequence` from the latest result. On `SCENE_SEQUENCE_CONFLICT` re-read and\n re-plan; never bump the number blindly.\n- Copy ids (`libraryId`, `poseId`, `presetId`, node ids) verbatim from command output. Never invent\n ids, dimensions or measurements.\n- After a render, open the returned PNG files and look at them before judging. A render that was\n not viewed is not visual evidence.\n- Change the 3D scene with topview-3d-cli (`node batch`, `pose batch`, `document apply`). Do not\n click, drag, or type in the Studio page, and do not use browser automation to move or edit\n nodes. The In-App Browser only opens Studio so the user can look at the scene.\n- One writer at a time: do not run a writing command while Studio is saving the same project.\n After the user edits in Studio, re-read with `document get` before planning the next change.\n Studio writes back through `project adopt`, so the project on disk is the edited scene.\n\n## Each session starts with context\n\n```bash\ntopview-3d-cli project status # or: topview-3d-cli project init for a new scene\ntopview-3d-cli document get --summary # nodes, cameras, sceneSequence\ntopview-3d-cli bom get # the plan record: intent, relations, cameras, verification\n```\n\nRead them before planning; re-read only after your own writes or a conflict. `topview-3d-cli document get\n --entity ` returns one full node or clip.\n\n## Workflow stages\n\nRead the reference for a stage once per session, before its first command:\n\n### Guide the user at every stage boundary\n\nCore principle: guidance makes the next useful action clear. Pause at creative decision points;\nuse progress updates for execution steps inside an already approved action.\n\nBy default, complete one stage below, make its result reviewable, then ask whether the user wants\nto continue to the named next stage or revise the current result. Wait for their answer before\nstarting that next stage. Do not silently run the entire table and ask only after rendering.\nThis applies to new scenes, edits and revisions, including the final delivery.\nException: once the user authorizes video generation for the current task, Stage 10 proceeds through\npreparation, service submission and delivery without further stage-boundary approval questions.\nThis authorization covers the current generation round, not every future version of the 3D plan.\nIf feedback sends the work back to the scene, model, pose or camera stages, complete and verify the\nrevised preview, then stop and ask whether to generate from it or adjust it further. Do not carry\nthe previous round's yes across this decision point. An explicit request to revise AND regenerate\nalready answers that choice; see `references/generate.md`.\n\n- Briefly state what is ready, show the relevant plan, preview or result, and mention any unresolved\n limitation that affects the next choice. For nonvisual stages, a concise summary is enough.\n- Recommend a concrete next action and explain its purpose in one sentence. End with one clear\n question in the user's language. Name the actual action and what can be revised, rather than\n asking only “Continue?” or “What next?”. Examples (written in English; localize when responding):\n - After the layout plan: “Would you like me to build this scene in 3D, or revise the layout first?”\n - After scene construction: “Would you like me to set up the camera movement, or modify this scene first?”\n - After camera setup: “Would you like me to render a preview video, or adjust the camera movement first?”\n - After the reference and generation prompt are ready: “Would you like to proceed to video generation,\n revise this scene, or edit the generation prompt first?”\n - After revising the 3D preview following feedback: “The revised camera preview is ready. Would you\n like me to generate a new realistic video from it, or adjust the scene or camera movement further?”\n Use only options appropriate to the current result and available capabilities. If the reference\n video is not ready, offer to render or export it before offering the generation handoff.\n- A stage is a user-facing milestone, not each CLI call. Finish the reads, measurements, dry-runs,\n rendering and necessary corrections that make that stage reviewable before asking. Do not ask\n permission for each tool invocation or stop on an unverified intermediate result.\n- If the user requests changes, make and verify those changes within the current stage, present the\n updated result, then offer the next-stage-or-revise choice again. A request to revise does not by\n itself authorize proceeding to later stages. Silence is not an answer.\n- Apply only stages relevant to the request: an edit does not restart completed setup or rebuild\n unrelated objects. For the last applicable stage, offer a concrete follow-up or further revision;\n respect “stop”, “not now”, or a request for no further questions.\n- If the user explicitly asks to complete several stages or the whole workflow without pauses,\n honor that scope and ask at its end instead. Do not repeatedly reconfirm stages they have already\n approved. Ordinary “build a scene” requests use the guided stage boundaries above.\n- At the rendered-output handoff, follow Stage 10: prepare and show the generation prompt. Ask whether\n to generate only if the user has not already authorized generation from this version. An explicit\n request such as “render and generate the video” already authorizes it. After authorization, use\n progress updates rather than repeated approval questions about preparation or execution.\n\n| Stage | What to do | Reference |\n| --- | --- | --- |\n| 1. Understand | Resolve intent from the conversation and current state; record it in the BOM | `references/state-intent.md` |\n| 2. Layout | Relationships, support, facing, clearance; BOM fields | `references/layout.md` |\n| 3. Props | 1–4 primitives first; imported models only when needed | `references/add-prop.md` |\n| 4. People | Pick from the built-in characters; place before posing | `references/add-character.md` |\n| 5. Pose | Reviewed text mappings; seat fitting | `references/pose.md` |\n| 6. Cameras | Mandatory bird's-eye overview plus story coverage scaled to the number of people | `references/camera.md` |\n| 7. Edit | Change only what was asked; batch syntax; keyframes | `references/edit.md` |\n| 8. Check | Numbers, renders, look at the PNGs, revise | `references/checks.md` |\n| 9. Studio | Open the finished scene in the local Studio with the In-App Browser | `references/doctor-browser.md` |\n| 10. Generate | Write and show the prompt; obtain generation authorization once if missing, then generate and record the result without repeated confirmation | `references/generate.md`, `references/video-prompt.md` |\n\n## After the frames are ready\n\nStage 10 is part of every workflow that ends in a rendered video or frames: do not close the session on\nthe renders without it. Read `references/generate.md` and follow it. As soon as the video is rendered, you\nwrite the generation prompt yourself, without being asked, by following `references/video-prompt.md`,\nshow it to the user, and ask whether to generate if authorization for this version is missing. Once authorized,\ncomplete service selection, generation and result recording without repeated approval prompts.\nA video generation uses the rendered or exported video as its reference.\n\nBuilding, checking and rendering stay offline. Stage 10 is the only stage that may reach an outside\nservice, within the user's authorized generation task. Never contact a generation\nservice from any other stage.\n\nAsset search rules for props, characters and poses are in `references/asset-selection.md`.\nInstallation, the browser and sandbox limits are in `references/doctor-browser.md`.\n\n## Commands\n\n| Need | Command |\n| --- | --- |\n| New project / state | `topview-3d-cli project init `, `topview-3d-cli project status ` |\n| Read the document | `topview-3d-cli document get --summary`, `topview-3d-cli document get --entity ` |\n| Add, change, delete nodes | `topview-3d-cli node batch changes.json [--dry-run]`, `topview-3d-cli node delete ` |\n| Low-level operations (scene settings, keyframes) | `topview-3d-cli document apply ops.json [--dry-run]` |\n| Find assets | `topview-3d-cli asset search --kind character\\|pose\\|prop`, `topview-3d-cli asset show ` |\n| Pose list | `topview-3d-cli pose catalog [--category sit]` |\n| Pose people | `topview-3d-cli pose batch poses.json [--dry-run]`, `topview-3d-cli pose apply ` |\n| Camera presets | `topview-3d-cli camera presets` |\n| Numbers without a browser | `topview-3d-cli evaluate [plan.json] [--frames 0,24] [--camera ]` |\n| Mesh measurements | `topview-3d-cli inspect nodes ... [--frame N]` |\n| Numbers plus renders per camera | `topview-3d-cli inspect views --camera ... --primary ` |\n| One render | `topview-3d-cli render [payload.json]` |\n| Find a rendered PNG | `topview-3d-cli renders list `, `topview-3d-cli renders show [runId] [--frame N]` |\n| Plan record | `topview-3d-cli bom get `, `topview-3d-cli bom checkpoint patch.json` |\n| Structural validation | `topview-3d-cli document validate ` |\n| Open in Studio | `topview-3d-cli studio open `, then open the returned `url` in the In-App Browser |\n\n## Hard rules\n\n1. Coordinates are right-handed, Y up, metres; rotations are Euler degrees; scale is a positive\n multiplier (`0.001` for a paper-thin axis). Node ids match `[A-Za-z0-9_-]{1,128}`.\n2. Measure before grounding or seating (`topview-3d-cli inspect nodes`); frustum and ground checks in\n `evaluate` use node origins and primitive boxes only.\n3. Every scene keeps one dedicated bird's-eye camera (BOM camera role `layout_overview`), refitted\n after layout changes. It is layout evidence, never the primary story image.\n4. Choose one BOM `story` camera as `--primary` for `inspect views`. Unless the user sets the\n count, cover multi-person scenes per the minimums in `references/camera.md` (3 or more people:\n a group master, one view per interacting group and one close-up per main character).\n5. Ordinary \"sitting\" means a chair, sofa, bench or stool unless floor sitting, cross-legged sitting\n or kneeling is explicit. Reuse a seat or build one from 1–4 primitives first.\n6. Report gaps honestly: a simplified substitute is described as such; an unverified constraint\n stays `unknown`.\n7. Thin lines, stripes, z-fighting and aliasing are renderer artifacts, not defects. Edit only with\n a measurement or a failed BOM hard relation behind it. One `inspect views` per correction pass.\n8. Default timeline: 24 fps, 120 frames. Never paste image bytes or Base64 into messages; give\n paths.\n9. Change the 3D scene with the CLI. Do not edit it through the Studio page or browser automation.\n10. Open the local Studio in the In-App Browser so the user can view it. `studio open` only starts\n the server and returns `url`; open that `url` in the In-App Browser, not the system browser.\n If it fails because Next.js is not installed, run `pnpm install` in the checkout's `editor/`\n directory once and retry `studio open` once. See `references/doctor-browser.md`.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}