@hypercerts-org/lexicon 0.10.0 → 0.11.1

package/README.md

@@ -1,39 +1,181 @@
-# 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, image)
+                     ├──► rights                (licensing terms)
+                     └──► workScope
+                            ├── cel ───► tag    (CEL expression referencing tags)
+                            └── string          (free-form scope)
+
+CONTEXT ─ evidence, data, and social verification
+──────────────────────────────────────────────────────────────────────
+  attachment ─────────────► any record (activity, evaluation, …)
+  measurement ────────────► any record (activity, …)
+  evaluation ─────────────► any record (activity, measurement, …)
+                  └──────► measurement
+  acknowledgement ────────► any record  (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, …)
+  link/evm                  (ATProto DID ↔ EVM wallet link)
+  actor/profile             (user profile)
+  actor/organization        (org metadata)
+  badge/response ──► badge/award ──► badge/definition
+```
 
-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 +183,7 @@ following icons:
 npm install @hypercerts-org/lexicon
 ```
 
-## Usage
-
-### Basic Import
+## Quick Start
 
 ```typescript
 import {
@@ -51,8 +191,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,222 +198,155 @@ 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 can be a CEL expression (structured, machine-evaluable):
-  workScope: {
-    $type: "org.hypercerts.workscope.cel",
-    expression:
-      "scope.hasAll(['mangrove_restoration', 'environmental_education']) && location.country == 'KE'",
-    usedTags: [
-      {
-        uri: "at://did:plc:alice/org.hypercerts.workscope.tag/3k2abc",
-        cid: "...",
-      },
-      {
-        uri: "at://did:plc:alice/org.hypercerts.workscope.tag/7x9def",
-        cid: "...",
-      },
-    ],
-    version: "v1",
-    createdAt: new Date().toISOString(),
-  },
-  // OR a strongRef to a single work scope tag:
-  // workScope: { uri: "at://did:plc:alice/org.hypercerts.workscope.tag/abc123", cid: "..." },
-  // OR a simple string: workScope: { $type: "org.hypercerts.claim.activity#workScopeString", scope: "Environmental conservation" },
-  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(record, ACTIVITY_NSID, "main");
+if (!result.success) throw new Error(String(result.error));
 
+// Write to the network
 await agent.api.com.atproto.repo.createRecord({
   repo: agent.session?.did,
   collection: ACTIVITY_NSID,
-  record: activityRecord,
+  record,
 });
 ```
 
-### Creating Location Records
+## Lexicon Reference
 
-Location records (`app.certified.location`) specify where work was performed
-using geographic coordinates or other location formats. They can be referenced
-by activities, collections, attachments, measurements, and evaluations.
+### Claims (`org.hypercerts.claim.*`)
 
-```typescript
-import { LOCATION_NSID } from "@hypercerts-org/lexicon";
+| 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 image.                                                   |
+| **Rights**                  | `org.hypercerts.claim.rights`                 | Licensing and rights terms (e.g. "CC BY-SA 4.0") attached to an activity.                                                              |
 
-const locationRecord = {
-  $type: LOCATION_NSID,
-  lpVersion: "1.0", // Location Protocol version
-  srs: "http://www.opengis.net/def/crs/OGC/1.3/CRS84", // Spatial Reference System
-  locationType: "coordinate-decimal", // or "geojson-point", "geojson", "h3", "geohash", "wkt", "address", etc.
-  location: {
-    uri: "https://example.com/location-data.geojson",
-  },
-  // Optional fields
-  name: "Project Site A",
-  description: "Primary research facility in the Amazon rainforest",
-  createdAt: new Date().toISOString(),
-};
-```
+### Collections (`org.hypercerts.*`)
 
-- `lpVersion` (required): Version of the Location Protocol specification
-- `srs` (required): Spatial Reference System URI defining the coordinate system
-- `locationType` (required): Format identifier (e.g., "coordinate-decimal", "geojson-point", "geojson", "h3", "geohash", "wkt", "address", "scaledCoordinates"). See the [Location Protocol spec](https://spec.decentralizedgeo.org/specification/location-types/#location-type-registry) for the full registry.
-- `location` (required): Location data as URI, blob, or string
-- `name` (optional): Human-readable name for the location
-- `description` (optional): Additional context about the location
-- `createdAt` (required): Timestamp when the record was created
+| 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. |
 
-**Location data formats:**
+### Context (`org.hypercerts.context.*`)
 
-The `location` field accepts three formats:
+| 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.       |
 
-1. **URI reference**: `{ uri: "https://..." }` - Link to external location data
-2. **Small blob**: Embedded location data (up to 10MB)
-3. **Location string**: Inline string wrapped in an object, containing coordinates or GeoJSON
+### Work Scope (`org.hypercerts.workscope.*`)
 
-```typescript
-// Example with embedded blob
-const locationWithBlob = {
-  $type: LOCATION_NSID,
-  lpVersion: "1.0",
-  srs: "http://www.opengis.net/def/crs/OGC/1.3/CRS84",
-  locationType: "geojson-point",
-  location: {
-    blob: {
-      $type: "blob",
-      ref: {
-        $link: "bafyrei...", // CID of the uploaded blob
-      },
-      mimeType: "application/geo+json",
-      size: 123,
-    },
-  },
-  name: "Amazon Research Station",
-  createdAt: new Date().toISOString(),
-};
+| 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. |
 
-// Example with inline string (coordinates)
-const locationWithCoordinates = {
-  $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", // lat, lon
-  },
-  name: "Amazon Research Site",
-  description: "Field station coordinates",
-  createdAt: new Date().toISOString(),
-};
+### Funding (`org.hypercerts.funding.*`)
 
-// Example with inline GeoJSON string
-const locationWithGeoJSON = {
-  $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(),
-};
-```
+| 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. |
 
-### Accessing NSIDs (Lexicon IDs)
+### Hyperboards (`org.hyperboards.*`)
 
-**Recommended**: Use individual NSID constants for cleaner, more readable code:
+| 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`). |
 
-```typescript
-import { ACTIVITY_NSID, COLLECTION_NSID } from "@hypercerts-org/lexicon";
+### Certified (`app.certified.*`)
 
-// Clean and explicit
-const record = {
-  $type: ACTIVITY_NSID,
-  // ...
-};
+| 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 with type, 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,
+  HYPERCERTS_COLLECTION_NSID,
+} from "@hypercerts-org/lexicon";
 ```
 
-**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.OrgHypercertsCollection;
+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 {
@@ -283,289 +354,217 @@ 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
-
-For complete schema documentation with all lexicon definitions and
-property tables, see [SCHEMAS.md](SCHEMAS.md).
-
 ## Examples
 
-### Collections
-
-Collections (`org.hypercerts.collection`) are named sets of references to
-other records, for any purpose the creator chooses. They live at the
-top-level namespace (not under `claim`) because they can contain more than
-just claims.
-
-#### Use Cases
-
-- Defining which activity claims belong to a project
-- Collections of projects
-- Favourites lists
-- Items associated with a particular funding round or funder
-- Portfolios of work by a contributor or organization
-- Thematic groupings (by work scope/topic)
-- Curated showcases for display (e.g. a hyperboard)
-- Milestone groupings (activities in a sprint/cycle)
-- Geographic groupings (projects or locations in a region)
-- Collections for reporting (e.g. all claims in a grant report)
-
-**Note**: Hyperboards are a separate concern — they are visualisations
-built on top of collections, not collections themselves.
-
-#### Creating a Collection with Nested Items
+### Creating Activities with Work Scope
 
 ```typescript
-import { TID } from "@atproto/common";
+import { ACTIVITY_NSID } from "@hypercerts-org/lexicon";
 
-const collectionRecord = {
-  $type: "org.hypercerts.collection",
-  title: "Climate Action Projects",
-  shortDescription:
-    "A collection of climate-related activities and sub-collections",
-  items: [
-    // Reference to an activity
-    {
-      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: "...",
-    },
-    // Reference to another collection (recursive!)
-    {
-      uri: "at://did:plc:carol/org.hypercerts.collection/4m5ghi",
-      cid: "...",
-    },
-  ],
+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 a Project
-
-Projects are collections with a `type` field set to "project" and can
-include rich-text descriptions:
+### Creating Collections (Projects, Portfolios, etc.)
 
 ```typescript
-const projectRecord = {
-  $type: "org.hypercerts.collection",
+import { HYPERCERTS_COLLECTION_NSID } from "@hypercerts-org/lexicon";
+
+const project = {
+  $type: HYPERCERTS_COLLECTION_NSID,
   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: "...",
-  },
+  shortDescription: "Activities focused on carbon reduction and reforestation",
   items: [
     {
-      uri: "at://did:plc:alice/org.hypercerts.claim.activity/3k2abc",
-      cid: "...",
+      itemIdentifier: {
+        uri: "at://did:plc:alice/org.hypercerts.claim.activity/3k2abc",
+        cid: "...",
+      },
     },
     {
-      uri: "at://did:plc:bob/org.hypercerts.claim.activity/7x9def",
-      cid: "...",
+      itemIdentifier: {
+        uri: "at://did:plc:bob/org.hypercerts.claim.activity/7x9def",
+        cid: "...",
+      },
+    },
+    // Collections can contain other collections (recursive nesting):
+    {
+      itemIdentifier: {
+        uri: "at://did:plc:carol/org.hypercerts.collection/4m5ghi",
+        cid: "...",
+      },
     },
   ],
   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.
-
-### Adding Visual Representation to Collections
-
-Collections can include `avatar` and `banner` fields for visual representation:
+### Creating Location Records
 
 ```typescript
-import { COLLECTION_NSID } from "@hypercerts-org/lexicon";
+import { LOCATION_NSID } from "@hypercerts-org/lexicon";
 
-const collectionRecord = {
-  $type: COLLECTION_NSID,
-  title: "Climate Action Projects",
-  avatar: {
-    image: blobRef, // or { uri: "https://..." }
+// 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: {
+    $type: "app.certified.location#string",
+    string: "-3.4653, -62.2159",
   },
-  banner: {
-    image: largeBlobRef, // or { uri: "https://..." }
+  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: {
+    $type: "app.certified.location#string",
+    string: '{"type":"Point","coordinates":[-62.2159,-3.4653]}',
   },
-  items: [
-    // ... collection items
-  ],
+  name: "Research Station Alpha",
   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.
-
 ### Acknowledging Inclusion
 
-The `org.hypercerts.context.acknowledgement` record enables bidirectional
-linking between records that live in different PDS repositories. When
-one user includes another user's record (e.g. adding an activity to a
-collection), the owner of the included record can create an
-acknowledgement to confirm or reject the inclusion. This forms a
-two-way link that an AppView can verify.
-
-Each acknowledgement uses `com.atproto.repo.strongRef` fields to
-reference both the **subject** (the record being included) and the
-**context** (the record it's being included in).
-
-See [SCHEMAS.md](SCHEMAS.md) for the full property reference.
-
-#### Use Case: Activity Included in a Collection
-
-A project organizer (Alice) creates a collection and adds Bob's
-activity to it via a `strongRef` in the collection's `items[]` array.
-Bob then creates an acknowledgement in his own repo to confirm:
+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
-import { ACKNOWLEDGEMENT_NSID } from "@hypercerts-org/lexicon";
+import { CONTEXT_ACKNOWLEDGEMENT_NSID } from "@hypercerts-org/lexicon";
 
-// Bob acknowledges that his activity is included in Alice's collection
 const ack = {
-  $type: ACKNOWLEDGEMENT_NSID,
+  $type: CONTEXT_ACKNOWLEDGEMENT_NSID,
   subject: {
     uri: "at://did:plc:bob/org.hypercerts.claim.activity/3k2abc",
     cid: "bafy...",
   },
+  // context is a union — use $type to specify the variant
   context: {
+    $type: "com.atproto.repo.strongRef",
     uri: "at://did:plc:alice/org.hypercerts.collection/7x9def",
     cid: "bafy...",
   },
-  acknowledged: true,
-  createdAt: new Date().toISOString(),
-};
-```
-
-#### Use Case: Contributor Included in an Activity
-
-Alice creates an activity that lists Bob as a contributor. Bob creates
-an acknowledgement in his own repo to confirm his participation:
-
-```typescript
-const ack = {
-  $type: ACKNOWLEDGEMENT_NSID,
-  subject: {
-    // Bob's contributor information record
-    uri: "at://did:plc:bob/org.hypercerts.claim.contributorInformation/abc123",
-    cid: "bafy...",
-  },
-  context: {
-    // Alice's activity that lists Bob as contributor
-    uri: "at://did:plc:alice/org.hypercerts.claim.activity/3k2abc",
-    cid: "bafy...",
-  },
-  acknowledged: true,
-  comment: "Confirming my contribution to this reforestation project",
-  createdAt: new Date().toISOString(),
-};
-```
-
-Setting `acknowledged: false` explicitly rejects inclusion, which an
-AppView can use to flag disputed associations.
-
-### 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:
-
-- `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
-
-**Validation and Expectations**:
-
-- 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
-
-### Adding Location to Collections
-
-Collections can include an optional `location` field to specify where the collection's activities were performed:
-
-```typescript
-const collectionRecord = {
-  $type: "org.hypercerts.collection",
-  title: "Climate Action Projects",
-  shortDescription: "A collection of climate-related activities",
-  location: {
-    uri: "at://did:plc:alice/app.certified.location/xyz789",
-    cid: "...",
-  },
-  items: [
-    // ... collection items
-  ],
+  acknowledged: true, // false to reject
   createdAt: new Date().toISOString(),
 };
 ```
 
-The `location` field is a strong reference to an `app.certified.location` record containing the same `uri` and `cid` fields as described above for activities.
-
 ### Creating Attachments
 
-Attachments provide commentary, context, evidence, or documentary material
-related to hypercert records. They can be linked to activities, evaluations,
-measurements, or even other attachments:
-
 ```typescript
-import { ATTACHMENT_NSID } from "@hypercerts-org/lexicon";
+import { CONTEXT_ATTACHMENT_NSID } from "@hypercerts-org/lexicon";
 
-const attachmentRecord = {
-  $type: ATTACHMENT_NSID,
+const attachment = {
+  $type: CONTEXT_ATTACHMENT_NSID,
   title: "Field Survey Report",
+  contentType: "report",
   subjects: [
     {
       uri: "at://did:plc:alice/org.hypercerts.claim.activity/abc123",
       cid: "...",
     },
   ],
-  contentType: "report",
+  // content items are a union — use $type to specify the variant
   content: [
-    { uri: "https://example.com/reports/survey-2024.pdf" },
-    { uri: "ipfs://Qm..." },
+    {
+      $type: "org.hypercerts.defs#uri",
+      uri: "https://example.com/reports/survey-2024.pdf",
+    },
+    { $type: "org.hypercerts.defs#uri", uri: "ipfs://Qm..." },
   ],
   shortDescription: "Quarterly field survey documenting project progress",
   createdAt: new Date().toISOString(),
 };
 ```
 
-**Key fields:**
+## Development
 
-- `title` (required): String title for the attachment
-- `shortDescription`/`description`: Support rich text via facet annotations
-- `subjects` (optional): Array of strong references to records this attachment relates to
-- `contentType` (optional): Type descriptor (e.g., "report", "audit", "evidence", "testimonial")
-- `content` (required): Array of URIs or blobs containing the attachment files
-- `location` (optional): Strong reference to an `app.certified.location` record
-- `createdAt` (required): Timestamp when the attachment was created
+### Commands
 
-**Adding Location to Attachments:**
+```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
+```
+
+### Linking ATProto Identity to EVM Wallets
+
+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
-const attachmentWithLocation = {
-  $type: ATTACHMENT_NSID,
-  title: "Site Inspection Photos",
-  content: [{ uri: "https://..." }],
-  location: {
-    uri: "at://did:plc:alice/app.certified.location/loc123",
-    cid: "...",
+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",
+    },
   },
   createdAt: new Date().toISOString(),
 };
 ```
+
+**Key fields:**
+
+- `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
+
+## License
+
+MIT