How we built docs.gritiva.com in 12 hours with an LLM drafter#

Published 2026-05-14. A behind-the-scenes look at building a 56-doc documentation site in a single day.

The starting line#

At 09:00 UTC on 2026-05-14, docs.gritiva.com had 0 published docs. The system existed (a FastAPI backend + Next.js frontend + Celery workers + an LLM drafter) but had been sitting dormant since August 2025. By 21:00 UTC the same day, the site had 56 docs live across 8 categories, plus a fully redesigned visual aesthetic.

This post walks through how — what we automated, what we wrote by hand, what broke, and what we learned about LLM-drafted documentation.

The system#

The docs drafter we ship at gritiva-docs-backend/ is a multi-stage pipeline:

enqueue → planning (LLM) → indexing (walks repo) → extracting (LLM) →
drafting (LLM) → review (LLM generates Q's) → waiting_feedback →
[human answers] → redraft (LLM) → approve → publish

Each stage is a Celery task; intermediate state lives in doc_iterations rows. The LLM is gpt-4o-mini via OpenAI, with prompts shaped by stage.

What we automated#

20 of the 56 docs went through the LLM pipeline. The pattern:

# 1. Create a Document shell with rich meta hints
POST /api/admin/docs/ { "title": "Concepts: Mesh", "meta": {...} }

# 2. Enqueue the LLM pipeline
POST /api/pipeline/docs/enqueue { "document_id": ... }

# 3. Wait ~30s for v1 draft (planning + indexing + drafting + review)
GET /api/pipeline/docs/status/{job_id} until iteration_status="waiting_feedback"

# 4. Redraft with explicit MUST-INCLUDE notes
POST /api/pipeline/docs/iterations/{iter}/redraft { "notes": "MUST INCLUDE EXACTLY ..." }

# 5. Wait ~30s for v2 draft
# 6. Approve
POST /api/pipeline/docs/iterations/{iter}/approve

We ran 12 such jobs in parallel for the operator + developer + user-facing batches. End-to-end: ~5 minutes for 12 docs to land published.

What broke (and what we learned)#

The meta field is silently ignored#

We poured rich meta.audience / meta.purpose / meta.module_hints / meta.key_terms into the document creation calls, expecting the planner LLM to read them and stay on-topic. It didn't. The first drafts of "Concepts: Scope" and "Concepts: Mesh" hallucinated generic project-management theory and 802.11s WiFi mesh content respectively, with zero reference to GritivaCore.

We documented this as the meta-ignored failure mode and worked around it with redraft notes. The real fix — plumbing meta.* into the planner's LLM prompt — is on our roadmap.

Verbatim commands need "MUST INCLUDE EXACTLY"#

In the v1 Quick Start draft, the LLM hallucinated sudo apt install gritivacore (which doesn't exist) instead of using the curl ... | sudo bash install we'd given as context in a question answer.

Workaround: in the redraft notes field, prefix every literal command with "MUST INCLUDE EXACTLY" and the LLM honors it. The v3 Quick Start has all 4 verbatim commands, no hallucinated apt.

Real bugs surface fast when you dogfood#

The very first dogfood attempt at a redraft hit IntegrityError: duplicate key value violates unique constraint "uq_doc_jobs_active_unique_doc" — the redraft handler tried to INSERT a new DocJob while the previous one was still in needs_input. PR #58 fixed it. We never would have found it without driving traffic through.

Drift footgun: prod is a git working tree#

Mid-day, the same fix appeared to revert from prod three times in a row. Root cause: /var/www/vhosts/gritiva.com/ is a Git working tree on branch recon-safe-additions-2026-05-13 (NOT main), and other Claude Code sessions on the same server periodically run git checkout -- . && git pull origin main which wipes any ad-hoc sudo cp deploys. Full write-up. Workaround: deploy via git checkout origin/main -- <subtree>, not scp.

What we wrote by hand#

36 of the 56 docs are hand-written. The categories where this matters most:

• Sales / marketing — Pricing, Why GritivaCore, vs Tailscale, vs Kubernetes. The LLM can't fake the "honest about limits" voice we want.
• Legal — Privacy Policy, Terms of Service, SLA, Subprocessors. The LLM is too vague for legal.
• Customer Success — FAQ + Common Errors. We need the real errors we've seen in support, not Wikipedia generalities.
• Reference — Investors, Press kit, Brand guidelines, Security disclosure. Voice matters.
• Runbooks — 8 of them. Each one is operationally specific (exact commands, exact severity assessments, exact mitigations); the LLM produces something that looks like a runbook but isn't actionable.

Cost#

The whole pipeline run cost about $1.20 in OpenAI API spend (~80 LLM calls across 20 docs × 4 stages). The hand-written content cost a couple hours of focused writing. The visual upgrade was about 4 hours of frontend work.

Compared to "hire a tech writer for 2 weeks at $5k", the trade-off is real. The catch is — you cannot ship the LLM output as v1. You need to redraft each one with strong notes, AND you need to hand-write anywhere voice or precision matters.

What we'd do differently#

1. Fix the meta-ignored issue first. Would have saved 30 minutes of hallucination cleanup.
2. Build a CLI for the pipeline. We wrote ad-hoc Python scripts for batch operations; a gritivactl docs batch CLI would be much cleaner.
3. Skip LLM for runbooks. v1 was too generic to be useful even after redraft. Hand-write them and treat the LLM as a polish pass.

What we shipped#

The site is at docs.gritiva.com. The system that produced it is at github.com/mohammad2000/GritivaCore/tree/main/gritiva-docs-backend. Try it yourself.

— Mohammad