Documentation

Working with other people

A project is not one person and one laptop. This is how more than one of each works.

Roles decide what each surface will let you do

Membership is per organisation, and the same role governs the browser and the CLI. A viewer can watch a task run; they cannot say it passed. That is enforced where the request is answered, not by hiding a button.

The roles and permissions screen: an access ladder from Viewer to Admin, and a capability matrix beneath it. — The ladder, and the matrix behind it. A custom role carries an explicit capability matrix rather than just a rung.

Role	Can
Viewer	Read the graph and the code
Editor	…and comment, and shape the architecture: sketch, rename, add
Coder	…and run tasks and execute code; limited merge-sync and contract editing
Programmer	…and approve reviews, sign off, merge sync, define contracts
Admin	…and invite and manage members, billing and model keys

The people and teams screen: who is in this organisation and the roles they hold. — Invite from **Organisation → Members**. An invite is a link with a role attached.

Invite them to the organisation

Organisation → Members → Invite, with the role they should have. They accept in the browser; nothing is installed yet.

They clone the repository

.vipl/link.json is committed, so the checkout already knows which project it is and on which deployment. There is nothing to configure.

They run `graph setup`

Which signs their machine in. Because the folder is already linked, the second half is a no-op. graph status will confirm it.

They run `graph agent`

Now there are two terminals on the project, and either can pick up work.

Several terminals on one project

More than one graph agent can serve the same project from different machines. The board lists every connected terminal with its hostname and folder, so Execute can be aimed at a particular one: the machine that has the database running, or the one with the right credentials.

The same fact from the terminal side.

What cannot happen is two runners in the same folder: the second refuses, because two agents editing one working tree is a corrupted checkout, not parallelism.

Seeing each other

The live graph screen: the sketch on the left, the typed graph on the right, with a presence indicator and a live/synced state along the bottom. — The live graph, with presence along the bottom edge. Edits and presence arrive over the project's event stream, not by polling, which is why the state reads *live · synced* rather than a timestamp of the last refresh.

The activity and history screen: a chronological log of everything that has happened to the project. — Activity and history: every interpretation, expansion, build and merge, with who did it.

Review and handoffs

Two screens exist for the moments when work passes between people rather than between machines.

The live expansion and review screen, showing a proposed graph expansion for approval. — **Review**: an expansion is proposed, narrated as it is produced, and approved or rejected before it becomes the graph.

The phases and handoffs screen showing project phases and who owns each. — **Phases**: which part of the plan is whose, so two people are not building the same route.

The scale screen, showing how a large project is partitioned for several contributors. — **Scale**: how a large graph is partitioned so a team can work on it at once.

Working with people who will not install anything

Share a link. Every panel is addressable, so a finding, a flow or a drifted node can be sent as a URL. One caveat today: ?project= is honoured for a slug id and silently dropped for a project still carrying the sketch-… id it was drawn under, which opens an empty board instead. Check the id in graph projects before sending the link.
Share the project read-only. A viewer needs no terminal and no local checkout to follow along.
Let CI be the third participant. graph check on a pull request is an opinion nobody has to remember to ask for. See The API, tokens and CI.

Reviewing what an agent did

Every build is a commit in your own git history with the task in the subject line, so the normal review tools work. git show <sha> is the diff, graph undo is the revert, and the board's Activity panel is the record of who asked for it.

Undo puts the folder back **and** puts the task back to pending, so the plan is runnable again rather than merely reverted.