SoundfishInterfaces · 2026-09-23
One document for people and agents
Soundfish renders every public page as HTML for people and Markdown for agents, and the same canonical document drives the browser editor, the CLI, and agent prompts. How one music model serves both audiences.
Two readers, one page
Every public Soundfish page answers content negotiation. A browser gets the HTML page; a request carrying Accept: text/markdown gets a Markdown twin generated from the same content source. Album pages, artist pages, the home page, docs, pricing, comparisons, and these research notes all participate, and the Link header advertises the twin on every HTML response.
The point is not novelty. An agent that can read a page without parsing layout, cookie banners, or script scaffolding is an agent that quotes the product accurately. The Markdown is authored alongside the HTML — not a screen scrape — so statements about limits, prices, and behavior come from the same constants the application enforces.
The document agents actually edit
For MIDI the story goes further than reading. A loop or song is a canonical document, and the published @hraness/soundfish Bun CLI inspects, verifies, transforms, and exports it. The browser editor and the CLI operate on the same bytes, so a change an agent makes is a change a person can open and hear.
The editor's Edit with agent flow exposes two honest paths. Chat app hands a hosted agent the loop's compose text — lossy by design, because it cannot carry IDs, lineage, or automation points — and pastes the reply back for review. Coding agent hands over the exact URL for the Soundfish skill and CLI to edit precisely, then verifies the result before it returns a new link. Compositions never travel in provider links; they move through the prompt itself or stay on the device.
What agents get for free
Discovery surfaces that usually cost a crawler budget are cheap here: llms.txt indexes the guides and every skill reference file, /openapi.json describes the audio API, the sitemap lists public pages and the published catalogue, and album and artist pages emit the structured data search engines and chat crawlers already understand.
- Accept: text/markdown twins on every public page, advertised through Link headers.
- The Soundfish skill at /skills/soundfish.zip plus reference files under /skills/soundfish/reference/.
- A documented compose format an agent can write by hand and have the CLI compile.
- Article and album structured data emitted from the same values the pages display.
The boundary on purpose
There is no unauthenticated hosted mutation endpoint for canonical documents. Composition edits happen in the browser or through a local CLI the person runs; the audio publishing API is a bearer-token or browser-session surface. Agent workflows end in human review — a paste, a new link, a published album — because a document a machine can write is still a document a person owns.
The short version
Treating agents as a first-class reader is mostly a matter of honesty: real Markdown, real structured data, a real document format, and a boundary that keeps writes where the owner can see them.