From 072807bf4863c78ce3937bf155a4571bb3a35685 Mon Sep 17 00:00:00 2001
From: simonredfern <simon@tesobe.com>
Date: Tue, 13 Oct 2026 18:56:33 +0200
Subject: [PATCH 1/2] Entity descriptions and links to API Manager

---
 src/lib/chain/onChain.test.ts          | 22 ++++++++-
 src/lib/chain/onChain.ts               | 50 ++++++++++++++++++++
 src/lib/components/Kpi.svelte          | 29 +++++++++++-
 src/lib/obp/domainApi.test.ts          | 13 +++++-
 src/lib/obp/domainApi.ts               |  9 ++++
 src/lib/obp/entityDescriptions.test.ts | 27 +++++++++++
 src/lib/obp/entityDescriptions.ts      | 65 ++++++++++++++++++++++++++
 src/routes/chain/+page.server.ts       | 49 +++++++++++++++++--
 src/routes/chain/+page.svelte          | 42 +++++++++++++++++
 src/routes/domain-api/+page.server.ts  | 26 +++++++++--
 src/routes/domain-api/+page.svelte     |  4 ++
 src/routes/registry/+page.server.ts    | 18 ++++---
 src/routes/registry/+page.svelte       | 53 ++++++++++++++++-----
 13 files changed, 377 insertions(+), 30 deletions(-)
 create mode 100644 src/lib/obp/entityDescriptions.test.ts
 create mode 100644 src/lib/obp/entityDescriptions.ts

diff --git a/src/lib/chain/onChain.test.ts b/src/lib/chain/onChain.test.ts
index 0c7b693..a985cd1 100644
--- a/src/lib/chain/onChain.test.ts
+++ b/src/lib/chain/onChain.test.ts
@@ -22,7 +22,8 @@ vi.mock('$lib/obp/requests', () => ({
 	}
 }));
 
-const { getChainTokens, getChainSyncStatus, formatUnits, idFromUri } = await import('./onChain');
+const { getChainTokens, getChainSyncStatus, getCreditTotals, formatUnits, idFromUri } =
+	await import('./onChain');
 
 beforeEach(() => {
 	for (const k of Object.keys(lists)) delete lists[k];
@@ -154,6 +155,25 @@ describe('getChainTokens', () => {
 	});
 });
 
+describe('getCreditTotals', () => {
+	it('sums issued batch amounts and held balances, in tonnes', async () => {
+		lists['carbon_credit_batch_on_chain'] = [
+			{ amount: '6500000000000000000', credit_decimals: '18' },
+			{ amount: '5500000000000000000', credit_decimals: '18' }
+		];
+		lists['carbon_credit_balance_on_chain'] = [
+			{ balance: '6500000000000000000', decimals: '18' },
+			{ balance: '2000000000000000000', decimals: '18' }
+		];
+		expect(await getCreditTotals()).toEqual({ issued: '12', active: '8.5' });
+	});
+
+	it('is zero with no records, and null for a mirror that cannot be read', async () => {
+		delete lists['carbon_credit_balance_on_chain'];
+		expect(await getCreditTotals()).toEqual({ issued: '0', active: null });
+	});
+});
+
 describe('formatUnits', () => {
 	it('scales base units by the decimals and trims trailing zeros', () => {
 		expect(formatUnits('6500000000000000000', 18)).toBe('6.5');
diff --git a/src/lib/chain/onChain.ts b/src/lib/chain/onChain.ts
index 3f2d296..ff59fe4 100644
--- a/src/lib/chain/onChain.ts
+++ b/src/lib/chain/onChain.ts
@@ -62,6 +62,22 @@ export interface ChainToken {
 
 export type ChainSectionKey = 'parcel' | 'activity' | 'certification' | 'batch' | 'balance';
 
+/**
+ * Each section's chain mirror entity, and the registry entity it mirrors from. The
+ * mirrors' descriptions say how they are filled; the source's says what the record is.
+ * A balance has no registry counterpart: it exists only on chain.
+ */
+export const CHAIN_SECTION_ENTITIES: Record<
+	ChainSectionKey,
+	{ entity: string; sourceEntity: string | null }
+> = {
+	parcel: { entity: ENTITY_PARCEL_ON_CHAIN, sourceEntity: 'parcel' },
+	activity: { entity: ENTITY_ACTIVITY_ON_CHAIN, sourceEntity: 'activity' },
+	certification: { entity: ENTITY_CERTIFICATION_ON_CHAIN, sourceEntity: 'certificate_of_compliance' },
+	batch: { entity: ENTITY_CARBON_CREDIT_BATCH_ON_CHAIN, sourceEntity: 'carbon_credit_batch' },
+	balance: { entity: ENTITY_CARBON_CREDIT_BALANCE_ON_CHAIN, sourceEntity: null }
+};
+
 /** Every token of one type, newest block first. */
 export interface ChainSection {
 	key: ChainSectionKey;
@@ -377,6 +393,40 @@ export async function getChainTokens(): Promise<ChainSection[]> {
 	];
 }
 
+/** Total credits, in tonnes CO2e: `issued` is what the batches were minted with, `active`
+ *  is what is held anywhere on chain (in batch accounts or wallets), so it drops when
+ *  credits are retired (burned). Null when the mirror cannot be read. */
+export interface CreditTotals {
+	issued: string | null;
+	active: string | null;
+}
+
+/** Sum of a base-unit field across records, as a decimal string. All CarbonCredit
+ *  amounts share the token's decimals, so the first record's decimals apply to all. */
+function sumUnits(records: Record<string, any>[], field: string, decimalsField: string): string {
+	let total = 0n;
+	for (const r of records) {
+		try {
+			total += BigInt(String(r[field] ?? 0));
+		} catch {
+			// A malformed amount is left out rather than failing the whole total.
+		}
+	}
+	return formatUnits(total.toString(), records[0]?.[decimalsField] ?? 18) ?? '0';
+}
+
+/** Issued and active credit totals, read anonymously from the public chain mirrors. */
+export async function getCreditTotals(): Promise<CreditTotals> {
+	const [batches, balances] = await Promise.all([
+		listPublicEntity(ENTITY_CARBON_CREDIT_BATCH_ON_CHAIN).catch(() => null),
+		listPublicEntity(ENTITY_CARBON_CREDIT_BALANCE_ON_CHAIN).catch(() => null)
+	]);
+	return {
+		issued: batches ? sumUnits(batches, 'amount', 'credit_decimals') : null,
+		active: balances ? sumUnits(balances, 'balance', 'decimals') : null
+	};
+}
+
 /** The four benefit fields a monitoring verification can carry, and the suffix
  * of the carbon_credit_batch_id each one mints as. Taken from the tokenizer's
  * MonitoringVerification.CreditBatches(): a batch is minted per field with a
diff --git a/src/lib/components/Kpi.svelte b/src/lib/components/Kpi.svelte
index 1679868..0122402 100644
--- a/src/lib/components/Kpi.svelte
+++ b/src/lib/components/Kpi.svelte
@@ -15,6 +15,8 @@
 	 * imply a judgement we have no data to make.
 	 *
 	 * `href` turns the label and value into links to the page behind the figure.
+	 * `browseLabel` (an app extension, not in the design system) adds a visible
+	 * "Browse …" link to the same page at the foot of the tile.
 	 */
 	import type { Snippet } from 'svelte';
 
@@ -28,6 +30,7 @@
 		tone = 'positive',
 		accentBar = true,
 		href,
+		browseLabel,
 		class: className = '',
 		...rest
 	}: {
@@ -38,6 +41,7 @@
 		tone?: Tone;
 		accentBar?: boolean;
 		href?: string;
+		browseLabel?: string;
 		class?: string;
 		[key: string]: unknown;
 	} = $props();
@@ -53,7 +57,10 @@
 				<span class="ogcr-kpi__icon" aria-hidden="true">{@render icon()}</span>
 			{/if}
 			{#if href}
-				<a {href} class="ogcr-kpi__label ogcr-kpi__link">{label}</a>
+				<!-- With a browse link, that is the one tab stop for the destination. -->
+				<a {href} class="ogcr-kpi__label ogcr-kpi__link" tabindex={browseLabel ? -1 : undefined}
+					>{label}</a
+				>
 			{:else}
 				<span class="ogcr-kpi__label">{label}</span>
 			{/if}
@@ -67,6 +74,9 @@
 	{#if secondaryText}
 		<p class="ogcr-kpi__secondary">{secondaryText}</p>
 	{/if}
+	{#if href && browseLabel}
+		<a {href} class="ogcr-kpi__browse">{browseLabel}</a>
+	{/if}
 </article>
 
 <style>
@@ -157,6 +167,20 @@
 		text-decoration: underline;
 	}
 
+	.ogcr-kpi__browse {
+		margin-top: var(--space-xs);
+		font-family: var(--font-family-default);
+		font-weight: 500;
+		font-size: var(--font-size-m);
+		color: var(--interaction-primary-default);
+		text-decoration: none;
+	}
+	.ogcr-kpi__browse:hover,
+	.ogcr-kpi__browse:focus-visible {
+		color: var(--interaction-primary-hover);
+		text-decoration: underline;
+	}
+
 	.ogcr-kpi__secondary {
 		margin: 0;
 		font-family: var(--font-family-default);
@@ -175,6 +199,9 @@
 	:global([data-mode='dark']) .ogcr-kpi__value {
 		color: var(--color-primary-200);
 	}
+	:global([data-mode='dark']) .ogcr-kpi__browse {
+		color: var(--color-primary-300);
+	}
 	:global([data-mode='dark']) .ogcr-kpi__label,
 	:global([data-mode='dark']) .ogcr-kpi__secondary {
 		color: var(--color-surface-400);
diff --git a/src/lib/obp/domainApi.test.ts b/src/lib/obp/domainApi.test.ts
index 3e22746..6a6024a 100644
--- a/src/lib/obp/domainApi.test.ts
+++ b/src/lib/obp/domainApi.test.ts
@@ -1,5 +1,16 @@
 import { describe, expect, it } from 'vitest';
-import { publicGets } from './domainApi';
+import { apiExplorerDomainApiLink, publicGets } from './domainApi';
+
+describe('apiExplorerDomainApiLink', () => {
+	it("opens API Explorer on the Domain API's own version", () => {
+		expect(apiExplorerDomainApiLink('https://explorer.example.org', 'crcf/ogcr/v1')).toBe(
+			'https://explorer.example.org/resource-docs/DomainAPI~crcf~ogcr~v1'
+		);
+		expect(apiExplorerDomainApiLink('http://localhost:5173/', 'crcf/ogcr/v1')).toBe(
+			'http://localhost:5173/resource-docs/DomainAPI~crcf~ogcr~v1'
+		);
+	});
+});
 
 const login = [{ DirectLogin: [] }, { OAuth2: [] }];
 
diff --git a/src/lib/obp/domainApi.ts b/src/lib/obp/domainApi.ts
index cf283b1..b6ae917 100644
--- a/src/lib/obp/domainApi.ts
+++ b/src/lib/obp/domainApi.ts
@@ -3,6 +3,15 @@
  * that Domain API's endpoints, at their published paths.
  */
 
+/**
+ * Where API Explorer shows a Domain API: it lists each publicly discoverable Domain API as a
+ * version of its own, keyed by its base path with `~` for `/` (a base path cannot contain `~`).
+ */
+export function apiExplorerDomainApiLink(apiExplorerUrl: string, basePath: string): string {
+	const base = apiExplorerUrl.endsWith('/') ? apiExplorerUrl : `${apiExplorerUrl}/`;
+	return new URL(`resource-docs/DomainAPI~${basePath.split('/').join('~')}`, base).toString();
+}
+
 /** A GET endpoint anyone may call, at its path under the Domain API's base path. */
 export type PublicGet = {
 	path: string;
diff --git a/src/lib/obp/entityDescriptions.test.ts b/src/lib/obp/entityDescriptions.test.ts
new file mode 100644
index 0000000..de3ca5e
--- /dev/null
+++ b/src/lib/obp/entityDescriptions.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import { descriptionFromDoc, entityTag } from './entityDescriptions';
+
+describe('entityTag', () => {
+	it('capitalises the first letter and adds the bank id', () => {
+		expect(entityTag('parcel_on_chain', 'ogcr')).toBe('_Parcel_on_chain(ogcr)');
+	});
+});
+
+describe('descriptionFromDoc', () => {
+	it('keeps only the definition description', () => {
+		const doc = {
+			description_markdown:
+				"Create new parcel.\n\nParcel' means a geospatially defined unit of land. This Dynamic Entity is part of OGCR.\n\n\n**Property List:**\n\n* parcel_id: id\n\nMethodRouting settings example: ..."
+		};
+		expect(descriptionFromDoc(doc, 'parcel')).toBe(
+			"Parcel' means a geospatially defined unit of land."
+		);
+	});
+
+	it('is null when there is no description', () => {
+		expect(
+			descriptionFromDoc({ description_markdown: 'Create new x.\n\n**Property List:**' }, 'x')
+		).toBeNull();
+		expect(descriptionFromDoc({}, 'x')).toBeNull();
+	});
+});
diff --git a/src/lib/obp/entityDescriptions.ts b/src/lib/obp/entityDescriptions.ts
new file mode 100644
index 0000000..456ff82
--- /dev/null
+++ b/src/lib/obp/entityDescriptions.ts
@@ -0,0 +1,65 @@
+import { env } from '$env/dynamic/public';
+import { ENTITY_ROLE_BANK_ID } from '$lib/constants/entities';
+
+/**
+ * Dynamic Entity descriptions, as written in each entity's definition.
+ *
+ * The definitions endpoints need an admin Role, but OBP copies each definition's
+ * description into the entity's generated resource docs, which are public. So this reads
+ * those, filtered by the entities' tags (`_Parcel_on_chain(ogcr)`) so only their docs come
+ * back rather than the whole space's (several MB).
+ */
+
+interface ResourceDoc {
+	request_verb?: string;
+	specified_url?: string;
+	description_markdown?: string;
+}
+
+/** OBP tags an entity's generated endpoints `_<Entity_name>(<bank id>)`. */
+export function entityTag(entity: string, bankId: string): string {
+	return `_${entity.charAt(0).toUpperCase()}${entity.slice(1)}(${bankId})`;
+}
+
+/**
+ * The definition's description, from the entity's create (POST) doc: OBP wraps it in a
+ * "Create new <entity>." line, then appends the property list, the routing example and a
+ * "This Dynamic Entity is part of …" line, all of which are dropped here.
+ */
+export function descriptionFromDoc(doc: ResourceDoc, entity: string): string | null {
+	const markdown = doc.description_markdown ?? '';
+	const text = markdown
+		.split(/\*\*Property List|MethodRouting settings example/)[0]
+		.replace(new RegExp(`^\\s*Create new ${entity}\\.`), '')
+		.replace(/This Dynamic Entity is part of [^.]*\./g, '')
+		.replace(/\s+/g, ' ')
+		.trim();
+	return text || null;
+}
+
+/** entity -> description, for those of `entities` whose docs OBP returned. Never throws. */
+export async function getEntityDescriptions(
+	entities: string[],
+	fetchFn: typeof fetch = fetch
+): Promise<Record<string, string>> {
+	const base = env.PUBLIC_OBP_BASE_URL?.replace(/\/$/, '') ?? '';
+	const bank = encodeURIComponent(ENTITY_ROLE_BANK_ID);
+	const tags = entities.map((e) => encodeURIComponent(entityTag(e, ENTITY_ROLE_BANK_ID))).join(',');
+	const url = `${base}/obp/v6.0.0/banks/${bank}/resource-docs/v6.0.0/obp?content=dynamic&tags=${tags}`;
+	try {
+		const response = await fetchFn(url);
+		if (!response.ok) return {};
+		const docs = ((await response.json())?.resource_docs ?? []) as ResourceDoc[];
+		const descriptions: Record<string, string> = {};
+		for (const entity of entities) {
+			const create = docs.find(
+				(d) => d.request_verb === 'POST' && (d.specified_url ?? '').endsWith(`/${entity}`)
+			);
+			const text = create ? descriptionFromDoc(create, entity) : null;
+			if (text) descriptions[entity] = text;
+		}
+		return descriptions;
+	} catch {
+		return {};
+	}
+}
diff --git a/src/routes/chain/+page.server.ts b/src/routes/chain/+page.server.ts
index aad26ab..2a52753 100644
--- a/src/routes/chain/+page.server.ts
+++ b/src/routes/chain/+page.server.ts
@@ -1,13 +1,26 @@
 import type { PageServerLoad } from './$types';
 import { OBPRequestError } from '$lib/obp/errors';
-import { getChainSyncStatus, getChainTokens, type ChainSection } from '$lib/chain/onChain';
+import {
+	CHAIN_SECTION_ENTITIES,
+	getChainSyncStatus,
+	getChainTokens,
+	type ChainSection,
+	type ChainSectionKey
+} from '$lib/chain/onChain';
+import { getEntityDescriptions } from '$lib/obp/entityDescriptions';
+import { API_MANAGER_URL, getAppDirectory } from '$lib/obp/appDirectory';
+import { apiManagerEntityHref } from '$lib/obp/entityPages';
+import { ENTITY_ROLE_BANK_ID } from '$lib/constants/entities';
+
+/** One entity's description, linked to its definition in API Manager when there is one. */
+type About = { entity: string; text: string; href: string | null };
 import { deriveHeartbeat, type Heartbeat } from '$lib/chain/heartbeat';
 import { env } from '$env/dynamic/public';
 import { normalizeExplorerBase } from '$lib/chain/explorer';
 
 /** Public: the chain mirror and its sync status are public dynamic entities, so the
  *  page is read anonymously and needs no login. */
-export const load: PageServerLoad = async () => {
+export const load: PageServerLoad = async ({ fetch }) => {
 	// A private chain has no explorer unless someone is running one, so
 	// transaction links are opt-in configuration rather than an assumption.
 	const explorerBase = normalizeExplorerBase(env.PUBLIC_CHAIN_EXPLORER_URL);
@@ -16,14 +29,41 @@ export const load: PageServerLoad = async () => {
 		// The status is what the heartbeat is built on, so a failure to read it is
 		// a page-level error. The tokens are read separately so a mirror that cannot
 		// be read cannot take the heartbeat down with it.
-		const [status, sections] = await Promise.all([
+		const [status, sections, descriptions, directory] = await Promise.all([
 			getChainSyncStatus(),
-			getChainTokens().catch(() => [] as ChainSection[])
+			getChainTokens().catch(() => [] as ChainSection[]),
+			// What each section holds, from the entity definitions (see CHAIN_SECTION_ENTITIES).
+			getEntityDescriptions(
+				Object.values(CHAIN_SECTION_ENTITIES).flatMap((e) =>
+					e.sourceEntity ? [e.entity, e.sourceEntity] : [e.entity]
+				),
+				fetch
+			),
+			getAppDirectory(fetch)
 		]);
+		const apiManagerUrl = directory[API_MANAGER_URL] ?? null;
+
+		// Per section: the source entity's description, then the on-chain entity's. Built
+		// here because CHAIN_SECTION_ENTITIES lives in server-only code.
+		const about = {} as Record<ChainSectionKey, About[]>;
+		for (const [key, { entity, sourceEntity }] of Object.entries(CHAIN_SECTION_ENTITIES)) {
+			about[key as ChainSectionKey] = [sourceEntity, entity].flatMap((e) =>
+				e && descriptions[e]
+					? [
+							{
+								entity: e,
+								text: descriptions[e],
+								href: apiManagerUrl ? apiManagerEntityHref(apiManagerUrl, ENTITY_ROLE_BANK_ID, e) : null
+							}
+						]
+					: []
+			);
+		}
 
 		return {
 			heartbeat: deriveHeartbeat(status),
 			sections,
+			about,
 			explorerBase,
 			error: null
 		};
@@ -37,6 +77,7 @@ export const load: PageServerLoad = async () => {
 		return {
 			heartbeat: deriveHeartbeat(null) as Heartbeat,
 			sections: [] as ChainSection[],
+			about: {} as Record<ChainSectionKey, About[]>,
 			explorerBase,
 			error: message,
 			errorDetails: error instanceof OBPRequestError ? error.toJSON() : undefined
diff --git a/src/routes/chain/+page.svelte b/src/routes/chain/+page.svelte
index 22b7ae1..9b220b7 100644
--- a/src/routes/chain/+page.svelte
+++ b/src/routes/chain/+page.svelte
@@ -226,6 +226,30 @@
 			headingLevel={2}
 			padding="l"
 		>
+			{@const about = data.about[section.key] ?? []}
+			{#if about.length > 0}
+				<!-- From the entity definitions: what the record is, then how its chain copy is kept. -->
+				<div class="chain-about">
+					{#each about as a (a.entity)}
+						<p>
+							{#if a.href}
+								<a
+									href={a.href}
+									target="_blank"
+									rel="noopener"
+									class="chain-about__label chain-link"
+									title="{a.entity} definition in API Manager"
+								>
+									{a.entity}<ExternalLink class="size-3" aria-label="(opens in a new tab)" />
+								</a>
+							{:else}
+								<span class="chain-about__label">{a.entity}</span>
+							{/if}
+							{a.text}
+						</p>
+					{/each}
+				</div>
+			{/if}
 			<Table
 				columns={tokenColumns(section.key)}
 				rows={section.tokens.map((t) => ({
@@ -319,6 +343,20 @@
 		color: var(--text-primary);
 		font-weight: 500;
 	}
+	.chain-about {
+		display: flex;
+		flex-direction: column;
+		gap: var(--space-2xs);
+		font-size: var(--font-size-s);
+		color: var(--text-neutral);
+	}
+	.chain-about__label {
+		font-family: var(--font-family-mono);
+		color: var(--text-secondary);
+	}
+	.chain-about__label::after {
+		content: ':';
+	}
 	.chain-note {
 		font-size: var(--font-size-s);
 		color: var(--text-secondary);
@@ -362,6 +400,10 @@
 
 	/* Dark mode: the design system has no dark palette, so fall back to the Skeleton
 	   dark surfaces, as Card does. */
+	:global([data-mode='dark']) .chain-about {
+		color: var(--color-surface-300);
+	}
+	:global([data-mode='dark']) .chain-about__label,
 	:global([data-mode='dark']) .chain-note,
 	:global([data-mode='dark']) .chain-record__detail,
 	:global([data-mode='dark']) .chain-links__label {
diff --git a/src/routes/domain-api/+page.server.ts b/src/routes/domain-api/+page.server.ts
index cd3debc..0561772 100644
--- a/src/routes/domain-api/+page.server.ts
+++ b/src/routes/domain-api/+page.server.ts
@@ -1,7 +1,8 @@
 import type { PageServerLoad } from './$types';
 import { env } from '$env/dynamic/public';
 import { ENTITY_ROLE_BANK_ID } from '$lib/constants/entities';
-import { publicGets, type PublicGet } from '$lib/obp/domainApi';
+import { apiExplorerDomainApiLink, publicGets, type PublicGet } from '$lib/obp/domainApi';
+import { API_EXPLORER_URL, getAppDirectory } from '$lib/obp/appDirectory';
 
 /** A Domain API as OBP lists it publicly at GET /obp/v7.0.0/banks/BANK_ID/domain-apis. */
 export type DomainApi = {
@@ -26,7 +27,14 @@ export const load: PageServerLoad = async ({ fetch }) => {
 	const base = env.PUBLIC_OBP_BASE_URL?.replace(/\/$/, '') ?? '';
 	const path = `/obp/v7.0.0/banks/${encodeURIComponent(ENTITY_ROLE_BANK_ID)}/domain-apis`;
 
-	let domainApis: (DomainApi & { publicGets: PublicGet[]; publicGetsError: string | null })[] = [];
+	// API Explorer, where OBP's app directory says it is, shows each Domain API's endpoints to try.
+	const apiExplorerUrl = (await getAppDirectory(fetch))[API_EXPLORER_URL] ?? null;
+
+	let domainApis: (DomainApi & {
+		publicGets: PublicGet[];
+		publicGetsError: string | null;
+		apiExplorerUrl: string | null;
+	})[] = [];
 	let error: string | null = null;
 	try {
 		const response = await fetch(`${base}${path}`);
@@ -42,18 +50,28 @@ export const load: PageServerLoad = async ({ fetch }) => {
 
 	return { space: ENTITY_ROLE_BANK_ID, domainApis, error };
 
+	function explorerLink(api: DomainApi): string | null {
+		return apiExplorerUrl ? apiExplorerDomainApiLink(apiExplorerUrl, api.base_path) : null;
+	}
+
 	/** The Domain API with its public GETs, or why they could not be read. */
 	async function withPublicGets(api: DomainApi) {
 		const url = `${api.url.replace(/\/$/, '')}/openapi.json`;
 		try {
 			const response = await fetch(url);
 			if (!response.ok) throw new Error(`OBP returned HTTP ${response.status} for ${url}`);
-			return { ...api, publicGets: publicGets(await response.json()), publicGetsError: null };
+			return {
+				...api,
+				publicGets: publicGets(await response.json()),
+				publicGetsError: null,
+				apiExplorerUrl: explorerLink(api)
+			};
 		} catch (e) {
 			return {
 				...api,
 				publicGets: [],
-				publicGetsError: e instanceof Error ? e.message : 'Could not reach OBP'
+				publicGetsError: e instanceof Error ? e.message : 'Could not reach OBP',
+				apiExplorerUrl: explorerLink(api)
 			};
 		}
 	}
diff --git a/src/routes/domain-api/+page.svelte b/src/routes/domain-api/+page.svelte
index e463100..ab2be81 100644
--- a/src/routes/domain-api/+page.svelte
+++ b/src/routes/domain-api/+page.svelte
@@ -43,6 +43,10 @@
 							<a href="{api.url}/openapi.json" class="anchor">openapi.json</a>
 							<a href="{api.url}/openapi.yaml" class="anchor">openapi.yaml</a>
 						</dd>
+						{#if api.apiExplorerUrl}
+							<dt class="text-body-s ogcr-secondary">Try it</dt>
+							<dd><a href={api.apiExplorerUrl} class="anchor">API Explorer</a></dd>
+						{/if}
 					</dl>
 
 					<section class="ogcr-public-gets" aria-label="Public GET endpoints of {api.title}">
diff --git a/src/routes/registry/+page.server.ts b/src/routes/registry/+page.server.ts
index 84ff569..0b16b78 100644
--- a/src/routes/registry/+page.server.ts
+++ b/src/routes/registry/+page.server.ts
@@ -1,18 +1,22 @@
 import type { PageServerLoad } from './$types';
 import { getRegistryActivities } from '$lib/registry/activities';
+import { getCreditTotals } from '$lib/chain/onChain';
 
 /**
  * The registry is a public surface, so this page takes no access token: the activity
  * count comes from the same public endpoint the activity list uses, and a signed-out
  * visitor sees the same figure a buyer would.
  *
- * Issued / Active / Retired units have no source yet. There is no issuance or
- * retirement data in the DCR schema, and the only credit quantities anywhere
- * (marketplace listings) are operator-entered commercial terms, not registry facts —
- * per design_goals.md the registry owns the activity's facts. Those tiles say so
- * rather than showing a fabricated number.
+ * Issued and Active units are read from the chain, through the public chain mirrors:
+ * Issued is what the credit batches were minted with, Active what is still held on
+ * chain. Retired units have no public source yet: the retirement entities are not
+ * public and OGCR-chain-cache does not mirror retirements, so that tile says so rather
+ * than showing a fabricated number.
  */
 export const load: PageServerLoad = async ({ fetch }) => {
-	const { count, error } = await getRegistryActivities(fetch);
-	return { activityCount: error ? null : count, error };
+	const [{ count, error }, credits] = await Promise.all([
+		getRegistryActivities(fetch),
+		getCreditTotals()
+	]);
+	return { activityCount: error ? null : count, error, credits };
 };
diff --git a/src/routes/registry/+page.svelte b/src/routes/registry/+page.svelte
index 4659606..d28c4b5 100644
--- a/src/routes/registry/+page.svelte
+++ b/src/routes/registry/+page.svelte
@@ -1,20 +1,38 @@
 <script lang="ts">
 	import type { PageData } from './$types';
 	import Kpi from '$lib/components/Kpi.svelte';
-	import { FolderKanban, BadgeCheck, Coins, Recycle } from '@lucide/svelte';
+	import { FolderKanban, BadgeCheck, Coins, Archive } from '@lucide/svelte';
 
 	let { data }: { data: PageData } = $props();
 
 	const activityCount = $derived(data.activityCount);
 
-	// Issuance, holding and retirement figures have no source in the DCR schema
-	// yet. The tiles stay in place so the layout is ready for when they do, but
-	// they say so rather than showing a fabricated number.
-	const unitStats = [
-		{ label: 'Issued Units', icon: Coins },
-		{ label: 'Active Units', icon: BadgeCheck },
-		{ label: 'Retired Units', icon: Recycle }
-	];
+	// Issued and Active come from the chain (see the loader). Retired has no public
+	// source yet, so that tile says so rather than showing a fabricated number.
+	const unitStats = $derived([
+		{
+			label: 'Issued Units',
+			icon: Coins,
+			value: data.credits.issued,
+			href: '/chain#section-batch',
+			browseLabel: 'Browse credit batches'
+		},
+		{
+			label: 'Active Units',
+			icon: BadgeCheck,
+			value: data.credits.active,
+			href: '/chain#section-balance',
+			browseLabel: 'Browse credit balances'
+		},
+		{
+			label: 'Retired Units',
+			icon: Archive,
+			value: null,
+			href: undefined,
+			browseLabel: undefined,
+			comingSoon: true
+		}
+	]);
 </script>
 
 <svelte:head>
@@ -35,11 +53,10 @@
 			covers, the practices applied, the operator responsible and the monitoring period over which
 			its results are measured.
 		</p>
-		<p class="text-body mb-8 text-surface-600-400">
+		<p class="text-body text-surface-600-400">
 			Certification is carried out by accredited bodies and recorded against the activity, so a
 			buyer can trace a unit back to the parcel, the practice and the verification behind it.
 		</p>
-		<a href="/registry/activities" class="btn preset-filled-primary-500">Browse Activities</a>
 	</div>
 
 	<section aria-labelledby="registry-summary" class="mt-12">
@@ -48,6 +65,7 @@
 			<Kpi
 				label="Activities"
 				href="/registry/activities"
+				browseLabel="Browse activities"
 				value={activityCount ?? '—'}
 				secondaryText={activityCount === null ? 'Unavailable right now' : undefined}
 				accentBar={false}
@@ -58,7 +76,18 @@
 			</Kpi>
 
 			{#each unitStats as stat (stat.label)}
-				<Kpi label={stat.label} value="—" secondaryText="Coming soon" accentBar={false}>
+				<Kpi
+					label={stat.label}
+					href={stat.href}
+					browseLabel={stat.browseLabel}
+					value={stat.value ?? '—'}
+					secondaryText={stat.comingSoon
+						? 'Coming soon'
+						: stat.value === null
+							? 'Unavailable right now'
+							: 'tCO₂e on chain'}
+					accentBar={false}
+				>
 					{#snippet icon()}
 						<stat.icon />
 					{/snippet}

From 85e590ef26ccbe7551f90cd83ed4039f2f836191 Mon Sep 17 00:00:00 2001
From: simonredfern <simon@tesobe.com>
Date: Tue, 13 Oct 2026 19:04:12 +0200
Subject: [PATCH 2/2] Create NOTICE

---
 NOTICE | 13 +++++++++++++
 1 file changed, 13 insertions(+)
 create mode 100644 NOTICE

diff --git a/NOTICE b/NOTICE
new file mode 100644
index 0000000..f0197dd
--- /dev/null
+++ b/NOTICE
@@ -0,0 +1,13 @@
+OGCR-App
+Copyright (C) 2026 TESOBE GmbH
+
+This program is free software: you can redistribute it and/or modify it under the
+terms of the GNU Affero General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License along with
+this program, in the LICENSE file. If not, see <https://www.gnu.org/licenses/>.