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/
|- 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.

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, update first, then relocate in one commit:

treaty update                       # first: records docs_dir: '.'
mkdir treaty_docs
git mv work_log.md next_steps.md treaty_conventions.md work_log_archive treaty_docs/
# then edit .copier-answers.yml: change  docs_dir: '.'  to  docs_dir: treaty_docs
git commit -am "Move treaty docs into treaty_docs/"

The order matters: treaty update has to run first, so the project is on a template version that understands docs_dir before the files move. Because the recorded answer and the files on disk then agree, the next treaty update merges at the new paths with no conflict.

Two things to check afterward, neither of which upstream can do for you:

• Doc links in your AGENTS.md still point at the old flat paths. That file is yours, so fix them by hand.
• Your .gitignore, if it denies everything and re-allows specific files (* followed by !work_log.md). Those negations stop matching once the files move, so anything added under treaty_docs/ later — a new archive chunk, say — is silently ignored. Add !treaty_docs/ and !treaty_docs/** , then confirm with git check-ignore -v treaty_docs/work_log.md.

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:

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.

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.

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.