# How we keep our docs in sync with the code

The docs agent we run on Kortix — connected to GitHub and our codebase. Once a day it checks the code that landed since its last run and updates the docs those changes affected, opening a PR for review.

Canonical page: https://openchatly.com/use-cases/docs-maintainer

Documentation tends to fall behind the code. The README, the setup guide, the
API reference, and architecture notes drift a release or two back while the code
keeps changing. The person who changes the code is usually not the person who
owns the page it affects, so the two rarely get updated together. A renamed
environment variable, a new setup step, or a removed endpoint is a small code
change and a docs change that often goes unmade.

We handle this by running a docs sweep close to when the code changes: once a
day, over everything that merged since the last run. This writes up how we run
that on Kortix — the connections, the steps, and the guardrails — so you can set
up the same thing for your own repo.

- **Team:** Kortix
- **Source of truth:** The codebase
- **Connected systems:** GitHub · Codebase · Docs site
- **Mode:** Daily sweep · PR-gated

## The problem

The common fixes each have limits. "Docs are part of the PR" tends to get cut
under deadline. A scheduled audit finds drift late and in bulk, when
reconstructing what changed is hardest. And a generic AI writer pointed at the
docs produces prose that doesn't match the code, because it never reads the code.

We wanted the docs we already have to stay accurate to the code, updated on each
merge rather than in periodic cleanups.

## What we built

On Kortix, a docs agent runs once a day in the same persistent session — a
cloud sandbox — with scoped access to what a docs update needs: the commits
that landed since its last run, the codebase for context, and the docs. It
picks up from a checkpoint it kept from the previous run, determines what
changed, rewrites the affected pages, and opens a single docs PR for review.
Nothing publishes without a human merge.

## How it works

### Copy the setup prompt into a new session

Open your Kortix workspace, start a new session, paste this prompt and send it.
The agent writes the agent file, the docs sync skill and the daily trigger,
and opens a change request for you to review. Prefer clicks? Choose **Use this
template** instead.

**Setup prompt**

```
Set up a daily docs maintainer agent in this workspace.

1. Create the agent agents/docs-maintainer.md. Its job is to keep the docs in owner/repo accurate to the code. It may use the GitHub connector and open pull requests.

2. Create the skill skills/docs-sync/SKILL.md with these rules:
   - Read the last checkpoint commit from memory/docs-sync-log.md, then read every commit that landed since then.
   - Read the changed code in full, not only the diff.
   - Find every page under docs/ and every README that the change made wrong. Update only the affected section.
   - Docs and READMEs are the only files you edit. If the code looks wrong, log it for a person. Never change code.
   - Group the day's changes into one pull request, with the commit that prompted each one. Never merge it.
   - If nothing doc-visible changed, move the checkpoint forward and stop without a pull request.

3. Add a cron trigger daily-docs-sync to kortix.yaml. It runs the docs-maintainer agent every day at 06:00 with the prompt "Load the docs-sync skill and run one docs sync pass on owner/repo."

4. Tell me which of these connectors are not connected yet.

5. Open a change request with all of it. Do not merge it.
```

### Connect your tools

Open **Connectors** in your workspace and connect GitHub. Credentials are brokered server-side and never enter the agent's machine.
Add a GitHub token as the `GH_TOKEN` secret so the agent can open the pull
request.

- **GitHub** (Required):
Reads new commits and opens one PR with the doc updates.
- **Mintlify** (Optional):
Publishes the docs once a person merges the PR.

### Run it once with this prompt

Merge the change request, then start a session with the **docs-maintainer** agent
and send this prompt. Read the pull request before you let the
schedule take over.

**Prompt**

```
Run one docs sync pass on owner/repo.

1. Read the checkpoint in memory/docs-sync-log.md and list the commits since then.
2. For each commit, read the changed code and note what behavior changed.
3. Search docs/ and every README for text that no longer matches the code.
4. Update only those sections, in the style the docs already use.
5. Open one pull request with the commit and the reason for each change. Do not merge it.
6. Move the checkpoint to the newest commit you read.
```

### Let the daily schedule take over

The change request added this trigger to `kortix.yaml`. From now on the agent
runs every day at 06:00, each run in a new session on its own cloud computer.
The checkpoint in memory tells each run where the last one stopped.
To change the time, edit the cron line, or open **Triggers** in the workspace.

**kortix.yaml**

```yaml
triggers:
  - slug: daily-docs-sync
    name: Daily docs sync
    on:
      cron: "0 0 6 * * *"
    run:
      agent: docs-maintainer
      prompt: Load the docs-sync skill and run one docs sync pass on owner/repo.
```

### Edit only docs, through a pull request

The agent edits only files under the docs path and README files. The rest of
the code is read-only to it. When the code itself looks wrong, it logs the
problem for a person instead of changing it. A person reviews the pull request
and merges it.

### Review the pull request

Each run ends with one docs pull request, or none when nothing drifted. This is
what a run looks like in the session:

> **Daily docs sync · 06:00**
>
> Prompt: Load the docs-sync skill and run one docs sync pass on owner/repo.
>
> Read **9** commits since the last checkpoint. **3** changed documented
> behavior: a renamed env var, a new API endpoint and a removed CLI flag.
> Updated **4** pages in one pull request, and the checkpoint moved to the
> newest commit.

> **The pattern**
> Connect the repo via a **trigger** on merge, give the agent scoped
> **connectors** into the diff, the codebase, and the docs, encode the writing
> standard as **skills** and **memory**, and gate every change behind a reviewed
> **PR**.

## Make it do more

Once it works, paste any of these into the same session.

**Draft missing pages**

```
When a commit adds a public endpoint or command with no doc page, draft a new page for it in the same pull request.
```

**Check code samples**

```
Run every code sample in the pages you change, and fix the sample when its output no longer matches the text.
```

**Find quiet drift**

```
Every Friday, list the doc pages that have not changed in 6 months but describe code that changed since then.
```

## Guardrails

Giving an agent write access to documentation is a trust question. The relevant
controls on Kortix:

- **Isolation.** The daily sweep runs in its own isolated sandbox, resuming the
  same session across runs via a durable checkpoint rather than persisting the
  raw repo state. The session can read the whole repo to understand a change,
  and only the docs PR it opens is written back out.
- **Scoped secrets.** The GitHub credential is encrypted in the secrets manager,
  injected into the sandbox at runtime, and scoped to the agents you grant it to.
- **PR-gated.** No change reaches a branch anyone reads without a person reviewing
  the diff and merging it.
- **Everything is code.** The agent's persona, skills, and permissions are files
  in the repo — versioned and changed through a reviewed **change request**, not a
  dashboard setting.

## The outcome

- **Daily:** Docs re-checked against the code that landed since the last run
- **Same-day:** Drift caught before it reaches a reader
- **3 systems:** The diff, the codebase, and the docs — in one agent

The backlog of "someone should update the README" changes now arrives as small,
reviewable PRs within a day of the code landing, with the reasoning written
down. The team reviews a diff instead of reconstructing months of drift, and
readers stop hitting instructions that are no longer accurate.

The setup relies on four pieces working together: sandbox isolation for the
daily session, a secrets manager to broker the GitHub token, a PR gate on every
change, and a durable checkpoint that carries the sweep forward run to run.
