Agent instructions#

Installing or configuring omagma#

A website or repository URL is sufficient to start. Fetch these instructions and the linked setup workflow through their public URLs, then download and verify the appropriate release yourself. Prepare the local folder and private files as part of setup; do not require the user to clone the source or obtain a bundle first. If a local installation already exists, inspect and reuse it.

When the user asks to install omagma on Linux or macOS, connect Gmail accounts or fix setup, read and follow the setup workflow. This is the installation entry point; it does not require installing the skill into an agent's global skills directory. Prefer brew install renerocksai/tap/omagma on Mac and follow macOS installation; use a verified matching native bundle if Homebrew is unavailable. For a Linux bar, prefer a complete matching bundle from the latest release, verify its SHA256SUMS entry and probe the included backend with --version before consent. End users do not need Zig. Build from source only if a compatible asset is unavailable, using the declared compiler pin.

On a new Mac setup, ask which variant the user wants: Interactive (default native Keychain; use the TUI/CLI in a local unlocked terminal) or Agent-enabled (the same binary, with refresh tokens in private owner-only, unencrypted files). Reuse an existing explicit choice during repairs; do not ask again or silently switch stores. Agent-enabled storage avoids Keychain audit-session restrictions, but the agent sandbox must still permit the selected config, grants, cache and credential files and Google network access. It does not grant those permissions automatically. Follow Mac credential setup for fresh authorization or migration of existing grants.

Use agent setup for the handoff and account setup / bar installation for details. Prepare installation and private configuration while the user completes Google registration or consent, and tell them exactly when a browser click is needed. Verify the installed binary, authorization status, mail access and profile links for setup. For agent-enabled setup, run actual live CLI subprocess account/mail/contact reads from the intended agent context; a working interactive TUI alone is insufficient. Fixture tests, automated GUI checks and resource/release qualification belong to development tasks. Linux static bundles still need Chrome and system CA certificates, plus Secret Service when using the default keyring; only the bar needs an Omarchy/Quickshell host. Mac terminal binaries use system libraries. Do not require a bar registration or install Linux systemd units for Mac terminal-only setup. Preserve any existing read-only registration and use a different one for broader terminal access; fresh terminal-only setup uses one registration.

Developing omagma#

Use Zig 0.17.0 exactly, the pin in build.zig.zon. An Omarchy system compiler may still be 0.16.x: use the official archive matching the task's OS/CPU, prepend its extracted directory to the task's PATH, and check zig version. Keep the global compiler unchanged so nested tools inherit the correct task-local compiler. Use -Doptimize=debug for correctness and -Doptimize=safe for release/memory checks.

For local interface iterations, build into a separate development prefix, run focused checks for the changed behavior, and atomically replace the installed executable when the user requests a local update. Keep the application version unchanged. Do not run memory soaks, collect release evidence, or publish a release unless the task calls for qualification or publication. Release qualification remains a separate workflow.

Keep the private feature journal under .local-notes/daily-log/ updated after each completed improvement and release. Append dated entries with stable feature IDs and superseding references when behavior changes; consolidate the current view in current-since-release.md for release notes, social posts and videos. Record release versions and source commits so the baseline is explicit. Keep the journal uncommitted, generic and free of private mail, account details or credentials.

Separate release qualification from publication. Full native checks may run proactively while the user tests the local candidate. A push or version bump does not authorize publication. Wait for an explicit release go-ahead, then promote the successful qualification run's exact artifacts using Publish qualified release. A changed revision needs fresh qualification; never publish stale or expired artifacts or replace a public release. See release maintenance.

Use Ctrl for modified application shortcuts, consistently across the TUI and bar; leave Alt available for desktop shortcuts. Keep Vim navigation and letter alternatives so workflows do not require laptop-dependent Home, End, Insert or function keys. Show the actual contextual shortcuts in buttons/help; printable letters remain data in text fields. Reserve Ctrl+B for Herdr/tmux prefixes. Buttons must be reachable with Tab/Shift+Tab and activated with Enter; file path completion uses Ctrl+F, not Tab.

Use zig build test -Doptimize=debug -Dtest-filter="local UI:" for the account/help regressions, and python3 tests/terminal_local_ui.py --binary /path/to/development/omagma for the corresponding owned-PTY interactions. Omit the filter for full correctness qualification.

All project-authored runtime helpers outside QML/JavaScript must be Zig. Python and Node.js support tests and release packaging, not runtime helpers. Keep the bar's read-only Gmail behavior. Terminal modes may use pinned libvaxis, bounded private persistence and explicitly scoped write capabilities; follow the terminal implementation. Release instructions describe version-driven Linux musl and native macOS qualification, followed by explicitly approved publication without replacing an existing release.

Preserve the bounded design: at most three configured accounts, 30 rows per account, one network worker, one pending job flag per account, bounded frames and a 64-entry UI request ledger. Replace snapshots instead of appending history. Check generations and the active handshake’s account identities. Keep bar mail strings plain text. Terminal HTML-only mail may use the bounded native semantic reader; render sanitized literal spans, never execute markup, controls or remote resources.

Keep OAuth tokens out of argv, logs, IPC and repository files. Default refresh-token storage is Secret Service on Linux and native Keychain on macOS. The explicitly selected file backend uses a private canonical directory and owner-only, unencrypted token files; preserve the user's selected store. The bar does not persist mail. Terminal modes may cache mail and drafts under explicit memory/disk quotas. Do not add shell runtime scripts, unbounded pagination, browser scraping or a unified unread total. Use fixtures for write acceptance until the user provides a dedicated test mailbox; development authorization is not permission to send production mail or change production contacts.

Use synthetic fixtures first. tests/ui_gui.py forces the offscreen Qt platform; automated tests must not map windows, grab the user’s keyboard or edit an installed desktop configuration. Real account, authorization and desktop installation checks need explicit user direction. Do not change package-owned Omarchy files.

Before heavy builds or runtime measurement suites on a shared host, follow the cooperative host measurement lock. Acquire the host-local directory atomically; hold it through child cleanup, and release only your verified ownership token. Keep lightweight editing available while another owner is active.

Run the checks appropriate to the change, as described in verification. debug checks correctness; safe additionally establishes release memory evidence. Receipts must use binary-reported compiler/mode information. Preserve failed measurements and existing acceptance thresholds. State the test platform and distinguish RSS, PSS and application-owned allocation limits. Historical evidence retains its actual compiler version; qualify 0.17.0 separately.

Public examples and captures use fictional accounts and synthetic mail. Never commit tokens, OAuth client downloads, private configurations, real messages or identifiers, personal paths, installation backups, raw local receipts or screenshots containing real mail. Keep public documentation generic and link only public artifacts.