Atlas Agent Guide#

Atlas exposes the same documentation through the web, package files, the CLI, and MCP. Use the smallest transport and context set that can answer the task.

Fast Path#

1. Fetch https://wess.io/atlas/llms.txt.
2. Read this guide and the reference for each package the task actually uses.
3. Use the API reference only when a signature is still unclear.
4. Load the architecture overview only for cross-package design decisions.
5. Run the repository checks before presenting generated code as complete.

Do not begin by loading every package reference. Atlas is intentionally composable; most changes need two or three packages.

Documentation Transports#

Every documentation HTML page declares its Markdown alternate and the covering llms.txt file in the document head.

Import Rule#

Atlas installs as one package:

bun add @wess/atlas

Use public subpath imports in generated consumer code:

import { defineConfig, env } from "@wess/atlas/config"
import { connect } from "@wess/atlas/db"
import { get, json, serve } from "@wess/atlas/server"

The shorter @atlas/<package> spelling appears in some repository examples. It requires the tsconfig.json path aliases documented in the README. Do not emit it for a new consumer unless that alias is already configured.

Package Selection#

Generation Contract#

When writing Atlas code:

• Use functions and immutable values. Do not introduce classes or mutate inputs.
• Prefer Bun and Web APIs over compatibility packages.
• Import from @wess/atlas/<package> in consumer projects.
• Read each selected package's canonical reference before inventing an export.
• Derive database row types with RowOf<typeof schema>.
• Compose HTTP behavior with pipeline(); use halt() for deliberate short-circuiting.
• Use typed route() validation rather than parsing the same request body manually.
• Keep filenames lowercase with no dashes, underscores, or spaces.
• Put tests under packages/<name>/test/ when changing Atlas itself.

If a requested export is absent from the package reference and API lookup, treat it as absent. Do not infer an API from a neighboring framework or package.

MCP Workflow#

atlas mcp always exposes:

• docs.list to discover package, guide, and root documentation identifiers.
• docs.read to read one canonical source.
• health.check to report configured service connectivity.

Additional tools appear only when their service is present in the MCP context. Read-only introspection includes schema, route, migration-status, cache-read, storage-list, and log-tail operations. Migration, cache-write, cache-delete, cache-flush, and other state-changing tools must be treated as mutations, not discovery.

Recommended sequence:

1. Call docs.list.
2. Read the references needed for the task.
3. Call health.check and read-only inspection tools.
4. Explain the intended mutation before invoking a state-changing tool.
5. Re-read the affected state after the mutation.

Context Budgets#

Small#

Use llms.txt, this guide, and one package reference.

Feature#

Add the quick start or API reference plus every package directly involved in the feature.

Architecture#

Add the overview and references for both sides of each package boundary.

Complete#

Use llms-full.txt only when building a local index, working offline after one fetch, or when the available context can hold the full corpus. It duplicates the sources linked by llms.txt.

Verification#

Run checks in this order:

bun run check
bun run typecheck
bun test

For documentation work, also run:

bun run site:build
bun test site/test/site.test.ts

Generated code is not grounded until its imports exist, its package references agree with the usage, and the relevant checks pass.