@martini-film/cli 0.2.0 → 0.4.0

package/dist/generated/guide.json

@@ -0,0 +1,104 @@
+{
+    "version": 1,
+    "transport": "cli",
+    "hash": "4ef5a98ba7228a60b3c0d69d82c216211c3531ee089a35a914f3de7f1cc03646",
+    "generatedAt": "1970-01-01T00:00:00.000Z",
+    "topics": [
+        {
+            "id": "orientation",
+            "title": "Orientation and the board",
+            "lines": [
+                "Make AI videos with Martini, an AI video production tool. You work in projects that hold canvases and nodes (shots), and a workspace-level LIBRARY of reusable collections (characters, props, locations, styles) referenced in prompts. Use get_projects to find existing projects; if none match and the user wants a new one, use create_project, then create_canvas before adding board content, and link_library_to_project to load library collections into it.",
+                "- When the user names a project, prefer get_board_overview with projectQuery as the primary board context read, or get_projects with query/exactName when you only need project identity. Do not list every project unless the user asks.",
+                "- Choose the project once: martini use <project name or id> writes .martini/context.json, and every later command in this directory takes its project and canvas from it (--project / --canvas on a command override it). Your shell is new on every command, so an exported variable does not last; the file does.",
+                "- Use rename_project only when the user explicitly asks to rename a whole project. Do not confuse it with collection.rename (edit_library) or update_bins.",
+                "- Orient before acting: use get_board_overview first when possible; it returns canvases, the library collections enabled for the project, variables, and direct canvas children. Use get_library for the whole workspace library, and get_canvas_children for narrower canvas/bin spatial follow-up. Add nodes to an existing canvas; only create_canvas when there is none or the user asks.",
+                "- Placing new nodes relative to existing ones: prefer the --placement intent on create_node/create_nodes/create_node_and_generate/create_nodes_and_generate over computing coordinates. --placement '{\"rightOf\":\"<id>\"}' drops an alternative on that node's row; '{\"below\":\"<id>\"}' drops a transform under it; '{\"bin\":\"<id>\"}' or '{\"bin\":\"new:<name>\"}' groups nodes in a bin. Martini reads sizes and clears occupied rows for you, so you don't need a get_canvas read first. Omit --placement and --position entirely for auto-placement to the right of existing content.",
+                "- Absolute position is the power path when you need exact pixel control. Canvas coordinates are absolute pixels, origin top-left: x increases rightward, y downward. Every node, subject, collection, and note reports an absolute position {x,y} plus a rendered size {width,height}. To compute relative to item A yourself, read it first: A's right is x = A.position.x + A.size.width + 20 at y = A.position.y; below A is y = A.position.y + A.size.height + 15 at x = A.position.x. Always read A's size — node heights vary by aspect ratio. position and placement are mutually exclusive.",
+                "- move_node and move_node_to_bin both take absolute coordinates; Martini converts to bin-relative storage for you. move_node only repositions a node within its current container — to take a node out of a bin (or drop it into one), use move_node_to_bin with targetBinId (null for the canvas root) and placement \"absolute\" with the final position.",
+                "- Use create_node/create_nodes to create draft nodes for planning, layout, storyboards, or user review. They never start generation or spend credits. draftPrompt seeds the editable prompt. Library elements attach at generate time (create_node_and_generate / generate), not on draft nodes.",
+                "- Node summaries expose displayName when a user-visible shot title exists. Pass displayName when creating planned shots, or use set_asset_metadata with displayNames to update titles later.",
+                "- To reframe or split a completed image without generation or credits — e.g. cutting a grid or contact-sheet image into separate shots, or isolating one character — use crop_image with action \"create\" and rects in natural pixels of the source image (read its width/height with get_asset first). Use action \"recrop\" to adjust an existing crop node; earlier crops stay in the node's cropRevisions history (visible via get_asset), and action \"restore\" re-points the node at an older revision.",
+                "- To perceive a video AS video — motion, continuity, whether the intended action actually happened — use martini inspect_video --video-asset-id <id> on a completed video asset (it returns one labeled contact sheet of frames sampled across the clip, plus duration/fps; printed, the sheet is a media stub, so save it and open the file: --out-dir <dir> writes one sheet per shot and prints which file is which, --out sheet.jpg writes one) instead of guessing timestamps with extract_video_frame. To QA a timeline edit you just made, use render_timeline_frame to see the COMPOSED timeline (clip order, trims, ordering, track priority) at a time or across a strip; it shows the top visible clip per instant, not baked transitions/filters.",
+                "- When reporting or referencing Martini canvases, shots, assets, or notes back to the user, prefer returned deepLinks.display.*.markdown. Use canvas deepLinks.display.canvas.markdown for whole canvases, and asset deepLinks.display.expandedViewer.markdown when the user should land directly in the expanded player.",
+                "- A workflow's kit can ship agent skills. When a workflow lists skills (get_board_overview workflows, list_saved_workflows, add_workflow_to_canvas, get_workflow_authoring kit.skills), read the skill before changing that workflow's bins, variables or briefs or starting a run: martini get_workflow_authoring --sections kit lists each skill's files and its download call; fetch the signed download URLs directly to disk.",
+                "- For board cleanup/layout edits, use the task-shaped batch tools when possible: move_nodes for multiple asset nodes, update_bins for bin rename/move/resize/collapse, and set_asset_metadata for review labels or node displayNames. Use dryRun true for layout previews.",
+                "- Use reorder_variation_stack_members only to reorder an existing variation stack; do not use it to add or remove members."
+            ]
+        },
+        {
+            "id": "library",
+            "title": "The library and board variables",
+            "lines": [
+                "- Keep characters and props consistent by reusing library collections rather than describing them in words. When the user names a character or prop, match it to a collection (get_library) and pass it as an element (--elements '[{\"libraryCollectionId\":\"<id>\"}]'), referencing it in the prompt as @Element1, @Element2… The project must have the collection enabled (link_library_to_project). Ingest anything that will recur into the library (import_library_assets). Exception: if the project already establishes characters or props through variables in its prompts, follow that convention instead of switching to elements.",
+                "- Board variables (listed in get_board_overview) often hold established canon: character sheets, recurring props, locations, style rules. Before writing prompts for an established project, read the relevant variables (get_variable — overview previews are truncated) and reuse what they establish rather than inventing alternatives.",
+                "- The library is workspace-scoped (personal or team org), managed with get_library / get_library_collection / edit_library / import_library_assets. Collections hold image/video variant assets plus text fragments; text fragments in project-enabled collections expand in prompts as @{id:name} chips (get_library_collection returns each promptChip ready to paste). Never modify collections marked sample:true (community samples).",
+                "- Use view_library_asset to visually inspect a library asset before electing it as an element frontal or collection hero."
+            ]
+        },
+        {
+            "id": "timeline",
+            "title": "The timeline",
+            "lines": [
+                "- For timeline edits, use get_timeline_context for a compact read, then apply_timeline_edit with dryRun true for complex edits. Prefer high-level actions like assemble, insert, update, remove, reorder, and normalize over many small raw edits. When inserting video assets, audio is included by default on split audio/video timelines; pass linkMode \"none\" only if the user explicitly asks for silent video.",
+                "- To mix a cut, set clip gainDb/fadeIn/fadeOut and track gainDb/pan through apply_timeline_edit (levels live on audio clips and audio tracks; a linked pair carries them on its audio half), then measure with get_timeline_audio_report against the delivery targetLufs/truePeakDbtp and pass the same targets to render_timeline. The report costs a draft-render quota slot, so edit first and measure once per revision.",
+                "- To see the cut, render it and open the file: martini render_timeline_frame --time <t> --out frame.jpg for one moment, or --frame-count <n> for a strip across the sequence."
+            ]
+        },
+        {
+            "id": "generation",
+            "title": "Generation",
+            "lines": [
+                "- When the user names a model or provider in natural language, preserve that choice. Pass that name as modelQuery to have Martini resolve it server-side (for example, \"GPT image\" or \"OpenAI image\" resolves to gpt-image-2); modelId must be an exact Martini model ID. If a modelId is not recognized and a close one exists, the error names it to retry with. Use get_models when you need exact inputs, limits, or to disambiguate.",
+                "- When new shots should match existing ones, read each reference shot's full prompt with get_asset before generating and mirror its structure (scene breakdowns, camera specs, level of physical detail) for the whole batch. promptPreview in list results is truncated — never prompt from it.",
+                "- Stay on the model the project already uses: completed shots report modelId (get_asset also reports draftModelId). Generate with that model unless the user asks to switch.",
+                "- Bind every generation reference by its 1-based array position: @ImageN for referenceImages, @ElementN for elements, @VideoN for videoReferences, and @AudioN for audioReferences. Bare names do not bind media. One contact sheet is one reference, not one per panel; crop or use separate images when panels need distinct tokens. Do not combine start-frame image-to-video inputs with reference arrays.",
+                "- Keep ordered cuts, dialogue, entrances, and impacts achievable within the selected duration. Split dense narrative sequences into separate generations when action order must remain clear.",
+                "- Generations cost credits and cannot be undone, and the CLI has no spend confirmation of its own; --approve --max-olives N caps a quoted command. Use generate or create_node_and_generate only when the user clearly wants generation now. For multiple, expensive, or ambiguous requests, lay out the plan first — model, prompts, count, rough cost — and get the user's approval before running any generate command.",
+                "- If a generation command times out or exits non-zero, verify state with martini get_board_overview and martini get_jobs before retrying: a submitted generation keeps running after the command ends, and a retry generates (and charges) twice. If no new node/job exists, say the request does not appear to have reached Martini; if it keeps failing, suggest Martini support.",
+                "- Generation is asynchronous: submitting returns a jobId. Wait with --wait on the generating command, or martini wait <asset-id…> --timeout 45 for every shot you are watching (one command; it returns as soon as they settle, and exit 4 means they are still running, so run it again) rather than polling get_jobs in a loop, and do not call a shot done until it completes and you have reviewed it — view_asset for images, inspect_video for video (so you actually judge motion and continuity, not a single still). Flag problems the user may not have noticed (off-prompt, inconsistent, unintended likeness).",
+                "- When a shot was generated with a staged voice take (audioReferences), judge sync with martini analyze_video_audio --video-asset-id <id> --reference-audio-asset-id <id>: it returns speech segments, loudness, where the take sits in the clip, and whether it was re-timed — instead of downloading the mp4.",
+                "- When a shot was staged from a start or end frame, or clips are joined on the timeline, judge the pictures with martini analyze_video_frames --video-asset-id <id> (plus --first-frame-reference-asset-id, --last-frame-reference-asset-id, or --timestamps-sec as needed): it says whether the first/last frames are the staged stills (match / similar / different with the numbers) and which of the named timecodes are black frames — a scripted check before a contact sheet."
+            ]
+        },
+        {
+            "id": "storage",
+            "title": "Uploads and downloads",
+            "lines": [
+                "- martini upload <files…> --canvas <id> runs prepare, the PUT to storage, and complete in one step, waits until the assets are processed, and lists a file it could not store under failed with its code, so there is no separate reachability check to make. martini download <asset-id…> --dir out/ saves files when the user wants them saved; ask where to save them first."
+            ]
+        },
+        {
+            "id": "support",
+            "title": "Support",
+            "lines": [
+                "- When the user is blocked by Martini setup, CLI sign-in, generation/upload failures, unclear product state, or repeated command failures, proactively offer help from Martini support as a practical next step.",
+                "- Frame support around unblocking the user: Martini support can use a redacted support packet to diagnose the issue faster, with their account email included so the team knows who needs help.",
+                "- If the user asks for help from Martini or agrees to contact support, offer to prepare a support request. Explain the categories of information you will include before using prepare_support_request.",
+                "- Use prepare_support_request only after the user asks for support or clearly agrees to prepare a support packet. Redact secrets, tokens, signed URL query strings, unrelated private conversation, and sensitive creative prompt details before sending command arguments whenever possible.",
+                "- After prepare_support_request, show the returned preview and redaction summary to the user. Mention that the request includes their account email for support follow-up if needed. Let the user ask for more redaction or changes before submission.",
+                "- Never call submit_support_request until the user has seen the support preview and explicitly tells you to send, submit, file, or escalate it, after being told the account email is included.",
+                "- If the user declines support, continue helping in the current conversation. Do not pressure them or repeat the offer unless a new blocker appears.",
+                "- If user frustration appears, recommend support by naming the concrete blocker and the help available. Do not ask whether the user is frustrated."
+            ]
+        },
+        {
+            "id": "shell",
+            "title": "Working from the shell",
+            "lines": [
+                "- Every command prints its result as JSON on stdout; errors and warnings go to stderr as JSON too, so stdout can go straight into jq or a file. Exit 0 means the command did everything it was asked; on any other code read error.code, and expect the part that was done on stdout (a push's skipped files, a timed-out wait's pending ids).",
+                "- --fields a,b.c keeps only those dotted paths of a result. A path that matches nothing is named on stderr; when none match, a read exits 2 and a command that wrote something prints its whole result instead, so do not run it again. A field that is a map keyed by id is stepped into for you (assets.status), or explicitly with a quoted * ('assets.*.status').",
+                "- --out <file> writes the result to a file and prints a one-line JSON receipt. With a media extension (.jpg, .png, .webp) it writes the picture of a tool that shows one (view_asset, render_timeline_frame); --out-dir <dir> writes every picture of a result (inspect_video on several shots) and prints { dir, files }, each file with the asset it shows. Nothing is shown to you until you open the file.",
+                "- Any argument can be passed as JSON: --args @args.json for the whole call, or one flag at a time, as in --placement '{\"rightOf\":\"<id>\"}'; a list of objects reads a file too (--nodes @nodes.json). martini <tool> --schema <flag> --keys lists the keys such an argument takes.",
+                "- An asset id works in either spelling a result prints: the bare id, or the node id asset-<id>.",
+                "- A generation command takes --wait to block until its assets are ready (on by default for single-item generations), and martini wait <ids…> --timeout N resumes one. Exit 4 means not ready yet: stdout carries the pending ids and stderr the command that resumes the wait. Exit 1 with ASSET_FAILED or JOB_FAILED means a shot settled without completing: the outcome is on stdout, and nothing is retried for you.",
+                "- Tools that quote first (generate_nodes, upscale_assets, enhance_draft) take --approve --max-olives N: the quote is approved only when its total is under the cap. Over the cap nothing starts and the exit is 5, with the quote on stdout: ask the user before raising the cap.",
+                "- martini <tool> --help shows a tool's flags and the result fields it declares (--help --all prints a long page whole); martini tools says how the server's tool list differs from this build's; martini call <tool> --args '{…}' calls one by name.",
+                "- martini files pull <dir> and martini files push <dir> never lose an edit silently: push exits 1 when a file changed on the server since the pull, and pull keeps a file you edited, setting the server's version aside under .martini/conflicts/ for you to merge.",
+                "- A command that prints a GUIDE_CHANGED warning ran with a guide older than the one the server serves: run martini guide again before relying on its rules.",
+                "- The MCP connector is for hosts without a shell (Claude Desktop, ChatGPT, claude.ai); when both are installed, the CLI is the one to use.",
+                "- Exit codes: 0 done, all of it · 1 tool error · 2 usage · 3 auth · 4 not ready or timed out · 5 over budget (olives, or a quote over --max-olives)."
+            ]
+        }
+    ]
+}