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 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.

The host does not matter: GitHub, Bitbucket and GitLab remotes are all read, in either SSH or HTTPS form, and a nested Bitbucket or GitLab group is recorded in full — strategiq/clients/checkout-web, not flattened to its last two segments. Only a local-path origin cannot be read, because there is no host-relative path to record; pass --repo explicitly in that case.

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.

Diagrams

A ```mermaid fence renders as a diagram, in both light and dark theme — it is not shown as code. Flowcharts, sequence diagrams and the rest of mermaid’s types all work.

flowchart LR
    A[Codebase] --> B[atlas push]
    B --> C[Atlas repo]
    C --> D[Coolify build]
    D --> E[atlas.strategiq.dev]

Rendering happens in the browser, so keep diagrams to plain ASCII edges and avoid <, > or quotes inside labels. A diagram that mermaid cannot parse renders as nothing, and the build will not catch it — check the page after pushing.

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.