Content Operations

Overview

Content operations ensure data integrity across entries, protected assets, and curated collections before deployment. This guide covers:

Entry auditing: Runtime validation and inventory checks
Asset coverage: Protected asset validation
Curation validation: Catalog and home featured checks
Doctor tool: Health checks and repair workflows

Entry Auditing

The dex entry audit command validates entries against runtime requirements and inventory models.

Audit Single Entry

dex entry audit --slug tim-feeney

Checks:

✅ Runtime markers: Required DOM elements and auth trio
✅ Script IDs: dex-sidebar-config, dex-manifest, etc.
✅ Token validation: Lookup numbers and asset references
✅ Recording index refs: PDF, bundle, and source URL tokens
✅ Forbidden patterns: No legacy Squarespace/Auth0 blocks
✅ Download tree: Coverage model for all selected buckets

Output (success):

✓ PASS tim-feeney
  runtime checks: 8/8 passed
  inventory: A, B (2 buckets)
  lookup: LOOKUP-0042
  recording index: PDF ✓, Bundle ✓, Source ✓

Output (failure):

✗ FAIL tim-feeney
  runtime: missing required marker: id="scroll-gradient-bg"
  token error: invalid lookup token format
  recording index: bundle token parse error

Audit All Entries

dex entry audit --all

Scans all entries in entries/ directory. Legacy entries (without entry.json) are skipped by default.

Include Legacy Entries

dex entry audit --all --include-legacy

Inventory-Only Check

Validate download tree coverage without runtime checks:

dex entry audit --slug tim-feeney --inventory-only

Useful for:

Checking manifest coverage before publishing
Validating protected asset mappings
Debugging missing download IDs

Custom Paths

Override default file paths:

dex entry audit --all \
  --entries-dir ./custom-entries \
  --catalog-entries-file ./data/custom-catalog.entries.json \
  --catalog-file ./data/catalog.editorial.json \
  --assets-file ./data/protected.assets.json

Entry Doctor

The dex doctor command scans for drift and health issues, with optional repair.

Interactive Doctor (TUI)

dex doctor

Keybindings:

Up/Down: Select entry report
Type: Filter by slug
Ctrl+S: Repair selected entry
Esc: Back to dashboard

The doctor screen shows:

✅ OK entries: No issues detected
⚠️ Warnings: Non-critical drift (stale HTML, missing files)
❌ Errors: Critical failures (missing entry.json, schema invalid)

Non-Interactive Doctor

Run in CI/CD or automated pipelines:

dex doctor

Exits nonzero on errors. Output:

Scanning 15 entries...

✓ tim-feeney: OK
⚠ jane-doe: STALE HTML: index.html differs from deterministic regeneration
❌ old-entry: entry.json missing

Summary: 13 OK, 1 warnings, 1 errors

Common Doctor Warnings

STALE HTML: index.html differs from deterministic regeneration

Cause: The entry’s index.html doesn’t match what would be generated from current entry.json and template.Solution: Repair the entry to regenerate HTML:

dex doctor
# Select the entry and press Ctrl+S to repair

Or use the Update wizard:

dex update
# Select the entry and save

manifest normalization drift detected

Cause: The manifest.json structure doesn’t match current normalization rules (missing buckets, wrong format keys).Solution: Repair normalizes the manifest automatically:

dex doctor
# Repair the entry

auth trio missing from index.html

Cause: The generated HTML is missing required authentication scripts:

/assets/vendor/auth0-spa-js.umd.min.js
/assets/dex-auth0-config.js or /assets/dex-auth-config.js
/assets/dex-auth.js

Solution: Regenerate from the canonical template:

dex doctor
# Repair the entry

legacy Auth0 blocks still present

Cause: Old Auth0 HTML markers remain:


id="btn-login"
id="btn-profile-container"

Solution: Repair removes legacy blocks:

dex doctor
# Repair the entry

bucket X has no populated download ids

Cause: A selected bucket (A, B, C, D, E, X) has no audio or video download IDs in the manifest.Solution: Either:

Populate the bucket in manifest.json:

{
  "audio": {
    "A": {
      "flac": "1a2b3c4d5e6f",
      "wav": "6f5e4d3c2b1a"
    }
  }
}

Remove the bucket from selected buckets:

dex update
# Deselect the unused bucket

looks like URL/path, expected plain drive id

Cause: A manifest entry contains a URL or path instead of a plain Google Drive ID:

{
  "audio": {
    "A": {
      "flac": "https://drive.google.com/file/d/1a2b3c4d5e6f/view"
    }
  }
}

Solution: Extract the plain ID:

{
  "audio": {
    "A": {
      "flac": "1a2b3c4d5e6f"
    }
  }
}

unknown tags: experimental, unreleased

Cause: Entry metadata includes tags not in the tags catalog.Solution: Either:

Remove unknown tags
Add tags to the tags catalog: data/tags.json

metadata.sampleLength missing

Cause: Entry metadata doesn’t include sampleLength.Solution: Add to entry.json:

{
  "metadata": {
    "sampleLength": "3:45",
    "tags": ["percussion", "solo"]
  }
}

Protected Assets Validation

Validate that all active catalog entries have protected asset coverage.

Validate Assets

dex assets validate

Checks:

✅ All active catalog lookups have asset mappings
✅ Asset file references are valid
✅ No orphaned asset entries

Output:

✓ Protected assets validation passed
  Active lookups: 15
  Mapped assets: 15
  Orphaned: 0

Validate Against Remote

dex assets validate --env test

Diff Assets

Compare local vs remote:

dex assets diff --env test

Output:

assets:diff (test) local=d4e5f6 remote=a1b2c3
  +3 added
  -0 removed
  ~2 changed

Catalog and Home Validation

Validate Catalog

dex catalog validate

See Managing the Catalog for details.

Validate Home Featured

dex home validate

Checks:

✅ All featured entries exist in catalog manifest
✅ Featured entries are not archived
✅ Schema compliance

Output:

✓ home:validate passed (3 featured entries)

Set Featured Entries

dex home featured set --entries entry-123,entry-124,entry-125

Reorder Featured Entries

dex home featured reorder --entries entry-125,entry-123,entry-124

Diff and Publish

dex home diff --env test
dex home publish --env test

Linking Entries to Catalog

Link an existing entry to the catalog after creation:

dex entry link \
  --entry tim-feeney \
  --catalog entry-123 \
  --status draft

With metadata:

dex entry link \
  --entry tim-feeney \
  --catalog entry-123 \
  --lookup LOOKUP-0042 \
  --season S2 \
  --performer "Tim Feeney" \
  --instrument "Percussion" \
  --title "Percussion Solo"

Dry Run

dex entry link --entry tim-feeney --catalog entry-123 --dry-run

Content Workflow (Canonical)

Create and validate entry

dex init --from ./seed.json
dex entry audit --slug tim-feeney

Run doctor check

dex doctor

Repair any warnings or errors.

Validate assets and curation

dex assets validate
dex catalog validate
dex home validate

Diff against test

dex assets diff --env test
dex catalog diff --env test
dex home diff --env test

Stop conditions:

Any entry audit FAIL
Doctor shows critical errors
Missing asset coverage for active lookups
Catalog/home validation failures

TUI Managers

Interactive content management:

Entry Audit Manager

dex
# Select "Entry Audit"

Keybindings:

Up/Down: Select inventory row
r: Rerun audit
Esc: Back

Right pane shows download tree/coverage model for selected entry.

Protected Assets Manager

dex
# Select "Assets"

Keybindings:

v: Validate coverage
d/f: Diff test/prod
p/o: Publish test/prod
b/n: Ensure bucket test/prod
r: Reload
Up/Down: Lookup navigation
Esc: Back

Troubleshooting

Entry audit runtime/token failure

Error:

FAIL tim-feeney: invalid token or missing recording index refs

Solution:

Open the Update wizard:
```
dex update
# Select tim-feeney
```
Correct lookup tokens and recording index refs
Save and regenerate
Re-run audit:
```
dex entry audit --slug tim-feeney
```

Preflight fails on missing protected coverage

Error:

preflight failed: missing protected asset coverage (LOOKUP-0042, LOOKUP-0043)

Solution:

Inspect missing coverage:

dex assets validate
dex entry audit --all --inventory-only

Add mappings in protected assets manager (TUI) or manually edit data/protected.assets.json
Re-run preflight:
```
dex release preflight --env prod
```

Best Practices

Audit After Every Change

Run dex entry audit after creating or updating entries

Use Doctor Regularly

Scan for drift weekly: dex doctor

Validate Before Publish

Always run validation commands before deploying

Inventory-Only for Assets

Use --inventory-only to debug asset coverage issues

Get Started

Core Concepts

Guides

Content Operations

Overview

Entry Auditing

Audit Single Entry

Audit All Entries

Include Legacy Entries

Inventory-Only Check

Custom Paths

Entry Doctor

Interactive Doctor (TUI)

Non-Interactive Doctor

Common Doctor Warnings

Protected Assets Validation

Validate Assets

Validate Against Remote

Diff Assets

Catalog and Home Validation

Validate Catalog

Validate Home Featured

Set Featured Entries

Reorder Featured Entries

Diff and Publish

Linking Entries to Catalog

Dry Run

Content Workflow (Canonical)

TUI Managers

Entry Audit Manager

Protected Assets Manager

Troubleshooting

Best Practices

Audit After Every Change

Use Doctor Regularly

Validate Before Publish

Inventory-Only for Assets

Next Steps

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Overview

​Entry Auditing

​Audit Single Entry

​Audit All Entries

​Include Legacy Entries

​Inventory-Only Check

​Custom Paths

​Entry Doctor

​Interactive Doctor (TUI)

​Non-Interactive Doctor

​Common Doctor Warnings

​Protected Assets Validation

​Validate Assets

​Validate Against Remote

​Diff Assets

​Catalog and Home Validation

​Validate Catalog

​Validate Home Featured

​Set Featured Entries

​Reorder Featured Entries

​Diff and Publish

​Linking Entries to Catalog

​Dry Run

​Content Workflow (Canonical)

​TUI Managers

​Entry Audit Manager

​Protected Assets Manager

​Troubleshooting

​Best Practices

Audit After Every Change

Use Doctor Regularly

Validate Before Publish

Inventory-Only for Assets

​Next Steps

Build docs developers (and LLMs) love

Overview

Entry Auditing

Audit Single Entry

Audit All Entries

Include Legacy Entries

Inventory-Only Check

Custom Paths

Entry Doctor

Interactive Doctor (TUI)

Non-Interactive Doctor

Common Doctor Warnings

Protected Assets Validation

Validate Assets

Validate Against Remote

Diff Assets

Catalog and Home Validation

Validate Catalog

Validate Home Featured

Set Featured Entries

Reorder Featured Entries

Diff and Publish

Linking Entries to Catalog

Dry Run

Content Workflow (Canonical)

TUI Managers

Entry Audit Manager

Protected Assets Manager

Troubleshooting

Best Practices

Next Steps