JSON output of the reference tool#

Every command of the tool accepts --json and then prints one JSON value on standard output. Paths are relative to the project root, with forward slashes; the root itself is ".". Later versions may add keys. The output of model has a schema of its own, versioned with the standard, and a key of it is never removed within a version.

Failure#

When a command cannot run, it prints this object, a message on standard error, and exits with 2 (3 for an internal error):

{"ok": false, "error": {"code": "no-project", "message": "no unifold project found: ..."}}

`code`	Meaning
`usage`	Wrong command line
`no-project`	No `unifold.yaml` with the key `unifold` here or above
`bad-root`	The root manifest does not parse or states another version than 0.3; `check` reports it as a finding instead
`no-such-path`, `not-a-folder`, `not-a-root`	The path given does not fit the command
`unknown-capability`, `unknown-rule`, `nested-project`	The thing asked for does not exist here
`not-writable`, `io`, `no-mermaid`	A file could not be read or written
`internal`	A bug in the tool

For check, the object also has summary and an empty findings list, so that a reader of findings needs no second code path.

check#

{"ok": false,
 "summary": {"units": 12, "error": 1, "warn": 0, "info": 0, "rules": {"W2": 1},
             "ignored": {"C2": 3}, "root": "/work/shop", "tool": "0.3.6"},
 "findings": [
  {"rule": "W2", "severity": "error", "file": "cloud/unifold.yaml", "line": 14,
   "message": "need 'alerts.push' has no provider",
   "fix": "Add `alerts.push: <provider>` to the wiring of this manifest, or declare a need `push` here to pass it up.",
   "url": "https://unifold.md/rules#w2"}]}

ok is true when the exit code is 0: no error, and with --strict no warning.
severity is error, warn or info. line is a number or null. file is the file to change; for a missing README.md or SKILL.md it is the folder.
fix says what to do, specific to the finding where the tool can tell.
ignored counts the findings that --ignore dropped, per rule; they are not in findings and not in the counts.
With --fix, summary.fixed has written, removed and refused (lists of paths). --fix writes generated files only, never a stamp.
--format github prints the same findings as lines ::error file=cloud/unifold.yaml,line=14,title=unifold W2::message Fix: ..., with paths relative to the current folder, then the summary line.

show#

{"name": "serial", "path": "transport/serial",
 "responsibility": "Moves frames through the serial port with deadlines",
 "kind": "adapter", "status": "planned", "owner": null,
 "secret": {"what": "opening the port, writing to it and reading it with deadlines",
            "decision": "transport/docs/decisions/0001-the-line-is-one-unit.md"},
 "not": [{"text": "frame layout", "need": "frames"}, {"text": "retries", "need": null}],
 "manifest": "transport/serial/unifold.yaml",
 "parent": {"path": "transport", "name": "transport", "status": "planned", "responsibility": "..."},
 "children": [], "nested-projects": [],
 "capabilities": {"transport": {
   "kind": null, "summary": "...", "contract": "docs/references/transport.md", "parts": null,
   "used-by": [{"unit": "session", "status": "planned", "need": "transport", "config": null}]}},
 "needs": {"frames": {
   "kind": null, "summary": "...", "contract": "docs/references/frames.md", "parts": ["encode"],
   "optional": false, "platform": false,
   "provided-by": [{"unit": "codec", "status": "planned", "capability": "frames", "config": null}]}},
 "scenarios": [{"unit": ".", "name": "open", "summary": "The host opens a session"}],
 "skills": [{"name": "add-a-quantity", "path": "...", "description": "..."}],
 "decisions": [{"path": "...", "title": "...", "status": "proposed"}],
 "documents": {"tutorials": [], "references": ["..."], "explanation": ["..."]},
 "diagrams": ["transport/serial/docs/diagrams/context.md"],
 "files": ["transport/serial/README.md", "..."]}

used-by and provided-by are resolved through the whole tree: they name the units whose own code is on the other side. A unit above can be such a user, when it wires a need of its own to this capability; a need that a unit meets inside is provided by a unit below it, never from outside.
The other form of an entry: {"outside": true, "root-capability": "api"} and {"outside": true, "root-need": "clock", ...} for the world outside the project.
config is the name of the alternative, or null. parts is the list under contract, or null for the whole contract.
contract is a path relative to the root. Both sides of a connection name the same contract, so an entry under used-by or provided-by repeats none.
scenarios lists the scenarios whose hops name the unit or use a wiring line of it, with the unit that holds each.
A status other than active, and a decision status other than accepted or derived, means: not in force. The text output marks these in brackets.

capability#

{"unit": "db", "name": "store", "side": "capabilities",
 "ends": [
  {"unit": "db", "status": "planned", "side": "capabilities", "name": "store", "kind": null,
   "summary": "Keeps things", "contract": "docs/references/store.md", "parts": null,
   "optional": null, "readme": "text of the README section, or null"},
  {"unit": "web/inner", "status": "active", "side": "needs", "name": "store", "...": "...",
   "optional": false, "config": null}]}

The first end is the capability or need asked for; the others are every final user or provider. An end outside the project has "outside": true.

impact#

{"unit": "db", "status": "planned", "capability": null, "file": null,
 "dependents": [{"unit": "web/inner", "status": "active", "distance": 1,
                 "via": "need 'store' is met by capability 'store' of db"}],
 "exposed-as": [{"unit": ".", "capability": "store"}],
 "outside": ["store"], "root-capabilities-affected": ["api", "store"],
 "citations": [{"file": "web/docs/explanation/context.md", "line": 12, "cites": "db/README.md",
                "kind": "context-item", "title": "db: storage rules",
                "says": "...", "stamp": "current"}]}

distance 1 is a direct user, which can be the parent when its own need is wired to the unit; higher numbers depend on a dependent. exposed-as lists the units above that provide the capability as their own; outside the capabilities of the root through which the world uses it directly; root-capabilities-affected every capability of the root that depends on it. stamp is current, stale or missing.

tree, cited-by, skills, rules#

tree prints a list, the root first:

[{"path": "cloud", "name": "cloud", "depth": 1, "status": "planned", "kind": "system",
  "responsibility": "...", "parent": ".", "capabilities": ["public-api"],
  "needs": ["push-service"], "children": ["cloud/platform"], "nested-projects": []}]

cited-by prints the citations rows of impact; a row of kind link has no title, says or stamp. skills prints [{"name", "unit", "path", "description"}]. rules prints [{"id", "severity", "what", "fix", "url"}].

model#

unifold model prints the resolved map of the whole project. Its schema is unifold-model 0.3 and changes only with a decision; within 0.3 keys are added, never removed or changed in meaning. Keys that start with x- in a manifest, a capability, a need or a scenario are passed through untouched under x. A process tool reads this and nothing else.

{"unifold-model": "0.3", "tool": "0.3.6", "project": "serial-line", "root": "/work/serial-line",
 "units": [
  {"path": "transport", "name": "transport", "parent": ".", "children": ["transport/framing", "transport/serial"],
   "responsibility": "Sends and receives frames over the serial line", "kind": "adapter",
   "status": "planned", "owner": null, "readme": "transport/README.md",
   "secret": {"what": "how frames travel over the line", "decision": "transport/docs/decisions/0001-the-line-is-one-unit.md"},
   "not": [{"text": "frame layout", "need": "frames"}, {"text": "retries after a failed write", "need": null}],
   "capabilities": [
    {"name": "transport", "summary": "...", "kind": null, "contract": "docs/references/transport.md", "parts": null,
     "contract-parts": [{"name": "send", "kind": "command"}, {"name": "receive", "kind": "query"}], "fake": "described",
     "final-users": [{"unit": "session", "need": "transport", "config": null}], "x": {}}],
   "needs": [
    {"name": "uart", "summary": "...", "kind": null, "contract": "docs/references/uart.md", "parts": null,
     "contract-parts": [{"name": "write", "kind": "command"}], "fake": "described", "optional": false, "platform": false,
     "final-providers": [{"outside": true, "root-need": "uart", "config": null}], "x": {}}],
   "wiring": [
    {"key": "transport", "value": "serial.transport", "alternative": null, "form": "implemented-by",
     "user": null, "need": null, "provider": "transport/serial", "capability": "transport", "to-need": null},
    {"key": "serial.uart", "value": "uart", "alternative": null, "form": "passed-up",
     "user": "transport/serial", "need": "uart", "provider": null, "capability": null, "to-need": "uart"}],
   "scenarios": [
    {"name": "reassemble", "summary": "Two frames arrive in one read", "source": "proto §4.3",
     "expect": "receive returns the first payload", "hops": [
      {"caller": "transport", "target": "serial", "part": "receive", "caller-unit": null, "target-unit": "transport/serial",
       "contract": "docs/references/transport.md", "via": [{"unit": "transport", "key": "transport"}]}],
     "x": {}}],
   "decisions": [{"path": "transport/docs/decisions/0001-the-line-is-one-unit.md", "title": "The line is one unit",
                  "status": "proposed", "date": "2026-10-27", "derived-from": null, "answer": null}],
   "documents": {"tutorials": [], "references": ["transport/docs/references/framing.md"], "explanation": []},
   "x": {}}],
 "root-needs": [{"name": "uart", "platform": false, "reached-by": ["transport/serial"]},
                {"name": "clock", "platform": true, "reached-by": ["session"]}]}

units holds every unit, the root first, then by path. parent is null for the root.
form of a wiring row is connection (a need of a child met by a sibling), passed-up (to to-need of this unit), met-inside (a need of this unit, user is this unit) or implemented-by (capability is the own capability named by key). One row per alternative; alternative is its name or null.
final-users and final-providers are the used-by and provided-by of show, without status. contract-parts lists the parts the contract defines, with their kind, or is null when the entry names no contract. fake is real when the contract's ## Fake section says the real implementation, described when it says anything else, and null without the section or the contract.
A hop's caller and target are the names as written; caller-unit and target-unit are the paths of the units they name, or null for a capability or need of the holding unit. via lists the wiring lines the hop uses, from the top down, as the unit that holds the line and the key of the line; it is empty for a hop between a capability and a need of a unit without children. contract is the document in which part was looked up. An unresolved hop has unresolved, the hop as written, and error.
answer of a decision is null when it has no ## Answer section, else {"empty": true} or {"empty": false}: an open question of a process is a decision whose ## Answer is empty.
reached-by names the units whose own code finally uses a need of the root.

Commands that write#

init: {"ok": true, "root", "written": [paths], "notes": [text], "units": 1}; written holds the root manifest, if init wrote it, and the generated files. generate and skills sync: {"ok", "written", "removed", "refused"}. explore: {"ok": true, "written": "/abs/explorer.html", "opened": true}; opened is false with --no-open or when no browser could be started. stamp names every stamp it wrote; action is added or refreshed:

{"ok": true, "stamped": 1, "items": [
  {"file": "web/docs/explanation/context.md", "line": 12, "cites": "db/README.md",
   "title": "db: storage rules", "action": "refreshed"}]}

This page as plain Markdown, and its source on GitHub.