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.

Launch detaches by default so the broker does not occupy a terminal. The foreground launcher waits until the detached broker has validated its workspace, bound its loopback port, and registered its session, then prints the URL and background process ID before returning. Use -D or --detach when an explicit spelling helps a script communicate intent. Use -F or --foreground to keep the broker attached for debugging and stop it with Ctrl-C. A startup failure fails the invoking command rather than reporting an uncertain session. The repository's npm start scripts select foreground mode explicitly.

Recover a live URL without starting another broker:

maintctl sessions
maintctl sessions --all-workspaces

The first command selects the configured workspace document. The second finds every compatible session owned by the local user and is useful when a launch used a document path you no longer remember. Each row prints a stable workspace ID, mode, start time, live-reload state, process ID, and exact capability URL. Session discovery omits document paths and workspace contents, rejects unsafe registry permissions and non-loopback URLs, checks process liveness, and completes an authenticated protocol and workspace-identity probe before showing a URL. Graceful broker shutdown removes its record; discovery prunes records for exited processes.

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, and Security remain primary destinations, while the Action Center, repositories, monitoring, schedules, environment files, shared secrets, audit, and shortcut help are nested in an instant Operations flyout. Navigation icons reinforce destination identity, and the Operations chevron remains visible before the flyout opens. 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.

Native selectors and expandable disclosures retain visible chevrons before interaction, then change their hover, focus, and open states. Suggested-value inputs use the same dropdown cue even though they still accept a new value. This applies to filters, policy repository scope, shared-secret destinations, evidence coverage, AI receipts, and the Operations flyout so hidden choices never depend on guesswork.

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.

Catch up, the Unacknowledged summary bucket, or C opens an exact project-scoped review route and focuses the first waiting record. Press J or K to move, S to defer the focused record, O to open its reconstructable detail and audit URL, A to plan acknowledgement, P to plan a pin, or Esc to return to the ordinary project feed. Pointer controls expose the same sequence, the queue reports the focused title and remaining count, and an empty queue keeps a visible caught-up state instead of looking like a failed load.

Summary mode, or M, adds summary=on to the Activity URL and reduces every visible card to one linked headline plus essential state. It works without AI by using source titles. A current AI-generated headline can replace that title after an explicit generation workflow, but editing the underlying activity record immediately makes the generated headline stale and restores the source title. Reload, Back, Forward, and copied links preserve the presentation mode without serializing generated text into the URL.

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. A project-scoped catch-up queue also offers Brief queue, which preselects a bounded set of the next unacknowledged records while leaving the model editable for an eligible small or open model. Summary mode offers Generate headlines for the bounded visible records without a current result, selects entry details for review, and starts from its independently configurable tiny-model 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, purpose, selected-field receipt, prompt hash, provider route, token ceiling, estimate or actual Gateway cost, and regeneration or local recovery action. A summary-mode response must contain exactly one bounded plain-text headline for every selected record in source order. The model sees array positions rather than private entry IDs; Maintainer HQ maps the validated result back to those IDs after receipt. Generated text is rendered as plain text, and neither the raw prompt nor provider error bodies enter the browser response.

Security workspace

The Security page combines normalized Dependabot vulnerability alerts and update pull requests with project context and separate operator-owned state. Every summary bucket is a link to its exact filtered feed. Project, severity, provider state, item type, repository, ecosystem, disposition, age, remediation, acknowledgement, due state, text, and order compose in the URL, while a closed More filters disclosure reports how many advanced filters remain active. Result pagination retains the same revision-bound query.

Catch up opens unacknowledged provider work in focus order. Press J or K to move, O to open details, A to plan acknowledgement, or P to plan a pin. The item URL reconstructs provider evidence, operator state, remediation correlations, private notes, and audit history after reload or browser navigation. Local acknowledgement, pin, disposition, due date, snooze, notes, and explicit alert-to-update linking or unlinking each open an exact plan and never modify GitHub.

Refresh security opens a bounded intake plan before contacting GitHub. A Dependabot alert can be dismissed with a supported reason or reopened from its item dialog, but only after the separate live-read plan and explicit provider confirmation. The result is reread and verified before the private tracker changes; partial or indeterminate outcomes preserve recovery guidance.

Project-owned policy cards select severity, events, overdue age, desktop disclosure, and repository scope. Repository scope defaults to all repositories in the project. Expanding it exposes preserved per-repository checkboxes, so closing the disclosure never discards a draft selection. Matching transitions create deduplicated private Inbox receipts. Desktop delivery remains a separately selected and reviewed action, and Coverage disclosures distinguish successful empty observations from disabled, unavailable, partial, or truncated evidence.

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, Security, 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, activity-entry, activity-editor, security-item, local-triage, security-policy, policy-exception, provider-detail, canonical-secret, secret-distribution-operation, global-search, and shortcut-help 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 a sanitized service response. Modal URLs contain only safe resource identifiers, never form values. Dialogs expose a Copy link control when their reconstructed state is safe to share within the protected local session.

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.

The Shared secrets page separates canonical records from durable distribution operations. Linked summary cards filter all, current, recovery, or undeployed canonical records. Search, status, repository, consumer, and order controls retain their state in the URL. Canonical cards show only identifier, description, canonical revision, declared destination metadata, and latest value-free operation state. Operations can be filtered by status, repository, and canonical identifier, then opened at a stable operation URL with per-destination attempts, categorical failures, timestamps, audit history, verification, and recovery controls.

Press N to open a new distribution, R to refresh the sanitized state, J or K to move through the active list, and O to open the focused canonical record or operation. The same focus style and visible hints used by Security make the catch-up sequence discoverable without requiring the mouse.

The distribution editor starts with an existing canonical record or a new identifier, a transient password control for a replacement value, and default target, environment, and key-name fields. For an environment target, its expanded repository disclosure initially selects every active enrolled repository where GitHub discovery found the exact environment name. Each row exposes a checkbox plus target-level, environment-name, and key-name overrides. Changing one row makes it an explicit draft; closing and reopening the disclosure preserves every selection and override. Select matching, Select all, and Clear remain available for deliberate bulk changes. Repository-level rows omit their environment at plan time.

The disclosure summary always shows its chevron and selected count before it opens. Native target selectors and suggested environment fields retain arrow glyphs in their resting state, so the existence of choices is visible without exploration. Responsive layouts keep these cues beside their labels rather than clipping them into the modal edge.

Review distribution clears the password control as soon as the request is handed to the broker. The next dialog lists the exact repository, target level, environment, key name, current name presence, and canonical change without returning the value. Distribute and verify requires a write session and explicit provider confirmation. Partial outcomes open the durable operation path instead of discarding successful targets; Resume builds an exact plan containing only unresolved targets, while Verify performs metadata reads without a write.

Write boundary

Write mode changes the workspace document, private activity sidecar, eligible local environment permissions, and exact reviewed GitHub secret destinations after the applicable plan and confirmation. Canonical distribution persists recovery state before its first provider write and independently verifies each destination. Individual Dependabot dismissal and reopening retain a separate live-read plan, provider confirmation, verification read, and bounded recovery result in both the dashboard and CLI. Other GitHub and Hookrelay mutations 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.