Dashboard guide

The Maintainer HQ dashboard provides detailed inspection and reviewed local edits over the sanitized workspace snapshot. It shows the workspace name in the header and gives a newly initialized empty workspace a direct path to repository onboarding commands. See the operator guide for CLI workflows and the security model for browser and mutation boundaries.

Launch and session behavior

Open a read-only session:

maintctl launch --read-only

Open a write-capable session:

maintctl launch --write

While changing dashboard assets in a development checkout, keep one functional session URL open and opt into automatic reloads:

maintctl launch --write --live-reload

Live reload watches only the bundled dashboard asset allowlist and sends a change signal over the random loopback session route. It is off in ordinary sessions. A reload preserves addressable page and filter state, but unsaved form fields remain intentionally transient.

The dashboard theme defaults to Auto, follows the system color scheme, and offers persistent Light and Dark choices in the top bar. Time display defaults to a 24-hour clock with seconds and offers persistent 24- or 12-hour choices with or without seconds. These display preferences use same-origin cookies and never enter the workspace document or activity sidecar.

The top-bar Refresh control rereads the sanitized inventory without reloading the browser document. A changed workspace revision clears revision-bound provider history, while a failed refresh keeps the last good inventory available.

The desktop header stays on one row. Overview, Activity, Action Center, and Repositories remain primary destinations, while monitoring, schedules, environment files, shared secrets, audit, and shortcut help are nested in an instant Operations flyout. Narrow screens use an explicit Menu control rather than a clipped horizontal navigation strip.

Press / to search, ? to open the addressable shortcut reference, or press G followed by the displayed destination key to navigate without leaving the keyboard.

Overview and Action Center

The overview leads with work that needs attention, groups repeated findings by the operation that resolves them, and keeps inventory totals below the work queue. Pending capabilities, missing or unverifiable Endpoint Monitor targets, unassociated target identities, recovery gaps, unavailable security features, review-required policy exceptions, due decision re-reviews, broad or uninspected environment files, and cross-repository Dependabot sharing each explain the observed state and recommend the next operator step. An unmanaged capability is neutral rather than incomplete, except that Maintained repositories, stored with the fleet classification value, must retain an endpoint-monitoring assessment.

A write session can accept a durable policy exception through the exact document plan, optionally schedule it for re-review, and return it to review later. A write session can also plan and repair one or several broad live environment files to 0600 directly. Provider history and workspace audits remain explicit reads on their own pages, so an unloaded provider surface is never represented as a successful check.

Overview counters are interactive drilldowns rather than display-only totals. Scope, endpoint-monitoring, recovery, and security counters expose their independent breakdowns and link directly to affected repository records. The monitoring drilldown answers which operated repositories still lack a decision, separates missing target IDs from an unavailable inventory read, and lists target identities that have no repository association. URLs and probe configuration are never loaded into the dashboard.

Press / or use Search workspace to search the sanitized snapshot across operator posture, repository policy, Endpoint Monitor target identities, schedule and loaded provider metadata, environment paths and variable names, and secret-safe identifiers and consumers.

Activity and project progress

The Activity page groups repositories into operator-defined projects and combines explicit project work with normalized delivery evidence. Project cards expose status, target version, repository membership, progress, open work, and event totals. A selected project can be edited, attached to another workspace repository, detached, refreshed, or given a manual update without leaving the feed.

The timeline supports project, type, origin, status, acknowledgement, pin, archive, text, time, and ordering filters. Goals, milestones, decisions, blockers, next actions, notes, and progress updates retain their type-specific state. Commit, CI-run, and release cards link to canonical provider evidence when a safe URL is present. Operator controls can edit manual state, acknowledge, pin, and archive without mutating provider evidence.

Refresh sources opens a plan before reading local Git or GitHub. Apply shows inserted, updated, unchanged, and partial-source results while stable evidence IDs prevent duplicate events on repeated refreshes. Source health remains visible separately from the feed, so an unavailable provider is not mistaken for an empty successful read.

When AI_GATEWAY_API_KEY is absent, the page labels AI as off and leaves every core activity control available. When configured, Summarize opens an explicit checklist of the exact records and fields that can leave the machine. Entry details and repository names are off by default. The next dialog shows the model, eligible zero-retention and no-training providers, output ceiling, conservative estimate, operator cost limit, and complete disclosure before Generate becomes available.

Completed, failed, and interrupted generations appear above the source timeline with their output or bounded error category, selected-field receipt, prompt hash, provider route, token ceiling, estimate or actual Gateway cost, and regeneration or local recovery action. Generated text is rendered as plain text, and neither the raw prompt nor provider error bodies enter the browser response.

Monitoring inventory

The Monitoring page turns the sanitized Endpoint Monitor read into a searchable inventory. It unions observed target IDs with IDs declared by repository monitoring decisions, then classifies each identity as present and associated, present without repository accountability, missing from the available inventory, or unverified because the inventory read failed. Summary controls, coverage filtering, risk and repository sorting, and result counts operate only on this derived identity data.

Every repository association links to the exact endpoint-monitoring decision. Endpoint URLs, expected statuses, response validation contracts, configuration and profile paths, probe output, incident state, and credentials remain outside the browser response. Target creation, editing, deletion, probing, synchronization, deployment, and incident operations continue through Endpoint Monitor's operator CLI.

Repository inventory

Repository inventory supports composed overall status, classification, endpoint-monitoring, recovery, security, CI assessment, visibility, and Dependabot facets plus deterministic name, attention, classification, monitoring risk, recovery risk, security risk, listing, and updater schedule sorts. Public or Private pills and distinct Archived or Deleted markers sit beside each repository name and also appear in schedule lists and repository details. Active records sort before archived records, deleted records sort last, and classification remains independent: Legacy describes operational ownership, while Deleted records that the GitHub repository no longer exists.

A write session can update recorded identity state, add or remove capability intent, record configured CI with its primary workflow path, or select Not applicable and require a repository-specific reason. Deleted state is a historical record, so the editor requires Legacy classification with no managed capabilities or repository secrets; visibility remains the last known GitHub value. Endpoint monitoring can remain pending, associate one or more Endpoint Monitor target IDs, accept a documented risk, or record why monitoring is not applicable. Maintained classification disables unmanaged monitoring and changes an unmanaged selection to pending. Endpoint accepted-risk and not-applicable decisions, listing exclusions, and not-applicable CI assessments offer optional 30, 90, 180, and 365 day re-review shortcuts plus an exact date field.

Private Hookrelay capabilities retain a separate approval after every sink has been reviewed as a privacy boundary, because private webhook payloads can contain non-public repository activity and security details. An unapproved capability is valid pending intent and remains visible in the dashboard, but Maintainer HQ refuses provider access until approval is recorded. Public Hookrelay capabilities do not display this approval.

Routes and navigation

Activity, Action Center, repository, monitoring, schedule, provider-history, environment, and shared-secret searches, facets, and sorts use bounded allowlisted URL parameters. Filtered views survive reload, Back, Forward, copied links, and opening a result in a new tab. Summary buckets and inventory counters link to a corresponding filtered view or routed drilldown rather than behaving as display-only totals.

Repository records and their detail sections have addressable routes such as #repositories/example-org/sample/policy-exceptions. Environment findings and search results also route to one sanitized file path. Monitoring target associations, schedule rows, search results, operator pills, Action Center items, and aggregate drilldowns are standard links to those routes, so they support copying, opening in a new tab, direct loading, and browser back or forward navigation. Security drilldowns include the exact affected feature and approved reason before linking to the focused policy-exception or security section.

Navigable dialogs extend the underlying hash route with a modal query such as #repositories/example-org/sample/scope?modal=update-scope. Repository and activity editors, policy-exception review, provider details, global search, shortcut help, and secret-safe metadata dialogs all follow that model. Opening a dialog pushes a history entry, closing returns to the underlying route, and direct loading, reload, Back, and Forward reproduce dialogs that can be rebuilt from the sanitized snapshot. Modal URLs contain only safe resource identifiers, never form values.

An exact write-review plan receives an in-session modal=review-plan route so closing and browser history remain coherent. Reload or direct loading safely removes that modal because reconstructing it would require persisting an unsaved mutation, including possible one-way secret replacements.

Schedule and provider history

The Schedule page orders every endpoint-monitoring, listing, CI, and policy-exception re-review by due date and shows the exact baseline commit and repository-local diff command. Future reviews remain informational; a review becomes a low-priority Action Center item on its due date and continues to require attention until the decision is updated, rescheduled, or reopened.

The same page orders effective Docker, GitHub Actions, npm, and pip Dependabot updater policy, identifies shared slots, distinguishes paired updaters within one repository from cross-repository sharing, filters by ecosystem or sharing type, and links each repository to GitHub's authoritative update-job logs. Its explicit Load history action queries the supported Actions workflow-runs REST endpoint, restricts the read to configured repositories and the Dependabot update workflow, and caches the sanitized result against the workspace revision for the session. Past runs can be searched, filtered, sorted, and opened for schedule context or their canonical Actions URL.

Raw workflow titles, dependency names, commit messages, logs, actor profiles, and provider error bodies never enter the browser response. GitHub does not include the per-manifest job timeline in its supported Dependabot REST API, so Maintainer HQ does not scrape the web page or rely on an undocumented endpoint.

Environment and shared secrets

Environment and shared-secret inventories provide their own search, filters, sorts, result counts, resets, and metadata dialogs. Environment paths are explicit detail controls, and eligible broad live files expose one-file repair alongside batch repair from the grouped work queue. Every browser-side search operates only on the already sanitized snapshot.

Write boundary

Write mode changes the workspace document and can restrict eligible local environment files after an exact reviewed plan. GitHub and Hookrelay operations continue through their explicit CLI phases and existing confirmation gates. Endpoint Monitor target edits, probes, synchronization, deployment, and incident operations continue through Endpoint Monitor itself; the dashboard edits only accountability and target-ID associations.