<p align="center"><img src="docs/icon.png" width="128" alt="Personal Ops Manual icon"></p>

Personal Ops Manual

<p align="center"> <img alt="macOS 26 or newer" src="https://img.shields.io/badge/macOS-26%2B-000000?logo=apple&logoColor=white"> <img alt="Swift 6" src="https://img.shields.io/badge/Swift-6-F05138?logo=swift&logoColor=white"> <img alt="SwiftUI" src="https://img.shields.io/badge/SwiftUI-native-0A84FF"> <img alt="Notarized" src="https://img.shields.io/badge/Developer%20ID-notarized-2DA44E"> <img alt="MCP server" src="https://img.shields.io/badge/MCP-7%20tools-6E56CF"> <img alt="Markdown files" src="https://img.shields.io/badge/data-Markdown%20%2B%20YAML-555555"> <img alt="Version" src="https://img.shields.io/badge/release-2.2.4-blue"> <img alt="MIT license" src="https://img.shields.io/badge/license-MIT-green"> </p> <p align="center"><a href="https://ops-manual.akakika.com/">ops-manual.akakika.com</a> · <a href="https://github.com/aka-kika/personal-ops-manual/releases/latest">latest release</a></p>

A native macOS app and an MCP server over one folder of Markdown pages that describe your setup: machines, services, launch agents, agents, MCP servers, domains, backups, recovery steps. The folder is the truth; the app and the server are two windows onto it. One operator writes, every other agent reads and reports.

• macOS 26 or newer. Swift 6, SwiftUI, XcodeGen, swift-markdown.
• Three columns: categories, pages, reader. Wiki links between pages, "Linked from", agent glyphs, a New and Edit sheet, search, settings.
• mcp/server.mjs: seven tools for any MCP client, read-only on pages (list_categories, list_documents, search_documents, get_document, get_stale) plus an inbox (report_change appends a line, list_reports reads it) so readers can tell the operator what changed. Node 18 or newer.

One page per thing

Every machine, service, agent or domain gets exactly one page, and every page looks the same: one line that says what it is, a few short sections, links to the pages that belong with it, and a last line that says when someone last checked the facts and how.

Pages point at each other with [[links]]. Open a page and the app also shows you which other pages point back at it, so nothing is ever a dead end. At the bottom, a small Frontmatter section shows the page's properties: its category, tags, dates and id.

The manual describes itself

The manual has a page about itself: where the files live, how to connect an agent, and who is allowed to change things. Anyone who opens the folder for the first time can read the rules right there.

Anything you have shipped gets a page too, under GitHub: what it is, where the website and the code are, the latest version, and how to install it. One place to look instead of five browser tabs.

Only the operator writes, and the folder can enforce it

Readers get no page write tools, but an agent with plain file access could still edit a page. scripts/ops-lock.sh closes that gap with the macOS locked flag (the Locked box in Finder's Get Info) on every page and on the folder itself. Every app and agent on the Mac then gets "Operation not permitted" on a write, whatever tool it uses. _inbox/ stays open, so report_change keeps working.

scripts/ops-lock.sh status          # locked or unlocked
scripts/ops-lock.sh unlock          # for the operator; locks again after 30 min
scripts/ops-lock.sh lock            # lock now

The app itself only reads (since 2.4.0): no editing, no new page, no trash. Its one write is the inbox's "Out of date" sections, described below. list_reports also returns lines someone typed into the inbox by hand under malformed, so none go unseen.

Drift: does the page still match the Mac?

A page can list the facts this Mac can confirm under checks: in its frontmatter, one per line, and name its repo and folder:

repo: aka-kika/personal-ops-manual
path: ~/_KIKA_MAIN/_INFRA/apps/ops-manual
checks:
  - app "Personal Ops Manual" 2.4.0 notarized
  - mcp personal-ops-manual
  - port 4319 node
  - launchd com.akakika.socials running
  - cli gh 2.103.3

The Drift row checks them (installed app version and notarization, MCP servers in ~/.claude.json, listening ports, launch jobs, CLI versions) and, for GitHub pages, the latest release and the repo folder. It lists the pages that no longer match, with a score and what drags it down. Each check runs one fixed program with fixed arguments; the page text never reaches a shell.

What is out of date goes into the inbox by itself, once, under ## Out of date: GitHub and ## Out of date: this Mac, placed before the readers' reports. Every line has the report_change shape. A fact that holds again leaves by itself; ticked lines are left for the operator. Drift never edits a page.

The check also runs without the window, for the operator's run and the weekly maintenance:

scripts/opsmanual check     # or: "/Applications/Personal Ops Manual.app/Contents/MacOS/Personal Ops Manual" --check

The app checks when Drift opens, by itself once a day (Settings > General > Drift), and again with the button in the window's top-right corner or Cmd-R. The score card follows the Health page of Cortex (MIT); ideas only, no code copied.

GitHub, MCP, Inbox

GitHub pages show as one A to Z list, a lock or globe before each name and one dot when work is not saved yet; a repo's page shows its branch, uncommitted and unpushed work, latest tag, open pull requests and, when the repo has GitHub Actions, its last build. The data comes from the gh login already on the Mac and local git; the app holds no token. The two MCP categories share one row and one A to Z list (a small person mark on your own servers). A category with no page open shows what lives there, one status line with a small ring, segments or date line, and the newest changes; without an "<Category> overview" page it uses the category's page tagged index. The App Store category reads each app's state from asc status (on sale, waiting for review, in review, pending release, rejected) with days, version and price, when it opens and on Cmd-R. The Inbox row shows the reports inside the app; with no line picked, it shows _inbox/reports.md itself as a page. Pages with status: parked or archived sit under one Parked row.

Install

brew install --cask aka-kika/tap/personal-ops-manual

Or download the zip from Releases, unzip, drop the app into /Applications. Or build it: ./build.sh --install (ad hoc signed, for the machine you build on).

Everything else, from the MCP install lines to the skills, is in the app's Settings and in docs/FIRST-SETUP.md.

Docs

• docs/FIRST-SETUP.md — standing the manual up on a new machine
• docs/PHILOSOPHY.md — why only one agent writes
• docs/HANDOFF.md — the code, how to build, known gaps
• docs/AGENT-ICONS.md — the glyphs and where they came from
• skill/ — the reader skill for every agent and the operator skill for one
• CONTRIBUTING.md — how to build, test, and send a change; LICENSE is MIT

Release

./release.sh builds with Developer ID, notarizes, staples, and zips; --install replaces the installed app, --publish creates the GitHub release. It reads the signing identity from a git-ignored release.env; the script header says what goes in it.

Contributing

Issues and pull requests are welcome; CONTRIBUTING.md has the build steps and the house style.

License

MIT. See LICENSE.