# Cobalt household demo runbook

This is a synthetic local exercise. Keep real household records out of it.

## 1. See what the notes would do

Run:

```sh
node cli.cjs prepare fixtures/notes.json
```

The output lists A1, A2, and A3, shows their source-line numbers, and includes a long `revision` fingerprint. This step creates no drafts.

The parser only recognizes lines starting `ACTION |`. Ordinary prose stays ordinary prose. A language model does not interpret or expand it. A malformed action stops the run with an error so it cannot silently become an invented task.

## 2. Review the exact actions

In a real review flow, a person would read each proposed destination, subject/body, date, time zone, and duration. Approval must identify the same meeting, the displayed revision, and the selected action IDs. A change to any note invalidates the earlier approval.

For this exercise, `fixtures/approval.json` is already populated with synthetic approval for A1 and A2. A3 is intentionally not approved. The fixture is a test input, not an authenticated human decision.

## 3. Create local drafts and repeat safely

```sh
node cli.cjs apply fixtures/notes.json fixtures/approval.json demo-state
```

Expected: two local draft objects, one remaining review ID (`A3`), and zero external actions. Open `demo-state/ledger.json` to inspect the records. These are JSON objects on disk, not Gmail drafts or live calendar events.

Run the identical command again. Expected: zero new draft objects and two `already_drafted` records. Keep using the same state folder. A different or deleted state folder has no memory of earlier drafts.

## 4. Understand a failure

| Visible message | Meaning | Recovery |
| --- | --- | --- |
| Approval does not match this exact meeting revision | Notes or meeting identity changed | Run prepare again and review the new proposal. Do not copy an old approval blindly. |
| Ledger is locked | Another process may be writing, or a stopped run left its lock | Stop initiating runs. Check whether another demo process is still active. Only after verifying none is active, move the lock aside and rerun against the same ledger. |
| Invalid state / malformed JSON | The ledger is damaged or has the wrong format | Preserve the file, stop processing, and restore a verified copy. Do not silently reset it to empty. |
| Ledger conflict | An existing draft differs from the expected record | Preserve the ledger and investigate the change before retrying. |
| Calendar time requires an explicit valid UTC offset | A date lacks an unambiguous time zone | Correct the source time with its offset, then prepare and review again. |
| Recipient must use the reserved .invalid domain | Real addresses are intentionally unsupported in this demo | Keep using the fictional fixture. Real destinations require a separately reviewed integration. |

Failures return exit code 1 and a JSON error to the terminal. There is no email or push alert because no external service is connected.

## 5. Recover from interruption

The CLI takes an exclusive lock before reading the ledger and replaces the ledger using a same-directory rename after preparing the complete result. Draft objects and replay keys are committed together. The command may fail after a successful write but before its output reaches the screen; repeating the same approved input will find the saved records and report skips.

A hard crash can leave `.lock` or `ledger.pending.json`. Preserve those files and inspect the last committed `ledger.json` before recovery. This file-based example is not a database, does not provide a power-loss durability guarantee, and has not been tested on network filesystems. The test run verifies ordinary local process replay, lock refusal, and corrupt-ledger refusal.

## 6. Household data boundary for a future deployment

| Information | Proposed starting location | Current demo behavior |
| --- | --- | --- |
| Original notes and private documents | Agreed folder on the household Mac | Synthetic local notes only; no documents read |
| Review list and approval history | Local service and local store | JSON review result and explicit approval fixture |
| Calendar suggestion and email text | Local drafts until a person approves destination and content | Local JSON objects only |
| Cloud request | Only explicitly selected fields and an agreed provider | No cloud requests exist |
| API tokens | A dedicated credential store with least privilege | No API tokens exist |

Before a real installation, confirm the Mac model, memory, storage, backup and sleep behavior, existing n8n version, account ownership, and permitted data destinations. Agree the authentication, review, retry, alert, retention, and credential-renewal behavior. Benchmark any local model on an approved non-sensitive sample before promising a response time. Production OAuth renewal, encryption, Notion/Google integration, model hosting, and private document indexing are outside this demonstration.