Cadence

A local-first workspace for the way you actually work.

People, tasks, notes and agenda — encrypted on your device.AI when you want it, off when you don't.

🌐 Marketing site · 📖 User guide · 🚀 Try the web app · ⬇️ Download for macOS

---

Why Cadence

A planner that doesn't ship your day to someone else's server. Four trade-offs we picked the unfashionable side on:

🔒 100% local-first	Every keystroke is written to your machine, not to a server. Atomic fsync'ed writes, 50 rolling auto-snapshots, refuse-to-overwrite guard, in-app recovery UI. A power loss or kernel panic can't lose acknowledged data.
🛡️ Encrypted at rest	The desktop data file is wrapped in AES-256-GCM with a key derived from your account password via scrypt. Notes get an opt-in passphrase lockbox on top (PBKDF2-SHA-256, 200k iters → AES-256-GCM, non-extractable CryptoKey).
🤖 AI is opt-in, BYO key	Bring your own API key for Anthropic Claude, OpenAI or Google Gemini, or point Cadence at your own gateway (OmniRoute, LiteLLM, Ollama, a company proxy) in any of four API formats. Calls go directly from your device to the provider — no Cadence proxy, no telemetry. Off completely until you pick a provider.
📖 Open source, no upsell	The codebase is on GitHub under MIT. No accounts in the cloud, no premium tier, no waitlist. The desktop app auto-updates straight from GitHub Releases.

About the name — Cadence is the new name for the project formerly called Leeadman. The desktop app auto-migrates legacy data on first launch (it copies Leeadman/ → Cadence/, renaming the leeadman-* files to cadence-*; the legacy folder stays as a safety net). See Migration notes at the bottom if you're coming from a pre-rename build.

---

Screenshots

A quick tour of the desktop app. Every page below is the macOS Electron build in dark mode — the light theme mirrors the same layouts.

Home — dashboard and quick access

Greets you with overdue counts, open to-dos and today's schedule. Stat cards for teams, tasks and people; quick-access tiles to Agenda, To-dos, Teams and Notes. The top bar carries a global search pill with a ⌘ K / Ctrl K shortcut badge — clicking it (or pressing the shortcut) opens the command palette that fuzzy-searches across navigation targets, teams, people, items, to-dos and notes (titles + content).

To-dos — Kanban-shaped status, Markdown details, drag-reorder

Each row carries a status: To do · In progress · Done · Cancelled. Active · Archived segment for tasks and lists. Filter by status, sort by Manual / Priority / Due date / Status (Kanban order), and drag rows by the grip handle to reorder manually. Every task can carry optional Markdown details. Recurring reminders fire as desktop notifications.

Notes — resizable sidebar, sort modes, Markdown toolbar

Two-pane macOS-Notes-style view with Active · Archived in the sidebar. Drag the divider to resize (220–560 px). Five sort modes plus drag-reorder inside the pinned tier. Notes open in Preview by default; switching to Write reveals a full Markdown formatting toolbar. Optional per-note passphrase lockbox.

Agenda — Today / This week / Overdue

One unified view of every reminder, due task and personal to-do for the next seven days, plus an Overdue bucket up top.

Planning — Eisenhower matrix for personal tasks

Drag tasks from your personal to-do lists into Do first, Schedule, Delegate, or Eliminate. Pin up to three for today's focus strip. The matrix is a planning view — tasks stay linked to their original lists.

Settings — grouped by relationship: security, data, integrations, about

Cards are organised into named groups: Account & security (stay signed in, recovery codes, PIN), Data & backup (one Export / Import backup, daily backup folder, rolling snapshots), Integrations (AI assistant and OS notifications) and About (user guide, version, auto-update).

---

What's in the box

For your daily ritual

📝 Notes	macOS-Notes-style two-pane view, resizable sidebar (220–560 px), always-editable rich-text surface (no Preview/Edit toggle) with formatting toolbar (B / I / S / H1–H3 / lists / link / inline code / code block / divider, with ⌘B / ⌘I / ⌘K shortcuts). Double-click images to enlarge; ⌘/Ctrl+click links to open. Five sort modes plus drag-to-reorder inside the pinned tier. Active | Archived segment to shelve notes without deleting. Optional per-note passphrase lockbox.
✅ To-dos	Lists grouped by project, each with its own priority (Urgent / High / Normal / Low) and per-row status (To do / In progress / Done / Cancelled). Optional Markdown details per task (Notes-grade editor). Sort by Manual / Priority / Due date / Status (Kanban order). Filter by status. Active | Archived for tasks and lists. Drag items between groups and within. Recurring reminders (daily / weekly / monthly) fire as desktop notifications. Hide / show closed, archive, search (title and details), bulk ops.
📅 Agenda	Unified Today / This-week / Overdue view combining reminders + due tasks + personal to-dos. Lives offline; never asks for calendar permission.
🎯 Planning	Personal Eisenhower matrix — drag tasks into Do first / Schedule / Delegate / Eliminate by urgency and importance.
👥 Teams + People	Group people into teams, give each a private scratchpad and a running agenda. 1:1 mode with a persistent markdown meeting agenda + archive of past meetings; unchecked items carry over. Person Timeline for review prep.
🔎 ⌘K command palette	Global search across notes, tasks, items, people and navigation targets. Indexes body text (not just titles), highlights matches with contextual snippets, deep-links straight to the result. Locked notes searchable by title only. Archived notes excluded from search.
📊 Analytics	Local-only dashboard: completion rate, daily / weekly / monthly / yearly created-vs-completed SVG chart, per-team performance bars, top-contributors table. Activity report tab for a chronological change log.
🧰 Utilities	Sidebar Document (rich-text, autosaved) and (CodeMirror: format, fold, Diff, compact/stringify). Plus — ephemeral encode/hash/text/time/codegen, lite ERD, and Excalidraw-style sketch. Tool inputs are session-only and never touch the workspace file.

Powered by your device

🔒 Encrypted at rest	AES-256-GCM data file keyed via scrypt(password). Notes get an additional PBKDF2 → AES-256-GCM lockbox with a non-extractable CryptoKey.
🔑 Stay signed in (opt-out)	After your first login, Cadence wraps the data-encryption key with Electron's safeStorage and persists it in your OS keychain (macOS Keychain / Windows DPAPI / Linux libsecret). Restarts skip the password prompt; Logout always purges the cached key, and Settings → Stay signed in gives you a one-click "ask on every launch" toggle. On Linux without libsecret we refuse to cache rather than fall back to a hardcoded-obfuscation key — same security promise on every platform.
🛟 Durable saves	Atomic open → write → fsync → close → rename cycle plus directory fsync. A power loss or kernel panic leaves either the old file or the new file — never a torn one. Worst case: ≤ 400 ms of unflushed typing.
🗂️ Auto-backups	50 rolling snapshots in backups/<userId>/ (labelled launch / post-login / pre-save / pre-pwchange / pre-restore) with a one-click in-app restore. Each snapshot shows teams / lists / tasks / notes counts; Reveal in Finder for manual inspection. Refuse-to-overwrite guard if the live file is undecipherable. Settings → Backup & recovery merges manual export/import and snapshot restore in one place — one Export backup and one Import backup (a single .zip with notes, tasks, images and — on desktop — note history; import shows what is inside and lets you add or replace), with folder and text-only JSON under Advanced.
🔐 Recovery codes	Optional MetaMask-style codes to reset your account password on this device without data loss. Generate at sign-up or in Settings; use /recover if you forget your password. Existing accounts without codes behave exactly as before.
📦 Workspace storage	Desktop app splits large workspaces into monthly files for efficiency while keeping a full copy in the base file for downgrade safety. Settings → Storage & cache shows a per-area size breakdown (notes, tasks, teams, archives).
🛡️

AI when you want it

🪶 Task extractor	Drop a wall of meeting notes / brain dump → get a clean ordered task list back, ready to file into any project group.
🧭 Coaching on a task	One-line reframing + three concrete next actions ordered by leverage + one risk to avoid. Always under 200 words.
🗺️ Visualize	Select text → a Mermaid flowchart, sequence or state diagram, checked with Mermaid's own parser before it is offered, inserted as a new block.
🔍 Challenge my idea	Assumptions, risks, alternatives and open questions about a note, added as a separate block at the end.
🪜 Break down	Split a task into editable steps: a checklist in its details, or new tasks in the same list.
🧮 Classify with AI	Suggest important / urgent for unsorted tasks on the Planning matrix; undoable.
🧩 Document, mock data and ER diagram	A structured copy of a document (outline, RFC, meeting summary or table, then drawn as Mermaid or Sketch), invented records shaped like your sample, and additive table suggestions; each lands as a new tab or only adds.
✏️ Sketch and screenshot → Mermaid	Convert a sketch's labels and arrows, or a picture of a diagram, into Mermaid (or an HTML mock-up) as a new note.
✏️ Draw from a description	Describe a diagram in words; get a Mermaid note or a Sketch board, then ask for changes. Added as new; nothing existing is touched.
📅 Weekly digest	A retrospective or an upward status update from titles and counts of your week; streams in as it is written.
🤝 Prepare a 1:1	Follow-ups, open goals, feedback and questions from one person's records; people data.
🔎 Ask your workspace	Answers from your own notes and tasks with [n] citations and links; optional search by meaning.
🧱 Feedback → SBI	Rewrite feedback as Situation / Behavior / Impact using only what you wrote; people data, so only to connections you allow.
🎛️ Three providers, one switch	Anthropic Claude, OpenAI ChatGPT, Google Gemini. One dropdown to swap.

Distribution

🖥️ macOS desktop	Universal signed + notarized DMG (Apple Silicon + Intel). Auto-updates via GitHub Releases with an in-app progress dialog. Optional PIN lock at launch with rate-limited account-password recovery.
📱 PWA	Installable on iOS / Android / desktop browsers. Slide-in drawer sidebar, full-screen content, iOS safe-area aware. Offline-capable. Data lives in the browser's storage on that device.
🐧 Windows / Linux	Code is fully cross-platform — encryption + backup + auto-update behave identically. No CI binaries yet; build locally when you need one.

---

Table of contents

For users

• Health check & roadmap — living scores, phased backlog, QA checklists
• User guide — daily use, archive, backups, recovery codes, storage (also in-app at /guide)
• Why Cadence
• Screenshots
• What's in the box
• Install
• Getting started
• Concepts
• Power features (notes, to-dos, AI, backups, device sync, …)
• Mobile / PWA
• Keyboard & native menus
• Data, privacy and backups
  • Importing a big batch of notes (or todos) safely
• Auto-updates

For developers

• Building from source
• Releasing
• macOS code signing & notarization
• Project structure
• Electron deep dive
• Troubleshooting
• Roadmap
• Contributing
• Migration notes (from Leeadman)
• License

---

Install

macOS desktop (signed + notarized)

1. Go to the latest release.
2. Download Cadence-<version>-universal.dmg. This is a universal binary that runs natively on both Apple Silicon (M1/M2/M3/M4) and Intel Macs — one file for everyone.
3. Open the DMG and drag Cadence.app into Applications.
4. Launch from Launchpad or Spotlight (⌘ + Space → "Cadence").

Because the DMG is signed with a Developer ID Application certificate and notarized by Apple, you will not see any "damaged" or "unidentified developer" warning.

Mobile (PWA on iOS / Android)

1. On your phone, open https://sercancelenk.github.io/cadence/ in Safari (iOS) or Chrome (Android).
2. iOS: tap the Share button → Add to Home Screen. Android: tap ⋮ → Install app.
3. Launch from the home-screen icon. The app opens full-screen and jumps straight to the To-dos page.

Mobile data is separate by default. The PWA stores its own data in the phone's localStorage (independent of the desktop's encrypted file). To move data between devices move a portable backup file across (Settings → Backup → Export, then Import / merge on the other device).

Unsigned local builds

If you build a DMG yourself without code signing, macOS quarantines it ("… is damaged"). Bypass once with:

xattr -dr com.apple.quarantine /Applications/Cadence.app

The official Releases DMG never needs this.

---

Getting started

1. Launch Cadence.
2. Click Create one under the sign-in card. Pick an email, display name and a password (8+ chars). The account exists only on this device.
3. A three-card welcome tour appears on first launch — it explains the workspace, the two optional sync paths (LAN / Drive) and where to go for AI key + sync setup. Hit Skip if you already know what you're doing; Get started if you want the orientation. Cadence remembers you've seen it (localStorage["cadence.tour.completed.v1"]) and won't show it again on this device. Returning devices (anything with an existing LAN pair or Drive tokens) skip the tour automatically.
4. You land on the Home screen. From there you can:
   • Open the auto-created My first team.
   • Create new teams from the Teams page.
   • Manage personal lists in To-dos.
   • See everything due today/this week in Agenda.
5. Press ⌘ K (or Ctrl K) anywhere to jump to people, items or pages instantly.

Tip: install Cadence on a second machine and use Settings → Backup → Export JSON / Import JSON to move your data.

---

Concepts

Account
└── App data file (JSON)
    ├── Utilities (Document scratch pad, JSON/YAML editor)
    └── Teams[]
        ├── Me              (auto-created per team)
        ├── My leader       (auto-created per team)
        └── People[]
            ├── Profile + scratchpad (markdown)
            ├── 1:1 agenda (markdown, archivable)
            └── Items[]
                ├── Task          (due date, reminders)
                ├── Goal          (status, start, deadline)
                ├── Note          (markdown body)
                ├── Feedback      (praise / coaching / concern)
                └── Document      (URL)

Personal
└── To-do lists (pin, archive, search, bulk ops)

• Account — local user; password is stored as a salted scrypt hash.
• Team — a workspace boundary. Mark teams as Active / Paused / Archived and pin favourites.
• Me — your personal space inside a team.
• My leader — a dedicated workspace for the relationship with your manager.
• People — direct reports / peers; each one has a profile, scratchpad, 1:1 agenda and items.
• Items — task, goal, note, feedback, document. All can carry markdown body and reminders.
• To-dos — personal lists, fully decoupled from teams.

The complete data model is in src/model.ts.

---

Power features

⌘K command palette

The top bar carries a global search pill ("Search teams, notes, tasks…") sitting next to the team-switcher — click it, focus it with /, or press ⌘ K (macOS) / Ctrl K (Windows / Linux) and the same palette opens. The button is both an entry point and a visual reminder of the keyboard shortcut (the trailing ⌘ K / Ctrl K badge auto-adapts to the platform).

The palette searches across:

• Navigate — Home, Teams, To-dos, Agenda, Notes, Profile, Settings.
• Teams — jump straight to any team or its People page.
• People — every person across every team.
• Items — every task / goal / note / feedback / document by title.
• To-dos — every personal task.
• Notes — every standalone note. Locked notes are searched by title only (we never decrypt bodies through the palette, and the title row carries a 🔒 + Locked hint so you know what you're clicking on).

Picking a Notes hit navigates to /notes?id=<id>; the page selects that note on mount and immediately strips the query string from the URL so a refresh doesn't keep fighting your manual navigation.

Arrow keys to move, Enter to open, Esc to close.

Markdown editing

Notes, personal to-do details, team-item bodies, person scratchpads and 1:1 agendas all use GitHub-flavored markdown with a Write / Preview toggle:

• Headings, bold/italic, lists, blockquotes, code blocks.
• Checklists (- [ ] / - [x]).
• Tables, autolinks, strikethrough.
• External links open in your default browser.

In Write mode the editor now also shows a formatting toolbar that operates on the current textarea selection (and falls back to a placeholder when nothing is selected, so the user can immediately type to replace it):

Button	What it does	Shortcut
B	Wraps selection in **…** (bold)	⌘ B / Ctrl B
I	Wraps selection in *…* (italic)	⌘ I / Ctrl I
S	Wraps in ~~…~~ (strikethrough)	—
H ▾	H1 / H2 / H3 — prepends #, ##, ### to every line in the selection	—
• / 1. / ☐	Prepends - , 1. , or - [ ] to every line	—
🔗	Inserts [selection](https://) and parks the caret over the URL placeholder	⌘ K when the textarea is focused
</>	Wraps in single backticks (inline code)	—
{ }	Inserts a fenced ```code block``` around the selection (smart-aware of line boundaries)	—
—	Inserts a --- horizontal divider	—

The toolbar is line-aware (lists and headings always operate on whole lines, never mid-word) and focus-preserving (the caret lands inside the new markup so you can keep typing without picking up the mouse again).

Person Timeline

Every person page has a Timeline tab that shows a chronological feed of every item attached to that person — tasks, goals, notes, feedback, documents — grouped by day (Today / Yesterday / Friday / …) and filterable by kind. Designed for review prep ("what happened with Alice in Q3?").

1:1 Mode

Every person also has a 1:1 Mode tab with two halves:

1. Current agenda — a persistent markdown document seeded with sections (Wins / Blockers / Action items / Notes). Use - [ ] for action items.
2. Past meetings — when you click Archive meeting, the current agenda becomes a dated note (1:1 · 15 May 2026) attached to that person, and the agenda resets. Any unchecked action items are carried over into the new agenda automatically.

The archived meetings are regular notes, so they also show up in the Person Timeline.

Agenda

The /agenda page is a global, unified view of:

• Overdue — anything past its due date / reminder still open.
• Today — always shown, even when empty.
• The next 6 days — only shown when they have entries.

It mixes team-item reminders + due dates with personal to-do dues, marks each entry with its origin team / person, and lets you mark-complete or jump to its workspace inline.

Analytics dashboard

The /analytics page is a fully local, dependency-free dashboard that reads straight from your workspace data:

• Stat cards — total / completed / open / overdue / completion rate.
• Created vs completed SVG bar chart with a Daily / Weekly / Monthly / Yearly toggle.
• Per-team performance — totals, completed, overdue and a completion-rate progress bar per team.
• Top contributors — top 10 people by completed-task count, with their team affiliation.
• Personal to-dos — a separate stat block for /todos items.

Nothing is sent off-device; the chart is rendered as inline SVG.

Utilities

Sidebar Utilities — workspace tools that are not notes, todos, or team items:

• Document (/utilities/document) — a standalone rich-text scratch pad with the same always-edit chrome as notes (sticky toolbar, autosave indicator). Persisted as utilityDocument in your workspace JSON.
• JSON / YAML (/utilities/structured) — a lazy-loaded CodeMirror editor for config and payload review:
  • Edit — paste JSON or YAML, fold nested blocks, format (pretty-print), validate inline, copy, undo/redo.
  • Diff — compare Before and After buffers side-by-side with merge highlighting (autosaved as content + diffContent).
  • JSON-only — Compact (single-line minify) and Stringify (escape as a JSON string literal for env vars / nested fields). Format unwraps stringified JSON back to a readable object.

Both utilities autosave to your encrypted workspace file like everything else.

Recurring reminders

Any item reminder can be made daily / weekly / monthly. When the reminder fires, the next occurrence is computed and assigned automatically — you never have to recreate weekly 1:1 reminders.

Feedback log

Every person has a dedicated Feedback log alongside Tasks/Goals/Notes/Documents. Each entry is tagged with one of:

• Praise (green)
• Coaching (blue)
• Concern (red)

This makes performance-review prep and growth-conversation prep trivial — open the person's Timeline, filter to Feedback, and you have your talking points.

Smart to-do lists

The /todos page scales as your lists grow:

• Drag-and-drop reorder, lists and items — grab the grip handle next to a list title and drop it anywhere; dropping a list across the pinned/unpinned line toggles its pin state automatically. Inside a list, drag individual items by their handle to reorder them.
• Priorities — every list and every item has an optional priority chip (Urgent / High / Normal / Low). Use the Sort dropdown (Manual / By priority / By due date) to reshape the list on the fly without losing your manual order.
• Hide / show completed — toggle at the top of the page; persists per-device so you can keep a clean active view by default.
• Delete confirmation — clicking the trash icon arms the row for 3 seconds and turns into a confirm button, so a finger-slip doesn't lose a task.
• Multi-line task input — task title is a proper auto-resizing textarea (Enter inserts a newline, ⌘ / Ctrl + Enter submits). Edit an existing task title the same way.
• Markdown details (optional) — every task can carry a long-form body: click Add details in the new-task form, or the 📝 toggle on any row. The editor is the same component as Notes (Write / Preview tabs, formatting toolbar, GFM checklists / tables / links). Existing tasks with a body open in Preview by default; closing the panel commits on blur.
• Quick scheduling — every task row has a Schedule chip that opens a popover with Today 5pm, Tomorrow 9am, +3h, Next Mon 9am presets, plus a custom datetime picker and a one-tap "Clear schedule" action.
• Pin to top / Archive — star a list to keep it above the rest, or archive it (toggle "Show archived" to bring them back). If every list in a workspace is archived, the page shows an explicit amber alert ("your data is safe — N items inside archived lists") instead of looking empty; the sidebar badge turns amber too.
• Compact / Comfortable toggle — clearly labelled in the top-right.
• Mark all complete / Clear completed — bulk operations with confirmations.
• Search — filter tasks across all lists in real time; matches title and Markdown details, not just the one-liner.
• Inline rename — click the list title to edit.
• Counts — every list shows <open> / <total> at a glance.

AI Assistant (BYO API key)

Every task row has an Ask AI button as soon as you connect a provider in Settings → AI Assistant. The assistant takes the task title + optional Markdown details and returns a structured next-action plan, rendered as Markdown in a side dialog.

• Bring your own key — pick a provider, paste your API key, optionally override the model name. There is no proxy; calls go from this device straight to the provider you chose. The provider sees your task title/body but not your other data.
• Providers supported
  • Anthropic Claude — default claude-sonnet-5-5. Suggested: claude-sonnet-5-5, claude-haiku-5-5, claude-opus-5-5.
  • OpenAI ChatGPT — default gpt-5.4-mini. Suggested: gpt-5.4-mini, gpt-5.5, gpt-5.6. (gpt-4o-mini, gpt-4o and gpt-4.1-mini have an announced shutdown on 2027-01-14.)
  • Google Gemini — default gemini-3.8-flash. Suggested: gemini-3.8-flash, gemini-3.6-flash, gemini-3.5-flash-lite, gemini-3.1-flash-lite. (Gemini 1.x and gemini-2.0-flash are retired and return HTTP 404; the Settings UI surfaces a one-click fix.)
  • Custom gateway — your own router or proxy (OmniRoute, LiteLLM, Ollama, a company gateway). Enter its base URL, the model name and (if needed) an API key, then pick the API format it speaks: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages or Google Gemini. Advanced lets you set the auth header, how the key is written, extra headers and the request path. On desktop the request is made by the app itself (no CORS needed); plain http:// is accepted only for localhost and private-network addresses. Failures offer copyable diagnostic details with secrets hidden.
• Test connection button — sends a one-token round-trip so you can verify the key + model before relying on it during a real task.
• Follow-up turns — keep chatting in the dialog (Enter sends, Shift+Enter for newlines). Markdown answers render with headings, lists, code blocks and tables.
• Append to task — copy the assistant's answer straight into the task's Markdown details so it sticks around.
• Extract tasks from notes — open To-dos → Extract from notes and paste a brain dump (meeting transcript, voice-memo, Slack thread, weekend wishlist). The assistant returns a structured list with one imperative task per line and a suggested priority. You edit titles inline, pick which list each task goes into, and click Add (per row) or to drop them into your workspace. Nothing is added automatically — the user is always the final filter. The prompt is constrained to return strict JSON so the picker stays predictable across providers.

Beyond Ask AI and Extract tasks there are Visualize (text → Mermaid diagram), Challenge my idea, Break down (a task into steps), Feedback → SBI, Classify with AI, document / mock-data / ER-diagram helpers, Convert to Mermaid (sketch), Diagram from a screenshot, Weekly digest, Prepare a 1:1 and Ask your workspace; each previews its result and writes nothing until you press its button (see docs/AI-INTEGRATION.md). JSON, ZIP and full-backup exports leave out your AI keys.

The provider-agnostic transport layer lives in src/lib/ai.ts. Connection details and limits: docs/AI-INTEGRATION.md. The design behind these features and what was left out on purpose: AI features: foundation and roadmap.

Backups & recovery

Settings → Backups & recovery is your safety net when something goes sideways — for example after a major version upgrade, a password rotation hiccup, or registering a fresh account by mistake.

• Auto-snapshots — every save, every successful sign-in and every app launch copies the current cadence-data-<userId>.json into backups/<userId>/data-<label>-<timestamp>.json. A rolling window of 50 snapshots is kept; oldest are pruned automatically (~115 KB for a typical workspace — disk use stays bounded).
• Refuse-to-overwrite guard — the data writer refuses to overwrite an existing file when it can't decrypt it with the current session key (instead of silently destroying it). The renderer surfaces this as a red banner pointing at this page.
• Boot-time integrity check — after every successful save, Cadence remembers a coarse fingerprint (teams / tasks / notes counts) in localStorage. On the next launch, if the loaded file is meaningfully smaller than that marker, an amber Looks like data may be missing banner appears app-wide with exact before/after numbers and a one-click jump here. Dismissing rebases the marker to the current state.
• Recovery list — the page enumerates every candidate source on this machine:
  • Current data file (live)
  • Legacy single-user file (leeadman-data.json, from the pre-accounts era — also picked up by the one-shot rename migration)
  • Automatic snapshots (with human-readable "5m ago / 2d ago" times)
  • Other accounts on this machine — orphaned cadence-data-<otherId>.json files (or pre-rename leeadman-data-<otherId>.json files left behind), useful when you registered twice
• Each row shows the file size, modified time, encryption status, and what's inside: teams, lists (with archived count), tasks, notes (with locked count). Rows flag common "looks empty but isn't" cases — e.g. all todo lists archived or an orphan notes-lock with no locked notes — so you can pick a healthier snapshot before restoring.
• Reveal opens the snapshot in Finder / Explorer for manual diffing (jq, a text editor, etc.).
• Restore is one click and reports what you got back (e.g. Loaded: 1 team, 5 tasks, 2 notes). The current state is itself snapshotted as pre-restore first, so the operation is reversible.
• Auto-migrate on login — if you log in and your per-user data file doesn't exist yet, but the legacy single-user file (leeadman-data.json from pre-accounts builds) does, Cadence imports it into your account automatically. No more "I updated and my old data is gone" surprise.

Existing users: recovery codes, ZIP backups, and note history are optional add-ons. Old JSON and folder backups import exactly as before; no forced migration.

Storage & cache

Settings → Storage & cache is the honest, read-only picture of what Cadence occupies on this device — plus a safe way to reclaim disk when the browser engine has cached a lot of HTTP responses, V8 code or GPU shaders over months of use.

• Per-bucket sizes: encrypted data file, legacy file, your backups, backups belonging to other accounts on the same machine, Chromium-managed caches (HTTP / code / GPU / shader, with a per-folder breakdown), total userData size.
• Clear browser caches (Electron) — wipes only Chromium-managed caches via the documented session.clearCache() / clearCodeCaches() / clearStorageData({ storages: ['cachestorage', 'shadercache'] }) APIs. Tasks, notes, AI keys, backups and account list are never touched. Caches repopulate naturally; you may see a one-time slower first request or a shader recompile on next launch.
• Reload web assets (PWA) — unregisters the service worker and clears the caches API entries on this origin, then hard-reloads. Use this if the PWA feels stuck on an older version; your localStorage (AI key, UI prefs, hashed account credentials) is preserved.

This panel is purely diagnostic — you can ignore it forever and nothing degrades. The auto-prune logic already keeps backups at 50 slots and Chromium self-manages its caches; the buttons exist so you have the option, not as a maintenance chore.

Notes (encrypted at rest)

/notes is a macOS-Notes-style two-pane view for free-form personal notes that don't belong to a team or a person:

• Resizable sidebar. Drag the thin vertical divider between the sidebar and the editor pane to size it to taste (Pointer Events under the hood, so it works with mouse, touch and pen). Bounded to 220–560 px so it never collapses to a useless slit or swallows the editor.
• Sortable list. A compact dropdown at the top of the sidebar offers five modes — Last updated (default), Last opened, Created, Title (A→Z) and Manual. Pinned notes always float to the top regardless of mode; the active mode controls the order within each pinned tier.
• Manual drag-to-reorder. Switch to Manual sort and each row grows a grip handle on the left — drag any row up or down to drop it into its new slot (a blue indicator paints the drop position). The reorder rewrites sortOrder only within the pinned tier the row belongs to, so you can never accidentally cross the pin boundary.
• Editor. A Markdown editor with edit/preview tabs (same renderer as person scratchpads and 1:1 agendas), now opening in Preview mode by default — reading is the common case, click Write to flip into the textarea + formatting toolbar (see Markdown editing). Title is a plain inline input; the body autosaves on every keystroke through the same debounced writer your tasks use.
• Last-opened tracking. Selecting a note stamps an internal lastOpenedAt timestamp that powers the "Last opened" sort mode. The stamp explicitly does not bump updatedAt, so opening a note never bubbles it up in the "Last updated" view.
• Pin / Delete — pin keeps a note at the top of the list; delete asks for explicit confirmation (locked notes get a louder warning because losing ciphertext is unrecoverable).

Per-note lock with workspace master key. Click the lock button on any note and you'll be prompted, once, to set a Notes passphrase (≥ 6 chars). From then on:

1. One-time key derivation. When you enter the passphrase, Cadence runs PBKDF2-SHA-256 (200,000 iterations) against a workspace salt (stored in AppData.notesLock) to derive a 256-bit master AES-GCM key. The key is created with extractable: false, so its raw bytes can't be retrieved even from JavaScript — only encrypt and decrypt calls work.
2. The passphrase string is discarded. Only the CryptoKey lives in renderer memory for the rest of the session. A memory dump won't yield the passphrase. The pending-input fields in the dialog are cleared as soon as derivation succeeds.
3. Locking a note encrypts its body with the cached master key and a fresh random 12-byte IV per save. Re-encryption is a single AES-GCM block (sub-millisecond) so we can safely re-encrypt on every keystroke while you're editing a locked note — the cipher blob on disk is always current.
4. Unlocking a note decrypts the same way. The unlock dialog checks the verifier blob first (it tries to decrypt a known constant "leeadman-notes-v2") — so a wrong passphrase is rejected before we touch a real note.
5. Out-of-order encrypt protection. A monotonic generation counter discards any encrypt result whose keystroke has already been superseded, so two near-simultaneous typings can't cause the older text to overwrite the newer ciphertext.
6. Session lifetime. The master key is wiped automatically by logging out, locking the app with PIN, or restarting — the NotesUnlockProvider lives below AuthGate and unmounts in any of those cases.

Remove the passphrase. A dedicated Remove notes passphrase button (padlock-with-slash icon) in the Notes sidebar header always prompts you to re-enter the Notes passphrase before showing the destructive confirm dialog — even if the session master key is still cached in memory from an earlier unlock this session. Once you've re-authenticated and confirmed, Cadence decrypts every locked note up-front with the current master key; if any note fails (master key mismatch) it aborts the whole operation and leaves your data untouched. On success it converts every locked note back to plaintext and clears AppData.notesLock in one atomic save.

Strict per-view unlocking. Clicking Unlock to view on a locked note always opens the passphrase prompt, even if you unlocked the same note (or another locked note) a minute ago in the same session. Navigating away from a viewed locked note clears its in-memory plaintext, and the next view request drops the cached session key and re-prompts — so locking a note actually keeps it hidden every time you come back to it, not just until you next clicked the unlock button. Editing a note that's currently visible still uses the in-memory key (so each keystroke isn't gated on a prompt), but the moment you leave the note the strict-prompt rule re-engages.

What's stored where:

Thing	Plain on disk?
Locked note's body	No — only { ivB64, cipherB64 }
Locked note's title, pin, timestamps	Yes (intentional — you can still find notes without unlocking)
Workspace verifier	Yes ({ saltB64, verifierIvB64, verifierCipherB64 }, no key material)
Notes passphrase	Never
Workspace master key	Renderer memory only, non-extractable, dropped on logout/lock/restart

No reset path on purpose. Because the passphrase is never written down, anyone who steals your data file (including future-you with backups) cannot derive it. If you forget the passphrase your locked notes are unreadable forever. That's the trade we make for honest at-rest encryption; if you want recoverability instead, just don't lock the note.

Profile & change password

/profile is a card-first, view-by-default page:

• Avatar — upload any image; it's downscaled to 384 px and stored as a JPEG data: URL on your profile, so it shows up in the top-bar avatar everywhere.
• View mode — name, role, department, phone, email and bio rendered as a read-only grid; an Edit button (top-right) flips the same card into form mode with a Save / Cancel pair.
• Change password — a secondary tab that asks for Current password, New password and Confirm. On Electron the new password is also used to re-encrypt your data file in a single atomic swap; the old key is wiped from memory immediately.

Move data between devices (offline, no cloud)

Companion guide: For the recommended one user, desktop + phone workflow, troubleshooting, and golden rules, see docs/LAN-SYNC.md.

When you don't want any cloud service involved, Cadence moves a workspace between devices with a portable backup file (plain ZIP, not encrypted — keep it private) — no network connection between the devices is ever required:

1. On the source device, open Settings → Data & backup and choose Export backup (a .zip that bundles the workspace, image attachments and, on desktop, note version history; unencrypted).
2. Carry the file across by whatever means you already trust — AirDrop, Files, a USB stick, a private chat to yourself.
3. On the target device, open Settings → Data & backup, choose Import backup, look at what is inside, and pick Add to what's here (merge) or Replace what's here.

There are two distinct import modes, and the difference matters for data safety:

• Replace (restore a backup) overwrites the target workspace with the file's contents. Use this to restore a device from a known-good backup.
• Merge items from another device is additive and lossless: every item already on the target is kept verbatim, and only entities the target doesn't already have are appended. Re-importing the same file is a no-op (idempotent), and your local config — profile, AI settings, notes passphrase, active team — is never touched. This is the safe choice for "I made notes on my phone, fold them into my desktop."

The merge is implemented by mergeAppendWorkspace (src/core/model/mergeWorkspace.ts) and deduplicates by entity id first, then by a stable content signature, so the same logical note created independently on both devices doesn't import as a near-duplicate. Because there are no tombstones in the model, a merge can never delete anything — the documented trade-off is that re-importing an old file can resurrect an item you had deleted locally.

There is no sync service: Cadence is local-first, so a second device gets your data only when you carry a file across. Live LAN pairing and Google Drive sync were retired.

---

Mobile / PWA

Cadence ships as a Progressive Web App in addition to the desktop Electron build. The same React bundle is deployed to GitHub Pages and installable on iOS/Android.

Setup (repository owner — one-time)

1. Settings → Pages → Source: GitHub Actions.
2. Push to main. The pages.yml workflow runs, builds with CADENCE_PWA=1, and publishes to https://<user>.github.io/cadence/.

Install on your phone

1. Open the URL above in Safari (iOS) or Chrome (Android).
2. Share → Add to Home Screen / ⋮ → Install app.
3. The app installs with its own icon and launches full-screen, going straight to the To-dos page.

What works offline

• The app shell (HTML / CSS / JS / icons) is cached on first visit.
• All your data lives in the phone's localStorage, so reads and edits work fully offline.
• New deploys are picked up silently the next time the device is online (service worker uses network-first for navigation, stale-while-revalidate for hashed assets).

Building the PWA locally

# Regenerate icons after editing public/icon.svg
npm run icons

# Build for GitHub Pages (sets base path to /cadence/)
npm run build:pwa

Mobile-specific UX

• Slide-in drawer sidebar — on screens ≤700 px the sidebar starts hidden so the content gets the full viewport. Tap the hamburger to slide it in over a backdrop; tap any link or the backdrop to dismiss. Body scroll is locked while the drawer is open.
• No iOS auto-zoom — every input/select/textarea renders at ≥16 px on phones, so Safari doesn't zoom in on focus.
• Full-screen command palette on mobile.
• Single-column to-do row layout with 40 px touch targets and a wrapped section header.
• Launching from the home-screen shortcut auto-redirects / → /todos.
• iOS safe-area padding is honoured (status bar / home indicator).

Files added for PWA support

public/
  manifest.webmanifest      # PWA metadata
  sw.js                     # Service worker (offline cache, auto-update)
  icon.svg                  # Source vector logo
  icon-192.png              # Manifest icon (any)
  icon-512.png              # Manifest icon (any) + splash
  icon-maskable-512.png     # Adaptive icon for Android (safe-zone padded)
  apple-touch-icon.png      # 180×180 iOS home-screen icon
  favicon-32.png            # Browser tab icon
scripts/
  generate-pwa-icons.mjs    # sharp-powered icon rasteriser
src/pwa.ts                  # SW registration (skipped under Electron/file://)
.github/workflows/pages.yml # Automated Pages deploy

---

Keyboard & native menus

Cadence ships with a native menu bar (English):

• Cadence — About, Check for Updates…, Quit
• File — Close window / Quit
• Edit — Undo / Redo / Cut / Copy / Paste / Select All
• View — Reload, Zoom, Toggle Full Screen
• Window — Minimize, Zoom
• Help — Project on GitHub, Report an Issue

Standard shortcuts apply (⌘ Q, ⌘ W, ⌘ R, ⌘ F, ⌘ , …). The global ⌘ K opens the command palette from anywhere.

---

Data, privacy and backups

• Where data lives (macOS): ~/Library/Application Support/Cadence/. (Pre-rename installs originally wrote to ~/Library/Application Support/Leeadman/; that folder is consumed and converted on first launch — see Dev vs installed app data isolation.)
  • cadence-accounts.json — user list (email, salted scrypt password hash, per-user encSalt).
  • cadence-session.json — id of the signed-in user.
  • cadence-data-<userId>.json — your workspace data, per account, encrypted at rest (AI key, tasks + optional Markdown details per task, lists, people, notes, preferences — everything).
  • leeadman-data.json — legacy single-user file from pre-accounts versions (only present if you upgraded from an old install). Auto-imported on first login.
  • backups/<userId>/data-<label>-<timestamp>.json — rolling auto-snapshots (50 slots; labels include launch, post-login, pre-save, pre-pwchange, pre-restore).
  • auth-lock.json — optional PIN hash.
• Encryption-at-rest (Electron): your data file is wrapped in AES-256-GCM. The 256-bit key is derived from your password with scrypt(password, encSalt) at login and lives only in main-process memory until logout. Changing your password atomically decrypts with the old key, derives a fresh encSalt, and re-encrypts under the new key. Legacy plaintext files from older versions are upgraded silently on the first save after login.
• Refuse-to-overwrite guard: when the data writer finds an existing file it can't decrypt with the in-memory key, it refuses to write — your data stays safe and the UI surfaces a banner pointing at Settings → Backups & recovery.
• PIN protection is an additional launch-time UI barrier (not the encryption key). It can be enabled/disabled independently in Settings. If you forget it, the lock screen has a "Forgot PIN? Reset with account password" flow (rate-limited).
• Mobile PWA: data lives in the browser's localStorage for the Pages origin and is not encrypted by the app — rely on the device's keychain / disk encryption.
• No telemetry, no analytics. Sync only happens when you explicitly use the LAN server (or Export/Import).

Durability guarantees (won't I lose data on a crash?)

The desktop build is engineered so a kernel panic, power loss or kill-9 cannot silently lose acknowledged writes:

• Atomic, fsync'ed writes. Every save opens a sibling .tmp file with an explicit open → write → fsync → close cycle, then atomically rename()s it over the live file, then fsyncs the containing directory. The bytes are on durable storage before saveData() returns. A crash mid-write leaves either the old file or the new file — never a torn half-write.
• Debounced + flushed-on-exit. Edits coalesce for 400 ms to avoid hammering the disk, but beforeunload / pagehide flush the pending payload synchronously. The worst case (an instant SIGKILL with a partial debounce timer) loses ≤ 400 ms of typing, never a committed save.
• Pre-save snapshots. Before every write, the current file is copied into backups/<userId>/data-pre-save-<timestamp>.json. So even a logic bug that writes garbage cannot destroy your previous state — the immediate prior version is one click away in Settings → Backups & recovery.
• Refuse-to-overwrite undecipherable data. If the live file exists but cannot be decrypted with the current session key (e.g. you signed in with the wrong password and somehow bypassed the prompt), the writer aborts and the UI shows a banner. You can't accidentally overwrite locked data with one character's worth of state.
• Global "autosave failed" banner. Any save failure — IPC error, refuse-to-overwrite, disk full — is surfaced as a red banner above every page, with a one-click link to Backups & recovery. There is no silent failure path.
• Boot-time integrity banner. After each successful save, a coarse fingerprint (teams / tasks / notes counts) is stored in localStorage. If the next launch loads a meaningfully smaller workspace, an amber banner spells out the before/after numbers and links to Backups & recovery — catching "everything disappeared" before you assume the worst (common when every todo list was archived, or after a bad session resume).
• Anonymous userData directory, not inside the app bundle. On macOS your data lives in ~/Library/Application Support/Cadence/, which is outside Cadence.app. Trashing the app does not delete your data. Reinstalling later picks the data right back up. The same is true on Linux (~/.config/cadence) and Windows (%APPDATA%\Cadence).
• Uninstall-safe backups. The rolling 50-snapshot history lives next to the live file inside userData/backups/<userId>/. As long as you don't manually delete , every save from the past N days is recoverable.

Belt-and-braces: keep an off-device copy

Atomic writes + 50 rolling snapshots survive crashes, bad updates and accidental in-app deletes. They do not survive a rm -rf ~/Library/Application Support/Cadence, a wiped SSD, a stolen laptop, or a misconfigured Time Machine.

For total peace of mind, periodically run Settings → Backup → Export JSON and copy the resulting cadence-backup-YYYY-MM-DD.json to iCloud Drive, Dropbox, a USB stick, or another machine. The export is a fully decrypted, version-tagged JSON dump — diff-friendly and migration-friendly. Importing it later restores everything (and snapshots the existing state to pre-restore first, so the import itself is reversible).

A monthly export is plenty for typical use; weekly if you treat the app as a primary system of record.

Importing a big batch of notes (or todos) safely

If you're moving everything from another app into Cadence in one sitting, the engine handles you (atomic writes, 50 pre-save snapshots, refuse-to- overwrite, autosave-failed banner) — but a few habits make the import itself more forgiving:

1. Take a "before" export first. Settings → Backup → Export JSON even on an empty workspace. That single file is your "I started here" anchor — if anything goes weird later you can diff against it.
2. Paste in moderate batches. Multi-line content pasted into the title field is auto-rescued (the first non-empty line becomes the title, the rest moves to the Markdown body) but each save consumes one of the 50 rolling snapshot slots. Dropping 200 notes in 30 seconds can age a previous snapshot off the back of the queue, so space large pastes out (or take an Export JSON between batches).
3. Don't lock notes until you've verified the passphrase. If you plan to enable the notes passphrase, write the passphrase down first — locked content can be recovered from a snapshot, but there's no recovery for the passphrase itself. (Optional recovery key in Settings → Notes lock is the supported fallback.)
4. Take an "after" export when you're done. A second cadence-backup-YYYY-MM-DD.json after the migration gives you a clean "known good" reference and is the file you'd hand to Import JSON if you ever need to fully redo a restore.
5. Watch the banners. Any save failure surfaces as a red autosave banner above every page, and a meaningful drop in totals between launches surfaces as an amber data-loss banner. Both link straight to Settings → Backups & recovery. Don't dismiss them without resolving — they are the single source of truth that something went wrong.

If you're migrating from a previous Leeadman install, see also Migration notes (from Leeadman) — the data-folder rename is consumed automatically on first launch.

---

Auto-updates

The packaged desktop app checks GitHub Releases on launch via electron-updater:

1. Reads latest-mac.yml from the latest release.
2. If the published version is higher than the installed one, downloads the new build in the background.
3. Shows an OS notification when the download is ready ("Update available — restart to install"). Quit and relaunch to apply.

You can also force an interactive check from Settings → Auto updates → Check for updates. A dialog walks you through the full flow:

• Checking… spinner.
• If you're current: "You're on the latest version (July 2026)." with an OK button.
• If a newer release exists: progress bar with percent and MB transferred.
• When the download finishes: an Install & restart button — clicking it runs quitAndInstall so the app closes, swaps in the new binary, and relaunches without you having to manually quit. Later defers the install until next launch.
• On a network error the check auto-retries a few times with backoff, then shows a friendly "We couldn't reach the update server" message (technical details are tucked behind a disclosure) with a Try again button. The app keeps working normally and re-checks on the next launch.

You can also trigger the same check from the menu bar via Cadence → Check for Updates…. Development builds (npm run dev) short-circuit the check and the dialog shows a "disabled in development mode" notice.

Versioning

Releases use CalVer: the build carries a YYYY.M.<build> version (e.g. 2026.7.72) where the year is the semver major, the month (1–12) is the minor, and the CI run number is the patch. This is still valid, strictly-increasing semver, so electron-updater's comparison stays trivially correct — every new release is greater than any previous one (including the legacy 0.3.x line, since 2026 > 0), meaning clients on older versions always see it as an upgrade.

In the UI you just see the friendly label — "July 2026" — with the exact build string available in the tooltip and under Settings → Application version. The version is produced in CI by scripts/compute-version.mjs and formatted for display by src/lib/appVersionLabel.ts. Before publishing, scripts/validate-release-config.mjs --check-version checks the new version against the latest published release and aborts the release if it isn't strictly greater — a guard that makes it impossible to ship a build that would freeze auto-updates for existing users. If GitHub can't be reached the guard retries and then fails open (never blocking a legitimate release for a transient network blip).

The PWA "updates" itself silently via the service worker — the next time the device is online and you reopen the app, the new build is fetched and applied on the following navigation. Bumping CACHE_VERSION in public/sw.js invalidates every old cache.

---

For developers

Everything below this line is implementation-detail territory — how to build from source, the on-disk layout, release plumbing, the architecture deep-dive. If you're using Cadence rather than hacking on it, you can stop here and head to Install instead.

---

Building from source

Requirements

• Node.js 20+
• npm 10+
• macOS 12+ (only for producing a macOS DMG)

Install

git clone https://github.com/sercancelenk/cadence.git
cd cadence
npm install

Scripts

Script	What it does
npm run dev	Starts Vite at http://localhost:5173 and launches Electron pointed at it with hot reload. Runs in an isolated userData directory (~/Library/Application Support/Cadence (Dev)/ on macOS), so a dev session can never read, write or corrupt the data of the installed app — see Dev vs installed app data isolation.
npm run build:web	Builds the Electron-targeted React bundle (base: ./) into dist/.
npm run build:pwa	Builds the GitHub-Pages-targeted PWA bundle (base: /cadence/) into dist/.
npm run build	build:web + electron-builder (local desktop bundle).
npm run build:release	build:web + electron-builder --publish always (used by the release workflow).
npm run icons	Regenerates PWA icons from public/icon.svg (uses sharp).
npm run preview	Vite preview server for the last build.
npm test	Runs the Vitest unit + integration suite (87 tests today — snapshot crypto, sync algorithm, Drive backend with fetch mocked, OAuth token flow, LAN client primitives). Fast, no network, runs under jsdom.
npm run test:watch	Same suite in watch mode, for TDD-style iteration.
npm run check:env	Pre-deploy sanity check: Node version, required source files (README.md, PRIVACY.md, TERMS.md, .env.example), .gitignore safety (no .env leaks), and the shape of VITE_GOOGLE_OAUTH_CLIENT_ID. Returns non-zero if anything critical is wrong, useful as a release-pipeline gate.

Testing

# One-shot
npm test

# Watch (re-runs on file change)
npm run test:watch

The suite covers the parts of the codebase that have the highest blast radius if they regress:

• src/lib/snapshotCrypto.test.ts — round-trip encrypt/decrypt, wrong passphrase, tampering detection, unsupported-version branch.
• src/lib/syncSnapshotGuard.test.ts — parseRemoteSnapshot accepts every valid shape and refuses every invalid one (defends against an empty/garbled remote overwriting your local data).
• src/core/model/mergeWorkspace.test.ts — the additive "import items from another device" merge: additive-only, no overwrite, content dedupe, idempotency, singleton protection.
• src/lib/useSyncAutoSync.test.ts — the full sync state machine (first-time pull, first-time seed, dirty push, clean pull, not-modified, conflict, auth-required, corrupt-remote) against a scripted FakeBackend.
• src/lib/syncBackends/gdrive.test.ts — 19 integration scenarios against a fetch-mocked Drive (auth, pull-ok, no-snapshot, wrong-password, not-modified, file-create, file-update, conflict, 401, network-error, 5xx retry-loop, 413 too-large, status, disconnect).
• src/lib/syncBackends/gdriveAuth.test.ts — OAuth token persistence, silent refresh-on-expiry, signOut revoke, redirect broker handling, runtime client-ID override priority.

Everything runs under jsdom, so no real network and no Drive credentials are needed — CI runs the same suite on every push.

Local DMG without Apple credentials

CSC_IDENTITY_AUTO_DISCOVERY=false npm run build

Windows / Linux builds (experimental, not in CI)

GitHub Releases ship signed macOS DMG + ZIP only. The renderer and the Electron main process are platform-agnostic (atomic fsync'ed writes, scrypt + AES-256-GCM, Google Drive sync, auto-updater all work on Windows and Linux), but the project's electron-builder config and release workflow only target macOS by design — adding Windows code signing infrastructure and ongoing CI minutes isn't worth it until there's real demand.

If you want to run Cadence on Windows or Linux today, you can build locally:

Windows (portable .exe, unsigned) — fastest path; no installer, no SmartScreen reputation needed (still shows a "Windows protected your PC" warning the first time; click More info → Run anyway).

# Run on a Windows machine (or via Wine on macOS/Linux with electron-builder docs)
npm pkg set "build.win.target=portable"
npm run build
# Output: release/Cadence-<version>-portable.exe

Windows (NSIS installer, unsigned) — full Start-menu + uninstall integration.

npm pkg set "build.win.target=nsis"
npm pkg set "build.nsis.oneClick=false"
npm pkg set "build.nsis.allowToChangeInstallationDirectory=true"
npm run build
# Output: release/Cadence Setup <version>.exe

Linux (AppImage) — single executable file; works on most distros without root.

# Run on Linux (or macOS with Docker for cross-compile)
npm pkg set "build.linux.target=AppImage"
npm pkg set "build.linux.category=Office"
npm run build
# Output: release/Cadence-<version>.AppImage

Data lives in %APPDATA%\Cadence\ on Windows and ~/.config/cadence/ on Linux — app.getPath('userData') resolves per-OS automatically and the same encryption + backup rules apply.

When/if community demand justifies it, these targets will be promoted into the release workflow (with Azure Trusted Signing for Windows so SmartScreen stays quiet). Until then, treat the above as "build it yourself" instructions.

Dev vs installed app data isolation

If you've already installed Cadence from a DMG and you want to run the local checkout side-by-side to try out new features, the two builds could otherwise share the same on-disk data — Electron derives userData from app.getName(), and macOS APFS is case-insensitive, so two builds with the same display name resolve to the same directory. Running a dev build on prod data is risky because a dev build typically writes a newer on-disk schema than the installed version understands, which can silently strip new fields on the next save.

To prevent this, electron/main.cjs detects dev mode (the VITE_DEV_SERVER_URL env var that npm run dev sets) and routes everything through a separate folder:

Build	macOS userData
Installed DMG (production)	~/Library/Application Support/Cadence/
npm run dev	~/Library/Application Support/Cadence (Dev)/

One-shot migration from the pre-rename name

This project used to be called Leeadman. The very first launch after the rename detects a ~/Library/Application Support/Leeadman/ (or Leeadman (Dev)/ for dev) folder, copies its contents into the new Cadence/ (or Cadence (Dev)/) folder, and renames every leeadman-*.json to cadence-*.json on the way. The legacy folder is left in place untouched as a safety net — feel free to delete it manually once you've confirmed your data made it across. The migration is guarded by the presence of cadence-accounts.json in the new folder, so it never runs twice and never overwrites a workspace you've already started using under the new name.

Side effects you should know about:

• A brand-new dev session starts with no accounts, no tasks, no notes — you'll see the same "register an account" screen as a brand-new user.
• The single-instance lock keys off app.getName() too, so the installed app and a dev session can run at the same time. They'll appear as two separate apps in the Dock; both windows are functional.
• Auto-update is already gated by app.isPackaged, so the dev session never tries to update itself.
• To test on a copy of your real data, quit the installed app first (it writes on quit), then copy the file you care about:

  cp -R "~/Library/Application Support/Cadence/"* \
        "~/Library/Application Support/Cadence (Dev)/"
  

  This includes accounts, encrypted data files, backups and sync config. The dev session opens the next time you npm run dev.

New to Electron? Have a look at the Electron deep dive below — it explains the main / renderer / preload split, the IPC patterns we use and the build pipeline this command actually runs.

---

Releasing

Both the desktop release and the PWA deploy are manual, and nothing runs automatically on push or pull request. To publish, open the Actions tab and pick the workflow you want; CI runs first as a gate inside it.

Workflows at a glance

Workflow	Trigger	What it does
ci.yml	reusable (workflow_call) + manual (Run workflow)	npm run typecheck + npm test + npm run build:web. Invoked as the green-light gate by Release & Pages; you can also fire it on demand to sanity-check a branch.
pages.yml	manual (Run workflow)	Calls CI → npm run build:pwa → publishes to GitHub Pages.
release.yml	manual (Run workflow)	Calls CI → computes a CalVer version YYYY.M.<run_number> and guards it against the latest release (updater-safety) → electron-builder --publish always → signs + notarizes the .app → uploads DMG/ZIP/latest-mac.yml to a new GitHub Release.

Cutting a desktop release

1. Actions tab → Release → Run workflow (on main).
2. The reusable CI job runs first; if it goes red the macOS job is skipped, no DMG built, no Apple minutes burned.
3. On green, the macOS runner signs + notarizes + publishes. Once the release shows up on GitHub, every installed Cadence picks it up via electron-updater.

Updating the mobile PWA

1. Actions tab → Deploy PWA to GitHub Pages → Run workflow.
2. Same CI gate, then the PWA bundle is rebuilt and Pages is updated. The service worker CACHE_VERSION invalidation makes existing installs pull the new shell on next visit.

Required repository permissions: Settings → Actions → General → Workflow permissions = Read and write.

---

macOS code signing & notarization

For DMGs to open without the "… is damaged and can't be opened" Gatekeeper error on someone else's Mac, the build must be:

1. Signed with a Developer ID Application certificate from a paid Apple Developer Program account, and
2. Notarized by Apple's notarytool service.

This repo's release workflow does both automatically. You only need to set up the secrets once.

1. Create a Developer ID Application certificate

1. In Keychain Access, open Certificate Assistant → Request a Certificate From a Certificate Authority…. Save the CSR to disk.
2. In developer.apple.com → Certificates, click +, choose Developer ID Application under Software, then G2 Sub-CA (Xcode 11.4.1 or later).
3. Upload the CSR, download the resulting .cer, and double-click to install it into the login keychain.
4. In Keychain Access → My Certificates, verify that "Developer ID Application: <Your Name> (<TEAM_ID>)" appears with a private key under it.

2. Export the certificate as .p12

1. Right-click the certificate → Export… → format Personal Information Exchange (.p12).
2. Set a strong export password (this becomes CSC_KEY_PASSWORD below).
3. Save as developer-id.p12.

3. Create an App-Specific Password

1. Go to https://appleid.apple.com.
2. Sign-In and Security → App-Specific Passwords → +.
3. Save the generated xxxx-xxxx-xxxx-xxxx password.

4. Add GitHub repository secrets

In Settings → Secrets and variables → Actions, add:

Secret name	Value
CSC_LINK	base64 of developer-id.p12 — base64 -i developer-id.p12 | pbcopy
CSC_KEY_PASSWORD	.p12 export password
APPLE_ID	Apple Developer account email
APPLE_APP_SPECIFIC_PASSWORD	the xxxx-xxxx-xxxx-xxxx password
APPLE_TEAM_ID	10-character Team ID (e.g. ME5ER9CA9Q)

The Team ID is also configured in package.json under build.mac.notarize.teamId — update it there if you fork this project.

5. Verify locally

After installing a signed build:

codesign -dv --verbose=4 /Applications/Cadence.app
spctl -a -t exec -vv /Applications/Cadence.app
xcrun stapler validate /Applications/Cadence.app

spctl should respond with accepted source=Notarized Developer ID. If it does, every user can install your DMG without any warning.

Entitlements

The signed binary uses the entitlements at build/entitlements.mac.plist:

• com.apple.security.cs.allow-jit — required by V8 in Electron.
• com.apple.security.cs.allow-unsigned-executable-memory — JIT support.
• com.apple.security.cs.disable-library-validation — load Electron framework dylibs.
• com.apple.security.cs.allow-dyld-environment-variables — used by Electron's bootstrap.
• com.apple.security.network.client / server — outbound update checks and IPC.

---

Project structure

.
├── electron/
│   ├── main.cjs                    # Main process: window, menu, IPC, auth, CSP, updater
│   └── preload.cjs                 # contextBridge surface exposed as window.leeadman
├── src/
│   ├── App.tsx                     # Router + protected shells, PWA-launch redirect
│   ├── main.tsx                    # React entry; StrictMode + ErrorBoundary + SW
│   ├── pwa.ts                      # Service-worker registration (web build only)
│   ├── AccountContext.tsx          # Account sign-in/up state
│   ├── AuthContext.tsx             # PIN lock state
│   ├── AppDataContext.tsx          # Workspace data, debounce-save, reminder watcher
│   ├── ThemeContext.tsx            # Dark / light theme
│   ├── actions.ts                  # Pure reducers operating on AppData
│   ├── model.ts                    # Domain types + migrations + normalization
│   ├── components/
│   │   ├── AppSidebar.tsx
│   │   ├── CommandPalette.tsx      # ⌘K palette
│   │   ├── ErrorBoundary.tsx
│   │   ├── Layout.tsx / TeamLayout.tsx / TopBar.tsx
│   │   ├── icons.tsx
│   │   ├── AIAssistantDialog.tsx   # Markdown chat dialog for the per-task AI button
│   │   └── ui/
│   │       ├── Button.tsx
│   │       ├── AutoResizeTextarea.tsx  # Multi-line task input (auto-grow + submitMode)
│   │       └── MarkdownEditor.tsx  # GFM markdown editor + viewer
│   ├── lib/
│   │   ├── ai.ts                   # Provider-agnostic AI client (Anthropic / OpenAI / Gemini)
│   │   └── …                       # datetime, routes, sorting, categories, etc.
│   └── views/
│       ├── HomePage.tsx
│       ├── HomeTeams.tsx
│       ├── TodosPage.tsx           # Drag-drop lists + items, priorities, hide-completed, AI button
│       ├── AgendaPage.tsx          # Today / This-week unified agenda
│       ├── AnalyticsPage.tsx       # Local analytics dashboard (SVG charts)
│       ├── People.tsx              # Person workspace + Timeline + 1:1 Mode tabs
│       ├── ProfilePage.tsx         # Avatar, view/edit toggle, change-password tab
│       ├── Settings.tsx            # Theme, PIN, AI key, backups & recovery
│       └── LoginPage.tsx / RegisterPage.tsx
├── public/                         # PWA static assets (manifest, sw.js, icons)
├── docs/
│   ├── LAN-SYNC.md                 # Offline device-to-device transfer (portable backup + merge)
│   ├── HEALTH-CHECK-AND-ROADMAP.md # Living health score + phased roadmap
│   ├── electron-guide.md           # Practical Electron tutorial walking through this codebase
│   ├── DEPLOYMENT-AND-POLICY.md
│   └── ENTERPRISE.md
├── build/
│   └── entitlements.mac.plist
├── scripts/
│   ├── generate-pwa-icons.mjs      # sharp-powered icon rasteriser
│   └── patch-publish.mjs           # Rewrites build.publish.owner at build time
├── .github/workflows/
│   ├── ci.yml
│   ├── release.yml                 # macOS signed + notarized release pipeline
│   └── pages.yml                   # PWA → GitHub Pages
├── vite.config.ts                  # Env-aware base path (Electron vs Pages)
├── package.json
└── README.md

---

Electron deep dive

If you want to go beyond "build it and ship it" and actually understand how the desktop side of Cadence works under the hood, there's a dedicated guide that doubles as a hands-on Electron tutorial:

docs/electron-guide.md — a practical Electron tutorial walking through this codebase: the two-process model, the preload bridge, IPC patterns, the security checklist, AES-256-GCM encryption at rest, the auto-update flow, the build pipeline, debugging tips and the most common pitfalls.

It's written so a developer who has never touched Electron can read it top-to-bottom and end up confidently extending electron/main.cjs and electron/preload.cjs.

---

Troubleshooting

For official releases this should not happen — they are signed + notarized. If it does, the file was likely tampered with in transit; download again from the releases page. For DIY (unsigned) builds, run:

xattr -dr com.apple.quarantine /Applications/Cadence.app

That usually means the renderer crashed before painting. The ErrorBoundary should display the stack trace; please file an issue with that text. In development you can open DevTools with ⌘ ⌥ I.

You're offline or behind a captive portal. Auto-update will retry on next launch; nothing to fix.

The service worker uses network-first for navigation, so a second visit when online should fetch the new shell. If you want to force-refresh: from the installed PWA, pull-to-refresh or close-and-reopen the app. From a browser, hard-refresh and clear site data once.

Passwords are not recoverable (they're stored as salted scrypt hashes locally). You can edit cadence-accounts.json in ~/Library/Application Support/Cadence/ and remove the user entry, then sign up again. Your workspace JSON file is named cadence-data-<userId>.json — keep it if you want to import it into the new account.

The lock screen has a Forgot PIN? Reset with account password link. It asks for your account password (the one you sign in with), rate-limits attempts, and on success clears the PIN so you can set a new one. No terminal commands required.

Don't panic — your data is still on disk. Open Settings → Backups & recovery. The page lists every candidate source: the current file, the legacy single-user file (leeadman-data.json, from pre-accounts builds), every automatic snapshot (50 rolling slots labelled launch / post-login / pre-save / pre-pwchange / pre-restore), and any orphaned per-user file from a previous account UUID. Pick the one with the right item counts → Restore. The current state is itself snapshotted as pre-restore first, so the operation is reversible.

Google retired the Gemini 1.x family in late 2025 and gemini-2.0-flash / gemini-2.0-flash-lite on 2026-06-01. Open Settings → AI Assistant, click the inline gemini-3.8-flash suggestion (or any other current model from the list), Save, then run Test connection again. Google limits the 2.5 models to users who already use them, so use the 3.x models for anything new.

---

Roadmap

✅ Tier 1 — shipped

#	Feature
1.1	Markdown editor for notes, scratchpads, item bodies and 1:1 agendas
1.2	Feedback log (praise / coaching / concern item kind)
1.3	Recurring reminders (daily / weekly / monthly cadence)
1.4	Person Timeline — chronological feed per person, filterable by kind
1.5	Today / This-week unified Agenda page
1.6	1:1 Mode — persistent agenda + archive + carry-over
1.7	⌘K command palette + global search
1.8	Smart to-do list management (pin, archive, move, bulk ops, search)
1.9	Mobile PWA build + GitHub Pages deploy
1.10	AES-256-GCM encryption of the data file with key derived from password
1.11	Profile redesign — avatar upload, view/edit toggle, change-password with old-password verification
1.12	Drag-and-drop reordering for to-do lists (handle + drop targets)
1.13	Quick-schedule presets for tasks (Today / Tomorrow / +3h / Next Mon)
1.14	Analytics dashboard with SVG bar chart, per-team and per-person stats
1.15	LAN sync — Electron HTTP server with token auth + pair UI in Settings
1.16	Mobile drawer sidebar + iOS-safe input sizing
1.17	AI Assistant with BYO API key for Claude / ChatGPT / Gemini, per-task button, Markdown chat dialog, append-to-task
1.18	Backups & recovery — rolling 50-snapshot backups, refuse-to-overwrite guard, in-app recovery UI with one-click restore
1.19	Universal macOS DMG — single Apple-Silicon + Intel build, simpler distribution
1.20	Task priorities on lists and items + sort-by-priority / sort-by-due-date toggle
1.21	Item drag-reorder, hide / show completed, delete confirmation, multi-line task textarea

Tier 2 — next

#	Feature	Why it matters
2.1	Cycle / Quarter scope for goals + progress %	OKR support: parent/child (Objective → Key Result), quarter tagging, progress with history.
2.2	Templates (1:1, skip-level, perf review, onboarding)	Apply a template to a new note/meeting and get a structured outline instantly.
2.3	Person attributes	Start date, timezone, location, level, manager (dotted-line), pronouns, skills. Auto-computed tenure.
2.4	iCal (.ics) export	Read-only feed so macOS Calendar / Google Calendar can subscribe.
2.5	Field-level merge in sync (last-write-wins per item)	Today's Pull / Push replace the whole snapshot; per-item merge would let two devices edit in parallel — the ETag conflict guard already prevents data loss, this would prevent the conflict in the first place.

Tier 3 — nice to have

#	Feature
3.1	Cadence heatmap (1:1 / feedback frequency per person, 12-week strip)
3.2	Tags + saved filter views (#growth, #blocker, "All overdue tasks")
3.3	Decisions log (team-level ADRs)
3.4	Kanban view for tasks (Today / This week / Later / Done)
3.5	Watch-folder mode — write notes as real .md files for Obsidian compatibility
3.6	Bulk operations on items (multi-select → mass reschedule / move / delete)
3.7	Per-team / per-person filter on the Analytics page

Tier 4 — engineering polish (post-v1)

Small, well-scoped follow-ups surfaced by the v1 production-readiness review. None block the MVP — they're listed here so the audit trail doesn't get lost between releases.

#	Item	Why it matters
4.1	Toast action button support (e.g. "Undo" after a destructive action)	The Toast provider in src/components/ui/Toast.tsx already owns the lifecycle, an action?: { label, onClick } slot would let destructive flows replace window.confirm while still being safely reversible.
4.2	Settings bundle split	dist/assets/Settings-*.js is ~68 kB / 20 kB gzip — Sync, Cloud Sync and AI sub-sections could be lazy-loaded as siblings of the main page, dropping the initial Settings chunk by roughly half.
4.3	Cloud sync "remember passphrase on this device" toggle	Cleans up the TODO in src/lib/syncSession.ts (line 45). The passphrase already lives in sessionStorage — exposing the policy as a Settings toggle just makes it discoverable.
4.4	Auto-updater TLS pinning (defence-in-depth)	electron-updater already verifies the Apple-signed binary; pinning a GitHub Releases certificate fingerprint at the IPC boundary would catch a hypothetical MITM at the download step even if the signature check were ever bypassed.
4.5	Toast queue position preference	Bottom-right is sensible default, but power users might want top-right (closer to where they typically focus). One-line addition to the toast container.
4.6	window.alert → toast migration sweep	Done for v1 in Settings + RegisterPage; spot-check other route surfaces (TodosPage, NotesPage, dialogs) for any remaining native dialogs that should be toasts.
4.7	Manual note ↔ task linking (picker)	v1.40 auto-links via AI extraction; a "🔗 Link to a note" button in todo edit mode (with a small note picker, fuzzy by title) would let users connect tasks they typed by hand to a relevant note. The data model already supports it — only the UI is missing.
4.8	Note checklist → inline task conversion	When a Markdown checklist line (- [ ] …) is detected in a note, surface a hover-only "Convert to task" affordance on that line. Creates a single todo (in the user's default or last-used list) with sourceNoteId set and replaces the checklist line with a reference. Faster than running the full extractor for one-off items.

Long-term

• Per-person reminders with timezone-aware scheduling
• Windows MSI + Linux AppImage signed builds (promote from "experimental local build" to CI-released)
• i18n framework (English is the primary language; community translations welcome)
• Per-field merge in sync (overlaps with Tier 2.5; full CRDT or operational-transform layer would let two phones edit the same note offline and reconcile cleanly)

---

Contributing

Issues and pull requests are welcome. Please:

1. Use Node 20+, install with npm install, and run npm run dev.
2. Keep all UI strings in English (no in-code i18n yet).
3. Before sending a PR, run:
   • npm run typecheck — strict type-check (same gate as CI).
   • npm run check — typecheck + unit tests in one shot.
   • npm run build:web — Electron-targeted Vite build.
   • npm run build:pwa — Pages-targeted Vite build.

AI coding agents

This repo ships agent context and a reusable Cursor rule "team" (AGENTS.md plus .cursor/rules/: developer-expert, code-review-expert, frontend-expert, technical-architect, devops-expert, test-expert) that steer AI agents toward production-ready, zero-data-loss work. See AI agent rules & project context for how they're built, how to use them, and how to reuse the setup in other projects.

---

Migration notes (from Leeadman)

The project was previously called Leeadman. The rename to Cadence touches every user-visible surface: window title, Dock, menus, manifest, on-disk file names (cadence-data-<userId>.json, cadence-accounts.json, …), localStorage keys and macOS appId (com.cadence.app).

If you have data from a pre-rename build on the same machine:

• The desktop app auto-migrates it once on first launch. It copies the contents of ~/Library/Application Support/Leeadman/ (or the equivalent on Windows / Linux) into the new Cadence/ userData folder, renaming every leeadman-* file to cadence-*. The legacy folder stays in place as a safety net — feel free to delete it after confirming the migration worked.
• PWA path migration. Older PWA installs registered against /cadence/?source=pwa. The marketing landing now lives at /cadence/ and the app moved to /cadence/app/; an inline redirect in the landing's <head> bounces ?source=pwa traffic so existing PWA installs keep working without manual reinstall.
• JSON backups still work. If you only have a JSON backup (leeadman-backup-*.json exported from the old build), use Settings → Backup → Import JSON in the new app — the importer reads the file contents, not the filename.
• Vite env variables. CADENCE_PWA=1 is the canonical flag now, but LEEADMAN_PWA=1 is still accepted for one more release so old CI workflows don't break.

---

Legal

• Privacy Policy — PRIVACY.md. What data Cadence stores, where it lives, what gets sent over the network and to whom. Short version: local-first, no telemetry, opt-in integrations only.
• Terms of Use — TERMS.md. Conditions for using the distributed binaries and the GitHub Pages PWA. Source code is governed by LICENSE.

Cadence is not affiliated with or endorsed by Google, Anthropic, OpenAI, or Microsoft. Mentioned trademarks belong to their respective owners.

License

MIT © Sercan Çelenk

See LICENSE if present, otherwise refer to the MIT License.