Docs maintenance guide for Screenpipe contributors

How Screenpipe maintainers keep docs synced with product changes, OpenAPI routes, app connections, UI screenshots, and changelog release notes.

Screenpipe moves quickly. Every user-facing change should leave the docs in a better state than it found them.

Release docs checklist

For every release PR or feature PR, check:

Change type	Docs update
New setting or UI flow	Relevant guide plus screenshot if it changes the user path
New API route or parameter	OpenAPI plus API recipes if user-facing
New connection	Connections and connection reference
New scheduled task behavior	Scheduled tasks, scheduled task debugging, or scheduled task permissions
Meeting feature	Meeting intelligence
privacy/security behavior	Privacy data flow and privacy filter
Platform reliability fix	Troubleshooting
Enterprise control	Teams or deployment docs

Validation

Run:

node docs/mintlify/validate-docs.mjs

This checks:

• docs.json is valid JSON
• Every nav page exists
• No MDX page is missing from nav
• Each MDX file has frontmatter with title and description
• Internal docs links point to a known page or public asset
• openapi.yaml contains routes
• The connection registry can be read from code

Screenshot workflow

Screenshots come from app e2e specs:

cd apps/screenpipe-app-tauri
bun run wdio run e2e/wdio.conf.ts \
  --spec e2e/specs/home-window.spec.ts \
  --spec e2e/specs/settings-sections.spec.ts \
  --spec e2e/specs/pipes.spec.ts

Copy selected images from apps/screenpipe-app-tauri/e2e/screenshots/ into:

docs/mintlify/docs-mintlify-mig-tmp/public/app-screenshots/

Then reference them as:

<img src="https://docs.screenpi.pe/public/app-screenshots/home-home.png" alt="screenpipe home" width="1200" />

Ownership map

Area	Owner checklist
Get started	First value, permissions, desktop vs CLI
MCP	Client setup, auth, restart requirements, troubleshooting
API	Generated OpenAPI, tested recipes, auth examples
Scheduled tasks	Lifecycle, permissions, logs, store, publishing
Connections	Registry drift, OAuth, proxy paths, multi-account
Meetings	Transcript, speakers, summaries, calendar context
Privacy	local/cloud data flow, PII, deletion, LAN access
Enterprise	Teams, managed presets, deployment, encryption
Troubleshooting	symptom-first fixes by platform

Drift rules

• If a route is added to code, OpenAPI and docs should mention it or intentionally keep it reference-only.
• If a connection is added to screenpipe-connect, docs must include it in the reference.
• If release notes mention a feature, the durable guide should also explain how to use it.
• If a screenshot changes materially, update the image in the same PR.

Match current product terminology

Use scheduled task in page titles, navigation, prompts, descriptions, and UI instructions. The app uses Scheduled tasks, My tasks, Discover, and NEW; an empty task list offers examples and a creation form.

Keep executable identifiers unchanged: screenpipe pipe, /pipes, pipe.md, configuration keys, and source filenames still use technical names. Explain that distinction in reference material. When renaming a docs route, update internal links and add a redirect so saved links continue to work. Remove or replace screenshots that display retired labels.

Casing, icons, and visual style

Use sentence case for page titles, sidebar labels, headings, cards, and instructions. Preserve product names and acronyms such as Screenpipe, ChatGPT, macOS, AI, API, MCP, and CLI. Write casing in the source; never use CSS text transforms. Keep commands, paths, URLs, configuration keys, code examples, and quoted output unchanged.

Every page needs a short sidebarTitle and a named Lucide icon in frontmatter. Use the shared icons.library setting in docs.json for both navigation and cards. Avoid mixing icon libraries, emoji, and custom integration logos in the sidebar. Check new icon names in the Mintlify preview.

Keep shared colors, fonts, and light/dark logos in docs.json, and reading typography and corner sizes in style.css. Follow the repository design guide: Space Grotesk headings, Crimson Text prose, IBM Plex Mono code, neutral ink and bone surfaces, and 8px surfaces with 6px controls. Check light and dark mode and a narrow viewport before pushing visual changes.

The docs validator checks navigation casing, product names, required page icons, and logo assets. Run bunx mint validate for the full Mintlify build and bunx mint broken-links for link checks.

Review analytics as documentation evidence

Use comparable date windows and exclude partial days when comparing trends. Keep human page views separate from agent requests; repeated llms.txt or page fetches are not unique users or product adoption.

Review unanswered assistant conversations and negative feedback for concrete failed steps. An answered label measures coverage, not correctness or customer resolution. Conversation categories can overlap, and live table totals can differ from the chart’s scope. Cluster incremental search strings into user intents before prioritizing work.

For each fix, record the source-backed answer, affected guide, and a question to retest after deployment. Useful regression questions include:

• Why does the desktop download ask for payment details?
• Does my plan include Claude Pro, or can I use an Anthropic API key?
• Where is Live meeting notes, and does it fix a failed summary?
• What should I do about an invalid bundled Pi compaction patch?
• Can I change the interface to Spanish or record an iPhone?
• How do I verify MCP or Ollama retrieved a real recording?

After publication, check the deployed page and assistant citations. Record answer accuracy separately from whether the original user’s problem was resolved. Keep private analytics and conversation details out of public issues and PRs.

Review and publish generated changes

A generated PR is not a published documentation update. For a failed automatic merge, inspect the actual PR, current base branch, conflicts, required checks, and GitHub merge receipt. Review generated release claims against merged source changes and the relevant release before landing them.

Keep branch protections in place. Use the repository’s authorized review and merge process for changes that cannot merge automatically. Do not broaden an app’s bypass permissions just to clear the automation dashboard. After a merge, verify the Mintlify deployment result and the live page. Track generated, reviewed, merged, and published changes separately.