# Digital Karma v7.1

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

Status: Current working guide
Authority date: 2026-04-21
Canonical authority: `specs/federation-spec-v7.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 v7.1.
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
- have the right files in the wrong locations
- 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 v7.1.

Agents should:

- inspect the repo before editing
- preserve working site-specific content where possible
- normalize paths and file placement to the v7.1 rules below
- update stale version declarations to `7.1`
- avoid inventing alternate endpoint layouts when the standard already defines one

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

---

## Canonical Definition of v7.1

Digital Karma Federation v7.1 is the current portable implementation profile for AI-readable websites in the Digital Karma portfolio.

A v7.1 site:

- publishes a machine-readable `/ai/` layer
- exposes 6 required federation artifacts
- declares `federation_version` as `"7.1"`
- publishes `llm.txt` at the site root
- 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
- 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.

---

## What Changed in v7.1

Compared to v7.0, v7.1 formalizes these rules:

- `robots.txt` must live at the site root
- `sitemap.xml` must live at the site root
- root `sitemap.xml` is the canonical crawl sitemap
- `/ai/sitemap.json` is optional and may exist as a machine-readable companion inventory, but it is not the canonical sitemap location
- if `sitemap.xml` is generated by GitHub Actions or another build step, agents must preserve federation discovery statements in source-controlled files rather than manually patching generated output
- the portable installer workflow is now explicit: this file is meant to be dropped into other repos and used as the upgrade brief for coding agents

---

## Source of Truth Order

When there is any conflict, use this precedence order:

1. `specs/federation-spec-v7.md`
2. this file, `v7.1-DigitalKarma.md`
3. live implementation patterns in the target repo
4. `README.md` and `llm.txt`
5. older supporting docs in `specs/`

Important:

- The spec file remains at `specs/federation-spec-v7.md` because it is still the active major-version authority for the v7 line.
- If an older file disagrees with this v7.1 guide on root placement of `robots.txt` or `sitemap.xml`, v7.1 wins.

---

## Minimum v7.1 Requirements

To declare a site as Digital Karma Federation v7.1, 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 `"7.1"` anywhere that field appears.
4. Use HTTPS.
5. Include Schema.org structured data on all primary pages.
6. Publish a Digital Karma payload. For strict compliance, this should include a score.
7. Link to at least one other federation member via `related_sites` or equivalent federation relationships.
8. Keep health and freshness data current, with weekly refresh as the baseline minimum.
9. Publish `robots.txt` at the root.
10. Publish `sitemap.xml` at the root.

---

## Required Federation Artifacts

Every v7.1 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/`.
- `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 v7.1 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

### `/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.

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:

- site name
- canonical site URL
- `federation_version`
- endpoint map or equivalent discoverable references
- updated timestamp

Recommended fields:

- tagline
- description
- `related_sites`
- 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:

- 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:

- `@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`
- 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

### `/ai/federation.json`

This is the formal federation relationship document.

It should communicate:

- `federation_version`
- site role or node type
- network name
- canonical manifest authority
- site identity
- endpoint references
- related peers and relationship types
- 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 v7.1 scoring model retains the 7 public signals:

| 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 v7.x sites
- use `Karma Certified`

---

## Compliance Tiers

### Starter

Minimum bar:

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

### 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 v7.1 Files

These are not required for minimum v7.1, but they should be used whenever possible:

| File | Path | Why It Matters |
|---|---|---|
| Diagnostics | `/ai/diagnostics.json` | Machine-readable compliance and health report |
| LLM JSON | `/llm.json` | Structured companion to `llm.txt` |
| 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 v7.1 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`

### 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

---

## Directory Blueprint

Minimum v7.1 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
```

---

## Upgrade Checklist for Existing Sites

Use this sequence when moving a site to v7.1:

1. Confirm the site uses HTTPS and a stable canonical domain.
2. Add or validate `/ai/manifest.json`.
3. Add or validate `/ai/health.json`.
4. Add or validate `/ai/catalog.json`.
5. Add or validate `/ai/karma.json`.
6. Add or validate `/ai/federation.json`.
7. Add or refresh `/llm.txt`.
8. Add or refresh `/robots.txt` at the root.
9. Add, generate, or validate `/sitemap.xml` at the root.
10. If `/ai/sitemap.json` exists, treat it as an optional companion inventory and align it with the root sitemap policy.
11. Change all version declarations from `7.0`, `6.1`, or older to `7.1`.
12. Rename any `Karma Bronze` badge usage to `Karma Certified`.
13. Add `related_sites` or explicit federation peer relationships.
14. Add Schema.org JSON-LD to all primary pages.
15. Add at least one dataset if the site is targeting Pro or higher.
16. Add `/ai/diagnostics.json` and `/entities/` if the site is targeting Elite.
17. Validate JSON syntax, URLs, dates, root discovery files, and endpoint accessibility.

---

## Validation Checklist

Before marking a site as v7.1 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
- canonical URLs are absolute where needed
- timestamps use ISO format
- `federation_version` is `7.1`
- Schema.org exists on primary pages
- federation peer links are present
- `robots.txt` does not block intended AI discovery
- `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: "7.1"`.
3. Keep `llm.txt`, `robots.txt`, and `sitemap.xml` at the root.
4. Never put `robots.txt` or `sitemap.xml` in `/ai/`.
5. Treat `/ai/sitemap.json` as optional companion inventory only.
6. Preserve federation discovery statements in source files when `sitemap.xml` is generated.
7. Add Schema.org to primary pages.
8. Link the site into the federation.
9. Keep the data current.

---

## Canonical References

- `specs/federation-spec-v7.md`
- `specs/endpoints-spec.md`
- `specs/scoring-spec.md`
- `specs/datasets-spec.md`
- `specs/llm-txt-spec.md`
- `specs/schema-spec.md`
- `README.md`
- `llm.txt`