Occam Handbook¶

Audience: Anyone who did not write Occam and wants to understand what it can do, how it works, and where its promises stop.

Authority: This handbook follows the canonical model in docs-audit/ (product definition, trust model, owner decisions, honesty schema). Where older pages under docs/ disagree, this handbook and the code win.

Version baseline: 1.1.1 (published install channel) · core MCP tools from the registry (runtime tools/list varies by profile/opt-in; product default OCCAM_PROFILE=reader) · live extract by default (opt-in cache_ttl_s for local replay)

Honesty preamble (read this first)¶

Occam is built around a contract that is easy to ignore and impossible for the product to enforce:

ok:false means the page content is UNKNOWN. Do not fill gaps from model memory. A typed refusal is an answer, not a blank page.
A receipt proves integrity relative to a key, not truth. It means this install's key asserted these exact compiled bytes. It does not prove the origin served them, who the signer is, or that the content is accurate.
Compiled markdown is the object. Occam returns a budgeted reading of a page, not the raw HTTP response body. Hashes and receipts cover that compiled form.
Names that overclaim are corrected here. claim_check retrieves and cites; it does not prove claims. attest is a heuristic citation assessment, not cryptographic attestation. crosscheck compares sources; it is not consensus proof. The Receipt field on occam_extract_knowledge is extraction telemetry, not Receipt v1.
Distribution honesty. npm is not a GA install channel. Cosign on install is policy-gated (required-cosign-v1 for published 1.0.0-rc.3+; legacy 1.0.0-rc.2 stays SHA-256-only). Authenticity ≠ page-content truth. The community marketplace is operational machinery, not a trusted auto-merge supply chain.
Every chapter is falsifiable. Each includes a CHECK you can run. When observation and text disagree, executable code wins.

If you read nothing else before calling tools, read Chapter 2 and Chapter 14.

What this book is¶

A teachable spine—not an API dump. Parameter tables live in tools-reference.md and reference/mcp-api.md. This handbook explains mechanisms, mental models, and limits.

Canonical one-sentence definition¶

Occam is a locally run host process that turns a URL into content an LLM agent can use: it acquires the page through a gated HTTP→browser ladder, compiles the result into a token-bounded representation, returns ok:false when content is unknown rather than guessed, and can sign what it produced so the exact bytes can be checked for tampering against a key the recipient obtains out of band.

Parts and chapters (1–14)¶

Part	Chapters	Theme
A — Orientation	1 · 2 · 3 · 4	What Occam is, the honesty contract, a testable install, and why there is no single product-wide spine
B — Reference path	5 · 6 · 7 · 8	How pages are fetched, what blocks them, how output is budgeted, and optional structured/differential shapes
C — Breadth	9 · 10	Cheaper signals before full extract, and many URLs under one budget
D — Site-specific	11 · 12 · 13	Recipes, authoring loop, typed field extraction
E — Trust	14	Receipt v1: what signatures and Merkle roots license you to say

Spine chapters (read carefully): 2, 4, 5, 7, 14.

Reading orders¶

Shortest path to competence (six chapters)¶

1 → 2 → 4 → 5 → 7 → 14

Definition, honesty contract, spine plurality, acquisition ladder, token contract, receipt limits. If you deploy for others, also read configuration, transports, and Chapter 18 — Exposure.

Agent integrator¶

1 → 2 → 3 → 4 → 5 → 7 → 8 → 9 → 10 → 14

Then 6 when you hit walls; 11–13 for site-specific extraction.

Operator¶

1 → 2 → 3 → 5 → 6 → 14 plus install, configuration, getting-started.

Auditor / verifier¶

1 → 2 → 7 → 14 then receipts, receipt_verification, guides/verify-sources.

Adoption decision (no install required)¶

1 → 2 → 5 (skim) → 14 plus trust-and-safety.

Recurring example: Task R¶

Throughout the handbook, Task R asks: What rate limits does this API document state? You need a quotable sentence, evidence it was on the page you read, and a way to notice change—without guessing.

The concrete host should be a public, gate-observed site (see corpora/l0-smoke.jsonl). Network checks are tagged NETWORK; prefer local checks when offered.

Public docs cross-links¶

Topic	Public page
Quick first success	quick-start.md
Install	install.md · getting-started.md
Tool choice	choosing-a-tool.md
Concepts	concepts.md
Failure codes	failure-codes.md
Receipts	receipts.md
Trust posture	trust-and-safety.md
API contract	reference/mcp-api.md

Parts and chapters (15–27)¶

Part	Chapters	Theme
E — Trust (continued)	15 · 16	Verify modes, claims and corpora limits
F — Deployment reality	17 · 18 · 19 · 20 · 21 · 22 · 23	Opt-in tools, exposure model, operations, automation, disk footprint, config negative space, security
G — Synthesis	24 · 25 · 26 · 27	Tool chains, diagnosis, internals, falsification protocol

Appendix: Status labels

Spine chapters in this range: 18 (exposure). Chapters 20–21 are the canonical route for automation and state questions.

Design provenance: docs-audit/HANDBOOK-OUTLINE.md (engineering reference, not user-facing).