Project layout

humanish init gives a project two roots:

humanish/   # committed study source
.humanish/  # ignored runtime state, evidence and local overrides

Committed study source: humanish/Copy Anchor Link

init writes these files, plus an AGENTS.md section for coding agents, and prints each file it created or changed:

humanish/
  README.md
  studies/
    first-run.yaml          # keyless preview
    try-live.yaml           # first live study
    cua-browser.yaml        # computer-use participants on a hosted desktop
    local-browser.yaml      # computer-use participants on a local desktop
  personas/
    synthetic-new-user.yaml
    skeptical-power-user.yaml
  scenarios/
    first-run-smoke.yaml    # the dry run's scenario

Rerunning init creates only missing files. It replaces its own AGENTS.md section, between the <!-- humanish:agents-guide --> and <!-- /humanish:agents-guide --> markers, and leaves the rest of the file as it was.

Studies select their subject, actor, participants, personas, scenarios, tasks, budgets and policies. Personas and scenarios are referenced by id. An adopter scorer is an .mjs module that a study names under review.scorer.ref.

Keep this directory reviewable and reproducible from a clean clone. Everything in it is public-safe: synthetic personas and fixtures, env var names without values.

Ignored runtime state: .humanish/Copy Anchor Link

.humanish/
  runs/             # run bundles, screenshots, transcripts, Observer output
  studies/          # private studies; a committed study with the same id wins
  local/studies/    # machine-local studies
  local/personas/   # machine-local personas; a committed persona with the same id wins
  cache/ tmp/ logs/

Never commit run bundles, raw screenshots, transcripts, local overrides or secrets. init adds .humanish/ to .gitignore.

FormatsCopy Anchor Link

• .yaml for human-authored source: studies, personas, scenarios. Prefer .yaml over .yml.
• .mjs for executable adopter scorers.
• .json for generated artifacts and synthetic fixtures; .ndjson for appendable event and transcript streams.
• .yml only where an outside tool expects it, such as .github/workflows/*.yml.