← All packagesThe spec · v0.1.0 · Apache-2.0
@flashyos/dialects
One charter, many dialects — and a refusal to emit a surface you do not serve
One charter, many dialects — emits the surfaces other standards define (agents.txt/agents.json, A2A Agent Card) from an organisation's AAO charter, so the same facts cannot drift between them. Refuses to emit a surface the organisation does not serve.
Why it exists
The agentic web has settled on several files that say roughly the same thing about an organisation: agents.txt, agents.json, an A2A agent card. Keeping them in step by hand is how they stop agreeing. This renders all of them from the one AAO charter a property already publishes, so the same facts cannot drift between the surfaces that carry them.
What it refuses to do
It will not emit a dialect for something the organisation does not actually serve. A card that advertises a capability nobody implemented is worse than no card — the first agent to call it learns that the whole document is decorative.
How it works
One charter in, several documents out. The AAO charter at `/.well-known/flashyos-charter.json` is the single statement of who an organisation is, what it does and who answers for it; each dialect is a projection of that into the shape another standard defined.
A pointer is a link and never a copy. Where another standard has its own vocabulary, a dialect cites it rather than restating it — a restatement goes stale the day they revise it, and nothing would say so. `declareSurfaces` emits `cites`, never `publishes`.
And it refuses rather than trimming. A dialect is emitted for a surface the organisation serves and for no other, so the set of files on disk after a run is a true statement about that property rather than an aspiration.
Related concepts
Use it
Render every dialect a property genuinely serves
npx @flashyos/dialects --charter ./.well-known/flashyos-charter.json --out ./public
In practice
Be legible to agents that never heard of this estate
A property already publishes an AAO charter. One command turns it into the discovery files agents built against other standards already know how to read, without anybody maintaining a second copy of the same facts.
Stop two files disagreeing about one organisation
An agents.txt written in March and a card written in August will disagree about the contact address, and neither will fail. Rendering both from the charter makes that impossible rather than unlikely.
Questions
Is this a competing discovery standard?
No. It emits the files other standards already defined, from a charter this estate publishes. Nothing here asks anybody to adopt a new file format, and no page claims compatibility with a standard before a fetchable document exists.
What happens if my organisation does not serve one of these surfaces?
It is not emitted. A dialect is rendered for a surface the organisation actually serves and for no other, because a card advertising a capability nobody implemented teaches the first agent that calls it to distrust the whole document.
Why render them instead of writing each file once?
Because two files stating one fact drift, and neither fails when they do. Rendering every dialect from the same charter makes disagreement impossible rather than merely unlikely.
The licence
Apache-2.0, read from the package’s own manifest. Embed it in anything, including closed software — that is what makes a spec adoptable and a verifier worth running. FlashyOS’s server side is AGPL-3.0-only instead, and a test in the monorepo asserts the direction between them: AGPL code may consume this, this may never consume AGPL code.
Keep reading
Also in the spec