# Agent instructions

For AI coding agents working in this repository. Human contributors: see
[CONTRIBUTING.md](CONTRIBUTING.md).

This file follows the `AGENTS.md` convention and is read by most agent tools.
If your tool reads a different filename, point that file here rather than
copying these rules.

## Read first

[PRD.md](PRD.md) is the source of truth for what this project is and what it
refuses to become — scope, requirements, safety model, and the phase plan.
[CONTRIBUTING.md](CONTRIBUTING.md) covers how changes are proposed and reviewed.

Both apply to you. This file only adds what is specific to agents and stated
nowhere else.

The project is **released at 1.13.0**.
It contains a Rust workspace of six crates and a reference interface in `ui/`.
Released binaries support six targets.
`1.0.0` established the document schema and operation API stability promise, so
a change that breaks either is a MAJOR release and needs a migration — say so
rather than making one quietly.

## Where working notes go

Handoffs, roadmaps, goals, decision drafts, and research notes belong in
**`.ai/`**, which is gitignored and local to each working copy — it is never
part of this repository, so you will not find it on GitHub. In a working copy
that has one, `.ai/README.md` documents the layout.

- **Do not create plans, notes, or session summaries at the repository root.**
- Read `.ai/handoffs/` (most recent first) and `.ai/goals/` when starting.
- Write a handoff at the end of a substantial session using
  `.ai/handoffs/TEMPLATE.md`.
- Never cite or quote `.ai/` content in commit messages, issues, pull requests,
  or any committed file — it does not exist for anyone else.

If `.ai/` is absent in your checkout, create it (a `README.md` describing the
subfolders, plus `handoffs/`, `goals/`, `decisions/`, `roadmap/`, `skills/`,
`research/`, `notes/`, `scratch/`); it is intentionally untracked.

## Rules

- **Do not claim unimplemented features work.** Do not add capabilities to the
  README until they exist and you have run them. This applies to your own
  summaries: report what you actually executed, and say plainly what you
  skipped.
- **Do not resolve an open decision as a side effect.** [PRD §16](PRD.md) lists
  which decisions are still open (resolved ones are marked there, with the
  rationale in §16.1 — the stack is Rust). Draft options for open ones in
  `.ai/decisions/` and let the maintainer choose.
- **Write all documentation in ASD-STE100 Simplified Technical English.** This
  applies to every new or edited documentation file (README, guides, PRD
  sections, examples, release-notes prose) from now on:
  - short sentences — one instruction per step, about 20 words maximum;
  - active voice, simple present tense, imperative for procedures;
  - one word, one meaning — no synonyms for the same technical term;
  - no idioms, colloquialisms, or metaphors;
  - keep technical names, commands, code, versions, and links unchanged.
  Do not rewrite verbatim license texts (for example
  `THIRD_PARTY_LICENSES.md`), and leave `CHANGELOG.md` history as-is.
- **Do not run `git init`, create remotes, commit, or push unless asked.**
- **Follow the version pipeline for release work.** Use one branch for each
  version, one pull request to `main`, and one tag after a green merge. Read
  [skills/version-pipeline/SKILL.md](skills/version-pipeline/SKILL.md) before
  you start a version or prepare its release documentation. Never push a
  commit directly to `main`. Never tag a commit that is not green. Name a
  version branch `release/X.Y.Z-<description>`. Never use a tool or agent
  name as a branch prefix. Use `chore/<description>`
  for work that owns no version.
- **Check changes against the PRD invariants** before proposing them —
  one operation layer, determinism, reversibility, protected layers, the
  filesystem boundary, and offline operation. If a change breaks one, say so
  instead of working around it.
- **Cross-platform.** Development targets Windows and Linux (NFR-2). No
  hardcoded path separators or shell assumptions.

## Environment note

This working copy lives inside a Nextcloud-synced folder. If you see
`* (conflicted copy *)` files, flag them; never commit them.