DEV Community: Jeremy Longshore

Braves Booth — Idle Recap, Dashboard Density, and AI Pitcher Narratives

Jeremy Longshore — Thu, 09 Apr 2026 21:18:19 +0000

Between games, the Braves Booth dashboard used to show a tab bar with RECAP and PREVIEW buttons. Pick one. The problem: announcers don't want to choose. They want the full picture — what just happened and what's coming next — on a single screen with no clicks.

Two commits, 29 files, 600 lines changed. The idle view got rebuilt, the entire UI got tighter, and the AI pitcher narrative system got replaced with something that actually works.

The Idle View Problem

The old between-games state showed either a recap or a preview, toggled by tab buttons in the GameStateBar. This forced a decision that shouldn't exist. When there's no live game, the announcer needs both: the line score and AI recap from the last game, plus a clickable card previewing the next one.

The fix removes the tab buttons entirely. The idle page now renders the full recap — line score plus AI-generated game summary — with a next-game preview card below it. Click the preview card and it expands into the full pregame view.

The backend side needed a new pregame route that fetches game context from the MLB schedule API for future games. The existing schedule fetcher only handled today's games. Now it looks ahead, pulls the matchup, and caches it with a TTL.GAME_SCHEDULE of 300 seconds.

// DRY pregame fallback — one helper instead of three scattered checks
static fromGameState(gameState: GameState): PregameContext {
  return {
    homeTeam: gameState.homeTeam,
    awayTeam: gameState.awayTeam,
    probablePitchers: gameState.probablePitchers,
    venue: gameState.venue,
    gameTime: gameState.gameTime,
  };
}

PR review caught the duplication early. Three different components were building pregame fallback objects with slightly different shapes. The fromGameState() helper killed all three.

Dashboard Density Overhaul

The dashboard runs on a three-column grid. Before this refactor, the columns had loose padding and inconsistent widths across breakpoints. The new layout uses responsive rails: 280px at the smallest breakpoint, 320px at medium, 360px at large.

Changes that sound small but affect every panel:

GameStateBar got a gradient background with larger score and inning text. The old bar had redundant labels — "Home:" and "Away:" before team names that were already obvious from the logo and position. Removed.
PanelHeader gained a variant prop. The center column uses primary (red accent border) to visually anchor it as the main content area. Side columns use the default.
Weather card absorbed the Wind Impact panel. Two separate cards for weather and wind was a waste of vertical space. One card, two sections.
Ticker got slowed from its original scroll speed to 75 seconds per cycle and reduced in height. The old ticker was distracting during live broadcasts.

The Font Floor Sweep

The second commit started with a specific fix — pitcher scouting reports — and turned into a codebase-wide audit. While tightening the center column, I found text-[7px] and text-[8px] classes scattered across 15 files. Sub-10px text on a dashboard meant for glancing during a live broadcast is useless.

Every instance got bumped. OnDeckPanel, CohostPanel, BullpenPanel — all labels moved to a 10px minimum. The ghost number (a decorative large number behind panel content) got removed entirely. It looked clever in the mockup and was visual noise in practice.

The center column went full TweetDeck-density: reduced padding, tighter gaps, more data per viewport pixel.

Replacing AI Narrative Duplication

The PitcherCard had an AI narrative block that was supposed to give announcers a quick scouting summary. The problem: it duplicated the same narrative generation logic that existed elsewhere, and the output was unstructured prose that varied wildly between pitchers.

The replacement is a dedicated buildPitcherFacts() function in a new file:

// frontend/src/lib/build-facts.ts

export function buildPitcherFacts(pitcher: PitcherStats): string[] {
  const facts: string[] = [];

  if (pitcher.era !== undefined) {
    facts.push(`ERA ${pitcher.era.toFixed(2)}`);
  }

  if (pitcher.strikeouts && pitcher.inningsPitched) {
    const kPer9 = (pitcher.strikeouts / pitcher.inningsPitched) * 9;
    facts.push(`${kPer9.toFixed(1)} K/9`);
  }

  if (pitcher.whip !== undefined) {
    facts.push(`WHIP ${pitcher.whip.toFixed(2)}`);
  }

  // Velocity trend, pitch arsenal, awards follow the same pattern
  return facts;
}

78 lines. Structured output. Every fact is a string the announcer can read verbatim: "ERA 3.42", "11.2 K/9", "WHIP 1.08". No prose, no variation, no AI hallucination risk. The stats come from the MLB API, not from an LLM making up numbers.

When stats aren't available — early season, minor league callup, whatever — the function returns an empty array and the card falls back to the basic stat line. No "Unable to generate narrative" error states.

H2H Matchup Polish

The head-to-head matchup display got two changes that matter more than they sound:

Larger text. The batter-vs-pitcher matchup numbers were the same size as surrounding panel text. They should be the focal point. Bumped up.

OPS conditional coloring. An OPS over .800 against the current pitcher is green. Under .600 is red. Between is neutral. The announcer glances at the card and instantly knows if the batter owns this pitcher or struggles against him. A summary callout line below reinforces it in plain English.

The CSS Hover Fix

The PR review flagged React onMouseEnter/onMouseLeave handlers on the next-game preview card. These were controlling a hover state that CSS can handle natively:

.next-game-card:hover {
  transform: scale(1.02);
  border-color: var(--braves-red);
}

No state management. No re-renders. CSS does this better in every dimension.

What Changed

Two commits. 605 insertions, 335 deletions across 29 files. One new file (build-facts.ts). The dashboard went from a tab-based idle view to a unified recap-plus-preview layout. Every font in the codebase is now 10px or larger. The AI pitcher narrative system went from duplicated LLM prose to a deterministic fact builder that announcers can trust.

The pattern is the same one that keeps showing up on this project: broadcast tools need to be glanceable, trustworthy, and zero-interaction. Every change here moved in that direction.

Building a Production Multi-Agent AI System — multi-agent architecture patterns relevant to the AI narrative pipeline
Building an AI-Friendly Codebase — the CLAUDE.md-driven development approach used across this project
Building Production-Grade Testing Infrastructure — testing patterns that apply to dashboard components

Software Supply Chain Security After Axios

Jeremy Longshore — Mon, 06 Apr 2026 18:18:09 +0000

On March 31, 2026, attackers published two malicious versions of axios — a package with roughly 100 million weekly npm downloads — during a window of a little over three hours. Google Threat Intelligence Group attributed the campaign to UNC1069, a North Korea-nexus threat actor. The malicious releases introduced a dependency that used a postinstall script to deploy a cross-platform remote access trojan.

During that window, any CI/CD pipeline or developer workstation that freshly resolved the affected versions and allowed lifecycle scripts to run could have been compromised. Projects with previously committed lockfiles were far less likely to be affected.

A 38-page academic paper had already explained exactly how and why this would happen.

The Paper That Called It

Williams et al. published "Research Directions in Software Supply Chain Security" in ACM TOSEM in May 2025. Fifteen researchers from the NSF-funded S3C2 consortium synthesized findings from eight summits with 131 practitioners across 42 industrial organizations and 15 US government agencies. They identified three attack vectors: code dependencies, build infrastructure, and humans.

The axios compromise hit all three simultaneously.

I read this paper the same week the axios incident broke. The overlap is not a coincidence — it's confirmation that we have a well-understood problem and a deeply inadequate response.

What Happened

The group Google Threat Intelligence tracks as UNC1069 (Microsoft calls them Sapphire Sleet) compromised the npm account of axios maintainer jasonsaayman. They published two versions — 1.14.1 and 0.30.4 — targeting both the current and legacy release lines. Both added a new dependency: plain-crypto-js.

That dependency's postinstall hook downloaded a platform-specific RAT from sfrclak[.]com:8000. macOS, Windows, Linux — all covered. In npm, postinstall scripts run automatically during npm install. No user interaction required. No warning displayed.

The exposure window was a little over three hours before community detection triggered a takedown. That's a long time for a package installed roughly 100 million times per week.

The initial compromise path was familiar — credential theft followed by a malicious publish. But the downstream payload was serious: a staged dependency, a cross-platform RAT with macOS/Windows/Linux coverage, and cleanup behavior to hide the postinstall evidence. It worked against one of the most popular packages in the ecosystem.

Vector 1: The Dependency Problem

Sonatype logged 512,847 malicious packages in 2024 — a 156% increase year-over-year. Meanwhile, 96% of commercial code bases contain open source components, and 77% of all code is open source (Synopsys). The attack surface grows faster than detection capability.

The paper documents that detection tools for malicious packages have false positive rates exceeding 15% (Vu et al.). At that rate, automated blocking is impractical — you can't reject one in seven legitimate packages. So most malicious packages get through, and the ones that get caught are caught by humans who happen to notice.

The axios attacker exploited the most basic trust assumption in package management: that a published version of a popular package is safe, and that its dependencies are reviewed. plain-crypto-js was a brand-new package. Nobody reviewed it because postinstall hooks execute automatically.

The broader picture is worse. Three thousand popular npm packages (over 10K monthly downloads each) are abandoned. Vulnerabilities remain undiscovered for an average of three years. When they are discovered, 63% of security advisories in the GitHub Advisory Database lack patch links. We're failing to respond to known vulnerabilities, let alone prevent new attacks.

Vector 2: Your CI/CD Pipeline Is the Weapon

Any pipeline or workstation that freshly resolved axios during the exposure window and allowed lifecycle scripts to run was a potential victim. The RAT didn't need to trick a developer. It just needed the build pipeline to do what build pipelines do: resolve dependencies and run scripts. Projects with committed lockfiles that didn't update were not affected.

The paper found that only 20% of software builds match bit-to-bit when reproduced. Eighty percent of builds can't prove they haven't been tampered with. The ARGUS study analyzed 2.8 million GitHub Actions workflows across one million repositories and found code injection vulnerabilities in 4,307 of them.

SolarWinds demonstrated the category in 2020 — attackers compromised a vendor's build and update channel to sign malicious code with official keys. The axios incident is a different mechanic (registry publish via a compromised maintainer account) but the same underlying failure: build systems trust what they install, and attackers exploit that trust at whatever layer is weakest.

SLSA (Supply-chain Levels for Software Artifacts) defines maturity levels for build provenance. Sigstore has accumulated over 2.2 million signatures across critical software projects. But most organizations have no provenance metadata, no build attestation, no verification. The tools exist. The adoption doesn't.

Vector 3: The Human Problem Has No Patch

The axios attack started with a compromised human. Jasonsaayman's npm credentials were the entry point. Everything else followed from that single point of failure.

The 2024 Tidelift survey found that 60% of open source maintainers are unpaid. They spend 11% of their time on security — up from 4% in 2021 — a nearly threefold increase in security burden with no increase in compensation. Only 14% have formal processes to prioritize security issues.

The xz-utils attack in 2024 showed the extreme case: a multi-year social engineering campaign targeted a burned-out solo maintainer. The attacker gained trust, became a co-maintainer, and inserted a backdoor into a compression library used by virtually every Linux distribution. The paper's authors admit: "it is unclear if any existing security practice could have meaningfully prevented or even detected the xz-utils attack."

You can mandate 2FA. You can enforce credential rotation. But the human attack surface is not a technical problem with a technical solution. It's a systemic problem rooted in how open source is funded, maintained, and governed.

What to Do Monday Morning

The paper catalogs frameworks — SLSA, SBOMs, OpenSSF Scorecard, Sigstore — and documents their limitations. OpenSSF Scorecard has only 9 of 18 metrics that are reliably computable, and its ability to predict actual vulnerabilities is weak (R-squared of 9-12%, meaning it explains almost none of the variance). SBOMs are mandated by Executive Order 14028, but 71% of NVD entries lack the patch links that make them actionable.

The frameworks matter, but none of them would have stopped the axios attack alone. Defense-in-depth is the only viable strategy. Six steps, ordered by effort:

1. Pin exact dependency versions with integrity hashes. Stop resolving to latest. If your lockfile specified axios 1.14.0 with a hash, the malicious 1.14.1 never installed.

2. Disable postinstall scripts in CI. Run npm install --ignore-scripts and whitelist explicitly. The axios RAT relied entirely on a postinstall hook. No execution, no compromise.

3. Enable 2FA on every package registry account. npm, PyPI, RubyGems — all of them. The axios attacker got in through compromised credentials.

4. Run OpenSSF Scorecard on your critical dependencies. It's imperfect, but it surfaces obvious red flags: no branch protection, no code review, no signed releases.

5. Adopt SLSA level 1 for your own builds. Generate provenance metadata. It costs almost nothing and gives you a baseline for build integrity.

6. Fund your dependencies. If 60% of maintainers are unpaid and your business runs on their code, your security budget should include them. Tidelift, GitHub Sponsors, Open Collective — pick one.

None of these are sufficient alone. The xz-utils attack would have bypassed most of them. That's the point — make the attacker's job harder at every layer.

The Gap Between Knowledge and Action

The Williams et al. paper is not a prediction. It's a diagnosis. The researchers documented failure modes that practitioners already know about, backed by data from 131 industry participants who confirmed: yes, these are the problems, and no, we haven't solved them.

The axios compromise didn't reveal a new vulnerability. It demonstrated an old one, at scale, against a trusted target, by a nation-state-linked adversary. The three-hour window between compromise and remediation is a testament to the community's response speed — but lockfiles, npm ci, and --ignore-scripts would have blocked exposure without relying on detection at all. Response speed was the most visible defense that worked in real time. It shouldn't have been the primary one.

Read the paper. It's 38 pages. It won't make your dependencies safe. But it will show you exactly where the risks are, what exists to counter them, and why none of it is enough yet.

IntentCAD Viewer — Closing the DWG FastView Gap

Jeremy Longshore — Sun, 29 Mar 2026 04:31:42 +0000

DWG FastView is the benchmark. It's the viewer AEC professionals already use. It loads fast, zooms smooth, and never locks the UI on a 50MB drawing. If your browser-based CAD viewer doesn't match that bar, nobody will trust it with real work.

IntentCAD's viewer wasn't there yet. It worked. But "works" and "feels right" are different categories. The drawing would freeze for a few seconds on load. Zoom was instant — which sounds good until you realize instant zoom with no interpolation is disorienting. And when you selected three entities, they all turned the same shade of blue. Good luck telling them apart.

Two PRs this week fixed all of it.

The Main Thread Problem

The dxf-viewer library does everything on the main thread by default. Font loading, fetching, DXF parsing, geometry preparation — all of it blocks the UI. On a small test drawing, you don't notice. On a real architectural floor plan, you get 2-4 seconds of frozen interface.

The fix is three lines in a web worker file:

// web/frontend/src/workers/dxf-viewer-worker.js
import { DxfViewer } from 'dxf-viewer';
DxfViewer.SetupWorker();

Three lines. The library already supports worker-based parsing — it just needs a worker file and a factory function. The viewer component passes both:

const workerFactory = () =>
  new Worker(new URL('../workers/dxf-viewer-worker.js', import.meta.url), { type: 'module' });

Now DXF parsing runs off the main thread. The UI stays responsive during load. No freezing.

Progress Feedback

A responsive UI during load is necessary but not sufficient. The user still needs to know something is happening. DWG FastView shows a progress bar. We need one too.

The dxf-viewer library exposes a progressCbk callback with phase labels and byte counts:

const progressCbk = (phase, processedSize, totalSize) => {
  const labels = { font: 'Loading fonts', fetch: 'Downloading', parse: 'Parsing', prepare: 'Preparing' };
  setLoadPhase(labels[phase] || phase);
  if (phase === 'fetch' && totalSize > 0) {
    setLoadProgress(Math.round((processedSize / totalSize) * 100));
  } else if (phase === 'prepare') {
    setLoadProgress(90);
  }
};

Four phases, human-readable labels, a 4px progress bar with smooth CSS transitions. The user sees "Downloading... 34%" instead of a blank canvas.

Animated Zoom

The old zoom behavior: click the + button, camera jumps to 1.3x. Instant. No interpolation.

The problem is spatial orientation. When the view changes instantly, your brain has to re-locate where you are in the drawing. FastView animates its zoom. Every professional CAD viewer animates its zoom. There's a reason.

The replacement uses requestAnimationFrame with an ease-out cubic curve:

const animateZoom = useCallback((targetZoom) => {
  const startZoom = cam.zoom;
  const startTime = performance.now();
  const duration = 200;
  const step = (now) => {
    const t = Math.min((now - startTime) / duration, 1);
    const ease = 1 - (1 - t) ** 3; // ease-out cubic
    cam.zoom = startZoom + (targetZoom - startZoom) * ease;
    cam.updateProjectionMatrix();
    viewer.Render();
    if (t < 1) requestAnimationFrame(step);
  };
  requestAnimationFrame(step);
}, []);

200ms. Fast enough to not feel sluggish, slow enough for the eye to track the transition. The cubic ease-out decelerates at the end — the zoom settles rather than stopping dead.

Color-Cycling Selections

When you select multiple entities in the viewer, you need to distinguish them visually. The old behavior gave every selection the same blue highlight. Select five entities and you get five blue outlines with no way to match them to their entries in the operations panel.

The fix is a six-color palette applied by index: blue, emerald, amber, purple, pink, cyan. Each selected entity gets its own color in both the viewer overlay and the entity tag in the sidebar. Selection #1 is blue, #2 is emerald, #3 is amber, and so on.

Six colors is intentional. You rarely select more than six entities at once, and the palette cycles if you do. The colors are chosen for contrast on both dark backgrounds (the viewer canvas) and light backgrounds (the operations panel).

Click-to-Focus Operations

The operations panel lists planned changes. "Move HVAC-UNIT-01 to (240, 180)." Useful, but which entity is HVAC-UNIT-01? On a dense drawing, good luck finding it.

Now each operation row is clickable. The backend adds bounds to each operation via a new _op_bounds() helper that looks up the target entity's bounding box. The frontend calls focusOnBounds() to pan and zoom the viewer to the target entity with a highlight ring.

Click an operation. The viewer flies to it. Simple interaction, large usability gain.

The Small Stuff

Two things that don't warrant their own section but matter:

Accessibility fix. Operation checkboxes had been changed from <label> to <div> elements. Screen readers couldn't associate the checkbox with its text. Restored proper <label> elements.

CI hygiene. Ruff flagged a SIM103 simplification lint. Fixed. Pygments has an unpatched CVE-2026-4539 — we don't use Pygments in production, so added an ignore rule rather than blocking CI on a dev-only dependency with no upstream fix.

Dependabot Housekeeping

The google-adk bump from 1.18.0 to 1.28.0 arrived via Dependabot as PR #131. It branched before the lint and CVE fixes landed, so CI was red. Merged main into the dependabot branch, CI went green, squash-merged. Routine dependency maintenance.

The Gap Is Closing

FastView is still the reference. It has years of optimization behind it. But the gap is now about edge cases and scale, not fundamentals. IntentCAD's viewer loads off the main thread, shows progress, animates transitions, and gives you color-coded multi-selection. That's the baseline for a professional CAD viewer in the browser.

Two PRs. About 15 files changed. 614 insertions. The viewer went from "demo-quality" to "production-ready."

IntentCAD: Entity Selection + Diff Detection UX — the PR that built the selection system this work extends
IntentCAD: Pascal Editor, Cached Index & Tool Narrowing — performance work on the backend that pairs with these frontend improvements
Write Once, Publish Everywhere — Content Distribution Infra — the pipeline that publishes these posts

Write Once, Publish Everywhere: Building Content Distribution Across Three Sites

Jeremy Longshore — Fri, 27 Mar 2026 04:49:51 +0000

Three websites. One hundred blog posts. Thirty-one field notes. Four plugin repos. All synced automatically. None of it existed yesterday.

March 25th was about content distribution infrastructure. Not writing content — moving it. The problem: Intent Solutions runs three public-facing sites (startaitools.com, tonsofskills.com, intentsolutions.io) plus a plugin marketplace. Each site had its own content silo. Posts written here never appeared there. Plugin updates in source repos required manual marketplace syncs. The content existed. The distribution didn't.

Eight commits across two primary repos fixed that.

100 Posts: Hugo to Astro

tonsofskills.com is an Astro marketplace. startaitools.com is a Hugo blog. They use different content formats, different frontmatter schemas, different directory structures. Hugo uses TOML frontmatter with +++ delimiters. Astro expects YAML with --- delimiters. Hugo puts posts in content/posts/. Astro wants them in src/content/blog/.

The backfill pulled 100 posts from the Hugo site into tonsofskills.com's new blog section. This isn't an RSS embed or an iframe. It's actual content transformation — frontmatter conversion, path rewriting, image reference updates.

The section launched as "Blog" and got immediately renamed to "Work Diary." The name matters. A marketplace blog competes with the source blog for SEO. A work diary is a different content type — it's the builder's log, not the tutorial. Different intent, different audience, same underlying content.

The /pro page also got deactivated with a 301 redirect to homepage. One less page to maintain, one less nav link to confuse visitors. The Pro nav slot got replaced with the Work Diary link. Every page on a site should earn its place.

31 Field Notes: intentsolutions.io Gets Content

The corporate site at intentsolutions.io had the opposite problem — no content section at all. A services company without published thinking is a brochure. Brochures don't rank and they don't build trust.

The fix was a Field Notes section with 31 curated posts backfilled from startaitools.com. Not all 100. Thirty-one, filtered by professional tags. The corporate site gets the architecture posts, the production engineering posts, the CI/CD deep-dives. It doesn't get the daily work diary entries.

The implementation touched six files:

content.config.ts — Astro content collection with field-notes schema
Listing page with card-slate design and JSON-LD structured data
Detail pages with prose styles and canonical URL override
RSS feed at /field-notes/rss.xml via @astrojs/rss
Nav updates across desktop, mobile menu, and footer
Layout.astro modified to accept optional canonical prop

The canonical URL override is the key detail. When the same post lives on both startaitools.com and intentsolutions.io, Google needs to know which is the original. The canonical prop lets each field note point back to the source URL, avoiding duplicate content penalties while still serving the content on both domains.

A backfill script (sync-to-intentsolutions.sh) handles the ongoing sync. Write a post on startaitools.com, run the script, it appears on intentsolutions.io if the tags match.

CodeRabbit Catches a No-Op Filter

The second intentsolutions.io commit is the small one with the lesson. The field notes listing page had a filter:

posts.filter(post => !post.data.featured || post.data.featured !== undefined)

This filter does nothing. If featured is falsy, the first condition is true. If featured is truthy, it's definitely not undefined, so the second condition is true. Every post passes. It's a no-op masquerading as a filter.

CodeRabbit caught it in PR review. Not a human. An AI reviewer. The fix was one line — remove the dead filter. But the pattern is instructive: conditional logic with OR operators where both branches are always true. It's the boolean equivalent of if (true). Easy to write, hard to spot in review, especially when the variable names suggest the filter should be doing something meaningful.

Cross-Repo Plugin Sync: repository_dispatch

The plugin marketplace at tonsofskills.com lists plugins from four external repos: box-cloud-filesystem, x-bug-triage-plugin, claude-code-slack-channel, and pr-to-prompt. Until today, syncing required manual triggers. Push to a source repo, remember to trigger the marketplace sync, wait for CI, check it landed.

The fix uses GitHub's repository_dispatch event. Each source repo got a notify-marketplace.yml workflow:

on:
  push:
    branches: [main]

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - uses: peter-evans/repository-dispatch@v3
        with:
          token: ${{ secrets.MARKETPLACE_SYNC_PAT }}
          repository: owner/marketplace-repo
          event-type: external-plugin-update
          client-payload: '{"repo": "${{ github.repository }}"}'

The marketplace repo's sync-external.yml listens for repository_dispatch events with that event type. Push to any source repo, the marketplace syncs automatically. No human in the loop.

The x-bug-triage-plugin was the first to use this pipeline. Five skills, four agents, and an MCP server synced to the marketplace on the same commit that deployed the dispatch trigger. box-cloud-filesystem also got re-synced with its latest upstream.

This closes the loop on the external sync system built in January. That system used a cron schedule — daily syncs at midnight. The repository_dispatch approach is event-driven. Push to source, marketplace updates in minutes instead of waiting for the next cron window.

The Distribution Graph

After today, the content flow looks like this:

startaitools.com (Hugo, source of truth) publishes daily work diary posts. A subset gets synced to intentsolutions.io (Astro, corporate) as field notes, filtered by professional tags, with canonical URLs pointing back to source. The full archive gets synced to tonsofskills.com (Astro, marketplace) as the Work Diary section.

Plugin repos push to main. repository_dispatch fires. The marketplace syncs within minutes. No cron. No manual triggers.

Three sites. One content pipeline. Zero manual steps after the initial publish.

The Broader Pattern

Content distribution is a solved problem for media companies. Syndication, RSS, cross-posting APIs — the tooling exists. For small dev shops running three Astro/Hugo sites and a plugin marketplace, the tooling doesn't exist. You build it yourself.

The investment was eight commits across two repos. The return is that every post written on startaitools.com now reaches three audiences automatically, and every plugin update reaches the marketplace without human intervention. The marginal cost of the next post or the next plugin sync is zero.

That's the whole point of infrastructure. You pay once, then it compounds.

Related Posts:

Building External Plugin Sync: Keeping Community Plugins Fresh — The January cron-based sync system that today's repository_dispatch replaces
X Bug Triage Plugin: Zero to v0.4.3 in One Day — The plugin that got its first marketplace sync today
Content Quality War: 7-Check Audit Across 340 Plugins — The content quality standards that the sync pipeline now enforces automatically

Usable, Not Just Functional: Entity Selection, Binary Eval, and 6 UX Fixes Across 4 Repos

Jeremy Longshore — Fri, 27 Mar 2026 04:49:42 +0000

Functional is table stakes. Usable is the moat.

March 24th was a 40+ commit day spread across four repositories. The theme wasn't new capabilities. It was making existing capabilities pleasant to operate. Entity selection that highlights the right rectangle instead of a wrong one. Confirmation feedback after every review command. Color-coded tags that match their overlay boxes. The kind of work that separates a prototype from a tool someone uses twice.

CAD Entity Selection: The Bounding Box Problem

The entity selection UX in cad-dxf-agent had a fundamental problem. When you clicked an entity in the viewer, the highlight overlay was wrong.

Not subtly wrong. Wrong by entire model units.

The frontend was using hardcoded ±10 model units from the entity centroid to draw selection rectangles. For a door schedule text block that spans 200 units, the highlight covered maybe 5% of the actual entity. For a tiny dimension tick, the highlight was 20x too large. Every selection looked broken because it was.

Real Bounding Boxes from the Backend

The fix required the backend to compute actual entity bounding boxes and send them to the frontend. Not approximate. Not "close enough." Real bounds from the DXF geometry.

def compute_entity_bounds(entity) -> dict:
    """Compute actual bounding box from entity geometry, not centroids."""
    if entity.dxftype() == 'LINE':
        start, end = entity.dxf.start, entity.dxf.end
        return {
            'min_x': min(start.x, end.x),
            'min_y': min(start.y, end.y),
            'max_x': max(start.x, end.x),
            'max_y': max(start.y, end.y),
        }
    # INSERT, TEXT, MTEXT, LWPOLYLINE — each has its own geometry extraction
    ...

Every DXF entity type stores its geometry differently. A LINE has start/end points. A LWPOLYLINE has a vertex list. An INSERT (block reference) requires resolving the block definition, applying scale and rotation, then computing the transformed bounds. TEXT and MTEXT need font metrics to get the width right.

The hardcoded ±10 was a shortcut from week one. It worked well enough to prove the concept. But "well enough" in a selection UI means "wrong every time in a way the user notices immediately."

Color-Cycling Selection Highlights

With correct bounding boxes, the next step was visual differentiation. When you select three entities for a chat prompt, which highlight goes with which tag?

Six-color palette, assigned by selection index:

const SELECTION_COLORS = [
  'rgba(59, 130, 246, 0.3)',   // blue
  'rgba(16, 185, 129, 0.3)',   // emerald
  'rgba(245, 158, 11, 0.3)',   // amber
  'rgba(139, 92, 246, 0.3)',   // purple
  'rgba(236, 72, 153, 0.3)',   // pink
  'rgba(6, 182, 212, 0.3)',    // cyan
];

The same color index applies to both the viewer overlay rectangle and the entity tag in the chat panel. Select entity #1, get a blue box and a blue tag. Entity #2 gets emerald. No guessing which tag maps to which highlight.

Click-to-Focus Operations

The diff comparison already generates a planned operations checklist — "MOVE door D-101 from grid A to grid B," "DELETE redundant hatch pattern." Those operations sat in a text list. You had to find the referenced entity yourself.

Now they're clickable. Click an operation, the viewer pans and zooms to the target entity. The backend computes bounds per operation, the frontend does the camera math. The drawing is the navigation UI.

The Diff Detection Fix

Separate from the UX work, the diff comparison engine had a bug: MODIFIED and MOVED categories never appeared. Everything was either ADDED or DELETED.

Root cause: match_search_radius and geometric tolerance were the same value. The search radius determines how far the algorithm looks for potential matches. The tolerance determines how close two entities must be to count as the same entity. When they're identical, the algorithm finds a candidate and immediately rejects it — the match is exactly at the boundary, and floating-point rounding pushes it out.

The fix split them:

MATCH_SEARCH_RADIUS = 50.0   # how far to look for candidates
GEOMETRIC_TOLERANCE = 1.0     # how close to count as "same entity"
MOVE_THRESHOLD = 5.0          # minimum distance to classify as MOVED vs MODIFIED

Three distinct thresholds for three distinct questions. The move_threshold was also too low — entities with minor coordinate drift from re-export were classified as MOVED when they should have been MODIFIED. Raising it to 5.0 model units resolved the false positives.

A separate bug: block ATTRIBs (text attributes on block references) weren't captured during comparison. Two otherwise-identical door blocks with different room number ATTRIBs looked identical to the diff engine. Now ATTRIB text is included in the entity fingerprint.

PR #129 landed with 16 files changed. PR review caught a missing <label> element for accessibility, an undocumented magic number, and a SIM103 lint warning. All fixed before merge.

j-rig-binary-eval: Zero to v0.2.8

A brand new project went from git init to v0.2.8 in a single day. Thirty-plus commits.

j-rig-binary-eval is a calibration framework for evaluating Claude Code skill quality. Not "does this skill run without errors" — that's CI. Binary eval asks "does this skill produce output that a senior engineer would approve?" Judgment layers, calibration curves, scoring rubrics, experiment design.

The day broke into phases.

Phase 1: Governance scaffolding. CLAUDE.md, beads integration, doc-filing index, master build blueprint. Ten epic reference files (EPIC-01 through EPIC-10) defining the full system architecture before writing a line of application code.

Phase 2: Templates library. Forty-seven reference files imported from the enterprise template collection. Immediately audited for bloat: 9 files deleted (~975 lines), 6 stale enterprise standards removed (~7,500 lines). The templates library was bigger than the project it was meant to serve.

This is a pattern worth calling out. Enterprise template libraries grow monotonically. Nobody deletes templates. The audit removed files that hadn't been referenced in 6+ months and standards documents from a previous org structure. The remaining templates are the ones that actually get used.

Phase 3: Pattern A README. The one-pager + operator-grade system analysis format. Title, tagline, badges, links, W5 table, stack table, key differentiators, then the full operator section. This README format exists so any engineer can understand the project in 90 seconds and operate it in 5 minutes.

The project is pre-code. All 30+ commits are governance, architecture, and planning artifacts. No application logic yet. That's intentional. The binary eval framework needs to be right before it's fast. Getting the epic structure, scoring rubrics, and experiment design wrong means rebuilding the calibration pipeline later.

X Bug Triage Plugin: Six UX Enhancements

The x-bug-triage-plugin shipped v0.4.4 with six targeted UX improvements via PR #19. Yesterday was the zero-to-v0.4.3 sprint. Today was making it feel finished.

E1: Action confirmation feedback. All 11 review commands (approve, reject, defer, escalate, etc.) now emit a structured confirmation response. Before: the command ran silently. The user had to query the state to confirm it worked. After: immediate feedback with the action taken, the affected entity, and the new state.

E2: Freshness assessment. Source data ages. A tweet from 3 hours ago is fresh. A tweet from 3 weeks ago might reference a bug that's already fixed. The freshness system assigns date_confidence bands — HIGH (< 24h), MEDIUM (1-7d), LOW (7-30d), STALE (> 30d) — and surfaces warnings when the triage pipeline processes stale data.

E3: Source status header. Aggregates a DegradationReport per X API endpoint. If the tweets endpoint is returning 429s, the header shows it. If the search endpoint is slow, the header shows latency. Operators see API health at a glance instead of discovering it when a command fails.

E4: File-based JSON cache. Opt-in caching layer for X API responses. Development and testing no longer require live API calls. The cache writes JSON files with request fingerprints as filenames. DEBUG_CACHE logging shows hit/miss rates.

E5: Hybrid dedup. The original dedup was exact-match on tweet ID. Duplicate content across different tweets (retweets, quote tweets, copy-paste reports) passed through. The new hybrid approach combines character-trigram similarity with token-Jaccard scoring. Two tweets with 85%+ trigram overlap and 80%+ token-Jaccard get flagged as semantic duplicates before clustering.

E6: Per-tier evidence counts. The summary and detail views now show evidence counts broken down by severity tier. "3 CRITICAL, 7 HIGH, 12 MEDIUM" instead of just "22 bugs." Operators triage by tier, so the counts should match.

Eight new files, 14 modifications, 70 new tests (348 total), zero breaking changes.

PR review caught three things: magic numbers that should be extracted constants, fixed-width column padding that should be dynamic, and DEBUG_CACHE logging that was always on instead of opt-in. All addressed before merge.

The mermaid architecture diagram in the README was also replaced with a plain text flow diagram. Mermaid doesn't render on GitHub Pages. A tool that documents itself with diagrams nobody can see isn't documenting itself.

The Pattern

Three projects, same lesson. The CAD tool had real entity selection from day one — the highlight was just in the wrong place. The triage plugin had all 11 review commands — they just didn't confirm they worked. The binary eval framework had enterprise templates — most of them were dead weight.

Functional is the first 80%. Usable is the remaining 80%.

The common thread across all of today's work: removing the gap between "this technically works" and "this is pleasant to use." Correct bounding boxes. Color-coded selections. Confirmation messages. Freshness warnings. Evidence counts by tier. None of these are features. They're the absence of friction.

Related Posts:

X Bug Triage Plugin: Zero to v0.4.3 in One Day — the bootstrap sprint this work builds on
PDF Extraction Bugs, Broadcast Persistence, and a 42-Commit Sweep Day — another heavy multi-repo day with CAD debugging
Building a Deterministic DXF Comparison Engine in One Day — the original diff engine that today's MODIFIED/MOVED fix corrects

The Evolution of a Development Machine: 20 Days from Ubuntu Install to Production Powerhouse

Jeremy Longshore — Wed, 25 Mar 2026 22:57:24 +0000

The Journey: From Fresh Ubuntu to Full-Stack Development Environment

Today I want to share the incredible 20-day evolution of my Ubuntu development machine. Using file timestamps and git history, I've reconstructed the exact timeline of how a fresh Linux install became a production powerhouse running multiple SaaS projects, processing millions of data points, and generating content automatically.

Day 0: August 25, 2025 - The Beginning

5:00 PM: Fresh Ubuntu installation

.bashrc and .profile created
User account established
Basic system configuration

The machine starts its life as a blank canvas.

Day 1: August 26 - Foundation Building

Morning (8:00 AM - 12:00 PM):

Railway deployment platform configured
Docker installation and setup
Chrome profiles for testing environments

Afternoon (2:00 PM - 6:00 PM):

SSH keys generated for GitHub
Git configuration
Claude.ai integration setup

Evening (8:00 PM - 11:00 PM):

Initial project directories created
VS Code extensions installed

Days 2-4: August 27-29 - Tool Arsenal Assembly

August 27:

Netlify CLI installation
Node.js environment setup
Python virtual environments

August 28:

Google Cloud SDK installation begins
BigQuery CLI tools
Cloud SQL proxy setup

August 29:

Codex integration
AI coding assistants configured
First automated scripts written

Day 6: August 31 - Docker Revolution

9:00 AM - 10:00 PM:

Docker Compose configurations
Multi-container development environments
Database containers (PostgreSQL, Redis)
First microservices architecture sketched

Days 7-10: September 1-4 - The Project Explosion

September 1-2: DiagnosticPro Birth

SvelteKit project initialized
50+ components created
Tailwind CSS integration
First deployment to production

September 3: Data Architecture

BigQuery schema design begins
First 50 tables created
Real-time data pipeline planned

September 4:

Gemini API integration
AI feature development
226 RSS feeds configured

Days 11-13: September 6-8 - The Great Scaling

September 6: Content Pipeline

N8N workflow automation installed
Daily content generation workflows
Reddit scraper (500K+ posts collected)
YouTube data extractor built

September 7: Blog Platform Launch

Hugo static site generator
Two separate blogs created:
- jeremylongshore.com (personal)
- startaitools.com (business)
10 initial posts written

September 8: Cloud Native

Google Cloud integration complete
254 BigQuery tables in production
Netlify auto-deployment
CI/CD pipelines operational

Days 14-17: September 9-12 - Enterprise Evolution

September 9:

Project management structure created
Handoff documentation system
Active/Archive pattern established

September 10: System Optimization

Performance monitoring
Log aggregation
Error tracking
Analytics dashboard

September 11: DiagnosticPro Features

Payment integration (Stripe)
User authentication
Real-time diagnostics
AI-powered analysis

September 12: Master Documentation

27,440-word master document created
Complete system architecture documented
API specifications written
Database schemas finalized (266 tables!)

Days 18-19: September 13 - The Great Reorganization

1:00 AM - 3:00 AM: Directory Cleanup

29 empty directories removed
7 old backups archived
3 duplicate projects consolidated
9 comprehensive READMEs created

10:00 AM - 2:00 PM: Content Migration

Blog migration from Archie to Hugo Book theme
15 posts reorganized
Learning paths created
Glossary system implemented

3:00 PM - 11:00 PM: Open Source Contributions

Bob's Brain released to community
AI documentation shared
Multiple PRDs created

Day 20: September 14 - The Professional Toolkit

12:00 AM - 4:00 AM: AI Dev Tasks Creation

16 professional documentation templates
8,465+ lines of documentation
Complete SDLC coverage
Open sourced with full attribution

The Current State: A Production Powerhouse

By The Numbers (20 Days)

Code & Development

Lines of Code Written: 150,000+
Git Commits: 500+
Projects Active: 7
Projects Completed: 3
Open Source Contributions: 2

Data & Infrastructure

BigQuery Tables: 266
Data Processed: 10GB+
RSS Feeds Monitored: 226
Reddit Posts Collected: 500,000+
API Integrations: 15+

Content & Documentation

Blog Posts Published: 25+
Documentation Pages: 50+
PRDs Created: 6
Templates Developed: 16
Total Words Written: 200,000+

Automation & Efficiency

N8N Workflows: 10+
Automated Tasks: 50+
Time Saved Weekly: 20+ hours
Deployment Pipelines: 5

The Directory Structure Evolution

Day 1:  /home/jeremy/ (empty)
Day 5:  3 directories, 10 files
Day 10: 15 directories, 200+ files
Day 15: 30 directories, 1000+ files
Day 20: Organized hierarchy with clear purpose

Current:
/home/jeremy/
├── _ACTIVE_PROJECTS/     # The brain
├── _PROJECT_MANAGEMENT/  # The memory
├── projects/             # The workshop
├── research/             # The library
└── [tools & utilities]   # The toolkit

Key Learnings

Week 1: Foundation is Everything

Spend time on tooling setup
Automate from day one
Version control everything

Week 2: Embrace the Chaos

Multiple projects accelerate learning
Cross-pollination of ideas
Document as you build

Week 3: Organization Scales

Structure enables creativity
Archives preserve knowledge
Automation compounds value

The Philosophy That Emerged

"Every action should create value beyond its immediate purpose"

Writing code? Generate documentation
Solving problems? Create blog posts
Building features? Design templates
Learning tools? Share tutorials

Tools That Made the Difference

The MVPs

Claude/Cursor: AI pair programming
Hugo: Lightning-fast static sites
N8N: Workflow automation
BigQuery: Massive data processing
Docker: Consistent environments

The Unsung Heroes

tmux: Terminal multiplexing
ripgrep: Fast searching
jq: JSON processing
GitHub Actions: CI/CD
Netlify: Instant deployments

What's Next: Days 21-30

Planned Enhancements

Kubernetes orchestration
Multi-region deployment
ML model integration
Real-time analytics dashboard
Community platform launch

Expected Metrics

500K+ daily data points
50+ automated workflows
100+ blog posts
5 production applications
1M+ users served

The Transformation

In 20 days, this Ubuntu machine went from a fresh install to:

Development Hub: 7 active projects
Data Processor: 266 BigQuery tables
Content Factory: 25+ blog posts
Automation Center: 50+ automated tasks
Learning Platform: Comprehensive documentation
Open Source Contributor: Multiple projects shared

Conclusion: The Power of Momentum

The most striking revelation from this timeline is the exponential nature of development momentum. Each day built upon the previous, each tool enabled new capabilities, and each project informed the next.

What started as a blank Ubuntu installation became a sophisticated development environment processing millions of data points, running multiple production applications, and automatically generating content.

The machine isn't just a tool anymore - it's a partner in creation, a repository of knowledge, and a launchpad for ideas.

Your Turn

Want to build your own development powerhouse? Here's my advice:

Document everything - Your future self will thank you
Automate early - Even simple tasks
Organize often - Don't wait for "later"
Share freely - Open source amplifies impact
Build daily - Momentum is everything

This Ubuntu machine has been running for 20 days, 8 hours, and 30 minutes.

Total uptime: 99.8%

Total value created: Immeasurable

Terraform for AI Infrastructure: Complete Learning Guide from Zero to Production

Jeremy Longshore — Wed, 25 Mar 2026 22:57:13 +0000

Terraform for AI Infrastructure: Complete Learning Guide

TL;DR: Learn Infrastructure as Code with Terraform from beginner to advanced. Covers core concepts, state management, modules, best practices, and production deployment patterns for AI infrastructure.

What is Terraform?

Terraform is an Infrastructure as Code (IaC) tool that lets you define and provision cloud infrastructure using declarative configuration files instead of manual clicking in web consoles.

Key Benefits

Declarative Configuration: Describe what you want, not how to get there
Plan Before Apply: Preview all changes before execution
Version Control: Track infrastructure changes in Git
Multi-Cloud: Works with AWS, GCP, Azure, and 100+ providers
Idempotent: Safe to run multiple times without side effects

How It Works

1. Write Configuration (.tf files)
   ↓
2. terraform init (Download providers)
   ↓
3. terraform plan (Preview changes)
   ↓
4. terraform apply (Execute changes)
   ↓
5. Infrastructure Created/Updated

Core Concepts

1. Providers

Providers are plugins that interact with cloud platform APIs:

# Configure the Google Cloud Provider
provider "google" {
  project = "my-ai-project"
  region  = "us-central1"
}

# Configure AWS Provider
provider "aws" {
  region = "us-west-2"
}

2. Resources

Resources describe infrastructure objects:

# Create a Cloud Storage bucket for ML models
resource "google_storage_bucket" "ml_models" {
  name     = "my-ai-project-models"
  location = "US"

  versioning {
    enabled = true
  }

  lifecycle_rule {
    action {
      type = "Delete"
    }
    condition {
      age = 90  # Delete old models after 90 days
    }
  }
}

# Create Compute Instance for training
resource "google_compute_instance" "training_vm" {
  name         = "ml-training-vm"
  machine_type = "n1-standard-8"
  zone         = "us-central1-a"

  boot_disk {
    initialize_params {
      image = "deeplearning-platform-release/tf2-gpu-2-11-cu113"
      size  = 100
    }
  }

  network_interface {
    network = "default"
    access_config {}
  }
}

3. Variables

Make configurations reusable:

# variables.tf
variable "project_id" {
  description = "GCP Project ID"
  type        = string
}

variable "environment" {
  description = "Environment (dev, staging, prod)"
  type        = string

  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "Environment must be dev, staging, or prod"
  }
}

variable "ml_model_bucket" {
  description = "Bucket for ML models"
  type        = string
  default     = "ml-models"
}

# Use variables
resource "google_storage_bucket" "models" {
  name     = "${var.project_id}-${var.environment}-${var.ml_model_bucket}"
  location = "US"
}

4. Outputs

Expose information about your infrastructure:

# outputs.tf
output "bucket_url" {
  description = "URL of ML models bucket"
  value       = google_storage_bucket.models.url
}

output "training_vm_ip" {
  description = "Public IP of training VM"
  value       = google_compute_instance.training_vm.network_interface[0].access_config[0].nat_ip
}

5. Data Sources

Query existing infrastructure:

# Get current project info
data "google_project" "current" {}

# Get latest GPU-enabled image
data "google_compute_image" "gpu_image" {
  family  = "pytorch-latest-gpu"
  project = "deeplearning-platform-release"
}

# Use in resource
resource "google_compute_instance" "gpu_vm" {
  name         = "gpu-training"
  machine_type = "n1-standard-8"

  boot_disk {
    initialize_params {
      image = data.google_compute_image.gpu_image.self_link
    }
  }
}

State Management

Terraform tracks infrastructure state in a .tfstate file.

Local State (Development)

# Default: state stored locally
# terraform.tfstate in current directory

Remote State (Production)

Google Cloud Storage:

# backend.tf
terraform {
  backend "gcs" {
    bucket = "my-terraform-state"
    prefix = "ai-infrastructure/state"
  }
}

AWS S3:

terraform {
  backend "s3" {
    bucket = "my-terraform-state"
    key    = "ai-infra/terraform.tfstate"
    region = "us-west-2"

    dynamodb_table = "terraform-locks"
    encrypt        = true
  }
}

State Management Commands

# View state
terraform show

# List resources in state
terraform state list

# Remove resource from state (doesn't delete resource)
terraform state rm google_storage_bucket.example

# Move resource in state (rename)
terraform state mv google_storage_bucket.old google_storage_bucket.new

# Refresh state from real infrastructure
terraform refresh

Modules: Reusable Infrastructure Components

Module Structure

terraform/
├── modules/
│   └── ml-training-vm/
│       ├── main.tf       # Resources
│       ├── variables.tf  # Input variables
│       └── outputs.tf    # Output values
└── environments/
    ├── dev/
    │   └── main.tf      # Uses modules
    └── prod/
        └── main.tf

Creating a Module

modules/ml-training-vm/main.tf:

resource "google_compute_instance" "training_vm" {
  name         = "${var.name_prefix}-training-vm"
  machine_type = var.machine_type
  zone         = var.zone

  boot_disk {
    initialize_params {
      image = var.boot_image
      size  = var.disk_size_gb
    }
  }

  network_interface {
    network = var.network
    access_config {}
  }

  metadata = {
    environment = var.environment
    managed_by  = "terraform"
  }
}

modules/ml-training-vm/variables.tf:

variable "name_prefix" {
  description = "Prefix for resource names"
  type        = string
}

variable "machine_type" {
  description = "Machine type for VM"
  type        = string
  default     = "n1-standard-8"
}

variable "zone" {
  description = "GCP zone"
  type        = string
  default     = "us-central1-a"
}

variable "environment" {
  description = "Environment name"
  type        = string
}

Using a Module

environments/prod/main.tf:

module "training_vm" {
  source = "../../modules/ml-training-vm"

  name_prefix  = "prod-ml"
  machine_type = "n1-highmem-16"
  zone         = "us-central1-a"
  environment  = "production"
}

# Access module outputs
output "training_vm_ip" {
  value = module.training_vm.instance_ip
}

Best Practices

1. Project Structure

terraform/
├── environments/
│   ├── dev/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   ├── terraform.tfvars
│   │   └── backend.tf
│   ├── staging/
│   └── prod/
├── modules/
│   ├── compute/
│   ├── networking/
│   └── storage/
└── shared/
    ├── providers.tf
    └── versions.tf

2. Naming Conventions

# Resource naming: project-environment-service-resource
resource "google_storage_bucket" "ml_models" {
  name = "${var.project_id}-${var.environment}-ml-models"
}

# Variable naming: descriptive and clear
variable "ml_training_instance_tier" {
  description = "Machine tier for ML training instance"
  type        = string
  default     = "n1-standard-8"
}

3. Version Constraints

# versions.tf
terraform {
  required_version = ">= 1.0"

  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 5.0"
    }
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

4. Resource Tagging/Labeling

# Consistent labeling across all resources
locals {
  common_labels = {
    environment = var.environment
    project     = var.project_name
    managed_by  = "terraform"
    team        = var.team_name
    cost_center = var.cost_center
  }
}

resource "google_storage_bucket" "ml_models" {
  name   = var.bucket_name
  labels = local.common_labels
}

resource "google_compute_instance" "training" {
  name   = var.instance_name
  labels = local.common_labels
}

5. Secrets Management

# Don't store secrets in .tf files!
variable "database_password" {
  description = "Database password"
  type        = string
  sensitive   = true  # Marks as sensitive in outputs
}

# Use random provider for generated secrets
resource "random_password" "db_password" {
  length           = 32
  special          = true
  override_special = "!#$%&*()-_=+[]{}<>:?"
}

# Store in Secret Manager
resource "google_secret_manager_secret" "db_password" {
  secret_id = "db-password"

  replication {
    automatic = true
  }
}

resource "google_secret_manager_secret_version" "db_password_version" {
  secret      = google_secret_manager_secret.db_password.id
  secret_data = random_password.db_password.result
}

Advanced Topics

1. Terraform Workspaces

Manage multiple environments with one configuration:

# Create workspace
terraform workspace new staging

# List workspaces
terraform workspace list

# Switch workspace
terraform workspace select prod

# Current workspace
terraform workspace show

Use in configuration:

locals {
  environment = terraform.workspace

  machine_types = {
    dev     = "n1-standard-2"
    staging = "n1-standard-4"
    prod    = "n1-standard-8"
  }

  machine_type = local.machine_types[terraform.workspace]
}

resource "google_compute_instance" "app" {
  name         = "${terraform.workspace}-app-server"
  machine_type = local.machine_type
}

2. Dependencies

Implicit dependency (recommended):

resource "google_storage_bucket" "ml_data" {
  name = "ml-training-data"
}

resource "google_storage_bucket_object" "dataset" {
  bucket = google_storage_bucket.ml_data.name  # Implicit dependency
  name   = "dataset.csv"
  source = "data/dataset.csv"
}

Explicit dependency:

resource "google_compute_instance" "training_vm" {
  name = "training-vm"

  depends_on = [
    google_storage_bucket.ml_data,
    google_storage_bucket.ml_models
  ]
}

3. Import Existing Infrastructure

# Import existing bucket
terraform import google_storage_bucket.existing my-existing-bucket

# Then write configuration to match
resource "google_storage_bucket" "existing" {
  name     = "my-existing-bucket"
  location = "US"
}

# Verify import
terraform plan  # Should show no changes

Real-World Example: ML Training Infrastructure

Complete setup for machine learning training:

# main.tf
terraform {
  required_version = ">= 1.0"

  backend "gcs" {
    bucket = "my-terraform-state"
    prefix = "ml-infrastructure/state"
  }

  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 5.0"
    }
  }
}

provider "google" {
  project = var.project_id
  region  = var.region
}

# Locals for common values
locals {
  common_labels = {
    environment = var.environment
    project     = "ml-training"
    managed_by  = "terraform"
  }
}

# Storage buckets
resource "google_storage_bucket" "training_data" {
  name          = "${var.project_id}-${var.environment}-training-data"
  location      = var.region
  force_destroy = false

  labels = local.common_labels

  versioning {
    enabled = true
  }

  lifecycle_rule {
    action {
      type = "Delete"
    }
    condition {
      age = 90
    }
  }
}

resource "google_storage_bucket" "ml_models" {
  name          = "${var.project_id}-${var.environment}-models"
  location      = var.region
  force_destroy = false

  labels = local.common_labels

  versioning {
    enabled = true
  }
}

# Training VM with GPU
resource "google_compute_instance" "gpu_training" {
  name         = "${var.environment}-gpu-training"
  machine_type = var.gpu_machine_type
  zone         = var.zone

  labels = local.common_labels

  boot_disk {
    initialize_params {
      image = "deeplearning-platform-release/pytorch-latest-gpu"
      size  = 100
      type  = "pd-ssd"
    }
  }

  guest_accelerator {
    type  = "nvidia-tesla-t4"
    count = 1
  }

  scheduling {
    on_host_maintenance = "TERMINATE"  # Required for GPU instances
  }

  network_interface {
    network = "default"
    access_config {}
  }

  service_account {
    scopes = ["cloud-platform"]
  }

  metadata_startup_script = file("${path.module}/scripts/startup.sh")
}

# BigQuery dataset for analytics
resource "google_bigquery_dataset" "ml_analytics" {
  dataset_id = "${var.environment}_ml_analytics"
  location   = var.region

  labels = local.common_labels

  access {
    role          = "OWNER"
    user_by_email = var.admin_email
  }
}

# Outputs
output "training_data_bucket" {
  value = google_storage_bucket.training_data.name
}

output "models_bucket" {
  value = google_storage_bucket.ml_models.name
}

output "gpu_vm_ip" {
  value = google_compute_instance.gpu_training.network_interface[0].access_config[0].nat_ip
}

output "bigquery_dataset" {
  value = google_bigquery_dataset.ml_analytics.dataset_id
}

variables.tf:

variable "project_id" {
  description = "GCP Project ID"
  type        = string
}

variable "region" {
  description = "GCP region"
  type        = string
  default     = "us-central1"
}

variable "zone" {
  description = "GCP zone"
  type        = string
  default     = "us-central1-a"
}

variable "environment" {
  description = "Environment name"
  type        = string

  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "Must be dev, staging, or prod"
  }
}

variable "gpu_machine_type" {
  description = "Machine type for GPU training"
  type        = string
  default     = "n1-standard-8"
}

variable "admin_email" {
  description = "Admin email for BigQuery access"
  type        = string
}

terraform.tfvars:

project_id       = "my-ai-project"
region           = "us-central1"
zone             = "us-central1-a"
environment      = "prod"
gpu_machine_type = "n1-standard-8"
admin_email      = "admin@example.com"

Common Pitfalls & Solutions

1. State File Conflicts

Problem: Multiple team members modifying infrastructure simultaneously

Solution: Use remote state with locking

terraform {
  backend "gcs" {
    bucket = "terraform-state"
    prefix = "prod"
  }
}

2. Hardcoded Values

Problem: Credentials and secrets in code

Solution: Use variables and secret management

# Bad
resource "google_sql_database_instance" "db" {
  root_password = "hardcoded-password-123"
}

# Good
resource "google_sql_database_instance" "db" {
  root_password = var.db_password  # From env var or secret manager
}

3. No Version Constraints

Problem: Provider updates break infrastructure

Solution: Pin provider versions

terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 5.0"  # Allow 5.x updates, not 6.0
    }
  }
}

Essential Commands

# Initialize working directory
terraform init

# Validate configuration
terraform validate

# Format code
terraform fmt -recursive

# Preview changes
terraform plan

# Apply changes
terraform apply

# Destroy infrastructure
terraform destroy

# Show current state
terraform show

# List resources
terraform state list

# Import existing resource
terraform import <resource_type>.<name> <id>

# Refresh state
terraform refresh

# Output values
terraform output

Learning Resources

Official Documentation

Best Practices

Tutorials

Key Takeaways

Infrastructure as Code - Treat infrastructure like software
State Management - Always use remote state in production
Modules - Build reusable components
Version Control - Track all infrastructure changes in Git
Plan First - Always review terraform plan before applying
Security - Never commit secrets, use Secret Manager
Consistency - Use naming conventions and labels

What's Next

Set up remote state backend
Create reusable modules for common patterns
Implement CI/CD for infrastructure changes
Add automated testing with terraform validate and tflint
Explore advanced features like for_each and dynamic blocks

Questions or feedback: jeremy@intentsolutions.io
GitHub: @jeremylongshore

Educational resource from Intent Solutions for AI infrastructure and DevOps practitioners.

Self-Hosting n8n on Contabo VPS: Enterprise Automation for $0/Month

Jeremy Longshore — Wed, 25 Mar 2026 22:51:50 +0000

We just deployed a production-ready n8n instance at n8n.intentsolutions.io with zero monthly software costs. Here's the complete technical architecture and deployment process.

The Business Case

Before: Paying $20+/month for n8n Cloud
After: $0/month on existing Contabo VPS
Setup Time: 2 hours
ROI: Infinite (one-time setup, zero recurring cost)

Architecture Overview

┌─────────────────────────────────────┐
│   n8n.intentsolutions.io (DNS)      │
│   ↓                                  │
│   194.113.67.242:443 (HTTPS)        │
│   ↓                                  │
│   Caddy Reverse Proxy               │
│   - Auto SSL (Let's Encrypt)        │
│   - Port 443 (HTTPS)                │
│   ↓                                  │
│   Docker Container: n8n             │
│   - Port 5678 (internal)            │
│   - SQLite database                 │
│   - Persistent data: ./data         │
│   - Backups: ./backups              │
└─────────────────────────────────────┘

Technical Challenge: Port Conflicts

The server was already running:

Port 80: Apache2 (existing web server)
Port 443: Needed for n8n HTTPS
Port 8080: Caddy file browser

Solution: Configure Caddy with auto_https disable_redirects to handle HTTPS only without requiring port 80:

{
    auto_https disable_redirects
}

n8n.intentsolutions.io:443 {
    reverse_proxy localhost:5678
}

Docker Configuration

Key decisions for production stability:

Network Mode: host (avoids port mapping conflicts)

services:
  n8n:
    image: n8nio/n8n:latest
    network_mode: "host"
    environment:
      - N8N_HOST=n8n.intentsolutions.io
      - N8N_PROTOCOL=https
      - WEBHOOK_URL=https://n8n.intentsolutions.io/

Database: SQLite (perfect for single-user/small team)

environment:
  - DB_TYPE=sqlite
  - DB_SQLITE_VACUUM_ON_STARTUP=true

Workflow Import Process

Imported 15 workflows using n8n CLI:

# Prepare workflows (remove problematic fields)
jq 'del(.id, .versionId, .tags) | . + {active: false}' workflow.json > clean.json

# Copy to container
docker cp workflows/ n8n:/tmp/

# Import via CLI
docker exec -u node n8n n8n import:workflow --separate --input=/tmp/workflows/

Result: Successfully imported:

Daily Energizer Article Generator V4
Tech/AI News Pipeline
Lead Follow-up System (with Bland.ai integration)
AI Blog Journalist
Upwork Proposal Generator
Disposable Marketplace
Gmail Drive Organizer

SSL Certificate Automation

Caddy automatically obtains SSL certificates from Let's Encrypt on first HTTPS request. No manual certificate management required.

Certificate Location: /var/lib/caddy/.local/share/caddy/certificates/

Security Hardening

Basic Authentication: Enabled with secure password
HTTPS Enforced: All traffic over SSL
Firewall: UFW configured for port 443
Environment Variables: Secrets stored in .env (not committed)
API Token: Generated for programmatic access

Performance & Monitoring

Resource Usage:

Memory: ~200MB (n8n container)
CPU: Minimal (idle workflows)
Storage: SSD on Contabo VPS

Monitoring Commands:

# Container health
docker ps | grep n8n

# Logs
docker logs -f n8n

# Disk usage
du -sh data/ backups/

Cost Comparison

Option	Monthly Cost	Setup Time	Maintenance
n8n Cloud	$20-50+	5 minutes	Zero
Self-Hosted	$0	2 hours	Minimal
Annual Savings	$240-600	One-time	Backups only

Backup Strategy

# Weekly backup script
tar -czf "n8n-backup-$(date +%Y%m%d).tar.gz" ./data
mv n8n-backup-*.tar.gz ./backups/

# Cleanup old backups (30 days)
find ./backups/ -name "n8n-backup-*.tar.gz" -mtime +30 -delete

Lessons Learned

1. Use Existing Infrastructure

We had Caddy already running - adding n8n was just one more config block. Don't deploy redundant services.

2. Network Mode Matters

host networking avoided all port mapping complexity. Sometimes the simple solution is best.

3. SQLite is Underrated

For single-user or small team, SQLite is perfect. No PostgreSQL overhead needed.

4. CLI Import > API

The n8n CLI handled workflow imports reliably. The API had validation issues with exported JSON structure.

Next Steps

Migrate to PostgreSQL (if team grows beyond 5 users)
Set up CI/CD for workflow version control
Configure monitoring/alerts for workflow failures
Implement automated backups to cloud storage

Conclusion

Self-hosting n8n on existing infrastructure eliminated $240-600/year in SaaS costs while maintaining full control over data and workflows. The 2-hour setup investment pays for itself in the first month.

Business Impact:

✅ Zero recurring automation costs
✅ Complete data ownership
✅ Custom domain with SSL
✅ 15 production workflows migrated
✅ Enterprise-grade infrastructure

Repository: n8n-workflows

Want to eliminate your SaaS costs while maintaining enterprise capabilities? Let's talk about self-hosted automation architecture for your business.

Scaling AI Batch Processing: Enhancing 235 Plugins with Vertex AI Gemini on the Free Tier

Jeremy Longshore — Wed, 25 Mar 2026 22:51:36 +0000

The Problem: 235 Plugins Need Comprehensive Documentation

I maintain claude-code-plugins, a marketplace with 235 plugins for Claude Code. Each plugin needed enhanced SKILL.md files (8,000-14,000 bytes) following Anthropic's Agent Skills standards. Doing this manually would take weeks.

The goal: Process all 235 plugins overnight using Vertex AI Gemini 2.0 Flash - entirely on the free tier.

The constraints:

Must stay within Vertex AI free tier limits
Need 100% success rate (no corrupted files)
Require full audit trail for compliance
Zero tolerance for API quota violations

The Journey: From Ultra-Conservative to Optimized

Phase 1: Initial System Design

I built overnight-plugin-enhancer.py with these core components:

# Ultra-conservative rate limiting
RATE_LIMIT_DELAY = 90.0  # 90 seconds base delay
RATE_LIMIT_RANDOMNESS = 30.0  # Add 0-30 seconds random

Why so slow? I wanted to ensure we stayed well under the Vertex AI free tier limits:

1,500 requests/day
235 plugins = 470 API calls (analysis + generation per plugin)
At 90-120s per plugin: ~15 plugins/hour = Safe

The system included:

SQLite Audit Database

def init_database(self):
    cursor.execute('''
        CREATE TABLE IF NOT EXISTS enhancements (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            timestamp TEXT NOT NULL,
            plugin_name TEXT NOT NULL,
            plugin_path TEXT NOT NULL,
            enhancement_type TEXT NOT NULL,
            status TEXT NOT NULL,
            processing_time_seconds REAL
        )
    ''')

Automatic Backups Before Changes

def backup_plugin(self, plugin):
    timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
    backup_dir = BACKUP_DIR / 'plugin-backups' / f"{plugin['name']}_{timestamp}"
    shutil.copytree(plugin_path, backup_dir)

Two-Phase AI Generation

# Phase 1: Analyze and create enhancement plan
plan = self.generate_enhancement_plan(plugin)

# Phase 2: Generate comprehensive SKILL.md
skill_content = self.generate_skill_md(plugin, plan)

Phase 2: Testing and Timeout Issues

First test run on 10 plugins:

timeout 120 python3 overnight-plugin-enhancer.py --limit 10

Problem: Process appeared stuck - no output for minutes.

Diagnosis: Python output buffering. The script was working but output wasn't showing in real-time.

Fix: Unbuffered output flag

python3 -u overnight-plugin-enhancer.py

Result: Real-time log streaming confirmed the system was working perfectly. Each plugin took 90-100 seconds as designed.

Phase 3: Expanding to All Categories

Initially, I only processed 7 plugin categories (testing). Time to go all in:

# Before (testing with 7 categories)
CATEGORIES = [
    'productivity', 'security', 'testing', 'packages',
    'examples', 'community', 'mcp'
]

# After (all 17 categories - full 235 plugins)
CATEGORIES = [
    'productivity', 'security', 'testing', 'packages',
    'examples', 'community', 'mcp', 'ai-agency', 'ai-ml',
    'api-development', 'crypto', 'database', 'devops',
    'fairdb-operations-kit', 'finance', 'performance',
    'skill-enhancers'
]

Started the overnight batch:

nohup python3 -u scripts/overnight-plugin-enhancer.py >> overnight-enhancement-all-plugins.log 2>&1 &

Phase 4: Disaster Recovery Planning

Mid-batch, user concern: "What if I get locked out of GitHub?"

This is a legitimate fear when you have 235 production plugins and rely on GitHub for everything. I needed an off-site backup solution immediately.

Enter Turso: Edge SQLite database with free tier (500 databases, 9GB storage).

Built turso-plugin-backup.sh in 30 minutes:

# Creates comprehensive backup with integrity checks
create_plugins_archive() {
    local archive_name="plugins-$(date +%Y%m%d-%H%M%S).tar.gz"
    tar -czf "$archive_path" -C "$PLUGINS_DIR" .

    # Calculate SHA256 hash for integrity
    local hash=$(sha256sum "$archive_path" | cut -d' ' -f1)
}

# Store metadata in Turso
upload_to_turso() {
    turso db shell "$TURSO_DB_NAME" <<EOF
    INSERT INTO backup_history (timestamp, version, plugin_count,
                                archive_size, backup_metadata)
    VALUES ('$timestamp', '$version', $plugin_count,
            $archive_size, '$metadata');
EOF
}

The backup system includes:

All 235 plugins (tar.gz compressed)
Enhancement SQLite database
Plugin inventory JSON
SHA256 integrity hashes
Turso metadata for queryability

Recovery time objective: < 30 minutes to restore complete repository from Turso.

Related: Building Production Testing Suite with Playwright covers similar disaster recovery planning.

Phase 5: Speed Optimization Request

At 12:53 PM (after 12 hours): 157/235 plugins complete (66%)

User: "Let's speed it up - we have room."

Analysis:

Only using 7-14% of Vertex AI free tier quota
Success rate: 100%
Could safely cut delays in half

Optimization:

# Old: Ultra-conservative
RATE_LIMIT_DELAY = 90.0
RATE_LIMIT_RANDOMNESS = 30.0

# New: Conservative but 2x faster
RATE_LIMIT_DELAY = 45.0
RATE_LIMIT_RANDOMNESS = 15.0

Impact:

Before: ~15 plugins/hour → Completion: 5:30 AM
After: ~30 plugins/hour → Completion: 2:30 AM (saved 3 hours!)

Killed the old process and restarted:

kill 876147
nohup python3 -u scripts/overnight-plugin-enhancer.py >> overnight-enhancement-all-plugins.log 2>&1 &

The system intelligently skips already-enhanced plugins:

skill_path = plugin_path / 'skills' / 'skill-adapter' / 'SKILL.md'
if skill_path.exists() and len(skill_path.read_text()) > 8000:
    print(f"  ⏭️  SKILL.md already comprehensive ({len(content)} bytes)")
    # Skip AI generation, just backup and validate

The Technical Architecture

Rate Limiting Strategy

def apply_rate_limit(self, idx, total):
    """Apply intelligent rate limiting"""
    # Base delay with randomness
    base_delay = RATE_LIMIT_DELAY + random.uniform(0, RATE_LIMIT_RANDOMNESS)
    time.sleep(base_delay)

    # Extra rest every 10 plugins
    if idx % 10 == 0:
        extra_delay = random.uniform(30, 60)
        print(f"  ⏸️  Extra rest break: {extra_delay:.1f}s...")
        time.sleep(extra_delay)

Why this works:

Randomness prevents patterns that might trigger rate limits
Extra breaks every 10 plugins ensure long-term sustainability
Configurable delays allow real-time optimization without code changes

Smart Processing Logic

def process_plugin(self, plugin):
    """Process single plugin with comprehensive enhancement"""
    try:
        # Always backup first (disaster recovery)
        self.backup_plugin(plugin)

        # Generate enhancement plan
        plan = self.generate_enhancement_plan(plugin)

        # Generate or validate SKILL.md
        if needs_generation:
            skill_content = self.generate_skill_md(plugin, plan)
        else:
            print(f"  ⏭️  SKILL.md already comprehensive")

        # Create bundled resource directories
        for resource_type in ['scripts', 'references', 'assets']:
            if plan['bundled_resources_needed'][resource_type]:
                create_resource_directory(resource_type)

        # Log to SQLite audit trail
        self.log_enhancement(plugin, 'success', changes)

    except Exception as e:
        self.log_enhancement(plugin, 'failed', error=str(e))
        raise

Monitoring and Observability

Real-time progress tracking:

# Check current status
tail -f overnight-enhancement-all-plugins.log

# Query database for metrics
sqlite3 backups/plugin-enhancements/enhancements.db \
  "SELECT COUNT(*) FROM enhancements WHERE status = 'success';"

# Get processing time stats
sqlite3 backups/plugin-enhancements/enhancements.db \
  "SELECT AVG(processing_time_seconds), MAX(processing_time_seconds)
   FROM enhancements WHERE status = 'success';"

The Results

Final Metrics (as of 11:30 PM):

Plugins processed: 163/235 (69% complete)
Success rate: 100%
Average SKILL.md size: 10,617 bytes
Processing time: ~60-100 seconds per plugin
API calls used: ~326 of 1,500 daily limit (22%)
Estimated completion: 2:30-3:00 AM

Quality metrics:

All SKILL.md files follow Anthropic Agent Skills standards
Comprehensive documentation (8,000-14,000 bytes each)
Proper YAML frontmatter
Bundled resource directories created
Complete backup trail in SQLite

Lessons Learned

1. Start Conservative, Optimize Later

Initial 90-120s delays seemed wasteful, but they ensured:

No quota violations
100% success rate
Confidence to optimize

Once we had data proving safety margins, cutting to 45-60s was an easy decision.

2. Real-Time Observability is Critical

The unbuffered output fix was crucial. Without seeing real-time progress:

Can't identify stuck processes
Can't calculate accurate completion times
Can't debug issues as they happen

3. Disaster Recovery Before Production

Building the Turso backup system mid-batch was the right call. Production systems need:

Off-site backups (not just local)
Integrity verification (SHA256 hashes)
Fast recovery (< 30 minutes)
Queryable metadata (Turso SQLite)

4. SQLite for Audit Trails

Using SQLite for enhancement tracking provided:

Complete history of every change
Easy querying for metrics
Backup-friendly (just copy the .db file)
No external dependencies

Related: Building 254 BigQuery Schemas in 72 Hours shows similar database-driven automation patterns.

5. Smart Skipping Saves Money

The system automatically skips already-enhanced plugins:

Saves API quota
Reduces processing time
Allows safe restarts after failures
Enables incremental improvements

The Code

Full implementation: claude-code-plugins/scripts/overnight-plugin-enhancer.py

Key files:

overnight-plugin-enhancer.py - Main batch processor
turso-plugin-backup.sh - Disaster recovery system
TURSO-BACKUP-GUIDE.md - Recovery procedures
enhancements.db - SQLite audit trail

What's Next

Immediate (tonight):

[x] Complete batch processing (163/235 done)
[ ] Run Turso backup after completion
[ ] Release v1.2.0 with 235 enhanced plugins

Short-term (this week):

[ ] Generate analytics on enhancement quality
[ ] Spot-check 10 random SKILL.md files
[ ] Deploy marketplace website with new content
[ ] Set up automated weekly backups to Turso

Long-term (future releases):

[ ] Build turso-plugin-restore.sh for automated recovery
[ ] Add Turso backup to release checklist
[ ] Implement progressive enhancement (update existing SKILL.md files)
[ ] A/B test different SKILL.md structures for effectiveness

Try It Yourself

The enhancement system is open source and works with any plugin repository:

# Clone the repo
git clone https://github.com/jeremylongshore/claude-code-plugins
cd claude-code-plugins

# Configure Vertex AI
gcloud auth application-default login

# Test on single plugin
python3 scripts/overnight-plugin-enhancer.py --plugin overnight-dev

# Run batch on 10 plugins
python3 scripts/overnight-plugin-enhancer.py --limit 10

# Full overnight batch
nohup python3 -u scripts/overnight-plugin-enhancer.py >> batch.log 2>&1 &

Requirements:

Google Cloud account with Vertex AI enabled
Python 3.12+
Claude Code plugins repository structure

Free tier limits:

1,500 Vertex AI requests/day
Process ~750 plugins/day (2 calls per plugin)
Completely free for repositories under 1,000 plugins

Conclusion

Batch processing 235 plugins with AI isn't just about throwing API calls at the problem. It requires:

Conservative rate limiting that respects free tier limits
Real-time observability to catch issues immediately
Disaster recovery planning before you need it
Smart optimization based on real data
Complete audit trails for compliance and debugging

The overnight batch will complete around 2:30 AM with 100% success rate, entirely on the Vertex AI free tier. That's 235 plugins × 10KB of AI-generated documentation = 2.3MB of high-quality content created overnight.

Not bad for free.

Want to see the results? Check out claudecodeplugins.io to see the enhanced plugins in action, or explore the complete source code on GitHub.

Have questions about batch processing with Vertex AI? Drop a comment or find me on X @AsphaltCowb0y.

Perception Dashboard: Wiring Real Triggers, Topic Watchlists, and the BSL-1.1 Decision

Jeremy Longshore — Wed, 25 Mar 2026 22:46:13 +0000

What Perception Does

Perception is a media intelligence dashboard. It ingests articles from 128 RSS feeds, scores them by relevance and trending signals, and surfaces the ones that matter through a React dashboard backed by Firestore and a FastAPI MCP service.

The dashboard existed before February. What didn't exist: real data ingestion, interactive topic management, or auto-ingestion on login. The dashboard was running on mock data. This month, the plumbing got real.

Mock to Real: The store_articles Trigger

The mock store_articles function returned fake results. The real implementation uses Firestore batch writes with URL-based deduplication:

# Document ID: art-{sha256(url)[:16]}
doc_id = f"art-{hashlib.sha256(url.encode()).hexdigest()[:16]}"

# Batch writes with merge=True (preserves AI-enriched fields)
batch = db.batch()
for article in articles[:500]:  # Firestore batch limit
    ref = db.collection('articles').document(doc_id)
    batch.set(ref, article_data, merge=True)
batch.commit()

The merge=True strategy is deliberate. When the ingestion pipeline re-processes an article, it preserves any AI-enriched fields (summaries, tags, relevance scores) that were added after the initial store. New raw data merges in without overwriting analysis results.

The orchestration endpoint (POST /trigger/ingestion) loads all 128 RSS sources from a YAML config, fetches feeds with a 10-item semaphore for concurrency control, stores articles in 500-doc batches, and upserts author metadata. It returns 202 immediately and runs the pipeline in a background task, updating a Firestore ingestion_runs document with live phase progress.

Idempotency is built in: if a run is already active, the endpoint returns 409. Stale runs (older than 10 minutes) get auto-cleaned. Success evaluation checks that articles were actually stored, fewer than 50% of sources failed, and the run completed within 5 minutes.

Auto-Ingestion on Login

The login flow now redirects to /dashboard instead of the feed page. On mount, a useAutoIngestion hook fires once per browser session:

const SESSION_KEY = 'perception-auto-ingestion-fired';

useEffect(() => {
  if (sessionStorage.getItem(SESSION_KEY)) return;
  sessionStorage.setItem(SESSION_KEY, '1');

  fetch(`${MCP_URL}/trigger/ingestion`, {
    method: 'POST',
    body: JSON.stringify({ trigger: 'auto', time_window_hours: 24 }),
  });
}, []);

Fire-and-forget. The hook dispatches a custom event that the IngestionButton component listens for, showing live progress phases: "Loading sources..." → "Fetching feeds..." → "Storing articles..." → "Done." The button polls every 3 seconds and detects stuck runs with a 5-minute timeout.

The user experience: log in, immediately see fresh articles loading in the background. No manual trigger needed.

Interactive Topic Watchlist

The Topic Watchlist moved from a static display to full CRUD with real-time Firestore sync:

Add topics with keyword input, category dropdown (16 categories), and source search with autocomplete
Multi-select source assignment per topic — pick which of the 128 feeds should match
Delete with hover-reveal button — no accidental deletions
Live metadata showing "N sources available" and "M topics watching"

// Firestore write on topic creation
await setDoc(doc(db, 'topics_to_monitor', topicId), {
  keyword: topicKeyword,
  category: selectedCategory,
  sources: selectedSources,
  created_at: new Date(),
  user_id: auth.currentUser.uid,
});

The source search filters against the full 128-source catalog with max 10 results, so the dropdown stays usable. Categories include the obvious ones (ai, engineering, infrastructure) plus niche feeds (hn-popular, crypto, automotive).

Per-Category Trending

The Articles page now shows the top 3 trending articles per category, scored by a simple algorithm:

TrendingScore = RelevanceScore + RecencyBoost + HNBoost

RecencyBoost: 5 points at < 1 hour, decaying to 0 over 24 hours
HNBoost: Every 100 Hacker News points = 1 trending point (capped at 5)

The HN integration fetches the top 30 stories and matches by URL against the article database. Articles that are both recent and popular on HN bubble to the top. Articles older than 24 hours lose their recency boost entirely, keeping the trending view fresh.

Category filters show per-category article counts. The Articles page became the default home route — the first thing you see after login is what's trending right now across your monitored topics.

The BSL-1.1 Decision

Perception moved from Apache 2.0 to Business Source License 1.1. The terms:

Change Date: Four years from publication
Change License: Converts to Apache 2.0 automatically
Permitted: Non-production use (testing, development, research, academic)
Restricted: Commercial repackaging as a competing service

This wasn't a philosophical decision. It was practical. Perception has a real competitive advantage in its RSS source curation (128 feeds), its trending algorithm, and its MCP service architecture. Apache 2.0 lets anyone fork and deploy a competing hosted version immediately. BSL-1.1 gives a four-year commercial window while keeping the code source-available for developers who want to learn from it, build on it, or use it in their own non-competing products.

After four years, it converts to Apache 2.0 automatically. No renewal, no decision needed.

What I Learned

Mock-to-real is where architecture gets tested. The mock ingestion worked because it returned the exact shape the dashboard expected. Real Firestore writes, concurrent feed fetching, and batch limits exposed timing issues and data shape mismatches that mocks hide by design.

Fire-and-forget with visibility. The auto-ingestion hook doesn't wait for completion. It fires the trigger and the IngestionButton shows progress independently. This pattern works because the user doesn't need to wait — they can browse existing articles while fresh ones load.

Session guards prevent duplicate work. Without the sessionStorage guard, every React re-render would fire another ingestion trigger. The guard ensures one trigger per browser session, and the server-side idempotency guard (409 Conflict) catches anything the client misses.

OKLCH: Why Your CSS Color System Is Lying to You

Jeremy Longshore — Wed, 25 Mar 2026 22:46:02 +0000

Pick two colors in HSL. Same saturation, same lightness, different hues. They should look equally bright. They don't.

This is the core lie of HSL. And it bit me during a full visual facelift of the claude-code-plugins marketplace.

The HSL Problem

Try this yourself. Open a browser console:

.yellow { background: hsl(60, 100%, 50%); }
.blue   { background: hsl(240, 100%, 50%); }

Both are 100% saturation, 50% lightness. Mathematically identical brightness. Put them side by side and yellow screams while blue recedes. Your eyes aren't broken — HSL is. It maps to a color model that doesn't account for how human vision actually perceives luminance.

This matters when you're generating color palettes programmatically. If your primary, secondary, and accent colors share the same lightness value in HSL, they'll look inconsistent. Buttons will feel heavier in some hues than others. Hover states will shift perceived brightness depending on the color. Your design system lies to you at the API level.

OKLCH Fixes This

OKLCH is a perceptually uniform color space. Same lightness value means same perceived brightness, regardless of hue. The "OK" refers to Björn Ottosson's improved version of the CIE Lab color model. Three channels:

L — Lightness (0 = black, 1 = white, perceptually linear)
C — Chroma (color intensity, like saturation but calibrated)
H — Hue (0-360 degrees, same as HSL)

The equivalent comparison:

.yellow { background: oklch(0.9 0.2 100); }
.blue   { background: oklch(0.9 0.2 260); }

Same lightness, same chroma. These actually look equally bright. You can sweep through hues and get a coherent palette without manual per-color tweaking.

The Marketplace Facelift

PR #343 applied this across the entire claude-code-plugins marketplace. Every page. Homepage, explore, blog, verification badges, individual skill pages. One PR, one coherent visual system.

The OKLCH adoption wasn't just a color swap. It was part of a broader typography and layout overhaul:

Color system — All color values moved to OKLCH, including shadow values
Typography — New font stack and size scale for better hierarchy
Navigation — Restructured nav for cleaner information architecture
Footer — Updated links, layout, and dynamic copyright year

PR review caught inline styles that needed extraction and OKLCH shadow values that were hardcoded instead of using CSS custom properties. Good catches. The kind of feedback that turns a facelift into a maintainable system.

When to Adopt OKLCH

Browser support is there. Every modern browser handles oklch() natively. If you're building a design system, generating theme colors from code, or maintaining a dark/light mode toggle, OKLCH eliminates an entire class of "why does this color look wrong" bugs.

If you're tweaking three hex values on a landing page, HSL is fine. But the moment your color system becomes programmatic — tokens, theme generation, dynamic palettes — OKLCH is the correct abstraction.

Applying Universal Directory Standards to a Prompt Engineering Repository

Jeremy Longshore — Wed, 25 Mar 2026 22:40:40 +0000

The Problem: Inconsistent File Naming Across Master Systems

I had a prompt engineering repository with 150+ templates organized in a logical category structure, but the 000-master-systems/ directory had inconsistent file naming. Some files used CATEGORY-###-description-MMDDYY.md, others didn't. I needed to apply universal directory standards without breaking the existing structure.

The repository: prompts-intent-solutions

The Challenge: Two Different Naming Conventions

Here's where it got interesting. I initially thought the pattern was:

CATEGORY-###-description-MMDDYY.md

Looking at existing files in 000-master-systems/github/:

GITHUB-001-master-repo-audit-092825.md
GITHUB-002-master-repo-chore-092825.md
GITHUB-003-master-repo-release-092825.md

But the MASTER DIRECTORY STANDARDS document specified a different format:

NNN-abv-description.ext

Where:

NNN = zero-padded sequence number (001, 002, 003...)
abv = approved abbreviation (tsk, gde, rel, aud, etc.)
description = kebab-case description
No date suffix for reference documents

The confusion: Number first or category first?

The Iterative Solution Process

Attempt 1: Following the Existing Pattern

I created new TaskWarrior files matching the github directory pattern:

TASKWARRIOR-001-mandatory-integration-protocol-100825.md
TASKWARRIOR-002-complete-usage-guide-100825.md

This seemed right because it matched what I saw.

Attempt 2: Examining the Standards Document

Then I re-read the MASTER DIRECTORY STANDARDS more carefully:

## DOCS FILE NAMING STANDARD

### Format
NNN-abv-short-description.ext

- NNN = Zero-padded sequence number (chronology enforced)
- abv = Approved abbreviation from table below
- short-description = 1–4 words, kebab-case
- ext = File extension

The realization: The existing github/ directory was using an old pattern. The standard called for number-first, not category-first.

Attempt 3: The Correct Approach

Renamed to proper format:

001-tsk-mandatory-integration-protocol.md
002-gde-complete-usage-guide.md

Using approved abbreviations:

tsk = Task Breakdown/List
gde = User Guide/Handbook

Key insight: Reference documents don't need date suffixes. Dates are for versioned files like deployment-config-2024-10-05-v2.json.

What We Built: Five Master System Documents

1. TaskWarrior Integration Protocol (`001-tsk-mandatory-integration-protocol.md`)

Purpose: Enforce TaskWarrior lifecycle tracking for all code-related tasks.

The Four-Phase Mandate:

Task Decomposition - Break work into discrete tasks before coding
Task Activation - Start time tracking with task <ID> start
Code Execution - Implement with progress annotations
Task Completion - Mark done and review time spent

Required Attributes:

task add "Build authentication system" \
  project:WebDev \
  priority:H \
  due:today \
  +coding +security

Every task must include:

project: - Categorization
priority: - Urgency (H/M/L)
due: - Realistic deadline
tags: - Minimum 2 relevant tags

The Validation Checklist:

[ ] All discrete work units captured as tasks
[ ] Dependencies properly linked
[ ] Priority and due dates set
[ ] Task started before code execution
[ ] Time tracking active
[ ] Task marked done after completion

2. TaskWarrior Usage Guide (`002-gde-complete-usage-guide.md`)

Purpose: Practical examples for every usage scenario.

Pattern Catalog:

Simple single-task: Create → start → code → done
Complex multi-step: Parent task with dependent subtasks
Debugging: High priority, annotation of findings, resolution notes
Recurring maintenance: recur:weekly for ongoing tasks

Troubleshooting Section:
Common issues and solutions:

Claude jumps to code without creating tasks → Re-emphasize mandate
Tasks lack proper attributes → Specify required fields
No time tracking → Verify task active output
Tasks not completed → Explicit completion command

Customization Examples:

Team collaboration mode
Custom urgency weights
Project-specific tag vocabularies
Minimal mode for rapid prototyping

3. Streamlined GitHub Release Workflow (`001-rel-master-repo-release.md`)

Purpose: Complete release pipeline without handoff bloat.

The Problem We Solved:
The original release system had:

Chore handoff files
Manual script orchestration
Complex initialization phases
Handoff between audit → chore → release

The Solution - 8-Phase Linear Pipeline:

Verification - Close issues, run tests, check clean state
Version Management - Determine bump type, increment, commit
Changelog Generation - Build entry (newest first), commit
Documentation Sync - Update README, docs, commit
Tag & Release - Annotated tag, push, GitHub release
Deployment - NPM/Docker/Actions based on repo type
Announcement - Issue, pin, discussion post
Archive & Schedule - Save artifacts, schedule next audit

Guarantees:

Sequential correctness - proper semantic versioning
Consistency - all references match current release
Audit trail - archived artifacts with linked milestones
Automation ready - standalone or end-to-end execution

Practical Implementation:

# Version bump
npm version patch -m "chore: bump version to %s"

# Changelog update
cat >> CHANGELOG.md << 'EOF'
## [X.Y.Z] - YYYY-MM-DD
### Added
- New features
### Fixed
- Bug fixes
EOF

# Create tag and release
git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push origin vX.Y.Z
gh release create vX.Y.Z --generate-notes --latest

4. Multi-Repo Workflow Installation (`002-aut-install-release-workflow-all-repos.md`)

Purpose: Install standardized release workflow across entire GitHub organization.

The Mega Prompt Approach:

Discovery Phase:

# Scan organizations
gh repo list "$ORG" --limit 1000 --json name,owner,isArchived,isFork

# Filter repos
grep -E "$INCLUDE_REGEX" | grep -Ev "$EXCLUDE_REGEX"

Workflow Features:

Auto-detect version bump from commits (BREAKING CHANGE, feat:, or patch)
Generate changelog from commit history since last tag
Update version files (package.json, version.txt, README.md)
Create annotated Git tags
Generate GitHub releases
Dry run mode for testing

Safety Features:

Concurrency control
Test validation before release
Clean state verification
No destructive operations

Output:
CSV summary with status for each repo:

repo,status,branch,commit_or_pr
jeremylongshore/prompts-intent-solutions,pr-opened,main,https://github.com/.../pull/42
jeremylongshore/bobs-brain,pr-opened,main,https://github.com/.../pull/15

5. Universal Web-App QA Framework (`001-qap-universal-webapp-qa-mega-prompt.md`)

Purpose: Complete end-to-end QA suite for any web application.

The Non-Negotiables:

✅ Preserve every existing test (only add or refactor)
✅ Idempotent runs (no destructive ops)
✅ Gate optional suites behind capability checks
✅ Report after each phase

6-Phase Workflow:

Phase 0 - Detect & Plan:

Auto-detect framework (React/Next/Vue/Svelte/Static)
Auto-detect host (Netlify/Vercel/Cloudflare/AWS)
Select adapters for submission verification and email
Print plan summary and wait for approval

Phase 1 - Structure & Scripts:

tests/
├── playwright/
├── cypress/
├── helpers/
├── adapters/
├── scripts/
└── artifacts/<YYYY-MM-DD_HHMM>/

Capability-guarded npm scripts:

{
  "test:core": "Playwright E2E",
  "test:accessibility": "axe/pa11y",
  "test:performance": "Lighthouse",
  "test:visual": "BackstopJS",
  "test:security": "headers, XSS/SQLi",
  "test:complete": "everything available"
}

Phase 3 - Test Coverage Matrix (11 categories):

A. Manual-equivalent E2E:

Form happy path with submission verification
Dashboard/API verification
Email notification receipt and content check
Error handling, network fail, offline messaging
Rate-limit/spam, honeypot/reCAPTCHA checks

B. Validation & Edge Cases:

Empty, partial, invalid formats
Boundary lengths, unicode, RTL, emojis
XSS payloads (confirm no alert/injection)
Rapid multi-submit and idempotency

C. Cross-browser & Devices:

Chromium, Firefox, WebKit
Mobile (iPhone/Android), tablet, desktop
Private mode and ad-block

D. Accessibility (WCAG 2.1 AA):

Keyboard-only flow, tab order, focus visible
Labels, roles, ARIA announcements
Color contrast, 200% zoom without horizontal scroll
Live regions for status updates

E. Performance:

Lighthouse thresholds: Performance ≥70, Accessibility ≥90, Best-Practices ≥90, SEO ≥90
Web-Vitals sampling

F. Visual Regression:

Key routes and form states
Mismatch threshold ≤ 0.1%

G. Security Sanity:

HTTPS redirect, HSTS, X-Frame-Options, X-Content-Type-Options
CSP, Referrer-Policy
XSS/SQLi probes must not leak stack traces

H. Networking & Observability:

Console error-free
Network POST status 2xx/3xx
Server/app logs captured

I. Load/Soak (optional):

1-5 rps warmup, 10 rps sustain, 20 rps spike
Track p95 latency and error rate

J. Internationalization:

Locale switch, date/number formats, RTL

K. Cookies/Storage/Auth:

CSRF token presence and rotation
SameSite, Secure flags

Phase 5 - Evidence Pack:

Complete audit trail in tests/artifacts/<timestamp>/:

├── reports/              # HTML, JSON, JUnit
├── screenshots/          # Visual evidence
├── videos/               # Test recordings
├── traces/               # Playwright traces
├── lighthouse/           # Performance reports
├── accessibility/        # a11y results
├── security/             # Security scans
├── visual/               # Regression diffs
├── evidence/             # IDs, headers, payloads
└── SUMMARY.md            # Executive summary

Exit Criteria:

All core E2E pass
WCAG 2.1 AA violations = 0 (or documented waivers)
Lighthouse thresholds met (or ticketed)
Security headers present (or ticketed)
Visual diffs approved
Evidence pack complete

Adapter Pattern:

// tests/adapters/submission-verifier.netlify.js
class NetlifySubmissionVerifier {
  async verifySubmission(submissionId, expectedData) {
    const response = await axios.get(
      `https://api.netlify.com/api/v1/sites/${siteId}/submissions/${submissionId}`,
      { headers: { Authorization: `Bearer ${authToken}` } }
    );

    return {
      found: true,
      matches: Object.keys(expectedData).every(
        key => response.data.data[key] === expectedData[key]
      ),
      submissionId: response.data.id,
      timestamp: response.data.created_at
    };
  }
}

Applying the Directory Standards

The Adaptation Challenge

The repository isn't a traditional code project - it's a prompt library. The standard structure assumes:

02-Src/      # Source code
03-Tests/    # Test suites

But our core product is:

prompts/     # 150+ prompt templates

Decision: Adapt the standards while preserving the product structure.

Final Structure

prompts-intent-solutions/
├── .github/                    # Workflows, templates
├── 000-master-systems/         # Master automation (DO NOT MODIFY)
│   ├── taskwarrior/            # TaskWarrior protocols
│   ├── directory/              # Directory standards
│   ├── github/                 # GitHub workflows
│   ├── content/                # Content systems
│   ├── debug/                  # Debug workflows
│   ├── tracking/               # Time tracking
│   ├── testing/                # QA frameworks
│   └── legacy/                 # Archive
├── 01-Docs/                    # Project docs (FLAT)
├── prompts/                    # Core prompt library
│   ├── development/            # Dev prompts
│   ├── business/               # Business prompts
│   └── specialized/            # Advanced prompts
├── tools/                      # Validation & automation
├── 99-Archive/                 # Deprecated content
├── .directory-standards.md     # Standards reference
├── README.md                   # Updated with standards
├── CLAUDE.md                   # Updated with standards
├── CHANGELOG.md                # Newest-first format
└── LICENSE

Updated Documentation

README.md addition:

## Directory Standards

This project follows the **MASTER DIRECTORY STANDARDS**.

- **Structure**: See `.directory-standards.md` for details
- **Documentation**: All docs in `01-Docs/` using `NNN-abv-description.ext`
- **Prompts**: Core library organized in `prompts/` by category
- **File Naming**: kebab-case files, PascalCase directories
- **Chronology**: Documentation in strict chronological order

CLAUDE.md addition:

## Directory Standards

Follow `.directory-standards.md` for structure and file naming.

### Key Standards
- Store all docs in `01-Docs/` using `NNN-abv-description.ext`
- Maintain strict chronological order
- Prompts directory is core product - organize by category
- File naming: kebab-case, PascalCase for main directories
- CHANGELOG.md: Newest entries on TOP
- 000-master-systems/: DO NOT modify without permission

CHANGELOG.md format:

# Changelog

Format: Newest entries on TOP (reverse chronological order).

## [Unreleased]
### Changed
- Applied MASTER DIRECTORY STANDARDS
- Updated README.md and CLAUDE.md with standards references
- Reorganized CHANGELOG.md to newest-first

## [1.0.1] - 2025-10-02
...

The Abbreviation Table Discovery

The MASTER DIRECTORY STANDARDS includes 120+ approved abbreviations organized by category:

Product & Planning:

prd, pln, rmp, brd, frd, sow, kpi, okr

Architecture & Technical:

adr, tad, dsg, api, sdk, int, dia

Testing & Quality:

tst, tsc, qap, bug, perf, sec, pen

Operations & Deployment:

ops, dep, inf, cfg, env, rel, chg, inc, pst

Project Management:

tsk, bkl, spr, ret, stb, rsk, iss

Documentation & Reference:

ref, gde, man, faq, gls, sop, tmp, chk

After Action:

aar, lsn, pmi

Workflows & Automation:

wfl, n8n, aut, hok

This standardization means every document type has a consistent, recognizable abbreviation across all projects.

Lessons Learned

1. Examine Before You Name

Don't assume the existing pattern is correct. Check the authoritative standards document first.

2. Numbers vs Categories

The sequence number comes first (001-tsk-), not the category (TASKWARRIOR-001-). This enforces chronological order and makes sorting work correctly.

3. Date Suffixes Are Optional

Reference documents don't need dates. Reserve -MMDDYY suffix for versioned files that change over time.

4. Flat Structures for Documentation

Both 01-Docs/ and claudes-docs/ should be flat - no subdirectories. Use the numbering and abbreviation system for organization.

5. CHANGELOG Newest-First

Modern practice: newest entries on top (reverse chronological). Users want to see what's new immediately.

6. Adaptation Over Rigidity

The standards are universal, but implementation must adapt to the repository type. A prompt library isn't a code project, so preserve the product structure while applying the naming standards.

7. Protection of Master Systems

The 000-master-systems/ directory is protected. It contains the source-of-truth automation workflows that shouldn't be modified without explicit approval.

Related Resources

AI Dev Transformation Part 2: Enterprise Library - Building comprehensive prompt libraries
AI-Assisted Technical Writing Automation Workflows - Documentation automation systems
GitHub Repository Organization Master Standards

Key Takeaways

File naming matters - Consistent naming enables automation, sorting, and discovery
Standards require interpretation - Adapt universal standards to repository type
Chronology is enforced - Sequential numbering creates a timeline of development
Abbreviations reduce cognitive load - 120+ standard abbreviations mean instant recognition
CHANGELOG format evolved - Newest-first is modern best practice
Master systems need protection - Source-of-truth workflows shouldn't be casually modified
Iteration is normal - We went through 3 attempts to get the naming right

The result: A professionally organized prompt engineering repository with universal directory standards, comprehensive automation workflows, and complete documentation.

Repository: prompts-intent-solutions