← Building Glasstrace

Validating the Zero-Configuration Claim: An Installation Audit Across Six Codebases

Building Glasstrace, Part 2 · August 27, 2026

“Zero-configuration” is an easy claim to make in developer tooling and a frequently false one. By early May the software development kit (SDK) installed cleanly on every project I owned, which demonstrated very little, since a maintainer unconsciously builds projects that suit his own tooling. Before the phrase “one-command install” appeared in any public material, I pointed the installer at six production open-source codebases I had never worked with, and recorded what happened.

The audit

On May 4, 2026 (SDK version 1.3.2), the targets were Rallly, Formbricks, Documenso, Inbox Zero, OpenStatus, and Papermark: five production Next.js applications and one React Router application (Documenso), with genuine monorepo layouts and package-manager diversity. Documenso stayed in the sample as an out-of-scope control.

The results were as follows. Baseline installation passed 6 of 6; every repository installed and ran before Glasstrace was introduced, a control condition that matters because the kit cannot be faulted for a repository that was already broken. Package addition passed 6 of 6. Initialization passed cleanly on only 4 of 6, or 66.7 percent fully automatic. OpenStatus was a partial: npx glasstrace init --yes failed while direct invocation of the binary (./node_modules/.bin/glasstrace init --yes) succeeded — the recorded error was npm error could not determine executable to run, most likely a package-manager workspace interaction rather than a defect in the kit, and it had never appeared on my machines. Documenso failed outright with “No Next.js project found” — correctly, in one sense: it is a React Router and Hono application, and the initializer supports Next.js roots only. That failure marks a scope boundary rather than a detection defect.

Scored generously, that is 5 of 6, or 83.3 percent passing or partial. From the developer’s side it is 4 of 6 on the promise as advertised. One further detail stung: every successful Next.js initialization logged a write failure for public/.well-known/glasstrace.json (filed as DISC-1565). The installation succeeded while reporting that something had failed, a category of blemish that costs trust out of proportion to its practical harm.

A day later the same six targets were re-scored as validation candidates rather than installation targets. That readiness audit rated four “partial” and two (Documenso and Papermark) “not ready.” The same six codebases scored lower when the question changed from installation to validation readiness.

What the numbers changed

The audit reordered engineering priorities.

Initialization became injection rather than generation. Real applications already contain an instrumentation.ts; scaffolding a fresh one solves the easy case that rarely occurs. The command-line tool learned to inject registerGlasstrace into existing files (glasstrace-sdk@ad5e5e2, pull request 74). Architecturally this is a shift from owning the entry point to living as a guest inside the application’s own.

Dependencies became the project’s responsibility. Bundling OpenTelemetry into the kit for zero-dependency tracing (bcbb81a) means version skew between our instrumentation and the application’s own OpenTelemetry configuration cannot break installation. The cost is that the project tracks OpenTelemetry upstream itself and needed explicit coexistence logic for applications already running it, work that later surfaced and corrected a real Prisma instrumentation gap (14691e9, SDK-025 and DISC-1223).

And the claim acquired a qualifier. In every subsequent document, from the investor brief to the board pack, the figure is 83 percent including the partial result, across six repositories, with its date attached and Documenso named. “Works with Next.js” would have been easier to write. It works with most Next.js applications, and I would rather publish the smaller sentence.

The trade-off ledger

Each installation-path decision involved a trade-off, and the audit settled several of them.

Developers type the npx form; the direct binary works everywhere. The documented path remains npx, with the fallback hardened, accepting that some fraction of first attempts will need the second command.

Framework detection has a hard scope boundary, as Documenso demonstrated, and workspace tooling interacts with the installer in ways that are difficult to predict, as OpenStatus demonstrated. Explicit configuration would fail more predictably but forfeits the zero-configuration positioning. The project kept detection and treats each failure as a named defect, on the premise that the defect list converges.

The DISC-1565 experience argued for quieter failure messages. The decision went the other way: keep warnings visible and repair the write path. Hiding minor failure messages now makes it easier for a serious one to go unnoticed later.

The unplanned origin of the validation system

What lasted from the audit was less any single fix than a habit. Four days later, on May 8, a dedicated validation repository was created, and its first two commits are indicative: a Model Context Protocol (MCP) evidence-ledger sidecar (glasstrace-validation@6db212c) and trace-positive overlay validation (8faef92). Having watched the kit behave differently on codebases I had not written, I wanted a permanent facility in which Glasstrace would be tested against the world rather than against my assumptions, with evidence retained instead of pass-or-fail results.

That repository and its successors grew into the machinery the rest of this series describes: 180 commits through July on its working branch, then a remote-execution successor that has produced more than 1,800 further commits. At the time it felt like a detour from feature work. Every statistical claim in the later articles of this series traces back to it.

Supporting data and commit references

Evidence availability: references to glasstrace-sdk are public — the repository, commits, and files are linked in the series evidence manifest. All other repositories cited above are private; artifacts may be shared as needed, and the manifest publishes each cited artifact’s SHA-256 digest so that any shared copy can be verified against the version these articles describe.