Plonk: Instructions file for Codex

Agent rules

Rules for AI agents working in this repo.

Layout

• App/ — Swift package, the menu bar app. One type per file, files stay under ~300 lines.
• mcp/ — TypeScript MCP server: src/server.ts compiled to dist/ via npm run build. Keep it a thin proxy; logic belongs in the app. Tests are mcp/test/*.test.js, run against dist/ on the Node test runner with no extra dependencies. Tool description rules are in mcp/AGENTS.md.
• scripts/build.sh — the only build entry point.

Inside App/Sources/plonk/, the pieces that are easy to get lost in:

• Router owns the route table and nothing else: every case is one line to the module that handles it, in a Router+* file of its own.
• AppDelegate.swift is the list of what the app is made of and the order it comes up in, and nothing else. Every module's wiring lives in an AppDelegate+<Module>.swift beside it, which is why none of those stored properties is private: Swift only lets an extension in the same file see that. New behavior goes in the module's file, or in a new one.
• ConfigStore is the only way a setting is written. update clamps and saves it, then didMutate fires and AppDelegate.applyConfig hands the whole config to every manager. Nothing pushes a single field at a manager itself.
• Ink holds the surfaces, the radius and the accent gradient every page draws with, and SettingRows the rows a settings card is made of. Pages compose those instead of spelling out colours.
• Resources/en.lproj/Localizable.strings holds every word the user reads, and the Strings+*.swift files declare the keys that reach it. Views hold keys, never sentences — see "Text" below.
• AppActions is what the UI can ask the app to do: commands, not settings. A setting needs nothing there — update(\.field, to:) writes any field of Config. AppModel holds that config plus the state config cannot answer: what a manager is doing now, what macOS has granted, what is on screen. Views never reach past it.
• ScreenIdentity turns a screen index into the keys config is stored under.
• WindowAccess holds every Accessibility call that reads or moves a window, and WindowManager is its only caller: one decides where a window goes, the other is how it gets there. A window that moves without WindowManager.place seeing it announces nothing. Two other surfaces talk to AX directly and are not behind it — ShortcutGuide walks another app's menu bar and NewWindowWatcher subscribes to window-opened notifications. Anything about a window's frame belongs in WindowAccess; those two do not.