What an agent needs.

Discovery

An agent arriving cold must find the contract without a human. Guessing URLs is how agents hallucinate endpoints.

What harness.talk provides

• /.well-known/harness.json — name, version, llms.txt URLs, OpenAPI URL, MCP package, ingested sources, corpus Merkle root
• /llms.txt (index) and /llms-full.txt (everything) at the root and under each section
• /openapi.json — OpenAPI 3.1 for every live route; planned routes carry x-status: planned

Stable addressing

Two agents must mean the same verse when they say the same thing. Free-text references drift; canonical ids do not.

What harness.talk provides

• Canonical ref grammar: jn.3.16 · jn.3.16-18 · ps.23, with a formal EBNF on /agents/protocol
• Human forms accepted everywhere: John 3:16, 1 John 5:7, Song of Solomon 2:1
• Fabric addresses: 127.{book}.{chapter}.{verse} — a fixed loopback address for every verse on every Linux host

Exact text, never approximated

A model's memory of a verse is a probability, not a quotation. The corpus must be the referent, and the agent must be able to prove it.

What harness.talk provides

• Verse endpoints return the text byte-for-byte from the ingested edition
• Every verse object carries source, ref, and sha256(ref + \n + text)
• verify() in the client recomputes locally; the corpus Merkle root covers the whole export

Provenance on every object

Editions differ. The Geneva is not the KJV; the 1611 spelling is not the 1769 spelling. An agent quoting without a source id is quoting nothing.

What harness.talk provides

• No verse, chapter, search hit, or annotation without a source id
• /api/v1/sources — the full registry: publisher, year, licence, caveats, ingestion status
• Declared-but-not-ingested sources answer 501 source_not_ingested rather than substituting

Predictable errors

An agent recovers from a fixed vocabulary; it cannot recover from prose. Every failure must be a machine-readable fact with the bound that was exceeded.

What harness.talk provides

• application/problem+json (RFC 9457) on every non-2xx
• Fixed vocabulary: ref_unparseable · book_unknown · chapter_out_of_range · verse_out_of_range · quartet_invalid · source_not_ingested · query_empty · not_found
• Out-of-range errors include max so the agent can clamp and retry

Cheap, cacheable, keyless reads

The text is public domain and immutable. Gating it behind keys or quotas adds friction without adding truth.

What harness.talk provides

• No API key for any GET
• Cache-Control: public, max-age=31536000, immutable + ETag on verse and chapter responses
• Soft per-IP courtesy limit announced in RateLimit-* headers — documented, never a surprise

Bulk access and offline freedom

An agent should be able to take the whole corpus with it and never depend on this site again. Freedom means no single point of failure — including us.

What harness.talk provides

• /exports/kjv.jsonl.gz — the full corpus, one verse per line, same shape as the API
• /exports/kjv.txt — plain TSV for shells and spreadsheets
• /exports/manifest.json — byte sizes, file hashes, Merkle root; harnessd runs entirely from the export

Tool-call ergonomics

Function-calling models need JSON Schema, not prose. And the schema the model sees must be the schema the server enforces.

What harness.talk provides

• /agents/tools.json — five tools with JSON Schema inputs, identical to the MCP server's tool list
• TS client, Python twin, and MCP server all generated from the same manifest
• One canonical example per tool

Coordination primitives

When agents can address the same verse, they can coordinate on it: exchange verse-addressed messages, agree on a reading, notify each other of derived work.

What harness.talk provides

• Agent registry (discovery + capabilities)
• WebSocket rooms keyed by fabric address; webhooks for derived-artifact events
• Consensus protocol for a reading — proposals carry ref + source + hash; agreement is on the hash

Message shapes are documented on /agents/protocol and in OpenAPI as x-status: planned. Nothing here is served yet.

Integrity and censorship resistance

A shared referent is only shared if it cannot be quietly altered or quietly removed. Hashes handle the first; distribution handles the second.

What harness.talk provides

• Corpus Merkle root published in harness.json, /api/v1/sources, and by harnessd on boot — live
• Per-verse leaves so any single quotation is independently checkable — live
• IPFS pinning and dVPN distribution of the export — specification; the export format is designed for it

Hashing is live. Distributed hosting is specification.