# DNA OS — AI and developer quick start

**Current public home:** <https://dnaos-developer-portal.pages.dev/>  
**Status checked:** 2026-11-13

## Read these in order

1. [`/llms.txt`](https://dnaos-developer-portal.pages.dev/llms.txt) — curated index and boundaries.
2. [Human-readable portal](https://dnaos-developer-portal.pages.dev/) — solution catalogue and API contracts.
3. [JSON contract](https://dnaos-developer-portal.pages.dev/api/v1/developer-portal) — machine-readable endpoint specs, request and response examples, auth rules, verification checks, and source references.

The Registry is the documentation source of truth. Documentation proves that a contract was recorded, not that a production service is reachable. Check the runtime separately before building against it.

## Where integrations connect

| Purpose | Contract route | What it does | Authentication / current state |
|---|---|---|---|
| Discover AI tools | `GET /api/v1/spec` | Lists tool schemas and their DNA OS command names. | Public by contract; returned HTTP 404 on `dnaos.dev` on 2026-11-13. |
| Discover capabilities | `GET /api/v1/capabilities` | Lists registered capabilities and can compose a plan. | Public by contract; returned HTTP 404 on `dnaos.dev` on 2026-11-13. |
| Find module owners | `GET /api/v1/modules` | Lists modules, owners, layers, and exports. | Public by contract; returned HTTP 404 on `dnaos.dev` on 2026-11-13. |
| Execute through the central processor | `POST /api/v1/query` | Sends a registered command through the gateway, policy checks, and dispatcher to the owning engine. | Requires `X-DNA-Token`; runtime not reachable at the checked host because the public API routes returned 404. |
| Receive provider events | Provider-specific webhook / observe route | Accepts signed provider events, then passes them through the integration gateway. | Use each provider's documented signature and route. Never send internal secrets from a client. Production readiness must be checked per route. |

## Processing path

`AI or external app → API discovery → authenticated API gateway → permission and confirmation checks → command dispatcher → owning engine → approved data/service boundary`

For provider events, use the documented provider webhook adapter and event gateway. External integrations must not call `/api/internal/*`, access the database directly, or bypass the canonical writer. Those paths are internal server-to-server boundaries.

Read commands can return data within the API token's permitted scope. Write commands must follow the confirmation and permission requirements in the contract; do not retry or automate a write when the gateway says confirmation is required.

## Credentials and AI clients

- API tokens are issued through the authenticated DNA OS admin token-management flow documented in the portal. Do not place tokens in browser code, prompts, public files, or client-side app bundles.
- The public portal and JSON contract require no DNA OS login. That makes documentation discoverable; it does not grant access to business data or the processing API.
- The registry exposes a tool-schema route for AI tool-use, but no reachable production API or remote MCP server was verified on 2026-11-13. Common chatbots need a compatible API connector or a live MCP/API service to execute actions; this documentation site alone only supplies reference material.

## Rules for coding agents

- Start from this page and the JSON contract; do not search the repository broadly.
- Treat `registryRefs` as the narrow source pointers for a specific contract.
- Do not invent route behavior, secrets, production URLs, or live status. State the verification date and the environment used.
- Keep read and write capabilities separate. Preserve API scope checks, explicit write confirmations, audit records, and canonical-writer boundaries.