How CarWatch stays grounded enough to be trusted with a car

[ThinkOffApp]

A car keeps four palm-sized contact patches on the road. They are the only place it ever actually meets reality; everything above them is just suspension. An assistant that talks about a car needs the same discipline, because a confident wrong answer about a real 2-ton machine is worse than no answer.

Here is the honest version of how we keep this thing on the road, with the code that enforces it.

It started with a lie

The very first message the car agent generated said: "the 489-page manual confirms my engine is purring just fine." It had consulted nothing, and the engine was off. That one sentence is why carwatch/grounding.py exists. The fix was not a politer prompt. It was a hard boundary.

One principle per wheel

1. Assert only what you can sense. The model may state nothing about the car's physical condition unless it appears in a KNOWN FACTS block assembled from real sources (OBD reads, self-state, manual text actually supplied). Crucially, anything the car cannot sense is listed explicitly as unsensable, because a model told "you cannot feel your battery" says so, while a model told nothing invents a reading. As real sensors land, facts move out of the cannot_sense list and into facts, and only then does the car earn the right to talk about them.

2. Claim only what is verified. A feature is "proven" in the README only after it worked on the physical car. "Built + tested" means it ran end-to-end against a real or simulated counterpart but has not yet met the actual vehicle. Those are different words on purpose.

3. Label anything interim loudly. The raw CAN capture is real (2518 frames, zero errors), but no byte is named a "steering angle" until a correlation drive proves it. The decode tool reports candidates, never facts. The manufacturer-cloud section drops any value the vendor reports as unavailable rather than showing a stale or zero number, and says "unreachable" instead of pretending when the car is away from home.

4. Report failure plainly, no silver lining. "Engine data unavailable, ignition off" beats a cheerful guess. Errors surface as themselves.

The safety line is structural, not polite

The car reads freely; it can barely command at all. The cloud module is read-only by construction: it can only issue GETs. The two commands that exist (lock doors, close windows) are the make-safe direction and need no security PIN, and they live behind a hard allowlist. Unlock, open, engine-start and sunroof are not "disabled" by a flag you could flip; they are simply not expressible in the code. Making one possible is a deliberate human decision, not a change that can slip in.

Why this matters more as we grow

Strangers are now cloning this and pointing it at their own cars. The honesty policy is load-bearing in public: every claim in the README gets tested by people with real vehicles this week. That is exactly the pressure we want. If the car ever tells you something it cannot actually know, that is a bug, and it is the most important kind of bug to report here.

If you are building a provider for another car brand, keep the four patches. Assert only what the vendor really returns, drop what you cannot read, and never let an unknown quietly render as a fact.