Portable, always-fresh docs for agents and humans.
Agents read your docs on every run, and can’t tell a fresh one from a rotted one. Two open layers fix that: OKF (Google’s open format) makes your docs portable and accessible; Surface governs their freshness, failing the build when the code a claim describes changes. Portable and fresh, they measurably improve how well agents perform.
In a pre-registered benchmark, accurate context made every model measurably better, and cheaper.See the study →Accurate context beats a bigger model. And it costs less.
A pre-registered benchmark put 5 models, across three providers, through the same documentation tasks. Accurate context made every model measurably better, and cheaper; a bigger model, on its own, didn’t close the gap. Freshness is the lever, not raw capability.
- 36–46%cheaper
- fresh docs vs none: equal-or-better accuracy at lower spend, on 4 of 5 models
- 68–100%misled
- the flip side, measured: when code had drifted, a stale doc still swung the answer on most tasks, every model
- 0LLM judges
- deterministic grading, pre-registered, 3,250 completions, 0 errors
A test asserts behavior. Surface asserts prose.
Your tests are green. Your docs can still be stale. The two drift apart the moment someone updates one and forgets the other. Code that works fine but no longer matches its description is the cell nothing else catches.
Surface owns that cell.
catches thiscode brokentests catch itboth might fire
Anchor a sentence to the code it’s about. The gate seals its logic.
# auth.md
anchors:
- claim: refresh rotation is single-use;
reuse forces global logout
at: auth.ts > rotateToken
hash: a1b2c3d$ surf check
DIVERGED auth.md
at auth.ts > rotateToken
stored a1b2c3d -> now e4f5a6b
magnitude: Small
surf check: 1 divergence(s).- 01Locate. tree-sitter resolves the at: path to an exact node span.
- 02Canonicalize. the syntax tree, not the text: comments & renames drop out.
- 03Hash. SHA-256, truncated. A list anchor is stale if any site changes.
- 04Compare. against the sealed hash. Equal passes; different blocks the merge.
A hub is a conformant OKF concept. Surface adds the freshness.
Hubs speak Open Knowledge Format, Google’s vendor-neutral standard for knowledge as markdown + frontmatter. OKF makes your docs portable and accessible; Surface layers on the freshness OKF leaves out. A hub drops into any OKF consumer, Google’s Knowledge Catalog, the visualizer, Obsidian, git-backed editors, which read the prose and ignore the anchors Surface governs.
type: BigQuery Table # OKF: any tool reads
title: Orders
tags: [sales, revenue]
anchors: # Surface governs
- claim: immutable once shipped
at: orders.ts > freeze
hash: 9b1c33aRename a local · silent
- const userId = user.id+ const uid = user.idReformat · silent
- sum(a,b,c)+ sum(a, b, c)Add a comment · silent
- return base + tax+ return base + tax // incl. tax
Flip + to − · fires
- return base + tax+ return base - tax< to <= · fires
- if (i < limit)+ if (i <= limit)Drop an await · fires
- await save(user)+ save(user)
Surface watches the logic your docs describe, and only that.
complexity × velocity× (humans+ agents)
Honestly? Maybe not. A small, slow, simple codebase doesn’t need this; two well-kept markdown files beat the whole apparatus. Use Surface where rebuilding the mental model from source is expensive and the code moves fast enough to drift.
One multiplier pushes it toward yes: agents.A human onboards once and amortizes over months. An agent re-onboards every session and amortizes nothing, so accurate context isn’t a nicety, it’s the performance budget.