DEV Community: Alex Shev

When ‘Nearest Driver’ Is Not the Nearest Driver: What UBCab’s Routing Stack Teaches Us

Alex Shev — Sat, 10 Oct 2026 18:44:43 +0000

Media credit: Google Maps Platform / UBCab via the source LinkedIn post. The image is retained unchanged as sourced media; rights remain with its owner.

The dispatch mistake hidden in a simple distance calculation

“Nearest available driver” sounds like a geometric problem. In a real city, it is usually an operations problem.

The driver who is closest in straight-line distance may be separated from a rider by a river crossing, a traffic bottleneck, a one-way system, or a route that becomes impractical in winter. Assign that driver anyway and the marketplace absorbs the consequences: volatile ETAs, rejected trips, riders waiting longer than promised, and support teams explaining the gap.

That is the useful lesson in a new case study from Mongolia’s UBCab. The company operates mobility, delivery, and other services in Ulaanbaatar. In a city where winter temperatures can fall to −40 °C and formal addresses are not always sufficient to identify a pickup point, a distance-only dispatch rule was never going to be enough.

Google Maps Platform published the case study on October 8, 2026. It describes how UBCab changed the core question in its dispatch engine from “which driver is physically closest?” to “which driver can actually arrive first?”

Replace distance with arrival time

UBCab’s earlier matching flow used straight-line distance to find nearby drivers. That shortcut ignored road layout and live traffic, so a driver who looked close on a map could still be a long drive away.

The replacement was a travel-time model based on Google Maps Platform Mobility services and the Routes API. The dispatch engine evaluates road layout and current traffic before it assigns a trip. That gives the system a more useful input for both matching and rider communication: a defensible ETA.

This is a broadly applicable architecture pattern for any delivery or marketplace product:

Generate candidate supply near a request.
Score candidates on estimated time of arrival, not only spatial distance.
Include live road conditions and routing constraints in that score.
Return an ETA that the product can stand behind.
Measure the downstream effects: acceptance, waiting time, cancellations, support contacts, and pricing disputes.

The key is not simply adding a map. It is putting routing intelligence inside the decision that determines who gets the job.

A map is a base layer, not the whole location model

The more interesting part of the UBCab story is that accurate routing still did not solve location by itself.

Parts of Ulaanbaatar do not have formal or consistently used street addresses. People may describe destinations through local landmarks and inherited neighborhood language rather than an official postal address. UBCab overlaid its proprietary addressing system on top of the map base layer so drivers could identify the intended pickup point precisely.

That is a strong reminder for teams building location-aware products: external map data is foundational, but local operational knowledge can be the differentiator.

A robust location stack may need to combine:

a commercial or open map base;
travel-time and traffic data;
a locally maintained place/landmark layer;
aliases users and drivers actually recognize;
confidence signals when an address is ambiguous; and
a correction loop that turns failed pickups into better location data.

The point is not to replace the global map. It is to create a translation layer between how a city is represented in a mapping system and how people actually navigate it.

Partner note: This article includes a promotional link to SEOG.ai. For local businesses, technical location data only becomes useful when the public business profile, customer feedback, and neighborhood-level visibility are also maintained. SEOG.ai is a local-SEO workspace for auditing Google Business Profiles, tracking local map rankings, monitoring reviews and nearby competitors, and turning those signals into a prioritized action list. It is relevant here for the layer after the route is complete: making sure a customer can find, trust, and choose a local business in the first place. Review its recommendations before publishing changes; SEO visibility and rankings are not guaranteed.

Keep navigation in the driver workflow

UBCab also integrated turn-by-turn navigation into its own driver app, rather than requiring drivers to switch into a separate navigation product. The company added Mongolian voice guidance so newer drivers could navigate unfamiliar routes without creating another distraction.

This matters because context switching has a cost. Every switch can break the driver’s view of an active job, make state harder to reconcile, and introduce friction exactly when the product needs fast, safe execution.

For product teams, this suggests a practical checklist:

Does the driver retain trip context while navigating?
Are pickup instructions and landmark data available at the moment of arrival?
Does guidance support the language and mental model of the people using it?
Can the app learn from a missed pickup without asking operations staff to reconstruct the incident manually?

The reported outcomes are operational, not cosmetic

According to Google Maps Platform’s case study, UBCab reported:

a 15% increase in driver trip acceptance;
a 25% reduction in average passenger pickup time, equal to about one minute;
roughly 540 hours of rider waiting time saved per month; and
a 30–40% reduction in customer complaints about price and arrival time.

Those are useful metrics because they trace the path from infrastructure to user experience. Better route selection improves driver confidence; more reliable arrival estimates reduce rider uncertainty; both can reduce the operating load placed on support teams.

They should be read as company-reported outcomes from this deployment, not as universal performance guarantees. The magnitude will depend on a marketplace’s geography, fleet density, road network, data quality, and how well the dispatch logic is integrated into the rest of the product.

The next challenge is not only routing

UBCab says it plans to extend the approach to food and package delivery, while exploring visual positioning, 3D mapping, and other Google Maps Platform capabilities for international visitors. It also plans to explore generative AI for dispatch workflows and disruption prediction.

That future work has a familiar product constraint: AI is only useful when it has reliable geography, clear operational boundaries, and a human workflow that can act on its output. A prediction that cannot be connected to a real driver, road, pickup point, or exception-handling process is still just a prediction.

The UBCab case is therefore bigger than a mapping integration. It is an example of location intelligence as product infrastructure: route data, local address knowledge, navigation, and measurable feedback working together inside a high-stakes operational loop.

Sources

Google Maps Platform: UBCab case study — published October 8, 2026.
Google Maps Platform Mobility services
Google Maps Routes API
Source LinkedIn post

Outside Agent: a local-first prompt that gets the screen out of the way

Alex Shev — Fri, 09 Oct 2026 21:43:23 +0000

This is a draft submission for the Hacktoberfest Open-Source AI Challenge Week 1: Touch Grass. It is deliberately marked as a draft: the CLI and its tests are complete, but I have not yet run a locally installed model or published the source repository.

What I Built

Outside Agent is a small command-line tool that turns a few constraints into one outdoor micro-adventure: a broad area, available time, energy level, and an interest such as birds, plants, or light.

The point is to make the screen the shortest part of the experience. The model makes a compact plan; the person then leaves the device behind and completes the activity outside.

The tool intentionally asks only for a broad area. It does not collect an address, track location, check weather, invent trail conditions, or make claims about opening hours or accessibility. Every generated plan tells the user to choose a public, legal, familiar place and verify local conditions themselves.

Demo

The implemented CLI accepts a local Ollama model and a small input set:

python3 outside_agent.py \
  --area "a nearby public park" \
  --minutes 35 \
  --energy low \
  --interest birds

It sends one request to http://127.0.0.1:11434/api/generate with streaming disabled, then prints the model's Markdown plan.

The project has automated tests for the user-context prompt, its safety contract, and the local Ollama request shape:

Ran 3 tests in 0.000s
OK

I have not run a downloaded model in this environment yet, so I am not presenting a generated outdoor plan as a measured result. A real local-model transcript or video demo is the next required validation before this draft becomes a contest submission.

Code

The initial source is a standard-library Python CLI with a small unit-test suite:

outside_agent.py — prompt contract, local Ollama request, CLI arguments, and explicit error handling.
tests/test_outside_agent.py — no-network tests for user-context handling, the safety instructions, and the /api/generate request.
README.md — local setup, run command, test command, privacy boundary, and current status.

Before publication, I will make this source available in a public repository and add the repository URL here. I will not imply that a private local folder is a public code release.

How I Built It

The open component is the model runtime: Outside Agent uses Ollama to call a locally installed open-weight model. The default model name is gemma3:4b, but the command accepts any installed model name through --model.

The model is constrained by a system prompt that requires four sections:

Mission — one practical outdoor activity.
What to bring — only ordinary, low-risk items.
Screen-off cue — a clear point when planning ends and the device can stay away.
Adaptation — a bounded fallback if the user's chosen place or conditions are unsuitable.

The prompt also forbids local factual claims and medical, emergency, wildlife-handling, or navigation advice. Those are deliberately human decisions, not model outputs.

Why Does Open Innovation Matter?

For this project, local inference is not a decorative implementation detail. It makes the tool usable without a cloud API key and lets a person choose the model that runs on their own machine. The user controls the model, the runtime, and the small amount of context that leaves the command line.

That is a better fit for a tool whose purpose is to reduce time on a screen: it should not require a new account, an analytics pipeline, or continuous location collection in order to suggest a short walk, a bird-listening loop, or a plant-observation prompt.

Open-weight models also make the prompt and safety boundary inspectable. If a community finds a better way to make the planner more useful or more cautious, the implementation is small enough to understand and change.

Validation Still Needed

This draft is not a claim that the model has been evaluated. Before submitting it to the challenge, I will:

Run the CLI against an actually installed local open-weight model.
Save a real terminal transcript or video demo.
Publish the source repository.
Re-read the final post against the challenge rules and publish only if the code, demo, and article all match the evidence.

Beyond the Pin: Building a Production-Ready Google Maps Stack in 2026

Alex Shev — Thu, 10 Sep 2026 17:04:47 +0000

Most Google Maps integrations begin with one question: How do we put a pin on a map?

That is the easy part.

The harder, more valuable problem is building a system that can answer questions such as:

Which nearby locations should a customer see?
How long will the trip take right now?
Which parts of a business profile changed, and does the change need attention?
Is a local-visibility drop a data problem, a competitive problem, or simply a measurement problem?

In 2026, Google Maps Platform is moving developers toward a cleaner answer: use the map for presentation, use the newer web services for computation and place data, and keep product decisions in your own application layer.

This article walks through that architecture with TypeScript examples. The examples use a local-business use case, but the pattern applies just as well to delivery, marketplaces, store locators, field services, and travel tools.

The change that should trigger an architecture review

On February 25, 2026, Google deprecated google.maps.DirectionsService\, DirectionsRenderer\, and DistanceMatrixService\ in the Maps JavaScript API. They still work and Google says they are not currently scheduled for discontinuation, but new projects should use the recommended newer services instead. Google's release notes are clear about the direction of travel.

This is not a reason to rewrite a working map overnight. It is a reason to stop treating browser-side map services as your routing backend.

The durable split looks like this:

\text Browser ├─ Maps JavaScript API: render map, markers, user interactions └─ Your backend: authenticated product requests ├─ Routes API: route, ETA, route matrix ├─ Places API (New): discovery and place details ├─ Your database: snapshots, caches, audit history └─ Your rules: alerts, prioritization, permissions \\

That boundary matters. It keeps API keys and billing-sensitive requests off the client, gives you a single place to add caching and observability, and stops your business rules from being scattered across React components.

1. Treat the map as a view—not the source of truth

The browser should render the current product state. It should not decide which data is fresh, calculate every route directly, or store your only copy of a business location.

A useful internal model is deliberately small:

\`ts
type PlaceSnapshot = {
placeId: string;
displayName: string;
formattedAddress?: string;
location?: { lat: number; lng: number };
primaryType?: string;
businessStatus?: string;
fetchedAt: string;
};

type RouteSnapshot = {
originKey: string;
destinationKey: string;
travelMode: "DRIVE" | "WALK" | "BICYCLE" | "TRANSIT";
durationSeconds?: number;
distanceMeters?: number;
encodedPolyline?: string;
fetchedAt: string;
};
`\

fetchedAt\ is not cosmetic. Place data and travel time are observations, not eternal facts. Once you persist that fact, your UI can say “updated 12 minutes ago,” your jobs can refresh high-value data, and your audit layer can distinguish a new change from an old one.

2. Move routing behind a server endpoint

The Routes API computes routes over HTTP. Google requires a response field mask, which is a good discipline: request only the fields your feature really needs.

Here is a minimal Next.js route handler. The API key stays on the server.

\`ts
// app/api/route/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(request: NextRequest) {
const { origin, destination } = await request.json();

const response = await fetch(
"https://routes.googleapis.com/directions/v2:computeRoutes",
{
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Goog-Api-Key": process.env.GOOGLE_MAPS_SERVER_KEY!,
"X-Goog-FieldMask":
"routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline",
},
body: JSON.stringify({
origin: { location: { latLng: origin } },
destination: { location: { latLng: destination } },
travelMode: "DRIVE",
routingPreference: "TRAFFIC_AWARE",
computeAlternativeRoutes: false,
}),
},
);

if (!response.ok) {
return NextResponse.json(
{ error: "Route lookup failed" },
{ status: response.status },
);
}

return NextResponse.json(await response.json());
}
`\

The official Compute Routes guide shows the same endpoint and documents the duration\, distanceMeters\, and encoded-polyline response fields.

In production, add four things before calling this “done”:

Input validation. Accept numeric latitude/longitude pairs or validated place IDs—never arbitrary unbounded input.
A cache key. Include origin, destination, travel mode, and the parameters that materially affect the response.
A short TTL for traffic-aware results. An ETA is useful precisely because it changes; avoid serving it as if it were permanent.
Metrics. Log latency, status, cache hits, and API errors. You cannot manage an expensive dependency by looking only at browser errors.

For many-to-many dispatch or store-selection problems, use Compute Route Matrix rather than firing a large number of individual route requests. The principle is the same: do the work on the backend and persist only the result your product needs.

3. Make field masks a product contract

Places API (New) does not return a default payload when you omit a field mask; the request fails. That can feel strict at first, but it forces a useful design conversation: what information does this screen or job actually need?

For example, a location selector may only need a name, address, identifier, and coordinates:

\`ts
async function searchPlaces(textQuery: string) {
const response = await fetch(
"https://places.googleapis.com/v1/places:searchText",
{
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Goog-Api-Key": process.env.GOOGLE_MAPS_SERVER_KEY!,
"X-Goog-FieldMask":
"places.id,places.displayName,places.formattedAddress,places.location",
},
body: JSON.stringify({ textQuery, pageSize: 10 }),
},
);

if (!response.ok) throw new Error("Place search failed");
return response.json();
}
`\

Avoid using *\ outside exploratory work. Google's Text Search (New) documentation explicitly warns that wildcard masks can return unnecessary data, increasing processing and billing cost.

The bigger win is architectural: name your masks and test them.

\`ts
const PLACE_CARD_FIELDS = [
"places.id",
"places.displayName",
"places.formattedAddress",
"places.location",
].join(",");

const PLACE_AUDIT_FIELDS = [
"places.id",
"places.displayName",
"places.primaryType",
"places.businessStatus",
"places.formattedAddress",
].join(",");
`\

Now a pull request that adds a field has an obvious review question: which screen needs it, what is the expected lifecycle, and what does it cost? That is much better than a mystery payload growing in the background.

4. Model a business as a changing entity

Local products break when they represent a business as name + coordinates + rating\ forever.

A real-world location can change its hours, categories, services, address, website, phone number, or status. It can move. A service-area business may not have a customer-facing storefront at all. A new business can be relevant before its opening date.

Those are not edge cases if you are building local search, lead routing, or visibility software. They are the product.

Start with a refresh policy rather than an assumption that every field has the same freshness requirement:

\ts const refreshPolicy = { placeIdentity: "when user connects or edits a location", businessStatus: "daily for monitored locations", hours: "daily plus before showing time-sensitive UI", competitors: "scheduled scan, not every page view", routes: "on demand with a short traffic-aware cache", } as const; \\

The current Places documentation also supports discovery patterns that used to require awkward workarounds. Text Search can include pure service-area businesses with includePureServiceAreaBusinesses\, and can include future-opening businesses with includeFutureOpeningBusinesses\. Use those options only when they match the user intent; they are not a substitute for a clearly defined search experience.

One subtle but important detail: Google notes that identical Text Search requests are not guaranteed to produce a consistent list of places. That means a rank or competitor scan needs a recorded timestamp, query, viewport/bias, and response snapshot. Without those, “we dropped three places” may simply mean “we compared two different observations.”

5. Separate collection from decisions

Maps APIs can give your product excellent geographic and place data. They cannot tell an operator what to fix first.

That is your application’s job.

For a local-business workflow, the signal pipeline might look like this:

\`text
collect → normalize → compare → explain → queue an action

GBP/profile data ─┐
map-pack scans ├─→ per-location snapshot → change detector → action queue
reviews ┤
competitor data ┘
`\

A small rules layer goes a long way:

\`ts
type Finding = {
key: string;
impact: "high" | "medium" | "low";
evidence: string[];
suggestedAction: string;
};

function prioritize(findings: Finding[]) {
return findings.sort((a, b) => {
const weight = { high: 3, medium: 2, low: 1 };
return weight[b.impact] - weight[a.impact];
});
}
`\

The hard part is not the sort\. It is preserving evidence: the measured locations, the keyword, the scan time, the competing businesses, and the profile fields that informed the finding. That makes a recommendation reviewable instead of magical.

This is exactly the operating layer we built SEOG for. SEOG turns public Google Business Profile signals, geo-grid map rankings, reviews, competitor movement, and NAP consistency into a prioritized local-visibility plan—instead of leaving owners with another dashboard to decode. If you are building on Maps APIs, that distinction is useful: the API retrieves data; the product turns observations into accountable next actions.

6. A migration checklist for existing Maps JavaScript API apps

If your application still uses DirectionsService\ or DistanceMatrixService\, do not start by replacing every call mechanically. First find the product intent behind each call.

“Show the route on the map.” Use Routes API for computation; render the returned encoded polyline in your map UI.
“Choose the closest available technician.” Use Route Matrix, with caching and a clear freshness window.
“Find a business from a query.” Use Places API (New) with an explicit field mask.
“Power a local-visibility dashboard.” Store dated snapshots, define a measurement method, and compare like with like.

Then work through this implementation checklist:

Inventory legacy routing calls and identify the user-facing behavior each one supports.
Create server-side adapters for Routes and Places before changing the UI.
Restrict API keys by application and API; never expose an unrestricted server key in a browser bundle.
Define named field masks per feature and test the expected response shape.
Store observation time, query context, and request parameters alongside results you plan to compare.
Add caching, retries with sensible limits, error metrics, and budget alerts.
Roll out behind a feature flag and compare new versus existing behavior before removing the legacy path.

The takeaway

The modern Google Maps stack is not “a prettier map.” It is a set of services that let you build a reliable local-data system—as long as you keep the right boundaries.

Render maps in the client. Compute routes and fetch place data through your backend. Ask for only the fields you need. Record when and how you observed local data. And build an operational layer that turns those observations into decisions people can act on.

If you want to see that last layer applied to Google Business Profile visibility, map-pack rankings, reviews, and local competitors, try the free analysis at SEOG.

A Single Google Maps Ranking Is a Bad Metric: Treat Local Visibility as a Spatial Sample

Alex Shev — Wed, 02 Sep 2026 22:37:54 +0000

“We rank #3 on Google Maps” sounds like a measurement.

Usually, it is an anecdote.

The result a business sees in Google Maps depends on the query, the searcher’s location, the map viewport, competitors, and the shape of the result page. Checking one keyword from one phone at one location is closer to sampling one pixel than measuring a service area.

That distinction matters when a local business says calls dropped or an agency reports that a rank “went down.” Before changing a category, rewriting a business name, or buying another citation package, ask a more useful question:

Where did visibility change, for which query, and compared with what baseline?

Local rankings are a surface, not a scalar

For a normal web page, a rank tracker can often reduce a query to one result position. Local search is different. Relevance, distance, and prominence interact with the location of the searcher.

Imagine a plumber with good visibility near its office and weak visibility ten miles away. A single “plumber near me” rank cannot tell you whether the business is losing everywhere, losing only in one neighborhood, or simply being evaluated from a different point.

Treat the market as a grid of samples:

query × coordinate × time → visible result set

The goal is not to manufacture a perfect score. It is to detect meaningful change without confusing a local variation for a business-wide failure.

Start with a baseline you can compare

A usable baseline needs more than a position number. For each monitored query, record:

the coordinate or neighborhood being sampled;
the date and approximate time;
whether the business appeared in the map pack or wider result set;
the competitors appearing at the same sample point;
the profile and conversion state at the time: verified status, core facts, phone, booking route, reviews, and linked page.

That last piece matters. A business can have roughly stable visibility while calls fall because the appointment link broke. It can also appear lower in a few cells because a nearby competitor gained fresh reviews, not because the profile suddenly became invalid.

Without the surrounding state, a chart invites panic edits.

Diagnose the pattern before choosing a fix

The sample pattern narrows the investigation.

Pattern	Start by checking
Drop across most sampled areas	Profile status, major edits, reviews, website support, or a broader result shift
Drop in one neighborhood	Proximity, a new local competitor, local intent, or service-area mismatch
One service query weakens	Category, service evidence, and the linked service page
Visibility looks stable but calls fall	Phone, booking path, reviews, and conversion friction
A competitor wins selected cells	Their category fit, review freshness, distance, and page support

This is not a promise that the cause will be obvious. It is a way to avoid treating every symptom as a category problem.

Do not use the grid as an automation trigger

Spatial data helps with diagnosis; it should not blindly alter public business facts.

The dangerous response to a noisy sample is an automatic change to the business name, address, primary category, or service area. Those fields affect public identity and can create policy or verification risk.

Safer automation can:

run the same samples on a schedule;
flag cells whose movement exceeds a chosen threshold;
attach the competing profiles and relevant page evidence;
identify whether the pattern is local or broad;
prepare a review queue for an operator.

The public change itself should be evidence-backed and owned by someone who can confirm it is true.

Think like an observability system

This is the useful analogy for developers: a grid scan is not an alert by itself. It is telemetry.

Good telemetry becomes useful only with a baseline, a threshold, context, and a response path. A meaningful local-visibility alert might read:

“Emergency plumber” lost map-pack presence in 7 of 9 north-side samples
between the last two weekly checks. The profile is live. Two competitors
gained recent reviews; the service page still points to an outdated booking path.

That is actionable. “Rank dropped from 3 to 6” usually is not.

The action may be to fix a conversion path, verify a service claim, improve real evidence on a page, or simply continue observing. It is not automatically “add keywords.”

A lightweight implementation loop

For a local team, keep the loop small:

Pick a few commercial queries and a defensible set of locations.
Capture the first grid as a baseline, including competitors and profile state.
Re-run on a consistent cadence.
Investigate changes that are broad, persistent, or tied to a commercial outcome.
Record the evidence and owner before a sensitive profile edit.
Re-sample after the approved change to see whether the pattern actually moved.

SEOG supports this diagnostic workflow with geo-grid map scans, keyword tracking, competitor snapshots, profile checks, and an action-oriented visibility view. The point is not to promise a rank. It is to make the next investigation more precise.

The takeaway

Local visibility is spatial data with business consequences. Treating it as one universal position produces false certainty and bad automation.

Sample the market deliberately. Compare like with like. Diagnose the shape of the change. Then choose the smallest evidence-backed action that can address the real problem.

Disclosure: AI assistance was used to draft and edit this article.

How to Build a Local-Service Site That Can Answer ‘Can You Fix My RV Today?’

Alex Shev — Sat, 22 Aug 2026 15:16:54 +0000

An RV repair business does not lose a service call because a visitor failed to read a clever headline.

It loses the call when a person with a broken slide-out, roof leak, or electrical issue cannot answer four basic questions quickly:

Do you handle this exact problem?
Do you serve where I am?
Are you available and credible?
What do I do next?

That sounds like marketing. It is mostly a systems-design problem.

The implementation goal is not “make more city pages.” It is to make the business's real-world facts available, consistent, crawlable, and usable across the website, Google Business Profile, analytics, and the conversion flow.

This post turns SEOG’s RV repair checklist into an implementation pattern a developer can apply to any local-service site.

The model: one source of truth, many decision surfaces

Local customers do not encounter a business in one place. They may see a Google result, a Maps profile, a service page, a review, or a call button before they ever submit a form.

Treat the site as one consumer of a small, canonical business data model rather than a collection of independently written pages.

business facts ─┬─> server-rendered service pages
                ├─> JSON-LD
                ├─> XML sitemap + canonical URLs
                ├─> GBP sync/review queue (with human approval)
                ├─> call/form events
                └─> audit and change history

The important part is the left side. If a mobile RV technician's phone number, service coverage, repair categories, and hours live in five unrelated CMS fields, a mismatch is inevitable.

Start with an explicit domain object.

type BusinessLocation = {
  id: string;
  legalName: string;
  publicName: string;
  phoneE164: string;
  website: string;
  address?: {
    streetAddress: string;
    addressLocality: string;
    addressRegion: string;
    postalCode: string;
    addressCountry: "US";
  };
  geo?: { latitude: number; longitude: number };
  serviceAreas: Array<{ name: string; state: string; proof: string[] }>;
  hours: Array<{ dayOfWeek: string[]; opens: string; closes: string }>;
  services: Array<{
    slug: string;
    name: string;
    customerProblem: string;
    evidence: string[];
    emergency: boolean;
  }>;
};

proof and evidence are deliberate fields. They prevent the familiar anti-pattern where a generator creates a page merely because a city name and a service name exist in a spreadsheet. A service-area claim should be backed by something real: a dispatch region, technician coverage, case work, a physical facility, or a documented operating policy.

Build pages from real combinations, not every possible combination

A useful URL is not a matrix cell.

/rv-roof-repair/mesa-az should exist only if the business actually serves Mesa for roof repair and the page can provide information a customer cannot get from a generic page.

For a Next.js application, make the eligibility rule executable instead of leaving it to editorial memory:

function canPublishServiceAreaPage(
  service: BusinessLocation["services"][number],
  area: BusinessLocation["serviceAreas"][number],
) {
  return service.evidence.length > 0 && area.proof.length > 0;
}

export async function generateStaticParams() {
  const business = await getBusinessLocation();

  return business.services.flatMap((service) =>
    business.serviceAreas
      .filter((area) => canPublishServiceAreaPage(service, area))
      .map((area) => ({ service: service.slug, area: slugify(area.name) })),
  );
}

This is a product guardrail, not an SEO trick. Google’s spam policies explicitly call out substantially similar regional pages that funnel users toward one destination as doorway abuse. A page needs its own user value, not just a different token in the title. Google’s policy is worth reading before automating local landing pages.

Render the decision-critical facts in the initial HTML

Do not make a potential customer — or a crawler — wait for a client-side API call to learn whether you repair RV electrical systems or whether emergency dispatch is available.

Use server rendering or static generation for the core page content:

// app/[service]/[area]/page.tsx
export default async function ServiceAreaPage({ params }: Props) {
  const { business, service, area } = await resolveServiceArea(params);

  return (
    <main>
      <h1>{service.name} in {area.name}</h1>
      <p>{service.customerProblem}</p>

      <section aria-labelledby="coverage">
        <h2 id="coverage">Coverage and dispatch</h2>
        <p>{area.proof.join(" ")}</p>
      </section>

      <section aria-labelledby="proof">
        <h2 id="proof">What we repair</h2>
        <ul>{service.evidence.map((item) => <li key={item}>{item}</li>)}</ul>
      </section>

      <a href={`tel:${business.phoneE164}`} data-event="service_call_click">
        Call for {service.name}
      </a>
      <RequestServiceForm serviceId={service.slug} areaId={area.name} />
    </main>
  );
}

Google can render JavaScript, but it processes JavaScript in crawling, rendering, and indexing stages. Server-rendering the essential content improves the experience for people and for crawlers, and helps other bots that do not execute the full application. See Google’s JavaScript SEO guidance.

The page should answer the real query, not manufacture confidence. If dispatch availability is unknown, say how the customer gets an answer. Never render “same-day service” because a marketing field was left enabled.

Generate structured data from the same object

Schema should be a projection of visible, maintained facts — never a second source of truth.

For a fixed physical location, use the most specific appropriate LocalBusiness subtype. For a mobile-only service, do not invent a customer-facing address. Keep the markup aligned with the content a person can see on the page.

function localBusinessJsonLd(business: BusinessLocation) {
  return {
    "@context": "https://schema.org",
    "@type": ["AutoRepair", "LocalBusiness"],
    "@id": `${business.website}/#location-${business.id}`,
    name: business.publicName,
    url: business.website,
    telephone: business.phoneE164,
    ...(business.address && { address: { "@type": "PostalAddress", ...business.address } }),
    ...(business.geo && { geo: { "@type": "GeoCoordinates", ...business.geo } }),
    openingHoursSpecification: business.hours.map((hours) => ({
      "@type": "OpeningHoursSpecification",
      ...hours,
    })),
    areaServed: business.serviceAreas.map((area) => ({
      "@type": "AdministrativeArea",
      name: `${area.name}, ${area.state}`,
    })),
    hasOfferCatalog: {
      "@type": "OfferCatalog",
      name: "RV repair services",
      itemListElement: business.services.map((service) => ({
        "@type": "Offer",
        itemOffered: { "@type": "Service", name: service.name },
      })),
    },
  };
}

<script
  type="application/ld+json"
  dangerouslySetInnerHTML={{ __html: JSON.stringify(localBusinessJsonLd(business)) }}
/>

Validate the final URL with Google’s Rich Results Test and URL Inspection — not only the JSON object in a unit test. Google recommends JSON-LD, but valid markup is an eligibility signal, not a promise of a rich result. Its LocalBusiness documentation is precise about both the implementation and that distinction.

Make canonicalization and discovery part of the build

The system should publish only the URLs it wants search engines to treat as canonical.

// app/sitemap.ts
export default async function sitemap() {
  const pages = await getPublishedServiceAreaPages();

  return pages.map((page) => ({
    url: `https://example.com/${page.service}/${page.area}`,
    lastModified: page.updatedAt,
  }));
}

Each route also needs a self-referencing canonical in its metadata. Do not put filtered, preview, parameterized, or unpublished pages in the sitemap.

Google recommends listing the canonical URLs you prefer in a sitemap; for larger sites, generate that sitemap from the same data store that controls publishing. See its sitemap guide and canonicalization guide.

Instrument the conversion path, not only page views

If the business says calls are down, “organic sessions are flat” is not enough diagnosis.

Record the transition from discovery to action without collecting more personal data than the business needs:

type LocalIntentEvent = {
  name: "service_call_click" | "quote_form_started" | "quote_form_submitted";
  service: string;
  area: string;
  pageType: "service" | "service_area";
  referrerClass: "organic" | "maps" | "paid" | "direct" | "other";
};

export function trackLocalIntent(event: LocalIntentEvent) {
  analytics.track(event.name, event);
}

Track the call click, form start, form submission, and any booking completion that the business can measure. Send only the fields needed for analysis; do not put phone numbers, issue descriptions, or other sensitive request content into generic analytics events.

Then join those events with a small operational audit:

service + area + page version
  -> rendered page checks
  -> profile/review freshness check
  -> call/form events
  -> prioritized human-approved change
  -> re-check window

This makes it possible to distinguish “we need more demand” from “people are reaching us but the service, coverage, trust, or contact path is unclear.”

Add tests where local sites usually drift

The highest-value tests are boring:

it("does not publish a service-area route without service and coverage proof", () => {
  expect(canPublishServiceAreaPage(noEvidenceService, coveredArea)).toBe(false);
  expect(canPublishServiceAreaPage(realService, noProofArea)).toBe(false);
});

it("keeps the phone number consistent across page and JSON-LD", async () => {
  const html = await renderPage("rv-electrical-repair", "mesa-az");
  expect(html).toContain("+14805550199");
  expect(extractJsonLd(html).telephone).toBe("+14805550199");
});

Also run an integration check in CI for:

200 responses for published pages and 404 for ineligible combinations;
canonical URL matches the route;
sitemap contains only published canonical URLs;
no noindex leaks from preview/staging configuration;
JSON-LD reflects visible service, hours, phone, and location data;
call/form controls exist and are keyboard accessible;
content changes have a reviewed audit record.

The operating rule: suggest changes, do not silently mutate trust surfaces

A developer can automate discovery, validation, and draft generation. That does not mean an integration should silently rewrite a Google Business Profile, alter service areas, or publish review responses.

Use an approval queue:

observed fact -> proposed correction -> evidence -> risk -> human approval -> apply -> verify

This keeps automation useful without treating a business identity as an unattended configuration file.

Closing thought

The durable local-service implementation is not a pile of keywords and location templates.

It is a small, tested facts system that makes the same answer available everywhere a customer needs it:

We fix this problem. We serve this area. Here is the proof. Here is what to do next.

That is a better foundation for search visibility, Maps presence, AI-assisted discovery, and — most importantly — a service call that actually reaches the business.

Original business-facing guide: RV Repair SEO Checklist: What to Fix When Service Calls Slow Down

Build the audit, or start with the evidence

If you are building this workflow for a local-service team, SEOG turns the same inputs — Google Business Profile completeness, map visibility, competitor context, reviews, local pages, and conversion gaps — into a prioritized, human-approved action plan.

Explore the platform: seog.ai

Stop Treating Local SEO Expansion Like a City-Page Generator

Alex Shev — Mon, 10 Aug 2026 20:00:18 +0000

Most local SEO expansion plans start too late in the workflow.

The client says:

We want more jobs in this suburb.

The team answers:

Create a city page.
Add the city to the service area.
Track a few keywords.
Maybe buy more leads.

That can work sometimes.

But it is also how teams create doorway pages, make risky Google Business Profile changes, and spend money in markets where the actual blocker was not content.

The better question is not:

Can we target this city?

The better question is:

What local signals say this market is worth pursuing, and what should be fixed before we expand?

That is where location intelligence becomes useful for local SEO.

Not as a fancy map demo.

As a decision system.

The problem with city-level thinking

Local search is geographic, but many local SEO workflows still behave as if geography is just a keyword modifier.

They treat:

plumber dallas
plumber plano
plumber frisco

as three content tasks.

But a local market is not only a keyword.

It has:

competitor density
review expectations
map visibility patterns
category fit
service-area reality
local proof
customer trust signals
citation and entity consistency
website support for the actual service and area

A business can be strong near its office and invisible ten miles away.

A service-area business can have a wide radius on paper and still look weak in a specific neighborhood.

A website can mention a suburb and still fail to prove that the business actually serves it.

That is why a single rank check from the office is not enough.

It tells you one viewpoint.

It does not tell you the market.

Location intelligence, in practical terms

For local SEO, I would define location intelligence like this:

Turning geographic signals into a prioritized action plan.

That sounds simple, but it changes the order of work.

Instead of starting with:

What page should we create?

you start with:

Where is the business already credible?
Where is it visible but not trusted?
Where is it trusted but not visible?
Where are competitors stronger?
Where does the website fail to support the local promise?
Which fix is likely to matter first?

That is a much better operating loop.

It also makes the final recommendation safer.

Sometimes the answer is still a new local page.

Sometimes the first fix is review velocity.

Sometimes it is a Google Business Profile category or service mismatch.

Sometimes it is citation cleanup.

Sometimes it is simply: do not expand here yet.

A market-area scorecard beats an unordered audit

The most useful version of this workflow is not a giant report.

It is a market-area scorecard.

For each target area, compare a small set of signals:

Market area: North suburb
Primary service: emergency HVAC repair

Profile readiness:
- GBP categories match the service?
- services listed clearly?
- photos and hours current?
- call / booking path visible?

Map visibility:
- visible near the office?
- visible near the target suburb?
- missing for money terms?

Trust:
- review count vs competitors?
- review recency?
- negative reviews unanswered?
- service-specific proof?

Competitors:
- who dominates the local pack?
- are they stronger because of reviews, proximity, category fit, website support, or all of it?

Website support:
- useful service page?
- useful location / area proof?
- internal links?
- conversion path?

Entity consistency:
- name, phone, site, address or service-area signals aligned?
- important directories clean enough?

Recommendation:
- first three fixes
- what not to do yet
- re-check date

This is not complicated.

That is the point.

A client can understand it.

An agency can repeat it.

An operator can re-check it after the fixes.

And an AI agent can run parts of it if the inputs are structured enough.

The dangerous fixes are usually the premature ones

The biggest value of this approach is not that it finds more tasks.

It stops bad tasks.

For example, do not start with:

changing a Google Business Profile address or service area without risk review
creating dozens of thin city pages because competitors have them
adding keywords to the business name
buying citations before core entity data is clean
increasing ad spend before fixing profile, review, and conversion gaps
assuming one office-location rank check represents the whole market

That last one is especially common.

The map is not one result.

The map is a local surface that changes with the searcher, query, proximity, category fit, competitor strength, and trust signals.

If you are making expansion decisions, you need area-level evidence.

Not vibes.

A simple priority order

When a client asks, "Should we expand into this area?", I like this order:

1. Entity mismatch

If the business name, phone, website, address, or service-area signals are inconsistent, fix that before scaling.

Messy entity data makes everything else less trustworthy.

2. Profile mismatch

If the Google Business Profile does not clearly support the target service, fix categories, services, hours, photos, and conversion links before writing more pages.

3. Trust gap

If local competitors have fresher reviews, better photos, clearer services, or stronger ratings, the first fix may be trust, not content.

Customers often choose from a small local set.

Small trust differences compound fast.

4. Coverage gap

If the site does not support the service-area promise, build or improve the relevant page.

But make it useful.

A local page should help a customer choose you, not just repeat a city name.

5. Competitor gap

If competitors dominate because their profile, reviews, categories, and pages are aligned, you need a market-specific improvement plan.

Not a generic "local SEO package."

6. Measurement gap

If you cannot re-check the same area after changes, the report becomes opinion.

Track the target area, the first fixes, and the re-check window.

Where software should help

This is where I like the SEOG framing.

The product is not interesting because it promises a magic ranking button.

That would be the wrong promise.

The useful promise is more operational:

Run a local visibility preview.
Compare the market-area signals.
Turn the gaps into a prioritized action plan.

That is the job most local SEO teams actually need help with.

Not another dashboard full of disconnected metrics.

Not another spreadsheet where every row has the same urgency.

A workflow that says:

This market is worth pursuing.
These competitors are the pressure.
These signals are weak.
Fix these three things first.
Do not touch these risky things yet.
Re-check this area after the changes.

That is a stronger client conversation.

It is also a better internal workflow for agencies.

Why this matters for developers and automation teams

If you are building internal tools for marketing teams, this is a good example of a broader product lesson:

Do not only expose data.
Expose decisions.

A local SEO tool can show:

rankings
reviews
competitors
profile fields
citations
pages
traffic
calls

But the operator still needs to know what to do first.

The more useful system connects those signals into a decision model:

input signals -> market comparison -> risk checks -> priority order -> action plan -> re-check

That is the difference between a dashboard and an operating workflow.

Dashboards are good for visibility.

Workflows are good for action.

Local SEO expansion needs both, but the workflow is usually the missing piece.

A practical template

Here is the template I would use before recommending expansion into a new local market:

Target area:
Primary service:
Current local visibility:
Strongest three competitors:
Profile gaps:
Review / trust gaps:
Website support gaps:
Citation / entity gaps:
Conversion path gaps:
Risky changes to avoid:
First three fixes:
Re-check date:
Decision:
  - expand now
  - fix first, then expand
  - hold / not worth the effort yet

That last line matters.

Not every market deserves action right now.

Sometimes the best SEO recommendation is sequencing.

Final thought

Local SEO expansion should not begin as a city-page generator.

It should begin as a market decision.

If the evidence says the business is visible, trusted, and supported by the site, then expansion work can make sense.

If the evidence says the profile is mismatched, reviews are stale, competitors are stronger, and the website does not support the area, more pages may only create noise.

The better workflow is:

compare the market -> find the gap -> fix the blocker -> re-check -> expand with evidence

That is the angle I like in SEOG's location-intelligence checklist.

It turns local SEO from an unordered pile of tasks into a decision system.

Original SEOG guide:

https://seog.ai/blog/location-intelligence-local-seo-checklist-market-expansion

Midnight Borscht: CSS Comfort Food Art

Alex Shev — Tue, 04 Aug 2026 05:09:56 +0000

This is a submission for Frontend Challenge - Comfort Food Edition, CSS Art.

Inspiration

Midnight Borscht is inspired by the kind of comfort food that feels quiet instead of flashy: a deep beet soup, a spoon on the side, rye bread nearby, sour cream melting into the surface, dill scattered on top, and an embroidered tablecloth underneath.

I wanted the art to feel like a small kitchen after dark. The bowl is warm, the wall tiles are dim, and the tablecloth pattern gives the scene a handmade feeling.

Demo

Live demo: https://desciple88.github.io/midnight-borscht-css-art-devchallenge-2026/

Source code: https://github.com/desciple88/midnight-borscht-css-art-devchallenge-2026

Journey

The constraint for this piece was simple: no images, no SVG, and no JavaScript. Everything is HTML and CSS.

The bowl, soup surface, sour cream, dill, beet pieces, potato, spoon, bread, wall tiles, and woven tablecloth are all built from layered div and span elements with gradients, border radii, shadows, repeated backgrounds, transforms, and pseudo-depth.

The hardest part was making it read as food at both desktop and mobile sizes. The desktop version has a composed poster feel, while the mobile version keeps the bowl large enough to show the toppings without letting the scene become a random crop.

CSS details I cared about:

The borscht surface uses stacked radial gradients to keep the soup from looking flat.
The sour cream and dill sit above the beet base to create a clear focal point.
The tablecloth is made with repeating linear gradients and stitched bands instead of an image.
The wall tiles use rotated CSS squares so the background still feels handcrafted.
Steam is animated, but prefers-reduced-motion disables the motion for users who request it.

I self-checked the final piece with local desktop and mobile screenshots, verified that the page contains no image, SVG, or script tags, and deployed it as a public GitHub Pages demo.

License: MIT.

Leftover Ladle: Comfort Food from What You Already Have

Alex Shev — Tue, 04 Aug 2026 04:42:21 +0000

This is a submission for Frontend Challenge - Comfort Food Edition, Perfect Landing

What I Built

Leftover Ladle is a landing page for a fictional comfort-food service that turns fridge leftovers into a warm dinner plan.

The theme is built around one very human comfort-food moment: it is late, it is raining, you do not want another delivery app, and the best meal is probably already hiding in your kitchen.

I focused the page around a complete landing experience:

A first-viewport hero with a CSS kitchen scene, simmering pot, window, rain, jars, and steam.
A clear “how it works” section that explains the product without a wall of copy.
An interactive bowl builder where users choose a base, comfort mood, heat level, and allergy adjustments.
A concise menu section with three comfort-food directions.
A reservation form with accessible status feedback.

Demo

Live demo: https://desciple88.github.io/leftover-ladle-devchallenge-2026/

Source code: https://github.com/desciple88/leftover-ladle-devchallenge-2026

Journey

I chose the Perfect Landing prompt because it rewards more than decoration. A good food landing page has to make the visitor hungry, but it also has to feel easy to use.

The main design choice was to avoid a generic restaurant page. Instead of selling one dish, Leftover Ladle sells a useful comfort-food ritual: pick what is already in your pantry, choose the mood, and get a bowl plan.

Accessibility and resilience were part of the build from the beginning:

Semantic header, nav, main, section, form, fieldset, and footer structure.
A skip link for keyboard users.
Real labels for controls and inputs.
An aria-live bowl preview so updates are announced.
High-contrast buttons and focus states.
prefers-reduced-motion handling for the rain and steam animation.
No runtime dependencies, so the page stays fast and easy to inspect.

The part I am happiest with is the CSS kitchen scene. It gives the page its own visual identity without relying on a stock food photo, and it still supports the landing page rather than becoming a separate art experiment.

I also self-checked the project with desktop and mobile screenshots, static HTML checks for duplicate IDs and label targets, and a JavaScript syntax check before submitting.

License: MIT.

How I Debugged a Broken Vertex AI Image Pipeline and Finally Made It Reliable

Alex Shev — Mon, 03 Aug 2026 16:47:18 +0000

Last week, I lost more time to AI infrastructure than to the actual creative work.

The task sounded simple: generate images through Vertex AI for a content pipeline.

What actually happened:

one key worked yesterday and failed today
one project returned invalid_grant
another returned permission denied
free tier worked sometimes, then hit quota walls
the code looked fine, but the system still didn’t produce images

This is the part nobody tells you about AI workflows:
most failures are not model failures. They’re credential, project, and policy failures.

Here’s how I finally debugged the whole thing and got the image route working again.

The symptoms

At first, the failures looked unrelated.

I saw three different classes of errors:

invalid_grant: account not found

403 Permission denied

429 RESOURCE_EXHAUSTED

That usually means one of two things:

your system is broken in multiple places
your system is pointing at multiple environments and you don’t know which one is real

In my case, it was the second one.

Step 1: Stop guessing which path is canonical

The first useful move was brutally simple:
find the one script that the team actually trusts.

For us, that was:

~/clawd/ops/production/scripts/generate_panels.py

That became the source of truth.

Not old snippets.
Not half-working notebooks.
Not memory.

Once I checked the actual script, I immediately found one hidden problem:

PROJECT = "old-project-id"

The pipeline was still hardcoded to an old project.

So even when I updated the credentials, the requests were still going to the wrong place.

That alone explained a lot.

Step 2: Separate free-tier failure from paid-route failure

We had two different routes mixed together:

Gemini API / AI Studio free tier
Vertex AI paid route

That sounds harmless, but it creates terrible debugging conditions.

Because the failure modes are different:

free tier dies with quota errors
Vertex dies with IAM / service account / project errors

If you mix them, you start solving the wrong problem.

For example, this looked like a model problem at first:

429 RESOURCE_EXHAUSTED

But it turned out to be just a burned free-tier key.

Meanwhile the paid route was failing for a completely different reason.

Lesson: treat free and paid as separate systems, even if they use the same model.

Step 3: Verify the service account before touching the code

Once I had the new Vertex JSON, I didn’t start by generating an image.
I started by checking whether the credential could even mint a token.

That kind of test saves time because it tells you whether the problem is:

auth
project permissions
or model invocation

In Python, the logic is basically:

from google.oauth2 import service_account
from google.auth.transport.requests import Request

creds = service_account.Credentials.from_service_account_file(
    "vertex_ai_key.json",
    scopes=["https://www.googleapis.com/auth/cloud-platform"],
)

creds.refresh(Request())
print(creds.token[:40])

If this step fails, don’t touch your prompts.
Don’t touch the model.
Don’t touch the rendering code.

You don’t have an image problem yet.
You have an auth problem.

Step 4: Watch for organization policies

This one burned the most time.

I created a new service account, everything looked correct, and then Google Cloud refused to create a JSON key.

The error turned out to be caused by this policy:

iam.disableServiceAccountKeyCreation

That wasn’t obvious from the first screen.
The UI showed one policy as “not enforced,” while a legacy constraint was still active somewhere above it.

That kind of mismatch is why cloud debugging feels cursed.

The practical fix was not to keep fighting the same project.
The practical fix was to create a clean personal project without inherited org-policy baggage.

That ended up being faster than trying to untangle admin policy state.

Step 5: Create one clean project and move on

The final working setup looked like this:

a new clean Vertex project
a new service account
a fresh JSON key
the canonical script updated to the new project id
one successful test generation to prove the whole path worked

Only after that did I consider the route fixed.

Not when the key existed.
Not when the policy screen looked green.
Not when the script stopped crashing.

Only when this produced an actual file:

outputs/nanobanana_vertex_test.png

That was the only result that mattered.

The working mental model

When an AI image pipeline breaks, I now check things in this order:

Which script is canonical?
Which project is the request actually hitting?
Can the credential mint a token?
Is this free-tier quota or Vertex IAM?
Are org policies blocking service-account keys?
Did I generate one real image successfully?

That order is much faster than randomly changing keys and re-running prompts.

What actually fixed it

For us, the final fix was not “better prompting.”
It was:

stopping reliance on stale project ids
replacing broken credentials
separating free-tier and paid routes
avoiding inherited org-policy traps
testing the pipeline end-to-end with a real output file

That’s not glamorous.
But it’s the difference between a pipeline you trust and a pipeline that only works when you’re lucky.

Final thought

A lot of AI tooling discourse is still obsessed with models.

But once you work with these systems in production, the real bottleneck is often much more boring:
identity, permissions, quotas, and project hygiene.

The model can be state of the art.
If your project graph is a mess, you still won’t ship.

Where Terminal Skills fits

This is also exactly the kind of workflow I want to turn into a Terminal Skill.

Not because a skill should hide the cloud setup behind magic, but because the debug order should not live only in someone’s memory.

A useful vertex-ai-image-pipeline skill would give an agent a repeatable checklist:

identify the canonical script
verify the configured project id
test whether the service account can mint a token
separate free-tier quota failures from Vertex IAM failures
check for organization-policy blockers
run one minimal generation test before touching prompts
report the exact failing layer instead of guessing

That is the broader idea behind Terminal Skills: turn messy, real operational workflows into reusable agent skills.

I will probably translate this article into a proper Terminal Skills use case next, because this is the kind of boring production workflow agents need more than another prompt template.

If you’ve had to debug a broken AI pipeline recently, I’d genuinely love to hear what failed first for you.

Stop Testing APIs by Hand. Give Your AI Agent a Bruno Workflow.

Alex Shev — Wed, 29 Jul 2026 23:25:57 +0000

Most API testing workflows break in a boring way.

Not because the team does not care about testing.

Not because nobody knows how to send a request.

Because the API workflow lives in too many places at once.

One developer has a Postman collection.
Another has a few curl commands in shell history.
The backend repo has environment variables in .env.example.
CI has a smoke test that only checks one endpoint.
The docs say one thing.
The staging API behaves slightly differently.

Then an AI coding agent enters the repo and gets asked:

Can you check this API flow?

The agent can read code.
It can write tests.
It can generate curl commands.
It can explain HTTP status codes.

But it still has the same problem a new human has.

Where is the API workflow?

If the answer is "somewhere in a GUI tool, someone's local history, and a few scattered docs," the agent has to reconstruct the whole thing from scratch.

That is not a tool problem.

That is a workflow packaging problem.

API collections should live near the code

This is why I like Bruno.

Bruno is an open-source API client that stores collections as plain text files in your Git repository.

That detail matters more than the UI.

If your API collection lives next to the application code, it becomes part of the engineering system:

request changes show up in pull requests
environment files can be reviewed
auth flows can be documented as runnable requests
test assertions can live with the request that needs them
CI can run the same collection humans use locally
new team members can learn the API by running the collection

The collection is not a private artifact hidden in a synced workspace.

It is a repo artifact.

That changes what an AI agent can do with it.

The real unit is not a request

A single API request is easy.

The useful workflow is usually a sequence:

Login.
Save the token.
Create a resource.
Read it back.
Update it.
Verify the response shape.
Clean up or test the failure path.

When developers test this manually, they often remember the sequence in their head.

That works until the API changes.

It works until staging has different data.

It works until someone else needs to debug the same flow.

It works until an agent has to run it and cannot rely on tribal memory.

The important thing to encode is not:

Send a POST request.

It is:

This is the auth flow.
These variables move from one request to the next.
These assertions prove the contract still works.
This command runs the flow in CI.

That is where Bruno's file-based model becomes useful.

A .bru request can contain the request metadata, headers, body, scripts, and tests in a human-readable format.

An environment file can define baseUrl, test users, and secret placeholders.

Post-response scripts can save values for later requests.

The CLI can run the collection:

bru run --env staging

or a folder:

bru run auth/ --env dev

or output CI-friendly results:

bru run --env dev --output results.xml --format junit

That is a much better artifact for an agent than a vague instruction like:

Test the API.

What an AI agent should not improvise

I do not want an agent inventing an API testing workflow every time.

That is how you get impressive-looking activity and weak verification.

The agent might:

hit the happy path only
test against the wrong environment
forget auth state
use fake data that bypasses the real bug
skip assertions and only report that the request returned something
paste a curl command that nobody ever runs again

None of those failures look dramatic.

They look like work.

The agent says:

I tested the endpoint.

But the team has no durable artifact, no diff, no reusable flow, and no CI hook.

That is the wrong end state.

For API work, I want the agent to leave behind something the repo can keep.

A better Bruno workflow for agents

The workflow I would want from an AI coding agent looks like this.

1. Discover the API surface

The agent should inspect routes, controllers, OpenAPI specs if they exist, existing tests, and any current API docs.

The output should be a short map:

auth endpoints
core resources
destructive actions
environment assumptions
test data requirements
flows that need chained state

No collection changes yet.

First understand the shape.

2. Create a Git-friendly collection structure

The collection should mirror the API, not the agent's thought process.

For example:

api-collection/
  bruno.json
  environments/
    dev.bru
    staging.bru
  auth/
    login.bru
    refresh-token.bru
  users/
    list-users.bru
    get-user.bru
    create-user.bru
  orders/
    create-order.bru
    process-refund.bru

That structure is boring on purpose.

People can navigate it.

Agents can navigate it.

Reviewers can diff it.

3. Encode variables and secrets correctly

Environment files should carry normal config like:

baseUrl: http://localhost:3000
testEmail: test@example.com

Secrets should be marked as secrets and not committed as plain values.

This is one of the places where an agent needs a rule, not vibes.

If a tool can run requests, it can also leak credentials by accident.

So the workflow has to define where config lives, which values can be committed, and what must stay local or injected by CI.

4. Chain requests deliberately

Many real API tests are stateful.

Create user returns an ID.

Create order depends on the user.

Refund depends on the order.

The agent should not fake those IDs when it can capture them from the real response.

That is where post-response scripts are useful.

The point is not clever scripting.

The point is making the API flow executable instead of explanatory.

5. Put assertions next to the request

A request without assertions is only a smoke signal.

The agent should add tests for the contract that matters:

status code
required fields
expected types
auth behavior
error shape
permission boundaries
idempotency or retry behavior when relevant

The test should answer:

What would make this endpoint unsafe to ship?

Not:

Did the server return any JSON?

6. Add a CI command

The workflow is not done until there is a command the team can run again.

For example:

bru run --env staging

or:

bru run auth/ users/ --env ci --output results.xml --format junit

The exact command depends on the project.

But the artifact should be clear enough that a developer, CI job, or future agent can repeat the same check.

Where Terminal Skills fits

This is exactly the kind of workflow that belongs in a skill.

The Terminal Skills catalog has a bruno skill for AI agents:

Bruno on Terminal Skills

The useful part is not "the agent has heard of Bruno."

That is not enough.

The useful part is giving the agent an operating procedure:

use Bruno as a Git-first API testing tool
store collections as reviewable repo files
organize requests by API structure
use environment files for config
keep secrets out of committed values
write assertions in requests
chain state between calls intentionally
run collections through the Bruno CLI
treat the collection as living API documentation

Install for Codex:

npx terminal-skills install bruno --agent codex

Install for Gemini CLI:

npx terminal-skills install bruno --agent gemini

Install for Claude Code:

npx terminal-skills install bruno

The broader point is simple:

If an agent is going to touch your API workflow, do not ask it to improvise testing.

Give it a repeatable workflow it can follow, edit, run, and leave behind.

Why this matters for API teams

API testing is one of those areas where AI can create false confidence quickly.

An agent can generate a convincing explanation of an endpoint.

It can generate sample requests.

It can say the test passed.

But unless the workflow leaves a durable artifact, the value disappears after the chat.

The better outcome is:

the Bruno collection was updated
the change is visible in Git
the request has assertions
the environment is explicit
the command can run locally
CI can run it later
the next agent does not need to rediscover the flow

That is the difference between assistance and operational memory.

The agent did not just test the API.

It improved how the team tests the API.

My practical checklist

If I were reviewing an agent-generated Bruno workflow, I would ask:

Does the collection live in the repo?
Does the folder structure match the API shape?
Are environments separated cleanly?
Are secrets marked and excluded from committed values?
Do important requests include assertions?
Are auth tokens and IDs passed through real response state?
Can the collection run from the CLI?
Is there a CI-ready command?
Would a new teammate understand the API faster after reading and running it?

If the answer is yes, the agent left behind something useful.

If the answer is no, it probably just tested by hand with extra steps.

The broader lesson

AI agents are good at producing one-off work.

Engineering teams need repeatable work.

That is the gap skills are meant to close.

For API testing, the difference is especially visible.

Do you want the agent to send a request once?

Or do you want it to build the API workflow your team can keep using?

That is why Bruno is a good fit for Terminal Skills.

It turns API testing into files, diffs, commands, and checks.

And those are exactly the kinds of artifacts agents can use without asking everyone to trust a chat transcript.

Disclosure: AI assistance was used to draft and edit this article.

I fixed an unbounded audio queue in a live translation server before it could take the process down

Alex Shev — Wed, 15 Jul 2026 01:51:04 +0000

This is a submission for DEV's Summer Bug Smash: Clear the Lineup powered by Sentry.

Project Overview

The project is a live speech translation app.

A browser client captures microphone audio, converts it to 16 kHz PCM, and streams it to a NestJS server over Socket.IO. The server opens one WebSocket session to a local ML service, forwards the audio frames, and relays translated segments back to listeners.

The important part for this bug: audio starts arriving from the browser before the ML WebSocket is guaranteed to be open.

That is normal for realtime systems. The dangerous part was what happened when the ML service was unavailable, slow to handshake, or stuck behind a bad connection.

Bug Fix or Performance Improvement

The MlSession class buffered audio frames while waiting for the ML WebSocket to open:

sendAudio(pcm: Buffer) {
  if (this.closed) return;
  if (this.open) this.ws.send(pcm);
  else this.queue.push(pcm);
}

That looks harmless until you remember what the data is: raw PCM audio.

At 16 kHz, mono, 16-bit PCM, the stream is roughly 32 KB per second per active speaker. If the ML WebSocket never opens, every audio event keeps appending another Buffer to queue. A stalled ML service could quietly turn one active audio source into an unbounded memory growth path.

The server did not have to be under heavy traffic for this to matter. One broadcaster with a stuck ML backend was enough to create an ever-growing in-memory queue.

Code

I added an explicit cap for queued audio before the ML connection opens, tracked queued bytes, reset the counter once the connection opens, and released queued buffers on close/error.

const MAX_QUEUED_AUDIO_BYTES = Number(
  process.env.ML_MAX_QUEUED_AUDIO_BYTES || 512 * 1024,
);

The send path now fails fast instead of buffering forever:

sendAudio(pcm: Buffer) {
  if (this.closed) return;
  if (this.open) this.ws.send(pcm);
  else {
    if (this.queuedBytes + pcm.byteLength > MAX_QUEUED_AUDIO_BYTES) {
      this.finish(new Error("ML websocket audio queue overflow before connection opened"));
      try {
        this.ws.close();
      } catch {}
      return;
    }
    this.queue.push(pcm);
    this.queuedBytes += pcm.byteLength;
  }
}

When the socket opens, queued audio is flushed and the byte counter goes back to zero:

this.ws.on("open", () => {
  this.ws.send(JSON.stringify({ type: "config", ...config }));
  this.open = true;
  for (const buf of this.queue) this.ws.send(buf);
  this.queue = [];
  this.queuedBytes = 0;
});

Close/error paths also clear the queue:

close() {
  this.closed = true;
  this.queue = [];
  this.queuedBytes = 0;
  try {
    this.ws.close();
  } catch {}
}

private finish(err?: Error) {
  if (this.closed) return;
  this.closed = true;
  this.queue = [];
  this.queuedBytes = 0;
  this.onClose(err);
}

My Improvements

The fix changes the failure mode.

Before:

ML service unavailable or stuck
browser keeps streaming audio
server queues every PCM frame
memory grows until the process is restarted or killed

After:

ML service unavailable or stuck
server accepts only a bounded amount of pending audio
session closes with a specific overflow error
existing gateway cleanup runs and listeners get the normal ended signal
memory is released immediately

I kept the default cap at 512 KB, which is around 16 seconds of 16 kHz mono PCM audio. That is enough for normal connection delay but small enough to prevent a single stalled session from becoming a memory leak.

The value is configurable:

ML_MAX_QUEUED_AUDIO_BYTES=1048576

That lets production tune the buffer based on expected network conditions without changing code.

Verification

The normal server build still passes:

npm run build

Output:

> live-translation-server@0.1.0 build
> tsc -p tsconfig.json

I also ran a smoke test that accepts the TCP connection but intentionally never completes the WebSocket handshake. Then I sent audio chunks into MlSession with a small queue limit.

Expected result: the session should close with the overflow error instead of keeping the buffers forever.

Observed result:

{"closed":true,"errMessage":"ML websocket audio queue overflow before connection opened"}

That is the behavior I wanted: when the ML backend is not actually ready to receive audio, the realtime server fails the session explicitly instead of becoming a quiet memory sink.

What I learned

Realtime systems make small buffers feel safe.

This was not a dramatic bug in the happy path. The app worked when the ML WebSocket opened quickly. The bug lived in the waiting room between "the browser is already sending audio" and "the ML service is ready."

That is exactly where production bugs like to hide: not in the main algorithm, but in the glue code that assumes the next component will be ready soon.

The fix was not a bigger abstraction. It was a boundary:

audio may wait briefly, but it may not wait forever.

That one rule turns an unbounded failure into a controlled one.

Your AI App Does Not Need Ten Model Clients. It Needs a Gateway Workflow.

Alex Shev — Tue, 14 Jul 2026 23:44:12 +0000

Most AI apps start with one provider.

That is usually fine.

You add an OpenAI SDK call, pick a model, ship the feature, and move on.

Then the product grows.

One workflow needs a cheaper model. Another needs a stronger reasoning model. Another needs image or video generation. A customer wants data routed through a specific provider. A fallback model becomes necessary because the primary one is rate-limited during a launch.

Suddenly, "just call the model" is not really the architecture anymore.

The real problem is routing.

The trap: provider logic spread across the app

The messy version looks like this:

if (task.type === "support_summary") {
  return openai.chat.completions.create(...)
}

if (task.type === "deep_research") {
  return anthropic.messages.create(...)
}

if (task.type === "image") {
  return imageProvider.generate(...)
}

That works for a while.

But as soon as the team needs fallbacks, model swaps, cost controls, or media endpoints, provider decisions start leaking into product code.

Now the app has two problems:

product logic
model routing logic

Those should not be the same layer.

A gateway is boring in the best way

This is why I like the routerbase-gateway pattern on Terminal Skills.

The useful idea is not "one more AI provider."

The useful idea is putting OpenAI-compatible calls, model IDs, fallback choices, streaming behavior, tool calling, JSON mode, and media generation behind one gateway layer.

Instead of teaching every part of the app how to talk to every model provider, the application talks to one interface.

The routing layer decides what happens behind it.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ROUTERBASE_API_KEY,
  baseURL: "https://api.routerbase.com/v1",
});

const result = await client.chat.completions.create({
  model: "fast-support-summary",
  messages: [
    { role: "system", content: "Summarize the customer issue clearly." },
    { role: "user", content: transcript },
  ],
});

The application code stays boring.

The routing policy can change without rewriting every feature.

Why this matters for agents

An AI coding agent can wire up raw API calls.

That is not the hard part.

The hard part is getting the agent to make the same architectural decision the team would make:

keep provider-specific logic out of product code
use environment variables consistently
keep model names configurable
support fallbacks without scattering conditionals everywhere
preserve streaming and JSON-mode behavior where the feature needs it
avoid logging sensitive prompts or keys

That is exactly the kind of workflow that belongs in a skill.

Not because the commands are complicated.

Because the judgment should be repeatable.

The skill version of the task

Without a skill, the prompt tends to be vague:

Migrate this app to use RouterBase.

That leaves too many decisions open.

With a workflow-oriented skill, the agent has a narrower job:

npx terminal-skills install routerbase-gateway --agent codex

Then the agent can follow a safer pattern:

Find existing OpenAI-compatible client calls.
Move provider configuration into environment variables.
Replace direct provider clients with the gateway base URL.
Keep model IDs outside hard-coded feature logic where possible.
Preserve streaming, tool calling, and structured-output behavior.
Add a small verification path before claiming the migration worked.

That is much closer to production work than "switch the API key."

The real win is change management

Model routing is not just an infra preference.

It changes how product teams can operate.

When the routing layer is explicit, the team can:

test cheaper models on low-risk tasks
keep stronger models for high-value workflows
add a fallback route for outages
move media generation behind the same operational pattern
compare providers without rewriting the feature
keep provider churn away from product code

The application becomes less attached to one vendor.

The team becomes more explicit about which model is used for which job.

This is where skills are useful

Most teams do not need an agent that merely knows a gateway exists.

They need an agent that knows how to migrate safely:

inspect the codebase first
identify provider-specific assumptions
make the smallest useful change
avoid leaking secrets
preserve existing behavior
verify the path after the edit

That is the difference between a tool and a workflow.

The tool is the gateway.

The workflow is how you introduce it without making the codebase harder to reason about.

Source workflow:

https://terminalskills.io/use-cases/route-ai-model-requests-through-routerbase

The short version:

If your AI app is starting to juggle providers, models, fallbacks, and media endpoints, do not scatter that logic through the product.

Put it behind a gateway.

Then teach the agent the migration workflow.

DEV Community: Alex Shev

When ‘Nearest Driver’ Is Not the Nearest Driver: What UBCab’s Routing Stack Teaches Us

The dispatch mistake hidden in a simple distance calculation

Replace distance with arrival time

A map is a base layer, not the whole location model

Keep navigation in the driver workflow

The reported outcomes are operational, not cosmetic

The next challenge is not only routing

Sources

Outside Agent: a local-first prompt that gets the screen out of the way

What I Built

Demo

Code

How I Built It

Why Does Open Innovation Matter?

Validation Still Needed

Beyond the Pin: Building a Production-Ready Google Maps Stack in 2026

The change that should trigger an architecture review

1. Treat the map as a view—not the source of truth

2. Move routing behind a server endpoint

3. Make field masks a product contract

4. Model a business as a changing entity

5. Separate collection from decisions

6. A migration checklist for existing Maps JavaScript API apps

The takeaway

Further reading

A Single Google Maps Ranking Is a Bad Metric: Treat Local Visibility as a Spatial Sample

Local rankings are a surface, not a scalar

Start with a baseline you can compare

Diagnose the pattern before choosing a fix

Do not use the grid as an automation trigger

Think like an observability system

A lightweight implementation loop

The takeaway

How to Build a Local-Service Site That Can Answer ‘Can You Fix My RV Today?’

The model: one source of truth, many decision surfaces

Build pages from real combinations, not every possible combination

Render the decision-critical facts in the initial HTML

Generate structured data from the same object

Make canonicalization and discovery part of the build

Instrument the conversion path, not only page views

Add tests where local sites usually drift

The operating rule: suggest changes, do not silently mutate trust surfaces

Closing thought

Build the audit, or start with the evidence

Stop Treating Local SEO Expansion Like a City-Page Generator

The problem with city-level thinking

Location intelligence, in practical terms

A market-area scorecard beats an unordered audit

The dangerous fixes are usually the premature ones

A simple priority order

1. Entity mismatch

2. Profile mismatch

3. Trust gap

4. Coverage gap

5. Competitor gap

6. Measurement gap

Where software should help

Why this matters for developers and automation teams

A practical template

Final thought

Midnight Borscht: CSS Comfort Food Art

Inspiration

Demo

Journey

Leftover Ladle: Comfort Food from What You Already Have

What I Built

Demo

Journey

How I Debugged a Broken Vertex AI Image Pipeline and Finally Made It Reliable

The symptoms

Step 1: Stop guessing which path is canonical

Step 2: Separate free-tier failure from paid-route failure

Step 3: Verify the service account before touching the code

Step 4: Watch for organization policies

Step 5: Create one clean project and move on

The working mental model

What actually fixed it

Final thought

Where Terminal Skills fits