v0.3.2

Release 0.3.2

Docs/tooling release: site is generated from this repo on release,
commands.md governed by surf check, version refs derived from Cargo.toml.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

v0.3.1

Surface 0.3.1

Docs: reposition (documentation governed like code), slim README, site-ready docs/ tree,
and bring docs current with 0.3.0.

v0.3.0

Surface 0.3.0

Python non-callable resolution (#28), decorator span + verbatim decorator names (#8),
per-anchor ignore_literals (#21), git file-rename follow (#3), versioned --format json
envelope (#16).

v0.2.0

Surface 0.2.0

AGENTS.md pointer enforcement (#14), surf suggest (#18), and the features
merged since 0.1.1 (check scoping, JSON for lint/verify, lint granularity).
See CHANGELOG.md.

v0.1.1

chore: release 0.1.1

Patch release: const-bound call-expression anchor resolution (#20) and
no-op `surf verify` skip behavior (#22).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

v0.1.0 — first public release

Your test suite is green. Your documentation is lying. Surface catches the second one.

A deterministic CI gate that fails the build when the code a doc describes changes out from under it — the same way a failing test does. No model, no network, no API key in the core.

Languages: TypeScript/JSX, JavaScript, Rust, Python, Go.

Install

curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/Connorrmcd6/surface/main/install.sh | sh

Or cargo install --git https://github.com/Connorrmcd6/surface surf-cli, the GitHub Action (Connorrmcd6/surface@v0.1.0), or the pre-commit hook — see the README.

Try it in ~2 minutes

From inside one of your repos (any TS/JS/Rust/Python/Go project):

surf init                 # writes surf.toml + hubs/
surf new auth             # creates hubs/auth.md
# edit hubs/auth.md: write a claim and point `at:` at a real symbol, e.g.
#   at: src/auth.ts > rotateToken
surf lint                 # does the anchor resolve?
surf verify               # seal it (stamps the hash)
surf check                # green
# now change that function's logic and run it again:
surf check                # DIVERGED — blocks until you re-read the claim

What I'd love feedback on

• Does anchoring claims feel natural, or fiddly?
• False alarms (fires on a cosmetic change) or misses (didn't fire when it should)?
• Anchor resolution failures on your real code (ambiguous / not found)?
• Is the honest limit below clear enough?

The honest limit

A green check means "nothing you anchored has changed since it was last verified" — not that your docs are true, and nothing at all about code you didn't anchor. Surface guards the spans you chose to describe; it is not a security/taint analysis.

Platforms

Prebuilt binaries: macOS (Apple Silicon / arm64), Linux (x86_64). On Intel macOS, Windows, or other arches, install from source: cargo install --git https://github.com/Connorrmcd6/surface surf-cli (or use WSL).