The Clearing

A safe haven carved out of the chaos. Daily care companion — pain, headaches, focus, and small joys, all in one warm hearth.

Built in the Stewardship OS "Cozy Solarpunk" style with the Keepers (Lumi, Patch, Echo, Dash) woven throughout.

A Note on Development: This application is proudly "vibe coded" with the assistance of AI. Utilizing AI as a collaborative pair-programming partner allows for a deeply personal, creative, and joyful development process to bring this vision to life. If you're curious about AI-assisted development, you'll find its fingerprints in the swift iteration and cozy aesthetic of this project.

---

Install (Windows 11)

Download the latest build from the Releases page:

1. TheClearing-Setup-1.4.2.exe — full installer. Recommended.
   • Creates Start Menu + Desktop shortcuts
   • Registers auto-launch on sign-in
   • Lives in %LOCALAPPDATA%\Programs\TheClearing
2. TheClearing-Portable-1.4.2.exe — single-file, no install. Just double-click.

Because the app isn't code-signed, SmartScreen will say "Windows protected your PC" the first time. Click More info → Run anyway. That only happens once.

Data lives here

• Database: %APPDATA%\TheClearing\clearing.db (single SQLite file — back it up, copy it, sync it to Google Drive, whatever you like)
• Settings: %APPDATA%\TheClearing\config.json
• Network cert: %APPDATA%\TheClearing\net-cert.pem + net-key.pem (self-signed, generated on first Network enable)

How to use it

Place	What it's for
The Hearth	Home dashboard. Today at a glance, quick actions, recent pain, recent journal, Keepers.
Dash's Pace	Work/break timer. Configurable minutes, gentle chime, auto-long-break.
Headache Ledger	Separate tabs for Headaches vs Migraines. Quick-log or detailed entry. One-click monthly doctor report (PDF).
Pain Log	Multiple entries per day. Severity pills 0–10, locations, quality chips, notes, timeline grouped by day.
Lantern Log	Short-form bulleted journal + gratitude + accomplishments. Three types, three colors.
Reports	Any date range, pick sections (Overview, Pain, Headaches, Migraines, Journal, Focus). Print, Save as PDF, or raw CSV exports.
Achievements	Track and celebrate your progress with tiered Cozy Solarpunk badges for your interactions up to 1,000,000 milestones!
The Workshop	Settings. Your Information (name, DOB, pronouns, meds, providers, emergency contact — all blank by default), toggle autostart, edit chip vocabularies, manual backup, Phone & network sharing, about.

Always-on behavior

• Tray icon (lantern): single-click toggles the window. Right-click for Open / Start Pomodoro / Log Pain / Log Headache / Journal Entry / Quit.
• Closing the window minimizes to tray — The Clearing keeps running quietly. Use "Quit" from the tray menu to fully exit.
• Global hotkey: Ctrl + Alt + C pops the Clearing open from anywhere in Windows.
• Sidebar toggle: Ctrl + B collapses the left menu to icon-only (state persists).
• Autostart on sign-in is on by default (toggle in The Workshop).
• Single-instance lock — clicking the shortcut a second time just focuses the already-running window.

Phone & network sharing (v1.3.x)

• Open The Workshop → Phone & network sharing, flip Share on local network on.
• On your phone (same Wi-Fi), visit the HTTPS URL shown. Your phone will warn about the self-signed cert — tap Advanced → Proceed. Normal for a home server.
• Back on the desktop, tap Begin pairing and type the 6-digit code on your phone. Done.
• Every entry made on either device syncs to the other in real time (Server-Sent Events). No manual refresh needed.
• Revoke a device any time from the Paired devices list — that device's screen is wiped and it's returned to the pair screen within a second.

Security posture

• Self-signed TLS cert generated locally (stored encrypted via Windows DPAPI / Electron safeStorage).
• Bearer-token per device, minted only by a short-lived 6-digit code you type in.
• Nothing leaves your LAN. Best-effort security, no warranty — intended for trusted home networks.

Backup

The Workshop has a Manual backup button that copies clearing.db to a location you choose. For cloud sync, point the copy into your Google Drive folder — the whole database is one portable file.

Print monthly doctor reports

1. Go to Reports.
2. In Quick doctor reports, click This month · Headaches (or migraines, or last month, or 3-month quarterly).
3. A preview window opens with the stats, a frequency bar, top triggers/symptoms, and every episode. Hit Print or Save as PDF.

The Keepers

Spirits of the System. They appear in the left footer panel with a rotating note relevant to what you're doing.

• 🕯️ Lumi — The Lantern-Bearer. Guide / Perspective.
• 🔨 Patch — The Beaver. Builder / The Ledger keeps what memory forgets.
• 🦉 Echo — The Owl. Sage / Governance / Confirmations.
• ⚡ Dash — The Hare. Connector / Pace / Short sprint, long mercy.

Tech

• Electron 31 + better-sqlite3 11 (local SQLite, no cloud)
• Embedded HTTPS server (Node https) + mDNS (bonjour-service) for phone pairing
• Server-Sent Events for realtime sync; per-device bearer tokens
• All UI is plain vanilla JS modules — no framework
• electron-builder NSIS + portable targets, x64
• Theme: Amber Gold #FFBF00, Deep Slate #2D3436, Moss #55EFC4, Moonlight #74B9FF, Kinetic Lime #A3CB38

Customizing

• Edit pain locations, pain qualities, headache triggers, headache symptoms in The Workshop → Customize vocabulary. Changes apply immediately.
• Change global hotkey: src/main.js → globalShortcut.register('CommandOrControl+Alt+C', ...).
• Change autostart: app.setLoginItemSettings({ openAtLogin: false }).

Run from source

npm install
npx electron-rebuild -f -w better-sqlite3
npm start

Rebuild installers:

npm run dist          # NSIS installer
npm run dist:portable # portable .exe

Project layout

src/
  main.js                  Electron main process — BrowserWindow, tray, IPC, boot sequence
  preload.js               Context-bridge between renderer and main
  db.js                    SQLite schema + query helpers (better-sqlite3)
  backup.js                Manual + portable backup / restore
  secure-store.js          DPAPI-encrypted settings store
  network.js               HTTPS server, pairing, devices, SSE, (future) synced timer
  network-assets/          Mobile PWA (HTML/CSS/JS/manifest/service worker)
  renderer/
    index.html, app.js     Desktop app shell
    views/                 Hearth / Pomodoro / Headache / Pain / Journal / Reports / Settings
    util.js, keepers.js
assets/                    Icons + installer imagery
build/                     electron-builder artifacts (tray icon, NSIS script)

Roadmap

• Direct Google Drive sync (hook points wired in src/backup.js).
• Synced pomodoro timer across devices (SSE scaffolding exists; UI was pulled in v1.3.2).
• Mac + Linux builds.

Changelog

See CHANGELOG.md.

License

MIT — personal health-tracking app built for and by the author. Use, fork, adapt.

---

One good thing. Just one. That is where we start. — Lumi