[Photon] Ground Control

Your code changed. Your README didn't. Ground Control catches every stale claim in your docs and opens the fix PR in one click. Docs you can finally trust.

Comment 1

Inspiration

Every developer has lost an hour to a README that lied. It says npm run dev, but the script was renamed months ago. It says Node 18, but the project needs 22. It links to docs/setup.md, which no longer exists.

Code gets reviewed, tested, and type-checked on every commit. Documentation gets none of that, so it quietly drifts until the first person to trust it gets burned, usually a new contributor. We wanted docs to get the same guarantee code does: if it's wrong, you find out automatically, and fixing it takes one click.

What it does

Ground Control reads a repository's documentation, extracts every checkable claim, and verifies each one against the actual code.

  • Static checks. Does this file path exist? Is this npm script in package.json? Does the documented Node version match engines?
  • AI extraction. Gemini or Claude turns prose like "Copy .env.sample to .env" into structured, checkable claims, each grounded in an exact quote from the README.
  • Deep checks. For repos you opt in, a GitHub Action runs documented commands, starts the server, and hits documented ports and endpoints in CI.

When a claim fails, you can:

  • Fix. AI rewrites only the cited lines, using the repo's real files and package.json as ground truth, and opens a draft pull request.
  • Ignore. Mark it intentional. It stops counting toward drift, and you can restore it any time.
  • Get alerted. Optionally link your phone and handle drift from iMessage with a one-word reply: FIX, KEEP, or IGNORE.

The Sky view plots scanned repositories like satellites. The more a repo's docs disagree with its code, the further it drifts off course:

$$ \text{drift}^\circ = 90 \times \frac{\text{failing checks}}{\text{checkable claims}} $$

How we built it

  • TypeScript monorepo on Bun, with focused packages for claim extraction, check planning, the check runner, public scanning, corrections, and messaging.
  • Hono API + React/Vite frontend, SQLite storage, and GitHub OAuth. Fix PRs are opened with the repo owner's own GitHub token.
  • A small, strict check vocabulary: nine claim kinds, from file_exists and script_exists to port_listens and http_example. Models may only propose claims of these kinds, validated with Zod. Model output is always data, never executable code.
  • A trust model instead of blind alerts. A claim that passes becomes confirmed; one that fails on first sight is only disputed. It becomes real drift only when a previously confirmed claim later fails.
  • Gemini and Claude behind one interface for extraction and fixes, Photon Spectrum for cloud iMessage, GitHub Actions for deep checks, and Docker + Azure for deployment.

Challenges we ran into

  • Landing on the idea. It took a while to settle on a problem that was real, specific, and buildable in a weekend. "Docs drift from code" is easy to agree with, but turning it into a concrete product took real iteration.
  • Trimming scope. Our idea started out abstract, and an abstract idea makes a vague, confusing UI. We had to cut aggressively and decide what one screen should say at a glance: which lines in your README are wrong, and how do you fix them?
  • Designing a clear UI. Showing trust states, check results, and drift without overwhelming people went through several redesigns. That included rebuilding the repo page mid-hackathon into a simple ✓ / ✕ checklist.
  • Getting Photon to work smoothly. Linking a phone to a GitHub account, routing replies to the right repo, and making iMessage actions (FIX, IGNORE, KEEP) stay in sync with the web UI took a lot of debugging.
  • Reusable components. With several people building UI in parallel, we kept running into duplicated, inconsistent pieces. We refactored toward shared components so every page looks and behaves the same.

Accomplishments that we're proud of

  • An end-to-end loop that works on a real repo: scan → find stale claims → one click → a draft PR with correct fixes.
  • AI that stays grounded. Every finding cites the exact README line, and every fix is checked against the real repository.
  • A strict safety boundary: public scanning never executes a line of anyone's code.
  • The Sky, a visualization that makes documentation health instantly readable.

What we learned

  • Making setup nearly effortless. Our biggest lesson was how much onboarding matters. We built a flow where a few clicks add the repo secret, commit the workflow files, and open a test PR. Turning a multi-step CI setup into something anyone can finish in under a minute changed how usable the whole product felt.
  • Reusable GitHub Actions workflows. We learned to write a custom, reusable workflow that any repository can call. The logic lives in one place, and each repo just references it.
  • Sign in with GitHub. We implemented GitHub OAuth end to end: sessions, repo permissions, and using the signed-in owner's own token to open fix PRs safely.

What's next for Ground Control

  • More doc sources. Wikis, Confluence, and docs sites beyond the README.
  • A one-step GitHub Action so any repo can add deep checks and catch drift on every pull request.
  • Beyond JavaScript. Python, Go, and Rust projects.

Built With

Share this project:

Updates

Submission history