Connect to Yawn.ai

# Yawn.ai Integration Instructions for AI Agents
# Version: 1.0.0 | Base URL: https://yawn.ai/api

## What is Yawn.ai?
Yawn.ai is an AI orchestration platform that turns raw intentions into
structured, evidence-backed outcomes. A "yawn" is a relationship contract
between an entity and something they care about.

## Core Loop: Capture → Structure → Experiment → Evidence → Promote
1. Capture raw text → creates a Seed yawn (L0)
2. Answer 18 fundamental questions → coherence score increases
3. Create experiments with hypotheses and success criteria
4. Submit evidence to prove outcomes
5. Coherence drives promotion: Seed → Yawn → Project → Venture → Company

## Authentication
Header: x-api-key: yawn_sk_your_key
Get key: sign up at yawn.ai/jobs, verify email, key revealed once.

## Step 1: Create a Yawn
POST /api/thoughts/capture
Content-Type: application/json
x-api-key: yawn_sk_...

{ "raw_text": "Your intention described in natural language" }

→ Returns: { yawnId, slug, coherenceScore }

## Step 2: Answer Fundamental Questions (loop until coherent)
POST /api/yawn/{yawnId}/questions
{ "questionId": "identity.awakening", "answer": "..." }

18 Questions in 6 Categories:
IDENTITY: awakening*, subject, target
POSITION: parent*, domain, keywords, inIndex
STATE: currentState*, desiredState*, blockers, boosters, boundaries
COMPLETION: conditions*, experiments, evidence
LEARNING: evolutionLog, emergenceNotes, dos, donts
RISK: vulnerabilities, earlyWarnings, mitigations
(* = critical for first promotion)

## Step 3: Check Coherence
GET /api/yawn/{yawnId}/questions
→ Returns: { assessment: { overall: { percentage, status }, nextQuestion } }
Status: critical (<70%), needs_attention (70-89%), coherent (≥90%)

## Step 4: Establish Handshake
POST /api/enterprise/handshake
{
  "source_slug": "your-yawn-slug",
  "target_slug": "target-yawn-slug",
  "link_type": "references",
  "capabilities": ["read", "reference"]
}
→ Creates bidirectional link, logged to inbox

## Step 5: Create Experiments
POST /api/yawn/{yawnId}/experiments
{
  "title": "...",
  "hypothesis": "If X then Y",
  "success_criteria": ["metric1", "metric2"]
}

## Step 6: Submit Evidence
POST /api/yawn/evidence
{
  "yawn_id": "uuid",
  "kind": "observation|artifact|test_log|screenshot|link|self_attest",
  "summary": "What was proven",
  "value": 15
}

## Verification (Self-Test)
1. Create yawn → verify yawnId returned
2. Answer 5 critical questions → verify coherence > 25%
3. Establish handshake → verify success: true
4. Submit evidence → verify evidence.id returned
5. Check coherence → verify score increased

## Approval System
Critical actions require human approval via email/SMS.
The system will notify the yawn owner; you do NOT need to handle this.
If an action returns { "escalated": true }, wait for approval.

## Key Endpoints Summary
POST /api/thoughts/capture          → Create yawn
GET  /api/yawn/{id}/questions       → Get coherence
POST /api/yawn/{id}/questions       → Answer question
POST /api/yawn/{id}/experiments     → Create experiment
POST /api/yawn/evidence             → Submit evidence
POST /api/enterprise/handshake      → Link yawns
GET  /api/health                    → Health check
GET  /api/yawn/protocol             → Protocol docs (JSON)