Kam is a self-describing product.

Kam documentation is not ordinary help copy. It is a public semantic interface. It teaches people and agents how to operate Kam with the same language Kam uses internally, without exposing raw storage keys, debug traces, or private conversation text.

The public chain is:

backend contracts
shared public definitions
human docs
agent-readable llms.txt
well-known JSON endpoints
tests that prevent drift

What the interface exposes

Kam exposes public-safe definitions for:

1. Capabilities: what Kam can do.
2. Request context: what the chat screen or an agent can attach.
3. Response contracts: what a good answer must show.
4. Data availability states: whether data is ready, stale, blocked, or outside scope.
5. Receipt types: how an answer links back to capability, source state, and next action.
6. Typed actions: what the user or an agent can do next.

The public docs should use plain language. The JSON endpoints should include canonical IDs for agents, receipts, support diagnostics, and regression fixtures.

Capability shape

A capability definition should answer these questions:

What can Kam do?
What inputs are required?
Which sources are supported?
Which response view should render?
Which data plane supports the result?
Which states can occur?
Which receipt type proves the answer?
Which typed next actions are valid?
Which wording is allowed or forbidden?

Example public capability:

{
  "capabilityId": "kam.cap.sports.market.compare_polymarket.v1",
  "publicName": "Compare sportsbooks and Polymarket",
  "requiredInputs": ["sport", "date", "marketType"],
  "supportedSources": ["sportsbooks", "polymarket"],
  "possibleStates": [
    "ready_nonempty",
    "available_not_rendered",
    "not_materialized",
    "stale",
    "blocked"
  ],
  "responseView": "market_alignment",
  "receiptType": "kam.receipt.sports.market.compare_books.v1"
}

Ordinary users do not need to memorize the canonical ID. Agents and receipts should preserve it so a response can link back to the exact product contract.

Typed next actions

Every useful response should end with an action that can be represented without scraping button labels.

Example:

{
  "typedActionId": "kam.act.sports.market.switch_market.v1",
  "label": "Open FanDuel moneyline timeline",
  "arguments": {
    "marketText": "h2h",
    "bookmakerText": "fanduel"
  }
}

Typed actions should use safe public arguments. They should not include raw storage keys, provider debug fields, claim permissions, or final internal state.

Public endpoints

Agents can read these endpoints before submitting a request:

/.well-known/kam-capabilities.json
/.well-known/kam-request-context.json
/.well-known/kam-response-contracts.json
/.well-known/kam-receipt-types.json
/.well-known/kam-navigation.json

Use /llms.txt for compact product rules. Use the .well-known files when an agent needs structured capability, response, receipt, and navigation definitions.

Public versus internal language

Keep internal and public terminology paired:

{
  "capabilityId": "kam.cap.sports.market.compare_books.v1",
  "publicName": "Compare prices across sportsbooks",
  "plainLanguageDescription": "Compare the same market across available sportsbook prices."
}

This lets:

1. Internal systems use canonical IDs.
2. Frontend code render public names.
3. Receipts link the two.
4. External agents operate the product without guessing.

Drift rule

Do not write the same product truth separately in backend comments, MDX, /llms.txt, frontend help copy, and support FAQs.

The shared data should own the stable facts. Docs should add explanation, examples, and copy/paste prompts.

Safety boundary

Public definitions may include:

capability IDs
typed action IDs
required inputs
supported sources
response states
receipt fields
safe next-action arguments
public docs links

Public definitions must not include:

raw storage keys
raw traces
debug payloads
private conversation text
provider credentials
unbounded internal identifiers

That keeps Kam self-describing without leaking implementation details.