atlas

A local docs-state console for agentic development.

One shared frontmatter schema for markdown documentation across every slothworks repository, plus a small toolchain over it: a CLI (validation in CI), an MCP server (agents), and a local web UI (humans). Files stay where they are and remain the source of truth; atlas only reads them, enriches them with git history, and writes frontmatter back.

Status: core, CLI, MCP and web console implemented; the post-v1 backlog is reconciled — see the follow-ups doc for what remains.

• Design spec — docs/superpowers/specs/2026-09-06-atlas-docs-console-design.md
• Claude Design prompt — docs/design/claude-design-prompt.md
• Implementation plan 1 (core + CLI + MCP) — docs/superpowers/plans/2026-09-06-atlas-core-cli-mcp.md
• Web design — docs/superpowers/specs/2026-09-06-atlas-web-design.md
• Implementation plan 2 (web console) — docs/superpowers/plans/2026-09-06-atlas-web.md
• Implementation plan 3 (backlog rename, migration, dashboard) — docs/superpowers/plans/2026-09-07-atlas-backlog-and-follow-ups.md
• Follow-ups after the web branch — docs/ideas/web-follow-ups.md

Install

Published to npm as a public package, installed once globally:

bun install -g @slothworks/atlas

atlas init       # sets up this repository, or atlas on this machine
atlas upgrade    # checks the CLAUDE.md blocks, the skill and MCP, offers a fix
atlas start      # starts the console on :4321 and opens the browser
atlas stop       # stops it
atlas serve      # runs the console in the foreground, without a browser
atlas validate   # runs in each repository's PR gate
atlas migrate    # rewrites frontmatter that a renamed field value broke
atlas mcp        # stdio MCP server, launched by the agent, not by hand

If the shell answers command not found: atlas, the install worked and the command is in ~/.bun/bin, but that directory is not in your PATH. It happens when bun itself came from Homebrew: the official bun installer adds the line to your shell profile and Homebrew does not. Add it once, then open a new terminal:

echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.zshrc

One instance, fixed port. atlas start on an already-running console just opens the browser.

Configuration

Per-machine, at ~/.config/atlas/config.json (never in this repo). atlas init --global writes it for you; here is what it contains:

{
  "roots": ["~/Projects/slothworks"],
  "port": 4321
}

Each connected repository carries its own docs/atlas.json marker, committed — see §6 of the design spec.

Develop from a checkout

bun install

bun run start      # builds the client, starts the console, opens a browser
bun run stop       # stops the console
bun run restart
bun run check      # tests, both typechecks, client build — run before committing

bun run stop reads ~/.local/share/atlas/daemon.json, which the running server writes, and stops only the process recorded there. Anything else holding the port is reported, not killed: the port tells you something is listening, not whose process it is.

Against this repository's own documents:

bun run validate
bun run migrate

Against any other repository, and for the parts with no script:

bun packages/cli/src/bin.ts serve [--port <n>]
bun packages/cli/src/bin.ts init [--repo <path>] [--global] [--yes] [--name <name>]
bun packages/cli/src/bin.ts validate --repo <path>
bun packages/cli/src/bin.ts migrate --repo <path> [--apply]
bun packages/cli/src/bin.ts mcp

atlas migrate is the command someone adopting the schema in another repository needs: it rewrites documents whose frontmatter still carries a renamed field value (today, status: idea to status: backlog) to the current schema. It reports what it would change and writes nothing unless --apply is given, and it is otherwise not discoverable — there is no prompt for it anywhere else.

Development, with hot reload:

bun run dev        # client on :5173, proxying /api to :4321

The API server is separate in this mode — start it with bun run start in another terminal.

Releasing

The workspace has four packages, but only one is published. bun run build:npm bundles the CLI, the MCP server, core and the web server half into a single file under dist/npm, next to the built client, and writes a manifest with no workspace:* references, which npm cannot resolve.

.github/workflows/publish.yml does that on every push to main. The version in packages/cli/package.json is the release version: bump it to release. If that version is already on npm, the job says so and stops, so a merge that changes only docs stays green.

Auth is npm trusted publishing over OIDC, so there is no token in the repository and no secret to rotate. The trusted publisher is registered on npmjs.com against this repository and publish.yml.

Next steps

1. Backfill ergaily and split its ADRs into docs/decisions/. atlas migrate is the first step of that, not the whole thing.
2. Point ergaily's Stop hook and skills at the atlas MCP server.
3. Pay back the web package's remaining test debt — the server half (routes, watcher, reconciliation) is now covered; the views still have none by decision. See docs/ideas/web-test-coverage.md.
4. Publish 0.1.0 to npm by hand, then register the trusted publisher on the package page. npm only accepts one for a package that already exists, so the first release cannot come from CI. Every release after that does.