@hypercerts-org/lexicon 0.10.0-beta.9 → 0.11.0

package/README.md

@@ -1,39 +1,180 @@
-# Hypercerts Lexicon Documentation
-
-This repository contains ATProto lexicon definitions for the
-Hypercerts protocol. Each lexicon defines a record type that can be
-stored on the ATProto network.
-
-## Entity Relationship Diagram
+# @hypercerts-org/lexicon
+
+ATProto lexicon definitions and TypeScript types for the
+[Hypercerts](https://hypercerts.org) protocol — a system for tracking,
+evaluating, and funding impact work on the
+[AT Protocol](https://atproto.com) network.
+
+## Lexicon Map
+
+```text
+CLAIMS ─ the core impact record and its parts
+──────────────────────────────────────────────────────────────────────
+  activity ──────────┬──► collection ◄──┐  (recursive nesting)
+  (the hypercert)    │       │          │
+                     │       ▼          │
+                     ├──► contribution          (role, timeframe)
+                     ├──► contributorInformation (identity, avatar)
+                     ├──► rights                (licensing terms)
+                     └──► workScope
+                            ├── cel             (CEL expression)
+                            └── tag             (reusable scope atom)
+
+CONTEXT ─ evidence, data, and social verification
+──────────────────────────────────────────────────────────────────────
+  attachment ─────────────► activity / evaluation / ...
+  measurement ────────────► activity / ...
+  evaluation ─────────────► activity / attachment
+                  └──────► measurement
+  acknowledgement ────────► activity / collection  (bidirectional link)
+
+FUNDING ─ payment records
+──────────────────────────────────────────────────────────────────────
+  receipt ────────────────► activity    (from funder → to recipient)
+
+HYPERBOARDS ─ visual display layer (hyperboards.org)
+──────────────────────────────────────────────────────────────────────
+  board ──────────────────► activity / collection
+    └── contributorConfig ► contributorInformation
+  displayProfile            (per-user visual defaults)
+
+CERTIFIED ─ shared lexicons (certified.app)
+──────────────────────────────────────────────────────────────────────
+  location                  (geo coordinates, GeoJSON, H3, …)
+  actor/profile             (user profile)
+  actor/organization        (org metadata)
+  badge/definition ──► badge/award ──► badge/response
+```
 
-The following diagrams show the relationship between:
+Every arrow (`►`) is a `strongRef` or union reference stored on the
+AT Protocol network. Full field-level documentation is in
+[SCHEMAS.md](SCHEMAS.md).
 
-- data classes represented by ATProto lexicons, which model the data
-  sets relating to hypercerts
+## Consuming These Lexicons
 
-- contributors to activity records (modelled/identified by ATProto
-  DIDs rather than lexicons)
+If you are building a downstream application on top of these lexicons,
+we strongly recommend **NOT** reading from `main` or other development
+branches of the repository, but instead via the following published
+releases:
 
-- hypercerts protocol tokens which are onchain representations of
-  activity records in ATProto
+- **For TypeScript / JavaScript code** — use [the npm package
+  `@hypercerts-org/lexicon`](https://www.npmjs.com/package/@hypercerts-org/lexicon),
+  which includes generated types, validation helpers, and schema
+  constants.
+- **For other languages** — use the [tagged
+  releases](https://github.com/hypercerts-org/hypercerts-lexicon/releases)
+  published in this GitHub repository.
 
-Note that contributors and tokens do not require lexicons.
+Both npm releases and git tags follow [SemVer](https://semver.org/).
+For npm, you can depend on a version range to receive compatible
+updates automatically. For GitHub releases/tags, pin a specific tag
+or upgrade manually to a newer compatible SemVer release.
 
-To distinguish these in the diagrams, each class has one of the
-following icons:
+The raw lexicons published on ATProto can also be used, but they are
+(unavoidably) missing useful context such as full documentation
+(including changelogs), TypeScript type definitions, SemVer
+guarantees, git history, and other tooling provided by the packaged
+releases.
 
-- "D" means "data class"
-- "E" means "entity"
-- "P" means "protocol"
+### AI Agent Skill
 
-![Hypercert ERD](ERD.svg)
+If you use AI coding assistants (e.g. Claude Code, OpenCode), you can
+install a skill that teaches your agent how to build with these
+lexicons:
 
-<details>
-<summary>View ERD with field details</summary>
+```bash
+npx skills add hypercerts-org/hypercerts-lexicon
+```
 
-![Hypercert ERD with fields](ERD-with-fields.svg)
+This installs the
+[`building-with-hypercerts-lexicons`](.agents/skills/building-with-hypercerts-lexicons/SKILL.md)
+skill, which provides your agent with guidance on package entry points,
+TypeScript types, validation, all lexicon schemas, code examples, and
+AT Protocol conventions.
+
+## Maintenance and publishing releases
+
+Clearly stability and predictability for users and developers are
+essential.
+
+Unfortunately AT Protocol doesn't support any kind of native
+versioning or migrations which could support lexicon schema changes.
+Instead, the AT Protocol community recommends minimising changes to
+lexicons in general, and to avoid breaking changes wherever possible:
+
+- https://atproto.com/guides/lexicon-style-guide
+- https://www.pfrazee.com/blog/lexicon-guidance
+
+This project intends to follow that guidance as much as possible
+whilst retaining a pragmatic approach. In practice that means:
+
+- Changes to other tooling within this repository which _do not touch
+  lexicons_ may be made at any time as long as they follow
+  [SemVer](https://semver.org/) to avoid negative impact on
+  developers.
+
+- Non-breaking changes to lexicons, such as adding an optional
+  property or updating a `description`, may be made sparingly. While
+  these changes are backwards-compatible at the protocol level, they
+  may still require consuming applications and indexers to update
+  their schemas for consistent UX.
+
+- Breaking changes to lexicons will only be made in exceptional
+  circumstances. Specifically, a breaking change will only proceed
+  **if and only if**:
+  - the broader community — not just the Hypercerts core team —
+    agrees that the benefits clearly outweigh the cost of the
+    breakage, **and**
+  - full consideration is given to all affected parties across the
+    community and wider ecosystem, not only those involved in the
+    decision, **and**
+  - no viable alternative exists, such as releasing a new `.v2`
+    version of the lexicon or introducing a `v2` field.
+
+  To date, breaking changes have only occurred during the early
+  stages of launching Hypercerts on AT Protocol, before external
+  consumers were building against the lexicons. We intend to keep
+  it that way.
+
+It is also worth noting that members of the ATProto community have
+been working on tooling to make these problems easier to deal with in
+future, e.g. see https://panproto.dev/
+
+## Use of branches
+
+`main` is the only evergreen branch and the default branch on GitHub.
+We aim to minimise deviations between `main` and versions published on
+npm and ATProto. However the publishing processes involve several
+moving parts (including third-party systems), and it is technically
+impossible to update all three at the same time. So **please do not
+assume they will always be perfectly in sync**.
+
+See [docs/PUBLISHING.md](docs/PUBLISHING.md) for the full release workflow.
+
+> If you see a `develop` branch, it is a stale leftover from a
+> previous workflow and is no longer used; do not open pull requests
+> against it.
+
+## Contributing / development
+
+Please see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+### Project Structure
+
+```text
+lexicons/               Source of truth (committed)
+  org/hypercerts/         Hypercerts protocol lexicons
+  org/hyperboards/        Hyperboards visual layer lexicons
+  app/certified/          Shared/certified lexicons
+  com/atproto/            ATProto external references
+
+generated/              Auto-generated TypeScript (gitignored)
+dist/                   Built bundles (gitignored)
+scripts/                Build and codegen scripts
+```
 
-</details>
+> **Never edit `generated/` or `dist/` directly** — they are
+> regenerated from lexicon JSON files.
 
 ## Installation
 
@@ -41,9 +182,7 @@ following icons:
 npm install @hypercerts-org/lexicon
 ```
 
-## Usage
-
-### Basic Import
+## Quick Start
 
 ```typescript
 import {
@@ -51,8 +190,6 @@ import {
   ACTIVITY_NSID,
   validate,
 } from "@hypercerts-org/lexicon";
-
-// Use with AT Protocol Agent
 import { Agent } from "@atproto/api";
 
 const agent = new Agent({ service: "https://bsky.social" });
@@ -60,116 +197,152 @@ const agent = new Agent({ service: "https://bsky.social" });
 // Register lexicons with the agent
 agent.api.lex.add(...HYPERCERTS_SCHEMAS);
 
-// Create a record
-const activityRecord = {
+// Build a record
+const record = {
   $type: ACTIVITY_NSID,
-  title: "My Impact Work",
-  shortDescription: "Description here",
-  workScope: {
-    uri: "at://did:plc:alice/org.hypercerts.claim.workscope/abc123",
-    cid: "...",
-  },
-  startDate: "2023-01-01T00:00:00Z",
-  endDate: "2023-12-31T23:59:59Z",
+  title: "Reforestation in Amazon Basin 2024",
+  shortDescription: "Planted 5,000 native trees across 12 hectares",
   createdAt: new Date().toISOString(),
 };
 
-// Validate before creating
-const validation = validate(ACTIVITY_NSID, activityRecord);
-if (!validation.valid) {
-  console.error("Validation failed:", validation.errors);
-}
+// Validate before writing
+const result = validate(ACTIVITY_NSID, record);
+if (!result.valid) throw new Error(JSON.stringify(result.errors));
 
+// Write to the network
 await agent.api.com.atproto.repo.createRecord({
   repo: agent.session?.did,
   collection: ACTIVITY_NSID,
-  record: activityRecord,
+  record,
 });
 ```
 
-### Accessing NSIDs (Lexicon IDs)
+## Lexicon Reference
+
+### Claims (`org.hypercerts.claim.*`)
+
+| Lexicon                     | NSID                                          | Description                                                                                                                            |
+| --------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| **Activity**                | `org.hypercerts.claim.activity`               | The main hypercert record — describes impact work with title, description, contributors, work scope, timeframe, locations, and rights. |
+| **Contribution**            | `org.hypercerts.claim.contribution`           | Details about a specific contribution: role, description, and timeframe.                                                               |
+| **Contributor Information** | `org.hypercerts.claim.contributorInformation` | Identity record for a contributor: identifier (DID or URI), display name, and avatar.                                                  |
+| **Rights**                  | `org.hypercerts.claim.rights`                 | Licensing and rights terms (e.g. "CC BY-SA 4.0") attached to an activity.                                                              |
+
+### Collections (`org.hypercerts.*`)
+
+| Lexicon        | NSID                        | Description                                                                                                                                                 |
+| -------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Collection** | `org.hypercerts.collection` | A named, weighted group of activities and/or other collections. Supports recursive nesting. Used for projects, portfolios, favourites, funding rounds, etc. |
+
+### Context (`org.hypercerts.context.*`)
+
+| Lexicon             | NSID                                     | Description                                                                             |
+| ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------- |
+| **Attachment**      | `org.hypercerts.context.attachment`      | Documents, reports, evidence, or other files linked to a record.                        |
+| **Measurement**     | `org.hypercerts.context.measurement`     | Quantitative data point (metric + unit + value) linked to one or more records.          |
+| **Evaluation**      | `org.hypercerts.context.evaluation`      | An assessment of a record with evaluators, summary, score, and supporting measurements. |
+| **Acknowledgement** | `org.hypercerts.context.acknowledgement` | Bidirectional link: confirms or rejects inclusion of a record in another context.       |
+
+### Work Scope (`org.hypercerts.workscope.*`)
+
+| Lexicon            | NSID                           | Description                                                                                                                       |
+| ------------------ | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| **Tag**            | `org.hypercerts.workscope.tag` | Reusable scope atom (topic, domain, method, …) with taxonomy support, aliases, and linked ontologies.                             |
+| **CEL Expression** | `org.hypercerts.workscope.cel` | Structured work scope using [CEL](https://github.com/google/cel-spec) expressions over tags. Embedded inline in activity records. |
+
+### Funding (`org.hypercerts.funding.*`)
+
+| Lexicon     | NSID                             | Description                                                                                                                                                       |
+| ----------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Receipt** | `org.hypercerts.funding.receipt` | Records a payment to a recipient, with amount, currency, payment rail, and optional transaction ID. The sender (`from`) is optional to support anonymous funders. |
 
-**Recommended**: Use individual NSID constants for cleaner, more readable code:
+### Hyperboards (`org.hyperboards.*`)
+
+| Lexicon             | NSID                             | Description                                                                                                                         |
+| ------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| **Board**           | `org.hyperboards.board`          | Visual presentation layer wrapping an activity or collection with background, colors, aspect ratio, and per-contributor styling.    |
+| **Display Profile** | `org.hyperboards.displayProfile` | Per-user visual defaults (avatar, hover image, video, click-through URL) reusable across boards. Singleton record (`literal:self`). |
+
+### Certified (`app.certified.*`)
+
+| Lexicon              | NSID                               | Description                                                                                                                     |
+| -------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| **Location**         | `app.certified.location`           | Geographic reference using the [Location Protocol](https://spec.decentralizedgeo.org) (coordinates, GeoJSON, H3, WKT, etc.).    |
+| **Profile**          | `app.certified.actor.profile`      | User account profile with display name, bio, avatar, and banner.                                                                |
+| **Organization**     | `app.certified.actor.organization` | Organization metadata: legal structure, URLs, location, founding date.                                                          |
+| **Badge Definition** | `app.certified.badge.definition`   | Defines a badge type with title, icon, and optional issuer allowlist.                                                           |
+| **Badge Award**      | `app.certified.badge.award`        | Awards a badge to a user, project, or activity.                                                                                 |
+| **Badge Response**   | `app.certified.badge.response`     | Recipient accepts or rejects a badge award.                                                                                     |
+| **EVM Link**         | `app.certified.link.evm`           | Verifiable ATProto DID ↔ EVM wallet link via EIP-712 signature. Extensible for future proof methods (e.g. ERC-1271, ERC-6492). |
+
+> **Full property tables** → [SCHEMAS.md](SCHEMAS.md)
+
+## Entity Relationship Diagram
+
+![Hypercert ERD](ERD.svg)
+
+<details>
+<summary>View ERD with field details</summary>
+
+![Hypercert ERD with fields](ERD-with-fields.svg)
+
+</details>
+
+## Usage
+
+### Accessing NSIDs
+
+Individual constants (recommended):
 
 ```typescript
 import { ACTIVITY_NSID, COLLECTION_NSID } from "@hypercerts-org/lexicon";
-
-// Clean and explicit
-const record = {
-  $type: ACTIVITY_NSID,
-  // ...
-};
 ```
 
-**Alternative**: Use the semantic NSID object when you need multiple NSIDs:
+Semantic object:
 
 ```typescript
 import { HYPERCERTS_NSIDS } from "@hypercerts-org/lexicon";
 
-// Access via semantic keys
-const activityId = HYPERCERTS_NSIDS.ACTIVITY;
-const collectionId = HYPERCERTS_NSIDS.COLLECTION;
-const rightsId = HYPERCERTS_NSIDS.RIGHTS;
+const id = HYPERCERTS_NSIDS.ACTIVITY;
 ```
 
-**Type-based mapping**: If you need to map TypeScript type namespaces to NSIDs:
+Type-based mapping:
 
 ```typescript
 import { HYPERCERTS_NSIDS_BY_TYPE } from "@hypercerts-org/lexicon";
 
-// Access via type namespace names
-const activityId = HYPERCERTS_NSIDS_BY_TYPE.OrgHypercertsClaimActivity;
-const collectionId = HYPERCERTS_NSIDS_BY_TYPE.OrgHypercertsClaimCollection;
+const id = HYPERCERTS_NSIDS_BY_TYPE.OrgHypercertsClaimActivity;
 ```
 
-**Lightweight Bundle**: Import from `/lexicons` for runtime validation without TypeScript types (smaller bundle size):
+Lightweight bundle (no TypeScript types, smaller bundle):
 
 ```typescript
 import { schemas, validate, ids } from "@hypercerts-org/lexicon/lexicons";
-
-// Lighter bundle, type-based namespace access
-const result = validate(ids.OrgHypercertsClaimActivity, record);
 ```
 
-**Note**: Individual constants (e.g., `ACTIVITY_NSID`) are the recommended approach for most use cases as they provide the best developer experience with clear, concise naming.
-
 ### TypeScript Types
 
-All lexicon types are exported as namespaces:
-
 ```typescript
 import { OrgHypercertsClaimActivity } from "@hypercerts-org/lexicon";
 
-// Use the Main type
 const activity: OrgHypercertsClaimActivity.Main = {
   $type: "org.hypercerts.claim.activity",
   title: "My Impact Work",
-  // ... other fields
+  shortDescription: "...",
+  createdAt: new Date().toISOString(),
 };
 ```
 
-### Individual Lexicon Imports
-
-Each lexicon is available in two forms as individual constants:
+### Lexicon Documents
 
 ```typescript
 import {
-  // Raw JSON (untyped) - direct import from JSON files
-  ACTIVITY_LEXICON_JSON,
-  RIGHTS_LEXICON_JSON,
-
-  // Typed LexiconDoc - from lexicons.get() at module initialization
-  ACTIVITY_LEXICON_DOC,
-  RIGHTS_LEXICON_DOC,
+  ACTIVITY_LEXICON_JSON, // raw JSON (untyped)
+  ACTIVITY_LEXICON_DOC, // LexiconDoc (typed)
 } from "@hypercerts-org/lexicon";
 ```
 
-| Suffix  | Type                 | Source                    | Use Case                       |
-| ------- | -------------------- | ------------------------- | ------------------------------ |
-| `_JSON` | Untyped JSON         | Direct JSON import        | Raw schema data                |
-| `_DOC`  | `LexiconDoc` (typed) | `lexicons.get()` instance | Type-safe lexicon manipulation |
-
-Or access all lexicons via semantic mapping objects:
+Or via semantic mapping objects:
 
 ```typescript
 import {
@@ -177,126 +350,205 @@ import {
   HYPERCERTS_LEXICON_DOC,
 } from "@hypercerts-org/lexicon";
 
-// Access via semantic keys (same keys as HYPERCERTS_NSIDS)
-const activityJSON = HYPERCERTS_LEXICON_JSON.ACTIVITY;
-const activityDoc = HYPERCERTS_LEXICON_DOC.ACTIVITY;
-const rightsJSON = HYPERCERTS_LEXICON_JSON.RIGHTS;
-const rightsDoc = HYPERCERTS_LEXICON_DOC.RIGHTS;
+const doc = HYPERCERTS_LEXICON_DOC.ACTIVITY;
 ```
 
-## Schema Documentation
+## Examples
 
-For complete schema documentation with all lexicon definitions and
-property tables, see [SCHEMAS.md](SCHEMAS.md).
+### Creating Activities with Work Scope
 
-## Examples
+```typescript
+import { ACTIVITY_NSID } from "@hypercerts-org/lexicon";
 
-### Creating a Collection with Nested Items
+const activity = {
+  $type: ACTIVITY_NSID,
+  title: "Mangrove Restoration in Mombasa",
+  shortDescription: "Restored 3 hectares of mangrove forest",
+  // Structured work scope via CEL expression:
+  workScope: {
+    $type: "org.hypercerts.workscope.cel",
+    expression:
+      "scope.hasAll(['mangrove_restoration']) && location.country == 'KE'",
+    usedTags: [
+      {
+        uri: "at://did:plc:alice/org.hypercerts.workscope.tag/3k2abc",
+        cid: "...",
+      },
+    ],
+    version: "v1",
+    createdAt: new Date().toISOString(),
+  },
+  startDate: "2024-01-01T00:00:00Z",
+  endDate: "2024-12-31T23:59:59Z",
+  createdAt: new Date().toISOString(),
+};
+```
+
+### Creating Collections (Projects, Portfolios, etc.)
 
 ```typescript
-import { TID } from "@atproto/common";
+import { COLLECTION_NSID } from "@hypercerts-org/lexicon";
 
-const collectionRecord = {
-  $type: "org.hypercerts.claim.collection",
-  title: "Climate Action Projects",
-  shortDescription:
-    "A collection of climate-related activities and sub-collections",
+const project = {
+  $type: COLLECTION_NSID,
+  type: "project",
+  title: "Carbon Offset Initiative",
+  shortDescription: "Activities focused on carbon reduction and reforestation",
   items: [
-    // Reference to an activity
     {
-      uri: "at://did:plc:alice/org.hypercerts.claim.activity/3k2abc",
-      cid: "...",
+      itemIdentifier: {
+        uri: "at://did:plc:alice/org.hypercerts.claim.activity/3k2abc",
+        cid: "...",
+      },
     },
-    // Reference to another activity
     {
-      uri: "at://did:plc:bob/org.hypercerts.claim.activity/7x9def",
-      cid: "...",
+      itemIdentifier: {
+        uri: "at://did:plc:bob/org.hypercerts.claim.activity/7x9def",
+        cid: "...",
+      },
     },
-    // Reference to another collection (recursive!)
+    // Collections can contain other collections (recursive nesting):
     {
-      uri: "at://did:plc:carol/org.hypercerts.claim.collection/4m5ghi",
-      cid: "...",
+      itemIdentifier: {
+        uri: "at://did:plc:carol/org.hypercerts.collection/4m5ghi",
+        cid: "...",
+      },
     },
   ],
   createdAt: new Date().toISOString(),
 };
 ```
 
-### Creating a Project
+### Creating Location Records
+
+```typescript
+import { LOCATION_NSID } from "@hypercerts-org/lexicon";
+
+// Decimal coordinates
+const location = {
+  $type: LOCATION_NSID,
+  lpVersion: "1.0",
+  srs: "http://www.opengis.net/def/crs/OGC/1.3/CRS84",
+  locationType: "coordinate-decimal",
+  location: { string: "-3.4653, -62.2159" },
+  name: "Amazon Research Station",
+  createdAt: new Date().toISOString(),
+};
+
+// GeoJSON
+const geoLocation = {
+  $type: LOCATION_NSID,
+  lpVersion: "1.0",
+  srs: "http://www.opengis.net/def/crs/OGC/1.3/CRS84",
+  locationType: "geojson-point",
+  location: { string: '{"type":"Point","coordinates":[-62.2159,-3.4653]}' },
+  name: "Research Station Alpha",
+  createdAt: new Date().toISOString(),
+};
+```
+
+### Acknowledging Inclusion
 
-Projects are collections with a `type` field set to "project" and can
-include rich-text descriptions:
+When one user includes another's record (e.g. adding an activity to a
+collection), the owner can confirm or reject with an acknowledgement:
 
 ```typescript
-const projectRecord = {
-  $type: "org.hypercerts.claim.collection",
-  type: "project",
-  title: "Carbon Offset Initiative",
-  shortDescription: "A project focused on carbon reduction and reforestation",
-  description: {
-    uri: "at://did:plc:alice/pub.leaflet.pages.linearDocument/abc123",
-    cid: "...",
+import { ACKNOWLEDGEMENT_NSID } from "@hypercerts-org/lexicon";
+
+const ack = {
+  $type: ACKNOWLEDGEMENT_NSID,
+  subject: {
+    uri: "at://did:plc:bob/org.hypercerts.claim.activity/3k2abc",
+    cid: "bafy...",
   },
-  items: [
-    {
-      uri: "at://did:plc:alice/org.hypercerts.claim.activity/3k2abc",
-      cid: "...",
-    },
+  context: {
+    uri: "at://did:plc:alice/org.hypercerts.collection/7x9def",
+    cid: "bafy...",
+  },
+  acknowledged: true, // false to reject
+  createdAt: new Date().toISOString(),
+};
+```
+
+### Creating Attachments
+
+```typescript
+import { ATTACHMENT_NSID } from "@hypercerts-org/lexicon";
+
+const attachment = {
+  $type: ATTACHMENT_NSID,
+  title: "Field Survey Report",
+  contentType: "report",
+  subjects: [
     {
-      uri: "at://did:plc:bob/org.hypercerts.claim.activity/7x9def",
+      uri: "at://did:plc:alice/org.hypercerts.claim.activity/abc123",
       cid: "...",
     },
   ],
+  content: [
+    { uri: "https://example.com/reports/survey-2024.pdf" },
+    { uri: "ipfs://Qm..." },
+  ],
+  shortDescription: "Quarterly field survey documenting project progress",
   createdAt: new Date().toISOString(),
 };
 ```
 
-**Note**: The `type` field is optional and can be set to "project",
-"favorites", or any other collection type. The `description` field
-supports rich-text via Leaflet linear documents.
+## Development
 
-### Adding Visual Representation to Collections
+### Commands
 
-Collections can include `avatar` and `banner` fields for visual representation:
+```bash
+npm run gen-api       # Regenerate TypeScript types from lexicons
+npm run build         # Build distributable bundles (ESM, CJS, types)
+npm run check         # Validate + typecheck + build (run before committing)
+npm run lint          # Check formatting (Prettier + ESLint)
+npm run format        # Auto-fix formatting
+npm run gen-schemas-md # Regenerate SCHEMAS.md
+npm run test          # Run tests
+```
 
-```typescript
-import { COLLECTION_NSID } from "@hypercerts-org/lexicon";
+### Linking ATProto Identity to EVM Wallets
 
-const collectionRecord = {
-  $type: COLLECTION_NSID,
-  title: "Climate Action Projects",
-  avatar: {
-    image: blobRef, // or { uri: "https://..." }
-  },
-  banner: {
-    image: largeBlobRef, // or { uri: "https://..." }
+The `app.certified.link.evm` record enables verifiable linking between
+an ATProto DID and an EVM wallet address. The link is proven via a
+cryptographic signature, allowing any verifier to confirm that the
+wallet owner authorized the binding. Currently supports EOA wallets
+via EIP-712 typed data signatures; the `proof` field is an open union
+to allow future signature methods (e.g. ERC-1271, ERC-6492).
+
+```typescript
+import { LINK_EVM_NSID } from "@hypercerts-org/lexicon";
+
+const evmLinkRecord = {
+  $type: LINK_EVM_NSID,
+  address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+  proof: {
+    $type: "app.certified.link.evm#eip712Proof",
+    signature: "0xabc123...", // truncated for readability; real signatures are 130-132 hex chars
+    message: {
+      $type: "app.certified.link.evm#eip712Message",
+      did: "did:plc:alice",
+      evmAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+      chainId: "1",
+      timestamp: "1709500000",
+      nonce: "0",
+    },
   },
-  items: [
-    // ... collection items
-  ],
   createdAt: new Date().toISOString(),
 };
 ```
 
-**Note**: Both `avatar` (up to 5MB) and `banner` (up to 10MB) fields
-are optional and support either embedded image blobs or URI references to
-external images.
-
-### Adding Locations to Activities
-
-The `locations` field in activity records is an array of strong references
-(`com.atproto.repo.strongRef`) pointing to `app.certified.location` records.
-Each strong reference contains two required fields:
+**Key fields:**
 
-- `uri`: The ATProto URI of the location record (e.g., `at://did:plc:alice/app.certified.location/abc123`)
-- `cid`: The content identifier (CID) of the location record, ensuring referential integrity
+- `address` (required): 0x-prefixed EVM wallet address (EIP-55
+  checksummed, 42 chars)
+- `proof` (required): Open union containing the cryptographic proof of
+  wallet ownership. Each variant bundles its signature with the
+  corresponding message format. Currently the only variant is
+  `#eip712Proof` for EOA wallets.
+- `createdAt` (required): Timestamp when the record was created
 
-**Validation and Expectations**:
+## License
 
-- All location records referenced in the `locations` array must conform to the
-  `app.certified.location` lexicon schema
-- The `uri` field must be a valid ATProto URI pointing to an existing location record
-- The `cid` field must match the current CID of the referenced location record
-- The `locations` field is optional; activities can be created without location data
-- When using the sidecar pattern (same TID), ensure the location record is created
-  or updated alongside the activity record for consistency
+MIT