# Digital Karma v8.0

Portable installer and implementation guide for bringing any website up to the current Digital Karma Federation v8.0 standard.

Status: Current working guide
Authority date: 2026-07-29
Canonical authority: `specs/federation-spec-v8.md`

---

## Purpose

Use this file as a portable Digital Karma specs installer.

Intended workflow:

1. Drop this file into the root of a target website repository.
2. Ask Copilot, Claude Code, Codex, or another coding agent to upgrade the site to Digital Karma Federation v8.0.
3. The agent should inspect the existing site, preserve what already works, add anything missing, and normalize inconsistent legacy implementations.

This file exists for websites that:

- have no Digital Karma implementation yet
- have partial or older Digital Karma files (v7.1 or earlier)
- have the right files in the wrong locations
- have a hand-typed `related_sites` list that has drifted from the site's real constellation membership
- need a repeatable upgrade path across the portfolio

---

## Agent Operating Rule

When this file is present in a site root, treat it as an instruction to make that site conform to Digital Karma Federation v8.0.

Agents should:

- inspect the repo before editing
- preserve working site-specific content where possible
- normalize paths and file placement to the v8.0 rules below
- update stale version declarations to `8.0`
- avoid inventing alternate endpoint layouts when the standard already defines one
- check whether `related_sites` actually reflects the site's real constellation peers before trusting it -- this is the single most common drift found in the v8.0 revision

Agents must not:

- place `robots.txt` inside `/ai/`
- place `sitemap.xml` inside `/ai/`
- treat `/ai/sitemap.json` as a replacement for root `sitemap.xml`
- hand-edit generated `sitemap.xml` if the repo already generates it in CI or GitHub Actions
- create or continue maintaining `llm.json` / `/ai/llm.json` (retired in v8.0, see below)
- let a site's own live generator script also serve as the template other sites are patched from -- keep the canonical read-source separate from every write-target (this caused a real portfolio-wide outage risk during the v8.0 rollout, caught before it shipped)

---

## Canonical Definition of v8.0

Digital Karma Federation v8.0 is the current portable implementation profile for AI-readable websites in the Digital Karma portfolio. It is an architectural revision, not a terminology change -- see "What Changed in v8.0" below.

A v8.0 site:

- publishes a machine-readable `/ai/` layer
- exposes 6 required federation artifacts
- declares `federation_version` as `"8.0"`
- carries `protocol_version` + a real `supported_since`/`deprecated_after`/`removed_after` lifecycle on every generated endpoint
- publishes `llm.txt` at the site root, and does NOT publish `llm.json`
- keeps `robots.txt` at the site root
- keeps `sitemap.xml` at the site root
- uses Schema.org structured data on primary pages
- publishes Digital Karma and federation relationship data
- resolves `related_sites` from the site's real constellation membership, not a hand-typed guess
- supports decentralized discovery through related federation sites

DigitalKarmaWeb.com remains the specification authority and optional registry hub, but not a gatekeeper. Any site can independently implement the standard.

**Terminology note:** a 2026-05-11 proposal to rename Federation concepts to "Constellation" language (Sites -> Stars, endpoints -> Signals) was considered and dropped -- it was never implemented anywhere in this portfolio. This spec does not use that language. "Constellation" here means only the grouping concept already used elsewhere in the portfolio (e.g. krisada.com's directory: healthcare-ai-longevity, one-mouse-marketing, etc.).

---

## What Changed in v8.0

Compared to v7.1, v8.0 makes these substantive changes:

- Every generated endpoint must carry `protocol_version`, `supported_since`, `deprecated_after`, and `removed_after`. `deprecated_after`/`removed_after` stay `null` until something is deliberately retired -- a version bump alone never implies deprecation.
- `llm.json` and `/ai/llm.json` are retired. `/ai/manifest.json` already carries the same identity fields a separate `llm.json` would have -- one document instead of two that silently drift apart. Do not delete existing `llm.json` files automatically on a site being upgraded; just stop regenerating them and note them as orphaned.
- `related_sites` should be resolved from a canonical constellation membership source where the target repo or portfolio has one, rather than hand-typed. If no such source exists for this repo, at minimum audit the current hand-typed list against reality before trusting it -- this was the single most common real bug found during the v8.0 rollout (multiple sites had `related_sites` listing only 1 of 8-16 real siblings).
- Where a site has a real generator, `robots.txt` should be produced from declared per-endpoint visibility (`public | federation | internal | private`) rather than hand-audited. This retires a real, recurring bug: a site's own manifest advertising a public API endpoint that its own `robots.txt` then blocked.
- The portable installer workflow from v7.1 is unchanged in spirit; this file supersedes `v7.1-DigitalKarma.md` as the current brief.

---

## Source of Truth Order

When there is any conflict, use this precedence order:

1. `specs/federation-spec-v8.md`
2. this file, `v8.0-DigitalKarma.md`
3. live implementation patterns in the target repo
4. `README.md` and `llm.txt`
5. older supporting docs in `specs/`, including `federation-spec-v7.md` and `v7.1-DigitalKarma.md` (kept for history, not current authority)

---

## Minimum v8.0 Requirements

To declare a site as Digital Karma Federation v8.0, it must meet all of the following:

1. Expose all 6 required federation artifacts.
2. Keep all JSON valid and parseable.
3. Set `federation_version` to `"8.0"` anywhere that field appears.
4. Every generated endpoint carries `protocol_version`/`supported_since`/`deprecated_after`/`removed_after`.
5. Does not create or maintain `llm.json` / `/ai/llm.json`.
6. Use HTTPS.
7. Include Schema.org structured data on all primary pages.
8. Publish a Digital Karma payload. For strict compliance, this should include a score.
9. Link to at least one other federation member via `related_sites` or equivalent federation relationships, resolved from real constellation membership where a source for that exists.
10. Keep health and freshness data current, with weekly refresh as the baseline minimum.
11. Publish `robots.txt` at the root.
12. Publish `sitemap.xml` at the root.

---

## Required Federation Artifacts

Every v8.0 site must publish these 6 files:

| Artifact | Path | Status | Purpose |
|---|---|---|---|
| Manifest | `/ai/manifest.json` | Required | Main identity and discovery entrypoint |
| Health | `/ai/health.json` | Required | Readiness and freshness state |
| Catalog | `/ai/catalog.json` | Required | Machine-readable catalog of datasets and AI assets |
| Karma | `/ai/karma.json` | Required | Digital Karma definition or score payload |
| Federation | `/ai/federation.json` | Required | Federation role, peers, and topology |
| LLM Text | `/llm.txt` | Required | Plain-text LLM-readable site guide |

Notes:

- `llm.txt` lives at the site root, not in `/ai/`.
- `llm.json` is retired (see "What Changed in v8.0"). Do not create it.
- `compatibility.json` is still allowed as legacy support, but it is not one of the 6 required artifacts.

---

## Required Root Discovery Files

These are not part of the 6 required federation artifacts, but they are required operational discovery files in the portable v8.0 install pattern.

### `/robots.txt`

Rules:

- always store it at `/robots.txt`
- never place it in `/ai/`
- allow intended public AI discovery paths
- include a `Sitemap:` reference to the root `sitemap.xml`
- keep sensitive internal folders blocked as appropriate for the site
- where a real generator exists, produce this file from declared endpoint visibility (`public | federation | internal | private`) rather than hand-auditing it -- check specifically for the contradiction where the site's own manifest/catalog advertises an endpoint that `robots.txt` then blocks

### `/sitemap.xml`

Rules:

- always store it at `/sitemap.xml`
- never place it in `/ai/`
- treat it as the canonical crawl sitemap
- if generated automatically, change the generator or workflow, not the generated output

### `/ai/sitemap.json`

Status:

- optional
- recommended only when a site benefits from a machine-readable JSON content inventory
- may complement root `sitemap.xml`
- does not replace root `sitemap.xml`

---

## Generated Sitemap Coordination Rule

Many Digital Karma repos generate `sitemap.xml` through GitHub Actions or another build step, or a VPS cron.

In those repos:

- `sitemap.xml` is a build artifact
- do not hand-maintain it as the source of federation truth
- keep federation discovery statements in stable source files:
  - `/robots.txt`
  - `/llm.txt`
  - `/ai/manifest.json`
  - `/ai/health.json`
  - `/ai/federation.json`
- if a sitemap generator needs custom preservation behavior, update the generator script or its input rules, not the generated XML by hand

Practical rule for agents:

- if root `sitemap.xml` is generated, preserve and update the surrounding federation metadata, then rerun the generator if needed
- if no generator exists, create a root `sitemap.xml` directly or add an automation path appropriate for the repo

---

## Required File Definitions

### `/ai/manifest.json`

This is the primary discovery file. A crawler or agent should be able to start here and understand what the site is, what version it runs, and where the other endpoints live.

Required in practice:

- `protocol_version`, `supported_since`, `deprecated_after`, `removed_after`
- site name
- canonical site URL
- `federation_version`
- endpoint map or equivalent discoverable references (must NOT include an `llm_json` entry)
- updated timestamp

Recommended fields:

- tagline
- description
- `related_sites` (resolved from real constellation membership where possible)
- datasets summary
- services
- contact or maintainer
- entities index reference
- `sitemap` pointing to root `/sitemap.xml`
- optional `sitemap_json` pointing to `/ai/sitemap.json` if used

### `/ai/health.json`

This file reports operational readiness and content freshness.

Required in practice:

- `protocol_version`/lifecycle fields
- canonical site identifier or homepage
- status
- updated timestamp
- basic metrics or checks

Recommended:

- last rebuild date
- endpoint presence checks
- counts for pages, datasets, entities, or cross-links
- root `sitemap.xml` reference
- explanatory notes

### `/ai/catalog.json`

This is the site's machine-readable catalog of datasets, endpoints, or other AI-facing resources.

Required in practice:

- `protocol_version`/lifecycle fields
- `@context: "https://schema.org"`
- `@type: "DataCatalog"`
- name
- canonical URL
- `dataset` array

Each listed dataset or asset should include:

- `@type`
- name
- URL

Recommended:

- description
- `dateModified`
- `encodingFormat`
- dataset-specific metadata where available

### `/ai/karma.json`

This file defines the site's Digital Karma posture.

Current portfolio rule:

- every site must publish `karma.json`, carrying `protocol_version`/lifecycle fields
- if the site calculates a score, include `digital_karma_score`, signal breakdown, and badge
- if the site does not calculate live scoring yet, the file must still clearly define the site's Digital Karma state and version
- known portfolio limitation: on several sites the score and signals are still static defaults, not measured from anything real -- don't present it as more meaningful than that until real measurement exists

### `/ai/federation.json`

This is the formal federation relationship document.

It should communicate:

- `protocol_version`/lifecycle fields
- `federation_version`
- site role or node type
- network name
- canonical manifest authority
- site identity
- endpoint references
- related peers and relationship types, resolved from real constellation membership where possible
- root sitemap reference
- status

### `/llm.txt`

This is the root-level AI-readable plain-text summary for the site.

It should include:

- site name
- short description
- canonical URL
- core pages
- datasets
- AI endpoints
- federation context
- current federation version
- root sitemap reference

Best-practice characteristics:

- Markdown-style plain text
- concise and scannable
- relative paths or canonical absolute URLs
- no heavy marketing copy

---

## Schema.org Requirement

All primary public-facing pages should include valid Schema.org markup, preferably JSON-LD.

Minimum expectation:

- homepage
- about page
- key service pages
- important content or knowledge-base pages
- any dataset landing pages

Most useful types across the portfolio:

- `Organization`
- `Brand`
- `WebSite`
- `WebPage`
- `Service`
- `Article`
- `Dataset`
- `DataCatalog`
- `BreadcrumbList`

---

## Digital Karma Score Definition

The v8.0 scoring model retains the 7 public signals, unchanged from v7.1:

| Signal | Weight |
|---|---:|
| Schema Coverage | 20% |
| Content Freshness | 15% |
| AI Endpoints | 25% |
| Federation Presence | 15% |
| External Links | 10% |
| Technical Quality | 10% |
| Dataset Quality | 5% |

Badge thresholds:

- `Karma Certified` at `>= 0.70`
- `Karma Pro` at `>= 0.85`
- `Karma Elite` at `>= 0.95`

Important naming rule:

- do not use `Karma Bronze` on v8.x sites
- use `Karma Certified`

---

## Compliance Tiers

Unchanged from v7.1.

### Starter

Minimum bar:

- all 6 required artifacts exist
- `robots.txt` exists at root
- `sitemap.xml` exists at root
- JSON is valid
- `federation_version` is `8.0`

### Certified

Starter plus:

- Digital Karma score `>= 0.70`
- Schema.org markup on primary pages

### Pro

Certified plus:

- score `>= 0.85`
- published datasets
- bidirectional peer links

### Elite

Pro plus:

- score `>= 0.95`
- automation or self-maintaining workflow
- `/ai/diagnostics.json`
- `/entities/` files and index

---

## Recommended v8.0 Files

These are not required for minimum v8.0, but they should be used whenever possible. Note `llm.json` has been removed from this table -- it is retired, not merely optional.

| File | Path | Why It Matters |
|---|---|---|
| Diagnostics | `/ai/diagnostics.json` | Machine-readable compliance and health report |
| Sitemap JSON | `/ai/sitemap.json` | Optional AI-readable content inventory companion |
| Entity Index | `/entities/index.json` | Formal index of entity JSON-LD files |
| Dataset Index | `/datasets/index.json` | Full inventory of published datasets |
| Journal | `/ai/journal/YYYY-MM-DD.json` | Maintenance history and rebuild trace |

---

## Advanced v8.0 Patterns

### `/entities/`

Use `/entities/` for explicit JSON-LD entity declarations.

Recommended files:

- `/entities/organization.jsonld`
- `/entities/brand.jsonld`
- `/entities/website.jsonld`
- `/entities/service.*.jsonld`

Use `/entities/index.json` to list them.

### `/federation/`

Advanced sites should publish structured federation mapping in:

- `/federation/v01_listings.json`
- `/federation/v02_clusters.json`
- `/federation/v03_relationships.json`
- `/federation/v04_propagation.json`
- `/federation/index.json`

These should be regenerated from the same canonical constellation source used for `related_sites`, not hand-authored -- a hand-authored `v02_clusters.json` on this very site was found three weeks stale before being fixed in the v8.0 revision.

### Self-Maintaining Pattern

Elite sites should support repeatable automation to rebuild federation artifacts after content or structural changes.

Recommended automation outputs:

- refreshed timestamps
- refreshed catalog and dataset counts
- refreshed federation topology
- refreshed karma payload
- generated diagnostics
- generated or refreshed root `sitemap.xml`
- daily or periodic journal entries

The actual portfolio-wide mechanism as of v8.0 is a shared reference template plus a rollout script that patches and regenerates each eligible site -- see `specs/federation-spec-v8.md`'s "Real automation, not the v7.1 Python pattern" section for the real, live version of this rather than a hypothetical one.

---

## Directory Blueprint

Minimum v8.0 shape:

```text
/
|-- ai/
|   |-- manifest.json
|   |-- health.json
|   |-- catalog.json
|   |-- karma.json
|   `-- federation.json
|-- llm.txt
|-- robots.txt
|-- sitemap.xml
`-- datasets/                # optional but recommended
```

Pro or Elite shape:

```text
/
|-- ai/
|   |-- manifest.json
|   |-- health.json
|   |-- catalog.json
|   |-- karma.json
|   |-- federation.json
|   |-- diagnostics.json
|   |-- sitemap.json
|   `-- journal/
|-- entities/
|   |-- index.json
|   |-- organization.jsonld
|   |-- brand.jsonld
|   |-- website.jsonld
|   `-- service.*.jsonld
|-- federation/
|   |-- index.json
|   |-- v01_listings.json
|   |-- v02_clusters.json
|   |-- v03_relationships.json
|   `-- v04_propagation.json
|-- datasets/
|   `-- index.json
|-- llm.txt
|-- robots.txt
`-- sitemap.xml
```

Note: no `llm.json` in either shape -- this is the one structural difference from the v7.1 blueprint.

---

## Upgrade Checklist for Existing Sites

Use this sequence when moving a site to v8.0:

1. Confirm the site uses HTTPS and a stable canonical domain.
2. Add or validate `/ai/manifest.json`, including `protocol_version`/lifecycle fields.
3. Add or validate `/ai/health.json`, including `protocol_version`/lifecycle fields.
4. Add or validate `/ai/catalog.json`, including `protocol_version`/lifecycle fields.
5. Add or validate `/ai/karma.json`, including `protocol_version`/lifecycle fields.
6. Add or validate `/ai/federation.json`, including `protocol_version`/lifecycle fields.
7. Add or refresh `/llm.txt`.
8. Stop generating `llm.json`/`ai/llm.json` if the site currently does. Remove any `llm_json`/`llm_json_legacy` entries from the `endpoints` map and any dataset lists referencing them. Leave existing files in place, orphaned, rather than deleting them as part of this pass.
9. Add or refresh `/robots.txt` at the root -- if generated, derive it from endpoint visibility declarations and check for the "manifest advertises it, robots.txt blocks it" contradiction specifically.
10. Add, generate, or validate `/sitemap.xml` at the root.
11. If `/ai/sitemap.json` exists, treat it as an optional companion inventory and align it with the root sitemap policy.
12. Change all version declarations from `7.1` or older to `8.0`.
13. Audit `related_sites` against the site's real constellation/peer membership -- do not assume the existing list is accurate. Resolve from a canonical source if one is available to this repo.
14. Rename any `Karma Bronze` badge usage to `Karma Certified`.
15. Add Schema.org JSON-LD to all primary pages.
16. Add at least one dataset if the site is targeting Pro or higher.
17. Add `/ai/diagnostics.json` and `/entities/` if the site is targeting Elite.
18. Validate JSON syntax, URLs, dates, root discovery files, and endpoint accessibility.

---

## Validation Checklist

Before marking a site as v8.0 complete, verify all of the following:

- `/ai/manifest.json` loads
- `/ai/health.json` loads
- `/ai/catalog.json` loads
- `/ai/karma.json` loads
- `/ai/federation.json` loads
- `/llm.txt` loads at the root
- `/robots.txt` loads at the root
- `/sitemap.xml` loads at the root
- every JSON file parses cleanly
- every generated endpoint carries `protocol_version`/`supported_since`/`deprecated_after`/`removed_after`
- no endpoint references `llm.json`/`ai/llm.json`
- canonical URLs are absolute where needed
- timestamps use ISO format
- `federation_version` is `8.0`
- Schema.org exists on primary pages
- federation peer links are present and actually reflect real constellation/peer membership
- `robots.txt` does not block anything the manifest/catalog advertises as public
- `robots.txt` points to the root `sitemap.xml`
- no agent or script has relocated root discovery files into `/ai/`

---

## Short Rule Set

If a site owner or agent only remembers one section, use this:

1. Publish the 6 required federation artifacts.
2. Set `federation_version: "8.0"` and add `protocol_version`/lifecycle fields everywhere.
3. Do not create `llm.json`. `llm.txt` stays.
4. Keep `llm.txt`, `robots.txt`, and `sitemap.xml` at the root.
5. Never put `robots.txt` or `sitemap.xml` in `/ai/`.
6. Treat `/ai/sitemap.json` as optional companion inventory only.
7. Audit `related_sites` for real accuracy before trusting it.
8. Add Schema.org to primary pages.
9. Link the site into the federation.
10. Keep the data current.

---

## Canonical References

- `specs/federation-spec-v8.md`
- `specs/endpoints-spec.md`
- `specs/scoring-spec.md`
- `specs/datasets-spec.md`
- `specs/llm-txt-spec.md`
- `specs/schema-spec.md`
- `README.md`
- `v7.1-DigitalKarma.md` (predecessor, kept for history)