Map your system

Sioma builds its map from an OpenAPI spec. You can bring one you already have, or generate one from your code with the CLI.

Scan your repo#

npx @sioma/cli scan .

scan walks your real routes, TypeScript types, and validators, and writes openapi.json. Every field is traced through the TypeScript compiler to a declared type. Anything that cannot be proven is dropped rather than invented, so the spec is honest about what your code actually declares.

Scanning the same code twice produces byte-identical output. A spec diff always means the code changed.

Supported today: Next.js (App and Pages Router), express, fastify, and hono.

Run it from the app's own directory, with node_modules installed. Types resolve through your real dependency graph, including generated clients like Prisma's, and a bare checkout with no dependencies installed will find far less.

In a monorepo, scan each app, not the root. The scanner detects one framework at the directory you point it at, and a workspace root is not one:

npx @sioma/cli scan apps/server --out apps/server/openapi.json
npx @sioma/cli scan apps/web --out apps/web/openapi.json

Publish each as its own named source so they stay distinct.

Check what you got#

npx @sioma/cli verify .

verify builds the entity map from the spec and reports what is missing or malformed, before you publish anything.

Publish it#

Publishing is the step that makes your map servable. Registering a spec builds it for the app, but until it is published, your agent's first call has nothing to answer with.

export SIOMA_PUBLISH_KEY=...              # Control room, Keys, scope: publish
export SIOMA_APP_URL=https://app.sioma.ai # your workspace origin, the default
npx @sioma/cli publish .

Used the one-prompt setup instead? The approval already handed your agent a publish key: the token response's sioma_publish_key is exactly the SIOMA_PUBLISH_KEY above. No second trip to the Keys page.

Publish your docs too#

Your API map answers "what exists and how it connects". Your docs answer "how do I…" — and a copilot grounded on both is the difference between an endpoint list and a product assistant. Point the CLI at any folder of markdown:

npx @sioma/cli scan --docs ./docs
npx @sioma/cli publish --spec docs-spec.json --name docs

Each page becomes a servable, citable source: the title is what matching finds, the body is what the copilot answers with, and a frontmatter route: (optional) is the link it cites. Pages marked draft: true and files starting with _ are skipped. Publish it as its own source, next to your API — the two stay separately named and separately updatable.

Keep it current in CI#

diff exits 1 when the code has changed since your last publish, so the whole CI loop is two commands, and a re-run with no changes does nothing:

npx @sioma/cli diff . || npx @sioma/cli publish .

What leaves your machine#

Nothing, except when you run publish. Then exactly one thing goes out: the generated openapi.json. scan, verify, and diff never touch the network. Keys are read from the environment and never written to disk.

Without the CLI#

If you already have a spec, open Control room and go to the API spec panel. Upload it there and publish from the same place. That panel is also where you manage sources over time: re-publishing under the same source name updates that source, it never adds a duplicate.