# How we keep our docs matching what the code does Once a day a Machine agent reads every commit merged since its last pass, finds the doc pages those changes made wrong, rewrites them and sends you one pull request to review. Canonical page: https://themachine.myapps.ai/use-cases/docs-maintainer Code moves fast and docs limp after it. Give it a release or two and the README, the setup guide, the API reference and the architecture notes all describe a product that no longer quite exists. Part of the reason is ownership: whoever edits the code is rarely whoever looks after the page. Rename an environment variable, add a setup step or drop an endpoint, and the code change ships in minutes while the matching docs edit simply never happens. So we update the docs while the change is still fresh. Every day an agent looks at whatever merged since it last ran and fixes the pages that drifted. This piece walks through how we set it up on Machine, from the connections to the steps to the limits, so you can copy it for your own repo. - **Team:** Machine - **Source of truth:** The code in the repo - **Connected systems:** GitHub · Codebase · Docs site - **Mode:** One sweep a day · every change goes through a PR ## The problem Every standard answer falls short somewhere. Make docs a required part of each PR and they are the first thing trimmed when a deadline bites. Run a periodic docs audit and you discover the drift all at once, long after anyone remembers why things changed. Point a general-purpose AI writer at the docs and you get fluent paragraphs that are wrong, because it never opened the code. What we actually wanted was simple: keep the docs we already have true to the code, fixed close to each merge instead of in a big clean-up every quarter. ## What we built A docs agent on Machine runs once a day inside one long-lived **session**, a cloud computer (sandbox) that it comes back to on every run. It has limited access to exactly three things: the commits merged since its previous run, the codebase for background, and the docs. It reads the bookmark it left last time, works out what changed, rewrites the pages that are now wrong and opens one docs PR. A person has to merge it before anything goes live. ## How it works ### Hook up GitHub and a daily wake-up A **cron trigger** goes off each day and reopens the same long-lived **session**, instead of starting a new one for every merge. The agent checks the bookmark from its last run and collects every commit on the default branch after it, whether that is one merge or forty. Each doc page that needs work is treated as a separate job, so trouble on one page never holds up the others. The result is a single sweep and a single PR, and the bookmark moves forward at the end even on a day when nothing needed fixing. ### Teach it the code and your house style The way we write docs is kept as **skills** and **memory**, a playbook loaded into every session that the agent keeps improving. It covers how our docs are laid out, the words we use for things, which page owns which topic and fixes that have worked before. The agent follows that guide instead of making up its own, and the guide grows each time a docs PR is merged. ### Connect only what a docs fix needs **Connectors** are scoped links to your tools. The keys stay on our servers, so no raw token ever reaches the model. Through them the agent can: - **Read the change and the code around it**: look at the diff, then at the nearby code, so it understands why something changed and not only what. - **Search across the docs**: track down every page, README and reference section that talks about the behaviour that changed. - **Open a pull request on GitHub**: send the rewritten pages back as a PR you can review, linked to the commit that caused it. ### Set the limits Nothing is pushed to a branch people read. Every edit arrives as a **pull request** and waits for a human to merge it. The agent may only edit files in the docs and README paths, and it can look at the code but never change it. Credentials are stored encrypted in the **Secrets Manager** and only handed to the agents you grant them to. ### Let each day's merges fix their own docs From there it runs itself. Each daily pass sorts through what changed since the last bookmark, spots the pages that no longer match, rewrites them and opens a docs PR that explains its thinking. Rename an env var and the setup guide gets fixed. Ship a new endpoint and a reference entry appears, written from the real handler. Remove a feature and a PR arrives that deletes the outdated section. > **The pattern** > Hook the repo up with a **trigger** tied to its merges, give the agent scoped > **connectors** to the diff, the code and the docs, write your docs style down > as **skills** and **memory**, and send every edit through a reviewed **PR**. ## Guardrails Letting an agent edit your docs means trusting it with words people rely on. Here is what keeps that trust on Machine: - **Isolation.** The daily pass runs in a private sandbox. It returns to the same session each time using a saved bookmark, not a stored copy of the repo. It can read the entire repo for context, yet the docs PR is the one thing it sends out. - **Scoped secrets.** The GitHub key is stored encrypted in the **Secrets Manager**, passed into the sandbox when the run starts, and only handed to the agents you grant it to. - **PR-gated.** No edit lands on a branch people read until someone has looked at the diff and merged it. - **Everything is code.** The agent's persona, skills and permissions are files in the repo, kept in version control. Changing them takes a reviewed **change request**, never a click in a dashboard. ## The outcome - **Daily:** Each day's merges checked against the docs - **Same-day:** Stale pages fixed before readers trip over them - **3 systems:** Diff, code and docs, handled by a single agent All those "somebody should fix the README" moments now show up as small PRs you can review, usually the day after the code merged, with the reasoning spelled out. Your team checks a short diff rather than piecing together months of drift, and readers no longer follow steps that stopped working. Four things make it hold together: a private sandbox for the daily session, the **Secrets Manager** guarding the GitHub key, a PR gate on every edit, and a saved bookmark that lets each run start where the last one stopped.