Handover Done Right: Delivering Your Vibe Project to Clients Without the 3 AM Calls

A friend of mine, Chen, took a freelance gig last year: a membership booking mini-program for a chain of offline stores. Two weeks of vibe coding, a zip file sent over WeChat, and the client replied "Got it, thanks." Three months later, at 1 AM, Chen's phone rang — the system was down, and the store's grand-opening event the next morning depended on that mini-program. It took him two hours to remember: the server was under his own account, the domain renewal email had gone to his spam folder, and the SSL certificate had expired the week before.

This is the classic way vibe coders die on client work: the code is done, but the project was never truly handed over. AI compressed coding time from two months to two weeks, but handover is still manual labor from a decade ago — send a zip, say "call me if anything breaks," leave every credential in your own hands. You think you delivered a project; what you actually delivered was a time bomb, and when the countdown ends, it's your sleep that explodes first.

This guide is about the handover itself. Not how to write code — how to hand code over to someone else, cleanly, and then sleep well.

Why handover matters three times more in the vibe era. First, delivery speed changed: a two-month project used to give the client time to learn the system along the way; a two-week delivery leaves them knowing almost nothing, and handover is their only systematic chance to learn — miss it and they'll ask you forever. Second, code volume changed: when AI-generated code breaks, even you need half a day to trace it; handing over undocumented code is handing over a black box. Third, your client radius changed: gigs used to come from local acquaintances you could visit; now they come from communities and platforms across the country, fully remote, and written documents are the only carrier of trust. One conclusion: the faster code gets generated, the heavier handover needs to be.

1. The Three Ways Handovers Die

First, align on one thing: delivery ≠ sending code. There is exactly one completion criterion — the client's system keeps running without you. Check yourself against these three causes of death:

Death 1: Missing documentation. The client has the code but doesn't know how to restart the service, where backups live, or what any third-party password is. The first outage brings them to you, the second too, and by the tenth you're lifetime free tech support. Vibe projects are especially dangerous here: AI generates a month of code in a day, but documentation stays at zero — AI won't proactively write you a "restart manual for non-technical people."

Death 2: Permissions never transferred. The domain is in your name, the server is in your account, the payment webhook still uses your Stripe key. The client nominally owns the project while you hold every lifeline. That's not delivery, that's a hostage exchange — except the hostage is you: the client calls you at midnight not because you're important, but because you're the only one who can renew things.

Death 3: Verbal maintenance promises. "Call me anytime if anything breaks" — that sentence has infinite cost. No boundaries, no expiry, no definition of what counts as "broken." Three months later the client asks you to "just add an Excel export." Do you? If yes, this one's free, what about next time? If no — "didn't you say to call you with problems?" Every dispute traces back to boundaries that were never written down at handover.

Remember: the quality of your handover decides how much of your time this project will eat over the next year. The six sections below turn that sentence into executable actions.

Do the math and handover pays for itself. Say your freelance rate is $50/hour. A sloppy handover costs you on average 20 hours of "free aftercare" over the next six months (restarting services, finding passwords, explaining why "a small extra feature" isn't free) — $1,000 in hidden cost. A serious handover takes about 8 hours of prep plus the meeting: $400. That's $600 saved, not counting the mental cost of midnight wake-ups — or the opportunity cost of the 20 hours you could have spent on the next gig. Handover isn't a cost; it's the highest-ROI hours you'll spend — 8 hours to buy out six months of entanglement.

One vibe-era trap: AI-generated code is three times harder to hand over than hand-written code. With hand-written code you at least remember why each module looks the way it does; with 30,000 lines AI spat out in a day, you haven't read all of it yourself. When the client asks "what does this cron job do" and you can't answer, trust drops on the spot. So vibe projects need slightly thicker handover docs than traditional ones — not because you're lazy, but because the code's "knowledge half-life" is shorter. Start a HANDOVER.md in week one and jot things down as they occur; it's ten times easier than a last-week documentation sprint.

2. The Handover Doc Pack: Written for "the Next Person"

The readers of your handover docs aren't you. They're three people: the client (non-technical), the client's future developer, and you-three-months-later with amnesia. For these readers, the pack needs exactly four things — one more is clutter:

1. A non-technical README for the client. No architecture, just three moves: how to restart when it's down, where data lives and how it's backed up, what to do about common issues. Write it in the client's language, e.g. "If the mini-program won't open, first check whether the status page shows green." Include every third-party login and its monthly cost — the client has a right to know what they're paying for each month.

2. Architecture on one page. One diagram plus half a page of text: where the frontend lives, where the backend lives, where the database lives, who the key third parties are (payments/SMS/maps). Vibe project architectures are rarely complex; one page is enough. The goal: "the next person" (whoever the client hires later) understands the whole thing in 30 minutes instead of reading 30,000 lines of AI-generated code.

How to write the one-pager (copy the format): four boxes at the top — client side (mini-program/app/web, be specific), app services (which cloud, what spec), database (type, backup policy), third parties (one line each for payments/SMS/push/maps: provider + purpose + monthly fee). Three lines at the bottom: repo URL, production URL, and "if you remember one thing: check the status page first." Skip the rationale for your stack choices — the client doesn't care why you picked Supabase over Postgres; they care who to call when it's down.

3. The accounts & assets register. A table with six columns: asset name, owning account, login method, transfer status, monthly cost, notes. Covers domains, servers/cloud accounts, repos, databases, third-party APIs (payments/SMS/push/maps), monitoring alerts, SSL certificates. Every row gets a "transferred/pending" status — this table later becomes an attachment to the signed handover confirmation. The "login method" column matters: note whether it's "email+password," "WeChat QR scan," or "hardware key" — QR and hardware-key logins are the most commonly forgotten transfers because they don't live in a password manager. The "monthly cost" column shows the client the true cost of ownership for the first time, preempting the "why am I charged so much every month" complaint six months later.

4. A demo recording. Fifteen minutes walking through the core flows: how an admin logs in, what daily operations look like, where to look when something breaks. Video beats docs against forgetting — the client checks the video first and only calls you when it doesn't answer. This is the first firewall for your sleep.

Before recording, make a shot list so you don't discover gaps afterward: ① login (admin and regular user, once each); ② the core business flow end to end; ③ viewing and exporting data in the admin panel; ④ the "when it breaks" trilogy on camera (check status page, restart, find backups); ⑤ a 30-second outro: your contact info, response times, and saying "30-day handover support" out loud. Phone screen recording is fine, no editing needed, just add a title — the client needs "something to follow," not a promo video.

Before handover, give AI-generated code a 30-minute health check: ① grep the whole repo for sk-, AKIA, password, secret to confirm no hardcoded keys (rotate any you find — see section 3); ② list every TODO/FIXME the AI left behind; fix what you can, and put the rest in the known-issues list instead of pretending they don't exist; ③ hunt "magic numbers" (e.g. where did the 3 in if (retry > 3) come from) and comment each one — AI writes code without explaining, so at handover you must explain, or the next person (or amnesiac future-you) can only guess.

Read the pack yourself when done. The bar: with amnesia, could you resurrect the system from these four items alone? If not, fill the gaps. Here's a fill-in-the-blank skeleton for the non-technical README:

# XX System User Manual (the version for the boss)

## When the system is down (do in order)
1. Open the status page https://status.xxx.com — is it green?
2. If red, call XXX (phone). Don't click around randomly.
3. If the status page itself won't load, restart the server:
   log in to https://console.xxx.com → click "Restart"

## Three things to check every month
- 1st: confirm SMS balance > 500 (check on the XX platform)
- 15th: download one data backup (click "Export" in admin, save to company drive)
- Domain/server renewal date: __/__/__ (calendar reminder set)

## FAQ
Q: Customer didn't get the SMS? A: Check SMS balance first, then the phone number.
Q: Can't log in to admin? A: Click "Forgot password," code goes to the boss's phone.
Q: Want a new feature? A: Contact the developer via the change process.
   Don't hire a random freelancer to patch the code.

That last line isn't a joke. Plenty of post-handover messes start with the client hiring a cheap freelancer for "a small change," breaking things, and coming back to blame you. Writing it in the manual is insurance for future-you.

3. Transferring Permissions & Assets: Give the Lifelines Back

This is the part most easily "done later," and the most painful when skipped. The principle: everything the client owns must be transferred on handover day — no "let's leave it with me for now" tails.

Code repo: transfer, don't fork. GitHub/GitLab both have Transfer Ownership — move the whole repo to the client's organization. A fork leaves a "you're upstream" hazard; transfer is the real handover. Tag one last release first (e.g. v1.0-handover), then keep only read-only collaborator access for yourself (for the support period) and leave when it ends.

The exact GitHub transfer flow (3 minutes, order matters): Settings → General → Danger Zone → Transfer ownership → type the target org name → the client confirms via email. Two gotchas: first, clear or rotate Actions secrets before transferring — don't leave keys to your other projects in the repo's secrets; second, confirm the client's org has enough seats — transferring a private repo to a free org that exceeds collaborator limits locks it on the spot. One question asked upfront saves an hour of debugging.

Domain transfer. Do a Change of Ownership at the registrar — not just repointing DNS. Most disputes get stuck here: DNS points over, but the domain is still in your name, so renewals, real-name verification, and transfer codes all still need you. After transfer, have the client confirm the WHOIS registrant has changed.

The most common domain pitfall is "changed DNS but never transferred ownership." The full chain: initiate ownership transfer at the registrar → client confirms the transfer email → client completes real-name verification → you verify the WHOIS registrant changed → turn on auto-renewal with the client's payment method. The whole flow usually takes 3–5 days including registrar review, so start the domain transfer at T-7, not on meeting day. Domains registered or transferred within the last 60 days are transfer-locked — check the registration date early.

Cloud & payment account transfer. Move servers/databases to the client's own cloud account where possible; where migration isn't feasible, at minimum give the client an IAM admin sub-account and CC the client's finance email on billing alerts. Payment merchant accounts (Stripe/WeChat Pay/Alipay) must be under the client's business entity — money must never flow through you, not one cent. That's a red line.

When cloud migration truly can't happen, the compromise: create an IAM admin sub-account for the client, move the root account's MFA to the client's hardware key or phone, change the billing alert email to the client's finance address. Then add one line to the handover confirmation: "Servers temporarily managed by Party B; migration to be completed by __/__/__, costs borne by Party A during the interim." Temporary management needs a deadline — "temporary" without a deadline is permanent.

Rotate every API key. Every key used during development (AI models, SMS, push, maps, monitoring) gets rotated at handover: old keys revoked, new keys handed to the client. Why: your local .env, chat logs, and AI conversation history all contain these keys — not rotating is leaving the back door open to the world. For rotation method see the secrets-management guide; the point here is timing — handover day is rotation day.

Hand over two-factor auth. Unbind every account tied to your personal phone/authenticator and rebind to the client's phone, one by one. It's tedious; skip it and you'll be woken at 3 AM to read out verification codes three months from now.

4. Acceptance: Turning "Done" into "the Client Agrees It's Done"

"Looks good" in a chat message is not acceptance. This is the most counterintuitive rule of handover: the client says "nice" in WeChat, then two weeks later says "this isn't what I imagined," and you have no recourse — because there was never a written standard. So acceptance criteria should be written when the contract is signed (or work begins); at handover you're just ticking boxes against them.

What do acceptance criteria look like? No legalese needed — three columns suffice: feature, how to verify, pass standard. Example:

• Member booking — verify by: complete one booking end-to-end with a test account — pass: SMS confirmation received, order visible in merchant admin
• Report export — verify by: export the last 30 days of data — pass: Excel opens, numbers match the admin panel
• Concurrency — verify by: 50 simultaneous bookings — pass: no errors, response under 3 seconds

Every line must be an executable action + a checkable result. Never write unfalsifiable phrases like "the system runs stably."

The UAT (user acceptance testing) flow: three days before handover, hand the test environment (or production) to the client and have them personally walk the core flows. You watch; hands off — every place the client gets stuck is a place the docs need patching. Split UAT findings into two buckets: inside acceptance criteria → fix same day; outside criteria → log as "new feature" (see section 6), never promise on the spot.

Acceptance form template (print two copies, both parties sign, each keeps one):

Project Acceptance Form
Project: ________    Date: ________
Result: □ Pass  □ Conditional pass (open issues attached)  □ Fail
Open issues (id / description / agreed fix date):
1.
Accepted by (client) signature: ________
Delivered by signature: ________

"Conditional pass" is the escape hatch for small projects: minor issues that don't block the main flow go into the open-issues list with fix dates, and signatures unblock the final payment. Without this tier, small nits stall the entire handover.

Give the client a "test script" on UAT day (don't let them freestyle — freestyle finds nothing):

UAT script (client operates personally; developer watches, doesn't touch)
□ Scenario 1: Register as a new member → book tomorrow 3 PM → receive SMS confirmation
□ Scenario 2: Merchant admin → find the order just created → click "Complete service"
□ Scenario 3: Admin → export this month's report → open in Excel, verify numbers
□ Scenario 4: Phone offline → reopen the mini-program → is the prompt friendly?
□ Scenario 5: Place 3 orders in a row → is stock/quota deducted correctly?
Client signs after each completed item. Issues are logged on the spot; no code changes during UAT.

"Developer watches, doesn't touch" is the soul of UAT. The moment you help, you're testing "works with your help," not "the client can do it alone." If the client is stuck for 5 minutes, log it — that's a docs gap, not a cue to grab the keyboard. End UAT with two artifacts on the spot: passed items ticked and signed, failed items in the open-issues list with fix dates. Never "schedule another time" — lock the dates now.

One rule for the open-issues list: more than 5 items, or any P0/P1, means no "pass" — sign "conditional pass" and freeze part of the final payment, e.g. hold 10% until the list hits zero. This isn't punishing the client; it's protecting you: an unfrozen open-issues list has a fix date of "whenever." Conversely, once the list is cleared, proactively send the client a photo of the signed form and remind them of the payment date. Proactive, punctual, documented — those three cut payment disputes in half.

5. Money: Final Payment and Maintenance Pricing

Money is only three things: when the final payment lands, how much retention to hold, and how to charge for future maintenance. All agreed before handover; the meeting is for signing, not negotiating.

Final payment milestones. For small projects (under ~$7k) use 30-30-40: 30% at kickoff, 30% at the mid-point demo, 40% on signed acceptance. Not 50-50 — motivation decays after the first 50% lands; that's human nature, and a 40% tail is what gets you to take handover seriously. Bigger projects can use 30-20-30-20 with an extra "UAT passed" node. Final payment due within 3 business days of the signed acceptance form — in the contract, reminded once at the meeting.

Retention. Some clients want to hold 10% as retention for 3–6 months. Acceptable, but cap it: retention covers bugs only, not "new features" (judged by section 6's tree), and it releases automatically when the period ends — no "confirm there are no issues" gate, or retention becomes a permanent tail.

Three maintenance pricing models (pick one, write it into the handover confirmation):

• Per-incident: $70–300 per ticket (scaled to project size), quote before lifting a finger. Best for stable systems with a reasonably capable client. Cleanest boundaries; downside is the client hesitates before reporting, so small issues accumulate into big ones.
• Monthly retainer: a fixed monthly fee (usually 5%–10% of the project total) covering N responses plus minor fixes. Best for fast-changing businesses and non-technical clients. Note the retainer covers "maintenance," not "new features" — those are quoted separately.
• No maintenance: after the 30-day support period, no maintenance offered; the client hires someone else. Best for one-off small projects. If you pick this one, say it out loud at the meeting and recommend 1–2 peers who could take over — the client reads it as professionalism, not abandonment.

No model is better; only "fits this client." One test: the client's technical self-sufficiency. They can restart the service themselves → per-incident. They won't dare click the admin panel → retainer. Project too small to matter → none — but say it explicitly.

The most common pricing trap is the client asking for "three months free maintenance to start." The standard answer: "Bugs are fully free during the 30-day support period — that's included; after day 30 it's per-incident or retainer, your pick." Don't concede to 90 days — the length of the free period sets the client's mental price for 'you're always on call'; charging after 90 free days feels like a betrayal. Thirty days is the industry sweet spot: long enough to cover post-launch break-in bugs, short enough to prevent dependency.

Reference anchors for retainer pricing: a $4k–7k project → $200–400/month; ~$15k → $400–800/month. Write the inclusions in stone: X remote responses per month, bugs fixed free, minor tweaks (text changes, image swaps, parameter tuning) Y times per month. Anything beyond is billed per incident. Writing down the "minor tweaks" quota matters enormously — a 5-minute text change feels unbillable each time, but at 20 times a month it's a week of work.

One last iron rule: every pricing promise needs a written carrier. The retainer fee agreed in chat gets restated at the meeting, written into the handover confirmation, signed by both sides. A verbal quote becomes "I remember you said it was free" three months later; a signed document never gets amnesia.

Worst case: the client signed acceptance but stalls on the final payment. Prevention beats collection, three moves: ① never let the tail drop below 30% — below that you have no leverage; ② for large projects (over ~$15k) use third-party escrow (platform escrow or escrow services) so acceptance triggers release, bypassing the client's "mood"; ③ write late terms into the confirmation ("0.05% per day late fee" looks scary; its real job is getting payment onto the client's schedule). If you do meet a deadbeat, the escalation order is: written demand → pause maintenance responses (finish in-support bugs, freeze all new features) → lawyer's letter. Never threaten to shut the system down — it's the client's system now; shutting it down is unlawful. Your leverage is "no further services."

Flip it: if you're the client hiring someone for a vibe project, read this guide backwards as a "how to vet your freelancer" manual — demand the doc pack, watch them change passwords in front of you, insist on a written acceptance form. Handover is two-way; good freelancers aren't afraid of acceptance, they're afraid of having no standard.

Platform gigs and private gigs need different handover weight. On platforms (Upwork/Fiverr and equivalents) with built-in escrow and dispute arbitration, handover can be lighter: doc pack + permission transfer + acceptance form is enough, with the platform backing the tail payment. Private gigs (friend referrals, community intros) need to be heavier: with no platform safety net, your own written documents carry every boundary. And where work started before any contract was signed — common in relationship-based gigs — it's even more important to produce the acceptance form and handover confirmation at the end. Starting without a contract is survivable; ending without an acceptance form leaves you holding zero cards.

Project size sets the granularity too. A $700 micro-gig: compress the doc pack to one page plus a 5-minute video, do the meeting as a 20-minute call — but never skip "permission transfer + written confirmation"; micro-gigs actually dispute more, because neither side took it seriously. A ~$7k mid-size gig: follow this guide's full playbook. A $30k+ large gig: add two items — ① a code walkthrough (you present, the client's technical advisor listens, one hour); ② a parallel-run period (old system stays up for two weeks, cut over only when confirmed clean). The bigger the job, the "slower" the handover should be. Slow is fast.

6. The Maintenance Boundary: a Decision Tree for Bug vs. Feature

Ninety percent of post-handover disputes are one sentence: "Is this a bug or a new feature?" So don't argue — hand over a decision tree, printed on page one of the handover docs:

The logic in plain words, four rules:

• Reproducible now, behaved differently at acceptance → bug, fixed free. Your fault; own it.
• Behaved the same at acceptance, and it was signed off → new feature, billed. "I didn't notice at the time" doesn't reopen it — the signed acceptance form is the answer. This is why section 4 insists on written acceptance.
• A third party is down (payments/SMS/cloud) → follow the maintenance agreement. You file the ticket with the vendor and switch to the backup plan promptly — that counts as one maintenance response; but the vendor's outage is not your bug. Don't apologize for it, and don't "compensate" for free.
• "While you're at it, add…" → always a new feature. There is no "while you're at it." Every addition goes through a change order: quote first, client confirms, then you build. No exceptions during the support period either — the support period covers bugs, not "while you're at it."

Graded response times (in the maintenance agreement): P0 (system fully down) — respond within 4 hours, workaround within 24; P1 (core feature impaired) — respond within 24 hours; P2 (cosmetic) — respond within 3 business days. Note it's "respond," not "resolve" — telling the client you've seen it beats three silent days of fixing for calming nerves.

The 30-day support period: 30 days after the handover meeting, bugs fixed free, response times per P0/P1/P2. On day 30, send a "support period ended" letter: which bugs were fixed, current system status, and the three maintenance models for the client to pick one. The letter is ritual and boundary at once — from then on, "call me anytime" is officially expired.

Two real disputes to show why the tree must come first. Case one: the client said "the exported Excel is missing the amount column." The developer checked: at acceptance the client had said "skip the amount column for now, later." By the tree, that's "same as acceptance + signed" = new feature. But there was no written acceptance form, both sides argued from memory, and the developer built it free — two days of work plus resentment. Case two: the client said "the mini-program got slow." The developer looked: the client had uploaded 200MB original photos as carousel images. By the tree — "reproducible by following the docs?" The docs said compress images; the client didn't. Not a bug — a usage issue, solved with 10 minutes of remote guidance, no charge. With the tree, both calls end in 5 minutes; without it, each is half a day of emotional labor.

Make the response times a small card that ships with the doc pack:

Incident response commitment (valid during support & retainer periods)
P0 System fully down      → respond within 4h, workaround within 24h
P1 Core feature impaired  → respond within 24h
P2 Cosmetic/UX issue      → respond within 3 business days, scheduled fix
"Respond" = acknowledge receipt with an assessment, not "fixed."
Public holidays add half a day.

That last line is written in blood: without it, you'll get a "system feels slow" message at 7 AM on Lunar New Year's Day. With it, the client at least waits until day two.

7. The Handover Ritual: a 60-Minute Meeting Agenda

Handover needs a defined moment, not a slow fade over chat. Schedule a 60-minute handover meeting (remote is fine) with a fixed agenda:

• 0–15 min: Demo. You operate, the client watches, walking the core flows. Emphasize "when it breaks": where the restart lives, where backups download, what the status page URL is.
• 15–30 min: Document transfer. Walk through the four pack items from section 2; change passwords live on the accounts register (client watches you do it) and confirm they can log into every system.
• 30–45 min: Boundary confirmation. Read through section 6's decision tree and response times aloud, confirm the chosen maintenance model, confirm the tail amount and payment date. Saying the uncomfortable things upfront is the highest form of consideration.
• 45–60 min: Sign. Acceptance form + handover confirmation, both parties sign (e-signature fine), photo archived.

Don't underestimate "signing." The ritual of a signed confirmation is a dispute firewall: someone who signed "30-day support, per-incident billing after" in black and white will be embarrassed to call you at midnight three months later asking for free features. Human nature needs a ladder; the signature is the ladder.

Handover confirmation template (the acceptance form covers "it's done"; this one covers "it's handed over cleanly"):

Handover Confirmation
Project: ________    Date: ________
1. Transferred assets (see attached Accounts & Assets Register,
   __ items, all verified log-in-able)
2. Delivered docs (README / one-page architecture / demo video / decision-tree card)
3. Acceptance: □ Pass □ Conditional pass (__ open issues, see acceptance form)
4. Finance: final payment __ due by __/__/__; retention __ auto-releases __/__/__
5. Maintenance: □ Per-incident (__/ticket) □ Retainer (__/mo, __ responses) □ None
6. Support period: __/__/__ to __/__/__ (30 days), bugs only
Handed over by: ________    Received by: ________

Remote handovers (80% of them now) need three extra moves: first, record the screen share end to end and send the client a copy — "this is how you were taught" is the best anti-dispute evidence; second, move passwords via a shared 1Password/Bitwarden vault, never chat — a password in chat history is still there three months later, a time bomb; third, use e-signatures (DocuSign/HelloSign or local equivalents) — don't let "print-sign-photo-send-back" friction stall the tail payment.

Below is the six-phase timeline overview. Start preparing at T-14; don't compress it into the final week:

Hidden in the timeline is a key design choice: permission transfer (T-7 to T-3) happens before UAT (T-3 to T-1). Never reverse the order — the client must do UAT with their own accounts, not yours. If you click through UAT for them on your accounts, you've verified nothing: permission issues (the client's account lacking access to some admin menu is the most common gotcha) only surface under the client's own identity. Handover is essentially "changing the person"; every verification must happen in the changed state.