Architecture

Maintainer HQ is a local-first application with one active workspace per process. The CLI, loopback dashboard broker, and stdio MCP server all construct the same workspace service with an immutable document path, repository roots, environment roots, adapter configuration, and read or write authority.

CLI -----------+
Dashboard -----+--> workspace service --> private workspace document
MCP -----------+            +------------> private activity ledger
                            |
                            +--> bounded local inventory readers
                            +--> explicit optional provider adapters

Workspace boundary

The versioned JSON document is the source of truth. It carries a stable random workspace ID, a display name, creation metadata, repository records, provider intent, recovery state, canonical secret values, and secret-consumer metadata. The ID identifies the logical workspace but is not a credential. A service instance never switches workspace during a request.

Local 0.x operation has one implicit owner and one workspace per process. A future team service can place authentication and workspace selection in front of service construction, then map the same workspace-scoped operations to another storage implementation. Repository identity, mutation schemas, plan digests, and interface contracts do not depend on a home directory or personal account.

Read and write paths

Reads validate file type, permissions, size, identity, schema, and optional Git encryption before returning a normalized object. Every external interface derives a secret-free projection from that object. Browser and MCP consumers cannot request the raw document.

Local writes produce an exact plan bound to the current document revision and complete requested mutation. Secret-bearing requests retain values only in a bounded, expiring process-local plan store. Apply reacquires the document, validates the plan, obtains the adjacent lock, rereads the revision, and atomically replaces the file. Provider writes also rerun their adapter plan around confirmation and reject changed output.

Adapters

Adapters are explicit capabilities, not generic provider passthroughs. The GitHub audit and reconciliation commands receive private compatibility projections. GitHub secret distribution discovers environment names, reads exact key metadata, and writes fixed Actions targets through a dedicated adapter. Hookrelay receives a private manifest and retains its own phase and confirmation model. Endpoint Monitor contributes only a sanitized target-ID inventory. Adapter absence is a skipped diagnostic unless an operator invokes the dependent capability.

This narrow design preserves useful mature integrations while keeping the core install portable. New providers should expose domain operations with bounded schemas, safe read projections, exact planning, confirmation, verification, and recovery instead of accepting arbitrary commands or API paths.

Interface parity

Every operator capability belongs in src/operator-capabilities.mjs. A non-visual feature is incomplete until its CLI or broker outcome has equivalent purpose-built MCP coverage, tests, and documentation. The parity test rejects undeclared tools, orphan tools, and uncovered mutation kinds.

The dashboard remains a local view over the same service semantics. It binds to 127.0.0.1, uses a random session route and header, serves only bundled assets, and sends no workspace secrets or remote scripts to the browser.

Activity ledger and derived summaries

The activity ledger is a separate private, workspace-ID-bound sidecar because feed evidence changes more frequently than repository policy and can be rebuilt independently. Projects group existing workspace repository identities. Manual entries retain operator state and audit records, while bounded local Git and GitHub readers normalize commits, CI runs, and releases into stable source identities. Idempotent merge keeps corroborating sources together and preserves acknowledgement, pin, and archive state.

Optional AI outputs are derived records, never implicit provider access. A plan binds the activity revision, purpose, selected entries and their timestamps, disclosed fields, model, eligible private providers, token ceiling, pricing snapshot, conservative estimate, and operator limit. Apply revalidates the catalog and revision, persists a pending generation, then routes one request through the AI SDK and Vercel AI Gateway. Briefings persist structured text; summary mode persists an exact ordered array of bounded headlines mapped to private entry IDs only after provider receipt. Terminal records keep output, source timestamps, lineage, prompt hash, usage, and cost while excluding the raw prompt and provider diagnostics. A process-local active set prevents recovery from racing a live request; a later process can explicitly mark an abandoned pending receipt as aborted.

The core feed has no dependency on an AI credential or model response. Its addressable summary presentation can always collapse cards to source titles. Summary planning never calls a model, generation is always separately confirmed, stale headlines are rejected at display time by source timestamp, and retries create new linked records of the same purpose instead of overwriting evidence.

Canonical secret distribution

The workspace owns the canonical value and intended GitHub Actions consumers. The activity sidecar owns a separate value-free secret-distribution domain with operation, destination, attempt, audit, and recovery state. Keeping the operation journal out of the lower-churn workspace lets each provider attempt advance atomically without rewriting the canonical value.

Planning accepts only active enrolled repositories and fixed repository or environment destinations. Environment discovery and preflight metadata reads are bounded and normalized before the plan binds the workspace revision, workspace identity, canonical revision, exact destinations, current key metadata, requested actor, and value-bearing mutation into a process-local HMAC digest. Only the digest and redacted plan leave the service.

Apply refreshes the exact plan, writes the canonical mutation atomically when required, then persists the pending operation before starting any provider write. Destinations execute with bounded concurrency. Each attempt records a categorical result and an independent metadata verification before the operation advances to completed, partial, failed, or indeterminate recovery state. If operation persistence fails, no provider write starts. If later persistence fails after a provider call, recovery still treats that target as unresolved rather than assuming success.

Resume requires the same canonical secret revision and replans only unresolved destinations from the durable record. A later canonical value supersedes recovery from the older operation. CLI, broker, dashboard, headless service, and MCP tools all call this controller rather than implementing their own provider sequence.

Security operations

Security findings share the activity sidecar while remaining provider-scoped records rather than duplicated project records. One stable item can belong to every project containing its repository. A refresh plan binds the workspace revision, activity revision, and selected projects before provider access; apply reads only those repositories and commits the result only if both revisions remain exact.

The GitHub adapter uses fixed commands, host, API version, request limits, response limits, and concurrency. Dependabot alert collections use bounded opaque-cursor pages and individually recheck tracked open findings that disappear from a complete open collection. Dependabot-authored pull requests follow the same tracked-item rule. Canonical URLs are constructed locally, provider failures collapse to categories, and only allowlisted alert, update, filename, and coverage evidence crosses the adapter boundary.

Exact package identity is required for an automatic remediation correlation, and an exact manifest-path match raises its confidence. New automatic links require both the alert and update to be open. A correlated update inherits the highest linked alert severity and remains one provider item. Stable provider fingerprints make polling idempotent while state changes emit project-specific security events into the rolling feed.

Operator triage is a separate local state machine over the normalized provider record. Acknowledgement, pinning, disposition, snooze, due dates, notes, and explicit remediation links bind the activity revision and an authenticated actor into a short-lived plan digest. Apply rereads the ledger, rejects stale revisions or changed plans, appends bounded audit evidence, and leaves provider-owned state untouched. Explicit links override automatic inference, and explicit unlinks survive later refreshes. Provider/operator disagreements and due state are derived at query time so filtering does not rewrite source evidence.

Policy evaluation compares the pre-refresh and normalized post-refresh ledgers before the atomic write. Project and repository scope, minimum severity, selected events, overdue threshold, and policy revision determine each match. Notification IDs hash the policy, item, event, and transition fingerprint, so the inbox, suppression evidence, and refresh state cannot diverge or duplicate under polling. Policy removal is a disabled tombstone because notifications retain their originating policy reference.

Desktop notification delivery is outside passive refresh. An exact selection and privacy mode receives a separate short-lived plan, followed by a fixed platform adapter only after confirmation. macOS uses /usr/bin/osascript with a fixed standard-input program and data arguments. Linux uses /usr/bin/notify-send with an option terminator. Output, execution time, selection size, and message length are bounded; unsupported tools reduce to fixed categories that are persisted with the in-app receipt.

GitHub-owned Dependabot alert state uses a distinct mutation boundary. A dismissal or reopening plan performs one narrow normalized read and hashes the workspace revision, activity revision, local and provider fingerprints, repository, numeric alert identity, target state, and fixed reason. Apply recomputes that plan, requires provider-specific confirmation, sends a fixed PATCH body through standard input, and rereads the alert before local persistence. The provider update and local merge are deliberately separate phases: a timeout becomes indeterminate, a failed verification becomes partial, and a verified provider update that loses a local revision race remains recoverable through ordinary refresh. No response body, dismissal comment, raw diagnostic, credential, or arbitrary provider method crosses the boundary.

Source layout

• src/ contains workspace, schema, service, CLI, MCP, broker, mutation, inventory, and adapter logic
• public/ contains dependency-light dashboard assets with no remote runtime dependencies
• test/ contains unit and integration coverage
• e2e/ contains browser workflows
• scripts/ contains hermetic checks, packaging, clean-install verification, and guarded release tooling
• docs/ contains durable operator and contributor contracts plus the build-time VitePress documentation portal
• wrangler.docs.jsonc defines a separate assets-only documentation Worker without application authority