House Guide — Owner's handbook
In the dashboard: open Guide Editor → Writing guide for the integrated help system (searchable, always available while you edit).
This file mirrors that content for reading in git or offline. For technical deployment and API details, see house-guide-cms.md.
What you are building
The House Guide is a structured manual for living in your home: rooms, appliances, Scooter, Wi‑Fi, emergency info, and local tips. Sitters open it on a phone, tablet, or laptop signed into the hub under House Guide (or via deep links such as #/house-guide/topic/scooter-bedtime).
You do not edit one long document. Instead, content is organised in layers:
Guide (one home)
└── Areas (categories) e.g. Kitchen, Scooter, Emergency
└── Topics (pages) e.g. Dishwasher, Feeding, Fuse box
└── Blocks paragraphs, steps, photos, tips…
└── Quick actions optional buttons (Alexa, links, info panels)Theory: each topic is one answer to one question (“How do I use the dishwasher?”, “What is Scooter’s bedtime routine?”). Blocks are reusable building blocks with fixed shapes (paragraph, steps, warning, photo). The app knows how to display each block type consistently on a tablet — large type, clear callouts, tappable photos.
This is intentional. Structured blocks keep sitter pages scannable and accessible. They also let search, Scooter companion sections, and Emergency cards pull the right topic without parsing free‑form prose.
Where content lives
| What | Where |
|---|---|
| Your live edits | Cloudflare D1 database (via the Worker API) |
| Photos you upload | Private R2 storage |
| Bundled photos | Shipped with the app from git (legacy originals) |
| Fallback copy | guide-catalog.json in git — used only if cloud is empty or unreachable |
| Secrets (Wi‑Fi password, etc.) | Not in the CMS — separate private config |
Normal workflow: edit in Guide Editor → Save draft → Publish. Sitters see published content on the next load. You never need to commit JSON or redeploy the frontend for text or photo changes.
First time only: open Guide Editor and tap Copy current guide to cloud to import the bundled catalog into D1.
Draft vs publish
Think of this like “save privately” vs “go live”.
| Action | Who sees it |
|---|---|
| Save draft | You, in Guide Editor (draft mode) |
| Publish topic | House sitters and guests in House Guide |
| Publish all changes | Every topic that still has unpublished edits |
The toolbar shows how many unpublished changes exist. Topics with drafts show a Draft label in the topic list.
Important: saving without publishing is safe for experimenting. Sitters always receive the last published version of each topic.
Opening Guide Editor
- Unlock Owner Mode on the tablet (PIN if in guest mode).
- Open Guide Editor from the home screen.
- Pick an area (category), then a topic, or create a new one.
You can also change Guide intro text (collapsed section at the top) — the title and subtitle on the House Guide home screen.
Writing a topic — recommended order
- Title & subtitle — what sitters see in lists and search results. Keep subtitles short (“Evening routine · Upstairs”).
- Summary — one or two sentences; used in cards and search.
- Who can see this topic — tick Family, Sitter, Guest and/or Cleaner. New topics start with everyone but cleaners. Untick everyone for owner-only notes.
- Blocks — the main instructions (see below). To move a block, drag its handle (⠿). While you drag, every block folds to one line (type and heading or first words) so the whole list fits on screen, and the page scrolls when you hold near the top or bottom edge. Blocks open again when you let go.
- Search keywords — extra words sitters might type (“Netflix”, “bo kettle”, “bins”).
- Appliance manual links — names that match published appliance manuals (optional).
- Quick actions — buttons at the bottom of the page (Alexa routines, jump to another topic, info panel).
- Save draft, preview mentally, then Publish topic.
Topic IDs
When creating a topic, choose a short id: letters, numbers, hyphens (e.g. bin-day, scooter-bedtime). IDs are used in URLs and links; they cannot be changed easily after creation, so pick something stable.
Block types — when to use what
Use the Add block dropdown at the bottom of the topic editor.
| Block | Use for | Sitter sees |
|---|---|---|
| Paragraph | Normal explanation. Optional heading. | Heading + body text |
| Numbered steps | Sequences (“Each meal”, “Before you leave”) | Ordered list |
| Tip | Helpful hint (green-style callout) | Highlighted box |
| Warning | Safety, roads, don’t-do-this | Strong callout |
| Note | Neutral aside | Callout |
| Details list | Label + value pairs (breed, model, program number) | Definition list |
| Contacts | Names, numbers; optional tel: / mailto: links | Tappable phone/email where set |
| Photo | One hero image with caption | Large image, tap to enlarge |
| Location | “Where is the stop tap?” | Heading + text |
| Expandable section | Extra detail sitters can open if needed | {details} toggle |
| Place | Pub, walk, vet — name, address, dog-friendly flag | Place card |
Not editable in Guide Editor: Private info blocks (Wi‑Fi, lockbox codes). These remain in secure private configuration; existing blocks are preserved if you save a topic that already had them.
Writing tips for blocks
- One idea per block — split long walls of text into paragraph + steps + tip.
- Steps for procedures — dishwasher, heating, bedtime routine, TV input.
- Warnings for consequences — roads, lead, fuse box, water stop tap.
- Photos for “which button?” — remote, fuse box, machine panel. Upload a clear, well-lit photo; write alt text as if describing it to someone on the phone.
- Short headings — sitters skim on a tablet arm’s length away.
Photos
Inside a topic (Photo block)
- Add a Photo block.
- Prefer Upload photo — file is stored in cloud and attached automatically.
- Or expand Choose existing to pick from the library.
- Fill Alt text (required for accessibility) and optional Caption.
Several photos together (Photo gallery block)
- Add a Photo gallery block and give it an optional heading.
- Under Upload photos, choose one or more files at once. Each is saved to the photo library (id and alt text from the file name, never replacing a photo already there) and added to the gallery.
- Or expand Pick photos from your library and tap photos to add or remove them.
- Use ← and → to change the order, and ✕ to take a photo out of the gallery (it stays in the library).
On the guide page the photos sit side by side on a tablet or computer and one under another on a phone. Tap any photo to see it full size.
Photo library (toolbar)
Photo library lists all images — bundled originals and your uploads.
- Replace — swap the file for an uploaded photo (same id, new image).
- Delete — removes uploaded photos from cloud. Topics still pointing at that id will show “Image unavailable” until you pick another.
Bundled photos from the original import are read-only in the library.
Quick actions
Buttons at the bottom of a topic page in House Guide.
| Type | Purpose | Example |
|---|---|---|
| Alexa routine | Fires a Virtual Button by number | “Bedtime” → button 2 |
| Open another topic | Jumps to a different guide page | “Feeding guide” |
| Info panel | Small overlay with extra label/value rows | Treat rules, phone list |
Each action needs a button label sitters will tap. Save draft, then publish — quick actions only appear in House Guide after publish (not in Guide Editor preview alone).
Validation errors (e.g. missing topic id on a navigate action) are shown before save/publish.
Search
Sitters search from the House Guide home screen. A topic matches if the query appears in:
- Title, subtitle, summary
- Search keywords you add in the editor
- Text inside blocks (published content)
Add keywords for synonyms and brand names sitters might use but you did not put in the title: Netflix, kettle, Alexa, bbq, charger.
Owner-only topics
Untick every box under Who can see this topic for internal reminders you do not want on the sitter tablet. These topics:
- Appear in Guide Editor for you
- Are excluded from the published catalog sitters receive
- Do not appear in sitter search
Use sparingly — most operational content should be visible to sitters and guests so they are not forced to call you.
Who sees what
Each request to the hub reads as one audience: Owner, Family (Settings → People → Family), Sitter (the manual sitter list, or a stay set to House sitter), Guest (a stay's guests, or an owner tablet in Guest mode) or Cleaner (a stay set to Cleaner). The Worker only sends topics, codes and app data that audience may see.
- Topics — ticks in Guide Editor, per topic. Topics saved before audiences were added show to family, sitters and guests (not cleaners).
- Codes and apps — Settings → People → Who sees what. By default cleaners get the lockbox code, address, contacts, House Guide and Emergency, but not Wi‑Fi, pets, weather, bins or controls. Sitters and guests still only get codes during their stay. My Day (the home calendar) is off for everyone until you tick it, for example for Family.
- Pet care — the Pet care row covers the Pet care app, pet details on Home and every guide area about pets (the starter guide's Pets area, or one you named after your pet, or "Pet care") and any topic elsewhere whose title names your pet, whatever the topic ticks say. That holds in the guide, search, Ask Lottie, the offline download and the cleaner page. On a hub set up for Mixed stays (sitters and short lets), guests don't get pet care until you tick Guest; family and sitters do. Mark a sitter's stay House sitter so they keep it.
- Rows you haven't changed follow the hub type. Changing one tick saves only that row; every other row keeps following the hub's use case.
- Stays — the stay form's Who's staying sets the audience for everyone on that stay. Cleaner stays can overlap other stays.
- View as — owners can preview the hub as Family, Sitter, Guest or Cleaner from the header switcher.
Topic management
- Create — form at the bottom of an area’s topic list. New topics start unpublished.
- Reorder — drag topics in the list (or use drag handles) to change order within an area.
- Delete — bottom of topic editor; permanent after confirm.
Appliance manuals
In Appliance manual links, enter names that match published manuals in the Appliance Manuals feature. Matching names become links on the sitter topic page. Names must match exactly what sitters see in the manuals list.
What sitters see vs what you see
| Feature | Owner (Guide Editor) | Sitter (House Guide) |
|---|---|---|
| Draft edits | Yes | No |
| Owner-only topics | Yes | No |
| Published guest topics | Yes | Yes |
| Quick actions | After publish | Yes |
| Private info values | If configured on device | Resolved at runtime |
Use Owner / Guest switcher in the header (home deployment) to preview the guest home and app set without handing over the tablet.
Deep links
You can link directly to a topic:
https://your-dashboard.pages.dev/#/house-guide/topic/scooter-bedtimeEmergency cards and in-guide “open another topic” actions use the same routing. Useful for messages to sitters: “Open this link on the tablet.”
Offline behaviour
Opening House Guide once is not a reliable offline copy. While the sitter is online, inside the sit access window (usually from 14 days before check-in through the day after the sit ends), House Guide shows Download for offline. That saves the published guide and uploaded photos on that device until access closes.
Lockbox and Wi‑Fi codes are not part of that download. They load when the server allows them during the stay, then stay on the device until that secrets window ends.
Published edits reach the tablet only when it is online. The banner then updates the saved copy on its own, or it asks for Update offline copy. Download again is there when the copy is ready, expired, or out of date. Checking offline guide status… is the status check when the guide opens — wait for it to finish before treating the download as failed.
To try this without a sitter signed in, use the header Owner / Guest switcher and Download for offline (preview). That preview does not include lockbox or Wi‑Fi codes, and it expires after 7 days.
The service worker still caches the published catalog and uploaded photos after a successful online read (production builds). Check the download button, not a single page view. On an iPhone, storage pressure can drop cached photos; the saved guide text remains. Appliance manual PDFs are not in the offline pack. Bundled JSON and images remain a fallback if the API is down and no pack was saved.
Troubleshooting
| Problem | What to check |
|---|---|
| Sitters still see old text | Did you Publish? On the tablet, online and on Wi‑Fi, open House Guide and let the banner update, or tap Update offline copy. A hard refresh does not replace a saved offline pack. |
| Photo shows “Image unavailable” | Photo block has empty or deleted mediaId — re-upload or pick from library. |
| Quick action does nothing | Publish topic; confirm Alexa button number matches Controls app. |
| Search does not find topic | Add Search keywords; publish. |
| “Copy to cloud” needed again | Rare — usually only on a fresh environment without D1 seed. |
| API errors on reorder/upload | Worker may need deploy — see house-guide-cms.md. |
Text, emojis, and formatting today
The editor is plain text only:
- All fields are
{textarea}/{input}— no bold buttons, no font picker, no WYSIWYG. - Content is stored as strings and displayed with
textContent(HTML is not interpreted — pasted markup appears as literal characters). - Line breaks in a single paragraph field appear as one block of text unless you split into separate blocks or use Numbered steps / Details list.
Emojis today
Unicode emojis work if you paste or type them directly into any text field (title, steps, tips, button labels): 🐕 ✅ ⚠️ 📺. They render on sitter tablets like normal characters.
There is no emoji picker in the app yet. Use your system emoji keyboard on the device you edit from, or copy/paste.
Use emojis sparingly — one per heading or callout is enough. Screen readers read emoji names; warnings are clearer as Warning blocks than as emoji alone.
Rich text — directions to consider
If you want more expressive editing later, these are the main options (not built yet — for planning):
Option 1 — Lightweight Markdown (recommended direction)
Allow a small subset in paragraph/callout fields:
**bold**,*italic*,[link text](url)- Optional
-bullet lines inside a paragraph block
Pros: Fast to type, stores plain strings, easy to sanitize, works with emoji.
Cons: Owners must learn minimal syntax (or we add toolbar buttons that insert markers).
Option 2 — Structured inline styles (no free HTML)
Store content as [{ t: "text", bold: true }, { t: "🐕" }] instead of raw HTML.
Pros: Safe, predictable rendering.
Cons: More complex editor UI and migration from existing strings.
Option 3 — Full rich text (contenteditable / ProseMirror / TipTap)
WYSIWYG bold, lists, links, emoji picker.
Pros: Familiar Word-like experience.
Cons: Harder on tablets, paste-from-Word mess, security sanitisation, harder to keep block-based layout consistent.
Option 4 — Emoji picker only (smallest step)
Keep plain text; add a button that inserts emoji at the cursor in text fields.
Pros: Quick win, no rendering changes.
Cons: Still no bold/links.
Recommendation
Stay block-based for layout (steps, warnings, photos). Add Markdown-lite + emoji picker inside text fields first — best balance for a tablet-edited home manual. Avoid full HTML or paste-rich-word unless you need it.
If you want to pursue this, a sensible phase would be:
- Emoji picker on titles, steps, tips, action labels
- Markdown rendering for
text/tip/warning/note/collapsibleonly - Link validation and “open in new tab” for external URLs
Related docs
- house-guide-cms.md — architecture, API, Cloudflare setup
- house-guide-content.md — legacy git/JSON workflow (fallback)
- appliance-manuals.md — PDF manuals for appliances
Quick reference — owner checklist
- [ ] Cloud guide seeded (Copy current guide to cloud once)
- [ ] Edit in Guide Editor, not git, for day-to-day changes
- [ ] Save draft while working; Publish when sitters should see it
- [ ] Use steps + warnings + photos for how-to content
- [ ] Add search keywords for how sitters actually ask
- [ ] Upload photos with clear alt text
- [ ] Test as sitter: Guest view + House Guide app
- [ ] Emojis OK as unicode; no bold/italic until rich text is added