Most of what we inherit when we’re brought in to take over an AI integration is not a system, it’s a gap. The agency built something real, shipped it, invoiced for it, and left. What they didn’t leave was any record of what the thing actually does, what credentials it holds, or how to stop it cleanly. That gap is the project.
Why AI Handoff Documentation Fails in Practice
Most AI projects close with a “here’s your login” email and a Loom walkthrough. That is not documentation. It is a liability.
The gap is structural. The agency has already invoiced for delivery. Writing thorough handoff documentation costs time they’re no longer billing for. The incentive to cut corners is real, and the client rarely knows what complete documentation even looks like to push back.
Vendors Who Under-Document Aren’t Always Lazy, Sometimes It’s Strategic
A vendor who holds the only working knowledge of your AI integration has use at renewal time. If you can’t hand the project to a new developer without calling your current agency, you don’t own your integration, you rent access to it.
This is the most common form of lock-in in AI projects, and it doesn’t require any explicit deception. The vendor simply delivers what they feel is “enough,” which happens to leave several critical artifacts missing. The result: switching costs that weren’t in the original contract but materially raise the cost of leaving.
What “We’ll Handle It” Actually Costs You at Renewal Time
“We’ll handle ongoing maintenance” sounds like a service. Sometimes it is. Often it is a substitute for transferring knowledge you were entitled to receive at project close.
When the relationship ends, through your choice, theirs, or a key contact leaving, you discover the integration is a black box. Reproducing it from scratch costs 60–80% of the original build. That is the real price of thin documentation.
The Core Document Set You Need Before Any AI Project Closes
There are five artifacts that every AI integration handoff must include. If your vendor’s closing deliverables don’t cover all five, the project is not done, regardless of what the contract says.
Architecture and Data Flow Diagram
This document shows every system the integration touches: your CRM, your database, any third-party APIs, and the AI model endpoints. It maps what data moves where, in what format, and under what conditions.
Without it, a new developer inherits an archaeology project. They will spend the first two weeks reverse-engineering connections that should have been diagrammed on day three. Require a current-state diagram, not a wireframe from the discovery phase, the two are often very different by go-live.
Secrets and Credentials Inventory
Every API key, OAuth token, webhook secret, and service account credential used by the integration needs to be inventoried, located in a password manager or secrets vault you control, and rotated before handoff.
This is the most commonly omitted item. Credentials left in a vendor’s 1Password or hardcoded in environment variables they manage are credentials you don’t control. If the vendor relationship ends badly, your production system is exposed. Require written confirmation of where each secret lives and evidence that you hold the access.
Model Card and Configuration Record
If your integration uses a hosted AI model, GPT-4o, Claude, Gemini, a fine-tuned variant, you need a model card documenting which model version is in production, what system prompt governs its behaviour, what temperature and parameter settings are applied, and what the fallback behaviour is when the model returns an error or unexpected output.
Model versions deprecate. Providers change default behaviour between versions. Without this record, the next developer inheriting the project has no baseline to compare against when behaviour drifts.
Acceptance Criteria and Test Results Log
What did “done” look like for this project? What tests were run, on what inputs, and what outputs were considered passing? This log is the closest thing to a warranty for the system’s behaviour at delivery.
Projects with quantified success metrics defined upfront achieve a 54% success rate versus 12% for those without. The acceptance criteria record is how you prove those metrics were met, and how a future developer knows what to preserve when making changes.
Operational Runbook (Including the Off Switch)
A runbook covers: how to restart the integration if it fails, how to monitor it for errors, what the alert thresholds are, and, critically, how to disable it safely without breaking dependent systems.
The off switch is not optional. At some point you will need to pause or retire this integration. Without a documented shutdown procedure, “turning it off” becomes a project in itself, often with unintended side effects on connected systems.
Handoff to Client vs. Handoff to a New Developer, They’re Different
These are two distinct documents with different audiences. Conflating them produces documentation that serves neither.
What a Non-Technical Owner Needs
The client-facing handoff document explains what the integration does in plain language, what it costs to run each month, who to contact when something goes wrong, and what routine maintenance it requires. It does not need to explain how the API authentication works. It does need to explain what a credential rotation looks like and who is responsible for it.
AI integrations built on custom WordPress development or WooCommerce infrastructure require the same handoff clarity, the AI layer doesn’t make the underlying platform less important to document.
What a New Development Team Needs on Day One
The technical handoff package is the five-artifact set above, plus: local development setup instructions, environment variable documentation, deployment process, and a changelog covering any material changes made post-launch.
A new developer should be able to clone the repository, configure their environment, and run the integration locally within four hours. If that isn’t possible with the documentation provided, the handoff is incomplete.
Compliance Obligations That Affect Your Documentation Requirements
This is no longer a best-practice conversation. For many businesses, it is a legal one.
EU AI Act, August 2026 Deadlines and What They Mean for Documentation Retention
The EU AI Act’s Annex III high-risk provisions become enforceable on August 2, 2026. For systems that qualify as high-risk, which includes AI used in employment, credit, critical infrastructure, and certain customer-facing decisions, the Act requires technical documentation retained for at least 10 years and made available to the AI Office on request.
If your business operates in the EU or serves EU customers, “we deleted the docs when the project closed” is not a compliant posture. Retention obligations need to be written into your vendor contract before the project starts, not discovered at a compliance audit.
NIST AI RMF Alignment, What Auditors Expect to See
The NIST AI Risk Management Framework asks organisations to document AI system provenance, intended use, limitations, and governance controls. Auditors following NIST RMF expect to see version-controlled configuration records, test logs, and evidence of ongoing monitoring, not a PDF produced after the fact.
If you’re building AI into operations that will face regulatory scrutiny, the documentation standard in this article is the floor, not the ceiling.
How to Verify Your Documentation Is Actually Complete
Receiving a documentation package is not the same as receiving complete documentation. Two checks will surface most gaps.
The New Developer Test
Put the documentation package in front of a developer who had no involvement in the project. Ask them to answer these questions from the documents alone: What does this integration do? What would break if the primary API key was revoked? How do you restart it if it fails at 2am? How do you disable it without breaking the CRM?
If they can’t answer all four from the documents without calling anyone, the documentation is incomplete. This test takes two hours and costs far less than a failed transition.
Red Flags in What Your Vendor Delivered
Watch for these specific patterns: documentation written in the same week as the final invoice (rushed post-delivery rather than maintained throughout); diagrams that show the planned architecture rather than what was actually built; credentials listed as “stored in agency systems” with no transfer instruction; a runbook that describes monitoring setup without showing the current alert configuration.
Designodin’s approach to project ownership starts from the premise that documentation is a deliverable, not a courtesy. See how we scope and build this at designodin.com/ai.
Frequently Asked Questions
What documents should I receive when an AI integration project is finished?
At minimum: an architecture and data flow diagram, a secrets and credentials inventory with confirmed transfer to your control, a model card and configuration record, an acceptance criteria and test results log, and an operational runbook including shutdown procedure. If your vendor’s closing package doesn’t include all five, the project isn’t closed, the contract terms for delivery haven’t been met.
How long should AI integration documentation be retained?
For EU businesses or those serving EU customers, the AI Act mandates at least 10 years for high-risk AI systems. For other contexts, a practical minimum is the operational life of the integration plus three years. The operational runbook and model configuration record are particularly important to retain, as they establish what the system’s behaviour was at any given point in time.
What is a model card and why does my business need one?
A model card documents which AI model version is in use, its configuration parameters (system prompt, temperature, output constraints), and its known limitations and failure modes. You need one because AI model providers deprecate versions and change default behaviour. Without a model card, you have no baseline to compare against when the integration starts behaving differently, and no record of what the system was supposed to do when it was built.
What should be in an AI integration runbook?
A runbook should cover: how to verify the integration is running correctly, what error states look like and how to resolve common ones, how to restart the system if it fails, what the monitoring setup is and where alerts go, and how to disable the integration safely. A runbook without the shutdown procedure is incomplete, “turning it off” is a real operational need and needs to be documented before you need it urgently.
How do I know if my vendor’s documentation is incomplete on purpose?
Deliberate under-documentation has specific patterns: credentials stored in vendor systems without transfer instructions, diagrams that don’t match what was actually built, no documented deployment or restart process, and no changelog. The business incentive is clear, a client who can’t hand off the project without help has to keep paying for support. If your vendor resists producing complete documentation at project close, that resistance is the signal. Escalate it before final payment, not after.
If you want to talk through what documentation requirements should look like for your build, before any commitment, start a conversation.