Perigee — Reference Manual

Overview

Perigee is built around two ideas. The first is local-first: everything you write is stored in your own browser, so it's instant and works fully offline — the network is a convenience, never a dependency. The second is one substrate, many lenses: every document, whatever product you created it in, is the same kind of record underneath. A spreadsheet, a board card, a wiki page, and a note are all just text with a type, and each product is a different way of looking at that shared pool — not a separate database. That is why a card can move to a board lane, a note can be summarised into a graph, and all of it syncs through one connection.

Because the content is plain text, features like to-do lists, spreadsheet formulas, or flowchart shapes are conventions the app understands rather than separate data. A note exports as a clean .md file; a spreadsheet is a markdown table; even a flowchart is only text underneath.

Working solo needs no account at all — Perigee runs entirely on your machine. When you want it on more than one device, or want to work with someone else, you sign in and share a workspace; edits then flow between everyone in real time, while everything stays local-first underneath.

Running Perigee

Most people just use the hosted app and never think about this section. To run your own copy, the app loads as ES modules, so it must be served over HTTP rather than opened from the filesystem. From the project folder, start any static server and open the local URL:

python3 -m http.server 8000
# then open http://localhost:8000

npx serve or an editor's live-server extension work equally well. This manual, by contrast, is a single self-contained file and opens directly in any browser.

Signing in & workspaces

Perigee works with no account at all. On the start screen, Continue without an account drops you straight into a local-only workspace: everything is saved on this device and nothing is ever sent anywhere. It's the right choice for trying Perigee out, or for purely solo, single-machine use.

To use Perigee on more than one device, or with other people, choose Sign in with GitHub instead. After signing in you land in a workspace — a shared container for your documents. You can create one, or join an existing one with an invite code.

The account panel opens from the status badge at the right end of the top bar. From there you can set your display name, invite a collaborator, turn on AI, switch workspaces, or sign out. In local-only mode the same badge offers to sign in. Inviting people lives in the People product.

Collaboration & sync

Inside a shared workspace, edits sync in real time — across your own devices and between everyone in the workspace. Open the same document in two places and you'll watch changes appear as they happen.

Sync never gives up local-first. Your edits land instantly and keep working offline; when you reconnect, everything reconciles on its own. Changes to different things merge cleanly, with no conflicts and no duplicate copies. The status badge in the top bar shows whether you're synced, working offline, or reconnecting.

Structure replicates eagerly while bodies follow lazily: a document's metadata — its type, title, board lane, due date, column shape — travels first so every view stays correct, and the full body arrives when something needs to open it.

The interface

The window has two regions. On the left, a sidebar holds whatever the current product needs — a calendar and note list for Notes, a page tree for the Wiki, a document list for Spreadsheets and Flowcharts. On the right, the main area shows a top bar above the working surface.

The product menu sits in the centre of the top bar and switches between the nine tools. They share one workspace and one connection, so signing in and inviting people applies to all of them at once. On narrow screens the sidebar collapses into a drawer, opened with the menu button and dismissed with Esc or a tap outside it.

Write & Read

Document-style products — Notes, Wiki, and the documents you open from Queries — have two views, toggled by the segmented control in the top bar or with Ctrl/Cmd + E. Write shows the raw markdown in an editor; Read renders it. A few elements are interactive only in Read mode — notably to-do checkboxes, which write their change back into the source text. Everything you type is saved automatically as you go.

Searching

In Notes, the sidebar search box transcends the day folder: while it's empty the list shows the selected day's notes, and as soon as you type it searches across every day. Clicking a result centres that note and moves the selected day to match it. For querying across types and sorting the results, the Queries product is the fuller tool.

Export & delete

The top bar's export control downloads the active document as a plain .md file, named from its title. The delete control removes the active document after a confirmation. Because every product writes to the same text substrate, export gives you the real source — a spreadsheet comes out as a markdown table, a note as markdown prose.

30k Foot View

A read-only dashboard — your day at altitude. It gathers three things from across the workspace and links each item back to its source:

• Your open tickets — board cards assigned to you that aren't in a Done lane, soonest due first. Each ticket carries a left stripe in its card's board colour, and anything overdue is flagged in red.
• Recently mentioning you — notes and wiki pages whose #MENTIONFROM footer tagged you, newest first.
• To-dos on your pages — the open #TODO items sitting on documents that mention you. Completed items are left off.

A running count of outstanding tickets sits up top. The view needs your display name set (in account settings) so it knows which cards and mentions are yours; until then it prompts you to set one.

Notes

Notes is the markdown journal — the prose product. Notes are organised by day, each with its own URL you can bookmark, and they support the full markup reference below, plus the cross-cutting mentions, to-dos, and AI features.

The page strip

Notes live in a horizontal strip ordered by date — oldest on the left, newest on the right. The active note sits centred inside dashed margin guides, and its neighbours peek in at the edges, dimmed and non-interactive. Click a peeking neighbour to glide it to the centre. A large + button rides the right edge of the active page and always adds a note dated to the currently selected day. Only the centred page is live.

Calendar & days

The calendar drives navigation. The selected day is the single thing that steers the view: the sidebar list shows that day's notes, the calendar rings it, and the + button adds to it. Each day cell can show a dot (holds at least one note), a filled cell (today), and a ring (the selected day), which may stack. The month arrows browse without changing your selection; a Jump to today link appears whenever the selected day isn't today.

Creating & dating notes

New notes — from the + button, the sidebar's +, or Ctrl/Cmd + N — are dated to the selected day. Creating on today is the frictionless common case. Creating on any other day is backdating, and Perigee surfaces a quiet, non-blocking notice — "Added to <date> · Move to today · Undo." — rather than a confirmation dialog.

Inline tables

Notes can hold simple inline tables. The Insert button in the bottom toolbar opens a grid picker; drag across it to choose dimensions, fill the cells, toggle the header row, and press Done. Click a table in Read mode to reopen the editor. Under the hood a table is stored as ordinary <table> HTML inline in the note body, so it still exports in the .md. These are distinct from the Spreadsheets product, which is for typed, structured data.

Wiki

The Wiki organises documents into a hierarchical tree rather than by day — a living knowledge base. From the sidebar you create root pages and, with the + on any page, child pages nested beneath it. Each page is a full markdown document with Write and Read modes and every footer feature, so a wiki page can carry mentions, to-dos, an AI summary, and semantic backlinks just like a note.

Pages connect through the semantic backlinks feature and in-app deep links: clicking a backlink jumps straight to the linked document, wherever it lives. The same content is reachable as graph nodes in Mental Model.

Board

The Board is a kanban over your documents. Lanes are columns you add with + Add lane and remove with the × on a lane header; cards are created inside a lane and dragged between lanes to change status. The arrangement is field-derived — a card is simply a document carrying a lane name, so moving it just changes metadata, and it syncs like everything else with no separate board file.

Right-click a card for its menu, where you can set:

• Colour — a tint from a small palette (this is the colour echoed on the 30k view);
• Points — a story-point estimate shown as a badge;
• Heft — visual weight, drawn as the card's border thickness;
• Assignee — picked from the workspace members;
• Due date — a date, shown on the card and flagged when overdue.

Assignee and due date are what feed your open tickets on the 30k Foot View.

Queries

Queries lets you ask which documents you want and see them through a lens. The query bar filters by:

• Text — free text, or a #tag to match hashtags;
• Type — any document type, or one in particular;
• Sort — the order results come back in.

Results render in a layout — a List today, with more planned. Click a result to read it in place; Back to results returns you to the list. Your query and layout are remembered between visits, so Queries doubles as a saved working view over the whole workspace.

Spreadsheets

Spreadsheets put structured, typed data on the same local-first substrate. Under the hood a sheet is a markdown pipe table, so it exports and round-trips as text like everything else — but each column carries a type that decides how its cells render, validate, and sort.

Columns & types

Click a column header to open its menu. There you set the column's type — text, number, date, single-select (a dropdown), or checkbox — rename it, reorder it (move left/right), insert a column to its left or right, or delete it. Single-select options are listed one per line and can each carry a colour, written in parentheses — Done (green) — which tints the cell.

Rows & layout

Click a row number for its menu: insert a row above or below, or delete the row. Drag a column's right edge to resize it; text that's too long wraps rather than stretching the column. + Add row and the header's + add to the end.

Formulas

A cell whose text begins with = is a formula. It shows a computed result and recomputes whenever a cell it depends on changes. Formulas are numeric — they evaluate to a number. Click a formula cell to see and edit the formula itself; a small corner marker shows which cells hold one. Formulas can be typed into text and number columns.

Cells are addressed in the usual A1 style — a column letter followed by a row number (A1, C4), case-insensitive. A reference to a blank or non-numeric cell counts as 0 in arithmetic. A range is two references joined by a colon (A1:A10) and is used inside functions, where blank and non-numeric cells are skipped.

Operators are + - * / with parentheses and a leading minus, with normal precedence. The functions are:

A worked example: a budget sheet with Qty in column B and Unit cost in column C might put =B1*C1 in a Line total column, then =SUM(D1:D3) for the grand total — change any quantity and the totals follow.

When a formula can't be computed it shows a short code: #DIV/0 (division by zero), #REF (a bad reference), #NAME (unknown function), #CYCLE (a formula that depends on itself), or #ERR (a parse error). Two things to keep in mind: formulas are numeric only — no text or logical functions yet — and references don't shift when you insert or delete rows and columns, so =A1 always means column A, row 1. After restructuring a sheet, glance over any formulas that referred to moved cells.

Flowcharts

Flowcharts is a visual editor for boxes-and-arrows diagrams. While you work, the diagram is what you edit; Perigee quietly compiles it to text behind the scenes and syncs that, so a flowchart is as portable and merge-friendly as a note. A workspace can hold many charts — create, name, and delete them from the sidebar, just like notes. Editing is mouse-first.

Adding & moving

Double-click any empty space to add a node, then type its label. The + Node and + Group toolbar buttons add one in the centre of the view. Drag a node to move it; it snaps to a grid as you drop it.

Connecting

Hover a node and small ports appear on its four sides. Drag from a port onto another node to draw an arrow. To label a connection, double-click it (or right-click and choose Edit label); clearing the text removes the label but keeps the arrow.

Shapes, colours & groups

Right-click a node for its menu. Shape chooses between process, terminal, decision, and input/output forms; Colour tints it. A group is a container: drag a node inside one to add it (and out to remove it), or use the menu's add/remove items. Moving a group moves everything inside it.

Editing labels & deleting

Double-click a node to rename it. Select anything and press Delete or Backspace to remove it — deleting a node also removes its connections, and deleting a group ungroups its contents rather than destroying them. Esc clears the selection and closes any open menu.

Getting around

Scroll to pan and Ctrl/Cmd + scroll to zoom. The Fit button frames the whole chart, and Perigee fits the chart for you each time you open one.

Mental Model

Mental Model shows your documents as a living graph of semantic connections. Every document you've summarised becomes a node; the semantic backlinks between them become edges. Nodes are coloured by type — note, wiki page, spreadsheet, flowchart, board, or card — with a legend when more than one type is present.

Tap a node to see its summary and connection count in a side panel. Double-click a node (or use Open document in the panel) to jump to it in its own product — a spreadsheet node opens the spreadsheet, a wiki node the wiki, and so on. Scroll to zoom, drag the background to pan, and drag a node to pin it where you want.

The graph is built from the AI features below: summarise a few documents and run Find related documents, and the view fills in. With AI off, or before anything has been summarised, it simply waits.

People

People is the workspace roster. It shows the workspace name, a member count, and everyone in it — each with an avatar, name, and email; you are marked you and the workspace creator is marked Owner.

+ Add member invites someone by email: Perigee emails them a one-time link that expires in seven days, or — if it can't send mail itself — hands you a link to pass along. Workspace members are exactly the people you can @mention and assign board cards to.

Mentions & names

Any document can record who mentioned whom. Press Mention… in the document corner, search and tap the workspace members you want, and press OK; Perigee writes a #MENTIONFROM footer to the bottom — you first, then the people you tagged (re-running replaces it rather than stacking). Documents that mention you then surface on the 30k Foot View.

Names follow an underscore convention: spaces become underscores so a person's name reads as a single token (Ada_Lovelace). Because mentions reference members of your workspace, the feature needs an account and a workspace.

To-dos

A #TODO block turns any document into a checklist — a title line followed by item lines, where -/*/+ are open and x is done (see the markup reference for the exact form). In Read mode the items become checkboxes that write their state back into the text. Open items living on documents that mention you are gathered under To-dos on your pages on the 30k Foot View; completed ones are left off there.

AI features

Perigee's AI features are bring-your-own-key and off by default. In account settings, turn AI on and paste your own free Google Gemini key. Your text and key go straight to Google from your browser and never touch Perigee's servers.

With AI on, the corner of a document offers Mental Model…:

• Summarize document asks your Gemini model to distil the document into a one-sentence summary plus a few tags, and writes that as a #MENTALMODEL footer. Re-running replaces it.
• Find related documents compares this document's summary against the summaries of your most-recent documents and writes the genuine matches as a #BACKLINKS footer of in-app links. (Each document needs a summary first — that's what the comparison reads.)

Spreadsheets and flowcharts carry the same summariser in their own corner, so they too can become nodes. The Mental Model product is the visualisation of everything these footers produce.

Keyboard shortcuts

Markup reference

Every markup form Perigee understands, shared by Notes, the Wiki, and any document you open. The left column is what you type; the right is what Read mode shows.

Limitations

Perigee's markdown is a deliberate kernel, not full CommonMark. Known gaps:

• no nested lists or nested block quotes — block structure is one level deep;
• inline note tables are inserted as HTML, not written in pipe syntax — the pipe-table form is reserved for the Spreadsheets product;
• no - [ ]-style task lists — to-dos use the #TODO block instead;
• inside a paragraph, a single line break becomes a line break (not a space), which differs from CommonMark.

The products have their own early edges. Spreadsheet formulas are numeric only, and references don't shift when rows or columns are inserted or deleted. Queries offers a List layout for now, with more planned. Mental Model needs AI turned on and documents summarised before the graph has anything to draw. In Flowcharts, connections route directly rather than bending around boxes, and the single case that can collide is two people moving the same node at the same instant — edits to different nodes always merge cleanly. The AI features depend on your own Gemini key and send the relevant document text to Google to work.