Project Manager

A local-first desktop workspace for notes, projects, spreadsheets, charts, and custom apps. Everything lives in plain files in one folder. The desktop app is Electron; the interface is React, CSS, and WebGL.

What it does

• Home. A configurable focus project and a switchable countdown, both chosen directly from the overview. The WebGL liquid-glass hero tracks the project hierarchy, optional dates, roadmaps, and progress.
• Projects. Nested subprojects, any number of independent linear roadmaps, a real date-scaled Gantt timeline, goals, checklists, optional start and deadline dates, links to notes, note folders, events, and other projects.
• Calendar. App-native custom calendar with month, week, and agenda views. Project deadlines and roadmap phase starts and ends are derived automatically from project files, so they never need to be duplicated as events. A Projects toggle and legend keep the calendar readable.
• Notes. Obsidian-style live-preview editing: rendered blocks, with only the active block showing its markdown source. View mode is the same article with editing disabled. Images, KaTeX math, Mermaid diagrams, ten chart types, CSV-driven charts, Python plots, tables, wiki links, backlinks, folder filtering, tags, per-note fonts, per-line font overrides, and a project-aware notes graph.
• Graph. Projects are organized into families: solid arrowed parent-to-child edges, dashed related-project edges, folder nodes for linked note folders, and rooted family clustering. The layout settles in about a second.
• Spreadsheets. Real CSV files with a fast grid, formulas, multi-cell copy/paste, CSV import/export, column resizing, header styles, cell fills, number formats, and charts saved into sheet metadata.
• Custom apps. Build dashboards from chart, Python chart, table, metric, markdown, note, sheet, project, and checklist widgets. Apps are saved as markdown files.
• Settings. A balanced responsive card layout that uses the full window at 1100, 1440, and 1920 widths without empty columns.
• Agents. A loopback HTTP API plus a plain-file vault lets external agents read and write everything while the app is open.
• Sync and updates. Two-way mirroring to a local folder, mapped drive, or NAS. The Windows NSIS installer upgrades in place, and the app can check a release feed, verify a downloaded installer, and install the update.

Run

Requirements: Windows 10 or 11, Node.js 22 or newer, pnpm. Python 3.8+ is optional and used for Python plots.

pnpm install
pnpm dev

pnpm dev starts Vite and the Electron window. To use the app without a dev server:

pnpm build
pnpm start

Build a Windows installer and portable executable:

pnpm dist:win

Artifacts are written to release/:

• ProjectManager-Setup-1.3.0.exe (installer)
• Project Manager 1.3.0.exe (portable)
• win-unpacked/ (unpacked application)

The web build (pnpm dev:web) also runs in a browser with a localStorage-backed vault. Desktop-only features such as choosing a vault folder, Python plotting, the local agent API, NAS sync, and installer updates appear as desktop-only there.

Home

The focus project and the home countdown are persisted in settings.md as focusProjectId and homeCountdownId. Pick either directly from the home screen or from Settings → Home. Clearing a selection returns to automatic behavior: the most urgent active root project and the next upcoming countdown.

Notes format

A note is a markdown file under notes/. The filename is decorative; identity comes from id, and folder is the virtual folder path.

---
id: n_launch1
type: note
title: Launch brief
created: 2026-10-18T09:00:00.000+08:00
updated: 2026-10-27T20:40:00.000+08:00
folder: Strategy
tags:
  - launch
---

Orion opens quietly, then gets loud.

- [x] Lock the narrative
- [ ] Clear the waitlist

See [[project:Orion]] and [[Visual language]].

Body markdown supports headings and heading links, bold/italic/code, links, images from assets/, tables, task lists, KaTeX math, Mermaid diagrams, chart fences that read CSVs, and pyplot fences that use Python when available. Individual lines can use pm-font-* spans, applied from the Type control in the editor or written by hand. See docs/NOTES.md for the complete note format, frontmatter fields, link syntax, per-line font classes, and examples.

Live note editor

Edit and View use the same rendered article. In Edit mode, clicking a block reveals only that block's markdown source in place; everything else stays rendered, the way Obsidian live preview works. View mode simply disables editing and hides the formatting controls. Font formatting can apply to a selection or a single line without leaving markdown.

Projects and roadmaps

Projects are markdown files. A project can contain nested subprojects through parentId, and any number of independent linear roadmaps in roadmaps. Each roadmap has ordered phases with optional dates and a status of planned, active, or done.

id: p_orion
type: project
title: Orion
status: active
parentId: p_orion_parent
start: 2026-09-18
deadline: 2026-11-21
linkedFolders: [Strategy, Design]
linkedNotes: [n_launch1]
linkedEvents: [e_review]
relatedProjects: [p_signal]
roadmaps:
  - id: rm_product
    title: Product
    phases:
      - id: r_foundation
        title: Foundation
        status: done
        start: 2026-09-18
        end: 2026-10-02
      - id: r_launch
        title: Public launch
        status: active
        start: 2026-10-25
        end: 2026-11-21

Both start and deadline are optional and independent. Projects without dates render no date chip and no fake countdown. Subprojects keep their own goals, checklists, roadmaps, and links, and roll up into parent progress. The project list is an expandable tree with parent breadcrumbs. Old vaults that still contain the single roadmap: list are migrated in memory to one roadmap titled Roadmap.

The roadmap workspace animates real Gantt bars against a shared date axis. Bars are positioned and scaled from their phases, with a progress rail, done milestones, today marker, active-phase emphasis, and a graceful evenly spaced fallback for undated plans.

Calendar

The calendar is built into the app, with custom UI and no external calendar dependency.

• User events, all-day events, linked notes, projects, and events, and live countdowns.
• Project deadlines appear as flag items only when the project actually has a deadline.
• Roadmap phase starts and ends appear as diamond and square milestones in every view.
• A Projects toggle hides all derived project items; project chips filter to a project and its descendants.
• Clicking a deadline opens the project. Clicking a phase milestone opens the project and jumps to the matching roadmap and phase.
• Balanced overflow (+N more) keeps user events visible even on dense days.

Vault

On first launch the app creates a vault in Documents\Project Manager unless you select another folder. This setup uses E:\Projects. Change the folder in Settings → Vault.

Project Manager/
  notes/<Folder>/<slug>-<id>.md
  projects/<slug>-<id>.md
  calendar/events/<date>-<slug>-<id>.md
  calendar/countdowns/<slug>-<id>.md
  spreadsheets/<name>.csv
  spreadsheets/<name>.meta.md
  apps/<slug>-<id>.md
  assets/
  settings.md

Markdown frontmatter carries structure. Spreadsheet data stays in standard CSV; styling, formulas, column widths, and saved charts live in the adjacent .meta.md sidecar. Files are written atomically. Conflict copies (*.conflict-*) and hidden folders are ignored by the app so a sync cannot introduce duplicate entities.

The bundled demo-vault/ is the sample data used by the browser build and the first-run demo. It includes a project family with subprojects, two-level and multi-roadmap plans, projects with and without deadlines, linked note folders, derived calendar milestones, countdowns, spreadsheets, charts, and a custom app. The active E:\Projects vault on this machine uses the same project structure.

• Note format
• Vault format
• Spreadsheets
• Updates
• Sync

Python plots

Python plots are rendered by the bundled python/pm_plot.py, which uses only the Python standard library. It reads a .csv from the vault and produces a themed standalone SVG.

Set an interpreter in Settings → Python or let the app detect py -3, python, or python3. If Python is unavailable, every chart type still renders through the built-in SVG engine.

```pyplot
{"type":"bar","source":"spreadsheets/launch.csv","x":"Month","y":["Revenue"]}
```

Custom apps

Custom apps are markdown files in apps/ with a widget list in frontmatter. Create and edit them visually from Apps, or write them directly. Widgets can read spreadsheets, embed notes and projects, show metrics, display markdown, or render live Python and SVG charts. See docs/VAULT_FORMAT.md.

Agents

While the desktop app is open, a local HTTP server is available at http://127.0.0.1:47821 (falling back through port 47830). It binds loopback only.

Invoke-RestMethod http://127.0.0.1:47821/api/manifest
Invoke-RestMethod http://127.0.0.1:47821/api/files

Method	Path	Purpose
GET	/api/files	List markdown, CSV, app, and sheet files
GET	/api/files?path=...	Read raw markdown or CSV
PUT	/api/file?path=...	Replace or create a file
POST	/api/append?path=...	Append a markdown block
POST	/api/notes	Create a note from JSON
POST	/api/projects	Create a project from JSON
POST	/api/events	Create a calendar event from JSON
POST	/api/countdowns	Create a countdown from JSON
GET	/api/events	Server-sent change feed

See docs/AGENT_API.md and AGENTS.md. The current address is shown in Settings → Agent.

Updates

The app checks an update feed in Settings → Updates, downloads the installer to its own user data folder, verifies the SHA-256 when provided, then installs it. The NSIS installer uses the same application ID, so running a newer setup upgrades an existing installation while keeping the vault and settings.

pnpm publish:update --installer "release\ProjectManager-Setup-1.3.0.exe" --base-url "https://example.com/project-manager"

Upload the generated latest.json and installer to that base URL. See docs/UPDATES.md.

Sync

Open Settings → Sync → Choose folder and select a local folder, mapped network drive, or UNC share. The app mirrors both directions every few seconds, copies newer files, preserves simultaneous versions as conflict copies, and never deletes content. See docs/SYNC.md.

Shortcuts

Keys	Action
Ctrl K	Command palette
Ctrl N	New note
Ctrl Shift N	Quick capture
Ctrl S	Save now
Ctrl 1 to Ctrl 8	Overview, Notes, Calendar, Projects, Sheets, Apps, Graph, Settings
?	Shortcut reference
Esc	Close overlay

Notes: Ctrl E toggles read and edit, Ctrl B and Ctrl I format text. Calendar: M, W, A switch views, T is today, N creates an event, arrow keys move between periods. Projects: N creates a project, / focuses search. Sheets: arrows move cells, Enter edits, Ctrl+C/V copy and paste, Ctrl+Z/Y undo and redo. Apps: Ctrl 6.

Development

src/                 React app
  features/          dashboard, notes, graph, calendar, projects, sheets, apps, settings
  components/        shell, chart renderer, markdown, liquid glass, overlays
  lib/               file formats, CSV, formulas, charts, links, project hierarchy, progress
  state/             vault store and UI state
  styles/            tokens and per-feature styles
electron/            main process, preload bridge, vault, agent API, Python, updater, sync
python/              stdlib-only plotting script
demo-vault/          first-run demo content and assets
docs/                agent, vault, spreadsheet, sync, and update reference
tests/platform/      vault, bridge, agent API, Python, updater, and sync checks

pnpm typecheck
pnpm test:platform
pnpm build

Windows is the initial supported desktop target. Linux and macOS packaging will follow; the vault, watcher, agent API, Python bridge, updater service, and sync layers are platform-neutral Node code.