When peering works end to end: describe it in README + ARCHITECTURE

Cordy commented

2026-08-05 18:46:16 +00:00

Owner

Trigger-based documentation debt, in the same spirit as #118 (which was closed once the dependency claims were settled by PR #122). This one is about the feature description, which is a different thing and is still missing.

Do not action before #106. Until peering demonstrably works between two instances, any description would be written from intent rather than from fact — which is how the "age is post-quantum" line and the "four dependencies" line both went stale.

Trigger: #106 (second-instance dogfood) passing a real A↔B transfer.

What is missing today:

README.md — the Features list has no peering entry at all. Every other shipped capability has one (WebDAV, TUS, share links, storage drivers, auth modes, authorization, trash, governance, quota, encryption, licensing, ops).
README.md — the configuration paragraph lists every opt-in block (shares, storage.quota, storage.trash, storage.encryption, auth.admins, …) and does not mention peering.
example.config.json — no peering block.
ARCHITECTURE.md — the v0.5 roadmap entry still describes peering in the future tense; it needs to move to a shipped § section like the other implemented subsystems, with the transport, trust model and delivery path described rather than proposed.
docs/handbook/ — no peering page. Carried over from #118 and noted on #123.

Write it once, at the end. One pass after #106 covers #102–#106 together and describes what actually shipped. Four partial passes as each issue lands would repeat the failure mode this issue exists to prevent.

Also fold in at that point: auth.perUserHomes is a hard prerequisite for peering (see #123 and docs/handbook/deployment.md) — the README feature entry and the handbook peering page must both say so, because an operator who discovers it at the first failed transfer has already had a bad day.

Trigger-based documentation debt, in the same spirit as #118 (which was closed once the *dependency* claims were settled by PR #122). This one is about the **feature description**, which is a different thing and is still missing. **Do not action before #106.** Until peering demonstrably works between two instances, any description would be written from intent rather than from fact — which is how the "age is post-quantum" line and the "four dependencies" line both went stale. **Trigger:** #106 (second-instance dogfood) passing a real A↔B transfer. **What is missing today:** - `README.md` — the Features list has **no peering entry at all**. Every other shipped capability has one (WebDAV, TUS, share links, storage drivers, auth modes, authorization, trash, governance, quota, encryption, licensing, ops). - `README.md` — the configuration paragraph lists every opt-in block (`shares`, `storage.quota`, `storage.trash`, `storage.encryption`, `auth.admins`, …) and does not mention `peering`. - `example.config.json` — no `peering` block. - `ARCHITECTURE.md` — the v0.5 roadmap entry still describes peering in the future tense; it needs to move to a shipped `§` section like the other implemented subsystems, with the transport, trust model and delivery path described rather than proposed. - `docs/handbook/` — no peering page. Carried over from #118 and noted on #123. **Write it once, at the end.** One pass after #106 covers #102–#106 together and describes what actually shipped. Four partial passes as each issue lands would repeat the failure mode this issue exists to prevent. **Also fold in at that point:** `auth.perUserHomes` is a hard prerequisite for peering (see #123 and `docs/handbook/deployment.md`) — the README feature entry and the handbook peering page must both say so, because an operator who discovers it at the first failed transfer has already had a bad day.

Cordy added this to the v0.5 — Instance peering (federation v1) milestone

2026-08-05 18:46:16 +00:00

Cordy referenced this issue

2026-08-06 02:29:17 +00:00

When gRPC lands: correct the dependency claims in README + ARCHITECTURE §1.4 #118

Cordy referenced this issue

2026-08-09 02:33:09 +00:00

Peering dogfood: second instance on k3s + live A↔B e2e #106

Cordy referenced this issue from a commit

2026-08-09 02:56:42 +00:00

ci: scout docs surfaces for #124

Cordy referenced this issue from a commit

2026-08-09 03:00:55 +00:00

ci: peering feature docs — README, ARCHITECTURE, handbook, example config (#124)

forgejo-actions referenced this issue from a commit

2026-08-09 03:01:38 +00:00

docs: describe instance peering from fact — README, ARCHITECTURE §10, handbook page, example config (#124)

Cordy referenced this issue from a pull request that will close it,

2026-08-09 03:02:53 +00:00

docs: instance peering described from fact (#124) #151

Cordy referenced this issue from a commit

2026-08-09 03:03:11 +00:00

Merge pull request 'docs: instance peering described from fact (#124)' (#151) from docs/peering-124 into main

Cordy closed this issue

2026-08-09 03:03:12 +00:00

Cordy commented

2026-08-09 03:03:23 +00:00

Author

Owner

Done in PR #151, written once, from fact, after #106's live A↔B transfer — exactly the discipline this issue existed to enforce. Every gap from the issue body is closed:

README Features now carries the peering entry (the last shipped capability without one): explicit-admin trust model, shown-once verifier-only keys, per-direction allow-lists, e2e age encryption on the wire, Inbox delivery, runtime switch, Test connection, notifications — and the auth.perUserHomes prerequisite stated up front, so no operator discovers it at their first failed transfer.
README configuration paragraph lists peering among the opt-in blocks.
example.config.json has a peering block (three default paths, annotated; verified still valid JSON).
ARCHITECTURE.md gained §10 Instance peering (implemented) — model, single-port transport including the #140/#143 lessons learned live, fail-closed authorization in both directions, the delivery path through the full decorator stack, and runtime operation. Milestones moved to §11, and the v0.5 milestone bullet now records the ship date and points at §10 instead of describing peering in the future tense.
docs/handbook/peering.md (new, product-neutral): prerequisites, the pairing walkthrough built around the alias-is-the-join-key rule (#145's trap, taught before it bites), allow-lists, sending/receiving UX, a troubleshooting table that maps every error the #106 dogfood actually produced to its cause, and the security properties. Handbook index updated; peering removed from the #109 backlog line.

Done in PR #151, written **once, from fact**, after #106's live A↔B transfer — exactly the discipline this issue existed to enforce. Every gap from the issue body is closed: - **README Features** now carries the peering entry (the last shipped capability without one): explicit-admin trust model, shown-once verifier-only keys, per-direction allow-lists, e2e age encryption on the wire, Inbox delivery, runtime switch, Test connection, notifications — and the `auth.perUserHomes` prerequisite stated up front, so no operator discovers it at their first failed transfer. - **README configuration paragraph** lists `peering` among the opt-in blocks. - **example.config.json** has a `peering` block (three default paths, annotated; verified still valid JSON). - **ARCHITECTURE.md** gained **§10 Instance peering (implemented)** — model, single-port transport including the #140/#143 lessons learned live, fail-closed authorization in both directions, the delivery path through the full decorator stack, and runtime operation. Milestones moved to §11, and the v0.5 milestone bullet now records the ship date and points at §10 instead of describing peering in the future tense. - **docs/handbook/peering.md** (new, product-neutral): prerequisites, the pairing walkthrough built around the alias-is-the-join-key rule (#145's trap, taught before it bites), allow-lists, sending/receiving UX, a troubleshooting table that maps every error the #106 dogfood actually produced to its cause, and the security properties. Handbook index updated; peering removed from the #109 backlog line.

Cordy referenced this issue

2026-08-09 03:17:46 +00:00

v0.6 docs: backup story, sharp-edge table, ARCHITECTURE section (write last, from fact) #158

Cordy referenced this issue

2026-08-09 03:18:12 +00:00

State-in-backend: instance state lives encrypted in the storage backend, not on local disk #138

Cordy referenced this issue

2026-08-10 00:25:44 +00:00

v0.6 docs: backup story, sharp-edge table, ARCHITECTURE section (write last, from fact) #158

Cordy referenced this issue

2026-09-17 23:36:31 +00:00

Docs run: the handbook still says a share is a link (#529 2/3, shipped v0.6.212) #585