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#

If your tool supports skills, run atlas skills install and start from the atlas skill. Each skill holds the imports and patterns for one kind of work, which usually removes the need for the steps below.

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#

Select released library modules with the Atlas installer:

bunx --package https://github.com/wess/atlas/releases/download/v0.5.1/wess-atlas-cli-0.5.1.tgz atlas add server config db/postgres db/query

See README.md for the release candidate's publication status. Import public @wess/atlas/<module> entry points, for example @wess/atlas/server, @wess/atlas/auth/password, or @wess/atlas/db/postgres. The installer includes the selected implementation packages and their dependency closure. Applications must build without source aliases, links, local tarballs, or a local Atlas checkout. Keep exact coordinated Atlas versions and the application's lockfile.

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.
• Route web apps with real paths through the History API, never # routes or in-memory view state.
• 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, and cache-flush tools exist only when writes are allowed (ATLAS_MCP_ALLOW_WRITES=1), and these 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

For skills, also run bun run skills:verify, which typechecks every snippet against the source.

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