zwicky

Copy and paste into Codex or Claude Code

Set up Zwicky and help me explore this design space with General Morphological
Analysis.

Install the current Zwicky and EDSL `main` branches from GitHub. If `uv` is not
installed, first run `python -m pip install --upgrade uv`. Then install both
CLIs as a managed tool:

uv tool install --upgrade --force \
  --with-executables-from "edsl @ git+https://github.com/expectedparrot/edsl.git@main" \
  "zwicky @ git+https://github.com/expectedparrot/zwicky.git@main"

Verify that the expected command-line tools are available:

uv tool dir --bin
command -v zwicky
command -v ep
zwicky --help
ep --help

Confirm that `command -v` resolves both commands inside the directory reported
by `uv tool dir --bin`. If either command resolves to an older installation,
do not use it: run `uv tool update-shell`, verify again, or invoke the commands
by their absolute paths in the uv tool bin directory.

Initialize a Zwicky project for my decision question, then immediately run:

zwicky -C <project-dir> guide

Treat `guide` as the authoritative, state-aware workflow. Follow its current
phase, next command, quality checks, interaction guidance, and report guidance.
Rerun `guide` after every material action and continue until the analysis is
complete or my input or approval is required. Do not edit `.zwicky/` directly.

When Zwicky builds EDSL `.ep` jobs, stop before paid model execution and show me
the commands, evaluator panels, criteria, scale, estimated job count, and likely
cost. After I approve, let the EDSL CLI manage authentication: run
`ep auth status`, use `ep auth login` only if needed, inspect the redacted
configuration with `ep profiles current`, and run `ep check`. Never display,
copy, or commit API keys. Run every job command returned by Zwicky, ingest all
result packages, analyze them, and follow `guide` through the decision handoff.
Write the final narrative report yourself; Zwicky supplies evidence and report
guidance but does not write the report.

zwicky is an MIT-licensed, offline command-line tool for General Morphological Analysis: define a problem, create a morphological box, record cross-consistency judgments, and generate the internally consistent product or feature configurations that survive.

Documentation: Read the rendered Morphological Analysis tutorial or browse the HTML source.

It is designed to be driven by people or AI agents:

• JSON output by default
• plain-text project stores that are easy to diff
• stateless commands that read and write local files
• no runtime dependencies
• no network access

Install

Install directly from GitHub:

pip install "git+https://github.com/expectedparrot/zwicky.git"

Or, if you prefer an isolated CLI install:

pipx install "git+https://github.com/expectedparrot/zwicky.git"

For local development from a cloned checkout:

pip install -e .

You can also run from a checkout without installing:

python -m zwicky init bottle --problem "Design a smart water bottle"

Quick Start

zwicky init bottle --problem "Design a smart water bottle"

zwicky -C bottle dim add mechanism --values "uv light,filter,reminder"
zwicky -C bottle dim add user --values "athletes,office workers,parents"
zwicky -C bottle dim add form --values "cap module,built in,clip on"

zwicky -C bottle cca set mechanism.uv-light user.parents --verdict tension --reason "Safety messaging must be explicit"
zwicky -C bottle cca set mechanism.filter form.clip-on --verdict incompatible --reason "Filter needs inline water path"

zwicky -C bottle config generate
zwicky -C bottle sample create --method coverage --size 4 --seed 123
zwicky -C bottle config list --human
zwicky -C bottle config stats

Complete Examples

For a book-length introduction covering the mathematical logic, CLI workflow, adaptive Bayesian sampling, Pareto analysis, and worked examples, read the interactive Morphological Analysis tutorial.

Generate two self-contained demonstration projects with synthetic digital-twin scores. No remote jobs or credentials are required; the deterministic scores exist to exercise the complete local workflow and are not research findings.

python examples/run_demos.py --example all --output /tmp/zwicky-demos

Available examples:

• hot-dog — 72 feasible product concepts, three consumer twins, purchase intent, operational complexity, and novelty.
• shelter — 216 feasible policy configurations, three stakeholder twins, protection, deployment time, program cost, and equity.

Each project contains generated EDSL job packages and a writeup/ directory with its CCA matrix, two Pareto frontiers, JSON audit data, complete analysis, an eight-concept diverse frontier portfolio, and adaptive-summary.json. The adaptive summary records a D-optimal initial batch, fitted Bayesian surrogate, UCB follow-up batch, accumulated refit, diagnostics, and explicit tradeoffs.

Commands

zwicky [-C <project-dir>] <command> ...

zwicky init <name> --problem "..."
zwicky -C <project-dir> guide
zwicky -C <project-dir> status

zwicky -C <project-dir> stakeholders add --name "Customers" --description "..." [--kind customer]
zwicky -C <project-dir> stakeholders list
zwicky -C <project-dir> stakeholders rm <name>

zwicky -C <project-dir> criteria add <name> --question "..." [--direction maximize|minimize] [--weight 1] [--evaluators stakeholder-a,stakeholder-b]
zwicky -C <project-dir> criteria list
zwicky -C <project-dir> criteria rm <name>

zwicky -C <project-dir> dim add <name> --values a,b,c
zwicky -C <project-dir> dim list
zwicky -C <project-dir> dim rm <name>

zwicky -C <project-dir> value add <dim> <value>
zwicky -C <project-dir> value rm  <dim> <value>

zwicky -C <project-dir> cca set <valA> <valB> --verdict incompatible|tension|ok --reason "..."
zwicky -C <project-dir> cca list
zwicky -C <project-dir> cca gaps
zwicky -C <project-dir> cca plot --output cca.svg [--mode assessment|results]

zwicky -C <project-dir> rule add --values value-a,value-b,value-c --reason "..."
zwicky -C <project-dir> rule list
zwicky -C <project-dir> rule rm <rule-id>

zwicky -C <project-dir> config generate [--max-configs 100000]
zwicky -C <project-dir> config list [--promising]
zwicky -C <project-dir> config show <cfg_id>
zwicky -C <project-dir> config promote <cfg_id> [--unpromote]
zwicky -C <project-dir> config stats
zwicky -C <project-dir> config infer --select value-a,value-b [--max-configs 100000]
zwicky -C <project-dir> diagnose [--max-configs 100000]

zwicky -C <project-dir> sample create --method random --size <n> [--seed <seed>]
zwicky -C <project-dir> sample create --method coverage --size <n> [--strength 2] [--seed <seed>]
zwicky -C <project-dir> sample create --method d-optimal --size <n> [--features main-effects|main-plus-pairwise]
zwicky -C <project-dir> sample create --method bayesian --size <n> --surrogate <model-id> [--acquisition thompson|ucb|uncertainty]
zwicky -C <project-dir> sample list
zwicky -C <project-dir> sample show <sample-id>
zwicky -C <project-dir> sample stats <sample-id>
zwicky -C <project-dir> sample export <sample-id> --path assessment.json

zwicky -C <project-dir> model fit --assessment <utility-id> [<more-utility-ids> ...] --criterion <criterion> [--features main-effects|main-plus-pairwise]
zwicky -C <project-dir> model list
zwicky -C <project-dir> model show <model-id>

zwicky -C <project-dir> images ingest --results <image-results.ep> [--name "Option renders"]
zwicky -C <project-dir> images list
zwicky -C <project-dir> images show <image-run-id>
zwicky -C <project-dir> images export <image-run-id> [--output scenario-list.ep]

zwicky -C <project-dir> presentations ingest --results <writeup-results.ep> [--name "Concept writeups"]
zwicky -C <project-dir> presentations list
zwicky -C <project-dir> presentations show <presentation-run-id>

zwicky -C <project-dir> report guide
zwicky -C <project-dir> report template

zwicky -C <project-dir> edsl build

zwicky -C <project-dir> utility build --sample <sample-id> [--scale 7] [--criteria criterion-a,criterion-b] [--instruction TEXT] [--rationale-question TEXT] [--low-label TEXT] [--high-label TEXT]
zwicky -C <project-dir> utility build --all-configs [--scale 7] [--batch-size 250] [--rationale none|all]
zwicky -C <project-dir> utility ingest <utility-id> --results <results.ep> [<more-results.ep> ...]
zwicky -C <project-dir> utility analyze <utility-id>
zwicky -C <project-dir> utility preview <utility-id> [--examples 2] [--output preview.json]
zwicky -C <project-dir> utility compare <utility-id> --configs <id-a> <id-b> [<id-c> ...] [--output comparison.json]
zwicky -C <project-dir> utility disagreement <utility-id> [--limit 20] [--output disagreement.json]
zwicky -C <project-dir> utility sensitivity <utility-id> [--criteria a,b,c] [--draws 1000] [--seed 123] [--output sensitivity.json]
zwicky -C <project-dir> utility shortlist <utility-id> --criteria a,b,c --size 6 [--output shortlist.json]
zwicky -C <project-dir> utility plot <utility-id> --type pareto --x <criterion> --y <criterion> --output pareto.svg
zwicky -C <project-dir> utility portfolio <utility-id> --criteria a,b,c --size 8

Generated Option Images

EDSL image-generation results can be retained as project evidence instead of being left in an ad hoc results file. images ingest reads configuration IDs and native image FileStore answers, validates them against the materialized Zwicky configurations, writes each unique image once under the content-addressed images/assets/ directory, indexes its option mapping in images/images.jsonl, and preserves the original Results package under images/runs/<image-run-id>/.

zwicky -C hot-dog images ingest \
  --results hot-dog/preference-images-12.ep \
  --name "Hot-dog option renders"

zwicky -C hot-dog images list
zwicky -C hot-dog images show image-run-47871b01
zwicky -C hot-dog images export image-run-47871b01

The defaults expect scenario.config_id, scenario.description, and answer.configuration_image. Use --config-field, --description-field, and --image-field when the EDSL Results package uses different column names. The registry keeps one row per configuration with its content hash, relative asset path, role, variant, description, and originating run. images export builds a self-contained EDSL ScenarioList.ep only when a downstream job needs one.

Configuration Presentations

Generated concept names, descriptions, and writeups can be stored by configuration ID and reused as the exact text shown in later evaluations:

zwicky -C hot-dog presentations ingest \
  --results option-writeups.ep \
  --name "Hot-dog concept writeups"

zwicky -C hot-dog utility build --sample <sample-id> \
  --presentation <presentation-run-id>

zwicky -C hot-dog preference build <preference-design-id> \
  --presentation <presentation-run-id>

The defaults read scenario.config_id, scenario.description, and answer.concept_writeup. Custom EDSL layouts can use --config-field, --description-field, --title-field, and --writeup-field. Zwicky requires the selected presentation run to cover every configuration in the evaluation.

Pairwise Preferences And Price

Ratings answer an absolute question; pairwise choices ask an evaluator to choose Option A, Option B, indifference, or (by default) Neither. Indifference means the offers seem equivalent; Neither rejects both. Each option is a complete feasible configuration with an independently assigned numeric price. This makes price a modeled attribute rather than burying it in the persona prompt.

preference design constructs a bounded, balanced set of comparisons instead of enumerating every possible pair. --no-outside-option forces A/B choice. Use --evaluators to select registered stakeholders. A stakeholder registered with stakeholders add --agent-list panel.ep contributes the agents from that exact EDSL AgentList; ordinary persona stakeholders work in the same command. preference build also writes an expanded human_survey.ep plus a Humanize schema with responsive product-card CSS. Each designed pair is a question in that survey, so a respondent sees the complete sequence. Use the returned edsl humanize preview and edsl humanize create commands to collect the same choices from people, then save responses with edsl humanize responses and ingest that Results package normally.

zwicky -C <project-dir> preference design --sample <sample-id> \
  --pairs 40 --price-levels 6,8,10 --evaluators buyers
zwicky -C <project-dir> preference build <preference-design-id>
edsl run <jobs.ep> --output <results.ep>
zwicky -C <project-dir> preference ingest <preference-id> --results <results.ep>
zwicky -C <project-dir> preference fit <preference-id>

The fit is a regularized Bayesian multinomial-logit model with categorical morphological effects and a linear price coefficient. Its output includes model diagnostics, segment summaries, configuration choice shares at a stated reference price, and approximate willingness-to-pay values in the same currency units supplied to --price-levels.

An uncertainty-focused follow-up uses the fitted posterior:

zwicky -C <project-dir> preference design --sample <sample-id> \
  --pairs 20 --price-levels 6,8,10 --evaluators buyers \
  --design adaptive --model <preference-model-id>

All commands emit JSON unless --human is supplied.

Cross-Consistency Visualization

Render the block-triangular CCA matrix as a self-contained SVG:

zwicky -C bottle cca plot --output cca.svg --mode assessment
zwicky -C bottle cca plot --output cca-report.svg --mode results

Assessment mode shows incompatible, tension, OK, and unassessed pairs. Results mode emphasizes only incompatibilities and tensions for a cleaner report figure. Hovering over a matrix cell shows its values, verdict, and recorded reason. Each plot also writes a neighboring .cca.json file containing the same audit data.

Conditional Rules, Inference, And Diagnostics

Pairwise CCA remains the primary consistency assessment. When every pair can coexist but a particular combination of three or more values cannot, record a multi-part rule instead of excluding otherwise valid pairs:

zwicky -C study rule add \
  --values channel.mobile,identity.anonymous,payment.invoice \
  --reason "Invoice collection requires an accountable identity"

config infer treats any partial configuration as input and reports compatible, forced, and eliminated values, along with matching configuration counts and examples. Counts and eliminations are conclusive only when count_exact and value_coverage_complete are true; both become false when the safety cap is reached.

diagnose reports Ritchey-style connectivity, constraint, and solution quotients; the dimension connection graph; inactive and rare values; and warnings for disconnected or capped analyses. Multi-part rules are reported separately because a conditional three-way exclusion does not make any of its constituent pairs incompatible.

After zwicky init, prefer zwicky -C <project-dir> ... for later commands. This avoids path mistakes in agents that run parallel shell calls from changing working directories. Do not run commands from inside .zwicky/, and do not use legacy command shapes such as zwicky add-dim; the supported form is zwicky dim add.

Agent Guidance

zwicky guide is more than a command suggester. It returns:

• the current methodological phase
• the next command to run
• a short General Morphological Analysis brief
• phase-specific agent instructions
• quality checks for the current phase
• references for deeper background

Example:

zwicky guide --human

The guidance emphasizes the core discipline of the method: build the design space first, judge cross-consistency second, and only then evaluate which surviving configurations are promising.

The guide also includes collaboration rules for agent use:

• ask a small number of yes/no or multiple-choice clarifying questions before mutating the project
• present proposed dimensions, values, and eliminations for user approval
• proceed with reasonable assumptions only when the user explicitly authorizes "yolo mode"
• write client-facing reports as structured design-space exploration, avoiding internal tool names and preserving assumptions, eliminations, tensions, and validation steps

Report Guidance

Zwicky does not generate final reports. It returns guidance and a Markdown template for the calling coding agent, which should write the final report in its own study structure, normally writeup/report.md.

zwicky report guide
zwicky report template

The text passed to criteria add --question is the exact valuation question placed before each configuration. utility build supplies smart defaults for the shared agent instruction, rationale prompt, and direction-aware endpoint labels. Override them when the study needs more specific framing:

zwicky utility build --sample sample-a1b2c3d4 \
  --criteria purchase-intent \
  --instruction "Evaluate each concept as a weekday lunch purchase." \
  --rationale-question "What primarily explains your {criterion} score?" \
  --low-label "Definitely would not buy" \
  --high-label "Definitely would buy"

{criterion} in --rationale-question expands to the criterion's display name. The resolved prompt settings are stored in manifest.json and contribute to the assessment ID, so changing the wording creates a distinct assessment.

report guide returns writing rules, available evidence, recommended sections, and EP-agent study layout expectations. report template returns a Markdown template that the calling agent can adapt into writeup/report.md. Zwicky keeps the audit trail and analysis artifacts; the report authoring and rendering belong to the calling agent.

Assessment Samples

config generate defines the feasible universe. sample create draws a reproducible assessment plan from that universe for a person, model, survey, or experiment to evaluate later.

config generate materializes feasible configurations in memory and on disk, so it has a hard safety cap of 100,000 and writes nothing when the cap would be exceeded. Sampling does not require materialization. It draws uniform Cartesian indices, decodes them into configurations, rejects incompatible draws, and reports attempts and acceptance rate. This permits random sampling from spaces with billions of theoretical combinations.

zwicky -C bottle sample create --method random --size 20 --seed 123
zwicky -C bottle sample create --method coverage --size 20 --strength 2 --seed 123

The random method selects feasible configurations with a deterministic seed. The coverage method greedily selects configurations that cover as many cross-dimension value pairs as possible. Samples report value coverage, pairwise coverage, candidate count, and actual size. They do not score or rank the configurations.

Random sampling selects directly from the implicit feasible draws. Coverage, D-optimal, and Bayesian methods optimize over a bounded implicit pool controlled by --candidate-pool; --max-attempts controls how many Cartesian draws may be used to fill it. Larger pools search more broadly but require more memory and computation. Sparse feasible regions may require more attempts.

Export a sample for downstream assessment:

zwicky -C bottle sample export sample-a1b2c3d4 --path assessment.json

Adaptive Bayesian Sampling

Use a D-optimal initial design when exhaustive twin scoring is too expensive and no utility results exist yet:

zwicky sample create \
  --method d-optimal \
  --features main-plus-pairwise \
  --candidate-pool 10000 \
  --size 200 \
  --seed 123

After scoring and analyzing that sample, fit an interpretable Bayesian linear surrogate for one criterion:

zwicky model fit \
  --assessment utility-initial \
  --criterion purchase-intent \
  --features main-plus-pairwise \
  --prior-precision 1

Select an unscored follow-up batch:

zwicky sample create \
  --method bayesian \
  --surrogate model-123 \
  --acquisition ucb \
  --candidate-pool 10000 \
  --exploration 1.5 \
  --diversity 0.25 \
  --size 100 \
  --seed 456

Then score the follow-up and refit with accumulated evidence:

zwicky model fit \
  --assessment utility-initial utility-followup \
  --criterion purchase-intent \
  --features main-plus-pairwise

Available acquisitions expose different tradeoffs:

• thompson draws one plausible utility surface, providing a stochastic balance between high predictions and uncertain alternatives.
• ucb adds an explicit uncertainty bonus. Increase --exploration to favor less-known configurations.
• uncertainty ignores predicted utility and selects for information gain.
• --diversity rewards morphological distance within a parallel batch, at the possible cost of lower immediate predicted utility.

D-optimal samples, model manifests, and Bayesian samples include a tradeoffs object and diagnostics. These report feature count, estimable rank, rows per feature, prior influence, fit error, posterior uncertainty, coverage, and the estimated predicted-score concession made for exploration and diversity. Low-order Bayesian linear models are interpretable and efficient, but can miss higher-order or discontinuous interactions.

Stakeholder Evaluation With EDSL

Register stakeholders whose perspectives should be used to evaluate the levels inside each dimension:

zwicky stakeholders add \
  --name "Small business customer" \
  --description "A time-constrained buyer comparing agent packages for concrete work outcomes." \
  --kind "customer segment"

zwicky stakeholders add \
  --name "Internal engineering" \
  --description "The team responsible for supportability, implementation effort, and quality controls." \
  --kind "internal team"

Stakeholders can also be backed by an existing EDSL AgentList package:

zwicky stakeholders add \
  --name "Customer twins" \
  --description "A population of modeled buyers for utility assessment." \
  --kind "customer population" \
  --agent-list customer_twins.agent_list.ep

Then build EDSL artifacts:

zwicky edsl build

This creates git-backed EDSL .ep packages under .zwicky/edsl/:

• agent_list.ep: an EDSL AgentList built from registered stakeholders
• scenario_list.ep: one scenario per dimension, carrying level names and context
• survey.ep: an EDSL survey with QuestionRank questions for each dimension and free-text reason questions
• jobs.ep: an EDSL Jobs package combining the survey and stakeholder agent list
• manifest.json: paths and next steps

The calling agent should run the saved jobs.ep package directly in its EDSL workflow and decide how to incorporate the resulting stakeholder rankings into writeup/report.md. Use the EDSL results as perspective evidence, not as automatic decisions; the reasons are usually more useful than the rank order alone.

Configuration Utility With EDSL

zwicky utility evaluates complete feasible configurations. Each criterion can target the registered stakeholders or imported EDSL AgentLists qualified to judge it. Criteria with the same evaluator panel share a survey; different panels produce separate EDSL Jobs packages whose Results are ingested together. Configurations are EDSL scenarios, so large spaces produce long-form results.

Define explicit criteria when the evaluation has important tradeoffs. Direction controls Pareto dominance and composite orientation; weights affect the summary ranking but never determine frontier membership.

zwicky criteria add "Purchase intent" \
  --question "How likely are you to purchase this configuration?" \
  --evaluators traditionalists,adventurous-diners,health-conscious-diners
zwicky criteria add "Operational cost" \
  --question "How costly would this be to prepare and serve?" \
  --direction minimize \
  --evaluators food-service-operations-expert

zwicky utility build --sample sample-a1b2c3d4 --scale 7 \
  --criteria purchase-intent,operational-cost
edsl run /path/to/consumer-jobs.ep --output /path/to/consumer-results.ep
edsl run /path/to/expert-jobs.ep --output /path/to/expert-results.ep
zwicky utility ingest utility-a1b2c3d4 \
  --results /path/to/consumer-results.ep /path/to/expert-results.ep
zwicky utility analyze utility-a1b2c3d4
zwicky report template

For exhaustive parallel scoring, omit rationales on the first pass and shard the configuration space into independently runnable jobs packages:

zwicky utility build --all-configs --scale 7 --rationale none --batch-size 250

The returned run_commands contains one edsl run command per shard. After running them, ingest all result packages in one command. A directory containing .ep packages can also be supplied.

zwicky utility ingest utility-a1b2c3d4 --results results-0001.ep results-0002.ep

After analysis, render a self-contained SVG Pareto frontier. Hover over a point for its scores and complete configuration. Dominated alternatives are faded and only frontier configurations are labeled.

zwicky utility plot utility-a1b2c3d4 \
  --type pareto \
  --x purchase-intent \
  --y operational-cost \
  --output writeup/pareto.svg

zwicky utility portfolio utility-a1b2c3d4 \
  --criteria purchase-intent,operational-cost \
  --size 8

Portfolio selection operates only on the nondominated frontier. It starts with the highest composite-scoring configuration, then greedily favors different morphological value combinations so the result is not a set of near-duplicates.

utility build returns the exact edsl run ... --output ... command and the expected results.ep path. The driving agent should normally run EDSL directly, because that agent owns credentials, remote inference mode, waiting, retries, and any UI-specific workflow.

Utility artifacts are stored under .zwicky/utility/assessments/<utility-id>/:

• agent_list.ep: the stakeholder/digital-twin agents used for the assessment
• scenario_list.ep: the sampled or full configurations being assessed
• survey.ep: rating and rationale questions for complete configurations
• jobs.ep or jobs-*.ep: independently runnable EDSL job packages
• results.ep or results-*.ep: result packages recorded with utility ingest
• scores.jsonl: normalized long-form twin/configuration scores
• ranking.jsonl: the complete configuration ranking
• analysis.json: top 100 configurations, completion statistics, stakeholder summaries, and value rollups

After analysis, build a structured evidence handoff for the separate agent that writes the final report:

zwicky utility preview utility-a1b2c3d4
zwicky utility compare utility-a1b2c3d4 --configs config-a config-b config-c
zwicky utility disagreement utility-a1b2c3d4
zwicky utility sensitivity utility-a1b2c3d4 \
  --criteria purchase-intent,operational-cost,novelty \
  --draws 1000 --seed 123
zwicky utility shortlist utility-a1b2c3d4 \
  --criteria purchase-intent,operational-cost,novelty --size 6
zwicky guide
zwicky report guide

These commands persist JSON under .zwicky/utility/assessments/<utility-id>/decision/. The preview records exact rendered prompts and execution counts; comparison creates side-by-side concept cards; disagreement identifies the largest stakeholder gaps; sensitivity reports win share and rank range across sampled weights; and shortlist records an explained, morphologically diverse selection from the Pareto frontier. Zwicky exposes these artifacts to the report-writing agent through guide and report guide but does not write the narrative report.

The calling agent should use analysis.json plus zwicky report template to write the final narrative into its study report.

Store Format

A project is a visible workspace directory named <name>/. Internal bookkeeping is stored under <name>/.zwicky/:

• project.json: name, problem statement, status
• dimensions.json: dimensions and values
• cca.jsonl: one cross-consistency judgment per line
• configs.jsonl: generated surviving configurations
• samples.jsonl: reproducible assessment plans sampled from feasible configurations
• stakeholders.json: registered stakeholders and optional AgentList references
• criteria.json: named scoring criteria, direction, and optional ranking weight
• models/*: Bayesian surrogate manifests, posterior parameters, predictions, diagnostics, and tradeoffs
• utility/assessments/*: EDSL-backed configuration utility assessments

End users should not normally edit .zwicky/ by hand. Reports and other client-facing outputs are written in the visible project workspace.

Value references can use full IDs such as mechanism.uv-light, or bare value names when unambiguous.