estatehelm 1.0.0

package/README.md

@@ -0,0 +1,181 @@
+# EstateHelm CLI
+
+Command-line tools for EstateHelm, including an MCP (Model Context Protocol) server for AI assistants like Claude Code.
+
+## Installation
+
+```bash
+npm install -g estatehelm
+```
+
+## Quick Start
+
+### 1. Login
+
+```bash
+estatehelm login
+```
+
+This will:
+1. Open your browser for OAuth authentication
+2. Prompt for your Recovery Key
+3. Register this device as a trusted device
+4. Sync your encrypted data locally
+
+### 2. Configure Claude Code
+
+Add to your `~/.claude.json` (or Claude Code settings):
+
+```json
+{
+  "mcpServers": {
+    "estatehelm": {
+      "command": "estatehelm",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+### 3. Use with Claude Code
+
+Start Claude Code and you can now ask questions like:
+- "What pets do I have?"
+- "Show me upcoming maintenance tasks"
+- "What's the WiFi password for the cabin?"
+- "What insurance policies are expiring soon?"
+
+## Commands
+
+### `estatehelm login`
+
+Authenticate with EstateHelm and register this device.
+
+### `estatehelm logout`
+
+Remove credentials and revoke device access.
+
+### `estatehelm mcp [options]`
+
+Start the MCP server.
+
+Options:
+- `-m, --mode <mode>` - Privacy mode: `full` (default) or `safe`
+- `--poll <interval>` - Background sync interval (e.g., `15m`)
+
+### `estatehelm status`
+
+Show current login status and cache information.
+
+### `estatehelm sync`
+
+Force sync cache from server.
+
+### `estatehelm cache clear`
+
+Clear local cache (keeps credentials).
+
+### `estatehelm cache stats`
+
+Show cache statistics.
+
+### `estatehelm config set <key> <value>`
+
+Set a configuration value.
+
+Available keys:
+- `defaultMode` - Default privacy mode (`full` or `safe`)
+
+### `estatehelm config get [key]`
+
+Get configuration value(s).
+
+## Privacy Modes
+
+### Full Mode (default)
+
+All data is returned as-is. Use this when you're alone and want full access.
+
+```bash
+estatehelm mcp --mode full
+```
+
+### Safe Mode
+
+Sensitive fields (passwords, account numbers, etc.) are redacted. Use this when sharing your screen or when uncertain.
+
+```bash
+estatehelm mcp --mode safe
+```
+
+Redacted fields by entity type:
+- `password`: password, notes
+- `identity`: password, recoveryKey, securityAnswers
+- `bank_account`: accountNumber, routingNumber
+- `investment`: accountNumber
+- `access_code`: code, pin
+- `credential`: documentNumber (shows last 4)
+
+## MCP Resources
+
+The server exposes your EstateHelm data as MCP resources:
+
+- `estatehelm://households` - List all households
+- `estatehelm://households/{id}` - Specific household
+- `estatehelm://households/{id}/pets` - Pets in household
+- `estatehelm://households/{id}/properties` - Properties
+- `estatehelm://households/{id}/vehicles` - Vehicles
+- `estatehelm://households/{id}/contacts` - Contacts
+- `estatehelm://households/{id}/insurance` - Insurance policies
+- `estatehelm://households/{id}/bank_account` - Bank accounts
+- And more...
+
+## MCP Tools
+
+- `search_entities` - Full-text search across entities
+- `get_household_summary` - Overview with counts
+- `get_expiring_items` - Items expiring soon
+- `refresh` - Force re-sync from server
+
+## Security
+
+- **Zero-knowledge**: Your data is encrypted locally. The server never sees plaintext.
+- **Recovery key**: Only used locally for key derivation. Never uploaded.
+- **Device revocable**: Remove from Settings → Trusted Devices in EstateHelm
+- **OS keychain**: Credentials stored securely in your OS keychain
+- **Safe mode**: Optional field-level redaction for sensitive data
+
+## Data Location
+
+```
+macOS:    ~/Library/Application Support/estatehelm/
+Windows:  C:\Users\<name>\AppData\Roaming\estatehelm\
+Linux:    ~/.local/share/estatehelm/
+
+Contents:
+├── cache.db      # SQLite database (encrypted entities)
+├── config.json   # User preferences
+└── .device-id    # Device identifier
+```
+
+## Troubleshooting
+
+### "Not logged in"
+
+Run `estatehelm login` to authenticate.
+
+### "Failed to load encryption keys"
+
+Your credentials may have been revoked. Run `estatehelm logout` then `estatehelm login` again.
+
+### "Device was removed"
+
+The device was revoked from EstateHelm settings. Run `estatehelm login` to re-register.
+
+### Cache issues
+
+Try clearing the cache: `estatehelm cache clear`, then `estatehelm sync`.
+
+## License
+
+Proprietary. Copyright EstateHelm.