Live Coding: Setting Up DocPilot on a Real Repository

Hook

There is a particular kind of confidence that only comes from watching a tool do real work on a real repository — not a contrived demo with five files and a tidy folder structure, but a working project with half-finished features, stale READMEs, and that one orphan endpoint nobody wants to touch. This is that walkthrough. In the next fifteen minutes, we will point DocPilot at a live GitHub repo, watch it read the codebase, generate a complete documentation set, and then prove the sync works by pushing a commit and seeing the docs update before the coffee cools.

No staged screenshots. No mock data. Just a terminal, a browser tab, and a repository that was, until now, relying on a hand-written README from 2022.

The Repo We Are Starting With

The target repository is a small Node.js service called tx-svc — a transaction-processing API used in a previous DocPilot stress test. It has:

• 47 source files across src/, routes/, and lib/
• A README written when the project had three routes and two of them were broken
• An OpenAPI spec that is roughly 40% accurate
• No architecture documentation
• Two contributors and one active production bug

This is the kind of repo where documentation debt is measurable in deploy anxiety.

Step 1: Connecting GitHub

The first thing any DocPilot session needs is a connection to where the code actually lives. From the DocPilot dashboard, the flow is intentionally short:

1. Click Connect Repository.
2. Authorize the GitHub App for the organization (or personal account) that owns the repo.
3. Select tx-svc from the list.

For a private repo, the GitHub App needs read access to contents and metadata. DocPilot requests the minimum scopes required — no write access to code, no admin scopes, nothing that would let a misconfiguration escalate. The permission set is visible during installation, and the audit log lives in GitHub under Settings → Installed GitHub Apps.

What Happens Behind the Modal

Once authorized, DocPilot performs an initial clone of the repository into its analysis environment. For tx-svc, the clone completed in under nine seconds. The platform then runs a language detection pass — Node.js and JavaScript in this case — and queues the repository for documentation generation.

Step 2: First-Pass Documentation Generation

The default behavior is to generate four documents on the first pass:

• README — rewritten to reflect current functionality
• Setup Guide — environment, dependencies, environment variables, run commands
• Architecture Overview — module map, data flow, external integrations
• API Reference — derived from the source, cross-checked against the OpenAPI spec where one exists

For tx-svc, generation took 84 seconds. The progress indicator showed four parallel stages, one per document, each independently rerunnable.

Reading the Output

The generated README is where the most visible improvement lands. The original began with ## Installation and a three-line snippet that no longer works because the project switched package managers last year. The DocPilot-generated README opens with:

• A one-paragraph description of what the service actually does, derived from src/index.js and the route handlers
• A feature list pulled from exported functions and named route groups
• A corrected installation block using pnpm, the current package manager
• A configuration section listing every environment variable read from process.env, with defaults inferred from the code

This is not a paraphrase of the existing README. DocPilot reads the code first and treats any existing documentation as a hint, not a source of truth.

Step 3: The API Reference

The API reference is usually the most labor-intensive document to maintain by hand, which is why it is usually the most out of date. For tx-svc, DocPilot walked the Express route definitions and produced:

Method	Path	Handler	Auth	Notes
POST	/transactions	createTransaction	required	idempotency-key header
GET	/transactions/:id	getTransaction	required	—
POST	/transactions/:id/refund	refundTransaction	required	admin scope
GET	/health	healthCheck	none	liveness probe

The interesting moment came when DocPilot flagged a discrepancy. The OpenAPI spec in the repo documented a /transactions/:id/capture endpoint that does not exist in the code. Rather than copying the spec, DocPilot marked the endpoint as declared but unimplemented and linked the spec file as evidence. That is the kind of finding a static analysis tool might surface, but documentation tooling rarely does.

Drift Detection in Practice

DocPilot stores a hash of the source tree at generation time. On every subsequent webhook, it compares the incoming commit's affected files against the last analyzed version and regenerates only the documents that depend on those files. Editing a route handler regenerates the API reference. Renaming a module regenerates the architecture overview. Changing the package manager regenerates the setup guide.

Step 4: Wiring Up the Webhook

Once the initial docs are in place, the next step is keeping them there. DocPilot installs a webhook on the repository that fires on push events. The setup happens automatically when the GitHub App is granted push permissions, but it can be verified from Repo Settings → Integrations.

Testing the Sync Live

This is the part of the walkthrough that tends to surprise people. With the webhook active, we made a small change to tx-svc — adding a new query parameter to the getTransaction handler:

router.get('/transactions/:id', validateScope('read'), async (req, res) => {
  const { id } = req.params;
  const { includeArchived } = req.query;
  const transaction = await transactionService.findById(id, {
    includeArchived: includeArchived === 'true'
  });
  // ...
});

Commit, push, and watch the DocPilot dashboard. Within seven seconds, the analysis pipeline picked up the new commit. Within another forty seconds, the API reference had been regenerated and the change was reflected in the published docs. The setup guide and architecture overview were untouched — the diff in routes/transactions.js did not affect them, and DocPilot did not waste compute regenerating documents that did not need to change.

What Triggers a Full Regeneration

For the curious: a full regeneration is forced when DocPilot cannot determine which documents are affected. This happens on force pushes that rewrite history, on bulk file renames that touch more than 30% of the project, or when the user clicks Regenerate All from the dashboard. Otherwise, the platform errs on the side of incremental updates, which keeps both latency and cost low.

Step 5: Review and Publish

DocPilot generates into a staging environment by default. Before documents replace the existing README or spec files in the repository, a human has to approve the change set. For tx-svc, the diff against the existing README was substantial — 187 lines added, 42 removed — and was presented as a pull request rather than a direct push.

The pull request description included:

• A summary of what changed and why
• A list of source files that informed the new content
• A confidence score per section, based on how much of the content was derived from code versus inferred from naming

That last point matters. Sections marked low confidence are the ones where DocPilot had to guess — typically business context, deployment topology, or anything that lives outside the repository. Those sections are kept as suggestions rather than committed as facts.

What the Repo Looks Like Now

After the live session, tx-svc had:

• A README that accurately describes the current state of the service
• A setup guide that works on a clean clone
• An architecture overview showing the dependency graph between modules
• An API reference that reflects actual route definitions
• A webhook that keeps all four documents in sync going forward

The total time from connecting the repository to opening the documentation PR was under four minutes. The total time to approve and merge the PR was a separate decision — and a deliberate one, because documentation that auto-merges without review is documentation you cannot trust.

Common Questions From the Live Session

Does DocPilot write to the repository directly? Only when explicitly configured to. The default is to open a pull request and wait for human approval.

What about monorepos? Supported. Each package can be documented independently, and DocPilot will detect workspace boundaries from pnpm-workspace.yaml, package.json workspaces, or lerna.json.

Can it generate docs in languages other than English? Yes. Output language is configurable per repository, and the model translates technical content with the same fidelity it generates in English.

What happens if the codebase is too large? For repositories over a configurable threshold (default 50,000 lines), DocPilot switches to a sampled analysis and flags sections of code that were not read. The user can then expand the sample or run a full analysis on demand.

Closing Thoughts

The reason this walkthrough works as a live demo is that DocPilot does not need a clean repo to be useful. The messier the starting point, the more visible the improvement. A tool that can only generate documentation for a freshly scaffolded project is a toy. A tool that walks into a repo with stale docs, half-broken specs, and missing sections — and leaves it with a coherent documentation set and a webhook that keeps it there — is infrastructure.

If you have a repository that has been on your documentation backlog for longer than you want to admit, the fastest way to see what DocPilot does with it is to point it at the actual code. Free tier covers public repositories and a limited number of private ones; paid tiers scale by repository size and sync frequency. The GitHub App install takes about thirty seconds, and the first documentation pass takes about as long as it takes to brew a cup of coffee — which, conveniently, is also how long the sync takes once you push your first commit afterward.