Agent-readable publishing, hosted by you.
Sphere is a structured access layer for publishing written knowledge to AI agents. It treats a piece of writing not as crawlable text but as a fragment: a bounded unit with provenance, license, access policy, and typed relations to other fragments. Agents read the contract; people read a rendered page at the same address.
This repository is the content source: the documentation and theory behind Sphere, kept as plain Markdown. It is not a website and not an application. It is the body of writing that becomes agent-readable fragments and gets published to a Sphere Node.
Sphere is three small pieces and a node that serves itself.
flowchart LR
A["content<br/>(this repo)"] --> B["sphere-plugin<br/>generate + validate"]
B --> C["sphere-node<br/>self-hosted server"]
C --> D["agents<br/>fragment contract"]
C --> E["people<br/>rendered page"]
| Repository | Role |
|---|---|
| sphere (this repo) | The Markdown content that fragments are made from. |
| sphere-node | The self-hostable server on Cloudflare Workers. Serves the fragment contract to agents and renders a human-readable surface. One-click deploy. |
| sphere-plugin | The local Claude plugin that prepares and validates fragments from this content. |
The fragment contract is canonical in sphere-node under spec/ (fragment.schema.json and node-api.md). This repository never redefines it.
content/is the documentation and theory, as Markdown. Each file keeps its frontmatter (title,description,summary, astatusofshipped,mixed, orvision, and an optionalsourceslist), useful metadata when generating fragments.content/notes/holds theory notes, for example why Sphere is named Sphere.
A content file may declare sources in its frontmatter: the external works it draws on. Provenance is legitimacy, so it is part of the fragment contract — the plugin copies it through to the fragment sphere.json, and the node renders it. It lives in the source frontmatter so it survives regeneration. Each entry has a type (book, article, paper, video, webpage, dataset, or other) and a title, with optional author, url, date, and note:
sources:
- type: book
title: The Structural Transformation of the Public Sphere
author: Jürgen Habermas
date: "1962"sources is EXTERNAL provenance only — not the internal document a fragment was generated from (that build lineage is captured by canonical_url, not the contract). Original, node-native content simply has no sources. The canonical schema lives in sphere-node/spec/fragment.schema.json; this repo never redefines it.
A content file may declare relations in its frontmatter: the typed edges from this fragment to others. Like sources, relations live in the source frontmatter so they survive regeneration — the plugin copies them through to the fragment sphere.json unchanged, and the node validates and serves them. Each edge has a type (a short, open relation kind — related, continues, cites, responds-to, …; not enumerated) and a target:
relations:
- type: continues
target: 2026-06-23-concept # same-node: a bare fragment id
- type: cites
target: https://other.node/fragments/2026-01-10-source # external: an absolute canonical fragment URLtarget is a canonical fragment reference, the one scheme used everywhere a fragment is named: either a same-node fragment id (yyyy-mm-dd-slug) or an absolute URL to another node's canonical fragment ({node_base}/fragments/{id}). A relation always points at a fragment — it is not the place for external citations (those are sources) or for the document a fragment was generated from (that is canonical_url). The reference scheme is defined in sphere-node/spec/node-api.md.
The content here is the input. Fragments are generated from it with the Claude plugin, validated against the contract, and published to a Sphere Node that the publisher runs themselves. Updating a fragment is republishing it; the node is the home of what is served.
The concept docs are the best way in:
| Document | What it covers |
|---|---|
| Concept | Why Sphere exists, the public sphere, fragments and constellations, the revenue-model vision. |
| Format | What a fragment is, and the shape of its metadata. |
| HTTP layer | How content negotiation and the 402 seam work over plain HTTP. |
| Governance and deployment | How nodes, ownership, and publication fit together. |
The reference node serves this project's own fragments at sphere.pub: a human index in the browser, and the fragment contract for agents at /.well-known/sphere.json. Sphere publishes itself.
The writing in this repository is the Sphere project by Mariano Viola, an independent project. Published fragments default to CC BY-NC unless a fragment states otherwise. The node and plugin code carry their own licenses in their repositories.