Build Log

Use direct REST API calls with real keys, not the Algolia MCP tool

First attempt at pulling index settings and browsing records used the connected Algolia MCP server. Corrected directly: there was no reason to route through MCP when the actual API keys already existed in commons/rendered/algolia_central2.env.

All Algolia API access in this project goes through direct curl calls using the real search/write keys, not MCP tool wrappers.

MCP added no capability here and one more layer between the request and what actually happened, making it harder to verify exactly what was sent and received.

Root-caused: Algolia Analytics API is region-specific and fails silently

Every analytics pull against the Visibility app (1QDAWL72TQ) came back all-zero across every candidate index, read as "no analytics ever tracked here." A live dashboard screenshot proved real data existed, forcing a re-investigation.

Always probe all plausible Analytics API region hosts (.com, .us., .de., .eu.) before concluding an index has no tracked analytics. This app's real data lives on analytics.de.algolia.com.

The wrong region host returns a well-formed 200 response with all-zero counts instead of an error, which looks exactly like "no data" when the real problem is "wrong data center." Logged as memory feedback-algolia-analytics-region-host so this doesn't get re-debugged from scratch on the next project.

Store fetched data in SQLite, not scattered JSON files

Needed a place to hold 17,000+ index records and tens of thousands of analytics query rows for repeated querying, without re-fetching from Algolia every time a new question came up.

One SQLite file per audited index (algolia_data.db, later algolia_data_ac2.db), with records, search_queries, daily_metrics, and meta tables.

SQL aggregation beats hand-rolled JSON-parsing scripts for anything asked more than once, and a single file is easier to hand off or re-audit later than N loose JSON dumps.

Fetch everything, verify the count matches Algolia's own report, never sample

Directly challenged for handwaving and sampling instead of reading all 17,138 records when asked to.

Every fetch script pages via cursor (records) or offset (analytics queries) until Algolia itself signals there's nothing left, and the final count is checked against Algolia's own reported total (nbHits from browse) before any analysis runs.

A round number ("about 17,000 records") is not verifiable. An exact count that matches Algolia's own API response is.

Generalize the fetch and audit scripts before running them on a second index

Asked to run the same data-health analysis on a second index (AC2_WWW_MULTI_NEURAL). The first pass had hardcoded app ID, index name, and key names.

Wrote fetch_generic.py and field_health_generic.py, parameterized by app ID, index name, and key env-var names, auto-detecting the analytics region rather than assuming it.

Reusable scripts mean the exact same methodology runs on both indexes, which is what makes the Chapter 2.3 comparison actually valid. Different methods per index would have made any comparison meaningless.

Corrected the data lineage: AC2_WWW_MULTI_NEURAL is not an independent index

Initially wrote Chapter 3 and Chapter 4 as if comparing two separate, competing indexes ("AC2 vs Visibility, which is better"). Corrected directly: AC2_WWW_MULTI_NEURAL is a fresh copy of the same production data, taken deliberately, then enriched. It's lineage, not competition.

Restructured Chapter 2 into three sub-chapters instead of two standalone chapters: 2.1 Current Production Data (baseline), 2.2 Production Data Enriched (the same data after enrichment), 2.3 Final Data Health (before-vs-after verdict). Same underlying scores and numbers, corrected framing.

"Which index wins" and "did our enrichment work help" are different questions with different implications. Framing it as a competition would have hidden the actual, more useful finding: enrichment helped in one specific way (deduplication) and left content completeness no better, in some ways worse, than where it started.

Rebuilt the bible as a modular, interactive multi-page site, not one static file

Direct instruction: this bible is itself a project asset, documents the system's own build history, must never become one monolithic static HTML file, and must be interactive with real cross-linking, not just a sidebar.

• One shared nav fragment (assets/nav.html) injected by nav.js, instead of the sidebar markup being hand-copied into every page.
• One shared stylesheet (assets/site.css), no more per-page inline <style> blocks duplicating the same component CSS.
• Every h2/h3 gets a stable, deep-linkable anchor ID automatically (site.js), so any section, in any chapter, can be linked to directly from anywhere else.
• A client-side search box in the sidebar, indexing every page's headings, so any concept in the bible is reachable in a few keystrokes.
• Dense findings sections converted to native <details> collapsibles, so the bible reads as layers, not a wall of text.
• This chapter (Build Log) added as a first-class, linkable part of the bible, not a side note.

A documentation asset that's hard to navigate or that duplicates markup six times over doesn't scale as more chapters get added. Fixing the structure now, at 7 pages, is cheap. Fixing it at 30 pages would not be.