Five open repository folders on a wooden desk, one inspected under a magnifying glass during a security audit

Five of my public repos got a full-service detail this weekend: rewritten READMEs, proper license files, a secrets audit, and a housekeeping pass. I farmed the work out to five coding agents running in parallel — one per repo — and by the end of the day everything was reviewed, merged, and pushed.

The surprise wasn't hiding in my git history. It had been sitting on the front pages the whole time.

The setup

My GitHub had accumulated the usual sediment. A couple of repos with sparse READMEs, one with a README describing an architecture I'd replaced months ago, none with license files, and a general vibe of "I'll tidy that up later." Later arrived on Sunday.

The brief for each agent was the same:

  • Rewrite the README to a professional standard — but verify every claim against the actual code first
  • Audit the repo for secrets: the working tree AND the full git history
  • Report anything that needed rotating or rewriting out of history

That second bullet is the one I cared most about. History is where secrets go to be forgotten, not deleted — removing a key from the current tree does nothing if it's sitting three hundred commits back.

The READMEs were the liars

The secrets audit came back clean on all five repos — tree and history. Nothing to rotate, no history surgery required. Genuinely the best possible outcome, and also the boring one.

The READMEs, though. Every factual error the agents caught was in the documentation, not the code:

  • One README proudly claimed the project ran on Next.js 15. The package.json said Next.js 16. The README was simply a version behind reality.
  • A documented keyboard shortcut for search didn't match the shortcut the code actually listens for.
  • One README listed an npm dependency that doesn't exist — a package name that was never in package.json, never installed, never real. It just... lived in the docs.
  • A feature count was off by one: eighteen things claimed, seventeen things shipped.
  • One README's clone URL pointed at a repository that doesn't exist. You could not have followed the project's own setup instructions from a cold start.
  • An architecture section described a UI implementation I'd replaced with a different approach a while back.

None of these threw an error. That's the thing about documentation: it compiles nothing and runs nothing, so it never fails loudly. It just drifts, one stale claim at a time, until your README is a historical fiction about a project you used to have.

The fix that worked — and I'd recommend it to anyone — is making "verify against code" an explicit step instead of an assumption. Don't ask "is this README good?" Ask "which of these sentences is false?" Different question, much better answers.

The boring, essential secrets audit

Even though mine came back clean, the audit was the part I'd tell everyone to actually do. The pattern that burns people is almost never a key in the current tree — it's the .env committed in week one and deleted in week two, which is not deletion at all as far as git is concerned.

A few things worth knowing if you've never run one:

  • Scan history, not just the working tree. Tools like gitleaks and trufflehog walk every commit.
  • A clean scan means nothing to rotate. A dirty scan means rotate FIRST, then worry about history — rotating is what actually closes the hole.
  • If you do have to purge history, remember that every fork and clone is a copy. Rotation is the real fix; history rewriting is hygiene.

Five repos, zero secrets. I'll take boring every single time.

Picking a license on purpose

All five repos now carry MPL-2.0, and that was a choice, not a default. The quick version of the decision:

  • MIT/BSD: do literally anything, including take the code, improve it, and give nothing back. Great for adoption, zero reciprocity.
  • GPL: strong copyleft. Improvements must be shared, but the license also reaches across your whole project — which scares off a lot of reuse.
  • MPL-2.0: file-level, weak copyleft. Modify one of my licensed files and you share those modifications back; build whatever you want around them and that's yours.

For showcase code, MPL felt exactly right: people can learn from it, reuse it, build on it — but improvements to my files come home. It's the middle lane, and I think it's underused.

The icon detour

The desktop app also finally got a real icon. I had a logo PNG; a quick image-processing pass trimmed it, squared it, and generated a proper multi-size .ico (16px through 256px) plus the MSIX store tile set for packaging. Bonus fix: the project file had been referencing an icon that didn't exist, so fresh clones were building with a dangling reference. Small thing, deeply satisfying to close.

The point

Your public repos are the front of your house. Anyone who looks at your work — a collaborator, a future contributor, some random developer at 2 AM — meets your README before they meet your code.

Mine were telling small lies, missing licenses, and pointing at repos that didn't exist. One Sunday, five parallel agents, and a "verify every claim" rule fixed all of it. The audit was clean, the licenses are deliberate, and the READMEs now describe the projects I actually have.

When did you last check whether yours do?