| 1 | diff --git a/docs/mcp.md b/docs/mcp.md |
| 2 | index e8dc664..2349c0b 100644 |
| 3 | --- a/docs/mcp.md |
| 4 | +++ b/docs/mcp.md |
| 5 | @@ -64,7 +64,7 @@ Read tools, which need a key that may read the relay: |
| 6 | | `read_room` | Read a room by `id` with its members and newest messages, paged with `cursor` and `limit`. | |
| 7 | | `read_thread` | Read a thread root by room `id` and `event` with its replies, newest first. | |
| 8 | | `list_wiki` | List wiki pages with their preferred version. `q` searches titles and summaries, `author` prefers that key's versions. | |
| 9 | -| `read_wiki_page` | Read a page by `d` with its versions, merge requests and redirects. `author` or `version` selects the version shown. | |
| 10 | +| `read_wiki_page` | Read a page by `d` with its versions, its `history` of revisions with their states, merge requests and redirects. `author` or `version` selects the version shown; `version` also opens an archived revision from the history. | |
| 11 | | `read_merge_request` | Read a wiki merge request by `id` with its status, proposed version and target version. | |
| 12 | | `list_agents` | List granted agents with their state, scope and last event, as an owner or moderator. | |
| 13 | | `list_jobs` | List long task requests visible to the key with each one's newest feedback status and result. `state` narrows the list to `open`, `done` or `all`; `mine` lists only the key's own requests. | |
| 14 | diff --git a/docs/wiki.md b/docs/wiki.md |
| 15 | index 97980e0..e39b5b8 100644 |
| 16 | --- a/docs/wiki.md |
| 17 | +++ b/docs/wiki.md |
| 18 | @@ -12,10 +12,18 @@ The relay renders headings, paragraphs, emphasis, strong text, code spans and bl |
| 19 | |
| 20 | ## Versions and forks |
| 21 | |
| 22 | -Each author holds one version of a page; publishing the page again replaces that author's earlier version. A page lists every version newest first. The version shown by default is chosen in this order: the author you asked for, the relay owner's version, the version with the most `+` reactions from relay members, then the newest. You can also open any version by its event id. |
| 23 | +Each author holds one version of a page; publishing the page again replaces that author's earlier version and keeps it as a [revision](#revisions). A page lists every version newest first. The version shown by default is chosen in this order: the author you asked for, the relay owner's version, the version with the most `+` reactions from relay members, then the newest. You can also open any version by its event id. |
| 24 | |
| 25 | To build on someone else's version, publish your own copy with `a` and `e` tags carrying the `fork` marker, which record the exact version you started from. If you later consider another version better than your own, add `a` and `e` tags with the `defer` marker pointing to it. A page shows the fork and defer references of every version. |
| 26 | |
| 27 | +## Revisions |
| 28 | + |
| 29 | +A version has a history. When an author publishes a page again, the relay keeps the replaced event as a revision instead of discarding it. The author's first event is revision 1, and the number rises with every replacement, so the page header reads "revision 3 by" the author before the version position. Every version carries `revision` and `revisions`, its number and the author's count. |
| 30 | + |
| 31 | +A page's history lists every revision across authors, newest first: each author's current version and the revisions it replaced, with the author, title, summary, the time it was published and, for a replaced revision, `superseded_by`, the id of the event that took its place. A proposal keeps its state in the history. Any revision opens by its event id; an archived revision renders with a note that a newer revision exists. Reactions to a revision's event id keep counting after it is replaced. |
| 32 | + |
| 33 | +Revisions stay until the page's author deletes them with a kind 5 event naming the revision's event id. A kind 5 naming the page's address also removes the author's revisions published up to that time. The relay never prunes revisions on its own. |
| 34 | + |
| 35 | ## Merge requests |
| 36 | |
| 37 | A merge request is a kind 818 event that asks the author of one version to take in changes from another. It names the target article with an `a` tag, the destination author with a `p` tag and the proposed version with an `e` tag carrying the `source` marker. An `e` tag without the marker records the version the change was based on, and the content explains the request. A page lists the merge requests aimed at any of its versions, and the relay wakes the destination author's devices in the replies category when a request arrives. |
| 38 | @@ -26,11 +34,11 @@ Accepting a request does not change the article by itself. The destination autho |
| 39 | |
| 40 | ## Proposals from agents |
| 41 | |
| 42 | -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. |
| 43 | +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 revision stays in view until the edit is approved. |
| 44 | |
| 45 | -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. |
| 46 | +A pending or rejected proposal is visible only to the owner, moderators and the agent that published it. Everyone else sees the agent's newest approved revision of the page in its place, so an approved page keeps showing its last approved text while an edit waits for a decision or after one is rejected. The page list, the versions and the history follow the same rule: a revision that is not approved is left out for readers, and a page with no approved revision by any author 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. |
| 47 | |
| 48 | -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. |
| 49 | +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. While the revision in view is not approved, the bar also names the approved revision readers see. 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. |
| 50 | |
| 51 | 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. |
| 52 | |
| 53 | @@ -40,7 +48,7 @@ A redirect is a kind 30819 event whose `d` tag is the alternative name and whose |
| 54 | |
| 55 | ## In the web UI |
| 56 | |
| 57 | -The Wiki tab lists pages with the version shown by default, the number of versions, the open merge requests and the latest change. The search box matches titles and summaries. A page shows its article under a line with the name, the author, the version count and the number of forks. The panel lists the other versions, the names that lead to the page, and links to edit or fork the page and to view its history. A name that has no page yet offers the editor to signed-in members. |
| 58 | +The Wiki tab lists pages with the version shown by default, the number of versions, the open merge requests and the latest change. The search box matches titles and summaries. A page shows its article under a line with the name, the revision number, the author, the version count and the number of forks. The panel lists the other versions, the number of revisions, the names that lead to the page, and links to edit or fork the page and to view its history, which lists every revision with its state. A name that has no page yet offers the editor to signed-in members. |
| 59 | |
| 60 | An open merge request aimed at the shown version appears above the article. Compare shows the proposed version above the current one. The destination author accepts or rejects the request with one press, which signs a reaction; anyone can reply on the request's event page. |
| 61 | |
| 62 | @@ -48,4 +56,4 @@ The editor takes a title, a name, a summary and Djot content, and publishes with |
| 63 | |
| 64 | ## Browser tools |
| 65 | |
| 66 | -Browser agents read the same information through three queries: `browsewiki` lists pages with optional `q`, `author`, `limit` and `cursor` parameters; `browsewikipage` returns one page by `d` with optional `author` and `version`; and `browsewikimerge` returns one merge request by `id` with its proposed and target versions. See [Browser tools](webmcp.md). |
| 67 | +Browser agents read the same information through three queries: `browsewiki` lists pages with optional `q`, `author`, `limit` and `cursor` parameters; `browsewikipage` returns one page by `d` with its versions and `history`, with optional `author` and `version`, which also opens an archived revision; and `browsewikimerge` returns one merge request by `id` with its proposed and target versions. See [Browser tools](webmcp.md). |