Getting started with Atlas

Install

npm i -g github:StrategiQ-Dev/strategiq-atlas
atlas doctor

Authentication is your existing GitHub SSH key. No registry, no token, no login.

Wire up a codebase

Run once per repository:

cd ~/code/some-client-site
atlas init

This adds the atlas MCP server to .mcp.json, an instruction block to CLAUDE.md, and the /atlas-audit skill to .claude/skills/. Restart Claude Code afterwards. Claude can then search and write Atlas without being asked. Running it twice is safe — it replaces its own block rather than appending a second one, and rewrites the skill file from the current template.

Write a page

atlas push notes.md --site checkout --type runbook --title "Stripe webhook fails"

atlas fills in the owner from your git config, the source repository and commit from your working directory, and today’s date. Do not write frontmatter yourself.

Type	Slug	Path
`architecture`	none	`sites/<site>/architecture`
`onboarding`	none	`sites/<site>/onboarding`
`feature`	defaults from the title	`sites/<site>/features/<slug>`
`runbook`	defaults from the title	`sites/<site>/runbooks/<slug>`
`integration`	defaults from the title	`sites/<site>/integrations/<slug>`

Use --site platform for anything that is not about one client site.

Amend a page

Writes replace the whole file, so read first:

atlas read sites/checkout/architecture > /tmp/edit.md
$EDITOR /tmp/edit.md
atlas push /tmp/edit.md --site checkout --type architecture --title "Checkout architecture"

The original author stays as owner; last_verified moves to today.

Add a new site

cd ~/code/some-client-site
atlas add-site checkout --name "Checkout Web"

--repo defaults to the current repository’s GitHub origin and --owner to your git user.email, so run it from the codebase you are about to document. Both can be passed explicitly. The slug is canonicalised for you — Checkout Web becomes checkout-web.

Until a site is in the registry, atlas push rejects it and the health dashboard cannot show that its documentation is missing. add-site refuses to redefine an existing slug: the dashboard keys off the registry, so a slug reassigned by a typo would report another site’s pages as missing. If an entry is genuinely wrong, edit site/src/data/sites.json in the Atlas repository.

Document a codebase from nothing

atlas init installs the /atlas-audit skill. Run it in a client repository and Claude audits the code feature by feature, then publishes one feature page each.

cd ~/code/blog-site
atlas add-site blog-site --name "Blog Site"
# restart Claude Code, then run /atlas-audit

Feature pages are written for two readers at once — whoever picks the project up cold, and Claude when it is later asked to change that feature. Every page answers the same questions in the same order:

what the feature does and why it exists
entry points, as a table of real file:line paths
how it works, including data and external calls
configuration by variable name (never values)
invariants and gotchas
how to change it safely: what to update alongside, what to run
which tests cover it, and which do not

Claude shows you the feature inventory before writing anything, so you can cut it down. Twelve good pages beat forty thin ones. It finishes by updating the site’s architecture page to link them together, and onboarding with verified local setup steps.

The skill is generated from src/audit-skill.js in this repository and rewritten on every atlas init — improve it there, not in a client repo.

If a write is blocked

The secret gate refused because something looked like a credential. It prints the pattern, the field and the line number, never the value. It scans the body, the title, the description and the commit summary, because a commit message stays in history even after the file is fixed.

There is no override — reword the content. Naming an environment variable is fine; pasting its value is not.