docs: synchronize API reference with manifest and enforce freshness

CONTRIBUTING.md

@@ -13,6 +13,16 @@ pnpm build
 
 `pnpm test:unit` runs the discovered tests under `api/tests/unit`; unit tests use local fixtures and fake process/network adapters, and do not seed a database or contact HappyView. `pnpm check` also checks generated-source freshness, JavaScript and Lua lint, types, and endpoint tests. `pnpm build` emits Lua handlers declared by the root and module manifests. Shared Lua files are bundled into capability handlers rather than installed independently.
 
+## API reference snapshots
+
+When a change affects registered query Lexicons or their schemas, refresh the committed explorer artifacts from the current API manifest:
+
+```sh
+pnpm docs:sync
+```
+
+This updates `docs/sources/index.json`, the committed Lexicon snapshots, `docs/openapi.json`, and `docs/coverage.json`. It uses the repository-pinned `@hypercerts-org/lexicon` dependency and makes no HappyView requests. Coverage reports manifest inclusion only; it does not validate runtime behavior or deployment. See [docs/README.md](docs/README.md) for the source and snapshot policy.
+
 ## HTTP runtime tests
 
 `pnpm test:http` runs the suites in `api/tests/http` against the activity, badge-definition, badge-query, EVM-link, acknowledgement, collection, context-measurement, context attachment and evaluation, contributor-information, funding, location, profile, organization, feature, work-scope-tag, rights, vocabulary-tag, graph, and contribution query XRPC endpoints installed from this checkout. These tests exercise real HTTP behavior against PostgreSQL, not only Lua handlers with a fake database.
@@ -56,4 +66,6 @@ For the pinned HappyView release, ordinary Lua `error()` exceptions return HTTP
 
 ## Operations with external effects
 
-`pnpm install:api` sends admin requests to a HappyView instance and uploads declared assets. By default, conflicting declared assets stop the install before asset writes; `pnpm install:api --override` explicitly replaces only those conflicts. Override does not bypass source/dependency validation, authentication, or profile resolver-setting requirements. If a write request errors, the installer checks the installed asset and treats it as complete only if it matches the bundle. Writes are not rolled back if a later asset fails. Run the installer only for an explicitly approved target with an approved token. Review the target and release notes before installing a released bundle; see [api/README.md](api/README.md).
+For pull requests that change the installable API bundle or operator-visible behavior, add a release note following the [Changesets guidance](.changeset/README.md). Documentation-only or endpoint-explorer-only changes do not need a Changeset.
+
+`pnpm install:api` sends admin requests to a HappyView instance and uploads declared assets. By default, conflicting declared assets stop the install before asset writes; `pnpm install:api --override` explicitly replaces only those conflicts. Override does not bypass source/dependency validation, authentication, or profile resolver-setting requirements. If a write request errors, the installer checks the installed asset and treats it as complete only if it matches the bundle. Writes are not rolled back if a later asset fails. Run the installer only for an explicitly approved target with an approved token. Review the target and release notes before installing a released bundle; see [api/README.md](api/README.md) for release installation and `HYPERCERTS_HANDLE_RESOLVER_URL` setup, permission requirements, and retained-setting behavior.

README.md

@@ -1,23 +1,8 @@
 # Hypercerts API workspace
 
-This repository combines the shared HappyView installer, pinned Lexicon dependencies, reusable Lua projections, fixtures, offline checks, and independently owned capability modules. This composed checkout includes public query modules for actor profiles and organizations, activity, badge definitions and queries, collections, context measurements, attachments and evaluations, actor and entity follows, recent follows, funding receipts, Certified EVM links, locations, features, work-scope tags, contribution records, contributor information, vocabulary tags, and acknowledgements. The `org.hypercerts.vocab.getVocabTag` and `org.hypercerts.vocab.listVocabTags` handlers are bundled and registered through `api/modules/vocab/manifest.json`.
+This repository combines the shared HappyView installer, pinned Lexicon dependencies, reusable Lua projections, fixtures, offline checks, and independently owned capability modules. `api/manifest.json` is authoritative for the modules included in this checkout. The endpoint explorer and its generated OpenAPI and coverage artifacts derive their operations from the query and procedure Lexicons registered by those modules; referenced schemas come from local API Lexicons and the pinned `@hypercerts-org/lexicon` package.
 
-This checkout is one of the additive local sibling branches used to compose the API:
-
-Included query endpoints:
-
-- Rights: `org.hypercerts.claim.getRights`, `org.hypercerts.claim.listRights`
-
-- Badge definitions: `app.certified.badge.getBadgeDefinition`, `app.certified.badge.listBadgeDefinitions`
-- Badge queries: `app.certified.badge.searchBadgeDefinitions`, `app.certified.badge.getBadgeAward`, `app.certified.badge.listBadgeAwards`, `app.certified.badge.getBadgeResponse`, `app.certified.badge.listBadgeResponses`
-- Certified EVM links: `app.certified.link.getEvmLink`, `app.certified.link.listEvmLinks`
-- Funding receipts: `org.hypercerts.funding.getReceipt`, `org.hypercerts.funding.listReceipts`
-- Acknowledgements: `org.hypercerts.context.getAcknowledgement`, `org.hypercerts.context.listAcknowledgements`
-- Contributions: `org.hypercerts.claim.getContribution`, `org.hypercerts.claim.listContributions`
-- Contributor information: `org.hypercerts.claim.getContributorInformation`, `org.hypercerts.claim.listContributorInformation`
-- Vocabulary tags: `org.hypercerts.vocab.getVocabTag`, `org.hypercerts.vocab.listVocabTags`
-
-`api/manifest.json` is authoritative for the modules and validation Lexicons included in this checkout. The `docs/` workspace contains the endpoint explorer and full schema snapshots.
+The explorer runs from committed Lexicon snapshots and does not require an API checkout or HappyView service. See [docs/README.md](docs/README.md) for local use and the `pnpm docs:sync` command. The generated [coverage report](docs/coverage.json) lists the exact manifest-registered operation IDs and distinguishes source inclusion from runtime or deployment validation.
 
 ## Checks
 
@@ -27,7 +12,7 @@ pnpm check
 pnpm build
 ```
 
-`pnpm check` validates generated handlers, lint, types, and unit tests. `pnpm build` refreshes declared Lua handler bundles. These checks do not deploy or contact a HappyView instance. `pnpm install:api` sends admin requests and requires an explicitly approved target and token. See [CONTRIBUTING.md](CONTRIBUTING.md) for local development and HTTP test guidance, and [api/README.md](api/README.md) for API bundle, badge-query, and release installation details.
+`pnpm check` validates generated handlers, lint, types, API unit tests, and endpoint-explorer tests, including read-only freshness checks for the committed docs artifacts. `pnpm build` refreshes declared Lua handler bundles. These checks do not deploy or contact a HappyView instance. `pnpm install:api` sends admin requests and requires an explicitly approved target and token. See [CONTRIBUTING.md](CONTRIBUTING.md) for local development, HTTP test guidance, and release-note requirements, and [api/README.md](api/README.md) for bundle installation and operator guidance.
 
 ## Installed HTTP endpoint inventory
 

api/README.md

@@ -1,6 +1,6 @@
 # HappyView API toolkit and query modules
 
-This package owns the shared API installer and build tooling, pinned upstream Lexicons, common view definitions, reusable Lua projections, offline fixture/test utilities, and the EVM-link, feature, contribution, rights, badge-query, vocabulary-tag, and acknowledgement modules. The `modules/shared/manifest.json` contains record schemas and shared query/view Lexicons; it contains no Lua endpoint scripts. A foundation-only install does not implement those queries. Capability modules listed in the root manifest register their endpoint Lexicons and Lua handlers separately; the `badge-queries` module installs five public badge query Lexicons and their Lua handlers.
+This package owns the shared API installer and build tooling, pinned upstream Lexicons, common view definitions, reusable Lua projections, offline fixture/test utilities, and independently registered query modules. The root `api/manifest.json` selects the modules included in this checkout; each module manifest declares its assets and dependencies. The `modules/shared/manifest.json` contains record schemas and shared query/view Lexicons; it contains no Lua endpoint scripts. A foundation-only install does not implement those queries. The exact explorer operation inventory is generated in [the docs coverage report](../docs/coverage.json); its inclusion labels describe manifest registration, not runtime or deployment validation.
 
 ## EVM-link queries
 
@@ -140,6 +140,13 @@ HAPPYVIEW_BASE_URL='https://your-happyview.example' HAPPYVIEW_ADMIN_TOKEN='<scop
 
 Review that release's notes and target only an explicitly approved HappyView instance.
 
+For a bundle that registers `app.certified.actor.getProfile`, handle lookups require the HappyView script variable `HYPERCERTS_HANDLE_RESOLVER_URL`. It has no built-in default and must be an HTTPS resolver origin without credentials, a path, query, or fragment. When the setting is missing, an interactive install prompts for it. For a noninteractive install, set it in the environment:
+
+```sh
+HYPERCERTS_HANDLE_RESOLVER_URL='https://resolver.example' HAPPYVIEW_BASE_URL='https://your-happyview.example' HAPPYVIEW_ADMIN_TOKEN='<scoped-admin-token>' pnpm install:api
+```
+
+The installer inspects script variables before writing assets, so the admin token needs `script-variables:read`; if the resolver setting is absent, creating it also requires `script-variables:create`. An existing setting is retained without prompting or overwriting it. HappyView exposes only a masked preview, so the installer cannot verify its actual value. If the installer creates the setting and a later asset write fails, the setting remains on the instance; installation writes are not rolled back.
 ## Rights queries
 
 - `org.hypercerts.claim.getRights` accepts the exact rights-record AT-URI with a DID authority. An unindexed record returns `RecordNotFound`.

docs/README.md

@@ -23,6 +23,18 @@ VITE_HAPPYVIEW_SERVERS='[{"label":"Staging","url":"https://staging.api.hypercert
 
 The value must be a nonempty JSON array of labeled, distinct http(s) base URLs without credentials, query, or fragment. The first entry is the default; Local and Custom remain available. These URLs are public in the browser bundle, so do not include secrets. Changing a deployed site's configuration requires a rebuild and redeploy.
 
+## Refresh the committed API reference
+
+From the workspace root, run:
+
+```sh
+pnpm docs:sync
+```
+
+The command reads `api/manifest.json`, the registered module manifests, local API Lexicons, and the pinned `@hypercerts-org/lexicon` package. It refreshes the endpoint index, committed Lexicon snapshots, `openapi.json`, and `coverage.json`. Schema references are resolved locally; the command does not fetch remote Lexicons or contact HappyView. Install the repository-pinned dependencies first with `pnpm install --frozen-lockfile`.
+
+The exact explorer operations and their module inclusion come from the manifest. `coverage.json` describes manifest inclusion only; it does not claim runtime or deployment validation. The endpoint test suite, also run by the workspace-root `pnpm check`, performs a read-only freshness check of the full index metadata, every referenced snapshot (including pinned package schemas), OpenAPI, and coverage against the current API sources. That check requires the pinned Lexicon dependency, but the explorer build and runtime still use committed snapshots without needing an API checkout.
+
 ## Build and check
 
 ```sh