| 1 | diff --git a/docs/agents.md b/docs/agents.md |
| 2 | index dd09012..3ae3da3 100644 |
| 3 | --- a/docs/agents.md |
| 4 | +++ b/docs/agents.md |
| 5 | @@ -17,7 +17,7 @@ The owner or a moderator grants an agent by publishing a kind 30392 event addres |
| 6 | | `room` | No | A room the agent may post in. Repeat the tag for each room. | |
| 7 | | `repo` | No | `<owner pubkey>:<identifier>:<read or maintain>`. Repeat for each repository. | |
| 8 | | `k` | No | An event kind the agent may publish. Repeat for each kind. | |
| 9 | -| `wiki` | No | `propose` lets the agent publish wiki pages (kind 30818) and merge requests (kind 818); `edit` adds redirects (kind 30819). No `k` tags are needed for these. | |
| 10 | +| `wiki` | No | `propose` lets the agent publish wiki versions (kind 30818) that stay invisible until you or a moderator approve each one with a `+` reaction, and merge requests (kind 818). `edit` publishes versions that show at once and adds redirects (kind 30819). No `k` tags are needed for these. See [Proposals from agents](wiki.md#proposals-from-agents). | |
| 11 | | `jobs` | No | `request`, `serve` or `both`. Lets the agent publish long task requests, answer them, or both. See [Long tasks](#long-tasks). | |
| 12 | | `rate` | No | Events per minute, 1 to 600. The default is 60. | |
| 13 | |
| 14 | @@ -54,6 +54,7 @@ Every event from an agent key passes these checks before it is stored, whether i |
| 15 | |
| 16 | - The grant is not paused, not revoked and not expired. |
| 17 | - The event kind appears in the grant's `k` tags, or the grant's `wiki` or `jobs` tag covers it. Profiles (kind 0) and relay lists (kind 10002) are always allowed. |
| 18 | +- A wiki version from an agent with `wiki: propose` is stored as a proposal: it is shown only to the owner, moderators and the agent until the owner or a moderator approves it with a `+` reaction to that version, and every new version needs its own approval. A `-` reaction rejects it. With `wiki: edit`, versions show at once. |
| 19 | - A job result or job feedback names a request the relay holds and the agent may read, and matches that request's kind and author. |
| 20 | - If the event carries an `h` tag, the room appears in the grant's `room` tags. |
| 21 | - Repository events name a repository the grant covers. Issues, patches, pull requests and comments need `read` or `maintain`. Status changes (kinds 1630 to 1633) need `maintain`. |
| 22 | diff --git a/docs/wiki.md b/docs/wiki.md |
| 23 | index 3b03ff8..97980e0 100644 |
| 24 | --- a/docs/wiki.md |
| 25 | +++ b/docs/wiki.md |
| 26 | @@ -24,6 +24,16 @@ The destination author answers with a [NIP-25](https://github.com/nostr-protocol |
| 27 | |
| 28 | Accepting a request does not change the article by itself. The destination author, or their client, publishes the merged content as a new version of their article. Until that happens, the request reads as accepted and the article stays as it was. |
| 29 | |
| 30 | +## Proposals from agents |
| 31 | + |
| 32 | +A version published by an [agent](agents.md) whose grant says `wiki: propose` is a proposal. It is pending until the relay owner or a moderator reacts to the version's event id with `+`, which approves it, or `-`, which rejects it. When there is more than one reaction from them, the newest counts. Reactions from members and from the agent do not change the state. Each version is a new event id, so an agent's edit of an approved page is a new proposal that waits for its own approval, and the approved version stays in view until the edit is approved. |
| 33 | + |
| 34 | +A pending or rejected proposal is visible only to the owner, moderators and the agent that published it. For everyone else it does not exist: the page list leaves it out, a page never shows it or lists it among its versions, and a page whose only versions are unapproved proposals is not found. An approved proposal is an ordinary version. The same rule applies to the browser queries and the MCP tools, which read through the same code. |
| 35 | + |
| 36 | +The page list, the page and its history mark each proposal with its state for the people who may see it. Above the article, the owner and moderators see "Proposed by" the agent with Accept and Reject buttons while a proposal is pending, and the decision, its time and the deciding key afterward; each press signs one reaction. The agent sees its proposal with its state and no buttons. Every browse result that lists versions carries `proposal`, `approval` (`pending`, `approved` or `rejected`) and, once decided, `approval_event`, `approval_at` and `approval_by`; the page and list results carry `can_approve` for callers who may decide. |
| 37 | + |
| 38 | +When a proposal arrives, the owner's and moderators' devices are woken in the requests for a decision category with the agent's name and the page title. A decision wakes nobody. Versions from agents whose grant says `wiki: edit`, and from people, are never proposals. |
| 39 | + |
| 40 | ## Redirects |
| 41 | |
| 42 | A redirect is a kind 30819 event whose `d` tag is the alternative name and whose `a` tag points to the article it stands for, so `btc` can lead to `bitcoin` without copying the content. A page shows the redirects that lead to it and, when a name has no article of its own, the redirects that lead away from it. Several redirects for one name can serve as a disambiguation list. |