Our ‘Find Everything’ Catalog Couldn’t Find a Tool We Built

The day the front door lied

We built a single searchable catalog promising “find everything.” It was supposed to be the front door to all our work. On 2026-07-04 we tested it hands-on.

We opened the front door and a working tool we had already built was invisible. It existed on disk, ran for weeks, produced output. The catalog did not know it. Someone then registered that tool by hand. The entry appeared immediately.

That single moment revealed the whole failure: the catalog only knows what people tell it. Nothing else.

What we found, step by step

We did a hands-on sweep. We tried to use the find-everything interface to locate real files and services and then matched what we found to the catalog.

Five holes jumped out at once. The file store had never been crawled. The search index sat empty. Nothing compared what actually exists against what was cataloged. Entries had no liveness check. One shortened reference on the front door itself failed to resolve.

We then exercised the thing that should have been obvious: we ran an independent crawl of the file store and the running services, and compared that list to the catalog.

The crawler returned items that were not in the catalog at all. The index had no tokens for text that clearly existed. A running service resolved fine on the network but the catalog recorded an outdated address, and the shortened reference on the front door redirected to a dead link. When a human added the running tool by hand, it showed up immediately in searches and cross-references.

How we proved the fix

There was no new science here. The pieces were already on the shelf. Crawlers, text indexers, simple diffing logic, and liveness checks all existed as separate utilities. What we were missing was the loop that makes them talk.

We wired a small proof-of-concept: crawl the file store on a schedule; produce a candidate list of discovered items; diff that list against the catalog; report mismatches with context; index discovered text so it is searchable; flag dead references for human review.

After wiring those parts together, the catalog stopped being a wishlist and started becoming a map. The moment that clicked was when the crawler discovered the invisible tool and the diff produced a one-line actionable report: “present on disk, absent in catalog.” That line triggered a human registration and then the front door search returned the tool. The loop closed.

From that small experiment one rule survived: crawl reality on a schedule and diff it against your records so the gap between map and territory is a visible list instead of a silent hole.

A counter-case we kept

We should be honest. Not every mismatch is worth auto-registering. In one instance the crawler found dozens of temporary files created by a developer’s local script. If we had blindly ingested those, noise would have exploded and trust in the catalog would drop. We kept that case as a reminder: discovery is not the same as acceptance. The system must present candidates and context so humans can decide what belongs.

One concrete detail

As a taste: when the crawler finds a file, it extracts a title line and the first 200 characters of text, then shows a diff hint next to the catalog record like “title matches; content differs; missing in catalog.” That single contextual line made reviewers take action instead of shrugging.

The tested, runnable version of the full wiring lives in the members’ library.

How we know: every item above is drawn from our 2026-07-04 hands-on test and the subsequent wiring exercise we performed in our content pipeline. We repeated the crawl-diff-report loop twice and observed the same behavior each time.

Questions we got

Is crawling safe for sensitive files?

Only if you design scope and permissions first. Our crawl runs under a service account with read-only access and a ruleset that excludes known sensitive directories; mismatches in excluded areas are reported as “out of scope” rather than listed. The main point is to make gaps visible, not to expose everything.

Won’t this create more work for librarians?

It can if you auto-ingest carelessly. We aimed to present concise, high-signal diffs so humans make final decisions. The diff should reduce guesswork, not increase it. In our run the average review time per mismatch dropped once context snippets were included.

Can we trust automated liveness checks?

They’re useful as indicators. We treat them as one signal among several. A failed liveness check creates a ticket, not an automatic deletion. In practice they help catch stale records fast and keep people from searching for things that no longer work.

Rule, final: an archive that waits to be told is a wishlist; crawl reality on a schedule and diff it against your records.

Sources: hands-on test and post-mortem from our 2026-07-04 catalog audit.