HouseQuest Core v0.6.0

HouseQuest Core is a self-hosted, local-first household mission game. A parent can record a natural video of one or more messes in a known room; HouseQuest interprets the visible mess and parent speech, extracts a representative still for each mission, and preserves only a clearly direct parent-to-child audio message. A parent can also ask HouseQuest to find a visible object or surface across eight temporary views of a textured GLB, confirm the raycast-grounded 3D point, and attach that point to any unpublished mission in the same room. A child launches each proof-required mission from a pictorial rocket control, flies into a reversible dollhouse cutaway of the room, orbits the chosen mission point when one is attached, and sees the room and mess photo together. Textured-room orbit framing samples the actual transformed scan vertices, trims sparse horizontal outliers, anchors whole-room rotation at the inferred floor center, and preserves a stable camera distance so stray scan fragments cannot pull the room out of view. The child returns through a preschool pictorial camera control, submits the required after photo, works through every queued mess, opens earned rewards, and brings the device to the parent for an accept-or-retry gallery.

HouseQuest is game-first. Room models and placements are spatial grounding for missions, not a general inventory database, CAD package, or facility-management system.

The repository is the complete MIT-licensed source distribution. It contains no household database, room scan, mess photo, PIN, session, provider credential, or private demonstration capture.

v0.6.0 feature videos

Both demonstrations use a generated geometric room and synthetic mess art. They contain no household scan, photo, name, database, or voice recording.

• Find and confirm a reusable 3D mission point
• Launch a child mission, orbit its chosen point, and reveal the mess

The parent point finder renders eight temporary views, asks the configured vision model for one evidence-backed image coordinate, raycasts that coordinate onto loaded room geometry, and waits for parent confirmation before persistence. Mission drafts may reference one confirmed point from the same room. The child reveal then anchors its zoom and orbit to that immutable camera pose while the mess photo fades in beside the room.

Supported runtime

Dependency	Supported contract
Node.js	24 or newer
OMP	17.1.5 or newer, with the required non-interactive flags
Model	google-antigravity/gemini-3.5-flash
Thinking	low
Media tools	ffmpeg and ffprobe
Browser	Current Chromium, Safari, or Firefox with WebGL support
Managed service	Windows 10/11, current user, Scheduled Task

Install dependencies without running package lifecycle scripts:

npm ci --ignore-scripts

Run the release gate before trusting an extracted source archive:

npm run release:check

The gate rejects untracked or ignored files, proof media, private workstation paths, secret-shaped text, an unexpected package allowlist, and nondeterministic source-tree ordering.

Quick start on Windows

1. Install Node 24 or newer, OMP 17.1.5 or newer, FFmpeg, and FFprobe.
2. Extract HouseQuest Core to a stable source directory. Do not run the managed service from Downloads or a temporary extraction directory.
3. Open PowerShell in the source directory.
4. Run:

npm ci --ignore-scripts
node scripts/housequest.mjs doctor --data-dir "$env:LOCALAPPDATA\HouseQuestNext"
powershell -NoLogo -NoProfile -ExecutionPolicy Bypass -File deploy/install-service.ps1

5. Open http://127.0.0.1:4200 or double-click Start HouseQuest Core.cmd. The launcher installs or upgrades the same-user service and opens the browser only after readiness succeeds.
6. Create the household, choose a parent PIN, and add kid names.

The installer writes one strict housequest.service.v1 configuration under the private data directory and registers the existing same-user Scheduled Task name HouseQuest Next. It refuses to replace a task owned by a different user or pointing outside the current or recognized legacy HouseQuest source tree.

Foreground run on any supported Node host

Managed-service scripts are Windows-only. The application itself can run in the foreground anywhere Node and the required tools are available:

$env:HOUSEQUEST_NEXT_DATA_DIR = "C:\private\housequest-data"
$env:HOST = "127.0.0.1"
$env:PORT = "4200"
npm start

On bash-compatible hosts, set the same environment variables with export.

Defaults:

• host: 127.0.0.1
• port: 4200
• database: <data-dir>/housequest-next.sqlite
• media: <data-dir>/media
• OMP: omp
• FFmpeg: ffmpeg
• FFprobe: ffprobe

Optional exact overrides:

• HOUSEQUEST_NEXT_MEDIA_DIR
• HOUSEQUEST_NEXT_DB_PATH
• HOUSEQUEST_ALLOWED_HOSTS
• HOUSEQUEST_OMP_PATH or OMP_PATH
• HOUSEQUEST_FFMPEG_PATH or FFMPEG_PATH
• HOUSEQUEST_FFPROBE_PATH or FFPROBE_PATH
• HOUSEQUEST_OMP_MODEL
• HOUSEQUEST_OMP_THINKING

A non-loopback bind fails closed unless HOUSEQUEST_ALLOWED_HOSTS supplies the exact comma-separated hostnames or IP literals clients will send in the HTTP Host header. Browser mutation requests also require same-origin Origin or Sec-Fetch-Site provenance. HouseQuest does not trust forwarded-host headers and is not configured here for a reverse proxy.

Example private-LAN bind:

$env:HOST = "0.0.0.0"
$env:HOUSEQUEST_ALLOWED_HOSTS = "housequest.home,192.168.1.50"
npm start

Do not expose this HTTP listener directly to the public internet. TLS, remote identity, reverse-proxy trust, and internet routing require a separately reviewed boundary.

Doctor

Shallow doctor checks Node, OMP version and required flags, FFmpeg, FFprobe, configuration, the single-writer lock, and private filesystem permissions. An absent database is a valid pre-install state and is not created by doctor.

node scripts/housequest.mjs doctor --data-dir "$env:LOCALAPPDATA\HouseQuestNext"

Deep doctor additionally checks a private snapshot of SQLite, schema version, every database media reference, every stored media file, sizes, available hashes, missing files, and orphaned files:

node scripts/housequest.mjs doctor --deep --data-dir "$env:LOCALAPPDATA\HouseQuestNext"

Stop the service before deep doctor. A live process owns the data lock, so doctor reports in-use rather than reading a changing household. Doctor emits one versioned JSON receipt and never emits private paths, filenames, PINs, session tokens, prompts, or provider payloads.

Backup

Backups are deterministic store-only ZIP64 archives with a strict manifest, a checkpointed SQLite database, every private media file, byte sizes, SHA-256 hashes, and structural media validation. The output must be outside the live data directory and must not already exist.

Stop the service, then create a backup:

Stop-ScheduledTask -TaskName "HouseQuest Next"
node scripts/housequest.mjs admin backup `
  --data-dir "$env:LOCALAPPDATA\HouseQuestNext" `
  --output "D:\HouseQuest Backups\household-2026-07-29.hqbackup"

Copy the completed archive to a second private device or encrypted volume. The receipt includes archive bytes, manifest hash, schema version, and media count. A backup is not proven until the command completes successfully.

Backup creation inspects and snapshots the stopped SQLite database directly. It does not construct the application store or migrate an older schema; the source database, WAL/SHM sidecars, media, and schema version must remain unchanged while the archive is created.

Restore

Restore rejects malformed ZIP structures, traversal paths, links, duplicate or unexpected entries, unsupported manifests, corrupt hashes, bad media signatures, failed SQLite integrity, and unsupported schema versions before touching live data.

Restore always creates a timestamped safety backup of the current household beside the live data directory, closes SQLite, swaps database and media as one operation, restores filesystem privacy, and rolls back the swap on failure.

Stop-ScheduledTask -TaskName "HouseQuest Next"
node scripts/housequest.mjs admin restore `
  --data-dir "$env:LOCALAPPDATA\HouseQuestNext" `
  --input "D:\HouseQuest Backups\household-2026-07-29.hqbackup" `
  --yes
node scripts/housequest.mjs doctor --deep --data-dir "$env:LOCALAPPDATA\HouseQuestNext"
Start-ScheduledTask -TaskName "HouseQuest Next"

--yes is mandatory because restore replaces live household data. Keep the reported pre-restore safety archive until browser verification is complete.

Upgrade

1. Stop the Scheduled Task.
2. Create and retain a backup outside the data directory.
3. Extract the new source candidate to a new stable directory.
4. Run npm ci --ignore-scripts and npm run release:check in the new source directory.
5. Run shallow and deep doctor against the private data directory.
6. Run deploy/install-service.ps1 from the new source directory. The installer atomically rewrites the strict service config and replaces only an owned task.
7. Confirm http://127.0.0.1:4200/readyz, then exercise parent and kid flows in the browser.
8. Retain the prior source directory and backup until the upgrade is accepted.

HouseQuest Core v0.6.0 remains on schema version 8. Its point-of-interest feature is source-only: the browser captures eight temporary views of a loaded textured GLB, the configured Gemini model returns one strictly validated image-space selection or an honest no-match result, the browser raycasts that selection into the local model, and only a parent-confirmed camera pose is stored. The contact sheet is deleted after the bounded request and is never added to HouseQuest media. Missions use interaction artifact v2 to reference an optional same-room focus area, and the child orbit anchors to that exact point. Legacy interaction v1 records remain readable. The v0.5.3 robust textured-room orbit framing, v0.5.2 child navigation and camera refinement, v0.5.1 dollhouse refinement, and v0.5.0 video-first mission pipeline remain unchanged and compatible.

Rollback

Code rollback and data restore are separate decisions:

1. Stop the Scheduled Task.
2. Run the prior source directory's deploy/install-service.ps1 to return the task and service config to that source tree.
3. Start the task and check /readyz.
4. Restore a backup only if the failed upgrade changed household data or the prior source cannot read the current schema. A source-only rollback normally leaves data untouched.

Never copy one runtime's SQLite or media directory over another live runtime. Use the receipted backup/restore commands with both services stopped.

Uninstall

The uninstaller removes only a Scheduled Task owned by the current user and matching the current or recognized legacy HouseQuest action. It does not delete source, SQLite, media, backups, OMP, Node, FFmpeg, or FFprobe.

powershell -NoLogo -NoProfile -ExecutionPolicy Bypass -File deploy/uninstall-service.ps1

Delete private household data only as a separate, deliberate owner action after a verified backup. The default data root is %LOCALAPPDATA%\HouseQuestNext.

Household workflows

Parent

1. Create a room and upload a textured Scaniverse GLB when available.
2. Open the room and choose Record mess video. Point at each mess, pause so it is clear, and speak naturally. HouseQuest drafts the missions without mandatory typing and extracts one grounded still per mission.
3. HouseQuest uses ordinary parent speech as drafting context. It preserves and plays only an exact bounded segment that the agent identifies as a direct message to the child; unrelated speech stays out of the child experience. Review the inferred missions, optionally add correction text or choose a reward, then publish the queue.
4. Use Use mess photos when a still-photo fallback is preferable; select up to eight room photos to generate separate silent missions.
5. Use Find in 3D in a textured GLB room to describe a visible object or surface, inspect the highlighted result, and save it as a reusable 3D point. In each unpublished mission card, choose a saved point from 3D focus point before publishing. Mark this view remains available for precise manual camera placement. Use House Memory to say where an item belongs and optionally attach one item-reference image.
6. Open Rewards to use the built-in stickers and 3D trophies, generate a bounded sticker or OBJ trophy with Gemini, or add validated family art, an optional voice clip, and a physical redemption instruction.
7. Review each completed before-and-after pair. Accept the result or return that exact mission for another photo.

Kid

1. Press Start on the current mission.
2. Press Go to watch the room orbit and zoom toward the target; the extracted mess still fades over the room model. No synthetic text-to-speech voice plays. If the parent recorded a direct message for the child, only that bounded original-audio segment plays.
3. Clean the mess, return to the mission, and take the required PNG, JPEG, or WebP after photo.
4. HouseQuest stores and assesses the proof, completes that item, and immediately offers the next queued mess. A parent-requested retry returns the exact mission with clear guidance and requires a new photo.
5. After the queue is complete, bring the device back to the parent for the before-and-after review. Earned rewards can then be opened and kept on the trophy shelf.

Room capture and media

Textured Scaniverse GLB is the preferred mobile-proven room format. Retained spatial formats are .glb, .spz, .splat, .ksplat, and .ply.

HouseQuest validates file structure, not only extensions and MIME labels:

• images: HEIC/HEIF, JPEG, PNG, WebP
• video: MP4, MOV, M4V, WebM
• audio: M4A, OGG, WebM
• spatial: SPZ, SPLAT, KSPLAT, PLY, GLB
• reward visuals: transparent PNG stickers, bounded standalone OBJ trophies, or validated physical-reward images
• reward voice clips: M4A, OGG, WebM

Limits:

• room spatial assets: 750 MiB
• captures: 250 MiB
• proof, reference, and item-reference images: 12 MiB
• spoken House Memory: 8 MiB
• extracted query frames: 5 MiB
• reward sticker or physical-reward images: 12 MiB
• reward voice clips: 8 MiB
• reward trophy OBJ files: 2 MiB

Empty, oversized, mislabeled, corrupt, symlinked, or junction-traversing media fails closed. Upload retries use a stable upload key and never leave a partial final file.

Data custody and provider privacy

SQLite, media, service configuration, locks, and local backups are private household material. HouseQuest restricts them to the current Windows user and SYSTEM, or owner-only modes on POSIX hosts. It refuses to operate when privacy enforcement fails.

HouseQuest adds no telemetry or cloud storage. It is not air-gapped:

• OMP sends selected workflow prompts and attachments to the configured model provider.
• Placement teaching text is sent for interpretation.
• Selected room, proof, item-reference, and temporary point-search contact-sheet images may be sent. Point-search contact sheets are deleted after the bounded request and are not retained as HouseQuest media.
• Stored voice recordings are not sent to the model; their reviewed textual interpretation may be.
• Reward-generation directions and the text-only configured mission-reward catalog may be sent. Uploaded or generated reward media and recorded reward voice clips are not attached to mission-drafting requests.
• OMP/model-provider retention, account, and regional terms remain outside this repository and must be reviewed by the operator.

Never put real household media, database files, PINs, session cookies, provider credentials, or workstation-specific paths in source control or issue reports.

Troubleshooting

• DATA_DIR_IN_USE: stop the other HouseQuest process. Do not delete a live lock. A later owner safely reclaims a receipted stale lock after process death.
• MISDIRECTED_REQUEST: correct the browser URL or exact allowed-host list. Do not bypass Host checks.
• CROSS_ORIGIN_REQUEST: use the HouseQuest origin directly. Do not add a permissive CORS wildcard.
• OMP_UNAVAILABLE: install OMP 17.1.5 or newer and confirm doctor reports every required flag.
• PRIVATE_PERMISSIONS_INVALID or PRIVATE_PERMISSIONS_FAILED: restore ownership/ACL authority; do not broaden household data permissions.
• MEDIA_CONTENT_INVALID (HTTP) or MEDIA_SIGNATURE_INVALID (CLI): re-export the actual media. Renaming an extension does not make bytes valid.
• restore rejection: preserve the archive and live data unchanged; do not extract and copy individual files by hand.

Complete command help is machine-readable and has no filesystem side effects:

node scripts/housequest.mjs --help

Deferred capabilities

Not present or implied in v0.6.0:

• automatic semantic classification or destructive editing of scan geometry
• automatic saved-view repair for scans without a usable parent-marked view
• automated splat diagnosis and repair
• refrigerator, pantry, grocery, party, or general household-management automation

License and security

HouseQuest Core is licensed under the MIT License. See LICENSE.

Report suspected vulnerabilities privately as described in SECURITY.md. Do not open a public issue containing private household data or exploit details.