May 9, 2026: cidx flipped from private to public. v1.7.0 followed two days later, carrying the cleanup work that the visibility change forced. This post is the milestone for the opening; the v1.7.0 release-notes cover the technical changes.

Decision

  • What — moved cidx-org/cidx from a private personal repo to public.
  • Why — cidx was already in use across four personal projects with a stable surface (init, run, generate). Keeping it private no longer paid for itself: I couldn’t link to its README from blog posts, couldn’t go install from a clean machine, and was re-explaining setup project by project.
  • Choice — release with light polish (LICENSE link, SECURITY.md, CODE_OF_CONDUCT.md, README install section) and accept that real users would surface more. v1.7.0 two days later absorbed the immediate cleanup. Anything else gets caught when someone hits it.

What we learned

Three things this opening surfaced — all of which were fine while I was the only user.

Defaults encode the author’s habits invisibly

The example cidx.toml in the repo root was 491 lines. It served two contradictory roles: actual config for building cidx itself, and an exhaustive catalog of every option with pedagogical comments. A new project’s cidx init output should be 15–20 lines. A 491-line example sent the wrong signal — this is how much config you need.

Caught only by imagining the first ten minutes through someone else’s eyes. The lesson: examples are public signals, not internal documentation. When the same artifact serves two audiences with opposite requirements (terse template / exhaustive reference), the fix is structural — split into two files. Cosmetic tightening doesn’t help.

First-time-user flows include retries

cidx init was not idempotent. Running it twice — to undo a typo, to test “what if I run this again” — would either error out or clobber existing config. For me this was a known quirk; for anyone trying cidx fresh, the second invocation was a lost-work experience.

The fix (--diff / --update) is small. The lesson is that a tool’s most-used path is cmd then cmd again, not just cmd. The first-attempt-only codepath isn’t a real codepath in any tool other people will use.

A bug that doesn’t move when you fix it is being mis-categorized

Issue #127 — cidx printing “violation” lines from previous runs even after fixing them — was misdiagnosed as cache invalidation for weeks. Two cache-related tweaks didn’t move the needle. The actual root cause was ContainerLogs without a Since cutoff returning the full log history of a reused container. Four-line fix in pkg/executor/docker.go once we suspected the diagnosis, not the implementation.

The lesson: when a fix doesn’t move the symptom, the diagnosis is the bug. Stop iterating on variants of the same hypothesis; go back to the source of truth (in this case, what does ContainerLogs actually return without Since?).

What it cost

v1.7.0 carries the cleanup: cidx.toml 491 → 84 lines, idempotent cidx init, log replay fix, README / SECURITY.md / CODE_OF_CONDUCT.md. See the v1.7.0 release-notes for what shipped and the decisions taken.

What’s next

Real users will surface what else the private-repo era let me get away with. The polishing wasn’t exhaustive — it was triage based on imagining one new visitor, not exhaustive code review. The next milestone is cidx generate github emitting actions/checkout@v6 before GitHub’s June 2, 2026 Node 20 deadline (#138).