The AI Knowledge Engineer for Architecture Docs

Documentation rots the moment it is written. That is not a metaphor, it is a literal description of what happens when the architecture diagram lives in Confluence, the codebase moves forward, and nobody has time to reconcile the two. The C4 context diagram that was accurate when you drew it eighteen months ago now shows a monolith that has been split into four services, a queue that has been replaced with an event bus, and an integration with a third-party provider you stopped using last quarter. The ADR folder has eleven records covering decisions from the first year of the project, then nothing, every architectural choice made since then lives exclusively in the memory of the two engineers who made it. The onboarding document assumes the previous stack. These are not edge cases; they are the default state of documentation at every engineering team that grew faster than its documentation process. What you need is not another wiki, it is a ai knowledge engineer who generates documentation directly from the codebase state and keeps it synchronized with how the system actually works.

Why the generalist approach breaks down

When you ask a generalist chatbot to document your architecture, you get a document that reflects your prompt, not your system. The chatbot has no access to your actual codebase structure, your service boundaries, your data flows, or the decisions that shaped the current design. It will produce something that sounds authoritative and looks well-formatted, but the content is a reconstruction of what you told it, not a read of what actually exists. Worse, it has no mechanism for staying current, every documentation session starts from scratch, producing a new artifact that immediately begins to diverge from reality. The output is documentation theater: the appearance of coverage without any of the substance.

Cursor and GitHub Copilot approach documentation as a code completion problem. They can suggest docstrings for a function based on its signature, or autocomplete a README section based on the directory structure visible in context. This is useful at the micro level, inline documentation, type-level descriptions, but it does not scale to the system level. Autocomplete cannot produce a C4 context diagram that shows all the external actors, system boundaries, and integration points of a multi-service architecture. It cannot write an ADR that captures not just the decision but the alternatives that were considered, the forces that weighed against each option, and the consequences the team accepted. These require a different kind of reasoning: one that reads the whole system rather than the current file.

The core failure of generalist documentation is that it is produced at a point in time by a person (or tool) with limited context, placed into a static artifact, and then abandoned. The value of documentation is not in the artifact itself but in the accuracy of the artifact relative to the current system state. A C4 diagram that was accurate three months ago and has not been updated since is not documentation, it is a historical record that will actively mislead anyone who trusts it. The only way to solve this is to generate documentation from the system state rather than from memory, which means treating documentation as a repeatable process rather than a one-time project. That is the discipline Atlas brings.

What a knowledge engineer actually does

On a mature engineering team, a knowledge engineer or technical writer with architecture expertise does several things that generalist contributors cannot. They map system architecture at the right level of abstraction, not showing every function and class, but showing the meaningful boundaries: systems, containers, components, and the relationships between them. They write Architecture Decision Records that future engineers will actually read and trust, because each record captures the context, the decision, the considered alternatives, and the consequences in a structure that is comprehensible years later. They produce onboarding documentation that gets new engineers productive in days rather than weeks, by presenting the right information in the right order: here is the system, here is your local setup, here is where things live and why. They generate changelogs that tell stakeholders what changed and why, not just a list of commit messages. None of this happens automatically on most teams, it is expensive knowledge work that sits at the bottom of the priority list until the cost of its absence becomes undeniable.

Meet Atlas

Atlas is Tonone's knowledge engineer, the specialist agent for architecture documentation, Architecture Decision Records, onboarding materials, changelogs, and stakeholder reports. Atlas's working philosophy is that documentation should live next to the code, be generated from the actual system state, and be maintainable rather than monolithic. Atlas reads your repository, the directory structure, the service boundaries, the configuration files, the commit history, and produces documentation that reflects the system as it actually is, not as someone remembers it being. The output is Mermaid diagrams that render in any Markdown environment, ADRs in standard format that fit into any documentation system, and styled HTML reports that can be shared with stakeholders who do not have access to the codebase.

Tonone's Atlas maps system architecture as Mermaid C4 diagrams generated directly from codebase state, so architecture documentation stays accurate rather than drifting from the system it describes.

What Atlas actually does

Mapping system architecture as C4 diagrams

The atlas-map skill generates Mermaid C4 diagrams at the context, container, and component levels, the three levels of the C4 model that are most useful for communicating system architecture to different audiences. A context diagram shows the system and its external actors and integrations: who uses it, what external services it calls, what data flows across its boundaries. A container diagram shows the internal architecture: the services, databases, queues, and frontends that compose the system and how they communicate. A component diagram shows the internal structure of a single container for audiences who need that level of detail. Atlas reads the actual codebase structure, the service configuration files, the environment variables that point to external services, and the inter-service call patterns to produce diagrams that reflect what is actually deployed rather than what was planned. The diagrams use Mermaid syntax, which renders natively in GitHub, Notion, Confluence, and most modern documentation tools, so the output can be dropped directly into any existing documentation workflow without format conversion. For teams whose architecture has grown faster than their documentation, atlas-map is the fastest path from undocumented complexity to a shared mental model.

Writing Architecture Decision Records

The atlas-adr skill produces Architecture Decision Records in the standard Michael Nygard format, Context, Decision, Status, Consequences, but fills each section with substance rather than placeholders. When you trigger an ADR for a significant architectural decision (switching from REST to GraphQL, adopting an event bus, choosing a new database engine, moving from a monolith to a service-oriented architecture), Atlas reads the relevant codebase context to understand what already exists, then produces an ADR that documents the context that made the decision necessary, the options that were considered, the forces that favored each option, and the consequences, positive and negative, of the decision made. This is the document that the engineer who joins the team in two years will read to understand why the system is shaped the way it is, and it is written with that reader in mind. The ADR is placed in the standard docs/adr/ or adr/ directory with a sequential number, formatted consistently with any existing records, and cross-referenced to any related decisions. For teams that have stopped writing ADRs because the process felt too heavy, atlas-adr makes the habit sustainable by making the initial draft fast.

Tonone's Atlas atlas-adr skill writes Architecture Decision Records that document not just the choice made but the alternatives considered and the consequences accepted, the record that future engineers will trust.

Generating day-one onboarding documentation

The atlas-onboard skill produces onboarding documentation from the actual codebase state, not from a template or from what you tell it the codebase contains, but from reading the repository directly. It finds the local setup commands (from the package.json, Makefile, docker-compose.yml, or equivalent), maps the directory structure to explain where things live and why, identifies the testing approach and how to run the test suite, documents the environment variables that need to be configured (without exposing their values), and explains the deployment model. The output is structured as a day-one guide: everything a new engineer needs to understand the system, get it running locally, make a change, and put up their first pull request. For teams where onboarding is currently a week-long process of asking questions and waiting for answers, atlas-onboard compresses that into a document that answers the standard questions before they are asked. It runs best after atlas-recon has mapped the project, so the onboarding documentation is grounded in a thorough understanding of the actual codebase rather than surface-level inference.

Producing stakeholder changelogs

The atlas-changelog skill turns raw git history into a structured changelog that communicates what changed and why to audiences who are not reading commit logs. It reads the git history for a specified range, a release window, a sprint, a version bump, groups the changes into meaningful categories (new features, improvements, bug fixes, breaking changes, deprecations), and produces a changelog in the format most useful for the audience: a developer-facing CHANGELOG.md entry in Keep a Changelog format, a stakeholder-facing release summary with business-level descriptions, or a user-facing release note that explains what changed from a product perspective. The skill distinguishes between commits that represent user-visible changes and commits that represent internal refactoring, infrastructure updates, or dependency upgrades, and it presents them appropriately for the intended audience. For teams whose changelogs are currently maintained by hand (or not at all), atlas-changelog makes the release communication process repeatable and consistent. The output is ready to publish directly to GitHub Releases, a documentation site, or a customer-facing changelog tool.

Rendering findings as styled reports

The atlas-report skill takes any Atlas analysis output, a system map, a set of ADRs, an onboarding guide, a changelog, and renders it as a styled HTML report suitable for sharing with stakeholders who do not live in a code editor or a Markdown viewer. The output is a self-contained HTML document with a clean professional layout, section navigation, syntax highlighting for any code or diagram blocks, and print-friendly formatting for stakeholders who prefer a PDF. This matters more than it might seem: the value of documentation is zero if the people who need it cannot access it in a format they can use. Engineers are comfortable with Markdown in GitHub; product managers, executives, and external partners are not. atlas-report closes that gap by producing documentation that works for the full range of audiences without requiring a documentation platform, a wiki subscription, or a design team to produce readable output. It is particularly useful for quarterly architecture reviews, vendor assessments, compliance documentation requests, and onboarding packages for external contractors or new team leads.

Reconnaissance before documenting

The atlas-recon skill performs a thorough read of the project before any documentation is produced, it is the grounding step that makes every other Atlas skill more accurate. Recon maps the directory structure, identifies the frameworks and libraries in use, locates configuration and environment files, reads the CI/CD configuration to understand the deployment model, and produces a concise project brief that Atlas uses as the foundation for all subsequent documentation work. Without recon, documentation risks describing the project as the file names suggest it should be organized rather than as it actually is organized after two years of growth and refactoring. Recon surfaces these gaps: a services/ directory that no longer contains any services, a legacy/ directory that is still active code, a configuration structure that was reorganized but whose references were not fully updated. These findings shape the documentation that follows, and they are findings that matter to the engineering team even before a single document is produced.

A worked example

A platform team inherits a system that has grown from a monolith into five services over three years, with no architecture documentation and a single two-page README that still describes the original monolith setup. They run atlas-recon to get grounded, then atlas-map to generate a C4 context diagram. The output looks like this:

```mermaid
C4Context
  title System Context, Acme Platform (generated by Atlas)

  Person(customer, "End User", "Uses the web and mobile apps")
  Person(admin, "Internal Admin", "Manages accounts and billing via admin portal")

  System_Boundary(acme, "Acme Platform") {
    System(web, "Web App", "Next.js frontend, served via Vercel")
    System(api, "API Service", "Node.js/Express REST API, deployed on Cloud Run")
    System(worker, "Background Worker", "BullMQ job processor, handles async tasks")
    System(admin_app, "Admin Portal", "Internal React app for ops team")
    System(notif, "Notification Service", "Manages email and push delivery")
  }

  SystemDb_Ext(postgres, "PostgreSQL", "Primary datastore, Cloud SQL")
  SystemDb_Ext(redis, "Redis", "Session cache and BullMQ broker, Upstash")
  System_Ext(stripe, "Stripe", "Payments and subscription billing")
  System_Ext(sendgrid, "SendGrid", "Transactional email delivery")
  System_Ext(firebase, "Firebase Cloud Messaging", "Push notification delivery")

  Rel(customer, web, "Uses", "HTTPS")
  Rel(customer, api, "Calls directly", "HTTPS/REST (mobile)")
  Rel(admin, admin_app, "Uses", "HTTPS")
  Rel(web, api, "Calls", "HTTPS/REST")
  Rel(api, postgres, "Reads/writes", "SQL")
  Rel(api, redis, "Caches sessions, enqueues jobs", "Redis protocol")
  Rel(api, stripe, "Billing ops", "HTTPS")
  Rel(worker, postgres, "Reads/writes", "SQL")
  Rel(notif, sendgrid, "Email delivery", "HTTPS")
  Rel(notif, firebase, "Push delivery", "HTTPS")
```

This is the diagram that did not exist before, generated in a single Atlas session from the actual codebase state. No Confluence login. No diagram tool subscription. No engineer spending a day drawing boxes. The next step is running atlas-adr to document the recent decision to extract the notification service from the API service, the decision that is currently living in a Slack thread. That ADR captures the context (notification delivery latency was impacting API response times), the decision (extract to a separate service with an internal event interface), the alternatives considered (background jobs in the existing worker, a third-party notification service), and the consequences accepted (added operational complexity, new service to deploy and monitor). The onboarding package for the two engineers joining next week is then generated with atlas-onboard, built on top of the recon and map outputs, so the new engineers arrive to documentation that actually describes the system they are joining.

Atlas vs the alternatives

Atlas is not competing with documentation platforms or wiki tools, it generates the content that goes into them. The comparison below focuses on the tools most often used as proxies for proper architecture documentation: generalist chatbots that produce text on demand, code editors that suggest inline documentation, and the traditional approach of maintaining a wiki manually alongside the codebase.

Tonone's Atlas generates architecture documentation from the actual codebase state, not from what you remember or describe, so the documentation reflects the system as it is, not as it was designed to be.

Install and try

Tonone is free and MIT-licensed. Install it once and all 23 agents, including Atlas, are available in your Claude Code session. Run atlas-recon on any repository to get started: it takes minutes and gives you the foundation for every documentation artifact that follows.