DEV Community: Bracketly

Five AI Companies Just Agreed on a Plugin Format — Here's a Free Validator for It

Bracketly — Sun, 09 Aug 2026 07:26:43 +0000

Five AI Companies Just Agreed on a Plugin Format — Here's a Free Validator for It

On August 6th, OpenAI, AWS, Cursor, Microsoft, and Vercel published Agent Plugins 1.0.0 — a shared packaging standard so a single plugin folder can install into ChatGPT, Codex, GitHub Copilot, VS Code, Cursor, and AWS's Kiro without rewriting setup instructions for each one. It's not a new format competing with Agent Skills (SKILL.md) or MCP — it's the layer that wraps both: a plugin.json manifest, an optional skills/ folder, and an optional mcp.json for MCP server configs, all in one portable directory.

The catch with a spec this fresh: almost nobody has actually validated a manifest against the real schema yet, because almost nobody's had the chance to. The plugin.json format is deliberately narrow — exactly ten permitted top-level fields, a name field with a strict character-and-length pattern, a closed author object — and most people writing their first one right now are working from blog posts and a single canonical example, not the JSON Schema itself. It's easy to add a field that gets silently dropped, or write a plugin name that looks fine and fails validation outright.

I added a free Agent Plugins Manifest Validator to Bracketly, my free client-side dev tools site. Paste a plugin.json and it checks it against the published 1.0.0 schema: the exact $schema URL, the name pattern (lowercase alphanumeric plus hyphens and periods, no doubled -- or .., must start and end alphanumeric), and correct types on every optional field. It also knows the difference between what the spec treats as fatal versus not — an unrecognized top-level field or a non-object extensions value is explicitly non-fatal per spec (clients report and ignore it, then keep loading the plugin), so those show as warnings rather than errors, matching how a real client actually behaves instead of over-flagging. Paste an optional mcp.json too, and it validates the three MCP transport types — including a rule that's easy to miss by hand: a stdio server's command has to be a single executable token, not a full command line with embedded arguments.

Every check is built directly from the published JSON Schema and spec text at agent-plugins.org, not a paraphrase of a summary post, and verified against more than three dozen hand-constructed test cases — valid and invalid — before shipping.

Like everything on the site, it's 100% client-side. Nothing you paste is sent anywhere.

MCP Just Broke Its Own Handshake — Here's a Free Checker for the 2026-07-28 Spec

Bracketly — Fri, 07 Aug 2026 07:24:51 +0000

MCP Just Broke Its Own Handshake — Here's a Free Checker for the 2026-07-28 Spec

On July 28th, the Model Context Protocol spec shipped its biggest breaking change since the protocol launched: the initialize/initialized handshake and the Mcp-Session-Id header — the thing every MCP server and client has been built around since day one — are gone. In their place, every single request now has to carry its own protocol version and capabilities in a _meta object, on every call, with no more one-time negotiation. There's also new header-based routing (Mcp-Method, Mcp-Name, MCP-Protocol-Version), a resultType field that's now mandatory on every successful result, and a Multi Round-Trip Requests mechanism that replaces server-initiated streams for mid-call user input.

All four Tier 1 SDKs — TypeScript, Python, Go, C# — already speak the new spec. Which means if you've got a hand-rolled MCP server, a custom transport layer, or anything that isn't just calling an official SDK's helpers, it can look completely fine in isolation and still fail the moment it talks to an updated client or gateway, with nothing more informative than a routing failure or a silently-dropped request.

I added a free MCP 2026-07-28 Migration Checker to Bracketly, my free client-side dev tools site, for exactly this. Paste a JSON-RPC message and it flags the deprecated initialize handshake if it's still there, checks whether params._meta has the required io.modelcontextprotocol/protocolVersion and clientCapabilities fields, and validates that responses declare resultType and that input_required results carry the inputRequests/requestState fields the new Multi Round-Trip flow needs. If you paste a full raw HTTP block instead of just the JSON body, it also checks the new routing headers — including flagging a lingering Mcp-Session-Id header as a sign you're still on the old stateful model.

Building this meant going straight to the published TypeScript schema for the 2026-07-28 revision rather than trusting summaries, since a wire-protocol checker that's subtly wrong about field names is worse than no checker at all — so every check is tuned to how confident I actually am in it: the required-field checks are strict (spec violations), while corners of the spec I'm less certain are fully nailed down, like the exact shape of individual Multi Round-Trip entries, are flagged as gentler notes instead of hard failures.

Like every tool on the site, it runs entirely in your browser — nothing you paste is sent anywhere. If you're migrating an MCP server or client right now, it's a quick first pass before you go digging through logs.

Your Custom AI SDK Backend Returns 200 OK and the Chat UI Still Shows Nothing

Bracketly — Thu, 06 Aug 2026 07:37:10 +0000

Your Custom AI SDK Backend Returns 200 OK and the Chat UI Still Shows Nothing

Vercel's AI SDK makes streaming a chat response trivial — as long as your backend is also written in JS and calls streamText().toUIMessageStreamResponse(). The moment you're not in that world — a Go, Python, or Rust backend, a queue that re-serializes the stream, a proxy sitting between your LLM call and the client — you have to hand-produce the exact Server-Sent Events format useChat expects, and there's no error message when you get it wrong. The request succeeds, the status is 200, and the UI just renders an empty message or silently stalls.

I hit this building a small side project and ended up staring at raw response bytes in a terminal for longer than I'd like to admit, so I added an AI SDK Stream Protocol Validator & Debugger to Bracketly.

The protocol itself is a sequence of data: {...} JSON lines, each with a type field — text-start, text-delta, text-end for streamed text; tool-input-start/tool-input-delta/tool-input-available for tool calls; finish and a closing data: [DONE] to end the stream. It reads as simple until you're generating it by hand and discover how many ways there are to get it subtly wrong: a text-delta referencing an id you never opened with text-start, a text-start that never gets a matching text-end, a missing messageId on the initial start event, or just forgetting the trailing [DONE] so the client waits forever for a stream that already finished.

The tool parses each event, checks it against the documented part types and their required fields, and tracks state across the whole stream so it can catch the ordering bugs a plain JSON validator would miss — an orphaned delta, an unclosed span, a tool-output event referencing a toolCallId that was never introduced. It also reconstructs the assembled message text from the deltas, so you can see in one glance what the client would actually have rendered from your stream. Paste the raw response body — straight from curl -N or your browser's network tab — and it runs entirely in your browser tab; nothing gets sent anywhere.

Try it here — feedback and edge cases welcome.

Your Truncated Embedding Vector Is Silently the Wrong Length — Here's the One-Line Fix

Bracketly — Mon, 03 Aug 2026 07:20:00 +0000

Your Truncated Embedding Vector Is Silently the Wrong Length — Here's the One-Line Fix

Most major embedding APIs — OpenAI's text-embedding-3 family, Gemini's gemini-embedding models, Cohere embed-v4, Nomic Embed v1.5 — are now trained with Matryoshka Representation Learning, which means you can safely shorten an embedding after the fact to save storage and search cost, with only a small, predictable accuracy hit. That's a genuinely useful trick. It's also got a one-line gotcha that's easy to miss the first time, so I added an Embedding Vector Truncator & Renormalizer to Bracketly, my free client-side dev tools site.

Here's the gotcha: embeddings from these APIs are L2-normalized to unit length by default — that's what makes cosine similarity and dot-product search interchangeable, and it's part of why the math downstream (nearest-neighbor search, reranking, thresholding) behaves predictably. Slice off the last N dimensions of a unit vector and the result is not unit length anymore — you've changed its magnitude without touching its direction. If you then compare that truncated vector against others with cosine similarity or dot product without renormalizing first, you get numbers that are subtly, silently wrong. Nothing throws an error. Your search results just get quietly worse, and it's the kind of bug that's genuinely hard to notice unless you're specifically looking for it, because the vectors still look like embeddings — same shape, plausible-looking floats.

Providers that expose a native truncation parameter (OpenAI's dimensions argument, for instance) handle this for you automatically. The gap is when you're truncating a vector yourself — a value you already stored at full size and want to shrink for a cheaper index, or a self-hosted Matryoshka-trained model where you're slicing the array by hand. In that case the fix really is one line: take the L2 norm of the truncated slice (square root of the sum of its squared values) and divide every value by it. The tool does exactly that — paste a vector, pick a target dimension, get back the renormalized result plus its norm before and after, so you can confirm it's actually unit length again.

I also added an optional second-vector field so you can paste a comparison vector and see cosine similarity computed two ways: on the original full-length vectors, and on both truncated-and-renormalized. The two numbers won't be identical — you did genuinely discard information, so a small shift is the expected accuracy/size tradeoff Matryoshka truncation is built around — but seeing the actual delta for your own real vectors is a lot more convincing than trusting a blog post's abstract claim that "it should still work reasonably well." Everything runs as plain array arithmetic in your browser tab; nothing you paste is sent anywhere.

Your MCP Tool Definition Can Be 100% Spec-Compliant and Still Not Work

Bracketly — Sat, 01 Aug 2026 07:15:58 +0000

Your MCP Tool Definition Can Be 100% Spec-Compliant and Still Not Work

I've been building a few free browser-based tools for people working with LLM APIs — a GPT token counter, a Citations API debugger, a Gemini thought-signature checker. This week I added one for the Model Context Protocol: a schema validator for MCP tool definitions.

What sent me down this path was how small the actual MCP spec is. A Tool object only has two required fields: name and inputSchema. That's it. No character restrictions on the name, no length cap, nothing that says inputSchema has to describe an object at its root rather than, say, a string or an array. Read the raw JSON Schema for Tool and you'd reasonably conclude almost anything goes.

Then you actually wire a server up to a real client and watch tools silently fail to load, or get called with arguments that don't match what you expected, and none of it was a JSON syntax error — the JSON was fine the whole time.

The gap is between what the spec requires and what every real client assumes. Tool names get used as function identifiers, so a name with a space or a slash in it works fine against the raw protocol and then gets rejected the moment it passes through an OpenAI-compatible bridge, because OpenAI's function-calling format does constrain names and the bridge inherits that constraint whether or not MCP itself does. inputSchema without "type": "object" at the root parses as valid JSON Schema and then breaks argument validation, because every SDK assumes tool arguments arrive as a JSON object of named parameters, spec text or not. A required array listing a property that doesn't exist in properties is a typo the spec has no opinion on, but it'll confuse the client's own JSON Schema validator in a way that's hard to trace back to that one line.

None of these are things a JSON validator catches, and none of them are exactly the MCP spec's problem either — they're the difference between "technically valid" and "what actually works," which is exactly the gap a linter is for.

So the tool checks both: the hard spec requirements (missing name, missing inputSchema, a required entry that doesn't exist) as errors, and the practical client conventions (name character set, 64-character length caps, $ref support varying by client) as warnings, labeled clearly as which is which. Paste a single tool, an array, or a full tools/list response — it detects the shape and validates every tool in it. Free, runs entirely client-side, no server ever sees your tool definitions.

Try it here — feedback and edge cases welcome.

Gemini 3's Function Calling Has a Signature Rule That Only Bites You Once You Add a Second Tool Call

Bracketly — Thu, 30 Jul 2026 07:20:16 +0000

Gemini 3's Function Calling Has a Signature Rule That Only Bites You Once You Add a Second Tool Call

Gemini 3 introduced thoughtSignature — an encrypted blob attached to a functionCall part that preserves the model's reasoning state across a multi-turn tool-use conversation. Drop it when replaying history back to the API and you get a 400. Simple enough, until you actually build something that calls more than one tool, so I added a Gemini Thought Signature Validator to Bracketly, my free client-side dev tools site.

The rule that's easy to get backwards

There are two distinct cases, and they require opposite handling:

Parallel function calls (one response, several tool calls at once — "check the weather in Tokyo, Mumbai, and São Paulo"): only the first functionCall part in that response carries a thoughtSignature. The rest legitimately have none.
Sequential function calls (separate turns, one call each, across multiple steps of a longer task): every turn's functionCall needs its own signature.

Write code that handles one case correctly and you'll ship something that works fine in testing — most people's first tool-calling demo is a single function — and then breaks the moment a prompt fans out into multiple calls, or the model chains several tool steps together. Worse, if you're serializing conversation history yourself (a custom agent loop, a stored session you replay later) it's easy to accidentally treat "no signature on this part" as a bug and strip or regenerate something that was never supposed to have one, which breaks the correctly signed request instead.

What the tool actually checks

Paste a request body, a bare contents array, or a raw generateContent response, and it walks every turn checking exactly the things that cause real failures: whether the first functionCall in each model turn has a signature, whether the following turn's functionResponse parts exist, match in count, and are in the same order as their calls, and whether Gemini 3's per-call id field gets echoed back correctly. It can't decode what's inside a signature — nobody outside Gemini can — but it doesn't need to; the failures that actually happen are structural, not cryptographic.

Built and verified against the documented request/response shapes with hand-written test vectors before touching a line of UI code — parallel-call signing, sequential-call signing, missing-response detection, id mismatches, malformed input, all covered. 100% client-side, nothing you paste leaves your browser: bracketly.pages.dev/tools/gemini-signature-validator.

A Citation Can Look Correct and Still Be Silently Wrong — So I Built a Debugger for It

Bracketly — Wed, 29 Jul 2026 07:26:55 +0000

A Citation Can Look Correct and Still Be Silently Wrong — So I Built a Debugger for It

Anthropic's Claude API has a Citations feature: turn it on for a document you send in, and Claude's response comes back with each claim traceable to the exact passage that backs it — a cited_text string, which document it came from, and a location (character range, page number, or content block index). It's genuinely useful for RAG apps where "trust me" isn't good enough. But building against it surfaced a failure mode I hadn't planned for, so I added a Citations API Response Viewer to Bracketly, my free client-side dev tools site.

The part that surprised me

The first surprise is structural: with citations on, Claude doesn't return one text block with inline footnote markers. It returns multiple text blocks, and only the blocks backed by a source carry a citations array at all. If your code assumes response.content is always a single chunk of prose, that assumption breaks the moment citations are enabled — you have to stitch the blocks back together yourself to get the readable answer.

The second surprise is worse, because it fails quietly. Each citation gives you start_char_index / end_char_index into your document — not Claude's copy of it, yours. If the document you show your user, or use for a fact-check pass, isn't byte-for-byte the exact string you sent in the API request — different line endings, a re-export, a "fixed" typo, even different whitespace — those indices point at the wrong span. The cited_text field still reads correctly on its own, so nothing looks broken. You only find out when someone clicks a citation and it highlights the wrong sentence.

What the tool does

Paste a response (the full message, its content array, or a single block — it auto-detects), and it:

Reassembles the answer text with each cited passage highlighted and numbered
Lists every citation with its source document, location, and quoted text, cross-linked back to the passage
Lets you paste your actual source document per citation and checks, character-by-character, whether source.slice(start, end) really equals cited_text — flagging a mismatch with the exact (wrong) span it found instead of just saying "nope"

That last part is the one I actually needed and couldn't find anywhere: a way to verify my own document handling was consistent, not just a pretty renderer for the JSON.

100% client-side, nothing you paste leaves your browser: bracketly.pages.dev/tools/citations-viewer.

I Added a GPT Token Counter, and Learned Tiktoken's Own npm Package Ships the Vocab Files Twice

Bracketly — Thu, 23 Jul 2026 07:19:37 +0000

I Added a GPT Token Counter, and Learned Tiktoken's Own npm Package Ships the Vocab Files Twice

I use OpenAI's API often enough that I'm regularly guessing at token counts before I hit send — "is this prompt going to blow the context window" is a dumb thing to find out from an error response. So I added a GPT Token Counter to Bracketly, my free client-side dev tools site, and it turned into a smaller, more interesting problem than I expected.

The tokenizer, not an approximation

The obvious wrong answer is "estimate ~4 characters per token." The obvious right answer is js-tiktoken, OpenAI's own pure-JS port of tiktoken — same byte-pair-encoding vocabulary the API actually bills against, not a guess. GPT-5.5, GPT-5.4, and GPT-4o all still tokenize with the o200k_base encoding (confirmed against OpenAI's own tiktoken repo — nothing newer has shipped a different one yet), while GPT-4 and GPT-3.5 Turbo use the older cl100k_base. Two vocab files cover essentially every model anyone's actually calling right now.

The part that made me look twice

Those vocab files aren't small — o200k_base alone is about 2.3MB unminified, because it's a literal table of ~200,000 byte-pair merge ranks, not code. Bundling that into every page on the site would tax everyone visiting a JSON formatter to benefit nobody. So the tool imports js-tiktoken/lite (just the encoder logic, no vocab) and dynamically import()s only the one rank file the selected model actually needs — Vite splits each into its own chunk automatically, so it only downloads the first time you type something, cached from then on.

I didn't trust "it compiled" as proof it worked. I ran the actual built-and-bundled tool in a real headless browser against known tiktoken outputs — "Hello, world!" is 4 tokens in both encodings, "The quick brown fox jumps over the lazy dog." is 10 — and only shipped it once the live page matched exactly.

What it doesn't do

It doesn't cover Claude or Gemini — their tokenizers aren't tiktoken-compatible, and I'd rather leave a model out than fake a number for it. It also doesn't add the small fixed per-message overhead a chat-format API request tacks on for role/name framing — it counts raw text tokens only, which is the number you actually want when you're sizing a prompt before you've decided how to structure the request.

Free, no signup, runs entirely in your browser: bracketly.pages.dev/tools/token-counter.

I Finally Gave Bracketly a Logo That Means Something

Bracketly — Mon, 20 Jul 2026 12:05:30 +0000

I Finally Gave Bracketly a Logo That Means Something

Bracketly has had a favicon since day one — a vaguely hood-shaped abstract mark that, looking back, had nothing to do with the name. It just sat there in the browser tab looking like a placeholder nobody replaced. Today I replaced it.

The new mark

It's just [ ] — two brackets, rendered as rounded stroke paths rather than sharp geometric corners, to match the soft-radius design language already used everywhere else on the site (cards, buttons, pills). Literal, obvious in hindsight, and the kind of thing that should've been there from the start for a site called Bracketly.

It ships in two forms:

A monochrome version for the favicon — theme-aware, so it switches between black and white depending on whether your OS is in light or dark mode, same as the rest of the site already does for text and backgrounds.
A full-color version using the site's existing accent gradient (blue → purple → pink) for the header and anywhere else a full-color mark makes sense.

How it's built

Nothing fancier than two <path> elements with stroke-linecap="round" and stroke-linejoin="round" — the rounded bracket ends come for free from the stroke rendering, no manual arc math needed. The tricky part wasn't the shape, it was the spacing: my first attempt had the two brackets' arms overlapping in the middle, which at a glance just looked like a solid rounded rectangle instead of two distinct brackets. Rendered a preview at actual favicon size (32×32) before shipping anything, since a mark that reads fine at 512px can easily turn into mush at the size it actually gets used.

All the PNG variants (32×32, 512×512, and a 180×180 Apple touch icon for anyone who adds the site to their home screen) are rasterized directly from that one SVG source rather than hand-exported, so there's exactly one file to ever update if the mark changes again.

Small change, but it's the kind of detail that either quietly signals "someone's paying attention here" or quietly signals the opposite. Come take a look.

I Built a Cron Expression Parser Because I Kept Getting the "Day" Fields Wrong

Bracketly — Mon, 20 Jul 2026 11:34:37 +0000

I Built a Cron Expression Parser Because I Kept Getting the "Day" Fields Wrong

Cron syntax has five fields — minute, hour, day-of-month, month, day-of-week — and most people can read the first three just fine. 0 9 * * * is obviously "9am, every day." It's the interaction between the last two fields that trips people up, and it tripped me up enough times that I added a Cron Expression Parser to Bracketly, my free client-side dev tools site.

The gotcha: it's OR, not AND

Here's the thing that isn't obvious from staring at 0 0 1 * 1: if you read it left to right, you might assume it means "midnight, on the 1st of the month, AND on a Monday" — i.e. only fires when the 1st happens to land on a Monday.

That's wrong. Standard cron semantics say: when both day-of-month and day-of-week are restricted (neither is a bare *), a date matches if it satisfies either one. So 0 0 1 * 1 actually fires at midnight on the 1st of every month, and separately every Monday. If you wanted "only when the 1st is a Monday," cron can't directly express that at all.

This isn't a bug anywhere — it's just how POSIX cron has always worked — but it's exactly the kind of thing you forget between the few times a year you write a cron expression, and get wrong silently until a job fires on a day you didn't expect.

What the tool does

Paste a cron expression (or one of the @daily / @hourly / @weekly shortcuts) and it gives you:

A plain-English explanation, written to make the OR-not-AND behavior explicit rather than paper over it
The next 5 times the schedule will actually fire, computed from your current time
Inline validation — a field like 99 * * * * gets a specific "value out of range" error instead of just silently doing something unexpected

Like every tool on Bracketly, it's 100% client-side — the parsing and date math happen in your browser, nothing is sent anywhere. It supports the standard field syntax (*, ranges like 1-5, steps like */15, comma lists like 1,15), though numeric fields only for now — no MON/JAN-style names yet.

If you've ever second-guessed whether your deploy schedule actually means what you think it means, it's free and takes about ten seconds to check: bracketly.pages.dev/tools/cron-parser.

Cloudflare's "Autoconfig" Bot Quietly Broke My Static Site's Deploy — Here's What Happened

Bracketly — Mon, 20 Jul 2026 06:08:39 +0000

Cloudflare's "Autoconfig" Bot Quietly Broke My Static Site's Deploy — Here's What Happened

A few days ago, Cloudflare's cloudflare-workers-and-pages[bot] opened a pull request on Bracketly's repo, titled "Add Cloudflare Workers configuration." It sat there unmerged while I worked on other things. Today I merged it without thinking too hard about it — it's from Cloudflare's own bot, on a project already hosted on Cloudflare Pages, seemed safe enough.

It took the site down.

What the PR actually did

It added the @astrojs/cloudflare adapter to astro.config.mjs, generated a wrangler.jsonc, and updated package.json. The framing in the PR description is "configures your project for Cloudflare Workers deployment," which sounds like a reasonable modernization — Workers is Cloudflare's newer, more capable runtime.

The problem: Bracketly is a 100% static, client-side site. Every "tool" on it (JSON formatter, Base64 encoder, hash generator, etc.) runs entirely in the browser — there was never a server-rendering need to justify a Workers adapter in the first place.

Adding the adapter restructured the build output. Before: a flat dist/ with index.html at the root, exactly what a plain static-file deploy expects. After: dist/client/ (the actual site) and dist/server/ (a Workers runtime bundle), because the adapter assumes you want on-demand server rendering alongside static assets.

Why it "succeeded" while actually being broken

My existing GitHub Actions deploy step ran wrangler pages deploy dist — the same command that had worked for weeks. It reported success. The build succeeded. The deploy step reported "Deployment complete." Every automated signal said everything was fine.

Wrangler had actually detected the new dist/client/wrangler.json and silently redirected the deploy target from dist to dist/client on its own — a "helpful" auto-detection feature that meant the command exit code was misleading. It genuinely uploaded files and genuinely returned success. It just wasn't obviously communicating that the actual site paths (/, /tools/whatever, the sitemap) were now 404ing.

I only caught it because I happened to run a manual curl against the live homepage right after the merge and got nothing back where a title tag should be.

The fix

git revert -m 1 <merge-commit>, rebuild locally to confirm dist/index.html exists again (not nested), push. Total downtime: a few minutes, only because I was actively watching for it.

The actual lesson

Automated "helpful" configuration bots — especially ones with commit/PR access to your deploy pipeline — don't know your project's actual architecture. This one assumed "Cloudflare Pages project" implies "wants Workers/SSR," which is a reasonable default guess but was flatly wrong for a purely static site. A green checkmark on a CI deploy step is not the same thing as "the site actually works" — it just means the command didn't throw a non-zero exit code. Worth an actual curl against production after any deploy-pipeline change, automated or not, regardless of how official-looking the bot that proposed it is.

The Silent Cloudflare Pages Bug That Was Quietly Hurting My SEO

Bracketly — Mon, 20 Jul 2026 05:55:33 +0000

The Silent Cloudflare Pages Bug That Was Quietly Hurting My SEO

While building a broken-link checker for Bracketly (a small free dev-tools site), I found something I wasn't expecting: every nonexistent URL on the site — /literally-anything-i-typed, /tools/does-not-exist, whatever — was returning HTTP 200, with the homepage's content, instead of a 404.

Why this happens

Cloudflare Pages has a fallback behavior for unmatched routes: if your deployed site has no 404.html, it serves index.html for any path it can't otherwise resolve — but critically, it does this with a 200 status code, not 404. This is the classic SPA-router pattern (makes sense for a client-side-routed React/Vue app where you want every path to load index.html and let JS take over routing). It's the wrong default for a plain static multi-page site, and if you never explicitly add a 404.html, you get it silently, with zero warning.

I only noticed because I was building a script to curl every URL in my sitemap and flag non-200 responses — and a deliberately-broken test URL came back green.

Why it's worse than it looks

This is what's sometimes called a "soft 404" — a page that should be an error but returns success. Search engines treat this specially, and not kindly:

Google's crawler explicitly detects soft-404 patterns (repeated identical content served at different URLs with a 200 status) and can flag the pattern site-wide, not just the one URL
Every broken/mistyped/old link pointing at your site becomes a duplicate-content page in Google's eyes, all serving the same homepage
It dilutes whatever ranking signal your actual homepage has, since Google now sees N copies of it at different URLs

For a site that had literally zero custom 404 handling, this meant any crawled dead link — a typo'd URL, an old removed page, a bot probing random paths — was quietly generating homepage duplicates in the index.

The fix

Trivial once you know to look for it. In Astro (or basically any static site generator), you just need a page that generates 404.html:

---
// src/pages/404.astro
import BaseLayout from '../layouts/BaseLayout.astro';
---
<BaseLayout title="Page Not Found" description="...">
  <h1>404</h1>
  <p>This page doesn't exist.</p>
</BaseLayout>

Astro (and most SSGs) automatically emits this as dist/404.html, and Cloudflare Pages automatically serves it with a genuine 404 status for any unmatched route once it exists — no config needed, just the file being present.

$ curl -o /dev/null -w "%{http_code}" https://example.com/nonexistent-page
# before: 200
# after:  404

The lesson

If you're deploying a static site to Cloudflare Pages, Vercel, Netlify, or similar — check right now whether a random broken URL on your site returns 404 or 200. It's a two-second check and a five-minute fix, but it's exactly the kind of thing that never shows up unless you go looking, since the page looks completely normal (it's literally rendering your homepage) — there's no visible error to notice.

Source for the actual fix: https://github.com/GRimkiller360/bracketly