Docs as code: keep your voice agent in step with your Git docs.

What does docs as code mean for an AI agent?

Docs as code means writing documentation with the same tools as code: issue trackers, version control, plain-text markup such as Markdown, code review and automated tests. Changes go through a pull request, and merging publishes them.

An AI support agent is a second reader of those docs. If it answers from a copy, the copy has to follow the same flow, or callers hear last month’s answer after your docs site has moved on.

How does the GitHub import read your docs?

The import is simple, and each of its rules shapes how you write.

• Each import takes one .md, .mdx or .txt file of up to 50,000 characters into the support agent’s knowledge. It can’t read reStructuredText or AsciiDoc files, so paste those pages in as documents.
• It reads the file from the repository’s default branch as raw text. Components, front matter and comments arrive as written, and snippets your docs build pulls in from other files don’t arrive at all.
• The source is titled with the repository and path, such as your-org/docs / guides/invite-teammates.md. The title counts when the agent searches, so file names in customers’ words help it find the right file.
• Public repositories need no setup. Ask us before relying on a private one, because access is set up on our side for each workspace.
• The sales agent never sees GitHub imports. Copy anything sales needs, such as plan limits, into a sales note.

1. Choose the docs worth importing.

Start with the pages behind your most common support questions: setup, billing, permissions and the errors customers hit most. A workspace holds 100 sources across both agents, so leave out pages nobody asks about aloud, such as changelogs and contributor guides.

Short files work best. The agent reads up to four sources for each search, in excerpts of about 4,500 characters, so the answer in a 20,000-character page can sit outside what it reads. Splitting a page that covers several tasks helps your readers as well as the agent.

2. Write docs that read well as raw text.

The agent sees the file the way your editor does, not the way your docs site renders it.

• Put the answer in plain prose near the top. Tabs, accordions and other components reach the agent as markup, so keep key steps outside them.
• Add a one-line description in customers’ words to the front matter. It sits at the top of the file, so when it uses the caller’s words, the excerpt starts there.
• Write out values your build fills in, such as product names or version numbers held in variables. The import sees the placeholder, not the value.
• Describe each step in words. The agent can’t see images.

3. Re-sync changed files after each merge.

Nothing syncs automatically when you push. After a docs change merges, re-sync each changed file with the refresh button on the Knowledge tab, the sync_github MCP tool or POST /api/manage/github. Each re-sync, even of unchanged text, sets the source back to Needs review. If GitHub can’t return the file, the sync fails and the old version stays as it was.

A re-synced file stops answering until someone approves it, which cuts both ways: callers stop hearing the old text straight away, and the agent knows less until the new version is approved. So re-sync only files that changed, and approve them the same day.

The GitHub Actions workflow below re-syncs the Markdown files under docs that a push to main changed, and lists any that were deleted or renamed. It follows GitHub’s documentation as reviewed on 8 October 2026. It isn’t a built-in feature, so try it in a test repository first.

Store a workspace token as an encrypted Actions secret named KAWLNOW_TOKEN. A token can also approve sources, so the workflow never calls the approval endpoint, and a person approves each file after reading it.

# .github/workflows/resync-voice-agent-docs.yml
name: Re-sync changed docs for voice agent review
on:
  push:
    branches: [main]
    paths:
      - 'docs/**/*.md'
      - 'docs/**/*.mdx'
permissions:
  contents: read
jobs:
  resync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - name: Re-sync changed files (each one waits for approval)
        env:
          KAWLNOW_TOKEN: ${{ secrets.KAWLNOW_TOKEN }}
          BEFORE: ${{ github.event.before }}
        run: |
          # In git pathspecs, * also matches /, so subfolders are included.
          git diff --name-only --no-renames --diff-filter=AM "$BEFORE" "$GITHUB_SHA" -- 'docs/*.md' 'docs/*.mdx' |
          while read -r path; do
            echo "Re-syncing $path for review"
            body=$(jq -n --arg repo "$GITHUB_REPOSITORY" --arg path "$path" '{repo: $repo, path: $path}')
            printf 'Authorization: Bearer %s\n' "$KAWLNOW_TOKEN" |
              curl -sS --fail-with-body -X POST 'https://app.kawlnow.com/api/manage/github' \
                -H @- -H 'Content-Type: application/json' -d "$body"
            echo
          done
          git diff --name-only --no-renames --diff-filter=D "$BEFORE" "$GITHUB_SHA" -- 'docs/*.md' 'docs/*.mdx' |
            sed 's/^/Deleted or renamed, remove its old source: /'

4. Remove sources for renamed and deleted files.

A sync is tied to a repository and path. A renamed file becomes a new source on its first import, and the source for the old path keeps answering until you remove it.

A deleted file doesn’t remove its source either. Re-syncing it fails because GitHub can’t find the file, so the last approved text keeps answering. Remove the source on the Knowledge tab or with DELETE /api/manage/sources/{id}. Over MCP, approve_knowledge with approved set to false takes it out of the agent’s knowledge.

5. Add the agent to your docs review.

Add a few lines to your pull request template, so the author flags changes that affect spoken answers and names who approves the re-synced file. The agent then gets the same review your docs already have.

## Voice agent
- [ ] This changes an answer the support agent may give
- [ ] After merge, the changed files are re-synced and approved (owner: @name)
- [ ] Sources for renamed or deleted files are removed

Common questions