Sources

A source is a folder with files: a git repository or a plain folder on disk, placed in the tree beside the documents it belongs with. The site's code can sit next to the pages it serves. Source code stays in git, where it merges per commit and a build can run against it. Mod knows where each checkout is and which session works in it, and shows you what changed.

How it works

Mod has two realms and keeps them apart. Documents live on the log and merge per character. Code lives in git and merges per commit, because a build has to run against a whole, consistent snapshot. Code is never put on the log as documents; it moves between machines as git objects.

A path has one owner: it is a document or a file, never both. Disk is a projection, never a peer, and nothing syncs between documents and files in the background. Every crossing between the realms is a command with one direction: a checkout, a pull, a save to disk, or dragging a document into a checkout or a file out of one. A document dropped into a checkout is written there as a file and leaves Mod; git sees a new file. A file dropped among documents becomes a document and leaves the disk; git sees a deletion.

The rule exists because treating a document and a file as two copies that reconcile is how work gets lost without anyone noticing. Mod lost work that way twice before making it.

A project can hold several sources, each a repository or a plain folder. The project records each source's identity: its name, its kind, and for a repository its remote and trunk. It never records a path on a device. Each device attaches its own folder for a source, so a device without that checkout shows the source folder as unavailable, and a link to one of its files still points at the right place. A source folder holds only its files.

Saving a file is guarded. If the file changed on disk since you opened it, say because an agent edited it, the save is refused and you see the difference first. A tracked file's earlier version is also recoverable from git.

Git, as it is. Mod does not replace git or your git host. A session that changes code gets its own branch, mod/session/<id>, forked from the trunk in its own worktree, so parallel sessions never share a working copy. A session started on a branch that already exists attaches to it instead, and a session on a Mod branch opens a git branch of the same name, so a piece of work's documents and code travel together. Writing to git is the agent's own, through git or jj in its harness. Every commit, merge and push is a command on the session's log, so you can see when and why it happened.

Code moves between machines as git objects, so a session's branch and its uncommitted work reach whichever machine runs it. Two agents in one repository merge per commit, through git, and a change git cannot merge on its own becomes a task for the session.

Seeing code beside the work. Code changes appear in a session's and a project's history beside the document changes: a session lists the commits on its branch since its base, and a project shows recent commits on its branches plus what is not yet committed. A commit opens to its files, and a branch opens in the review canvas, where people and agents comment on lines and merge.

A reference to a file names the source and a path, never a host. Moving a checkout to another folder or machine does not break a link to it. A source can also move to another project, keeping its id, its git pointer and each device's checkout.

Using it as you build

Attach a repository or folder from any folder's menu in the tree, including the root. It appears as a child folder there, named after the directory.

From the command line, start a project from a repository, or add a repository to a project you already have:

mod-next init "Launch site" --repo ~/code/site
mod-next code adopt <projectId> --repo ~/code/site --base main --name site

An agent adds a folder that exists on its own device with add_source, and says where in the tree it goes:

add_source { "path": "~/code/site", "folder": "marketing/site" }

remove_source detaches one. Detaching never deletes the files or the repository; it only takes the source out of the project and makes this device forget the folder.

A session in a VM publishes its branch with publish_branch, which pushes it and opens a pull request through your Mac's own git sign-in, and merges with merge_pr. A merge into your main branch asks the person in the session first.

You decide which repositories and folders a project uses, the branches, and which device or VM holds each worktree. Your git host, CI and review rules stay yours. Mod does not replace them.

Limits

• publish_branch only fast-forwards. It never rewrites a branch, and it publishes only what is committed.

• An agent can only add a folder on the device its session runs on. A session in a VM cannot attach a folder on your Mac.

• A plain folder has no branches, diffs or review. Those need git.

• Two sources in one project cannot overlap on disk. One inside another is refused.

• Opening a source file from a link in an app or a comment is being built (RFC 0356). soon