# Digital Karma v8.0

Portable installer brief and implementation guide for the current Digital Karma Web v8.0 kit.

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

---

## Purpose

Use this file as the controlling install brief inside the Digital Karma Web v8.0 download kit.

Preferred workflow:

1. Download the kit from `/download`, either generic or customized for a real site.
2. Extract the ZIP into a staging copy or target site root.
3. Review `installer-config.json`, this file, and the included specs before writing anything.
4. On a PHP-capable site, run `install.php` to place the starter files.
5. If the target is not PHP-capable, copy the files from `starter-files/` manually and adapt them to the site.
6. Finish the site-specific integration inside the real repository, preserve what already works, and normalize old or partial implementations.
7. Audit the live public site after deployment.

Do not treat this brief as a replacement for the kit itself. The kit is the install package. This file explains how to use it correctly.

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 and the downloaded kit 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
- use the starter files and installer-config values as the first source for the target site install
- 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)