unifold 0.3.6

Your first map#

For a developer who has a repository with a few folders, Python 3.9 or newer and uv. In about fifteen minutes you give the repository a root manifest, describe two folders as units, connect them, and see the first generated diagram. The example is a repository shop with a folder billing/ that uses a folder platform/; use your own folders in their place.

Install the tool with uv tool install unifold, or write uvx unifold wherever the steps write unifold.

1. Start the project#

Run, in the root of the repository:

unifold init
unifold check

init writes unifold.yaml with the version of the standard, the name of the folder and responsibility: TODO. If the repository has no README.md, it writes one from the template, with placeholders in angle brackets. check prints three warnings and no error: the TODO, and two example headings of the template. A project of one unit already conforms.

Replace the TODO with one line that says what the repository is. In README.md, write the first paragraph and the ## Why, and delete the sections that do not apply yet. Run unifold check --fix. It reports no error and no warning.

2. Make one folder a unit#

Give the folder that others depend on most a manifest and a front page:

# platform/unifold.yaml
responsibility: Shared runtime services
capabilities:
  clock: The current time

# platform

Shared runtime services for the other parts of the shop.

## Why

Every part needs the same few services; one implementation keeps them alike.

Save the second file as platform/README.md; every unit has one. Run unifold check --fix. It writes the generated files: docs/diagrams/component.md in the root, with one box, and platform/AGENTS.md. One warning remains: 'platform.clock' is provided but nothing uses it.

3. Declare what the second folder needs#

Give billing/ a manifest with a need, and a README.md like the one of platform:

# billing/unifold.yaml
responsibility: Creates invoices
needs:
  clock: A time source

Write the need in the words of billing: what it needs, never who has it. Run unifold check --fix. You see an error:

error W2 unifold.yaml: need 'billing.clock' has no provider

That is the point of the check: a need that nobody meets is found before anybody reads the code.

4. Connect the need in the parent#

Connect the need in the unit above both folders, here the root:

# unifold.yaml in the root
unifold: "0.3"
name: shop
responsibility: Shop backend
wiring:
  billing.clock: platform.clock

Run unifold check --fix. The first error is gone, and two new ones appear:

error W11 unifold.yaml:5: capability 'platform.clock' names no contract
error W11 unifold.yaml:5: need 'billing.clock' names no contract

The connection exists, but nothing says what travels on it.

5. Write down what they agree on#

Write the contract of the connection, docs/references/clock.md in the root: what the clock gives and in which form, with one example, and what stands in for it in the tests of billing. contracts.md explains every line; this is about the smallest contract that passes:

# clock

Contract of `platform.clock`, the current time. Notation: wit.
Sources: none

## Parts

### now

Kind: query

```wit
now: func() -> u64;
```

Pre: none.
Result: the seconds since 1970-01-01T00:00:00Z.
Errors: none.
Examples:

| Case | Input | Expected |
|---|---|---|
| at 2026-01-01T00:00:00Z | `now()` | `1767225600` |

## Fake

A clock that stands still until a test moves it. Faults it can inject: none.

The contract lives in the unit that connects the two sides, and both name it:

# platform/unifold.yaml
capabilities:
  clock:
    summary: The current time
    contract: ../docs/references/clock.md
# billing/unifold.yaml
needs:
  clock:
    summary: A time source
    contract: ../docs/references/clock.md

Run unifold check --fix. It reports 3 unit(s): 0 error(s), 0 warning(s), 0 info. The component diagram now shows two boxes and an arrow from billing to platform, labelled clock. The check does not read your code: keeping the code and the map in step is part of every change, and of its review.

6. See the map in the browser#

Run:

unifold explore

It writes the explorer, one HTML page, outside your repository and opens it in the browser: the component diagram with billing and platform, each box clickable, and beside the map the two README.md files and the contract clock.md. Nothing is committed; run the command again after a change.

7. Ask the map a question#

Run:

unifold show billing

It prints the unit, its need with the contract, and who provides it: provided by platform capability 'clock'. From any file inside billing/ the same command finds the unit. This is what a coding agent runs first.

8. Let agents in#

Run:

unifold init --agents

This installs the skills unifold and unifold-convert and the tool into docs/skills/, writes their stubs into .agents/skills/ and .claude/skills/, and adds the unifold block, with the index of units, to the root AGENTS.md. From here, ask an agent to convert the rest of the repository with the skill unifold-convert. Or continue one folder at a time: a manifest, a README.md, the needs, the contract, the wiring line, check. Most folders never need a manifest.

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