teleo-codex/schemas/entity.md

# Entity Schema

Entities are tracked objects in the world — companies, protocols, people, markets — that have attributes changing over time. Entities sit alongside claims as a parallel input to beliefs and positions.

```
Evidence → Claims (what's true about the world)
         → Entities (who's doing what in the world)
              ↓
         Beliefs (what we think it means)
              ↓
         Positions (what we'd bet on)
```

Claims are static propositions with confidence levels. Entities are dynamic objects with temporal attributes. Both feed into agent reasoning.

## Entity Types

| Type | What it tracks | Examples |
|------|---------------|----------|
| `company` | Protocol, startup, fund, DAO | MetaDAO, Aave, Solomon, Devoted Health |
| `person` | Individual with tracked positions/influence | Stani Kulechov, Gabriel Shapiro, Proph3t |
| `market` | Industry segment or ecosystem | Futarchic markets, DeFi lending, Medicare Advantage |
| `decision_market` | Governance proposal, prediction market, futarchy decision | MetaDAO: Hire Robin Hanson, MetaDAO: Burn 99.3% of META |

## YAML Frontmatter

```yaml
---
type: entity
entity_type: company | person | market | decision_market
name: "Display name"
domain: internet-finance | entertainment | health | ai-alignment | space-development
handles: ["@StaniKulechov", "@MetaLeX_Labs"]  # social/web identities
website: https://example.com
status: active | inactive | acquired | liquidated | emerging  # for company/person/market
# Decision markets use: active | passed | failed
tracked_by: rio  # which agent owns this entity
created: YYYY-MM-DD
last_updated: YYYY-MM-DD
---
```

## Required Fields

| Field | Type | Description |
|-------|------|-------------|
| type | enum | Always `entity` |
| entity_type | enum | `company`, `person`, `market`, or `decision_market` |
| name | string | Canonical display name |
| domain | enum | Primary domain |
| status | enum | Current operational status |
| tracked_by | string | Agent responsible for keeping this current |
| created | date | When entity file was created |

## Optional Fields (all entity types)

| Field | Type | Description |
|-------|------|-------------|
| handles | list | Social media handles, URLs |
| website | string | Primary web presence |
| last_updated | date | When entity was last reviewed for accuracy |
| tags | list | Discovery tags |
| secondary_domains | list | Other domains this entity is relevant to |

## Decision Market-Specific Fields

Decision markets are individual governance decisions, prediction market questions, or futarchy proposals. Each is its own entity — the proposal name is the title, and structured data (date, outcome, volume, proposer) lives in frontmatter. The parent entity (e.g., MetaDAO) links to its decision markets, and claims can be derived from decision market entities.

Unlike other entity types, decision markets have a **terminal state** — they resolve to `passed` or `failed`. After resolution, the entity is essentially closed. Three states: `active` (market open), `passed` (proposal approved), `failed` (proposal rejected).

```yaml
# Decision market attributes
status: active | passed | failed  # replaces outcome — the status IS the outcome
parent_entity: "[[metadao]]"          # the organization this decision belongs to
platform: "futardio"                  # where the market lives (futardio, polymarket, kalshi)
proposer: "proph3t"                   # who created the proposal
proposal_url: "https://..."           # canonical link to the market/proposal
proposal_date: YYYY-MM-DD            # when proposed/created
resolution_date: YYYY-MM-DD          # when resolved (null if active)
category: "treasury | fundraise | hiring | mechanism | liquidation | grants | strategy"
summary: "One-sentence description of what the proposal does"

# Volume fields are platform-specific:

# Futarchy proposals (governance decisions):
pass_volume: "$150K"              # capital backing pass outcome
fail_volume: "$100K"              # capital backing fail outcome

# Futarchy launches (ICOs via Futardio):
funding_target: "$2M"
total_committed: "$103M"          # total capital committed (demand signal)
amount_raised: "$8M"              # actual capital received after pro-rata

# Prediction markets (Polymarket, Kalshi):
market_volume: "$3.2B"            # total trading volume
peak_odds: "65%"                  # peak probability for primary outcome
```

**Filing convention:** `entities/{domain}/{parent-slug}-{proposal-slug}.md`
Example: `entities/internet-finance/metadao-hire-robin-hanson.md`

**Relationship to parent entity:** The parent entity page should include a "## Key Decisions" summary table with date, title (wiki-linked), proposer, volume, and outcome. Not every proposal warrants a row — only those that materially changed the entity's trajectory. The full detail lives in the decision_market entity file.

```markdown
## Key Decisions
| Date | Proposal | Proposer | Volume | Outcome |
|------|----------|----------|--------|---------|
| 2025-02-10 | [[metadao-hire-robin-hanson]] | proph3t | $X | Passed |
| 2024-03-03 | [[metadao-burn-993-meta]] | proph3t | $X | Passed |
| 2024-06-26 | [[metadao-fundraise-2]] | proph3t | $X | Passed |
```

**What gets a decision_market entity vs. a timeline entry:**
- **Entity:** Proposals with real capital at stake, governance decisions that changed organizational direction, markets that produced notable information, or contested outcomes (significant volume on both sides — a contested failure is more informative than an uncontested pass)
- **Timeline entry only:** Test proposals, spam, trivial parameter tweaks, minor operational minutiae, uncontested routine decisions
- **Estimated ratio:** ~33-40% of real proposals qualify for entity status

**Extraction output for proposal sources:**
1. **Primary:** decision_market entity file with structured frontmatter
2. **Secondary:** Timeline entry on parent entity (one-line summary + date)
3. **Optional:** Claims ONLY if the proposal contains novel mechanism insight, surprising market outcome, or instructive governance dynamics (~20% of proposals)

**Eval checklist for decision_market entities (all mechanical):**
1. `parent_entity` exists in entity index
2. Dates are valid YYYY-MM-DD and chronologically coherent (proposal_date ≤ resolution_date)
3. `status` matches source data (passed/failed/active)
4. Not a duplicate of existing entity
5. Meets significance threshold (not test/spam/trivial)

**Wiki links use filenames only** (e.g., `[[metadao-hire-robin-hanson]]`), not full paths. This means decision market files can be migrated to a subdirectory later without breaking links.

**Body format:**
```markdown
# [Parent Entity]: [Proposal Title]

## Summary
[What the proposal does and why it matters — 2-3 sentences]

## Market Data
- **Volume:** $X
- **Outcome:** Passed/Failed/Pending
- **Key participants:** [notable traders, proposers, commenters]

## Significance
[Why this decision matters — what it reveals about governance dynamics, organizational direction, or mechanism design]

## Relationship to KB
- [[parent-entity]] — governance decision
- [[relevant-claim]] — how this decision relates to broader thesis
```

## Company-Specific Fields

```yaml
# Company attributes
founded: YYYY-MM-DD
founders: ["[[person-entity]]"]
category: "DeFi lending protocol"
parent: "[[parent-entity]]"  # e.g., [[futardio]] for launched projects
stage: seed | growth | mature | declining | liquidated
market_cap: "$X"  # latest known, with date in body
funding: "$X raised"  # total known funding
key_metrics:
  tvl: "$40B"
  volume: "$X"
  users: "X"
competitors: ["[[competitor-entity]]"]
built_on: ["Solana", "Ethereum"]

# Capital formation fields (for launched/funded entities)
raise_target: "$500K"          # intended raise amount
amount_raised: "$969K"         # actual amount raised
total_committed: "$14.9M"      # total capital committed (shows demand)
# oversubscription_ratio is calculated: total_committed / raise_target
# Do NOT store it — derive it to prevent inconsistency
treasury: "$575K USDC"         # current treasury balance
token_price: "$0.05"           # current token price
monthly_allowance: "$50K"      # approved monthly spend rate
launch_date: YYYY-MM-DD       # when the entity launched/raised
```

## Person-Specific Fields

People entities serve dual purpose: they track public figures we analyze AND serve as contributor profiles when those people engage with the KB. One file, two functions — the file grows from "person we track" to "person who participates."

```yaml
# Person attributes
role: "Founder & CEO of Aave"
organizations: ["[[company-entity]]"]
followers: 290000  # primary platform
credibility_basis: "10 years building largest DeFi protocol"
known_positions:
  - "DAOs need founder-led execution with onchain accountability"
  - "DeFi must capture traditional lending market"
influences: ["[[person-entity]]"]  # who they cite/follow
influenced_by: ["[[person-entity]]"]

# Contributor attributes (populated if/when they engage with the KB)
contributor: false  # becomes true when they contribute
contributions: []  # list of claims they proposed, challenged, or enriched
first_contribution: null  # date of first KB interaction
attribution_handle: null  # how they want to be credited
```

## Market-Specific Fields

```yaml
# Market attributes
total_size: "$120B TVL"
growth_rate: "flat since 2021"
key_players: ["[[company-entity]]"]
market_structure: "winner-take-most | fragmented | consolidating"
regulatory_status: "emerging clarity | hostile | supportive"
```

## Body Format

```markdown
# [Entity Name]

## Overview
[What this entity is, why we track it — 2-3 sentences]

## Current State
[Latest known attributes, metrics, positioning — updated when new info arrives]

## Timeline
- **YYYY-MM-DD** — [Event: founded, launched, acquired, pivoted, etc.]
- **YYYY-MM-DD** — [Event]
- **YYYY-MM-DD** — [Event]

## Competitive Position
[Where this entity sits relative to competitors. Market share, differentiation, vulnerabilities.]

## Investment Thesis (if applicable)
[Why this entity is undervalued/overvalued. What catalysts exist. What would change the thesis.]

## Relationship to KB
[Which claims, beliefs, or positions depend on or reference this entity]
- [[claim-title]] — how this entity relates
- [[belief]] — what this entity's trajectory means for our worldview

---

Relevant Entities:
- [[competitor]] — competitive relationship
- [[founder]] — founded by

Topics:
- [[domain-map]]
```

## Governance

- **Who creates:** Any agent can create entities in their domain. `tracked_by` field sets ongoing ownership.
- **All updates go through eval.** Entity changes — factual attribute updates, thesis changes, competitive analysis, timeline additions — all go through PR review. Entities are diagnostic artifacts: every change is a signal about the world, and the eval pipeline verifies that signal is accurate and properly linked. No shortcuts.
- **Staleness:** Entities not updated in 90 days get flagged. The `tracked_by` agent is responsible for keeping entities current.
- **Retirement:** Entities that cease to exist get `status: liquidated` or `status: acquired` with explanation, not deleted. Their history remains valuable.

## Filing Convention

**Location:** `entities/{domain}/{slugified-name}.md`

```
entities/
  internet-finance/
    metadao.md
    aave.md
    solomon.md
    stani-kulechov.md
    gabriel-shapiro.md
    metadao-hire-robin-hanson.md       # decision_market
    metadao-burn-993-percent-meta.md   # decision_market
  entertainment/
    claynosaurz.md
    pudgy-penguins.md
    matthew-ball.md
  health/
    devoted-health.md
    function-health.md
```

**Filename:** Lowercase slugified name. Companies use brand name, people use full name. Decision markets use `{parent}-{proposal-slug}.md`.

## How Entities Feed Beliefs

When an entity's attributes change (new funding round, market cap shift, product launch, leadership change, liquidation), agents should:
1. Update the entity file
2. Check which claims reference this entity
3. Check which beliefs depend on those claims
4. Flag beliefs for re-evaluation if the entity change is material

This is the same cascade logic as claim updates, extended to entity changes.

## Relationship to Sources

Sources often contain entity information. During extraction, agents should:
- Extract claims (propositions about the world) → `domains/{domain}/`
- Update entities (factual changes to tracked objects) → `entities/{domain}/`
- Both from the same source, in the same PR

## Key Difference from Claims

| | Claims | Entities |
|---|---|---|
| Nature | Propositions (true/false) | Objects (exist/change) |
| Change model | Confidence shifts | Attribute updates |
| Title format | "X is true because Y" | "Company Name" |
| Disagreement | Counter-claims challenge | Competitive analysis compares |
| Value | Reasoning chains | Situational awareness |
| Temporal | Created date, mostly static | Timeline of events |