AI Pet Care Handbook: How PupPal Builds Instructions Any Sitter Can Follow — PupPal

2026-08-25

AI Pet Care Handbook: How PupPal Builds Instructions Any Sitter Can Follow — PupPal

Every owner who has ever left a dog behind has faced the same moment: your mother, your neighbor, or your college roommate is standing in your kitchen, looking at your dog, and waiting for instructions. You have thirty seconds of their attention and seven years of knowledge about this animal, and you are about to try to compress all of it into a speech. The kibble brand, the portion size, the medicine that has to go with dinner, the fact that the dog bolts for the door if the vacuum cleaner turns on, the vet number that should be dialed before your number. You will forget something, they will forget something, and the dog will pay for it.

PupPal solves that exact moment with an AI pet care handbook: a structured, generated care document that assembles itself from the data your daily photo check-ins have already collected, and that any sitter can read after typing a nine-digit care code and a four-digit PIN. No account, no app install, no phone call where you try to remember the dosage. The handbook is not a suggestion box or a chatbot answer — it is a real, versioned artifact with a defined structure, hard safety rules, and a lifecycle that runs from the moment you tap "start care" to the moment the session expires.

This post is a technical tour of how that handbook is actually built, grounded in the real Puppal source code: the webhook that triggers it, the pet profile it reads from memory, the iron rule that protects the dangerous fields, the prompt that shapes the tone, and the snapshot mechanism that keeps the handbook alive even when the AI service is unreachable. If you have already read the story of Nina and her six-page care document, this is the machinery underneath that story.

The Webhook That Starts Every Handbook

Nothing about a care handbook happens by accident, and nothing happens while you are asleep. A handbook is generated the moment you start a care session, and the trigger is a webhook called puppal-care-create.

The flow begins in the Flutter app, but it is decided in the Cloudflare Worker relay. When you tap "start care" for your dog, the app calls the relay's care-creation endpoint. The relay does four things in a deliberate order. First, it validates the request: it needs a dog_id at minimum, plus optional start_time and end_time that define the session window. Second, it generates the sharing credentials — a nine-digit care code modeled on the RustDesk connection code (grouped 3-3-3 so it can be read aloud over the phone) and a four-digit PIN, which is hashed with SHA-256 plus a server secret before it is ever stored. Third, it persists a care session record under the KV key care:{careCode} with a thirty-day time-to-live, and mirrors a durable copy into D1 so the metadata outlives the KV expiry. Fourth, it fires the webhook.

The webhook payload is deliberately small:

{
  "dog_id": "doudou",
  "care_session_id": "care_abc123",
  "start_time": "2026-06-18T10:00:00Z",
  "end_time": "2026-06-20T18:00:00Z",
  "care_code": "908 174 553"
}

No photos, no full profile dump, no free text. The webhook is a notification with coordinates — the Hermes Agent that receives it knows exactly where to find everything else. The endpoint is POST /webhooks/puppal-care-create on the owner's self-hosted Hermes, authenticated with the shared webhook secret, and the skill that handles it is care-handbook, one of the five skills in the Puppal profile distribution.

Why a webhook instead of generating the handbook inline in the app? Because the handbook is a document about the dog, and the deepest knowledge about the dog lives in Hermes memory, which the app never holds. The webhook is the boundary: the relay knows who the dog is, Hermes knows what the dog is like, and the webhook is the single, authenticated moment where those two bodies of knowledge are allowed to meet. The care code and PIN, meanwhile, never leave the relay — the care codes and PIN post covers that security model in full. The handbook is the first thing the code opens the door to.

The Profile: The Memory the Handbook Is Built From

When Hermes receives puppal-care-create, the care-handbook skill does not ask the owner anything. It reads. The skill issues two memory reads, dog:{dog_id}:profile and dog:{dog_id}:state, and what comes back is the complete pet record that the owner built during onboarding — the same record that every photo check-in has been quietly enriching.

The profile structure is worth looking at in detail, because the handbook's quality is entirely a function of this structure. The profile holds:

  • Identity: name, breed, age in years, weight in kilograms, gender, neutered status, microchip ID.
  • Feeding: brand, portion per meal (often with a weight, like "2 cups, about 280 g"), meal times, and free-text notes — including warnings like "wait 30 minutes after eating before walking, prone to bloat."
  • Medications: each with name, exact dosage, schedule, and administration tips such as "massage the ear base gently for 30 seconds after the drops."
  • Allergies: a plain list — chicken, beef, whatever the vet flagged.
  • Behavior: friendliness with strangers, leash training quality ("good, but pulls when he sees a squirrel"), known commands, fears (vacuum cleaners, thunder), and quirks ("carries socks to the living room, never chews them").
  • Vet: name, phone, address, and opening hours.
  • Emergency contact: the owner's name and phone, plus a backup contact.

Notice what is here and what is not. The profile contains the factual spine of dog care: what to feed, how much, when, what medicine, how much, when, and who to call. It also contains the cultural spine — the quirks and fears that no instruction sheet from a boarding facility would ever capture. The handbook skill treats both spines as raw material, but it treats them very differently, and that difference is the whole design.

The dog:{dog_id}:state read matters almost as much as the profile. State holds the living picture of the dog — the posture, expression, and environment tags from the most recent photo analysis, the anomaly flags, the check-in history. The handbook does not embed this state, because a handbook should describe the dog's steady world, not yesterday's snapshot. But the skill reads it so the generated guidance can acknowledge the dog's current condition where it matters — for example, noting in the care instructions that the dog's ear was flagged as itchy in the last two check-ins, so the sitter knows to pay attention to it. The handbook is generated from memory, not from a form the owner fills out under pressure at the airport, and that is exactly the point.

The Iron Rule: Fields the AI Cannot Touch

Here is the most important design decision in the entire skill, and it is the one that separates a real care document from a confident AI essay: the AI is not allowed to change the dangerous numbers.

The skill declares an iron rule. Feeding portions and schedule, medication names, dosages, and schedules, vet phone and address, and emergency contacts must be copied verbatim from the owner's profile. The language model organizes, adds behavior suggestions, and writes warm encouragement — and nothing else. The prompt given to the model states this as a numbered rule: the values in the feeding, medication, and contact sections must be copied from the profile exactly, with no alteration and no "optimization."

Why does this rule exist? Because a generated handbook that rounds 2.5 mL of ear drops down to "a few drops" is a handbook that has quietly killed the entire point of the document. Dosages are not prose; they are data with legal and medical weight. The LLM's job is to make the document readable, not to improve on the veterinarian. The skill enforces this with a post-generation self-check: after the text is assembled, every field is compared against the original profile — feeding amount and times, medication details, vet contact — and the handbook is only considered valid if the values match exactly and the full text contains no fabricated numbers.

The safety boundaries go further, and they are all encoded in the skill:

  • Never fabricate missing data. If the profile has no medication entry, the handbook says "None." The model is explicitly forbidden from inventing a supplement, a dosage, or a "typical" schedule because the real one is missing.
  • Guard the emergency contact. The sitter never sees the emergency contact's private phone number. The handbook says only: "In case of emergency, contact the vet immediately." The owner's backup contact is a safety net for the owner, not a phone number for a stranger.
  • Cap the length. The complete handbook is limited to about 2000 characters, a deliberate budget sized for a sitter who is standing in a kitchen with a dog, not reading a blog. Readability is a safety feature.
  • Never invent dates. If the owner started an open-ended care session with no end time, the handbook has no validity period. No guessed end date, no "through Sunday," ever.

The result is a document with a strange and wonderful property: the most important sentences in it were not written by the AI at all. They were written by the owner, in the calm of onboarding, and the AI is merely the frame that holds them. The generated parts — behavior tips, check-in guidance, the closing encouragement — are the parts where style and warmth are safe.

How the Handbook Is Written: Prompt to Markdown

With the profile read and the rules loaded, the skill hands the assembly to the model. The prompt positions the model as a professional pet care handbook writer. The required output is a concise, structured list — not an essay — in a warm but professional tone, and the rules are restated in the prompt itself so the model's constraints are part of its context, not just a developer's comment.

The handbook structure is fixed, and it is the same eight sections every time:

  1. Basic pet info — name, breed, age; this is the part that makes the document feel like it is about this dog.
  2. Feeding — brand, portion per meal, schedule, and the owner's notes. Verbatim from the profile.
  3. Medication — name, dosage, schedule, administration tips. Verbatim from the profile.
  4. Behavior habits and care tips — friendliness, leash behavior, known commands, fears, quirks, plus the AI's practical suggestions ("keep her on the short leash near park squirrels").
  5. Vet contact — name, phone, address, hours. Verbatim from the profile.
  6. Emergency instructions — the guarded section: contact the vet immediately, never the private number.
  7. Check-in guidance — how to take a check-in photo with the app, and that an optional note can be attached, so the sitter knows the photo is the proof of care.
  8. Closing encouragement — one warm line, because the person reading this is doing the owner a favor.

The assembly is then a merge, not a monologue. The model's output supplies the behavior section, the check-in guidance, and the closing message. The immutable fields are merged into the final JSON structure from the profile directly, untouched by model output. The final handbook object carries pet_name, a pet_photo_url pointing at the dog's avatar in R2, the section map, the care_session_id, and valid_from / valid_until timestamps derived from the session window the owner chose. It is returned as Markdown, which is why the sitter's view is cleanly formatted on any phone, in any browser, with no rich-text rendering logic anywhere in the chain.

On the agent side, the conversation is streamed. In the Durable Object that hosts the AI session, the care_handbook skill message carries dog_id and pet_profile, acknowledges the request, streams the generated text in chunks with progress updates, and finishes with a done envelope containing the assembled handbook. The model used is resolved per skill through the relay's model configuration, so the handbook can be pointed at a different model than photo analysis if the operator wants a cheaper or more careful one. If the model call fails, the client gets a retryable error — and, as we will see, the handbook does not actually depend on the model call succeeding.

After the handbook is returned, the skill closes the loop by writing to memory: dog:{dog_id}:care_sessions gains an entry for the new care_session_id, with status active, a handbook_generated_at timestamp, the session window, and an empty caregiver_photos array that the sitter's check-ins will fill. The skill is done, but the document it produced now has a life of its own.

The Snapshot: What Happens When Hermes Is Offline

A care handbook that only exists inside an AI service is a care handbook that fails exactly when it is needed most. The Puppal architecture treats that failure mode as a first-class problem, and the solution is a snapshot.

Watch the creation flow carefully, because the order matters. The relay stores the care session in KV before it calls Hermes. When the webhook response comes back, the relay does something subtle: it accepts a handbook from either of two sources, with the client winning. If the app sent a handbook string in the creation request — the result of the handbook preview the owner saw and confirmed in the creation wizard — that client-confirmed text becomes the session's handbook field in KV. If no client handbook was sent, the relay falls back to the handbook or markdown field from the Hermes webhook result. If both are missing, the field stays null. This is the "what you see is what you get" rule: the handbook the owner reviewed on screen is the handbook the sitter will read, because the owner is the final editor of their own dog's instructions.

The session record in KV therefore carries a durable copy of the handbook, sitting beside the PIN hash and the session window, all under the care:{careCode} key with the thirty-day TTL. That copy is the snapshot. It survives Hermes reboots, model outages, network partitions, and an owner who turned off their laptop mid-trip.

Now consider the verify flow, when the sitter types the nine-digit code and the PIN. The relay checks the rate limits, hashes the PIN with a timing-safe comparison, locks the code after ten wrong attempts for a full hour, and on success issues a short-lived upload token — valid for the lesser of the session's remaining time and seven days. It also calls the Hermes webhook puppal-care-get to try to fetch a fresh handbook. And then the fallback ladder kicks in. If Hermes returned a handbook, that wins. If Hermes returned nothing, the relay serves the KV snapshot. If both are absent, the handbook field is simply omitted, and the sitter's page shows a polite notice instead of a broken layout.

Every Hermes call in the care path is wrapped in tryHermesWebhook, which converts any failure into an empty result. This one decision is what makes the whole flow honest: care never depends on the AI being online. Creating a session, verifying a code, and accepting a handbook all succeed with Hermes down, because the essential artifact — the snapshot — was already written when it could be written, at the moment the owner pressed start.

There is one more lifecycle twist worth naming. The sitter does not merely read the handbook; they acknowledge it. A dedicated endpoint, /puppal-care-handbook-accept, takes the sitter's care_token and marks the session handbook_accepted: true with a timestamp — idempotently, so a double-tap does not corrupt the record. The owner's export view later shows whether the sitter actually opened and accepted the instructions. A care document that was generated but never accepted is, in the product's own mental model, a care document that was never delivered. The acceptance flag is the delivery receipt.

From Code Entry to Check-In: The Sitter Experience

The technical chain only matters if it produces the experience the owner actually wants, so it is worth walking the whole path from the sitter's side of the screen.

The sitter receives the care code and PIN however the owner chooses to send them — a text message, a WeChat message, a note on the fridge. They open the H5 page, a web page that requires no account and no app install. They type 908 174 553 and the PIN. The relay verifies the PIN against the hash, checks the session window, issues the upload token, and serves the handbook — from Hermes if it is reachable, from the KV snapshot if it is not. The sitter sees a document that begins with the dog's name and photo, moves through feeding and medication with the owner's exact numbers, explains the fears and quirks, and tells them exactly how to do a check-in.

From that moment, the sitter's job is the same as the owner's: photo equals check-in. Each photo the sitter takes travels over the care channel — validated against the token, stored in R2, analyzed by the photo pipeline running in foster-like care mode with tighter anomaly thresholds, so anything unusual escalates straight to the owner instead of waiting for the nightly review. The handbook's check-in guidance is what makes this feel natural: the sitter was told, in the document itself, that a photo of the dog's face, food bowl, or water bowl is the proof of care, and that an optional note can be attached. The photos accumulate in the session's caregiver_photos history, which the owner sees as a timeline of the dog's days while away. The sitter never needs to know how any of the machinery works, because the handbook turned the machinery into a list of eight sections and one habit.

The session ends in one of three ways: the owner ends it manually, the sitter's token expires, or the hourly cron notices the end_time has passed and marks the session ended, notifying Hermes with puppal-care-end and the reason expired, then cleaning up the session's R2 photos once the session has been over for seven days. The handbook snapshot lives out the full window — generated at creation, served at verification, acknowledged by the sitter, and finally retired with the session. It is never a document that goes stale mid-trip, because it was born from the profile on the day it was needed, and it was frozen at the exact moment the owner pressed start.

For the full picture of what happens to those sitter photos after they land, the photo check-in deep dive walks the same bytes through vision analysis and anomaly detection, and the foster care monitoring post explains why someone else's care session runs with sharper thresholds than the owner's own routine.

What the AI Pet Care Handbook Means for Your Dog

Step back from the pipeline and the artifact is remarkable for what it is not. It is not a chatbot that answers questions when someone remembers to ask. It is not a note taped to the fridge that expires the moment the dog's routine changes. It is not a document drafted at the airport from memory. It is a generated care document that inherits its facts from a living profile, protects the numbers that matter with an iron rule, survives infrastructure failure through a snapshot, and carries a delivery receipt.

That is the difference between instructions and care. Instructions are what you write when you are leaving. Care is what happens when the right information reaches the right person at the right moment — the AI pet care handbook is PupPal's way of making sure that moment is every moment of the session. The feeding amounts are the owner's amounts. The medication schedule is the vet's schedule. The fears and quirks are the dog's actual personality, captured photo by photo since onboarding. The AI contributed the structure, the safety rules, and the warmth — and the iron rule ensured it never touched the one thing it must not touch: the facts.

The next time you are about to write a six-page document, or deliver a thirty-second speech in a kitchen, remember that PupPal can have the handbook ready before the sitter arrives — generated from the check-in history you already built, exact in the ways that matter, kind in the ways that count. Start a care session, send the nine-digit code, and the document writes itself from the dog outward. One photo a day made it possible; one care code delivers it.