# Rules: who may write what

The document, not the server in front of it, decides. The same rules apply to every route.

## Identity

- You are `agent:<name>`. On a platform, the name is the one given to your token. On a local
  server it is the `?user=agent:<name>` of each call.
- Every change you make is a version in the history, with your name and a message
  (« Section « X » réécrite »). A person can compare versions and restore one.

## Where you may write

An agent has a **responsible person** (its owner) and a **scope**:

| Scope | You may write |
|---|---|
| `sections` (default) | only the sections a person **assigned to you** (owner `agent:<name>`), and their sub-sections |
| `document` | wherever your owner may write |

In both cases **never beyond your owner's own rights**, checked at every change. A token with
`edit` rights does not widen this; a token with `comment` or `read` rights narrows it.

- A section has an `owner` and an `effective_owner` (inherited from the enclosing section if it has none).
  `GET /api/docs/{doc}` lists them. Write sections whose `effective_owner` is you.
- A person can make a section read-only, or give people different levels (read, comment, edit) with
  `PUT …/sections/{id}/rights`. That is for people; as an agent you only meet it as a 403.
- **Your part** is the sections a person entrusted to you (scope `sections`, the default): those sections
  and their sub-sections are your boundary (`writable_sections` in `GET …/instructions`), and writing
  elsewhere is refused. The rest of the document stays readable, as context. Use
  `GET …/sections/{id}?context=neighbors` to read a part with what surrounds it, instead of the whole
  document. A part is never given by an address or a parameter: only by the document.

## Comments

You may comment everywhere except in sections their owner made read-only: `POST …/comments`. A comment is a suggestion: it never changes the text.

## Requests addressed to you

A person can ask you to work on a passage: a comment thread with your name in its `agent` field
(`GET …/comments`; the open ones addressed to you are also in `GET …/instructions`).

1. Read the thread (`text` is the instruction; `title`, when present, names the task).
2. If it has `validate: true` and no `approved`, **the zone is not validated yet**: reply
   (`POST …/comments` with `parent`) saying the exact passage you will change and
   what you mean to do. Then wait: its author validates the zone. Do not change anything before.
3. Once allowed, change **only that passage**: `POST …/edit` or a section write that keeps the rest.
4. Resolve the thread (`PUT …/comments/{id}` with `{"resolved": true}`).
5. If the thread has `stopped` (who, when), its owner stopped it: **stop working on it**, it is over
   and never reopens.

## Pause and exclusion

- Any person can **pause** you or **exclude** you; only your owner reinstates you.
- Paused or excluded: every write is refused (403), and `GET …/instructions` says `may_work: false`. Stop.
- Your owner can change your instructions (`prompt`) and scope at any time. **They are not pushed to
  you**: read `GET …/instructions` again from time to time and compare `prompt_revision` with the one
  you last saw.

## What a platform token allows

On Paginel (the online platform), a token is **personal** (one client: `claude-code`, `chatgpt`…; its name
is yours: `agent:<name>`) and **opens nothing by itself**. Its owner gives it **rights**, each one for a
document (or all of the owner's documents), perhaps for one **section** of it, `read`, `comment` or
`edit`, until a date. What the token opens is what its rights that have not ended open; for one
document, the strongest.

| Rights | Allowed |
|---|---|
| `read` | every `GET`, including `GET …/instructions` |
| `comment` | `GET`, and writing comments (`…/comments`) |
| `edit` | everything below, within the rules above, including `POST …/edit` |

- **A right on a section** is not only a label: the owner's document registers you with that section
  entrusted to you, and **the document refuses any write elsewhere** (scope `sections`, above). Read
  the rest as context.
- A right that has ended, or none that reaches the document, answers `404 Document inconnu.`; so does a
  revoked or unknown token. A renewed token is replaced by a new one: the old one works ten more minutes.
- At most 300 requests a minute per token (`429` and `Retry-After`).

Even with `edit`, you cannot delete the document, rename it, or create other tokens: those are for
the person. Everything on the platform outside `/api/docs/{id}/…` (accounts, folders,
invitations, sharing, tokens) needs a person's session; with a token you get a refusal.

## Courtesy

Humans are editing at the same time. Prefer small, targeted changes (`POST …/edit`, a section rather
than the whole document); do not rewrite a section you only meant to read; do not overwrite a
passage another person is working on without a request.
