# Digital Karma v8.2

Portable installer brief and implementation guide for Digital Karma Web v8.2.

Status: Current working guide

Authority date: 2026-09-23

Canonical authority: `specs/federation-spec-v8.md`

## Purpose

Use this file as the controlling install brief inside the Digital Karma Web v8.2 download kit. v8.2 closes the gap between machine-readable federation files and the HTML that search engines actually render and inspect.

A site cannot claim v8.2 because its `/ai/` files exist. It can claim v8.2 only after every canonical URL in its root sitemap renders the required dataset graph and a current audit receipt proves it.

## Agent Operating Rule

When this file is present in a site root, make the entire public site conform to Digital Karma Federation v8.2.

Conformance is site-wide and route-complete. It is not limited to a homepage, a preferred template, a directory section, or sites whose names mention data. Every newly added public route and every newly populated reusable content family inherits this requirement at release time.

Agents must:

1. Inspect the site architecture, sitemap, catalog, content types, and existing JSON-LD before editing.
2. Preserve working site-specific content and schema.
3. Treat `/ai/catalog.json` as the source of truth for the datasets rendered in HTML.
4. Render one `DataCatalog` and every catalog `Dataset` on every canonical sitemap page.
5. Connect the page's primary entity to the relevant dataset or datasets with `subjectOf` or an equivalent Schema.org relationship.
6. Run the rendered dataset validator against every sitemap URL after deployment.
7. Publish the passing receipt at `/ai/rendered-schema.json`.
8. Expose that receipt through the manifest and health endpoints.
9. Refuse to declare v8.2 while any sitemap page fails.
10. Treat a missing, empty, or older-version manifest as an audit failure, never as a reason to skip the site.
11. Compare the site registry with the actual public docroots and fail any unregistered content site instead of leaving it outside the audit.

Agents must not:

1. Treat federation endpoint generation as proof that rendered HTML is correct.
2. Spot-check one page and infer coverage for the rest of the site.
3. Publish a passing receipt without crawling every sitemap URL.
4. hand-edit `/ai/rendered-schema.json`.
5. let a content type exist without a corresponding catalog Dataset when that content is a reusable collection.
6. hand-maintain `llm.json`, `/ai/llm.json`, or `/llms.txt`.
7. represent several populated content families with one generic Dataset label.

## What Changed in v8.2

v8.2 adds the rendered HTML layer to the protocol:

1. Every canonical URL in `sitemap.xml` is in scope.
2. Every page must emit parseable `application/ld+json`.
3. Every page must expose one `DataCatalog` node.
4. Every page must expose at least the number of `Dataset` nodes declared by `/ai/catalog.json`.
5. Dataset nodes must carry stable identifiers and required Google Dataset fields.
6. The page's primary entity must connect to the dataset layer.
7. `/ai/rendered-schema.json` is the seventh required federation artifact.
8. The receipt records the sitemap hash, catalog hash, page counts, expected dataset count, coverage, failures, and validator identity.
9. The nightly build must regenerate the federation files, generate LLM files, crawl every sitemap page, write the receipt, and then run federation conformance checks.

v8.0 and v8.1 sites remain readable federation members. They are not v8.2 compliant until the rendered audit passes.

## Seven Required Federation Artifacts

1. Manifest at `/ai/manifest.json` for identity, discovery, endpoint maps, and constellation links.
2. Health at `/ai/health.json` for current readiness, metrics, and rendered audit state.
3. Catalog at `/ai/catalog.json` for the canonical DataCatalog and Dataset inventory.
4. Karma at `/ai/karma.json` for the Digital Karma definition or measured score.
5. Federation at `/ai/federation.json` for role, peers, and topology.
6. Rendered schema receipt at `/ai/rendered-schema.json` for entire-site proof.
7. LLM text at `/llm.txt` for the root-level machine-readable site guide.

Root `/robots.txt` and `/sitemap.xml` remain required operational discovery files. Generated `/llm.json`, `/ai/llm.json`, and `/llms.txt` remain standard outputs.

## Rendered HTML Dataset Contract

Every canonical sitemap page must render a coherent Schema.org `@graph` containing:

1. `WebSite`.
2. The publisher or creator entity.
3. The page's primary entity, such as `WebPage`, `Article`, `FAQPage`, `CollectionPage`, `Service`, or another accurate type.
4. One `DataCatalog` representing `/ai/catalog.json`.
5. One `Dataset` for every entry in the catalog's dataset array.
6. A relationship from the primary entity to the relevant dataset layer.

Each rendered `Dataset` must include:

1. `@type: Dataset`.
2. A stable `@id`.
3. `name`.
4. `description` between 50 and 5000 characters.
5. A canonical `url`.
6. `includedInDataCatalog` pointing to the rendered catalog node.
7. `creator` or `publisher`.
8. `isPartOf` connecting it to the site.
9. `distribution` with `contentUrl` when a downloadable representation exists.

Prefer one merged graph instead of disconnected script blocks. Do not replace richer page-specific schema. Merge the dataset layer into it.

Before adding catalog schema, inspect every native JSON-LD block. Preserve
richer page-specific nodes and fields, merge matching Organization, WebSite,
page, DataCatalog, and Dataset nodes onto one canonical `@id` each, rewrite
their references, and add only missing entities or fields. Multiple script
blocks are valid when they resolve to one coherent graph identity. Duplicate
typed IDs, competing DataCatalog or Dataset identities, and sitemap redirects
are validation failures.

## Rendered Audit Receipt

The receipt is generated by the validator after it fetches every sitemap URL. It must include:

1. `protocol_version: 8.2`.
2. `status: passed`.
3. The root sitemap URL and SHA-256 hash.
4. The catalog URL and SHA-256 hash.
5. `expectedDatasetCount` matching the live catalog.
6. `pagesChecked`, `pagesPassed`, and `pagesFailed`.
7. `coverage: 1`.
8. `validator: DigitalKarma-RenderedDatasetAudit/8.2`.
9. An empty `failures` array.

The receipt becomes stale when the sitemap or catalog hash changes. A stale receipt fails the public audit.

## Required Build Order

Run these steps in this order:

1. Build the root sitemap.
2. Build the federation endpoints and catalog.
3. Crawl every sitemap URL with the rendered dataset validator.
4. Write `/ai/rendered-schema.json`.
5. Update health metrics and the rendered schema check from the audit result.
6. Generate `/llm.json`, `/ai/llm.json`, and generated `/llms.txt` from the final manifest and catalog.
7. Run the dataset inventory and federation conformance audits.

If step 3 fails, the site remains below v8.2 and health must not report a passing rendered schema state.

## Minimum v8.2 Requirements

1. Publish all seven required federation artifacts.
2. Keep all JSON valid and parseable.
3. Set current protocol and federation declarations to `8.2`.
4. Carry lifecycle metadata on generated endpoints.
5. Generate LLM outputs from source endpoints in the same build.
6. Use HTTPS.
7. Expose datasets in rendered HTML on every sitemap page.
8. Publish a current passing rendered schema receipt.
9. Publish a Digital Karma payload.
10. Link to the site's real constellation peers at their declared origins.
11. Keep root discovery files public.
12. Keep content, data, AI, feed, JSON, and Markdown resources publicly reachable unless a specific file contains sensitive configuration.

## Validation Command

Portfolio installs use the shared validator:

```text
php /home/webserver005/scripts/audit-rendered-datasets.php site=example.com root=/home/webserver005/public_html write_receipts=1
```

The command must report zero failed sites and zero failed URLs before the site declares v8.2.

## Upgrade Checklist

1. Inventory every content type and public collection.
2. Add a catalog Dataset for every reusable content collection.
3. Merge the catalog and Dataset nodes into the site's shared JSON-LD engine.
4. Ensure every route and content type uses that shared engine.
5. Add stable IDs and page-to-dataset relationships.
6. Update manifest endpoint discovery with `rendered_schema`.
7. Initialize health's rendered schema check as false before validation.
8. Build the sitemap and federation endpoints.
9. Run the validator across the complete sitemap.
10. Confirm the receipt hashes match the current sitemap and catalog.
11. Confirm health reports full rendered coverage and zero failures.
12. Run the public audit and confirm no required failure remains.

## Canonical References

1. `specs/federation-spec-v8.md`
2. `specs/datasets-spec.md`
3. `specs/schema-spec.md`
4. `specs/endpoints-spec.md`
5. `v8.1-DigitalKarma.md` for historical v8.1 behavior