# Vision Quest Digital Journals API

The Vision Quest Digital Journals API exposes ceremonial journaling scaffolds
for Native American vision quest traditions. Each journal includes
phase-by-phase prompts, integration timelines, safeguarding guidance, and
recommended digital artefacts to support ethical, well-documented practice.

## Endpoints

### `GET /v1/mythology/vision-quests`

Returns a catalogue of available vision quest journals plus metadata for client
discovery.

> **BFF proxy:** The BFF exposes this endpoint verbatim, forwarding to the
> content service when available and falling back to the same curated dataset if
> the downstream dependency is unavailable. Use the BFF base URL (e.g.,
> `https://api.example.org`) when calling from client applications.

```json
{
  "journals": [
    {
      "slug": "lakota",
      "tradition": "Lakota Sioux",
      "phases": 4,
      "integrationHighlights": [
        "Grounding with food, water, and touch",
        "Begin translating symbols into commitments",
        "Seal the first moon cycle of integration"
      ],
      "digitalArtifacts": [
        "audio-medicine-song",
        "dawn-light-photography",
        "dream-symbol-sketch",
        "heartbeat-drum-loop"
      ],
      "safeguarding": {
        "checkIns": [
          "Daily sunrise physiological check (pulse, hydration, emotional state)",
          "Midnight safety log with weather, wildlife, and emotional rating",
          "Post-return weekly integration check with mentor for first moon"
        ],
        "emergencyProtocols": [
          "If disorientation persists after return, notify designated elder immediately",
          "Activate emergency beacon if experiencing hypothermia or severe dehydration",
          "Document any medical interventions in journal with timestamps"
        ]
      },
      "eldersReview": [
        "Upload summary for elder council within 48 hours for symbolic interpretation support",
        "Invite elder annotations directly onto integration board artifacts",
        "Schedule storytelling circle and link journal artifacts for shared reflection"
      ]
    }
  ],
  "metadata": {
    "count": 2,
    "generated_at": "2025-01-01T00:00:00.000Z",
    "documentation": "docs/vision-quest-digital-journals.md",
    "sources": [
      "PaganismEarthSpirituality.NatureMysticismPractices",
      "WorldMythology.NativeAmericanTraditions"
    ]
  }
}
```

### `GET /v1/mythology/vision-quests/:slug/journal`

Retrieves the full journal blueprint for a specific tradition. The `slug` path
parameter corresponds to the catalogue `slug` (e.g., `lakota` or `plains`).

Response payload:

- Content service is the source of truth; the BFF returns the upstream response
  and supplies a parity fallback mirroring the structure below if the content
  service cannot be reached.

- `phases`: Ordered ceremony phases with prompts and suggested digital
  practices.
- `integrationTimeline`: Day-by-day integration checkpoints.
- `digitalArtifacts`: Recommended media captures to support archival continuity.
- `safeguarding`: Safety check-ins and emergency protocols.
- `eldersReview`: Steps for elder council accountability.
- `supportingAnimalSpirits`: Animal medicine guidance for the quest.
- `preparationChecklist`: Pre-quest preparation steps derived from ceremonial
  teachings.
- `integrationHighlights`: Core focus reminders extracted from the integration
  timeline.

```json
{
  "slug": "lakota",
  "tradition": "Lakota Sioux",
  "phases": [
    {
      "id": "preparation",
      "title": "Purification & Intention Setting",
      "focus": [
        "Clarify core question for the spirits",
        "Document teachings from supporting elders",
        "Track physical preparations and fasting protocol"
      ],
      "prompts": [
        "What life threshold am I preparing to cross during this quest?",
        "Which teachings from the sweat lodge or elders feel most alive in my body today?",
        "What offerings am I taking to the hill, and what do they symbolize?"
      ],
      "digitalPractices": [
        "Create a voice memo capturing elder teachings verbatim",
        "Upload a photo of sacred bundle with annotations for each item",
        "Log fasting milestones with body sensations and mood tracking"
      ]
    }
  ],
  "integrationTimeline": [
    {
      "day": "Return Day",
      "focus": [
        "Grounding with food, water, and touch",
        "Sharing first words of gratitude with supporters",
        "Capturing raw impressions before analytical mind engages"
      ],
      "actions": [
        "Log first meal and bodily response",
        "Record voice note recounting vision in present tense",
        "Tag supporters who assisted the quest with gratitude notes"
      ],
      "reminders": [
        "Hydrate slowly; note any dizziness or sensory overload",
        "Pause before interpreting the vision—capture sensation first"
      ]
    }
  ],
  "digitalArtifacts": [
    "audio-medicine-song",
    "dawn-light-photography",
    "dream-symbol-sketch",
    "heartbeat-drum-loop"
  ],
  "safeguarding": {
    "checkIns": [
      "Daily sunrise physiological check (pulse, hydration, emotional state)",
      "Midnight safety log with weather, wildlife, and emotional rating",
      "Post-return weekly integration check with mentor for first moon"
    ],
    "emergencyProtocols": [
      "If disorientation persists after return, notify designated elder immediately",
      "Activate emergency beacon if experiencing hypothermia or severe dehydration",
      "Document any medical interventions in journal with timestamps"
    ]
  },
  "eldersReview": [
    "Upload summary for elder council within 48 hours for symbolic interpretation support",
    "Invite elder annotations directly onto integration board artifacts",
    "Schedule storytelling circle and link journal artifacts for shared reflection"
  ],
  "supportingAnimalSpirits": [
    {
      "name": "Eagle",
      "medicine": "Vision, spiritual connection, courage",
      "characteristics": [
        "Highest flier",
        "Connection to Great Spirit",
        "Messenger"
      ],
      "teachings": "Seeing from highest perspective, spiritual courage, divine connection"
    }
  ],
  "preparationChecklist": [
    "Purification in sweat lodge",
    "Fasting",
    "Prayer with pipe"
  ],
  "integrationHighlights": [
    "Grounding with food, water, and touch",
    "Begin translating symbols into commitments",
    "Seal the first moon cycle of integration"
  ]
}
```

## TypeScript SDK Integration

The Lilith TypeScript SDK now exposes typed helpers for both endpoints, ensuring
clients receive strongly typed catalogue metadata and detailed journal
blueprints. Example usage:

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

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

// Fetch catalogue with safeguarding guidance and integration highlights
const catalogue = await client.listVisionQuestJournals();
catalogue.journals.forEach((journal) => {
  console.log(`${journal.tradition}: ${journal.integrationHighlights[0]}`);
});

// Retrieve the full journal blueprint for a specific tradition
const lakotaJournal = await client.getVisionQuestJournal('lakota');
console.log(lakotaJournal.phases.map((phase) => phase.title));
```

## Change Log

- **2025-02-XX** — Initial launch: catalogue and journal retrieval endpoints
  with safeguarding, integration, and metadata scaffolding.
