cli-maintenance

name	cli-maintenance
description	Checklist and decision tree for adding, modifying, or removing CLI commands. Keeps CLI source, slash commands, docs, and skills in sync.
requires	{"scripts":["tools/scripts/cli_sync_check.py"]}

CLI Maintenance

When to use this skill

• Adding a new subcommand to the CLI
• Changing args/behavior of an existing command
• Removing or renaming a command
• Responding to a cli-plugin-sync hook reminder
• Auditing CLI / plugin / docs consistency

Adding a CLI Command — Full Checklist

1. Implement in CLI source

• Create tools/cli/cmd_<name>.cpp with int cmd_<name>(const std::vector<std::string>& args)
• Add declaration to tools/cli/cli_common.hpp in the command forward declarations section
• Add entry to the command table in tools/cli/pulp_cli.cpp (Command, ScriptCommand, or BinaryCommand)
• Update tools/cli/CMakeLists.txt to compile the new file

For Rust-native commands, the source of truth is experimental/pulp-rs/src/main.rs's enum Command plus the matching experimental/pulp-rs/src/cmd/<name>.rs implementation. Add the command to experimental/pulp-rs/src/help.rs too; the installed Rust binary's help banner is user-facing even when there is no C++ table entry.

2. Update the CLI commands manifest

• Add entry to docs/status/cli-commands.yaml with:
  • name, status (use status vocabulary: stable/usable/experimental), summary
  • args with name, kind (positional/option/flag/passthrough), description
  • subcommands if applicable

3. Decide: does this need a slash command?

Create a slash command (.claude/commands/<name>.md) if:

• The command is user-facing and interactive (not plumbing)
• An agent would benefit from a /name shortcut
• The command has a natural "ask the user then run" pattern

Skip a slash command if:

• It's a low-level plumbing command (e.g., cache clean)
• It's adequately covered by an existing skill
• It's a subcommand of something already covered

Commands that intentionally don't have slash commands: audio, cache, clean, export-tokens, ci-local, design-debug, harness, help, identity, macos, overflow, projects, project, tool, tweaks

project, tool, and tweaks intentionally stay slashless: project is a per-project SDK pin helper, tool is registry/install plumbing for optional developer tools and importer add-ons, and tweaks is a local pulp-tweaks.json drift diagnostic that mirrors the inspector drawer. identity is an audit/review helper whose lockfile diff should stay explicit in the terminal and commit. Agents call these CLIs directly. Keep this classification in sync with tools/scripts/cli_sync_check.py and tools/scripts/cli_mcp_parity_baseline.json.

Commands that DO have slash commands (list for cross-reference, not exhaustive — ls .claude/commands/ is authoritative): build, test, run, validate, ship, version, doctor, create, docs, status, design, import-design, inspect, pr, ci, ci-host, upgrade, prototype-loop, motion, trace, audio-harness, audio-inspect, audio-compare

audio-harness is a workflow slash command (wraps the audio observability harness ctest targets + the audio-harness skill) — it is NOT a pulp CLI subcommand. Note the distinction from the pulp audio CLI: that command owns the model/bundle tooling (model/excerpt-find/read-bundle), the offline pulp audio validate <verb> harness CLI (summarize/doctor/compare/assert, tools/cli/cmd_audio_validate.cpp, over captured WAVs / audio-run/ bundles — no live plugin), AND pulp audio render (tools/cli/cmd_audio_render.cpp driver + cmd_audio_render_parse.cpp pure parser + the header-only cmd_audio_render_step.hpp block stepper), which DOES load a plugin: it renders an explicit --plugin <bundle> offline through pulp::host::PluginSlot and emits a WAV + the same metrics manifest the validate verbs read. Three render gotchas: --param <id>=<value> is the PLAIN parameter domain (native min..max, NOT normalized [0,1] — the PluginSlot::set_parameter arg name normalized_value is a misnomer; every loader treats it as plain); --param @frame is sample-accurate — the per-block queue the stepper builds is forwarded straight to PluginSlot::process (all four loaders apply param_events at the sample offset; LV2 block-rate by its control-port nature) and the driver does NOT also call set_parameter (that double-applies); and the stepper is a deliberate callback-driven parallel to OfflineRenderHost::render (PluginSlot has no ProcessContext, so it can't reuse the core renderer) guarded by a block-partition-invariance test. pulp audio intentionally has no slash command of its own; the /audio-harness command documents the validate and render verbs. Keep the live boundary in sync with the audio-harness skill: live Audio Inspector use is landed under /audio-inspect / pulp run --audio-inspector, and live capture-to-WAV is landed in two modes — pulp run --audio-capture-wav (earliest-window int16 dump — good for validate summarize/assert) and pulp run --audio-capture-rolling (last-N via RollingAudioCaptureBuffer — the steady-state window doctor/compare want — float by default, or int24 via --audio-capture-rolling-format int24). When adding a run capture flag, mirror slice A/A2's surfaces: cmd_run.hpp/cmd_run_parse.cpp/cmd_run.cpp, the standalone detail/standalone_audio_capture_* writer + standalone_environment.hpp env+predicate, docs/status/cli-commands.yaml (under run), docs/reference/cli.md#run, and both the audio-harness and this skill. When adding a validate or render flag, update the matching cmd_audio_*.cpp, docs/status/cli-commands.yaml (nested under audio), docs/reference/cli.md#audio, and both skills. WAV writing is write_wav_file(path, data, WavBitDepth) — Int16 (default overload), Int24, or Float32. pulp audio render is also exposed as the pulp_audio_render MCP tool (tools/mcp/mcp_tools.cpp handler + pulp_mcp.cpp tools_list/dispatch + test/test_mcp_server.cpp membership/required-arg coverage + the docs/guides/claude-code-plugin.md tool table); it takes a single param/midi token (the hand-rolled MCP JSON has no array extractor), returns the metrics JSON, and defaults --out to a temp WAV. When adding a render flag worth exposing, mirror it there too.

pulp ship swap-pack signs a hot-reload UX bundle (tools/cli/cmd_ship.cpp). It is the only ship subcommand that does NOT require a configured build/ dir (it signs an explicit --bundle, gated out of the build-dir check by sub != "swap-pack"). It reuses the header-only reload building blocks — build_signable_manifest (walk + hash + capability inference from the JS), swap_pack_signing_summary, serialize_swap_pack_manifest, and key_store — so the CLI itself is thin assembly. The Ed25519 signing key comes from a --sign-key <file> (created if absent) or, on macOS, the login keychain under pulp.reload.signing.<plugin_id> / account gen1 (stored as a single-line base64 of the key blob); a freshly generated key prints a loud provenance/backup banner and is NEVER silently regenerated (a corrupt keychain entry is refused, not overwritten). The subcommand is GPU-gated only because the whole CLI target is (if(PULP_ENABLE_GPU) around add_subdirectory(tools/cli)), so its shell-out test pulp-test-cli-swap-pack runs in GPU builds.

pulp audio compare is the shipped CLI verb over the dev-only Python Audio Quality Lab compare surface (tools/audio/quality-lab/, advisory measure→compare→judge). It is a thin ORCHESTRATOR: tools/cli/cmd_audio_compare.cpp locates the opt-in managed tool ($HOME/.pulp/tools/python-envs/audio-quality-lab/run.sh, via tool_registry.hpp locate_tool) and forwards the compare verb + all flags to it — no numpy/soundfile/FFT ever links into the MIT CLI. It parses arity locally (missing WAVs → exit 2), prints an actionable pulp tool install audio-quality-lab hint + exit 1 when the tool is absent, and otherwise passes the tool's stdout/stderr + exit code straight through (2 == could-not-measure/invalid, never a judgment). When touching it, mirror: cmd_audio_compare.cpp/.hpp, the dispatch + usage line in cmd_audio.cpp, CMakeLists.txt, docs/status/cli-commands.yaml (nested under audio), docs/reference/cli.md#audio, the shell-out test test/test_cli_audio_compare.cpp (help/arity/not-installed-hint/forward-and-passthrough via a fake run.sh), and the audio-harness skill. The /audio-compare slash command wraps the SAME surface for agents, and the pulp_audio_compare MCP tool mirrors this shipped verb (like pulp_audio_render mirrors pulp audio render): handler handle_audio_compare in tools/mcp/mcp_tools.cpp (+ decl in mcp_tools.hpp), tool JSON + dispatch + using in pulp_mcp.cpp, an mcp_only entry in tools/scripts/cli_mcp_parity_baseline.json, and membership + required-arg coverage in test/test_mcp_server.cpp + the docs/guides/claude-code-plugin.md tool table. A new audio SUB-verb needs no CLI↔MCP parity promotion (the checker only tracks top-level pulp commands), but a new MCP sub-tool still needs its baseline mcp_only entry. Distinct from the gate-oriented pulp audio validate compare (null/spectral diff, nonzero exit): pulp audio compare is an advisory judgment, never a gate.

Inspector-proxy MCP tools use a different, lighter pattern than the mcp_tools.cpp-handler tools above. pulp_motion_* and pulp_trace_* do NOT have mcp_tools.cpp handlers — they inline-forward in pulp_mcp.cpp's dispatch (an else if (name == "pulp_X_*" || …) block that maps each tool to an inspector_method + --params '<args_json>' and shells pulp inspect --command). So a new inspector-proxy tool needs only: tool JSON in tools_list_json(), the inline dispatch block, membership in test/test_mcp_server.cpp's expected list, and the docs/guides/claude-code-plugin.md table — no handler, no mcp_tools.*. Parity: a tool whose top-level CLI command already carries a cli_only baseline entry (e.g. trace) needs NO new baseline row; only add an mcp_only entry for a tool with no CLI peer at all. Client-side CLI verbs with no inspector RPC (trace doctor / open / fetch, offline query --trace) get no MCP tool — say so in the plugin-table row and the cli_only reason so the asymmetry reads as intentional.

Not every slash command wraps a pulp CLI subcommand. A slash command may also document a developer-tool surface with no CLI backing — e.g. audio-inspect opens the in-app Audio Inspector window (pulp::view::AudioInspectorWindow, registered via CommandRegistry), so it needs no cli-commands.yaml entry and no pulp <name> subcommand. When a slash command is window/feature documentation rather than a CLI wrapper, skip the CLI-source / manifest / docs/reference/cli.md steps and just keep the .md and this cross-reference accurate.

4. Update docs

• Add/update section in docs/reference/cli.md
• If it changes capabilities: update docs/reference/capabilities.md
• If it's in the plugin: update docs/guides/claude-code-plugin.md command table

5. Update skills that reference CLI commands

• grep -r "pulp <name>" .agents/skills/ — update any skill that calls this command

6. Update CLAUDE.md if needed

• If the command is referenced in the "CLI tool" code block
• If the command changes the build/test/validate workflow

7. Validate sync

python3 tools/scripts/cli_sync_check.py
python3 tools/scripts/check_cli_mcp_parity.py --mode=report

cli_sync_check.py unions the C++ command tables with Rust-native commands from experimental/pulp-rs/src/main.rs. check_cli_mcp_parity.py uses the same installed-command model by default, so a Rust-only command still needs either a matching pulp_<command> MCP tool or an explicit tools/scripts/cli_mcp_parity_baseline.json reason.

8. Decide: does this need an MCP tool?

Every top-level CLI command is checked for MCP parity by tools/scripts/check_cli_mcp_parity.py. The check enforces an invariant: a new CLI command must either land alongside a pulp_<command> tool in tools/mcp/pulp_mcp.cpp (with both a tools_list_json() entry AND a handle_request() dispatch arm), OR it must be added to tools/scripts/cli_mcp_parity_baseline.json under cli_only with a one-line reason.

Decision heuristics for "does this deserve MCP exposure":

• One-shot RPC-shaped command (build, test, validate) → YES, add the MCP tool.
• Long-running watch/loop (dev, loop, run, host) → NO, baseline it.
• Trivial Bash equivalent (clean, version, config) → NO, baseline it.
• Interactive surface (design, ship) → NO, baseline it.
• Subcommand under an umbrella tool already present (audio, docs, inspect) → NO, baseline it (the umbrella's sub-tools cover the surface).
• Trust-boundary workflows with many reviewable subcommands (kit/content) → YES for the umbrella and explicit MCP sub-tools. Keep pulp kit and pulp content documented as top-level CLI commands, but expose agent-safe sub-tools such as pulp_kit_plan, pulp_kit_apply, pulp_content_preview, and pulp_content_install so MCP callers cannot blur inspect/preview/approve/apply boundaries. Add those sub-tools to the mcp_only baseline with a reason that they are sub-tools of the umbrella CLI command, not missing top-level CLI peers.
• tools/cli/kit_commands.cpp is a frozen refactor hotspot. Before moving kit command code, follow tools/cli/KIT_COMMANDS_MODULE_MAP.md: keep manifest validation, archive safety, publish policy, apply/remove mutation, profile verification, and dispatch in separate modules, and lower the hotspot ceiling when the split shrinks the monolith.

The gate runs in three places, all pinned to the same script:

1. hooks/scripts/cli-plugin-sync.sh — advisory --mode=hint after Edit/Write of pulp_cli.cpp, pulp_mcp.cpp, or the baseline JSON.
2. .github/workflows/version-skill-check.yml — enforcing --mode=report on every PR. Hard-fails if a new CLI command lacks both an MCP tool and a baseline entry.
3. The shipping pre-push gate stack (skill-sync / version-bump / compat-sync) — the parity check rides alongside.

Naming convention: hyphenated CLI command import-design ↔ underscored MCP tool name pulp_import_design. The script handles the conversion automatically; baselines should use the form natural to each side (cli_only is hyphenated, mcp_only carries the full pulp_ prefix).

When promoting an entry off the cli_only list, add the matching pulp_<command> tool to tools/mcp/pulp_mcp.cpp and the parity check will auto-detect the new coverage; remove the baseline entry in the same PR.

Adding an inspector sub-tool (e.g. pulp_inspect_set_param)

Inspector tools are MCP sub-tools of pulp inspect, so they live in the mcp_only baseline (no top-level CLI command of their own) — add the new pulp_inspect_* name there or the parity check hard-fails. Two gotchas when the tool takes arguments:

• Pass arguments via pulp inspect --params '<json>', not by concatenating the JSON after --command METHOD. The CLI parses --command and --params as separate flags; a bare {...} token is ignored. Read-only tools that take no args sidestep this, so don't copy their dispatch shape for a tool that carries a payload.
• Do not wrap inspector error text as media. Protocol-reserved methods that are not wired yet (for example the screenshot surface waiting on a WindowHost reference) should return ordinary text/error content through MCP until the inspector method returns a real payload.
• The scripted-UI runtime inspector IS wired now. Runtime.evaluate, Runtime.getCapabilities, Runtime.interrupt, and Console.getMessages (device-log cursor poll) reach the live JS engine when a host calls DomainHandler::set_script_inspector(session.script_inspector()). Evaluate is marshaled onto the engine thread by ScriptInspectorBridge — single in-flight, ~2 s timeout, auto-interrupt on hang. It is an honest evaluate/inspect console, NOT a step debugger: mainline QuickJS has no breakpoint protocol, so getCapabilities reports canBreak/canStep/canInspectLocals=false. Cover these in test_inspector_domains.cpp. See docs/reference/scripted-ui-inspector.md and the engine skill's interrupt section.
• Mutating tools must go through a typed inspector method (e.g. State.setParameter) with validation + gesture wrapping in StateInspector/DomainHandler — never via Runtime.evaluate. Cover the happy path, the unknown-id error, and any normalized/raw mode in test_inspector_domains.cpp.

Modifying a CLI Command

Same as above, focus on steps 2, 4, 5, 6, 7. Key risks:

• Changed args not reflected in cli-commands.yaml
• Changed behavior not reflected in slash command .md
• Skills calling the old invocation syntax
• Slash-command recipes must only name flags accepted by pulp <cmd> --help and docs/status/cli-commands.yaml. Do not invent convenience aliases such as --formats; for platform-gated defaults, document the real opt-in flag (for pulp create, --targets android) or omit the prompt entirely.
• /test must invoke pulp test or ./build/pulp test, not raw ctest --test-dir build; the CLI owns project-root resolution, cold-start builds, FetchContent cache preflight, and ctest passthrough. If slash-command arguments already contain ctest flags such as --exclude-regex, forward them after pulp test instead of wrapping the whole argument string in -R.
• Output path flags should accept both nested paths and bare filenames; guard empty std::filesystem::path::parent_path() before creating directories and add shellout coverage for the bare-filename case.

pulp status — build-governance tier line

pulp status reports the active host-resource governance tier via a Build governance: Tier N (…) line, backed by detect_build_governance() in tools/cli/tartci_lease.cpp. Detection is fail-safe (never throws): Tier 2 when TARTCI_ORCHARD_URL is set, else Tier 1 when a resolvable tartci (PULP_TARTCI_BIN or PATH, unless PULP_TARTCI_LEASES=0) answers tartci host-profile (surfacing its PULP_BUILD_JOBS / PULP_BUILD_MEM_BUDGET_MB), else Tier 0 (the CLI's built-in bounded builds). Coverage lives in test/test_cli_tartci_lease.cpp. Keep the tier semantics in step with the lease-acquisition path in the same file.

Package command CMake generation

pulp add can now generate CMake for source-backed FetchContent packages, not only header-only packages or upstream-exported targets. The registry's cmake.sources field means "compile these fetched source files into the declared target." Keep that behavior centralized in package_commands_util.cpp so guarded and unguarded blocks stay identical except for their surrounding if(...) condition.

When adding a new generated-target package shape, update all four surfaces in one PR: tools/packages/registry-schema.json, package_registry.{hpp,cpp}, the CMake block generation helpers, and test/test_cli_package_commands.cpp. mts-esp is the reference source-backed case: generated static target, position-independent code, include dir rooted at the fetched source, and ${CMAKE_DL_LIBS} linked when available.

Some header-only packages should be fetched source-only because their upstream CMakeLists.txt builds tools/tests or exports a target shape Pulp does not want to impose on plugin projects. Set cmake.add_subdirectory=false; generation must use FetchContent_MakeAvailable() with an inert SOURCE_SUBDIR, then create the declared interface target itself. sst-tuning-library is the reference case.

pulp dev --hot-dsp — live DSP hot-swap dev loop

pulp dev --hot-dsp (cmd_dev.cpp) is a watch-loop MODE flag, not a new command. It sets WatchOptions::hot_dsp, which watch_loop() (cli_common.cpp) reads to suppress the post-rebuild relaunch: the launched app stays alive and its ReloadableShell filesystem watcher hot-swaps the rebuilt DSP logic library in place (relaunching would kill the plugin + lose audio/UI state). Gotchas:

• --hot-dsp requires --run <target>; cmd_dev errors (exit 2) otherwise.
• Only meaningful for a reloadable-shell target (one whose processor is a ReloadableShell); for a plain plugin it just means "don't relaunch." The CLI deliberately doesn't inspect the target — it only changes relaunch behavior.
• The rebuild must produce the logic library the shell watches; a normal cmake --build of the project rebuilds it, and the shell's poll picks it up.
• pulp loop --ar-swap-from is retired to a redirect that points here — it no longer prints a bare not-implemented notice (cmd_loop.cpp). If you touch the reload dev loop, keep that redirect message accurate.
• The C++ delegate (pulp-cli) is GPU-gated (PULP_ENABLE_GPU), so a GPU-off worktree can't build/run it; verify CLI edits via a -fsyntax-only parse and rely on the GPU-on CI lane for the link + shell-out --help assertion.
• Parser-order fixes that preserve the documented command surface still need tests proving malformed argv is rejected before platform guards or side effects, especially for commands like pulp ship release where macOS-only execution follows cross-platform flag parsing.
• Shell-out wrappers that build a command string must quote resolved repo/config paths and every forwarded user argument before interpolation. For passthrough commands such as pulp docs build-site, add a fake-tool PATH test that records argv from a nested cwd and includes spaces in forwarded paths, so config discovery and argument preservation do not depend on the real external tool being installed.
• Platform-specific flags are still parsed cross-platform but only act inside a platform #if. E.g. pulp ship package --format appimage --binary <exe> [--icon <png>] parses everywhere, yet only the #if defined(__linux__) arm routes to pulp::ship::create_appimage; on other platforms the flags are accepted-but-inert. Document the flag in cli-commands.yaml regardless, and put the behavioral assertion in a platform-gated unit test (here: test_linux_packaging.cpp) rather than a cross-platform shellout, since the required macOS lane can't exercise the Linux-only branch.
• pulp ship package (macOS) DEFAULTS to a single component-selectable .pkg: it collects every built format into one create_combined_pkg call so the installer shows a Customize pane (one pre-checked, toggleable choice per format) — users are never forced to install every format. --separate is the legacy per-format-.pkg path; --dmg makes disk images. Discovery scans the whole build/{VST3,CLAP,AU,Standalone} tree, so a multi-example build bundles EVERY plugin's formats (dozens of choices) unless you pass --product <name> to scope to one product's bundles (also names the installer). Verify a real installer by unpacking its Distribution (xar -xf … Distribution) and checking for <options customize="allow"> + one <line choice> per format — a flat Bom/Payload/PackageInfo archive is a bare pkgbuild with NO Customize.
• A subcommand that must work BEFORE a build exists (e.g. pulp ship doctor, which makes signing non-interactive) has to be dispatched above cmd_ship's build/CMakeCache.txt guard — that early-return fires first and would otherwise reject it with "Build directory not found." Put such handlers right after find_project_root().
• pulp ship doctor shells out to tools/scripts/ensure_signing_ready.sh (the canonical logic + its own test_ensure_signing_ready.sh); the C++ side is a thin pass-through, and ship sign invokes it as a best-effort quiet preflight (|| true) so a doctor failure never masks the real sign error. Keep secrets in $PULP_SECRETS_DIR/, never the repo.

Rust CLI cutover path convention

After the v0.78.1 cutover, the user-facing CLI is Rust pulp. Release archives install pulp plus sibling pulp-cpp, and source builds stage the Rust binary at ./build/pulp. Slash-command examples should prefer pulp on PATH for installed users and ./build/pulp for source-tree examples. Do not point new docs at ./build/tools/cli/pulp; that path was the old C++ default. Use pulp-cpp only when documenting fallthrough, rollback, or debug comparisons.

pulp import — framework-importer substrate

pulp import (tools/cli/cmd_import.cpp + import_run.{hpp,cpp} + import_detect.{hpp,cpp} + import_spi.{hpp,cpp} + import_emit.{hpp,cpp} + import_emit_scan.{hpp,cpp}) reads an existing audio-plugin project read-only and emits a Pulp migration scaffold. The SDK owns only the generalized substrate; the framework-specific parsers are vendor-specific add-on tools in their own private repos, driven over a JSON-over-stdio SPI.

Gotchas / invariants when touching this surface:

• cmd_import.cpp is arg-parse + dispatch only. The SPI-verb orchestration (run_detect / run_inspect / run_emit and their shared helpers — framework-index + importer resolution, the SPI request/response envelope run_verb, the analyze/emit payload builders, the clean-room output gate, and scaffold materialisation) lives in import_run.{hpp,cpp} under namespace pulp::cli::import_run. cmd_import.cpp only parses flags into import_run::ImportOptions and calls the three run_* entry points. Keep new verb logic in import_run.cpp; keep cmd_import.cpp small. Both files (and any new tools/cli/*import* file) must stay vendor-free — the pulp-test-cli-import directory scan asserts no juce/iplug/steinberg/ wdl token appears in any of them.

• Vendor-agnostic is enforced. SDK code, mainline tests, and generic CI name NO vendor or framework. The ONLY place real markers (.jucer, juce_add_plugin, iPlug PLUG_NAME, Steinberg::Vst::, …) may appear is the DATA file tools/import/known-frameworks.json. Tests use a NEUTRAL id (example-framework) and a temp index. test_cli_import.cpp has a guard that greps tools/cli/*import* for juce/iplug/steinberg/wdl — keep new import code clean of those tokens (put markers in the data file).

• Detection markers are DATA, not code. import_detect.cpp only knows the shape of a marker (file_glob / content_match + weight), never a specific marker. Add a framework by editing the JSON index, not the engine.

• The Rust front routes import via fallthrough automatically. import is NOT a declared clap subcommand in experimental/pulp-rs/src/main.rs, so it hits ErrorKind::InvalidSubcommand and clap_exit_code delegates to pulp-cpp. You still add an Entry to help.rs::COMMANDS so the usage banner lists it (and the C++ commands[] table in pulp_cli.cpp).

• SPI version is negotiated every call. import_spi::check_version compares the importer's response spi_version against the registry's [spi_min, spi_max] window and fails loudly ("upgrade Pulp" vs "upgrade the importer"). Never silently proceed on a mismatch.

• The SPI request goes in on real stdin. import_spi::run writes the one-line request to a temp file and redirects it into the importer through the shell (/bin/sh -c '<cmd> < tmp' / cmd /c), because ChildProcess::run captures stdout but doesn't feed stdin. Reads the first non-empty stdout line as the response envelope.

• Importer fields on ToolDescriptor are optional. frameworks, spi_min/spi_max, sdk_min/sdk_max, capabilities, health_check are parsed only when present. Don't add a fake vendor entry to tool-registry.json; the loader tolerates their absence.

• emit materialises a real scaffold; the SDK writes + gates the output. detect/inspect/emit are all real. emit runs analyze → ProjectIR then the SPI emit verb → an EmissionManifest (the importer PROPOSES files, never writes them). The SDK then: parses the manifest (import_emit::parse_manifest), runs the clean-room output denylist scan (import_emit_scan::scan_manifest) over every generated/stub file, computes a write-plan that rejects any path escaping --output (compute_write_plan), writes each file (inline content, or a verbatim copy_from copy for copied-user-file provenance), and writes migration_status.json + .pulp-import-provenance.json. Parse / write-plan / scan are pure functions over structs so they unit-test without spawning; the spawn/IO is a thin shell in cmd_import.cpp.

• The output scan is data-driven, not hardcoded. Keep the clean-room denylist vendor-free: denylist_from_known_frameworks() builds it from the known-frameworks index's content_match markers (the ONE place real tells live). Do NOT hardcode juce/iplug/… tokens in import_emit_scan.cpp — the vendor guard greps for them. copied-user-file provenance is EXEMPT from the scan (it's the user's own DSP); only generated/stub content is scanned. Watch comment wording too: a literal .jucer in a comment trips the juce substring guard.

• The importer may double-wrap the IR. When emit hands the analyze result back as project_ir, an importer that frames analyze as {"project_ir": IR} must unwrap its own envelope (the SDK passes the analyze result verbatim). If a scaffold comes out with empty formats / pass-through-only DSP, suspect a double-wrapped IR on the importer side, not the SDK.

• inspect/emit are gated by the IMPORTER_TERMS accept-to-run gate (import_terms.{hpp,cpp}, run_gate). The terms BODY is vendor DATA carried on the add-on's ToolDescriptor (terms_text/terms_version/vendor_id) — the SDK ships no terms body and names no vendor, it only surfaces + hashes the text and records acceptance under ~/.pulp/importer-terms-accepted.json (honours $PULP_HOME), keyed by importer id + an FNV hash of the terms. A changed body → new hash → re-prompt. --accept-importer-terms is the non-interactive (CI) path; without a TTY and without the flag the gate returns NonInteractive and BLOCKS (exit 1) rather than hanging. Mirrors pulp add --accept-license in UX + storage shape. --importer-cmd has no registry entry, so --importer-terms-text/--importer-terms-version supply the body directly (tests + power users). has_terms()==false (no body) → the gate passes through transparently. run_gate takes injected GateIo (in/out/interactive) + a now_utc string so it unit-tests deterministically without a real TTY or clock.

• Provenance PR-check is tools/scripts/check_import_provenance.py (neutral, vendor-free), the audit that a migrated project landing in a PR was produced clean-room: marker present + well-formed, valid per-file provenance values, and no framework-source marker in any file the marker labels generated/stub (copied-user-file is exempt). The content denylist is DATA from the known-frameworks index ($PULP_KNOWN_FRAMEWORKS or tools/import/); with no index the structural checks still run and the scan reports as skipped. Wired into gates.sh as an opt-in lane (PULP_IMPORT_PROVENANCE_DIRS) so it's a no-op for normal Pulp-repo pushes and only fires on a PR that lands a scaffold.

pulp tool install <importer> — importer add-on packaging

The install-side contract for framework-importer add-ons lives in tools/cli/importer_install.{cpp} (declarations in tool_registry.hpp). pulp tool install <importer> and the pulp add <importer> alias both route through it. User-facing contract: docs/reference/framework-importer-packaging.md.

Gotchas / invariants when touching this surface:

• An importer is a tool-registry entry with category: "importer". The generic binary/python install path is untouched: cmd_tool's install/ uninstall first call handle_importer_install / handle_importer_uninstall, which return std::nullopt for non-importers so the generic path still runs. try_add_importer_alias is the pulp add entry — it only fires when the id resolves to an importer in tools/packages/tool-registry.json.
• Three install gates, in order, and they fail/refuse — never warn-and-proceed: (1) version window — check_importer_compat requires the running SDK in [sdk_min, sdk_max] AND the importer's [spi_min, spi_max] to overlap the SDK's import-SPI window; (2) sha256 — the fetched/--from archive must match the registry sha256; (3) skill + record. Keep the messages actionable (upgrade Pulp vs upgrade the importer, refusing to install).
• SHA-256 is hand-rolled in importer_install.cpp, on purpose. It avoids linking mbedTLS into the lightweight pulp-test-cli-* targets (which only link pulp::platform). It's validated against FIPS-180-4 known vectors in test_cli_importer_install.cpp — if you touch the digest, those vectors are the guard. Do NOT swap it for pulp::runtime::sha256_hex without also adding the runtime link to every test target that compiles importer_install.cpp.
• The SDK version reaches the dispatch via env-var-then-header. host_sdk_version() reads PULP_SDK_VERSION (tests set it to drive the window check) and falls back to PULP_SDK_VERSION_GENERATED from <pulp_version_gen.h>, included via #if __has_include so unit-test targets (no generated header) still compile. The pure functions (install_importer, check_importer_compat) take the SDK version + SPI bounds as PARAMETERS — keep them parameterized so they stay testable without globals.
• Skills install to ~/.agents/skills/<skill_name>/ honoring $PULP_HOME. skills_dir() maps $PULP_HOME → $PULP_HOME/agents/skills (tests rely on this); without it, the real ~/.agents/skills. Records go under pulp_home()/importers/<id>.json. Uninstall recovers the skill dir name from the record's skill_path so it removes the right directory even if the registry entry changed.
• --from <path|file://> is importer-only. Both pulp tool install and pulp add reject --from for non-importers. It's the offline/test source — the checksum + version gates still apply, so a mock local package with a known sha is the unit-test vehicle (build one with tar -czf, hash it with sha256_file_hex, feed it back into the descriptor).
• Producer side is NOT decided in code. Artifact build/hosting/pinning, the bundled-libclang choice, and signing/notarization are maintainer decisions documented (as open questions) in docs/reference/framework-importer-packaging.md. The CLI consumes the contract; don't bake a hosting URL, an LLVM pin, or a signing identity into the SDK.
• Two test targets compile tool_registry.cpp. tool_registry.cpp now references importer_install.cpp + import_spi.cpp symbols, so BOTH pulp-test-cli-tool-registry and pulp-test-cli-importer-install link all three TUs. Adding a symbol used by cmd_tool means updating both targets.

pulp tool install — bare binaries vs archives, and the verified-fetcher lane

The generic binary_download path in install_binary_tool (tool_registry.cpp) assumes an archive: with no archive_format it defaults the download extension to .tar.xz and runs extract_archive. A bare binary source (no archive_format, e.g. Perfetto's trace_processor_shell) would fail there ("cannot extract" on a raw Mach-O/ELF) — and this path never verifies a SHA (the sha256 field is read but unused). So a bare-binary tool is installed only by its own SHA-256-verified fetcher, never this generic path:

• install_binary_tool skips any source with an empty archive_format (returns ok, installs nothing) so an --all sweep reaching it via pulp-cpp doesn't error. The Rust front-end owns the real install: cmd/tool.rs short-circuits install/update <id> to the verified fetcher, and its install --all pre-fetches the bare-binary tool so the delegated C++ sweep finds it already-present (C++ locate_tool searches tools/<id>/ recursively) and skips it.
• trace-processor is the live example: pins + fetch live in experimental/pulp-rs/src/cmd/trace_fetch.rs; pulp trace fetch and pulp tool install trace-processor share that code. If you add another bare binary, give it a verified fetcher — don't rely on the generic path.

pulp tool info — Rust/C++ parity

pulp-cpp tool info <tool-id> [--json] prints the same descriptor metadata that installer add-on workflows need when deciding whether a registry entry is a machine-scoped tool add-on, importer package, or legacy validator. The Rust front-end owns pulp tool dispatch for installed users, so adding descriptor fields or subcommands to tool_registry.cpp must be mirrored in experimental/pulp-rs/src/tool_registry.rs and experimental/pulp-rs/src/cmd/tool.rs; otherwise Rust pulp tool <subcommand> can reject a command that the C++ delegate and tests already support. Keep managed-install layout parity here too: C++ npm-package tools install under $PULP_HOME/tools/npm-packages/<id>/run.{sh,bat}, so Rust locate_tool and uninstall_tool must check/remove that wrapper directory alongside binary-download and python-env installs. Otherwise Rust-native pulp tool info, path, run, doctor, and uninstall can disagree with tools installed by the delegated C++ install path. The targeted pulp tool doctor <id> [--run] surface is part of that same contract: --run executes the resolved tool path with no forwarded arguments and returns its exit code. For npm_package tools, that path is the run.{sh,bat} wrapper smoke check.

Every added managed_by_pulp tool must be user-updatable + overridable

Convention (hard rule for the opt-in tool lane, NOT for shipped-by-default deps like Skia/Dawn): when you register a managed_by_pulp tool in tools/packages/tool-registry.json, users must be able to update it and pin their own version without waiting for Pulp to bump the committed pin. This is what pulp tool update + the version-override tiers provide, and it is enforced — do not add a managed tool that lacks it.

• Declare a non-empty pinned_version. It is the anchor the update/override path keys off. tools/packages/validate_registry.py's validate_tool_registry fails the build if any managed_by_pulp tool ships without one (covered by tools/packages/test_package_validation_tools.py).
• pulp tool update <id> [--version <v>] lives in experimental/pulp-rs/src/cmd/tool.rs. Bare update re-installs at the registry pin and clears any prior user override; --version <v> re-installs at an explicit version and records a durable override. The archive re-fetch delegates to pulp-cpp tool install <id> --force (Rust can't extract archives), forwarding the resolved version via env — the override file is the cross-language source of truth.
• Override precedence (highest first, in experimental/pulp-rs/src/tool_version.rs): PULP_TOOL_<ID>_VERSION env var → $PULP_HOME/tool-overrides.json (durable; what --version writes) → registry pinned_version. pulp tool info surfaces the active version and its source (text + --json as active_version / active_version_source), so it is always explicit which version is in effect and why.
• When you add a managed tool, touch (same PR): the registry entry (with pinned_version), and — if you extend the update/override surface itself — tool.rs + tool_version.rs + their tests, docs/status/cli-commands.yaml (tool subcommands), docs/reference/cli.md#tool, and docs/reference/extending-pulp.md. The full convention lives in extending-pulp.md.

pulp tool install <in-tree python tool> — source_dir install

A Python tool that lives inside this repo (not on PyPI) registers as a normal python_pip entry but adds two descriptor fields:

• source_dir — repo-relative package dir (with a pyproject.toml), e.g. tools/audio/quality-lab. When set, install_python_tool pip-installs that directory (resolved via repo_root_from_registry(find_tool_registry_path())) instead of <pip_package>==<version>. This mirrors the repo-local npm_package precedent.
• module — the python -m <module> the run wrapper invokes (e.g. quality_lab.cli); defaults to pip_package for classic PyPI tools.

The managed venv still lands under $PULP_HOME/tools/python-envs/<id>/, so locate_tool / uninstall_tool need no change. The tool's pyproject.toml owns its dependency list (mirror requirements.txt). Per the parity rule above, both new fields are also declared in experimental/pulp-rs/src/tool_registry.rs (serde #[serde(default)], ignored on the delegated install path) so pulp tool info/list round-trip them. First user: audio-quality-lab.

Remove/uninstall commands name what they deleted

Every extend-surface removal (pulp tool uninstall, pulp kit remove, pulp content remove, pulp add --remove) closes on an OK line that names what it removed, not just the id — this is the shared extend-surface lifecycle contract (see docs/reference/extending-pulp.md). tool uninstall prints (removed <path>) from the returned PathBuf; content remove mirrors it with the deleted content-pack path; kit remove deletes a set of lock-recorded files, so it names the count instead ((removed N files)). When you add or change a removal command, keep the OK line honest — echo the concrete path (or count, for multi-file removals) the command actually deleted, and assert it in the command's test via capture_stdout_for so "it names what it removed" is proven, not assumed.

Package suggestion and analyzer metadata commands

Package search/suggestion code (tools/cli/package_commands_search.cpp) is a user-facing CLI surface even when the change is "just output shaping." Keep the plain-text and --format json lanes semantically aligned:

• JSON output must escape strings through the shared helper, not by hand-writing raw descriptor fields into JSON.
• pulp suggest filters license-gated packages by default; the --include-license-gated flag is the explicit inspection path for packages whose license is rejected or needs review. When changing this lane, keep the omission counts and human hints in sync with JSON fields so automation and terminal output tell the same story.
• Analyzer descriptor plumbing in package_analyzer_descriptors.{hpp,cpp} is metadata-only. It maps package provides tokens into pulp::audio::AnalyzerDescriptor records for UI/control-thread discovery. It must not install packages, fetch network state, launch tools, or enter realtime paths. If a new analyzer capability token lands in package metadata, update the mapping, CLI build list, package command tests, and any package docs/skills that describe discoverable analyzer providers in the same PR.

Binary subcommand delegation

BinaryCommand entries in tools/cli/pulp_cli.cpp delegate to helper binaries inside the active build tree, e.g. pulp import-design launches tools/import-design/pulp-import-design. Do not hard-code build/ for these lookups: CI uses matrix-scoped directories such as build-linux, build-macos, and build-windows, and self-hosted macOS can mask mistakes with stale warm build/ artifacts. Resolve helpers from the running CLI's sibling build tree first, honor PULP_BUILD_DIR when present, and keep test/test_cli_shellout.cpp subprocess-output INFO(...) diagnostics so future failures show the delegated binary's stderr.

On multi-config generators (MSVC / Visual Studio), the helper executable lives under the configuration directory, e.g. build-windows/tools/import-design/Release/pulp-import-design.exe, while the delegated relative path remains tools/import-design/pulp-import-design. Candidate lookup must therefore check both the direct single-config path and Release / RelWithDebInfo / Debug / MinSizeRel subdirectories, preferring the config inferred from the running pulp-cpp path when it is itself under tools/cli/<config>/. Add or keep a focused delegate_to_build_binary test that asserts the missing-helper diagnostic includes a Release candidate; a macOS/Linux single-config build will otherwise miss this Windows-only failure mode.

Cwd independence (2026-05-14): delegate_to_build_binary in tools/cli/cli_delegate.cpp MUST NOT require cwd to be inside a Pulp project to find a delegate. Sibling helpers live next to the CLI binary itself, so the argv[0]-relative resolution path is authoritative and project-root is a fallback. The original require_project_root() gate broke cd /tmp && pulp import-design --from claude --file ~/x.html for no good reason — a first-time user shouldn't need to cd into a pulp checkout just to translate a design file with absolute paths. When the delegate truly is missing, the error message lists every candidate path that was tried and gives the exact cmake --build line to remediate; do not regress to "Run pulp build first" — that's misleading if the top-level target doesn't depend on the missing helper.

Delegated exit codes must be decoded (2026-06-02): run() in tools/cli/cli_common.cpp returns std::system, which on POSIX is a waitpid status, NOT the child exit code — a child exit of 2 comes back as 0x200, and propagating it as the CLI's own exit code truncates to 0 (& 0xFF). That silently turned delegated failures into success: e.g. pulp import-design --export-tokens --format bogus (which the helper exits 2 for) read as exit 0 through pulp-cpp. run() now routes through decode_system_status() (WIFEXITED/WEXITSTATUS on POSIX, raw on Windows, 128+signal for signalled children); the spinner-runner does the same. Any new std::system call that feeds an exit code MUST decode it the same way. Covered by pulp delegates a non-zero child exit code intact in test/test_cli_shellout.cpp (which runs against pulp-cpp, the delegate).

Prefer pulp::platform::exec over std::system for quoted-path shell-outs on Windows (2026-06-14): std::system(cmd) runs cmd.exe /c <cmd>. When <cmd> starts with a quoted path and contains further quotes (e.g. quoted arguments and a quoted redirect target — the common shape "C:\tool.exe" --output "C:\out" > "C:\log" 2>&1), cmd /c mis-parses it and aborts with "The filename, directory name, or volume label syntax is incorrect" before running anything — so the tool never launches and no output/redirect file is created. Reproduced against a real Windows host through the CRT system(). The robust fix is to not go through the shell at all: spawn the tool with pulp::platform::exec(program, args_vector, timeout_ms), which passes an argv array straight to the process (no cmd, no quote parsing). pulp kit verify --execute-screenshots (maybe_execute_screenshot_profile in tools/cli/kit_commands.cpp) hit this — it now uses exec() for both the direct-.exe path and the .cmd/.bat path (exec("cmd", {"/C", shell_command})). If you must use std::system (e.g. you genuinely need shell features) and the command begins with a quoted path, wrap the ENTIRE command in one extra pair of double quotes (command = "\"" + command + "\"";) so cmd strips exactly that pair and runs the remainder verbatim.

A CLI subcommand that renders shells out to pulp-screenshot

pulp design gallery renders each tagged card by spawning the sibling pulp-screenshot binary rather than linking Skia/Dawn into the CLI process — the CLI stays GPU-free and testable, and the render tool owns the backend. Two conventions apply to any subcommand that does this:

• Locate the sibling next to the CLI first, then under <root>/build/tools/ screenshot, and let the user override with an explicit --screenshot <bin> (mirrors delegate_to_build_binary's cwd-independent search). If it is not found, fail with an actionable message or offer a --no-render inventory mode — never silently emit an artifact full of broken images.
• Spawn with pulp::platform::exec(bin, args_vector), not a shell string. The command begins with a quoted path and carries quoted --output/--script args — the exact shape std::system's cmd /c mis-parses on Windows (see the quoted-path note above). The argv array sidesteps the shell entirely and gives a timed_out flag for the render wall-clock cap.

The render output is content-hash cached: the PNG filename embeds gallery_content_hash(bytes), so an unchanged card at an unchanged viewport maps to a file that already exists and is skipped. Keep the pure card model (core/view/src/design_gallery.cpp) free of filesystem/render concerns — the CLI owns the walk, the cache, and the shell-out; the core only parses tags and serializes the manifest/HTML.

pulp design splits offline verbs from the live-tool launcher

cmd_design.cpp is only the verb dispatcher plus the live GPU design-tool launcher (project discovery, build, watch loop, spawn). The nine pure-data offline handlers — lint, diff, compile, lint-adherence, record, gallery, handoff, variants, tweak — live in cmd_design_subcommands.cpp behind the pulp::cli::design namespace, declared in cmd_design_subcommands.hpp. To add a new offline pulp design <verb>: add the run_<verb> handler (and its private helpers) to cmd_design_subcommands.cpp, declare run_<verb> in the header, and wire one args[0] == "<verb>" branch in the cmd_design dispatcher. Handlers must not open a window; they read/write files and call the design cores in core/view. Keep helpers namespace-local so they stay implementation-private.

Numeric CLI flags

For count-like flags such as pulp run --frames, parsers should accept only plain non-negative decimal digits and reject a leading +. C++ from_chars acceptance varies by implementation for signed prefixes, and the Rust-facing CLI surface should stay deterministic across platforms. Add regression tests for boundary spelling when changing these parsers.

pulp run forwards each launcher flag two ways — as argv AND as an env var — so the standalone host picks up whichever it reads. When adding a flag here (cmd_run_parse.cpp parses into ParseRunResult; cmd_run.cpp exports the env var + builds argv via assemble_launch_args), wire BOTH and add the flag to the print_help text plus the pulp run --help shellout assertion in test_cli_shellout.cpp and the parser test in test_cli_run_options.cpp. The Audio Inspector flags follow this shape: --audio-inspector → PULP_AUDIO_INSPECTOR=1 (does NOT imply headless); --audio-probe-json <path> → PULP_AUDIO_PROBE_JSON=<path> (implies headless, like --screenshot); --audio-scope-json <path> → PULP_AUDIO_SCOPE_JSON=<path> (+ window/trigger/ channel); --audio-capture-wav <file> → PULP_AUDIO_CAPTURE_WAV=<file> (+ --audio-capture-frames → PULP_AUDIO_CAPTURE_WAV_FRAMES), which dumps the live output ring to a WAV for pulp audio validate, implies headless, and shares the single capture FIFO with --audio-inspector / --audio-scope-json (the three are mutually exclusive at parse time). A bare --audio-probe-json / --audio-scope-json / --audio-capture-wav run is headless but must NOT auto-assign a default screenshot PNG path — guard the headless-default branch on all three being empty. See docs/guides/audio-inspector.md.

The live window also reads display-only waveform env vars: PULP_AUDIO_INSPECTOR_TRIGGER=rising-zero, PULP_AUDIO_INSPECTOR_GRID=0, and PULP_AUDIO_INSPECTOR_SCALE=<n>. These are not CLI parse flags and do not change the probe JSON or audio path.

Headless here means "no visible UI", not "no system audio". pulp run still launches a standalone host and may activate the live audio device, including the --audio-probe-json path. Keep the pre-launch stderr notice wired in cmd_run.cpp, keep PULP_RUN_AUDIO_NOTICE=0 as the explicit quiet-automation escape hatch, and prefer Audio Doctor / HeadlessHost for no-speaker tests.

Import-design artifact flags

pulp import-design --output <path> is the destination for the primary artifact, not an artifact-kind selector. Keep sidecar anchoring tied to --output while using --emit {js|ir-json|cpp|swiftui} for the primary artifact vocabulary. Accepted import-design artifact or runtime values must stay aligned across pulp_import_design.cpp, docs/reference/cli.md, docs/reference/design-import.md, docs/status/cli-commands.yaml, and the import-design skill.

--emit swiftui (baked SwiftUI, Workstream B1) is a fourth lowering parallel to cpp — baked-only, mirroring cpp's enum/parse/validation/dispatch in pulp_import_design.cpp (generate_pulp_swift). Its sidecars are per-view — <RootView>.swift + a <RootView>Theme.swift + <RootView>.bindings.json — so two imports never collide on a shared theme. --screenshot-backend {skia|coregraphics} selects the --validate render backend (default skia, the faithful path that composites file-backed images; see the screenshot skill).

--format is a separate axis from --emit: it picks the token file format, not the primary artifact kind. Values are w3c (default, DTCG JSON), css-variables (CSS custom properties; base → :root, .dark-suffixed modes → @media (prefers-color-scheme: dark); sidecar default flips from tokens.json to theme.css), and the tailwind/json-tailwind/css-tailwind variants. Token dispatch is exhaustive on purpose: an unknown --format exits 2, and the Tailwind variants are gated to --from designmd (they re-parse DESIGN.md for section context) — on --export-tokens or any non-designmd source they exit 2 rather than silently emitting W3C under the requested name (generalizing them is Workstream A2). Keep --format values aligned across pulp_import_design.cpp, the help text, docs/reference/design-import.md, and the import-design skill.

For --emit ir-json, asset-manifest flags are part of that same synced surface: --allow-network-fetch, --asset-cache, --asset-timeout-ms, and repeated --asset-hash <uri=sha256>. Keep their help text, YAML manifest rows, reference docs, and import-design skill text in lockstep. Network asset fetching must remain explicit opt-in; default JS emission should not fail just because an IR asset reference points at HTTP(S).

--mode baked is implemented for --emit ir-json and --emit cpp; cpp requires baked mode. --mode live remains the default and --from jsx --mode live --emit js writes the precompiled bundle verbatim. Because that path does not parse or render the bundle, it must reject --validate, --reference, --diff, and --debug with a clear usage error rather than silently bypassing shared post-processing. When changing this lane, keep the CLI help, docs/status/cli-commands.yaml, docs/reference/cli.md, docs/reference/design-import.md, and the import-design skill aligned. The JSX baked snapshot policy is --snapshot-semantics {fail|warn|accept}: fail rejects dynamic APIs by default, warn proceeds with a structured diagnostic, and accept proceeds silently.

The shipped import-design default is --mode live --emit js. User preference overrides belong in the existing config surface as import_design.default_mode (live|baked) and import_design.default_emit (js|ir-json|cpp), with PULP_IMPORT_DESIGN_DEFAULT_MODE / PULP_IMPORT_DESIGN_DEFAULT_EMIT as one-environment overrides. Keep C++ and Rust pulp config, pulp status, the import-design helper, docs, slash commands, and the MCP status output aligned whenever these keys change. If only default_mode=baked is configured, ir-json is implied.

Adding a pulp config key: cmd_config.cpp allow-lists every key in three places — is_allowed_key, validate_value, and the list dump (plus the usage() help text). Add the key to all of them or set rejects it / list omits it. Example: [claude] send_user_file (on|off, default on) gates the plugin's SessionStart hook (hooks/scripts/inject-claude-prefs.sh) that tells the agent to surface image/file artifacts via SendUserFile. A config-only key needs no cli-commands.yaml subcommand entry (it's not a new command), but do update the command summary there + docs/reference/cli.md#config + a test_cli_shellout.cpp get/set/validate case. Reading config from a hook (bash) means a small TOML scan — scope the read to the right [section] so a same-named key in another table can't flip it.

Sidecar output anchoring: when a CLI command takes --output <path>/main.ext and also emits sidecar artifacts (e.g. pulp import-design writes bridge_handlers.cpp, classnames.json, tokens.json alongside ui.js), the sidecars MUST default to the same directory as --output — not cwd. Track an _explicit bool per sidecar flag and only derive the anchored path when the user didn't set it. Scattering sidecars to cwd is a first-user trap (we hit it 2026-05-14 during a cd /tmp reimport demo). Test the default-anchored path AND the explicit-override path so regressions surface.

Adding a new value to an enum-like flag (e.g., --from <source>)

When extending a flag that takes one of a fixed set of values (pulp import-design --from {figma,stitch,v0,pencil,claude,...}, pulp validate --target {auval,clap-validator,pluginval,...}, etc.), all four surfaces have to land in the same PR or the skill-sync gate trips:

1. The CLI source switch (tools/import-design/pulp_import_design.cpp, etc.) — accept the new value in the parser and the dispatch.
2. The slash command file under .claude/commands/ — usage block, examples, and any "when to detect this" notes.
3. The matching topical .agents/skills/*/SKILL.md — same prose, kept in sync so the agent's pre-context matches what the slash command says.
4. The path map (tools/scripts/skill_path_map.json) — add the new header/source paths if the new source brings new C++ files.

Reason this gets called out: editing .claude/commands/<name>.md maps to the cli-maintenance skill (because the path map owns .claude/commands/**), not to the topical skill. So a diff that updates the slash command + the topical skill but leaves cli-maintenance untouched still trips skill-sync. Keep this section present so the gate stays satisfiable by the topical edit alone. --from claude is the worked example.

Adding a credential flag backed by an env-file (pulp ship notarize pattern)

When a CLI command needs to consume a credential the user wants to persist outside ~/.pulp/config.toml (e.g. App Store Connect API key, ASIO licence file, S3 access keys), follow the lane established for pulp ship notarize --api-key/--api-key-id/--api-issuer:

1. Parser in tools/cli/notary_env.{hpp,cpp} (or a sibling file). Hand-roll a tiny bash-style KEY=VALUE parser. Support # comments, blank lines, "double quoted" (with $HOME expansion) and 'single quoted' (literal) values, export KEY=val prefix, and trailing # inline comment on bare values. Keep it stdlib-only so the unit test can link it directly without dragging pulp::runtime into the test binary.
2. Resolver with a pluggable getenv lambda. Layer CLI flag > env var > parsed file > config.toml, and record the source of each value ("cli" / "env" / "file") so the CLI can print diagnostics like key-id: ABC (from file). Cred path values must be redacted to the trailing filename (…/AuthKey_X.p8) — never log the secret material itself.
3. Default path: $HOME/.config/pulp/secrets/<name>.env, overridable via PULP_<NAME>_ENV env var and a --env-file <path> flag (the env var is the test hook; the flag is for CI sandboxes).
4. --dry-run that short-circuits before the real side effect and prints the assembled subprocess argv. Lets the shell-out test verify resolution without touching the external service.
5. Test layers: a pure-stdlib unit test for the parser + resolver (compiled directly against the source, no pulp::runtime link), plus shell-out cases in test/test_cli_*_shellout.cpp covering --dry-run with CLI flags, with an env file, with CLI overriding env file, and the no-creds error path.
6. Skill + doc updates: extend the topical SKILL.md (here, ship/SKILL.md) with the resolution precedence table, and add the new flags to docs/reference/cli.md + docs/status/cli-commands.yaml.

Reference implementation: PR landing feature/asc-notary-key-flow (2026-05-26). Files: tools/cli/notary_env.{hpp,cpp}, tools/cli/cmd_ship.cpp (notarize block), test/test_notary_env.cpp, test/test_cli_ship_shellout.cpp ASC-key cases.

A subcommand that orchestrates other subcommands (pulp ship share)

cmd_ship calls itself recursively (cmd_ship({"notarize", "--path", ...})) to compose stages — share and release both reuse the notarize handler's credential-resolution chain rather than duplicating it. When you add a flag like --path to a leaf subcommand, any orchestrating subcommand can thread it through for free. Conventions that kept this testable without Apple creds:

• Add a --dry-run to orchestrators (share) that prints the plan and returns 0 before any codesign/notarytool/spctl call — shellout tests assert the plan text. Mirror the existing notarize --dry-run / auv3-xcodeproj --dry-run pattern.
• Put guard rails (input not found, unsupported extension, missing identity) before the side-effecting work so they're exercised by credential-free shellout tests.
• Keep accepted orchestrator flags discoverable across cmd_ship help/usage, docs/reference/cli.md, docs/status/cli-commands.yaml, topical skill text, and parser-error shellout coverage. The share path accepts --output and --entitlements in addition to credentials/dry-run; if either changes, update all surfaces together.
• For pulp ship sign --path, describe the argument as an explicit desktop artifact rather than an Apple-only .app/.dmg/bundle set. The same CLI primitive dispatches to macOS codesign or Windows signtool; .pkg installers are intentionally rejected because package signs them at creation time.
• A subcommand of ship does NOT need its own top-level slash command or a commands top-level entry — it lives under the ship entry's subcommands in cli-commands.yaml and the /ship slash command. cli_sync_check.py only diffs top-level commands, so a new ship subcommand won't show there; keep the ship subcommand list in cli-commands.yaml current by hand.

Reference: feature/ship-oneoff-notarize (2026-06-01). Files: tools/cli/cmd_ship.cpp (sign --path, notarize --path, release artifact selection, share), test/test_cli_ship_shellout.cpp [oneoff] cases, .claude/commands/ship.md, .agents/skills/ship/SKILL.md.

SDK build strips the dev authoring surface (§6a)

cli_sdk.cpp's release configure deliberately disables the developer-only surfaces so shipped SDKs / plugins don't carry them: it passes -DPULP_ENABLE_AUDIO_PROBES=OFF and -DPULP_ENABLE_INSPECTOR=OFF (the inspector is the in-plugin authoring / MCP-reachable surface). The scaffolded project templates (tools/templates/.../build.gradle.kts.template) mirror this.

Keep the two flags together when editing the SDK configure command. A developer who deliberately wants an inspectable / MCP-reachable plugin re-enables it in their own plugin build with -DPULP_ENABLE_INSPECTOR=ON. The standalone pulp CLI and the MCP server (tools/mcp/pulp_mcp.cpp) are separate binaries — not compiled into a plugin — so this flag never strips them; bundling them alongside a plugin distribution is a packaging choice.

The SDK build also passes -DPULP_ENABLE_DESIGN_IMPORT=OFF, which strips the design-import authoring cluster (importers, codegen, lock_to_source, jsx_lock, token_lock, runtime design-import) from shipped plugins. The runtime W3C token pair (importDesignTokens / exportDesignTokens, via core/view/src/w3c_tokens.cpp) stays compiled; WidgetBridge::install_runtime_import_handlers() becomes a no-op stub. Keep all three strip flags (audio-probes / inspector / design-import) together in the SDK configure command. Building the test suite requires PULP_ENABLE_DESIGN_IMPORT=ON (the CMake gate hard-errors otherwise); a stripped build uses PULP_BUILD_TESTS=OFF.

Removing a CLI Command

• Remove from cmd_*.cpp and command table in pulp_cli.cpp
• Remove from cli_common.hpp declarations
• Remove from CMakeLists.txt
• Remove from cli-commands.yaml
• Remove slash command if it exists
• Remove from docs/reference/cli.md
• Search all skills: grep -r "pulp <name>" .agents/skills/
• Search CLAUDE.md
• Run sync check

CLI Git/CMake shell helpers

tools/cli/cmd_project_common.cpp and tools/cli/cmd_misc.cpp shell out to git / cmake from unit-tested helper paths, including Windows CI. Keep output redirection platform-aware: POSIX uses /dev/null, but Windows cmd.exe needs NUL. Do not add raw 2>/dev/null or >/dev/null 2>&1 in these files; route new call sites through the shared stderr_to_null() or output_to_null() helpers in tools/cli/shell_redirect.* instead. Otherwise Windows can leak "The system cannot find the path specified." into stderr, misreport clean/dirty git state, or fail origin-main probes even though the same tests pass on macOS/Linux. The pulp status quotes source checkout paths before reading Git metadata test covers the stderr contract locally; Windows CI is the platform proof for the null-device behavior.

pin / unpin / floating SDK mode

pin is the primary command name; bump survives as a deprecated alias through cmd_project's dispatch (if (sub == "pin" || sub == "bump")). When adding a new project subcommand, add the canonical name AND keep any old alias for one minor release — existing scripts and skill examples break otherwise.

The Rust user-facing CLI must mirror the same surface in experimental/pulp-rs/src/cmd/project.rs, experimental/pulp-rs/src/main.rs, and experimental/pulp-rs/src/help.rs. Do not update only the C++ command: pin, bump, unpin, and undo all need Rust parser/help coverage too.

pulp project unpin rewrites pulp.toml's sdk_version to "latest" in-place (single-line value swap, preserving surrounding TOML structure and comments). Do NOT delete the field — downstream tooling that greps for it loses a clear signal. The dispatch entry lives at the same spot as pin/bump/undo and shares find_bumpable_project_root_from.

sdk_version = "latest" is the floating-SDK marker. Resolution happens in read_sdk_version() (cli_common.cpp) — "latest" becomes the newest installed version under ~/.pulp/sdk/<x.y.z>/, falling back to PULP_SDK_VERSION when none are installed. Callers that need to distinguish the floating marker from a real semver use read_raw_sdk_version() + is_floating_sdk(). Don't open-code the "latest" comparison anywhere — both helpers are exported from cli_common.hpp so the comparison stays in one place.

pulp create writes sdk_version = "latest" by default (cmd_create.cpp). The --pin flag opts into exact-version pinning at create time. Both code paths print a discoverable post-create message about pulp project pin so users learn the opt-in command without hunting.

The Rust-native pulp create --ci path is a scaffold-only fallback: it parses the full create flag inventory for help/parity, but full-path flags such as --pin and --debug only take effect through the delegated C++ create path. Keep those flags modeled in CreateArgs so the native --ci path can warn when it ignores them instead of silently treating them like typos.

pulp pr — shim over shipyard pr

By default pulp pr delegates to shipyard pr (on PATH), forwarding argv. Shipyard owns skill-sync, version-bump, PR creation, tracking state, and cross-host validation; pulp pr exists so the old invocation, the /pr slash command, and natural-language triggers in the ci skill all continue to work. Users can explicitly opt out per checkout with pulp config set pr.workflow github or manual, or for one command with --workflow / PULP_PR_WORKFLOW.

Invariants:

• When shipyard is on PATH, pulp pr execs shipyard pr <args> and exits with shipyard's status. Do NOT add pre/post-processing in cmd_pr.cpp — shipyard is the single source of truth.
• When shipyard is NOT on PATH, pulp pr prints an install hint pointing at tools/install-shipyard.sh and exits non-zero. It must NOT silently fall back to gh; that is how Shipyard tracking gaps happen. Update the hint text in cmd_pr.cpp::print_install_shipyard_hint() when the install path changes.
• pr.workflow=github is the explicit GitHub CLI path. It requires gh on PATH, runs the native gate/bump/PR flow, and leaves Shipyard tracking disabled by design.
• pr.workflow=manual prints the suggested commands and exits before pushing or creating a PR.
• pulp status reports the effective PR workflow and selected tool health.
• --native keeps the legacy in-process orchestrator for forensic/debugging use. Do not use it as the default path and do not document it as the primary surface — Shipyard-managed shipyard pr is the primary surface.
• pulp pr (shim or --native) still refuses to run on main.

Gotchas:

• Changing cmd_pr.cpp triggers the cli-maintenance skill-sync gate. If you're modifying the shim, the install hint, or --native logic, add a bullet here and you're covered. If the change is mechanical (e.g. renaming a helper) and genuinely doesn't need skill documentation, add a Skill-Update: skip skill=cli-maintenance reason="..." trailer on the tip commit.
• Don't call the Python scripts (skill_sync_check.py, version_bump_check.py) by hand. shipyard pr calls them with the right flags via the shim. Direct invocation skips the commit-trailer parsing and the PR-body rendering.
• Bump level is per-surface. A plugin-only feat: in a commit subject does not upgrade the SDK. The Version-Bump: <surface>=<level> trailer is authoritative and surface-scoped.
• pulp version check --with-bump-check is the fast sanity check to run before pulp pr if you want to see what the gate will say. Same script, --mode=report.

pulp macos — per-PR macOS-runner retargeting

tools/cli/cmd_macos.cpp plus .github/workflows/build-macos.yml.

pulp macos retarget --pr N --to <local|namespace|github-hosted> cancels any in-flight macOS-bearing workflow_runs for PR N (from both build.yml's matrix and any prior build-macos.yml dispatch) and fires a fresh gh workflow run build-macos.yml --ref <pr-head> --field runner=<choice>.

Why a separate workflow file (and not just a new pulp pr --retarget-macos flag): the build.yml matrix couples Linux/Windows/macOS into one workflow_run. Rerunning macOS via that matrix re-runs Linux/Windows too. build-macos.yml is independent — it produces its own macos-named check that supersedes the matrix's macos check by recency. Branch protection's required-check name stays one stable token.

pulp macos status --pr N reads the latest macos check from the GitHub check-runs API for the PR's head SHA. Useful for confirming a retarget landed and which runner pool picked it up.

Repo variables the workflow reads (defined globally for build.yml's overflow logic; reused here unchanged):

• PULP_LOCAL_MACOS_RUNS_ON_JSON — --to local
• PULP_NAMESPACE_BUILD_MACOS_RUNS_ON_JSON — --to namespace
• (--to github-hosted is always "macos-15", no var needed)

When this is the right tool vs. shipyard rescue:

Goal	Tool
Move one PR's macOS to a different pool without disturbing Linux/Windows	pulp macos retarget
Move multiple PRs' workflow_runs to a different provider (cancel + redispatch the WHOLE workflow)	shipyard rescue

pulp overflow — macOS overflow routing

tools/cli/cmd_overflow.cpp. Wraps three repo variables that .github/workflows/build.yml's resolve-provider reads:

Var	Purpose
PULP_LOCAL_MACOS_RUNS_ON_JSON	Selector when local has capacity
PULP_NAMESPACE_BUILD_MACOS_RUNS_ON_JSON	Selector when local is saturated (overflow target; despite the historical name, this is the generic overflow var)
PULP_LOCAL_MAC_OVERFLOW_THRESHOLD	BUSY count that trips overflow

Surfaces:

• pulp overflow status — show current state, including which runner the local target points at, the overflow target, threshold value, and registered self-hosted runners (if the default token can list them).
• pulp overflow enable [--to <selector>] — set the overflow target. Default --to "macos-15" for free GH-hosted; pass --to '"namespace-profile-generouscorp-macos"' for paid Namespace.
• pulp overflow disable — delete the overflow var. Note this only changes future dispatches; in-flight cloud runs keep running.
• pulp overflow threshold [N] — get (no arg) or set the BUSY count.

The variable is named PULP_NAMESPACE_BUILD_MACOS_RUNS_ON_JSON for historical reasons (Plan B in planning/2026-05-13-namespace-overflow- implementation.md originally targeted Namespace exclusively). It now holds the overflow target regardless of provider — rename tracked as a future cleanup.

pulp upgrade --check-only

The sandbox E2E harness runs this command with PULP_UPDATE_CHECK_DISABLED=1 and expects a non-silent, network-free result. If the update cache is empty in that mode, print the installed CLI version and an explicit disabled/not-queried latest-version line instead of probing GitHub Releases. Otherwise PR sandbox lanes can fail spuriously when GitHub release fetches are blocked or rate-limited.

pulp upgrade self-heals PATH

After a successful self-update, cmd_upgrade.cpp calls upgrade_install::ensure_dir_on_path(install_dir, ...) to append the CLI's own directory to the user's shell profile (.zshrc / .bash_profile / .bashrc / fish config.fish / .profile) when it isn't already on $PATH. This closes a real gap: the curl install.sh adds PATH, but a user who first got pulp via a source / SDK-prefix install (cmake --install --prefix ~/pulp-sdk → the binary lands at ~/pulp-sdk/bin/pulp) could pulp upgrade successfully yet still hit "command not found" in a fresh shell. The helper is pure on its inputs (env passed in, not read from globals) so it is unit-tested in test_cli_upgrade_install.cpp without mutating the process environment. It honors PULP_NO_MODIFY_PATH=1 (same opt-out as install.sh) and is idempotent (skips when the profile already references the dir). If you change the profile-selection logic, keep it in sync with tools/install/install.sh's PATH block so the two install surfaces agree.

pulp run --headless / screenshot / live audio flags

tools/cli/cmd_run.cpp plus the shared parser in tools/cli/cmd_run_parse.cpp (parse_run_options / assemble_launch_args) expose CI-friendly rendering flags and live-audio inspection flags on top of the basic launch path. The Rust front end mirrors this surface in experimental/pulp-rs/src/cmd/run_parse.rs; keep both parsers and forwarding orders in lockstep.

• --headless — run the standalone offscreen (no window). Forwarded as --headless and as the PULP_HEADLESS=1 env var so binaries that read either source pick it up.
• --screenshot <path> — save a PNG to <path> after rendering. Implies --headless. Forwarded as --screenshot <path> AND PULP_SCREENSHOT=<path>. If --headless is set without an explicit screenshot path, the CLI writes build/<target>.png so simple invocations still produce an artifact.
• --frames <n> — number of frames to render before capturing (default 1). Forwarded as --frames <n> AND PULP_FRAMES=<n>.
• --watch — re-launch the binary on file changes via the existing watch_loop plumbing. Composes with the headless flags so dev loops can render PNGs on every save.
• --audio-inspector — open the live Audio Inspector. Forwarded as --audio-inspector and PULP_AUDIO_INSPECTOR=1.
• --audio-probe-json <path> — write live probe metrics JSON and exit. Implies --headless, but does not imply a screenshot artifact. Forwarded as --audio-probe-json <path> and PULP_AUDIO_PROBE_JSON=<path>.
• --audio-scope-json <path> — write versioned live Audio Scope JSON and exit. It owns the acquisition flags --audio-scope-window, --audio-scope-trigger, and --audio-scope-channel; those flags are only valid with --audio-scope-json. Forward all four argv values plus PULP_AUDIO_SCOPE_JSON, PULP_AUDIO_SCOPE_WINDOW, PULP_AUDIO_SCOPE_TRIGGER, and PULP_AUDIO_SCOPE_CHANNEL.
• --audio-capture-wav <path> — write the live output ring to a WAV and exit. It owns --audio-capture-frames, implies --headless, does not imply a screenshot artifact, and shares the single live capture FIFO with --audio-inspector / --audio-scope-json. Forward the argv pair plus PULP_AUDIO_CAPTURE_WAV; forward PULP_AUDIO_CAPTURE_WAV_FRAMES only when the frames option is explicitly positive. Keep the C++ parser, Rust parser, C++ help, Rust help, docs/status entry, and skill text in sync.

The CLI parser is unit-tested in test/test_cli_run_options.cpp (parse + forwarding contract) and end-to-end shell-out coverage lives in test/test_cli_shellout.cpp, which exercises the discover-binary → launch-with-flags → PNG-on-disk path against the fixture binary in test/fixtures/cli_run_fixture.cpp. Rust parser and orchestrator parity lives in experimental/pulp-rs/src/cmd/run_parse.rs and experimental/pulp-rs/src/cmd/orchestrate.rs tests; update these in the same PR whenever the C++ run parser gains a user-facing flag.

Gotchas:

• --screenshot without a path argument exits 2 with a diagnostic. Bad --frames (non-integer / <= 0) exits 2 too. Both are caught before project resolution so they fail fast in --help-adjacent contexts.
• CLI-owned launcher flags must appear before --; tokens after -- are passed through to the launched binary. Do not document pulp run -- --screenshot ... as the screenshot path — use pulp run --headless --screenshot ... and reserve -- ... for target-specific arguments.
• Both argv AND env vars are set on every invocation. Do not remove the env-var fallback — older standalone binaries (and the pulp-screenshot flow) read env first.
• --watch is consumed by the CLI; it is NOT forwarded to the launched binary. The launched binary just sees the headless flags.
• --audio-scope-json cannot be combined with --audio-inspector because both consume the live capture FIFO.

pulp validate — plugin-format validators

Runs clap-validator / pluginval / auval / optional AAX validator on built plugins in build/{CLAP,VST3,AU,AAX}. Lives in tools/cli/cmd_validate.cpp.

Modes:

• Default — best-effort. Missing validators skip gracefully but emit a loud WARNING at the end listing each missing tool + install hint.
• --strict — CI enforced tier. Any "skipped because tool not installed" upgrades to exit 1. Use in CI gates.