How to use the atoms directory

One request, every catalog

Everything an agent needs to discover the Convergent Systems atoms ecosystem is at one URL:

curl https://atoms.convergent-systems.co/directory.json

Shape

{
  "ecosystem": "convergent-systems",
  "spec": "atoms-spec/v1",
  "built_at": "2026-05-21T22:00:00.000Z",
  "summary": {
    "total": 13,
    "live": 4,
    "bootstrap": 9
  },
  "catalogs": [
    {
      "name": "channel-atoms",
      "version": "0.1.0",
      "status": "live",
      "domain": "channel-atoms.com",
      "pages_url": "https://channel-atoms.pages.dev",
      "github_url": "https://github.com/convergent-systems-co/channel-atoms",
      "federation": "convergent-systems.co",
      "purpose": "Communication channels canonicalized — Slack, email, SMS, webhook, ...",
      "atom_types": ["protocol", "endpoint", "delivery-semantic", "transport", "auth-method"],
      "composition_type": "channels",
      "composition_dir": "channels",
      "runtime_consumers": ["aish", "olympus"],
      "license": "Apache-2.0",
      "live": {
        "catalog_url": "https://channel-atoms.pages.dev/exports/catalog.json",
        "atoms": 40,
        "compositions": 2,
        "rules": 0,
        "built_at": "2026-05-21T..."
      }
    },
    {
      "name": "compliance-atoms",
      "version": "0.1.0",
      "status": "bootstrap",
      "atom_types": [...],
      "composition_type": "frameworks",
      "live": null
    }
  ]
}

Fields

• status: live (web app deployed, /exports/catalog.json reachable) or bootstrap (schemas + intent declared, no deploy yet).
• atom_types: declared types in ATOMS.yml. For live catalogs this matches the types in the live catalog.json.
• composition_type / composition_dir: where compositions live (prompts, agents, etc).
• runtime_consumers: products / runtimes that pull this catalog at runtime.
• live: present only when the catalog is deployed; contains the live atom / composition / rule counts and a built_at timestamp from the catalog's own export.

Consuming a specific catalog

Each live catalog publishes its full content at <pages_url>/exports/catalog.json. Example:

curl https://channel-atoms.pages.dev/exports/catalog.json | jq '.atoms[0]'

Caching

The directory is cached for 60s at the edge (Cache-Control: public, max-age=60). CORS is open (Access-Control-Allow-Origin: *) so any client can fetch.

Rebuild cadence

The directory rebuilds on every push to main of convergent-systems-co/atoms. To force a refresh, push a no-op commit or re-run the deploy workflow.