docs(website): record the shard visibility framework #64

wtclaude · 2026-07-28T15:06:05Z

wtclaude commented

2026-07-28 15:06:05 +00:00

What & why

Documentation for Protocol 3.0 Part A (the visibility framework), landing alongside website#109. Companion to the design in link/v3.md (#63).

Two documents, two audiences:

website/SHARD_VISIBILITY.md (new) — the admin-facing guide. The audience ladder in plain terms, what each of the ten shard features exposes, every default and why it is that default, the two rules that are code rather than configuration, and four worked examples ("I want a private shard", "publish the market but don't tie vendors to players", …).
website/BACKEND_DESIGN.md §6.5 (new) — the same thing as a security contract: the ladder and how viewerLevel resolves it, the locked acct/webId rule, the fail-closed kind map, the asymmetric ladder fallbacks and why a single shared fallback can't work, and the three enforcement points. Plus the shard_feature_visibility schema entry, the /public/shard/features route row, and the adminOnly tier on /admin/shard/visibility.

Notes worth flagging for review:

Defaults reproduce pre-3.0 behavior everywhere, with one deliberate exception — documented as such in both files: /public/shard/guilds and /public/shard/governors previously returned the raw stored payload, whose leader/governor actors carry acct and webId, to anonymous callers. That is the leak Part A closes.
SHARD_VISIBILITY.md §6 is honest about the fact that loosening House owner is a real disclosure — house ownership is visible in game, but the website makes it searchable in a way the game doesn't. That asymmetry is the thing an admin should weigh, so it says so rather than presenting the toggle as neutral.

Docs-only. Targets edge, not main.

How it was tested

N/A — documentation. Every route, table, field name and default cited was taken from the implementation in website#109 rather than from the plan, and the public-shard route count in §2 was corrected 12 → 13 for the added /features endpoint.

Checklist

I have read CONTRIBUTING.md.
The change builds and existing tests/checks pass locally.
I have added or updated tests/docs where it makes sense.
My commits are reasonably scoped with clear messages.

AI-assisted contributions (required)

AI tools were used. Tool(s): Claude Code (Opus 5). I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a Co-Authored-By trailer.

License

I agree that my contribution is licensed under this project's license (GNU GPL v3.0 or later), and I have the right to contribute it.

## What & why Documentation for Protocol 3.0 **Part A** (the visibility framework), landing alongside website#109. Companion to the design in `link/v3.md` (#63). Two documents, two audiences: - **`website/SHARD_VISIBILITY.md` (new)** — the admin-facing guide. The audience ladder in plain terms, what each of the ten shard features exposes, every default and *why* it is that default, the two rules that are code rather than configuration, and four worked examples ("I want a private shard", "publish the market but don't tie vendors to players", …). - **`website/BACKEND_DESIGN.md` §6.5 (new)** — the same thing as a security contract: the ladder and how `viewerLevel` resolves it, the locked `acct`/`webId` rule, the fail-closed kind map, the asymmetric ladder fallbacks and why a single shared fallback can't work, and the three enforcement points. Plus the `shard_feature_visibility` schema entry, the `/public/shard/features` route row, and the `adminOnly` tier on `/admin/shard/visibility`. Notes worth flagging for review: - Defaults reproduce pre-3.0 behavior everywhere, **with one deliberate exception** — documented as such in both files: `/public/shard/guilds` and `/public/shard/governors` previously returned the raw stored payload, whose `leader`/`governor` actors carry `acct` and `webId`, to anonymous callers. That is the leak Part A closes. - `SHARD_VISIBILITY.md` §6 is honest about the fact that loosening **House owner** is a real disclosure — house ownership is visible in game, but the website makes it *searchable* in a way the game doesn't. That asymmetry is the thing an admin should weigh, so it says so rather than presenting the toggle as neutral. Docs-only. Targets `edge`, not `main`. ## How it was tested N/A — documentation. Every route, table, field name and default cited was taken from the implementation in website#109 rather than from the plan, and the public-shard route count in §2 was corrected 12 → 13 for the added `/features` endpoint. ## Checklist - [x] I have read [CONTRIBUTING.md](CONTRIBUTING.md). - [x] The change builds and existing tests/checks pass locally.  - [x] I have added or updated tests/docs where it makes sense. - [x] My commits are reasonably scoped with clear messages. ## AI-assisted contributions (required) - [x] AI tools were used. Tool(s): `Claude Code (Opus 5)`. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a `Co-Authored-By` trailer. ## License - [x] I agree that my contribution is licensed under this project's license (**GNU GPL v3.0 or later**), and I have the right to contribute it.

wtclaude added 1 commit 2026-07-28 15:06:06 +00:00

docs(website): record the shard visibility framework bf41105ec0

Protocol 3.0 Part A. Admin-configurable, per-feature and per-field
audience control over every shard-derived surface, replacing the static
PUBLIC_KINDS allowlist that used to be the whole boundary.

- SHARD_VISIBILITY.md (new): the admin-facing guide - the ladder, what
  each of the ten features exposes, the defaults, the two rules that are
  code rather than configuration, and worked examples.
- BACKEND_DESIGN.md 6.5 (new): the same thing as a security contract -
  the ladder and how viewerLevel resolves it, the locked acct/webId rule,
  the fail-closed kind map, the asymmetric ladder fallbacks, and the
  three enforcement points. Plus the shard_feature_visibility schema, the
  /public/shard/features route, and the adminOnly tier on
  /admin/shard/visibility.

Defaults reproduce pre-3.0 behavior everywhere, with one deliberate
exception which is the leak Part A was written to close: guilds and
governors previously returned the raw stored payload, whose leader and
governor actors carry acct and webId, to anonymous callers.

Co-Authored-By: Claude <noreply@anthropic.com>

whitlocktech added 1 commit 2026-07-28 15:06:44 +00:00

Merge branch 'edge' into docs/shard-visibility 8b4fc439ee

whitlocktech merged commit 5cb77595aa into edge

2026-07-28 15:06:59 +00:00

whitlocktech referenced this issue from a commit

2026-07-28 15:06:59 +00:00

Merge pull request 'docs(website): record the shard visibility framework' (#64) from docs/shard-visibility into edge

whitlocktech deleted branch docs/shard-visibility

2026-07-28 15:06:59 +00:00

Sign in to join this conversation.