devopstoolsarchitecture

Maria asked the useful question: when Q breaks, would the team know where to look? Gary’s concern is continuity. The answer should begin with recovery contacts, access, and shared procedures, before asking anyone to learn the architecture.

This page is that starting point. The technical maintenance handoff in ops gives the next operator more detail. That handoff was merged on October 16, 2026, through ops PR #20.

Ask Noam, then Laura

Start with Noam. He can get into the machine, has done maintenance on Q, and has run his own OpenClaw instance. He has both access and useful context.

Laura is the backup contact. She has access and could likely investigate in an emergency. Whoever takes the lead can connect to the office Mac Studio through screen sharing or SSH over the tailnet. Ask an existing operator for the approved connection details; this page does not grant access.

Check the tailnet before planning a trip

Unreachable does not mean powered off. In a previous incident, the Mac disappeared from the tailnet and an operator drove to the Broomfield office to investigate. The actual remedy was a tailnet configuration change that someone with admin access could have made remotely from the console.

The lesson is to check remote access before assuming a physical failure. A tailnet administrator should inspect the device’s console record, last-seen information, and relevant access or configuration changes. Host access and tailnet admin access are separate; confirm who has the latter.

If those checks cannot establish or restore access, Gary is the contact for coordinating someone at the office to check power, the office network, or hardware. A physical visit remains an option once the remote possibilities have been checked.

Investigate from the Mac

The Mac already has the tools. It has ChatGPT/Codex and Claude desktop and CLI applications installed. Using an assistant on the Mac over screen sharing is the established maintenance approach.

An assistant running on the Mac can inspect Q’s installation even when Q’s Slack interface is unavailable. Give it the symptom, when it started, and the ops handoff, and ask it to begin with local diagnosis. If one provider is unavailable, another installed tool may help, provided its login and service still work.

The operator guide points to the installed maintenance helper, health checks, and existing deployment and rollback instructions. Use those procedures for a proposed repair, preserve current work, and verify the original failing path afterward. A service starting successfully is only part of recovery if the team still cannot use it.

Find the system that owns the failure

Q spans several systems. The name in Slack or on a review does not tell you which one ran the work.

What failed Where to begin
Remote access to the whole Mac Tailnet admin checks, then office coordination if needed
Q’s Slack conversations OpenClaw gateway, Slack connection, and channel routing
Reviews triggered by new pull requests AWS event pipeline and the Mac’s event consumer, documented in Constructured/ops
Scheduled engineering reviews or auto-fixes The owning scheduler: Claude Routines or OpenClaw, depending on the job

One Q, Two Engines explains this ownership map. The Operator’s Guide to Q explains operating boundaries. The Status Light explains how to communicate availability. Read the relevant piece once the immediate failure is identified.

Keep the handoff in ops

New operating guidance belongs in ops. The October 15 documentation decision is to use Constructured/ops, with docs/q/ for the overall handoff and detailed component procedures beside their code. Cairns remains the readable starting point.

The older shared-doc material referred to as doc-shares/doc-vault is legacy reference. It can explain earlier decisions, but it is not the default home for new Q operating material and should be checked against the current system. This decision does not disable existing prompt exports or change which sources QMD indexes; putting a new guide in git does not automatically make it indexed.

This is a team maintenance guide. The recovery contacts identify who can help; they do not designate a service owner. The first version draws on the team’s maintenance discussion and the installed procedures. Noam and Laura have not yet independently walked through a recovery using it. A useful next check is to confirm backup access, identify the available tailnet admins, and verify the office-access path. Maria can help coordinate that check without needing to maintain the technical instructions herself.

  1. Q maintenance handoff in Constructured/ops — Contacts, remote-access triage, host recovery, component runbooks, and remaining handoff checks. Merged in ops PR #20 on October 16, 2026.
  2. One Q, Two Engines — The architecture and automation ownership map.
  3. Operator's Guide to Q — The operating lanes and maintenance boundaries.