pipx install agent-collab-treaty     # isolated (recommended)
pip install agent-collab-treaty      # or in a regular venv

cd your-project && treaty init

treaty init asks a few short questions and writes the treaty files into the current directory.

The CLI is a thin wrapper around Copier, so you can skip it:

pipx run copier copy gh:yzhaoinuw/agent_collab_treaty .

Or copy the files by hand from template/ — not from this repo's root, which holds our own dogfooded docs. Replace the Jinja placeholders in template/AGENTS.md.jinja, rename it to AGENTS.md, and fill in the bracket placeholders in the other files. The literal {{ docs_dir }} directory in there is the docs folder awaiting its name: copy its contents into treaty_docs/ (or straight to the root for a flat layout).

Hand-copied projects have no .copier-answers.yml, so treaty update and treaty diff won't work on them — you'd copy new sections from template/ by hand instead.

Fill in the bracket placeholders in AGENTS.md (runtime, common tasks, project reminders) and project_overview.md (entrypoints, active vs. legacy, authored vs. derived), then put whatever is in flight into next_steps.md and run treaty validate ..

Leave work_log.md empty — it starts accumulating from the next session. Backfilling it from git history produces exactly the "implemented function X" noise the log exists to avoid.

Non-interactive install, if you're scripting adoption:

treaty init . --defaults \
  --data integration_branch=main \
  --data env_activation='conda activate myenv' \
  --data verification_command='pytest -v -m "not slow"' \
  --data has_releases=false \
  --data 'agent_pointers=["claude-code", "cursor"]'

Three questions drop sections that don't apply to your project. All default to yes, so code repos see no change:

Opting out beats deleting: a section that never rendered can never conflict, while a section you deleted collects a conflict every time upstream revises it.

Three more worth knowing:

• docs_dir is the folder the working docs live in, treaty_docs by default. Answer . to keep everything flat at the repo root. See Where the docs live below.
• env_activation accepts none for projects that deliberately have no managed environment. AGENTS.md then says so explicitly, instead of leaving an agent to helpfully create a venv.
• verification_command is whatever proves the repo is in good shape — pytest, npm test, a link checker, a lint pass, or treaty validate .. It replaced test_command in v0.5.0; older projects carry their recorded answer over automatically.

Since v0.8.0 the working docs install into treaty_docs/, leaving AGENTS.md and project_overview.md at the repo root:

your_repo/
|- .copier-answers.yml
|- AGENTS.md
|- project_overview.md
|- treaty_docs/
|  |- treaty_conventions.md
|  |- next_steps.md
|  |- work_log.md
|  |- work_log_archive/

AGENTS.md has to stay at the root: agents resolve the nearest AGENTS.md up the directory tree, so one nested inside treaty_docs/ would apply only to files inside that folder — the opposite of what you want. project_overview.md stays with it as the human-facing entry point.

.copier-answers.yml stays at the root too, at every docs_dir value — including after treaty relocate moves the working docs. It is Copier's bookkeeping, not a treaty doc: it records your answers and the template version you are pinned to, and treaty update / treaty diff read it from the repo root. It is also the file that records docs_dir itself, so it cannot live inside the folder it names. Commit it; a gitignored answers file breaks every later update, which is why treaty init warns about one and treaty validate flags it.

The docs_dir question controls the folder name. Answer . for the flat layout, or any other name (docs/agents, .treaty) to put them elsewhere.

Projects installed before v0.8.0 are not moved. They have no recorded docs_dir, and treaty update pins those to the flat layout automatically, so updating changes nothing but adds docs_dir: '.' to .copier-answers.yml. Verified against every Copier-managed adopter we maintain: identical files touched, identical conflicts, versus the same update on v0.7.0.

To move an existing project into a folder, use treaty relocate:

treaty update                       # first: records docs_dir
treaty relocate --dry-run           # see the plan
treaty relocate                     # apply it

It moves the four working docs with git mv so history follows, rewrites the doc links in AGENTS.md and project_overview.md, retargets the project-relative links inside the moved docs for their new depth, records the new docs_dir, and does it in one pass so the recorded answer and the files on disk never disagree. --to picks a different folder, and --to . flattens everything back to the root.

Two things it will not do silently:

• It refuses to run before treaty update. A project whose answers predate docs_dir is pinned to a template that hardcodes the flat paths, so moving first guarantees a conflict on the next update. The command says so and stops.
• It checks your .gitignore. If your repo denies everything (*) and re-allows specific files, those rules stop matching once the docs move — already-tracked files survive, but the next work-log rotation is silently untracked. treaty relocate names the offending rule, and treaty validate keeps flagging it (treaty-doc-gitignored) until it is fixed.

Links pointing in both directions are handled, but differently:

• Out of a moved doc, at your own files — a [demo](media/README.md) in next_steps.md — is rewritten to ../media/README.md so it still resolves. URLs, bare anchors, absolute paths, and links that were already broken are left exactly as written. The dry run lists these before it touches anything.
• Into the treaty docs, from files the treaty does not own — your README, CHANGELOG, CI config — is reported but never rewritten. Those are yours to update.

treaty init runs a non-destructive preflight first. It warns about existing treaty files, case-mismatched ones such as Work_Log.md, and common planning docs such as TODO.md, ROADMAP.md, NOTES.md, or CLAUDE.md. It never moves, archives, rewrites, or deletes anything, and matching treaty paths are skipped rather than overwritten.

Case-mismatched treaty-looking paths block the install, because they can prevent canonical files from being created — especially on Windows. Rename or archive them, then rerun.

To fold existing docs into the treaty, say so explicitly — migration touches files the treaty otherwise never rewrites.

Prompt — type this into your agent's chat:

Migrate this repo's existing planning and logging docs into the treaty. Preserve the originals.

pipx upgrade agent-collab-treaty      # get the latest CLI first

treaty --version                      # CLI version, and the template you're pinned to
treaty diff                           # which sections would conflict?
git add -A && git commit -m "wip"     # update refuses a dirty tree
treaty update --dry-run               # preview: answer changes, updated files, conflicts
treaty update                         # apply

treaty update does a three-way merge from your pinned version up to the latest release, so edits that don't overlap upstream changes are kept automatically. If any file is left conflicted, the command names it and exits non-zero — a conflicted update is never reported as a success.

treaty update --dry-run runs that same merge in a disposable clone of your committed state and prints the summary a real apply would print — planned answer changes, files that update cleanly, files that would conflict — without writing anything to your project. It exits non-zero when the merge would conflict, so scripts can use it the same way as a real apply. Because the clone is of your committed state, uncommitted edits aren't previewed — but --data values are, since they come from the command line.

Answering questions that are new in the target version. Recorded answers are reused, and any question added since your pinned version silently takes the template default. Name the ones you care about with --data, repeatable:

treaty update --data uses_precommit=false --data verification_command="python -m pytest -q"

That is the whole reason it exists: without it, a big version jump leaves you re-prompting for every question with --interactive, or hand-editing the .copier-answers.yml whose first line tells you not to. --data docs_dir=… is refused on purpose — changing the layout through Copier deletes your customized docs and writes pristine ones at the new path, which is what treaty relocate exists to do safely.

treaty diff writes nothing. It renders the template version you're pinned to into a temp directory and compares section by section:

AGENTS.md
  untouched 9   modified 1   removed 3   added 1
  ! removed: '## Release / Tag Checklist' — upstream edits arrive with nothing local to merge into
  ~ modified: '## Runtime Environment'

Conflict exposure: 4 section(s) across 1 file(s) would conflict if upstream revises them.

Cost depends on what you edit, not how much:

treaty diff reports this breakdown for your project, and calls out renamed headings by name so you can restore the upstream heading and keep your body. work_log.md and next_steps.md are yours by design, so their drift is reported but never counted as risk.

Where your edits overlap a changed region, the merge leaves standard markers (<<<<<<< before updating / >>>>>>> after updating) in an unmerged file. Resolve them like any git merge — keep your content, fold in the new sections — and don't commit unresolved markers:

# after resolving what treaty update listed:
git add -A && git commit

After merging, treaty update prints a summary: old → new template version, answer changes, updated files, conflicted files. Your recorded answers are reused by default; pass --interactive only to re-answer the template questions.

The project must be git-tracked with a clean working tree — Copier uses git for the three-way merge and to show a reviewable diff. Run git init && git add . && git commit -m "treaty baseline" once if you haven't.

To keep unrelated untracked files (data, scratch output) from tripping the clean-tree check, list them in .git/info/exclude. Don't hide them with status.showUntrackedFiles=no, and don't gitignore *.rej: Copier finds each conflict through the .rej file it leaves in git status, so with either setting a conflicting file would be silently replaced by the template version. treaty update refuses to run under either one, and fails if a merge leaves a .rej behind anyway.

The tri-color SVG above is the primary recommendation: its text is outlined to vector paths, with no embedded or system font, so it renders identically on GitHub across every platform — no font substitution, no clipping.

Use the single-color shields.io fallback only if your README also renders outside GitHub — e.g. on PyPI or npm — where raw SVG images may be sanitized or blocked:

[![Agent Collab Treaty](https://img.shields.io/badge/Agent_Collab_Treaty-adopted-6d81f1?style=flat-square)](https://github.com/yzhaoinuw/agent_collab_treaty)

This repo's own README uses the tri-color badge via a relative path; adopters use the raw.githubusercontent.com URL, which is the same image.