feat(permissions): add org.hyperboards.authWrite; mark design implemented

The repo has a third first-class record namespace — org.hyperboards (board,
displayProfile, described in AGENTS.md as the "Hyperboards visual layer") — that
had no permission set, so a user's Hyperboards data was not grantable via any
published set. Add org.hyperboards.authWrite granting create/update/delete over
both org.hyperboards.* record collections, matching the other two namespaces.
Verified it enumerates exactly the type:"record" defs on disk and expands to one
combined repo: scope.

Also update the surrounding docs that the new set and the now-shipped state make
stale:

- docs/design/permission-sets.md: Status "Proposed" -> "Implemented" (the sets
  are published lexicon files in this PR, not a proposal); "two sets" -> three
  throughout, with a new org.hyperboards.authWrite subsection and the three
  distinct authorities (hypercerts.org, hyperboards.org, certified.app) spelled
  out; corrected a stray claim that hypercerts/hyperboards "share a domain".
- SKILL.md: third table row; "two sets, never one" -> "one set per namespace".
- .changeset/permission-sets-crud.md: two -> three sets.
- AGENTS.md: the add-a-lexicon permission-set step now lists all three
  namespaces.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: aspiers

.agents/skills/building-with-hypercerts-lexicons/SKILL.md

@@ -192,16 +192,17 @@ if (result.success) {
 
 ## Permission Sets (OAuth scopes)
 
-To **write** Hypercerts or Certified records to a user's repo, your app needs
-the user's authorization. AT Protocol grants this via OAuth scopes: each
-collection write needs a `repo:<collection>?action=…` scope. Rather than list
-every collection by hand, request a **permission set** — a published bundle —
-with a single `include:` scope:
-
-| Permission set NSID        | Grants write (create/update/delete) on    |
-| -------------------------- | ----------------------------------------- |
-| `org.hypercerts.authWrite` | all `org.hypercerts.*` record collections |
-| `app.certified.authWrite`  | all `app.certified.*` record collections  |
+To **write** Hypercerts, Hyperboards, or Certified records to a user's repo,
+your app needs the user's authorization. AT Protocol grants this via OAuth
+scopes: each collection write needs a `repo:<collection>?action=…` scope. Rather
+than list every collection by hand, request a **permission set** — a published
+bundle — with a single `include:` scope:
+
+| Permission set NSID         | Grants write (create/update/delete) on     |
+| --------------------------- | ------------------------------------------ |
+| `org.hypercerts.authWrite`  | all `org.hypercerts.*` record collections  |
+| `org.hyperboards.authWrite` | all `org.hyperboards.*` record collections |
+| `app.certified.authWrite`   | all `app.certified.*` record collections   |
 
 In your OAuth client's authorization request, ask for the set(s) you need:
 
@@ -213,10 +214,10 @@ The user's PDS resolves the published set and expands it into the underlying
 `repo:` scopes on the consent screen, where the user sees the set's plain-language
 description (e.g. "Manage your Hypercerts data"). Notes:
 
-- **Two sets, never one.** A permission set may only reference its own namespace
-  authority (atproto permission spec), so `org.hypercerts.*` and
-  `app.certified.*` cannot share a set. An app needing both requests **both**
-  `include:` scopes.
+- **One set per namespace, never combined.** A permission set may only reference
+  its own namespace authority (atproto permission spec), so `org.hypercerts.*`,
+  `org.hyperboards.*`, and `app.certified.*` each need their own set. An app
+  needing more than one requests **each** `include:` scope.
 - **Writes only.** These cover create/update/delete. **Reading** records needs no
   scope at all — atproto repo records are public.
 - **`repo:` scopes carry no `aud`** — request the `include:` without an `?aud=`.

.changeset/permission-sets-crud.md

@@ -2,11 +2,11 @@
 "@hypercerts-org/lexicon": minor
 ---
 
-Add two permission-set lexicons — `org.hypercerts.authWrite` and `app.certified.authWrite` — each granting create/update/delete over every record collection in its namespace.
+Add three permission-set lexicons — `org.hypercerts.authWrite`, `org.hyperboards.authWrite`, and `app.certified.authWrite` — each granting create/update/delete over every record collection in its namespace.
 
 A [permission set](https://atproto.com/specs/permission#permission-sets) lets any AT Protocol app request a whole bundle of `repo:` scopes with a single `include:<nsid>` OAuth scope, instead of enumerating each collection by hand. The user's PDS resolves and expands the set during the OAuth grant; the same published set can also be consumed by services (e.g. the Certified group service) when expanding API-key scopes.
 
-There are **two** sets rather than one because the spec requires it: a permission set "is limited to expressing permissions that reference resources under the same NSID namespace as the set itself" and "can not address 'sibling groups' or 'parents'". `org.hypercerts` and `app.certified` are separate namespace authorities, so they cannot be combined in a single set — an app needing both requests both `include:` scopes.
+There are **three** sets rather than one because the spec requires it: a permission set "is limited to expressing permissions that reference resources under the same NSID namespace as the set itself" and "can not address 'sibling groups' or 'parents'". `org.hypercerts`, `org.hyperboards`, and `app.certified` are separate namespace authorities, so they cannot be combined in a single set — an app needing more than one requests each `include:` scope.
 
 Permission sets are published as-is (they are the source of truth for what gets published to AT Protocol) but have no TypeScript shape — `lex gen-api` cannot generate code for `permission-set` defs. They are therefore excluded from the codegen globs (`gen-api`/`gen-md`/`gen-ts`) and from `generated/exports.ts`, while still shipping as raw lexicon JSON.
 

AGENTS.md

@@ -235,18 +235,21 @@ scripts/                Build and codegen scripts
    - Auto-generate `generated/exports.ts` with all exports
 
 3. Update the relevant **permission set** if appropriate:
-   - The `permission-set` lexicons (`lexicons/org/hypercerts/authWrite.json`
-     and `lexicons/app/certified/authWrite.json`) each enumerate **every
+   - The `permission-set` lexicons (`lexicons/org/hypercerts/authWrite.json`,
+     `lexicons/org/hyperboards/authWrite.json`, and
+     `lexicons/app/certified/authWrite.json`) each enumerate **every
      `type: "record"` collection in their namespace** — the list is both
      the grant and its boundary, with no wildcards allowed inside a set.
-   - When you **add** a new `org.hypercerts.*` or `app.certified.*` record
-     lexicon, add its NSID to the matching set's `permissions[].collection`
-     list, or it will not be grantable via the published set. Likewise
-     **remove** the NSID when you delete a record lexicon.
+   - When you **add** a new `org.hypercerts.*`, `org.hyperboards.*`, or
+     `app.certified.*` record lexicon, add its NSID to the matching set's
+     `permissions[].collection` list, or it will not be grantable via the
+     published set. Likewise **remove** the NSID when you delete a record
+     lexicon.
    - A set may only reference collections under **its own namespace
-     authority**, so `org.hypercerts.*` records go in
-     `org.hypercerts.authWrite` and `app.certified.*` records in
-     `app.certified.authWrite` — never the other set.
+     authority**, so each namespace's records go in its own set
+     (`org.hypercerts.*` → `org.hypercerts.authWrite`, `org.hyperboards.*` →
+     `org.hyperboards.authWrite`, `app.certified.*` →
+     `app.certified.authWrite`) — never another set.
    - This does not apply to non-record defs (e.g. `query`, `object`, or
      `permission-set` lexicons themselves), which are not repo collections.
    - See [docs/design/permission-sets.md](docs/design/permission-sets.md)

SCHEMAS.md

@@ -7,6 +7,12 @@
 
 Hypercerts-specific lexicons for tracking impact work and claims.
 
+### `org.hypercerts.authWrite`
+
+**Description:** Permission set granting create, update, and delete on every Hypercerts (org.hypercerts) record collection.
+
+---
+
 ### `org.hypercerts.claim.activity`
 
 **Description:** A hypercert record tracking impact work.
@@ -299,12 +305,6 @@ A free-text string value (e.g. a display name, wallet address, or other identifi
 
 ---
 
-### `org.hypercerts.permissions.crud`
-
-**Description:** Permission set granting create, update, and delete on every Hypercerts (org.hypercerts) record collection.
-
----
-
 ### `org.hypercerts.workscope.cel`
 
 **Description:** A structured, machine-evaluable work scope definition using CEL (Common Expression Language). Tags referenced in the expression correspond to org.hypercerts.workscope.tag keys. See https://github.com/google/cel-spec. Note: this is intentionally type 'object' (not 'record') so it can be directly embedded inline in union types (e.g., activity.workScope) without requiring a separate collection or strongRef indirection.
@@ -490,6 +490,12 @@ A labeled URL reference.
 
 ---
 
+### `app.certified.authWrite`
+
+**Description:** Permission set granting create, update, and delete on every Certified (app.certified) record collection.
+
+---
+
 ### `app.certified.graph.follow`
 
 **Description:** Record declaring a social 'follow' relationship of another account. Duplicate follows will be ignored by the AppView.
@@ -547,12 +553,6 @@ The EIP-712 typed data message that was signed by the wallet. Contains the field
 
 ---
 
-### `app.certified.permissions.crud`
-
-**Description:** Permission set granting create, update, and delete on every Certified (app.certified) record collection.
-
----
-
 ### `app.certified.signature.defs`
 
 **Description:** Common type definitions for cryptographic signatures attached to records, per the ATProtocol Attestation Specification.

docs/design/permission-sets.md

@@ -1,12 +1,16 @@
-# Design: Permission Sets for Hypercerts & Certified data
+# Design: Permission Sets for Hypercerts, Hyperboards & Certified data
 
-Status: **Proposed**
+Status: **Implemented** — the sets described here are published as lexicon
+files in this repository (`lexicons/org/hypercerts/authWrite.json`,
+`lexicons/org/hyperboards/authWrite.json`,
+`lexicons/app/certified/authWrite.json`). This document records the design and
+the rationale behind it.
 
-This document designs **permission sets** for the `org.hypercerts.*` and
-`app.certified.*` record collections defined in this repository — published,
-reusable bundles of AT Protocol OAuth scopes that any application can request
-with a single `include:<nsid>` scope, instead of enumerating every underlying
-`repo:` scope by hand.
+This document designs **permission sets** for the `org.hypercerts.*`,
+`org.hyperboards.*`, and `app.certified.*` record collections defined in this
+repository — published, reusable bundles of AT Protocol OAuth scopes that any
+application can request with a single `include:<nsid>` scope, instead of
+enumerating every underlying `repo:` scope by hand.
 
 ## Background: what a permission set is
 
@@ -35,11 +39,12 @@ set replaces that with one curated, versioned name.
 These are general AT Protocol artifacts, not specific to any one service. The
 expected consumers, in rough order of generality:
 
-1. **Any atproto app working with Hypercerts / Certified data directly.** An
-   OAuth client requests `include:org.hypercerts.authWrite` (and/or the
-   `app.certified.*` set) in its authorization request; the user's PDS expands it
-   and the app reads/writes those collections in the user's own repo. No
-   intermediary is involved. This is the broadest case.
+1. **Any atproto app working with Hypercerts / Hyperboards / Certified data
+   directly.** An OAuth client requests `include:org.hypercerts.authWrite`
+   (and/or the `org.hyperboards.*` or `app.certified.*` set) in its
+   authorization request; the user's PDS expands it and the app reads/writes
+   those collections in the user's own repo. No intermediary is involved. This
+   is the broadest case.
 2. **The Certified group service (CGS), via OAuth.** CGS is used as a standard
    OAuth resource (reached through AT Protocol service proxying). A client
    calling CGS on a user's behalf requests the same sets; the user's PDS expands
@@ -56,17 +61,18 @@ key-creation — reads the same published definition.
 
 ## The sets
 
-We define two **record-collection write** sets — one per data namespace in this
-repo. Each grants the three `repo:` write actions — create, update, delete —
+We define three **record-collection write** sets — one per data namespace in
+this repo. Each grants the three `repo:` write actions — create, update, delete —
 over all of that namespace's record collections.
 
-| Set NSID                   | Grants write (create/update/delete) on    |
-| -------------------------- | ----------------------------------------- |
-| `org.hypercerts.authWrite` | all `org.hypercerts.*` record collections |
-| `app.certified.authWrite`  | all `app.certified.*` record collections  |
+| Set NSID                    | Grants write (create/update/delete) on     |
+| --------------------------- | ------------------------------------------ |
+| `org.hypercerts.authWrite`  | all `org.hypercerts.*` record collections  |
+| `org.hyperboards.authWrite` | all `org.hyperboards.*` record collections |
+| `app.certified.authWrite`   | all `app.certified.*` record collections   |
 
-Both are authored and published from **this repository**, which is the namespace
-authority for both — see _Namespace authority_ below.
+All three are authored and published from **this repository**, which is the
+namespace authority for all of them — see _Namespace authority_ below.
 
 > **Write only — no read action.** The leaf is `authWrite` because a `repo:`
 > permission has only three actions — `create`, `update`, `delete` (there is no
@@ -134,6 +140,36 @@ Enumerates every `type: "record"` collection under `org.hypercerts.*`:
 }
 ```
 
+### `org.hyperboards.authWrite`
+
+Enumerates every `type: "record"` collection under `org.hyperboards.*`:
+
+```jsonc
+{
+  "lexicon": 1,
+  "id": "org.hyperboards.authWrite",
+  "defs": {
+    "main": {
+      "type": "permission-set",
+      "description": "Permission set granting create, update, and delete on every Hyperboards (org.hyperboards) record collection.",
+      "title": "Manage your Hyperboards data",
+      "detail": "Create, edit, and delete your Hyperboards records (board configurations and display profiles).",
+      "permissions": [
+        {
+          "type": "permission",
+          "resource": "repo",
+          "collection": [
+            "org.hyperboards.board",
+            "org.hyperboards.displayProfile",
+          ],
+          "action": ["create", "update", "delete"],
+        },
+      ],
+    },
+  },
+}
+```
+
 ### `app.certified.authWrite`
 
 Enumerates every `type: "record"` collection under `app.certified.*`:
@@ -170,9 +206,10 @@ Enumerates every `type: "record"` collection under `app.certified.*`:
 }
 ```
 
-> The collection lists are derived from this repo's `lexicons/org/hypercerts/`
-> and `lexicons/app/certified/` (`type: "record"` defs at time of writing). They
-> must be **kept in sync** as record types are added — see _Maintenance_.
+> The collection lists are derived from this repo's `lexicons/org/hypercerts/`,
+> `lexicons/org/hyperboards/`, and `lexicons/app/certified/` (`type: "record"`
+> defs at time of writing). They must be **kept in sync** as record types are
+> added — see _Maintenance_.
 
 ## Design rules these sets follow
 
@@ -188,12 +225,14 @@ and `rpc:` permissions (by lxm NSID).
 Consequences here:
 
 - A set under `org.hypercerts.*` may grant `repo:org.hypercerts.*` collections,
-  and **only** those — it cannot reference `app.certified.*` collections, or any
-  third party's, or any service's `rpc:` methods. Likewise the `app.certified.*`
-  set is confined to `app.certified.*`.
-- This is why there are **two** sets rather than one combined set: the two
-  namespaces are distinct authorities and cannot legally be mixed in a single
-  set. An app that needs both requests both `include:` scopes.
+  and **only** those — it cannot reference `org.hyperboards.*` or
+  `app.certified.*` collections, or any third party's, or any service's `rpc:`
+  methods. Likewise each of the `org.hyperboards.*` and `app.certified.*` sets
+  is confined to its own namespace.
+- This is why there are **three** sets rather than one combined set: the three
+  namespaces have distinct authorities (`hypercerts.org`, `hyperboards.org`,
+  `certified.app`) and cannot legally be mixed in a single set. An app that
+  needs more than one requests each `include:` scope.
 - The authority confinement is also what makes a published set **safe for any
   client to resolve**: an `include:` can only ever widen access to the set's own
   namespace, never smuggle in foreign permissions.
@@ -211,9 +250,10 @@ not what these sets are for.)
 
 ### `repo:` permissions carry no `aud`
 
-A `repo:` scope targets the **user's own repo**, so it has no audience. Both sets
-here are `repo:`-only, so an `include:` for them is requested **without** any
-`?aud=` parameter. Each set expands to a **single combined `repo:` scope** that
+A `repo:` scope targets the **user's own repo**, so it has no audience. All
+three sets here are `repo:`-only, so an `include:` for them is requested
+**without** any `?aud=` parameter. Each set expands to a **single combined
+`repo:` scope** that
 lists every collection — `IncludeScope.toScopes` coalesces the permission's
 collection array into one scope string
 (`repo:?collection=<a>&collection=<b>&…&action=create&action=update&action=delete`),
@@ -227,7 +267,7 @@ would.)
 
 ## Publication and resolution
 
-Both sets are published like any other Lexicon schema in this repo (see
+All three sets are published like any other Lexicon schema in this repo (see
 [`PUBLISHING.md`](../PUBLISHING.md)) and resolved at runtime via the standard
 **Lexicon resolution system**, to which the permission spec defers:
 _"Permission sets are Lexicon schemas and are published and fetched using the
@@ -269,16 +309,17 @@ full detail lives in the CGS design doc
 
 The point for _this_ repo: the sets must be **self-contained and
 deployment-agnostic** — no CGS-specific assumptions baked into the definitions.
-The two CRUD sets satisfy this trivially (pure `repo:` collection grants).
+All three CRUD sets satisfy this trivially (pure `repo:` collection grants).
 
 ## Maintenance
 
 The enumerated `collection` lists are the one ongoing obligation. Whenever a
-`type: "record"` lexicon is added to or removed from `org.hypercerts.*` or
-`app.certified.*`, the corresponding set must be updated and re-published, or the
-new collection will be silently uncovered by the set. Worth a check in the
-release process (and ideally an automated test asserting each set lists exactly
-the `type: "record"` defs in its namespace).
+`type: "record"` lexicon is added to or removed from `org.hypercerts.*`,
+`org.hyperboards.*`, or `app.certified.*`, the corresponding set must be updated
+and re-published, or the new collection will be silently uncovered by the set.
+The `AGENTS.md` "Adding / modifying a lexicon" checklist calls this out. Worth a
+check in the release process too (and ideally an automated test asserting each
+set lists exactly the `type: "record"` defs in its namespace).
 
 > **Known pending update.** PR
 > [#219](https://github.com/hypercerts-org/hypercerts-lexicon/pull/219)

lexicons/org/hyperboards/authWrite.json

@@ -0,0 +1,23 @@
+{
+  "lexicon": 1,
+  "id": "org.hyperboards.authWrite",
+  "defs": {
+    "main": {
+      "type": "permission-set",
+      "description": "Permission set granting create, update, and delete on every Hyperboards (org.hyperboards) record collection.",
+      "title": "Manage your Hyperboards data",
+      "detail": "Create, edit, and delete your Hyperboards records (board configurations and display profiles).",
+      "permissions": [
+        {
+          "type": "permission",
+          "resource": "repo",
+          "collection": [
+            "org.hyperboards.board",
+            "org.hyperboards.displayProfile"
+          ],
+          "action": ["create", "update", "delete"]
+        }
+      ]
+    }
+  }
+}