From 4c9a6a0da95040dbbb2fc078bdfedfac0e611885 Mon Sep 17 00:00:00 2001
From: Kristofer Lund <kristofer@fmckl.se>
Date: Tue, 15 Sep 2026 12:10:15 +0200
Subject: [PATCH 1/7] docs: restructure protocol documentation

---
 components/Layout.js                          |   6 +-
 components/SearchDialog.js                    |   8 +-
 docs/information-architecture.md              |  92 +++++
 docs/remote-markdown.md                       |  14 +
 lib/generate-last-updated.js                  |   2 +-
 lib/generate-search-index.js                  |  31 +-
 lib/navigation.js                             | 195 +++++-----
 pages/architecture/account-and-identity.md    |  25 +-
 pages/architecture/data-flow-and-lifecycle.md | 250 ++++---------
 pages/architecture/overview.md                |  28 +-
 pages/architecture/portability-and-scaling.md |  56 ++-
 pages/change-history/index.md                 |  23 ++
 pages/client-integration/index.md             |  38 ++
 pages/core-concepts/cel-work-scopes.md        | 236 ++----------
 pages/core-concepts/certified-identity.md     |  88 +++--
 pages/core-concepts/common-use-cases.md       |  50 +--
 pages/core-concepts/funding-and-value-flow.md | 116 ++----
 .../hypercerts-core-data-model.md             | 146 ++++----
 .../validation-and-interpretation.md          |  67 ++++
 pages/core-concepts/what-is-hypercerts.md     |  48 +--
 pages/core-concepts/why-at-protocol.md        |  26 +-
 pages/ecosystem/why-we-need-hypercerts.md     |   4 +
 .../getting-started/building-on-hypercerts.md |  37 +-
 pages/getting-started/quickstart.md           | 354 ------------------
 .../getting-started/testing-and-deployment.md |  10 +-
 .../working-with-evaluations.md               |  87 -----
 pages/guide/index.md                          |  69 ++++
 pages/index.md                                |  40 +-
 .../certified-lexicons/badge-award.md         |   6 +-
 .../certified-lexicons/badge-definition.md    |   6 +-
 .../certified-lexicons/badge-response.md      |   6 +-
 pages/lexicons/certified-lexicons/index.md    |  11 +-
 pages/lexicons/certified-lexicons/location.md |   2 +-
 pages/lexicons/certified-lexicons/profile.md  |   2 +-
 .../certified-lexicons/shared-defs.md         |   9 +-
 .../hypercerts-lexicons/acknowledgement.md    |   2 +-
 .../hypercerts-lexicons/activity-claim.md     |   6 +-
 .../hypercerts-lexicons/attachment.md         |   6 +-
 .../hypercerts-lexicons/collection.md         |   8 +-
 .../hypercerts-lexicons/contribution.md       |  12 +-
 .../hypercerts-lexicons/evaluation.md         |   6 +-
 .../hypercerts-lexicons/funding-receipt.md    |   8 +-
 pages/lexicons/hypercerts-lexicons/index.md   |  11 +-
 .../hypercerts-lexicons/measurement.md        |   4 +-
 pages/lexicons/hypercerts-lexicons/rights.md  |   2 +-
 pages/reference/faq.md                        |  17 +-
 pages/reference/glossary.md                   |   8 +-
 pages/reference/index.md                      |  56 +++
 pages/reference/lexicon-inventory.md          |  71 ++++
 pages/roadmap.md                              |   5 +-
 pages/tools/hyperboards.md                    |  85 -----
 pages/tools/hypercerts-feed-service.md        |   5 +-
 pages/tools/hyperindex.md                     |   4 +-
 pages/tools/scaffold.md                       | 297 ---------------
 styles/globals.css                            |   4 +-
 vercel.json                                   |  44 ++-
 56 files changed, 1128 insertions(+), 1721 deletions(-)
 create mode 100644 docs/information-architecture.md
 create mode 100644 pages/change-history/index.md
 create mode 100644 pages/client-integration/index.md
 create mode 100644 pages/core-concepts/validation-and-interpretation.md
 delete mode 100644 pages/getting-started/quickstart.md
 delete mode 100644 pages/getting-started/working-with-evaluations.md
 create mode 100644 pages/guide/index.md
 create mode 100644 pages/reference/index.md
 create mode 100644 pages/reference/lexicon-inventory.md
 delete mode 100644 pages/tools/hyperboards.md
 delete mode 100644 pages/tools/scaffold.md

diff --git a/components/Layout.js b/components/Layout.js
index 1aab698..234efe4 100644
--- a/components/Layout.js
+++ b/components/Layout.js
@@ -162,8 +162,10 @@ export default function Layout({ children, frontmatter }) {
           </Link>
           <span className="header-divider" aria-hidden="true" />
           <nav className="header-nav" aria-label="Main navigation">
-            <Link href="/getting-started/quickstart" className="header-nav-link">Docs</Link>
-            <Link href="/tools/scaffold" className="header-nav-link">Tools</Link>
+            <Link href="/guide" className="header-nav-link">Guide</Link>
+            <Link href="/client-integration" className="header-nav-link">Client integration</Link>
+            <Link href="/reference" className="header-nav-link">Reference</Link>
+            <Link href="/change-history" className="header-nav-link">Change history</Link>
           </nav>
           <div style={{ flex: 1 }} />
           <button
diff --git a/components/SearchDialog.js b/components/SearchDialog.js
index b451eff..30bae4c 100644
--- a/components/SearchDialog.js
+++ b/components/SearchDialog.js
@@ -23,12 +23,12 @@ function getSnippet(body, query, contextChars = 60) {
 
 // Paths for the curated quick links shown in the empty state
 const QUICK_LINK_PATHS = [
-  '/getting-started/quickstart',
+  '/guide',
+  '/client-integration',
+  '/reference',
+  '/change-history',
   '/core-concepts/what-is-hypercerts',
   '/core-concepts/hypercerts-core-data-model',
-  '/tools/scaffold',
-  '/architecture/overview',
-  '/reference/glossary',
 ];
 
 export function SearchDialog({ isOpen, onClose }) {
diff --git a/docs/information-architecture.md b/docs/information-architecture.md
new file mode 100644
index 0000000..0edc441
--- /dev/null
+++ b/docs/information-architecture.md
@@ -0,0 +1,92 @@
+# Documentation information architecture
+
+This is the working migration map for the protocol-first documentation restructure. It is a maintainer document, not a protocol specification.
+
+## Principles
+
+- The documentation has four primary sections: Guide, Client Integration, Reference, and Change History.
+- Together, the Guide, Lexicons, API and SDK contracts, reference implementation behavior, and change history describe the protocol. There is no separate ratified formal specification.
+- Guide pages explain meaning and shared usage. Reference pages provide exact source-backed contracts.
+- Integration pages publish tested paths, not inferred or aspirational APIs.
+- Existing public routes remain stable during the first pass unless their content has been explicitly retired.
+- A proposal in the third editor's draft is not a protocol requirement unless it is independently ratified and reflected in authoritative sources.
+
+## First-pass migration
+
+| Previous area | New primary home | Treatment |
+|---|---|---|
+| Get Started | Client Integration | Keep Building on Hypercerts and Testing & Deployment. Retire the current Quickstart and Working with Evaluations pages. |
+| Core Concepts | Guide | Keep and regroup the existing concept pages. Review claims against current Lexicons and AT Protocol behavior. |
+| Tutorials | Client Integration | Keep the ePDS tutorial source-backed from its service repository. |
+| Tools | Reference | Keep Agent Skills, Hypercerts Feed Service, Labelers, and legacy Hyperindex. Remove Scaffold from the active documentation because it is not a supported integration path. |
+| Architecture | Guide or Reference | Put lifecycle and portability guidance in Guide; put system and service architecture in Reference; put account setup in Client Integration. |
+| Lexicons and service directories | Reference | Keep existing routes and expand source-backed coverage. |
+| Lexicon releases | Change History | Keep the imported upstream changelog and add adopter-facing migration context separately. |
+| Ecosystem and vision | Guide | Keep protocol-purpose content in the conceptual path. |
+| Roadmap | Unassigned | Keep the source for now, but do not mix planned capabilities into supported instructions or change history. |
+
+## Third editor's draft disposition
+
+The draft at `https://claude.ai/code/artifact/cf891a57-416c-4d63-8ec3-8194e6cb6e28` is explicitly unratified. Use it as an inventory and review source, not as publication-ready normative text.
+
+| Draft material | Destination | Publication rule |
+|---|---|---|
+| Introduction and relationship to AT Protocol (section 1) | Guide foundations | Reuse descriptive material after checking current terminology. |
+| Conformance model and requirement keywords (section 2) | Do not publish as current protocol | No conformance classes or test suite have been ratified. |
+| General requirements (section 3) | Guide topics such as references, trust, validation, and aggregation | Treat the numbered requirements as proposals until reviewed. |
+| Terminology and data model (section 4) | Guide and Glossary | Separate concept meaning from field-level Reference content. |
+| Identity, authority, and provenance (section 5) | Guide: Identity and Trust | Explain repository attribution, named subjects, corroboration, and optional record-level attestations. |
+| Hypercerts and Certified schema chapters (sections 6 to 11) | Guide concept groups plus Lexicon Reference | Take structural facts from released Lexicons, not from the prose draft alone. |
+| Interoperability profiles (section 13) | Unresolved | Do not publish the proposed profiles as compatibility requirements. |
+| Authorization and permission sets (section 14) | Client Integration and Reference | Document released permission sets and tested OAuth behavior; review proposed expansion rules separately. |
+| Versioning and releases (section 15) | Change History | Distinguish independent component releases from any coordinated protocol release relationship. |
+| Open issues (section 16) | Future known-limitations pages | Publish verified limitations, not speculative resolutions. |
+| Lexicon inventory (appendix B) | Reference coverage checklist | Verify every item against a released Lexicon source. |
+| Worked example (appendix C) | Future Client Integration walkthrough | Rebuild as a runnable, tested SDK and XRPC example. |
+| Proposed requirements register (appendix D) | Draft review only | Do not convert it into active documentation requirements. |
+
+## Missing pages and source work
+
+### Guide
+
+- Protocol and infrastructure boundaries
+- Record identity, versions, and references
+- Identity, authority, trust, and corroboration
+- Validation and extensibility
+- Aggregation and interpretation
+- Known limitations and open semantic questions
+
+### Client Integration
+
+- Prerequisites and supported environments
+- Authentication and permission sets
+- Create and store records with the SDK
+- Read and discover records through XRPC
+- Complete project, activity, and evidence walkthrough
+- Evaluation workflow
+- Organization-managed records
+- Troubleshooting and production readiness
+
+### Reference
+
+- Complete `org.hypercerts.*` and `app.certified.*` Lexicon inventory
+- XRPC query and procedure pages generated or imported from canonical schemas
+- SDK exports, types, validation, errors, and version support
+- Hypercerts API service overview and environments
+- Per-service subpages for ePDS, CGS, labelers, feed generators, relay or Jetstream, and operational status
+
+### Change History
+
+- Adopter-facing change entries that link meaning, schemas, components, and migration steps
+- Component changelog links without implying one universal compliance version
+- Migration guides for changes that require adopter action
+
+## External service documentation
+
+Keep one local service overview when the documentation site needs to explain role, support status, and relationships. Import each canonical technical subpage independently from its owning repository through `docs-sources.yml` and a frontmatter-only route wrapper. This preserves source ownership while allowing a service to occupy a full subtree in the documentation site.
+
+Do not combine locally maintained prose with imported Markdown on the same route. The import loader intentionally rejects that pattern to prevent two sources from drifting.
+
+## URL migration
+
+The first pass reorganizes navigation while preserving the existing URLs of retained pages. The four explicitly retired pages redirect to the nearest active section hub. Future route moves should be made only with permanent redirects, internal-link checks, and a review of raw Markdown URLs.
diff --git a/docs/remote-markdown.md b/docs/remote-markdown.md
index eb15e18..ea19486 100644
--- a/docs/remote-markdown.md
+++ b/docs/remote-markdown.md
@@ -77,6 +77,20 @@ externalDoc: epds-architecture
 
 Do not add a local Markdown body. The registered file is the only page body, which prevents stale fallback content from diverging from rendering, search, or `/raw` exports.
 
+## Document a service with subpages
+
+Use a local overview page for the service's role, status, supported environments, and relationship to the rest of the Hypercerts stack. Keep implementation-specific detail in the service repository when that repository owns the contract.
+
+For each canonical upstream Markdown file:
+
+1. Add a separate source entry to `docs-sources.yml`.
+2. Add a frontmatter-only wrapper at the intended child route.
+3. Link the imported child page from the local service overview.
+
+This allows a service to have multiple source-backed subpages without copying its documentation into this repository. The current loader deliberately does not support a local introduction plus an imported body on the same route. Use a local parent page when editorial context is needed, then keep each imported child page fully canonical to its upstream file.
+
+Choose `ref` according to the source's publishing policy. A moving branch such as `main` follows upstream changes through the refresh workflow. A tag or commit creates a stable documentation snapshot and must be updated deliberately.
+
 ## Build behavior
 
 `npm run generate:external-docs` fetches every registered file once through the GitHub contents API and writes `lib/external-docs-content.json`. The static build then uses that immutable snapshot for:
diff --git a/lib/generate-last-updated.js b/lib/generate-last-updated.js
index 0f10073..b8e0b49 100644
--- a/lib/generate-last-updated.js
+++ b/lib/generate-last-updated.js
@@ -41,7 +41,7 @@ const map = {};
 
 for (const file of files) {
   const rel = "/" + relative(PAGES_DIR, file).replace(/\.md$/, "");
-  const route = rel === "/index" ? "/" : rel;
+  const route = rel.replace(/\/index$/, "") || "/";
   const pagePath = relative(PAGES_DIR, file);
   const markdown = readFileSync(file, "utf8");
   const frontmatter = parseMarkdownFrontmatter(markdown, pagePath);
diff --git a/lib/generate-search-index.js b/lib/generate-search-index.js
index a8c1279..62fe9eb 100644
--- a/lib/generate-search-index.js
+++ b/lib/generate-search-index.js
@@ -86,14 +86,31 @@ function stripMarkdown(content) {
 }
 
 function getSection(path) {
-  if (path === "/") return "Get Started";
-  if (path.startsWith("/getting-started")) return "Get Started";
-  if (path.startsWith("/core-concepts")) return "Core Concepts";
-  if (path.startsWith("/tools")) return "Tools";
-  if (path.startsWith("/architecture")) return "Architecture";
+  if (path === "/change-history" || path === "/reference/releases") {
+    return "Change History";
+  }
+  if (
+    path === "/client-integration" ||
+    path.startsWith("/getting-started") ||
+    path.startsWith("/tutorials") ||
+    path === "/architecture/account-and-identity"
+  ) {
+    return "Client Integration";
+  }
+  if (
+    path === "/" ||
+    path === "/guide" ||
+    path.startsWith("/core-concepts") ||
+    path.startsWith("/ecosystem") ||
+    path === "/architecture/data-flow-and-lifecycle" ||
+    path === "/architecture/portability-and-scaling"
+  ) {
+    return "Guide";
+  }
+  if (path.startsWith("/tools")) return "Reference";
+  if (path.startsWith("/architecture")) return "Reference";
   if (path.startsWith("/lexicons")) return "Reference";
   if (path.startsWith("/reference")) return "Reference";
-  if (path.startsWith("/ecosystem")) return "Ecosystem & Vision";
   if (path === "/roadmap") return "Reference";
   return "Other";
 }
@@ -109,7 +126,7 @@ async function main() {
   for (const file of files) {
     const localContent = readFileSync(file, "utf-8");
     const rel = "/" + relative(PAGES_DIR, file).replace(/\.md$/, "");
-    const path = rel === "/index" ? "/" : rel;
+    const path = rel.replace(/\/index$/, "") || "/";
 
     const frontmatter = parseMarkdownFrontmatter(localContent, relative(PAGES_DIR, file));
     const title = getStringFrontmatterValue(frontmatter, "title");
diff --git a/lib/navigation.js b/lib/navigation.js
index 919d300..3c93ee7 100644
--- a/lib/navigation.js
+++ b/lib/navigation.js
@@ -1,105 +1,117 @@
 export const navigation = [
   {
-    section: "Get Started",
+    section: "Guide",
     children: [
-      { title: "Welcome", path: "/" },
-      { title: "Quickstart", path: "/getting-started/quickstart" },
+      { title: "Guide overview", path: "/guide" },
       {
-        title: "Working with Evaluations",
-        path: "/getting-started/working-with-evaluations",
-      },
-      {
-        title: "Building on Hypercerts",
-        path: "/getting-started/building-on-hypercerts",
-      },
-      {
-        title: "Testing & Deployment",
-        path: "/getting-started/testing-and-deployment",
-      },
-    ],
-  },
-  {
-    section: "Core Concepts",
-    children: [
-      {
-        title: "What are Hypercerts?",
-        path: "/core-concepts/what-is-hypercerts",
-      },
-      {
-        title: "Common Use Cases",
-        path: "/core-concepts/common-use-cases",
-      },
-      {
-        title: "Core Data Model",
-        path: "/core-concepts/hypercerts-core-data-model",
-      },
-      {
-        title: "Certified Identity",
-        path: "/core-concepts/certified-identity",
+        title: "Foundations",
+        children: [
+          {
+            title: "What are Hypercerts?",
+            path: "/core-concepts/what-is-hypercerts",
+          },
+          {
+            title: "Why AT Protocol?",
+            path: "/core-concepts/why-at-protocol",
+          },
+          {
+            title: "Core Data Model",
+            path: "/core-concepts/hypercerts-core-data-model",
+          },
+          {
+            title: "Common Use Cases",
+            path: "/core-concepts/common-use-cases",
+          },
+        ],
       },
-      { title: "Why AT Protocol?", path: "/core-concepts/why-at-protocol" },
       {
-        title: "Funding & Value Flow",
-        path: "/core-concepts/funding-and-value-flow",
+        title: "Meaning and trust",
+        children: [
+          {
+            title: "Identity, Authorship & Trust",
+            path: "/core-concepts/certified-identity",
+          },
+          {
+            title: "Work Scopes & Classification",
+            path: "/core-concepts/cel-work-scopes",
+          },
+          {
+            title: "Funding Records & Value Flow",
+            path: "/core-concepts/funding-and-value-flow",
+          },
+        ],
       },
       {
-        title: "CEL Work Scopes",
-        path: "/core-concepts/cel-work-scopes",
+        title: "Shared operation",
+        children: [
+          {
+            title: "Records, References & Lifecycle",
+            path: "/architecture/data-flow-and-lifecycle",
+          },
+          {
+            title: "Public Data, Discovery & Portability",
+            path: "/architecture/portability-and-scaling",
+          },
+          {
+            title: "Validation, Extension & Interpretation",
+            path: "/core-concepts/validation-and-interpretation",
+          },
+        ],
       },
-    ],
-  },
-  {
-    section: "Tutorials",
-    children: [
       {
-        title: "Integrate with ePDS",
-        path: "/tutorials/epds",
+        title: "Background",
+        children: [
+          {
+            title: "Why Hypercerts Matter",
+            path: "/ecosystem/why-we-need-hypercerts",
+          },
+        ],
       },
     ],
   },
   {
-    section: "Tools",
+    section: "Client Integration",
     children: [
-      { title: "Scaffold Starter App", path: "/tools/scaffold" },
-      { title: "Agent Skills", path: "/tools/hypercerts-agent-skills" },
-      { title: "Hyperindex", path: "/tools/hyperindex" },
+      { title: "Integration overview", path: "/client-integration" },
       {
-        title: "Hypercerts Feed Service",
-        path: "/tools/hypercerts-feed-service",
+        title: "Building on Hypercerts",
+        path: "/getting-started/building-on-hypercerts",
       },
-      { title: "Hyperboards", path: "/tools/hyperboards" },
-      { title: "Labelers", path: "/tools/labelers" },
-    ],
-  },
-  {
-    section: "Architecture",
-    children: [
-      { title: "Architecture Overview", path: "/architecture/overview" },
       {
         title: "Account & Identity Setup",
         path: "/architecture/account-and-identity",
       },
       {
-        title: "ePDS Architecture",
-        path: "/architecture/epds",
-      },
-      {
-        title: "Certified Group Service (CGS)",
-        path: "/architecture/certified-group-service",
-      },
-      {
-        title: "Data Flow & Lifecycle",
-        path: "/architecture/data-flow-and-lifecycle",
+        title: "Integrate with ePDS",
+        path: "/tutorials/epds",
       },
       {
-        title: "Portability & Data Access",
-        path: "/architecture/portability-and-scaling",
+        title: "Testing & Deployment",
+        path: "/getting-started/testing-and-deployment",
       },
     ],
   },
   {
     section: "Reference",
     children: [
+      { title: "Reference overview", path: "/reference" },
+      { title: "Lexicon inventory", path: "/reference/lexicon-inventory" },
+      { title: "Glossary", path: "/reference/glossary" },
+      { title: "FAQ", path: "/reference/faq" },
+      {
+        title: "Architecture",
+        path: "/architecture/overview",
+        children: [
+          {
+            title: "ePDS Architecture",
+            path: "/architecture/epds",
+          },
+          {
+            title: "Certified Group Service",
+            path: "/architecture/certified-group-service",
+          },
+        ],
+      },
       {
         title: "Lexicons",
         path: "/lexicons/introduction-to-lexicons",
@@ -175,25 +187,37 @@ export const navigation = [
           },
         ],
       },
-      { title: "Lexicon Releases", path: "/reference/releases" },
-      { title: "Certified Services", path: "/reference/certified-services" },
-      { title: "Certified PDSs", path: "/reference/certified-pdss" },
       {
-        title: "Certified Group Services",
-        path: "/reference/certified-group-services",
+        title: "Services and tooling",
+        children: [
+          {
+            title: "Certified Services",
+            path: "/reference/certified-services",
+          },
+          { title: "Certified PDSs", path: "/reference/certified-pdss" },
+          {
+            title: "Certified Group Services",
+            path: "/reference/certified-group-services",
+          },
+          {
+            title: "Hypercerts Feed Service",
+            path: "/tools/hypercerts-feed-service",
+          },
+          { title: "Labelers", path: "/tools/labelers" },
+          { title: "Hyperindex (legacy)", path: "/tools/hyperindex" },
+          {
+            title: "Agent Skills",
+            path: "/tools/hypercerts-agent-skills",
+          },
+        ],
       },
-      { title: "Glossary", path: "/reference/glossary" },
-      { title: "FAQ", path: "/reference/faq" },
-      { title: "Roadmap", path: "/roadmap" },
     ],
   },
   {
-    section: "Ecosystem & Vision",
+    section: "Change History",
     children: [
-      {
-        title: "Why We Need Hypercerts",
-        path: "/ecosystem/why-we-need-hypercerts",
-      },
+      { title: "Change history overview", path: "/change-history" },
+      { title: "Lexicon Releases", path: "/reference/releases" },
     ],
   },
 ];
@@ -222,6 +246,7 @@ export function flattenNavigation(nav = navigation, currentSection = "") {
 export function getPrevNext(currentPath) {
   const flat = flattenNavigation();
   const index = flat.findIndex((item) => item.path === currentPath);
+  if (index === -1) return { prev: null, next: null };
   return {
     prev: index > 0 ? flat[index - 1] : null,
     next: index < flat.length - 1 ? flat[index + 1] : null,
diff --git a/pages/architecture/account-and-identity.md b/pages/architecture/account-and-identity.md
index 8940da2..8885ee6 100644
--- a/pages/architecture/account-and-identity.md
+++ b/pages/architecture/account-and-identity.md
@@ -5,7 +5,7 @@ description: Understand your identity, configure custom domains, and manage cred
 
 # Account & Identity Setup
 
-If you followed the [Quickstart](/getting-started/quickstart), you already have an account. This page explains what that account gives you and how to configure it — custom domain handles for organizations, app passwords for scripts, shared repositories for teams, and account recovery.
+This page explains what an AT Protocol account gives you and how to configure it: custom domain handles for organizations, app passwords for scripts, shared repositories for teams, and account recovery.
 
 ---
 
@@ -14,28 +14,27 @@ If you followed the [Quickstart](/getting-started/quickstart), you already have
 Sign up at [certified.app](https://certified.app/). You'll get:
 
 - **Low-friction sign-in** — Sign in with just your email and a code. No passwords or protocol knowledge required.
-- **A DID** — Your permanent, portable identifier (e.g., `did:plc:z72i7hdynmk6r22z27h6tvur`). It never changes, even if you switch servers or handles.
-- **A Repository** — Your own collection on the certified PDS, where your hypercerts, evaluations, and other records are stored. You own this data and you can migrate it between servers.
-- **An (embedded) wallet** — Add your existing EVM wallet or get a new one.
-- **Ecosystem access** — Your identity works across every Hypercerts application.
+- **A DID** — Your portable account identifier (e.g., `did:plc:z72i7hdynmk6r22z27h6tvur`), distinct from the current server address and handle.
+- **A repository** — An AT Protocol repository on a Certified PDS, where Hypercerts and other supported records can be stored.
+- **Application access** — A DID and repository that compatible applications can support through their own authentication and permission flows.
 
 ### Why Certified?
 
 The Hypercerts Protocol is built on AT Protocol — the same decentralized data layer that powers Bluesky. But most Hypercerts users are not Bluesky users. They are researchers, land stewards, open-source maintainers, funders, and evaluators. Asking them to "sign in with Bluesky" to use a funding platform would be confusing — it ties a funding tool to a social media brand. This is no knock on Bluesky — it's a great platform, just not the right entry point for a funding tool.
 
-Certified is a neutral identity provider that isn't tied to any single application. You create an account and immediately have an identity that works across the entire ecosystem — no knowledge of Bluesky, ATProto, or decentralized protocols required.
+Certified provides a Hypercerts-oriented account path without requiring users to understand Bluesky or AT Protocol internals. Each application still determines which account providers and permissions it supports.
 
 {% callout type="note" %}
-Hypercerts is fully interoperable with the AT Protocol ecosystem. If you already have a Bluesky account or any other ATProto identity, log in with your existing handle (e.g., `alice.bsky.social`) and use all Hypercerts applications — no additional account needed.
+Existing Bluesky and other AT Protocol accounts can be used by Hypercerts applications that support their authentication provider and request the required permissions. Check the target application's supported account types before treating an existing identity as a complete integration path.
 {% /callout %}
 
 ---
 
 ## Your DID
 
-Your DID is your permanent identity. It looks like `did:plc:z72i7hdynmk6r22z27h6tvur` and is resolved via the [PLC directory](https://plc.directory), which maps it to your current PDS, public keys, and handle.
+Your DID is your account identifier. It looks like `did:plc:z72i7hdynmk6r22z27h6tvur` and is resolved via the [PLC directory](https://plc.directory), which maps it to the current PDS, public keys, and handle.
 
-Every record you create carries your DID as the author. If you change PDS providers, your DID stays the same — other applications continue to recognize you and your data migrates with you.
+The DID in a record's AT-URI identifies the repository that published it. An account migration that preserves the DID can preserve those AT-URIs when the PDS changes; application recognition and index freshness remain implementation concerns.
 
 ---
 
@@ -43,7 +42,7 @@ Every record you create carries your DID as the author. If you change PDS provid
 
 Handles are not needed to log in to the Hypercerts ecosystem, but every user has one. They serve as human-readable names for publicly addressing others and for interacting with other applications in the AT Protocol ecosystem that haven't implemented email-based login with Certified. Your handle is a human-readable name like `alice.certified.one`. Unlike your DID, your handle can change — it's a pointer to your DID, not your identity itself.
 
-**Organizations should use custom domain handles.** A handle like `numpy.org` proves organizational identity — anyone can verify that the DID behind `numpy.org` is controlled by whoever controls the domain.
+**Organizations should use custom domain handles.** A handle like `numpy.org` demonstrates control of the domain at verification time and gives applications a recognizable name for the DID.
 
 To set up a custom handle, add a DNS TXT record or host a file at `https://your-domain.com/.well-known/atproto-did`. See the [AT Protocol handle documentation](https://atproto.com/specs/handle) for details.
 
@@ -74,7 +73,7 @@ Certified operates hosted CGS instances for its environments (used by "create a
 
 ### OAuth (for applications)
 
-Applications authenticate users via AT Protocol OAuth. The AT Protocol client libraries handle the full OAuth flow — authorization, token management, and session restoration. Users authorize your app through their PDS and never share credentials with your application. See the [Quickstart](/getting-started/quickstart) for the authentication setup.
+Applications authenticate users via AT Protocol OAuth. The AT Protocol client libraries handle the full OAuth flow — authorization, token management, and session restoration. Users authorize your app through their PDS and never share credentials with your application. See [Client Integration](/client-integration) for the evolving integration guidance.
 
 ### OAuth (for ePDS)
 The ePDS (extended PDS) adds email/passwordless login on top of the standard PDS, without modifying the underlying AT Protocol PDS code. When a user authenticates, the ePDS Auth Service handles the OTP flow and then issues a standard AT Protocol authorization code back to your app.
@@ -106,5 +105,5 @@ Beyond identity, Certified contributes shared data schemas to the AT Protocol ec
 
 ## Next steps
 
-- [Quickstart](/getting-started/quickstart) — build a complete hypercert with contributions, attachments, and measurements
-- [Working with Evaluations](/getting-started/working-with-evaluations) — create evaluations of other people's work
+- [Client Integration](/client-integration) — review the target SDK and XRPC path and current gaps
+- [Evaluation Lexicon](/lexicons/hypercerts-lexicons/evaluation) — inspect the evaluation record schema
diff --git a/pages/architecture/data-flow-and-lifecycle.md b/pages/architecture/data-flow-and-lifecycle.md
index 4ef428b..0651a41 100644
--- a/pages/architecture/data-flow-and-lifecycle.md
+++ b/pages/architecture/data-flow-and-lifecycle.md
@@ -1,229 +1,107 @@
 ---
-title: Data Flow & Lifecycle
-description: How a hypercert moves from creation through evaluation to funding.
+title: Records, References & Lifecycle
+description: How AT Protocol record slots, versions, references, updates, deletion, and reverse discovery shape Hypercerts.
 ---
 
-# Data Flow & Lifecycle
+# Records, References & Lifecycle
 
-A hypercert flows through six stages from creation to ongoing accumulation of attachments and funding.
+Hypercerts records do not follow one mandatory sequence. An activity may be published before, during, or after work. Context can appear later from other repositories. Records may also be updated or deleted. The durable model is therefore based on record identity, version identity, and explicit references rather than a fixed workflow.
 
-## The Lifecycle of a Hypercert
+## Record slots and versions
 
-Every hypercert follows a similar path through the system, though the timeline and participants vary.
-
-**Creation** happens when a contributor writes an activity claim to their Personal Data Server. The claim gets a unique identifier and becomes part of the contributor's repository.
-
-**Enrichment** adds supporting data. Contribution records link collaborators. Attachment records attach proof of work. Measurement records provide quantitative data. Rights records define the terms of the claim. Collection records group claims into projects. These can live on the same server or different servers.
-
-**Evaluation** brings third-party assessment. Evaluators create evaluation records on their own servers that reference the original claim. Multiple evaluators can independently assess the same work. Evaluations accumulate over time.
-
-**Discovery** makes the hypercert findable. Relays aggregate records from many servers. Indexers build searchable databases. Platforms query indexers to surface hypercerts to users.
-
-**Funding** connects funders to the claim. Funding receipts (`org.hypercerts.funding.receipt`) record who funded what, how much, and when — this works today on AT Protocol. Optionally, the claim can be frozen and anchored on-chain for tokenized funding. The on-chain tokenization layer is [planned but not yet implemented](/core-concepts/funding-and-value-flow).
-
-**Accumulation** continues indefinitely. More evaluations arrive. Additional attachments get attached. The data layer continues evolving.
-
-```
-Creation → Enrichment → Evaluation → Discovery → Funding → Accumulation
-   ↓           ↓            ↓            ↓          ↓           ↓
-  PDS        PDS        Other PDS     Indexer   On-chain*   Ongoing
-```
-
-*On-chain layer is planned. See [Funding & Value Flow](/core-concepts/funding-and-value-flow).
-
-## Stage 1: Creation
-
-A hypercert begins when a contributor creates an activity claim on their PDS.
-
-The contributor writes an `org.hypercerts.claim.activity` record. This record includes fields like `workScope`, `startDate`, `endDate`, and `contributors`. The PDS validates the record against the lexicon schema.
-
-The record receives a unique AT-URI. The format is `at://did:plc:abc123/org.hypercerts.claim.activity/tid` where `did:plc:abc123` is the contributor's DID and `tid` is a timestamp-based identifier.
-
-The PDS signs the record and includes it in the contributor's repository. The signature proves the contributor created this record at this time. The repository is a Merkle tree that provides tamper-evidence.
-
-The relay picks up the new record. Within seconds, the record is available to downstream consumers. Indexers can now discover and process it.
-
-```
-Contributor → PDS → Relay → Indexers
-              ↓
-         (signed record)
-         at://did:plc:alice/org.hypercerts.claim.activity/3k7
-```
-
-## Stage 2: Enrichment
-
-Supporting data gets attached through additional records that reference the activity claim.
-
-#### Contribution Records
-
-Contributors are embedded in the activity claim's `contributors` array. For richer profiles, separate `org.hypercerts.claim.contributorInformation` and `org.hypercerts.claim.contribution` records can be created and referenced. Contributions can be created by the original contributor or by collaborators on their own servers.
-
-#### Attachment Records
-
-`org.hypercerts.context.attachment` records attach supporting documentation. Attachments can be URLs, file uploads, or structured data. Each attachment record includes a strong reference to the claim it supports.
-
-#### Measurement Records
-
-`org.hypercerts.context.measurement` records provide quantitative data. A measurement specifies what was measured, the value, the unit, and the methodology. Multiple measurements can track different metrics.
-
-#### Rights Records
-
-`org.hypercerts.claim.rights` records define the rights associated with a hypercert — for example, public display rights, attribution licenses, or transferability terms. The activity claim references a rights record via a strong reference. Rights are defined using a name, type, and description, with an optional attached legal document.
-
-#### Location Records
-
-`app.certified.location` records anchor work geographically. A location record can specify a point, a region, or multiple areas. This enables geographic filtering and regional funding mechanisms.
-
-#### Collection Records
-
-`org.hypercerts.collection` records group multiple activity claims into a project or portfolio. Each collection has weighted items (strong references to activity claims or other collections), supporting recursive nesting. A collection with `type="project"` represents a multi-year project composed of individual activity claims.
-
-#### Funding Receipts
-
-`org.hypercerts.funding.receipt` records track funding events. A receipt records who funded which activity, how much, through which payment rail, and when. Receipts reference the activity claim they fund. See [Funding & Value Flow](/core-concepts/funding-and-value-flow) for details.
-
-#### Cross-Server References
-
-These records can live on different PDS instances. A contributor on PDS-A can create an activity claim. A collaborator on PDS-B can create a contribution record that references it. A collaborator on PDS-C can create an attachment. Strong references ensure the connections are tamper-evident.
+An AT-URI identifies a record slot:
 
+```text
+at://did:plc:alice/org.hypercerts.claim.activity/3k7
 ```
-PDS-A (Alice)                    PDS-B (Bob)                     PDS-C (Carol)
-─────────────                    ───────────                     ─────────────
-activity claim                   contribution record             attachment record
-at://did:alice/...               at://did:bob/...                at://did:carol/...
-                                 subject: at://did:alice/...     subject: at://did:alice/...
-```
-
-## Stage 3: Evaluation
-
-Third parties assess the work by creating evaluation records on their own servers.
-
-An evaluator creates an `org.hypercerts.context.evaluation` record on their PDS. The evaluation includes a `subject` field with a strong reference to the activity claim. Strong references include both the AT-URI and the CID (content hash), ensuring the evaluation references a specific version of the claim.
-
-The evaluation record includes the evaluator's assessment. This can be a score, a category, structured feedback, or a link to a detailed report. The lexicon allows flexible evaluation formats.
-
-Multiple evaluators can independently assess the same claim. Each evaluation is a separate record on the evaluator's server. There's no central registry or coordination required.
-
-Evaluations accumulate over time. A claim created in January might receive its first evaluation in March, another in June, and more years later. Evaluations are never "final" — new assessments can always arrive.
-
-The evaluator's reputation matters. Applications can weight evaluations based on the evaluator's DID, their history, or their credentials. The protocol doesn't enforce any particular trust model.
-
-```
-Activity Claim (Alice's PDS)
-at://did:alice/org.hypercerts.claim.activity/3k7
-         ↑                    ↑                    ↑
-         │                    │                    │
-    Evaluation 1         Evaluation 2         Evaluation 3
-    (Eve's PDS)          (Frank's PDS)        (Grace's PDS)
-```
-
-## Stage 4: Discovery & Indexing
-
-Relays and indexers make hypercerts findable across the network.
-
-#### Relays
 
-Relays aggregate records from many PDS instances. When a user writes a new record, the relay picks it up and adds it to the firehose. Relays provide a complete stream of network activity.
+The three meaningful parts are the publishing repository DID, the Lexicon collection, and the record key. The record stored at that slot can change or disappear.
 
-#### Indexers (App Views)
+A CID is the content identifier for one exact version. Updating a record changes its CID while retaining the AT-URI. Deleting a source record removes it from its repository, although relays, indexers, caches, or prior recipients may retain copies.
 
-Indexers read from relays and build queryable databases. An indexer might filter for hypercerts-related records, resolve references between claims and evaluations, and compute derived data like total evaluation scores.
+## Relationship forms
 
-Different indexers can build different views. One indexer might focus on climate-related hypercerts. Another might specialize in open-source contributions. A third might aggregate all evaluations from trusted evaluators.
+### Strong references
 
-#### Platform Queries
+A strong reference pairs the AT-URI with a CID:
 
-Applications query indexers to surface hypercerts to users. A funding platform might query for "all hypercerts in the climate category with at least two evaluations." A dashboard might query for "all hypercerts created by this DID."
-
-Indexers expose APIs that applications consume. The protocol doesn't mandate a specific API format, but common patterns include GraphQL and REST endpoints.
-
-#### The Discovery Flow
-
-A typical discovery flow: a user creates a claim → the relay picks it up → indexers process it and update their databases → applications query indexers → users discover the claim on platforms.
-
-```
-Many PDS Instances
-       ↓
-     Relay (firehose)
-       ↓
-   Indexers (filtered views)
-       ↓
-  Applications (queries)
-       ↓
-     Users
+```json
+{
+  "uri": "at://did:plc:alice/org.hypercerts.claim.activity/3k7",
+  "cid": "bafyreib2rxk3rh6kzwq7..."
+}
 ```
 
-## Stage 5: Funding & Ownership (Planned)
-
-The on-chain funding layer is not yet implemented. The planned design: before a hypercert can be funded, its ATProto records are frozen and the snapshot is anchored on-chain. This ensures funders know exactly what they are paying for — the cert's contents cannot change after freezing.
+This records which version the publisher referred to. If the record at that URI is later updated, a consumer can detect that the current CID differs.
 
-For the full planned design — including anchoring, tokenization, funding mechanisms, and funding readiness patterns — see [Funding & Value Flow](/core-concepts/funding-and-value-flow).
+A strong reference does not freeze the target, ensure it remains available, prove its contents, or enforce the target Lexicon named in a field description. Consumers must apply those checks.
 
-## Stage 6: Accumulation
+### URI-only record subjects
 
-The hypercert continues evolving after funding.
+Some relationships should survive updates. `app.certified.defs#recordSubject`, used by entity follows, stores an AT-URI without a CID. It follows the record slot rather than one version.
 
-#### Ongoing Evaluations
+### DIDs and embedded values
 
-New evaluations arrive over time. A hypercert funded in 2024 might receive evaluations in 2025, 2026, and beyond. Each evaluation is a new record on the evaluator's PDS.
+A DID identifies an AT Protocol account rather than one record. Embedded objects and strings carry information inside the source record and have no separately addressable lifecycle.
 
-Indexers pick up new evaluations and update their databases. Applications can show the evolving assessment history. Funders can see how perceptions of the work change over time.
+## Forward references and backlinks
 
-#### Additional Attachments
+Relationships are stored only in the source record. For example:
 
-Contributors can attach more supporting documentation as outcomes become clear. A research project might add published papers. A climate initiative might add measurement data showing carbon reduction.
+- An activity points to reusable contributor, contribution, rights, location, and work-scope records.
+- A collection points to its activity, feature, or nested-collection items.
+- An attachment or measurement points to zero or more subjects.
+- An evaluation points to at most one primary subject and may point to supporting measurements.
+- A receipt may point to the work or organization it funded.
 
-Attachment records reference the original activity claim. The claim itself doesn't change — attachments accumulate around it.
-
-#### Long-Term Value
-
-The separation of data and ownership enables long-term value accumulation. A hypercert's reputation can grow as evaluations accumulate. The data remains portable and accessible regardless of future ownership changes.
+AT Protocol repository reads can retrieve a known source record. They do not natively answer "which records across the network point to this activity?" That reverse query requires an indexer or another backlink service.
 
+```mermaid
+flowchart LR
+  P1["Project repository"] --> A["Activity"]
+  P2["Evaluator repository"] --> E["Evaluation"]
+  P3["Funder or facilitator repository"] --> R["Funding receipt"]
+  E -->|strongRef to assessed version| A
+  R -->|strongRef to funded subject| A
+  I["Indexer"] -.observes and joins.-> A
+  I -.observes and joins.-> E
+  I -.observes and joins.-> R
+  I --> V["Application view"]
 ```
-Time →
-─────────────────────────────────────────────────────────
-Creation  Evaluation 1  Discovery  Evaluation 2  Attachment  Evaluation 3
-   ↓          ↓           ↓           ↓            ↓          ↓
-  PDS      PDS-Eva1     Indexer    PDS-Eva2      PDS       PDS-Eva3
-```
-
-## Cross-PDS References
 
-Records on different servers reference each other through strong references.
+The completeness of an assembled hypercert depends on what the indexer observed, retained, and chose to expose.
 
-A strong reference includes both the AT-URI and the CID (content hash). The URI identifies the record. The CID ensures the reference points to a specific version.
+## Common lifecycle events
 
-```json
-{
-  "subject": {
-    "uri": "at://did:plc:alice/org.hypercerts.claim.activity/3k7",
-    "cid": "bafyreib2rxk3rh6kzwq7..."
-  }
-}
-```
+### Create
 
-If the referenced record changes, the CID won't match. This makes references tamper-evident. An evaluation that references version 1 of a claim won't silently point to version 2.
+A client writes a record to a repository. The PDS accepts it into the repository and the repository's signed commit history attributes publication to that DID. Hypercerts Lexicon validation is normally a client, SDK, or indexing responsibility; do not assume every PDS enforces domain schemas.
 
-Applications can verify references by fetching the record and computing its CID. If the CID matches, the reference is valid. If not, the record was modified after the reference was created.
+### Update
 
-This enables trust across servers. A record on PDS-A can safely reference a record on PDS-B. The reference is verifiable without trusting either server.
+The publisher replaces the contents at the same AT-URI. New readers see the new CID. Existing strong references continue to identify the earlier version they cited, provided that version remains available from a source or cache.
 
-## What This Flow Enables
+### Add context
 
-The lifecycle supports use cases that span time, servers, and participants.
+Another publisher creates a separate record that points to an existing subject. No update to the subject is required. This is how evaluations, measurements, attachments, acknowledgements, badges, and receipts can accumulate across repositories.
 
-**Retroactive funding** works because creation and funding are separate stages. A contributor can create a claim in January, accumulate attachments and evaluations through the year, and receive funding in December. The data layer preserves the full history.
+### Delete
 
-**Cross-platform collaboration** works because enrichment happens across servers. A contributor on Platform A can work with a collaborator on Platform B. Their contribution records reference the same activity claim. Indexers aggregate both records.
+The publisher deletes the record from its repository. References to it become unresolved against the current source. Consumers should preserve the reference and its CID, mark the target unavailable, and avoid silently substituting another version.
 
-**Independent evaluation** works because evaluators control their own data. An evaluator doesn't need permission from the contributor or any platform. They create a record on their server that references the claim. Applications can discover and display it.
+### Discover and aggregate
 
-**Evolving reputation** works because accumulation is ongoing. A hypercert's value isn't fixed at creation. Evaluations arrive over time. Attachments accumulate. The full history is queryable.
+Relays and indexers can observe records from many repositories and build reverse-reference indexes, search, hydrated views, totals, and rankings. These are derived services with explicit coverage and policy, not canonical fields in the source graph.
 
-## Next Steps
+## Consumer rules
 
-For the overall architecture and how layers connect, see [Architecture Overview](/architecture/overview).
+A compatible consumer should:
 
-For details on specific record types and their schemas, see [Introduction to Lexicons](/lexicons/introduction-to-lexicons).
+1. Preserve source AT-URIs and version CIDs.
+2. Distinguish the current record from the version a strong reference cited.
+3. Show stale, missing, or deleted targets rather than silently repairing them.
+4. Validate that a referenced record has the expected collection and semantics.
+5. Identify the indexer and coverage assumptions behind backlinks and aggregates.
+6. Keep derived values separate from source records.
 
-For a practical walkthrough of creating a hypercert, see [Quickstart](/getting-started/quickstart).
+Next: [Public Data, Discovery & Portability](/architecture/portability-and-scaling).
diff --git a/pages/architecture/overview.md b/pages/architecture/overview.md
index 01f3b0c..0c24198 100644
--- a/pages/architecture/overview.md
+++ b/pages/architecture/overview.md
@@ -5,36 +5,34 @@ description: How the Hypercerts Protocol stack fits together.
 
 # Architecture Overview
 
-The Hypercerts Protocol is built on [AT Protocol](https://atproto.com/docs) — the same decentralized data layer that powers Bluesky. Users own their data, applications are interoperable, and records are cryptographically signed.
+The Hypercerts Protocol uses [AT Protocol](https://atproto.com/docs) for identity, repositories, record addressing, signed commits, and portability. Hypercerts and Certified Lexicons define domain records; applications and services write, discover, index, and interpret them.
 
-## Three Layers
+## Current layers
 
 ![The Hypercerts Stack](/images/architecture-stack.svg)
 
-**Data.** All hypercert records — activity claims, contributions, attachments, evaluations, measurements — live on AT Protocol. Each user's data is stored on a Personal Data Server (PDS) they control. Shared schemas called [lexicons](/lexicons/introduction-to-lexicons) define the structure of every record type, so any application can read any record. Users can switch PDS providers without losing data. For cases where multiple identities need to co-manage a single repository, the [Certified Group Service (CGS)](/architecture/certified-group-service) adds role-based governance in front of a PDS. See [Account & Identity](/architecture/account-and-identity) and [Portability & Data Access](/architecture/portability-and-scaling).
+**Source records.** Hypercerts and Certified records live in AT Protocol repositories hosted by PDSs. Public Lexicons define their shapes. A compatible consumer can fetch known records directly and preserve their AT-URIs and CIDs.
 
-**Applications.** Funding platforms, dashboards, and evaluation tools read from and write to the data layer. They query [indexers](/tools/hyperindex) that aggregate records from across the network into searchable databases. Different indexers can build different views of the same underlying data.
+**Discovery and views.** Relays observe repository events. Indexers select records, resolve references, build backlink indexes, and expose queryable views. Coverage and interpretation depend on each service. [Hyperindex](/tools/hyperindex) is retained as legacy GraphQL infrastructure while the target XRPC API is being developed.
 
-**Ownership (planned).** On-chain anchoring for funding and tokenization is not yet implemented. The intended design freezes a hypercert's ATProto records and anchors them on-chain before funding — so funders know exactly what they're paying for. See [Funding & Value Flow](/core-concepts/funding-and-value-flow).
+**Applications.** Funding platforms, project tools, evaluation services, dashboards, and agents read source or indexed records and publish new records. Their authentication, private data, workflows, ranking, and payment execution are outside the record schemas.
+
+**Managed access.** [Certified](https://certified.app), ePDS, and the [Certified Group Service](/architecture/certified-group-service) provide account and organization-oriented access paths. They support the protocol but do not define its source-record semantics.
 
 ## How Data Flows
 
-A user writes a record to their PDS. The PDS signs it and adds it to the user's repository. A relay picks up the new record and streams it to indexers. Indexers update their databases. Applications query indexers to display the data.
+A client writes a record to a repository through a PDS or managed service. A relay may observe the repository event; an indexer may include it; an application may query that index or fetch the source directly. Each step has its own availability and policy.
 
 ![Data flow through ATProto](/images/architecture-dataflow.svg)
 
-For the full lifecycle — creation, enrichment, evaluation, discovery, funding, and accumulation — see [Data Flow & Lifecycle](/architecture/data-flow-and-lifecycle).
+For record versions, relationship directions, and reverse discovery, see [Records, References & Lifecycle](/architecture/data-flow-and-lifecycle).
 
 ## Why It's Trustworthy
 
-Every PDS repository is a Merkle tree signed by the user's DID key — any third-party tampering is detectable because the signature won't match. When one record references another (e.g., an evaluation pointing to an activity claim), the reference includes a content hash, so you can tell if the target was modified after the reference was created. DIDs resolve via the [PLC directory](https://plc.directory) to a public key, so signatures are independently verifiable.
-
-This means: Alice creates a hypercert and her PDS signs it. Bob evaluates it, referencing Alice's record by URI and content hash. Anyone can verify Alice authored the claim, Bob authored the evaluation, and Bob evaluated the exact version Alice published.
-
-## Why This Architecture
+Signed repository commits make unauthorized changes detectable and attribute publication to the repository DID. Strong references identify the exact record version a publisher cited. Optional record-content signatures, acknowledgements, and evaluations can add other provenance and corroboration signals.
 
-**Why not fully on-chain?** Storing rich data on-chain is expensive — a single activity claim with attachments could cost hundreds of dollars in gas. On-chain works for ownership state, not for the full data layer.
+These mechanisms do not prove that a claim is true, that every named actor participated, or that an evaluator is independent. Applications must distinguish repository publishers from actors named inside records and apply their own trust policies.
 
-**Why not fully off-chain?** Funding requires immutability. Without on-chain anchoring, there's no way to guarantee that what a funder evaluated is what they end up funding.
+## Boundaries
 
-**Why ATProto?** Persistent DIDs, shared schemas, user-controlled data, and a growing ecosystem. IPFS has no identity layer or schemas. Ceramic has similar goals but a smaller ecosystem. Bluesky demonstrates ATProto scales to millions of users. See [Why AT Protocol?](/core-concepts/why-at-protocol).
+The released protocol does not guarantee a complete index, private records, payment settlement, claim freezing, tokenization, organization governance, or one universal trust model. See the [Guide](/guide) for domain meaning, [Client Integration](/client-integration) for current integration guidance, and [Reference](/reference) for exact service contracts.
diff --git a/pages/architecture/portability-and-scaling.md b/pages/architecture/portability-and-scaling.md
index f90d95d..161c73a 100644
--- a/pages/architecture/portability-and-scaling.md
+++ b/pages/architecture/portability-and-scaling.md
@@ -1,22 +1,60 @@
 ---
-title: Portability & Data Access
-description: How ATProto enables data migration, app switching, and transparent data access.
+title: Public Data, Discovery & Portability
+description: How source records, repository migration, relays, indexers, availability, and public-data limits differ.
 ---
 
 # {% $markdoc.frontmatter.title %}
 
-## Public by default
+Hypercerts uses public AT Protocol repository records so independent applications can read and connect them. Publication, availability, discovery, and presentation are different operations, and none guarantees the others.
 
-ATProto records are public by default. Anyone can read your activity claims, evaluations, and contributions. This is intentional — impact work benefits from transparency and discoverability.
+## Public source records
+
+Records in the released Hypercerts and Certified collections should be treated as public. Do not publish secrets, private contact details, confidential applications, access tokens, or personal data that should not be replicated.
+
+A source record being public does not mean every application will discover or display it. A reader may need its AT-URI, access to the current PDS, or an indexer that has observed it.
 
 ## Switching PDSs
 
-Users can migrate their entire repository to a new PDS without breaking references. Export from the old PDS, import to the new one, and update your DID document to point to the new URL. Applications automatically follow.
+AT-URIs use a DID rather than a server address. When an AT Protocol account migration preserves the DID, repository records can retain their identifiers after the DID document points to the new PDS.
+
+Migration still depends on a correct repository transfer, DID update, supported account state, and consumers resolving the current DID document. Applications and stale caches do not necessarily update immediately. See the [AT Protocol account migration guide](https://atproto.com/guides/account-migration) for the protocol process.
+
+## Discovery and indexed views
+
+Cross-repository applications commonly use relays and indexers:
+
+- A PDS hosts the current source repository.
+- A relay observes repositories and emits events according to its crawl and policy scope.
+- An indexer consumes selected events, resolves relationships, and builds queryable views.
+- An application reads those views and may also fetch source records directly.
+
+No index is inherently complete. Coverage can differ by repositories, collections, time range, moderation policy, retention, and failed ingestion. Applications should identify the source of aggregate claims and avoid presenting "not indexed" as "does not exist."
+
+## Switching applications
+
+Shared Lexicons make it possible for another application to parse a source record without a bilateral data export. Practical interoperability still depends on the second application supporting:
+
+- The record's Lexicon version and shared usage conventions.
+- Authentication and permissions for any writes.
+- The relevant repository or indexer coverage.
+- Unknown fields, record types, and values without data loss.
+- Product-specific workflows that are not encoded in the protocol.
+
+An application can therefore build on the same records without every application having identical features or trust policies.
+
+## Updates, deletion, and persistence
+
+Publishers can update and delete repository records. Other systems may retain prior versions, indexed copies, screenshots, exports, or references. Deleting the source is not a guarantee that all public copies disappear.
+
+Consumers should distinguish:
 
-This works because AT-URIs use DIDs, not server addresses — so all existing references remain valid after migration. See the [ATProto account migration guide](https://atproto.com/guides/account-migration) for the full process.
+- Current source state from cached or historical state.
+- A missing record from one outside the indexer's coverage.
+- An unavailable PDS from a deleted record.
+- A strong reference to an older CID from a broken reference.
 
-## Interoperable data
+## Operational limits
 
-Because data is stored on PDSs, not in application databases, users can switch apps without losing data. A claim created in App A is immediately readable by App B. Evaluations, attachments, and measurements created in different apps all reference the same underlying claims.
+Portability does not by itself guarantee availability. DIDs must resolve, PDSs must serve repositories, and indexing paths must remain healthy. Applications that depend on durable access should define retry, cache, source-verification, and outage behavior without presenting a cache as the source of truth.
 
-This is fundamentally different from traditional platforms, where switching apps means starting over.
+Next: [Validation, Extension & Interpretation](/core-concepts/validation-and-interpretation).
diff --git a/pages/change-history/index.md b/pages/change-history/index.md
new file mode 100644
index 0000000..83f241f
--- /dev/null
+++ b/pages/change-history/index.md
@@ -0,0 +1,23 @@
+---
+title: Change History
+description: Adopter-facing history for Hypercerts schema, guidance, SDK, API, and service changes.
+---
+
+# Change History
+
+Change history helps adopters understand what changed, who is affected, and whether an integration requires action.
+
+The current source-backed history covers [Hypercerts Lexicon releases](/reference/releases). Future entries should connect changes in protocol meaning and guidance to the affected Lexicons, SDK, APIs, and services.
+
+## Change entry structure
+
+Each adopter-facing entry should include:
+
+- the date and affected contracts or component versions;
+- a concise description of what changed;
+- compatibility impact and who is affected;
+- required migration steps, or an explicit statement that no action is required;
+- links to changed Guide and Reference pages;
+- links to the independent source releases and changelogs.
+
+Coordinated protocol packaging is still evolving. Change entries must not imply a universal conformance version or combine independent component releases into one version unless that release relationship has been explicitly established.
diff --git a/pages/client-integration/index.md b/pages/client-integration/index.md
new file mode 100644
index 0000000..e147316
--- /dev/null
+++ b/pages/client-integration/index.md
@@ -0,0 +1,38 @@
+---
+title: Client Integration
+description: Build applications that create, store, discover, and display Hypercerts records.
+---
+
+# Client Integration
+
+Client integration documentation is being rebuilt around the Hypercerts SDK and XRPC APIs. The target path is a tested end-to-end flow rather than the previous GraphQL-first quickstart.
+
+## Recommended path
+
+1. Authenticate an AT Protocol account and request the required permissions.
+2. Create compatible records with the Hypercerts SDK.
+3. Store records in the appropriate Personal Data Server (PDS).
+4. Read and discover records through supported XRPC APIs.
+5. Apply labels or feeds when the application needs them.
+6. Display connected records and preserve authorship and reference state.
+
+Detailed code will be published only after this complete path is tested against supported SDK, API, and service versions.
+
+## Available integration material
+
+{% card-grid %}
+{% card-link title="Building on Hypercerts" href="/getting-started/building-on-hypercerts" %}
+Review application patterns and interoperability principles.
+{% /card-link %}
+{% card-link title="Account & Identity Setup" href="/architecture/account-and-identity" %}
+Understand accounts, OAuth, handles, and organization-managed records.
+{% /card-link %}
+{% card-link title="Integrate with ePDS" href="/tutorials/epds" %}
+Use the source-backed ePDS authentication walkthrough.
+{% /card-link %}
+{% card-link title="Testing & Deployment" href="/getting-started/testing-and-deployment" %}
+Validate records, test safely, and prepare an integration for production.
+{% /card-link %}
+{% /card-grid %}
+
+Use the [Reference](/reference) for Lexicons and current service details. Hyperindex remains documented as legacy GraphQL infrastructure, not as the target protocol API.
diff --git a/pages/core-concepts/cel-work-scopes.md b/pages/core-concepts/cel-work-scopes.md
index b58d649..c5de702 100644
--- a/pages/core-concepts/cel-work-scopes.md
+++ b/pages/core-concepts/cel-work-scopes.md
@@ -1,224 +1,60 @@
 ---
-title: CEL Work Scopes
-description: How CEL (Common Expression Language) makes hypercert work scopes machine-readable, composable, and queryable.
+title: Work Scopes and Classification
+description: How Hypercerts records describe and classify the work covered by a claim.
 ---
 
-# CEL Work Scopes
+# Work Scopes and Classification
 
-Hypercert work scopes describe what work was done. A CEL expression alongside the human-readable work scope makes hypercerts machine-verifiable, composable, and queryable.
+A work scope describes what an activity covers. Classification tags describe projects, features, and reusable categories. The released model keeps these concerns separate.
 
-[CEL (Common Expression Language)](https://github.com/google/cel-spec) is an open-source expression language built by Google for evaluating conditions in distributed systems. It's used by Kubernetes, Firebase, and Google Cloud IAM.
+## Activity work scopes
 
-## Why structured scopes matter
+An activity's `workScope` can contain either:
 
-A community in coastal Kenya mints a hypercert for "mangrove restoration and environmental education." A collective in Uganda creates one for "agroforestry with beekeeping." A drone operator in the Amazon documents "biodiversity monitoring in the Negro River region." These are all legible to a person reading them one at a time. They're invisible to any system trying to connect funders to relevant work at scale.
+- A free-form work-scope string for human-readable descriptions.
+- An embedded `org.hypercerts.workscope.cel` object for machine-readable expressions.
 
-As the Hypercerts Protocol grows on ATProto — with actions, evaluations, and evidence living as persistent, portable records — the richer the network becomes, the harder it is to find, compare, validate, and compose claims when the most important field is unstructured text.
+The CEL object is embedded inside the activity; it is not a repository record. It contains an expression, a version, and `usedTags`, which are strong references to `org.hypercerts.workscope.tag` records.
 
-## Architecture: two layers
+Work-scope tags are reusable atoms for expressions. They can identify a parent tag, an equivalent external concept, or a replacement tag. Applications still need to decide which publishers and vocabularies they recognize.
 
-The design uses two complementary layers:
+## General classification
 
-1. **Vocabulary layer** — `workScopeTag` records define what each tag *means* (e.g., what `mangrove_restoration` refers to, its description, hierarchy, and links to external ontologies).
-2. **Composition layer** — `celExpression` objects compose those tags into evaluable logic on activity records (e.g., "this work includes mangrove restoration AND environmental education, AND is in Kenya").
+`org.hypercerts.vocab.tag` provides broader classifications for:
 
-```text
-workScopeTag records (vocabulary)
-  ├── mangrove_restoration
-  ├── environmental_education
-  ├── fishpond_management
-  └── ecotourism
+- `org.hypercerts.collection` records, including project collections.
+- `org.hypercerts.entity.feature` records.
 
-           ↓ referenced by
+General vocabulary tags can name broader concepts, equivalent external concepts, and superseding tags. The attached tags apply together by the released convention; they do not provide the Boolean expression language used by activity work scopes.
 
-celExpression (composition)
-  expression: scope.hasAll(['mangrove_restoration', 'environmental_education'])
-                && scope.hasAny(['fishpond_management', 'ecotourism'])
-                && location.country == 'KE'
-  usedTags: [strongRef → mangrove_restoration, strongRef → environmental_education, ...]
+## The three related schema families
 
-           ↓ embedded in
+- `org.hypercerts.workscope.cel` defines the structured Common Expression Language (CEL) object used by work-scope fields.
+- `org.hypercerts.workscope.tag` defines reusable terms used in work-scope expressions.
+- `org.hypercerts.vocab.tag` provides broader classification tags outside the work-scope expression model.
 
-activity.workScope (union)
-  → celExpression   (structured, machine-evaluable)
-  → workScopeString (simple free-form fallback)
-```
+These replace the older `org.hypercerts.ontology.*` names that appeared in previous documentation drafts.
 
-The vocabulary layer tells you what a tag means. The composition layer tells you what logic applies to a specific hypercert. The `workScopeString` fallback supports simple free-form scopes.
+## Shared usage guidance
 
-## Lexicon schemas
+- Use a simple textual scope when shared machine interpretation is not required.
+- Use a CEL scope when consumers need to apply logical operations to shared work-scope terms.
+- Use general vocabulary tags for classification of a collection or feature, not as a substitute for an activity's work-scope expression.
+- Preserve the publisher's AT-URI with every referenced tag. Matching names or keys from different repositories do not establish identical meaning.
+- Follow `supersededBy` and hierarchy relationships according to an explicit application policy. The Lexicons do not prevent cycles or invalid hierarchies.
+- Preserve unknown `knownValues`, tags, and CEL versions even when the application cannot interpret them.
+- Do not describe a scope or classification as verified merely because it passes structural validation.
 
-### `org.hypercerts.ontology.celExpression`
+## Open values and governance
 
-A CEL expression object embedded inline in the `activity.workScope` union. It's intentionally an `object` type (not a `record`) so it can be embedded directly without requiring a separate collection.
+Lexicon `knownValues` are open suggestions, not closed enums. A writer may publish another value that remains structurally valid. This supports extension, but it also means interoperable applications need fallback behavior.
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `expression` | `string` | Yes | A CEL expression encoding the work scope conditions. Max 10,000 characters. |
-| `usedTags` | `strongRef[]` | Yes | Strong references to `workScopeTag` records used in the expression. Enables fast indexing by AT-URI and provides referential integrity. Max 100 entries. |
-| `version` | `string` | Yes | CEL context schema version. Known values: `v1`. Open enum — new versions can be added non-breakingly. |
-| `createdAt` | `datetime` | Yes | Client-declared timestamp when this expression was originally created. |
+Vocabulary authority is similarly contextual. The DID in a tag's AT-URI identifies its publisher. It does not make that publisher universally authoritative for a domain. Applications should state which tag publishers they recognize and retain the original source when presenting normalized categories.
 
-### `org.hypercerts.ontology.workScopeTag`
+For exact fields and constraints, use the released `@hypercerts-org/lexicon` package and the [Lexicon inventory](/reference/lexicon-inventory). Tested SDK examples remain part of the evolving [Client Integration](/client-integration) path.
 
-A reusable scope atom — the building block of the vocabulary. Each record represents a single concept like `mangrove_restoration` or `biodiversity_monitoring`.
+## Related pages
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `key` | `string` | Yes | Lowercase, underscore-separated machine-readable key (e.g., `mangrove_restoration`). Used as the canonical identifier in CEL expressions. |
-| `label` | `string` | Yes | Human-readable display name. |
-| `kind` | `string` | No | Category type. Known values: `topic`, `language`, `domain`, `method`, `tag`. |
-| `description` | `string` | No | Longer explanation of the scope. |
-| `parent` | `strongRef` | No | Reference to a parent `workScopeTag` for taxonomy/hierarchy support. |
-| `status` | `string` | No | Lifecycle status. Known values: `proposed`, `accepted`, `deprecated`. Communities propose tags, curators accept them, deprecated tags point to replacements. |
-| `supersededBy` | `strongRef` | No | When status is `deprecated`, points to the replacement `workScopeTag`. |
-| `aliases` | `string[]` | No | Alternative names or identifiers for this scope. |
-| `sameAs` | `uri[]` | No | Links to equivalent concepts in external ontologies (e.g., Wikidata QIDs, ENVO terms, SDG targets). |
-| `externalReference` | `uri \| blob` | No | External reference as a URI or blob. |
-| `createdAt` | `datetime` | Yes | Client-declared timestamp when this record was originally created. |
-
-### `activity.workScope` union
-
-The `workScope` field on `org.hypercerts.claim.activity` accepts two variants:
-
-- **`celExpression`** — a structured, machine-evaluable scope (described above).
-- **`workScopeString`** — a simple free-form string for cases where a CEL expression isn't needed.
-
-## Examples
-
-### Mangrove restoration in coastal Kenya
-
-```json
-{
-  "$type": "org.hypercerts.claim.activity",
-  "title": "Tsunza Mangrove Restoration & Education",
-  "workScope": {
-    "$type": "org.hypercerts.ontology.celExpression",
-    "expression": "scope.hasAll(['mangrove_restoration', 'environmental_education']) && scope.hasAny(['fishpond_management', 'ecotourism']) && location.country == 'KE'",
-    "usedTags": [
-      { "uri": "at://did:plc:curator/org.hypercerts.ontology.workScopeTag/mangrove_restoration", "cid": "..." },
-      { "uri": "at://did:plc:curator/org.hypercerts.ontology.workScopeTag/environmental_education", "cid": "..." },
-      { "uri": "at://did:plc:curator/org.hypercerts.ontology.workScopeTag/fishpond_management", "cid": "..." },
-      { "uri": "at://did:plc:curator/org.hypercerts.ontology.workScopeTag/ecotourism", "cid": "..." }
-    ],
-    "version": "v1",
-    "createdAt": "2025-07-22T10:00:00Z"
-  },
-  "startDate": "2024-06-01T00:00:00Z",
-  "endDate": "2025-12-31T23:59:59Z"
-}
-```
-
-### Agroforestry in Uganda
-
-```json
-{
-  "workScope": {
-    "$type": "org.hypercerts.ontology.celExpression",
-    "expression": "scope.hasAll(['agroforestry', 'tree_planting', 'beekeeping']) && location.country == 'UG'",
-    "usedTags": [
-      { "uri": "at://did:plc:curator/org.hypercerts.ontology.workScopeTag/agroforestry", "cid": "..." },
-      { "uri": "at://did:plc:curator/org.hypercerts.ontology.workScopeTag/tree_planting", "cid": "..." },
-      { "uri": "at://did:plc:curator/org.hypercerts.ontology.workScopeTag/beekeeping", "cid": "..." }
-    ],
-    "version": "v1",
-    "createdAt": "2025-06-15T08:00:00Z"
-  }
-}
-```
-
-## What CEL unlocks
-
-### Funder matching
-
-Funders can define their criteria as CEL expressions and the appview matches them against existing hypercerts:
-
-```cel
-// "All mangrove work in East Africa"
-scope.has("mangrove_restoration") && location.country in ["KE", "TZ", "MZ", "MG"]
-```
-
-### Evaluation matching
-
-An auditor who verified mangrove survival rates can express applicability as a CEL condition, and the appview automatically matches it to relevant hypercerts:
-
-```cel
-scope.has("mangrove_restoration")
-  && location.country == "KE"
-  && time.end >= timestamp("2025-01-01T00:00:00Z")
-```
-
-### Overlap detection
-
-When someone mints a new hypercert, CEL can check whether the claimed work scope overlaps with existing claims:
-
-```cel
-existing.scope.overlaps(new.scope)
-  && existing.time.start < new.time.end
-  && new.time.start < existing.time.end
-  && existing.location.region == new.location.region
-```
-
-### Measurement-based queries
-
-Because CEL can access linked measurement records, funders can write queries that go beyond tags:
-
-```cel
-// "Agroforestry that planted 500+ verified trees"
-scope.has("agroforestry")
-  && measurements.exists(m, m.metric == "trees_planted" && m.value >= 500)
-```
-
-## CEL context schema (v1)
-
-Every CEL expression evaluates against a typed context. Each variable maps to data already present in the activity record and its linked records.
-
-| Variable | Type | Source | Description |
-|----------|------|--------|-------------|
-| `scope` | `ScopeSet` | `usedTags` on the CEL expression | The set of `workScopeTag` keys |
-| `location` | `Location` | Linked location records | Geo context |
-| `time` | `TimeRange` | `startDate` / `endDate` on activity | Work time range |
-| `contributors` | `list(Contributor)` | Contributors on activity | Contributor DIDs and roles |
-| `measurements` | `list(Measurement)` | Linked measurement records | Measurement data |
-| `evidence` | `list(Evidence)` | Linked attachment records | Evidence / attachments |
-
-### Custom functions on `ScopeSet`
-
-| Function | Signature | Semantics |
-|----------|-----------|-----------|
-| `has` | `ScopeSet.has(string) → bool` | True if label key is present |
-| `hasAll` | `ScopeSet.hasAll(list(string)) → bool` | True if every key is present |
-| `hasAny` | `ScopeSet.hasAny(list(string)) → bool` | True if at least one is present |
-| `overlaps` | `ScopeSet.overlaps(ScopeSet) → bool` | True if the two sets share any key |
-
-## Starter tag vocabulary
-
-`workScopeTag` records are published as ATProto records that anyone can reference via strong references. [Certified](https://certified.app) publishes curated tag sets for specific domains. Here's an example for regenerative work:
-
-| Domain | Example tags |
-|--------|-------------|
-| Agroforestry | `agroforestry`, `shade_trees`, `coffee_cultivation`, `beekeeping` |
-| Forest conservation | `forest_protection`, `reforestation`, `tree_planting` |
-| Marine / coastal | `mangrove_restoration`, `fishpond_management`, `coral_reef` |
-| Biodiversity monitoring | `biodiversity_data_collection`, `drone_imagery`, `bioacoustics`, `edna` |
-| Carbon / climate | `carbon_sequestration`, `emissions_reduction`, `soil_carbon` |
-| Community livelihoods | `community_data_income`, `ecotourism`, `artisanal_crafts` |
-| Education & capacity | `environmental_education`, `capacity_building`, `workshops` |
-
-Anyone can create `workScopeTag` records for other domains. Communities don't write CEL by hand — the vocabulary powers a visual builder, and the structured expression gets generated behind the scenes.
-
-## Where CEL lives in the stack
-
-CEL doesn't need to run onchain. The evaluation layer belongs alongside the ATProto infrastructure:
-
-| Layer | What lives here |
-|-------|----------------|
-| **ATProto records** | `workScopeTag` records define the vocabulary. Activity records carry the human-readable scope + CEL expression. |
-| **Appview / indexer** | CEL parsing and evaluation (using `cel-go`, `cel-rust`, or `cel-js`). Handles validation, querying, overlap detection, evaluation matching. |
-| **Client UI** | A scope builder that helps communities construct valid CEL from the `workScopeTag` vocabulary — no code writing required. |
-
-## Further reading
-
-- [CEL specification](https://github.com/google/cel-spec)
-- [Core Data Model](/core-concepts/hypercerts-core-data-model) — how records connect
-- [Activity Claim lexicon](/lexicons/hypercerts-lexicons/activity-claim) — the `workScope` field in context
+- [Core Data Model](/core-concepts/hypercerts-core-data-model)
+- [Validation, Extension & Interpretation](/core-concepts/validation-and-interpretation)
+- [Lexicon inventory](/reference/lexicon-inventory)
diff --git a/pages/core-concepts/certified-identity.md b/pages/core-concepts/certified-identity.md
index fc59dff..8c2f6b5 100644
--- a/pages/core-concepts/certified-identity.md
+++ b/pages/core-concepts/certified-identity.md
@@ -1,72 +1,70 @@
 ---
-title: Certified Identity
-description: How identity works in the Hypercerts ecosystem — DIDs, signing, portability, and wallet linkage.
+title: Identity, Authorship & Trust
+description: How repository publishers, named actors, signatures, acknowledgements, and application trust policies differ.
 ---
 
-# Certified Identity
+# Identity, Authorship & Trust
 
-Every hypercert record has an author. Every evaluation carries a signature. Every funding receipt traces back to a DID. Identity is a core primitive of the protocol — it determines who owns records, who can be trusted, and who receives funding.
+Every Hypercerts record is addressed inside an AT Protocol repository identified by a DID. This makes its publication attributable, but attribution is only one input to trust.
 
-## Identity in the Hypercerts Protocol
+## Four claims to keep separate
 
-The Hypercerts Protocol uses AT Protocol's identity system. Every participant — whether an individual contributor, an evaluator, or an organization — is identified by a **DID (Decentralized Identifier)**.
+| Claim | What it means |
+|---|---|
+| **Repository publisher** | The DID in the AT-URI identifies the repository that published the record. Signed repository commits make unauthorized changes detectable. |
+| **Named actor** | A record can name contributors, evaluators, senders, recipients, issuers, or subjects. Those fields are assertions and may not identify the repository publisher. |
+| **Record-content attestation** | Many released records optionally carry inline signatures or references to remote proof records. These are separate from AT Protocol repository signatures. |
+| **Application trust** | A client decides which publishers, evidence, attestations, and corroborating records it accepts for a purpose. The protocol does not calculate one global trust score. |
 
-A DID like `did:plc:z72i7hdynmk6r22z27h6tvur` is:
+## DIDs and repositories
 
-- **Permanent** — it never changes, even if you switch servers or handles
-- **Portable** — your records, reputation, and history follow your DID across platforms
-- **Cryptographically verifiable** — every record you create is signed by your DID's key pair, and anyone can verify the signature
+A DID such as `did:plc:z72i7hdynmk6r22z27h6tvur` identifies an AT Protocol account independently of its current handle or PDS host. DID resolution provides the service location and verification methods needed by AT Protocol clients.
 
-Your DID resolves via the [PLC directory](https://plc.directory) to a DID document containing your current PDS, public signing keys, and handle.
+AT-URIs include this DID. For example, `at://did:plc:example/org.hypercerts.claim.activity/3k7` attributes the record slot to that repository. A CID identifies one version of the record contents.
 
-## How identity connects to the protocol
+Do not describe every actor-like field as a DID:
 
-| Layer | How identity is used |
-|-------|---------------------|
-| **Data** | Every record (activity claims, evaluations, measurements) carries the author's DID. The PDS signs records into a Merkle tree, making authorship tamper-evident. |
-| **Trust** | Evaluators build reputation tied to their DID. Applications can weight evaluations based on the evaluator's history and credentials. |
-| **Funding** | Funding receipts link funder DIDs to the work they support. Wallet linkage (work-in-progress) connects DIDs to on-chain addresses for payment flows and tokenization. |
-| **Portability** | Switching PDS providers doesn't change your DID. Your entire history — claims, evaluations, contributions — migrates with you. |
+- Activity contributor identities can contain a DID or another identifier string.
+- Contributor information can identify a person through a DID or social-profile URI by convention.
+- Evaluation `evaluators` are DID objects, but the schema does not require one of them to be the repository publisher.
+- Receipt parties can be text, a DID, or a strong reference to another record.
 
-## Certified: the reference identity provider
+## Organization records
 
-[Certified](https://certified.app) is the identity provider built for the Hypercerts ecosystem. It provisions the full identity stack in a single sign-up:
+An organization can use an AT Protocol account containing two singleton records:
 
-- **A DID** — your permanent identifier
-- **A PDS** — your Personal Data Server, where records are stored
-- **Low-friction sign-in** — email and code, no passwords or protocol knowledge required
+- `app.certified.actor.profile/self` for general profile information.
+- `app.certified.actor.organization/self` for organization-specific metadata.
 
-Certified exists because most Hypercerts users are not Bluesky users. Researchers, land stewards, open-source maintainers, and funders need an entry point that doesn't require knowledge of ATProto or decentralized protocols. Certified provides that — a neutral identity provider that isn't tied to any single application.
+Their association is the shared repository identity and `self` key. The released schemas do not define members, administrators, ownership, or links from an organization to its projects. Multi-user repository governance is an infrastructure concern described in the [Certified Group Service](/architecture/certified-group-service) Reference.
 
-[`certified.app`](https://certified.app) is the frontend where your Certified identity is managed day-to-day: sign up, sign in, update your profile, change your handle, create groups, and manage passwords. It talks to the production Certified PDS at `certified.one` under the hood.
+## Corroboration records
 
-### Handles (your public username)
+The graph can accumulate independent responses without changing the original assertion:
 
-Handles are not needed to log in to the Hypercerts ecosystem, but every user has one. They serve as human-readable names for publicly addressing others and for interacting with other applications in the AT Protocol ecosystem that haven't implemented email-based login with Certified. Your handle (e.g., `alice.certified.one`) is human-readable but not permanent — it's a pointer to your DID. Organizations can use **custom domain handles** (e.g., `numpy.org`) to prove organizational identity through DNS verification.
+- An acknowledgement accepts or rejects a subject or relationship from another repository.
+- A badge response records a response to a badge award separately from the award itself.
+- An evaluation can cite measurements and publish its own assessment of a subject.
+- Optional signatures can attest to record content through a verification method or proof record.
 
-For setup details, see [Account & Identity Setup](/architecture/account-and-identity).
+None of these relationships is automatically reciprocal. An award does not imply acceptance, a contributor mention does not prove participation, and an evaluation does not prove independence merely because it is stored separately.
 
-## Compatible with Bluesky and other AT Protocol accounts
+## From provenance to trust
 
-{% callout type="note" %}
-Hypercerts is fully interoperable with the AT Protocol ecosystem. If you already have a Bluesky account or any other ATProto identity, you can log in with your existing handle (e.g., `alice.bsky.social`) and use all Hypercerts applications — no additional account needed.
-{% /callout %}
+A compatible application should show or preserve:
 
-## Wallet linkage
+1. The source AT-URI and version CID.
+2. The repository DID that published the record.
+3. Actors named inside the record.
+4. Acknowledgements, responses, signatures, and evidence that corroborate or challenge it.
+5. The application's own inclusion, ranking, and authority policy.
 
-To receive on-chain funding, a DID needs to be linked to an on-chain wallet address. This is handled by [**IdentityLink**](https://identitylink.vercel.app/) — a cryptographic attestation system that binds a DID to one or more on-chain addresses via a signed proof stored in your PDS. For the Ethereum ecosystem this looks like:
+This supports plural trust models. A community, certifier, funder, and automated agent can evaluate the same graph differently while working from attributable source records.
 
-1. Authenticates the user via ATProto OAuth
-2. Connects an EVM wallet (EOA, Smart Wallet, or Safe)
-3. Signs an EIP-712 typed message proving ownership
-4. Stores the attestation in the user's PDS
+## Certified as one access path
 
-The attestation is self-sovereign (stored in your PDS, not a central database) and verifiable by anyone. See the [Roadmap](/roadmap) for current IdentityLink status.
+[Certified](https://certified.app) provides Hypercerts-oriented accounts and organization tooling. It is one provider and application surface, not the identity layer of the protocol itself. Existing AT Protocol identities may be usable where an application supports their authentication and the required permissions.
 
-## Next steps
+For account creation, OAuth, service environments, and organization-managed writes, use [Account & Identity Setup](/architecture/account-and-identity) and [Client Integration](/client-integration).
 
-- [Account & Identity Setup](/architecture/account-and-identity) — create an account, configure custom domains, manage app passwords, and set up organization accounts
-- [Architecture Overview](/architecture/overview) — how identity fits into the protocol stack
-- [Quickstart](/getting-started/quickstart) — create your first hypercert
-
-Next: [Why AT Protocol?](/core-concepts/why-at-protocol) — how identity and records stay portable across apps.
+Next: [Work Scopes & Classification](/core-concepts/cel-work-scopes).
diff --git a/pages/core-concepts/common-use-cases.md b/pages/core-concepts/common-use-cases.md
index 7d69700..78fd741 100644
--- a/pages/core-concepts/common-use-cases.md
+++ b/pages/core-concepts/common-use-cases.md
@@ -1,49 +1,39 @@
 ---
 title: Common Use Cases
-description: See how hypercerts work for different types of contributions.
+description: See how common funding and evaluation scenarios map to the Hypercerts record graph.
 ---
 
 # Common Use Cases
 
-Hypercerts work for any kind of impact work. This page shows four common scenarios and how they map to the hypercerts data model.
+These examples show how domain workflows can use the same record graph. They are conceptual mappings, not tested SDK or XRPC instructions.
 
 ## Open-source software maintenance
 
-A team maintains a widely-used library. They create a hypercert covering a year of maintenance — bug fixes, documentation updates, and community support.
-
-```typescript
-const result = await agent.com.atproto.repo.createRecord({
-  repo: agent.session.did,
-  collection: "org.hypercerts.claim.activity",
-  record: {
-    title: "Library maintenance, 2025",
-    shortDescription: "Ongoing maintenance of an open-source library",
-    description: "Fixed 47 bugs, reviewed 120 pull requests, updated documentation, and provided community support on Discord.",
-    workScope: { allOf: ["Software Development", "Open Source"] },
-    startDate: "2025-01-01T00:00:00Z",
-    endDate: "2025-12-31T23:59:59Z",
-    $type: "org.hypercerts.claim.activity",
-    createdAt: new Date().toISOString(),
-  },
-});
-```
-
-The team then attaches links to the repository, release notes, and commit history. Contribution records identify who did what — core developers, documentation leads, community managers. Organizations that depend on the library can fund this work retroactively.
+A team publishes an activity for a year of library maintenance. Contributor entries describe maintainers and roles. Attachments link releases and reports; measurements describe issues resolved or downloads; peer evaluators publish assessments. A project collection can group annual activities, and receipts can record prospective or retroactive support.
 
 ## Regenerative land stewardship
 
-A conservation group restores degraded forest over several years. The activity claim covers the full project timeline (2020–2025) with work scopes like "Ecosystem Restoration" and "Biodiversity Conservation".
-
-Measurement records track hectares restored, native species planted, and carbon sequestration estimates. Location records anchor the work geographically. Attachments include satellite imagery, biodiversity surveys, and field reports. Climate funders can review the full record before deciding to support the next phase.
+A project collection with `type: "project"` groups restoration activities and the land areas they concern. Feature records represent zones or strata; location records provide spatial representations. Attachments link satellite imagery and reports, measurements describe observations, and community or expert evaluations assess the work. Receipts can point to the project collection or a specific activity.
 
 ## Scientific research
 
-A research team completes a multi-year study and wants to document the effort with clear contributor roles. The activity claim describes the research and its outputs, with contribution records identifying the principal investigator, postdocs, and graduate students along with their relative contributions.
-
-Attachments link to published papers (via DOI), lab notebooks, and experimental protocols. Evaluation records capture peer review outcomes. Research foundations or industry partners interested in the field can fund the work.
+A research activity identifies contributors and reusable contribution details. Attachments link papers, data, and protocols. Measurements can describe outputs; evaluations record peer assessments and cite relevant measurements. A funding receipt records support but does not establish research quality or payment settlement by itself.
 
 ## Community event organization
 
-A group runs regular workshops teaching practical skills to underrepresented communities. They want to document their educational impact. The activity claim covers the full year of workshops with work scopes like "Education" and "Community Building".
+A program collection groups workshop activities and optional cohort features. Contributor entries identify instructors and hosts. Attachments provide materials and reports; measurements record attendance or outcomes; participant or expert evaluations add assessments. Acknowledgements can confirm particular relationships without turning them into protocol-wide truth.
+
+## Certifications and network recognition
+
+A network or certifier publishes a badge definition and then an award whose subject is an account or project record. The recipient can publish a separate badge response. The award does not imply acceptance, and the definition's issuer list requires application-level authorization checks.
+
+## What remains application-specific
+
+In every scenario, applications still decide:
+
+- Which publishers, evaluators, certifiers, and vocabularies they trust.
+- Which records their index includes and how backlinks are resolved.
+- How source data becomes forms, search, rankings, totals, or recommendations.
+- How private operational data and payment execution stay outside public records.
 
-Measurement records track total attendees, completion rates, and outcomes. Contribution records identify instructors, venue hosts, and curriculum developers. Attachments include workshop materials and participant feedback. Organizations with community programs can review the record and decide to fund future sessions.
+For implementation status, use [Client Integration](/client-integration). For exact schemas, use the [Lexicon inventory](/reference/lexicon-inventory).
diff --git a/pages/core-concepts/funding-and-value-flow.md b/pages/core-concepts/funding-and-value-flow.md
index 07a1df4..0a905e1 100644
--- a/pages/core-concepts/funding-and-value-flow.md
+++ b/pages/core-concepts/funding-and-value-flow.md
@@ -1,107 +1,69 @@
 ---
 title: "Funding & Value Flow"
-description: How hypercerts track the funding of activities.
+description: What released funding receipts record, how they connect to work, and what they do not prove.
 ---
 
 # Funding & Value Flow
 
-{% callout type="note" %}
-Funding is under active development.
-{% /callout %}
-
-Hypercerts track the funding of activities without prescribing how funds flow — any payment method and any funding mechanism works.
-
-What hypercerts add is a structured, verifiable record of who funded what.
+Hypercerts can describe funding without prescribing a payment rail or funding mechanism. The released `org.hypercerts.funding.receipt` schema records an assertion about a funding payment. It does not execute or independently verify that payment.
 
 ## Hypercerts work with any funding mechanism
 
-Funding can be **prospective** (before work begins) or **retroactive** (after outcomes are demonstrated). Different mechanisms suit different contexts, for example:
+Funding can be prospective, concurrent, or retroactive. A receipt can be used around grants, crowdfunding, matching, bounties, purchases, or other mechanisms when the parties can represent the event with the released fields.
 
-| Mechanism | Description |
-|-----------|-------------|
-| **Grant funding** | Funders award grants to support planned activities |
-| **Milestone-based funding** | Funds are released as work reaches defined milestones |
-| **Prize competitions** | Awards for achieving specific outcomes |
-| **Quadratic funding** | Small donations amplified through matching pools |
-| **Sale of impact certificates** | Funders purchase certificates representing completed work |
-| **Auction of impact certificates** | Competitive bidding on verified impact claims |
-
-Multiple mechanisms can coexist for the same activity — a project might receive a grant prospectively and sell impact certificates retroactively. Hypercerts tracks this accurately without double counting: every funding receipt references the specific activity claim it funds, making it possible to compute total funding per claim across all receipts.
+The protocol records funding context. It does not define eligibility, allocation, matching, settlement, refunds, or ownership semantics for those mechanisms.
 
 ## Tracking funding
 
-{% callout type="note" %}
-Funding tracking is in active development. Receipts and acknowledgements exist today.
-{% /callout %}
-
-Hypercerts separate the *tracking* of funding from the *flow* of funds. Any existing payment infrastructure can work with hypercerts — the protocol simply records the fact that funding happened.
-
-The protocol tracks funding through the `org.hypercerts.funding.receipt` record. A funding receipt records who funded which activity, how much, and when — creating a verifiable funding trail. The receipt references the activity claim it funds, linking the funding record to the work it supports.
-
-Funding receipts are typically created by a **facilitator** — a payment processor, grant platform, funding app, or other intermediary that processes the payment and creates the receipt. The facilitator acts as a neutral third party, giving the receipt more credibility than a self-reported claim.
-
-| Scenario | Facilitator | Verification |
-|----------|-------------|--------------|
-| **On-chain funding** | A funding app verifies the transaction and creates the receipt, linking the transaction hash and chain ID | Verifiable on-chain |
-| **Card / bank transfer** | A payment processor settles the payment and creates the receipt | Trust in the processor |
-| **Grant platform** | The grant platform records the award and creates the receipt on behalf of the funder | Trust in the platform |
-
-The funder or the contributor can then create an **acknowledgement** — a counter-signature confirming the receipt's accuracy — to strengthen its credibility.
-
-The protocol does not enforce that projects or funders disclose their funding — creating a receipt is voluntary. Funders can also choose to remain anonymous in the public record; a receipt can track a contribution without revealing the funder's identity.
-
-## Tokenization
-
-{% callout type="note" %}
-Tokenization is under active development. This section describes the planned architecture.
-{% /callout %}
-
-A hypercert can optionally be wrapped in an on-chain token. This gives funders a programmable proof of their contribution. Tokenization is an optional wrapper around a claim snapshot; the canonical record remains the AT Protocol data.
-
-When locking is available, a claim can be frozen before tokenization. This gives funders a stronger guarantee — the claim they reviewed is exactly the claim they funded, and it cannot change after the fact.
-
-| Property | Detail |
-|----------|--------|
-| **Token standards** | ERC-20, ERC-1155, or custom — different standards on different chains |
-| **Transferability** | Ranges from non-transferable recognition to fully transferable certificates |
-| **Single-wrap constraint** | Every claim can only be wrapped in a token once, preventing double counting |
-| **Rights** | Optional definition of the rights of the owners, set in the hypercert's `org.hypercerts.claim.rights` record |
-
-Tokenization enables programmable funding — smart contract logic can enforce distribution rules, matching formulas, and other mechanisms that would be difficult to coordinate offchain.
+The receipt has four required fields:
 
-## Example: from creation to funding
+- `to`: the recipient, represented by free text, a DID, or a strong reference.
+- `amount`: a string representing the amount.
+- `currency`: a string identifying the payment currency.
+- `createdAt`: the record creation time.
 
-There are many different flows that can be represented with hypercerts. Below is one example that follows a hypercert from creation to funding.
+It can also include:
 
-### Stage 1 — Creation and evaluation
+- `from`: an optional sender. Omitting it allows an anonymous sender assertion.
+- `for`: a strong reference to the activity, project collection, organization record, or other subject funded.
+- Payment-rail, date, transaction, memo, and optional signature information.
 
-Alice plants 500 trees in a reforestation project and creates an activity claim with measurements and attachments. Bob, an environmental auditor, evaluates the claim from his own PDS. See [Quickstart](/getting-started/quickstart) for a walkthrough.
+The schema intentionally supports publishers other than the sender or recipient. A funding platform, grant program, payment processor, sender, or recipient can publish a receipt. Consumers should therefore distinguish the repository publisher from the parties named inside it.
 
-### Stage 2 — Funding
+## Connecting funding to work
 
-Carol, a climate funder, reviews Alice's claim and Bob's evaluation. She decides to fund Alice's work through her organization's grant platform. The payment facilitator processes the payment and creates a funding receipt, recording Carol's contribution and referencing Alice's activity claim.
+```mermaid
+flowchart LR
+  P["Receipt publisher"] -->|publishes| R["Funding receipt"]
+  R -->|from, optional| F["Sender"]
+  R -->|to, required| T["Recipient"]
+  R -->|for, optional strongRef| W["Activity, project, organization, or other record"]
+  A["Acknowledging actor"] -->|separate record| K["Acknowledgement"]
+  K -->|subject| R
+```
 
-| Record | Owner |
-|--------|-------|
-| Funding receipt | Payment facilitator |
-| Acknowledgement | Alice or Carol |
+An acknowledgement can add an independently published acceptance or rejection. It is a relationship record, not a cryptographic counter-signature and not proof of bank or blockchain settlement.
 
-Either party can then create an acknowledgement — a counter-signature confirming the receipt's accuracy — to strengthen its credibility.
+## What applications must decide
 
-### Stage 3 — Locking
+The released schema does not guarantee:
 
-{% callout type="note" %}
-Locking is planned but not yet implemented.
-{% /callout %}
+- That a payment settled, was not refunded, or matches an external transaction.
+- That the publisher was authorized to speak for a named party.
+- That every relevant receipt has been published or indexed.
+- That duplicate or conflicting receipts have been removed.
+- That amount and currency strings can be safely summed without normalization.
 
-Alice locks the claim, freezing it so its contents can't change. This gives future funders a guarantee — the claim they review is exactly the claim they'll be funding.
+Applications should preserve source records, define accepted publishers and payment evidence, identify deduplication rules, and label derived totals as index-dependent.
 
-### Stage 4 — Retroactive funding
+## Current boundary
 
-Two years later, Eve assesses the health of Alice's trees and publishes a positive evaluation. Grace, a climate funder focused on proven outcomes, sees the original claim, both evaluations, and Carol's earlier funding. She funds the project retroactively with a new funding receipt referencing the same activity claim.
+The released 1.4.0 Lexicons do not define claim freezing, token wrapping, ownership fractions, auctions, or settlement. Those ideas may appear in historical or future design material, but they are not current protocol behavior and should not be inferred from a funding receipt.
 
 
 ## See also
 
-- [Architecture Overview](/architecture/overview) — how the full protocol stack fits together
-- [Data Flow & Lifecycle](/architecture/data-flow-and-lifecycle) — how a hypercert moves through the system
+- [Core Data Model](/core-concepts/hypercerts-core-data-model)
+- [Identity, Authorship & Trust](/core-concepts/certified-identity)
+- [Records, References & Lifecycle](/architecture/data-flow-and-lifecycle)
+- [Funding Receipt reference](/lexicons/hypercerts-lexicons/funding-receipt)
diff --git a/pages/core-concepts/hypercerts-core-data-model.md b/pages/core-concepts/hypercerts-core-data-model.md
index 2d2e6bc..09d998d 100644
--- a/pages/core-concepts/hypercerts-core-data-model.md
+++ b/pages/core-concepts/hypercerts-core-data-model.md
@@ -1,106 +1,120 @@
 ---
 title: Core Data Model
-description: The data model behind hypercerts — record types, dimensions, and how they connect.
+description: The released Hypercerts and Certified record families, their relationship directions, and the conventions layered on them.
 ---
 
 # Core Data Model
 
-A hypercert is an [activity claim](/lexicons/hypercerts-lexicons/activity-claim) with linked records that describe work done. The activity claim is the anchor — contributions, attachments, measurements, and evaluations reference it to add context.
+The released model is a graph of independently published AT Protocol records. It has no single aggregate object containing a complete project, all evidence, and every assessment. Applications assemble a view from records they can discover and choose to interpret.
 
-This page explains what records exist, what they contain, and how they connect.
+This page describes `@hypercerts-org/lexicon` 1.4.0. See the [Lexicon inventory](/reference/lexicon-inventory) for the exact released surface.
 
-## The core record: activity claim
+## Relationship map
 
-Every hypercert starts with an **activity claim** — the central record that answers four questions:
+Arrows show the direction stored in the source record. Reverse discovery, such as finding every evaluation of an activity, requires an indexer that has observed those records.
 
-| Dimension | Question | Example |
-|-----------|----------|---------|
-| **Contributors** | Who is doing (or did) the work? | Alice, Bob |
-| **Work scope** | What are they doing (or what did they do)? | Documentation, Reforestation |
-| **Time of work** | When is it happening (or when did it happen)? | January – March 2026 |
-| **Location** | Where is it taking (or did it take) place? | Coastal Kenya |
+```mermaid
+flowchart LR
+  A["Activity claim"] --> CI["Contributor information"]
+  A --> C["Contribution details"]
+  A --> R["Rights"]
+  A --> L["Location"]
+  A --> WS["Embedded work scope"]
+  WS --> WST["Work-scope tags"]
 
-The activity claim gets a permanent AT-URI like `at://did:plc:alice123/org.hypercerts.claim.activity/3k7`.
+  COL["Collection"] --> A
+  COL --> F["Feature"]
+  COL --> COL
+  COL --> VT["Vocabulary tags"]
+  F --> L
+  F --> VT
 
-## Additional details
+  ATT["Attachment"] --> A
+  M["Measurement"] --> A
+  E["Evaluation"] --> A
+  E --> M
+  FR["Funding receipt"] --> A
+  ACK["Acknowledgement"] --> A
 
-The activity claim has a `contributors` array. Each entry is a contributor object with three fields:
+  BA["Badge award"] --> A
+  BA --> BD["Badge definition"]
+  BR["Badge response"] --> BA
+```
 
-- **`contributorIdentity`** — either an inline identity object (`#contributorIdentity`, containing an `identity` DID string) or a strong reference to an `org.hypercerts.claim.contributorInformation` record with a full social profile
-- **`contributionWeight`** — an optional relative weight string (e.g. `"1"`, `"0.5"`)
-- **`contributionDetails`** — either an inline role object (`#contributorRole`, containing a `role` string) or a strong reference to an `org.hypercerts.claim.contribution` record with structured contribution data
+The diagram uses an activity as an example subject. Attachments, measurements, evaluations, funding receipts, acknowledgements, and badge awards can refer to other records where their schemas allow it.
 
-Simple cases use inline objects directly in the activity claim. Richer profiles use separate records that the contributor or project lead creates independently.
+## Activities and contribution detail
 
-| Record type | What it adds | Who creates it | Lexicon |
-|-------------|-------------|----------------|---------|
-| **Contributor Information** | Social profile, image, display name | The contributor or project lead | `org.hypercerts.claim.contributorInformation` |
-| **Contribution** | Structured role and contribution data | The contributor or project lead | `org.hypercerts.claim.contribution` |
+`org.hypercerts.claim.activity` describes work. Its required fields are `title`, `shortDescription`, and `createdAt`. Contributors, work scope, dates, locations, rights, and signatures are optional, so "who, what, when, and where" is recommended conceptual coverage rather than the minimum valid shape.
 
-## Records that attach to a hypercert
+An activity can contain contributor entries. Each entry can keep identity and role information inline or point outward to reusable records:
 
-Other records link to the activity claim to add context. Again, each is a separate record with its own AT-URI – they reference the activity claim, not the other way around.
+- `org.hypercerts.claim.contributorInformation` provides identifier and presentation details.
+- `org.hypercerts.claim.contribution` provides a role, description, and optional timeframe.
+- `org.hypercerts.claim.rights` describes rights or licensing terms and is referenced directly by the activity.
 
-The following diagram shows record types and how they reference the activity claim. Records can be created by different people and live in different repositories.
+These reusable records do not point back to the activity. The activity contains the relationship.
 
-{% figure src="/images/hypercert-erd.svg" alt="Hypercert record relationships" /%}
+## Projects, collections, and features
 
-The diagram includes a **token** entity — tokenization (anchoring a hypercert on-chain) is not yet implemented.
+`org.hypercerts.collection` groups activities, `org.hypercerts.entity.feature` records, and nested collections. Each item contains a strong reference and may have a weight.
 
-| Record type | What it adds | Who creates it | Lexicon |
-|-------------|-------------|----------------|---------|
-| **Attachment** | Supporting documentation — URLs, uploaded files, IPFS links. Can link to any record type, not only activity claims. | Anyone with additional data | `org.hypercerts.context.attachment` |
-| **Measurement** | Quantitative data — "12 pages written", "50 tons CO₂ reduced" | E.g. a third-party measurer or the project (self-reported) | `org.hypercerts.context.measurement` |
-| **Evaluation** | An (independent) assessment of the work | E.g. a third-party evaluator, community members, beneficiaries | `org.hypercerts.context.evaluation` |
+{% callout type="note" %}
+A project is not a separate Lexicon. The shared convention is an `org.hypercerts.collection` record with `type: "project"`. The `type` field is optional and open, so applications must implement this convention. Project membership is stored from the collection to its items; activities have no project field.
+{% /callout %}
 
-### Additional notes
+A feature represents a non-agent subject, such as a geographic zone, ecological stratum, participant cohort, or campaign. It can carry locations, general vocabulary tags, and external identifiers. Collections can group features with the activities concerning them.
 
-- Records don't have to be created together. Users can create a measurement first and link it to an activity claim later. 
-- A record can also be linked to multiple other records, e.g. a measurement in a bioregion is linked to multiple activity claims.
-- An evaluator creates an evaluation from their own account — it references an activity claim but lives in their personal data server.
+## Context records
 
-This means a hypercert grows over time – it is a living record. The core claim stays the same, but attachments, measurements, and evaluations accumulate around it.
+Context records can be published after their subjects and from different repositories:
 
-## Grouping hypercerts
+| Record | Stored relationship | Important limit |
+|---|---|---|
+| `org.hypercerts.context.attachment` | Optional plural `subjects` | An attachment may be evidence, commentary, a report, or another content type; it does not verify itself. |
+| `org.hypercerts.context.measurement` | Optional plural `subjects`; optional measurer DIDs and evidence URIs | The schema does not establish methodology quality or measurer authority. |
+| `org.hypercerts.context.evaluation` | Optional singular `subject`; optional measurement references | Named evaluators are not automatically corroborated by the repository publisher. |
+| `org.hypercerts.context.acknowledgement` | Required `subject`; optional relationship `context` | Acknowledgement is an independent acceptance or rejection record, not an automatic counter-signature. |
 
-Hypercerts can be grouped into **collections**. A multi-year project might have one hypercert per year, with a collection representing the full project. But collections are flexible — anyone can create one for any purpose. Someone might curate a personal collection of hypercerts they find interesting, or an organization might group all their hypercerts together. A hypercert can belong to many collections.
+An activity does not have to be changed when new context is published. The graph grows as indexers discover records that point to it.
 
-| Record type | What it adds | Who creates it | Lexicon |
-|-------------|-------------|----------------|---------|
-| **Collection** | Groups activity claims and/or other collections into a project or portfolio. Supports recursive nesting. | E.g. the project organizer | `org.hypercerts.collection` |
+## Funding records
 
-## How records connect
+`org.hypercerts.funding.receipt` describes a claimed funding payment. It requires a recipient, amount, currency, and creation time. The sender and funded subject are optional. Parties may be represented by text, a DID, or a record reference.
 
-Records reference each other using [strong references](/reference/glossary#strong-reference) — if a referenced record is modified after the reference was created, the change is detectable.
+A receipt can point to an activity, a project collection, an organization record, or another subject. It does not itself prove settlement or prevent duplicate and conflicting receipts. See [Funding Records & Value Flow](/core-concepts/funding-and-value-flow).
 
-```text
-Activity Claim (the core record)
-├── contributors[0]
-│   ├── contributorIdentity: {identity: "did:plc:alice..."} (inline #contributorIdentity or ref to ContributorInformation)
-│   ├── contributionWeight: "1"
-│   └── contributionDetails: {role: "Lead author"} (inline #contributorRole or ref to Contribution)
-├── contributors[1]
-│   ├── contributorIdentity: → ContributorInformation record (Bob)
-│   └── contributionDetails: → Contribution record (Technical reviewer, Jan-Mar)
-├── Attachment: GitHub repository link
-├── Measurement: 12 pages written
-├── Measurement: 8,500 words
-└── Evaluation: "High-quality documentation" (by Carol)
-```
+## Two classification systems
+
+The released model deliberately separates:
+
+- `org.hypercerts.workscope.tag`, referenced by the CEL expression embedded in an activity's work scope.
+- `org.hypercerts.vocab.tag`, used to classify collections and features.
+
+They have different purposes and hierarchy rules. They should not be treated as one interchangeable tag system. See [Work Scopes & Classification](/core-concepts/cel-work-scopes).
 
+## Adjacent Certified records
 
+The `app.certified.*` namespace supplies records that Hypercerts applications can use around the work graph:
 
-## Mutability
+- Actor profiles and organization metadata describe the repository identity. Their relationship comes from sharing the same repository and `self` record key, not an explicit link.
+- Location records provide reusable spatial representations.
+- Badge definitions, awards, and responses model recognition and recipient response.
+- Account follows and entity follows help clients define social and discovery scopes.
+- EVM link records connect a DID to an EVM address through a proof structure.
+- Signature definitions and proof records support optional record-content attestations.
 
-Activity claims and their linked records are currently immutable once created. Record versioning and edit history will be supported in a future release, along with the ability to lock a hypercert at a specific version for funding.
+These records complement Hypercerts but do not create organization membership, project ownership, evaluator independence, or universal trust rules.
 
+## References are typed by usage
 
-## What happens next
+The graph uses several relationship forms:
 
-Once you understand the data model, you're ready to build:
+- **Strong reference:** an AT-URI plus CID, used to pin one content version.
+- **AT-URI:** identifies a record slot without pinning a version, useful when a relationship should survive updates.
+- **DID:** identifies an AT Protocol account.
+- **Embedded object or string:** carries information by value rather than linking to another record.
 
-- **[Quickstart](/getting-started/quickstart)** — create your first activity claim
-- **[Quickstart](/getting-started/quickstart)** — build a complete hypercert with all record types
-- **[Lexicon reference](/lexicons/hypercerts-lexicons)** — field-by-field schema for every record type
+Most strong-reference target restrictions are described conventions rather than constraints enforced by the generic `strongRef` shape. Compatible applications must validate both the reference structure and the expected target semantics.
 
-Next: [Certified Identity](/core-concepts/certified-identity) — who authors records and how signatures work.
+Next: [Identity, Authorship & Trust](/core-concepts/certified-identity).
diff --git a/pages/core-concepts/validation-and-interpretation.md b/pages/core-concepts/validation-and-interpretation.md
new file mode 100644
index 0000000..b91ab87
--- /dev/null
+++ b/pages/core-concepts/validation-and-interpretation.md
@@ -0,0 +1,67 @@
+---
+title: Validation, Extension & Interpretation
+description: How structural Lexicon validation differs from semantic compatibility, and how clients handle extensions and derived views.
+---
+
+# Validation, Extension & Interpretation
+
+Passing Lexicon validation means a record has an accepted structural shape. It does not mean the record is true, authorized, complete, discoverable, or useful for a particular decision.
+
+## Three layers of validation
+
+| Layer | Typical checks | Who performs them |
+|---|---|---|
+| **Structural** | Required fields, primitive formats, lengths, unions, and referenced object shapes | SDKs, clients, validators, and indexers |
+| **Semantic** | Expected target collection, project convention, numeric ranges, chronology, tag policy, and role consistency | Compatible applications and indexers |
+| **Trust and policy** | Publisher authority, evaluator independence, evidence quality, payment verification, moderation, and ranking | Each application, community, or decision-maker |
+
+A PDS stores AT Protocol repository records. Do not assume it enforces every Hypercerts domain rule. Writers should validate before publication, and readers should validate untrusted records again.
+
+## Constraints beyond the Lexicons
+
+Several released conventions cannot be fully expressed by the schemas:
+
+- A project is a collection with `type: "project"`; `type` is optional and open.
+- Most strong-reference fields structurally accept any strong reference even when their descriptions name expected target collections.
+- Numeric amounts, weights, measurements, and scores are strings; meaningful ranges and arithmetic require application checks.
+- Required arrays can still be empty unless a minimum length is declared.
+- Date ordering, hierarchy cycles, record-key conventions, and cross-field equality require additional validation.
+- A named contributor, evaluator, issuer, sender, or recipient is not automatically the repository publisher.
+
+Compatible clients should document which of these rules they enforce on writes, reads, or both.
+
+## Open values and unknown data
+
+AT Protocol `knownValues` are not closed enums. A value outside the published list can remain structurally valid. Open unions similarly allow later record shapes.
+
+Readers should:
+
+1. Preserve unknown fields and values when round-tripping data.
+2. Display a safe fallback instead of assigning an invented meaning.
+3. Avoid rejecting an entire graph because one connected record is unknown.
+4. Record which Lexicon package version and usage conventions they support.
+
+## Extending the model
+
+Use a standard `org.hypercerts.*` or `app.certified.*` field when it fits the intended meaning. When an application needs data outside those schemas, publish a separate namespaced record that references the standard subject rather than adding unregistered fields and expecting other clients to interpret them.
+
+An extension becomes interoperable only when other consumers know its Lexicon and usage. Default Hypercerts indexers are not required to ingest application-specific namespaces.
+
+## Aggregation and derived views
+
+Search results, backlinks, totals, scores, and hydrated project views are derived from an indexer's observed records. They should retain links to source AT-URIs and state material policies such as:
+
+- Included repositories and record collections.
+- Accepted versions and extensions.
+- Handling of updates, deletions, and stale strong references.
+- Deduplication and conflict rules.
+- Trusted publishers or vocabulary authorities.
+- Moderation and ranking behavior.
+
+Derived data should not overwrite or masquerade as source assertions. Two indexers can legitimately produce different views from different coverage or policies.
+
+## Current compatibility boundary
+
+There are no ratified Hypercerts conformance classes or universal test suite. The current compatibility baseline is the released Lexicons plus documented shared conventions. API availability, SDK behavior, service support, and user-facing workflows have their own versions and should not be inferred from record schemas.
+
+Continue to [Client Integration](/client-integration) for tested implementation paths or [Reference](/reference) for exact contracts.
diff --git a/pages/core-concepts/what-is-hypercerts.md b/pages/core-concepts/what-is-hypercerts.md
index 354e984..026bb45 100644
--- a/pages/core-concepts/what-is-hypercerts.md
+++ b/pages/core-concepts/what-is-hypercerts.md
@@ -1,46 +1,52 @@
 ---
 title: What are Hypercerts?
-description: Living digital records of impact that help you track, share, and get recognized for the work you do.
+description: Shared records for describing valuable work and connecting it to context, assessment, and funding.
 ---
 
 # What are Hypercerts?
 
-A hypercert is a living record of impact work — a verifiable claim that grows as the creator and others add measurements, evaluations, and supporting evidence.
+A hypercert is an `org.hypercerts.claim.activity` record that describes valuable work. Other records can connect contributors, evidence, measurements, evaluations, acknowledgements, classifications, projects, and funding history to that activity over time.
 
-Think of it like this: you do meaningful work — restoring a forest, maintaining open-source software, running a community program, publishing research. A hypercert captures that work in a structured, verifiable record. Over time, the creator and others enrich it with measurements and evaluations — making it more trustworthy and more useful for recognition and funding.
+Together, these records form an open graph rather than one final certificate or document. Different people and organizations publish from their own AT Protocol repositories. Applications assemble the parts relevant to their users and preserve who published each assertion.
 
 ## The structure of a hypercert
 
-At its core, a hypercert answers four questions:
+The activity model is designed to answer four useful questions:
 
 - **Who** is doing (or did) the work?
 - **What** are they doing (or what did they do)?
 - **When** is it happening (or when did it happen)?
 - **Where** did it happen? (physical or digital)
 
-That's the starting point. From there, the record grows as people add more context:
+These are conceptual dimensions, not all required fields in the released schema. Version 1.4.0 requires a title, short description, and creation time; richer records add the dimensions needed for their use case.
 
-- **Attachments** — photos, links, datasets, documents, or descriptions that substantiate the work
-- **Measurements** — quantitative indicators that make the impact concrete ("142 issues resolved", "50 hectares restored"), which can be outputs or outcomes depending on the domain
-- **Evaluations** — independent qualitative or quantitative assessments from domain experts, community members, beneficiaries, etc.
-- **Contributions** — additional information about who was involved and what they contributed
-- **Rights** — what rights are attached to the hypercert (e.g. public display)
+Related records can add more context:
+
+- **Attachments:** documents, links, files, reports, or other material. An attachment may be evidence, but its existence does not verify its contents.
+- **Measurements:** quantitative observations, their units, methods, measurers, and evidence links.
+- **Evaluations:** assessments with named evaluators, summaries, optional scores, reports, and supporting measurements.
+- **Contributions:** reusable details about who was involved, their roles, and their periods of contribution.
+- **Collections:** group activities, non-agent features, and other collections into projects, programs, portfolios, or other sets.
+- **Funding receipts:** record assertions about funding payments and what they supported.
+- **Acknowledgements, badges, and signatures:** add independent signals about relationships, recognition, and provenance.
 
 
 
 ## What a hypercert is not
 
-- **Not a grant application** — it records work that has been done or is in progress, not a request for funding
-- **Not a token** — it's a data record, though onchain tokenization for funding is planned
-- **Not a single document** — it’s a collection of linked records that can grow over time
+- **Not a truth certificate:** valid structure and attributable publication do not prove a claim is correct.
+- **Not a payment rail:** a funding receipt describes a claimed transfer; Hypercerts does not settle the payment.
+- **Not a token:** the released protocol model is based on AT Protocol records.
+- **Not a single document:** related records can be published and updated independently across repositories.
+- **Not a complete global view:** finding every backlink requires an indexer, and every index has a coverage policy.
 
 ## How people use them
 
 **If you're doing the work**, you create a hypercert to make your contributions visible. Instead of writing reports that sit in a folder, you publish a verifiable record that any platform can display and build on.
 
-**If you're evaluating work**, you add your assessment to someone else's hypercert. Your evaluation lives on your own data server linking to their work. You build up reputation over time based on your assessments.
+**If you're evaluating work**, you publish an assessment from an AT Protocol repository and reference the record version you assessed. Applications can use your identity, evidence, and history as inputs to their own trust model.
 
-**If you're funding work**, you can see the full picture before deciding: the original claim, the attachments behind it, and what independent evaluators think. Funding decisions can be based on verifiable records — not just narratives, wordy applications, and guessing.
+**If you're funding work**, you can inspect attributable project information and assessments, then publish a receipt describing support. Whether that receipt proves settlement depends on its publisher and supporting data.
 
 **If you're building a platform**, you can read and write hypercerts using shared schemas. A funding platform, a project dashboard, and an evaluation tool can all work with the same data.
 
@@ -52,18 +58,18 @@ Say a team runs a coastal reforestation project. They create a hypercert:
 >
 > 50 hectares restored over 12 months (the activity claim). Satellite imagery confirms canopy coverage. An independent ecologist evaluates the work as "high-quality restoration with strong community engagement."
 
-The activity claim is the starting record. Over the following months, the team adds measurement data as new satellite imagery comes in. An independent evaluator reviews the project and attaches their assessment. A funder browsing the ecosystem sees the full picture — the claim, the evidence, and the evaluation — and decides to support the next phase.
+The activity claim is the starting record. Over the following months, the team or third parties publish measurements and attachments that refer to it. An evaluator can assess a specific version. An indexer can assemble those independently published records for a funding application, which may then record support with a funding receipt.
 
 ## Why it's built this way
 
 Hypercerts are designed to live beyond any single platform.
 This is why we built hypercerts on [AT Protocol](/core-concepts/why-at-protocol), a decentralized data layer that also powers Bluesky. This gives hypercerts some important properties:
 
-- **You own your data.** Your hypercerts live on your [Personal Data Server (PDS)](/architecture/overview) or on a hosted PDS of your choice, not on a single platform.
-- **It's portable.** You can move your data to a different server anytime. No lock-in.
-- **It's verifiable.** Every record is cryptographically signed. Anyone can check that it hasn't been tampered with.
-- **It works everywhere.** Any app that speaks the Hypercerts protocol can read and display your records. Learn more in the [Architecture Overview](/architecture/overview).
+- **Repository-controlled:** records live in an AT Protocol repository associated with the publisher's DID rather than only in one application's database.
+- **Portable:** the DID and AT-URIs do not encode the current server address, so repository migration can preserve record identifiers.
+- **Attributable:** signed repository commits let consumers verify which repository published a version; optional record-level attestations are a separate mechanism.
+- **Interoperable by agreement:** applications can understand records when they implement the released schemas and compatible usage conventions.
 
 ## Next step
 
-To see the records that make this work, read the [Core Data Model](/core-concepts/hypercerts-core-data-model).
+To see the full graph, including projects and adjacent Certified records, read the [Core Data Model](/core-concepts/hypercerts-core-data-model).
diff --git a/pages/core-concepts/why-at-protocol.md b/pages/core-concepts/why-at-protocol.md
index 754545f..e411077 100644
--- a/pages/core-concepts/why-at-protocol.md
+++ b/pages/core-concepts/why-at-protocol.md
@@ -5,34 +5,34 @@ description: Why the Hypercerts Protocol is built on AT Protocol.
 
 # Why AT Protocol?
 
-The Hypercerts Protocol is built on [AT Protocol](https://atproto.com/docs) — the same open protocol for decentralized data that powers Bluesky.
+The Hypercerts Protocol is built on [AT Protocol](https://atproto.com/docs), the open protocol for decentralized data that also powers Bluesky.
 
-In Hypercerts v0.1, every hypercert was an on-chain token — publishing one required a wallet, gas fees, and a blockchain transaction. This created friction for the contributors, researchers, and organizations the protocol is designed to serve. By moving the data layer to ATProto, creating a hypercert requires no wallet, no gas, and no transaction fees. On-chain anchoring is reserved for where it actually matters: funding and settlement.
+Earlier Hypercerts versions centered on onchain tokens. The current model uses AT Protocol repositories for rich, evolving work records. Publishing these records does not inherently require a blockchain wallet, gas, or a settlement transaction.
 
 ATProto gives hypercerts three properties that matter for impact funding: portable data, shared schemas, and a trust graph rooted in cryptographic identity.
 
 ## Portable, user-controlled data
 
-Contributions must outlive any single platform.
+Information about valuable work should be reusable beyond the application that collected it.
 
-Hypercert records are stored in signed user repositories hosted on Personal Data Servers (PDS). Each repository is cryptographically tied to a user's DID — not to the server hosting it. Contributors, evaluators, and funders choose where their data lives: on Hypercerts Foundation infrastructure, on third-party providers, or self-hosted. They can migrate at any time without losing records or needing anyone's permission.
+Hypercerts records are stored in AT Protocol repositories hosted on Personal Data Servers (PDSs). Each repository is addressed through a DID rather than a fixed server URL. An account migration that preserves the DID can therefore preserve record AT-URIs when the hosting location changes.
 
-Applications are views over user-owned data — not gatekeepers of it. See [Portability & Data Access](/architecture/portability-and-scaling).
+Applications can build views over source records without becoming the only database that defines those records. See [Public Data, Discovery & Portability](/architecture/portability-and-scaling).
 
 ## Shared schemas across applications
 
-For impact funding to work across applications, a contribution recorded in one app must be evaluable in another and fundable in a third — without bespoke integrations.
+For project information to be reused, a record written by one application needs an open shape that another application can parse.
 
-ATProto enables this through [lexicons](/lexicons/introduction-to-lexicons): shared, namespaced schemas that define how records are structured. Because lexicons are open, any app can create compatible records and any app can read them. No bilateral API integrations required.
+AT Protocol enables this through [Lexicons](/lexicons/introduction-to-lexicons): shared, namespaced schemas that define record structures. A client can implement those public schemas and usage conventions without obtaining a proprietary schema from the original application.
 
-Records reference each other via AT-URIs, forming a traversable graph: an evaluation references an activity claim, a funding receipt references both the claim and the funder. This graph is what indexers crawl to build queryable views. See [Hyperindex](/tools/hyperindex).
+Records reference accounts and other records through DIDs, AT-URIs, and strong references. Indexers can observe those forward links and build backlink queries and hydrated views. See [Records, References & Lifecycle](/architecture/data-flow-and-lifecycle).
 
-## A decentralized trust graph
+## Attributable inputs to trust
 
-ATProto provides persistent, portable identities via Decentralized Identifiers (DIDs). Every record carries its author's DID and cryptographic signature. Over time, these identities accumulate contribution records, evaluations, endorsements, and funding decisions — forming a durable impact trust graph that persists across platforms.
+AT Protocol provides account identity through DIDs and attributes repository publication through signed commits. Hypercerts adds records that can name contributors, evaluators, issuers, funders, and subjects. These named actors may differ from the repository publisher.
 
-Trust becomes computable across the ecosystem — not siloed within individual platforms. A funder can trace who evaluated a project, what else those evaluators have assessed, and how their past judgments correlated with outcomes. Because all records are signed and publicly indexable, trust models can be independently implemented, compared, and audited.
+This gives applications attributable inputs for their own trust models. It does not establish one trust score, verify every named actor, or guarantee that every public record has been indexed. See [Identity, Authorship & Trust](/core-concepts/certified-identity).
 
-## Data layer + ownership layer
+## Protocol boundary
 
-The design principle: keep rich, evolving contribution data off-chain (ATProto) and use on-chain systems only where immutability and settlement matter. ATProto handles the data layer — claims, attachments, evaluations, trust signals. On-chain anchoring and tokenization handle the funding layer — immutable snapshots, programmable funding, and settlement mechanisms. See [Architecture Overview](/architecture/overview) for how the layers fit together.
+The released Hypercerts Lexicons describe AT Protocol records. They do not define payment settlement, claim freezing, token ownership, or a canonical global index. Those capabilities can be implemented by applications or future schemas without changing the role of AT Protocol as the source-record layer.
diff --git a/pages/ecosystem/why-we-need-hypercerts.md b/pages/ecosystem/why-we-need-hypercerts.md
index cfe177a..abbcf78 100644
--- a/pages/ecosystem/why-we-need-hypercerts.md
+++ b/pages/ecosystem/why-we-need-hypercerts.md
@@ -5,6 +5,10 @@ description: Recognizing and rewarding value creators.
 
 # Why We Need Hypercerts
 
+{% callout type="warning" %}
+This is a vision and background essay. Its economic and ownership examples are not a description of the current released protocol. Use the [Guide](/guide) for the current model and [Funding Records & Value Flow](/core-concepts/funding-and-value-flow) for released funding semantics.
+{% /callout %}
+
 ## The Problem
 
 #### A Simple Observation
diff --git a/pages/getting-started/building-on-hypercerts.md b/pages/getting-started/building-on-hypercerts.md
index 62a7dc9..4755ae1 100644
--- a/pages/getting-started/building-on-hypercerts.md
+++ b/pages/getting-started/building-on-hypercerts.md
@@ -25,7 +25,7 @@ Create platforms that use hypercerts to structure contributions and distribute f
 
 - Retroactive funding rounds where evaluators assess completed work
 - Milestone-based grant systems that release funds as work progresses
-- Crowdfunding campaigns where backers receive fractional rights to impact claims
+- Crowdfunding campaigns that connect project information, partner review, and funding receipts
 - Quadratic funding mechanisms that allocate matching pools based on community support
 
 ### Evaluation Tools
@@ -37,21 +37,6 @@ Build services that help domain experts create structured, verifiable evaluation
 - Code quality analysis for open source software
 - Educational outcome measurement for learning programs
 
-```javascript
-// Example: Create an evaluation
-const evaluation = await agent.com.atproto.repo.createRecord({
-  repo: agent.session.did,
-  collection: "org.hypercerts.context.evaluation",
-  record: {
-    subject: { uri: claimUri, cid: claimCid },
-    evaluators: [{ did: "did:plc:ragtjsm2j2vknwkz3zp4oxrd" }],
-    summary: "Scientific rigor and reproducibility assessment",
-    $type: "org.hypercerts.context.evaluation",
-    createdAt: new Date().toISOString(),
-  },
-});
-```
-
 ### Dashboards & Explorers
 
 Aggregate and display hypercerts across the ecosystem:
@@ -61,7 +46,7 @@ Aggregate and display hypercerts across the ecosystem:
 - Impact maps visualizing geographic distribution of work
 - Timeline views tracking contribution history
 
-Read-only integrations require only an indexer connection — no PDS needed.
+Read-only integrations can fetch known source records without an authenticated PDS session. Cross-repository search and backlinks normally require an indexer, whose coverage and API contract must be evaluated separately.
 
 ### Impact Portfolios
 
@@ -85,7 +70,7 @@ Build AI systems that participate in the ecosystem:
 
 To query hypercerts efficiently, run your own indexer:
 
-1. **Subscribe to the relay firehose** for hypercert lexicon records
+1. **Choose a relay or repository ingestion scope** for the Hypercerts and Certified record collections you support
 2. **Parse and validate** incoming records against lexicon schemas
 3. **Store in a queryable database** (PostgreSQL, MongoDB, etc.)
 4. **Expose an API** for your application to query
@@ -98,26 +83,20 @@ The ecosystem works because platforms follow shared conventions:
 
 ### Use Standard Lexicons
 
-Use the standard `org.hypercerts.*` and `app.certified.*` lexicons for data that fits them — this is what makes your data interoperable across the ecosystem. Default indexers subscribe to these namespaces, so records using standard lexicons are automatically discoverable. If you need additional fields to extend the standard lexicons, create a [sidecar record](https://atproto.com/guides/lexicon-style-guide#design-patterns) that references the standard record via a strong reference. Since sidecars are likely application-specific, default indexers won't see them unless explicitly configured to index your namespace.
+Use the standard `org.hypercerts.*` and `app.certified.*` Lexicons for data that fits them. This gives other applications a public shape to implement, but discovery still depends on relay and indexer coverage. If you need data outside the standard schemas, create a [sidecar record](https://atproto.com/guides/lexicon-style-guide#design-patterns) in your own namespace and reference the standard subject with the relationship form appropriate to its lifecycle. Indexers must explicitly choose to ingest application-specific namespaces.
 
 You're also free to create new lexicons for use cases that don't fit the original schemas — ATProto is designed for this.
 
-### Use Strong References
-
-Always include CID when referencing records. The CID is a content hash of the record at the time you referenced it — if the record is later modified, the CID won't match, making tampering detectable.
+### Use the declared relationship shape
 
-```javascript
-// Good: includes CID
-{ uri: "at://did:plc:abc/org.hypercerts.claim.activity/123", cid: "bafyreiabc..." }
+Use a strong reference when the field requires an AT-URI and CID for one content version. Use DID fields for accounts and URI-only record subjects where the Lexicon deliberately models a relationship that survives updates. Do not substitute one reference form for another.
 
-// Bad: URI only (no tamper-evidence)
-{ uri: "at://did:plc:abc/org.hypercerts.claim.activity/123" }
-```
+See [Records, References & Lifecycle](/architecture/data-flow-and-lifecycle) and [Validation, Extension & Interpretation](/core-concepts/validation-and-interpretation) before publishing an extension.
 
 
 ## Next Steps
 
 - Read the [Lexicons reference](/lexicons/introduction-to-lexicons) to understand the data model
 - Explore the [Architecture overview](/architecture/overview) to see how components fit together
-- Try the [Quickstart](/getting-started/quickstart) to create your first hypercert
+- Follow the evolving [Client Integration](/client-integration) path for supported SDK and XRPC guidance
 - Join the community to discuss your integration plans
diff --git a/pages/getting-started/quickstart.md b/pages/getting-started/quickstart.md
deleted file mode 100644
index e8429d7..0000000
--- a/pages/getting-started/quickstart.md
+++ /dev/null
@@ -1,354 +0,0 @@
----
-title: Quickstart
-description: Create your first hypercert in under 5 minutes.
----
-
-# Quickstart
-
-Create your first hypercert. This guide uses TypeScript and Node.js v20+.
-
-## Create an account
-
-[Sign up at certified.app](https://certified.app). This gives you an AT Protocol identity and a PDS where your data is stored. (Already have a Bluesky or other ATProto account? That works too.)
-
-## Install dependencies
-
-```bash
-pnpm add @atproto/oauth-client-node @atproto/jwk-jose @atproto/api
-```
-
-{% callout type="info" %}
-Building a React app? Use `@atproto/oauth-client-browser` instead, alongside `@tanstack/react-query` for data fetching and caching.
-{% /callout %}
-
-## Authenticate
-
-Authentication uses AT Protocol OAuth. Your app needs a client metadata document hosted at a public URL:
-
-```typescript
-import { NodeOAuthClient } from "@atproto/oauth-client-node";
-import { JoseKey } from "@atproto/jwk-jose";
-import { Agent } from "@atproto/api";
-
-const client = new NodeOAuthClient({
-  clientMetadata: {
-    client_id: "https://your-app.example.com/client-metadata.json",
-    client_name: "My App",
-    client_uri: "https://your-app.example.com",
-    redirect_uris: ["https://your-app.example.com/callback"],
-    grant_types: ["authorization_code", "refresh_token"],
-    scope: "atproto transition:generic",
-    response_types: ["code"],
-    application_type: "web",
-    token_endpoint_auth_method: "private_key_jwt",
-    token_endpoint_auth_signing_alg: "RS256",
-    dpop_bound_access_tokens: true,
-    jwks_uri: "https://your-app.example.com/jwks.json",
-  },
-  keyset: await Promise.all([
-    JoseKey.fromImportable(process.env.PRIVATE_KEY_1, "key1"),
-    JoseKey.fromImportable(process.env.PRIVATE_KEY_2, "key2"),
-    JoseKey.fromImportable(process.env.PRIVATE_KEY_3, "key3"),
-  ]),
-  stateStore: { /* ... your state store implementation */ },
-  sessionStore: { /* ... your session store implementation */ },
-});
-
-// Redirect the user to their PDS to authorize
-const url = await client.authorize("alice.certified.one");
-
-// After the user approves, exchange the callback params for a session
-const { session } = await client.callback(new URLSearchParams(callbackQuery));
-
-// Wrap the session in an Agent to make authenticated calls
-const agent = new Agent(session);
-```
-
-See the [AT Protocol OAuth documentation](https://atproto.com/specs/oauth) for full details on client metadata, session storage, and keyset configuration. For further info on how to set up OAuth you can check out [AT Protos node.js implementation tutorial](https://atproto.com/guides/oauth-cli-tutorial) or the [scaffold app](/tools/scaffold).
-
-## Create your first hypercert
-
-The activity claim is the core record — it describes what work was done, when, and in what scope. Here's how each field maps to the [activity lexicon](/lexicons/hypercerts-lexicons/activity-claim):
-
-- **Contributors** are embedded directly in the activity claim as a `contributors` array. Each entry has a `contributorIdentity` (inline DID string, or a strong reference to a [`contributorInformation`](/lexicons/hypercerts-lexicons/contributor-information) record), an optional `contributionWeight`, and an optional `contributionDetails` (inline role string, or a strong reference to an [`org.hypercerts.claim.contribution`](/lexicons/hypercerts-lexicons/contribution) record for richer detail).
-- **Work scopes** can be a simple free-form string (`{ scope: "Documentation" }`) or a structured [CEL expression](/core-concepts/work-scopes) for machine-evaluable queries across the network.
-- **Time** is expressed as `startDate` and `endDate` in ISO 8601 format.
-- **Locations** are separate [`app.certified.location`](/lexicons/certified-lexicons/location) records referenced from the activity claim. They support coordinates, GeoJSON, and other formats.
-
-```typescript
-const result = await agent.com.atproto.repo.createRecord({
-  repo: agent.did,
-  collection: "org.hypercerts.claim.activity",
-  record: {
-    $type: "org.hypercerts.claim.activity",
-    title: "NumPy documentation maintenance, Q1 2026",
-    shortDescription: "Updated API docs and fixed 15 broken examples.",
-    description: "Created 12 new documentation pages covering quickstart, use cases, evaluations, and architecture. Migrated from GitBook to a custom Next.js + Markdoc site.",
-    workScope: {
-      $type: "org.hypercerts.claim.activity#workScopeString",
-      scope: "Documentation",
-    },
-    startDate: "2026-01-01T00:00:00Z",
-    endDate: "2026-03-31T23:59:59Z",
-    createdAt: new Date().toISOString(),
-  },
-});
-
-console.log(result.data.uri);
-// → at://did:plc:abc123/org.hypercerts.claim.activity/3k2j4h5g6f7d8s9a
-
-console.log(result.data.cid);
-// → bafyreiabc123...
-```
-
-Each AT-URI is a permanent, globally unique identifier. Other records (evaluations, attachments, measurements) reference your hypercert using its URI. The CID is a content hash that makes references tamper-evident. Save both — you'll need them to link other records to this hypercert. See the [Activity Claim lexicon](/lexicons/hypercerts-lexicons/activity-claim) for the complete schema.
-
-## Add contributions
-
-Contributors are embedded directly in the activity claim's `contributors` array. Each entry uses inline identity and role objects:
-
-```typescript
-const result = await agent.com.atproto.repo.createRecord({
-  repo: agent.did,
-  collection: "org.hypercerts.claim.activity",
-  record: {
-    $type: "org.hypercerts.claim.activity",
-    title: "NumPy documentation maintenance, Q1 2026",
-    shortDescription: "Updated API docs and fixed 15 broken examples.",
-    workScope: {
-      $type: "org.hypercerts.claim.activity#workScopeString",
-      scope: "Documentation",
-    },
-    startDate: "2026-01-01T00:00:00Z",
-    endDate: "2026-03-31T23:59:59Z",
-    contributors: [
-      {
-        contributorIdentity: {
-          $type: "org.hypercerts.claim.activity#contributorIdentity",
-          identity: "did:plc:alice123",
-        },
-        contributionWeight: "70",
-        contributionDetails: {
-          $type: "org.hypercerts.claim.activity#contributorRole",
-          role: "Lead author",
-        },
-      },
-      {
-        contributorIdentity: {
-          $type: "org.hypercerts.claim.activity#contributorIdentity",
-          identity: "did:plc:bob456",
-        },
-        contributionWeight: "30",
-        contributionDetails: {
-          $type: "org.hypercerts.claim.activity#contributorRole",
-          role: "Technical reviewer",
-        },
-      },
-    ],
-    createdAt: new Date().toISOString(),
-  },
-});
-```
-
-Each contributor entry has:
-- `contributorIdentity` — inline `#contributorIdentity` with a DID string, or a strong reference to an `org.hypercerts.claim.contributorInformation` record
-- `contributionWeight` — relative weight as a string (weights don't need to sum to 100)
-- `contributionDetails` — inline `#contributorRole` with a role string, or a strong reference to an `org.hypercerts.claim.contribution` record for richer detail
-
-## Attach supporting documentation
-
-Attachments link supporting documents, reports, or URLs to any record. Create an attachment record that references the hypercert:
-
-```typescript
-await agent.com.atproto.repo.createRecord({
-  repo: agent.did,
-  collection: "org.hypercerts.context.attachment",
-  record: {
-    $type: "org.hypercerts.context.attachment",
-    subjects: [{ uri: result.data.uri, cid: result.data.cid }],
-    title: "Documentation site repository",
-    shortDescription: "Source code and content for the Hypercerts Protocol documentation.",
-    content: [
-      {
-        $type: "org.hypercerts.defs#uri",
-        uri: "https://github.com/hypercerts-org/hypercerts-atproto-documentation",
-      },
-    ],
-    createdAt: new Date().toISOString(),
-  },
-});
-```
-
-The `subjects` field is an array of strong references (AT-URI + CID). The `content` field is an array of `org.hypercerts.defs#uri` objects (for URLs) or `org.hypercerts.defs#smallBlob` objects (for file uploads). You can create multiple attachment records — one for the repo, one for the deployed site, one for a methodology document, etc.
-
-## Add a measurement
-
-Measurements record quantitative data about the work. Create a measurement record that references the hypercert:
-
-```typescript
-await agent.com.atproto.repo.createRecord({
-  repo: agent.did,
-  collection: "org.hypercerts.context.measurement",
-  record: {
-    $type: "org.hypercerts.context.measurement",
-    subjects: [{ uri: result.data.uri, cid: result.data.cid }],
-    metric: "Documentation pages written",
-    value: "12",
-    unit: "pages",
-    startDate: "2026-01-01T00:00:00Z",
-    endDate: "2026-03-31T23:59:59Z",
-    methodType: "manual-count",
-    createdAt: new Date().toISOString(),
-  },
-});
-```
-
-Required fields are `metric`, `value`, and `unit`. The `subjects` array links the measurement to your hypercert via strong references. You can attach multiple measurements to the same hypercert — one per metric.
-
-## Add an evaluation
-
-Evaluations are third-party assessments of the work. They reference the hypercert via a single `subject` strong reference and are typically created by someone other than the hypercert author:
-
-```typescript
-await agent.com.atproto.repo.createRecord({
-  repo: agent.did,
-  collection: "org.hypercerts.context.evaluation",
-  record: {
-    $type: "org.hypercerts.context.evaluation",
-    subject: { uri: result.data.uri, cid: result.data.cid },
-    evaluators: [{ did: "did:plc:ragtjsm2j2vknwkz3zp4oxrd" }],
-    summary: "High-quality documentation with clear examples and thorough coverage.",
-    score: { min: 1, max: 5, value: 4 },
-    content: [
-      {
-        $type: "org.hypercerts.defs#uri",
-        uri: "https://example.com/evaluation-report.pdf",
-      },
-    ],
-    createdAt: new Date().toISOString(),
-  },
-});
-```
-
-Required fields are `evaluators`, `summary`, and `createdAt`. Unlike attachments and measurements, `subject` is a single strong reference (not an array). The optional `score` object takes integer `min`, `max`, and `value` fields.
-
-## What you've built
-
-Your hypercert now has a complete structure:
-
-```text
-Activity Claim (the core record)
-├── contributors[] (embedded)
-│   ├── Alice — identity: did:plc:alice123, weight: 70, role: Lead author
-│   └── Bob   — identity: did:plc:bob456,  weight: 30, role: Technical reviewer
-├── Attachment: GitHub repository link  ← strong reference (AT-URI + CID)
-├── Measurement: 12 pages written       ← strong reference (AT-URI + CID)
-└── Evaluation: "High-quality documentation" (by Carol)  ← strong reference (AT-URI + CID)
-```
-
-Contributors live inside the activity claim record itself. External records — attachments, measurements, evaluations — link to the activity claim via **strong references** (AT-URI + CID). The CID is a content hash: if the referenced record changes, the hash won't match, making the entire structure tamper-evident.
-
-This is the same pattern described in the [Core Data Model](/core-concepts/hypercerts-core-data-model#how-records-connect). As the hypercert grows over time, third parties can add measurements, evaluations, and more attachments — each as a separate record referencing your activity claim.
-
-## Create via the Scaffold App
-
-If you don't want to write code, the [Scaffold app](https://hypercerts-scaffold.vercel.app) lets you create a full hypercert through a guided wizard. Visit [hypercerts-scaffold.vercel.app](https://hypercerts-scaffold.vercel.app) to get started.
-
-### Step 1 — Sign in
-
-Enter your ATProto handle (e.g. `yourname.certified.one` or `yourname.bsky.social`) on the sign-in screen. You'll be redirected to your PDS to authorize the app. Once you approve, you'll land on the home screen with your DID and display name visible.
-
-![Scaffold sign-in screen showing handle input field](/images/scaffold/sign-in.png)
-*Enter your ATProto handle to authenticate via OAuth.*
-
-### Step 2 — Basic info
-
-Click **"Create a new hypercert"** on the home screen (or go directly to [hypercerts-scaffold.vercel.app/hypercerts/create](https://hypercerts-scaffold.vercel.app/hypercerts/create)). This opens a multi-step wizard. The first step collects the core fields that form the `org.hypercerts.claim.activity` record on your PDS.
-
-![Hypercert creation form showing title, description, work scope, and date fields](/images/scaffold/create-cert.png)
-*Step 1: Define the basic claim — what work was done, when, and in what scope.*
-
-| Field | Description |
-|---|---|
-| **Title** | A specific name for this piece of work. Be verbose — a project may have many hypercerts over time. Max 256 characters. Example: `NumPy documentation maintenance, Q1 2026`. |
-| **Short description** | A 1–3 sentence summary suitable for card previews and list views. Max 300 characters. |
-| **Description** | A longer narrative of what was done, by whom, and how. Supports rich text. Max 3,000 characters. |
-| **Work scope** | One or more tags that precisely define what work is included. Multiple tags are conjunctive — e.g. `Trees` + `Germany` means only tree-planting in Germany. Leave empty for an unconstrained scope. |
-| **Start date** | When the work began (ISO 8601). |
-| **End date** | When the work ended (ISO 8601). |
-| **Cover image** | An optional image for the hypercert card — URL or file upload. |
-| **Rights Information** | Required information about the rights to this hypercert |
-| **Contributors** *(optional)* | The people or organizations that did the work. Each contributor has an identity (DID or name), an optional relative weight, and an optional role description. You can add multiple contributors here or leave this empty. |
-
-### Step 3 — Add attachments
-
-Attach supporting documentation that backs up the claim — reports, URLs, files, or other references. Each attachment becomes an `org.hypercerts.context.attachment` record linked to your hypercert.
-
-![Evidence form for attaching supporting documentation](/images/scaffold/add-evidence.png)
-*Step 2: Attach supporting documentation to back up the claim.*
-
-| Field | Description |
-|---|---|
-| **Title** | A label for this attachment. Max 256 characters. Example: `GitHub repository`. |
-| **Attachment type** | The kind of attachment: `report`, `audit`, `evidence`, `testimonial`, `methodology`, etc. Max 64 characters. |
-| **Short description** | A brief summary of what this attachment contains. Max 300 characters. |
-| **Detailed description** | A detailed summary of what this attachment contains. (optional) |
-| **Content** | One or more URLs or file uploads that make up the attachment. Max 100 items. |
-
-### Step 4 — Add location *(optional)*
-
-Optionally anchor the work geographically. This creates an `app.certified.location` record referenced from your hypercert.
-
-![Location form for adding geographic context](/images/scaffold/add-location.png)
-*Step 3: Add location data to anchor the work geographically.*
-
-| Field | Description |
-|---|---|
-| **Name** | A human-readable place name. Example: `Amazon Basin, Brazil`. Max 100 characters. |
-| **Location type** | The format of the location data: `coordinate-decimal`, `geojson`, `address`, `h3`, `geohash`, `wkt`, etc. |
-| **Location Data** | The location data in the chosen format. Example for `coordinate-decimal`: `-3.47, -62.21`. |
-| **Location Description** | Optional context about the location. Max 500 characters. |
-
-### Step 5 — Add measurements *(optional)*
-
-Add quantitative data that makes the impact concrete — metrics, values, units, and measurement methods. Each entry becomes an `org.hypercerts.context.measurement` record.
-
-![Measurement form for adding quantitative impact data](/images/scaffold/add-measurement.png)
-*Step 4: Add measurements to quantify the impact.*
-
-| Field | Description |
-|---|---|
-| **Metric** | What is being measured. Example: `pages written`, `CO₂e avoided`, `users reached`. Max 500 characters. |
-| **Value** | The measured numeric value. Example: `12`. |
-| **Unit** | The unit of measurement. Example: `pages`, `kg CO₂e`, `hectares`, `count`. Max 50 characters. |
-| **Start / end date** | The period during which this measurement was taken. |
-| **Method type** | A short identifier for how it was measured. Example: `automated-count`, `manual-survey`. Max 30 characters. |
-| **Method URI** | A link to the methodology documentation or standard protocol. |
-
-### Step 6 — Add evaluations *(optional)*
-
-Add third-party assessments of the work. Evaluations are authored by evaluators and can reference measurements. Each entry becomes an `org.hypercerts.context.evaluation` record.
-
-![Evaluation form for adding third-party assessments](/images/scaffold/add-evaluation.png)
-*Step 5: Add evaluations from third-party assessors.*
-
-| Field | Description |
-|---|---|
-| **Evaluators** | DIDs or handles of the users who contributed to this evaluation |
-| **Summary** | A brief written assessment of the work. Max 1,000 characters. Example: `High-quality documentation with clear examples and thorough coverage.` |
-| **Score** *(optional)* | A numeric score on a defined scale. Set a minimum, maximum, and value — e.g. min 1, max 5, value 4. |
-| **Content** *(optional)* | Links to detailed evaluation reports or methodology documents — URLs or file uploads. |
-| **Measurement** *(optional)* | URI to the measurement tied to this evaluation. It can also be a normal URL. |
-
-### Step 7 — Done
-
-Your hypercert is now created and stored on your PDS. The completion screen shows the finalized record — copy the AT-URI to reference it from other records (attachments, measurements, evaluations) or to share it.
-
-![Completion screen showing the finished hypercert](/images/scaffold/finalized-cert.png)
-*The hypercert is created and stored on your PDS.*
-
-For full details on the Scaffold app — including self-hosting, environment setup, and extending the codebase — see the [Scaffold app documentation](/tools/scaffold).
-
-## Next steps
-
-Third parties can now [evaluate your hypercert](/getting-started/working-with-evaluations) by creating evaluation records and measurements on their own PDS.
diff --git a/pages/getting-started/testing-and-deployment.md b/pages/getting-started/testing-and-deployment.md
index db6e9fc..f35f0a4 100644
--- a/pages/getting-started/testing-and-deployment.md
+++ b/pages/getting-started/testing-and-deployment.md
@@ -35,7 +35,7 @@ Create dedicated test accounts — never use production identities for testing.
 
 ### Create and verify a test record
 
-Create a record using the same `createRecord` call from the [Quickstart](/getting-started/quickstart), then read it back to confirm it was stored correctly. The returned CID is a content hash — if the record changes, the CID changes, which is how you verify data integrity.
+Create a record using the same client path your application will use in production, then read it back to confirm it was stored correctly. The returned CID is a content hash. If the record changes, the CID changes, which is how you identify the version that was read.
 
 ### Clean up test data
 
@@ -69,7 +69,7 @@ All datetime fields must use ISO 8601 format (e.g., `2026-01-15T00:00:00Z`).
 
 ### Strong references
 
-When one record references another (e.g., an evaluation referencing an activity claim), the reference must include both the AT-URI and the CID. The CID is a content hash — if the referenced record is later modified, the CID won't match, making tampering detectable. If you need the current CID, fetch the record with `getRecord` before creating the reference.
+When a field uses `com.atproto.repo.strongRef`, include both the AT-URI and CID. Other declared relationship forms include DIDs and URI-only record subjects, so follow the target Lexicon rather than converting every relationship to a strong reference. If you need the current CID for a strong reference, fetch the record before creating the reference.
 
 ### String and array limits
 
@@ -138,7 +138,7 @@ If you accidentally publish PII, delete the record immediately and contact index
 
 ## Authentication in production
 
-Use OAuth for production applications. OAuth lets users authorize your app without sharing credentials. See the [Quickstart](/getting-started/quickstart) for the authentication setup and the [ATProto OAuth spec](https://atproto.com/specs/oauth) for the full protocol details.
+Use OAuth for production applications. OAuth lets users authorize your app without sharing credentials. See [Client Integration](/client-integration) for the evolving integration guidance and the [ATProto OAuth spec](https://atproto.com/specs/oauth) for the full protocol details.
 
 Instead of using generic [transitional](https://atproto.com/specs/oauth#authorization-scopes) permission scopes like `transition:generic` use [granular scopes](https://atproto.com/specs/permission) as much as possible. Example: `repo:org.hypercerts.claim.activity?action=create&action=update`.
 
@@ -160,7 +160,7 @@ Before deploying to production:
 
 ## See also
 
-- [Quickstart](/getting-started/quickstart) — create your first hypercert
+- [Client Integration](/client-integration) — review the target SDK and XRPC path and current gaps
 - [Lexicon reference](/lexicons/hypercerts-lexicons) — field definitions and constraints for each record type
 - [Architecture Overview](/architecture/overview) — how the protocol stack fits together, including the security model
-- [Data Flow & Lifecycle](/architecture/data-flow-and-lifecycle) — how records move through the system
+- [Records, References & Lifecycle](/architecture/data-flow-and-lifecycle) — how records change and connect across repositories
diff --git a/pages/getting-started/working-with-evaluations.md b/pages/getting-started/working-with-evaluations.md
deleted file mode 100644
index f29fd57..0000000
--- a/pages/getting-started/working-with-evaluations.md
+++ /dev/null
@@ -1,87 +0,0 @@
----
-title: Working with Evaluations
-description: Learn how to evaluate hypercerts and build trust in the ecosystem.
----
-
-# Working with Evaluations
-
-Evaluations are third-party assessments of hypercerts and other claims. They live on the evaluator's own PDS, not embedded in the original claim, and accumulate over time as different actors provide their perspectives.
-
-## Create an evaluation
-
-```typescript
-import { AtpAgent } from "@atproto/api";
-
-const agent = new AtpAgent({ service: "https://bsky.social" });
-await agent.login({
-  identifier: "evaluator.certified.app",
-  password: "your-app-password",
-});
-
-// Create an evaluation of an activity claim
-const evaluation = await agent.com.atproto.repo.createRecord({
-  repo: agent.session.did,
-  collection: "org.hypercerts.context.evaluation",
-  record: {
-    subject: {
-      uri: "at://did:plc:xyz789/org.hypercerts.claim.activity/3k2j4h5g6f7d8s9a",
-      cid: "bafyreiabc123...",
-    },
-    evaluators: ["did:plc:evaluator123"],
-    summary: "Verified documentation updates. All 15 examples tested and working. High quality contribution with clear impact on developer experience.",
-    $type: "org.hypercerts.context.evaluation",
-    createdAt: new Date().toISOString(),
-  },
-});
-
-console.log(evaluation.data.uri);
-```
-
-The `subject` is a strong reference (AT-URI + CID) to the claim being evaluated. The `evaluators` array contains DIDs of those conducting the assessment.
-
-## Add measurements
-
-Measurements provide quantitative data that supports your evaluation:
-
-```typescript
-const measurement = await agent.com.atproto.repo.createRecord({
-  repo: agent.session.did,
-  collection: "org.hypercerts.context.measurement",
-  record: {
-    subject: {
-      uri: "at://did:plc:xyz789/org.hypercerts.claim.activity/3k2j4h5g6f7d8s9a",
-      cid: "bafyreiabc123...",
-    },
-    metric: "Documentation page views",
-    unit: "views",
-    value: "12500",
-    measurers: ["did:plc:evaluator123"],
-    methodType: "analytics",
-    methodURI: "https://example.com/analytics-methodology",
-    evidenceURI: ["https://example.com/analytics-report.pdf"],
-    comment: "Page view data collected over the first 30 days after publication.",
-    $type: "org.hypercerts.context.measurement",
-    createdAt: new Date().toISOString(),
-  },
-});
-```
-
-The `subject` field is a strong reference (AT-URI + CID) to the claim being measured.
-
-You can then reference this measurement in an evaluation's `measurements` array (an array of strong references) to link quantitative data to your assessment.
-
-## Evaluation patterns
-
-**Expert review:** Domain experts assess technical quality, methodology, and impact. Their DID becomes a portable credential — other projects can discover and trust evaluations from recognized experts.
-
-**Community assessment:** Multiple stakeholders provide independent evaluations. The diversity of evaluator DIDs creates a richer signal than any single assessment.
-
-**Automated evaluation:** Scripts and bots can publish evaluations based on API metrics, external data sources, or other programmatic checks. The evaluator DID identifies the automation system and its operator.
-
-## Trust and reputation
-
-Every evaluation is signed by its creator's DID, creating accountability. Unlike anonymous reviews, evaluators build portable reputation across the ecosystem. A DID with a history of rigorous, accurate evaluations becomes a trusted signal. Projects can filter evaluations by evaluator identity, weight them differently, or build custom trust graphs based on their values and domain expertise.
-
-{% callout type="note" %}
-Evaluations are append-only. You can't delete someone else's evaluation of your work, and they can't delete yours. This creates a permanent, multi-perspective record of how claims are assessed over time.
-{% /callout %}
diff --git a/pages/guide/index.md b/pages/guide/index.md
new file mode 100644
index 0000000..8cde04f
--- /dev/null
+++ b/pages/guide/index.md
@@ -0,0 +1,69 @@
+---
+title: Guide
+description: Understand the Hypercerts Protocol, its data model, and the conventions that make records useful across applications.
+---
+
+# Guide
+
+Hypercerts gives valuable work, project context, assessments, and funding history shared formats that independent applications can reuse. This Guide explains the protocol model and the conventions that make those records meaningful together.
+
+Use the Guide to understand the system. Use [Client Integration](/client-integration) for tested implementation paths and [Reference](/reference) for exact schemas and service contracts.
+
+{% callout type="note" %}
+The current schema baseline is `@hypercerts-org/lexicon` 1.4.0. Hypercerts evolves through additive Lexicon releases and shared usage guidance. There is no ratified conformance specification or universal compatibility badge.
+{% /callout %}
+
+## What the protocol includes
+
+The practical protocol spans several layers:
+
+| Layer | Responsibility |
+|---|---|
+| **AT Protocol** | DIDs, repositories, record addressing, signed commits, Personal Data Servers (PDSs), and data portability |
+| **Released Lexicons** | The structural shapes for Hypercerts and Certified records |
+| **Shared usage guidance** | Conventions for concepts such as projects, references, attribution, classification, and interpretation |
+| **Applications and services** | Writing, discovery, indexing, aggregation, policy, and user experience |
+| **Change history** | Released additions, corrections, and migration context |
+
+Lexicons establish structural validity. They do not prove that work happened, that an evaluator is independent, that a receipt corresponds to a settled payment, or that an index contains every related record. Those judgments depend on provenance, corroboration, application policy, and evidence.
+
+```mermaid
+flowchart LR
+  A["Authors and organizations"] -->|publish| P["AT Protocol repositories"]
+  P --> H["Hypercerts and Certified records"]
+  H --> I["Relays and indexers"]
+  I --> X["Applications and agents"]
+  G["Lexicons and usage guidance"] -.shape and meaning.-> H
+  X -->|publish more context| P
+```
+
+## Follow the model
+
+{% card-grid %}
+{% card-link title="What are Hypercerts?" href="/core-concepts/what-is-hypercerts" %}
+Start with the problem, the protocol boundary, and what a hypercert represents.
+{% /card-link %}
+{% card-link title="Why AT Protocol?" href="/core-concepts/why-at-protocol" %}
+Understand the identity, record, and portability foundation.
+{% /card-link %}
+{% card-link title="Core Data Model" href="/core-concepts/hypercerts-core-data-model" %}
+See every released record family, relationship direction, and higher-level convention.
+{% /card-link %}
+{% card-link title="Common Use Cases" href="/core-concepts/common-use-cases" %}
+Map real scenarios to the record graph without depending on one application.
+{% /card-link %}
+{% /card-grid %}
+
+## Understand meaning and trust
+
+- [Identity, Authorship & Trust](/core-concepts/certified-identity) separates repository publishers, named actors, attestations, and application trust decisions.
+- [Work Scopes & Classification](/core-concepts/cel-work-scopes) distinguishes activity scope expressions from tags used to classify projects and features.
+- [Funding Records & Value Flow](/core-concepts/funding-and-value-flow) explains what a receipt records and what it does not prove.
+
+## Operate across repositories
+
+- [Records, References & Lifecycle](/architecture/data-flow-and-lifecycle) explains record slots, versions, strong references, updates, deletion, and backlink discovery.
+- [Public Data, Discovery & Portability](/architecture/portability-and-scaling) explains the difference between publication, availability, discovery, and indexed views.
+- [Validation, Extension & Interpretation](/core-concepts/validation-and-interpretation) separates schema checks from application semantics and explains safe extension.
+
+For an exact list of released schemas, continue to the [Lexicon inventory](/reference/lexicon-inventory).
diff --git a/pages/index.md b/pages/index.md
index df6620f..2b02d4b 100644
--- a/pages/index.md
+++ b/pages/index.md
@@ -1,36 +1,34 @@
 ---
 title: Hypercerts Documentation
-description: Documentation for the Hypercerts Protocol — structured, verifiable records of impact work built on AT Protocol.
+description: Guides, integration paths, technical reference, and change history for the Hypercerts Protocol.
 ---
 
-# Certified & Hypercerts Protocol
+# Hypercerts Documentation
 
-Certified is a place to record and recognize real work and impact. You publish activities, group them into projects, organize as groups, and back each other with endorsements — all on the open AT Protocol, so your account and everything you create stay portable across compatible apps instead of locked into one platform.
+The Hypercerts Protocol provides shared record formats and usage conventions for publishing information about work, evidence, evaluations, and funding on AT Protocol.
 
-Certified uses the Hypercerts Protocol. A hypercert is a structured, verifiable record of impact work — it captures who contributed, what they did, over what time period, and in what scope, along with measurements and supporting evidence. It's a living impact certificate — as evaluations, measurements, and new contributions are added, the record grows richer over time.
+The protocol does not currently have a separate formal specification. The Guide, available integration material, source-backed technical reference, and change history together describe how compatible applications use and evolve the protocol.
 
-## Get started
+## Choose a section
 
 {% card-grid %}
-{% card-link title="Quickstart" href="/getting-started/quickstart" icon="<svg viewBox=\"0 0 24 24\"><path stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M3.75 13.5l10.5-11.25L12 10.5h8.25L9.75 21.75 12 13.5H3.75z\"/></svg>" %}
-Create your first hypercert in under 5 minutes
+{% card-link title="Guide" href="/guide" %}
+Understand the protocol, its data model, and shared usage conventions.
 {% /card-link %}
-{% card-link title="Building on Hypercerts" href="/getting-started/building-on-hypercerts" icon="<svg viewBox=\"0 0 24 24\"><path stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M11.42 15.17l-5.384 3.161 1.028-5.995L2.28 7.823l6.02-.874L11.42 1.5l2.692 5.449 6.02.874-4.784 4.513 1.028 5.995-5.384-3.161z\"/></svg>" %}
-Integration patterns for platforms and tools
+{% card-link title="Client integration" href="/client-integration" %}
+Review the target path from authentication and record creation to discovery and display, including the current gaps.
 {% /card-link %}
-{% /card-grid %}
-
-## Core concepts
-
-{% card-grid %}
-{% card-link title="What are Hypercerts?" href="/core-concepts/what-is-hypercerts" icon="<svg viewBox=\"0 0 24 24\"><path stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M9.879 7.519c1.171-1.025 3.071-1.025 4.242 0 1.172 1.025 1.172 2.687 0 3.712-.203.179-.43.326-.67.442-.745.361-1.45.999-1.45 1.827v.75M21 12a9 9 0 11-18 0 9 9 0 0118 0zm-9 5.25h.008v.008H12v-.008z\"/></svg>" %}
-The record structure and why it's built on ATProto
-{% /card-link %}
-{% card-link title="Core Data Model" href="/core-concepts/hypercerts-core-data-model" icon="<svg viewBox=\"0 0 24 24\"><path stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M20.25 6.375c0 2.278-3.694 4.125-8.25 4.125S3.75 8.653 3.75 6.375m16.5 0c0-2.278-3.694-4.125-8.25-4.125S3.75 4.097 3.75 6.375m16.5 0v11.25c0 2.278-3.694 4.125-8.25 4.125s-8.25-1.847-8.25-4.125V6.375m16.5 0v3.75m-16.5-3.75v3.75m16.5 0v3.75C20.25 16.153 16.556 18 12 18s-8.25-1.847-8.25-4.125v-3.75m16.5 0c0 2.278-3.694 4.125-8.25 4.125s-8.25-1.847-8.25-4.125\"/></svg>" %}
-Record types, dimensions, and how they connect
+{% card-link title="Reference" href="/reference" %}
+Inspect Lexicons, service architecture, interfaces, environments, and tooling.
 {% /card-link %}
-{% card-link title="Why AT Protocol?" href="/core-concepts/why-at-protocol" icon="<svg viewBox=\"0 0 24 24\"><path stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M12 21a9.004 9.004 0 008.716-6.747M12 21a9.004 9.004 0 01-8.716-6.747M12 21c2.485 0 4.5-4.03 4.5-9S14.485 3 12 3m0 18c-2.485 0-4.5-4.03-4.5-9S9.515 3 12 3m0 0a8.997 8.997 0 017.843 4.582M12 3a8.997 8.997 0 00-7.843 4.582m15.686 0A11.953 11.953 0 0112 10.5c-2.998 0-5.74-1.1-7.843-2.918m15.686 0A8.959 8.959 0 0121 12c0 .778-.099 1.533-.284 2.253m0 0A17.919 17.919 0 0112 16.5c-3.162 0-6.133-.815-8.716-2.247m0 0A9.015 9.015 0 013 12c0-1.605.42-3.113 1.157-4.418\"/></svg>" %}
-Why the protocol is built on AT Protocol
+{% card-link title="Change history" href="/change-history" %}
+Track schema and component changes, compatibility notes, and migration guidance.
 {% /card-link %}
 {% /card-grid %}
 
+## Recommended path
+
+1. Start with the [Guide](/guide) to understand the model and common interpretation.
+2. Use [Client integration](/client-integration) for current integration material and known gaps.
+3. Consult the [Reference](/reference) for exact source-backed contracts.
+4. Review [Change history](/change-history) when upgrading an integration.
diff --git a/pages/lexicons/certified-lexicons/badge-award.md b/pages/lexicons/certified-lexicons/badge-award.md
index f29ce85..ff6517b 100644
--- a/pages/lexicons/certified-lexicons/badge-award.md
+++ b/pages/lexicons/certified-lexicons/badge-award.md
@@ -9,8 +9,8 @@ description: Lexicon reference for the Badge Award record type in Certified.
 
 Awards a badge to a user, project, or activity claim. Each award references a badge definition and a subject — either an account DID (for user badges) or a strong reference to a specific record like an activity claim (for project or work badges).
 
-Badge awards can include an optional note explaining why the badge was given. This creates a public record of recognition that can be verified by anyone.
+Badge awards can include an optional note explaining why the badge was given. Consumers can verify which repository published the record, but must separately decide whether that publisher was authorized to award the badge.
 
-Recipients can respond to badge awards using the badge response lexicon, allowing them to accept or reject badges and assign relative weights to accepted badges. This enables consent-based recognition where recipients have control over what badges appear on their profile.
+Recipients can respond to badge awards using the badge response Lexicon, accepting or rejecting a referenced award and optionally assigning a relative weight. Applications must verify that a response was published by the award's subject before treating it as the recipient's response.
 
-For the full schema, see [`app.certified.badge.award`](https://github.com/hypercerts-org/hypercerts-lexicon/blob/main/lexicons/app/certified/badge/award.json) in the lexicon repo.
+For the full released schema, see [`app.certified.badge.award` at v1.4.0](https://github.com/hypercerts-org/hypercerts-lexicon/blob/v1.4.0/lexicons/app/certified/badge/award.json).
diff --git a/pages/lexicons/certified-lexicons/badge-definition.md b/pages/lexicons/certified-lexicons/badge-definition.md
index 0a90dc6..c8d738a 100644
--- a/pages/lexicons/certified-lexicons/badge-definition.md
+++ b/pages/lexicons/certified-lexicons/badge-definition.md
@@ -7,10 +7,10 @@ description: Lexicon reference for the Badge Definition record type in Certified
 
 `app.certified.badge.definition`
 
-Defines a badge that can be awarded to users, projects, or activity claims. Each badge definition includes a title, description, icon, and badge type (like endorsement, participation, or affiliation).
+Defines a badge that can be awarded to accounts or records. A badge definition requires a title, badge type, and creation time; its description, icon, and issuer allowlist are optional.
 
-Badge definitions can optionally specify an allowlist of DIDs that are permitted to issue the badge. If no allowlist is provided, anyone can create badge awards using this definition. This enables both open badges (where anyone can award them) and restricted badges (where only specific issuers are authorized).
+Badge definitions can specify an allowlist of issuer DIDs. Applications must compare an award's repository publisher with this list; the generic repository schema does not enforce issuer authorization.
 
 Once created, a badge definition can be referenced by multiple badge award records. This separation allows the badge's visual identity and meaning to be defined once and reused many times.
 
-For the full schema, see [`app.certified.badge.definition`](https://github.com/hypercerts-org/hypercerts-lexicon/blob/main/lexicons/app/certified/badge/definition.json) in the lexicon repo.
+For the full released schema, see [`app.certified.badge.definition` at v1.4.0](https://github.com/hypercerts-org/hypercerts-lexicon/blob/v1.4.0/lexicons/app/certified/badge/definition.json).
diff --git a/pages/lexicons/certified-lexicons/badge-response.md b/pages/lexicons/certified-lexicons/badge-response.md
index cf427f3..02c8165 100644
--- a/pages/lexicons/certified-lexicons/badge-response.md
+++ b/pages/lexicons/certified-lexicons/badge-response.md
@@ -7,10 +7,10 @@ description: Lexicon reference for the Badge Response record type in Certified.
 
 `app.certified.badge.response`
 
-A recipient's response to a badge award. Recipients can accept or reject badges, and can optionally assign a relative weight to accepted badges to indicate their importance or relevance.
+A response to a badge award. The record can accept or reject a referenced award and can optionally assign a relative weight.
 
-Badge responses are created in the recipient's own repository, making them independently verifiable. This enables consent-based recognition — rather than assuming that receiving a badge implies acceptance, responses make consent explicit.
+The schema does not require the response repository to match the award subject. Applications must perform that identity check before interpreting a response as the recipient's consent.
 
 The weight field allows recipients to curate their badge display, emphasizing badges they consider most significant. Applications can use these weights to determine how prominently to display different badges on a user's profile.
 
-For the full schema, see [`app.certified.badge.response`](https://github.com/hypercerts-org/hypercerts-lexicon/blob/main/lexicons/app/certified/badge/response.json) in the lexicon repo.
+For the full released schema, see [`app.certified.badge.response` at v1.4.0](https://github.com/hypercerts-org/hypercerts-lexicon/blob/v1.4.0/lexicons/app/certified/badge/response.json).
diff --git a/pages/lexicons/certified-lexicons/index.md b/pages/lexicons/certified-lexicons/index.md
index 35a58c1..2e58b96 100644
--- a/pages/lexicons/certified-lexicons/index.md
+++ b/pages/lexicons/certified-lexicons/index.md
@@ -5,13 +5,20 @@ description: Lexicon reference for Certified identity records — profiles, loca
 
 # Certified Lexicons
 
-These lexicons live in the `app.certified` namespace. They provide shared data structures for identity, profiles, badges, and location — building blocks that other, more specialized lexicons can reference.
+These Lexicons live in the `app.certified` namespace. They provide shared records for profiles, organizations, badges, follows, locations, EVM links, and record-content attestations.
 
 | Lexicon | NSID | Description |
 |---------|------|-------------|
-| **[Shared Definitions](/lexicons/certified-lexicons/shared-defs)** | `app.certified.defs` | Common type definitions: the `did` type |
+| **[Shared Definitions](/lexicons/certified-lexicons/shared-defs)** | `app.certified.defs` | Embedded DID and URI-only record-subject definitions |
 | **[Location](/lexicons/certified-lexicons/location)** | `app.certified.location` | Geographic location representation using the Astral Location Protocol |
 | **[Profile](/lexicons/certified-lexicons/profile)** | `app.certified.actor.profile` | Account profile with display name, description, avatar, and banner |
 | **[Badge Definition](/lexicons/certified-lexicons/badge-definition)** | `app.certified.badge.definition` | Defines a badge type with title, icon, and optional issuer allowlist |
 | **[Badge Award](/lexicons/certified-lexicons/badge-award)** | `app.certified.badge.award` | Awards a badge to a user, project, or activity claim |
 | **[Badge Response](/lexicons/certified-lexicons/badge-response)** | `app.certified.badge.response` | Recipient accepts or rejects a badge award |
+| **Organization** | `app.certified.actor.organization` | Organization metadata in the account's singleton record |
+| **Follow** | `app.certified.graph.follow` | Account-to-account follow |
+| **Entity Follow** | `app.certified.graph.entityFollow` | Follow of a record subject by AT-URI |
+| **EVM Link** | `app.certified.link.evm` | DID-to-EVM-address link with proof data |
+| **Signature Proof** | `app.certified.signature.proof` | Remote proof containing an attested content CID |
+
+The package also includes `app.certified.signature.defs` and the `app.certified.authWrite` permission set. See the complete [Lexicon inventory](/reference/lexicon-inventory). Use the released package for exact field constraints until all field pages are generated.
diff --git a/pages/lexicons/certified-lexicons/location.md b/pages/lexicons/certified-lexicons/location.md
index 18bd437..78576ab 100644
--- a/pages/lexicons/certified-lexicons/location.md
+++ b/pages/lexicons/certified-lexicons/location.md
@@ -11,4 +11,4 @@ A location record implementing the [Astral Location Protocol](https://spec.decen
 
 Locations can be represented in multiple formats: decimal coordinates, GeoJSON, H3 indices, geohashes, etc. Each record includes a Spatial Reference System (SRS) URI so coordinate values are unambiguous. See the [location type registry](https://spec.decentralizedgeo.org/specification/location-types/#location-type-registry) for the full list of supported formats.
 
-For the full schema, see [`app.certified.location`](https://github.com/hypercerts-org/hypercerts-lexicon/blob/main/lexicons/app/certified/location.json) in the lexicon repo.
+For the full released schema, see [`app.certified.location` at v1.4.0](https://github.com/hypercerts-org/hypercerts-lexicon/blob/v1.4.0/lexicons/app/certified/location.json).
diff --git a/pages/lexicons/certified-lexicons/profile.md b/pages/lexicons/certified-lexicons/profile.md
index 23de427..20b204f 100644
--- a/pages/lexicons/certified-lexicons/profile.md
+++ b/pages/lexicons/certified-lexicons/profile.md
@@ -9,4 +9,4 @@ description: Lexicon reference for the Profile record type in Certified.
 
 A user profile in the Certified ecosystem. This is a singleton record — each account has exactly one, stored with the key `self`. Includes display name, avatar, banner image, description, website URL, and pronouns.
 
-For the full schema, see [`app.certified.actor.profile`](https://github.com/hypercerts-org/hypercerts-lexicon/blob/main/lexicons/app/certified/actor/profile.json) in the lexicon repo.
+For the full released schema, see [`app.certified.actor.profile` at v1.4.0](https://github.com/hypercerts-org/hypercerts-lexicon/blob/v1.4.0/lexicons/app/certified/actor/profile.json).
diff --git a/pages/lexicons/certified-lexicons/shared-defs.md b/pages/lexicons/certified-lexicons/shared-defs.md
index 0ea0823..97e2073 100644
--- a/pages/lexicons/certified-lexicons/shared-defs.md
+++ b/pages/lexicons/certified-lexicons/shared-defs.md
@@ -7,8 +7,11 @@ description: Reusable type definitions shared across Certified lexicons.
 
 `app.certified.defs`
 
-Common type definitions used across the certified ecosystem. Currently defines the `did` type, which represents a Decentralized Identifier.
+Common embedded definitions used across the Certified and Hypercerts Lexicons. Version 1.4.0 defines:
 
-The `did` type is used throughout the certified and hypercerts lexicons to reference accounts and actors. It ensures consistent formatting and validation of DIDs across all record types.
+- `did`: an object containing a DID-formatted account identifier.
+- `recordSubject`: an object containing an AT-URI, used when a relationship should follow a record slot without pinning one CID.
 
-For the full schema, see [`app.certified.defs`](https://github.com/hypercerts-org/hypercerts-lexicon/blob/main/lexicons/app/certified/defs.json) in the lexicon repo.
+These are embedded object definitions, not repository record collections.
+
+For the full released schema, see [`app.certified.defs` at v1.4.0](https://github.com/hypercerts-org/hypercerts-lexicon/blob/v1.4.0/lexicons/app/certified/defs.json).
diff --git a/pages/lexicons/hypercerts-lexicons/acknowledgement.md b/pages/lexicons/hypercerts-lexicons/acknowledgement.md
index adae159..4a89d8e 100644
--- a/pages/lexicons/hypercerts-lexicons/acknowledgement.md
+++ b/pages/lexicons/hypercerts-lexicons/acknowledgement.md
@@ -52,4 +52,4 @@ A project lead disagrees with an evaluation of their work and wants to flag it.
 
 The rejection doesn't delete the evaluation — it creates a counter-signal that applications can use to present both sides.
 
-For the full schema, see [`org.hypercerts.context.acknowledgement`](https://github.com/hypercerts-org/hypercerts-lexicon/blob/main/lexicons/org/hypercerts/context/acknowledgement.json) in the lexicon repo.
+For the full released schema, see [`org.hypercerts.context.acknowledgement` at v1.4.0](https://github.com/hypercerts-org/hypercerts-lexicon/blob/v1.4.0/lexicons/org/hypercerts/context/acknowledgement.json).
diff --git a/pages/lexicons/hypercerts-lexicons/activity-claim.md b/pages/lexicons/hypercerts-lexicons/activity-claim.md
index bd91558..9877d81 100644
--- a/pages/lexicons/hypercerts-lexicons/activity-claim.md
+++ b/pages/lexicons/hypercerts-lexicons/activity-claim.md
@@ -7,10 +7,10 @@ description: Lexicon reference for the Activity Claim record type — the core r
 
 `org.hypercerts.claim.activity`
 
-The activity claim is the core hypercert record — the anchor point for all impact tracking. It represents a durable, referenceable statement that a clearly bounded piece of work is planned, ongoing, or completed.
+The activity claim is the core hypercert work record. It represents a referenceable statement about work that is planned, ongoing, or completed.
 
-An activity claim defines work using four core dimensions: who performed it, what was done, when it happened, and where it took place. By making work precisely scoped and inspectable, activity claims become stable reference points that others can build on. Contributions, attachments, measurements, evaluations, and funding receipts all reference back to an activity claim.
+Who, what, when, and where are useful conceptual dimensions, but contributors, work scope, dates, and locations are optional in the released schema. Other records can reference an activity, while contributor information, contribution details, rights, and locations are referenced from the activity.
 
 The activity claim supports rich descriptions with text formatting, cover images, contributor lists with weights and roles, work scope definitions, time ranges, location references, and rights declarations. It's designed to be flexible enough to represent everything from open-source software maintenance to forest stewardship to research projects.
 
-For the full schema, see [`org.hypercerts.claim.activity`](https://github.com/hypercerts-org/hypercerts-lexicon/blob/main/lexicons/org/hypercerts/claim/activity.json) in the lexicon repo.
+For the full released schema, see [`org.hypercerts.claim.activity` at v1.4.0](https://github.com/hypercerts-org/hypercerts-lexicon/blob/v1.4.0/lexicons/org/hypercerts/claim/activity.json).
diff --git a/pages/lexicons/hypercerts-lexicons/attachment.md b/pages/lexicons/hypercerts-lexicons/attachment.md
index 290d67a..8dfcd47 100644
--- a/pages/lexicons/hypercerts-lexicons/attachment.md
+++ b/pages/lexicons/hypercerts-lexicons/attachment.md
@@ -7,8 +7,8 @@ description: Lexicon reference for the Attachment record type in Hypercerts.
 
 `org.hypercerts.context.attachment`
 
-An attachment links supporting documentation to one or more existing records. It can reference files, documents, external URIs, or IPFS content, and can attach to any record type via strong references.
+An attachment can link documentary material or other context to zero or more records. Its optional `subjects` array uses strong references, and its optional content can include URI or blob objects.
 
-Attachments are useful for providing evidence, documentation, or additional context for hypercerts. For example, you might attach a research paper to an activity claim, link a GitHub repository to a software project, or include photos documenting environmental work. Each attachment includes a title, optional description, the URI or content reference, and an array of strong references to the records it supports.
+Only `title` and `createdAt` are required. Description, subjects, content, content type, location, and signatures are optional. Applications should not assume that every attachment is evidence or that its contents verify a subject.
 
-For the full schema, see [`org.hypercerts.context.attachment`](https://github.com/hypercerts-org/hypercerts-lexicon/blob/main/lexicons/org/hypercerts/context/attachment.json) in the lexicon repo.
+For the full released schema, see [`org.hypercerts.context.attachment` at v1.4.0](https://github.com/hypercerts-org/hypercerts-lexicon/blob/v1.4.0/lexicons/org/hypercerts/context/attachment.json).
diff --git a/pages/lexicons/hypercerts-lexicons/collection.md b/pages/lexicons/hypercerts-lexicons/collection.md
index 13a08af..a33aa21 100644
--- a/pages/lexicons/hypercerts-lexicons/collection.md
+++ b/pages/lexicons/hypercerts-lexicons/collection.md
@@ -7,8 +7,10 @@ description: Lexicon reference for the Collection record type in Hypercerts.
 
 `org.hypercerts.collection`
 
-A collection groups activity claims into a named set. A single hypercert can belong to multiple collections at the same time — for example, one collection representing a multi-year reforestation program, another curating a funder's portfolio, and a personal "favorites" list. Collections make it easy to organize and surface hypercerts in different contexts without duplicating data.
+A collection groups activity claims, feature records, and other collections into a named set. The same record can be referenced by multiple collections, such as a project, program, portfolio, or favorites list.
 
-Each collection has a title, description, and an array of strong references to the claims it contains.
+Each optional `items` entry is an object containing an `itemIdentifier` strong reference and an optional `itemWeight`. Collections can also reference one location and general vocabulary tags.
 
-For the full schema, see [`org.hypercerts.collection`](https://github.com/hypercerts-org/hypercerts-lexicon/blob/main/lexicons/org/hypercerts/collection.json) in the lexicon repo.
+A project is represented by the shared convention `type: "project"`; it is not a separate record type. The `type` field is optional and open, so consumers must implement the convention.
+
+For the full released schema, see [`org.hypercerts.collection` at v1.4.0](https://github.com/hypercerts-org/hypercerts-lexicon/blob/v1.4.0/lexicons/org/hypercerts/collection.json).
diff --git a/pages/lexicons/hypercerts-lexicons/contribution.md b/pages/lexicons/hypercerts-lexicons/contribution.md
index 1198825..b0c8fba 100644
--- a/pages/lexicons/hypercerts-lexicons/contribution.md
+++ b/pages/lexicons/hypercerts-lexicons/contribution.md
@@ -11,23 +11,23 @@ This page covers two related lexicons that work together to represent contributo
 
 `org.hypercerts.claim.contributorInformation`
 
-Stores identity information for a contributor: display name, identifier (like a GitHub username or email), and an optional profile image. This record can be created once and referenced from multiple activity claims, making it easy to maintain consistent contributor identity across projects.
+Stores presentation and identifier information for a contributor: display name, an optional identifier described as a DID or social-profile URI, and an optional image. The schema does not validate the identifier as a DID or URI.
 
-A contributor doesn't need a full `contributorInformation` record. The activity claim's `contributors` array accepts either a strong reference to a `contributorInformation` record or an inline identity string (typically a DID). Use the inline form for simple cases; use the record when you want a reusable profile with a display name and image.
+A contributor does not need a separate `contributorInformation` record. The activity claim's contributor entry accepts either a strong reference to that record or an inline `contributorIdentity` object containing an `identity` string. The inline value is an object, not a bare string.
 
-For the full schema, see [`org.hypercerts.claim.contributorInformation`](https://github.com/hypercerts-org/hypercerts-lexicon/blob/main/lexicons/org/hypercerts/claim/contributorInformation.json) in the lexicon repo.
+For the full released schema, see [`org.hypercerts.claim.contributorInformation` at v1.4.0](https://github.com/hypercerts-org/hypercerts-lexicon/blob/v1.4.0/lexicons/org/hypercerts/claim/contributorInformation.json).
 
 ## Contribution
 
 `org.hypercerts.claim.contribution`
 
-Stores details about a specific contribution, including the contributor's role, a description of what they did, and the timeframe of their work. Like contributor identity, contribution details can be provided inline (as a role string) or as a strong reference to a separate record.
+Stores details about a contribution, including an optional role, description, and timeframe. Contribution details in an activity can be an inline `contributorRole` object containing a `role` string or a strong reference to this separate record. The inline value is not a bare string.
 
 The activity claim's `contributors` array also supports contribution weights to indicate relative effort or impact.
 
 ## Choosing contribution weights
 
-Weights are always proportional. The protocol stores them as strings and does not enforce any particular calculation method. How you arrive at the numbers is up to you. The following are just examples — pick whatever approach fits your project, or invent your own.
+Weights are intended as positive relative values. The protocol stores them as strings and does not enforce numeric syntax, normalization, or a calculation method. The following are application-policy examples, not protocol requirements.
 
 ### Equal split
 
@@ -82,4 +82,4 @@ Example: A team weights roles at 40% and peer scores at 60%. Alice (lead, peer s
 Weights are stored as strings and do not need to sum to any particular value. These examples all produce relative values — what matters is the ratio between contributors, not the absolute numbers.
 {% /callout %}
 
-For the full schema, see [`org.hypercerts.claim.contribution`](https://github.com/hypercerts-org/hypercerts-lexicon/blob/main/lexicons/org/hypercerts/claim/contribution.json) in the lexicon repo.
+For the full released schema, see [`org.hypercerts.claim.contribution` at v1.4.0](https://github.com/hypercerts-org/hypercerts-lexicon/blob/v1.4.0/lexicons/org/hypercerts/claim/contribution.json).
diff --git a/pages/lexicons/hypercerts-lexicons/evaluation.md b/pages/lexicons/hypercerts-lexicons/evaluation.md
index b0b4ddc..a34f70b 100644
--- a/pages/lexicons/hypercerts-lexicons/evaluation.md
+++ b/pages/lexicons/hypercerts-lexicons/evaluation.md
@@ -7,8 +7,8 @@ description: Lexicon reference for the Evaluation record type in Hypercerts.
 
 `org.hypercerts.context.evaluation`
 
-An evaluation is a structured assessment of a hypercert or other record. Third parties — auditors, peer reviewers, grant programs — use evaluations to assess whether claimed work actually happened and had the stated impact. It includes the evaluator's DID, a summary of their assessment, an optional numeric score, and can reference measurements that informed the evaluation.
+An evaluation is a structured assessment. It requires an `evaluators` array, a summary, and a creation time. It can identify one primary `subject`, reference supporting measurements, attach report content, and include a string-based score range.
 
-An evaluation can reference multiple records (for example, assessing a collection and all its constituent claims), and can cite specific measurements as evidence. This creates a traceable chain from raw data through measurements to final assessments.
+The `subject` is optional and singular. Measurements are a separate plural relationship. The schema does not require the named evaluators to be the repository publisher, require a non-empty evaluator array, establish independence, or enforce numeric score ordering.
 
-For the full schema, see [`org.hypercerts.context.evaluation`](https://github.com/hypercerts-org/hypercerts-lexicon/blob/main/lexicons/org/hypercerts/context/evaluation.json) in the lexicon repo.
+For the full released schema, see [`org.hypercerts.context.evaluation` at v1.4.0](https://github.com/hypercerts-org/hypercerts-lexicon/blob/v1.4.0/lexicons/org/hypercerts/context/evaluation.json).
diff --git a/pages/lexicons/hypercerts-lexicons/funding-receipt.md b/pages/lexicons/hypercerts-lexicons/funding-receipt.md
index 07f2da6..51d8b66 100644
--- a/pages/lexicons/hypercerts-lexicons/funding-receipt.md
+++ b/pages/lexicons/hypercerts-lexicons/funding-receipt.md
@@ -7,10 +7,10 @@ description: Lexicon reference for the Funding Receipt record type in Hypercerts
 
 `org.hypercerts.funding.receipt`
 
-A funding receipt records a funding payment from one party to another. It's typically created by a facilitator or funding platform, but can be created by either the funder or recipient.
+A funding receipt records an assertion about a funding payment. It can be published by a facilitator, platform, sender, recipient, or another party.
 
-Each receipt includes the funder's DID, the recipient's DID, the amount and currency, the payment rail used (like bank transfer, crypto, or grant platform), and an optional transaction ID for verification. Receipts can reference the activity claims or collections they fund, creating a traceable link from funding to impact work.
+The required fields are `to`, `amount`, `currency`, and `createdAt`. The sender, funded subject, payment rail, payment date, and transaction identifier are optional. Sender and recipient values can use free text, a DID, or a strong reference.
 
-Funding receipts enable transparent funding tracking and make it possible to see who funded what work. They're designed to be simple and flexible enough to represent everything from traditional grants to crypto payments to in-kind contributions.
+The optional `for` strong reference can connect a receipt to an activity, project collection, organization record, or another subject. A structurally valid receipt does not itself prove settlement, authorization, uniqueness, or acknowledgement by either party.
 
-For the full schema, see [`org.hypercerts.funding.receipt`](https://github.com/hypercerts-org/hypercerts-lexicon/blob/main/lexicons/org/hypercerts/funding/receipt.json) in the lexicon repo.
+For the full released schema, see [`org.hypercerts.funding.receipt` at v1.4.0](https://github.com/hypercerts-org/hypercerts-lexicon/blob/v1.4.0/lexicons/org/hypercerts/funding/receipt.json).
diff --git a/pages/lexicons/hypercerts-lexicons/index.md b/pages/lexicons/hypercerts-lexicons/index.md
index 3fb4dbc..21833af 100644
--- a/pages/lexicons/hypercerts-lexicons/index.md
+++ b/pages/lexicons/hypercerts-lexicons/index.md
@@ -5,16 +5,21 @@ description: Lexicon reference for Hypercerts record types — activity claims,
 
 # Hypercerts Lexicons
 
-These lexicons define the record types for tracking impact work in the `org.hypercerts` namespace. The **activity claim** is the central record — all other types attach to it.
+These Lexicons define work, context, grouping, feature, funding, and classification records in the `org.hypercerts` namespace. An activity claim is the central work record, but not every record type attaches to an activity.
 
 | Lexicon | NSID | Description |
 |---------|------|-------------|
-| **[Activity Claim](/lexicons/hypercerts-lexicons/activity-claim)** | `org.hypercerts.claim.activity` | The core hypercert record — who did what, when, where |
+| **[Activity Claim](/lexicons/hypercerts-lexicons/activity-claim)** | `org.hypercerts.claim.activity` | The core record describing work; contributor, scope, time, and location detail is optional |
 | **[Contribution](/lexicons/hypercerts-lexicons/contribution)** | `org.hypercerts.claim.contributorInformation`{% br /%}`org.hypercerts.claim.contribution` | Contributor identity and contribution details (two lexicons) |
 | **[Attachment](/lexicons/hypercerts-lexicons/attachment)** | `org.hypercerts.context.attachment` | Supporting documentation — URLs, files, IPFS links |
 | **[Measurement](/lexicons/hypercerts-lexicons/measurement)** | `org.hypercerts.context.measurement` | Quantitative data attached to a claim |
 | **[Evaluation](/lexicons/hypercerts-lexicons/evaluation)** | `org.hypercerts.context.evaluation` | Third-party assessment of a claim |
 | **[Collection](/lexicons/hypercerts-lexicons/collection)** | `org.hypercerts.collection` | Groups activity claims and/or other collections into a project |
 | **[Rights](/lexicons/hypercerts-lexicons/rights)** | `org.hypercerts.claim.rights` | Rights associated with a hypercert |
-| **[Funding Receipt](/lexicons/hypercerts-lexicons/funding-receipt)** | `org.hypercerts.funding.receipt` | Records a funding payment from one party to another |
+| **[Funding Receipt](/lexicons/hypercerts-lexicons/funding-receipt)** | `org.hypercerts.funding.receipt` | Records an assertion about a funding payment |
 | **[Acknowledgement](/lexicons/hypercerts-lexicons/acknowledgement)** | `org.hypercerts.context.acknowledgement` | Acceptance or rejection of a relationship |
+| **Feature** | `org.hypercerts.entity.feature` | Non-agent subject such as a zone, stratum, cohort, or campaign |
+| **Vocabulary Tag** | `org.hypercerts.vocab.tag` | General classification for collections and features |
+| **Work-scope Tag** | `org.hypercerts.workscope.tag` | Reusable atom for an activity CEL work-scope expression |
+
+The package also includes the definition-only `org.hypercerts.defs` and `org.hypercerts.workscope.cel` schemas plus the `org.hypercerts.authWrite` permission set. See the complete [Lexicon inventory](/reference/lexicon-inventory). Use the released package for exact field constraints until all field pages are generated.
diff --git a/pages/lexicons/hypercerts-lexicons/measurement.md b/pages/lexicons/hypercerts-lexicons/measurement.md
index db47a1e..810abf6 100644
--- a/pages/lexicons/hypercerts-lexicons/measurement.md
+++ b/pages/lexicons/hypercerts-lexicons/measurement.md
@@ -9,6 +9,6 @@ description: Lexicon reference for the Measurement record type in Hypercerts.
 
 A measurement records a single quantitative data point related to a hypercert or other record. It captures what was measured (the metric), the unit of measurement, the measured value, and when the measurement was taken.
 
-Measurements support methodology traceability through optional fields for method type, method URI (linking to a detailed methodology), and evidence URIs (linking to raw data or supporting documentation). This makes measurements auditable and reproducible.
+Measurements support methodology traceability through optional fields for method type, method URI, and evidence URIs. These references can help consumers audit or reproduce a measurement, but the record does not verify the linked method or evidence.
 
-For the full schema, see [`org.hypercerts.context.measurement`](https://github.com/hypercerts-org/hypercerts-lexicon/blob/main/lexicons/org/hypercerts/context/measurement.json) in the lexicon repo.
+For the full released schema, see [`org.hypercerts.context.measurement` at v1.4.0](https://github.com/hypercerts-org/hypercerts-lexicon/blob/v1.4.0/lexicons/org/hypercerts/context/measurement.json).
diff --git a/pages/lexicons/hypercerts-lexicons/rights.md b/pages/lexicons/hypercerts-lexicons/rights.md
index e73c074..eb21d8f 100644
--- a/pages/lexicons/hypercerts-lexicons/rights.md
+++ b/pages/lexicons/hypercerts-lexicons/rights.md
@@ -9,4 +9,4 @@ description: Lexicon reference for the Rights record type in Hypercerts.
 
 Describes the rights associated with a hypercert — whether it can be sold, transferred, and under what conditions. Rights are defined as a separate record and referenced from an activity claim, so the same rights definition can be reused across multiple claims.
 
-For the full schema, see [`org.hypercerts.claim.rights`](https://github.com/hypercerts-org/hypercerts-lexicon/blob/main/lexicons/org/hypercerts/claim/rights.json) in the lexicon repo.
+For the full released schema, see [`org.hypercerts.claim.rights` at v1.4.0](https://github.com/hypercerts-org/hypercerts-lexicon/blob/v1.4.0/lexicons/org/hypercerts/claim/rights.json).
diff --git a/pages/reference/faq.md b/pages/reference/faq.md
index 9ff31b5..9a35d27 100644
--- a/pages/reference/faq.md
+++ b/pages/reference/faq.md
@@ -9,19 +9,19 @@ description: Common questions about building with Hypercerts.
 
 ## What is a hypercert?
 
-A structured digital record of a contribution — who did what, when, where, and with what supporting documentation. You create one by writing an `org.hypercerts.claim.activity` record to your PDS. See the [Quickstart](/getting-started/quickstart).
+A structured digital record of a contribution — who did what, when, where, and with what supporting documentation. Its core is an `org.hypercerts.claim.activity` record stored in an AT Protocol repository. See [Client Integration](/client-integration) for current integration guidance and known gaps.
 
 ## How is this different from the previous (EVM-based) Hypercerts?
 
-The new protocol stores data on AT Protocol instead of purely on-chain. This gives you richer schemas, data portability, and lower costs. On-chain anchoring for funding is [planned](/core-concepts/funding-and-value-flow) but not yet implemented.
+The current protocol stores its source records on AT Protocol rather than representing every hypercert as an onchain token. The released Lexicons do not define anchoring, freezing, token ownership, or settlement.
 
 ## Do I need a blockchain wallet?
 
-Not to create or evaluate hypercerts — you only need an account on [certified.app](https://certified.app) or any ATProto provider. A wallet will be needed for on-chain funding once the [tokenization layer](/core-concepts/funding-and-value-flow) is built.
+Not for the released Hypercerts record model. A particular application or payment mechanism may separately require a wallet.
 
 ## Can I use my Bluesky account?
 
-Yes. Bluesky accounts are ATProto accounts. Your existing DID and identity work with Hypercerts out of the box.
+Bluesky accounts are AT Protocol accounts. They can use Hypercerts applications that support their authentication provider and request the required record permissions; support is an application capability, not a guarantee of the record Lexicons.
 
 ## Is my data public?
 
@@ -33,17 +33,16 @@ You can delete records from your account. However, cached copies may persist in
 
 ## Who can evaluate my hypercert?
 
-Anyone with an ATProto account. Evaluations are separate records created by the evaluator, linked to your hypercert via a strong reference. You don't control who evaluates your work. See [Working with Evaluations](/getting-started/working-with-evaluations).
+Anyone with an ATProto account. Evaluations are separate records created by the evaluator, linked to your hypercert via a strong reference. You don't control who evaluates your work. See the [Evaluation Lexicon](/lexicons/hypercerts-lexicons/evaluation) for the record schema.
 
 ## How do I query hypercerts across the network?
 
-Use the [Hyperindex](/tools/hyperindex) GraphQL API at `https://api.indexer.hypercerts.dev/graphql`. It indexes all hypercert records across the network and supports filtering, search, real-time subscriptions, and standard introspection for typed client generation. You can explore the API in GraphiQL at `https://api.indexer.hypercerts.dev/graphiql`.
+For a known AT-URI, read the record from its repository. Cross-repository discovery requires an indexing service and depends on that service's coverage. The supported Hypercerts XRPC read API is being documented as it stabilizes. [Hyperindex](/tools/hyperindex) remains available as legacy GraphQL infrastructure, but it is not the target protocol interface.
 
 ## How do I fund a hypercert?
 
-The on-chain funding layer is not yet implemented. The planned design freezes records before funding to ensure funders know exactly what they are paying for. See [Funding & Value Flow](/core-concepts/funding-and-value-flow).
+Hypercerts does not execute payments. A platform can process funding through its chosen payment rail and publish a funding receipt that describes the payment. The receipt does not independently prove settlement. See [Funding Records & Value Flow](/core-concepts/funding-and-value-flow).
 
 ## Where do I get help?
 
-- [GitHub](https://github.com/hypercerts-org) — source code, issues, and discussions
-- [Roadmap](/roadmap) — what's being built and what's next
+- [GitHub](https://github.com/hypercerts-org) — source code and repository-specific issues or discussions
diff --git a/pages/reference/glossary.md b/pages/reference/glossary.md
index e344465..8dbab13 100644
--- a/pages/reference/glossary.md
+++ b/pages/reference/glossary.md
@@ -13,7 +13,7 @@ The central record in the hypercerts data model. Describes the work that was don
 
 #### AT-URI
 
-The permanent, globally unique identifier for a record. Looks like `at://did:plc:abc123/org.hypercerts.claim.activity/3k7`. You'll see these in every API response — they're how records reference each other.
+The stable, globally unique identifier for a record slot. It looks like `at://did:plc:abc123/org.hypercerts.claim.activity/3k7`. The record at that URI can be updated or deleted; a CID identifies one exact content version.
 
 #### Attachment
 
@@ -21,7 +21,7 @@ Supporting documentation linked to one or more records — a URL, uploaded file,
 
 #### Certified
 
-The identity provider for the Hypercerts ecosystem. We built Certified to give the ecosystem a unified entry point — one account that works across all Hypercerts applications. When you sign up at [certified.app](https://certified.app), you get a DID, a PDS, and an embedded wallet. See [Account & Identity Setup](/architecture/account-and-identity).
+An account and application provider oriented toward Hypercerts users and organizations. A Certified account provides a DID and repository on a Certified PDS. Application compatibility still depends on supported authentication and permissions. See [Account & Identity Setup](/architecture/account-and-identity).
 
 #### CGS (Certified Group Service)
 
@@ -37,7 +37,7 @@ Who contributed to a hypercert. Can be as simple as a DID string, or a richer re
 
 #### DID (Decentralized Identifier)
 
-A permanent identifier for a user or organization. Looks like `did:plc:abc123xyz`. You get one when you create an account on [certified.app](https://certified.app) or [Bluesky](https://bsky.app). Your DID never changes, even if you switch servers or handles. Every record you create carries your DID as the author.
+An identifier for an AT Protocol account, such as `did:plc:abc123xyz`. The DID in an AT-URI identifies the repository that published the record. It is distinct from a mutable handle and from actors named inside the record.
 
 #### ePDS (extended PDS)
 
@@ -53,7 +53,7 @@ A structured digital record of a contribution: who did what, when, where, and wi
 
 #### Hyperindex
 
-A reference indexer that indexes hypercert records across the network and exposes them via a GraphQL API. Other indexers exist — see [Hyperindex](/tools/hyperindex).
+A legacy indexer that indexes Hypercerts records and exposes them through GraphQL. It is supporting infrastructure, not the target Hypercerts protocol API. See [Hyperindex](/tools/hyperindex).
 
 #### Lexicon
 
diff --git a/pages/reference/index.md b/pages/reference/index.md
new file mode 100644
index 0000000..f559c02
--- /dev/null
+++ b/pages/reference/index.md
@@ -0,0 +1,56 @@
+---
+title: Reference
+description: Exact schemas, interfaces, services, environments, and implementation sources for the Hypercerts Protocol.
+---
+
+# Reference
+
+The Reference contains exact, source-backed contracts. Use the [Guide](/guide) when you need the meaning of a concept or the common convention around it.
+
+{% card-grid %}
+{% card-link title="Lexicons" href="/lexicons/introduction-to-lexicons" %}
+Browse Hypercerts and Certified record schemas and shared definitions.
+{% /card-link %}
+{% card-link title="Lexicon inventory" href="/reference/lexicon-inventory" %}
+See every Hypercerts and Certified schema released in package version 1.4.0 and the current reference coverage.
+{% /card-link %}
+{% card-link title="Architecture" href="/architecture/overview" %}
+Understand how PDSs, relays, APIs, indexers, and supporting services connect.
+{% /card-link %}
+{% card-link title="Services" href="/reference/certified-services" %}
+Find current environments, endpoints, service identities, and status pages.
+{% /card-link %}
+{% card-link title="Lexicon releases" href="/reference/releases" %}
+Read the source-backed Lexicon package changelog.
+{% /card-link %}
+{% /card-grid %}
+
+## API and SDK
+
+The XRPC API and SDK reference will be added from their canonical implementation sources as those contracts stabilize. Method pages must identify authentication, inputs, outputs, failure behavior, service version, and source schema. This documentation does not infer API methods from record Lexicons.
+
+## Source-owned documentation
+
+Four detailed documents are currently imported from their owning repositories during the documentation build:
+
+| Source | Owning repository | Local route |
+|---|---|---|
+| ePDS architecture | `hypercerts-org/ePDS` | [ePDS Architecture](/architecture/epds) |
+| ePDS integration tutorial | `hypercerts-org/ePDS` | [Integrate with ePDS](/tutorials/epds) |
+| Hyperindex documentation | `gainforest/hyperindex` | [Hyperindex](/tools/hyperindex) |
+| Hypercerts Lexicon changelog | `hypercerts-org/hypercerts-lexicon` | [Lexicon releases](/reference/releases) |
+
+The build stores the resolved source commit and content hash. These imports currently follow each repository's `main` branch. Release contracts should prefer immutable package versions, tags, or commits where available.
+
+Canonical external imports are not yet configured for the SDK, Hypercerts XRPC API, Certified Group Service, Hypercerts Feed Service, labelers, or a versioned generated Lexicon field reference. Their local overview pages should not be read as complete API contracts.
+
+## Services and tooling
+
+- [ePDS Architecture](/architecture/epds) and [ePDS integration](/tutorials/epds)
+- [Certified Group Service](/architecture/certified-group-service)
+- [Hypercerts Feed Service](/tools/hypercerts-feed-service)
+- [Labelers](/tools/labelers)
+- [Hyperindex](/tools/hyperindex), retained as legacy GraphQL infrastructure
+- [Hypercerts Agent Skills](/tools/hypercerts-agent-skills)
+
+Service overview pages can be maintained locally while detailed subpages continue to be imported from each service repository. See the repository maintainer documentation for the source ownership pattern.
diff --git a/pages/reference/lexicon-inventory.md b/pages/reference/lexicon-inventory.md
new file mode 100644
index 0000000..1107c3d
--- /dev/null
+++ b/pages/reference/lexicon-inventory.md
@@ -0,0 +1,71 @@
+---
+title: Lexicon Inventory
+description: Complete inventory of Hypercerts and Certified schemas released in @hypercerts-org/lexicon 1.4.0.
+---
+
+# Lexicon Inventory
+
+This page inventories the `org.hypercerts.*` and `app.certified.*` schemas in [`@hypercerts-org/lexicon` 1.4.0](https://www.npmjs.com/package/@hypercerts-org/lexicon/v/1.4.0). The immutable source tag is [`v1.4.0`](https://github.com/hypercerts-org/hypercerts-lexicon/tree/v1.4.0/lexicons).
+
+The package contains 23 repository record collections, two write permission sets, and four definition-only schemas across these namespaces. It contains no Hypercerts or Certified XRPC query or procedure Lexicons. API methods and SDK behavior must therefore be documented from their own canonical sources.
+
+## Hypercerts record collections
+
+| NSID | Role | Local detail |
+|---|---|---|
+| `org.hypercerts.claim.activity` | Describes impact work | [Activity Claim](/lexicons/hypercerts-lexicons/activity-claim) |
+| `org.hypercerts.claim.contribution` | Reusable contribution role and timeframe | [Contribution](/lexicons/hypercerts-lexicons/contribution) |
+| `org.hypercerts.claim.contributorInformation` | Reusable contributor identity and presentation | [Contribution](/lexicons/hypercerts-lexicons/contribution) |
+| `org.hypercerts.claim.rights` | Rights and licensing terms | [Rights](/lexicons/hypercerts-lexicons/rights) |
+| `org.hypercerts.collection` | Weighted grouping of activities, features, or collections | [Collection](/lexicons/hypercerts-lexicons/collection) |
+| `org.hypercerts.context.acknowledgement` | Acceptance or rejection of a subject or relationship | [Acknowledgement](/lexicons/hypercerts-lexicons/acknowledgement) |
+| `org.hypercerts.context.attachment` | Documentary material, evidence, reports, or commentary | [Attachment](/lexicons/hypercerts-lexicons/attachment) |
+| `org.hypercerts.context.evaluation` | Assessment with named evaluators and optional supporting data | [Evaluation](/lexicons/hypercerts-lexicons/evaluation) |
+| `org.hypercerts.context.measurement` | Quantitative observation, method, and evidence links | [Measurement](/lexicons/hypercerts-lexicons/measurement) |
+| `org.hypercerts.entity.feature` | Non-agent subject such as a zone, stratum, cohort, or campaign | Source schema only |
+| `org.hypercerts.funding.receipt` | Assertion about a funding payment | [Funding Receipt](/lexicons/hypercerts-lexicons/funding-receipt) |
+| `org.hypercerts.vocab.tag` | Governed general classification term | Source schema only |
+| `org.hypercerts.workscope.tag` | Reusable atom for an activity CEL work scope | Source schema only |
+
+## Hypercerts definitions and permissions
+
+| NSID | Kind | Role |
+|---|---|---|
+| `org.hypercerts.defs` | Definitions | Reusable descriptions, blobs, images, video, and URI objects |
+| `org.hypercerts.workscope.cel` | Definition | CEL expression embedded inside an activity work scope; not a repository record |
+| `org.hypercerts.authWrite` | Permission set | Create, update, and delete grants for the 13 Hypercerts record collections |
+
+## Certified record collections
+
+| NSID | Role | Local detail |
+|---|---|---|
+| `app.certified.actor.profile` | Singleton account profile | [Profile](/lexicons/certified-lexicons/profile) |
+| `app.certified.actor.organization` | Singleton organization metadata | Source schema only |
+| `app.certified.badge.definition` | Badge type definition | [Badge Definition](/lexicons/certified-lexicons/badge-definition) |
+| `app.certified.badge.award` | Badge award to an account or record | [Badge Award](/lexicons/certified-lexicons/badge-award) |
+| `app.certified.badge.response` | Recipient response to an award | [Badge Response](/lexicons/certified-lexicons/badge-response) |
+| `app.certified.graph.follow` | Account-to-account follow | Source schema only |
+| `app.certified.graph.entityFollow` | Follow of a record subject by AT-URI | Source schema only |
+| `app.certified.link.evm` | DID-to-EVM-address link with an EIP-712 proof shape | Source schema only |
+| `app.certified.location` | Reusable spatial representation | [Location](/lexicons/certified-lexicons/location) |
+| `app.certified.signature.proof` | Remote proof containing the CID of attested content | Source schema only |
+
+## Certified definitions and permissions
+
+| NSID | Kind | Role |
+|---|---|---|
+| `app.certified.defs` | Definitions | DID object and URI-only record-subject object |
+| `app.certified.signature.defs` | Definitions | Inline and remote record-content signature variants |
+| `app.certified.authWrite` | Permission set | Create, update, and delete grants for the 10 Certified record collections |
+
+## Coverage status
+
+The human-readable pages currently cover the original activity, context, collection, funding, profile, location, and badge families. The 1.4.0 feature and vocabulary records, organization and graph records, EVM link, signature system, common definitions, and permission sets still need generated or source-owned field reference pages.
+
+Until that reference is generated, use the versioned package or [`v1.4.0` source tree](https://github.com/hypercerts-org/hypercerts-lexicon/tree/v1.4.0/lexicons) for exact fields. Do not use mutable `main` as the production contract.
+
+## Package boundary
+
+The NPM package also bundles dependency schemas outside the `org.hypercerts.*` and `app.certified.*` namespaces. Package inclusion does not make every bundled namespace part of this documentation's Hypercerts Protocol surface.
+
+See the [Core Data Model](/core-concepts/hypercerts-core-data-model) for meaning and relationships and [Validation, Extension & Interpretation](/core-concepts/validation-and-interpretation) for constraints that applications must enforce.
diff --git a/pages/roadmap.md b/pages/roadmap.md
index 5236ab7..a1badf2 100644
--- a/pages/roadmap.md
+++ b/pages/roadmap.md
@@ -167,12 +167,11 @@ Applications built on the infrastructure, governed by the Hypercerts Collective:
 | Frontend | Purpose | Status |
 |----------|---------|--------|
 | **Ma Earth** | Regenerative land funding, community onboarding | Active |
-| **hyperboards.org** | Hypercert visualization and management | Active |
 | **Other frontends** | Third-party applications | Ecosystem |
 
 **How records flow:**
 
-1. User creates a hypercert record via a frontend (Ma Earth, hyperboards.org, etc.)
+1. User creates a hypercert record via a frontend such as Ma Earth
 2. Frontend writes the record to the user's PDS
 3. PDS syncs to the network via the relay
 4. Hyperindex indexes the record
@@ -270,7 +269,7 @@ Open governance body for the ATProto impact ecosystem. Coordinates decisions abo
 
 - Evaluators
 - Hypercerts Labeller
-- Frontend applications (Ma Earth, hyperboards.org)
+- Frontend applications
 - Lexicon standards adoption
 
 ### Lexicon Indexing Requests (LIRs)
diff --git a/pages/tools/hyperboards.md b/pages/tools/hyperboards.md
deleted file mode 100644
index 436907a..0000000
--- a/pages/tools/hyperboards.md
+++ /dev/null
@@ -1,85 +0,0 @@
----
-title: Hyperboards
-description: Visual contributor boards on ATProto — see who built what, beautifully.
----
-
-# Hyperboards
-
-Hyperboards creates visual contributor boards backed by ATProto data. Build a board from your hypercerts, customize the layout, and embed it anywhere.
-
-Live at [hyperboards.org](https://hyperboards.org). Source: [github.com/hypercerts-org/hyperboards](https://github.com/hypercerts-org/hyperboards).
-
-## What it does
-
-Hyperboards turns hypercert data into shareable, embeddable visualizations. Each board is a treemap layout that shows contributors, their roles, and relative weights at a glance.
-
-- **Treemap layouts** — contributors are displayed as proportionally sized tiles, making contribution weights immediately visible
-- **Drag-to-resize editing** — adjust contributor tile sizes interactively to reflect their relative contributions
-- **Embeddable** — drop a board into any website with a simple iframe
-- **ATProto-native** — board data comes directly from signed ATProto records, not a separate database
-
-## How it works
-
-1. **Sign in** with your ATProto handle (e.g. `yourname.certified.one` or `yourname.bsky.social`)
-2. **Create a board** from the dashboard — select one or more hypercerts to visualize
-3. **Customize** the treemap layout by dragging and resizing contributor tiles
-4. **Share** the board URL or embed it on your website via iframe
-
-Because boards pull data from ATProto repositories, the contributor information is cryptographically signed and publicly verifiable. Anyone can inspect the underlying records and confirm who contributed to a hypercert.
-
-## How weights become tile sizes
-
-Hyperboards normalizes contributor weights into proportional tile areas using this formula:
-
-```text
-tileArea = contributorWeight / sumOfAllWeights
-```
-
-For example, if three contributors have weights `"70"`, `"20"`, and `"10"`:
-
-| Contributor | Weight | Calculation | Tile Area |
-|-------------|--------|-------------|-----------|
-| Alice       | 70     | 70 / 100    | 70%       |
-| Bob         | 20     | 20 / 100    | 20%       |
-| Carol       | 10     | 10 / 100    | 10%       |
-
-D3 recomputes tile positions from the weights on every render.
-
-**Missing or invalid weights:** Contributors without a `contributionWeight` default to a weight of 1. There are two fallback layers: (1) if `contributionWeight` is undefined or null, the string `"1"` is used; (2) if the string cannot be parsed as a number (e.g. empty string), the number `1` is used. Contributors are never excluded — they always appear on the board with at least a weight of 1.
-
-**Drag-to-resize behavior:** When you drag to resize tiles in the editor, this directly updates the `contributionWeight` stored in the contributor's ATProto activity record on their PDS. There is no separate layout layer — the weight IS the layout. Weights are rounded to one decimal place on save.
-
-**Choosing weights for visual clarity:** For boards with many contributors, using percentage-style weights (summing to 100) makes the visual proportions intuitive. For boards with few contributors, simple multipliers (like `"3"`, `"2"`, `"1"`) work well.
-
-For methods to calculate contributor weights, see [Choosing contribution weights](/lexicons/hypercerts-lexicons/contribution#choosing-contribution-weights).
-
-## Embedding
-
-Add a board to any website:
-
-```html
-<iframe
-  src="https://hyperboards.org/embed/BOARD_ID"
-  width="100%"
-  height="400"
-  frameborder="0"
-></iframe>
-```
-
-Replace `BOARD_ID` with your board's identifier from the dashboard.
-
-## Use cases
-
-**Project pages** — Embed a board on your project website to showcase your team. The treemap makes it easy to see who contributed and how much.
-
-**Funding transparency** — Show funders exactly who their contributions support. Contributors are displayed with verifiable ATProto-backed attribution.
-
-**Impact portfolios** — Contributors can link to boards as portable proof of their work. Because the underlying records are signed, the attribution is credible across platforms.
-
-**Recognition** — Publicly acknowledge contributors in a visual, shareable format that is not locked into any single platform.
-
-## See also
-
-- [Quickstart](/getting-started/quickstart) — build a hypercert with contributors that Hyperboards can display
-- [Core Data Model](/core-concepts/hypercerts-core-data-model) — understand the record types behind a board
-- [Scaffold Starter App](/tools/scaffold) — another example of building on ATProto with the Hypercerts protocol
diff --git a/pages/tools/hypercerts-feed-service.md b/pages/tools/hypercerts-feed-service.md
index e58a9a5..72866ce 100644
--- a/pages/tools/hypercerts-feed-service.md
+++ b/pages/tools/hypercerts-feed-service.md
@@ -126,9 +126,9 @@ The response contains only ordered source-record AT-URIs and, when another page
 
 Keep cursors opaque and send them back only with the same `feedId`. Put `cursor` and `limit` at the top level of the request, not inside `params`.
 
-## Supported event kinds
+## Documented event kinds
 
-Omit `params.kinds`, or pass an empty array, to include every supported kind. These values describe the type of source record and the hydrated content returned for it:
+Omit `params.kinds`, or pass an empty array, to include every event kind supported by the service. These values cover the Hypercerts and Certified source records documented here; consult the implementation repository for the complete service contract.
 
 | Kind | Source record | Description |
 |---|---|---|
@@ -137,7 +137,6 @@ Omit `params.kinds`, or pass an empty array, to include every supported kind. Th
 | `project.created_with_cert` | `org.hypercerts.collection` | A collection representing a project created together with a Hypercert activity |
 | `evaluation.create` | `org.hypercerts.context.evaluation` | A newly published evaluation of a target record |
 | `measurement.create` | `org.hypercerts.context.measurement` | A newly published measurement of a target record |
-| `hyperboard.create` | `org.hyperboards.board` | A newly created Hyperboard |
 | `update.create` | `org.hypercerts.context.attachment` | A newly published update or attachment |
 | `endorsement.award` | `app.certified.badge.award` | An endorsement awarded to an account |
 
diff --git a/pages/tools/hyperindex.md b/pages/tools/hyperindex.md
index ecd75d6..497ba63 100644
--- a/pages/tools/hyperindex.md
+++ b/pages/tools/hyperindex.md
@@ -1,5 +1,5 @@
 ---
-title: Hyperindex
-description: A Go ATProto indexer that indexes hypercert records and exposes them via GraphQL.
+title: Hyperindex (legacy)
+description: Legacy GraphQL indexing infrastructure for Hypercerts and Certified records.
 externalDoc: hyperindex
 ---
diff --git a/pages/tools/scaffold.md b/pages/tools/scaffold.md
deleted file mode 100644
index 7e30f2b..0000000
--- a/pages/tools/scaffold.md
+++ /dev/null
@@ -1,297 +0,0 @@
----
-title: Scaffold Starter App
-description: A Next.js starter app for building on ATProto with the Hypercerts protocol.
----
-
-# Scaffold Starter App
-
-The Hypercerts Scaffold is a working Next.js app that demonstrates how to build on ATProto with the Hypercerts protocol. It handles OAuth authentication, profile management, and the full hypercert creation workflow — from basic claims through attachments, locations, measurements, and evaluations.
-
-Live at [hypercerts-scaffold.vercel.app](https://hypercerts-scaffold.vercel.app). Source: [github.com/hypercerts-org/hypercerts-scaffold-atproto](https://github.com/hypercerts-org/hypercerts-scaffold-atproto).
-
-The repo is also indexed on [deepwiki](https://deepwiki.com/hypercerts-org/hypercerts-scaffold-atproto) if you want to dive deeper into the docs and setup.
-
-## Tech Stack
-
-| Category | Technology |
-|----------|------------|
-| Framework | Next.js 16 (App Router), React 19, TypeScript |
-| Styling | Tailwind CSS 4, shadcn/ui (Radix primitives) |
-| State Management | TanStack React Query v5 |
-| Auth / Protocol | AT Protocol OAuth, `@atproto/oauth-client-node` |
-| Infrastructure | Redis (session + OAuth state storage) |
-
-## What the app does
-
-### Sign in with ATProto
-
-Enter your handle (e.g. `yourname.certified.one` or `yourname.bsky.social`) and the app redirects you to your PDS for OAuth authorization. Once approved, you're signed in with a session tied to your DID.
-
-Alternatively, the sign-in dialog has an **Email** tab (visible when `NEXT_PUBLIC_EPDS_URL` is configured). Entering your email authenticates via the ePDS — if no account is registered with that email, the ePDS creates one for you automatically.
-
-![Scaffold sign-in screen showing handle input field](/images/scaffold/sign-in.png)
-*The sign-in screen. Enter your ATProto handle to authenticate via OAuth.*
-
-### Home screen
-
-After signing in, the home screen shows your active session — your DID, display name, and handle. From here you can create a new hypercert or view your existing ones.
-
-![Scaffold home screen showing session info and action buttons](/images/scaffold/homepage.png)
-*The authenticated home screen with session details and quick actions.*
-
-### Create a hypercert
-
-The creation flow is a 5-step wizard with a sidebar stepper that tracks your progress:
-
-**Step 1 — Basic info.** Title, description, work scope tags, start and end dates, and an optional cover image. This creates the core `org.hypercerts.claim.activity` record on your PDS.
-
-![Hypercert creation form showing title, description, work scope, and date fields](/images/scaffold/create-cert.png)
-*Step 1: Define the basic claim — what work was done, when, and in what scope.*
-
-**Step 2 — Attachments.** Attach supporting documentation — URLs, files, or descriptions that back up the claim.
-
-![Evidence form for attaching supporting documentation](/images/scaffold/add-evidence.png)
-*Step 2: Attach supporting documentation to back up the claim.*
-
-**Step 3 — Location.** Add geographic context to the work — where it happened.
-
-![Location form for adding geographic context](/images/scaffold/add-location.png)
-*Step 3: Add location data to anchor the work geographically.*
-
-**Step 4 — Measurements.** Add quantitative data — metrics, values, and measurement methods that make the impact concrete.
-
-![Measurement form for adding quantitative impact data](/images/scaffold/add-measurement.png)
-*Step 4: Add measurements to quantify the impact.*
-
-**Step 5 — Evaluations.** Add third-party assessments of the work.
-
-![Evaluation form for adding third-party assessments](/images/scaffold/add-evaluation.png)
-*Step 5: Add evaluations from third-party assessors.*
-
-**Step 6 — Done.** Review the completed hypercert and create another or view your collection.
-
-![Completion screen showing the finished hypercert](/images/scaffold/finalized-cert.png)
-*Step 6: The hypercert is created and stored on your PDS.*
-
-### Browse your hypercerts
-
-The hypercerts page shows all your claims in a card grid. Each card displays the title, description, creation date, work scope tags, and cover image. Click any card to view its full details.
-
-![Grid of hypercert cards showing titles, descriptions, and work scope tags](/images/scaffold/view-hypercerts.png)
-*Your hypercerts displayed as cards with metadata and work scope tags.*
-
-### Edit your profile
-
-The profile page lets you update your Certified profile — display name, bio, pronouns, website, avatar, and banner image. Changes are written directly to your PDS.
-
-![Profile editing form with display name, bio, and avatar fields](/images/scaffold/profile.png)
-*Edit your Certified profile. Changes are stored on your PDS.*
-
-## Environment variables
-
-| Variable | Description |
-|----------|-------------|
-| `NEXT_PUBLIC_BASE_URL` | App URL (`http://127.0.0.1:3000` for local) |
-| `ATPROTO_JWK_PRIVATE` | OAuth private key (generate with `pnpm run generate-jwk`) |
-| `REDIS_HOST` | Redis hostname |
-| `REDIS_PORT` | Redis port |
-| `REDIS_PASSWORD` | Redis password |
-| `NEXT_PUBLIC_PDS_URL` | Target PDS for the standard handle-based OAuth sign-in flow. Can be any AT Protocol PDS (Bluesky, a Certified ePDS, a self-hosted PDS, etc.). |
-| `NEXT_PUBLIC_EPDS_URL` | Optional. Target ePDS for the email/passwordless sign-in tab. Only needed if you want to offer email login; leave unset to disable that tab. Must be an ePDS (a PDS with the ePDS email-login extension), so in practice a [Certified-operated ePDS](/reference/certified-pdss). |
-
-{% callout type="note" %}
-Redis is the default session store, but you can use any persistent storage (Supabase, Postgres, DynamoDB, etc.). You just need to implement the `NodeSavedStateStore` and `NodeSavedSessionStore` interfaces from `@atproto/oauth-client-node`. See `lib/redis-state-store.ts` for the reference implementation.
-{% /callout %}
-
-## Run it locally
-
-1. Clone and install:
-```bash
-git clone https://github.com/hypercerts-org/hypercerts-scaffold-atproto
-cd hypercerts-scaffold-atproto
-pnpm install
-```
-
-2. Configure environment:
-```bash
-cp .env.example .env.local
-pnpm run generate-jwk >> .env.local
-```
-
-3. Start Redis (for session storage):
-```bash
-docker run -d -p 6379:6379 redis:alpine
-```
-
-4. Run the dev server:
-```bash
-pnpm run dev
-```
-
-Open `http://127.0.0.1:3000`. Requires Node.js 20+ and pnpm.
-
-> **Note:** Use `127.0.0.1` not `localhost` for local development. ATProto OAuth requires IP-based loopback addresses per RFC 8252. The app auto-redirects, but your `.env.local` must use `127.0.0.1`.
-
-## Architecture
-
-### OAuth Flow
-
-The scaffold implements ATProto OAuth with DPoP-bound tokens. The flow involves four parties: the **Browser**, the **Scaffold Server** (Next.js), the **Authorization Server** (user's PDS), and **Redis** (session storage).
-
-![Sequence diagram showing the ATProto OAuth flow between Browser, Scaffold Server, Auth Server (PDS), and Redis](/images/scaffold/oauth-flow.png)
-*The ATProto OAuth flow — from login initiation through session creation and subsequent request authentication.*
-
-**1–3 — Login initiation.** The browser sends the user's handle to `POST /api/oauth/login`. The server resolves the handle to a DID, discovers their PDS, and generates an authorization URL. Temporary OAuth state is stored in Redis (`oauth-state:<id>`, 10-minute TTL) to prevent CSRF.
-
-**4–6 — Authorization.** The browser redirects to the PDS where the user grants consent. The PDS redirects back to `/api/oauth/callback` with an authorization code.
-
-**7–9 — Session creation.** The server exchanges the code for a DPoP-bound session via the OAuth client's `callback()` method. The session (tokens, refresh token, DID) is persisted to Redis (`session:<did>`, no TTL) and a `user-did` httpOnly cookie is set in the browser.
-
-**10–12 — Session restore.** On subsequent requests, the server reads the `user-did` cookie and calls `oauthClient.restore(did)` to load the session from Redis, auto-refreshing expired tokens. This call is wrapped in React's `cache()` so multiple server components in the same render only hit Redis once.
-
-**Logout.** `GET /api/oauth/logout` revokes tokens with the PDS, deletes the Redis session, and clears the cookie.
-
-**Discovery endpoints.** Before any of this works, the PDS needs to discover the app's identity. Two endpoints handle this:
-
-- `/client-metadata.json` (`app/client-metadata.json/route.ts`) — serves RFC 7591 client metadata: `client_id`, redirect URIs, scopes, and DPoP configuration.
-- `/jwks.json` (`app/jwks.json/route.ts`) — serves the public half of the app's ES256 key pair (from `ATPROTO_JWK_PRIVATE`). The PDS uses this to verify client assertion JWTs.
-
-### Local Loopback Development
-
-ATProto OAuth requires loopback clients to use `127.0.0.1` rather than `localhost`, per RFC 8252 Section 7.3. This prevents DNS rebinding attacks and means local development operates differently from production in two ways:
-
-**`client_id` format.** In production, the `client_id` is the URL of the client metadata document (`https://yourdomain.com/client-metadata.json`). In local development, ATProto uses a special loopback format: `http://localhost?scope=...&redirect_uri=...`. The `lib/config.ts` module auto-detects which format to use based on whether the base URL resolves to a loopback address.
-
-**Automatic redirect.** The app includes a proxy (`proxy.ts`) that issues a 307 redirect from `localhost` to `127.0.0.1` for any incoming request.
-
-> **Note:** Your `.env.local` must set `NEXT_PUBLIC_BASE_URL=http://127.0.0.1:3000`. Using `localhost` will cause the configuration validator in `lib/config.ts` to throw an error at startup.
-
-### Server-Side Data Boundary
-
-All data fetching happens server-side. The ATProto session lives in Redis, accessed via an httpOnly cookie — there is no browser-side session. Client components never talk to the PDS directly.
-
-The app exposes server-side logic to client components through two patterns: **API Routes** (`app/api/`) for operations that need FormData like file uploads, and **Server Actions** (`lib/create-actions.ts`) for simpler operations called directly without an HTTP round-trip. Client components use TanStack React Query hooks (in `queries/`) to call both.
-
-Server component pages like `app/hypercerts/page.tsx` and `app/hypercerts/[hypercertUri]/page.tsx` skip this entirely — they call the ATProto client directly on the server and pass fetched data as props to client components.
-
-### Constellation Backlinks
-
-ATProto has no built-in reverse lookup — given a hypercert URI, there is no native way to find which attachments, evaluations, or measurements reference it. The scaffold uses [Constellation](https://constellation.microcosm.blue), an external backlinks service, to solve this.
-
-Constellation indexes ATProto records and returns all records that reference a given subject URI. The scaffold queries three source paths:
-
-- Attachments: `org.hypercerts.context.attachment:subjects[com.atproto.repo.strongRef].uri`
-- Evaluations: `org.hypercerts.context.evaluation:subject.uri`
-- Measurements: `org.hypercerts.context.measurement:subject.uri`
-
-The query hooks follow a two-step pattern: fetch backlink URIs from Constellation, then fetch each record's full data via Server Actions. This split is necessary because Constellation returns record identifiers, not record contents.
-
-## Project structure
-```text
-hypercerts-scaffold/
-├── app/
-│   ├── layout.tsx                    # Root layout (server component, wraps providers)
-│   ├── page.tsx                      # Landing page (server component)
-│   ├── loading.tsx                   # Root loading state
-│   ├── robots.ts                     # Robots meta
-│   ├── sitemap.ts                    # Sitemap generation
-│   ├── client-metadata.json/
-│   │   └── route.ts                  # OAuth client metadata endpoint (RFC 7591)
-│   ├── jwks.json/
-│   │   └── route.ts                  # JWKS public key endpoint for OAuth
-│   ├── api/
-│   │   ├── oauth/
-│   │   │   ├── login/route.ts        # POST — initiate OAuth login (handle)
-│   │   │   ├── callback/route.ts     # GET — OAuth callback, sets session
-│   │   │   ├── logout/route.ts       # GET — revoke session, clear cookie
-│   │   │   └── epds/
-│   │   │       ├── login/route.ts    # POST — initiate ePDS email login (PAR + PKCE)
-│   │   │       └── callback/route.ts # GET — ePDS token exchange
-│   │   ├── certs/
-│   │   │   ├── route.ts              # POST — create hypercert
-│   │   │   ├── add-location/route.ts # POST — attach location to hypercert
-│   │   │   └── add-attachment/route.ts # POST — attach evidence/files
-│   │   └── profile/
-│   │       ├── update/route.ts       # POST — update Certified profile
-│   │       └── bsky/update/route.ts  # POST — update Bluesky profile
-│   ├── hypercerts/
-│   │   ├── page.tsx                  # List all hypercerts (server component)
-│   │   ├── loading.tsx
-│   │   ├── create/
-│   │   │   ├── page.tsx              # Multi-step creation wizard
-│   │   │   └── layout.tsx
-│   │   └── [hypercertUri]/
-│   │       ├── page.tsx              # Hypercert detail view (server component)
-│   │       ├── loading.tsx
-│   │       ├── edit/page.tsx         # Edit hypercert
-│   │       └── add/[type]/page.tsx   # Add evidence/evaluation/measurement/etc.
-│   ├── profile/
-│   │   ├── page.tsx                  # Certified profile editor
-│   │   └── loading.tsx
-│   └── bsky-profile/page.tsx         # Bluesky profile editor
-│
-├── lib/
-│   ├── config.ts                     # Centralized config, env validation, URL detection
-│   ├── hypercerts-sdk.ts             # NodeOAuthClient initialization + Redis stores
-│   ├── atproto-session.ts            # Session restore helpers (server-only, cached)
-│   ├── atproto-writes.ts             # StrongRef resolution, location creation, blob upload
-│   ├── atproto-branding.ts           # OAuth page CSS/logo branding
-│   ├── epds-config.ts                # Derives ePDS OAuth endpoints from NEXT_PUBLIC_EPDS_URL
-│   ├── epds-helpers.ts               # PKCE + DPoP utilities for ePDS flow
-│   ├── repo-context.ts               # getRepoContext() — authenticated Agent + DID context
-│   ├── redis.ts                      # Redis client singleton (server-only)
-│   ├── redis-state-store.ts          # Redis-backed OAuth state + session stores
-│   ├── create-actions.ts             # Server Actions ("use server")
-│   ├── record-validation.ts          # Generic lexicon record validation
-│   ├── blob-utils.ts                 # Blob/image URL resolution (server-only)
-│   ├── contribution-helpers.ts       # Contributor/contribution utilities
-│   ├── types.ts                      # Core TypeScript types
-│   ├── utils.ts                      # Shared utilities (cn, validators)
-│   └── api/                          # Client-side API layer
-│       ├── client.ts                 # Base fetch wrappers (JSON, FormData)
-│       ├── auth.ts                   # Auth API functions
-│       ├── hypercerts.ts             # Hypercert API functions
-│       ├── profile.ts                # Profile API functions
-│       ├── bsky-profile.ts           # Bluesky profile API functions
-│       ├── types.ts                  # Shared API types
-│       ├── query-keys.ts             # Centralized TanStack Query key factory
-│       └── external/
-│           ├── bluesky.ts            # Bluesky public API (search, profiles)
-│           └── constellation.ts      # Constellation backlinks API
-│
-├── providers/
-│   ├── AllProviders.tsx              # QueryClientProvider (client component)
-│   ├── AuthErrorToast.tsx            # Auth error toast notifications
-│   └── SignedInProvider.tsx          # Auth gate + Navbar (server component)
-│
-├── queries/                          # TanStack Query hooks (all client-side)
-│   ├── use-active-profile-query.tsx
-│   ├── auth/                         # Login/logout mutations
-│   ├── hypercerts/                   # Create, edit, delete, attach queries/mutations
-│   ├── profile/                      # Profile update mutations
-│   └── external/                     # Bluesky search, Constellation queries
-│
-├── components/
-│   ├── ui/                           # shadcn/ui primitives
-│   ├── navbar.tsx                    # Top navigation
-│   ├── login-dialog.tsx              # Login form (handle + email tab toggle)
-│   ├── hypercerts-create-form.tsx    # Create wizard wrapper
-│   ├── hypercerts-edit-form.tsx      # Edit hypercert form
-│   ├── evidence-form.tsx             # Evidence step
-│   ├── locations-form.tsx            # Location step
-│   ├── measurement-form.tsx          # Measurement step
-│   ├── evaluation-form.tsx           # Evaluation step
-│   ├── contributions-form.tsx        # Contributors step
-│   ├── hypercert-detail-view.tsx     # Detail page client component
-│   ├── hypercert-*-section.tsx       # Collapsible detail sections (evidence, evaluations, etc.)
-│   ├── delete-confirm-dialog.tsx     # Delete confirmation
-│   ├── profile-form.tsx              # Certified profile form
-│   └── bsky-profile-form.tsx         # Bluesky profile form
-│
-├── scripts/
-│   └── generate-jwk.mjs             # JWK key pair generator (ES256)
-│
-└── vendor/                           # Packed dependency tarballs (pre-release)
-```
-
-`app/` contains pages (server components by default) and API routes. `lib/` is split: top-level files are server-only, while `lib/api/` is the client-side fetch layer that browser code calls. `providers/` has one server component (`SignedInProvider`, which handles the auth gate and renders the Navbar) and one client component (`AllProviders`, which sets up the TanStack Query client). `queries/` is entirely client-side TanStack Query hooks. `components/` is entirely client-side React components.
diff --git a/styles/globals.css b/styles/globals.css
index 0485154..c40d9ae 100644
--- a/styles/globals.css
+++ b/styles/globals.css
@@ -714,7 +714,7 @@ html.dark .search-pill {
   display: none;
 }
 
-@media (min-width: 769px) {
+@media (min-width: 1100px) {
   .header-nav {
     display: flex;
     align-items: center;
@@ -743,7 +743,7 @@ html.dark .search-pill {
   display: none;
 }
 
-@media (min-width: 769px) {
+@media (min-width: 1100px) {
   .header-divider {
     display: block;
     width: 1px;
diff --git a/vercel.json b/vercel.json
index 2139892..8353993 100644
--- a/vercel.json
+++ b/vercel.json
@@ -1,5 +1,47 @@
 {
   "buildCommand": "npm run build",
   "installCommand": "npm install",
-  "framework": "nextjs"
+  "framework": "nextjs",
+  "redirects": [
+    {
+      "source": "/getting-started/quickstart",
+      "destination": "/client-integration",
+      "permanent": true
+    },
+    {
+      "source": "/getting-started/working-with-evaluations",
+      "destination": "/client-integration",
+      "permanent": true
+    },
+    {
+      "source": "/tools/scaffold",
+      "destination": "/client-integration",
+      "permanent": true
+    },
+    {
+      "source": "/tools/hyperboards",
+      "destination": "/reference",
+      "permanent": true
+    },
+    {
+      "source": "/raw/getting-started/quickstart.md",
+      "destination": "/raw/client-integration.md",
+      "permanent": true
+    },
+    {
+      "source": "/raw/getting-started/working-with-evaluations.md",
+      "destination": "/raw/client-integration.md",
+      "permanent": true
+    },
+    {
+      "source": "/raw/tools/scaffold.md",
+      "destination": "/raw/client-integration.md",
+      "permanent": true
+    },
+    {
+      "source": "/raw/tools/hyperboards.md",
+      "destination": "/raw/reference.md",
+      "permanent": true
+    }
+  ]
 }

From 9d77fd2ab676bd77140a074ccd1e676e91c5c3e5 Mon Sep 17 00:00:00 2001
From: Kristofer Lund <kristofer@fmckl.se>
Date: Tue, 15 Sep 2026 14:14:09 +0200
Subject: [PATCH 2/7] feat: scope navigation by documentation section

---
 components/Layout.js  | 11 +++++----
 components/Sidebar.js | 24 ++++++++++++++++++--
 lib/navigation.js     | 21 +++++++++++++++--
 styles/globals.css    | 53 +++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 100 insertions(+), 9 deletions(-)

diff --git a/components/Layout.js b/components/Layout.js
index 234efe4..db6795d 100644
--- a/components/Layout.js
+++ b/components/Layout.js
@@ -4,7 +4,7 @@ import Link from 'next/link';
 import { useRouter } from 'next/router';
 import { Sidebar } from './Sidebar';
 import { TableOfContents } from './TableOfContents';
-import { getPrevNext } from '../lib/navigation';
+import { getNavigationSection, getPrevNext } from '../lib/navigation';
 import { LastUpdated } from './LastUpdated';
 import { Breadcrumbs } from './Breadcrumbs';
 import { ThemeToggle } from './ThemeToggle';
@@ -24,6 +24,7 @@ export default function Layout({ children, frontmatter }) {
   const [searchOpen, setSearchOpen] = useState(false);
   const router = useRouter();
   const currentPath = router.asPath.split('#')[0].split('?')[0];
+  const currentSection = getNavigationSection(currentPath)?.section;
   const { prev, next } = getPrevNext(currentPath);
 
   const title = frontmatter?.title;
@@ -162,10 +163,10 @@ export default function Layout({ children, frontmatter }) {
           </Link>
           <span className="header-divider" aria-hidden="true" />
           <nav className="header-nav" aria-label="Main navigation">
-            <Link href="/guide" className="header-nav-link">Guide</Link>
-            <Link href="/client-integration" className="header-nav-link">Client integration</Link>
-            <Link href="/reference" className="header-nav-link">Reference</Link>
-            <Link href="/change-history" className="header-nav-link">Change history</Link>
+            <Link href="/guide" className={`header-nav-link${currentSection === 'Guide' ? ' header-nav-link-active' : ''}`}>Guide</Link>
+            <Link href="/client-integration" className={`header-nav-link${currentSection === 'Client Integration' ? ' header-nav-link-active' : ''}`}>Client integration</Link>
+            <Link href="/reference" className={`header-nav-link${currentSection === 'Reference' ? ' header-nav-link-active' : ''}`}>Reference</Link>
+            <Link href="/change-history" className={`header-nav-link${currentSection === 'Change History' ? ' header-nav-link-active' : ''}`}>Change history</Link>
           </nav>
           <div style={{ flex: 1 }} />
           <button
diff --git a/components/Sidebar.js b/components/Sidebar.js
index 909cf3e..8fcaeb5 100644
--- a/components/Sidebar.js
+++ b/components/Sidebar.js
@@ -1,7 +1,7 @@
 import { useState, useEffect, useRef } from 'react';
 import Link from 'next/link';
 import { useRouter } from 'next/router';
-import { navigation } from '../lib/navigation';
+import { getNavigationSection, navigation } from '../lib/navigation';
 
 function isActive(path, currentPath) {
   return path === currentPath;
@@ -112,6 +112,8 @@ function NavSection({ item, currentPath }) {
 export function Sidebar({ isOpen, onClose, collapsed, onToggleCollapse }) {
   const router = useRouter();
   const currentPath = router.asPath.split('#')[0].split('?')[0];
+  const currentSection = getNavigationSection(currentPath);
+  const visibleNavigation = currentSection ? [currentSection] : navigation;
 
   const onCloseRef = useRef(onClose);
   useEffect(() => {
@@ -169,8 +171,26 @@ export function Sidebar({ isOpen, onClose, collapsed, onToggleCollapse }) {
 
         {/* Nav content — hidden when collapsed */}
         <div className="sidebar-content">
+          <div className="sidebar-section-switcher">
+            <span className="sidebar-section-switcher-title">Sections</span>
+            {navigation.map((section) => {
+              const overview = section.children.find((child) => child.path);
+              if (!overview) return null;
+
+              const active = section.section === currentSection?.section;
+              return (
+                <Link
+                  key={section.section}
+                  href={overview.path}
+                  className={`sidebar-section-switcher-link${active ? ' sidebar-section-switcher-link-active' : ''}`}
+                >
+                  {section.section}
+                </Link>
+              );
+            })}
+          </div>
           <ul className="sidebar-nav">
-            {navigation.map((item, i) => (
+            {visibleNavigation.map((item, i) => (
               <NavSection
                 key={item.section || item.path || i}
                 item={item}
diff --git a/lib/navigation.js b/lib/navigation.js
index 3c93ee7..43a2639 100644
--- a/lib/navigation.js
+++ b/lib/navigation.js
@@ -240,11 +240,28 @@ export function flattenNavigation(nav = navigation, currentSection = "") {
   return result;
 }
 
+function containsPath(items, targetPath) {
+  return items.some((item) =>
+    item.path === targetPath ||
+    (item.children && containsPath(item.children, targetPath)),
+  );
+}
+
+/**
+ * Return the top-level documentation section containing a path.
+ */
+export function getNavigationSection(currentPath) {
+  return navigation.find(
+    (item) => item.section && item.children && containsPath(item.children, currentPath),
+  ) || null;
+}
+
 /**
- * Given a path, return { prev, next } objects or null.
+ * Given a path, return adjacent pages from the same documentation section.
  */
 export function getPrevNext(currentPath) {
-  const flat = flattenNavigation();
+  const section = getNavigationSection(currentPath);
+  const flat = flattenNavigation(section ? [section] : navigation);
   const index = flat.findIndex((item) => item.path === currentPath);
   if (index === -1) return { prev: null, next: null };
   return {
diff --git a/styles/globals.css b/styles/globals.css
index c40d9ae..bf88f1c 100644
--- a/styles/globals.css
+++ b/styles/globals.css
@@ -738,6 +738,11 @@ html.dark .search-pill {
   text-decoration: none;
 }
 
+.header-nav-link-active {
+  background: var(--active-bg);
+  color: var(--color-text-title);
+}
+
 /* Header group dividers */
 .header-divider {
   display: none;
@@ -921,6 +926,10 @@ html.dark .header-divider {
   list-style: none;
 }
 
+.sidebar-section-switcher {
+  display: none;
+}
+
 .sidebar-section {
   margin-top: var(--space-4);
   padding-top: var(--space-4);
@@ -1950,6 +1959,46 @@ html.dark .search-result-snippet mark {
   }
 }
 
+@media (max-width: 1099px) {
+  .sidebar-section-switcher {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-1);
+    margin: 0 0 var(--space-3);
+    padding: 0 var(--space-3) var(--space-3);
+    border-bottom: 1px solid var(--color-border);
+  }
+
+  .sidebar-section-switcher-title {
+    padding: var(--space-1) var(--space-2);
+    font-size: 12px;
+    font-weight: 700;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: var(--color-text-secondary);
+  }
+
+  .sidebar-section-switcher-link {
+    padding: 6px var(--space-2);
+    border-radius: var(--radius-sm);
+    color: var(--color-text-sidebar);
+    font-size: 14px;
+    line-height: 20px;
+  }
+
+  .sidebar-section-switcher-link:hover {
+    background: var(--hover-bg);
+    color: var(--color-text-title);
+    text-decoration: none;
+  }
+
+  .sidebar-section-switcher-link-active {
+    background: var(--active-bg);
+    color: var(--color-text-title);
+    font-weight: 500;
+  }
+}
+
 /* Tablet: reduce content padding, narrow sidebar */
 @media (min-width: 769px) and (max-width: 1024px) {
   :root {
@@ -2026,6 +2075,10 @@ html.dark .search-result-snippet mark {
     color: var(--color-text-primary);
   }
 
+  .sidebar-section-switcher {
+    padding-right: calc(var(--space-3) + 40px);
+  }
+
   .sidebar-overlay {
     display: block;
     position: fixed;

From dfc988d790b2f8be4a5f558c098ed5541372bb23 Mon Sep 17 00:00:00 2001
From: Kristofer Lund <kristofer@fmckl.se>
Date: Tue, 15 Sep 2026 14:47:12 +0200
Subject: [PATCH 3/7] docs: make the guide a narrative learning path

---
 docs/information-architecture.md              |  22 ++-
 lib/navigation.js                             |  79 ++---------
 pages/architecture/data-flow-and-lifecycle.md | 107 +++-----------
 pages/architecture/overview.md                |   2 +-
 pages/architecture/portability-and-scaling.md |  60 +++-----
 pages/core-concepts/cel-work-scopes.md        |  60 +++-----
 pages/core-concepts/certified-identity.md     |  70 +++-------
 pages/core-concepts/common-use-cases.md       |  51 ++++---
 pages/core-concepts/evaluations.md            |  36 +++++
 .../evidence-and-measurements.md              |  38 +++++
 pages/core-concepts/funding-and-value-flow.md |  73 ++++------
 .../hypercerts-core-data-model.md             | 132 ++++--------------
 .../core-concepts/projects-and-collections.md |  42 ++++++
 .../validation-and-interpretation.md          |  69 +++------
 pages/core-concepts/what-is-hypercerts.md     |  78 +++--------
 pages/core-concepts/why-at-protocol.md        |  34 +++--
 pages/ecosystem/why-we-need-hypercerts.md     |   2 +-
 .../getting-started/building-on-hypercerts.md |   2 +-
 .../getting-started/testing-and-deployment.md |   2 +-
 pages/guide/index.md                          |  67 +++------
 pages/index.md                                |  33 ++---
 pages/reference/faq.md                        |   2 +-
 pages/reference/glossary.md                   |   2 +-
 pages/reference/lexicon-inventory.md          |   2 +-
 24 files changed, 409 insertions(+), 656 deletions(-)
 create mode 100644 pages/core-concepts/evaluations.md
 create mode 100644 pages/core-concepts/evidence-and-measurements.md
 create mode 100644 pages/core-concepts/projects-and-collections.md

diff --git a/docs/information-architecture.md b/docs/information-architecture.md
index 0edc441..1e05a9a 100644
--- a/docs/information-architecture.md
+++ b/docs/information-architecture.md
@@ -11,6 +11,19 @@ This is the working migration map for the protocol-first documentation restructu
 - Existing public routes remain stable during the first pass unless their content has been explicitly retired.
 - A proposal in the third editor's draft is not a protocol requirement unless it is independently ratified and reflected in authoritative sources.
 
+## Guide reader journey
+
+The landing page introduces the promise; the Guide explains how it works; Client Integration helps readers build; Reference supplies the details they look up along the way.
+
+Assume readers have seen the landing page, with an optional link to `https://hypercerts.org` at the start for those who haven't. The Guide follows the same story one level deeper: reuse existing knowledge, connect contributions from different people, build a fuller picture over time, and bring it into funding decisions.
+
+- Begin with familiar questions and explain technical terms at the point they become useful. Introduce AT Protocol, repositories, Lexicons, and indexers early enough to explain cross-application reuse.
+- Give activities, projects, evidence, and evaluations recognizable concept pages. Explain what they are and why a reader would use them before discussing schema details.
+- Use short illustrative examples. Keep field inventories, exhaustive validation rules, and implementation contracts in Reference or Client Integration.
+- Explain a limitation alongside the decision it affects, rather than opening each page with a list of things the protocol cannot do.
+- Keep the Guide navigation flat and ordered for a start-to-finish reading path. Each page leads to the next; the final page leads to Client Integration with its current implementation status clear.
+- Treat the older vision essay as separate background, outside the sequential Guide. It includes historical economic ideas that would interrupt the current learning path.
+
 ## First-pass migration
 
 | Previous area | New primary home | Treatment |
@@ -22,7 +35,7 @@ This is the working migration map for the protocol-first documentation restructu
 | Architecture | Guide or Reference | Put lifecycle and portability guidance in Guide; put system and service architecture in Reference; put account setup in Client Integration. |
 | Lexicons and service directories | Reference | Keep existing routes and expand source-backed coverage. |
 | Lexicon releases | Change History | Keep the imported upstream changelog and add adopter-facing migration context separately. |
-| Ecosystem and vision | Guide | Keep protocol-purpose content in the conceptual path. |
+| Ecosystem and vision | Separate background | Retain the existing essay route outside the sequential Guide; the landing page provides the high-level introduction. |
 | Roadmap | Unassigned | Keep the source for now, but do not mix planned capabilities into supported instructions or change history. |
 
 ## Third editor's draft disposition
@@ -49,12 +62,7 @@ The draft at `https://claude.ai/code/artifact/cf891a57-416c-4d63-8ec3-8194e6cb6e
 
 ### Guide
 
-- Protocol and infrastructure boundaries
-- Record identity, versions, and references
-- Identity, authority, trust, and corroboration
-- Validation and extensibility
-- Aggregation and interpretation
-- Known limitations and open semantic questions
+The narrative path now covers the main concepts, common usage, and the handoff to building. Further work should test whether newcomers can explain the system and choose a useful integration after reading it, rather than expand the Guide into a field-by-field reference.
 
 ### Client Integration
 
diff --git a/lib/navigation.js b/lib/navigation.js
index 43a2639..8b3a2cd 100644
--- a/lib/navigation.js
+++ b/lib/navigation.js
@@ -2,71 +2,20 @@ export const navigation = [
   {
     section: "Guide",
     children: [
-      { title: "Guide overview", path: "/guide" },
-      {
-        title: "Foundations",
-        children: [
-          {
-            title: "What are Hypercerts?",
-            path: "/core-concepts/what-is-hypercerts",
-          },
-          {
-            title: "Why AT Protocol?",
-            path: "/core-concepts/why-at-protocol",
-          },
-          {
-            title: "Core Data Model",
-            path: "/core-concepts/hypercerts-core-data-model",
-          },
-          {
-            title: "Common Use Cases",
-            path: "/core-concepts/common-use-cases",
-          },
-        ],
-      },
-      {
-        title: "Meaning and trust",
-        children: [
-          {
-            title: "Identity, Authorship & Trust",
-            path: "/core-concepts/certified-identity",
-          },
-          {
-            title: "Work Scopes & Classification",
-            path: "/core-concepts/cel-work-scopes",
-          },
-          {
-            title: "Funding Records & Value Flow",
-            path: "/core-concepts/funding-and-value-flow",
-          },
-        ],
-      },
-      {
-        title: "Shared operation",
-        children: [
-          {
-            title: "Records, References & Lifecycle",
-            path: "/architecture/data-flow-and-lifecycle",
-          },
-          {
-            title: "Public Data, Discovery & Portability",
-            path: "/architecture/portability-and-scaling",
-          },
-          {
-            title: "Validation, Extension & Interpretation",
-            path: "/core-concepts/validation-and-interpretation",
-          },
-        ],
-      },
-      {
-        title: "Background",
-        children: [
-          {
-            title: "Why Hypercerts Matter",
-            path: "/ecosystem/why-we-need-hypercerts",
-          },
-        ],
-      },
+      { title: "Start Here", path: "/guide" },
+      { title: "Why AT Protocol?", path: "/core-concepts/why-at-protocol" },
+      { title: "A Shared Language", path: "/core-concepts/hypercerts-core-data-model" },
+      { title: "Activity Claims", path: "/core-concepts/what-is-hypercerts" },
+      { title: "Projects and Collections", path: "/core-concepts/projects-and-collections" },
+      { title: "Evidence and Measurements", path: "/core-concepts/evidence-and-measurements" },
+      { title: "Evaluations", path: "/core-concepts/evaluations" },
+      { title: "Trust and Recognition", path: "/core-concepts/certified-identity" },
+      { title: "Funding and Learning", path: "/core-concepts/funding-and-value-flow" },
+      { title: "Describing and Classifying Work", path: "/core-concepts/cel-work-scopes" },
+      { title: "Records That Change Over Time", path: "/architecture/data-flow-and-lifecycle" },
+      { title: "Finding and Reusing Information", path: "/architecture/portability-and-scaling" },
+      { title: "What You Can Build", path: "/core-concepts/common-use-cases" },
+      { title: "Building on Shared Records", path: "/core-concepts/validation-and-interpretation" },
     ],
   },
   {
diff --git a/pages/architecture/data-flow-and-lifecycle.md b/pages/architecture/data-flow-and-lifecycle.md
index 0651a41..c6a3463 100644
--- a/pages/architecture/data-flow-and-lifecycle.md
+++ b/pages/architecture/data-flow-and-lifecycle.md
@@ -1,107 +1,44 @@
 ---
-title: Records, References & Lifecycle
-description: How AT Protocol record slots, versions, references, updates, deletion, and reverse discovery shape Hypercerts.
+title: Records That Change Over Time
+description: Understand how updates, versions, and links let a project's public record grow without losing the context of earlier assessments.
 ---
 
-# Records, References & Lifecycle
+# Records That Change Over Time
 
-Hypercerts records do not follow one mandatory sequence. An activity may be published before, during, or after work. Context can appear later from other repositories. Records may also be updated or deleted. The durable model is therefore based on record identity, version identity, and explicit references rather than a fixed workflow.
+A team updates an activity description. An evaluator has already reviewed the earlier version. How can a reader tell what the evaluation was about?
 
-## Record slots and versions
+Hypercerts uses AT Protocol's record addresses and content identifiers to distinguish a record from a particular version of it.
 
-An AT-URI identifies a record slot:
+## Give each record an address
 
-```text
-at://did:plc:alice/org.hypercerts.claim.activity/3k7
-```
+Every repository record has an **AT-URI**, its address on the network. It identifies the publishing account, the kind of record, and the record's key within that account.
 
-The three meaningful parts are the publishing repository DID, the Lexicon collection, and the record key. The record stored at that slot can change or disappear.
+The address is separate from the website that displays the record. A project dashboard and an evaluation tool can therefore link to the same activity, even though each presents it on a different web page.
 
-A CID is the content identifier for one exact version. Updating a record changes its CID while retaining the AT-URI. Deleting a source record removes it from its repository, although relays, indexers, caches, or prior recipients may retain copies.
+If the publisher updates the activity at that address, it is still the same record, now with different contents.
 
-## Relationship forms
+## Know which version was reviewed
 
-### Strong references
+A **CID**, or content identifier, identifies the record's contents. Changing the contents changes the CID.
 
-A strong reference pairs the AT-URI with a CID:
+A **strong reference** combines an AT-URI with a CID. It says both “this record” and “this version.” An evaluation that links this way keeps pointing to the version it assessed, even after the team changes its activity description.
 
-```json
-{
-  "uri": "at://did:plc:alice/org.hypercerts.claim.activity/3k7",
-  "cid": "bafyreib2rxk3rh6kzwq7..."
-}
-```
+A reading app can then tell the user that the assessment concerns an earlier version. It should not silently present that assessment as a review of the changed claim. The reference identifies the older contents, but retrieving them still depends on a service having retained that version.
 
-This records which version the publisher referred to. If the record at that URI is later updated, a consumer can detect that the current CID differs.
+Some relationships deliberately follow a record across updates. For example, following a project can use its AT-URI without a CID. The appropriate form depends on whether the relationship concerns a specific version or the ongoing record.
 
-A strong reference does not freeze the target, ensure it remains available, prove its contents, or enforce the target Lexicon named in a field description. Consumers must apply those checks.
+## Add context without editing someone else's work
 
-### URI-only record subjects
+An evaluation, measurement, or attachment can be published as a new record linking to an existing activity. The publisher of the activity doesn't have to add it to a list or edit the original description.
 
-Some relationships should survive updates. `app.certified.defs#recordSubject`, used by entity follows, stores an AT-URI without a CID. It follows the record slot rather than one version.
+The link lives in the new record. To show “all evaluations of this activity,” an app needs to find records pointing back to it. An indexer helps answer that question across accounts.
 
-### DIDs and embedded values
+## What if a record disappears?
 
-A DID identifies an AT Protocol account rather than one record. Embedded objects and strings carry information inside the source record and have no separately addressable lifecycle.
+Publishers can delete records from their repositories. Links to a deleted record may remain in other people's evaluations, collections, or receipts. Copies may also remain elsewhere.
 
-## Forward references and backlinks
+A useful app keeps the link and explains that the target is unavailable. This preserves what the publisher referred to instead of substituting a different record or pretending the relationship never existed.
 
-Relationships are stored only in the source record. For example:
+For a technical overview of the services involved, see [Architecture](/architecture/overview).
 
-- An activity points to reusable contributor, contribution, rights, location, and work-scope records.
-- A collection points to its activity, feature, or nested-collection items.
-- An attachment or measurement points to zero or more subjects.
-- An evaluation points to at most one primary subject and may point to supporting measurements.
-- A receipt may point to the work or organization it funded.
-
-AT Protocol repository reads can retrieve a known source record. They do not natively answer "which records across the network point to this activity?" That reverse query requires an indexer or another backlink service.
-
-```mermaid
-flowchart LR
-  P1["Project repository"] --> A["Activity"]
-  P2["Evaluator repository"] --> E["Evaluation"]
-  P3["Funder or facilitator repository"] --> R["Funding receipt"]
-  E -->|strongRef to assessed version| A
-  R -->|strongRef to funded subject| A
-  I["Indexer"] -.observes and joins.-> A
-  I -.observes and joins.-> E
-  I -.observes and joins.-> R
-  I --> V["Application view"]
-```
-
-The completeness of an assembled hypercert depends on what the indexer observed, retained, and chose to expose.
-
-## Common lifecycle events
-
-### Create
-
-A client writes a record to a repository. The PDS accepts it into the repository and the repository's signed commit history attributes publication to that DID. Hypercerts Lexicon validation is normally a client, SDK, or indexing responsibility; do not assume every PDS enforces domain schemas.
-
-### Update
-
-The publisher replaces the contents at the same AT-URI. New readers see the new CID. Existing strong references continue to identify the earlier version they cited, provided that version remains available from a source or cache.
-
-### Add context
-
-Another publisher creates a separate record that points to an existing subject. No update to the subject is required. This is how evaluations, measurements, attachments, acknowledgements, badges, and receipts can accumulate across repositories.
-
-### Delete
-
-The publisher deletes the record from its repository. References to it become unresolved against the current source. Consumers should preserve the reference and its CID, mark the target unavailable, and avoid silently substituting another version.
-
-### Discover and aggregate
-
-Relays and indexers can observe records from many repositories and build reverse-reference indexes, search, hydrated views, totals, and rankings. These are derived services with explicit coverage and policy, not canonical fields in the source graph.
-
-## Consumer rules
-
-A compatible consumer should:
-
-1. Preserve source AT-URIs and version CIDs.
-2. Distinguish the current record from the version a strong reference cited.
-3. Show stale, missing, or deleted targets rather than silently repairing them.
-4. Validate that a referenced record has the expected collection and semantics.
-5. Identify the indexer and coverage assumptions behind backlinks and aggregates.
-6. Keep derived values separate from source records.
-
-Next: [Public Data, Discovery & Portability](/architecture/portability-and-scaling).
+Next: [Finding and Reusing Information](/architecture/portability-and-scaling), where these individual links become useful project views.
diff --git a/pages/architecture/overview.md b/pages/architecture/overview.md
index 0c24198..37dfb66 100644
--- a/pages/architecture/overview.md
+++ b/pages/architecture/overview.md
@@ -25,7 +25,7 @@ A client writes a record to a repository through a PDS or managed service. A rel
 
 ![Data flow through ATProto](/images/architecture-dataflow.svg)
 
-For record versions, relationship directions, and reverse discovery, see [Records, References & Lifecycle](/architecture/data-flow-and-lifecycle).
+For an introduction to record versions, links, and discovery, see [Records That Change Over Time](/architecture/data-flow-and-lifecycle).
 
 ## Why It's Trustworthy
 
diff --git a/pages/architecture/portability-and-scaling.md b/pages/architecture/portability-and-scaling.md
index 161c73a..6a791e6 100644
--- a/pages/architecture/portability-and-scaling.md
+++ b/pages/architecture/portability-and-scaling.md
@@ -1,60 +1,42 @@
 ---
-title: Public Data, Discovery & Portability
-description: How source records, repository migration, relays, indexers, availability, and public-data limits differ.
+title: Finding and Reusing Information
+description: How apps bring records from different accounts together and let people reuse them beyond the place they were published.
 ---
 
-# {% $markdoc.frontmatter.title %}
+# Finding and Reusing Information
 
-Hypercerts uses public AT Protocol repository records so independent applications can read and connect them. Publication, availability, discovery, and presentation are different operations, and none guarantees the others.
+A project description lives with the project. An assessment lives with its publisher. Funding receipts may come from several platforms. To show a useful project page, an application needs to find these pieces and connect them.
 
-## Public source records
+This is where indexing services help turn shared records into something people can browse and use.
 
-Records in the released Hypercerts and Certified collections should be treated as public. Do not publish secrets, private contact details, confidential applications, access tokens, or personal data that should not be replicated.
+## From individual records to a project view
 
-A source record being public does not mean every application will discover or display it. A reader may need its AT-URI, access to the current PDS, or an indexer that has observed it.
+If an app knows a record's address, it can read it from the account's PDS. For broader questions, such as “which projects have recent evaluations?”, it usually queries an indexer.
 
-## Switching PDSs
+A **relay** helps carry updates from repositories across the network. An **indexer** collects records it is interested in and organizes them for queries. It can track links, find evaluations of an activity, and assemble information for a project page.
 
-AT-URIs use a DID rather than a server address. When an AT Protocol account migration preserves the DID, repository records can retain their identifiers after the DID document points to the new PDS.
+The app adds the interface: a timeline, an evidence browser, a funding dashboard, or a comparison tool. It may show the same records in a very different way from the app that published them.
 
-Migration still depends on a correct repository transfer, DID update, supported account state, and consumers resolving the current DID document. Applications and stale caches do not necessarily update immediately. See the [AT Protocol account migration guide](https://atproto.com/guides/account-migration) for the protocol process.
+## Different views can serve different needs
 
-## Discovery and indexed views
+A community directory may focus on local projects. A research tool may show assessments by a particular group of experts. Both can use Hypercerts without indexing every kind of record or adopting the same ranking method.
 
-Cross-repository applications commonly use relays and indexers:
+This also explains why a missing search result doesn't necessarily mean a record doesn't exist. The index may not cover that account, may not support the record type, or may still be catching up with updates.
 
-- A PDS hosts the current source repository.
-- A relay observes repositories and emits events according to its crawl and policy scope.
-- An indexer consumes selected events, resolves relationships, and builds queryable views.
-- An application reads those views and may also fetch source records directly.
+When an app presents a total or a summary, it helps to say what it includes and link back to the source records. Readers can then understand the view they are seeing.
 
-No index is inherently complete. Coverage can differ by repositories, collections, time range, moderation policy, retention, and failed ingestion. Applications should identify the source of aggregate claims and avoid presenting "not indexed" as "does not exist."
+## Reuse information beyond one app
 
-## Switching applications
+Because the record formats are public, a new application can support them without inventing an export format with each existing platform. A project can use one tool for publishing updates and another for sharing its work with funders.
 
-Shared Lexicons make it possible for another application to parse a source record without a bilateral data export. Practical interoperability still depends on the second application supporting:
+The second app still needs to support the relevant formats and features. Shared records make reuse possible; they don't make every app identical.
 
-- The record's Lexicon version and shared usage conventions.
-- Authentication and permissions for any writes.
-- The relevant repository or indexer coverage.
-- Unknown fields, record types, and values without data loss.
-- Product-specific workflows that are not encoded in the protocol.
+People can also move their account to another supported PDS while preserving its DID. The record addresses can stay the same because they identify the account, rather than its current server. Hosting choices can change without giving the project a completely new identity.
 
-An application can therefore build on the same records without every application having identical features or trust policies.
+## Publish what is meant to be shared
 
-## Updates, deletion, and persistence
+This reuse depends on public records. Keep confidential applications and private personal information in systems suited to that purpose, and publish the information people intend to make available across the network.
 
-Publishers can update and delete repository records. Other systems may retain prior versions, indexed copies, screenshots, exports, or references. Deleting the source is not a guarantee that all public copies disappear.
+Deleting a public record from its source doesn't remove every copy others may have kept. Think of publishing here as sharing information openly, rather than placing it in a private project workspace.
 
-Consumers should distinguish:
-
-- Current source state from cached or historical state.
-- A missing record from one outside the indexer's coverage.
-- An unavailable PDS from a deleted record.
-- A strong reference to an older CID from a broken reference.
-
-## Operational limits
-
-Portability does not by itself guarantee availability. DIDs must resolve, PDSs must serve repositories, and indexing paths must remain healthy. Applications that depend on durable access should define retry, cache, source-verification, and outage behavior without presenting a cache as the source of truth.
-
-Next: [Validation, Extension & Interpretation](/core-concepts/validation-and-interpretation).
+Next: [What You Can Build](/core-concepts/common-use-cases), using these connections as the starting point for your own application.
diff --git a/pages/core-concepts/cel-work-scopes.md b/pages/core-concepts/cel-work-scopes.md
index c5de702..4467a1e 100644
--- a/pages/core-concepts/cel-work-scopes.md
+++ b/pages/core-concepts/cel-work-scopes.md
@@ -1,60 +1,36 @@
 ---
-title: Work Scopes and Classification
-description: How Hypercerts records describe and classify the work covered by a claim.
+title: Describing and Classifying Work
+description: Help people and applications understand what an activity covers and find related projects.
 ---
 
-# Work Scopes and Classification
+# Describing and Classifying Work
 
-A work scope describes what an activity covers. Classification tags describe projects, features, and reusable categories. The released model keeps these concerns separate.
+People describe similar work in different ways. That is fine for a conversation, but it makes searching and comparing projects harder. Shared terms help an application recognize connections without throwing away the detail in people's descriptions.
 
-## Activity work scopes
+Hypercerts offers two related tools: work scopes for activities, and classification tags for collections and features.
 
-An activity's `workScope` can contain either:
+## Say what an activity covers
 
-- A free-form work-scope string for human-readable descriptions.
-- An embedded `org.hypercerts.workscope.cel` object for machine-readable expressions.
+A **work scope** explains the work included in an activity claim. For an open-source project, it might say “maintenance of the mapping library, including bug fixes and documentation.” This helps a reader understand what the claim covers and what would belong in another activity.
 
-The CEL object is embedded inside the activity; it is not a repository record. It contains an expression, a version, and `usedTags`, which are strong references to `org.hypercerts.workscope.tag` records.
+A plain-text scope is often enough. When applications need to compare or combine scopes more precisely, there is also a structured form using **Common Expression Language (CEL)**. It combines shared work-scope terms with logical expressions instead of relying on wording alone.
 
-Work-scope tags are reusable atoms for expressions. They can identify a parent tag, an equivalent external concept, or a replacement tag. Applications still need to decide which publishers and vocabularies they recognize.
+You don't need to learn that expression language to understand the Guide. The choice is practical: use a readable description when people need an explanation, and consider the structured form when software needs a shared way to reason about the scope.
 
-## General classification
+## Help people find related projects
 
-`org.hypercerts.vocab.tag` provides broader classifications for:
+**Vocabulary tags** classify collections, including projects, and features such as land areas. They can help a directory group projects by subject or let a funder find work in a field it supports.
 
-- `org.hypercerts.collection` records, including project collections.
-- `org.hypercerts.entity.feature` records.
+These classification tags have a different job from an activity's work scope. A project category helps people find the project; a work scope says which work an activity covers. They use separate schemas.
 
-General vocabulary tags can name broader concepts, equivalent external concepts, and superseding tags. The attached tags apply together by the released convention; they do not provide the Boolean expression language used by activity work scopes.
+## Share terms, not just labels
 
-## The three related schema families
+A reusable tag is a record with its own publisher and identifier. Two tags called “restoration” may mean different things if different organizations define them. Keeping the link to the actual tag lets another app inspect the intended meaning.
 
-- `org.hypercerts.workscope.cel` defines the structured Common Expression Language (CEL) object used by work-scope fields.
-- `org.hypercerts.workscope.tag` defines reusable terms used in work-scope expressions.
-- `org.hypercerts.vocab.tag` provides broader classification tags outside the work-scope expression model.
+Tags can also relate to broader terms, external concepts, or replacement terms. Communities can develop vocabularies suited to their field, while applications choose which vocabularies to recognize.
 
-These replace the older `org.hypercerts.ontology.*` names that appeared in previous documentation drafts.
+This gives shared structure room to grow. An app can show an unfamiliar term with its source instead of silently translating it into a category that means something else.
 
-## Shared usage guidance
+The [Lexicon inventory](/reference/lexicon-inventory) lists the work-scope and vocabulary schemas when you need their exact definitions.
 
-- Use a simple textual scope when shared machine interpretation is not required.
-- Use a CEL scope when consumers need to apply logical operations to shared work-scope terms.
-- Use general vocabulary tags for classification of a collection or feature, not as a substitute for an activity's work-scope expression.
-- Preserve the publisher's AT-URI with every referenced tag. Matching names or keys from different repositories do not establish identical meaning.
-- Follow `supersededBy` and hierarchy relationships according to an explicit application policy. The Lexicons do not prevent cycles or invalid hierarchies.
-- Preserve unknown `knownValues`, tags, and CEL versions even when the application cannot interpret them.
-- Do not describe a scope or classification as verified merely because it passes structural validation.
-
-## Open values and governance
-
-Lexicon `knownValues` are open suggestions, not closed enums. A writer may publish another value that remains structurally valid. This supports extension, but it also means interoperable applications need fallback behavior.
-
-Vocabulary authority is similarly contextual. The DID in a tag's AT-URI identifies its publisher. It does not make that publisher universally authoritative for a domain. Applications should state which tag publishers they recognize and retain the original source when presenting normalized categories.
-
-For exact fields and constraints, use the released `@hypercerts-org/lexicon` package and the [Lexicon inventory](/reference/lexicon-inventory). Tested SDK examples remain part of the evolving [Client Integration](/client-integration) path.
-
-## Related pages
-
-- [Core Data Model](/core-concepts/hypercerts-core-data-model)
-- [Validation, Extension & Interpretation](/core-concepts/validation-and-interpretation)
-- [Lexicon inventory](/reference/lexicon-inventory)
+Next: [Records That Change Over Time](/architecture/data-flow-and-lifecycle), to see how these connections behave when information is updated.
diff --git a/pages/core-concepts/certified-identity.md b/pages/core-concepts/certified-identity.md
index 8c2f6b5..86961ac 100644
--- a/pages/core-concepts/certified-identity.md
+++ b/pages/core-concepts/certified-identity.md
@@ -1,70 +1,40 @@
 ---
-title: Identity, Authorship & Trust
-description: How repository publishers, named actors, signatures, acknowledgements, and application trust policies differ.
+title: Trust and Recognition
+description: Understand who stands behind information and how assessments, endorsements, and responses help people make decisions.
 ---
 
-# Identity, Authorship & Trust
+# Trust and Recognition
 
-Every Hypercerts record is addressed inside an AT Protocol repository identified by a DID. This makes its publication attributable, but attribution is only one input to trust.
+A project update, a neighbor's endorsement, and an expert assessment each tell you something different. Together, they can give you more confidence in the work, or reveal questions you need to investigate.
 
-## Four claims to keep separate
+Hypercerts makes these contributions visible and connects them to their sources. Deciding which ones to rely on remains a matter of judgment.
 
-| Claim | What it means |
-|---|---|
-| **Repository publisher** | The DID in the AT-URI identifies the repository that published the record. Signed repository commits make unauthorized changes detectable. |
-| **Named actor** | A record can name contributors, evaluators, senders, recipients, issuers, or subjects. Those fields are assertions and may not identify the repository publisher. |
-| **Record-content attestation** | Many released records optionally carry inline signatures or references to remote proof records. These are separate from AT Protocol repository signatures. |
-| **Application trust** | A client decides which publishers, evidence, attestations, and corroborating records it accepts for a purpose. The protocol does not calculate one global trust score. |
+## Start with who published it
 
-## DIDs and repositories
+Every record belongs to an AT Protocol account. Its DID identifies that account, and the repository's signed history lets software check that a version was published by it. A profile gives people a more readable introduction to the person or organization behind the account.
 
-A DID such as `did:plc:z72i7hdynmk6r22z27h6tvur` identifies an AT Protocol account independently of its current handle or PDS host. DID resolution provides the service location and verification methods needed by AT Protocol clients.
+This answers “which account published this?” It is a starting point for asking “why should I trust it?” A familiar research organization, a local community group, and an unknown account may all publish assessments, but a reader will weigh them differently.
 
-AT-URIs include this DID. For example, `at://did:plc:example/org.hypercerts.claim.activity/3k7` attributes the record slot to that repository. A CID identifies one version of the record contents.
+Also distinguish the publisher from the people named in the record. A platform might publish a receipt naming a funder and recipient. A team might name several contributors. Those names tell you what the publisher is saying; confirmation from the named parties adds another source.
 
-Do not describe every actor-like field as a DID:
+## Make recognition explicit
 
-- Activity contributor identities can contain a DID or another identifier string.
-- Contributor information can identify a person through a DID or social-profile URI by convention.
-- Evaluation `evaluators` are DID objects, but the schema does not require one of them to be the repository publisher.
-- Receipt parties can be text, a DID, or a strong reference to another record.
+**Badges** let a network or certifier recognize an account or a record, such as a project. A badge definition explains the recognition being offered. A badge award connects that definition to its recipient. A separate response lets the recipient accept or reject the award.
 
-## Organization records
+For example, a network could define a badge for a certification and award it to a project it has reviewed. An app displaying that badge needs to check who awarded it and whether that issuer is recognized by the certification scheme. The badge's name or icon alone tells you little.
 
-An organization can use an AT Protocol account containing two singleton records:
+An **acknowledgement** is another kind of response: it records acceptance or rejection of a subject or relationship. It can let someone confirm a contribution attributed to them, for example. The response is useful when the app checks that it came from the relevant account.
 
-- `app.certified.actor.profile/self` for general profile information.
-- `app.certified.actor.organization/self` for organization-specific metadata.
+Some records also support additional signatures on their contents. These can provide further confirmation from a signer, separate from the signature on the publishing repository.
 
-Their association is the shared repository identity and `self` key. The released schemas do not define members, administrators, ownership, or links from an organization to its projects. Multi-user repository governance is an infrastructure concern described in the [Certified Group Service](/architecture/certified-group-service) Reference.
+## Trust grows through useful contributions
 
-## Corroboration records
+A funder may value a specialist's technical assessment. Community members may give more weight to experiences reported by neighbors. Both can use the same connected records without agreeing on a single score.
 
-The graph can accumulate independent responses without changing the original assertion:
+More records do not automatically mean more trust. A contradictory evaluation may reduce confidence while making the overall picture more informative. A helpful app lets readers see the source, the reasoning, and the differences between accounts.
 
-- An acknowledgement accepts or rejects a subject or relationship from another repository.
-- A badge response records a response to a badge award separately from the award itself.
-- An evaluation can cite measurements and publish its own assessment of a subject.
-- Optional signatures can attest to record content through a verification method or proof record.
+This matters for AI-assisted decisions too. An agent can follow the same links to evidence and assessments, rather than rely only on the polish of a project's written pitch. Its conclusions still depend on the sources and judgment rules it uses.
 
-None of these relationships is automatically reciprocal. An award does not imply acceptance, a contributor mention does not prove participation, and an evaluation does not prove independence merely because it is stored separately.
+For record details, see [Badges](/lexicons/certified-lexicons/badge-definition) and [Acknowledgements](/lexicons/hypercerts-lexicons/acknowledgement). [Account & Identity Setup](/architecture/account-and-identity) explains how accounts work in practice, including the Certified account service.
 
-## From provenance to trust
-
-A compatible application should show or preserve:
-
-1. The source AT-URI and version CID.
-2. The repository DID that published the record.
-3. Actors named inside the record.
-4. Acknowledgements, responses, signatures, and evidence that corroborate or challenge it.
-5. The application's own inclusion, ranking, and authority policy.
-
-This supports plural trust models. A community, certifier, funder, and automated agent can evaluate the same graph differently while working from attributable source records.
-
-## Certified as one access path
-
-[Certified](https://certified.app) provides Hypercerts-oriented accounts and organization tooling. It is one provider and application surface, not the identity layer of the protocol itself. Existing AT Protocol identities may be usable where an application supports their authentication and the required permissions.
-
-For account creation, OAuth, service environments, and organization-managed writes, use [Account & Identity Setup](/architecture/account-and-identity) and [Client Integration](/client-integration).
-
-Next: [Work Scopes & Classification](/core-concepts/cel-work-scopes).
+Next: [Funding and Learning](/core-concepts/funding-and-value-flow), where these signals become useful to the next funding decision.
diff --git a/pages/core-concepts/common-use-cases.md b/pages/core-concepts/common-use-cases.md
index 78fd741..1ba34ea 100644
--- a/pages/core-concepts/common-use-cases.md
+++ b/pages/core-concepts/common-use-cases.md
@@ -1,39 +1,48 @@
 ---
-title: Common Use Cases
-description: See how common funding and evaluation scenarios map to the Hypercerts record graph.
+title: What You Can Build
+description: Explore how project tools, evaluation services, funding platforms, and agents can build on shared information.
 ---
 
-# Common Use Cases
+# What You Can Build
 
-These examples show how domain workflows can use the same record graph. They are conceptual mappings, not tested SDK or XRPC instructions.
+You don't have to build the whole journey from project reporting to funding. You can make one part of it better, using information others publish and contributing something useful in return.
 
-## Open-source software maintenance
+Here are some ways the building blocks in this Guide could come together.
 
-A team publishes an activity for a year of library maintenance. Contributor entries describe maintainers and roles. Attachments link releases and reports; measurements describe issues resolved or downloads; peer evaluators publish assessments. A project collection can group annual activities, and receipts can record prospective or retroactive support.
+## Help projects tell their story once
 
-## Regenerative land stewardship
+A project dashboard could help a team describe its work, organize activities, and publish updates with evidence. The team uses a familiar interface, while the application publishes shared records that other tools can read.
 
-A project collection with `type: "project"` groups restoration activities and the land areas they concern. Feature records represent zones or strata; location records provide spatial representations. Attachments link satellite imagery and reports, measurements describe observations, and community or expert evaluations assess the work. Receipts can point to the project collection or a specific activity.
+For a land stewardship project, that might mean grouping restoration activities and land areas, linking field observations, and showing progress across seasons. The resulting history can be useful to the next funder as well as to the team itself.
 
-## Scientific research
+## Make expertise easier to contribute
 
-A research activity identifies contributors and reusable contribution details. Attachments link papers, data, and protocols. Measurements can describe outputs; evaluations record peer assessments and cite relevant measurements. A funding receipt records support but does not establish research quality or payment settlement by itself.
+An evaluation tool could help reviewers find work in their field, inspect evidence, and publish assessments. The useful contribution is the reviewer's insight, made available beyond the process that first requested it.
 
-## Community event organization
+For research, this might mean an assessment of methods and findings. For open-source software, it might mean a review of maintenance quality and the experience of teams that depend on the library. Each field can choose its own questions and methods.
 
-A program collection groups workshop activities and optional cohort features. Contributor entries identify instructors and hosts. Attachments provide materials and reports; measurements record attendance or outcomes; participant or expert evaluations add assessments. Acknowledgements can confirm particular relationships without turning them into protocol-wide truth.
+## Bring existing knowledge into funding decisions
 
-## Certifications and network recognition
+A funding platform could read project information and earlier assessments, ask only for the additional context its process needs, and record support afterward.
 
-A network or certifier publishes a badge definition and then an award whose subject is an account or project record. The recipient can publish a separate badge response. The award does not imply acceptance, and the definition's issuer list requires application-level authorization checks.
+Crowdfunding with matching funds is an existing application described on the [landing page](https://hypercerts.org). Other mechanisms, such as outcome payments or milestone bounties, could use similar information, with their own selection and payment rules.
 
-## What remains application-specific
+## Make recognition easier to discover
 
-In every scenario, applications still decide:
+A network directory could show projects alongside certifications or endorsements from organizations its users recognize. It could explain who awarded each badge and link to supporting assessments.
 
-- Which publishers, evaluators, certifiers, and vocabularies they trust.
-- Which records their index includes and how backlinks are resolved.
-- How source data becomes forms, search, rankings, totals, or recommendations.
-- How private operational data and payment execution stay outside public records.
+A funder exploring a new field could use that directory to find relevant projects and people with expertise, then inspect the underlying records rather than rely only on a list of names.
 
-For implementation status, use [Client Integration](/client-integration). For exact schemas, use the [Lexicon inventory](/reference/lexicon-inventory).
+## Give agents useful sources to work with
+
+An agent could help a project prepare an update, find relevant evaluations for a funder, or flag a question that needs human review. Shared formats make it easier to distinguish a project's claim from someone else's assessment and follow each back to its source.
+
+An agent's summary is still an interpretation. Keeping the evidence and its publisher visible lets people check the conclusions, compare perspectives, and ask better questions.
+
+## Choose the connection your users need
+
+A useful starting point is a concrete question: “What has this project done since we funded it?” or “Which assessments can we reuse?” Then identify the records needed to answer it.
+
+Your app may begin by reading existing information, publishing one kind of record, or doing both. It gains value from the wider network without having to reproduce every other tool.
+
+Next: [Building on Shared Records](/core-concepts/validation-and-interpretation), the final step before Client Integration.
diff --git a/pages/core-concepts/evaluations.md b/pages/core-concepts/evaluations.md
new file mode 100644
index 0000000..677869f
--- /dev/null
+++ b/pages/core-concepts/evaluations.md
@@ -0,0 +1,36 @@
+---
+title: Evaluations
+description: Add assessments that other people and applications can read, compare, and use in their own decisions.
+---
+
+# Evaluations
+
+Evidence can tell us what happened. Deciding whether the work was useful often takes experience, local knowledge, or specialist judgment.
+
+An **evaluation** records an assessment of work or another subject. It helps someone understand both the conclusion and the reasons behind it.
+
+## Add a perspective others can use
+
+A specialist reviewing a community energy installation might examine the production data, explain whether the system is performing as expected, and identify remaining issues. Local participants might assess a different question: whether the project is meeting the community's needs.
+
+Both perspectives can be valuable. Hypercerts gives them a common way to publish an assessment without requiring one evaluation method for every field.
+
+An evaluation can include a summary, name the evaluators, link to a longer report, cite measurements, and provide scores when those are useful. A score is easier to interpret when the reader can also see the method and evidence behind it.
+
+## The assessment has its own author
+
+An evaluator can publish through their own account and link the assessment to the work reviewed. They don't need permission to edit the project's activity, because they are creating a separate record.
+
+This preserves the distinction between the team's description and someone else's assessment. It also lets a second evaluator publish a different conclusion. An application can show both rather than forcing every opinion into one project-owned report.
+
+Being published separately does not automatically make an evaluation independent. Readers still need to consider the evaluator's relationship to the project and their expertise.
+
+## Let the next decision build on the review
+
+When the next funder considers the project, the earlier assessment is available for reuse. The funder might accept parts of it, seek a second opinion, or ask for newer evidence. The starting point is richer than an empty application form.
+
+Evaluations can refer to the specific version of a record that was reviewed. This helps readers understand an older assessment when the project later updates its description. We'll explain that connection in [Records That Change Over Time](/architecture/data-flow-and-lifecycle).
+
+For exact fields, see the [Evaluation reference](/lexicons/hypercerts-lexicons/evaluation).
+
+Next: [Trust and Recognition](/core-concepts/certified-identity), to understand who stands behind these contributions and which signals matter to a decision.
diff --git a/pages/core-concepts/evidence-and-measurements.md b/pages/core-concepts/evidence-and-measurements.md
new file mode 100644
index 0000000..0412ec4
--- /dev/null
+++ b/pages/core-concepts/evidence-and-measurements.md
@@ -0,0 +1,38 @@
+---
+title: Evidence and Measurements
+description: Connect reports, observations, and data to the work they help explain.
+---
+
+# Evidence and Measurements
+
+An activity tells people what the team says it is doing. Reports, observations, and data help people look more closely.
+
+For a community energy project, an installation report might explain what was built. Photos can document progress. Meter readings can show how much electricity the installation produces. Each adds something different to the account of the work.
+
+Hypercerts has two building blocks for sharing this material: attachments and measurements.
+
+## Attachments give people something to inspect
+
+An **attachment** connects material such as documents, photos, datasets, or links to the records it concerns. It can carry a progress update, a research paper, a field report, or a link to a software release.
+
+The attachment is a record of its own. It can point to one or several subjects, so the same report can give context to more than one activity. The material can be linked from elsewhere or included as an uploaded file where supported.
+
+Not every attachment is evidence. A plan explains intent; a progress report describes work; a dataset may help test a claim. Give the material a clear title and description so readers know what they are looking at.
+
+## Measurements make observations easier to reuse
+
+A **measurement** records a quantitative observation: what was measured, the value, and the unit. It can also describe the method, name the measurers, identify the period, and link to supporting data.
+
+For example, “the installation produced 4,200 kWh during August” is more useful than a number in an unlabeled spreadsheet. Another application can recognize the metric and unit, show the observation alongside earlier readings, and let a reviewer inspect the method.
+
+Context still matters. Energy production is an observation; the broader environmental benefit requires interpretation. Similarly, attendance at a workshop is different from evidence of what participants learned.
+
+## Add information without rewriting the original
+
+The team can publish attachments and measurements, and other people can contribute their own. Each record links to the work it concerns and remains associated with its publisher.
+
+That means a project can gain new evidence after its initial description is published, including evidence that challenges an earlier account. The value comes from making the material accessible and connected, not from treating publication as proof.
+
+The [Attachment](/lexicons/hypercerts-lexicons/attachment) and [Measurement](/lexicons/hypercerts-lexicons/measurement) references describe the available fields.
+
+Next: [Evaluations](/core-concepts/evaluations), where people explain what the evidence means.
diff --git a/pages/core-concepts/funding-and-value-flow.md b/pages/core-concepts/funding-and-value-flow.md
index 0a905e1..7cd430b 100644
--- a/pages/core-concepts/funding-and-value-flow.md
+++ b/pages/core-concepts/funding-and-value-flow.md
@@ -1,69 +1,44 @@
 ---
-title: "Funding & Value Flow"
-description: What released funding receipts record, how they connect to work, and what they do not prove.
+title: Funding and Learning
+description: Use what is already known about a project, record support, and make the next funding decision better informed.
 ---
 
-# Funding & Value Flow
+# Funding and Learning
 
-Hypercerts can describe funding without prescribing a payment rail or funding mechanism. The released `org.hypercerts.funding.receipt` schema records an assertion about a funding payment. It does not execute or independently verify that payment.
+A funder considering a project wants to understand the work, the evidence behind it, and what others have learned. The records we've covered let an application bring those pieces together.
 
-## Hypercerts work with any funding mechanism
+The funder can then make a decision using its own priorities and process. Hypercerts helps carry information into that decision and preserve what happens afterward.
 
-Funding can be prospective, concurrent, or retroactive. A receipt can be used around grants, crowdfunding, matching, bounties, purchases, or other mechanisms when the parties can represent the event with the released fields.
+## Record support for the work
 
-The protocol records funding context. It does not define eligibility, allocation, matching, settlement, refunds, or ownership semantics for those mechanisms.
+A **funding receipt** describes a funding payment. It records a recipient, amount, currency, and creation time. It can also name the sender, link to the activity or project supported, and include payment details such as a transaction identifier.
 
-## Tracking funding
+A funding platform, facilitator, funder, or recipient can publish a receipt. That flexibility makes it useful across different funding arrangements. A reader should be able to see who published the receipt as well as the parties it names.
 
-The receipt has four required fields:
+For example, a platform could record a payment toward a community energy installation and link it to that activity. A later reader can then connect the support with the work and its subsequent reports.
 
-- `to`: the recipient, represented by free text, a DID, or a strong reference.
-- `amount`: a string representing the amount.
-- `currency`: a string identifying the payment currency.
-- `createdAt`: the record creation time.
+The payment itself happens through the platform's chosen payment system. The receipt describes it; verifying that money arrived requires payment evidence and trust in the source. An acknowledgement from a relevant party can add confirmation, but it doesn't replace payment verification.
 
-It can also include:
+## Close the loop after funding
 
-- `from`: an optional sender. Omitting it allows an anonymous sender assertion.
-- `for`: a strong reference to the activity, project collection, organization record, or other subject funded.
-- Payment-rail, date, transaction, memo, and optional signature information.
+The useful story continues after a funding round closes:
 
-The schema intentionally supports publishers other than the sender or recipient. A funding platform, grant program, payment processor, sender, or recipient can publish a receipt. Consumers should therefore distinguish the repository publisher from the parties named inside it.
+1. A project describes the work it intends to do.
+2. Funders use available information and assessments to decide what to support.
+3. Receipts record support for the work.
+4. The team reports progress, and others contribute observations or assessments.
+5. The next funding decision builds on that history.
 
-## Connecting funding to work
+This is an example, not a required sequence. Work may already be underway or completed before it receives funding. The point is to keep what each round learns available to the next.
 
-```mermaid
-flowchart LR
-  P["Receipt publisher"] -->|publishes| R["Funding receipt"]
-  R -->|from, optional| F["Sender"]
-  R -->|to, required| T["Recipient"]
-  R -->|for, optional strongRef| W["Activity, project, organization, or other record"]
-  A["Acknowledging actor"] -->|separate record| K["Acknowledgement"]
-  K -->|subject| R
-```
+## Support different ways of funding
 
-An acknowledgement can add an independently published acceptance or rejection. It is a relationship record, not a cryptographic counter-signature and not proof of bank or blockchain settlement.
+The landing page describes crowdfunding with matching funds as a current use. The same idea of shared evidence could support outcome payments, prize competitions, or milestone bounties. Investment and procurement are further possibilities to explore.
 
-## What applications must decide
+Those approaches need their own rules for eligibility, selection, and payment. Hypercerts supplies reusable information; it doesn't decide which funding mechanism a community should use.
 
-The released schema does not guarantee:
+Likewise, an app showing “total funding” needs to consider currencies, repeated receipts, and which publishers it includes. A number is more useful when readers can inspect the receipts behind it and understand its coverage.
 
-- That a payment settled, was not refunded, or matches an external transaction.
-- That the publisher was authorized to speak for a named party.
-- That every relevant receipt has been published or indexed.
-- That duplicate or conflicting receipts have been removed.
-- That amount and currency strings can be safely summed without normalization.
+The [Funding Receipt reference](/lexicons/hypercerts-lexicons/funding-receipt) has the field details.
 
-Applications should preserve source records, define accepted publishers and payment evidence, identify deduplication rules, and label derived totals as index-dependent.
-
-## Current boundary
-
-The released 1.4.0 Lexicons do not define claim freezing, token wrapping, ownership fractions, auctions, or settlement. Those ideas may appear in historical or future design material, but they are not current protocol behavior and should not be inferred from a funding receipt.
-
-
-## See also
-
-- [Core Data Model](/core-concepts/hypercerts-core-data-model)
-- [Identity, Authorship & Trust](/core-concepts/certified-identity)
-- [Records, References & Lifecycle](/architecture/data-flow-and-lifecycle)
-- [Funding Receipt reference](/lexicons/hypercerts-lexicons/funding-receipt)
+We've now followed the story from a description of work to evidence, trust, and support. Next, [Describing and Classifying Work](/core-concepts/cel-work-scopes) explains how apps can recognize related work across projects.
diff --git a/pages/core-concepts/hypercerts-core-data-model.md b/pages/core-concepts/hypercerts-core-data-model.md
index 09d998d..f0518ef 100644
--- a/pages/core-concepts/hypercerts-core-data-model.md
+++ b/pages/core-concepts/hypercerts-core-data-model.md
@@ -1,120 +1,48 @@
 ---
-title: Core Data Model
-description: The released Hypercerts and Certified record families, their relationship directions, and the conventions layered on them.
+title: A Shared Language
+description: Meet the building blocks that let projects, evaluators, networks, and funders contribute information others can use.
 ---
 
-# Core Data Model
+# A Shared Language
 
-The released model is a graph of independently published AT Protocol records. It has no single aggregate object containing a complete project, all evidence, and every assessment. Applications assemble a view from records they can discover and choose to interpret.
+“We restored a wetland” and “we reviewed that restoration” are different contributions to the same story. Hypercerts gives each a recognizable form so an application can tell them apart and connect them.
 
-This page describes `@hypercerts-org/lexicon` 1.4.0. See the [Lexicon inventory](/reference/lexicon-inventory) for the exact released surface.
+That shared language starts with the work and grows as more people contribute.
 
-## Relationship map
+## From an activity to a fuller picture
 
-Arrows show the direction stored in the source record. Reverse discovery, such as finding every evaluation of an activity, requires an indexer that has observed those records.
+An **activity claim**, also called a hypercert, describes a piece of work. It gives other records something specific to refer to. A project can bring several activities together, while evidence and evaluations help others understand what happened and why it matters.
 
-```mermaid
-flowchart LR
-  A["Activity claim"] --> CI["Contributor information"]
-  A --> C["Contribution details"]
-  A --> R["Rights"]
-  A --> L["Location"]
-  A --> WS["Embedded work scope"]
-  WS --> WST["Work-scope tags"]
+| Question | Building block |
+|---|---|
+| What work is being done, and by whom? | An **activity claim**, with contributor details |
+| How does it fit into a larger effort? | A **project**, which groups related activities |
+| What can we look at or measure? | **Attachments** and **measurements** |
+| What do others think of the work? | **Evaluations** |
+| Who recognizes or confirms a relationship? | **Badges**, **responses**, and **acknowledgements** |
+| What support has the work received? | **Funding receipts** |
 
-  COL["Collection"] --> A
-  COL --> F["Feature"]
-  COL --> COL
-  COL --> VT["Vocabulary tags"]
-  F --> L
-  F --> VT
+Imagine a community energy project. Installing solar panels is one activity. A report describes the installation, a measurement records energy production, and a specialist evaluates the results. A funder can read those pieces together before deciding whether to support the next phase.
 
-  ATT["Attachment"] --> A
-  M["Measurement"] --> A
-  E["Evaluation"] --> A
-  E --> M
-  FR["Funding receipt"] --> A
-  ACK["Acknowledgement"] --> A
-
-  BA["Badge award"] --> A
-  BA --> BD["Badge definition"]
-  BR["Badge response"] --> BA
+```mermaid
+flowchart LR
+  P["Community energy project"] -->|includes| A["Solar installation activity"]
+  R["Installation report"] -->|documents| A
+  M["Energy production measurement"] -->|measures results of| A
+  E["Specialist evaluation"] -->|assesses| A
+  F["Funding receipt"] -->|records support for| A
 ```
 
-The diagram uses an activity as an example subject. Attachments, measurements, evaluations, funding receipts, acknowledgements, and badge awards can refer to other records where their schemas allow it.
-
-## Activities and contribution detail
-
-`org.hypercerts.claim.activity` describes work. Its required fields are `title`, `shortDescription`, and `createdAt`. Contributors, work scope, dates, locations, rights, and signatures are optional, so "who, what, when, and where" is recommended conceptual coverage rather than the minimum valid shape.
-
-An activity can contain contributor entries. Each entry can keep identity and role information inline or point outward to reusable records:
-
-- `org.hypercerts.claim.contributorInformation` provides identifier and presentation details.
-- `org.hypercerts.claim.contribution` provides a role, description, and optional timeframe.
-- `org.hypercerts.claim.rights` describes rights or licensing terms and is referenced directly by the activity.
-
-These reusable records do not point back to the activity. The activity contains the relationship.
-
-## Projects, collections, and features
-
-`org.hypercerts.collection` groups activities, `org.hypercerts.entity.feature` records, and nested collections. Each item contains a strong reference and may have a weight.
-
-{% callout type="note" %}
-A project is not a separate Lexicon. The shared convention is an `org.hypercerts.collection` record with `type: "project"`. The `type` field is optional and open, so applications must implement this convention. Project membership is stored from the collection to its items; activities have no project field.
-{% /callout %}
-
-A feature represents a non-agent subject, such as a geographic zone, ecological stratum, participant cohort, or campaign. It can carry locations, general vocabulary tags, and external identifiers. Collections can group features with the activities concerning them.
-
-## Context records
-
-Context records can be published after their subjects and from different repositories:
-
-| Record | Stored relationship | Important limit |
-|---|---|---|
-| `org.hypercerts.context.attachment` | Optional plural `subjects` | An attachment may be evidence, commentary, a report, or another content type; it does not verify itself. |
-| `org.hypercerts.context.measurement` | Optional plural `subjects`; optional measurer DIDs and evidence URIs | The schema does not establish methodology quality or measurer authority. |
-| `org.hypercerts.context.evaluation` | Optional singular `subject`; optional measurement references | Named evaluators are not automatically corroborated by the repository publisher. |
-| `org.hypercerts.context.acknowledgement` | Required `subject`; optional relationship `context` | Acknowledgement is an independent acceptance or rejection record, not an automatic counter-signature. |
-
-An activity does not have to be changed when new context is published. The graph grows as indexers discover records that point to it.
-
-## Funding records
-
-`org.hypercerts.funding.receipt` describes a claimed funding payment. It requires a recipient, amount, currency, and creation time. The sender and funded subject are optional. Parties may be represented by text, a DID, or a record reference.
-
-A receipt can point to an activity, a project collection, an organization record, or another subject. It does not itself prove settlement or prevent duplicate and conflicting receipts. See [Funding Records & Value Flow](/core-concepts/funding-and-value-flow).
-
-## Two classification systems
-
-The released model deliberately separates:
-
-- `org.hypercerts.workscope.tag`, referenced by the CEL expression embedded in an activity's work scope.
-- `org.hypercerts.vocab.tag`, used to classify collections and features.
-
-They have different purposes and hierarchy rules. They should not be treated as one interchangeable tag system. See [Work Scopes & Classification](/core-concepts/cel-work-scopes).
-
-## Adjacent Certified records
-
-The `app.certified.*` namespace supplies records that Hypercerts applications can use around the work graph:
-
-- Actor profiles and organization metadata describe the repository identity. Their relationship comes from sharing the same repository and `self` record key, not an explicit link.
-- Location records provide reusable spatial representations.
-- Badge definitions, awards, and responses model recognition and recipient response.
-- Account follows and entity follows help clients define social and discovery scopes.
-- EVM link records connect a DID to an EVM address through a proof structure.
-- Signature definitions and proof records support optional record-content attestations.
+These are separate records, not sections everyone edits in a single document. Each can be published by the person or organization contributing that information. Links between them let an application bring the story together.
 
-These records complement Hypercerts but do not create organization membership, project ownership, evaluator independence, or universal trust rules.
+## Formats and meaning work together
 
-## References are typed by usage
+The Lexicons describe the fields software reads and writes. The Guide explains what those records mean and how to use them together.
 
-The graph uses several relationship forms:
+For example, a project uses a grouping record called a *collection*. Applications agree to recognize a collection marked as a project. That small shared convention lets a project dashboard and a funding platform recognize the same grouping.
 
-- **Strong reference:** an AT-URI plus CID, used to pin one content version.
-- **AT-URI:** identifies a record slot without pinning a version, useful when a relationship should survive updates.
-- **DID:** identifies an AT Protocol account.
-- **Embedded object or string:** carries information by value rather than linking to another record.
+You'll also encounter **Certified**. It provides accounts and tools for working with Hypercerts, and its shared schemas describe things such as profiles, organizations, locations, and badges. Those schemas can be used by other applications too.
 
-Most strong-reference target restrictions are described conventions rather than constraints enforced by the generic `strongRef` shape. Compatible applications must validate both the reference structure and the expected target semantics.
+You don't need to learn every schema before you begin. Start with the records that answer your users' questions. The next pages introduce the main building blocks individually; the [Lexicon inventory](/reference/lexicon-inventory) is there when you want the complete list.
 
-Next: [Identity, Authorship & Trust](/core-concepts/certified-identity).
+Next: [Activity Claims](/core-concepts/what-is-hypercerts), the starting point for describing the work.
diff --git a/pages/core-concepts/projects-and-collections.md b/pages/core-concepts/projects-and-collections.md
new file mode 100644
index 0000000..50b8dce
--- /dev/null
+++ b/pages/core-concepts/projects-and-collections.md
@@ -0,0 +1,42 @@
+---
+title: Projects and Collections
+description: Bring related activities together so people can follow a project across phases, places, and funding rounds.
+---
+
+# Projects and Collections
+
+An activity describes a piece of work. A project gives that work a wider context.
+
+A community energy project might include planning, installation, and ongoing maintenance. Describing these as separate activities makes each easier to explain and assess. Grouping them as a project lets people follow the effort as a whole.
+
+## Keep the project together over time
+
+A project can link to its activities without copying them. A funding platform can show the project overview, while a reviewer follows a link to the particular installation they are assessing.
+
+Later, the team can add another phase. Earlier activities and their assessments still have their own records. A new funding round can build on that history rather than replace it with a fresh application.
+
+## Collections are the grouping tool
+
+In Hypercerts, a **collection** groups related records. A project is a collection marked with `type: "project"`. That is the shared convention applications use to recognize it as a project.
+
+Collections are useful beyond projects. A funder might group activities into a portfolio, or a program might bring several project collections together. The same activity can be included in more than one collection, just as the same piece of work can matter to both a project and a funder.
+
+Including a record is a choice made by the collection's publisher. It doesn't transfer control of the original record or, by itself, establish a partnership with its author.
+
+## Include the places or subjects the work concerns
+
+Sometimes it helps to describe the subject of the work separately. A land restoration project may cover several zones, each with its own location and characteristics.
+
+A **feature** record can describe such a zone, or another subject such as a participant cohort. A collection can group features alongside activities. That lets an application show both the work and the places or subjects it concerns.
+
+Use this extra structure when it answers a real question. A small project may only need a collection and a few activities.
+
+## Projects and organizations play different roles
+
+An organization is a person or group acting in the world; a project organizes the work. An organization can publish a profile and organization information through the Certified schemas, then use its account to publish projects and activities.
+
+The project grouping describes how records belong together. Managing which team members can publish for an organization is a separate account-management task, introduced in [Client Integration](/client-integration).
+
+For implementation details, see the [Collection reference](/lexicons/hypercerts-lexicons/collection).
+
+Next: [Evidence and Measurements](/core-concepts/evidence-and-measurements), to show what happened within those activities.
diff --git a/pages/core-concepts/validation-and-interpretation.md b/pages/core-concepts/validation-and-interpretation.md
index b91ab87..ed0c606 100644
--- a/pages/core-concepts/validation-and-interpretation.md
+++ b/pages/core-concepts/validation-and-interpretation.md
@@ -1,67 +1,44 @@
 ---
-title: Validation, Extension & Interpretation
-description: How structural Lexicon validation differs from semantic compatibility, and how clients handle extensions and derived views.
+title: Building on Shared Records
+description: Bring the Guide together and prepare to build an application that others can understand and build on.
 ---
 
-# Validation, Extension & Interpretation
+# Building on Shared Records
 
-Passing Lexicon validation means a record has an accepted structural shape. It does not mean the record is true, authorized, complete, discoverable, or useful for a particular decision.
+We've followed a piece of work from its initial description through evidence, assessments, recognition, and funding. We've also seen how different people can contribute through different apps, while keeping their own records connected.
 
-## Three layers of validation
+Now the question is where your application joins that story.
 
-| Layer | Typical checks | Who performs them |
-|---|---|---|
-| **Structural** | Required fields, primitive formats, lengths, unions, and referenced object shapes | SDKs, clients, validators, and indexers |
-| **Semantic** | Expected target collection, project convention, numeric ranges, chronology, tag policy, and role consistency | Compatible applications and indexers |
-| **Trust and policy** | Publisher authority, evaluator independence, evidence quality, payment verification, moderation, and ranking | Each application, community, or decision-maker |
+## Put the pieces together
 
-A PDS stores AT Protocol repository records. Do not assume it enforces every Hypercerts domain rule. Writers should validate before publication, and readers should validate untrusted records again.
+The system has three complementary parts:
 
-## Constraints beyond the Lexicons
+- **AT Protocol** gives people accounts and repositories for publishing and linking records.
+- **Hypercerts** gives those records shared formats and meaning: activities, projects, evidence, evaluations, and funding history.
+- **Applications and services** help people publish, find, interpret, and act on that information.
 
-Several released conventions cannot be fully expressed by the schemas:
+An indexer can bring records into a queryable view. Your interface can help a user understand that view or add a new contribution. That contribution can, in turn, become useful in someone else's app.
 
-- A project is a collection with `type: "project"`; `type` is optional and open.
-- Most strong-reference fields structurally accept any strong reference even when their descriptions name expected target collections.
-- Numeric amounts, weights, measurements, and scores are strings; meaningful ranges and arithmetic require application checks.
-- Required arrays can still be empty unless a minimum length is declared.
-- Date ordering, hierarchy cycles, record-key conventions, and cross-field equality require additional validation.
-- A named contributor, evaluator, issuer, sender, or recipient is not automatically the repository publisher.
+## Write information others can understand
 
-Compatible clients should document which of these rules they enforce on writes, reads, or both.
+Use the existing Lexicons where they fit your purpose. Their fields give other applications a recognizable starting point. Validation checks that a record has the expected structure, such as required fields and correctly formed links.
 
-## Open values and unknown data
+Meaning needs attention too. A project should use the shared project convention. A measurement needs an understandable metric and unit. An evaluation should link to the work it assesses and make its reasoning accessible.
 
-AT Protocol `knownValues` are not closed enums. A value outside the published list can remain structurally valid. Open unions similarly allow later record shapes.
+A record passing a schema check doesn't establish whether its claims are true. Your app can help readers judge them by showing who published the information and what supports it.
 
-Readers should:
+## Build for a network with different tools
 
-1. Preserve unknown fields and values when round-tripping data.
-2. Display a safe fallback instead of assigning an invented meaning.
-3. Avoid rejecting an entire graph because one connected record is unknown.
-4. Record which Lexicon package version and usage conventions they support.
+Other applications may use newer fields, unfamiliar categories, or extensions you haven't implemented. Show what your app understands, retain unfamiliar information when editing where possible, and avoid silently giving it a different meaning.
 
-## Extending the model
+If your use case needs something the shared formats don't cover, you can define another Lexicon and publish records that link to the existing work. Other apps and indexers will need to support that extension before they can use it. This lets specialized tools develop without replacing the shared foundation.
 
-Use a standard `org.hypercerts.*` or `app.certified.*` field when it fits the intended meaning. When an application needs data outside those schemas, publish a separate namespaced record that references the standard subject rather than adding unregistered fields and expecting other clients to interpret them.
+The [Reference](/reference) links to exact schemas and service documentation. The current Guide uses the Hypercerts and Certified schemas in `@hypercerts-org/lexicon` 1.4.0; [Change History](/change-history) is where to follow their evolution.
 
-An extension becomes interoperable only when other consumers know its Lexicon and usage. Default Hypercerts indexers are not required to ingest application-specific namespaces.
+## Take the next step
 
-## Aggregation and derived views
+Choose one useful flow for your users: publish an activity, help someone evaluate work, or bring existing project information into a funding process. Decide who publishes each piece and what a reader needs to understand it.
 
-Search results, backlinks, totals, scores, and hydrated project views are derived from an indexer's observed records. They should retain links to source AT-URIs and state material policies such as:
+Then continue to [Client Integration](/client-integration) for account setup, the available walkthroughs, and the SDK and API path as it develops. The complete SDK/XRPC walkthrough is still being prepared; that section explains what is available today.
 
-- Included repositories and record collections.
-- Accepted versions and extensions.
-- Handling of updates, deletions, and stale strong references.
-- Deduplication and conflict rules.
-- Trusted publishers or vocabulary authorities.
-- Moderation and ranking behavior.
-
-Derived data should not overwrite or masquerade as source assertions. Two indexers can legitimately produce different views from different coverage or policies.
-
-## Current compatibility boundary
-
-There are no ratified Hypercerts conformance classes or universal test suite. The current compatibility baseline is the released Lexicons plus documented shared conventions. API availability, SDK behavior, service support, and user-facing workflows have their own versions and should not be inferred from record schemas.
-
-Continue to [Client Integration](/client-integration) for tested implementation paths or [Reference](/reference) for exact contracts.
+The aim is simple: make one contribution useful beyond the app where it began. Your application can help the next person start with more knowledge and less repeated work.
diff --git a/pages/core-concepts/what-is-hypercerts.md b/pages/core-concepts/what-is-hypercerts.md
index 026bb45..2b9e8b7 100644
--- a/pages/core-concepts/what-is-hypercerts.md
+++ b/pages/core-concepts/what-is-hypercerts.md
@@ -1,75 +1,41 @@
 ---
-title: What are Hypercerts?
-description: Shared records for describing valuable work and connecting it to context, assessment, and funding.
+title: Activity Claims
+description: Describe a piece of work so others can recognize contributions, add evidence, and assess its value.
 ---
 
-# What are Hypercerts?
+# Activity Claims
 
-A hypercert is an `org.hypercerts.claim.activity` record that describes valuable work. Other records can connect contributors, evidence, measurements, evaluations, acknowledgements, classifications, projects, and funding history to that activity over time.
+Maintaining an open-source library, restoring a wetland, or running a community workshop all involve work worth describing. An **activity claim**, or hypercert, gives that work a shared record that other people can refer to.
 
-Together, these records form an open graph rather than one final certificate or document. Different people and organizations publish from their own AT Protocol repositories. Applications assemble the parts relevant to their users and preserve who published each assertion.
+The word *claim* matters. The record is someone's account of the work. Evidence and assessments help others judge that account over time.
 
-## The structure of a hypercert
+## Give the work a clear description
 
-The activity model is designed to answer four useful questions:
+A useful activity description answers four questions:
 
-- **Who** is doing (or did) the work?
-- **What** are they doing (or what did they do)?
-- **When** is it happening (or when did it happen)?
-- **Where** did it happen? (physical or digital)
+- **Who** contributed?
+- **What** are they doing, or what did they do?
+- **When** does the work take place?
+- **Where** does it happen, whether in a physical place or online?
 
-These are conceptual dimensions, not all required fields in the released schema. Version 1.4.0 requires a title, short description, and creation time; richer records add the dimensions needed for their use case.
+For example, a team might describe “maintenance of an open-source mapping library, January to June.” It can name the maintainers, explain the work covered, and link to the repository. Someone reading it has a much clearer starting point than a broad claim to be “supporting open source.”
 
-Related records can add more context:
+An activity can describe planned, ongoing, or completed work. Make that distinction clear in the description. A plan for restoration and a report of completed restoration should not be mistaken for each other.
 
-- **Attachments:** documents, links, files, reports, or other material. An attachment may be evidence, but its existence does not verify its contents.
-- **Measurements:** quantitative observations, their units, methods, measurers, and evidence links.
-- **Evaluations:** assessments with named evaluators, summaries, optional scores, reports, and supporting measurements.
-- **Contributions:** reusable details about who was involved, their roles, and their periods of contribution.
-- **Collections:** group activities, non-agent features, and other collections into projects, programs, portfolios, or other sets.
-- **Funding receipts:** record assertions about funding payments and what they supported.
-- **Acknowledgements, badges, and signatures:** add independent signals about relationships, recognition, and provenance.
+## Recognize the people involved
 
+Contributor details let a team name the people or organizations involved and describe their roles. One person may have maintained the code, another written documentation, and another organized user testing.
 
+Simple identity and role details can be included directly. Reusable contributor and contribution records are available when you need more detail. Optional weights can express relative contributions, but how to choose those weights is a decision for the people and application using them.
 
-## What a hypercert is not
+Naming someone is the publisher's account of their involvement. A response from that person can add confirmation. We'll return to this in [Trust and Recognition](/core-concepts/certified-identity).
 
-- **Not a truth certificate:** valid structure and attributable publication do not prove a claim is correct.
-- **Not a payment rail:** a funding receipt describes a claimed transfer; Hypercerts does not settle the payment.
-- **Not a token:** the released protocol model is based on AT Protocol records.
-- **Not a single document:** related records can be published and updated independently across repositories.
-- **Not a complete global view:** finding every backlink requires an indexer, and every index has a coverage policy.
+## Let the picture develop
 
-## How people use them
+The activity provides a common point of reference. Later, the team can link a progress report, users can publish measurements, and reviewers can assess the results. These additions can live in other accounts without changing the activity itself.
 
-**If you're doing the work**, you create a hypercert to make your contributions visible. Instead of writing reports that sit in a folder, you publish a verifiable record that any platform can display and build on.
+This is why a hypercert can become more useful over time. The description of the work remains connected to what people learn about it.
 
-**If you're evaluating work**, you publish an assessment from an AT Protocol repository and reference the record version you assessed. Applications can use your identity, evidence, and history as inputs to their own trust model.
+You can start with a short record and add detail as it becomes useful. The schema requires a title, short description, and creation time; contributor, time, location, and other details are optional. The [Activity Claim reference](/lexicons/hypercerts-lexicons/activity-claim) covers the exact fields, including descriptions, work scope, and rights or licensing information.
 
-**If you're funding work**, you can inspect attributable project information and assessments, then publish a receipt describing support. Whether that receipt proves settlement depends on its publisher and supporting data.
-
-**If you're building a platform**, you can read and write hypercerts using shared schemas. A funding platform, a project dashboard, and an evaluation tool can all work with the same data.
-
-## An example
-
-Say a team runs a coastal reforestation project. They create a hypercert:
-
-> **Coastal mangrove restoration, 2025**
->
-> 50 hectares restored over 12 months (the activity claim). Satellite imagery confirms canopy coverage. An independent ecologist evaluates the work as "high-quality restoration with strong community engagement."
-
-The activity claim is the starting record. Over the following months, the team or third parties publish measurements and attachments that refer to it. An evaluator can assess a specific version. An indexer can assemble those independently published records for a funding application, which may then record support with a funding receipt.
-
-## Why it's built this way
-
-Hypercerts are designed to live beyond any single platform.
-This is why we built hypercerts on [AT Protocol](/core-concepts/why-at-protocol), a decentralized data layer that also powers Bluesky. This gives hypercerts some important properties:
-
-- **Repository-controlled:** records live in an AT Protocol repository associated with the publisher's DID rather than only in one application's database.
-- **Portable:** the DID and AT-URIs do not encode the current server address, so repository migration can preserve record identifiers.
-- **Attributable:** signed repository commits let consumers verify which repository published a version; optional record-level attestations are a separate mechanism.
-- **Interoperable by agreement:** applications can understand records when they implement the released schemas and compatible usage conventions.
-
-## Next step
-
-To see the full graph, including projects and adjacent Certified records, read the [Core Data Model](/core-concepts/hypercerts-core-data-model).
+Next: [Projects and Collections](/core-concepts/projects-and-collections), for work that spans more than one activity.
diff --git a/pages/core-concepts/why-at-protocol.md b/pages/core-concepts/why-at-protocol.md
index e411077..e886978 100644
--- a/pages/core-concepts/why-at-protocol.md
+++ b/pages/core-concepts/why-at-protocol.md
@@ -1,38 +1,36 @@
 ---
 title: Why AT Protocol?
-description: Why the Hypercerts Protocol is built on AT Protocol.
+description: How people using different applications can publish, connect, and reuse information about the same work.
 ---
 
 # Why AT Protocol?
 
-The Hypercerts Protocol is built on [AT Protocol](https://atproto.com/docs), the open protocol for decentralized data that also powers Bluesky.
+Suppose a project publishes a progress update through a funding platform. An evaluator wants to assess that work using their own tool. Another funder wants to read both. They shouldn't need to join the first platform or negotiate a custom data-sharing arrangement just to work with the same public information.
 
-Earlier Hypercerts versions centered on onchain tokens. The current model uses AT Protocol repositories for rich, evolving work records. Publishing these records does not inherently require a blockchain wallet, gas, or a settlement transaction.
+Hypercerts builds on [AT Protocol](https://atproto.com/docs), the open network technology that also powers Bluesky. It gives people an account and a place to publish records that different applications can work with.
 
-ATProto gives hypercerts three properties that matter for impact funding: portable data, shared schemas, and a trust graph rooted in cryptographic identity.
+## Records belong to accounts, not just apps
 
-## Portable, user-controlled data
+Think of a **record** as a small structured document, such as a description of an activity or an evaluation. An account keeps its records in a **repository**, a little like a folder of those documents. A **Personal Data Server (PDS)** hosts that repository. People can use a hosted service; they don't need to run their own server.
 
-Information about valuable work should be reusable beyond the application that collected it.
+An app helps someone create and read these records. The records can also be read by other apps that support their format. This separates the information from the interface used to publish it.
 
-Hypercerts records are stored in AT Protocol repositories hosted on Personal Data Servers (PDSs). Each repository is addressed through a DID rather than a fixed server URL. An account migration that preserves the DID can therefore preserve record AT-URIs when the hosting location changes.
+AT Protocol also gives each account a lasting identifier called a **DID**, short for decentralized identifier. It identifies the account separately from its current name or hosting server. This is what allows an account to keep its identity when moving between supported hosts.
 
-Applications can build views over source records without becoming the only database that defines those records. See [Public Data, Discovery & Portability](/architecture/portability-and-scaling).
+## Other people can add their perspective
 
-## Shared schemas across applications
+The evaluator publishes a new record in their own repository and links it to the project's work. The original activity stays with the project. The assessment stays with its publisher.
 
-For project information to be reused, a record written by one application needs an open shape that another application can parse.
+A funding app can then show them together. This is a central idea in Hypercerts: people can contribute information about the same work without sharing one account or giving each other permission to edit their records.
 
-AT Protocol enables this through [Lexicons](/lexicons/introduction-to-lexicons): shared, namespaced schemas that define record structures. A client can implement those public schemas and usage conventions without obtaining a proprietary schema from the original application.
+## A network needs a shared language
 
-Records reference accounts and other records through DIDs, AT-URIs, and strong references. Indexers can observe those forward links and build backlink queries and hydrated views. See [Records, References & Lifecycle](/architecture/data-flow-and-lifecycle).
+AT Protocol provides accounts, publishing, and links between records. Hypercerts provides the formats for describing work, evidence, evaluations, and funding.
 
-## Attributable inputs to trust
+These formats are defined in **Lexicons**. A Lexicon is a schema: it tells software what kind of record it is reading and which fields to expect. Using the same formats lets an evaluation tool and a funding platform exchange meaningful information, even if their interfaces look completely different.
 
-AT Protocol provides account identity through DIDs and attributes repository publication through signed commits. Hypercerts adds records that can name contributors, evaluators, issuers, funders, and subjects. These named actors may differ from the repository publisher.
+To find information spread across accounts, applications use **indexers**. An indexer collects records and makes them searchable, including connections such as “evaluations of this activity.” Each indexer has its own coverage, so different apps may show different parts of the network.
 
-This gives applications attributable inputs for their own trust models. It does not establish one trust score, verify every named actor, or guarantee that every public record has been indexed. See [Identity, Authorship & Trust](/core-concepts/certified-identity).
+You now have the basic division of work: AT Protocol lets people publish, Hypercerts gives the information a shared meaning, and applications help people use it.
 
-## Protocol boundary
-
-The released Hypercerts Lexicons describe AT Protocol records. They do not define payment settlement, claim freezing, token ownership, or a canonical global index. Those capabilities can be implemented by applications or future schemas without changing the role of AT Protocol as the source-record layer.
+Next, let's look at [the shared language itself](/core-concepts/hypercerts-core-data-model).
diff --git a/pages/ecosystem/why-we-need-hypercerts.md b/pages/ecosystem/why-we-need-hypercerts.md
index abbcf78..61c059f 100644
--- a/pages/ecosystem/why-we-need-hypercerts.md
+++ b/pages/ecosystem/why-we-need-hypercerts.md
@@ -6,7 +6,7 @@ description: Recognizing and rewarding value creators.
 # Why We Need Hypercerts
 
 {% callout type="warning" %}
-This is a vision and background essay. Its economic and ownership examples are not a description of the current released protocol. Use the [Guide](/guide) for the current model and [Funding Records & Value Flow](/core-concepts/funding-and-value-flow) for released funding semantics.
+This is a vision and background essay. Its economic and ownership examples are not a description of the current released protocol. Use the [Guide](/guide) for the current model and [Funding and Learning](/core-concepts/funding-and-value-flow) for how funding records connect to work.
 {% /callout %}
 
 ## The Problem
diff --git a/pages/getting-started/building-on-hypercerts.md b/pages/getting-started/building-on-hypercerts.md
index 4755ae1..f660b3a 100644
--- a/pages/getting-started/building-on-hypercerts.md
+++ b/pages/getting-started/building-on-hypercerts.md
@@ -91,7 +91,7 @@ You're also free to create new lexicons for use cases that don't fit the origina
 
 Use a strong reference when the field requires an AT-URI and CID for one content version. Use DID fields for accounts and URI-only record subjects where the Lexicon deliberately models a relationship that survives updates. Do not substitute one reference form for another.
 
-See [Records, References & Lifecycle](/architecture/data-flow-and-lifecycle) and [Validation, Extension & Interpretation](/core-concepts/validation-and-interpretation) before publishing an extension.
+See [Records That Change Over Time](/architecture/data-flow-and-lifecycle) and [Building on Shared Records](/core-concepts/validation-and-interpretation) before publishing an extension.
 
 
 ## Next Steps
diff --git a/pages/getting-started/testing-and-deployment.md b/pages/getting-started/testing-and-deployment.md
index f35f0a4..d5f9487 100644
--- a/pages/getting-started/testing-and-deployment.md
+++ b/pages/getting-started/testing-and-deployment.md
@@ -163,4 +163,4 @@ Before deploying to production:
 - [Client Integration](/client-integration) — review the target SDK and XRPC path and current gaps
 - [Lexicon reference](/lexicons/hypercerts-lexicons) — field definitions and constraints for each record type
 - [Architecture Overview](/architecture/overview) — how the protocol stack fits together, including the security model
-- [Records, References & Lifecycle](/architecture/data-flow-and-lifecycle) — how records change and connect across repositories
+- [Records That Change Over Time](/architecture/data-flow-and-lifecycle): how records change and connect across repositories
diff --git a/pages/guide/index.md b/pages/guide/index.md
index 8cde04f..fad4aec 100644
--- a/pages/guide/index.md
+++ b/pages/guide/index.md
@@ -1,69 +1,34 @@
 ---
 title: Guide
-description: Understand the Hypercerts Protocol, its data model, and the conventions that make records useful across applications.
+description: Follow how information about valuable work becomes useful to projects, evaluators, funders, and the applications they use.
 ---
 
 # Guide
 
-Hypercerts gives valuable work, project context, assessments, and funding history shared formats that independent applications can reuse. This Guide explains the protocol model and the conventions that make those records meaningful together.
+You've seen the idea: projects should be able to share their work once, and funders should be able to build on what others already know. This Guide explains how Hypercerts makes that possible.
 
-Use the Guide to understand the system. Use [Client Integration](/client-integration) for tested implementation paths and [Reference](/reference) for exact schemas and service contracts.
+If you'd like the high-level story first, visit [hypercerts.org](https://hypercerts.org). Here, we'll go one level deeper, from describing a piece of work to connecting it with evidence, independent assessments, and funding.
 
-{% callout type="note" %}
-The current schema baseline is `@hypercerts-org/lexicon` 1.4.0. Hypercerts evolves through additive Lexicon releases and shared usage guidance. There is no ratified conformance specification or universal compatibility badge.
-{% /callout %}
+## Start with what people already know
 
-## What the protocol includes
+A project team knows what it has been doing. A community knows how that work affects local people. A specialist can assess the methods. A funder knows why it chose to offer support. Each holds a different part of the picture.
 
-The practical protocol spans several layers:
+Usually, these pieces end up in separate application forms, reports, and databases. Hypercerts gives them a shared format and a way to connect. A team can publish an update through one app, an evaluator can review the work through another, and a funding platform can bring both into view.
 
-| Layer | Responsibility |
-|---|---|
-| **AT Protocol** | DIDs, repositories, record addressing, signed commits, Personal Data Servers (PDSs), and data portability |
-| **Released Lexicons** | The structural shapes for Hypercerts and Certified records |
-| **Shared usage guidance** | Conventions for concepts such as projects, references, attribution, classification, and interpretation |
-| **Applications and services** | Writing, discovery, indexing, aggregation, policy, and user experience |
-| **Change history** | Released additions, corrections, and migration context |
+The people contributing information keep their own voices. An evaluator publishes their assessment rather than editing the project's account of its work. Later, someone deciding whether to fund the project can see both accounts and the evidence behind them.
 
-Lexicons establish structural validity. They do not prove that work happened, that an evaluator is independent, that a receipt corresponds to a settled payment, or that an index contains every related record. Those judgments depend on provenance, corroboration, application policy, and evidence.
+That is how a useful record grows over time. The next decision can begin with what is already known, rather than another blank form.
 
-```mermaid
-flowchart LR
-  A["Authors and organizations"] -->|publish| P["AT Protocol repositories"]
-  P --> H["Hypercerts and Certified records"]
-  H --> I["Relays and indexers"]
-  I --> X["Applications and agents"]
-  G["Lexicons and usage guidance"] -.shape and meaning.-> H
-  X -->|publish more context| P
-```
+## What you'll learn
 
-## Follow the model
+We'll follow three parts of that story:
 
-{% card-grid %}
-{% card-link title="What are Hypercerts?" href="/core-concepts/what-is-hypercerts" %}
-Start with the problem, the protocol boundary, and what a hypercert represents.
-{% /card-link %}
-{% card-link title="Why AT Protocol?" href="/core-concepts/why-at-protocol" %}
-Understand the identity, record, and portability foundation.
-{% /card-link %}
-{% card-link title="Core Data Model" href="/core-concepts/hypercerts-core-data-model" %}
-See every released record family, relationship direction, and higher-level convention.
-{% /card-link %}
-{% card-link title="Common Use Cases" href="/core-concepts/common-use-cases" %}
-Map real scenarios to the record graph without depending on one application.
-{% /card-link %}
-{% /card-grid %}
+1. **Make information reusable.** Meet the open network underneath Hypercerts and the shared language that lets different apps understand the same records.
+2. **Build a fuller picture of the work.** Describe activities and projects, add evidence and evaluations, recognize contributions, and record funding.
+3. **Put that knowledge to use.** Understand how records stay connected as they change, how apps find them, and where your own application can contribute.
 
-## Understand meaning and trust
+Along the way, we'll introduce technical terms such as *Lexicon*, *repository*, and *indexer* when they help explain a practical question. Exact fields and constraints are linked in the Reference for when you need them.
 
-- [Identity, Authorship & Trust](/core-concepts/certified-identity) separates repository publishers, named actors, attestations, and application trust decisions.
-- [Work Scopes & Classification](/core-concepts/cel-work-scopes) distinguishes activity scope expressions from tags used to classify projects and features.
-- [Funding Records & Value Flow](/core-concepts/funding-and-value-flow) explains what a receipt records and what it does not prove.
+By the end, you should be able to explain how the pieces fit together and choose a starting point for your application. [Client Integration](/client-integration) is the next step toward building it.
 
-## Operate across repositories
-
-- [Records, References & Lifecycle](/architecture/data-flow-and-lifecycle) explains record slots, versions, strong references, updates, deletion, and backlink discovery.
-- [Public Data, Discovery & Portability](/architecture/portability-and-scaling) explains the difference between publication, availability, discovery, and indexed views.
-- [Validation, Extension & Interpretation](/core-concepts/validation-and-interpretation) separates schema checks from application semantics and explains safe extension.
-
-For an exact list of released schemas, continue to the [Lexicon inventory](/reference/lexicon-inventory).
+Start with [Why AT Protocol?](/core-concepts/why-at-protocol): how can people using different apps contribute to the same picture?
diff --git a/pages/index.md b/pages/index.md
index 2b02d4b..50f47a5 100644
--- a/pages/index.md
+++ b/pages/index.md
@@ -1,34 +1,31 @@
 ---
 title: Hypercerts Documentation
-description: Guides, integration paths, technical reference, and change history for the Hypercerts Protocol.
+description: Learn how Hypercerts connects work, evidence, assessments, and funding, then start building with it.
 ---
 
-# Hypercerts Documentation
+# Build with Hypercerts
 
-The Hypercerts Protocol provides shared record formats and usage conventions for publishing information about work, evidence, evaluations, and funding on AT Protocol.
+A project's story should travel with it: the work it has done, the people who contributed, what others think of it, and the support it has received. With Hypercerts, you can build applications that add to that story and use what others have already shared.
 
-The protocol does not currently have a separate formal specification. The Guide, available integration material, source-backed technical reference, and change history together describe how compatible applications use and evolve the protocol.
+Looking for a high-level introduction? Start at [hypercerts.org](https://hypercerts.org). These docs take the next step: understanding how it all works, then putting it into practice.
 
-## Choose a section
+## Start with the Guide
+
+The [Guide](/guide) introduces the building blocks through the questions they help answer. How do you describe work? How can someone else evaluate it? How can a funding platform use that assessment without asking the project to start again?
+
+Read it from start to finish, or jump to a concept you want to understand. You don't need to know AT Protocol before you begin.
 
 {% card-grid %}
 {% card-link title="Guide" href="/guide" %}
-Understand the protocol, its data model, and shared usage conventions.
+Understand how projects, evidence, evaluations, and funding connect across applications.
 {% /card-link %}
-{% card-link title="Client integration" href="/client-integration" %}
-Review the target path from authentication and record creation to discovery and display, including the current gaps.
+{% card-link title="Client Integration" href="/client-integration" %}
+Move from understanding to implementation, with the available walkthroughs and SDK and API guidance as it develops.
 {% /card-link %}
 {% card-link title="Reference" href="/reference" %}
-Inspect Lexicons, service architecture, interfaces, environments, and tooling.
+Look up record fields, schemas, and service details while you build.
 {% /card-link %}
-{% card-link title="Change history" href="/change-history" %}
-Track schema and component changes, compatibility notes, and migration guidance.
+{% card-link title="Change History" href="/change-history" %}
+See what has changed and what it means for your integration.
 {% /card-link %}
 {% /card-grid %}
-
-## Recommended path
-
-1. Start with the [Guide](/guide) to understand the model and common interpretation.
-2. Use [Client integration](/client-integration) for current integration material and known gaps.
-3. Consult the [Reference](/reference) for exact source-backed contracts.
-4. Review [Change history](/change-history) when upgrading an integration.
diff --git a/pages/reference/faq.md b/pages/reference/faq.md
index 9a35d27..2655e9e 100644
--- a/pages/reference/faq.md
+++ b/pages/reference/faq.md
@@ -41,7 +41,7 @@ For a known AT-URI, read the record from its repository. Cross-repository discov
 
 ## How do I fund a hypercert?
 
-Hypercerts does not execute payments. A platform can process funding through its chosen payment rail and publish a funding receipt that describes the payment. The receipt does not independently prove settlement. See [Funding Records & Value Flow](/core-concepts/funding-and-value-flow).
+Hypercerts does not execute payments. A platform can process funding through its chosen payment rail and publish a funding receipt that describes the payment. The receipt does not independently prove settlement. See [Funding and Learning](/core-concepts/funding-and-value-flow).
 
 ## Where do I get help?
 
diff --git a/pages/reference/glossary.md b/pages/reference/glossary.md
index 8dbab13..66b4e9d 100644
--- a/pages/reference/glossary.md
+++ b/pages/reference/glossary.md
@@ -73,4 +73,4 @@ A reference to another record that includes both the AT-URI and a content hash (
 
 #### Work scope
 
-The "what" dimension of a hypercert — what work is being claimed. Can be a simple free-text string or a structured [CEL expression](https://github.com/google/cel-spec) for machine-evaluable scopes. See [Work Scopes](/core-concepts/cel-work-scopes).
+The "what" dimension of a hypercert, meaning the work being claimed. Can be a simple text description or a structured [CEL expression](https://github.com/google/cel-spec) for machine-evaluable scopes. See [Describing and Classifying Work](/core-concepts/cel-work-scopes).
diff --git a/pages/reference/lexicon-inventory.md b/pages/reference/lexicon-inventory.md
index 1107c3d..895c43e 100644
--- a/pages/reference/lexicon-inventory.md
+++ b/pages/reference/lexicon-inventory.md
@@ -68,4 +68,4 @@ Until that reference is generated, use the versioned package or [`v1.4.0` source
 
 The NPM package also bundles dependency schemas outside the `org.hypercerts.*` and `app.certified.*` namespaces. Package inclusion does not make every bundled namespace part of this documentation's Hypercerts Protocol surface.
 
-See the [Core Data Model](/core-concepts/hypercerts-core-data-model) for meaning and relationships and [Validation, Extension & Interpretation](/core-concepts/validation-and-interpretation) for constraints that applications must enforce.
+For a conceptual introduction, read [A Shared Language](/core-concepts/hypercerts-core-data-model). [Building on Shared Records](/core-concepts/validation-and-interpretation) explains how shared formats and application choices work together.

From eba1483e8a10042ba81e0e13ba58728201e57208 Mon Sep 17 00:00:00 2001
From: Kristofer Lund <kristofer@fmckl.se>
Date: Wed, 16 Sep 2026 10:34:20 +0200
Subject: [PATCH 4/7] feat: add dedicated docs landing page

---
 components/DocsSection.js                     |  35 +++
 components/Layout.js                          | 106 +++++---
 components/SearchDialog.js                    |   2 +-
 docs/information-architecture.md              |  14 +-
 lib/generate-search-index.js                  |   6 +-
 lib/navigation.js                             |   4 +-
 markdoc/tags/docs-section.markdoc.js          |   9 +
 markdoc/tags/index.js                         |   2 +
 pages/_app.js                                 |   2 +
 pages/{change-history => changes}/index.md    |   6 +-
 .../validation-and-interpretation.md          |   2 +-
 pages/index.md                                |  72 ++++-
 styles/globals.css                            | 245 ++++++++++++++++++
 vercel.json                                   |  10 +
 14 files changed, 451 insertions(+), 64 deletions(-)
 create mode 100644 components/DocsSection.js
 create mode 100644 markdoc/tags/docs-section.markdoc.js
 rename pages/{change-history => changes}/index.md (86%)

diff --git a/components/DocsSection.js b/components/DocsSection.js
new file mode 100644
index 0000000..2671fa2
--- /dev/null
+++ b/components/DocsSection.js
@@ -0,0 +1,35 @@
+import Link from 'next/link';
+
+const icons = {
+  guide: <path d="M12 6.5C9.5 4.5 6 4 3 5v14c3-1 6.5-.5 9 1.5C14.5 18.5 18 18 21 19V5c-3-1-6.5-.5-9 1.5Zm0 0v14" />,
+  integration: <path d="m8 6-6 6 6 6m8-12 6 6-6 6m-3-15-2 18" />,
+  reference: <><rect x="5" y="3" width="15" height="18" rx="2" /><path d="M9 3v18M3 7h4m-4 5h4m-4 5h4m5-10h5m-5 4h5" /></>,
+  changes: <><path d="M3 11a9 9 0 1 1 2.6 7.4M3 4v7h7" /><path d="M12 7v5l3 2" /></>,
+};
+
+/** A section introduction and its curated links on the documentation landing page. */
+export function DocsSection({ title, href, icon, description, children }) {
+  const headingId = `docs-${icon}`;
+
+  return (
+    <section className="docs-section" aria-labelledby={headingId}>
+      <div className="docs-section-intro">
+        <span className="docs-section-icon" aria-hidden="true">
+          <svg width="26" height="26" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.3" strokeLinecap="round" strokeLinejoin="round">
+            {icons[icon]}
+          </svg>
+        </span>
+        <h2 id={headingId}>
+          <Link href={href} className="docs-section-title">
+            {title}
+            <svg className="docs-section-arrow" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+              <path d="M4 12h16m-6-6 6 6-6 6" />
+            </svg>
+          </Link>
+        </h2>
+        <p>{description}</p>
+      </div>
+      <div className="docs-section-links">{children}</div>
+    </section>
+  );
+}
diff --git a/components/Layout.js b/components/Layout.js
index db6795d..8c7d293 100644
--- a/components/Layout.js
+++ b/components/Layout.js
@@ -4,7 +4,7 @@ import Link from 'next/link';
 import { useRouter } from 'next/router';
 import { Sidebar } from './Sidebar';
 import { TableOfContents } from './TableOfContents';
-import { getNavigationSection, getPrevNext } from '../lib/navigation';
+import { getNavigationSection, getPrevNext, navigation } from '../lib/navigation';
 import { LastUpdated } from './LastUpdated';
 import { Breadcrumbs } from './Breadcrumbs';
 import { ThemeToggle } from './ThemeToggle';
@@ -18,12 +18,26 @@ const DEFAULT_DESCRIPTION =
   'Documentation for the Hypercerts Protocol — structured, verifiable records of impact work built on AT Protocol.';
 const OG_IMAGE = `${SITE_URL}/images/hypercerts_logo.png`;
 
+function SectionLinks({ currentSection }) {
+  return navigation.map(({ section, children }) => (
+    <Link
+      key={section}
+      href={children[0].path}
+      className={`header-nav-link${currentSection === section ? ' header-nav-link-active' : ''}`}
+      aria-current={currentSection === section ? 'location' : undefined}
+    >
+      {section}
+    </Link>
+  ));
+}
+
 export default function Layout({ children, frontmatter }) {
   const [sidebarOpen, setSidebarOpen] = useState(false);
   const [sidebarCollapsed, setSidebarCollapsed] = useState(false);
   const [searchOpen, setSearchOpen] = useState(false);
   const router = useRouter();
   const currentPath = router.asPath.split('#')[0].split('?')[0];
+  const isLanding = currentPath === '/';
   const currentSection = getNavigationSection(currentPath)?.section;
   const { prev, next } = getPrevNext(currentPath);
 
@@ -36,7 +50,7 @@ export default function Layout({ children, frontmatter }) {
 
   const jsonLd = {
     '@context': 'https://schema.org',
-    '@type': 'TechArticle',
+    '@type': isLanding ? 'WebPage' : 'TechArticle',
     headline: title || SITE_NAME,
     description,
     url: canonicalUrl,
@@ -62,6 +76,10 @@ export default function Layout({ children, frontmatter }) {
     }
   }, []);
 
+  useEffect(() => {
+    setSidebarOpen(false);
+  }, [currentPath]);
+
   useEffect(() => {
     const handler = (e) => {
       if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
@@ -92,7 +110,7 @@ export default function Layout({ children, frontmatter }) {
         <link rel="canonical" href={canonicalUrl} />
 
         {/* Open Graph */}
-        <meta property="og:type" content="article" />
+        <meta property="og:type" content={isLanding ? 'website' : 'article'} />
         <meta property="og:title" content={pageTitle} />
         <meta property="og:description" content={description} />
         <meta property="og:url" content={canonicalUrl} />
@@ -121,23 +139,25 @@ export default function Layout({ children, frontmatter }) {
 
       <AnnouncementBanner />
 
-      <header className="layout-header">
+      <header className={`layout-header${isLanding ? ' layout-header-landing' : ''}`}>
         <a href="#main-content" className="skip-to-content">Skip to content</a>
         <div className="layout-header-inner">
-          <button
-            className="hamburger-btn"
-            onClick={() => setSidebarOpen(!sidebarOpen)}
-            aria-label="Toggle navigation"
-          >
-            <svg width="20" height="20" viewBox="0 0 20 20" fill="none">
-              <path
-                d="M3 5h14M3 10h14M3 15h14"
-                stroke="currentColor"
-                strokeWidth="1.5"
-                strokeLinecap="round"
-              />
-            </svg>
-          </button>
+          {!isLanding && (
+            <button
+              className="hamburger-btn"
+              onClick={() => setSidebarOpen(!sidebarOpen)}
+              aria-label="Toggle navigation"
+            >
+              <svg width="20" height="20" viewBox="0 0 20 20" fill="none">
+                <path
+                  d="M3 5h14M3 10h14M3 15h14"
+                  stroke="currentColor"
+                  strokeWidth="1.5"
+                  strokeLinecap="round"
+                />
+              </svg>
+            </button>
+          )}
           <Link href="/" className="layout-logo">
             <img
               src="/images/certified_wordmark_black.svg"
@@ -163,10 +183,7 @@ export default function Layout({ children, frontmatter }) {
           </Link>
           <span className="header-divider" aria-hidden="true" />
           <nav className="header-nav" aria-label="Main navigation">
-            <Link href="/guide" className={`header-nav-link${currentSection === 'Guide' ? ' header-nav-link-active' : ''}`}>Guide</Link>
-            <Link href="/client-integration" className={`header-nav-link${currentSection === 'Client Integration' ? ' header-nav-link-active' : ''}`}>Client integration</Link>
-            <Link href="/reference" className={`header-nav-link${currentSection === 'Reference' ? ' header-nav-link-active' : ''}`}>Reference</Link>
-            <Link href="/change-history" className={`header-nav-link${currentSection === 'Change History' ? ' header-nav-link-active' : ''}`}>Change history</Link>
+            <SectionLinks currentSection={currentSection} />
           </nav>
           <div style={{ flex: 1 }} />
           <button
@@ -205,22 +222,35 @@ export default function Layout({ children, frontmatter }) {
         </div>
       </header>
 
-      <div className="layout-container">
-        <Sidebar
-          isOpen={sidebarOpen}
-          onClose={() => setSidebarOpen(false)}
-          collapsed={sidebarCollapsed}
-          onToggleCollapse={toggleCollapsed}
-        />
+      {isLanding && (
+        <nav className="landing-section-nav" aria-label="Documentation sections">
+          <SectionLinks />
+        </nav>
+      )}
+
+      <div className={`layout-container${isLanding ? ' layout-container-landing' : ''}`}>
+        {!isLanding && (
+          <Sidebar
+            isOpen={sidebarOpen}
+            onClose={() => setSidebarOpen(false)}
+            collapsed={sidebarCollapsed}
+            onToggleCollapse={toggleCollapsed}
+          />
+        )}
 
-        <main className="layout-content" id="main-content">
-          <Breadcrumbs />
-          {frontmatter && <CopyRawButton />}
-          <LastUpdated />
+        <main className={`layout-content${isLanding ? ' docs-landing' : ''}`} id="main-content">
+          {!isLanding && (
+            <>
+              <Breadcrumbs />
+              {frontmatter && <CopyRawButton />}
+              <LastUpdated />
+            </>
+          )}
+          {isLanding && <p className="docs-landing-eyebrow">Documentation</p>}
           <article>{children}</article>
 
 
-          {(prev || next) && (
+          {!isLanding && (prev || next) && (
             <nav className="pagination" aria-label="Page navigation">
               <div className="pagination-prev">
                 {prev && (
@@ -242,9 +272,11 @@ export default function Layout({ children, frontmatter }) {
           )}
         </main>
 
-        <aside className="layout-toc">
-          <TableOfContents />
-        </aside>
+        {!isLanding && (
+          <aside className="layout-toc">
+            <TableOfContents />
+          </aside>
+        )}
       </div>
       <SearchDialog isOpen={searchOpen} onClose={() => setSearchOpen(false)} />
     </>
diff --git a/components/SearchDialog.js b/components/SearchDialog.js
index 30bae4c..477dcc0 100644
--- a/components/SearchDialog.js
+++ b/components/SearchDialog.js
@@ -26,7 +26,7 @@ const QUICK_LINK_PATHS = [
   '/guide',
   '/client-integration',
   '/reference',
-  '/change-history',
+  '/changes',
   '/core-concepts/what-is-hypercerts',
   '/core-concepts/hypercerts-core-data-model',
 ];
diff --git a/docs/information-architecture.md b/docs/information-architecture.md
index 1e05a9a..3b68b78 100644
--- a/docs/information-architecture.md
+++ b/docs/information-architecture.md
@@ -4,7 +4,7 @@ This is the working migration map for the protocol-first documentation restructu
 
 ## Principles
 
-- The documentation has four primary sections: Guide, Client Integration, Reference, and Change History.
+- The documentation has four primary sections: Guide, Client Integration, Reference, and Changes.
 - Together, the Guide, Lexicons, API and SDK contracts, reference implementation behavior, and change history describe the protocol. There is no separate ratified formal specification.
 - Guide pages explain meaning and shared usage. Reference pages provide exact source-backed contracts.
 - Integration pages publish tested paths, not inferred or aspirational APIs.
@@ -24,6 +24,12 @@ Assume readers have seen the landing page, with an optional link to `https://hyp
 - Keep the Guide navigation flat and ordered for a start-to-finish reading path. Each page leads to the next; the final page leads to Client Integration with its current implementation status clear.
 - Treat the older vision essay as separate background, outside the sequential Guide. It includes historical economic ideas that would interrupt the current learning path.
 
+## Documentation landing page
+
+The root route is a section directory, with a short introduction, four section overviews, and curated links into each section. It has no sidebar, table of contents, or article tools. The header and a compact section navigation on smaller screens provide access to the section hubs; each hub retains its own sidebar.
+
+The public name and route for change history are **Changes** and `/changes`. Redirect the previous `/change-history` route and its raw Markdown URL to their new equivalents.
+
 ## First-pass migration
 
 | Previous area | New primary home | Treatment |
@@ -34,7 +40,7 @@ Assume readers have seen the landing page, with an optional link to `https://hyp
 | Tools | Reference | Keep Agent Skills, Hypercerts Feed Service, Labelers, and legacy Hyperindex. Remove Scaffold from the active documentation because it is not a supported integration path. |
 | Architecture | Guide or Reference | Put lifecycle and portability guidance in Guide; put system and service architecture in Reference; put account setup in Client Integration. |
 | Lexicons and service directories | Reference | Keep existing routes and expand source-backed coverage. |
-| Lexicon releases | Change History | Keep the imported upstream changelog and add adopter-facing migration context separately. |
+| Lexicon releases | Changes | Keep the imported upstream changelog and add adopter-facing migration context separately. |
 | Ecosystem and vision | Separate background | Retain the existing essay route outside the sequential Guide; the landing page provides the high-level introduction. |
 | Roadmap | Unassigned | Keep the source for now, but do not mix planned capabilities into supported instructions or change history. |
 
@@ -52,7 +58,7 @@ The draft at `https://claude.ai/code/artifact/cf891a57-416c-4d63-8ec3-8194e6cb6e
 | Hypercerts and Certified schema chapters (sections 6 to 11) | Guide concept groups plus Lexicon Reference | Take structural facts from released Lexicons, not from the prose draft alone. |
 | Interoperability profiles (section 13) | Unresolved | Do not publish the proposed profiles as compatibility requirements. |
 | Authorization and permission sets (section 14) | Client Integration and Reference | Document released permission sets and tested OAuth behavior; review proposed expansion rules separately. |
-| Versioning and releases (section 15) | Change History | Distinguish independent component releases from any coordinated protocol release relationship. |
+| Versioning and releases (section 15) | Changes | Distinguish independent component releases from any coordinated protocol release relationship. |
 | Open issues (section 16) | Future known-limitations pages | Publish verified limitations, not speculative resolutions. |
 | Lexicon inventory (appendix B) | Reference coverage checklist | Verify every item against a released Lexicon source. |
 | Worked example (appendix C) | Future Client Integration walkthrough | Rebuild as a runnable, tested SDK and XRPC example. |
@@ -83,7 +89,7 @@ The narrative path now covers the main concepts, common usage, and the handoff t
 - Hypercerts API service overview and environments
 - Per-service subpages for ePDS, CGS, labelers, feed generators, relay or Jetstream, and operational status
 
-### Change History
+### Changes
 
 - Adopter-facing change entries that link meaning, schemas, components, and migration steps
 - Component changelog links without implying one universal compliance version
diff --git a/lib/generate-search-index.js b/lib/generate-search-index.js
index 62fe9eb..3c58003 100644
--- a/lib/generate-search-index.js
+++ b/lib/generate-search-index.js
@@ -86,8 +86,9 @@ function stripMarkdown(content) {
 }
 
 function getSection(path) {
-  if (path === "/change-history" || path === "/reference/releases") {
-    return "Change History";
+  if (path === "/") return "Documentation";
+  if (path === "/changes" || path === "/reference/releases") {
+    return "Changes";
   }
   if (
     path === "/client-integration" ||
@@ -98,7 +99,6 @@ function getSection(path) {
     return "Client Integration";
   }
   if (
-    path === "/" ||
     path === "/guide" ||
     path.startsWith("/core-concepts") ||
     path.startsWith("/ecosystem") ||
diff --git a/lib/navigation.js b/lib/navigation.js
index 8b3a2cd..5a9a353 100644
--- a/lib/navigation.js
+++ b/lib/navigation.js
@@ -163,9 +163,9 @@ export const navigation = [
     ],
   },
   {
-    section: "Change History",
+    section: "Changes",
     children: [
-      { title: "Change history overview", path: "/change-history" },
+      { title: "Changes overview", path: "/changes" },
       { title: "Lexicon Releases", path: "/reference/releases" },
     ],
   },
diff --git a/markdoc/tags/docs-section.markdoc.js b/markdoc/tags/docs-section.markdoc.js
new file mode 100644
index 0000000..e4d71a8
--- /dev/null
+++ b/markdoc/tags/docs-section.markdoc.js
@@ -0,0 +1,9 @@
+export default {
+  render: 'DocsSection',
+  attributes: {
+    title: { type: String, required: true },
+    href: { type: String, required: true },
+    icon: { type: String, required: true, matches: ['guide', 'integration', 'reference', 'changes'] },
+    description: { type: String, required: true },
+  },
+};
diff --git a/markdoc/tags/index.js b/markdoc/tags/index.js
index 9610e46..329bd7c 100644
--- a/markdoc/tags/index.js
+++ b/markdoc/tags/index.js
@@ -5,6 +5,7 @@ import figure from './figure.markdoc';
 import cardLink from './card-link.markdoc';
 import cardGrid from './card-grid.markdoc';
 import heroBanner from './hero-banner.markdoc';
+import docsSection from './docs-section.markdoc';
 import br from './br.markdoc';
 
 export default {
@@ -16,4 +17,5 @@ export default {
   'card-link': cardLink,
   'card-grid': cardGrid,
   'hero-banner': heroBanner,
+  'docs-section': docsSection,
 };
diff --git a/pages/_app.js b/pages/_app.js
index 281d55f..f60fa7a 100644
--- a/pages/_app.js
+++ b/pages/_app.js
@@ -11,6 +11,7 @@ import { Link } from '../components/Link';
 import { DotPattern } from '../components/DotPattern';
 import { HeroBanner } from '../components/HeroBanner';
 import { CardGrid } from '../components/CardGrid';
+import { DocsSection } from '../components/DocsSection';
 import { MermaidDiagram } from '../components/MermaidDiagram';
 import { Analytics } from '@vercel/analytics/next';
 
@@ -27,6 +28,7 @@ const components = {
   DotPattern,
   HeroBanner,
   CardGrid,
+  DocsSection,
   MermaidDiagram,
 };
 
diff --git a/pages/change-history/index.md b/pages/changes/index.md
similarity index 86%
rename from pages/change-history/index.md
rename to pages/changes/index.md
index 83f241f..df16eee 100644
--- a/pages/change-history/index.md
+++ b/pages/changes/index.md
@@ -1,11 +1,11 @@
 ---
-title: Change History
+title: Changes
 description: Adopter-facing history for Hypercerts schema, guidance, SDK, API, and service changes.
 ---
 
-# Change History
+# Changes
 
-Change history helps adopters understand what changed, who is affected, and whether an integration requires action.
+This section helps adopters understand what changed, who is affected, and whether an integration requires action.
 
 The current source-backed history covers [Hypercerts Lexicon releases](/reference/releases). Future entries should connect changes in protocol meaning and guidance to the affected Lexicons, SDK, APIs, and services.
 
diff --git a/pages/core-concepts/validation-and-interpretation.md b/pages/core-concepts/validation-and-interpretation.md
index ed0c606..9b25ccf 100644
--- a/pages/core-concepts/validation-and-interpretation.md
+++ b/pages/core-concepts/validation-and-interpretation.md
@@ -33,7 +33,7 @@ Other applications may use newer fields, unfamiliar categories, or extensions yo
 
 If your use case needs something the shared formats don't cover, you can define another Lexicon and publish records that link to the existing work. Other apps and indexers will need to support that extension before they can use it. This lets specialized tools develop without replacing the shared foundation.
 
-The [Reference](/reference) links to exact schemas and service documentation. The current Guide uses the Hypercerts and Certified schemas in `@hypercerts-org/lexicon` 1.4.0; [Change History](/change-history) is where to follow their evolution.
+The [Reference](/reference) links to exact schemas and service documentation. The current Guide uses the Hypercerts and Certified schemas in `@hypercerts-org/lexicon` 1.4.0; [Changes](/changes) is where to follow their evolution.
 
 ## Take the next step
 
diff --git a/pages/index.md b/pages/index.md
index 50f47a5..217fb26 100644
--- a/pages/index.md
+++ b/pages/index.md
@@ -5,27 +5,73 @@ description: Learn how Hypercerts connects work, evidence, assessments, and fund
 
 # Build with Hypercerts
 
-A project's story should travel with it: the work it has done, the people who contributed, what others think of it, and the support it has received. With Hypercerts, you can build applications that add to that story and use what others have already shared.
+A project's story should travel with it: the work it has done, the evidence behind it, and the support it has received. Learn how the pieces connect, then build applications that add to that story.
 
-Looking for a high-level introduction? Start at [hypercerts.org](https://hypercerts.org). These docs take the next step: understanding how it all works, then putting it into practice.
+New to Hypercerts? Get the high-level introduction at [hypercerts.org](https://hypercerts.org), or start exploring below.
 
-## Start with the Guide
+{% docs-section title="Guide" href="/guide" icon="guide" description="Start with the concepts. Follow how work, evidence, assessments, and funding connect across applications." %}
 
-The [Guide](/guide) introduces the building blocks through the questions they help answer. How do you describe work? How can someone else evaluate it? How can a funding platform use that assessment without asking the project to start again?
+{% card-grid %}
+{% card-link title="Activity claims" href="/core-concepts/what-is-hypercerts" %}
+Describe the work and the people who contributed.
+{% /card-link %}
+{% card-link title="Projects and collections" href="/core-concepts/projects-and-collections" %}
+Bring related work together over time.
+{% /card-link %}
+{% card-link title="Evidence and measurements" href="/core-concepts/evidence-and-measurements" %}
+Connect reports, observations, and data to the work.
+{% /card-link %}
+{% card-link title="Evaluations" href="/core-concepts/evaluations" %}
+Add assessments that others can build on.
+{% /card-link %}
+{% /card-grid %}
+
+{% /docs-section %}
+
+{% docs-section title="Client Integration" href="/client-integration" icon="integration" description="Put the ideas into practice. Explore account setup and available walkthroughs as the SDK and API guidance develops." %}
+
+{% card-grid %}
+{% card-link title="Building on Hypercerts" href="/getting-started/building-on-hypercerts" %}
+Find a starting point for your application.
+{% /card-link %}
+{% card-link title="Accounts and identity" href="/architecture/account-and-identity" %}
+Understand accounts, handles, and authentication.
+{% /card-link %}
+{% card-link title="Integrate with ePDS" href="/tutorials/epds" %}
+Follow the authentication walkthrough.
+{% /card-link %}
+{% card-link title="Testing and deployment" href="/getting-started/testing-and-deployment" %}
+Prepare your integration for real use.
+{% /card-link %}
+{% /card-grid %}
+
+{% /docs-section %}
 
-Read it from start to finish, or jump to a concept you want to understand. You don't need to know AT Protocol before you begin.
+{% docs-section title="Reference" href="/reference" icon="reference" description="Look up the details while you build: record schemas, architecture, services, and supporting tools." %}
 
 {% card-grid %}
-{% card-link title="Guide" href="/guide" %}
-Understand how projects, evidence, evaluations, and funding connect across applications.
+{% card-link title="Lexicon reference" href="/reference/lexicon-inventory" %}
+Find the schemas for Hypercerts and Certified records.
 {% /card-link %}
-{% card-link title="Client Integration" href="/client-integration" %}
-Move from understanding to implementation, with the available walkthroughs and SDK and API guidance as it develops.
+{% card-link title="Architecture" href="/architecture/overview" %}
+See how the network and its services fit together.
 {% /card-link %}
-{% card-link title="Reference" href="/reference" %}
-Look up record fields, schemas, and service details while you build.
+{% card-link title="Services and endpoints" href="/reference/certified-services" %}
+Find service environments and their details.
 {% /card-link %}
-{% card-link title="Change History" href="/change-history" %}
-See what has changed and what it means for your integration.
+{% card-link title="Glossary" href="/reference/glossary" %}
+Get a quick explanation of an unfamiliar term.
 {% /card-link %}
 {% /card-grid %}
+
+{% /docs-section %}
+
+{% docs-section title="Changes" href="/changes" icon="changes" description="Follow releases and understand what has changed. The release history currently covers the Lexicon package." %}
+
+{% card-grid columns=1 %}
+{% card-link title="Lexicon releases" href="/reference/releases" %}
+Read the package changelog from the source repository.
+{% /card-link %}
+{% /card-grid %}
+
+{% /docs-section %}
diff --git a/styles/globals.css b/styles/globals.css
index bf88f1c..af5a6eb 100644
--- a/styles/globals.css
+++ b/styles/globals.css
@@ -2205,3 +2205,248 @@ html.dark .search-result-snippet mark {
     padding: var(--space-4) var(--space-3);
   }
 }
+
+/* ===== Documentation landing page ===== */
+.layout-container-landing {
+  display: block;
+}
+
+.layout-content.docs-landing {
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: 72px var(--space-10) var(--space-16);
+}
+
+.docs-landing .docs-landing-eyebrow {
+  margin: 0 0 var(--space-4);
+  font-family: var(--font-secondary);
+  font-size: 12px;
+  font-weight: 500;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--color-text-secondary);
+}
+
+.docs-landing h1 {
+  margin-bottom: var(--space-6);
+  font-size: clamp(40px, 4vw, 56px);
+  line-height: 1.1;
+}
+
+.docs-landing article > p {
+  max-width: 740px;
+}
+
+.docs-landing article > p:first-of-type {
+  font-size: 19px;
+  line-height: 1.65;
+  margin-bottom: var(--space-4);
+}
+
+.docs-landing article > p + p {
+  font-size: 14px;
+  color: var(--color-text-secondary);
+  margin-bottom: 56px;
+}
+
+.docs-section {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(0, 2fr);
+  gap: var(--space-16);
+  padding: var(--space-10) 0;
+  border-top: 1px solid var(--color-border);
+  align-items: start;
+}
+
+.docs-section-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 44px;
+  height: 44px;
+  margin-bottom: var(--space-4);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-md);
+  background: var(--color-info-bg);
+  color: var(--color-accent);
+}
+
+.docs-section h2 {
+  margin: 0 0 var(--space-3);
+  font-size: 30px;
+  line-height: 1.2;
+}
+
+.docs-section a.docs-section-title {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-3);
+  color: var(--color-text-title);
+  text-decoration: none;
+}
+
+.docs-section a.docs-section-title:hover {
+  color: var(--color-link-hover);
+}
+
+.docs-section-arrow {
+  flex-shrink: 0;
+}
+
+.docs-section-intro > p {
+  margin: 0;
+  font-size: 15px;
+  line-height: 1.6;
+  color: var(--color-text-secondary);
+}
+
+.docs-section .card-grid {
+  margin: 0;
+  gap: var(--space-3);
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+}
+
+.docs-section a.card-link {
+  align-items: flex-start;
+  padding: var(--space-5);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-md);
+  min-height: 112px;
+  transition: background var(--transition-fast), border-color var(--transition-fast);
+}
+
+.docs-section a.card-link:hover {
+  border-color: var(--color-border-strong);
+  background: var(--color-bg-subtle);
+}
+
+.docs-section .card-link-title {
+  font-size: 15px;
+  line-height: 1.4;
+  margin-bottom: var(--space-1);
+}
+
+.docs-section .card-link-desc p {
+  margin: 0;
+  font-size: 14px;
+  line-height: 1.5;
+}
+
+.landing-section-nav {
+  display: none;
+}
+
+@media (max-width: 1099px) {
+  .landing-section-nav {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: var(--space-2) var(--space-3);
+    border-bottom: 1px solid var(--color-border);
+    overflow-x: auto;
+  }
+
+  .landing-section-nav .header-nav-link {
+    flex-shrink: 0;
+    white-space: nowrap;
+  }
+
+  .docs-section {
+    gap: var(--space-8);
+  }
+}
+
+@media (max-width: 768px) {
+  .layout-content.docs-landing {
+    padding: var(--space-10) var(--space-6);
+  }
+
+  .docs-landing article > p:first-of-type {
+    font-size: 17px;
+  }
+
+  .docs-landing article > p + p {
+    margin-bottom: var(--space-8);
+  }
+
+  .docs-section {
+    grid-template-columns: minmax(0, 1fr);
+    gap: var(--space-6);
+    padding: var(--space-8) 0;
+  }
+
+  .docs-section-intro {
+    display: grid;
+    grid-template-columns: 44px minmax(0, 1fr);
+    column-gap: var(--space-4);
+    align-items: center;
+  }
+
+  .docs-section-icon {
+    margin: 0;
+  }
+
+  .docs-section h2 {
+    margin: 0;
+    font-size: 28px;
+  }
+
+  .docs-section-intro > p {
+    grid-column: 1 / -1;
+    margin-top: var(--space-3);
+  }
+
+  .landing-section-nav {
+    justify-content: flex-start;
+  }
+
+  .landing-section-nav .header-nav-link {
+    padding: 6px 8px;
+    font-size: 13px;
+  }
+}
+
+@media (max-width: 480px) {
+  .layout-header-landing .layout-logo-wordmark {
+    height: 14px;
+  }
+
+  .layout-header-landing .layout-logo-icon {
+    height: 18px;
+  }
+
+  .layout-header-landing .header-icon-link {
+    display: none;
+  }
+
+  .landing-section-nav {
+    justify-content: space-between;
+    padding: var(--space-1) var(--space-2);
+  }
+
+  .landing-section-nav .header-nav-link {
+    padding: 10px var(--space-1);
+    font-size: 12px;
+  }
+
+  .layout-content.docs-landing {
+    padding-left: var(--space-4);
+    padding-right: var(--space-4);
+  }
+
+  .docs-section .card-grid {
+    grid-template-columns: minmax(0, 1fr);
+    gap: var(--space-2);
+  }
+
+  .docs-section a.card-link {
+    min-height: 0;
+    padding: var(--space-4);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .docs-section a.card-link {
+    transition: none;
+  }
+}
diff --git a/vercel.json b/vercel.json
index 8353993..a16ff3d 100644
--- a/vercel.json
+++ b/vercel.json
@@ -3,6 +3,16 @@
   "installCommand": "npm install",
   "framework": "nextjs",
   "redirects": [
+    {
+      "source": "/change-history",
+      "destination": "/changes",
+      "permanent": true
+    },
+    {
+      "source": "/raw/change-history.md",
+      "destination": "/raw/changes.md",
+      "permanent": true
+    },
     {
       "source": "/getting-started/quickstart",
       "destination": "/client-integration",

From d492d6ee06d1449ad2c00a33f9b37ad32e4fa0d9 Mon Sep 17 00:00:00 2001
From: Kristofer Lund <kristofer@fmckl.se>
Date: Wed, 16 Sep 2026 11:49:56 +0200
Subject: [PATCH 5/7] feat: publish protocol history and component releases

---
 .github/workflows/docs-ci.yml          |  5 ++
 .gitignore                             |  1 +
 components/CardLink.js                 |  3 +-
 components/Sidebar.js                  |  1 +
 docs-sources.yml                       | 22 +++++++
 docs/information-architecture.md       | 14 ++++-
 docs/remote-markdown.md                | 20 ++++++-
 lib/external-doc-links.js              | 15 +++--
 lib/external-doc-page.js               |  4 +-
 lib/external-docs-loader.js            |  4 ++
 lib/external-docs-snapshot.js          | 27 ++++++++-
 lib/external-docs.js                   |  9 ++-
 lib/generate-docs-fingerprint.js       |  2 +-
 lib/generate-external-docs-manifest.js |  8 ++-
 lib/generate-search-index.js           |  2 +-
 lib/navigation.js                      |  9 ++-
 lib/protocol-releases.json             | 67 ++++++++++++++++++++++
 lib/release-components.json            | 48 ++++++++++++++++
 lib/releases.js                        | 62 ++++++++++++++++++++
 markdoc/nodes/index.js                 |  1 +
 markdoc/nodes/text.markdoc.js          | 17 ++++++
 markdoc/tags/card-link.markdoc.js      |  1 +
 pages/changes/api.md                   | 12 ++++
 pages/changes/cgs.md                   |  5 ++
 pages/changes/entryway.md              | 12 ++++
 pages/changes/feed-service.md          |  5 ++
 pages/changes/index.md                 | 33 +++++++----
 pages/changes/protocol.md              | 14 +++++
 pages/changes/relay.md                 |  5 ++
 pages/changes/sdk.md                   | 12 ++++
 pages/index.md                         | 12 ++--
 pages/reference/index.md               |  9 ++-
 styles/globals.css                     | 34 +++++++++++
 test/changelog-rendering.test.js       | 20 +++++++
 test/external-docs-snapshot.test.js    | 36 ++++++++++++
 test/external-docs.test.js             |  1 +
 test/releases.test.js                  | 79 ++++++++++++++++++++++++++
 37 files changed, 589 insertions(+), 42 deletions(-)
 create mode 100644 lib/protocol-releases.json
 create mode 100644 lib/release-components.json
 create mode 100644 lib/releases.js
 create mode 100644 markdoc/nodes/text.markdoc.js
 create mode 100644 pages/changes/api.md
 create mode 100644 pages/changes/cgs.md
 create mode 100644 pages/changes/entryway.md
 create mode 100644 pages/changes/feed-service.md
 create mode 100644 pages/changes/protocol.md
 create mode 100644 pages/changes/relay.md
 create mode 100644 pages/changes/sdk.md
 create mode 100644 test/changelog-rendering.test.js
 create mode 100644 test/releases.test.js

diff --git a/.github/workflows/docs-ci.yml b/.github/workflows/docs-ci.yml
index 4260c4a..4b07e80 100644
--- a/.github/workflows/docs-ci.yml
+++ b/.github/workflows/docs-ci.yml
@@ -15,6 +15,11 @@ on:
       - 'lib/generate-raw-pages.js'
       - 'lib/generate-search-index.js'
       - 'lib/compare-docs-fingerprint.js'
+      - 'lib/releases.js'
+      - 'lib/release-components.json'
+      - 'lib/protocol-releases.json'
+      - 'lib/navigation.js'
+      - 'styles/**'
       - 'markdoc/**'
       - 'next.config.js'
       - 'pages/**'
diff --git a/.gitignore b/.gitignore
index 06937ba..3bd32a3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,3 +13,4 @@ current-docs-fingerprint.json
 deployed-docs-fingerprint.json
 lib/external-docs-content.json
 lib/lastUpdated.json
+lib/release-catalog.json
diff --git a/components/CardLink.js b/components/CardLink.js
index c860124..08995e5 100644
--- a/components/CardLink.js
+++ b/components/CardLink.js
@@ -1,6 +1,6 @@
 import Link from "next/link";
 
-export function CardLink({ title, href, icon, children }) {
+export function CardLink({ title, href, icon, badge, children }) {
   return (
     <Link href={href} className="card-link">
       {icon && (
@@ -10,6 +10,7 @@ export function CardLink({ title, href, icon, children }) {
       )}
       <span className="card-link-text">
         <span className="card-link-title">{title}</span>
+        {badge && <span className="release-badge">{badge}</span>}
         {children && <span className="card-link-desc">{children}</span>}
       </span>
     </Link>
diff --git a/components/Sidebar.js b/components/Sidebar.js
index 8fcaeb5..74a8ebb 100644
--- a/components/Sidebar.js
+++ b/components/Sidebar.js
@@ -37,6 +37,7 @@ function NavItem({ item, currentPath, depth = 0 }) {
             style={{ paddingLeft: `${16 + depth * 16}px` }}
           >
             {item.title}
+            {item.badge && <span className="sidebar-release-badge">{item.badge}</span>}
           </Link>
         ) : (
           <span
diff --git a/docs-sources.yml b/docs-sources.yml
index 11a7593..225a87c 100644
--- a/docs-sources.yml
+++ b/docs-sources.yml
@@ -22,3 +22,25 @@ sources:
     repo: hypercerts-org/hypercerts-lexicon
     ref: main
     path: CHANGELOG.md
+    trackRelease: true
+
+  - id: cgs-changelog
+    title: Certified Group Service changelog
+    repo: hypercerts-org/certified-group-service
+    ref: main
+    path: CHANGELOG.md
+    trackRelease: true
+
+  - id: relay-changelog
+    title: Hypercerts Relay changelog
+    repo: hypercerts-org/hypercerts-relay
+    ref: main
+    path: CHANGELOG.md
+    trackRelease: true
+
+  - id: feed-changelog
+    title: Hypercerts Feed Service changelog
+    repo: hypercerts-org/hypercerts-feed-service
+    ref: main
+    path: CHANGELOG.md
+    trackRelease: true
diff --git a/docs/information-architecture.md b/docs/information-architecture.md
index 3b68b78..18ff96c 100644
--- a/docs/information-architecture.md
+++ b/docs/information-architecture.md
@@ -30,6 +30,14 @@ The root route is a section directory, with a short introduction, four section o
 
 The public name and route for change history are **Changes** and `/changes`. Redirect the previous `/change-history` route and its raw Markdown URL to their new equivalents.
 
+## Protocol release communication
+
+The documentation repository is the canonical source for protocol major/minor releases. The participating stack is Lexicons, Hypercerts API, SDK, Certified Group Service, Entryway, Relay, and Feed Service. Major/minor versions are coordinated; component patches advance independently. The intended shared-version compatibility promise must be supported by testing, not inferred from matching labels.
+
+The initial protocol history is reconstructed from Lexicon 1.0 through 1.4. This describes the changes that drove those release lines, not a retroactive assertion that all services shipped simultaneously or used those numbers. Component cards and sidebar badges show their actual published versions. Numeric alignment, release sources for the API and entryway, and the new SDK's first release remain implementation work in the owning projects.
+
+The Changes overview and docs landing page share the latest protocol summary and component catalog. Full protocol history lives at `/changes/protocol`; component changelogs are imported from owning repositories at build time. Blog links are added only when a real release article exists. See [the release-maintenance workflow](remote-markdown.md#protocol-releases-and-component-versions).
+
 ## First-pass migration
 
 | Previous area | New primary home | Treatment |
@@ -91,9 +99,9 @@ The narrative path now covers the main concepts, common usage, and the handoff t
 
 ### Changes
 
-- Adopter-facing change entries that link meaning, schemas, components, and migration steps
-- Component changelog links without implying one universal compliance version
-- Migration guides for changes that require adopter action
+- Establish the API and entryway release sources and connect the SDK when its repository exists.
+- Align component major/minor versions in the owning projects and verify the supported combinations.
+- Write release articles and migration guides for future coordinated changes that need them.
 
 ## External service documentation
 
diff --git a/docs/remote-markdown.md b/docs/remote-markdown.md
index ea19486..4e135df 100644
--- a/docs/remote-markdown.md
+++ b/docs/remote-markdown.md
@@ -60,6 +60,7 @@ sources:
 - `repo` is the GitHub `owner/repository` pair.
 - `ref` is the branch, tag, or commit to fetch.
 - `path` is one `.md`, `.mdoc`, or `.mdx` file in that repository.
+- `trackRelease: true` optionally captures the repository's latest published stable GitHub Release alongside its changelog. A missing release is supported; failed requests and non-semantic or prerelease tags are not turned into version badges.
 
 GitHub API request and browser URLs are derived internally. Do not add URLs, directory paths, or separate entrypoints to the registry.
 
@@ -103,11 +104,28 @@ Choose `ref` according to the source's publishing policy. A moving branch such a
 
 External Markdown is parsed with the same Markdoc configuration as local pages. Relative links point to the source repository, relative images use public GitHub content URLs, and fenced `mermaid` diagrams render through the Mermaid component. Extensionless relative paths are treated as directories; link to extensionless files such as `LICENSE`, `Dockerfile`, or `Makefile` with an absolute GitHub URL.
 
+## Protocol releases and component versions
+
+`lib/protocol-releases.json` is the reviewed, canonical protocol major/minor history, newest first. The initial 1.0–1.4 entries are reconstructed from Lexicon releases; dates are the corresponding package publication dates. A component release does not automatically announce a new protocol release. Edit this file to publish the next coordinated release summary, compatibility guidance, and source version. An optional `blogUrl` adds a release-article link when an article is actually published.
+
+`lib/release-components.json` names the seven participating components and their local changelog routes. A `sourceId` connects a component to a release-tracked source in `docs-sources.yml`. Components without a published release display **Under development**; the new SDK has no source repository attached yet. Entryway is separate from the preceding ePDS product, and HappyView's version is not substituted for the Hypercerts API version.
+
+During generation, `lib/release-catalog.json` holds the compact version/status data used by the sidebar. The same catalog is saved inside the external content snapshot. Local pages use these standalone build-time markers:
+
+- `release-latest`: short current-release summary for the landing page.
+- `release-summary`: current release with highlights and source links.
+- `release-cards`: protocol-history link and all component version/status cards.
+- `protocol-history`: the full reviewed major/minor history.
+
+Write a marker as a self-closing Markdoc-style line, such as `{% release-summary /%}`. The shared page resolver expands it before Markdoc rendering, search indexing, or raw Markdown export, so those surfaces contain the same actual release information. No release lookup happens in the browser.
+
+To connect a future component: register its verified `CHANGELOG.md` with `trackRelease: true`, assign that `sourceId` in the component registry, and replace the local status page with a frontmatter-only `externalDoc` wrapper. Do not point the new SDK or XRPC API at the similarly named legacy repositories.
+
 A missing source, failed content request, empty file, local fallback body, or invalid Markdoc in an external page fails the build with an actionable error. The existing deployment remains online instead of publishing stale or inconsistent content. Source commit timestamps are informational and may be omitted when GitHub cannot provide them.
 
 ## Refresh workflow
 
-`.github/workflows/docs-refresh.yml` runs hourly and can also be dispatched manually. It fetches the registered files, compares their combined fingerprint with the deployed site, and calls the configured Vercel deploy hook when they differ. Manual runs default to dry-run mode.
+`.github/workflows/docs-refresh.yml` runs hourly and can also be dispatched manually. It fetches the registered files and tracked release metadata, compares their combined fingerprint with the deployed site, and calls the configured Vercel deploy hook when they differ. A newly published component version triggers refresh even if the changelog content has not changed. Manual runs default to dry-run mode.
 
 `.github/workflows/docs-ci.yml` runs tests and builds the static documentation on relevant pull requests targeting `main`; it does not call a deploy hook.
 
diff --git a/lib/external-doc-links.js b/lib/external-doc-links.js
index 658d0bd..fee4f83 100644
--- a/lib/external-doc-links.js
+++ b/lib/external-doc-links.js
@@ -26,14 +26,13 @@ function resolveExternalDocHref(href, source) {
 
   const { owner, repoName, sourceDirectory } = getSourceLocation(source);
   const encodedRef = encodeURIComponent(source.ref);
-  const basePath = `/${owner}/${repoName}/blob/${encodedRef}/${sourceDirectory ? `${sourceDirectory}/` : ''}`;
-  const resolved = new URL(href, `https://github.com${basePath}`);
-  const [, resolvedOwner, resolvedRepo, , ref, ...repoPathParts] = resolved.pathname.split('/');
-  const repoPath = repoPathParts.join('/');
-  const lastSegment = repoPathParts[repoPathParts.length - 1] || '';
+  // Resolve inside a virtual repository root so excess '..' cannot consume the ref or repository.
+  const resolved = new URL(href, `https://repository.local/${sourceDirectory ? `${sourceDirectory}/` : ''}`);
+  const repoPath = resolved.pathname.slice(1);
+  const lastSegment = repoPath.split('/').pop() || '';
   const mode = /\.[a-z0-9]+$/i.test(lastSegment) ? 'blob' : 'tree';
 
-  return `https://github.com/${resolvedOwner}/${resolvedRepo}/${mode}/${ref}/${repoPath}${resolved.search}${resolved.hash}`;
+  return `https://github.com/${owner}/${repoName}/${mode}/${encodedRef}/${repoPath}${resolved.search}${resolved.hash}`;
 }
 
 /**
@@ -43,8 +42,8 @@ function resolveExternalDocImageSrc(src, source) {
   if (isAbsoluteOrSiteHref(src)) return src;
 
   const { owner, repoName, sourceDirectory } = getSourceLocation(source);
-  const base = `https://raw.githubusercontent.com/${owner}/${repoName}/${encodeURIComponent(source.ref)}/${sourceDirectory ? `${sourceDirectory}/` : ''}`;
-  return new URL(src, base).toString();
+  const resolved = new URL(src, `https://repository.local/${sourceDirectory ? `${sourceDirectory}/` : ''}`);
+  return `https://raw.githubusercontent.com/${owner}/${repoName}/${encodeURIComponent(source.ref)}${resolved.pathname}${resolved.search}${resolved.hash}`;
 }
 
 module.exports = {
diff --git a/lib/external-doc-page.js b/lib/external-doc-page.js
index f61b8c4..2fb2bf9 100644
--- a/lib/external-doc-page.js
+++ b/lib/external-doc-page.js
@@ -1,3 +1,5 @@
+const { expandReleaseMarkdown } = require('./releases');
+
 /**
  * Resolve one externalDoc id to the exact Markdown snapshot used by the build.
  */
@@ -31,7 +33,7 @@ function getMarkdownBody(markdown) {
  */
 function resolvePageDocument(frontmatter, localMarkdown, content, label = 'Markdown page') {
   if (!Object.prototype.hasOwnProperty.call(frontmatter, 'externalDoc')) {
-    return { markdown: localMarkdown, externalDoc: null };
+    return { markdown: expandReleaseMarkdown(localMarkdown, content?.releases), externalDoc: null };
   }
 
   if (getMarkdownBody(localMarkdown).trim() !== '') {
diff --git a/lib/external-docs-loader.js b/lib/external-docs-loader.js
index 4b959ee..a512313 100644
--- a/lib/external-docs-loader.js
+++ b/lib/external-docs-loader.js
@@ -36,6 +36,10 @@ function compileExternalDocPage(frontmatter, source, content, label) {
 function externalDocsLoader(source) {
   const frontmatter = parseMarkdownFrontmatter(source, this.resourcePath);
   if (!Object.prototype.hasOwnProperty.call(frontmatter, 'externalDoc')) {
+    if (/^{% (release-latest|release-summary|release-cards|protocol-history) \/%}$/m.test(source)) {
+      this.addDependency(CONTENT_PATH);
+      return resolvePageDocument(frontmatter, source, loadExternalDocsContent(), this.resourcePath).markdown;
+    }
     return source;
   }
 
diff --git a/lib/external-docs-snapshot.js b/lib/external-docs-snapshot.js
index cb001d0..2aed197 100644
--- a/lib/external-docs-snapshot.js
+++ b/lib/external-docs-snapshot.js
@@ -105,13 +105,35 @@ async function fetchSourceUpdatedAt(source, token) {
   }
 }
 
+/** Read a published stable GitHub release, never a package.json development version. */
+async function fetchLatestRelease(source, token) {
+  const url = `https://api.github.com/repos/${source.repo}/releases/latest`;
+  const response = await fetch(url, {
+    headers: getGitHubHeaders(token, 'application/vnd.github+json', 'hypercerts-docs-build'),
+    cache: 'no-store',
+  });
+  // No published release is a supported state. The Markdown fetch separately verifies repository access.
+  if (response.status === 404) return null;
+  if (!response.ok) throw new Error(`Release metadata for ${source.id} returned ${response.status}. Refusing to label a failed lookup as unreleased.`);
+  const release = await response.json();
+  const version = /^v?((?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*))$/.exec(release.tag_name || '')?.[1];
+  if (!version || release.draft || release.prerelease) throw new Error(`Expected a stable semantic release tag for ${source.id}.`);
+  return {
+    version,
+    tag: release.tag_name,
+    url: `https://github.com/${source.repo}/releases/tag/${encodeURIComponent(release.tag_name)}`,
+    publishedAt: release.published_at,
+  };
+}
+
 /**
  * Fetch one immutable Markdown snapshot used by rendering, search, raw exports, and fingerprinting.
  */
 async function collectSourceSnapshot(source, token = '') {
-  const [markdown, updatedAt] = await Promise.all([
+  const [markdown, updatedAt, release] = await Promise.all([
     fetchSourceMarkdown(source, token),
     fetchSourceUpdatedAt(source, token),
+    source.trackRelease ? fetchLatestRelease(source, token) : undefined,
   ]);
 
   return {
@@ -120,6 +142,7 @@ async function collectSourceSnapshot(source, token = '') {
     size: Buffer.byteLength(markdown),
     contentHash: sha256(markdown),
     markdown,
+    ...(source.trackRelease ? { release } : {}),
   };
 }
 
@@ -141,6 +164,7 @@ function stableSnapshotSource(snapshot) {
     ref: snapshot.ref,
     path: snapshot.path,
     contentHash: snapshot.contentHash,
+    ...(snapshot.trackRelease ? { release: snapshot.release || null } : {}),
   };
 }
 
@@ -164,6 +188,7 @@ function buildFingerprintDocument(snapshots) {
       size: snapshot.size,
       contentHash: snapshot.contentHash,
       fingerprint,
+      ...(snapshot.trackRelease ? { release: snapshot.release || null } : {}),
     };
     stableSources.push({ ...stableSource, fingerprint });
   }
diff --git a/lib/external-docs.js b/lib/external-docs.js
index 9669f03..86b7d48 100644
--- a/lib/external-docs.js
+++ b/lib/external-docs.js
@@ -15,7 +15,7 @@ const CONTENT_PATH = join(__dirname, 'external-docs-content.json');
 /** File extensions accepted for registered external Markdown sources. */
 const MARKDOWN_EXTENSIONS = /\.(md|mdoc|mdx)$/i;
 /** Registry keys allowed on each external documentation source. */
-const SOURCE_FIELDS = new Set(['id', 'title', 'repo', 'ref', 'path']);
+const SOURCE_FIELDS = new Set(['id', 'title', 'repo', 'ref', 'path', 'trackRelease']);
 
 /**
  * Read the trusted GitHub organization allowlist, falling back to project defaults.
@@ -87,7 +87,7 @@ function normalizeSource(rawSource, index, allowedOrgs) {
 
   const unsupportedFields = Object.keys(rawSource).filter((field) => !SOURCE_FIELDS.has(field));
   if (unsupportedFields.length > 0) {
-    throw new Error(`Invalid docs-sources.yml: ${label} contains unsupported field${unsupportedFields.length === 1 ? '' : 's'} ${unsupportedFields.map((field) => `"${field}"`).join(', ')}. Use only id, title, repo, ref, and path.`);
+    throw new Error(`Invalid docs-sources.yml: ${label} contains unsupported field${unsupportedFields.length === 1 ? '' : 's'} ${unsupportedFields.map((field) => `"${field}"`).join(', ')}. Use only id, title, repo, ref, path, and trackRelease.`);
   }
 
   const { id, title, repo, ref } = rawSource;
@@ -112,12 +112,17 @@ function normalizeSource(rawSource, index, allowedOrgs) {
     throw new Error(`Invalid docs-sources.yml: source "${id}" ref must not contain control characters.`);
   }
 
+  if (rawSource.trackRelease !== undefined && typeof rawSource.trackRelease !== 'boolean') {
+    throw new Error(`Invalid docs-sources.yml: source "${id}" trackRelease must be a boolean.`);
+  }
+
   return {
     id,
     title: title.trim(),
     repo,
     ref: ref.trim(),
     path: normalizeRegistryPath(rawSource.path, `source "${id}" path`),
+    ...(rawSource.trackRelease !== undefined ? { trackRelease: rawSource.trackRelease } : {}),
   };
 }
 
diff --git a/lib/generate-docs-fingerprint.js b/lib/generate-docs-fingerprint.js
index a053fed..a1f5374 100644
--- a/lib/generate-docs-fingerprint.js
+++ b/lib/generate-docs-fingerprint.js
@@ -15,7 +15,7 @@ const DEFAULT_OUTPUT = join(__dirname, '..', 'public', 'docs-fingerprint.json');
  * 1. A site build fetches every registered Markdown file into one immutable snapshot.
  *    Rendering, search, raw exports, and this script all consume that same snapshot.
  * 2. Scheduled refresh checks have no build snapshot, so they fetch the registered files directly.
- * 3. Each source fingerprint includes its registry identity and SHA-256 content hash.
+ * 3. Each source fingerprint includes its registry identity, SHA-256 content hash, and any tracked published release.
  * 4. Per-source fingerprints are sorted by id and combined into one stable fingerprint.
  * 5. Generation and source-update timestamps are informational and never affect comparisons.
  */
diff --git a/lib/generate-external-docs-manifest.js b/lib/generate-external-docs-manifest.js
index c02a608..9deac44 100644
--- a/lib/generate-external-docs-manifest.js
+++ b/lib/generate-external-docs-manifest.js
@@ -1,7 +1,10 @@
 const { mkdirSync, writeFileSync } = require('fs');
-const { dirname } = require('path');
+const { dirname, join } = require('path');
 const { CONTENT_PATH, loadExternalDocSources } = require('./external-docs');
 const { collectExternalDocSnapshots } = require('./external-docs-snapshot');
+const { buildReleaseCatalog } = require('./releases');
+const protocol = require('./protocol-releases.json');
+const components = require('./release-components.json');
 
 /**
  * Fetch every registered Markdown file once and write the immutable build snapshot.
@@ -10,14 +13,17 @@ async function generateExternalDocs() {
   const sources = loadExternalDocSources();
   const token = process.env.DOCS_SOURCE_TOKEN || process.env.GITHUB_TOKEN || process.env.GH_TOKEN || '';
   const snapshots = await collectExternalDocSnapshots(sources, token);
+  const releases = buildReleaseCatalog(protocol, components, snapshots);
   const content = {
     schemaVersion: 1,
     generatedAt: new Date().toISOString(),
     sources: Object.fromEntries(snapshots.map((snapshot) => [snapshot.id, snapshot])),
+    releases,
   };
 
   mkdirSync(dirname(CONTENT_PATH), { recursive: true });
   writeFileSync(CONTENT_PATH, `${JSON.stringify(content, null, 2)}\n`);
+  writeFileSync(join(__dirname, 'release-catalog.json'), `${JSON.stringify(releases, null, 2)}\n`);
 
   console.log(`Generated build-time snapshots for ${snapshots.length} external Markdown source${snapshots.length === 1 ? '' : 's'}`);
 }
diff --git a/lib/generate-search-index.js b/lib/generate-search-index.js
index 3c58003..0d1578e 100644
--- a/lib/generate-search-index.js
+++ b/lib/generate-search-index.js
@@ -87,7 +87,7 @@ function stripMarkdown(content) {
 
 function getSection(path) {
   if (path === "/") return "Documentation";
-  if (path === "/changes" || path === "/reference/releases") {
+  if (path === "/changes" || path.startsWith("/changes/") || path === "/reference/releases") {
     return "Changes";
   }
   if (
diff --git a/lib/navigation.js b/lib/navigation.js
index 5a9a353..4c3a974 100644
--- a/lib/navigation.js
+++ b/lib/navigation.js
@@ -1,3 +1,5 @@
+import releaseCatalog from './release-catalog.json' with { type: 'json' };
+
 export const navigation = [
   {
     section: "Guide",
@@ -166,7 +168,12 @@ export const navigation = [
     section: "Changes",
     children: [
       { title: "Changes overview", path: "/changes" },
-      { title: "Lexicon Releases", path: "/reference/releases" },
+      { title: "Protocol changelog", path: "/changes/protocol" },
+      ...releaseCatalog.components.map(component => ({
+        title: component.title,
+        path: component.path,
+        badge: component.label,
+      })),
     ],
   },
 ];
diff --git a/lib/protocol-releases.json b/lib/protocol-releases.json
new file mode 100644
index 0000000..e8946bd
--- /dev/null
+++ b/lib/protocol-releases.json
@@ -0,0 +1,67 @@
+[
+  {
+    "version": "1.4",
+    "date": "2026-08-24",
+    "title": "Features and shared vocabulary",
+    "summary": "Describe subjects such as land areas, ecological zones, or participant cohorts with feature records. Shared vocabulary tags let projects and features reuse the same definitions instead of relying on inconsistent free-text labels.",
+    "changes": [
+      "Introduces org.hypercerts.entity.feature for subjects that are not people or organizations, with descriptions, optional locations, and external identifiers.",
+      "Introduces org.hypercerts.vocab.tag for reusable classification, including broader terms, alternative names, external equivalents, and replacement terms.",
+      "Collections can include features alongside activities and other collections. Existing activities continue to reference locations directly."
+    ],
+    "compatibility": "Additive: existing records remain valid. Applications can add support for the new records as their use cases require.",
+    "sourceVersion": "1.4.0"
+  },
+  {
+    "version": "1.3",
+    "date": "2026-08-13",
+    "title": "Richer descriptions with updated Leaflet formats",
+    "summary": "Updates the bundled Leaflet schemas, giving applications more ways to represent rich descriptions while keeping them aligned with Leaflet's published formats.",
+    "changes": [
+      "Adds Leaflet block types including image galleries, HTML, post lists, and publication blocks, plus theme-color definitions.",
+      "Expands image, iframe, and rich-text options, including image display width, iframe aspect ratio, link hrefs, and highlight colors.",
+      "Linear documents can include the newly supported blocks."
+    ],
+    "compatibility": "Readers of rich descriptions should handle unfamiliar blocks gracefully. Applications that render or validate Leaflet content should review the updated bundled schemas.",
+    "sourceVersion": "1.3.0"
+  },
+  {
+    "version": "1.2",
+    "date": "2026-08-03",
+    "title": "Follow projects and request grouped permissions",
+    "summary": "Adds follows for records such as projects, and reusable permission sets that let applications request access to related record types together.",
+    "changes": [
+      "Introduces app.certified.graph.entityFollow for non-account entities. Its AT-URI reference keeps following the record across updates instead of pinning one content version.",
+      "Adds org.hypercerts.authWrite and app.certified.authWrite permission sets, so an application can request a namespace's listed write permissions through an include scope.",
+      "Account follows remain separate in app.certified.graph.follow."
+    ],
+    "compatibility": "These are additional capabilities. Use entity follows for records and account follows for accounts; review the permission sets when configuring authorization.",
+    "sourceVersion": "1.2.0"
+  },
+  {
+    "version": "1.1",
+    "date": "2026-07-06",
+    "title": "Optional signatures on record contents",
+    "summary": "Lets a signer attest to a record's contents, adding a form of provenance separate from the signature on the publishing AT Protocol repository.",
+    "changes": [
+      "Adds optional signatures to the record schemas, with shared app.certified.signature.defs definitions.",
+      "Supports inline signatures and references to remote app.certified.signature.proof records.",
+      "Record signatures complement the existing wallet-consent proof on EVM identity links."
+    ],
+    "compatibility": "Non-breaking: signatures are optional. Existing records without signatures remain valid.",
+    "sourceVersion": "1.1.0"
+  },
+  {
+    "version": "1.0",
+    "date": "2026-06-17",
+    "title": "First stable Lexicon baseline",
+    "summary": "Establishes the first stable release of the Hypercerts and Certified Lexicon package, its TypeScript types, and generated exports.",
+    "changes": [
+      "Promotes the existing package to 1.0.0. The stability promotion itself does not introduce new schemas or types.",
+      "Also increases the plain-text activity work-scope limit from 100 to 1,000 graphemes, with a 10,000-byte cap.",
+      "Establishes standard semantic versioning for the package: breaking changes advance the major version, compatible additions the minor version, and fixes the patch version."
+    ],
+    "compatibility": "The work-scope limit increase preserves existing valid records. This history begins with the stable 1.0 baseline; earlier pre-release migrations remain in the component changelog.",
+    "sourceVersion": "1.0.0"
+  }
+]
diff --git a/lib/release-components.json b/lib/release-components.json
new file mode 100644
index 0000000..15adf18
--- /dev/null
+++ b/lib/release-components.json
@@ -0,0 +1,48 @@
+[
+  {
+    "id": "lexicons",
+    "title": "Lexicons",
+    "path": "/reference/releases",
+    "sourceId": "hypercerts-lexicon-changelog",
+    "description": "Shared record schemas, types, and permission sets."
+  },
+  {
+    "id": "api",
+    "title": "Hypercerts API",
+    "path": "/changes/api",
+    "description": "The XRPC read API. Its own release history is being prepared."
+  },
+  {
+    "id": "sdk",
+    "title": "Hypercerts SDK",
+    "path": "/changes/sdk",
+    "description": "The new SDK is under development; no package release is available yet."
+  },
+  {
+    "id": "cgs",
+    "title": "Certified Group Service",
+    "path": "/changes/cgs",
+    "sourceId": "cgs-changelog",
+    "description": "Group accounts, permissions, and shared repository management."
+  },
+  {
+    "id": "entryway",
+    "title": "Entryway",
+    "path": "/changes/entryway",
+    "description": "The account entryway is under development; its release history will be linked here."
+  },
+  {
+    "id": "relay",
+    "title": "Hypercerts Relay",
+    "path": "/changes/relay",
+    "sourceId": "relay-changelog",
+    "description": "Network ingestion and relay infrastructure."
+  },
+  {
+    "id": "feed",
+    "title": "Hypercerts Feed Service",
+    "path": "/changes/feed-service",
+    "sourceId": "feed-changelog",
+    "description": "Feed selection and read interfaces."
+  }
+]
diff --git a/lib/releases.js b/lib/releases.js
new file mode 100644
index 0000000..32ba38c
--- /dev/null
+++ b/lib/releases.js
@@ -0,0 +1,62 @@
+const RELEASE_MARKER = /^{% (release-latest|release-summary|release-cards|protocol-history) \/%}$/gm;
+
+/** Build a small shared catalog for navigation and rendered Markdown, without upstream bodies. */
+function buildReleaseCatalog(protocol, components, snapshots) {
+  if (!Array.isArray(protocol) || protocol.length === 0) throw new Error('Protocol release history must not be empty.');
+  const seen = new Set();
+  for (const release of protocol) {
+    if (!/^\d+\.\d+$/.test(release.version) || seen.has(release.version)) throw new Error('Invalid or duplicate protocol release line.');
+    if (!release.sourceVersion.startsWith(`${release.version}.`)) throw new Error('Protocol source version must belong to its release line.');
+    seen.add(release.version);
+  }
+  return {
+    protocol,
+    components: components.map(component => {
+      const source = component.sourceId ? snapshots.find(item => item.id === component.sourceId) : null;
+      if (component.sourceId && !source?.trackRelease) throw new Error(`Missing release-tracked source for ${component.id}.`);
+      const release = source?.release || null;
+      return {
+        ...component,
+        version: release?.version || null,
+        label: release ? `v${release.version}` : 'Under development',
+        releaseUrl: release?.url || null,
+        publishedAt: release?.publishedAt || null,
+        changelogUrl: source ? `https://github.com/${source.repo}/blob/${source.ref}/${source.path}` : null,
+        aligned: release ? release.version.split('.').slice(0, 2).join('.') === protocol[0].version : false,
+      };
+    }),
+  };
+}
+
+function sourceLink(release) {
+  return `https://github.com/hypercerts-org/hypercerts-lexicon/releases/tag/v${release.sourceVersion}`;
+}
+
+function renderReleaseFragment(kind, catalog) {
+  if (!catalog?.protocol?.length || !catalog?.components) throw new Error('Missing release catalog. Run npm run generate:external-docs first.');
+  const latest = catalog.protocol[0];
+  if (kind === 'release-latest') {
+    return `**[Hypercerts Protocol ${latest.version}](/changes): ${latest.title}.** ${latest.summary}`;
+  }
+  if (kind === 'release-summary') {
+    return `## Hypercerts Protocol ${latest.version}\n\n**${latest.title}** · ${latest.date}\n\n${latest.summary}\n\n${latest.changes.map(change => `- ${change}`).join('\n')}\n\n${latest.compatibility}\n\n[Read the protocol changelog](/changes/protocol) · [Lexicons ${latest.sourceVersion} release](${sourceLink(latest)})${latest.blogUrl ? ` · [Read the release article](${latest.blogUrl})` : ''}`;
+  }
+  if (kind === 'release-cards') {
+    const cards = [
+      `{% card-link title="Protocol changelog" href="/changes/protocol" %}\nMajor and minor releases, from 1.0 to ${latest.version}.\n{% /card-link %}`,
+      ...catalog.components.map(component => `{% card-link title="${component.title}" href="${component.path}" badge="${component.label}" %}\n${component.description}\n{% /card-link %}`),
+    ];
+    return `{% card-grid %}\n${cards.join('\n')}\n{% /card-grid %}`;
+  }
+  if (kind === 'protocol-history') {
+    return catalog.protocol.map(release => `## ${release.version}: ${release.title}\n\n${release.date} · Based on [Lexicons ${release.sourceVersion}](${sourceLink(release)})\n\n${release.summary}\n\n${release.changes.map(change => `- ${change}`).join('\n')}\n\n**For existing integrations:** ${release.compatibility}${release.blogUrl ? `\n\n[Read the release article](${release.blogUrl})` : ''}`).join('\n\n');
+  }
+  throw new Error(`Unknown release fragment: ${kind}`);
+}
+
+/** Expand local build-time markers before rendering, indexing, and raw Markdown export. */
+function expandReleaseMarkdown(markdown, catalog) {
+  return markdown.replace(RELEASE_MARKER, (_, kind) => renderReleaseFragment(kind, catalog));
+}
+
+module.exports = { buildReleaseCatalog, expandReleaseMarkdown, renderReleaseFragment };
diff --git a/markdoc/nodes/index.js b/markdoc/nodes/index.js
index 3f0657a..26b8346 100644
--- a/markdoc/nodes/index.js
+++ b/markdoc/nodes/index.js
@@ -3,3 +3,4 @@ export { default as heading } from './heading.markdoc';
 export { default as fence } from './fence.markdoc';
 export { default as image } from './image.markdoc';
 export { default as link } from './link.markdoc';
+export { default as text } from './text.markdoc';
diff --git a/markdoc/nodes/text.markdoc.js b/markdoc/nodes/text.markdoc.js
new file mode 100644
index 0000000..f900d4b
--- /dev/null
+++ b/markdoc/nodes/text.markdoc.js
@@ -0,0 +1,17 @@
+const { nodes, Tag } = require('@markdoc/markdoc');
+
+/** Preserve safe empty HTML anchors used by upstream changelogs without rendering arbitrary HTML. */
+module.exports = {
+  ...nodes.text,
+  transform(node, config) {
+    const text = node.attributes.content;
+    if (!config.variables?.externalDocSource) return text;
+    const parts = [];
+    let offset = 0;
+    for (const match of text.matchAll(/<a id="([A-Za-z][A-Za-z0-9_.:-]*)"><\/a>/g)) {
+      parts.push(text.slice(offset, match.index), new Tag('span', { id: match[1] }, []));
+      offset = match.index + match[0].length;
+    }
+    return parts.length ? [...parts, text.slice(offset)] : text;
+  },
+};
diff --git a/markdoc/tags/card-link.markdoc.js b/markdoc/tags/card-link.markdoc.js
index 0331bad..cca0795 100644
--- a/markdoc/tags/card-link.markdoc.js
+++ b/markdoc/tags/card-link.markdoc.js
@@ -4,5 +4,6 @@ export default {
     title: { type: String, required: true },
     href: { type: String, required: true },
     icon: { type: String },
+    badge: { type: String },
   },
 };
diff --git a/pages/changes/api.md b/pages/changes/api.md
new file mode 100644
index 0000000..b0a1c89
--- /dev/null
+++ b/pages/changes/api.md
@@ -0,0 +1,12 @@
+---
+title: Hypercerts API Releases
+description: Release status of the Hypercerts XRPC API.
+---
+
+# Hypercerts API Releases
+
+**Under development.** The Hypercerts XRPC API does not yet have a published component release or a registered changelog for this documentation site.
+
+The API implementation builds on [HappyView](https://github.com/hypercerts-org/happyview). HappyView's own version is not the version of the Hypercerts API contract. This page will import the API's own changelog when its release source is established.
+
+The Hypercerts API is included in coordinated protocol major/minor releases, with independent component patches. See [Changes](/changes) for the current release line and component status, or [Client Integration](/client-integration) for implementation guidance as it develops.
diff --git a/pages/changes/cgs.md b/pages/changes/cgs.md
new file mode 100644
index 0000000..2a0b54a
--- /dev/null
+++ b/pages/changes/cgs.md
@@ -0,0 +1,5 @@
+---
+title: Certified Group Service Changelog
+description: Release history imported from the Certified Group Service repository.
+externalDoc: cgs-changelog
+---
diff --git a/pages/changes/entryway.md b/pages/changes/entryway.md
new file mode 100644
index 0000000..58ed925
--- /dev/null
+++ b/pages/changes/entryway.md
@@ -0,0 +1,12 @@
+---
+title: Entryway Releases
+description: Release status of the account entryway and its relationship to existing ePDS releases.
+---
+
+# Entryway Releases
+
+**Under development.** The account entryway does not yet have a separately published component release or a registered entryway changelog for this site.
+
+The existing [ePDS changelog](https://github.com/hypercerts-org/ePDS/blob/main/CHANGELOG.md) documents the preceding account infrastructure. Its releases are not labeled as Entryway releases here. The entryway's own changelog will be connected once its release source is established.
+
+Entryway is included in coordinated protocol major/minor releases, with independent component patches. See [Changes](/changes) for the release line and [Account & Identity Setup](/architecture/account-and-identity) for the current account guidance.
diff --git a/pages/changes/feed-service.md b/pages/changes/feed-service.md
new file mode 100644
index 0000000..595da86
--- /dev/null
+++ b/pages/changes/feed-service.md
@@ -0,0 +1,5 @@
+---
+title: Hypercerts Feed Service Changelog
+description: Release history imported from the Hypercerts Feed Service repository.
+externalDoc: feed-changelog
+---
diff --git a/pages/changes/index.md b/pages/changes/index.md
index df16eee..d64dd5b 100644
--- a/pages/changes/index.md
+++ b/pages/changes/index.md
@@ -1,23 +1,32 @@
 ---
 title: Changes
-description: Adopter-facing history for Hypercerts schema, guidance, SDK, API, and service changes.
+description: The current Hypercerts Protocol release, its new capabilities, and the release histories of the components that support it.
 ---
 
 # Changes
 
-This section helps adopters understand what changed, who is affected, and whether an integration requires action.
+This site is the canonical record of Hypercerts Protocol major and minor releases. Each release explains what changed for builders; the component changelogs retain the detailed implementation history.
 
-The current source-backed history covers [Hypercerts Lexicon releases](/reference/releases). Future entries should connect changes in protocol meaning and guidance to the affected Lexicons, SDK, APIs, and services.
+{% release-summary /%}
 
-## Change entry structure
+## Component releases
 
-Each adopter-facing entry should include:
+The protocol stack includes **Lexicons, Hypercerts API, SDK, Certified Group Service, Entryway, Relay, and Feed Service**. These cards and the sidebar show their latest published stable releases, refreshed when this site builds.
 
-- the date and affected contracts or component versions;
-- a concise description of what changed;
-- compatibility impact and who is affected;
-- required migration steps, or an explicit statement that no action is required;
-- links to changed Guide and Reference pages;
-- links to the independent source releases and changelogs.
+Shared major/minor numbering is being adopted. Some components still have earlier version numbers or are under development. The versions below are the actual published versions, not a claim that the entire stack has already been released and tested together on 1.4.
 
-Coordinated protocol packaging is still evolving. Change entries must not imply a universal conformance version or combine independent component releases into one version unless that release relationship has been explicitly established.
+{% release-cards /%}
+
+## How versions work
+
+**Major and minor versions identify the shared protocol release line**, such as 1.4. Included components can advance their patch versions independently within that line. A new coordinated major or minor release brings the components into alignment again.
+
+A compatible addition, such as the new feature and vocabulary-tag Lexicons in 1.4, is a minor release. Fixes advance the affected component's patch version. Breaking changes require a major release and migration guidance; a breaking change to an existing record format also needs a new schema identifier.
+
+The intended integration path is the latest stable patch of each participating component within the same release line, backed by compatibility testing. Published component versions are distinct from the versions currently deployed by a particular hosted service.
+
+## Earlier releases
+
+The [protocol changelog](/changes/protocol) covers **1.0 through 1.4**, reconstructed from the published Lexicon history. Its dates are the corresponding Lexicon release dates; the entries do not imply that every service released simultaneously at those times.
+
+Future protocol releases will summarize changes across the whole stack. Release articles can provide worked examples alongside these entries when published.
diff --git a/pages/changes/protocol.md b/pages/changes/protocol.md
new file mode 100644
index 0000000..1466495
--- /dev/null
+++ b/pages/changes/protocol.md
@@ -0,0 +1,14 @@
+---
+title: Protocol Changelog
+description: Hypercerts Protocol major and minor releases, from the stable 1.0 baseline to the current release.
+---
+
+# Protocol Changelog
+
+This is the canonical history of Hypercerts Protocol major and minor releases. Component patch releases remain in the individual changelogs linked in the sidebar.
+
+The 1.0–1.4 entries are reconstructed from the published Lexicon changelog, which drove these protocol changes. Dates are the corresponding Lexicon publication dates. They do not assert that all components shared these version numbers or shipped together historically.
+
+{% protocol-history /%}
+
+For the latest component releases and the versioning policy, return to [Changes](/changes).
diff --git a/pages/changes/relay.md b/pages/changes/relay.md
new file mode 100644
index 0000000..606fede
--- /dev/null
+++ b/pages/changes/relay.md
@@ -0,0 +1,5 @@
+---
+title: Hypercerts Relay Changelog
+description: Project-owned release history imported from the Hypercerts Relay repository.
+externalDoc: relay-changelog
+---
diff --git a/pages/changes/sdk.md b/pages/changes/sdk.md
new file mode 100644
index 0000000..584ee99
--- /dev/null
+++ b/pages/changes/sdk.md
@@ -0,0 +1,12 @@
+---
+title: Hypercerts SDK Releases
+description: Development status of the new Hypercerts SDK.
+---
+
+# Hypercerts SDK Releases
+
+**Under development.** The new Hypercerts SDK has not been released. There is no current package version or changelog to display yet.
+
+The SDK will participate in coordinated protocol major/minor releases, with independent patch versions. When its repository and release process are available, this page will import that changelog and the release cards will show its published version.
+
+See [Client Integration](/client-integration) for available integration material and [Changes](/changes) for the protocol release history.
diff --git a/pages/index.md b/pages/index.md
index 217fb26..b08d71c 100644
--- a/pages/index.md
+++ b/pages/index.md
@@ -66,12 +66,12 @@ Get a quick explanation of an unfamiliar term.
 
 {% /docs-section %}
 
-{% docs-section title="Changes" href="/changes" icon="changes" description="Follow releases and understand what has changed. The release history currently covers the Lexicon package." %}
+{% docs-section title="Changes" href="/changes" icon="changes" description="Follow the protocol's major and minor releases, then explore the latest releases of each component." %}
 
-{% card-grid columns=1 %}
-{% card-link title="Lexicon releases" href="/reference/releases" %}
-Read the package changelog from the source repository.
-{% /card-link %}
-{% /card-grid %}
+{% release-latest /%}
+
+{% release-cards /%}
+
+Versions show actual published component releases. Shared major/minor numbering is being adopted; components without a release are marked under development.
 
 {% /docs-section %}
diff --git a/pages/reference/index.md b/pages/reference/index.md
index f559c02..a2c2304 100644
--- a/pages/reference/index.md
+++ b/pages/reference/index.md
@@ -31,7 +31,7 @@ The XRPC API and SDK reference will be added from their canonical implementation
 
 ## Source-owned documentation
 
-Four detailed documents are currently imported from their owning repositories during the documentation build:
+Seven documents are currently imported from their owning repositories during the documentation build:
 
 | Source | Owning repository | Local route |
 |---|---|---|
@@ -39,10 +39,13 @@ Four detailed documents are currently imported from their owning repositories du
 | ePDS integration tutorial | `hypercerts-org/ePDS` | [Integrate with ePDS](/tutorials/epds) |
 | Hyperindex documentation | `gainforest/hyperindex` | [Hyperindex](/tools/hyperindex) |
 | Hypercerts Lexicon changelog | `hypercerts-org/hypercerts-lexicon` | [Lexicon releases](/reference/releases) |
+| Certified Group Service changelog | `hypercerts-org/certified-group-service` | [CGS releases](/changes/cgs) |
+| Hypercerts Relay changelog | `hypercerts-org/hypercerts-relay` | [Relay releases](/changes/relay) |
+| Hypercerts Feed Service changelog | `hypercerts-org/hypercerts-feed-service` | [Feed Service releases](/changes/feed-service) |
 
-The build stores the resolved source commit and content hash. These imports currently follow each repository's `main` branch. Release contracts should prefer immutable package versions, tags, or commits where available.
+The build stores a content snapshot and hash, with a source-file update timestamp when available. These imports currently follow each repository's `main` branch. Release contracts should prefer immutable package versions, tags, or commits where available. [Changes](/changes) combines the protocol release history with the published component versions.
 
-Canonical external imports are not yet configured for the SDK, Hypercerts XRPC API, Certified Group Service, Hypercerts Feed Service, labelers, or a versioned generated Lexicon field reference. Their local overview pages should not be read as complete API contracts.
+Detailed API-reference imports are not yet configured for the SDK, Hypercerts XRPC API, Certified Group Service, Hypercerts Feed Service, labelers, or a versioned generated Lexicon field reference. Importing a component changelog does not turn its local overview into a complete API contract.
 
 ## Services and tooling
 
diff --git a/styles/globals.css b/styles/globals.css
index af5a6eb..95abbe2 100644
--- a/styles/globals.css
+++ b/styles/globals.css
@@ -998,6 +998,40 @@ a.sidebar-link-active:hover {
   color: var(--color-text-title);
 }
 
+.sidebar-release-badge {
+  display: block;
+  font-family: var(--font-mono);
+  font-size: 11px;
+  line-height: 1.5;
+  font-weight: 400;
+  color: var(--color-text-secondary);
+  margin-top: 2px;
+}
+
+.release-badge {
+  align-self: flex-start;
+  font-family: var(--font-mono);
+  font-size: 11px;
+  line-height: 1.6;
+  padding: 2px 7px;
+  margin: 4px 0;
+  border-radius: var(--radius-sm);
+  border: 1px solid var(--color-border);
+  background: var(--color-bg-subtle);
+  color: var(--color-text-secondary);
+}
+
+.docs-section-links > p {
+  font-size: 15px;
+  line-height: 1.6;
+}
+
+.docs-section-links > .card-grid + p {
+  margin: var(--space-4) 0 0;
+  font-size: 13px;
+  color: var(--color-text-secondary);
+}
+
 .sidebar-nav-link-row {
   display: flex;
   align-items: center;
diff --git a/test/changelog-rendering.test.js b/test/changelog-rendering.test.js
new file mode 100644
index 0000000..e92dfb3
--- /dev/null
+++ b/test/changelog-rendering.test.js
@@ -0,0 +1,20 @@
+const assert = require('node:assert/strict');
+const test = require('node:test');
+const Markdoc = require('@markdoc/markdoc');
+const text = require('../markdoc/nodes/text.markdoc');
+const { resolveExternalDocHref, resolveExternalDocImageSrc } = require('../lib/external-doc-links');
+
+test('root-level changelog relative links stay within the source repository and ref', () => {
+  const source = { repo: 'hypercerts-org/certified-group-service', ref: 'main', path: 'CHANGELOG.md' };
+  assert.equal(resolveExternalDocHref('../docs/api-reference.md#ownership-transfer', source), 'https://github.com/hypercerts-org/certified-group-service/blob/main/docs/api-reference.md#ownership-transfer');
+  assert.equal(resolveExternalDocImageSrc('../images/example.png', source), 'https://raw.githubusercontent.com/hypercerts-org/certified-group-service/main/images/example.png');
+});
+
+test('explicit changelog anchors render safely and code examples remain literal', () => {
+  const config = { nodes: { text }, variables: { externalDocSource: { repo: 'hypercerts-org/example' } } };
+  const markdown = '- <a id="v0.6.0-ownership"></a> Ownership transfer\n\n`<a id="example"></a>`\n\n<a id="unsafe" onclick="bad()"></a>';
+  const html = Markdoc.renderers.html(Markdoc.transform(Markdoc.parse(markdown), config));
+  assert.match(html, /<span id="v0.6.0-ownership"><\/span>/);
+  assert.doesNotMatch(html, /<a id="unsafe"/);
+  assert.doesNotMatch(html, /<span id="example"/);
+});
diff --git a/test/external-docs-snapshot.test.js b/test/external-docs-snapshot.test.js
index d38fe3a..130bf33 100644
--- a/test/external-docs-snapshot.test.js
+++ b/test/external-docs-snapshot.test.js
@@ -117,3 +117,39 @@ test('registry ordering does not affect the combined fingerprint', () => {
     buildFingerprintDocument([second, first]).combinedFingerprint,
   );
 });
+
+test('published stable release metadata is captured in the build snapshot', async context => {
+  const originalFetch = global.fetch;
+  context.after(() => { global.fetch = originalFetch; });
+  global.fetch = async url => String(url).endsWith('/releases/latest')
+    ? response({ json: { tag_name: 'v1.4.12', published_at: '2026-09-01T00:00:00Z', draft: false, prerelease: false } })
+    : String(url).includes('/commits?') ? response({ json: [] }) : response({ text: '# Changelog' });
+  const snapshot = await collectSourceSnapshot({ ...source, trackRelease: true });
+  assert.equal(snapshot.release.version, '1.4.12');
+  assert.equal(snapshot.release.url, 'https://github.com/hypercerts-org/ePDS/releases/tag/v1.4.12');
+});
+
+test('an accessible repository without a GitHub release is explicitly unreleased', async context => {
+  const originalFetch = global.fetch;
+  context.after(() => { global.fetch = originalFetch; });
+  global.fetch = async url => String(url).endsWith('/releases/latest')
+    ? response({ ok: false, status: 404 })
+    : String(url).includes('/commits?') ? response({ json: [] }) : response({ text: '# Changelog' });
+  assert.equal((await collectSourceSnapshot({ ...source, trackRelease: true })).release, null);
+});
+
+test('failed release requests and unstable tags cannot silently become version badges', async context => {
+  const originalFetch = global.fetch;
+  context.after(() => { global.fetch = originalFetch; });
+  for (const failure of [response({ ok: false, status: 403 }), response({ ok: false, status: 500 }), response({ json: { tag_name: 'v1.5.0-beta.1', prerelease: true } })]) {
+    global.fetch = async url => String(url).endsWith('/releases/latest') ? failure
+      : String(url).includes('/commits?') ? response({ json: [] }) : response({ text: '# Changelog' });
+    await assert.rejects(() => collectSourceSnapshot({ ...source, trackRelease: true }), /Release metadata|stable semantic/);
+  }
+});
+
+test('publishing a release changes the refresh fingerprint even if Markdown is unchanged', () => {
+  const snapshot = { ...source, trackRelease: true, contentHash: sha256('# Changelog'), release: null };
+  const published = { ...snapshot, release: { version: '1.4.1', tag: 'v1.4.1', url: 'https://github.com/hypercerts-org/example/releases/tag/v1.4.1', publishedAt: '2026-09-01T00:00:00Z' } };
+  assert.notEqual(buildFingerprintDocument([snapshot]).combinedFingerprint, buildFingerprintDocument([published]).combinedFingerprint);
+});
diff --git a/test/external-docs.test.js b/test/external-docs.test.js
index a5ec52e..9a3c563 100644
--- a/test/external-docs.test.js
+++ b/test/external-docs.test.js
@@ -182,6 +182,7 @@ test('configures the Lexicon changelog as the releases page external source', ()
     repo: 'hypercerts-org/hypercerts-lexicon',
     ref: 'main',
     path: 'CHANGELOG.md',
+    trackRelease: true,
   });
 
   const pagePath = join(__dirname, '..', 'pages', 'reference', 'releases.md');
diff --git a/test/releases.test.js b/test/releases.test.js
new file mode 100644
index 0000000..582b039
--- /dev/null
+++ b/test/releases.test.js
@@ -0,0 +1,79 @@
+const assert = require('node:assert/strict');
+const test = require('node:test');
+const { buildReleaseCatalog, expandReleaseMarkdown } = require('../lib/releases');
+const { resolvePageDocument } = require('../lib/external-doc-page');
+const { compileExternalDocPage } = require('../lib/external-docs-loader');
+const history = require('../lib/protocol-releases.json');
+const components = require('../lib/release-components.json');
+
+function sources() {
+  return components.filter(component => component.sourceId).map(component => ({
+    id: component.sourceId,
+    repo: `hypercerts-org/${component.id}`,
+    ref: 'main',
+    path: 'CHANGELOG.md',
+    trackRelease: true,
+    release: component.id === 'relay' ? null : {
+      version: component.id === 'lexicons' ? '1.4.12' : '0.6.0',
+      url: 'https://github.com/hypercerts-org/example/releases/tag/v0.6.0',
+      publishedAt: '2026-09-01T00:00:00Z',
+    },
+  }));
+}
+
+test('component versions are independent of the protocol line and missing releases are explicit', () => {
+  const catalog = buildReleaseCatalog(history, components, sources());
+  assert.equal(catalog.protocol[0].version, '1.4');
+  const byId = Object.fromEntries(catalog.components.map(component => [component.id, component]));
+  assert.equal(byId.lexicons.label, 'v1.4.12');
+  assert.equal(byId.lexicons.aligned, true);
+  assert.equal(byId.cgs.label, 'v0.6.0');
+  assert.equal(byId.cgs.aligned, false);
+  for (const id of ['api', 'sdk', 'entryway', 'relay']) {
+    assert.equal(byId[id].version, null);
+    assert.equal(byId[id].label, 'Under development');
+  }
+  assert(byId.relay.changelogUrl);
+  assert.equal(byId.sdk.changelogUrl, null);
+});
+
+test('registered component changelogs must be available and release-tracked', () => {
+  assert.throws(() => buildReleaseCatalog(history, components, []), /Missing release-tracked source/);
+  assert.throws(() => buildReleaseCatalog(history, components, sources().map(source => ({ ...source, trackRelease: false }))), /Missing release-tracked source/);
+});
+
+test('history keeps protocol lines distinct from component patch releases', () => {
+  assert.deepEqual(history.map(release => release.version), ['1.4', '1.3', '1.2', '1.1', '1.0']);
+  assert.throws(() => buildReleaseCatalog([...history, history[0]], components, sources()), /duplicate/);
+  assert.throws(() => buildReleaseCatalog([{ ...history[0], sourceVersion: '1.3.1' }], components, sources()), /source version/);
+});
+
+test('release markers expand for page rendering, search, and raw Markdown through the shared resolver', () => {
+  const catalog = buildReleaseCatalog(history, components, sources());
+  const markdown = '# Releases\n\n{% release-latest /%}\n\n{% release-summary /%}\n\n{% release-cards /%}\n\n{% protocol-history /%}\n';
+  const result = resolvePageDocument({}, markdown, { releases: catalog }).markdown;
+  assert.doesNotMatch(result, /{% (?:release-|protocol-history)/);
+  assert.match(result, /Hypercerts Protocol 1\.4/);
+  assert.match(result, /badge="v1\.4\.12"/);
+  assert.match(result, /badge="v0\.6\.0"/);
+  assert.match(result, /badge="Under development"/);
+  assert.match(result, /## 1\.0: First stable/);
+  assert.doesNotMatch(result, /Read the release article/);
+  assert.equal(expandReleaseMarkdown('# Ordinary page'), '# Ordinary page');
+  assert.throws(() => expandReleaseMarkdown(markdown), /Missing release catalog/);
+});
+
+test('a later component patch updates badges without rewriting protocol history', () => {
+  const before = buildReleaseCatalog(history, components, sources());
+  const updated = sources();
+  updated[0].release.version = '1.4.35';
+  const after = buildReleaseCatalog(history, components, updated);
+  assert.equal(expandReleaseMarkdown('{% protocol-history /%}', before), expandReleaseMarkdown('{% protocol-history /%}', after));
+  assert.notEqual(expandReleaseMarkdown('{% release-cards /%}', before), expandReleaseMarkdown('{% release-cards /%}', after));
+});
+
+test('upstream changelog bodies are not expanded as local release instructions', () => {
+  const content = { sources: { example: { id: 'example', repo: 'hypercerts-org/example', ref: 'main', path: 'CHANGELOG.md', markdown: '# Upstream\n{% release-summary /%}' } } };
+  const output = compileExternalDocPage({ externalDoc: 'example' }, '---\nexternalDoc: example\n---\n', content, 'example.md');
+  assert.match(output, /{% release-summary \/%}/);
+});

From efb22f411884eb8b3ad80be4a98875c6dbe0c193 Mon Sep 17 00:00:00 2001
From: Kristofer Lund <kristofer@fmckl.se>
Date: Wed, 16 Sep 2026 12:02:31 +0200
Subject: [PATCH 6/7] fix: avoid GitHub rate limits during local development

---
 .github/workflows/docs-ci.yml          |   1 +
 docs/remote-markdown.md                |  10 +++
 lib/external-docs-cache.js             |  48 +++++++++++
 lib/external-docs-snapshot.js          |   4 +-
 lib/generate-docs-fingerprint.js       |   4 +-
 lib/generate-external-docs-manifest.js |  30 ++++---
 lib/github-auth.js                     |  24 ++++++
 package.json                           |   5 +-
 test/dev-generation.test.js            | 110 +++++++++++++++++++++++++
 9 files changed, 219 insertions(+), 17 deletions(-)
 create mode 100644 lib/external-docs-cache.js
 create mode 100644 lib/github-auth.js
 create mode 100644 test/dev-generation.test.js

diff --git a/.github/workflows/docs-ci.yml b/.github/workflows/docs-ci.yml
index 4b07e80..9a2f8d1 100644
--- a/.github/workflows/docs-ci.yml
+++ b/.github/workflows/docs-ci.yml
@@ -16,6 +16,7 @@ on:
       - 'lib/generate-search-index.js'
       - 'lib/compare-docs-fingerprint.js'
       - 'lib/releases.js'
+      - 'lib/github-auth.js'
       - 'lib/release-components.json'
       - 'lib/protocol-releases.json'
       - 'lib/navigation.js'
diff --git a/docs/remote-markdown.md b/docs/remote-markdown.md
index 4e135df..22286ce 100644
--- a/docs/remote-markdown.md
+++ b/docs/remote-markdown.md
@@ -94,6 +94,16 @@ Choose `ref` according to the source's publishing policy. A moving branch such a
 
 ## Build behavior
 
+### Local development and GitHub rate limits
+
+`npm run dev` reuses the last successful external-content snapshot when its sources still match `docs-sources.yml`. This makes repeated dev-server starts work offline and avoids spending GitHub API requests just to edit local pages. It still regenerates local release summaries, navigation data, search, and raw Markdown. The console reports the original fetch time; cached versions are not presented as newly fetched.
+
+On a first start, or after changing the source registry, it fetches fresh content. Run `npm run generate` whenever you want to refresh external docs and component versions explicitly. Production `npm run build` and the scheduled refresh always fetch fresh upstream data and still fail on unsuccessful requests.
+
+Authentication is resolved from `DOCS_SOURCE_TOKEN`, then `GITHUB_TOKEN`, then `GH_TOKEN`. Outside CI, the scripts also reuse an existing GitHub CLI login through `gh auth token --hostname github.com`. Run `gh auth login` if needed. Tokens stay in memory and request headers; they are not logged or written into generated content. Without authentication, GitHub's low shared-IP request limit can stop a fresh fetch.
+
+### Static build
+
 `npm run generate:external-docs` fetches every registered file once through the GitHub contents API and writes `lib/external-docs-content.json`. The static build then uses that immutable snapshot for:
 
 - Markdoc page rendering;
diff --git a/lib/external-docs-cache.js b/lib/external-docs-cache.js
new file mode 100644
index 0000000..b68bb67
--- /dev/null
+++ b/lib/external-docs-cache.js
@@ -0,0 +1,48 @@
+const { readFileSync } = require('node:fs');
+const { CONTENT_PATH } = require('./external-docs');
+const { sha256, collectExternalDocSnapshots } = require('./external-docs-snapshot');
+const { getGitHubToken } = require('./github-auth');
+
+/** Local dev can reuse a complete snapshot only when it still matches the source registry. */
+function readCompatibleSnapshot(sources, file = CONTENT_PATH) {
+  try {
+    const content = JSON.parse(readFileSync(file, 'utf8'));
+    if (content.schemaVersion !== 1 || !Number.isFinite(Date.parse(content.generatedAt)) || !content.sources) return null;
+    if (Object.keys(content.sources).length !== sources.length) return null;
+    for (const source of sources) {
+      const snapshot = content.sources[source.id];
+      if (!snapshot) return null;
+      if (['id', 'title', 'repo', 'ref', 'path', 'trackRelease'].some(key => snapshot[key] !== source[key])) return null;
+      if (typeof snapshot.markdown !== 'string' || !snapshot.markdown.trim() || snapshot.contentHash !== sha256(snapshot.markdown)) return null;
+      if (source.trackRelease) {
+        if (!Object.prototype.hasOwnProperty.call(snapshot, 'release')) return null;
+        if (snapshot.release !== null && !/^\d+\.\d+\.\d+$/.test(snapshot.release?.version || '')) return null;
+      }
+    }
+    return content;
+  } catch {
+    return null;
+  }
+}
+
+/** Fresh by default; only local dev explicitly opts into snapshot reuse. */
+async function loadExternalSnapshots(sources, {
+  preferCache = false,
+  file = CONTENT_PATH,
+  collect = collectExternalDocSnapshots,
+  getToken = getGitHubToken,
+} = {}) {
+  const cached = preferCache ? readCompatibleSnapshot(sources, file) : null;
+  if (cached) return {
+    snapshots: sources.map(source => cached.sources[source.id]),
+    generatedAt: cached.generatedAt,
+    reused: true,
+  };
+  return {
+    snapshots: await collect(sources, getToken()),
+    generatedAt: new Date().toISOString(),
+    reused: false,
+  };
+}
+
+module.exports = { readCompatibleSnapshot, loadExternalSnapshots };
diff --git a/lib/external-docs-snapshot.js b/lib/external-docs-snapshot.js
index 2aed197..f3e5517 100644
--- a/lib/external-docs-snapshot.js
+++ b/lib/external-docs-snapshot.js
@@ -60,7 +60,7 @@ async function fetchGitHubResponse(url, token, accept, userAgent) {
   });
   if (!response.ok) {
     const body = await response.text().catch(() => '');
-    throw new Error(`${url} returned ${response.status} ${response.statusText || ''}. Check repo, ref, path, and DOCS_SOURCE_TOKEN. ${body}`.trim());
+    throw new Error(`${url} returned ${response.status} ${response.statusText || ''}. Check repo, ref, path, and DOCS_SOURCE_TOKEN. For local authenticated requests, run gh auth login. ${body}`.trim());
   }
   return response;
 }
@@ -114,7 +114,7 @@ async function fetchLatestRelease(source, token) {
   });
   // No published release is a supported state. The Markdown fetch separately verifies repository access.
   if (response.status === 404) return null;
-  if (!response.ok) throw new Error(`Release metadata for ${source.id} returned ${response.status}. Refusing to label a failed lookup as unreleased.`);
+  if (!response.ok) throw new Error(`Release metadata for ${source.id} returned ${response.status}. Refusing to label a failed lookup as unreleased. Set DOCS_SOURCE_TOKEN or run gh auth login locally.`);
   const release = await response.json();
   const version = /^v?((?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*))$/.exec(release.tag_name || '')?.[1];
   if (!version || release.draft || release.prerelease) throw new Error(`Expected a stable semantic release tag for ${source.id}.`);
diff --git a/lib/generate-docs-fingerprint.js b/lib/generate-docs-fingerprint.js
index a1f5374..a7c20ed 100644
--- a/lib/generate-docs-fingerprint.js
+++ b/lib/generate-docs-fingerprint.js
@@ -1,6 +1,7 @@
 const { mkdirSync, readFileSync, writeFileSync } = require('fs');
 const { dirname, join } = require('path');
 const { loadExternalDocSources } = require('./external-docs');
+const { getGitHubToken } = require('./github-auth');
 const {
   buildFingerprintDocument,
   collectExternalDocSnapshots,
@@ -74,8 +75,7 @@ async function getSnapshots(contentPath) {
   if (contentPath) return loadSnapshotsFromContent(contentPath);
 
   const sources = loadExternalDocSources();
-  const token = process.env.DOCS_SOURCE_TOKEN || process.env.GITHUB_TOKEN || process.env.GH_TOKEN || '';
-  return collectExternalDocSnapshots(sources, token);
+  return collectExternalDocSnapshots(sources, getGitHubToken());
 }
 
 /**
diff --git a/lib/generate-external-docs-manifest.js b/lib/generate-external-docs-manifest.js
index 9deac44..0d8ebf7 100644
--- a/lib/generate-external-docs-manifest.js
+++ b/lib/generate-external-docs-manifest.js
@@ -1,22 +1,22 @@
 const { mkdirSync, writeFileSync } = require('fs');
 const { dirname, join } = require('path');
 const { CONTENT_PATH, loadExternalDocSources } = require('./external-docs');
-const { collectExternalDocSnapshots } = require('./external-docs-snapshot');
 const { buildReleaseCatalog } = require('./releases');
 const protocol = require('./protocol-releases.json');
 const components = require('./release-components.json');
+const { loadExternalSnapshots } = require('./external-docs-cache');
 
 /**
- * Fetch every registered Markdown file once and write the immutable build snapshot.
+ * Fetch fresh build content, or explicitly reuse compatible snapshots for local development.
  */
-async function generateExternalDocs() {
+async function generateExternalDocs({ preferCache = false } = {}) {
   const sources = loadExternalDocSources();
-  const token = process.env.DOCS_SOURCE_TOKEN || process.env.GITHUB_TOKEN || process.env.GH_TOKEN || '';
-  const snapshots = await collectExternalDocSnapshots(sources, token);
+  const { snapshots, generatedAt, reused } = await loadExternalSnapshots(sources, { preferCache });
+  // Always rebuild local release summaries, even when the remote content is cached.
   const releases = buildReleaseCatalog(protocol, components, snapshots);
   const content = {
     schemaVersion: 1,
-    generatedAt: new Date().toISOString(),
+    generatedAt,
     sources: Object.fromEntries(snapshots.map((snapshot) => [snapshot.id, snapshot])),
     releases,
   };
@@ -25,10 +25,18 @@ async function generateExternalDocs() {
   writeFileSync(CONTENT_PATH, `${JSON.stringify(content, null, 2)}\n`);
   writeFileSync(join(__dirname, 'release-catalog.json'), `${JSON.stringify(releases, null, 2)}\n`);
 
-  console.log(`Generated build-time snapshots for ${snapshots.length} external Markdown source${snapshots.length === 1 ? '' : 's'}`);
+  if (reused) {
+    console.log(`Reusing ${snapshots.length} external docs snapshots fetched ${generatedAt}. No GitHub requests. Run npm run generate to refresh upstream content.`);
+  } else {
+    console.log(`Generated build-time snapshots for ${snapshots.length} external Markdown source${snapshots.length === 1 ? '' : 's'}`);
+  }
 }
 
-generateExternalDocs().catch((error) => {
-  console.error(error);
-  process.exit(1);
-});
+if (require.main === module) {
+  generateExternalDocs({ preferCache: process.argv.includes('--prefer-cache') }).catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });
+}
+
+module.exports = { generateExternalDocs };
diff --git a/lib/github-auth.js b/lib/github-auth.js
new file mode 100644
index 0000000..1946e68
--- /dev/null
+++ b/lib/github-auth.js
@@ -0,0 +1,24 @@
+const { execFileSync } = require('node:child_process');
+
+/** Prefer explicit build credentials, then reuse a local gh login without exposing its token. */
+function getGitHubToken(env = process.env, run = execFileSync) {
+  for (const key of ['DOCS_SOURCE_TOKEN', 'GITHUB_TOKEN', 'GH_TOKEN']) {
+    const value = env[key]?.trim();
+    if (value) return value;
+  }
+
+  // CI must use its configured credentials, not an incidental runner keychain.
+  if (env.CI) return '';
+  try {
+    return run('gh', ['auth', 'token', '--hostname', 'github.com'], {
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      env,
+    }).trim();
+  } catch {
+    return '';
+  }
+}
+
+module.exports = { getGitHubToken };
diff --git a/package.json b/package.json
index 853ccb3..c269b41 100644
--- a/package.json
+++ b/package.json
@@ -13,8 +13,9 @@
     "test": "node --test",
     "generate:external-docs": "node lib/generate-external-docs-manifest.js",
     "docs:fingerprint": "node lib/generate-docs-fingerprint.js",
-    "generate": "npm run generate:external-docs && node lib/generate-search-index.js && node lib/generate-last-updated.js && node lib/generate-sitemap.js && node lib/generate-raw-pages.js && npm run docs:fingerprint -- --content lib/external-docs-content.json",
-    "dev": "npm run generate && next dev --webpack",
+    "generate:local": "node lib/generate-search-index.js && node lib/generate-last-updated.js && node lib/generate-sitemap.js && node lib/generate-raw-pages.js && npm run docs:fingerprint -- --content lib/external-docs-content.json",
+    "generate": "npm run generate:external-docs && npm run generate:local",
+    "dev": "node lib/generate-external-docs-manifest.js --prefer-cache && npm run generate:local && next dev --webpack",
     "build": "npm run generate && next build --webpack",
     "start": "next start"
   },
diff --git a/test/dev-generation.test.js b/test/dev-generation.test.js
new file mode 100644
index 0000000..e778d63
--- /dev/null
+++ b/test/dev-generation.test.js
@@ -0,0 +1,110 @@
+const assert = require('node:assert/strict');
+const test = require('node:test');
+const { mkdtempSync, writeFileSync, rmSync } = require('node:fs');
+const { tmpdir } = require('node:os');
+const { join } = require('node:path');
+const { getGitHubToken } = require('../lib/github-auth');
+const { sha256 } = require('../lib/external-docs-snapshot');
+const { readCompatibleSnapshot, loadExternalSnapshots } = require('../lib/external-docs-cache');
+
+const source = { id: 'test', title: 'Test', repo: 'hypercerts-org/example', ref: 'main', path: 'CHANGELOG.md', trackRelease: true };
+const snapshot = { ...source, markdown: '# Changelog', contentHash: sha256('# Changelog'), release: null };
+const cached = { schemaVersion: 1, generatedAt: '2026-09-01T00:00:00Z', sources: { test: snapshot } };
+function cacheFile(context, content = cached) {
+  const directory = mkdtempSync(join(tmpdir(), 'docs-dev-cache-'));
+  context.after(() => rmSync(directory, { recursive: true, force: true }));
+  const file = join(directory, 'snapshot.json');
+  writeFileSync(file, JSON.stringify(content));
+  return file;
+}
+
+test('explicit credentials take precedence without invoking gh', () => {
+  const noCli = () => { throw new Error('gh must not be invoked'); };
+  assert.equal(getGitHubToken({ DOCS_SOURCE_TOKEN: ' docs ', GITHUB_TOKEN: 'github', GH_TOKEN: 'gh' }, noCli), 'docs');
+  assert.equal(getGitHubToken({ DOCS_SOURCE_TOKEN: ' ', GITHUB_TOKEN: 'github', GH_TOKEN: 'gh' }, noCli), 'github');
+  assert.equal(getGitHubToken({ GH_TOKEN: 'gh' }, noCli), 'gh');
+});
+
+test('local fetches can reuse gh credentials with stdout captured and stderr suppressed', () => {
+  let invoked = false;
+  const value = getGitHubToken({}, (command, args, options) => {
+    invoked = true;
+    assert.equal(command, 'gh');
+    assert.deepEqual(args, ['auth', 'token', '--hostname', 'github.com']);
+    assert.deepEqual(options.stdio, ['ignore', 'pipe', 'ignore']);
+    assert.equal(options.timeout, 5000);
+    return 'local-test-token\n';
+  });
+  assert(invoked);
+  assert.equal(value, 'local-test-token');
+});
+
+test('CI does not consult gh and a missing local CLI is handled', () => {
+  let invoked = false;
+  assert.equal(getGitHubToken({ CI: 'true' }, () => { invoked = true; }), '');
+  assert.equal(invoked, false);
+  assert.equal(getGitHubToken({}, () => { throw new Error('no gh'); }), '');
+});
+
+test('development startup reuses a matching snapshot without any auth or network lookup', async context => {
+  const file = cacheFile(context);
+  const forbidden = () => { assert.fail('No network or credential lookup on cache hit'); };
+  const result = await loadExternalSnapshots([source], { preferCache: true, file, collect: forbidden, getToken: forbidden });
+  assert.equal(result.reused, true);
+  assert.equal(result.generatedAt, cached.generatedAt);
+  assert.deepEqual(result.snapshots, [snapshot]);
+});
+
+test('production and explicit refresh fetch fresh content even when a cache exists', async context => {
+  const file = cacheFile(context);
+  let requests = 0;
+  const result = await loadExternalSnapshots([source], {
+    file,
+    getToken: () => 'test-token',
+    collect: async (sources, token) => {
+      requests++;
+      assert.equal(token, 'test-token');
+      assert.deepEqual(sources, [source]);
+      return [{ ...snapshot, markdown: '# Fresh content' }];
+    },
+  });
+  assert.equal(requests, 1);
+  assert.equal(result.reused, false);
+  assert.equal(result.snapshots[0].markdown, '# Fresh content');
+});
+
+test('cache invalidates when registry identity or release tracking changes', context => {
+  const file = cacheFile(context);
+  for (const change of [{ ref: 'v2' }, { path: 'docs/CHANGELOG.md' }, { repo: 'hypercerts-org/other' }, { title: 'Other' }, { trackRelease: false }]) {
+    assert.equal(readCompatibleSnapshot([{ ...source, ...change }], file), null);
+  }
+  assert.equal(readCompatibleSnapshot([], file), null);
+});
+
+test('incomplete, corrupted, or pre-release-metadata snapshots are not reused', context => {
+  for (const content of [
+    { ...cached, sources: {} },
+    { ...cached, sources: { test: { ...snapshot, markdown: '# Changed' } } },
+    { ...cached, sources: { test: { ...snapshot, release: undefined } } },
+    { ...cached, sources: { test: { ...snapshot, release: { version: '1.0.0-beta' } } } },
+    { ...cached, generatedAt: 'invalid' },
+  ]) {
+    assert.equal(readCompatibleSnapshot([source], cacheFile(context, content)), null);
+  }
+  const file = cacheFile(context);
+  writeFileSync(file, '{incomplete');
+  assert.equal(readCompatibleSnapshot([source], file), null);
+});
+
+test('a cold dev start fetches, and a failed fresh fetch never silently falls back', async context => {
+  const file = cacheFile(context, {});
+  let requested = false;
+  const result = await loadExternalSnapshots([source], { preferCache: true, file, getToken: () => '', collect: async () => { requested = true; return [snapshot]; } });
+  assert(requested);
+  assert.equal(result.reused, false);
+  await assert.rejects(() => loadExternalSnapshots([source], {
+    file: cacheFile(context),
+    getToken: () => '',
+    collect: async () => { throw new Error('rate limited'); },
+  }), /rate limited/);
+});

From c671cc845a16c12d389ffd3f4ffb671f6c763c08 Mon Sep 17 00:00:00 2001
From: Kristofer Lund <kristofer@fmckl.se>
Date: Wed, 16 Sep 2026 12:16:27 +0200
Subject: [PATCH 7/7] docs: simplify protocol release presentation

---
 AGENTS.md                        |  6 ++++++
 docs/information-architecture.md |  5 +++--
 docs/remote-markdown.md          |  8 ++++----
 lib/external-docs-loader.js      |  2 +-
 lib/navigation.js                |  2 +-
 lib/protocol-releases.json       |  1 +
 lib/releases.js                  | 10 +++++-----
 pages/changes/index.md           | 14 +-------------
 pages/changes/protocol.md        | 12 +++---------
 pages/index.md                   |  4 ----
 styles/globals.css               | 11 -----------
 test/releases.test.js            | 10 ++++++++--
 12 files changed, 33 insertions(+), 52 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index fc5058d..3e069a4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,5 +1,11 @@
 # Agent Instructions
 
+## Documentation writing
+
+- Regular documentation and inline code comments describe the current state: what a concept or component is, how it works, and how to use it.
+- Keep historical decisions, previous approaches, and the reasons for replacing them in changelogs and blog posts. Do not add a backstory to a current-state explanation.
+- Keep overview pages concise. Use names, version badges, and short descriptions rather than commentary about how the documentation was assembled.
+
 ## Git Workflow — Branch + PR (MANDATORY)
 
 **NEVER commit directly to `main`.** All work goes through feature branches and pull requests.
diff --git a/docs/information-architecture.md b/docs/information-architecture.md
index 18ff96c..38c33da 100644
--- a/docs/information-architecture.md
+++ b/docs/information-architecture.md
@@ -7,6 +7,7 @@ This is the working migration map for the protocol-first documentation restructu
 - The documentation has four primary sections: Guide, Client Integration, Reference, and Changes.
 - Together, the Guide, Lexicons, API and SDK contracts, reference implementation behavior, and change history describe the protocol. There is no separate ratified formal specification.
 - Guide pages explain meaning and shared usage. Reference pages provide exact source-backed contracts.
+- Regular documentation and inline code comments describe the current state. Historical choices, changes in direction, and their reasoning belong in changelogs and blog posts.
 - Integration pages publish tested paths, not inferred or aspirational APIs.
 - Existing public routes remain stable during the first pass unless their content has been explicitly retired.
 - A proposal in the third editor's draft is not a protocol requirement unless it is independently ratified and reflected in authoritative sources.
@@ -34,9 +35,9 @@ The public name and route for change history are **Changes** and `/changes`. Red
 
 The documentation repository is the canonical source for protocol major/minor releases. The participating stack is Lexicons, Hypercerts API, SDK, Certified Group Service, Entryway, Relay, and Feed Service. Major/minor versions are coordinated; component patches advance independently. The intended shared-version compatibility promise must be supported by testing, not inferred from matching labels.
 
-The initial protocol history is reconstructed from Lexicon 1.0 through 1.4. This describes the changes that drove those release lines, not a retroactive assertion that all services shipped simultaneously or used those numbers. Component cards and sidebar badges show their actual published versions. Numeric alignment, release sources for the API and entryway, and the new SDK's first release remain implementation work in the owning projects.
+Protocol release entries cite their source Lexicon releases. Component cards and sidebar badges show published versions or **Under development**. Release numbering and source registration are maintained in the owning projects; the documentation does not substitute a protocol version for an unpublished component version.
 
-The Changes overview and docs landing page share the latest protocol summary and component catalog. Full protocol history lives at `/changes/protocol`; component changelogs are imported from owning repositories at build time. Blog links are added only when a real release article exists. See [the release-maintenance workflow](remote-markdown.md#protocol-releases-and-component-versions).
+The docs landing page and Changes overview use the same cards for Hypercerts Protocol and the components: name, version or development status, and a short description. The protocol card uses one sentence about the current release. The landing page has no additional release explanation above or below the cards. The Changes overview adds the current release details and versioning policy. Full protocol history lives at `/changes/protocol`, headed with the current Hypercerts Protocol version; each entry links to its source Lexicon release. Component changelogs are imported from owning repositories at build time. Blog links are added only when a real release article exists. See [the release-maintenance workflow](remote-markdown.md#protocol-releases-and-component-versions).
 
 ## First-pass migration
 
diff --git a/docs/remote-markdown.md b/docs/remote-markdown.md
index 22286ce..899f4a3 100644
--- a/docs/remote-markdown.md
+++ b/docs/remote-markdown.md
@@ -116,15 +116,15 @@ External Markdown is parsed with the same Markdoc configuration as local pages.
 
 ## Protocol releases and component versions
 
-`lib/protocol-releases.json` is the reviewed, canonical protocol major/minor history, newest first. The initial 1.0–1.4 entries are reconstructed from Lexicon releases; dates are the corresponding package publication dates. A component release does not automatically announce a new protocol release. Edit this file to publish the next coordinated release summary, compatibility guidance, and source version. An optional `blogUrl` adds a release-article link when an article is actually published.
+`lib/protocol-releases.json` is the reviewed, canonical protocol major/minor history, newest first. Each entry records its source Lexicon version and publication date. A component release does not automatically announce a new protocol release. Edit this file to publish the next coordinated release summary, compatibility guidance, and source version. Use `cardSummary` for a one-sentence description on release cards. An optional `blogUrl` adds a release-article link when an article is actually published.
 
 `lib/release-components.json` names the seven participating components and their local changelog routes. A `sourceId` connects a component to a release-tracked source in `docs-sources.yml`. Components without a published release display **Under development**; the new SDK has no source repository attached yet. Entryway is separate from the preceding ePDS product, and HappyView's version is not substituted for the Hypercerts API version.
 
 During generation, `lib/release-catalog.json` holds the compact version/status data used by the sidebar. The same catalog is saved inside the external content snapshot. Local pages use these standalone build-time markers:
 
-- `release-latest`: short current-release summary for the landing page.
-- `release-summary`: current release with highlights and source links.
-- `release-cards`: protocol-history link and all component version/status cards.
+- `protocol-title`: Hypercerts Protocol heading with the current version.
+- `release-summary`: current release with highlights for the Changes overview.
+- `release-cards`: Hypercerts Protocol and component version/status cards.
 - `protocol-history`: the full reviewed major/minor history.
 
 Write a marker as a self-closing Markdoc-style line, such as `{% release-summary /%}`. The shared page resolver expands it before Markdoc rendering, search indexing, or raw Markdown export, so those surfaces contain the same actual release information. No release lookup happens in the browser.
diff --git a/lib/external-docs-loader.js b/lib/external-docs-loader.js
index a512313..0e22e0e 100644
--- a/lib/external-docs-loader.js
+++ b/lib/external-docs-loader.js
@@ -36,7 +36,7 @@ function compileExternalDocPage(frontmatter, source, content, label) {
 function externalDocsLoader(source) {
   const frontmatter = parseMarkdownFrontmatter(source, this.resourcePath);
   if (!Object.prototype.hasOwnProperty.call(frontmatter, 'externalDoc')) {
-    if (/^{% (release-latest|release-summary|release-cards|protocol-history) \/%}$/m.test(source)) {
+    if (/^{% (protocol-title|release-summary|release-cards|protocol-history) \/%}$/m.test(source)) {
       this.addDependency(CONTENT_PATH);
       return resolvePageDocument(frontmatter, source, loadExternalDocsContent(), this.resourcePath).markdown;
     }
diff --git a/lib/navigation.js b/lib/navigation.js
index 4c3a974..c4ecf67 100644
--- a/lib/navigation.js
+++ b/lib/navigation.js
@@ -168,7 +168,7 @@ export const navigation = [
     section: "Changes",
     children: [
       { title: "Changes overview", path: "/changes" },
-      { title: "Protocol changelog", path: "/changes/protocol" },
+      { title: "Hypercerts Protocol", path: "/changes/protocol", badge: `v${releaseCatalog.protocol[0].version}` },
       ...releaseCatalog.components.map(component => ({
         title: component.title,
         path: component.path,
diff --git a/lib/protocol-releases.json b/lib/protocol-releases.json
index e8946bd..22615a9 100644
--- a/lib/protocol-releases.json
+++ b/lib/protocol-releases.json
@@ -3,6 +3,7 @@
     "version": "1.4",
     "date": "2026-08-24",
     "title": "Features and shared vocabulary",
+    "cardSummary": "Describe land areas, ecological zones, and other subjects with feature records and shared vocabulary tags.",
     "summary": "Describe subjects such as land areas, ecological zones, or participant cohorts with feature records. Shared vocabulary tags let projects and features reuse the same definitions instead of relying on inconsistent free-text labels.",
     "changes": [
       "Introduces org.hypercerts.entity.feature for subjects that are not people or organizations, with descriptions, optional locations, and external identifiers.",
diff --git a/lib/releases.js b/lib/releases.js
index 32ba38c..049db1a 100644
--- a/lib/releases.js
+++ b/lib/releases.js
@@ -1,4 +1,4 @@
-const RELEASE_MARKER = /^{% (release-latest|release-summary|release-cards|protocol-history) \/%}$/gm;
+const RELEASE_MARKER = /^{% (protocol-title|release-summary|release-cards|protocol-history) \/%}$/gm;
 
 /** Build a small shared catalog for navigation and rendered Markdown, without upstream bodies. */
 function buildReleaseCatalog(protocol, components, snapshots) {
@@ -35,15 +35,15 @@ function sourceLink(release) {
 function renderReleaseFragment(kind, catalog) {
   if (!catalog?.protocol?.length || !catalog?.components) throw new Error('Missing release catalog. Run npm run generate:external-docs first.');
   const latest = catalog.protocol[0];
-  if (kind === 'release-latest') {
-    return `**[Hypercerts Protocol ${latest.version}](/changes): ${latest.title}.** ${latest.summary}`;
+  if (kind === 'protocol-title') {
+    return `# Hypercerts Protocol ${latest.version}`;
   }
   if (kind === 'release-summary') {
-    return `## Hypercerts Protocol ${latest.version}\n\n**${latest.title}** · ${latest.date}\n\n${latest.summary}\n\n${latest.changes.map(change => `- ${change}`).join('\n')}\n\n${latest.compatibility}\n\n[Read the protocol changelog](/changes/protocol) · [Lexicons ${latest.sourceVersion} release](${sourceLink(latest)})${latest.blogUrl ? ` · [Read the release article](${latest.blogUrl})` : ''}`;
+    return `## Hypercerts Protocol ${latest.version}\n\n**${latest.title}** · ${latest.date}\n\n${latest.summary}\n\n${latest.changes.map(change => `- ${change}`).join('\n')}\n\n${latest.compatibility}${latest.blogUrl ? `\n\n[Read the release article](${latest.blogUrl})` : ''}`;
   }
   if (kind === 'release-cards') {
     const cards = [
-      `{% card-link title="Protocol changelog" href="/changes/protocol" %}\nMajor and minor releases, from 1.0 to ${latest.version}.\n{% /card-link %}`,
+      `{% card-link title="Hypercerts Protocol" href="/changes/protocol" badge="v${latest.version}" %}\n${latest.cardSummary || latest.summary}\n{% /card-link %}`,
       ...catalog.components.map(component => `{% card-link title="${component.title}" href="${component.path}" badge="${component.label}" %}\n${component.description}\n{% /card-link %}`),
     ];
     return `{% card-grid %}\n${cards.join('\n')}\n{% /card-grid %}`;
diff --git a/pages/changes/index.md b/pages/changes/index.md
index d64dd5b..4af16e5 100644
--- a/pages/changes/index.md
+++ b/pages/changes/index.md
@@ -5,16 +5,10 @@ description: The current Hypercerts Protocol release, its new capabilities, and
 
 # Changes
 
-This site is the canonical record of Hypercerts Protocol major and minor releases. Each release explains what changed for builders; the component changelogs retain the detailed implementation history.
-
 {% release-summary /%}
 
 ## Component releases
 
-The protocol stack includes **Lexicons, Hypercerts API, SDK, Certified Group Service, Entryway, Relay, and Feed Service**. These cards and the sidebar show their latest published stable releases, refreshed when this site builds.
-
-Shared major/minor numbering is being adopted. Some components still have earlier version numbers or are under development. The versions below are the actual published versions, not a claim that the entire stack has already been released and tested together on 1.4.
-
 {% release-cards /%}
 
 ## How versions work
@@ -23,10 +17,4 @@ Shared major/minor numbering is being adopted. Some components still have earlie
 
 A compatible addition, such as the new feature and vocabulary-tag Lexicons in 1.4, is a minor release. Fixes advance the affected component's patch version. Breaking changes require a major release and migration guidance; a breaking change to an existing record format also needs a new schema identifier.
 
-The intended integration path is the latest stable patch of each participating component within the same release line, backed by compatibility testing. Published component versions are distinct from the versions currently deployed by a particular hosted service.
-
-## Earlier releases
-
-The [protocol changelog](/changes/protocol) covers **1.0 through 1.4**, reconstructed from the published Lexicon history. Its dates are the corresponding Lexicon release dates; the entries do not imply that every service released simultaneously at those times.
-
-Future protocol releases will summarize changes across the whole stack. Release articles can provide worked examples alongside these entries when published.
+Within a shared release line, use the latest stable patch of each component. A hosted service may run a different version from its latest published release.
diff --git a/pages/changes/protocol.md b/pages/changes/protocol.md
index 1466495..d0b28a2 100644
--- a/pages/changes/protocol.md
+++ b/pages/changes/protocol.md
@@ -1,14 +1,8 @@
 ---
-title: Protocol Changelog
-description: Hypercerts Protocol major and minor releases, from the stable 1.0 baseline to the current release.
+title: Hypercerts Protocol
+description: Releases and changes to the Hypercerts Protocol.
 ---
 
-# Protocol Changelog
-
-This is the canonical history of Hypercerts Protocol major and minor releases. Component patch releases remain in the individual changelogs linked in the sidebar.
-
-The 1.0–1.4 entries are reconstructed from the published Lexicon changelog, which drove these protocol changes. Dates are the corresponding Lexicon publication dates. They do not assert that all components shared these version numbers or shipped together historically.
+{% protocol-title /%}
 
 {% protocol-history /%}
-
-For the latest component releases and the versioning policy, return to [Changes](/changes).
diff --git a/pages/index.md b/pages/index.md
index b08d71c..c6671e1 100644
--- a/pages/index.md
+++ b/pages/index.md
@@ -68,10 +68,6 @@ Get a quick explanation of an unfamiliar term.
 
 {% docs-section title="Changes" href="/changes" icon="changes" description="Follow the protocol's major and minor releases, then explore the latest releases of each component." %}
 
-{% release-latest /%}
-
 {% release-cards /%}
 
-Versions show actual published component releases. Shared major/minor numbering is being adopted; components without a release are marked under development.
-
 {% /docs-section %}
diff --git a/styles/globals.css b/styles/globals.css
index 95abbe2..14aaa18 100644
--- a/styles/globals.css
+++ b/styles/globals.css
@@ -1021,17 +1021,6 @@ a.sidebar-link-active:hover {
   color: var(--color-text-secondary);
 }
 
-.docs-section-links > p {
-  font-size: 15px;
-  line-height: 1.6;
-}
-
-.docs-section-links > .card-grid + p {
-  margin: var(--space-4) 0 0;
-  font-size: 13px;
-  color: var(--color-text-secondary);
-}
-
 .sidebar-nav-link-row {
   display: flex;
   align-items: center;
diff --git a/test/releases.test.js b/test/releases.test.js
index 582b039..969df1e 100644
--- a/test/releases.test.js
+++ b/test/releases.test.js
@@ -50,17 +50,23 @@ test('history keeps protocol lines distinct from component patch releases', () =
 
 test('release markers expand for page rendering, search, and raw Markdown through the shared resolver', () => {
   const catalog = buildReleaseCatalog(history, components, sources());
-  const markdown = '# Releases\n\n{% release-latest /%}\n\n{% release-summary /%}\n\n{% release-cards /%}\n\n{% protocol-history /%}\n';
+  const markdown = '{% protocol-title /%}\n\n{% release-summary /%}\n\n{% release-cards /%}\n\n{% protocol-history /%}\n';
   const result = resolvePageDocument({}, markdown, { releases: catalog }).markdown;
-  assert.doesNotMatch(result, /{% (?:release-|protocol-history)/);
+  assert.doesNotMatch(result, /{% (?:release-|protocol-)/);
   assert.match(result, /Hypercerts Protocol 1\.4/);
   assert.match(result, /badge="v1\.4\.12"/);
+  assert.match(result, /title="Hypercerts Protocol" href="\/changes\/protocol" badge="v1\.4"/);
+  assert(result.includes(history[0].cardSummary));
   assert.match(result, /badge="v0\.6\.0"/);
   assert.match(result, /badge="Under development"/);
   assert.match(result, /## 1\.0: First stable/);
   assert.doesNotMatch(result, /Read the release article/);
   assert.equal(expandReleaseMarkdown('# Ordinary page'), '# Ordinary page');
   assert.throws(() => expandReleaseMarkdown(markdown), /Missing release catalog/);
+  const summary = expandReleaseMarkdown('{% release-summary /%}', catalog);
+  assert.doesNotMatch(summary, /Read the protocol changelog|Lexicons 1\.4\.0 release/);
+  const fullHistory = expandReleaseMarkdown('{% protocol-history /%}', catalog);
+  assert.match(fullHistory, /Based on \[Lexicons 1\.4\.0\]/);
 });
 
 test('a later component patch updates badges without rewriting protocol history', () => {