> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.loreos.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.loreos.app/_mcp/server.

# Research, evidence, and social handoff

LoreOS Core can help a Social Presence or Lore Creators app decide whether a desired post
fits a character's current state. It does not write captions, publish posts, or pretend a
character visited somewhere without evidence.

The boundary is:

```text
Social app proposes a content goal
  -> LoreOS checks fit and evidence requirements
  -> human/operator evidence can be submitted
  -> review and commit materialize public-safe character state
  -> Social app reads the public slice
  -> Social app writes captions/posts using only claim-safe facts
```

## What LoreOS does

* Accepts content intents from an external app.
* Returns deterministic fit feedback and missing evidence requirements.
* Creates mission candidates for a human/operator to verify.
* Stores research, field, brand, receipt, or published-post evidence.
* Gates evidence before it becomes character state.
* Exposes a public slice for downstream social planning.

## What the Social app does

* Chooses the channel, format, creative angle, cadence, and publish workflow.
* Collects field evidence from the human operator.
* Generates captions, reels, stories, thumbnails, and approvals.
* Handles brand disclosures, usage rights, payouts, and Instagram publishing.

## Key boundary

> **Warning**
>
> Research is not lived memory. A mission is not a visit. A published post is not proof of
> a visit. First-person experience claims need first-hand or receipt-backed evidence.
> `POST /v1/characters/{slug}/published-posts` records publication only; it rejects
> `claim_basis=first_hand_visit` and `claim_basis=receipt_verified`.

## Public API flow

This is the externally supported flow. Use your own character slug from the
[Quickstart](https://docs.loreos.app/getting-started/quickstart).

```bash
export LOREOS_BASE="${LOREOS_BASE:-https://api.loreos.app}"
export LOREOS_KEY="ck_..."
export CHARACTER_SLUG="yura"
```

### 1. Submit a content intent

```bash
INTENT_JSON="$(curl -sS -X POST "$LOREOS_BASE/v1/characters/$CHARACTER_SLUG/content-intents" \
  -H "Authorization: Bearer $LOREOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "intent_type": "instagram_post",
    "title": "Cafe A visit post",
    "desired_outcome": "Publish a grounded first-hand cafe post.",
    "target_audience": "local cafe fans",
    "content_brief": "Show a verified cafe visit through the character point of view.",
    "target_entities": [{"type": "place", "name": "Cafe A"}],
    "required_claims": [{"claim": "The character visited Cafe A"}],
    "evidence_requirements": [{"claim_basis": "first_hand_visit"}]
  }')"
INTENT_ID="$(printf '%s' "$INTENT_JSON" | jq -r '.data.content_intent.id')"
```

### 2. Check fit before evidence exists

```bash
curl -sS -X POST "$LOREOS_BASE/v1/characters/$CHARACTER_SLUG/content-intents/$INTENT_ID/fit" \
  -H "Authorization: Bearer $LOREOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"create_mission_hint": true}' | jq '.data.fit_result'
```

Expected shape:

```json
{
  "fit_status": "needs_evidence",
  "needs": ["verified_evidence_for_required_claims", "field_or_receipt_evidence"],
  "mission_recommendation": {
    "mission_type": "field_verification"
  }
}
```

### 3. Create an operator mission

```bash
MISSION_JSON="$(curl -sS -X POST "$LOREOS_BASE/v1/characters/$CHARACTER_SLUG/mission-candidates" \
  -H "Authorization: Bearer $LOREOS_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"mission_type\": \"field_verification\",
    \"title\": \"Verify Cafe A\",
    \"reason\": \"First-hand evidence is required before a visit claim.\",
    \"source_content_intent_id\": \"$INTENT_ID\",
    \"target\": {\"type\": \"place\", \"name\": \"Cafe A\"},
    \"required_evidence\": [{\"claim_basis\": \"first_hand_visit\"}]
  }")"
MISSION_ID="$(printf '%s' "$MISSION_JSON" | jq -r '.data.mission_candidate.id')"
```

### 4. Submit verified field evidence

In production, this should come from the human/operator evidence form: photos, notes,
receipt or location proof when available, and structured observations. The example below
shows the API shape.

```bash
EVIDENCE_JSON="$(curl -sS -X POST "$LOREOS_BASE/v1/characters/$CHARACTER_SLUG/evidence" \
  -H "Authorization: Bearer $LOREOS_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"evidence_kind\": \"field_evidence\",
    \"claim_basis\": \"first_hand_visit\",
    \"verification_status\": \"verified\",
    \"confidence\": 0.93,
    \"title\": \"Cafe A field visit\",
    \"summary\": \"The operator visited Cafe A and verified it as a quiet lunch spot.\",
    \"source_provider\": \"operator\",
    \"extracted_claims\": [{\"claim\": \"Cafe A was visited first-hand\"}],
    \"content\": {
      \"target_type\": \"place\",
      \"source_mission_id\": \"$MISSION_ID\",
      \"structured_observations\": {\"crowd_level\": \"quiet\"}
    },
    \"public_eligible\": true,
    \"usable_in_chat\": true,
    \"usable_in_social\": true
  }")"
EVIDENCE_ID="$(printf '%s' "$EVIDENCE_JSON" | jq -r '.data.evidence.id')"
```

### 5. Re-check fit

```bash
curl -sS -X POST "$LOREOS_BASE/v1/characters/$CHARACTER_SLUG/content-intents/$INTENT_ID/fit" \
  -H "Authorization: Bearer $LOREOS_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"candidate_evidence_ids\": [\"$EVIDENCE_ID\"]}" | jq '.data.fit_result.fit_status'
```

Expected: `"story_fit_possible"`.

### 6. Move evidence through state review

```bash
CANDIDATE_JSON="$(curl -sS -X POST "$LOREOS_BASE/v1/characters/$CHARACTER_SLUG/evidence/$EVIDENCE_ID/state-candidate" \
  -H "Authorization: Bearer $LOREOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state_candidate_type": "public_memory_candidate"}')"
CANDIDATE_ID="$(printf '%s' "$CANDIDATE_JSON" | jq -r '.data.research_candidate.id')"

curl -sS -X PATCH "$LOREOS_BASE/v1/characters/$CHARACTER_SLUG/research/candidates/$CANDIDATE_ID/review" \
  -H "Authorization: Bearer $LOREOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "accepted_for_review", "reviewer_ref": "agent:public-doc"}' >/dev/null

REVIEW_JSON="$(curl -sS -X POST "$LOREOS_BASE/v1/characters/$CHARACTER_SLUG/state-reviews" \
  -H "Authorization: Bearer $LOREOS_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"target\": \"public_memory_candidate\",
    \"candidate_ids\": [\"$CANDIDATE_ID\"],
    \"reviewer_ref\": \"agent:public-doc\"
  }")"
REVIEW_ID="$(printf '%s' "$REVIEW_JSON" | jq -r '.data.state_review.id')"
printf '%s' "$REVIEW_JSON" | jq '.data.state_review.review_status'
```

Expected: `"ready_for_commit_review"`.

### 7. Commit and read the public slice

```bash
curl -sS -X POST "$LOREOS_BASE/v1/characters/$CHARACTER_SLUG/state-reviews/$REVIEW_ID/commit" \
  -H "Authorization: Bearer $LOREOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirm": true, "idempotency_key": "public-doc-cafe-a"}' | jq '.data.state_commit.commit_status'

curl -sS "$LOREOS_BASE/v1/characters/$CHARACTER_SLUG/public-slice?target_type=place" \
  -H "Authorization: Bearer $LOREOS_KEY" | jq '.data.public_slice'
```

The public slice contains only public/social-eligible committed facts. It excludes raw
provider dumps, private Story Room plans, branch forecasts, and runtime-only context.

## How to use the public slice

A Social Presence app can use `public_slice.facts` as the source material for post
planning. It should still enforce:

* first-person experience claims require `claim_basis` such as `first_hand_visit` or
  `receipt_verified`;
* sponsored or brand-provided claims require disclosure;
* "place exists" is not the same as "the character visited";
* published-post evidence does not prove the underlying visit. Submit field evidence or
  receipt-backed evidence separately, then link the published post to those evidence ids
  in `content`.

LoreOS gives the state and constraints. Your app still owns the post concept, caption,
approval, publishing, and performance loop.