Workspace setup and diagnostics

Run these commands from an intact source checkout with Python 3.13+. See installation for optional capabilities. The setup helper does not launch apps, contact providers, discover render services, download weights, or generate media.

$studioWorkspace = Join-Path $env:USERPROFILE 'StudioWorkspace'
python bin/studio_setup.py init "$studioWorkspace" --intuition
python -m studio.paths root
python bin/studio_setup.py doctor

Choose a new, empty folder outside the checkout. init creates the workspace, builds and verifies the generic doctrine pack, and seeds welcome with held example cues. --intuition also activates the installed Intuition pack ("packs": ["intuition"]), builds the intuition-studio doctrine pack from it and selects it for future productions; since packs phase 4 the pack is its own repository, so run python bin/studio_setup.py pack add https://github.com/0xIntuition/studio-pack-intuition.git first (without it --intuition refuses before writing anything and prints that line). It copies no character bible: the repository carries none, the roster starts empty, and a principal is added in its piece's cast/CAST.md (docs/WORKSPACE.md § Cast). The welcome example retains its generic doctrine. Private vault attachment never selects shared doctrine or identity. Setup does not approve draft canon or create missing identity locks.

Successful setup saves an ignored .studio-local.json in this checkout. New terminals and independently opened desktop clients using this checkout resolve that choice. No client settings, shell profiles, or machine environment are edited. --no-select creates without changing the choice. To use an already initialized workspace:

python bin/studio_setup.py select "C:/path/to/existing/workspace"

The resolver precedence is: explicit operation workspace, STUDIO_WORKSPACE, nearest studio.json above the current directory, checkout-local choice, legacy CA_ROOT/STUDIO_ASSET_ROOT, then, on Windows only and only when that directory exists, the historical F:\CreativeAssets. With none of them the studio is not set up: python -m studio.paths root prints studio not set up … run python bin/studio_setup.py onboard on stderr and exits 2, the SessionStart banner reads workspace: none (via unset) with the onboarding nudge, every tool that needs a root refuses with the same line, and the spend gate finds no workspace receipts, so it refuses every gated spend. select reports both the saved choice and the effective choice and flags an override. Named profiles (python bin/studio_setup.py profile list|add|use|remove|show|export) are names for initialized workspaces kept in the same file's workspaces; profile use <name> is select by name and does not change this order. After the workspace: line the SessionStart banner prints profile: <name|unnamed> · <root> · packs <list|none> · doctrine <x> · storage <label|none>, and appends (<source> wins over the saved profile <name>) whenever a cd or STUDIO_WORKSPACE overrides the saved choice. Each worktree has its own local choice. A malformed local file fails visibly instead of silently switching drives. Confirm python -m studio.paths root inside each client before writing production records.

init refuses a nonempty target. An interrupted initialization retains its partial files and saves no new local choice until successful completion. Inspect those files before deciding to repair that workspace; for a clean rehearsal choose another empty directory. Never use a force option to overwrite someone's existing work. select requires a schema-1 studio.json; it does not repair files or copy context.

Read the doctor report

doctor is read-only. doctor --workspace <path> inspects another workspace without selecting it. Exit 0 means the minimum planning environment exists; exit 1 means it does not; invalid input returns 2. The JSON fields deliberately answer different questions:

Field	Meaning
planning_ready	Python baseline, workspace config, the shared instruction files (instructions) and every pack rule this workspace requires (pack_rules) are present. This is not permission to generate.
instructions	The files every studio checkout needs, present or not: AGENTS.md, CLAUDE.md, .claude/rules/creative-loop.md.
pack_rules	Rules files an in-repo pack declares (packs/<name>/pack.json provides.rules), each {present, required, pack, doctrine}. pack:intuition/rules/intuition.md belongs to the intuition pack (doctrine intuition-studio) and is required only when that pack is active for the workspace (packs below), the workspace's studio.json doctrine is intuition-studio, or the workspace is Intuition work (its studio.json team is intuition, or the intuition-studio pack is built there; the saved profile's team covers the whole checkout and does not count); anywhere else its absence is reported and does not block.
packs	Studio packs (docs/PACKS.md): found (each in-repo and installed pack with valid and errors), active and source (studio.json for an explicit packs list, fallback for the packs matching the workspace's team or doctrine), missing/invalid active packs, links (linked, stale, missing, extra, conflicts, in_place for an installed pack's rules and skills) and problems. A missing or invalid active pack is a red row: every preflight in that workspace fails closed until it is fixed. It does not change planning_ready.
workspace	Effective path (null when nothing selects one, with selected_by unset), selection source and whether the old machine fallback was used.
doctrine.verified	The selected workspace pack matches its manifest. Production-specific packs and gates still need their own checks.
doctrine.current	The pack matches current repository/workspace inputs (verify --sources), separate from integrity.
context	Selected bible, repository location, optional private-vault path, and repository inventory/revision/uncommitted changes. A vault is not needed. Unknown Git state is reported as null.
clients	Codex wiring/self-test or Claude hook definitions. runtime_interception remains unverified: this process cannot certify another client's tool dispatch.
optional	Package, executable and identity-weight presence. Presence is not a successful render, model inference or version compatibility test. Providers are not contacted.
profile_active	The profile this run is in (packs phase 3, docs/PACKS.md § Profiles): name (from .studio-local.json workspaces, null when the workspace is unnamed), root, packs, doctrine, storage, selected_by, saved (the saved active profile) and overridden (the resolver source that wins over the saved choice, e.g. nearest studio.json after a cd), plus line, the same text as the SessionStart profile line. The Active profile row is amber when the workspace is unnamed or overrides the saved choice. Never changes planning_ready.
storage	The workspace's studio.json storage label and whether its credentials are present (credentials: found, missing, invalid, or n/a with no label), with source, bucket, endpoint and permission warnings; never a key. No network: python bin/studio_setup.py storage check <label> is the reach test. Never changes planning_ready.
profile	The profile onboard saved in .studio-local.json (name, team, role, harnesses, hosted, local, editor, handoff editor, motion graphics, Blender, vault, onboarded_at), or null when the machine is not onboarded. Its mismatches list holds strings such as "said premiere, not found".
tools	One entry per tool (ffmpeg, ffprobe, node, nvidia_smi, claude_cli, blender, premiere, after_effects, resolve, final_cut, comfyui, higgsfield_mcp), each with state (found, missing or unknown), where and a one-line fix. unknown means this process cannot tell; it is not a failure.
hermes	Hermes wiring, reported the same way as clients.codex (and repeated as clients.hermes), plus not-installed when there is no Hermes config and no hermes on PATH; that state is not an error.
readiness	Three booleans: planning_ready (same meaning as the top-level key, which is kept), generation_ready (planning_ready, the doctrine pack verifies, and studio.json has either a hosted-lane connection, or at least one comfyui connection while tools.comfyui is found; tools.comfyui is found when any probed URL answers, and the probe asks every comfyui connection's URL plus the profile's local.comfyui URL (auto means COMFY_URL or http://127.0.0.1:8188), so the answering URL need not be the connection's own; the Higgsfield connector itself is confirmed only in session by /doctor) and editing_ready (planning_ready, ffmpeg and ffprobe on PATH, and the editor the profile names (Premiere, or Resolve / Final Cut for a handoff) not reported missing; agent, later, CapCut, other or no profile need only ffmpeg and ffprobe). The ComfyUI probe runs only when a comfyui connection exists or the profile says local.comfyui is auto or a URL. Readiness is never permission to spend.

doctor --human prints the same report as a green/amber/red table with one fix per line instead of JSON; the exit code is unchanged. Python cannot see three things: the Higgsfield balance, the Higgsfield Bridge host status (Premiere, After Effects, Blender connected) and the claude.ai connectors attached to a session. The /doctor skill checks those in-session, read-only, and compares them with profile. First-time setup is onboard (SETUP_GUIDE.md § 2); init and select remain the manual route.

Missing Pillow, Node, providers, identity weights or ffmpeg does not block planning. Missing ffmpeg blocks encoding; missing identity instruments blocks a requested measurement. Address the capability actually needed instead of installing the entire optional stack.

If sources differ, review the repository changes and rebuild the selected pack explicitly when appropriate; the doctor never overwrites sources or a workspace bible. Before real brand work, record the maintainer-confirmed context revision and pack. Before generation, perform the actual client activation checks and the shared workflow's current cost, cue, identity, phase and prompt checks. Codex activation distinguishes local configuration from runtime trust; the internal guide covers both clients.