Failure PatternDecision layer
The Codocly Quota Trap: Why Agencies Fail With Codocly on Multi-Repo Client Retainers
Symptom: Agency account hits the Pro Plan's 40 docs per month ceiling mid-sprint because every Git push to a client repo triggers a fresh generation, not just the ones you wanted. Root cause: Codocly meters by docs generated per month (40 on Pro at ₹799 per user, 100 on Team at ₹1,499 per month), and continuous Git push sync means a busy client repository can burn quota on routine commits rather than on deliverables the agency actually scoped.
By InnovaAI ResearchPublished
How do you recognize it?
- •Agency account hits the Pro Plan's 40 docs per month ceiling mid-sprint because every Git push to a client repo triggers a fresh generation, not just the ones you wanted
- •Client-facing documentation site shows stale OpenAPI references while the README looks current, since sync health per output type is only visible in the central dashboard and nobody checks it
- •Team members share one login because the lower tiers lack role-based access, so commit attribution and change history on client docs become untraceable
- •Agency bills a flat retainer but the client keeps adding repositories, and each new repo import silently multiplies monthly doc consumption
- •Published docs sit on a Codocly-hosted subdomain instead of the client's branded domain because custom domain mapping with automated SSL was never configured at onboarding
Why does it happen?
- •Codocly meters by docs generated per month (40 on Pro at ₹799 per user, 100 on Team at ₹1,499 per month), and continuous Git push sync means a busy client repository can burn quota on routine commits rather than on deliverables the agency actually scoped
- •The Free Plan caps at 3 README generations per month with README.md export only, so agencies that pilot on Free and then migrate mid-project discover the other three output formats (OpenAPI 3.1, C4 guides, runbooks) were never validated against the client's codebase
- •Role-based access arrives only at the Team tier, so agencies running Pro across several delivery staff cannot separate who regenerated or published client documentation
- •Pricing is published in INR, and agencies billing clients in other currencies carry FX exposure on a per-user monthly line item that grows with headcount rather than with client value delivered
How do you fix it?
- •Open the central dashboard and audit sync health and generation stats per repository, then disable push-triggered regeneration on low-churn repos so quota is spent on scheduled releases instead of every commit
- •Move any multi-staff client engagement to the Team Plan (₹1,499/month, 100 docs) to get role-based access before the next delivery cycle starts
- •Map each client's published docs to their custom branded domain with automated SSL during onboarding, not after the first invoice, so the deliverable is visibly the client's asset
- •Re-run all four output types (README, OpenAPI 3.1 reference, C4 architecture guide, runbook) on a representative client repo before quoting a retainer, since Free Plan trials only exercise README export
More on Codocly
- StrategyWhy Codocly Turns Documentation Debt Into Agency Retainer Revenue
- ConceptCodocly Doc Volume Ladder
- Evaluation RuleCodocly Rule: Adopt Only When Git-Push Doc Sync Replaces a Recurring Client Deliverable
- Decision FrameworkCodocly: Buy vs Skip (Documentation Retainers for Dev Agency Clients)
- Implementation BlueprintCodocly Technical Docs Retainer Build (6-8 days)
- Operating ProcedureCodocly Client Documentation Retainer Setup (Onboarding)
More for AI Code Tools
- Failure PatternsThe Leadcode Credential Drift Trap: Why Agencies Fail With Leadcode in Multi-Client Delivery
- Failure PatternsWhy Agencies Fail With GenerativeIDE in Security-Sensitive Client Work
- Failure PatternsThe Ephemerals Billing Trap: Why Agencies Fail With Ephemerals in Client Delivery
- Failure PatternsThe yume Seat Resale Trap: Why Agencies Fail With yume in Client Delivery