Office Assistant · Design Contract

A lifecycle manager for everything you own

The catalogue is the spine. Each entry accrues domain objects — purchase, warranty, insurance, service, subscription — and each is a state machine over its scraped documents, advanced only by actions.

NEW / UNKNOWN IN_PROGRESS / ACTIVE DUE / OPEN action COMPLETED / RESOLVED EXPIRED / LAPSED

The catalogue — one registry, two kinds

products

The single registry of everything owned or subscribed to. Every domain object hangs off a catalogue entry by product_id — one query assembles the whole dossier.

physical tangible asset

accessoryAccessories — durable add-ons that extend value (a car stereo, the AMS Lite). Usually one-time.
consumableConsumables — replenished items (detergent, engine oil, filament), frequently on a subscription.

virtual digital / service

bundleBundles — grouped virtual items (an Adobe CC suite).
billingOne-time (Plex Lifetime, a Steam game) or subscription (Ollama, Fastmail) — decides whether it carries a recurring billing domain.

Domains — state machine × action set × required docs

Every domain shares one status vocabulary; what differs is its action set and the minimum documents it must archive. The store row is the AI-scraped metadata index over those files.

Purchase / fulfilment

invoices

NEW→ IN_PROGRESS→ COMPLETED

Actions

paymentshipmentout-for-deliverydeliverycustomsdutyreturnrefund

Min. documents

purchase-orderinvoice / receipt

One shared status vocabulary. Every edge is an action — automatic (agent) or user-assisted. An OPEN action means the item needs attention whatever its status; the tracker advances anything live and skips COMPLETED.

NEW scrape IN_PROGRESS paid·shipped COMPLETED

Warranty refinement: ACTIVE → EXPIRED is computed from expiry by warranty-sweep (agent), which auto-opens a renew-or-extend action for you.

Recurring refinement: insurance · registration · subscription cycle ACTIVE → DUE in the renewal window → RENEWED, or LAPSED if missed.

OPEN needs attention

Surfaced by store.py attention regardless of lifecycle status — this is the agent's worklist.

RESOLVED action closed

Resolving an action can fire the state transition it guards (e.g. renew-policy → back to ACTIVE).

USER vs AGENT owner

Each action is tagged automatic or needs-you, so nothing waits silently on the wrong party.

Worked example — the Maruti Ritz

One physical catalogue entry, four domain objects, each with its own state and actions. This is the shape a real asset takes in the store.

🚗

Maruti Suzuki Ritz LXi

owned products / prod_maruti-suzuki_ritz-lxi

purchaseoriginal purchase documentCOMPLETED

insuranceHDFC Ergo motor policy — renews 2027-05-05ACTIVE

registrationRC re-registration — expired 2026-05-05, OPEN action renew-registration (you)DUE

serviceDAKSHINA out-of-warranty service historyCOMPLETED

Build status

DONEFramework verbs in store.py — set-status · action-add/resolve · doc-add · attention · warranty-sweep
DONEBackfill applied — 48 invoices COMPLETED · 19 warranties ACTIVE · FNIRSI warranty actions OPEN
NEXTSchema write-up + new subscriptions / insurance stores + memory→store migration
NEXTMCP interface wrapping the verbs as parameterized tools

The verbs

set-statusaction-addaction-resolve doc-addattentionwarranty-sweep

Open decision — persistence. Stay on JSONL + stdlib (zero-dependency, git/chezmoi-versioned) or move to MongoDB (richer queries, native document collections — you have it installed)? The domain model above is identical either way; only the store layer changes.