# Cascade Protocol

> Cascade Protocol is a privacy-first, local-only protocol for structured health data. It serializes clinical and wellness records as RDF/Turtle with SHACL validation, bridging clinical standards (FHIR R4, SNOMED CT, LOINC, ICD-10, RxNorm) to machine-readable knowledge graphs. All operations run locally with zero network calls.

## Install

    npm install -g @the-cascade-protocol/cli

## Quick Start

    # Initialize a Pod (local health data store)
    cascade pod init ./my-pod

    # Validate Turtle files against SHACL shapes
    cascade validate ./my-pod

    # View Pod summary with record counts
    cascade pod info ./my-pod

    # Query specific data types
    cascade pod query ./my-pod --medications --conditions --lab-results --json

    # Convert FHIR R4 JSON to Cascade Turtle
    cascade convert patient-bundle.json --from fhir --to turtle

## Supported Data Types

Clinical: Medication, Condition, Allergy, LabResult, VitalSign, Immunization, Coverage, PatientProfile, Encounter, MedicationAdministration, ImplantedDevice, ImagingStudy, ClaimRecord, BenefitStatement
Wellness: HeartRate, BloodPressure, Activity, Sleep, Supplements

## MCP Server (for AI agents)

    cascade serve --mcp

Exposes 6 tools: cascade_pod_read, cascade_pod_query, cascade_validate, cascade_convert, cascade_write, cascade_capabilities

Claude Desktop config:
    {
      "mcpServers": {
        "cascade": {
          "command": "cascade",
          "args": ["serve", "--mcp"],
          "env": { "CASCADE_POD_PATH": "/path/to/pod" }
        }
      }
    }

## Security Model

- Zero external network calls -- all operations are local
- All data stays on local filesystem
- Agent-written data automatically tagged with AIGenerated provenance
- All MCP operations logged to provenance/audit-log.ttl

## Vocabulary Versions

Current stable vocabulary versions (check VOCAB_VERSIONS file in each repo for implementation status):

    core=3.6        # Identity, provenance, Pod structure; FHIR passthrough properties
    health=2.7      # Wellness metrics, device data; Pattern A flat-property vitals
    clinical=1.15   # EHR/clinical records; Encounter, MedicationAdministration, ImplantedDevice, ImagingStudy
    coverage=1.4    # Insurance; ClaimRecord, BenefitStatement, DenialNotice, DenialReasonCode
    checkup=3.3     # Patient-facing summaries
    pots=1.4        # POTS screening; PPP ratio measurements

The authoritative copy of this list is the VOCAB_VERSIONS file in the spec repository
(https://github.com/the-cascade-protocol/spec). This block is GENERATED from that file
by scripts/generate-llms.sh and checked by scripts/check-llms.sh; edit VOCAB_VERSIONS
and regenerate rather than editing the numbers here.

All vocabularies use namespace pattern: https://ns.cascadeprotocol.org/{vocab}/v1#

## Draft Vocabularies

Published for review under a v1-draft path. These are NOT in VOCAB_VERSIONS, carry
no compatibility guarantee, and may change or be withdrawn without a version bump.
Per-term maturity is carried in the ontologies themselves as vs:term_status
(http://www.w3.org/2003/06/sw-vocab-status/ns#), so a term marked stable inside a
draft vocabulary is safe to build on and one marked unstable is not.

<!-- generated by scripts/generate-llms.sh — do not edit by hand -->
    advisory        https://cascadeprotocol.org/docs/advisory/v1-draft/
    diabetes        https://cascadeprotocol.org/docs/diabetes/v1-draft/
    evidence        https://cascadeprotocol.org/docs/evidence/v1-draft/
    genomics        https://cascadeprotocol.org/docs/genomics/v1-draft/
    workbench       https://cascadeprotocol.org/docs/workbench/v1-draft/
<!-- /generated -->

## Deployment Process for AI Agents

If you are working on Cascade Protocol repositories, follow this sequence for vocabulary changes:

1. spec/ — author vocabulary changes (TTL ontologies, SHACL shapes, JSON-LD contexts)
   - Bump owl:versionInfo, update dct:modified, add changelog comment
   - Update VOCAB_VERSIONS file
   - Tag: vocab/{name}-v{X.Y}

2. cascadeprotocol.org/ — run scripts/sync-from-spec.sh, update HTML docs
   (maintainer-run: the documentation site is not a public repository, so an
   outside contributor completes the other six steps and notes this one)

3. conformance/ — add test fixtures for new classes/properties, tag release

4. cascade-cli/ — run scripts/sync-shapes-from-spec.sh, update VOCAB_VERSIONS

5. sdk-typescript/ — add model files, update predicates and context, update VOCAB_VERSIONS

6. sdk-python/ — add model files, update namespaces and predicates, update VOCAB_VERSIONS

7. cascade-agent/ — update system prompt query patterns, update VOCAB_VERSIONS

Each repo has a CONTRIBUTING.md (how to contribute, what must be green before review),
an AGENTS.md and a CLAUDE.md (repo-specific instructions for coding agents), and a
VOCAB_VERSIONS file tracking implementation status. The full seven-step sequence,
with the artifacts to update at each step and the drift check, is documented in
https://github.com/the-cascade-protocol/spec/blob/main/CONTRIBUTING.md

## Links

- Website: https://cascadeprotocol.org
- Full LLM reference: https://cascadeprotocol.org/llms-full.txt
  Roughly 1.8 MB, larger than most working contexts. It carries the full TTL of
  all six ratified and all five draft vocabularies, regenerated from the spec
  repository and gated on a version check, so it is complete but expensive to
  load. Read this file first and reach for that one when you need the ontologies
  themselves.
- Vocabulary schemas: https://cascadeprotocol.org/docs/cascade-protocol-schemas.md