1.1 Understand Productivities

Productivities is not just a task manager or a notes app. It is a workspace for the messy middle of personal work: the moment when a thought might become a task, a link might become research, a page might become a plan, and a project might need a calendar, a timeline, a table, and a few reminders around it.

The app works by creating durable objects and letting those objects travel. A task can link to a page, a pin can sit in the Universal Inbox until you decide what it is, a canvas node can reference a task, and a Space can collect a whole project without forcing everything into one folder. That matters because real workflows rarely fit one surface for long.

A useful way to think about the everyday loop is: capture something, decide what it is, place it in the right context, connect it to related work, and return to it through the view that helps today.

Core tools

• Tasks and Planner help you turn intention into visible commitments, then decide what belongs today, later, or inside a larger Space.
• Pages give your thinking somewhere portable to live, while still adding backlinks, properties, tags, embeds, graph views, and search.
• Pinboard gives captured material a holding area before you know whether it is reference, reading, research, or fuel for a task.
• Tables help when information needs structure: records, properties, filters, groups, formulas, and views rather than another loose note.
• Canvas helps when you need to understand shape and relationship visually, especially when tasks, pages, pins, and tables all belong to the same problem.
• People, Highlights, Forms, and Routines connect relationships, reading, structured capture, and repeatable actions to the work they support.
• Rediscover brings useful Pages, Pins, and Highlights back into view.
• Focus, Automations, Activity, and AI support the operating layer around the work: concentration, maintenance, history, and assistance.

1.2 Install and set up

Productivities is distributed as a desktop app for macOS and Windows. On macOS, install it by opening the disk image, dragging Productivities into Applications, and launching it from Applications or Spotlight. On Windows, use the Productivities installer, choose the installation location if prompted, and launch it from the Start menu or desktop shortcut.

The first run is deliberately about ownership. Productivities keeps the app database locally by default, while Pages and media folders can live in folders you choose. That means your writing and files are not trapped inside a hidden app format.

First run

1. Create the first local user account. This account becomes the administrator for the installation.
2. Choose where file-backed content should live. Pages are Markdown files, while media folders keep images, PDFs, videos, and audio accessible outside the app.
3. Open the main workspace and use the sidebar to move between Planner, Tasks, Spaces, Pages, Pinboard, Calendar, People, Highlights, Databases, Forms, and whichever tools are enabled for your plan and user.

Your app database lives in the Productivities application-data folder. Your Pages and media can live wherever you choose, so they remain accessible in Finder, File Explorer, and other tools.

1.3 Learn the interface

The main window is organised around a left sidebar, a central workspace, the Action Panel, and supporting panels for calendar, AI, and other context. Most work happens in the central workspace; the top and title-bar controls adapt to the active tool.

If you are new to the app, start by noticing that the sidebar changes the kind of work you are doing, while the objects themselves can remain connected. Moving from Planner to Pages or Pinboard is not switching to a separate silo; it is changing the lens.

Common navigation

• Sidebar opens the main tools and user menu entries such as Settings, Activity, and Admin Console. Use it when you want to change the type of work you are doing.
• Action Panel opens from the nine-dot button or Alt+Q. It gathers built-in, custom, and plugin actions; use Manage to reorder cards and pin favourites into the always-visible Action Bar.
• Split workspace places two tabs side by side for comparison or reference work and restores the session when you return.
• Title-bar actions hold commands that depend on the current view, such as creating a task, changing a table view, importing, filtering, or opening a panel.
• Context menus are available on most objects. Right-click tasks, pages, pins, rows, canvas nodes, Spaces, and events when you want to ask, “what can I do with this?”
• Global search helps you find work across object types, while the command bar helps you move quickly, capture quickly, or trigger an action without hunting through navigation.

1.4 Choose a plan

Some features depend on the plan, the current user, and the environment the app is running in. If something is missing, it does not always mean you are in the wrong place: the installation may not include it, an administrator may have disabled it for your user, or the current runtime may not support the native capability.

Free

Core personal tools for getting started, including Tasks, Pages, Pinboard, Spaces, Calendar, Routines, Plugins, saved views, Apple Calendar, and local-first use.

Personal Pro Pro

Advanced tools and capabilities for deeper personal workflows, including Canvas, Databases, Forms, People, Highlights, Rediscover, Activity, Automations, Time Tracking, Deep Work, Command Bar, Hably and Space Agents, external connections, and mobile access.

Cloud and shared deployments

Personal Pro capabilities with hosted sync and collaboration where offered. Self-hosted shared environments can also use PostgreSQL-backed operation, shared Spaces, groups, assignment, administration, and expanded operational controls.

Always use the Pricing page as the commercial source of truth; this documentation explains how the product behaves once a feature is available.

2.1 Choose the right tool and view

A tool is an area of the app designed for a particular kind of work. A durable object is something you create, capture, edit, connect, or return to later. A view is one way of looking at those objects: as a board, a list, a calendar, a table, a graph, a dashboard, or another useful arrangement.

The practical idea is simple: you should not have to choose one rigid format for everything. A task can be planned on a board, scheduled on a calendar, linked to a page, discussed in Activity, or shown inside a Space. The object stays the same; the view changes depending on what you need to understand or do next.

Tool

Tools are the main working areas. Each one has its own interface because writing notes, planning tasks, reading saved material, and reviewing a routine are different activities. They still share the same underlying model, so the work you create in one tool can stay connected to work elsewhere.

Object

Objects are the things Productivities remembers. They are durable: you can create them in one place, connect them somewhere else, and later find them through search, Spaces, views, links, or Activity.

View

Views are different ways of looking at the same underlying work. A Planner board helps you reason about flow. A task list helps you scan and clear work. A Week Calendar helps you understand time. A table view helps you compare structured records. Universal Inbox helps with triage. Activity helps you see what changed. A note graph helps you see relationships between pages. A filtered Pinboard helps you review saved material by type, Space, or context.

This distinction matters because Productivities tries not to trap work in a single surface. A task remains a task whether you see it in the Planner, a task list, a calendar projection, a Space dashboard, or a linked canvas node. The app is designed so the same piece of work can appear wherever it is useful.

2.2 Organise with Spaces, tags and links

A Space is the main organiser across tools. It can represent a project, client, topic, role, life area, or shared workspace. The reason Spaces matter is that they let you gather related work without flattening it into one kind of item. A project can have tasks, Pages, Pins, Canvases, Databases, People, Outcomes, a timeline, milestones, and Routines, and still feel like one place.

Spaces can be

• Manual containers when you want to explicitly decide which work belongs to a project, client, topic, or life area.
• Smart filters when the Space should gather matching work automatically based on criteria such as tags, keywords, or pin types.
• Private Spaces when sensitive contents should be encrypted at rest and require an unlock before they are visible in normal use.
• Shared work areas in deployments where groups and access controls decide who can see or contribute to the Space.

Links are the second organising layer. They explain how individual pieces of work relate to each other. A task can link to a Page, Pin, Database, Canvas, or calendar context. Pages can reference other Pages and embedded objects. Canvas nodes can reference Productivities objects. Adding the Routines artefact gives a Space a recurring operating cadence alongside all of that connected work. This gives you a way to keep context close without copying the same information into every place you might need it.

Tags provide a lighter organising layer across tools. Use them when work shares a theme or context but does not need the shared home of a Space. Tags can drive filters, saved views, and smart Spaces, so the same label can help you find related work wherever it lives.

2.3 Choose where your work lives

Productivities defaults to local storage. Structured data is stored in SQLite, while Pages are real Markdown files in the folder you choose. Media files are stored on disk and referenced by the app.

This is important if you care about longevity and control. You can use the app layer for search, links, views, and workflow, but your authored Markdown and media still live in normal files and folders.

• Database stores the structured parts of the workspace: users, settings, Spaces, tasks, Pins, Highlights, People and interactions, routines, Databases, Forms and responses, Canvases, Automations, time entries, comments, agent conversations and plans, and operational metadata.
• Markdown files hold Page bodies. The database mirrors metadata for search, properties, tags, scheduling, and backlinks, but the writing itself remains portable.
• Media folders hold images, PDFs, audio, and video so the Media Manager and Pages can work with files directly.
• Optional PostgreSQL supports server-style deployments where a shared backend is preferred.

2.4 Save and revisit useful views

As the workspace grows, you do not need to rebuild the same working view every time. Filters, grouping, sorting, and saved views let you preserve the lens that answers a recurring question while the underlying objects remain shared.

• Filters narrow a tool by search text, Space, tag, group, type, status, date, or other fields supported by that object.
• Groups and galleries organise objects visually without changing what they are. Managed groups are available across tools including People, Highlights, Databases, Canvas, Forms, and Automations.
• Saved views retain useful filter and layout combinations, can be renamed and reordered, and make recurring reviews a one-click return rather than a fresh setup.
• Navigation views can place compatible saved views directly in the sidebar, so a recurring filtered perspective behaves like a destination of its own.
• Workspace history provides back and forward navigation across tools and selected objects, so following a Page, Person, Pin, or Space connection does not lose your previous place.
• Tool discovery keeps the workspace calm by showing the tools you have enabled and offering relevant disabled tools when their context would be useful.

3.1 Create tasks and subtasks

A task can be as small as a quick capture or as rich as a scheduled, recurring, linked, assigned, blocked, typed, time-tracked work item. The value is not that every task needs every field. The value is that the simple task and the complex task can live in the same model, so you can add structure only when the work deserves it.

Task fields and relationships

• Status, priority, title, notes, due date, scheduled date, recurrence, size, and completion state help you decide what the task means operationally.
• Subtasks and dependencies help when a task is not really one action, or when another task or person has to move first.
• The Eisenhower Matrix separates urgent and important work into four quadrants, giving you a focused priority view without changing the underlying tasks.
• Space, tags, custom properties, custom task types, and custom statuses help different kinds of work carry the right context.
• Links to Pages, Pins, Canvases, Tables, and other supporting objects keep the material you need close to the action itself.
• Select multiple tasks to update shared properties in bulk. Task views can group by tag, isolate unscheduled work, and adjust progress directly where supported.

3.2 Plan and schedule work

The Planner is the day-to-day planning surface. It groups tasks into practical scheduling columns such as overdue, today, tomorrow, next week, or custom columns. Dragging a task between columns updates its scheduling context, which makes planning feel like arranging the work rather than editing a database field.

The Week Calendar and agenda place tasks, calendar events, and time blocks into a time-based layout. This helps answer a different question from the Planner: not “what is important?” but “does this fit in the time I actually have?” Apple Calendar, Google Calendar, native Productivities events, and iCal feeds can all contribute calendar context when configured.

Time blocking sits between a task list and a calendar. When a task needs a real appointment with your attention, drag it from the Planner or task list onto the agenda. When you need to protect capacity without attaching a specific task, create a named block instead: project work, admin, writing, errands, recovery, or anything else that helps the day have a visible shape.

3.3 Triage captured work Pro

The Universal Inbox is a triage view over real tasks and pins. It is useful when you capture faster than you can organise. Instead of forcing every new item into a perfect home immediately, the Inbox gives you a review surface for deciding what something is, where it belongs, and whether to keep, schedule, open, or clear it.

• Tasks and pins can enter the Inbox without becoming separate queue-only records, so triage does not disconnect the item from the rest of the workspace.
• Opening an item is different from triaging it. Review should not silently mark something as handled just because you inspected it.
• Keyboard navigation supports fast review when the Inbox feature is enabled, which helps when the Inbox becomes part of a daily startup or shutdown ritual.
• The user-facing term is Inbox or Universal Inbox.

3.4 Design task workflows Pro

Most task systems start with one assumption: every task moves through the same simple path. That is fine for quick personal actions, but it can become awkward when different kinds of work need different language or different checkpoints.

Advanced workflows are for that moment. They let you describe the shape of the work more honestly, without losing the common task model underneath. A writing task might move from idea to draft to editing. A support issue might move from reported to investigating to waiting on customer. A personal errand may only need open and done.

The key concept is the task type. A task type describes what kind of work this is. Each task type can have its own custom statuses, and those statuses map back to common lifecycle states: open, in progress, completed, and cancelled. That mapping matters because Productivities can still understand the basic state of the task even when your workflow uses more specific words.

• Use custom task types when different kinds of work need different fields, statuses, or expectations.
• Use custom statuses when the default open, in progress, completed, and cancelled lifecycle is too broad for the way a specific task type actually moves.
• Use custom columns when the Planner board should reflect how you decide what to do next, such as by date, phase, energy, priority, or another planning lens.
• Use time and workload tracking when you want to compare what you planned with what the work actually cost.
• Use Productivity Insights when you want completion, workload, focus, and time patterns to become easier to review over time.

3.5 Start and finish the day

Daily rituals are about starting and ending the day with intention. They belong with planning because they help you decide what matters before the day takes over, and close loops before unfinished work turns into background noise.

The morning ritual is a way to review the work already in motion: what is scheduled, what is overdue, what is sitting in the Inbox, what needs a decision, which blocks deserve protected time, and what genuinely deserves attention today. The shutdown ritual is the counterpart at the end of the day: review what changed, clear or reschedule loose tasks, adjust blocks that overflowed, and leave tomorrow with less ambiguity.

• Use startup to choose the day deliberately: review tasks, check calendar commitments, triage the Inbox, and decide what should be scheduled, blocked, or prioritised.
• Use shutdown to close open loops: capture what changed, move unfinished work to a sensible place, adjust tomorrow's blocks, and leave notes for the next session.

4.1 Write in Markdown

Pages live as plain Markdown files in your chosen folder. This matters because the writing is still yours outside the app. Productivities then adds an editor, tabs, split views, preview, scheduling, metadata, search, and graph features on top of those files.

The editor treats a Page as more than one long text field. You can work with sections of the page as blocks, which makes it easier to move, refine, embed, or connect parts of a document while the underlying file remains Markdown. When Markdown is not expressive enough, Pages can also include HTML, giving you a practical escape hatch for richer formatting or embedded content.

Use Pages when something needs more continuity than a task: project notes, meeting records, research, plans, documentation, reference material, or the developing thinking behind a decision.

• Use the folder tree when the file structure matters: browsing, creating, renaming, moving, and deleting Markdown files.
• Use block editing when you want to manipulate a section of a Page without treating the whole document as one fixed piece of text.
• Use tabs and split workspace when you are comparing notes, drafting from source material, or cross-linking related pages. Beta 2 keeps two tabs side by side and restores the session when you return.
• Use the unified slash menu, headings, lists, tables, block movement, background colours, formatting shortcuts, wikilinks, embeds, tags, backlinks, and HTML support when you want knowledge to become connected and expressive without giving up file portability.
• Switch between Markdown and Live editing modes, pin the Inspector when properties and relationships need to stay visible, and export a Page to PDF when it needs to leave the workspace as a finished document.
• Add external folders when useful Markdown already lives elsewhere. Page search indexes full content as well as titles and metadata, including while you work offline.

4.2 Connect and inspect Pages

Page metadata is mirrored into the database so the app can search and filter quickly while the body remains a normal file. Frontmatter can carry tags, properties, Space assignment, and other structured details.

This is the bridge between writing and workflow. A page can stay readable as Markdown, but still behave like a useful object in the app: it can belong to a Space, appear in search, show relationships, and connect to tasks, pins, tables, and canvases.

Open the Inspector when you want those relationships beside the document. It keeps Page details, properties, tags, backlinks, and related context available without taking you away from the writing.

Knowledge features

• Backlinks show what references the current page, which helps you rediscover context you may not remember manually.
• Suggested links help discover pages that may belong together, especially when a knowledge base grows beyond what you can keep in your head.
• Graph views make page relationships easier to inspect when you want a visual sense of how ideas cluster.
• Templates speed up recurring page formats, such as meeting notes, project briefs, reviews, or research records.
• Git integration can support file-level versioning workflows when configured, which is useful if you want history and sync around Markdown files.

4.3 Reuse useful passages Pro

Highlights turns useful passages from Pages and Pin readers into a durable reading library. A highlight keeps a route back to its source while gaining its own note, tags, favourite state, group, and Space assignment.

The Library is for finding and organising what you saved. Resurface deliberately brings older passages back into view, which is useful when reading should influence later thinking rather than end with the article.

• Search highlight text and filter by source type, group, Space, tag, or favourite state; save recurring filter combinations as named views.
• Open a highlight's original Page or Pin at the relevant source location when you need the surrounding context.
• Add your own note, organise related excerpts into managed groups, and connect the material to a Space without changing the source.
• Use Resurface to review passages again over time. The Study area is marked as coming soon and is not part of the current workflow.
• The prd CLI and permission-scoped agent tools can also list, read, or create Highlights when explicitly authorised.

4.4 Manage embedded media

The Media Manager is the file-facing surface for images, PDFs, videos, and audio. It is useful when your knowledge work includes source material, screenshots, documents, recordings, or visual references that need to remain findable and reusable.

Its practical value is not just browsing. When media files are moved or renamed through the Media Manager, Productivities can preserve reference integrity so Pages and other workflows keep pointing at the right material.

• Browse media folders directly from inside Productivities without losing the underlying folder organisation.
• Preview thumbnails and open supported media when you need to inspect a file before linking or embedding it.
• Move or rename media while keeping references intact, reducing the chance that Markdown embeds or linked workflows break as files are reorganised.
• Keep media organised by folder while still using it inside Markdown and object workflows.

4.5 Keep a daily journal

The Daily Journal gives each day a natural page-based capture point for notes, reflections, work logs, and loose thoughts. It is helpful when you want a chronological layer alongside project and topic-based organisation.

• Daily notes provide a chronological home for work logs, reflection, and loose thoughts that do not yet belong to a project page.

5.1 Save material to Pinboard

A Pin is a saved reference object. Productivities recognises many pin types and renders them differently where possible, because a Jira issue, a recipe, a PDF, a YouTube video, and a quote do not all need the same treatment. Choose the capture route that best fits where you are working:

Capturing directly inside Pinboard saves to the current Pinboard destination. Quick-capture routes can use the Universal Inbox when Inbox triage is enabled, giving you a place to add a Space, tags, scheduling, or other context later.

• Pins can represent links, articles, text notes, quotes, PDFs, images, videos, audio, recipes, books, movies, TV shows, X posts, TikTok, YouTube, Instagram, Jira, Confluence, and Google Drive items.
• Each pin can carry title, description, tags, Space, favourite state, scheduling, reading progress, and source metadata, so it can stay useful after the moment of capture.
• Pins can link back into tasks, pages, Spaces, and Inbox workflows when captured material becomes part of active work.
• Search and combine multiple type filters, review in-progress or unwatched media, group useful filter states into saved views, and reset the view when you want the full Pinboard again.

5.2 Capture from the browser and enrich links

Paste or save a URL and Productivities attempts to classify it, fetch useful metadata, and present the right reader or card type. The Web Clipper can send content into Productivities without switching context, which is useful when you are researching, reading, or collecting project material on the web.

Set up the Web Clipper

1. Install the Productivities Web Clipper for Chromium, Firefox, or Safari.
2. If you run a shared or self-hosted installation, ask an administrator to allow Web Clipper connections in Admin Console → External Connections.
3. In Productivities, open Settings → Integrations → Web Clipper and enable access for your account.
4. Start pairing from the browser extension, enter the short code it displays, review the capture permission, and approve the connection in Productivities.
5. On a page you want to keep, use the extension toolbar button or browser context menu to capture the page, an image, or selected text. A text selection is saved as a Pinboard note with its source page attached.

The Web Clipper is capture-only: it can add new Pins, but it cannot read your existing Pinboard or other workspace content. You can review or revoke paired browsers at any time under Settings → Integrations → Web Clipper.

Smart capture

• Article and reader extraction help turn noisy web pages into material you can read and return to.
• Type-aware cards for media, culture, recipes, PDFs, and work-app links keep the saved item recognisable.
• AI-assisted analysis can summarise or classify supported pins when AI features are enabled.
• Atlassian and Google Drive enrichment can pull useful context into Jira, Confluence, and Drive pins when those integrations are configured.

5.3 Read, annotate and schedule

Pins are not just bookmarks. They can be scheduled, reviewed, read, analysed, attached to tasks, and used as supporting material in Pages. That gives captured material a path from “interesting” to “useful”.

• Use readers and previews for PDFs, articles, images, spreadsheets, Word documents, PowerPoint presentations, comic-book archives, videos, and audio when the saved item needs attention, not just storage.
• Play supported Spotify and SoundCloud items without losing their Pinboard context.
• Mark supported media as watched or unwatched from its card or reader, and use Pinboard views to return to material still in progress.
• Schedule pins into planning views when a reference should become part of a day, such as an article to read before a meeting.
• Move captured pins into the Universal Inbox when they need triage before they become reference material.

5.4 Rediscover saved material Pro

Rediscover is a full-screen review surface that deliberately brings older Pages, Pins, and Highlights back into view. It is useful when saved knowledge should influence current work instead of disappearing into an archive.

• Move through resurfaced material with keyboard or on-screen controls and open supported items in their native reader.
• Exclude individual items or sources that should not return, while keeping the underlying content intact.
• Use Rediscover for broad review; use Highlight Resurface when you want a passage-focused practice.

6.1 Work with structured data Pro

Databases are structured collections shown through tables and other working views inside Productivities. They are useful when a list needs properties, formulas, views, grouping, imports, tags, or record-level links rather than a free-form note.

Use a table when you keep asking the same questions about a set of things: what status is this in, who owns it, what category is it, what date matters, which page describes it, or how should this list be filtered today?

• Typed properties—including text, number, date, checkbox, hyperlink, email, and Pin relationships—plus records, values, formulas, filtering, sorting, grouped views, gallery views, saved views, and linked relationships help a collection behave like a working database.
• Inspect and edit records without losing the current view, duplicate Tables, reorder records, drag-fill repeated values, format values, and insert records or properties relative to the current selection.
• CSV import/export keeps tabular data portable when it needs to move in or out of the app.
• Smart Tables create live, query-driven views of Tasks or Pages inside a Database. Choose filters, sorting, and a result limit to surface exactly the records the view is meant to answer.
• Obsidian .base import support helps bring note-backed datasets into Productivities.
• Row and cell comments support discussion or review around structured data, with empty-cell fallback to row-level discussion.

Customer,Email,Website,Active,Start date,Annual budget,Notes
Northwind,[email protected],https://example.com,true,2026-08-01,1250.50,"Priority account, review monthly"
Contoso,[email protected],https://example.org,false,2026-09-15,900,"Sam said ""follow up in October"""

6.2 Connect your work visually Pro

Canvas is a free-form visual workspace for thinking spatially. It can hold sticky notes, text, shapes, frames, edges, groups, and references to Productivities objects.

Canvas is useful when a list hides too much. Planning a project, mapping research, sketching a system, or connecting ideas often requires seeing proximity, clusters, gaps, and relationships.

• Use frames to group ideas and create visual sections when the board starts to grow.
• Link canvas nodes to tasks, pages, pins, tables, People, and other work objects so the visual map stays connected to the actual work. People cards can show portraits and open the associated profile.
• Use zoom, pan, selection, edges, thumbnails, and grouping to manage larger boards without losing orientation.
• Export a complete Canvas or the contents of an individual frame as PNG or SVG when the visual needs to be shared or used elsewhere.

6.3 Collect information with Forms Pro

Forms are reusable capture experiences backed by Databases. The designer lets you arrange instructions and validated fields without exposing the response table to the person completing the Form. Every submission becomes a structured response row that remains available for filtering, formulas, review, and connected workflows.

• Build Forms with short and long text, numbers, dates, checkboxes, single- and multiple-choice fields, instructions, required rules, defaults, and reusable choices sourced from Database columns.
• Drag fields into order, preview the fill experience, archive fields without destroying earlier response data, and choose a Page to show after a response is saved.
• Organise Forms with groups, Spaces, tags, filters, and saved views; schedule a Form or add it as a linked task when completion belongs in the plan.
• Open the connected response Database when submissions need analysis, or link a Form to a routine so a valid response can record that routine's completion.

6.4 Keep track of people Pro

People keeps relationship context close to the work without reducing a relationship to a task list. Each Person can hold contact details, structured addresses, social profiles, relationship notes, important dates, tags, groups, Spaces, an interaction timeline, and links to relevant workspace objects.

• Browse People as a list or portrait-led gallery, group related contacts, filter the collection, and preserve recurring perspectives as saved views.
• Record calls, emails, meetings, messages, notes, and other interactions; optionally update the last-contacted date at the same time.
• Review related tasks, Pages, Pins, and events from the Person, then create a follow-up task that already carries the relationship context.
• Assign People to Spaces and tags from cards or detail views. Space dashboards can expose the People associated with that project, client, or area.
• Export People when relationship data needs to move elsewhere, and add or edit People directly from supported Canvas cards and pickers.
• People also participate in global search, the workspace graph, the prd CLI, agent tools, and explicitly granted Plugin API capabilities.

Contact details and private notes are treated as a separate permission boundary in external tool surfaces. A connection that may list Person summaries does not automatically receive email addresses, phone numbers, locations, birthdays, or notes.

6.5 Make Spaces repeatable with Routines

Routines is a Space artefact, not a standalone tool or a separate system object. Add the artefact when a Space represents something that needs a repeatable cadence: a weekly review, an ongoing project, a health practice, household maintenance, or a creative workflow.

The Space provides the context; its Routines describe the actions that keep it operating. This effectively turns the Space into a system while keeping its recurring work beside the relevant Tasks, Pages, People, Forms, Outcomes, and other artefacts.

• Add Routines from the Space's artefact controls to reveal its dedicated Routines tab.
• Create an activity-completion Routine on Free. Connecting a Routine to a Form requires the Pro Form capability.
• Choose a daily, weekly, or monthly cadence, scheduled days or intervals, morning/evening/anytime placement, an optional time and duration, and a completion target.
• Use completion history, heatmaps, rates, and streaks to see whether the Space's recurring work is actually happening.
• Log today’s outcome from the Routine itself or from an Action Panel card, and use a Daily Journal action when the completion should add a written record.

6.6 Discuss and review changes Pro

Comments are shared-ready threads attached to objects such as tasks, page blocks, canvas nodes, table rows, and table cells. Activity provides a unified history surface for what changed across the workspace.

This matters because work often needs explanation, not just state. A comment can hold the decision behind a task, the review note on a table row, or the discussion around a canvas idea. Activity then gives you a way to see movement across tools without checking each one separately.

• Use comments for object-specific discussion, review, and decision notes where the context should stay attached to the item.
• Use Activity to inspect recent changes and cross-surface work history when you need to understand what moved.
• In shared deployments, these features become the backbone for collaborative review without splitting discussion by tool.

7.1 Protect time for Deep Work Pro

Deep Work is a distraction-reduced workspace for focus sessions. It is designed for the moments when the problem is not knowing what to do, but staying with it long enough to make progress.

It can hide normal navigation, persist focus state, support a companion window, track sessions, and use macOS app blocking where available.

• Start a focus session from the app controls or command workflows when you are ready to protect a block of attention.
• Use app blocking to reduce access to distracting apps during sessions where environmental friction helps.
• Review focus time later through insights and time-tracking views, so focus becomes something you can learn from rather than just hope for.

7.2 Find and open anything

The Command Bar Pro is the fast path for navigation, quick capture, desktop actions, folder/app launching helpers, clipboard workflows, and AI ask mode. It matters because many productivity systems fail at the moment of friction: you know what you want to do, but the interface makes you go looking for it.

Global search is available on Free and answers a different need: finding a Page, task, Pin, Table, or idea again after it has disappeared into the size of your workspace. Beta 2 searches full Page content as well as titles and metadata.

• Cmd+K opens the command bar.
• Cmd+Shift+F opens global search across workspace objects.
• Cmd+I or Ctrl+I opens the Universal Inbox only when Inbox triage is enabled.

7.3 Automate repeated work Pro

Automations are event or schedule-driven workflows. An automation combines a trigger, optional conditions, and one or more actions that run in the background.

Use them for work that is important enough to happen consistently but repetitive enough that you should not have to remember it every time. They are most useful for maintenance, reminders, organising, and keeping objects in the right state as your workspace changes.

• Use event triggers for Productivities changes such as created or updated objects when the action should follow something that happened in the workspace.
• Use scheduled automations for regular maintenance and reminders when the action belongs to a time or rhythm.
• Trigger flows manually or from changes to Tasks, Routines, Pins, Canvases, Database Tables, and Spaces, then narrow them with conditions based on the event data.
• Actions can update task organisation, add tags, create or update structured data, ask Hably, call a webhook or Zapier, show a desktop notification, and return reusable text output.
• Inspect automation runs and history when debugging behaviour, so the automation remains understandable rather than mysterious.

7.4 Work with Hably and AI Pro

Productivities supports chat-style AI and agentic planning. Depending on configuration, Hably can use local providers such as Ollama and LM Studio or user-supplied cloud connections for OpenAI, Anthropic, Grok, and Gemini.

The useful distinction is between asking for help in the moment and asking for help with a multi-step workflow. AI Chat is conversational and immediate. Agent plans are more structured: they can break work into steps, track progress, pause, resume, and ask for approval before direct actions that need care.

• AI Chat streams assistant responses, retains chat history, and can select configured tools from the request’s intent to work over workspace data.
• Agentic AI creates persistent plans, runs steps, pauses or resumes work, and asks for approval before destructive direct actions.
• Attachments and memory let a conversation work with supplied files and retain deliberately stored context instead of requiring every useful fact to be repeated.
• Provider keys are user-supplied and stored as sensitive settings, so you choose which local or cloud provider powers the workflow.

7.5 Add an Agent to a Space Pro

A Space Agent is a Hably conversation whose context and tool authority are constrained to one Space. It is useful when an agent should understand a particular project or area deeply without treating the whole workspace as one undifferentiated context.

• Add the Agent artefact to a Space to create a dedicated chat surface with persistent, searchable conversations and a resizable history panel.
• Attach images, PDFs, Markdown, text, or CSV files. Attachments and messages remain with the conversation, including in supported Cloud workflows.
• Ask Hably to search and work with the tasks, Pages, Pins, Canvases, Databases, and other content available to that Space, or use /agent to create a scoped multi-step plan.
• Review and manage Space-scoped memory, archive older conversations, and inspect the tools available through /tools.
• Every tool call rechecks the Space boundary, current permissions, enabled features, Private Space state, and approval requirements. A shared or locked Private Space does not silently widen the agent's authority.

8.1 Apple integrations

Native macOS integrations are provided through the desktop shell and a Swift helper where needed. They matter when your personal operating system already includes Apple Calendar, Reminders, Notes, speech, or paste workflows and you want Productivities to work with them rather than duplicate them.

• Apple Calendar can surface local and recurring events through EventKit and combine them with Productivities calendars, helping scheduled work sit beside existing commitments.
• Apple Reminders supports two-way sync between Reminders lists and Productivities Spaces/tasks when Reminders is already part of your capture habit.
• Apple Notes import can bring existing notes into the Pages workflow, including attachment handling where supported.
• Speech and paste helpers support native workflows used by command and AI features.
• Calendar planning lets you move supported tasks and events across days, tune view settings, and snooze items that should return later.

8.2 Google and calendars

Google and calendar integrations are opt-in and connect external events or files to the same calendar, Pinboard, and search surfaces used by local work. The point is not to replace Google services; it is to make their context visible where you plan and review your own work.

• Google Calendar brings connected calendars into the Productivities calendar view alongside local events, routines, time tracking, Apple Calendar, and iCal feeds.
• Google Drive recognises Drive, Docs, Sheets, Slides, Forms, and Drawings links and can enrich captured pins with file metadata and thumbnails where available.
• iCal feeds add subscribed external calendars by URL and can be shown, hidden, tested, or removed from the calendar settings.
• Google OAuth is used for connected Google services and can be disconnected when you no longer want Productivities to access the account.

8.3 Atlassian and work systems

Productivities can recognise work-system links and turn them into richer pins instead of plain bookmarks. Jira Cloud and Todoist connections are delivered through permissioned connector plugins, keeping the connection, granted capabilities, and imported external Tasks visible in one host-managed boundary.

• Jira links can become Jira pins with issue key, summary, status, type, priority, assignee, reporter, labels, description, parent issue, dates, and recent comments.
• Confluence links can become Confluence pins with page title, Space information, ancestors, creator, and update metadata.
• Jira Cloud connector can discover and import authorised issues as externally linked Productivities Tasks after its connection and Task capabilities are approved.
• Todoist connector can discover projects, import tasks, associate them with Productivities Spaces, and keep supported fields and completion state synchronised.
• Connector permissions are reviewed during installation and connection. Productivities brokers credential use and external operations instead of exposing secrets directly to plugin code.

8.4 Git and file-backed work

For Markdown-backed work, Productivities can sit on top of a Git repository so your Pages folder, or another chosen Git root, has visible version control inside the app. This matters if you treat writing, notes, or project files as long-lived material and want history, review, and remote sync without leaving the workspace.

• Status shows branch, changed files, untracked files, ahead/behind counts, and nested repository changes so you can see what has moved.
• Diff and history show working-tree diffs, recent commits, and the files changed in a selected commit when you need to understand or recover changes.
• Repository setup can initialise Git, write a sensible default .gitignore, and configure or remove an origin remote.
• Commit, push, and pull use the user-configured Git repository and normal Git credentials; hosted services such as GitHub, GitLab, Bitbucket, or self-hosted Git work through standard remotes.

8.5 Capture and web services

Pinboard classifies and enriches URLs so saved links keep their useful context when they move into Spaces, tasks, canvas nodes, or search. This helps a saved URL become something you can understand later, not just another unexplained bookmark.

• Web pages and articles can be captured with Open Graph metadata, images, readable content, and AI summaries where Smart Pins are enabled.
• Media services include typed pins for YouTube, TikTok, Instagram, X posts, PDFs, images, video, audio, books, movies, TV shows, and recipes.
• Custom URL classifications let users decide how matching URLs should be treated when Productivities captures them.
• External links remain connected to the rest of your workspace through Spaces, task links, Universal Inbox, global search, and Activity.

8.6 Clipper, CLI, and MCP Pro

External access is split into purpose-built, permission-scoped connections. The first-party interface still uses private /api/** routes, but external tools use the narrower Web Clipper, CLI, Plugin API, or MCP surface designed for that job.

Web Clipper

Productivities provides Chromium, Firefox, and Safari browser clippers. Pair an extension with the installed desktop app, approve the connection in Productivities, then capture a page, image, or text selection from the toolbar or browser context menu. Captures are classified through the same Pin rules as in-app capture, and the clipper closes after a successful save.

A clipper credential can only capture Pins. It cannot list existing Pins, read workspace data, upload local files, invoke CLI commands, or call private application routes.

Productivities CLI

The prd command-line tool pairs through an approval page opened in Productivities. Its credential is stored in macOS Keychain and receives only the scopes approved for that connection.

• Supported workspace commands cover listing, reading, creating, or completing selected Tasks, Pages, Pins, People, and Highlights, plus calendar sync according to granted scopes.
• Native EventKit, Reminders, paste, and speech commands stay local to the Mac and do not require a Productivities server credential.
• Use prd auth login --server <url> to start pairing, prd auth status to inspect the active profile, and prd auth logout to remove it.

MCP Server Preview

The MCP Server Preview lets compatible agents such as Codex and Claude Code use Productivities’ permission-aware workspace tool catalogue over Streamable HTTP. Ordinary tool calls remain stateless. Credentials with Activity access can also discover a workspace event Resource, and clients using MCP protocol version 2026-07-28 can listen for live change hints. It is available for Pro Local and self-hosted installations; Productivities Cloud, OAuth, and MCP Prompts are not part of the current Preview.

1. An administrator enables MCP for the installation in Admin Console → External Connections.
2. The user opens Settings → Integrations → MCP Server and enables personal access.
3. Create a credential, choose its feature allowlist, and optionally grant ordinary write access. Automation authoring has a separate management permission that also requires ordinary write access.
4. Copy the token when shown and configure the client with the absolute /mcp endpoint displayed by Productivities. Only the token hash is retained, so the original cannot be shown again.

Credentials are user- and workspace-scoped, can expire or be revoked immediately, and retain a snapshot of the features selected at creation. Read-only is the default. Ordinary write access allows normal mutations and recoverable moves to Trash, but never permanent purge, destructive or approval-gated tools, administration, credentials, device controls, Hably memory or plan orchestration, nested-model research, or unrestricted network access.

Connect Codex

export PRODUCTIVITIES_MCP_TOKEN='the-one-time-token'

[mcp_servers.productivities]
url = "http://127.0.0.1:9753/mcp"
bearer_token_env_var = "PRODUCTIVITIES_MCP_TOKEN"

Connect another Streamable HTTP client

{
  "mcpServers": {
    "productivities": {
      "type": "http",
      "url": "http://127.0.0.1:9753/mcp",
      "headers": {
        "Authorization": "Bearer <TOKEN>"
      }
    }
  }
}

Use the endpoint displayed in Productivities if its host or port differs from these local examples. Reconnect the client after changing feature or write permissions so it refreshes tools/list.

Follow workspace changes

Select Activity when creating the credential to expose the workspace_event_stream Resource and the get_workspace_events replay tool. Modern clients can subscribe for a prompt hint when a Task or Space event commits; older clients can read the same Resource and poll the replay tool.

The notification does not contain the event. Keep your own last-processed cursor, call get_workspace_events after each hint, process events in order, and save the returned cursor only after processing succeeds. This makes reconnects and coalesced or missed notifications safe.

See MCP Server API for a modular TypeScript SDK example, the complete event contract, tool catalogue, scope rules, transport limits, and troubleshooting codes.

Use loopback HTTP only for a local client. Non-loopback self-hosted MCP access requires HTTPS and a correctly configured trusted reverse proxy. Browser-origin requests are rejected.

8.7 Desktop, mobile, and remote modes

Productivities can run as a local desktop app, a standalone self-hosted server, a remote desktop client, or an iOS companion connected to a Productivities server. The mode matters because some capabilities depend on where the data, server, native helpers, and interface are running.

• Local desktop starts the bundled server and loads the app from localhost.
• Standalone server serves the same web app for browser or self-hosted use and can use SQLite or PostgreSQL depending on the deployment.
• Remote desktop client connects to a configured Productivities server while retaining the desktop shell where supported.
• iOS companion provides Planner, Tasks, Pages, Pinboard, Spaces, routines, Calendar, global search, Hably chat, named themes, home-screen Quick Actions, and share-sheet capture. It signs in to your own running Productivities server and does not move business logic into a separate mobile silo.
• Mobile access requires Pro, administrator enablement of LAN access, and permission for the current user. For access outside the local network, secure the self-hosted connection with infrastructure you control, such as a trusted VPN or HTTPS reverse proxy.
• System capabilities report which native or server-side capabilities are available, helping the UI explain what can work in the current mode instead of presenting actions that cannot run.

The Productivities server must be online for the iOS companion to work. Productivities Link is a proposed future relay and is not part of the current mobile connection flow.

8.8 Desktop updates Beta

Packaged desktop builds include a signed update client for discovering versioned releases after a channel is published. Updates are a security and compatibility feature available to Free and Pro installations.

• Check manually from Productivities → Check for Updates… or Settings → Workspace → Runtime → Productivities Updates. The app also checks periodically after startup.
• Productivities verifies the signed channel before trusting an update feed, rejects rollback to an older signed channel state, and relies on the release digest and operating-system signing identity during installation.
• An update does not download without approval. After it downloads, choose when to restart so active work, timers, the database, plugins, and the local server can close cleanly.
• Automatic desktop updates apply to the Electron application in Local, self-hosted Remote, and supported remote-client modes; they do not update a separately operated browser-only server. Availability can differ by platform and release channel while the beta rollout is being validated.

9.1 What plugins can add

A plugin is an installable .pr-plugin package. It describes the contribution it wants to make, the Productivities versions it supports, and the capabilities it needs. Productivities validates that declaration before the plugin can be installed or run.

Productivities renders all of these surfaces. A plugin supplies structured declarations and command results rather than inserting its own HTML, CSS, menus, or application code into the main window.

9.2 Availability and compatibility

The plugin platform is available on Free and Pro without a numeric installation limit. That does not make every plugin or every Productivities capability free: a plugin can require Pro, and it can use only the features available to the current user.

The developer preview runs in Local and self-hosted deployments. Productivities Cloud plugin execution, open community submission, general-purpose plugin interfaces, and durable background-event delivery are not available in this preview. The desktop app does support owner-only sandboxed-web Space artefacts for declared custom views. Plugins still have no arbitrary network access, but connector contributions can make bounded provider requests through Productivities using declared HTTPS destinations, methods, and host-owned credentials.

Ready

The plugin is compatible and all required capabilities are available and granted.

Limited

The plugin can run, but an optional capability is unavailable or has not been granted.

Needs permissions

One or more required capabilities still need approval.

Unavailable

A required Productivities capability is not available for this user, plan, or deployment.

Incompatible

The package requires a different Productivities or Plugin API version.

9.3 Install and enable plugins

1. Open Settings → Plugins and turn on Plugins in the Settings sidebar. On a local installation, the application administrator’s first enablement also starts the plugin runtime.
2. Use the Install tab to choose a verified plugin from the signed Productivities catalogue. Developers can instead select a local .pr-plugin package.
3. Open the installed plugin’s card and review every requested capability and the reason supplied by the publisher.
4. Grant the required capabilities and only the optional capabilities you want the plugin to use, then enable the plugin.
5. If the plugin contributes a Space artefact, open that Space’s settings and enable the artefact there. Plugin Quick Actions appear in the Action Panel and can be pinned to the Action Bar in Manage mode.

Catalogue packages are checked against a signed catalogue entry and package digest. Local developer packages are labelled unverified, begin disabled, and receive no capability grants automatically.

Install developer packages only when you trust their source. Sandboxing limits a plugin’s authority, but granting a write capability still authorises it to change the corresponding Productivities data.

9.4 Permissions and data access

Permissions are capability-based. Required permissions block enablement until they are granted; optional permissions let the rest of a plugin continue in a reduced mode. Productivities checks the capability again on every host operation, alongside the current user’s plan, feature access, workspace identity, and normal object permissions.

• Plugin settings are private to the current account and are rendered and saved by Productivities.
• Private Spaces and People visible only through them are not exposed through the plugin host, and encrypted Page content cannot be read or changed by a plugin.
• Person summaries omit email, phone, location, birthday, and notes unless the separate people.readDetails capability is granted.
• Connector credentials remain encrypted and are injected only into provider requests approved by the connector declaration.
• Revoking a capability or disabling the plugin takes effect before its next host operation.
• A plugin cannot use a hidden internal route to bypass plan entitlements or normal Productivities access checks.

9.5 Runtime safety

Executable plugin logic is compiled into a WebAssembly Component and runs in a disposable, resource-limited worker on the authoritative Productivities server. It receives a small, versioned host interface rather than a session, API key, database connection, or Electron bridge.

• No ambient access: component code has no direct filesystem, network, database, environment, process, browser DOM, credential, or Productivities session access. A sandboxed view controls only its own opaque-origin document, and connector traffic crosses a separately checked host broker.
• Host-owned interface: menus, forms, settings, collections, notifications, and object navigation are rendered from validated declarations by Productivities. A declared custom Space view runs in an opaque-origin, script-only iframe with a narrow browser SDK.
• Bounded execution: command duration, memory, messages, results, operation count, concurrency, rate, and storage are limited.
• Failure isolation: repeated runtime failures quarantine and disable the installation until it is reviewed and manually enabled again.
• Auditable diagnostics: Productivities keeps sanitised invocation and runtime events inside the workspace. Administrators can inspect, copy, refresh, or clear them from the plugin card.

9.6 Build a plugin Developer preview

Plugin API v1 uses TypeScript for authoring and the @productivities/plugin-sdk build tool to produce a WebAssembly-based .pr-plugin package. A project contains plugin.json, tsconfig.json, and src/index.ts.

npm install --save-dev @productivities/plugin-sdk
npx productivities-plugin build .

The build checks the TypeScript, bundles the SDK, disables ambient WASI features, validates the component imports, and writes the distributable package under dist/. The package can then be installed from Settings → Plugins → Install for local testing.

Manifest essentials

• Use manifest version 1, a stable reverse-domain plugin ID, SemVer version, publisher details, and explicit Productivities and Plugin API engine ranges.
• Declare a WebAssembly Component runtime and every required or optional permission with a short, user-facing reason.
• Declare commands first, then place them in Task, Page, Space, or Person context menus, configurable Action Panel Quick Actions, supported artefacts and panels, or connector handlers.
• Use the typed SDK for capability discovery, Task/Page/Space/Person operations, paginated optimistic storage, brokered provider requests, external Task and Highlight sync, diagnostics, notifications, and host-owned navigation.
• For a custom Space interface, declare a sandboxed-web artefact, its HTML entrypoint, supported intents, and every packaged file under ui.assets. Copy the SDK’s view-sdk.js browser module into those declared assets.

Sandboxed views and data packs

Use a sandboxed view only when the host-rendered forms, tables, collections, and panels cannot express the interaction. The host owns the surrounding title bar and runs the view with scripts only: no application DOM, cookies, filesystem paths, Electron bridge, arbitrary network, navigation, popups, downloads, forms, or eval. connectPluginView() establishes a nonce-bound channel for the limited browser API documented in Plugin SDK API.

• The boot context supplies the current owned Space, a declared intent, locale, semantic theme tokens, accessibility preferences, and verified resource handles.
• Large immutable assets can be declared as versioned data packs with a licence, exact byte size, SHA-256 digest, media type, and either a packaged fixture or HTTPS catalogue URL. Productivities owns disclosure, resumable download, integrity checks, activation, updates, rollback, and local Range serving.
• A Quick Action can use a space configuration field constrained to one of the plugin’s Space artefacts. The saved action receives the stable Space reference through context.input and can return api.ui.openContribution() with a declared intent.

See Plugin SDK API in Reference for every public SDK operation, its required capability, and its behaviour. API v1 is experimental; package formats and contribution types may evolve before community submission and Cloud execution become generally available.

9.7 Updates and troubleshooting

Verified catalogue plugins show an Update action when a newer compatible version is available. Developer packages can be updated by choosing a newer .pr-plugin with the same plugin ID. Updates preserve the installation, settings, stored data, diagnostics, enablement, and permissions that the new manifest still declares.

Earlier retained versions can be selected under Package lifecycle and restored with Rollback. Rollback keeps settings and plugin data. Uninstall is different: it removes the installation, grants, settings, stored data, diagnostics, invocation history, and enabled Space artefact bindings.

A plugin will not enable

Open its card and check compatibility, required permissions, plan or feature availability, and whether the plugin runtime is enabled for the installation.

A command or artefact is missing

Confirm that the plugin is enabled and Ready or Limited. For a Space artefact, also enable it in that Space. For a Quick Action, check the Action Panel and its Manage view.

A plugin stopped after repeated errors

Review Diagnostics for the stable error code and recent events. Manual re-enablement clears a failure quarantine; update the package first if a fixed version is available.

The catalogue is unavailable

Existing compatible installations can still be managed. Check the server’s network access and try refreshing later before installing or updating a catalogue package.

Cloud mode reports unavailable

The developer-preview runtime currently supports Local and self-hosted execution, not Productivities Cloud.

10.1 Users and permissions

The first user becomes an administrator. Administrators can manage users, roles, groups, feature permissions, server-level settings, and the installation-wide availability of external connections such as the CLI, Web Clipper, and MCP. In a single-user desktop setup this may stay mostly invisible; in shared or server-style deployments it becomes the control layer for who can see and use what.

• Roles separate normal users from administrators so operational controls are not available to everyone by default.
• Per-feature ACLs control access to tools such as tasks, pages, pins, AI, canvas, tables, command bar, and integrations.
• User groups support shared Spaces and multi-user access patterns when work belongs to a group rather than one person.
• External connection policy lets an administrator keep CLI, Web Clipper, MCP, mobile, or third-party connections unavailable until the installation is ready to accept them.
• Admin Console is the operational surface for these controls.

10.2 Licensing

Feature access is enforced on the server as well as reflected in the interface. This means hidden buttons are not the security boundary; API routes still check whether the current installation and user may use the feature.

For a user, licensing usually shows up as “why can I see this feature?” or “why is this feature unavailable?” The answer can involve the plan, the user’s permissions, and the deployment mode.

• Plan tiers decide what the installation is entitled to use.
• User permissions decide which enabled features a specific user can access.
• Signed tier state prevents simple local database edits from unlocking gated features.

10.3 Backups, restore, trash

Productivities includes operational safety nets for local-first data. These features matter because a personal operating system becomes valuable only if you trust it enough to keep important work there.

• Backups can be scheduled, retained, listed, validated, and restored when you need recovery points.
• Restore uses a pending-restore flow so the app can restart cleanly around database replacement.
• Trash provides unified soft-delete and restore flows for supported object types, giving accidental deletion a safer path.
• Retention cleanup keeps backups and trash from growing forever.

10.4 Server operations

Server-style deployments can use SQLite or PostgreSQL, session cookies, scoped external credentials, optional LAN access, HTTPS configuration, background schedulers, and job health reporting. These controls are mostly about making the product understandable as an operated service rather than just a desktop app.

• The server binds to loopback by default; LAN access is explicit.
• Background jobs cover backups, calendar refresh, reminders sync, Todoist sync, automations, notes indexing/sync, trash cleanup, and related maintenance, so recurring work can be observed.
• Operational logs live in the Productivities application-data area for packaged desktop builds.

11.1 Default privacy posture

The local desktop app stores your data on your machine by default. Network access is only needed for deliberately online features such as cloud AI providers, OAuth integrations, feed subscriptions, metadata fetching, or remote/server operation.

This matters because Productivities is designed for personal operating data: tasks, pages, plans, references, routines, and project context. The default posture is that this material starts locally, and online behaviour should come from features you intentionally configure.

• Pages are plain Markdown files, so authored knowledge remains portable.
• The default structured data store is SQLite, which supports local-first use.
• Media files remain on disk in user-controlled folders.
• Ollama can keep AI workflows local when you want local model use instead of a cloud provider.

11.2 Authentication and scoped credentials

Productivities uses session cookies for first-party interfaces and separate, purpose-bound credentials for external tools. The private /api/** transport is not a supported general scripting API: use the paired prd CLI, capture-only Web Clipper, brokered Plugin API, or scoped MCP Preview according to the workflow.

• Passwords are hashed.
• Sessions use signed HttpOnly cookies.
• CLI, Web Clipper, and MCP credentials are displayed once, stored as strong hashes, restricted to one user and workspace, and can be revoked independently.
• CLI and Web Clipper pairing opens Productivities for an explicit permission review. MCP begins read-only and requires a separate ordinary-write grant.
• Every request rechecks the credential, current feature state, plan, user permission, workspace, and transport scope, so a previously issued token cannot bypass a later policy change.
• Legacy unrestricted API keys are being retired and should not be used for new integrations.

11.3 Private Spaces

Private Spaces encrypt supported Pages, Tasks, Canvases, Tables, Pins, and managed media at rest, then require an unlock before their contents are visible. This is useful for sensitive areas inside an otherwise everyday workspace, especially when one installation holds both ordinary work and more private material.

Private Space content is protected with authenticated AES-256-GCM encryption. Productivities generates random 256-bit Space keys, derives a separate key for each encrypted object with HKDF-SHA-256, and uses Argon2id to derive the password key that protects the encryption master key. Managed media uses the same AES-256-GCM algorithm in independently authenticated chunks.

Create and store the recovery key when a Private Space is set up. Productivities cannot recover encrypted content without the Space password or recovery key. The older model of locking individual objects has been retired in favour of the Space-wide boundary.

Sensitive settings such as provider keys and OAuth tokens are encrypted at rest.

11.4 Network behaviour

Network activity depends on enabled features. Examples include metadata fetching for Pins, AI provider calls, OAuth-backed services, calendar feed refresh, connector sync, Google or Atlassian enrichment, paired browser capture, MCP clients, and remote or mobile connections.

If you are trying to understand what might leave the device, start with the features you have enabled. A local Markdown page does not need the network; a Google Calendar connection, cloud AI request, or Jira enrichment does.

• Native macOS permissions are requested only for integrations that need them, such as Calendar, Reminders, Speech, or automation helpers.
• Outbound fetches for user-provided URLs use safer fetch paths intended to reduce SSRF-style risks.
• The local server binds to loopback by default. LAN access and self-hosted exposure are explicit administrative decisions, and non-loopback MCP access requires HTTPS.
• Packaged desktop builds harden the Electron runtime and keep development tools gated away.

12.1 Shortcuts

Shortcuts are intended to reduce friction around common actions. You do not need to learn them all at once; start with command bar, search, and Inbox if those are part of your daily workflow.

• Alt+Q opens the Action Panel by default. You can change this binding in Settings.
• Cmd+K opens the command bar.
• Cmd+Shift+F opens global search.
• Cmd+I / Ctrl+I opens Universal Inbox when the feature is enabled.
• Return opens the selected Inbox pin during review.
• Arrow keys navigate Inbox review where supported.

12.2 File locations

These locations matter when you want to back up, inspect, move, or troubleshoot your local workspace. Productivities separates app data from user-chosen content folders so database state, Markdown pages, and media can be understood independently.

• Application data: ~/Library/Application Support/Productivities/ on macOS, or %APPDATA%\Productivities on Windows.
• Default database: productivities.db inside the application-data folder.
• Pages: the Markdown folder chosen during setup or in Settings.
• Media: image, PDF, video, and audio folders chosen in setup or Settings.
• Logs: application-data logs for packaged desktop troubleshooting.
• CLI profile metadata: ~/.pr/config.json. The paired prd bearer is stored separately in macOS Keychain, not in this file.

12.3 Troubleshooting

When something behaves unexpectedly, first ask which layer is involved: plan access, user permission, local/native capability, integration credentials, or runtime mode. Most confusing problems become easier once you know which layer is responsible.

A feature is missing

Check plan entitlement, user permissions, Settings visibility, and whether the runtime mode supports the native capability.

Calendar or Reminders are not syncing

Check macOS permissions, integration settings, and whether the native helper is available in the current mode.

AI is unavailable

Check provider configuration, the user-supplied key for a cloud provider, Ollama or LM Studio availability for local use, and feature permissions.

Remote mode behaves differently

Check system capabilities and avoid assuming desktop-only helpers exist when connected to a remote server.

Mobile cannot reach the workspace

Confirm the Productivities server is running, LAN access and the user's mobile permission are enabled, and the iPhone can reach the configured server URL. Outside the LAN, verify the VPN or HTTPS reverse proxy you operate.

A Web Clipper or CLI pairing does not complete

Confirm the relevant server-wide connection is enabled, Productivities opened the approval screen, and the current user approved the requested scopes. Revoke an abandoned connection and pair again instead of copying a legacy API key.

An MCP tool is missing or denied

Check installation-wide and user MCP enablement, credential expiry or revocation, ordinary-write scope, selected feature snapshot, current plan and ACL state, and whether the client reconnected after a permission change.

A plugin is unavailable or missing an action

Check Settings → Plugins for compatibility, required grants, enablement, runtime health, and deployment support. Space artefacts must also be enabled in their Space; plugin Quick Actions appear in the Action Panel.

12.4 Glossary

Productivities uses these terms consistently across the app and documentation. This alphabetised reference explains what each one means in the context of the product, including places where an older interface label may still appear.

12.5 Plugin SDK API API v1

This reference covers all 48 public component API v1 operations exported by the current SDK, followed by the separate browser API for sandboxed Space views. Command handlers receive the typed api object as their second argument. Await domain, storage, and connector operations; build declarative interface effects synchronously and return them in the command result. A component host operation fails with PluginApiError, whose stable code can be used for controlled error handling.

Registration, context, and capability discovery

Context-menu surfaces provide a matching context.task, context.page, context.space, or context.person snapshot. Quick Actions have no object context. Connector handlers use the connector surface and receive context.connection with an opaque connection ID, connector ID, and non-secret configuration; credentials are never included.

A context snapshot reflects the object selected when the command began. Call the relevant get operation when the handler needs the latest stored state.

Task operations

Page operations

Space operations

People and interaction operations

Connector and external synchronisation operations

Connector and external Task operations require an active connector invocation and connection context in addition to their capability grants. They are not general-purpose network or Task-import APIs.

Namespaced storage operations

Diagnostics and interface effects

Diagnostic methods accept a stable event code plus either structured fields or a message and fields. They are write-only, sanitised by the host, and capped per invocation. A command may return at most ten validated interface effects; Productivities owns their rendering and navigation.

Sandboxed Space view browser API

Package the SDK’s view-sdk.js as a declared UI asset and import connectPluginView() from the view entrypoint. It resolves to a PluginViewApi over the nonce-bound MessagePort supplied by the desktop host. Calls fail with PluginViewApiError; the view has no component command context and cannot call connector, Task, Person, workspace-storage, diagnostics, or arbitrary navigation APIs.

Sandboxed view calls are JSON-only, limited to 64 KiB per message and 240 server operations per minute per installation and user. Productivities also caps the browser module at 64 pending calls.

12.6 MCP Server API MCP 1.2 Preview

The current public MCP catalogue contains 97 tool definitions across 16 feature families. Each client sees only the subset permitted by its credential’s feature snapshot, read/write scopes, the user’s current plan and feature access, normal workspace ACLs, and the deployment mode. Tool discovery is therefore authoritative for that connection: if a capability is not returned by tools/list, the client cannot call it.

Protocol and endpoint

Workspace event Resource

A credential that includes Activity access can discover one workspace-specific Resource named workspace_event_stream. Its URI follows productivities://workspace/<workspace-public-id>/event-stream. Reading the Resource returns the current event-stream head:

{
  "schema_version": 1,
  "current_cursor": "1842",
  "occurred_at": "2026-09-06T13:30:00.000Z",
  "aggregate_types": ["task", "space"],
  "replay": {
    "tool": "get_workspace_events",
    "cursor_argument": "cursor",
    "semantics": "strictly_after"
  },
  "notification_delivery": "best_effort"
}

The Resource is a stream head, not a feed of event payloads. With MCP protocol version 2026-07-28, subscriptions/listen sends notifications/resources/updated after a supported Task or Space event commits. The notification contains the Resource URI only.

1. Read the Resource and store its current_cursor as the starting checkpoint.
2. Open a listen subscription for the Resource URI, then immediately replay after the starting checkpoint to close the small read-before-listen race.
3. After each update hint, call get_workspace_events with your last successfully processed cursor.
4. Process pages in ascending order until has_more is false. Store next_cursor only after the page has been processed successfully.
5. On reconnect, resume from your stored cursor. Treat notifications as best-effort and the cursor replay as authoritative.

Each event includes a cursor, globally unique event ID, event type, stable public Task or Space reference, source, optional correlation and causation IDs, schema version, bounded change data, and occurrence time. It does not expose internal actor IDs, source-local IDs, database IDs, complete entity snapshots, or private audit data. Re-read the current object through an authorised tool when you need canonical state.

Productivities does not store checkpoints for external MCP consumers. Notifications can be duplicated, delayed, coalesced, or missed during a disconnect, so consumers must tolerate duplicate processing. Only one live listen stream is allowed per credential. Expiry, revocation, MCP disablement, or loss of Activity, plan, feature, or ACL access closes the stream before another hint is sent.

A Resource update wakes only the connected MCP host. Whether that host runs or schedules an agent is controlled by the host. Use Productivities Automations when a reaction must run persistently inside the workspace.

Use the modular TypeScript SDK

New TypeScript integrations should use Node.js 20 or later and the official MCP SDK v2 modular packages. A client imports from @modelcontextprotocol/client; do not use the legacy monolithic @modelcontextprotocol/sdk/* import paths in new code. Existing Codex and Claude Code configuration does not change.

npm install @modelcontextprotocol/client@2

import {
  Client,
  StreamableHTTPClientTransport,
} from '@modelcontextprotocol/client';

const endpoint = new URL(process.env.PRODUCTIVITIES_MCP_URL);
const client = new Client(
  { name: 'my-productivities-client', version: '1.0.0' },
  { versionNegotiation: { mode: { pin: '2026-07-28' } } },
);
const transport = new StreamableHTTPClientTransport(endpoint, {
  requestInit: {
    headers: {
      Authorization: `Bearer ${process.env.PRODUCTIVITIES_MCP_TOKEN}`,
    },
  },
});

await client.connect(transport);

const { resources } = await client.listResources();
const stream = resources.find(item => item.name === 'workspace_event_stream');
if (!stream) throw new Error('Activity access is required');

const headResult = await client.readResource(
  { uri: stream.uri },
  { cacheMode: 'refresh' },
);
let cursor = JSON.parse(headResult.contents[0].text).current_cursor;

async function processEvent(event) {
  // Apply the event idempotently in your app.
}

async function saveCheckpoint(value) {
  // Persist the cursor in your app's durable storage.
}

async function replayEvents() {
  let page;
  do {
    const result = await client.callTool({
      name: 'get_workspace_events',
      arguments: { cursor, aggregate_types: ['task', 'space'] },
    });
    page = result.structuredContent;
    for (const event of page.events) await processEvent(event);
    if (page.next_cursor) {
      await saveCheckpoint(page.next_cursor);
      cursor = page.next_cursor;
    }
  } while (page.has_more);
}

let replayQueue = Promise.resolve();
const scheduleReplay = () => {
  // A later hint retries from the unchanged checkpoint after a failed replay.
  replayQueue = replayQueue.then(replayEvents, replayEvents);
  return replayQueue;
};

client.setNotificationHandler('notifications/resources/updated', message => {
  if (message.params.uri === stream.uri) void scheduleReplay();
});

const subscription = await client.listen({
  resourceSubscriptions: [stream.uri],
});
await scheduleReplay(); // Catch changes committed between read and listen.

// On shutdown:
await subscription.close();
await transport.close();

If you are building a server or Node.js adapter rather than a client, SDK v2 also separates those concerns into @modelcontextprotocol/server and @modelcontextprotocol/node. Install only the modules your integration uses.

Credential scopes

Complete tool catalogue

A catalogue name does not bypass Productivities policy. Private Spaces and their otherwise hidden content remain excluded, mutations still use authoritative domain services, and object references use public workspace identities rather than database IDs.

Automation authoring safety

• New MCP-authored Automations always start disabled. Enabling is a separate, explicit tool call so the complete draft can be inspected first.
• Definitions use stable UUIDs and optimistic expected_version checks. Full updates record the previous definition and retain the latest 20 revisions.
• Reads redact restricted action configuration. An existing Automation containing a restricted action can be listed, but cannot be enabled or rewritten through MCP until it uses only the safe action set.
• Recoverable delete and restore are available; permanent purge remains outside public MCP.

Transport security, limits, and audit

• Loopback HTTP is allowed for local clients. Any non-loopback endpoint requires HTTPS, either terminated directly or by a trusted reverse proxy.
• For proxy-terminated TLS, forward the original Host and X-Forwarded-Proto: https, strip client-supplied forwarding headers, restrict direct upstream access, and set PRODUCTIVITIES_MCP_TRUST_PROXY=true. Set this only when every request crosses that trusted proxy.
• The endpoint rejects browser origins and validates the Host, forwarded scheme, JSON content type, protocol version, and bearer credential.
• Limits are 1 MiB per request, four concurrent ordinary requests per credential, 120 requests per minute per credential, and one live listen stream per credential.
• Settings records recent tool use with workspace, user, credential, channel, tool, risk, outcome, stable error code, duration, and timestamp. Audits omit secrets, full arguments and results, and raw Page, comment, or memory content.

Troubleshooting codes