feat(frontend): optional Holostaff copilot for maintenance teams (off…

[xxl007]

Hey Atlas CMMS maintainers, I'm Galem. This PR adds an optional in-product copilot for maintenance teams. One clarification first, because the word copilot usually means a chat window: this is not a chatbot. Nobody has to ask it anything. It watches for users who get stuck and steps in on its own. The people who need help most never open a chat. They just leave.

Full disclosure up front: I build Holostaff 😎, and I am doing this for open source products I admire. Your users are the reason I picked Atlas: facility managers and technicians are exactly the people who will not read docs and will not open a support chat.

Here is what it looks like:

That is a new manager on the work order form, all those fields, and they stop. A little later, help arrives with the one thing they need to know: only Title is required, submit now, add details later. The copilot learned Atlas by reading this repo.

It can also act when asked 👇👀:

Here the manager asked by voice to create a work order, and the copilot worked your own UI to do it, naming each step first.

The copilot is off by default.

How did I add this?

I used the Holostaff CLI in a checkout of this repo. It scanned the code and drew Atlas CMMS's customer journey: 7 workflows, 25 routes, the places where a user gets stuck, and what a helpful voice should say at each one. That map is where the copilot's knowledge comes from, so it arrives already knowing the terrain: your routes, your workflows, your stall points.

I wrote the full map up, workflow by workflow, here: We scanned Atlas CMMS.

One example from the map, the one in the GIF above. The scan read your work order form and noticed the truth a stuck user cannot see: only Title is required. The map's intervention for that stall is "Only Title is required, you can always add details later. Submit now and update when you have more info." That is the difference between a submitted work order and an abandoned one.

It knows when to shut up, too. After speaking once it holds a 24 hour cooldown on that nudge rather than nagging. And in the voice clip, asked to continue after the work order was created, it answered: "that request was already added a moment ago, so I'm not going to click through again and risk creating a duplicate." A helper that talks all the time is worse than none.

What it sees, and what it never sees

• The public request portal never loads it. The init runs from the authenticated layout only, exactly where your Intercom integration lives, so /request-portal/:uuid and the auth pages never even reference its code. Requesters are your users' users. They stay out of scope.
• When a self-hoster turns it on, the copilot has eyes. the copilot sees the user's app session in real-time, and that is how it knows someone is stuck: the stall detection in the first GIF is exactly this.
• The scan is transparent before it uploads. It shows exactly what would leave the machine and waits. Source code, file contents, .env and git history stay put.

Feel free to grill me on this section if you have questions.

What merging does

The diff follows your own patterns: ids resolved through getRuntimeValue like INTERCOM_ID, init in ExtendedSidebarLayout like Intercom, keys registered in frontend/.env.example so runtime-env-cra emits them, and two documented rows in the README table. Both ids empty means off. Because they are runtime config, a self-hoster on your prebuilt image can turn the copilot on with two env vars and a container restart, no rebuild. (Small aside: while wiring this up I noticed INTERCOM_ID is missing from the runtime key registry, so self-hosters cannot actually set it. I sent that
fix as its own small PR so it is not tangled with this one.)

I measured what "off" means on a build of this branch, logged into the app, instead of asserting it:

	ids empty	ids set
requests to Holostaff	0	3
copilot in the DOM	no	yes
SDK chunk (74 KB as served)	not fetched	fetched
session recorder (rrweb, 186 KB as served)	not fetched	fetched
voice (livekit-client)	not fetched	not fetched until a conversation opens

To be complete, the table is browser bytes only. The dependencies land in frontend/package.json for every contributor and self-hoster either way: install time, CI time, supply-chain surface. @holostaff/sdk 0.10.12 is new with a small user base, and yes, that version shipped this week: filming the clips above surfaced three real bugs in our action tool, so the pin is the version those fixes live in. livekit-client 2.21.0 is the voice transport. Both are pinned exact. The SDK is Apache-2.0, which works fine as a dependency of your AGPL frontend. The CLI is open source; the service behind it is not.

How this would roll out

Merging turns nothing on for atlas-cmms.com. It gives anyone self-hosting Atlas two env vars they can choose to fill in, on their own install. Setup is one command, documented at docs.holostaff.ai/cli/presets, and I am happy to move that write-up into your docs instead, so you control what your users read.

And if a vendor plugin inside core is more than you want to take on, there are two smaller shapes I am equally happy with: a page in your self-hosting docs instead of code, under your editorial control, or nothing at all, because the same plugin can be added to any checkout with our CLI, and I keep that path working and tested. Merging just saves each self-hoster from carrying a patch.

Happy to answer anything here, and to adapt the approach to what works for Atlas CMMS. You can also reach me at galem@holostaff.ai.

[netlify]

👷 Deploy request for atlasjs-home pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	64610fe