# Oracle & Divination Systems API

The Oracle & Divination Systems API exposes ceremonial blueprints for
traditional and contemporary divination practices. Each blueprint provides core
mechanics, guided reading protocols, AI augmentation modes, and integration
prompts to support ethical, well-documented practice.

## Endpoints

### `GET /v1/divination/oracles`

Returns a catalogue of available divination systems with summary metadata for
discovery.

> **BFF proxy:** Access via the BFF base URL (e.g.,
> `https://api.example.org/v1/divination/oracles`) to benefit from built-in
> fallbacks and observability. The BFF forwards catalogue requests to the
> content service and transparently falls back to the curated dataset if the
> downstream dependency is unavailable.

Example response:

```json
{
  "systems": [
    {
      "slug": "tarot",
      "name": "Tarot",
      "tradition": "Esoteric Western Mystery Schools",
      "type": "card",
      "primaryTool": "78-card tarot deck (Major & Minor Arcana)",
      "digitalSupports": [
        "Sequence-based shuffle visualizer",
        "Sigil-based intention recorder",
        "Spread annotator",
        "Archetype cross-reference library",
        "Narrative weaving canvas",
        "Integration reminder scheduler"
      ]
    }
  ],
  "metadata": {
    "count": 4,
    "generated_at": "2025-01-01T00:00:00.000Z",
    "documentation": "docs/oracle-divination-systems.md",
    "sources": [
      "WorldMythology.ClassicalDivinationCorpus",
      "MysticPractices.OracularTraditions"
    ]
  }
}
```

### `GET /v1/divination/oracles/:slug`

Retrieves the full divination workflow for a specific system, including reading
protocols, prompt templates, and digital augmentation guidance. Slugs include
`i-ching`, `tarot`, `runes`, and `dream-oracle`.

```json
{
  "slug": "i-ching",
  "name": "I Ching",
  "tradition": "Classical Chinese",
  "origins": {
    "region": "Zhou Dynasty China",
    "era": "c. 1000 BCE",
    "lineage": "King Wen, Duke of Zhou, Confucian commentaries"
  },
  "type": "casting",
  "primaryTool": "Yarrow stalks or three coins",
  "supportTools": [
    "Hexagram charts",
    "Line change tracker",
    "Commentary corpus navigator"
  ],
  "coreMechanics": [
    "64 hexagrams derived from broken and solid lines",
    "Dynamic line changes indicating present transformations",
    "Nuclear hexagrams revealing hidden influences"
  ],
  "interpretivePrinciples": [
    "Balance between yin and yang polarities",
    "Movement through changing lines and resultant hexagram",
    "Consultant alignment with Dao through responsive action"
  ],
  "readingProtocols": [
    {
      "phase": "Preparation",
      "focus": [
        "Clarify heart-mind question",
        "Ground in breath and respectful posture"
      ],
      "actions": [
        "Document inquiry with context and emotional tone",
        "Set intention for guidance rather than prediction"
      ],
      "digitalSupports": [
        "Guided breathing timer",
        "Intention journaling template"
      ]
    }
  ],
  "promptTemplates": {
    "guidance": [
      "What changes are emerging through the moving lines, and how do they mirror my inner state?",
      "Where do I witness harmony or resistance between the primary and resulting hexagrams?"
    ],
    "integration": [
      "What concrete action honors the counsel of the Dao within the next six days?",
      "Which relationship or domain requires balancing yin and yang right now?"
    ],
    "reflection": [
      "How did the outcome evolve compared to the counsel received?",
      "What new pattern of change am I noticing after following the guidance?"
    ]
  },
  "digitalAugmentations": {
    "aiReadingModes": [
      "Classical commentary synthesis (Wilhelm, Cheng Yi, Wang Bi)",
      "Somatic integration prompts based on moving lines"
    ],
    "journalingWorkflows": [
      "Hexagram lineage tracker",
      "Change log with seasonal markers"
    ],
    "ritualEnhancements": [
      "Breath paced coin casting animation",
      "Sound bath tuned to trigram resonance"
    ]
  }
}
```

## TypeScript SDK Integration

The Lilith TypeScript SDK exposes strongly typed helpers for both endpoints.

```ts
import { APIClient } from '@lilith/sdk-ts';

const client = new APIClient({ baseUrl: 'https://api.example.org' });

// Catalogue discovery
const catalogue = await client.listDivinationSystems();
catalogue.systems.forEach((system) => {
  console.log(system.name, system.digitalSupports.length);
});

// Detailed blueprint
const runes = await client.getDivinationSystem('runes');
console.log(runes.promptTemplates.guidance[0]);
```

All responses include safeguarding guidance, integration prompts, and AI
augmentation suggestions to support ethical divination practices.
