Cameron Rye

Making My Portfolio Agent-Readable: From Files to an Interface Agents Can Act On

c@meron.io (Cameron Rye) — Mon, 15 Jun 2026 00:00:00 GMT

A few months ago I published an essay arguing that llms.txt is an elegant solution to a problem nobody important is willing to solve. No major AI platform reads it. Not OpenAI, not Google, not Anthropic, not Meta. The standard, I wrote, "sits unused, waiting for a problem that the powerful have chosen not to solve."

Then I went back to my portfolio and built more of it.

I added an agent card. I added an A2A endpoint that agents can actually POST to. I wrote markdown twins of every page on the site. And I added a manifest of skills an agent is told to verify, not just trust, before acting on them. If you only read the first essay, this looks like a man losing an argument with himself.

It is not. There is one distinction that makes building all of this the opposite of insane.

Discovery is dead; usability is the live question

The thing I declared dead was discovery. The idea that publishing the right file would make an AI crawler find me, rank me, surface me. That bet has not paid off and there is no sign it will. In my follow-up on AI slop I went further and reframed the entire category: these standards are valuable "not as a way to be discovered, but as a way to be verified once a user has found you."

Hold onto that sentence. It is the hinge of this whole post.

Because there is a completely different scenario the discovery debate ignores. A human is sitting in front of an agent (Claude, ChatGPT, some autonomous research thing) and they say: go look at Cameron's site and tell me what he's done with MCP. The agent is already here. Nobody had to discover me. The question is no longer "will it find me." The question is:

When it gets here, can it actually do anything?

That is a usability question, not an SEO question. And usability for an agent has a spectrum:

Can it read me? Most sites hand an agent a tag-soup DOM full of nav chrome, cookie banners, and analytics noise, then make it guess which <div> is the article.
Can it understand me? Even with clean text, can it tell a blog post from a project, find the publish date, know which pages are drafts?
Can it act on me? If the human says subscribe me to his newsletter or send him a message, is there a door the agent can open, or does it have to scrape a form and forge a POST?

My RAG chatbot, Ask, already handles the conversational half of this. This post is about the other half: the static, declarative, machine-addressable surface underneath. The part an agent reaches for when there is no chat box, just a URL and an intent.

I built it in five layers. None of them is a traffic play. Every one of them is a usability or verification mechanism for the agent a visitor already brought with them.

Every page has a markdown twin

Start with reading, because if an agent cannot cleanly read the page, nothing above it matters.

Every blog post on rye.dev is served at /blog/<slug>.md, and every project at /projects/<slug>.md. These are real routes: Astro file routes at src/pages/blog/[...slug].md.ts and src/pages/projects/[...slug].md.ts, with prerender = true so they bake to static files at build time.

Here is the part I care about: these do not convert HTML to markdown. They reconstruct it. The route takes the source content and emits a fresh YAML frontmatter block (title, description, date, updated, tags, author, plus a canonical_url I inject) followed by the raw markdown body, served as text/markdown; charset=utf-8. No nav, no footer, no cookie banner. Just the document, the way I actually wrote it.

Each response also carries a non-standard header I made up because I wanted it: x-markdown-tokens, set to ceil(markdown.length / 4). That four-chars-per-token estimate lets an agent budget its context window before it spends a fetch. A small courtesy, but the whole exercise is courtesies.

There is a second way in, for agents that don't know about the .md convention: HTTP content negotiation. Request the canonical HTML URL (/blog/foo, or /about) with Accept: text/markdown, and middleware serves you markdown instead. For blog and project pages it internally rewrites to the prebuilt .md sibling. For the eight static pages (/, /about, /now, /uses, /colophon, /reading, /resume, /blogroll) it serves hand-authored markdown twins embedded in the Worker bundle: src/data/static-page-md/*.md, imported via Vite's ?raw. One resource, two representations, picked by a header. Content negotiation working exactly as specified.

The part that took the longest was the part you can't see

I want to be honest about how much fighting the platform this took, because the clean result hides it.

Runtime HTML-to-markdown is impossible here. The obvious move (let a request come in, grab the rendered HTML, run it through turndown or cheerio) does not work on Cloudflare Workers. Those libraries pull in parse5, which is Node-only, and they crash the Workers runtime at module load. Not at call time. At import. So the conversion can never happen at the edge. It has to happen at build, which is why these are reconstructed routes, not a clever middleware filter.

run_worker_first is a trap. Cloudflare lets you ask the Worker to run before static assets are served. Except for routes that match a prerendered asset, serve_directly silently overrides it and the asset is handed back before your code runs. _routes.json does nothing: that is a Pages mechanism, and this is a Workers deploy. And Cloudflare's own zone-level "Markdown for Agents" feature, which would replace this entire layer, requires a paid plan. rye.dev is on the Free plan. So I built the free version by hand.

There's one subtlety that cost me an afternoon. The static .md routes must be prerender = false and there must be a registered SSR route at src/pages/[slug].md.ts, or Workers Static Assets answers the request first and 404s it before middleware ever runs. The Worker has to be the thing that picks up the phone.

One more, because it bit me in production: Vary: Accept is the correct header to set, and I set it. But Cloudflare's edge cache does not vary on Accept. So without intervention, the edge could cache an HTML body and then hand it to an Accept: text/markdown request. The fix is to force Cache-Control: private, no-store on the negotiable static-page paths. You give up edge caching on a handful of routes to guarantee correctness. Worth it.

The index nobody reads, built anyway, honestly

On top of the twins sits the file I already eulogized.

public/llms.txt is hand-authored. I'll say that plainly, because the next file isn't, and the distinction matters. It follows the llmstxt.org structure: an H1, a blockquote summary, then ## About, Featured Projects, All Projects, a reverse-chronological Technical Blog with dates, Technical Expertise, Connect, and Optional. It documents the .md-appended convention right at the top so an agent reading it knows the twins exist.

Being hand-authored, it can drift. So next to it is public/llms-full.txt, which is generated by scripts/generate-llms-full.ts as the first step of every build. It inlines the full body of every non-draft post and project (currently around 25 posts and 15 projects) into one grep-able file. If an agent has no fancier tool, the instruction is blunt: fetch llms-full.txt and grep it.

Do I think OpenAI is fetching this file? No. I said in the first essay that nobody is, and I stand by it. But it is trivial to generate when you already write everything in markdown, it signals to a human inspecting the site that I take the machine-reading problem seriously, and it gives my own tooling something clean to read. The cost of building it was an afternoon. The cost of being wrong about adoption is zero, because I lose nothing by being early. That was the entire argument for building llms.txt anyway, and it is the entire argument here.

An agent card that tells the truth about itself

Now we move from "read me" to "here is my interface."

At /.well-known/agent-card.json lives a static, hand-authored A2A Protocol AgentCard, version 1.0.0. It names the provider (https://rye.dev, "Cameron Rye"), points documentationUrl at the agent-skills index, and uses the site favicon as its icon. Its supportedInterfaces is a single entry: { url: https://rye.dev/a2a, protocolBinding: JSONRPC, protocolVersion: 1.0 }. That /a2a URL is the door. We'll walk through it in the last layer.

The honest part is capabilities:

"capabilities": { "streaming": false, "pushNotifications": false, "extendedAgentCard": false }

All false. No streaming, no push, no extended card. I could have left those out or fudged them aspirationally. I set them false because they are false, and an agent that reads streaming: false and then doesn't wait around for an event stream is an agent I've saved a timeout.

The card advertises five skills: search-blog, get-post, subscribe-newsletter, submit-contact, and mcp. Four of those are callable over the live endpoint. The fifth, mcp, is not an executable skill. It is a pointer that says "there is an MCP server at https://rye.dev/mcp, go talk to it." I list it as a skill because the A2A card is the most likely place an agent already on the site looks first, and I'd rather hand off cleanly than leave the MCP server undiscovered. But I'm telling you here what the card can't: four do something, one points elsewhere.

The dotfile problem, which I will mention exactly once per file

Cloudflare Workers Static Assets will not serve any file under a literal .well-known/ directory. The dotfile prefix is filtered out of the asset bundle. So nothing I just described could physically live where its URL says it lives.

The workaround, which recurs across this entire surface: every well-known file lives under public/wellknown/ (no dot) and is exposed at /.well-known/ via a status-200 internal rewrite in public/_redirects. The URL bar stays /.well-known/agent-card.json; the bytes come from wellknown/. public/_headers then layers on the CORS, Content-Type, and cache headers. (For the namespace background on why .well-known/ is the right place for any of this, I wrote a whole post on well-known URIs.)

And because a card that lies about its skills is worse than no card, there's a drift-guard test (tests/a2a-agent-card.test.ts) that asserts the card's skill descriptions match the agent-skills index verbatim. The two cannot silently diverge.

Skills an agent is told to verify before trusting

public/wellknown/agent-skills/index.json is the verification manifest: a pointer set for an agent already on the site, declaring $schema https://schemas.agentskills.io/discovery/0.2.0/schema.json. It's a flat skills array. Each entry has a name, a type of "skill-md", a description, an absolute url to a SKILL.md, and the interesting one: a digest of the form sha256:<hex> computed over that SKILL.md's bytes.

Each skill is a SKILL.md file: YAML frontmatter (name, description) plus a freeform markdown body of instructions written for an agent to read and follow.

The digest is the whole point, and it's the theme of this post wearing a hat. The discovery schema (v0.2.0) carries a per-skill sha256 digest precisely so a client can verify the artifact bytes before trusting a skill. scripts/agent-skills-digest.mjs (pnpm agent-skills:digest) recomputes them; edit a SKILL.md and forget to re-run it, and you ship a stale digest that a compliant agent will reject. That is not a bug. That is the verification handshake doing its job, the same thing I said standards are actually good for. Not "trust me because I'm in the index," but "here's the hash, check it yourself."

The five skills split into three kinds.

Read skills. search-blog tells the agent to prefer the MCP search_posts tool, fall back to fetching llms-full.txt and grepping, then read a hit via MCP get_post or GET /blog/<slug>.md. get-post describes get_post { slug } → { slug, frontmatter, body, url }, or the plain GET /blog/<slug>.md with Accept: text/markdown, drafts excluded, response carrying that x-markdown-tokens header. Reads are cheap and safe.

Write skills, where it gets interesting. subscribe-newsletter is POST /api/newsletter with { email, source }, double opt-in, returning 200 / 400 / 429. submit-contact is POST /api/contact with { name, email, subject, message } under field-length constraints. Both are rate limited and both are same-origin enforced: the Origin must be https://rye.dev.

That same-origin rule creates a fork in the road, and the skills document both branches honestly:

An in-browser agent (something running as a page-side tool) inherits the page's Origin, so it uses the WebMCP subscribe_newsletter / submit_contact tools and sails through the check.
An out-of-browser agent can't forge a same-origin request and shouldn't try, so the skill tells it to do the polite thing: send the human to https://rye.dev/#newsletter or the contact form. The agent doesn't pretend to be the user. It hands the user back the wheel.

The mcp pointer. The fifth skill-md entry, mcp, has its own SKILL.md and its own digest, but it isn't callable over /a2a. It describes connecting to the MCP server at https://rye.dev/mcp, Streamable HTTP, stateless (no Mcp-Session-Id), protocolVersion 2025-06-18, six read-only tools: list_posts, search_posts, get_post, list_projects, get_project, get_about. Which brings us to the layer where things actually execute.

The endpoints that do something

Everything above is description. /a2a is action.

It is live, not a placeholder: a server-rendered Astro route at src/pages/a2a.ts, prerender = false, speaking JSON-RPC 2.0, stateless and synchronous. It supports exactly one method, message/send; anything else gets a clean JSON-RPC -32601. It never returns an A2A Task: no streaming, no async job queue, which is precisely what the card's all-false capabilities promised.

Dispatch works like this. The client sends a message whose parts include a DataPart:

{ "kind": "data", "data": { "skill_id": "get-post", "args": { "slug": "ai-slop-is-a-search-problem-now" } } }

Four skills are callable through it: search-blog, get-post, subscribe-newsletter, submit-contact. Send a text-only message with no DataPart and you get a help reply listing exactly those four. No guessing.

Code reuse is the entire architecture, not a detail. The read skills call the same searchPosts / getPostBySlug functions the MCP server uses. The write skills call the same action handlers as the /api/newsletter and /api/contact REST routes, which means they inherit the existing validation and rate limiting for free: newsletter 3/hour, contact 5/hour, both fail-closed, keyed by client IP. I did not build a parallel A2A backend. I put a JSON-RPC face on the logic that already existed. One source of truth, three front doors (REST, MCP, A2A).

Being candid about the security posture

/a2a is deliberately unauthenticated, with open CORS: Access-Control-Allow-Origin: *. I want to be straight about that rather than let you discover it.

The reason is structural. My same-origin CSRF check is scoped to the /api/ prefix, and /a2a lives outside it so that a third-party agent (which by definition can't present my Origin) isn't blocked at the door. Put it under /api/ and the CSRF guard would reject every legitimate external agent, which defeats the entire point of being reachable by agents a human sent.

The honest tradeoff: anyone can POST to /a2a. It is an open endpoint. What protects me is not the transport but the fact that the only write paths reuse the rate-limited, fail-closed handlers above. The read paths expose only already-public blog content, so they are intentionally not rate-limited. An open read endpoint over my own published writing is not a thing I need to defend. An open write endpoint would be, which is why the writes keep their limits no matter which door they came through. That's hardening by design, not an oversight. I'm telling you it's open because the design expects it to be open.

The sibling is /mcp (src/pages/mcp.ts), with its own server card at /.well-known/mcp/server-card.json: serverInfo.name "rye.dev", title "Cameron Rye Portfolio MCP Server", streamable-http transport, capabilities ["tools"], the six read-only tools. The MCP card and the agent-skills index point at each other, so an agent that lands on either one finds the other.

The table of contents that holds it together

Five layers is a lot of surface. So there's a top-level map.

/.well-known/api-catalog is an RFC 9727 linkset, the table of contents for an agent that's already here. It links service-desc → /openapi.json, service-doc → /llms-full.txt, status → /api/health, the MCP server → /mcp, and the agent-skills index. It does not list the OAuth or web-bot-auth files. Those are placeholders, and a catalog that advertised them would be lying. (More on that in a second.)

Reinforcing the catalog, an RFC 8288 Link header rides on responses (emitted statically in _headers and dynamically on SSR responses in middleware) pointing at the rels for llmstxt.org, agentskills.io, modelcontextprotocol.io, and a2a-protocol.org. An agent that does nothing but read response headers still gets pointed at every entry point.

And for the humans: the homepage has a "Built for humans and AI agents" section (driven by src/data/agent-endpoints.ts) that just lists these endpoints in plain sight. I'm not hiding the machine surface in the metadata. I'm proud of it.

The whole thing is kept honest by drift guards I've already mentioned in passing: the card-versus-skills verbatim test, the digest recompute script, and build-time hash checks. The failure mode I'm most afraid of is not "no agent uses this." It's "an agent uses this and I've quietly lied to it." The guards exist so I can't.

So does anything actually consume this yet?

Honest answer: mostly nothing.

No major platform is fetching my llms.txt or my agent card on its own. I said that months ago and nothing has changed. The thing that does consume this surface is my own tooling (Ask reads the clean content, my MCP and A2A endpoints reuse it) plus whatever agent a visitor decides to point at the site today. That's it. That's the honest scorecard.

And it reconciles perfectly with what I argued before, because I never promised this would bring traffic. It won't. This is not a discovery play; I retired that idea in print. These are the exact benefits I pre-committed to in the llms.txt piece, and they still hold: it's trivial to generate when you already write in markdown; it signals technical care to anyone who looks; it lets me experiment with these protocols before they matter; it prepares me for if adoption ever comes; and (the one I underrated) the markdown twins double as genuinely clean documentation of my own site. The work pays for itself the day I build it, regardless of who shows up.

The reframe from the slop essay holds all the way down. These standards are not how an agent finds me. They're how an agent that a human already pointed here can read me cleanly, understand my structure, verify what it's about to trust, and act through a door I deliberately left open. Usability and verification. Not SEO.

Which leaves exactly one question unanswered, and it's the good one.

Everything here answers what can an agent read and do on this site. It says nothing about who is this agent, and should I trust it. My /a2a endpoint is open; right now it has no idea whether the thing POSTing to it is a research assistant or a scraper wearing a trench coat. There are already placeholders sitting in /.well-known/ for the answer: an http-message-signatures-directory publishing an Ed25519 public key for Web Bot Auth, and OAuth discovery metadata under RFC 8414 / RFC 9728. I'll be blunt about their status, because it's the same honesty the digests demand: the key is published but no request signing is implemented, and there is no OAuth server behind that metadata. The site cannot authenticate a bot or run an OAuth flow today. The doors are framed; the locks aren't installed.

Installing the locks (agent identity and verification) is the next post.

For now I've built an interface, told the truth about every corner of it, and left it open for the agents a human brings. That was always the realistic goal. Not to be discovered.

To be usable once you arrive.

Companion essays:

The /llms.txt Standard: An Elegant Solution Nobody's Using. The prequel: why no major platform reads these files, and why I built them anyway.
AI Slop Is a Search Problem Now. The reframe this whole post stands on: standards as a way to be verified, not discovered.
Standardizing Web Metadata with Well-Known URIs. The .well-known/ namespace background behind the agent card and api-catalog.
Building Ask: A RAG-Powered Portfolio Chatbot. The conversational counterpart to this static, declarative surface.

AI Slop Is a Search Problem Now

c@meron.io (Cameron Rye) — Sun, 24 May 2026 00:00:00 GMT

Ask Google "what temperature should I roast a chicken at," and Google answers you. There's a confident paragraph at the top of the page. There are no clicks. The recipe site that taught Google the answer doesn't know you exist. Its ad inventory served nothing. Its newsletter signup didn't fire. The cooking writer who tested four roasting temperatures and wrote about it three years ago isn't compensated, credited, or even visible above the fold.

This is the new search bargain, and we're naming the wrong thing when we call its byproduct "AI slop."

"AI slop" (Merriam-Webster's, the American Dialect Society's, and Macquarie Dictionary's word of the year for 2025) gets used to mean low-effort, AI-generated content polluting the internet. That definition treats the problem as a supply issue: too many machines making too much junk. The implication is that if the supply tightens (better detectors, watermarking, AI labels, content moderation), the problem subsides.

It won't. The supply side is downstream of a demand-side break that happened first. Search stopped sending users to publishers. Publishers stopped being able to afford humans. AI filled the gap. Search now answers from a corpus increasingly written by AI to be summarized by AI. That's not a content problem you can solve by writing better content. It's a search problem.

What the Numbers Actually Say

Let's get the data straight, because the figure that's been floating around, 34.5%, is now twelve months out of date.

That number came from an Ahrefs study in April 2025 which compared CTR for top-ranking pages before and after AI Overviews appeared on a query. By February 2026, Ahrefs' follow-up study using December 2025 data put the click reduction at 58%. Almost double, in eight months.

Pew Research, working independently, came to a similar place from a different angle. Their July 2025 study tracked the actual browsing behavior of 900 U.S. adults: 68,879 unique Google searches in March 2025, of which 12,593 surfaced an AI summary.

Users who saw an AI summary clicked a traditional search result in 8% of visits.
Users who didn't see one clicked in 15% of visits.
Clicks on links inside the AI summary itself: 1% of visits.

When an AI summary appears, the chance any single visitor clicks anything at all is around 9%. Without one, it's 15%. Almost half the would-be clicks evaporate.

The publisher-side data tracks. Chartbeat, monitoring traffic across 2,500+ news sites globally, reported a 33% decline in Google search referrals across 2025. Digital Content Next (the trade association for major publishers) surveyed its members and found most reporting 1–25% traffic losses, with some exceeding 75%. As of early 2026, approximately 58% of Google searches end in zero clicks.

And the response from publishers has stopped being polite. Penske Media (Rolling Stone, Billboard, The Hollywood Reporter) filed a federal antitrust suit against Google in September 2025, with a 56-page opposition to dismissal in February 2026. The argument is creative: not copyright infringement, but anticompetitive coercion. Google's search monopoly, Penske argues, forces a "forced choice": let your content train AI Overviews that cannibalize your traffic, or be excluded from search entirely. The European Publishers Council filed a parallel complaint with similar framing. One-third of publishers surveyed in early 2026 said they plan to block AI Overviews the moment tools become available.

Google's response was to ship "Further Exploration," a small section of curated links at the bottom of AI Overview answers, designed to send some traffic back. It's a thermostat on a burning house.

The Supply-Side Reading Misses the Diagnosis

The dominant framing of "AI slop" goes like this: generative AI made content creation effectively free, content farms exploit this, search engines fail to filter it, the open web fills with low-value junk. From this view, the cure is supply control: better classifiers, mandatory disclosure, platform moderation, "AI-free" certifications.

This framing isn't wrong, but it's incomplete in a way that matters. It treats the AI-generated content surge as an exogenous shock, something that happened to the web from outside. The supply surge isn't autonomous. It's a rational response to a price signal.

Until roughly 2023, the implicit deal was: write content, get ranked, get clicks, monetize via ads or conversions, fund more writing. That's the bargain that paid for recipe blogs, product reviews, local journalism, and most of the long tail of the web. Each click had a value. Each post had an expected return.

AI Overviews break the third step. Clicks per ranking position are falling fast, by every measure we have. But the cost of producing content didn't fall with them, and human writers didn't suddenly become cheaper. So what happens to a business whose revenue per article is dropping but whose cost per article is constant?

It writes fewer articles, or it writes cheaper articles. Most chose cheaper.

AI lets you produce a thousand SEO-optimized listicles for the cost of one freelance assignment. The margin on each individual page is awful, but it scales. The economics that produce "slop" aren't the economics of malice or laziness. They're the economics of a publisher trying to survive a 33% collapse in search referrals (per Chartbeat) without going out of business.

The supply of AI content isn't a content problem. It's a response to the search problem.

The Spiral

Once you see the loop, it's hard to unsee:

Answer engines (Google AI Overviews, Bing Copilot, Perplexity, the chat surface in every major LLM product) answer queries in-place, using publisher content as substrate.
Publishers' click-driven revenue collapses. Pew's 8%-vs-15% means the median page is clicked roughly half as often when an AI summary appears. Top-ranking pages, per Ahrefs, are clicked at 42% of their pre-AIO rate.
Publishers respond by lowering the unit cost of content. Some lay off staff. Some outsource. Many shift to AI-assisted production: a human edits a generated draft instead of researching and writing one.
The corpus answer engines train on and summarize from increasingly consists of AI-assisted content optimized to be ranked and summarized.
The summaries get blander, more derivative, more confidently wrong. Users notice. Trust erodes.
Search platforms respond by amplifying the AI surface further, since their own AI answer feels more authoritative than the slop substrate beneath it.
Loop.

Each cycle of this loop makes the next cycle cheaper for the platform, more expensive for the publisher, and worse for the user. It's not a stable equilibrium. It's a tightening spiral.

The Cloudflare data point that drives this home: per Cloudflare's own analysis, Anthropic's ClaudeBot crawls 20,583 pages for every single referral it returns to a publisher. That is the ratio of extraction to acknowledgement in the current AI/web relationship. It's not a small asymmetry. It is, functionally, a one-way valve.

The Reuters Institute's Journalism, Media, and Technology Trends and Predictions 2026 puts it tactfully: publishers plan to focus on "investigative journalism, analysis, and distinctive reporting" while "reducing investment in more routine content." Translated: humans will write the things only humans can defensibly write, and everything else becomes machine work that nobody pays for, that nobody clicks, and that everyone produces anyway because the alternative is producing nothing and dying faster.

That's the slop, and it isn't a moral failing of content producers. It's the equilibrium of a market whose price signal got rewired.

Why Standards Can't Fix This

I wrote about /llms.txt last September and concluded it was an elegant solution nobody is using. I want to be specific about why it isn't used, because the same reasoning will apply to every voluntary standard proposed to "fix" AI search.

/llms.txt assumes a cooperative relationship between publisher and platform. The publisher creates a curated, AI-friendly version of their content. The platform reads it and respects the curation. Both win.

That assumption is dead. Platforms have no reason to honor a publisher's curation, because the platform's incentive is not to send users to publishers. The platform's incentive is to keep users inside the platform. Reading /llms.txt to surface a publisher's preferred summary, then linking out to that publisher, would directly reduce the platform's most important metric (time-on-Google, in Google's case). Why would they?

The same argument disqualifies most variants. AI-bot-only robots.txt directives? Honored selectively: most major bots respect them, some don't, and the ones that don't are unaccountable. Schema.org annotations specific to AI consumption? Same incentive problem. A new HTTP header that signals "compensate me to summarize me"? The platform would need a reason to read it. There isn't one.

The Well-Known URIs standard (/.well-known/security.txt, /.well-known/openid-configuration, the IETF's tidy little namespace) works because the parties on both sides want the discovery to succeed. A security researcher and a website owner both benefit from a working security.txt. An OAuth client and an identity provider both benefit from openid-configuration. Coordination problems get solved when incentives align.

Publisher and AI platform incentives don't align. There is no standard you can write that fixes a structural conflict between two parties who would prefer the other to disappear.

So the AI Is Poisoning the Well It Drinks From

This is where the second-order effect gets interesting. AI Overviews are trained on, and summarize from, a corpus increasingly produced to be summarized. The model is reading text that was written by a model to optimize for being read by a model. There's a name for that (model collapse, technically), but you don't need a paper to see it. Search results have gotten genuinely worse over the last two years, and the worsening isn't subtle.

Cloudflare's Q1 2026 robots.txt analysis found that 89.4% of AI crawler traffic serves training or mixed purposes, not search. That asymmetry matters. The web isn't being read to be indexed and referred to. It's being read to be ingested, distilled, and returned without attribution. The Reuters Institute's tracking of AI-generated content in fact-checked claims rose from 7% of cases in 2024 to 16% in 2025, and that's just the cases where someone bothered to file a fact-check. The actual prevalence is higher, because most slop doesn't trigger a check; it just sits in the substrate, doing search-engine-optimization work, training the next generation of summaries.

The slop isn't sitting in a separate quarantine the AI can ignore. It is the AI's input.

The Exits

If standards can't fix it and the spiral is self-reinforcing, what's actually left?

A few things, and none of them are search.

Direct subscription. Newsletters. RSS. Bookmarks. The relationships where the reader decides what they read, and the publisher knows their reader exists. These don't scale the way search did, and that's precisely what makes them defensible. Algorithms can't disintermediate a relationship the user formed directly.

Paid relationships. Substack, Ghost, Patreon, individual paid newsletters, the whole micropayment-adjacent ecosystem. Click-driven advertising was always a fragile foundation; AI Overviews just clarified how fragile. The publishers most insulated from this collapse are the ones whose revenue comes from a reader's deliberate decision, not from incidental ad impressions during a search journey.

Infrastructure pushback. Cloudflare flipped its default in mid-2025: new customers get AI crawlers blocked unless they opt in, and "pay-per-crawl" exists for those who want a compensation channel. Cloudflare hosts roughly 20% of the web. When the substrate provider changes the default, the negotiation changes. This is the first piece of structural leverage publishers have had since AI Overviews shipped.

Trust signals where discovery used to be. This is where standards still matter, not as a way to be discovered but as a way to be verified once a user has found you. /.well-known/security.txt, /.well-known/openid-configuration, signed RSS feeds, verified author identity, ATProto handles, Keyoxide profiles. The post-search internet still needs trust infrastructure. It just doesn't need it to function as a search funnel.

What This Means If You're Building Something on the Web

Three implications I'd take seriously if I were starting a project right now:

Design for zero referral. Assume the search referral to your project is going to keep dropping. Build something that survives at 10% of today's discovery traffic. If your business model only works at 100%, your business model isn't a business model. It's an artifact of a market structure that's being dismantled in real time.

Treat the front page as the relationship. Newsletter signups, RSS subscribe buttons, and follow-on-Mastodon/Bluesky links aren't 2010 decorations. They're how someone who finds you once continues to find you. The home page of your site should optimize for the conversion from anonymous visit to known reader with the same seriousness that 2015 sites optimized for visit to page view.

Build for the AI surfaces, but don't depend on them. Yes, your content will be ingested. Yes, summaries will appear without your link. You can't opt out and expect to remain visible, and you can't opt in and expect to be compensated. Optimize for being recognizable inside a summary (distinctive voice, real expertise, claims that are hard to compress) so that the readers who care about provenance will look for the source. That's a tiny fraction of readers. It's the fraction you can actually keep.

A Note on Optimism

There's a version of this post that ends on a confident note about the open web reclaiming itself, RSS triumphant, search dethroned by trust-based discovery. I don't believe that version. The platforms that built the click-based bargain are larger, better-capitalized, and more entrenched than ever, and the AI surfaces are still in early innings. Things will get worse before they get different.

But "different" is the operative word. The web didn't go away when Google Reader died, when Twitter/X tilted, when Facebook hid links. It rerouted. Each rerouting cost something (visibility, breadth, frictionless discovery) and produced something else: smaller, slower, more deliberately chosen networks of readers and writers.

The current rerouting will produce another one of those. It will be smaller than the search-driven web ever was. It will be unrecognizable as a "market" by 2015 standards. And if you're a person who writes things you'd rather not see compressed, paraphrased, and served at the top of someone else's search results, it might also be the only web worth being on.

Coda

The "AI slop" framing is a comfortable diagnosis. It locates the problem in bad actors making bad content, which means there's someone to blame and something to filter. The real diagnosis is less comfortable: the search infrastructure the web monetized itself through changed its function from router to answerer, and everything downstream of that change, including the slop, is a market responding rationally.

You can't fix that with standards. You can't fix it with quality controls on content production. You can only route around it.

So route.

Sources and further reading:

Pew Research Center: Google users are less likely to click on links when an AI summary appears (July 2025, n=900, 68,879 searches)
Ahrefs: AI Overviews reduce clicks by 58% (February 2026 update)
Search Engine Journal: Antitrust filing says Google cannibalizes publisher traffic (Penske Media v. Google)
Reuters Institute: Journalism, Media, and Technology Trends and Predictions 2026
Transparency Coalition: Cloudflare blocks AI crawlers by default
The Next Web: Google updates AI Overviews with "Further Exploration" as 58% click decline triggers antitrust suits

Companion essays in this trilogy:

Building Aranet: A Rust Toolkit for Liberating Environmental Sensor Data

c@meron.io (Cameron Rye) — Sat, 04 Apr 2026 00:00:00 GMT

My Aranet4 has been sitting on my desk for over a year. It's a good sensor: accurate CO2, temperature, humidity, and barometric pressure readings in a compact e-ink package. But every time I wanted to check my data, I had to pull out my phone, open the Aranet app, wait for a Bluetooth connection, and scroll through a clunky interface that couldn't export anything useful.

The data was mine. I just couldn't get to it.

So I built a Rust workspace that talks directly to Aranet sensors over Bluetooth Low Energy, stores readings locally in SQLite, and exposes everything through the interfaces I actually want: a CLI, a terminal dashboard, a desktop GUI, a REST API, Prometheus metrics, MQTT, and webhooks. Seven crates. Zero cloud dependencies.

Why Environmental Monitoring Matters

The hardware hacking is the fun part, but the reason I bothered is health. Indoor CO2 levels have a measurable impact on cognitive performance. Studies show that levels above 1,000 ppm, common in poorly ventilated offices and bedrooms, can reduce decision-making ability by 11-23%. Above 2,500 ppm, cognitive function drops dramatically.

Radon is even more consequential. It's the second leading cause of lung cancer and you can't detect it without a sensor. The EPA estimates that radon causes about 21,000 lung cancer deaths per year in the US alone.

The sensors exist. Aranet makes excellent ones. But the pipeline between sensor and useful data was broken. It was locked behind a mobile app with no automation, no local storage, and no integration path for the monitoring infrastructure I already run.

Starting at the Bottom: BLE Protocol Reverse Engineering

The first challenge was understanding how Aranet devices communicate over Bluetooth Low Energy. There's no official protocol documentation. The Aranet4-Python project provided a starting point, but I needed to support four device families (Aranet4, Aranet2, AranetRn+, and Aranet Radiation), each with different data formats.

BLE devices broadcast advertisements: small packets of data that nearby receivers can pick up without establishing a connection. Aranet sensors embed their current readings in these advertisements, which means you can monitor them passively.

Here's where the protocol gets interesting. Aranet4 was the first device and its advertisement format doesn't include a device-type prefix. Later devices (Aranet2, AranetRn+, Aranet Radiation) prepend a type byte. The parser has to handle this inconsistency:

pub fn parse_advertisement_with_name(
    data: &[u8],
    name: Option<&str>,
) -> Result<AdvertisementData> {
    let is_aranet4_by_name = name
        .map(|n| n.starts_with("Aranet4"))
        .unwrap_or(false);
    let is_aranet4_by_len = data.len() == 7 || data.len() == 22;

    let (device_type, sensor_data) = if is_aranet4_by_name || is_aranet4_by_len {
        // Aranet4: no device-type prefix — detect by name or data length
        (DeviceType::Aranet4, data)
    } else {
        let device_type = match data[0] {
            0x01 => DeviceType::Aranet2,
            0x02 => DeviceType::AranetRadiation,
            0x03 => DeviceType::AranetRadon,
            other => return Err(Error::InvalidData(
                format!("Unknown device type byte: 0x{:02X}", other),
            )),
        };
        (device_type, &data[1..])
    };
    // ...
}

This is the kind of firmware quirk you only discover by sniffing packets. The Aranet4 was designed before multi-device support existed, so its format is a special case forever. Handling it cleanly rather than with a hack mattered here: this code runs on every single BLE advertisement the system receives.

Dealing with BLE's Unreliability

Anyone who's worked with Bluetooth knows it's flaky. Devices disappear, connections drop, scans return empty. A monitoring tool that crashes or hangs when BLE misbehaves is useless.

The scanner uses exponential backoff with a cap, retrying both failed scans and empty results:

pub async fn scan_with_retry(
    options: ScanOptions,
    max_retries: u32,
    retry_on_empty: bool,
) -> Result<Vec<DiscoveredDevice>> {
    let mut attempt = 0;
    let mut delay = Duration::from_millis(500);

    loop {
        match scan_with_options(options.clone()).await {
            Ok(devices) if devices.is_empty()
                && retry_on_empty
                && attempt < max_retries =>
            {
                attempt += 1;
                warn!("No devices found, retrying ({}/{})...", attempt, max_retries);
                sleep(delay).await;
                delay = delay.saturating_mul(2).min(Duration::from_secs(5));
            }
            Ok(devices) => return Ok(devices),
            Err(e) if attempt < max_retries => {
                attempt += 1;
                warn!("Scan failed ({}), retrying ({}/{})...", e, attempt, max_retries);
                sleep(delay).await;
                delay = delay.saturating_mul(2).min(Duration::from_secs(5));
            }
            Err(e) => return Err(e),
        }
    }
}

The saturating_mul prevents overflow on the delay, and the 5-second cap keeps retries responsive. The retry_on_empty flag matters: sometimes you want to distinguish "no devices nearby" from "BLE stack isn't ready yet." This is a small function, but it's the difference between a tool that works on a bench and one that works in production.

On Linux, there's an additional challenge: BlueZ (the Linux Bluetooth stack) can trigger pairing dialogs that hang BLE operations indefinitely. The core library automatically registers a BlueZ agent to suppress these prompts. These are the kind of platform-specific sharp edges that take longer to debug than the core protocol work.

The Seven-Crate Architecture

Environmental monitoring spans a surprisingly deep stack: hardware communication, data persistence, multiple user interfaces, and integration with external systems. Cramming all of that into a single crate would be unmaintainable. Splitting it into seven crates with clear boundaries keeps each piece focused and testable.

aranet/
├── crates/
│   ├── aranet-types/    # Platform-agnostic shared types
│   ├── aranet-core/     # BLE communication + protocol parsing
│   ├── aranet-store/    # SQLite persistence + sync logic
│   ├── aranet-service/  # REST API, WebSocket, MQTT, Prometheus
│   ├── aranet-cli/      # Command-line interface
│   ├── aranet-tui/      # Terminal dashboard (ratatui)
│   └── aranet-gui/      # Desktop GUI (egui)

The dependency graph flows strictly downward. aranet-types has no dependencies on other workspace crates. aranet-core depends only on aranet-types. aranet-store depends on aranet-types and aranet-core. The three interface crates (cli, tui, gui) and aranet-service sit at the top, consuming the lower layers.

This means adding a new interface (say, a web dashboard or a Home Assistant component) requires zero changes to the sensor communication or storage layers. The separation also means each crate compiles independently, which matters when cross-compiling for ARM targets like a Raspberry Pi.

Local-First Data: SQLite and Incremental Sync

Aranet devices store history in an onboard ring buffer. Downloading that history over BLE is slow, since each record requires a round-trip. Re-downloading everything on every sync would be painful.

The aranet-store crate tracks sync progress per device. On the first sync, it downloads all records. On subsequent syncs, it calculates the start index from the last checkpoint and only fetches new records:

/// Incremental Sync Algorithm:
///
/// 1. Read device's current `total_readings` count
/// 2. Call `Store::calculate_sync_start` to get start index
/// 3. Download records from `start_index` to `total_readings`
/// 4. Call `Store::update_sync_state` to save progress
///
/// First sync downloads all 500 records:
///   let start = store.calculate_sync_start("Aranet4 17C3C", 500)?;
///   assert_eq!(start, 1);
///
/// Next sync — device now has 510 records:
///   let start = store.calculate_sync_start("Aranet4 17C3C", 510)?;
///   assert_eq!(start, 501); // Only download 10 new records

Records are deduplicated at the SQLite level by (device_id, timestamp) pairs. This handles edge cases where the ring buffer wraps around or the device resets, so you never get duplicate readings in your local store.

The local-first approach is deliberate. Your data lives on your machine, in a standard SQLite database you can query with any tool. No account required. No API rate limits. No vendor deciding to shut down or change pricing. If the Aranet mobile app disappeared tomorrow, this toolkit wouldn't notice.

The Terminal Dashboard

The CLI handles one-off reads and scripting, but for day-to-day monitoring I wanted something I could leave running in a tmux pane. The TUI, built with ratatui, provides real-time multi-device monitoring with sparkline charts and threshold alerts.

It supports vim keybindings (naturally), light and dark themes, mouse interaction, CSV export, and device comparison views. CO2 readings above 1,000 ppm turn yellow; above 1,500 ppm, red. That's deliberately conservative, since cognitive effects are measurable well before the 2,500 ppm level where they become severe. Radon alerts follow EPA action levels. An audio bell fires when thresholds are crossed, which helps when the dashboard is running on a secondary monitor.

The sparkline charts show min/max labels and adapt to terminal width. It's the kind of information density that a mobile app can't match.

Desktop GUI

For less terminal-inclined users (or when I want a persistent window rather than a terminal pane), aranet-gui provides a desktop application built with egui:

Multi-panel interface with device list, detail views, history charts, comparison mode, and a configurable alert system. It exports to CSV and JSON, supports light and dark themes, and includes a service management panel for controlling aranet-service directly from the GUI.

From Sensors to Grafana: The Service Layer

The aranet-service crate ties everything together as a background daemon. It exposes a REST API for querying devices and readings, WebSocket streaming for real-time updates, and a Prometheus metrics endpoint that makes Aranet data available to existing monitoring infrastructure.

The Prometheus integration filters metrics by device capability. Aranet2 sensors don't have CO2, so they shouldn't emit aranet_co2_ppm metrics:

for (device, reading) in &device_readings {
    let device_type = resolve_device_type(device);

    if device_type.is_none_or(|dt| dt.has_co2()) && reading.co2 > 0 {
        co2_lines.push(format!(
            "aranet_co2_ppm{{{}}} {}\n", labels, reading.co2
        ));
    }
    if device_type.is_none_or(|dt| dt.has_temperature()) {
        temp_lines.push(format!(
            "aranet_temperature_celsius{{{}}} {:.2}\n",
            labels, reading.temperature
        ));
    }
}

The project ships with a pre-built Grafana dashboard template and a Docker Compose stack that spins up the service, Prometheus, and Grafana together. One docker compose up -d and you have a complete monitoring stack scraping your Aranet sensors.

MQTT publishing with Home Assistant auto-discovery means the sensors automatically appear in HA without manual configuration. Webhook notifications can ping Slack, Discord, or PagerDuty when thresholds are crossed. InfluxDB export is available for users who prefer that over Prometheus.

Why Rust for IoT

Environmental monitoring runs continuously on modest hardware, often a Raspberry Pi tucked behind a bookshelf. Rust's zero-cost abstractions and memory safety aren't academic niceties here; they're practical requirements for a long-running BLE daemon that needs to be reliable without consuming resources.

The async runtime (Tokio) handles concurrent BLE scanning, API serving, MQTT publishing, and metric collection without threading complexity. The type system catches protocol parsing errors at compile time rather than in production at 3 AM. And the workspace structure means each crate carries only the dependencies it needs: the CLI binary doesn't link against egui, and the GUI doesn't pull in the Prometheus library.

Cross-compilation to aarch64-unknown-linux-gnu (Raspberry Pi) works out of the box with cross. The CI pipeline builds and tests on macOS, Linux, and Windows.

Distribution: Meeting Users Where They Are

A tool nobody can install is a tool nobody uses. The project ships through multiple channels:

# Homebrew (macOS/Linux)
brew tap cameronrye/aranet && brew install aranet

# crates.io
cargo install aranet-cli

# Shell installer (macOS/Linux)
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/cameronrye/aranet/releases/latest/download/aranet-cli-installer.sh | sh

# Docker (full monitoring stack)
docker compose up -d

GitHub Releases include shell and PowerShell installers plus macOS DMG bundles for the GUI. The goal is that however someone prefers to install software, there's a path that works.

Liberating Your Data

The broader motivation behind this project goes beyond Aranet sensors. Hardware manufacturers increasingly treat the data your devices produce as something that flows through their cloud, their app, their ecosystem. You bought the sensor, but you're renting access to your own measurements.

Aranet is actually better than most. The sensors work entirely offline and the BLE protocol is straightforward to reverse-engineer. But the tooling gap between "sensor produces data" and "data is useful" was still filled entirely by a mobile app with no export, no API, and no automation.

Building from BLE packets up through storage, APIs, and dashboards in a single workspace proves that this gap doesn't need to exist. Your environmental data can live on your hardware, in standard formats, queryable by standard tools, integrated into the infrastructure you already run. No account required.

The project is open source on GitHub and published to crates.io. If you have an Aranet sensor, brew install aranet and run aranet scan. Your data is waiting.

RSS Is Still Great (and Miniflux Is the Tool You Need)

c@meron.io (Cameron Rye) — Thu, 05 Feb 2026 00:00:00 GMT

In 2026, the best way to read the internet is a 29-year-old technology that most people think died with Google Reader.

RSS (Really Simple Syndication) was created by Netscape in 1997 and later refined by Aaron Swartz. It's a protocol so simple it barely qualifies as one: websites publish a structured feed of their content, and you subscribe to the feeds you want. No algorithm decides what's "relevant." No engagement metrics determine what surfaces. Just content, in chronological order, from sources you chose.

This isn't nostalgia. It's a rational response to what the web has become.

The Problem: Algorithms Ate the Web

Open Google Discover on your phone. Scroll through the recommendations. Notice how many headlines are optimized for clicks rather than accuracy. Notice the AI-generated summaries of articles that themselves were AI-generated. Notice how you didn't ask for any of this.

This is the modern web. Social media algorithms decide what you see based on engagement metrics: not quality, not accuracy, not relevance to your actual interests. The result is a feedback loop optimized for outrage, addiction, and time-on-site.

As one writer put it, the post-Google Reader era gave us "filter bubbles, algorithmically driven news feeds, fake news, polarisation, privacy invasions, clickbait, spam bots, content farms, surveillance capitalism, notification addiction, doomscrolling, data harvesting, goldfish attention spans, cycles of outrage, misinformation loops, bad-faith discourse, trolling, trend-chasing, and the rise of the 'influencer.'"

That's not hyperbole. That's a description of the current state of content consumption.

Search results are polluted with SEO spam. AI-generated garbage floods every platform. Google's AI Overviews have reduced organic clicks by 34.5%, keeping users in Google's ecosystem while publishers watch their traffic evaporate. The platforms that promised to connect us to information have instead become intermediaries extracting value from both sides.

PC Gamer ran a piece in January calling 2026 "the year of the glorious return of the RSS reader," encouraging readers to "kill the algorithm in your head." They're not wrong.

The Solution: Take Back Control

RSS offers something radical: you choose what you read, in the order it was published, with zero tracking.

You choose your sources. No algorithm decides what's "relevant" to you. You subscribe to writers, publications, and topics you care about. If something stops being valuable, you unsubscribe. Simple.

Chronological order. Content appears when it's published, not when it's "trending." There's no algorithmic amplification of inflammatory takes. No engagement-bait rising to the top. Just a timeline that respects the passage of time.

No ads, no tracking, no engagement bait. RSS feeds are just data. They don't contain tracking pixels, don't set cookies, don't build advertising profiles. Your reading habits remain yours.

Portability. OPML export means you're never locked in. Don't like your current reader? Export your subscriptions and import them elsewhere. Try doing that with your YouTube recommendations or Twitter timeline.

It makes the web feel manageable. Instead of the infinite scroll, you have a finite reading list. You can actually reach the end. There's something psychologically healthy about completing your reading rather than drowning in an endless stream.

RSS also powers more than most people realize. Over 80% of podcast distribution still runs on RSS feeds. YouTube channels have RSS feeds (though Google hides them). GitHub releases, Reddit communities, government sites, academic preprints: all available via RSS. The infrastructure never went away.

Why Miniflux Gets It Right

There are dozens of RSS readers available. I've tried most of them. Miniflux is the one that stuck, and the reason comes down to philosophy.

Miniflux is a minimalist and opinionated self-hosted feed reader created by Frédéric Guillot. It's written in Go, compiles to a single static binary, and uses PostgreSQL as its only database. The entire thing runs on a couple megabytes of memory, even with hundreds of feeds.

The interface is deliberately spartan. No AI recommendations. No social sharing buttons. No fancy features competing for your attention. Just your feeds, presented cleanly, optimized for reading.

As one reviewer noted: "Coming from feature-rich, busy social media apps, Miniflux's interface may feel boring at first." That's the point. The absence of distraction is the feature.

Privacy by Design

Miniflux treats privacy as an architectural concern, not an afterthought:

Strips tracking pixels automatically from feed content
Removes UTM parameters and other tracking cruft from URLs
Proxies media through the server to prevent third-party tracking
Opens external links with rel="noopener noreferrer" and referrerpolicy="no-referrer"
Plays YouTube videos via youtube-nocookie.com
Zero telemetry, zero advertising

When every app harvests data by default, Miniflux's stance is refreshing. It respects HTTP caching headers to avoid hammering servers. It doesn't phone home. It just does its job.

Keyboard-Driven Workflow

Miniflux is designed for people who read a lot. Full keyboard shortcuts let you fly through hundreds of articles:

Arrow keys for navigation
v to open the original article
s to star/bookmark
d to fetch full article content
/ for search

The full-text fetching is particularly useful. Many feeds only include summaries, forcing you to click through to the original site. Miniflux can automatically fetch the complete article, letting you read everything in one place. You can enable this per-feed or trigger it manually with a keystroke.

25+ Integrations

One of Miniflux's underrated strengths is its integration ecosystem:

Category	Services
Read-it-later	Wallabag, Instapaper, Pocket, Readwise Reader
Bookmarking	Pinboard, Linkding, LinkAce, Shaarli
Notifications	Discord, Slack, Telegram, Matrix, Ntfy, Pushover
Note-taking	Notion
Automation	Webhooks, Apprise

The full REST API means you can build whatever custom integrations you need. There's also Fever API and Google Reader API compatibility, which opens up dozens of existing mobile apps.

Deployment

Getting Miniflux running takes about five minutes:

# docker-compose.yml
services:
  miniflux:
    image: miniflux/miniflux:latest
    ports:
      - "8080:8080"
    environment:
      - DATABASE_URL=postgres://miniflux:secret@db/miniflux?sslmode=disable
      - RUN_MIGRATIONS=1
      - CREATE_ADMIN=1
      - ADMIN_USERNAME=admin
      - ADMIN_PASSWORD=changeme
    depends_on:
      - db

  db:
    image: postgres:15
    environment:
      - POSTGRES_USER=miniflux
      - POSTGRES_PASSWORD=secret
    volumes:
      - miniflux-db:/var/lib/postgresql/data

volumes:
  miniflux-db:

Run docker-compose up -d, navigate to localhost:8080, and you're done. For those who don't want to self-host, there's an official hosted option at reader.miniflux.app for $15/year.

The RSS Ecosystem

Miniflux doesn't exist in isolation. A whole ecosystem of tools makes RSS more useful.

Feed Generators

Many sites have removed their RSS feeds or never had them. These tools bridge the gap:

RSS-Bridge is a PHP application that generates feeds for sites that removed them: YouTube, Twitter/X, Reddit, Telegram, and dozens more. The project's README includes a manifesto worth quoting: "Dear so-called 'social' websites... You're not social when you hamper sharing by removing feeds... We are rebuilding bridges you have willfully destroyed."

RSSHub is a community-driven project with 30,000+ GitHub stars, generating RSS feeds for seemingly everything. If a site exists, someone has probably written an RSSHub route for it.

Alternative Frontends

Miniflux's spartan interface isn't for everyone. Third-party frontends offer alternatives:

ReactFlux: Beautiful React-based web frontend with a more visual approach
Nextflux: Modern Reeder-inspired UI, PWA-capable
Reminiflux and Fluxjs: Additional web frontend options

These connect to Miniflux via its API, giving you the backend's reliability with a different presentation layer.

Mobile Apps

The Fever and Google Reader API compatibility means Miniflux works with excellent mobile apps:

iOS: Unread, Fiery Feeds, Lire
Android: Miniflutt (FOSS), Read You (Material You design), News+

Honest Limitations

Miniflux isn't perfect for everyone:

No feed discovery. You need to know your sources. If you want recommendation features, FreshRSS might be better.
Regex-only filtering. Block rules require regex knowledge, not a simple keyword UI.
Spartan by design. Some people genuinely want more features. That's valid.

For me, these limitations are features. The lack of discovery means I'm intentional about what I subscribe to. The minimal interface means I focus on reading, not fiddling with settings.

Getting Started

If you're new to RSS, here's a practical starting point:

Deploy Miniflux using the Docker Compose configuration above, or sign up for the hosted version.
Add feeds you already read. Most sites still have RSS feeds at /feed/, /rss/, or /feed.xml. Browser extensions like "Get RSS Feed URL" can help find them.
Subscribe to writers, not publications. Individual bloggers often have better signal-to-noise ratios than large publications.
Use RSS-Bridge for sites that don't have feeds. YouTube channels, Reddit subreddits, and Twitter accounts can all become RSS feeds.
Export your OPML periodically as a backup. This is your subscription list in a portable format.
Resist the urge to subscribe to everything. Start with 10-20 feeds. Add more only when you find yourself wanting more content.

The goal isn't to replicate the firehose of social media. It's to curate a reading list that actually serves your interests.

The Bigger Picture

RSS won't save the internet. The platform incentives that created the current mess aren't going away. Algorithms will continue optimizing for engagement. AI slop will continue flooding search results. Publishers will continue chasing whatever metrics the platforms reward.

But RSS might save your relationship with the internet.

There's something deeply satisfying about opening your feed reader and seeing exactly what you asked for: nothing more, nothing less. No manipulation. No dark patterns. No algorithmic anxiety about what you might be missing. Just content from people you chose to follow, in the order they published it.

In a web increasingly optimized for everyone's attention, RSS is optimized for yours.

The technology is 29 years old. It's been declared dead a dozen times. And it's still the best way to read the internet in 2026.

Resources:

Miniflux - Official site and documentation
Miniflux GitHub - Source code
RSS-Bridge - Generate feeds for sites without them
RSSHub - Community-driven feed generator
awesome-selfhosted RSS readers - Comprehensive list of alternatives

Building Zero Crust: Distributed State Management in Electron

c@meron.io (Cameron Rye) — Wed, 28 Jan 2026 00:00:00 GMT

Point-of-sale systems come with a specific architectural constraint. You need two displays, one for the cashier and one for the customer, showing identical information but running on separate hardware with strict security boundaries. Get the synchronization wrong and customers see incorrect prices. Get the security wrong and you're open to price tampering.

Zero Crust is my exploration of these patterns in Electron. It's a reference implementation for distributed state management with the defense-in-depth security that desktop applications need.

The Dual-Head Challenge

In production POS deployments, the cashier terminal and customer-facing display are often separate physical devices. The cashier's screen shows product grids, payment controls, and management functions. The customer's screen shows only the cart, a simple display that trusts nothing.

Electron's multi-window architecture maps cleanly onto this model. Each window runs in its own renderer process, sandboxed and isolated. The main process acts as the trusted coordinator. It's the only process with access to payment services, persistence, and the application state.

┌─────────────────┐     ┌─────────────────┐
│  Cashier Window │     │ Customer Window │
│   (Renderer)    │     │   (Renderer)    │
│   ┌─────────┐   │     │   ┌─────────┐   │
│   │ Cart UI │   │     │   │ Cart UI │   │
│   └─────────┘   │     │   └─────────┘   │
└────────┬────────┘     └────────┬────────┘
         │                       │
         │    IPC Commands       │
         ▼                       ▼
┌──────────────────────────────────────────┐
│            Main Process                   │
│  ┌──────────┐ ┌─────────┐ ┌──────────┐  │
│  │MainStore │ │Payment  │ │Broadcast │  │
│  │ (State)  │ │Service  │ │Service   │  │
│  └──────────┘ └─────────┘ └──────────┘  │
└──────────────────────────────────────────┘

Centralized State with MainStore

The heart of Zero Crust is MainStore, a centralized state container that serves as the single source of truth. Every piece of application state lives here: the cart items, transaction history, current session, and payment status.

// MainStore.ts - Centralized state management
export class MainStore {
  private state: InternalState;
  private listeners = new Set<Listener>();

  private updateState(recipe: (draft: InternalState) => void): void {
    this.state = produce(this.state, (draft) => {
      recipe(draft);
      draft.version++;
    });
    this.notifyListeners();
  }
}

The key insight here is state versioning. Every state update increments a version number. This allows renderers to detect stale state and provides an audit trail of state changes. Combined with Immer's structural sharing, updates are both immutable and efficient.

The Command Pattern for IPC

Renderers don't mutate state directly. They can't. They send commands to the main process, which validates and processes them. This is the Command Pattern applied to IPC:

// ipc-types.ts - Discriminated union of commands
export type Command =
  | { type: 'ADD_ITEM'; sku: string }
  | { type: 'REMOVE_ITEM'; sku: string }
  | { type: 'UPDATE_QUANTITY'; sku: string; quantity: number }
  | { type: 'CLEAR_CART' }
  | { type: 'START_PAYMENT' }
  | { type: 'VOID_TRANSACTION' };

Notice that renderers send SKUs, not prices. The main process looks up prices from its trusted product catalog. This ID-based messaging pattern prevents a compromised renderer from sending fake prices. The worst it can do is add items that exist.

Runtime Validation with Zod

TypeScript types vanish at runtime. When an IPC message crosses the process boundary, you have no guarantee it matches your type definitions. A malicious actor could send arbitrary data. This is where Zod comes in:

// schemas.ts - Runtime validation
export const AddItemSchema = z.object({
  type: z.literal('ADD_ITEM'),
  sku: z.string().min(1).max(50),
});

export const CommandSchema = z.discriminatedUnion('type', [
  AddItemSchema,
  RemoveItemSchema,
  UpdateQuantitySchema,
  ClearCartSchema,
  StartPaymentSchema,
  VoidTransactionSchema,
]);

Every incoming command is validated before processing. Invalid commands are rejected with detailed error messages for debugging. This transforms runtime errors from mysterious crashes into clear validation failures.

Defense in Depth: Electron Security

Zero Crust implements six layers of security, each catching threats that slip past others:

1. Electron Fuses: Compile-time flags that cannot be changed at runtime. Node.js integration is disabled at the binary level.

2. Context Isolation: Renderer processes run in an isolated JavaScript context. They cannot access Node.js APIs, Electron internals, or the preload script's scope.

3. Zod Validation: Every IPC message is validated against a strict schema. Malformed or unexpected data is rejected.

4. Sender Verification: IPC handlers check event.sender against known window IDs. Commands from unknown sources are dropped.

5. Navigation Control: All navigation is blocked except to file:// URLs. No external websites can be loaded into windows.

6. Permission Denial: All permission requests (camera, microphone, geolocation) are denied by default.

// SecurityHandlers.ts - Sender validation
function validateSender(event: IpcMainInvokeEvent): boolean {
  const webContents = event.sender;
  const knownIds = windowManager.getKnownWebContentsIds();
  return knownIds.includes(webContents.id);
}

The BroadcastService Pattern

State synchronization is notoriously tricky. Delta updates, conflict resolution, and eventual consistency are all PhD-level distributed systems problems. Zero Crust sidesteps that complexity with a brutally simple approach: broadcast the entire state on every change.

// BroadcastService.ts - Full-state sync
export class BroadcastService {
  constructor(mainStore: MainStore, windowManager: WindowManager) {
    mainStore.subscribe((state) => {
      windowManager.broadcastState(state);
    });
  }
}

When the cart changes, every renderer gets a complete snapshot of the new state. No diffing, no patches, no merge conflicts. Renderers replace their local state with whatever arrives.

This pattern eliminates entire categories of bugs:

No stale state: Renderers always have the latest version
No synchronization drift: State is identical across all windows by construction
No ordering issues: Each broadcast is a complete snapshot
Trivial debugging: Log any state snapshot and you see exactly what all renderers see

The performance cost? Negligible. A typical POS cart has maybe 20 items. Serializing and deserializing that with structuredClone takes microseconds.

The Architecture Debug Window

Debugging distributed systems is hard. You can't set a breakpoint across process boundaries. You can't easily trace the flow of messages between windows. That's why Zero Crust includes a real-time Architecture Debug Window.

The debug window shows:

Event Timeline: Every IPC message, state update, and trace event in chronological order
Architecture Graph: Visual representation of windows and message flow with animated edges
State Inspector: JSON tree view with diff highlighting showing exactly what changed
Live Statistics: Events per second, average latency, state version

The implementation uses a circular buffer to store trace events without unbounded memory growth:

// TraceService.ts - Event collection
export class TraceService {
  private events: TraceEvent[] = [];
  private maxEvents = 1000;

  record(event: Omit<TraceEvent, 'id' | 'timestamp'>): void {
    const fullEvent = {
      ...event,
      id: this.nextId++,
      timestamp: Date.now(),
    };
    this.events.push(fullEvent);
    if (this.events.length > this.maxEvents) {
      this.events.shift();
    }
    this.broadcast(fullEvent);
  }
}

Critically, the debug window is lazy activated. TraceService only collects events when the debug window is open. No overhead when you don't need it.

Integer Math for Currency

Here's a bug that bankrupts companies:

0.1 + 0.2 === 0.3  // false! It's 0.30000000000000004

Floating-point arithmetic is fundamentally incompatible with financial calculations. The IEEE 754 standard cannot precisely represent most decimal values. Zero Crust solves this by storing all monetary values as integers representing cents:

// currency.ts - Integer-only currency
export type Cents = number & { __brand: 'Cents' };

export function toCents(dollars: number): Cents {
  return Math.round(dollars * 100) as Cents;
}

export function formatCurrency(cents: Cents): string {
  return `$${(cents / 100).toFixed(2)}`;
}

The branded type Cents makes it impossible to accidentally mix cents and dollars. TypeScript will error if you pass a regular number where Cents is expected.

This pattern extends to all calculations:

Tax is computed as (subtotal * taxRate) / 100, rounded
Discounts are stored and applied as cent values
Totals are summed, never multiplied by fractional amounts

Screenshots

Here's Zero Crust in action:

The cashier window with product grid and cart sidebar

Customer display showing the synchronized cart state

Transaction history with completed orders

Lessons Learned

Building Zero Crust reinforced several principles:

Simplicity beats cleverness. Full-state broadcast is "inefficient" but eliminates entire bug categories. The debuggability alone is worth it.

Security is layers. No single security measure is sufficient. Context isolation protects against XSS. Zod validation catches malformed data. Sender verification stops spoofed messages. Each layer catches what others miss.

TypeScript needs runtime backup. Types are erased at runtime. Process boundaries need runtime validation. Zod provides this beautifully.

Debug tools pay dividends. The Architecture Debug Window took significant effort to build. It's saved ten times that in debugging time.

Model real hardware. Designing for dual-head from the start forced clean separation. The constraints improved the architecture.

Try It Yourself

Zero Crust is open source at github.com/cameronrye/zero-crust. Clone it, run pnpm dev, and explore the architecture. The debug window (View > Architecture or Cmd+Shift+A) is the best way to understand the message flow.

The patterns here aren't specific to point-of-sale. If you're working on any multi-window Electron app, I hope some of it transfers.

Building Ask: A RAG-Powered Chatbot for My Portfolio

c@meron.io (Cameron Rye) — Mon, 12 Jan 2026 00:00:00 GMT

Portfolio sites are inherently passive. Visitors land on a page, scan for relevant information, and either find what they need or bounce. Traditional search helps, but it requires visitors to know what to look for. I wanted something different: an AI assistant that understands my work and can have a conversation about it.

The result is Ask, a RAG-powered chatbot that lives on every page of rye.dev. It knows about my projects, can discuss my blog posts, and adapts its behavior based on which page you're viewing. This post documents how I built it.

The Architecture

Ask runs entirely on Cloudflare's edge infrastructure. There's no origin server, no container to manage, no cold starts to worry about. The stack consists of:

Frontend: Preact component with Nanostores for state management
API: Astro API routes deployed to Cloudflare Workers
RAG: AI Search (AutoRAG) with Vectorize fallback
LLM: Llama 3.3 70B via Workers AI
Observability: AI Gateway for request logging and analytics

The edge-first design means responses start streaming in under 200ms from anywhere in the world. The entire knowledge base (blog posts, project descriptions, technical details) lives in Cloudflare R2 and gets indexed automatically.

RAG: Teaching the AI About My Work

A general-purpose LLM knows nothing about my specific projects. RAG (Retrieval-Augmented Generation) solves this by injecting relevant context into each request. When someone asks "What MCP servers has Cameron built?", the system:

Searches the knowledge base for relevant content
Retrieves the top matches (blog posts about gopher-mcp, openzim-mcp, etc.)
Injects that context into the system prompt
Lets the LLM generate a grounded response

The chunking strategy matters. I split content by paragraphs, respecting a 2000-character maximum with 200-character overlap between chunks:

export function chunkText(
  text: string,
  maxChars = 2000,
  overlap = 200
): string[] {
  const chunks: string[] = [];
  const paragraphs = text.split(/\n\n+/);
  let currentChunk = '';

  for (const paragraph of paragraphs) {
    const trimmed = paragraph.trim();
    if (!trimmed) continue;

    if (currentChunk && currentChunk.length + trimmed.length + 2 > maxChars) {
      chunks.push(currentChunk.trim());
      // Start new chunk with overlap from previous
      const words = currentChunk.split(/\s+/);
      const overlapWords = words.slice(-Math.floor(overlap / 6));
      currentChunk = overlapWords.join(' ') + '\n\n' + trimmed;
    } else {
      currentChunk = currentChunk
        ? currentChunk + '\n\n' + trimmed
        : trimmed;
    }
  }

  if (currentChunk.trim()) {
    chunks.push(currentChunk.trim());
  }

  return chunks;
}

The overlap ensures that concepts spanning paragraph boundaries don't get lost. Each chunk gets embedded using BGE Base EN v1.5, producing 768-dimensional vectors stored in Cloudflare Vectorize.

Context-Aware Conversations

Ask adapts based on where you are on the site. On the homepage, you get general questions about my background. On a blog post, the starter questions relate to that specific article. On a project page, the questions focus on that project's tech and architecture. On a 404, Ask tries to help you find what you were looking for.

This works through a page context system. Each page passes metadata to the chat component:

interface PageContext {
  type: 'default' | 'blog' | 'project' | '404';
  title?: string;
  slug?: string;
  tags?: string[];
  description?: string;
}

The system prompt gets augmented with this context, so the LLM understands what the visitor is currently reading and can provide more relevant responses.

The System Prompt: Expert on My Work, Not Me

One design decision I'm particularly happy with: Ask is an expert system about my work, not a simulation of me. The distinction matters. The prompt explicitly states:

"You are Ask, an AI assistant on Cameron Rye's portfolio website at rye.dev. You are an expert system about Cameron's work, projects, and technical expertise—not Cameron himself."

This framing avoids the uncanny valley of AI pretending to be human while still providing helpful, knowledgeable responses. Ask can discuss my projects in detail, explain technical decisions, and point visitors to relevant content without ever claiming to be me.

Security: Hardening Against Prompt Injection

Any public-facing LLM application needs security hardening. Ask implements multiple layers of defense:

Input Sanitization: Before any processing, user input gets sanitized. Control characters are stripped, excessive whitespace is normalized, and the input is truncated to a reasonable length.

Prompt Injection Detection: A dedicated classifier runs on every message, looking for common injection patterns. This catches attempts to override the system prompt, extract internal instructions, or manipulate the AI's behavior:

const injectionPatterns = [
  /ignore\s+(all\s+)?(previous|above|prior)/i,
  /disregard\s+(all\s+)?(previous|above|prior)/i,
  /forget\s+(all\s+)?(previous|above|prior)/i,
  /new\s+instructions?:/i,
  /system\s*prompt/i,
  /you\s+are\s+now/i,
  /pretend\s+(you\s+are|to\s+be)/i,
  /act\s+as\s+(if|a|an)/i,
  /roleplay\s+as/i,
  /jailbreak/i,
  /bypass\s+(safety|filter|restriction)/i,
];

Rate Limiting: A sliding window rate limiter prevents abuse. Each IP gets a limited number of requests per time window, with the limits stored in Turso (a distributed SQLite database). This prevents both denial-of-service attacks and excessive API costs.

Response Filtering: The LLM's output also gets checked before being sent to the client. Any response that appears to contain leaked system prompts or internal instructions gets blocked.

Streaming: Real-Time Response Delivery

Nobody wants to wait for a complete response before seeing anything. Ask uses Server-Sent Events (SSE) to stream tokens as they're generated:

const stream = new ReadableStream({
  async start(controller) {
    const encoder = new TextEncoder();

    for await (const chunk of aiStream) {
      const text = chunk.response || '';
      controller.enqueue(
        encoder.encode(`data: ${JSON.stringify({ text })}\n\n`)
      );
    }

    controller.enqueue(encoder.encode('data: [DONE]\n\n'));
    controller.close();
  },
});

return new Response(stream, {
  headers: {
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache',
    'Connection': 'keep-alive',
  },
});

The frontend parses these events and updates the UI in real-time, giving that satisfying "typing" effect as the response streams in.

The UI: Minimal and Unobtrusive

The chat interface needed to be accessible without being intrusive. The solution: a floating button in the bottom-right corner that expands into a full chat panel. On mobile, it takes over the full screen. On desktop, it's a contained panel that doesn't interfere with the main content.

The design uses a liquid glass aesthetic: translucent backgrounds with subtle blur effects that let the underlying page show through. This keeps the chat feeling integrated rather than bolted-on.

State management uses Nanostores, a tiny (less than 1KB) state management library that works perfectly with Preact. The chat state (messages, loading status, error states) lives in a single store that components can subscribe to:

export const chatStore = atom<ChatState>({
  messages: [],
  isLoading: false,
  error: null,
  isOpen: false,
});

Lessons Learned

RAG quality depends on chunking strategy. My first attempt used fixed-size chunks that often split sentences mid-thought. Switching to paragraph-aware chunking with overlap dramatically improved retrieval quality.

System prompts need iteration. The initial prompt was too permissive, leading to responses that strayed from my actual work. Adding explicit constraints and examples of good responses helped focus the output.

Edge deployment changes everything. Running on Cloudflare Workers means the entire request, from receiving the message to starting the stream, happens in under 50ms. There's no cold start penalty, no container spin-up, just immediate response.

Security is non-negotiable. Within hours of deploying the first version, I saw prompt injection attempts in the logs. The multi-layer security approach catches these before they can cause problems.

What's Next

Ask is live and working, but there's always room for improvement. Future enhancements I'm considering:

Conversation memory: Currently each message is independent. Adding conversation history would enable more natural multi-turn dialogues.
Citation links: When Ask references a blog post or project, it should link directly to that content.
Analytics integration: Understanding what visitors ask about could inform future content.

The code is part of my portfolio site, which is open source. If you're building something similar, feel free to explore the implementation.

Ask is available on every page of rye.dev. Try it out: click the chat button in the bottom-right corner and ask about my projects, experience, or anything else you'd like to know.

Uzumaki: One Spiral Engine, Two Native Platforms

c@meron.io (Cameron Rye) — Thu, 08 Jan 2026 00:00:00 GMT

Spirals appear everywhere in nature. The nautilus shell grows in a logarithmic spiral, maintaining its shape at every scale. Sunflower seeds arrange themselves in Vogel spirals, optimizing for space using the golden angle. Galaxy arms sweep outward in patterns described by the same mathematics that fascinated Archimedes over two millennia ago.

Uzumaki started as a way to play with these patterns and actually see the equations behind them. It grew into a cross-platform application spanning six deployment targets: web browser, Progressive Web App, iOS, iPadOS, macOS, and watchOS.

Ten Algorithms, One Canvas

The core challenge was implementing ten distinct spiral algorithms with consistent behavior across platforms. Each spiral type follows a specific mathematical formula, most using polar coordinates where r is the radius and theta is the angle.

Polar Coordinate Spirals

The simpler spirals translate directly from mathematical formulas:

// Archimedean: constant spacing between turns
r = a * theta;

// Fibonacci (Golden): self-similar, found in nature
r = a * Math.pow(PHI, (2 * theta) / Math.PI) * 0.1;

// Logarithmic: equiangular, seen in hurricanes
r = a * Math.exp(0.1 * theta);

// Fermat: parabolic, used in optics
r = a * Math.sqrt(Math.abs(theta)) * 2;

Construction Spirals

Other spirals require iterative construction rather than simple formulas:

// Theodorus: built from right triangles
for (let n = 1; n <= numSteps; n++) {
  angle += Math.atan(1 / Math.sqrt(n));
  x += Math.cos(angle);
  y += Math.sin(angle);
}

// Vogel: phyllotaxis pattern (sunflower seeds)
const GOLDEN_ANGLE = Math.PI * (3 - Math.sqrt(5)); // ~137.5 degrees
for (let n = 0; n < numSteps; n++) {
  const theta = n * GOLDEN_ANGLE + rotation;
  const r = scale * Math.sqrt(n) * 2;
}

The Curlicue fractal produces particularly striking patterns by accumulating angles based on the golden ratio squared.

Web Performance: Workers and TypedArrays

Generating thousands of points per frame while maintaining 60fps required moving computation off the main thread. Web Workers handle spiral generation, but the real performance gain came from TypedArrays.

export function generateSpiralTyped(params: SpiralParams): TypedSpiralPoints {
  const points = createTypedPoints(numSteps); // Float32Array
  const rotation = time * spinRate;

  for (let i = 0; i < numSteps; i++) {
    const theta = i * stepSize + rotation;
    const r = calculateRadius(i * stepSize, params);
    setPoint(points, i, r * Math.cos(theta), r * Math.sin(theta));
  }
  return points;
}

TypedArrays are transferable between the main thread and Web Workers without copying, eliminating serialization overhead. The interleaved [x0, y0, x1, y1, ...] format maps directly to canvas drawing operations.

Swift Parity: SIMD Vectorization

The Swift implementation needed matching performance. Apple's SIMD framework enables vectorized math operations that process multiple points simultaneously:

func generatePolarSpiral(params: SpiralParams) -> [SIMD2<Float>] {
  var points: [SIMD2<Float>] = []
  let rotation = params.time * params.spinRate
  
  for i in 0..<params.numSteps {
    let theta = Float(i) * params.stepSize + rotation
    let r = calculateRadius(Float(i) * params.stepSize, params)
    points.append(SIMD2(r * cos(theta), r * sin(theta)))
  }
  return points
}

Both implementations follow the same algorithm specification document, ensuring a spiral generated on web looks identical on watchOS.

Maintaining Feature Parity

Cross-platform development often leads to feature drift, where platforms diverge as each adds unique capabilities. Uzumaki maintains parity through:

Shared Algorithm Specification: A single markdown document defines exact formulas and edge cases
Identical Presets: Both platforms ship with the same ten curated spiral configurations
Consistent Color Palettes: Rainbow, Aurora, Neon, Matrix, and six other presets render identically
Platform-Appropriate Controls: Touch gestures on mobile, keyboard shortcuts on desktop, Digital Crown on watch

iOS 26 Liquid Glass

Apple's upcoming iOS 26 introduces the Liquid Glass design language. Uzumaki's Apple apps include conditional support that activates on iOS 26 while maintaining backward compatibility with current releases. The translucent, depth-aware interface style complements the mathematical visualizations without competing for attention.

watchOS: Spirals on Your Wrist

The watchOS build came with its own constraints. The small display forces aggressive simplification, but spirals still hold up well at reduced complexity.

Key adaptations for watchOS:

Digital Crown: Smooth zoom control with haptic feedback at preset boundaries
Swipe Navigation: Horizontal swipes cycle through preset configurations
Complications: Circular, corner, rectangular, and inline complications show static spiral art
Tap Gestures: Single tap toggles animation, double tap resets zoom

The complications put spiral art on the watch face, cycling to a different preset each hour.

Shareable URLs

One feature absent from native apps appears on web: shareable URLs. Every spiral configuration encodes into a URL that recreates the exact state:

export function encodeState(params: SpiralParams): string {
  const state = {
    t: params.type,
    c: params.colorPreset,
    s: params.tightness,
    r: params.spinRate,
    z: params.zoom
  };
  return btoa(JSON.stringify(state));
}

Users can share spiral creations by copying the URL. The recipient sees the identical animation without any configuration.

Lessons Learned

Canvas rendering scales well. Both HTML Canvas and SwiftUI Canvas handle thousands of animated points at 60fps when computation moves off the render thread.

TypedArrays are underutilized. Most JavaScript developers default to regular arrays. For numerical computation, Float32Array offers significant performance gains and enables zero-copy Worker communication.

Algorithm documentation prevents drift. Without a formal specification, subtle differences accumulate between implementations. The shared algorithm document caught several bugs during development.

Platform idioms matter. Users expect swipe gestures on iOS and keyboard shortcuts on desktop. Forcing identical interaction patterns across platforms feels unnatural.

Explore mathematical spirals at uzumaki.app or browse the source code on GitHub. Download for iOS and iPadOS or macOS on the App Store.

Building ClarissaBot: Vehicle Safety Intelligence with Azure AI Foundry

c@meron.io (Cameron Rye) — Sat, 20 Dec 2025 00:00:00 GMT

Vehicle safety data exists in public databases, but getting at it means knowing where to look and how to read complex government datasets. ClarissaBot closes that gap. It's an AI agent that answers natural language questions about recalls, safety ratings, and consumer complaints by querying NHTSA data in real-time.

This project became an exploration of Azure AI Foundry's capabilities: function calling, streaming responses, managed identity authentication, and the emerging practice of Reinforcement Fine-Tuning. Here's what I learned building it.

The Problem Space

Every year, NHTSA (National Highway Traffic Safety Administration) issues hundreds of vehicle recalls. Consumers can search their database, but the interface assumes you know exactly what you're looking for. Ask "should I be worried about my 2020 Tesla Model 3?" and you get a list of recall campaigns, not an answer.

I wanted to build something that could:

Answer questions in natural language
Pull real-time data from authoritative sources
Maintain context across a conversation ("what about complaints?" after asking about recalls)
Decode VINs to identify vehicles automatically

What Azure AI Foundry Provides

Azure AI Foundry (formerly Azure Cognitive Services / Azure OpenAI) provides the infrastructure that makes ClarissaBot possible. Beyond just hosting models, it offers:

Function Calling: The model can decide to call external tools based on user intent
Streaming Responses: Server-Sent Events for real-time token delivery
Managed Identity: No API keys in configuration, just Azure RBAC
Reinforcement Fine-Tuning: Train specialized models using custom graders

The SDK integration with .NET is surprisingly clean. Using Azure.AI.OpenAI and DefaultAzureCredential:

var credential = new DefaultAzureCredential();
var client = new AzureOpenAIClient(new Uri(endpoint), credential);
var chatClient = client.GetChatClient(deploymentName);

No API keys to rotate. No secrets to manage. Just identity-based access.

Function Calling: Teaching the Model to Act

The core of ClarissaBot is function calling. Instead of training the model on vehicle data (which would become stale), I give it tools to query live APIs:

ChatTool.CreateFunctionTool(
    "check_recalls",
    "Check for vehicle recalls from NHTSA.",
    BinaryData.FromObjectAsJson(new {
        type = "object",
        properties = new {
            make = new { type = "string", description = "Vehicle manufacturer" },
            model = new { type = "string", description = "Vehicle model name" },
            year = new { type = "integer", description = "Model year" }
        },
        required = new[] { "make", "model", "year" }
    }))

The model receives tool definitions, decides when to call them, and synthesizes the results into conversational responses. It's the ReAct pattern in action: Reason about the task, Act by calling tools, Observe results, Repeat.

The Challenge of Vehicle Context

The hardest problem wasn't calling APIs. It was maintaining conversational context. When a user asks "any recalls?" after discussing their Tesla Model 3, the agent needs to remember what vehicle they're talking about.

The solution tracks vehicle context across turns:

public sealed class VehicleContextHistory
{
    private readonly List<(VehicleContext Vehicle, DateTime AccessedUtc)> _vehicles = [];
    
    public VehicleContext? Current => _vehicles.Count > 0 ? _vehicles[^1].Vehicle : null;
    
    public bool AddOrUpdate(VehicleContext vehicle)
    {
        var existingIndex = _vehicles.FindIndex(v => v.Vehicle.Key == vehicle.Key);
        if (existingIndex >= 0)
        {
            _vehicles.RemoveAt(existingIndex);
            _vehicles.Add((vehicle, DateTime.UtcNow));
            return false;
        }
        _vehicles.Add((vehicle, DateTime.UtcNow));
        return true;
    }
}

Context gets injected into the system prompt on each turn, reminding the model which vehicles are being discussed.

Streaming: Making AI Feel Responsive

Nothing kills user experience like staring at a blank screen. ClarissaBot streams responses token-by-token using Server-Sent Events:

public async IAsyncEnumerable<StreamingEvent> ChatStreamRichAsync(
    string userMessage,
    string? conversationId = null,
    CancellationToken cancellationToken = default)
{
    // ... setup code ...
    
    await foreach (var update in streamingUpdates.WithCancellation(cancellationToken))
    {
        foreach (var contentPart in update.ContentUpdate)
        {
            if (!string.IsNullOrEmpty(contentPart.Text))
            {
                yield return new ContentChunkEvent(contentPart.Text);
            }
        }
    }
}

The frontend receives typed events: ContentChunkEvent for text, ToolCallEvent when querying NHTSA, VehicleContextEvent when the vehicle changes. Users see the agent "thinking" in real-time.

Reinforcement Fine-Tuning: Training with Live Data

The most ambitious part of the project is preparing for Reinforcement Fine-Tuning (RFT). Instead of supervised fine-tuning with static examples, RFT uses a grader that evaluates model responses against live API data:

def grade_response(response: str, expected: dict) -> float:
    """Grades model response against live NHTSA data."""
    api_result = query_nhtsa(expected['year'], expected['make'], expected['model'])

    if expected['query_type'] == 'recalls':
        return score_recall_response(response, api_result)
    elif expected['query_type'] == 'safety_rating':
        return score_rating_response(response, api_result)
    # ...

The training dataset includes 502 examples covering recalls, complaints, safety ratings, multi-turn conversations, and edge cases. The grader validates that responses accurately reflect real NHTSA data: if Tesla issued a recall, the model better mention it.

Infrastructure as Code with Bicep

The entire infrastructure deploys through Azure Bicep templates:

module apiApp 'modules/container-app.bicep' = {
  params: {
    name: '${baseName}-api-${environment}'
    containerAppsEnvironmentId: containerAppsEnv.outputs.id
    containerImage: apiImage
    useManagedIdentity: true
    envVars: [
      { name: 'AZURE_OPENAI_ENDPOINT', value: azureOpenAIEndpoint }
      { name: 'APPLICATIONINSIGHTS_CONNECTION_STRING', value: monitoring.outputs.appInsightsConnectionString }
    ]
  }
}

Container Apps provide serverless scaling: scale to zero when idle, burst to handle traffic. Combined with managed identity, the API authenticates to Azure OpenAI without any secrets.

Lessons Learned

Function calling changes how you supply knowledge. Instead of cramming knowledge into model weights, give it tools. The model reasons about when to use tools; you implement what tools do.

Context management is underrated. Users expect conversational continuity. Tracking vehicle context across turns transformed the experience from "query interface" to "conversation."

Streaming is non-negotiable. Even with fast responses, the perceived latency of waiting for a complete response feels slow. Token-by-token streaming makes AI feel alive.

Managed identity simplifies everything. No API key rotation, no secrets in configuration, no accidental exposure. Just RBAC permissions on Azure resources.

RFT trains against a moving target. Training against live data means models stay current as the world changes. The grader becomes the source of truth.

What's Next

ClarissaBot currently uses GPT-4.1 through Azure OpenAI. The RFT training pipeline is ready for when Azure AI Foundry's reinforcement training becomes generally available. The goal: a specialized model that understands vehicle safety better than a general-purpose LLM.

The project also serves as a template for building other domain-specific agents. The patterns (function calling, context management, streaming, managed identity) apply to any scenario where AI needs to interact with real-world data.

ClarissaBot is open source at github.com/cameronrye/clarissabot. Try the live demo at bot.clarissa.run to check recalls on your vehicle.

Building Clarissa: Learning How AI Agents Actually Work

c@meron.io (Cameron Rye) — Sun, 07 Dec 2025 00:00:00 GMT

Building Clarissa started as a learning exercise. I wanted to understand how AI agents actually work. I'd used Claude, ChatGPT, and various coding assistants plenty, but I couldn't have told you what really happens between the prompt and the tool call, and that bothered me. What I found was simpler than I expected in some places and a lot fussier in others.

What follows is what building a terminal AI assistant from scratch taught me: the patterns that emerged, and the parts that turned out harder than they looked.

Why Build a Terminal AI Agent?

Existing AI interfaces felt disconnected from my actual workflow. I spend most of my day in the terminal, and switching to a browser or GUI to ask an AI for help created friction. More importantly, I wanted to understand:

How do AI agents decide when to use tools versus just respond?
How do you manage context windows that can hold millions of tokens?
What makes tool execution safe and reliable?
How does the Model Context Protocol actually work?

The best way to learn was to build.

The ReAct Pattern: Reasoning + Acting

The core of Clarissa is the ReAct (Reasoning + Acting) pattern. This isn't some complex neural architecture; it's a surprisingly simple loop:

async run(userMessage: string): Promise<string> {
  this.messages.push({ role: "user", content: userMessage });

  for (let i = 0; i < maxIterations; i++) {
    // Get LLM response
    const response = await llmClient.chatStreamComplete(
      this.messages,
      toolRegistry.getDefinitions()
    );

    this.messages.push(response);

    // Check for tool calls
    if (response.tool_calls?.length) {
      for (const toolCall of response.tool_calls) {
        const result = await toolRegistry.execute(
          toolCall.function.name,
          toolCall.function.arguments
        );
        this.messages.push({
          role: "tool",
          tool_call_id: toolCall.id,
          content: result.content
        });
      }
      continue; // Loop back for next response
    }

    // No tool calls = final answer
    return response.content;
  }
}

The LLM doesn't "decide" to use tools in some mysterious way. You send it available tool definitions, and it responds with either a message or a request to call specific tools. You execute those tools, feed the results back, and repeat until it responds without tool calls.

This loop is the entire agent. Everything else is infrastructure around it.

What I Learned About Tool Design

The most interesting challenge was designing tools that are both useful and safe. Early versions had tools that were too granular (read a single line) or too broad (execute arbitrary code). Finding the right level took a few passes.

Tool Confirmation

Potentially dangerous operations need confirmation. But what's "dangerous"? I settled on this heuristic:

No confirmation: Reading files, listing directories, viewing git status
Confirmation required: Writing files, executing shell commands, making commits

interface Tool {
  name: string;
  description: string;

### The Tool Registry Pattern

Rather than hardcoding tools, I built a registry that tools register themselves into:

```typescript
class ToolRegistry {
  private tools: Map<string, Tool> = new Map();

  register(tool: Tool): void {
    this.tools.set(tool.name, tool);
  }

  getDefinitions(): ToolDefinition[] {
    return Array.from(this.tools.values()).map(toolToDefinition);
  }

  async execute(name: string, args: string): Promise<ToolResult> {
    const tool = this.tools.get(name);
    const parsedArgs = JSON.parse(args);
    const validatedArgs = tool.parameters.parse(parsedArgs);
    return await tool.execute(validatedArgs);
  }
}

This pattern made MCP integration trivial. When connecting to an MCP server, I just convert its tools to my format and register them:

const tools = mcpTools.map((mcpTool) => ({
  name: `mcp_${serverName}_${mcpTool.name}`,
  description: mcpTool.description,
  parameters: jsonSchemaToZod(mcpTool.inputSchema),
  execute: async (input) => client.callTool({ name: mcpTool.name, arguments: input }),
  requiresConfirmation: true  // MCP tools are external
}));

toolRegistry.registerMany(tools);

Context Management: The Underrated Challenge

Context windows are measured in tokens, but managing them well requires more than counting. Here's what I learned:

Token Estimation

You can't send requests to the API just to count tokens. You need local estimation:

estimateTokens(text: string): number {
  // Rough approximation: ~4 chars per token for English
  return Math.ceil(text.length / 4);
}

estimateMessageTokens(message: Message): number {
  let tokens = 0;
  if (message.content) tokens += this.estimateTokens(message.content);
  if (message.tool_calls) {
    for (const tc of message.tool_calls) {
      tokens += this.estimateTokens(tc.function.name);
      tokens += this.estimateTokens(tc.function.arguments);
    }
  }
  return tokens + 4;  // Role overhead
}

Smart Truncation

When approaching the limit, you can't just drop the oldest messages. Tool calls and their results must stay together, or the LLM gets confused:

truncateToFit(messages: Message[]): Message[] {
  // Group messages into atomic units
  // User message -> Assistant response -> Tool results
  const messageGroups: Message[][] = [];

  // Keep system prompt, add groups from newest to oldest
  // until we hit the limit
  for (const group of reversedGroups) {
    const groupTokens = group.reduce((sum, msg) =>
      sum + this.estimateMessageTokens(msg), 0);
    if (totalTokens + groupTokens <= availableTokens) {
      toAdd.unshift(...group);
      totalTokens += groupTokens;
    }
  }
}

This was one of those bugs that took hours to track down. The LLM would suddenly start hallucinating tool results because it could see a tool call but not the corresponding result.

Building with Ink: React for the Terminal

Choosing Ink (React for CLIs) was initially just curiosity, but it proved invaluable. Terminal UIs have the same state management challenges as web UIs:

function App() {
  const [messages, setMessages] = useState<DisplayMessage[]>([]);
  const [isThinking, setIsThinking] = useState(false);
  const [streamContent, setStreamContent] = useState('');

  const handleSubmit = async (input: string) => {
    setIsThinking(true);
    await agent.run(input, {
      onStreamChunk: (chunk) => setStreamContent(prev => prev + chunk),
      onToolCall: (name) => setMessages(prev => [...prev, { type: 'tool', name }])
    });
    setIsThinking(false);
  };

  return (
    <Box flexDirection="column">
      {messages.map(msg => <Message key={msg.id} {...msg} />)}
      {isThinking && <ThinkingIndicator />}
      {streamContent && <StreamingResponse content={streamContent} />}
      <Input onSubmit={handleSubmit} />
    </Box>
  );
}

The streaming response visualization was particularly satisfying. Tokens appear as they arrive, giving users immediate feedback that something is happening.

The Memory System: Persistent Context

Sessions persist conversation history, but users also wanted to tell the agent facts it should always remember:

class MemoryManager {
  async add(content: string): Promise<Memory> {
    const memory = {
      id: this.generateId(),
      content: content.trim(),
      createdAt: new Date().toISOString(),
    };
    this.memories.push(memory);
    await this.save();
    return memory;
  }

  async getForPrompt(): Promise<string | null> {
    if (this.memories.length === 0) return null;
    const lines = this.memories.map((m) => `- ${m.content}`);
    return `## Remembered Context\n${lines.join("\n")}`;
  }
}

Memories get injected into the system prompt. Simple, but it transforms the experience. Tell Clarissa once that you prefer TypeScript over JavaScript, and it remembers across every session.

MCP Integration: Extending Without Modifying

The Model Context Protocol was the final piece. Rather than building every possible tool, Clarissa can connect to external MCP servers:

/mcp npx -y @modelcontextprotocol/server-filesystem /path/to/directory

The integration was straightforward once the tool registry pattern was in place. The challenge was converting JSON Schema (what MCP uses) to Zod (what I use internally):

function jsonSchemaToZod(schema: unknown): z.ZodType {
  const s = schema as Record<string, unknown>;

  if (s.type === "object" && s.properties) {
    const shape: Record<string, z.ZodType> = {};
    for (const [key, propSchema] of Object.entries(s.properties)) {
      shape[key] = jsonSchemaToZod(propSchema);
    }
    return z.object(shape);
  }

  if (s.type === "string") return z.string();
  if (s.type === "number") return z.number();
  if (s.type === "boolean") return z.boolean();
  if (s.type === "array") return z.array(jsonSchemaToZod(s.items));

  return z.unknown();
}

Key Learnings

Building Clarissa taught me several things that weren't obvious from using AI tools:

Agents are loops, not magic. The ReAct pattern itself is almost trivial. The complexity lives in the infrastructure around it: streaming, context management, tool safety.

Tool design is UX design. The tools you provide shape what the agent can do. Too few and it's limited. Too many and it gets confused. The sweet spot requires iteration.

Context windows are precious. Even with million-token windows, you can exhaust them quickly. Smart truncation and memory systems extend useful context far beyond raw limits.

Streaming matters. Users hate staring at a blank screen. Showing tokens as they arrive transforms the experience from "is this broken?" to "I can see it thinking."

Confirmation builds trust. Approving dangerous operations prevents mistakes, but it also changes how people interact with the agent. They're more willing to ask for ambitious tasks.

Try It Yourself

Clarissa is open source and available on npm:

bun install -g clarissa
# or
npm install -g clarissa

Set your OpenRouter API key and you're ready to go:

export OPENROUTER_API_KEY=your_key_here
clarissa

The source code is at github.com/cameronrye/clarissa, and the documentation at clarissa.run covers everything from basic usage to MCP integration.

Clarissa taught me more than most projects I've built. If you're curious how AI agents work, build one. The gap between using these tools and understanding them is smaller than it looks.

Retro Floppy: Building an Interactive 3.5" Floppy Disk React Component

c@meron.io (Cameron Rye) — Sun, 23 Nov 2025 00:00:00 GMT

The 3.5-inch floppy disk is still one of the most recognizable icons in personal computing. It held all of 1.44 megabytes, yet those disks carried operating systems and save files people actually cared about. The Retro Floppy component rebuilds that artifact in React, interactive elements and animations included.

Anatomy of a Floppy Disk

Recreating the floppy disk faithfully requires attention to its distinctive features:

The Metal Slider: The spring-loaded cover protecting the magnetic media
The Label Area: Where users wrote cryptic file descriptions
The Write-Protect Tab: That small sliding switch that saved many files
The Hub Ring: The metal center that the drive motor engaged

Each one is something to animate or make interactive.

Component Architecture

The component uses composition to separate visual elements:

interface FloppyDiskProps {
  label?: string;
  color?: string;
  onClick?: () => void;
  isInserted?: boolean;
}

export function FloppyDisk({ 
  label = 'UNTITLED', 
  color = '#1a1a2e',
  onClick,
  isInserted = false 
}: FloppyDiskProps) {
  return (
    <div 
      className={`floppy-disk ${isInserted ? 'inserted' : ''}`}
      style={{ '--disk-color': color } as React.CSSProperties}
      onClick={onClick}
    >
      <MetalSlider />
      <LabelArea text={label} />
      <WriteProtectTab />
      <HubRing />
    </div>
  );
}

CSS custom properties handle color theming without changing the component's structure.

The Metal Slider Animation

The sliding metal cover is the disk's most interactive element:

.metal-slider {
  position: absolute;
  width: 60%;
  height: 30%;
  background: linear-gradient(
    to bottom,
    #c0c0c0 0%,
    #808080 50%,
    #c0c0c0 100%
  );
  transform: translateX(0);
  transition: transform 0.3s cubic-bezier(0.4, 0, 0.2, 1);
  
  .floppy-disk:hover & {
    transform: translateX(30%);
  }
}

The cubic-bezier timing function mimics the spring-loaded action of a real slider.

Realistic Material Rendering

CSS gradients create the plastic texture:

.floppy-disk {
  background: linear-gradient(
    145deg,
    var(--disk-color) 0%,
    color-mix(in srgb, var(--disk-color) 80%, black) 100%
  );
  box-shadow:
    inset 2px 2px 4px rgba(255, 255, 255, 0.1),
    inset -2px -2px 4px rgba(0, 0, 0, 0.2),
    4px 4px 12px rgba(0, 0, 0, 0.3);
}

The combination of gradients and shadows creates depth that suggests the molded plastic of the original.

Label Typography

The label area deserves special attention. Many users remember handwritten labels in various states of legibility:

function LabelArea({ text }: { text: string }) {
  return (
    <div className="label-area">
      <div className="label-text">
        {text}
      </div>
      <div className="label-lines">
        {[...Array(3)].map((_, i) => (
          <div key={i} className="label-line" />
        ))}
      </div>
    </div>
  );
}

.label-area {
  background: #f5f5dc;
  border: 1px solid #ccc;
  padding: 8px;
}

.label-text {
  font-family: 'Courier New', monospace;
  font-size: 12px;
  text-transform: uppercase;
}

.label-lines {
  margin-top: 4px;
  
  .label-line {
    height: 1px;
    background: #ddd;
    margin: 4px 0;
  }
}

The ruled lines evoke office supply aesthetics of the era.

Insertion Animation

Simulating disk insertion adds another layer of interactivity:

@keyframes insert-disk {
  0% {
    transform: translateY(0) rotateX(0);
  }
  50% {
    transform: translateY(20px) rotateX(-5deg);
  }
  100% {
    transform: translateY(80%) rotateX(0);
    opacity: 0.7;
  }
}

.floppy-disk.inserted {
  animation: insert-disk 0.5s ease-in-out forwards;
}

The slight rotation mimics the angle at which disks were typically inserted into drives.

Sound Effects Integration

Audio feedback sells the nostalgia:

function useFloppySounds() {
  const clickSound = useRef(new Audio('/sounds/disk-click.mp3'));
  const insertSound = useRef(new Audio('/sounds/disk-insert.mp3'));
  
  return {
    playClick: () => clickSound.current.play(),
    playInsert: () => insertSound.current.play()
  };
}

The characteristic clicking and whirring of floppy drives remains deeply embedded in the memory of anyone who used them.

Accessibility Considerations

Interactive components must remain accessible:

<div
  className="floppy-disk"
  role="button"
  tabIndex={0}
  aria-label={`Floppy disk labeled ${label}`}
  onKeyDown={(e) => {
    if (e.key === 'Enter' || e.key === ' ') {
      onClick?.();
    }
  }}
>

Keyboard navigation and screen reader support ensure the component works for all users.

Practical Applications

The component finds use in various contexts:

Retro-themed websites: Adding period-appropriate UI elements
Save indicators: Visual feedback for save operations
Portfolio pieces: Showcasing creative CSS and React skills
Educational content: Illustrating computing history

Performance Optimization

Animations should not impact performance:

.floppy-disk {
  will-change: transform;
  transform: translateZ(0);
}

These hints enable GPU acceleration for smooth animations even on less powerful devices.

See the Retro Floppy component in action at cameronrye.github.io/retro-floppy or explore the source code on GitHub.

DosKit: Running DOS Software in Modern Browsers with WebAssembly

c@meron.io (Cameron Rye) — Sun, 16 Nov 2025 00:00:00 GMT

The DOS era produced a lot of software worth keeping around: demos, games, and the productivity apps people ran for years. As the original hardware fails, that software gets harder to run. DosKit is my attempt to keep it runnable in a browser, using WebAssembly to execute the DOS binaries directly.

The Preservation Imperative

Old hardware fails, and modern operating systems drop support for the software that ran on it. Running that software in a browser sidesteps both problems: nothing to install, it works on any platform with a browser, and web standards tend to stick around.

DosKit builds on js-dos, a WebAssembly port of DOSBox. It handles the fiddly parts of emulation setup for you but leaves the configuration exposed when you need to tune things.

WebAssembly: The Enabling Technology

WebAssembly makes browser-based DOS emulation practical by providing near-native execution speed:

async function initializeDosKit(containerElement, programUrl) {
  const bundle = await Dos(containerElement);
  const instance = await bundle.run(programUrl);
  
  return {
    instance,
    sendKey: (key) => instance.sendKeyEvent(key, true),
    setSpeed: (cycles) => instance.setConfig({ cycles })
  };
}

The compiled DOSBox core executes at speeds sufficient for even demanding DOS software, including action games and complex demos.

Cross-Platform Consistency

One of DosKit's primary goals is consistent behavior across platforms:

const platformConfig = {
  mobile: {
    touchControls: true,
    virtualKeyboard: true,
    audioContext: 'user-gesture-required'
  },
  desktop: {
    touchControls: false,
    fullscreenSupport: true,
    keyboardCapture: true
  }
};

function detectPlatform() {
  const isMobile = /Android|iPhone|iPad|iPod/i.test(navigator.userAgent);
  return isMobile ? platformConfig.mobile : platformConfig.desktop;
}

Mobile devices receive touch controls and virtual keyboards, while desktop browsers get full keyboard capture and fullscreen support.

Audio Handling Challenges

Browser audio policies require careful handling. Modern browsers block autoplay, requiring user interaction before audio can begin:

class AudioManager {
  constructor() {
    this.context = null;
    this.initialized = false;
  }
  
  async initialize() {
    if (this.initialized) return;
    
    this.context = new AudioContext();
    if (this.context.state === 'suspended') {
      await this.context.resume();
    }
    this.initialized = true;
  }
}

// Initialize on first user interaction
document.addEventListener('click', () => {
  audioManager.initialize();
}, { once: true });

That keeps audio working without fighting the browser's autoplay rules.

File System Abstraction

DOS programs expect a filesystem. DosKit provides virtual filesystem support:

async function mountFilesystem(instance, files) {
  for (const [path, content] of Object.entries(files)) {
    await instance.fs.writeFile(path, content);
  }
}

// Example: Mount a configuration file
await mountFilesystem(dosInstance, {
  '/CONFIG.SYS': 'FILES=40\nBUFFERS=25',
  '/AUTOEXEC.BAT': '@ECHO OFF\nPATH C:\\;C:\\DOS'
});

Programs can come from a URL, IndexedDB, or a user upload, and the DOS side sees a normal filesystem either way.

Performance Tuning

DOS software varies dramatically in resource requirements. DosKit provides configuration options:

const performanceProfiles = {
  '8086': { cycles: 300, type: 'real' },
  '286': { cycles: 3000, type: 'real' },
  '386': { cycles: 8000, type: 'real' },
  '486': { cycles: 25000, type: 'real' },
  'max': { cycles: 'max', type: 'auto' }
};

function applyPerformanceProfile(instance, profile) {
  const config = performanceProfiles[profile];
  instance.setConfig({
    cycles: config.cycles,
    cycleType: config.type
  });
}

Cycle-accurate emulation ensures software runs at authentic speeds, important for games with timing-dependent mechanics.

Touch Controls for Mobile

Mobile support requires virtual input devices:

class VirtualJoystick {
  constructor(container) {
    this.element = document.createElement('div');
    this.element.className = 'virtual-joystick';
    container.appendChild(this.element);
    
    this.bindTouchEvents();
  }
  
  bindTouchEvents() {
    this.element.addEventListener('touchmove', (e) => {
      const touch = e.touches[0];
      const rect = this.element.getBoundingClientRect();
      const x = (touch.clientX - rect.left) / rect.width;
      const y = (touch.clientY - rect.top) / rect.height;
      
      this.emitDirection(x, y);
    });
  }
  
  emitDirection(x, y) {
    // Convert position to arrow key presses
    if (x < 0.3) this.sendKey('ArrowLeft');
    if (x > 0.7) this.sendKey('ArrowRight');
    if (y < 0.3) this.sendKey('ArrowUp');
    if (y > 0.7) this.sendKey('ArrowDown');
  }
}

These controls make DOS software accessible on devices that never existed during the DOS era.

State Preservation

Save states enable users to pause and resume sessions:

async function saveState(instance) {
  const state = await instance.saveState();
  const blob = new Blob([state], { type: 'application/octet-stream' });
  
  // Store in IndexedDB for persistence
  await stateStorage.save('last-session', blob);
}

async function loadState(instance) {
  const blob = await stateStorage.load('last-session');
  if (blob) {
    const state = await blob.arrayBuffer();
    await instance.loadState(state);
  }
}

Close the tab, come back later, and pick up where you left off.

Conclusion

Old software doesn't have to end up in a museum or rot on dead hardware. WebAssembly is fast enough for faithful emulation, and the rest of the browser platform covers input, audio, and storage. What you get is DOS software you can open and run without hunting down a period-correct PC.

Experience DOS classics at doskit.net or explore the source at github.com/cameronrye/doskit.

Frostpane: A Modern CSS Library for Frosted Glass Effects

c@meron.io (Cameron Rye) — Sat, 08 Nov 2025 00:00:00 GMT

Frosted glass is everywhere in interface design right now: translucent panels, blurred backgrounds, and thin borders that give a layout some depth. Frostpane is my SCSS library for building those effects without fighting performance or browser support every time.

The Anatomy of Frosted Glass Effects

The effect comes from a handful of CSS properties stacked together:

.frost-panel {
  background: rgba(255, 255, 255, 0.15);
  backdrop-filter: blur(10px);
  -webkit-backdrop-filter: blur(10px);
  border: 1px solid rgba(255, 255, 255, 0.2);
  border-radius: 16px;
  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.1);
}

Each property contributes to the effect: the semi-transparent background provides the base layer, backdrop-filter creates the blur on content behind the element, the subtle border adds definition, and the shadow creates depth.

SCSS Architecture for Flexibility

Frostpane combines CSS custom properties with SCSS mixins so the look stays adjustable:

:root {
  --frost-blur: 10px;
  --frost-saturation: 180%;
  --frost-opacity: 0.15;
  --frost-border-opacity: 0.2;
  --frost-radius: 16px;
}

@mixin frost-base($blur: var(--frost-blur)) {
  backdrop-filter: blur($blur) saturate(var(--frost-saturation));
  -webkit-backdrop-filter: blur($blur) saturate(var(--frost-saturation));
  background: rgba(255, 255, 255, var(--frost-opacity));
  border: 1px solid rgba(255, 255, 255, var(--frost-border-opacity));
  border-radius: var(--frost-radius);
}

The custom properties give you runtime theming with sensible defaults. You can override individual values in the browser without recompiling the stylesheet.

Light and Dark Mode Variants

Liquid glass requires different treatments for light and dark backgrounds:

@mixin frost-light {
  @include frost-base;
  background: rgba(255, 255, 255, 0.25);
  border-color: rgba(255, 255, 255, 0.3);
}

@mixin frost-dark {
  @include frost-base;
  background: rgba(0, 0, 0, 0.25);
  border-color: rgba(255, 255, 255, 0.1);
}

@media (prefers-color-scheme: dark) {
  .frost-panel {
    @include frost-dark;
  }
}

The prefers-color-scheme query swaps variants automatically, so the panels match whichever theme the user is running.

Performance Considerations

Backdrop filters can impact rendering performance, particularly on lower-powered devices. Frostpane includes performance-conscious defaults:

@mixin frost-performant {
  @include frost-base;
  
  @media (prefers-reduced-motion: reduce) {
    backdrop-filter: none;
    background: rgba(255, 255, 255, 0.85);
  }
  
  // Fallback for unsupported browsers
  @supports not (backdrop-filter: blur(1px)) {
    background: rgba(255, 255, 255, 0.9);
  }
}

Browsers without backdrop-filter get a solid background, and anyone who has asked for reduced motion drops the blur entirely.

Animation Integration

A little animation sells the effect:

@mixin frost-animated {
  @include frost-base;
  transition: 
    backdrop-filter 0.3s ease,
    background 0.3s ease,
    transform 0.3s ease;
  
  &:hover {
    --frost-blur: 15px;
    --frost-opacity: 0.2;
    transform: translateY(-2px);
  }
}

On hover the blur and opacity ramp up and the panel lifts a couple of pixels, all transitioned rather than snapped.

Highlight Effects

Adding highlights creates the impression of light catching the glass surface:

@mixin frost-highlight {
  @include frost-base;
  position: relative;
  
  &::before {
    content: '';
    position: absolute;
    top: 0;
    left: 0;
    right: 0;
    height: 1px;
    background: linear-gradient(
      90deg,
      transparent,
      rgba(255, 255, 255, 0.4),
      transparent
    );
  }
}

This subtle gradient along the top edge suggests a light source above the element, adding to the three-dimensional illusion.

Browser Compatibility

backdrop-filter has broad support now, but it's still worth handling the browsers that lack it:

.frost-panel {
  // Solid fallback for older browsers
  background: rgba(255, 255, 255, 0.9);
  
  @supports (backdrop-filter: blur(1px)) {
    background: rgba(255, 255, 255, 0.15);
    backdrop-filter: blur(10px);
  }
}

The feature query means older browsers get a solid panel instead of a transparent, unreadable one.

Component Variations

Frostpane includes pre-built component styles for common use cases:

.frost-card {
  @include frost-base;
  padding: 1.5rem;
}

.frost-nav {
  @include frost-base;
  position: fixed;
  top: 0;
  width: 100%;
  z-index: 100;
}

.frost-modal {
  @include frost-base;
  max-width: 500px;
  margin: auto;
}

Treat them as starting points and adjust from there to fit whatever you're building.

Integration Patterns

Dropping it into an existing project is straightforward:

// Import the library
@use 'frostpane' as frost;

// Apply to custom components
.my-sidebar {
  @include frost.frost-base;
  @include frost.frost-highlight;
  width: 280px;
  padding: 1rem;
}

The namespaced @use keeps Frostpane's mixins from colliding with anything else in your styles.

See Frostpane in action at cameronrye.github.io/frostpane or explore the source code on GitHub.

Building ClaytonRye.com for My Father's 77th Birthday

c@meron.io (Cameron Rye) — Wed, 29 Oct 2025 00:00:00 GMT

Today, October 29, 2025, my father Clayton Rye turns 77. To celebrate, I'm launching ClaytonRye.com, a website honoring his life as an award-winning documentary filmmaker, Vietnam War veteran, and Professor Emeritus at Ferris State University.

It's a birthday gift, but really it's a record of his life's work: giving voice to the voiceless, preserving stories that might otherwise be forgotten, and teaching students that filmmaking is both a craft and a moral responsibility.

A Life Worth Documenting

My father's story begins with the war. From 1968 to 1970, he served in the U.S. Army's 1st Airborne Division as a radio operator, reaching the rank of Sergeant First Class. The war left a mark that shaped how he told stories for the next five decades: its complexity, its moral ambiguity, its human cost.

After Vietnam, he studied visual storytelling, earning a BA in Advertising from Michigan State University and an MFA in Cinema from the University of Southern California. Plenty of his classmates chased commercial work. Clayton went toward documentary, toward the stories that mattered and the voices that needed amplifying.

The Documentarian's Mission

Over his career, Clayton made films that stand as historical documents. He wasn't in it for entertainment or profit. The point was to bear witness, to record testimony, to make sure important stories survived for future generations.

Ten Vietnam Vets (1980s)

One of his earliest major works, Ten Vietnam Vets, featured firsthand accounts from fellow veterans. Having served himself, Clayton brought unique credibility and empathy to these interviews. The film won multiple awards including First Place at the Northwest Film Studies Center Festival and a Special Jury Award at the San Francisco International Film Festival. More importantly, it was selected for permanent preservation in the Texas Tech University and LaSalle University Vietnam Archives, so these testimonies would endure.

Jim Crow's Museum (2004)

In collaboration with Dr. David Pilgrim at Ferris State University, Clayton created a documentary exploring the Jim Crow Museum of Racist Memorabilia. The film examines how objects of oppression can become tools for education. Confronting the painful artifacts of racism, it argues, can teach tolerance and promote social justice. The documentary won Best Documentary at multiple festivals and was broadcast on PBS stations nationwide.

Detroit Civil Rights Trilogy (2010)

Perhaps his most significant work, the Detroit Civil Rights Trilogy brought to light three pivotal stories from Michigan's civil rights history:

Last Survivor of the Ford Hunger March: Dave Moore's firsthand account of the 1932 Ford Hunger March at the River Rouge plant, where police opened fire on over 3,000 unemployed workers during the Great Depression, killing five.

Rosa Parks of the Boblo Boat: Sara Elizabeth Haskell's 1945 challenge to segregation in Detroit, a full decade before Rosa Parks' famous bus protest. When she was denied access to the dance floor on the Boblo Island ferry, she fought back and took her case to the Michigan Supreme Court.

Mr. Interlocutor of Mount Clemens: Duane Gerlach's story of performing in blackface minstrel shows and his journey from participant to advocate, examining how these racist performances shaped American culture.

The trilogy won First Place for Documentary Feature at the Made-in-Michigan Film Festival in 2010, but its real value lies in preserving these stories before they were lost forever. Dave Moore was the last living survivor of the Ford Hunger March. Without Clayton's work, his testimony would have died with him.

The Educator's Legacy

In 1988, Clayton joined the faculty at Ferris State University, where he would spend the next 23 years teaching film production, television, and digital media production. Originally hired to teach film production, he adapted as the media landscape evolved, helping students master both traditional filmmaking techniques and emerging digital technologies.

His teaching came down to one belief: media creators have a responsibility to tell truthful, meaningful stories. Every frame, every edit, every story choice carried weight, he told his students. The technical skill was the easy part. What mattered more was listening, researching, and approaching subjects with respect and empathy.

Plenty of his students credit Clayton with teaching them that media can be a force for good. His legacy lives on in his films, and in the work of the filmmakers he mentored over more than two decades.

Building a Digital Legacy

When I started thinking about what to give my father for his 77th birthday, the answer was clear: his work needed to be preserved and made accessible. His documentaries are historical records. His story deserves to be told. And future generations should be able to find his life's work and learn from it: researchers, educators, students, family members.

The Technical Challenge

Building ClaytonRye.com wasn't a typical portfolio site or marketing page. It came with its own constraints, so it needed to be:

Archival: Complete documentation of his filmography
Respectful: Design that honored both the filmmaker and his subjects
Accessible: Fast, responsive, and usable by everyone
Discoverable: Properly structured for search engines and researchers
Enduring: Built to last, not dependent on trendy frameworks or services

I built it on Astro, a static site generator that ships minimal JavaScript and puts content ahead of complexity. The result is fast and accessible, and it should still work years from now.

Design Philosophy

Every design decision followed Clayton's approach to his films: keep it restrained, keep the focus on the stories.

Typography: Playfair Display for headings, a classic serif that carries some weight and dignity. The hierarchy keeps things clear without getting in the way.

Color Palette: A gold accent (#c9a961) adds warmth without pulling attention off the content. It holds up in both light and dark modes.

Layout: Open layouts with generous whitespace. The design stays out of the way of the content.

Performance: Images are responsive and optimized, videos load lazily, and pages come in fast.

Content Organization

The site is organized around five main sections:

Films: Complete filmography with detailed information about each work, awards, distribution, and historical context. Featured presentation of the Detroit Civil Rights Trilogy with embedded trailers and supplementary materials.

About: A full biography covering his path from Vietnam veteran to documentarian: education, career timeline, teaching philosophy, and key collaborations.

Service: Dedicated documentation of his Vietnam War service, including complete service record, historical context, and the connection between his military experience and documentary work.

Writing: Showcase of his written work, including his book Peckerwood and screenplay development.

Videos: A video archive with trailers, full documentaries where available, and supplementary content.

Technical Implementation

The site uses modern web tools while staying simple:

Astro: Static site generation with component islands for interactivity
Custom Backend: Content management and media handling
Theme Switching: Light/dark/system mode with localStorage persistence
Video Integration: Lightweight lite-youtube component for performance
Structured Data: Schema.org markup for discoverability
Responsive Images: Optimized images with modern formats (WebP, AVIF)
Accessibility: WCAG AA compliant with semantic HTML and keyboard navigation

The Stories That Matter

What strikes me most about my father's work is how consistently he went after stories that matter. He never chased commercial success or trendy subjects. He went looking for the forgotten, the marginalized, the voices nobody else was recording.

Dave Moore's testimony about the Ford Hunger March. Sara Elizabeth Haskell's fight against segregation a decade before Rosa Parks. The painful history of blackface minstrel shows. Vietnam veterans' firsthand accounts. The Jim Crow Museum's mission to teach tolerance through confronting intolerance.

These aren't easy stories, and they aren't comfortable. But they're essential, and without documentarians like Clayton Rye, they'd be lost.

Preserving What Matters

Most video today is made for views: algorithmic feeds, engagement metrics, the whole machine. My father's work is a reminder of what documentary can be instead, a tool for education, empathy, and historical preservation. His films don't chase likes. They record testimony and try to do right by the people in them.

Building ClaytonRye.com made me think hard about what actually matters here. It isn't flashy animations or trendy design patterns. It's clear presentation, accessibility, and something that will still be around in twenty years.

The Gift of Time

My father is 77 today. The last survivor of the Ford Hunger March was in his 90s when Clayton interviewed him. Sara Elizabeth Haskell's story might have been lost if not documented. The Vietnam veterans in Ten Vietnam Vets are aging, their numbers dwindling.

Time is the enemy of memory. Stories fade, witnesses die, history gets forgotten or rewritten. Documentary filmmakers like my father push back against that. They preserve and they document, so the stories outlast the people who lived them.

This website is my contribution to that fight. By making his work accessible and properly documented, I'm helping make sure his five decades of storytelling keep teaching people long after any of us are gone.

Happy Birthday, Dad

[!NOTE] A Personal Note Building this website has been one of the most meaningful projects of my career. Not for the technical challenges or the design work, but because it made me sit with the full scope of my father's life. Going through his filmography, watching his documentaries, and writing all of this down left me with a lot of respect and gratitude.

Happy 77th birthday, Dad. Thank you for showing me that technology and creativity can serve purposes beyond profit and entertainment. Thank you for demonstrating that storytelling is a moral responsibility. Thank you for spending five decades giving voice to the voiceless and preserving stories that matter.

This website is my attempt to honor that legacy and ensure your work continues to inspire future generations.

Visit ClaytonRye.com: claytonrye.com

Technical Notes

For anyone curious about how it's built, here are a few of the patterns I used:

Static Site Generation with Astro

Astro fit this project well. The site ships minimal JavaScript, just what theme switching and video embedding need. Content pages are pre-rendered HTML, so they load instantly and work everywhere.

Performance Optimization

A few things keep the site fast and accessible:

Image Optimization: Responsive images with modern formats
Lazy Loading: Videos and below-the-fold images load on-demand
Critical CSS: Inline critical styles for instant rendering
Font Optimization: Efficient web font loading with system font fallbacks
Minimal JavaScript: Only essential interactivity included

Accessibility First

WCAG AA compliance ensures the site is accessible to everyone:

Semantic HTML: Proper heading hierarchy and landmark regions
Keyboard Navigation: Full keyboard accessibility throughout
Screen Reader Support: ARIA labels and descriptive text
Color Contrast: Compliant contrast ratios in both light and dark modes
Focus Management: Clear focus indicators and logical tab order

Structured Data

Schema.org markup handles discoverability:

Person Schema: Detailed biographical information
FAQPage Schema: Common questions about Clayton's work
BreadcrumbList Schema: Clear navigation hierarchy
Optimized Metadata: Proper titles, descriptions, and social sharing

The complete source code and technical details are documented in the ClaytonRye.com project page.

Have stories about Clayton's films or teaching? I'd love to hear them. His work touched many lives, and preserving those connections is part of honoring his legacy.

The Web Audio API: A Cautionary Tale of Ambitious Design and Practical Limitations

c@meron.io (Cameron Rye) — Mon, 20 Oct 2025 00:00:00 GMT

The Web Audio API is one of the most ambitious and controversial additions to the web platform. It was designed to bring professional grade audio processing to browsers, and it promised to run game audio engines and full digital audio workstations (DAWs) entirely in the browser. Nearly a decade after its initial release, it has widespread browser support and some impressive demos to show for it. The story underneath is messier: design compromises, unmet expectations, and an unresolved argument over what audio on the web should be.

The API's troubled history has more to teach than most technical critiques do. It shows how web standards actually get made, what goes wrong when you design by committee, and how far apart audio professionals and working developers can be about what developers actually need.

What Is the Web Audio API?

The Web Audio API is a high-level JavaScript API for processing and synthesizing audio in web applications. Unlike the simple <audio> element designed for basic playback, the Web Audio API provides a sophisticated graph-based system for routing and processing audio.

The API is built around an audio routing graph made up of interconnected nodes:

Source nodes (oscillators, audio buffers, media elements)
Processing nodes (filters, compressors, reverb, analyzers)
Destination nodes (speakers, recording outputs)

According to the specification itself, the API has lofty ambitions: "It is a goal of this specification to include the capabilities found in modern game audio engines as well as some of the mixing, processing, and filtering tasks that are found in modern desktop audio production applications."

That breadth became both the API's main selling point and its central problem.

The Design Philosophy: Everything and the Kitchen Sink

The Web Audio API emerged from work by Chris Rogers at Google, based heavily on Apple's Core Audio framework. The design philosophy was clear: provide a comprehensive set of built-in audio processing nodes that would cover most common use cases without requiring developers to write low-level audio processing code.

The API includes nodes for:

DynamicsCompressorNode - Audio compression
ConvolverNode - Reverb and spatial effects
BiquadFilterNode - Various filter types
WaveShaperNode - Distortion effects
PannerNode - 3D spatial audio
AnalyserNode - Frequency analysis for visualizations

The reasoning seemed sound: JavaScript was too slow for real-time audio processing, and garbage collection would cause audio glitches. By providing these effects as native browser implementations, developers could build sophisticated audio applications without worrying about performance.

But this approach raised an immediate question: Who is this API actually designed for?

The Identity Crisis: Who Needs This?

Jasper St. Pierre, in his incisive 2017 blog post "I don't know who the Web Audio API is designed for," articulated a fundamental problem: the API seems to fall between multiple stools.

Not for Game Developers

Game developers typically use established audio middleware like FMOD or Wwise. These systems provide:

Precisely specified behavior across platforms
Extensive plugin ecosystems
Professional tooling and workflows
Deterministic, well-documented effects

The Web Audio API's built-in nodes, by contrast, are often underspecified. As St. Pierre notes: "Something like the DynamicsCompressorNode is practically a joke: basic features from a real compressor are basically missing, and the behavior that is there is underspecified such that I can't even trust it to sound correct between browsers."

With the advent of WebAssembly, game developers can now compile their existing FMOD or Wwise code to run in the browser. Why would they abandon their proven tools for an underspecified browser API?

Not for Audio Professionals

Professional audio applications require:

Precise control over every parameter
Extensive effect libraries and third-party plugins
Sample-accurate timing
Deterministic behavior for reproducible results

The Web Audio API's canned effects don't come close to meeting these needs. A professional wouldn't use a browser's built-in compressor when they could use industry-standard plugins with decades of refinement.

Not for Simple Use Cases Either

Perhaps most frustratingly, the API also fails developers with simple needs: those who just want to generate and play audio samples programmatically.

St. Pierre provides a telling example. Here's what a simple, hypothetical audio API might look like for playing a 440Hz sine wave:

const frequency = 440;
const stream = window.audio.newStream(1, 44100);
stream.onfillsamples = function(samples) {
    const startTime = stream.currentTime;
    for (var i = 0; i < samples.length; i++) {
        const t = startTime + (i / stream.sampleRate);
        samples[i] = Math.sin(t * frequency) * 0x7FFF;
    }
};
stream.play();

Clean, simple, understandable. But the Web Audio API makes this surprisingly difficult.

The Performance Paradox

The Web Audio API's approach to avoiding JavaScript performance problems created new performance problems of its own.

The ScriptProcessorNode Debacle

The original mechanism for custom audio processing was ScriptProcessorNode. It had several critical flaws:

No resampling support - The sample rate is global to the AudioContext and can't be changed. If your hardware uses 48kHz but you want to generate 44.1kHz audio, you're out of luck.
Main thread execution - Audio processing runs on the main thread, making glitches inevitable when the page is busy.
Deprecated before alternatives existed - ScriptProcessorNode was deprecated in 2014 in favor of "Audio Workers," which were never implemented. They were then replaced by AudioWorklets, which took years to ship.

The BufferSourceNode Garbage Problem

The alternative approach using AudioBufferSourceNode has its own issues. To play continuous audio, you must:

Create a new AudioBuffer for each chunk
Create a new AudioBufferSourceNode for each chunk
Schedule it to play at the right time
Hope the garbage collector doesn't cause glitches

As St. Pierre discovered: "Every 85 milliseconds we are allocating two new GC'd objects." The documentation helpfully states that BufferSourceNodes are "cheap to create" and "will automatically be garbage-collected at an appropriate time."

But as St. Pierre pointedly notes: "I know I'm fighting an uphill battle here, but a GC is not what we need during realtime audio playback."

Floating Point Everything

Another performance issue: the API forces everything into Float32Arrays. While this provides precision, it's slower than integer arithmetic for many operations. As St. Pierre observes: "16 bits is enough for everybody and for an output format it's more than enough. Integer Arithmetic Units are very fast workers and there's no huge reason to shun them out of the equation."

The Road Not Taken: Mozilla's Audio Data API

Robert O'Callahan, a Mozilla engineer who was deeply involved in the Web Audio standardization process, provides crucial historical context in his 2017 post "Some Opinions On The History Of Web Audio."

Mozilla had proposed an alternative: the Audio Data API. It was much simpler:

setup() - Configure the audio stream
currentSampleOffset() - Get current playback position
writeAudio() - Write audio samples

This push-based API was straightforward, supported runtime resampling, and didn't require breaking audio into garbage-collected buffers. It focused on the fundamental primitive: giving developers a way to generate and play audio samples.

Why Did Web Audio Win?

O'Callahan identifies several factors:

Performance concerns - The working group believed JavaScript was too slow for audio processing and GC would cause glitches. (Ironically, the Web Audio API's own design introduced GC issues.)
Audio professional authority - "Audio professionals like Chris Rogers assured me they had identified a set of primitives that would suffice for most use cases. Since most of the Audio WG were audio professionals and I wasn't, I didn't have much defense against 'audio professionals say...' arguments."
Lack of engagement - Apple's participation declined after the initial proposal. Microsoft never engaged meaningfully. Mozilla was largely alone in pushing for changes.
Shipping before standardization - Google and Apple shipped Web Audio with a webkit prefix and evangelized it to developers. Once developers started using it, Mozilla had to implement it for compatibility.

O'Callahan reflects: "What could I have done better? I probably should have reduced the scope of my spec proposal... But I don't think that, or anything else I can think of, would have changed the outcome."

Modern Challenges: WebAssembly Integration

Fast forward to 2025, and WebAssembly has transformed what's possible in browsers. Developers can now compile C++ audio processing code to run at near-native speeds. This should be the perfect complement to Web Audio, right?

Daniel Barta's recent article "Web Audio + WebAssembly: Lessons Learned" reveals that integration remains problematic.

The Worker Problem

AudioContext cannot be used in Web Workers. This is a fundamental limitation that has been marked as an "urgent priority" for over eight years without resolution.

Since WebAssembly instances typically run in workers for performance reasons, this creates an architectural problem. You can't have your WebAssembly audio processing code directly interact with the AudioContext.

No Shared Memory

The Web Audio API doesn't support SharedArrayBuffer for data exchange. This has also been a documented, high-priority issue for over seven years.

Without shared memory, you must copy audio data between threads, introducing exactly the kind of inefficiency the API was supposed to avoid.

Incomplete Tooling

Emscripten provides helper methods for Web Audio, but as Barta discovered, "their implementation is incomplete." The available methods were designed as basic helpers for testing, not production use.

Barta concludes: "A seamless experience seems within reach, and I am optimistic it will soon be realized. With these APIs and Chromium open for contributions, anyone—myself included—can actively participate in addressing these challenges."

That optimism is admirable, but the fact that critical issues have remained unresolved for 7-8 years suggests systemic problems beyond just needing more contributors.

What Went Wrong? Lessons in API Design

The Web Audio API's struggles illuminate several important principles:

1. Beware the "Everything API"

The API tried to be everything: a simple playback system, a game audio engine, and a professional audio workstation. This led to a bloated specification that serves none of these use cases particularly well.

Lesson: Focus on core primitives first. Let higher-level abstractions emerge from the community.

2. Don't Assume You Know What Users Need

The working group assumed developers needed canned audio effects more than they needed simple, efficient sample playback. This assumption proved wrong.

Lesson: Talk to actual developers building real applications, not just audio professionals who understand the domain.

3. Shipping Beats Standardization

Google and Apple shipped Web Audio before the spec was finalized, forcing other browsers to implement it for compatibility. This locked in design decisions before they could be properly evaluated.

Lesson: The "ship it and see" approach can be valuable, but it can also entrench poor designs.

4. The Extensible Web Principle Came Too Late

Shortly after Web Audio was standardized, the "Extensible Web" philosophy became popular: provide low-level primitives and let developers build higher-level abstractions.

Web Audio is the antithesis of this approach. It provides high-level abstractions (DynamicsCompressorNode) without solid low-level primitives (efficient sample generation).

Lesson: Low-level primitives should come first. They're harder to add later.

5. Authority Isn't Always Right

The working group deferred to "audio professionals" who assured them the API would meet developer needs. Those professionals were wrong about what web developers actually needed.

Lesson: Domain expertise is valuable, but it's not a substitute for user research and iterative design.

Current State: Adoption and Usage

Despite its flaws, the Web Audio API has achieved significant adoption:

Universal browser support - All major browsers now implement the API
Impressive demonstrations - Developers have built synthesizers, DAWs, games, and visualizations
Active ecosystem - Libraries like Tone.js provide higher-level abstractions

However, usage patterns suggest most applications use a small subset of the API:

Simple playback with AudioBufferSourceNode
Basic visualization with AnalyserNode
Occasional use of GainNode for volume control

The sophisticated graph routing and built-in effects that drove the API's design are used far less frequently. Most complex audio processing happens in WebAssembly, not through Web Audio nodes.

The Path Forward

What would it take to fix the Web Audio API? Several improvements are needed:

Short Term

Implement AudioWorklet everywhere - This provides efficient, worker-based audio processing
Add SharedArrayBuffer support - Enable zero-copy data sharing
Support AudioContext in workers - Remove the artificial limitation

Long Term

Provide a simple sample playback API - Something like Mozilla's original Audio Data API
Better specify existing nodes - Make behavior consistent across browsers
Embrace WebAssembly - Design for integration with compiled audio code

The Realistic Outlook

The fact that critical issues have remained "urgent priorities" for 7-8 years suggests these fixes may never arrive. The Web Audio API may be locked into its current design indefinitely.

For developers, this means:

Use WebAssembly for complex processing - Don't rely on built-in nodes
Keep it simple - Use the minimal subset of the API you need
Expect inconsistencies - Test across browsers
Consider alternatives - For some use cases, the <audio> element may be sufficient

Conclusion: A Cautionary Tale

The Web Audio API is a cautionary tale about the challenges of designing web standards. It shows what happens when:

Ambitious goals override practical needs
Authority substitutes for user research
Shipping precedes standardization
High-level abstractions come before low-level primitives

It also shows how resilient the web platform is. Despite its flaws, developers have built remarkable things with the Web Audio API. Libraries have emerged to paper over its rough edges, and WebAssembly provides an escape hatch for performance-critical code.

The API's greatest legacy may not be the features it provides, but the lessons it teaches about web standards development. Future API designers would do well to study both its ambitions and its failures.

As Jasper St. Pierre concluded his critique: "Can the ridiculous overeagerness of Web Audio be reversed? Can we bring back a simple 'play audio' API and bring back the performance gains once we see what happens in the wild? I don't know... But I would really, really like to see it happen."

Seven years later, we're still waiting.

Building an Interactive Circle of Fifths: Music Theory Meets Web Audio

c@meron.io (Cameron Rye) — Mon, 13 Oct 2025 00:00:00 GMT

The Circle of Fifths packs a surprising amount of music theory into a simple circular diagram, encoding the harmonic relationships between all twelve keys. I wanted a version you could actually hear, so I built an interactive one that plays audio when you click. That turns a centuries-old teaching tool into something you learn by ear as much as by eye.

The Circle of Fifths: Encoding Harmonic Space

For those unfamiliar with music theory, the Circle of Fifths arranges all twelve musical keys in a circular pattern where each adjacent key differs by a perfect fifth interval. Moving clockwise adds sharps; moving counter-clockwise adds flats. This arrangement reveals fundamental relationships that govern Western harmony.

The circle shows several things at once:

Key Signatures: The number of sharps or flats in each key
Relative Majors and Minors: Major and minor keys that share the same key signature
Chord Progressions: Common harmonic movements map to geometric patterns on the circle
Modulation Paths: Adjacent keys provide the smoothest key changes

Web Audio API: Bringing Theory to Life

The Web Audio API generates musical tones directly in the browser. Unlike pre-recorded samples, synthesized audio can respond dynamically to what the user does:

const audioContext = new AudioContext();

function playNote(frequency, duration = 0.5) {
  const oscillator = audioContext.createOscillator();
  const gainNode = audioContext.createGain();
  
  oscillator.connect(gainNode);
  gainNode.connect(audioContext.destination);
  
  oscillator.frequency.value = frequency;
  oscillator.type = 'sine';
  
  gainNode.gain.setValueAtTime(0.3, audioContext.currentTime);
  gainNode.gain.exponentialRampToValueAtTime(
    0.01, audioContext.currentTime + duration
  );
  
  oscillator.start(audioContext.currentTime);
  oscillator.stop(audioContext.currentTime + duration);
}

Now clicking a key gives immediate audio feedback, so you hear the tonic, dominant, and subdominant relationships that define tonal harmony.

Frequency Calculations and Equal Temperament

Converting musical notes to frequencies requires understanding equal temperament tuning, where each semitone represents a frequency ratio of the twelfth root of two:

const A4_FREQUENCY = 440; // Hz
const SEMITONE_RATIO = Math.pow(2, 1/12);

function noteToFrequency(note, octave) {
  const noteIndex = ['C', 'C#', 'D', 'D#', 'E', 'F', 
                     'F#', 'G', 'G#', 'A', 'A#', 'B'].indexOf(note);
  const semitonesFromA4 = (octave - 4) * 12 + (noteIndex - 9);
  return A4_FREQUENCY * Math.pow(SEMITONE_RATIO, semitonesFromA4);
}

That math keeps the pitches accurate across the whole circle, from C major through all twelve keys.

Interactive Visualization Design

The circular layout requires careful geometric calculations to position elements correctly:

function getKeyPosition(index, radius) {
  const angle = (index * 30 - 90) * (Math.PI / 180);
  return {
    x: radius * Math.cos(angle),
    y: radius * Math.sin(angle)
  };
}

Each key occupies 30 degrees of the circle (360/12), with the -90 degree offset placing C major at the top. The inner ring displays relative minors, maintaining the same angular relationship while using a smaller radius.

Educational Features

The app also does some teaching:

Scale Display: Clicking a key shows all notes in that major or minor scale
Chord Highlighting: Visualize which chords naturally occur in each key
Progression Patterns: Highlight common chord progressions like I-IV-V-I
Audio Playback: Hear scales and chords to connect visual patterns with sound

Responsive Design Considerations

Musical apps have their own responsive-design problems. Touch targets have to work for both precise mouse clicks and finger taps, and the circular layout has to stay legible across screen sizes:

.circle-key {
  min-width: 44px;
  min-height: 44px;
  cursor: pointer;
  transition: transform 0.2s ease;
}

.circle-key:hover,
.circle-key:focus {
  transform: scale(1.1);
}

@media (max-width: 600px) {
  .circle-container {
    transform: scale(0.8);
    transform-origin: center top;
  }
}

Performance Optimization

Audio applications require careful performance management to prevent clicks and latency:

// Pre-warm the audio context on first user interaction
document.addEventListener('click', () => {
  if (audioContext.state === 'suspended') {
    audioContext.resume();
  }
}, { once: true });

Modern browsers suspend the audio context to block autoplay, so this pattern wakes it up on the first click and keeps audio responsive after that.

Extending the Foundation

The same patterns carry over to other music education tools:

Interval Training: Recognizing the sound of fifths, fourths, and other intervals
Chord Quality Recognition: Distinguishing major, minor, diminished, and augmented chords
Sight-Reading Assistance: Connecting key signatures to scale patterns

Seeing the theory and hearing it at the same time sticks better than either one on its own.

Try the interactive Circle of Fifths at cameronrye.github.io/circle-of-fifths or explore the source code on GitHub.

Second Reality: 32 Years of Demoscene Excellence

c@meron.io (Cameron Rye) — Tue, 07 Oct 2025 00:00:00 GMT

Thirty-two years ago today, on October 7, 1993, Future Crew released Second Reality at Assembly '93 in Helsinki, Finland. It won first place in the PC demo competition and changed what people thought was possible on IBM-compatible hardware. For a generation of developers, including me, it was the moment computing stopped being a tool and became an art form.

I still remember the anticipation. The modem's carrier tone. The glacial progress bar as the file downloaded from a local BBS at 14.4 kbps. The nervous excitement of typing SECOND.EXE and hoping my 486 DX2/66 was fast enough. Then the screen exploded with impossible graphics, pulsing to a soundtrack that shouldn't have been possible on PC hardware.

That moment changed everything for me. Today you can see it for yourself, instantly, in the browser, with nothing to download: doskit.net/?app=secondreality

The BBS Era: When Demos Were Treasures

[!NOTE] Historical Context In 1993, the World Wide Web was barely a year old and virtually unknown. The internet as we know it didn't exist for most people. Instead we had BBSes (Bulletin Board Systems): single-computer servers you dialed into with a modem, one user at a time.

The demoscene of the early 1990s lived in a completely different world. There was no YouTube to watch demos. No GitHub to download source code. No Discord servers to discuss techniques. There were BBSes, hundreds of them, each a small island of digital culture reachable only through a direct modem connection.

Finding Second Reality meant:

Discovery: Hearing about it through word-of-mouth, reading about it in a text file, or seeing it mentioned in another demo's credits
Location: Finding a BBS that had it (not guaranteed; many boards had limited storage)
Access: Hoping the BBS wasn't busy (most had 1-4 phone lines maximum)
Download: Waiting hours for the 2.4MB file to transfer, praying the connection didn't drop
Verification: Checking the file wasn't corrupted during transfer
Experience: Finally running it on your hardware, hoping it was compatible

This friction made demos precious. You didn't casually click a link and watch. You invested time, effort, and often money (long-distance phone charges were real). When you finally got Second Reality running, you'd watched that progress bar for hours. You'd earned it.

Technical Achievements That Defined an Era

What made Second Reality legendary wasn't how it looked. It did things people thought were impossible on PC hardware.

The Architecture: Elegant Modularity

When the source code was released in 2013 for the demo's 20th anniversary, the demoscene expected a monolithic mess of assembly code. Instead they found a modular architecture with real software engineering behind it.

The structure was unusual for the time:

The Loader: A minimal 20KB engine that handled initialization and part sequencing
The DIS (Demo Interrupt Server): A custom interrupt handler providing services to all parts
32 Independent Executables: Each visual effect was a self-contained DOS program

This let development run in parallel. Multiple team members could work on different parts at once without conflicts. Each part had a 450KB memory budget and full autonomy within it. When a part finished, the loader overwrote it with the next one. Simple memory management that worked.

The codebase metrics tell the story:

Language                files       code
Assembly                   99     33,350
C++                       121     24,551
C/C++ Header                8        654
Make                       17        294
DOS Batch                  71        253
Total:                    316     59,102

This wasn't assembly hackers pushing hardware limits. It was a team picking the right tool for each job: assembly for performance-critical rendering, C++ for logic and coordination, makefiles for build automation. The codebase was nearly twice the size of the original Doom engine, and it stayed maintainable because the architecture was disciplined.

The Copper Simulator: Amiga Envy Solved

One of Second Reality's best tricks was simulating the Amiga's Copper coprocessor on PC hardware. The Copper was a favorite feature of Amiga computers: a specialized processor that could run programmed instruction streams in sync with the video hardware, which made effects possible that were difficult or impossible on PCs.

Future Crew didn't accept this limitation. They built a Copper simulator using the PC's 8254 Programmable Interval Timer (PIT) and 8259 Programmable Interrupt Controller (PIC). By carefully programming timer interrupts synchronized with VGA vertical retrace, they achieved similar capabilities:

Triggering custom routines at specific scanline positions
Changing palettes mid-frame for color cycling effects
Synchronizing visual effects with music timing
Enabling effects previously thought to require dedicated hardware

That took real systems-level engineering: a deep understanding of PC hardware architecture, interrupt handling, and precise timing control.

Development vs. Production: Seamless Workflow

The attention to developer experience was well ahead of its time. The team built infrastructure that made moving from development to production painless:

Development Mode:

DIS loaded as a TSR (Terminate and Stay Resident) program
Each part ran as an independent executable
Individual testing without running the full demo
Standard DOS file I/O for loading assets

Production Mode:

DIS embedded in the main executable
All parts encrypted and appended to SECOND.EXE
Custom DOS interrupt handlers for file operations
Single 1.45MB executable containing everything

The clever part was that a part didn't need to know which mode it was running in. The same code worked in both. It's the kind of abstraction modern developers take for granted in tools like Docker, and Future Crew built it in 1993 with assembly and C++.

Cultural Impact: From Demoscene to Game Industry

Second Reality's influence reached well beyond the demoscene. Several Future Crew members went on to found Remedy Entertainment, the studio behind Max Payne, Alan Wake, and Control. The same skill and vision that went into Second Reality became the foundation of a major game studio.

This pattern repeated across the industry. The demoscene became a training ground for game developers, graphics programmers, and technical artists. The skills demos demanded (extreme optimization, creative problem-solving under constraints, real-time graphics programming) carried straight over to game development.

The demoscene taught a generation of developers that constraints breed creativity. When you have 450KB for an entire visual effect including code and assets, you learn to be resourceful. When you're targeting a 486 CPU without hardware acceleration, you learn to optimize. When you're competing at Assembly, you learn to push boundaries.

The Spirit of Second Reality in Modern Development

What strikes me most about Second Reality, three decades later, is how much of it still applies:

The part-based system anticipated modern microservices and component-based design: each part was independently testable, deployable, and replaceable. The dev/prod workflow anticipated a lot of what we now call developer experience, because the team understood that good tools let people do good work. The optimization those real-time effects demanded on limited hardware taught lessons that still apply to web performance, mobile development, and embedded systems.

The architecture also let people work in parallel with no source control at all, which teams with Git and CI/CD pipelines can still learn from. And none of it was only technical. The mix of music, visuals, and pacing added up to something you felt, not just something you admired.

From BBS to Browser: DosKit and Instant Access

The contrast between 1993 and 2025 is striking. What once required hours of downloading and specific hardware now runs instantly in any modern browser. That gap is what led me to build DosKit, a tool for making DOS software accessible straight from the browser.

[!TIP] Experience Second Reality Now DosKit gives you instant browser-based access to Second Reality and other classic DOS software. No installation, no configuration. Just click, and you're looking at computing history.

DosKit uses WebAssembly to run a complete DOS environment in your browser. No installation. No configuration. No downloads. Just click:

Try Second Reality now: doskit.net/?app=secondreality

For complete technical details about DosKit's architecture and implementation, see the DosKit project page.

The technical implementation combines several modern web technologies:

js-dos: A DOS emulator compiled to WebAssembly
URL-based configuration: Apps load via query parameters
Instant initialization: Pre-configured DOS environment
Cross-platform compatibility: Works on desktop, mobile, tablets

What took hours in 1993 now takes seconds. The BBS download that required dedication and patience is a single click today. The demo itself is unchanged: the same code, the same effects, the same music that amazed people 32 years ago.

This accessibility matters. Second Reality still works as a lesson in software engineering, graphics programming, and creative problem-solving. Making it easy to reach means new generations can run it, learn from it, and take something from it.

Lessons for Modern Developers

A few of those lessons hold up well past its era:

1. Constraints Drive Innovation

The 486 CPU, VGA graphics, and 450KB memory limit forced creative solutions. We usually have nearly unlimited resources now, but self-imposed constraints can still lead to better design. Try building a feature in half the memory budget. Optimize for slower devices. Limits like that expose waste and push you toward simpler solutions.

2. Architecture Enables Collaboration

The modular part system let developers work independently. Modern microservices and component architectures serve the same purpose. Good architecture isn't about following patterns. It's about letting your team work effectively.

3. Developer Experience Compounds

The smooth dev/prod workflow saved the team a lot of time. Time you put into tooling, build systems, and developer experience keeps paying off over a project's life. The best teams treat developer experience as a first-class concern.

4. Performance Is a Feature

Second Reality's optimization wasn't optional. It was the whole point. Modern web applications often neglect performance and assume fast networks and fast devices. But performance is user experience. Every millisecond matters.

5. Technical Excellence Serves Artistic Vision

Second Reality wasn't only impressive to engineers. It was beautiful, and it stuck with you. The technical work served the art. Modern software should aim for the same union of solid engineering and user experience.

The Enduring Legacy

Thirty-two years later, Second Reality still holds up. Not because the graphics impress (though they're charming), but because the engineering, the problem-solving, and the artistic vision are still worth studying.

The demo represents a moment when a small team in Finland showed the world what was possible with dedication, skill, and creativity. They didn't have the best tools, the fastest hardware, or unlimited resources. They had constraints, talent, and vision.

That combination produced something that outlasted the hardware it ran on, the BBS networks that distributed it, and the era that created it. Second Reality endures because the work was good: technical, artistic, and collaborative.

And now, with tools like DosKit, all of that is more accessible than ever. The hours-long BBS download is a single click. The specific hardware requirements are gone; it just runs in a browser. The treasure you once had to work for is free to anyone curious enough to click a link.

Experience Second Reality today: doskit.net/?app=secondreality

The demo that changed my life as a kid is now just a URL away. That would have looked like science fiction in 1993. Yet here we are, 32 years on, with the past instantly available in the present.

Happy anniversary, Second Reality. Thank you for showing us what's possible.

Further Exploration:

DosKit Project Page - Complete technical documentation and architecture details
DosKit on GitHub - The open-source tool enabling instant DOS software access
Try DosKit Live - Experience the platform with curated DOS software
Second Reality Source Code - Released for the 20th anniversary
Fabien Sanglard's Code Review - Comprehensive technical analysis
Second Reality on Pouët - Demoscene database entry with community comments

Have your own Second Reality memories? I'd love to hear them. The demoscene community thrives on shared experiences and collective nostalgia for an era when computing felt like magic.

The /llms.txt Standard: An Elegant Solution Nobody's Using

c@meron.io (Cameron Rye) — Fri, 12 Sep 2025 00:00:00 GMT

There's something beautifully ironic happening on the web right now. Hundreds of websites have implemented a new standard called /llms.txt, a carefully crafted markdown file designed to help AI systems understand their content. Developers have built tools to generate these files. Community directories catalog implementations. SEO platforms flag sites that don't have one.

There's just one problem: not a single major AI platform actually uses it.

No, really. Not OpenAI. Not Google. Not Anthropic. Not Meta. The very systems that /llms.txt was designed to serve don't even check if the file exists. Server logs confirm it: when AI crawlers visit your website, they sail right past your lovingly crafted llms.txt file without a second glance.

A failed web standard is only part of it. This is also a case study in the power dynamics of the AI era, the difficulty of grassroots standardization, and the growing tension between publishers and the platforms that increasingly control how their content reaches users. The /llms.txt saga says something about who holds power in the AI/web ecosystem, and it isn't the people creating content.

What is /llms.txt?

Photo by Michael Burrows on Pexels

On September 3, 2024, Jeremy Howard, co-founder of fast.ai and creator of the popular nbdev framework, published a proposal for a new web standard. The idea was simple: websites would create a markdown file at /llms.txt that provides AI systems with a curated, structured overview of their content.

The problem Howard identified was real. "Large language models increasingly rely on website information," he wrote, "but face a critical limitation: context windows are too small to handle most websites in their entirety." Converting complex HTML pages (navigation menus, advertisements, JavaScript, formatting) into clean, LLM-friendly text is both difficult and imprecise.

The /llms.txt solution follows a specific structure:

An H1 heading with the project or site name (the only required element)
A blockquote containing a concise summary
Optional detailed information about the project
H2-delimited sections containing markdown lists of links to key resources
An optional "Optional" section for secondary content that can be skipped

Here's a simplified example from the FastHTML project:

# FastHTML

> FastHTML is a python library which brings together Starlette, Uvicorn, 
> HTMX, and fastcore's `FT` "FastTags" into a library for creating 
> server-rendered hypermedia applications.

## Docs

- [FastHTML quick start](https://fastht.ml/docs/tutorials/quickstart_for_web_devs.html.md): 
  A brief overview of many FastHTML features
- [HTMX reference](https://github.com/bigskysoftware/htmx/blob/master/www/content/reference.md): 
  Brief description of all HTMX attributes

## Optional

- [Starlette full documentation](https://example.com/starlette-sml.md): 
  A subset of the Starlette documentation useful for FastHTML development

The proposal also suggested that individual pages offer markdown versions by appending .md to their URLs, so example.com/docs/guide.html would also be available at example.com/docs/guide.html.md.

The Technical Elegance

From a design perspective, /llms.txt is actually quite clever. It follows the established pattern of /robots.txt and /sitemap.xml, simple text files in the root directory that help automated systems understand websites. Markdown is a good choice of format: human-readable, machine-parseable, and already familiar to developers.

The standard strikes a nice balance between structure and flexibility. The required elements ensure consistency, while the open-ended sections allow sites to organize information in ways that make sense for their specific content. The "Optional" section is particularly thoughtful. It acknowledges that LLMs with different context window sizes might need different amounts of information.

An ecosystem quickly emerged around the standard. The Python package llms_txt2ctx provides both a CLI tool and library for parsing llms.txt files and generating LLM-ready context. JavaScript implementations appeared. WordPress plugins and Drupal modules made implementation trivial for non-technical users. Community directories like llmstxt.site and directory.llmstxt.cloud began cataloging implementations.

The proposal even inspired creative extensions. Some projects generate "llms-full.txt" files containing the complete text of all linked documents, creating a single massive file that LLMs with large context windows could consume in one go. Guillaume Laforge, a developer advocate, demonstrated feeding his entire blog (682,000 tokens!) to Google's Gemini using this approach, enabling sophisticated queries across his complete writing history.

The Adoption Reality Check

Photo by David Pupăză on Unsplash

Here's where the story takes a turn. Despite the technical elegance, the growing ecosystem, and hundreds of implementations, /llms.txt faces a fundamental problem: the platforms it was designed for aren't using it.

In July 2025, nearly a year after the proposal's launch, Ahrefs published a blunt analysis: "no major LLM provider currently supports llms.txt. Not OpenAI. Not Anthropic. Not Google." This wasn't speculation. It was based on server log analysis showing that AI crawlers simply don't request llms.txt files when they visit websites.

Google's John Mueller, a Search Relations team member, was even more direct: "none of the AI services have said they're using LLMs.TXT (and you can tell when you look at your server logs that they don't even check for it)." He compared the protocol to the keywords meta tag, a once-popular HTML element that search engines eventually ignored because it was too easily manipulated.

The irony deepens when you look at who's implementing llms.txt. Anthropic, the company behind Claude, publishes its own llms.txt file. But Anthropic doesn't state that its crawlers actually use the standard when visiting other sites. It's the equivalent of putting up a sign in your window while ignoring everyone else's signs.

This has created a strange situation where SEO tools are recommending something that provides no demonstrated benefit. Semrush began flagging missing llms.txt files as site issues, prompting frustrated discussions in marketing forums. "Why should I incentivize people to get everything they need from an AI response and NOT visit their website?" one marketer asked, capturing the deeper tension.

Ryan Law, Director of Content Marketing at Ahrefs, put it succinctly: "llms.txt is a proposed standard. I could also propose a standard (let's call it please-send-me-traffic-robot-overlords.txt), but unless the major LLM providers agree to use it, it's pretty meaningless."

Why Platforms Aren't Adopting It

The non-adoption of /llms.txt isn't random. It reflects fundamental misalignments in incentives and power.

The Traffic Paradox: AI platforms face a basic conflict. Publishers want AI systems to send users to their websites. But platforms like Google, OpenAI, and Anthropic increasingly want to answer questions directly, keeping users within their own interfaces. Google's AI Overviews, for instance, have reduced organic clicks by 34.5% according to recent studies. Why would these platforms adopt a standard that makes it easier to send users away?

Existing Alternatives: From the platforms' perspective, they already have tools for understanding websites. Sitemaps list all pages. Structured data markup (Schema.org) provides semantic information. robots.txt indicates crawling preferences. The platforms have sophisticated systems for extracting and understanding content from HTML. They don't necessarily need publishers to create special markdown files.

Control vs. Cooperation: The /llms.txt proposal assumes a cooperative model where publishers and platforms work together. But the current AI/web ecosystem is increasingly adversarial. According to HUMAN Security, 80% of companies now actively block AI crawlers. Publishers feel their content is being used without fair compensation. Platforms feel entitled to crawl public web content. A voluntary standard requires trust that simply doesn't exist.

The Standardization Chicken-and-Egg: For /llms.txt to succeed, it needs critical mass. But publishers won't invest in creating comprehensive llms.txt files if platforms don't use them. And platforms won't build support for a standard that few sites implement. Without a forcing function such as regulatory requirements or industry consortium agreements, this deadlock persists.

Brett Tabke, CEO of Pubcon and WebmasterWorld, argued that the whole thing is redundant: "XML sitemaps and robots.txt already serve this purpose." From a platform perspective, he might be right.

What This Tells Us About the AI/Web Ecosystem

The /llms.txt story reveals deeper truths about how AI is reshaping the web.

Power Asymmetry: The most obvious lesson is about power. Publishers can propose standards, build tools, and implement files on their servers. But if platforms choose not to participate, none of it matters. This is fundamentally different from earlier web standards like RSS or microformats, which succeeded because they provided value to publishers independent of platform adoption. You could use RSS to syndicate your content whether or not Google Reader existed.

The Illusion of Control: Many publishers are implementing /llms.txt because it feels like taking control in an uncertain moment. "Everyone's scrambling in a dark room where nothing's clearly visible," one SEO practitioner wrote. Creating an llms.txt file is concrete, actionable, and follows best practices. But it's performative: a ritual that provides psychological comfort without functional benefit.

Grassroots vs. Platform-Driven Standards: The web has a history of both grassroots standards (like markdown itself) and platform-driven standards (like AMP). The successful grassroots standards typically solved problems for creators independent of platform adoption. The /llms.txt proposal, despite its grassroots origins, requires platform cooperation to function. It's a grassroots standard whose value depends on the platforms, perhaps an inherently unstable combination.

The Broader Context: This is happening against a backdrop of increasing tension between publishers and AI platforms. AI search visitors convert at 4.4 times higher rates than traditional organic visitors, making AI traffic valuable. But AI Overviews and chatbot answers are reducing the traffic publishers receive. Meanwhile, platforms face their own challenges. Google's AI Overviews have significant spam problems, and the quality of AI-generated answers remains inconsistent.

The /llms.txt saga is a microcosm of these larger conflicts. Publishers want standards that give them agency. Platforms want flexibility to optimize their systems. Users want accurate, helpful answers. These interests don't naturally align.

Future Scenarios: Where Does This Go?

Photo by MICHAEL CHIARA on Unsplash

Looking ahead, several scenarios seem possible:

Scenario 1: Permanent Niche Status The most likely outcome is that /llms.txt remains a niche practice among developer-focused sites and AI enthusiasts. It becomes a signal of technical sophistication rather than a functional standard, similar to how some sites still maintain RSS feeds even though RSS usage has declined. There's no harm in this, but also limited benefit.

Scenario 2: Regulatory or Consortium-Driven Adoption If regulations emerge requiring AI platforms to respect publisher preferences, /llms.txt could become part of the compliance framework. Alternatively, an industry consortium (perhaps involving publishers, platforms, and civil society groups) could negotiate standards for AI/web interaction, with llms.txt as one component. This would require significant external pressure.

Scenario 3: Evolution into Something Else The core ideas behind /llms.txt, structured and curated content for AI systems, might evolve into different implementations. Perhaps platforms develop their own submission systems (like Google Search Console but for AI). Or maybe the approach merges with existing standards like structured data markup. The specific llms.txt format might fade, but the underlying need persists.

Scenario 4: Unexpected Platform Adoption It's possible that a major platform could adopt /llms.txt as a differentiator. A new AI search engine trying to compete with Google might embrace it as a way to build publisher goodwill. Or an existing platform might adopt it in response to competitive pressure or regulatory scrutiny. This seems unlikely but not impossible.

What Would Need to Change? For meaningful adoption, we'd need:

Clear value proposition for platforms (not just publishers)
Incentive alignment or regulatory requirements
Demonstration of superior results compared to existing methods
Critical mass of high-quality implementations
Platform commitment to transparency about usage

None of these seem imminent.

What Should You Actually Do?

If you're a publisher or developer wondering whether to implement /llms.txt, here's a practical framework:

Don't implement it if:

You're doing it solely for SEO benefit (there is none currently)
You're hoping it will increase AI-driven traffic (it won't)
You're resource-constrained and need to prioritize

Consider implementing it if:

You're in the developer tools or technical documentation space where early adopters might manually use it
You want to signal technical sophistication to your audience
You're already creating markdown documentation and it's trivial to add
You're experimenting with AI-assisted documentation systems
You want to be prepared if adoption happens later

Focus instead on:

Creating high-quality, well-structured content
Using existing standards properly (sitemaps, structured data)
Optimizing for how AI systems actually work today
Building direct relationships with your audience
Diversifying traffic sources beyond search and AI

The harsh reality is that AI optimization remains more art than science. Aleyda Solis, a respected SEO expert, released AI search optimization guidelines that focus on content structure, crawlability, and quality. Those fundamentals matter regardless of specific standards.

The Value of the Attempt

Despite its current limitations, the /llms.txt proposal isn't worthless. It represents an important attempt to establish norms for AI/web interaction. It sparked conversations about publisher agency, platform responsibility, and the future of web standards. It demonstrated what a cooperative approach could look like, even if cooperation isn't currently happening.

Jeremy Howard's proposal also highlighted a real problem: the web wasn't designed for AI consumption, and AI systems weren't designed for the web's complexity. That tension won't resolve itself. We need standards, protocols, and norms for this new era. The /llms.txt approach might not be the answer, but asking the question was valuable.

There's also something admirable about the attempt to solve problems through open standards rather than proprietary systems. In an era of increasing platform consolidation, grassroots standardization efforts matter, even when they fail. They remind us that the web's architecture isn't predetermined, that alternatives exist, and that communities can propose different futures.

Conclusion: Lessons from a Standard in Limbo

The /llms.txt story is still being written, but its current chapter offers clear lessons. Technical elegance doesn't guarantee adoption. Grassroots enthusiasm can't overcome platform indifference. Standards that require cooperation struggle in adversarial environments. Power matters more than good ideas.

But perhaps the most important lesson is about the changing nature of the web itself. The era when publishers and platforms had aligned interests, when helping search engines understand your content meant more traffic, is ending. The AI age introduces new dynamics where platforms can extract value from content without sending users to sources. In this environment, voluntary standards face steep challenges.

For now, /llms.txt exists in a strange limbo: implemented but unused, promoted but ineffective, elegant but irrelevant. It's a monument to good intentions in an ecosystem increasingly defined by conflicting interests.

It might succeed, evolve into something else, or fade into obscurity. Either way, the /llms.txt experiment will remain a case study in the challenges of standardization in the AI era. It shows us both the possibilities of cooperative approaches and the harsh realities of power asymmetries.

The web has always been shaped by the tension between openness and control, cooperation and competition, idealism and pragmatism. The /llms.txt standard embodies all these tensions. Its fate will tell us something important about which forces prevail in the AI age.

For now, the elegant solution sits unused, waiting for a problem that the powerful have chosen not to solve.

Further Reading:

AT Protocol MCP Server: Bridging AI and Bluesky's Decentralized Social Network

c@meron.io (Cameron Rye) — Sat, 30 Aug 2025 00:00:00 GMT

I built the AT Protocol MCP Server to let LLMs talk directly to the AT Protocol, the network behind Bluesky and a growing set of other decentralized social apps. It's a Model Context Protocol implementation: an AI client connects to it and gets a set of tools for reading and writing AT Protocol data.

The gap it fills: AI tools have no standard, secure way to read from or write to these networks. AT Protocol is worth the effort because it's built differently from a centralized platform. Your data lives in a repository you control, you can move it between providers, and you pick your own feeds and moderation. That openness is what makes it a natural fit for automated analysis.

How AT Protocol Is Different

AT Protocol isn't federation in the ActivityPub sense, and it isn't a walled-garden platform either. It sits in between, and that middle ground is what makes it worth building against for AI integration.

Architectural Foundations

A few design choices set it apart from other social networking architectures:

Repository-based data model: your data lives in a personal data repository (PDR) that you control, so you can move it between service providers without losing it
Global state: relays aggregate the network into a globally consistent view, which sidesteps the sync problems that federated protocols run into
Algorithmic marketplace: content hosting and content discovery are separate, so you choose your own feed algorithms and moderation policies
Lexicon schema system: extensible schema definitions let the protocol add new record types without breaking backward compatibility or interoperability

For an AI client, that means you can read the social graph and public content freely, without fighting a platform that treats the data as its own.

Design Decisions

Zero-Configuration Public Access

The server works with no authentication at all. That was deliberate: a lot of what people want from AT Protocol is public data, and forcing an auth setup before you can read a single profile is friction nobody needs.

// Public data access requires no configuration
const profile = await mcpClient.callTool('get_user_profile', {
  identifier: 'user.bsky.social'
});

const posts = await mcpClient.callTool('search_posts', {
  query: 'artificial intelligence',
  limit: 20
});

An LLM client can start reading AT Protocol data right away, which keeps prototyping fast and cuts the integration work for the common cases.

Progressive Authentication Model

When you need to write posts or read private data, the server supports two auth methods: app passwords and OAuth.

// App password authentication for development
const authenticatedClient = new ATProtoMCPServer({
  identifier: 'user.bsky.social',
  password: 'app-specific-password'
});

// OAuth flow for production deployments
const oauthClient = await mcpClient.callTool('start_oauth_flow', {
  clientId: process.env.ATPROTO_CLIENT_ID,
  redirectUri: 'https://app.example.com/callback'
});

App passwords are easy for local development; OAuth is the right choice for anything you deploy.

Implementation Notes

Official SDK Integration

It's built on the official @atproto/api SDK, so it stays compliant as the protocol changes and I don't have to hand-roll the wire format:

import { BskyAgent } from '@atproto/api';

export class ATProtoMCPServer {
  private agent: BskyAgent;

  constructor(config: ServerConfig) {
    this.agent = new BskyAgent({
      service: config.service || 'https://bsky.social'
    });
  }

  async searchPosts(params: SearchParams): Promise<SearchResults> {
    const response = await this.agent.app.bsky.feed.searchPosts({
      q: params.query,
      limit: params.limit,
      cursor: params.cursor
    });

    return this.transformSearchResults(response.data);
  }
}

The SDK tracks the spec, and the MCP layer keeps the protocol details behind a small set of tools.

Tool Coverage

The tools cover most of what the protocol can do:

Social Operations: Post creation with rich text formatting, threading, reactions (likes, reposts), and social graph management (follows, blocks, mutes)

Content Discovery: search, custom feed access, timeline retrieval, and thread navigation

Media Handling: Image and video upload with automatic optimization, link preview generation, and rich embed support

Real-time Streaming: WebSocket-based event streams for live notifications, timeline updates, and social graph changes

Moderation Tools: Content and user reporting, muting, blocking, and list management for community curation

Performance

A few things matter once this is running under real load:

Connection pooling: persistent connections to AT Protocol services cut the per-request latency and hold up better under high volume.

Caching: a layered cache, keyed by record type, that follows AT Protocol's cache semantics and skips redundant network requests:

interface CacheStrategy {
  profileCache: LRUCache<string, Profile>;
  postCache: LRUCache<string, Post>;
  feedCache: LRUCache<string, FeedView>;
  ttl: number;
}

Rate limiting: backs off and retries when the service returns a rate-limit error, so you stay under AT Protocol's limits without leaving throughput on the table:

class RateLimiter {
  async executeWithBackoff<T>(
    operation: () => Promise<T>
  ): Promise<T> {
    try {
      return await operation();
    } catch (error) {
      if (this.isRateLimitError(error)) {
        await this.exponentialBackoff();
        return this.executeWithBackoff(operation);
      }
      throw error;
    }
  }
}

Production Deployment Architecture

Infrastructure

The repo ships with what you need to run this in production:

Docker: multi-stage builds that run as a non-root user, which keeps the image small and the attack surface minimal.

Kubernetes: Helm charts and deployment manifests for running it on a cluster.

Observability: Prometheus metrics, structured logging, and health-check endpoints.

Security: input validation, credential sanitization, CORS configuration, and secret management.

Deployment Configuration

# docker-compose.yml
version: '3.8'
services:
  atproto-mcp:
    image: atproto-mcp:latest
    environment:
      - NODE_ENV=production
      - LOG_LEVEL=info
      - ATPROTO_IDENTIFIER=${ATPROTO_IDENTIFIER}
      - ATPROTO_PASSWORD=${ATPROTO_PASSWORD}
    ports:
      - "3000:3000"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

What You Can Build With It

Social Media Analytics and Research

Because AT Protocol data is open, you can run analysis that would be locked away on a closed platform:

// Analyze engagement patterns across custom feeds
const feeds = await mcpClient.callTool('get_custom_feed', {
  feed: 'at://did:plc:example/app.bsky.feed.generator/tech-news'
});

// Track topic evolution and community dynamics
const searchResults = await mcpClient.callTool('search_posts', {
  query: 'machine learning',
  since: '2025-01-01'
});

Content Automation and Management

The write tools cover posting, so you can build content creation and curation workflows on top of them:

// Create rich text posts with mentions and links
await mcpClient.callTool('create_rich_text_post', {
  text: 'Exploring @user.bsky.social insights on AI: https://example.com',
  facets: [
    { type: 'mention', value: 'user.bsky.social' },
    { type: 'link', value: 'https://example.com' }
  ]
});

Community Management and Moderation

The moderation and list tools let you build AI-assisted community management, from muting and blocking to curating lists.

What's Next

A few things I'd like to add as the AT Protocol ecosystem grows:

Graph analysis: tools for mapping community structure and how information moves across the AT Protocol network.

Automation: content scheduling, engagement automation, and AI-driven curation workflows.

Cross-protocol bridges: connectors to other decentralized protocols, so you can manage accounts across platforms from one place.

Lexicon support: picking up new AT Protocol lexicons and record types automatically as the spec adds them.

Wrapping Up

That's the AT Protocol MCP Server: public reads with no setup, authenticated writes when you need them, and enough deployment tooling to run it for real. If you're building AI tools that touch Bluesky or anything else on AT Protocol, it should save you from wiring up the protocol yourself.

The thing I like about decentralized social is that the data is yours to work with. This is my attempt to make that data reachable from an LLM.

Resources:

Project: AT Protocol MCP Server

c@meron.io (Cameron Rye) — Sat, 30 Aug 2025 00:00:00 GMT

import MCPToolDemo from '../../components/demos/MCPToolDemo.tsx'; import { ATPROTO_MCP_TOOLS } from '../../data/lab-experiments';

The AT Protocol MCP Server bridges AI assistants with Bluesky and the decentralized social web. It provides zero-configuration public access for reading, with optional OAuth for authenticated operations.

Key Features

Zero Configuration: Immediate access to public AT Protocol data
Full Protocol Coverage: Posts, profiles, feeds, and social graph
OAuth Support: Secure authentication for write operations
Production Ready: Docker, Kubernetes, and enterprise deployment support

Why this project mattered

AT Protocol is interesting for reasons beyond powering Bluesky: it's decentralized, strongly typed, and split across multiple services with different responsibilities. That gives developers a lot of control, but it's awkward for LLMs and agent frameworks that need a stable interface.

This project turned that complexity into a predictable MCP surface area. Instead of asking an LLM to understand handles, DIDs, AppView reads, PDS writes, and OAuth on its own, the server exposes those capabilities as discoverable tools with clear inputs and outputs.

Architecture decisions

The most important design choice was separating read-only and authenticated operations.

Public tools route through the public AT Protocol APIs so an assistant can explore profiles, feeds, and search results immediately.
Authenticated tools are isolated behind OAuth so write access is explicit and scoped.
The MCP layer keeps protocol vocabulary intact enough for power users, while still normalizing the shape of requests for agent use.

That split makes the project useful in two modes: instant exploration with zero setup, and production workflows where identity and write access matter.

Tradeoffs and implementation lessons

One of the main tradeoffs was how much protocol detail to hide. Abstract too much, and the tool becomes misleading. Expose too much, and the tool stops being ergonomic. I aimed for a middle path: tool names and parameters reflect the underlying network model, but the server handles the plumbing around discovery, authentication, and response shaping.

That approach made it easier to support both hobbyist experimentation and more serious deployment scenarios such as hosted MCP servers, containers, and Kubernetes-based setups.

Outcome

The server is a translation layer, not a wrapper around Bluesky endpoints. It makes a decentralized protocol practical inside AI workflows: reads work with zero setup, writes require explicit OAuth grants, and the tool surface mirrors the protocol's own vocabulary of handles, DIDs, and feeds.

Infrastructure Sovereignty and the Economics of Decentralized Social Protocols

c@meron.io (Cameron Rye) — Fri, 25 Jul 2025 00:00:00 GMT

This analysis builds upon Dan Abramov's excellent explanation of AT Protocol in "Open Social", examining the deeper technical architecture trade-offs and governance implications of decentralized social media infrastructure.

Dan's explanation of AT Protocol's architecture is clear, and it lays out the technical advantages well. The broader discussion around decentralized social protocols raises questions worth examining from a systems architecture perspective, especially the practical side of building global social infrastructure.

The Infrastructure Sovereignty Question

AT Protocol gives you data sovereignty. Users control their repositories and can migrate between hosting providers. But it introduces a subtler dependency: infrastructure sovereignty. The global relay and AppView architecture creates its own kind of lock-in. Users may own their data, but whether that data is actually useful depends entirely on the availability and neutrality of massive aggregation infrastructure.

This is a fundamental trade-off. Email worked as a federated protocol precisely because it doesn't require global state consistency. Social media expects real-time, globally consistent feeds, and that expectation pushes toward centralized aggregation points. AT Protocol's answer is clever, but it necessarily concentrates power in the hands of whoever runs the relays and AppViews.

The comparison to Google Reader is particularly apt. Google provided immense value by aggregating RSS feeds, but when they discontinued the service, the entire ecosystem fragmented. AT Protocol faces similar risks: the protocol may be open, but the practical infrastructure required for global social media operates at a scale that few organizations can sustain.

Economic Sustainability and Governance Models

The economics of operating global social infrastructure are harder than the current discourse tends to admit. Running relays that process millions of events per second, and AppViews that serve billions of queries, takes serious compute and operational expertise. The current model assumes altruistic infrastructure providers, and that assumption gets shaky at scale.

History suggests infrastructure providers eventually go looking for sustainable business models. The ad-driven approach that led to the enshittification of centralized platforms could just as easily show up in the AT Protocol ecosystem. A relay operator facing mounting costs might give paying customers preferential treatment; an AppView might start filtering content to optimize for engagement metrics.

The PLC directory governance model shows the problem. The cryptographic verification gives you technical integrity, but the practical operation of identity resolution is a single point of failure. The planned transition to an independent entity is encouraging. The underlying question remains: how do we keep critical infrastructure neutral and accessible as economic pressure mounts?

Technical Architecture Implications

In distributed-systems terms, AT Protocol essentially picks consistency and partition tolerance over availability, in the CAP sense. The global relay architecture guarantees every participant sees the same state, but it pays for that with massive, always-available infrastructure. That choice ripples out into protocol evolution, caching strategies, and failure modes.

The lexicon system for schema evolution is sophisticated, but it opens the door to fragmentation at the application layer. As schemas evolve and new record types appear, keeping everything interoperable gets harder. The "open union" approach buys flexibility, and it also creates situations where different applications read the same data differently.

Developer experience is another factor. Building on AT Protocol means understanding repositories, DIDs, lexicons, and the relay architecture. That's a lot more to learn than a traditional API integration, and the added complexity may limit adoption among developers who care more about shipping fast than architectural purity.

Practical Adoption Considerations

Network effects loom large for any social protocol. AT Protocol's technical advantages are real, but adoption depends on hitting critical mass in a market where users care about immediate utility, not long-term data portability. Most people don't understand or care about repository ownership until they hit platform lock-in themselves.

The payoff has to be immediate and tangible. Bluesky's success so far comes mostly from being a better product than the alternatives, not from its underlying protocol architecture. That suggests protocol adoption depends more on application quality than technical superiority, which matches how technology adoption usually goes.

Strategic Implications for Open Social Infrastructure

The broader question is whether we can build sustainable, neutral infrastructure for global social communication. AT Protocol is a serious attempt at it, but getting there takes more than good architecture. It needs economic models that actually pay for themselves, governance that holds up under pressure, and broad adoption across a lot of different players.

The comparison to open source infrastructure is useful but incomplete. Open source succeeded partly because the marginal cost of distributing software is close to zero. Social infrastructure needs ongoing operational investment, and it doesn't scale on the same economics.

Maybe the most promising thing about AT Protocol is that it leaves room to experiment with different sustainability models. Different relays and AppViews could try subscriptions, cooperative ownership, or public funding, letting the ecosystem feel its way toward patterns that actually hold up.

Future Considerations

AT Protocol is a thoughtful approach to the core challenges of decentralized social media, but its success depends on solving problems that reach well beyond protocol design. The technical architecture is sound. The economic and governance problems are the ones that will need continued work and careful attention to incentive alignment.

The conversation shouldn't stop at whether AT Protocol is technically superior to the alternatives. The harder question is how we build sustainable, neutral infrastructure for global social communication. That means treating economic sustainability, governance models, and adoption incentives with the same rigor we bring to the technical architecture.

The stakes are real. If we solve these problems, AT Protocol could be the "open social" equivalent of open source infrastructure. If we don't, we risk building new forms of centralization that reproduce the exact problems we set out to solve.

Getting there will take continued experimentation, close attention to the patterns that emerge, and a willingness to revisit architectural decisions as real operational experience comes in. The technical foundation is promising. Whether it succeeds comes down to whether we can line up those technical capabilities with sustainable economic and governance models.

This analysis examines the practical implications of architectural choices in decentralized social protocols and the challenges of building sustainable open infrastructure for global social communication.

Wassette: Microsoft's WebAssembly Runtime for Secure AI Tool Execution

c@meron.io (Cameron Rye) — Wed, 18 Jun 2025 00:00:00 GMT

AI agents can now run external tools and reach into system resources, and the security model most software execution relies on wasn't built for that. Microsoft's Wassette takes a different line. It uses WebAssembly's sandbox to run AI tools in a secure runtime, exposed through the Model Context Protocol (MCP).

Today most MCP servers run with unrestricted system access. Wassette replaces that with a capability-based model, where a tool gets fine-grained control over exactly which resources it can touch without giving up the flexibility that made MCP worth using in the first place.

Understanding Wassette's Architecture

Wassette (pronounced "Wass-ette," a portmanteau of "Wasm" and "Cassette") is an open-source MCP server implementation that runs WebAssembly Components in a secure sandbox environment. Unlike traditional MCP servers that execute as standalone processes with full system privileges, Wassette constrains tool execution within WebAssembly's security boundaries while providing controlled access to system resources through explicit capability grants.

The architecture centers on three core principles:

Sandboxed Execution: Every tool runs within WebAssembly's memory-safe, isolated execution environment, preventing unauthorized access to system resources, memory corruption vulnerabilities, and arbitrary code execution.

Capability-Based Security: Tools must explicitly request and receive permission for specific operations, including file system access, network connections, and environment variable access, following the principle of least privilege.

Component Model Integration: Wassette uses the WebAssembly Component Model (WASM Components) to give tools strongly-typed interfaces and interoperability across languages.

The Security Imperative

Current MCP deployment patterns expose significant attack surfaces. Traditional approaches include:

Direct Binary Execution: Tools run via package managers like npx or uvx with full system privileges
Container Isolation: While providing some boundaries, containers lack fine-grained permission controls
Standalone Processes: MCP servers communicate via stdio or sockets but inherit host process privileges

These patterns create vulnerabilities where a malicious or compromised tool can read arbitrary files, open unauthorized network connections, or run system commands. Wassette closes this off with a zero-trust model: nothing is available until a capability is explicitly granted.

Technical Implementation and Architecture

Wassette is built in Rust on top of the Wasmtime runtime, which gives it a memory-safe, fast foundation for running WebAssembly. A few key pieces:

Core Runtime Components

Wasmtime Integration: Wassette builds on Wasmtime, Mozilla's production-ready WebAssembly runtime, inheriting its security properties and performance optimizations. Wasmtime provides the foundational sandboxing that isolates WebAssembly modules from the host system.

MCP Protocol Bridge: The runtime translates between MCP's JSON-RPC protocol and WebAssembly Component interfaces, so existing MCP clients work unchanged while type safety comes from the Component Model's interface definitions.

Permission Engine: A policy engine manages capability grants and revocations, supporting both static policy files and dynamic permission changes through MCP tools.

Component Model Integration

Wassette's use of the WebAssembly Component Model is a step up from plain WebAssembly modules. Components provide:

Strongly-Typed Interfaces: Tools expose their capabilities through WebAssembly Interface Types (WIT), enabling compile-time verification of interface compatibility and runtime type safety.

Language Agnostic Development: Components can be written in any language that compiles to WebAssembly, including Rust, JavaScript, Python, Go, and C++, while maintaining interface compatibility.

Composability: Components can be composed and linked together, enabling complex tool chains while maintaining isolation boundaries.

Here's an example WIT definition for a simple time server component:

package local:time-server;

world time-server {
    export get-current-time: func() -> string;
    export get-timezone: func() -> string;
    export format-time: func(timestamp: u64, format: string) -> string;
}

This interface definition is completely generic. There's nothing MCP-specific about it. Wassette automatically exposes these functions as MCP tools by introspecting the component's interface.

Security Model and Permission System

Wassette's permission system gives granular control over resource access, split across three resource categories:

File System Access Control

Storage permissions control access to file system resources through URI-based patterns:

permissions:
  storage:
    allow:
      - uri: "fs://workspace/**"
        access: ["read", "write"]
      - uri: "fs://config/app.yaml"
        access: ["read"]
    deny:
      - uri: "fs://system/**"

The permission system supports glob patterns for flexible path matching while maintaining security boundaries. Components can request read-only or read-write access to specific paths, and permissions can be granted or revoked dynamically.

Network Access Management

Network permissions control outbound connections to specific hosts and protocols:

permissions:
  network:
    allow:
      - host: "api.openai.com"
        protocols: ["https"]
      - host: "*.github.com"
        protocols: ["https"]
    deny:
      - host: "localhost"
      - host: "127.0.0.1"

This approach prevents tools from establishing unauthorized connections while enabling legitimate API access. The permission system can restrict access by hostname, IP address, port, and protocol.

Environment Variable Access

Environment variable permissions control access to system configuration:

permissions:
  environment:
    allow:
      - key: "API_KEY"
      - key: "USER_CONFIG_*"
    deny:
      - key: "SYSTEM_*"

Components must explicitly request access to environment variables, preventing unauthorized access to sensitive configuration data.

Practical Implementation Examples

Building a Weather Component

Here's a practical example: a weather component that ties external API access to Wassette's permission system.

First, define the component interface in WIT:

package weather:api;

world weather-server {
    export get-weather: func(location: string) -> result<weather-data, error-info>;
    export get-forecast: func(location: string, days: u32) -> result<forecast-data, error-info>;
}

record weather-data {
    location: string,
    temperature: f32,
    humidity: f32,
    description: string,
    timestamp: u64,
}

record forecast-data {
    location: string,
    days: list<daily-forecast>,
}

record daily-forecast {
    date: string,
    high-temp: f32,
    low-temp: f32,
    description: string,
}

record error-info {
    code: u32,
    message: string,
}

The implementation in Rust would look like:

use weather_api::*;

struct WeatherComponent;

impl Guest for WeatherComponent {
    fn get_weather(location: String) -> Result<WeatherData, ErrorInfo> {
        // Implementation requires network permission for weather API
        let api_key = std::env::var("WEATHER_API_KEY")
            .map_err(|_| ErrorInfo {
                code: 401,
                message: "API key not configured".to_string(),
            })?;

        // Make HTTP request to weather service
        // This requires network permission for the weather API host
        let response = make_weather_request(&location, &api_key)?;

        Ok(WeatherData {
            location,
            temperature: response.temp,
            humidity: response.humidity,
            description: response.description,
            timestamp: current_timestamp(),
        })
    }
}

To use this component, you would need to grant appropriate permissions:

# Load the weather component
wassette load-component oci://ghcr.io/example/weather:latest

# Grant network permission for weather API
wassette grant-network-permission <component-id> api.openweathermap.org

# Grant environment variable access for API key
wassette grant-environment-variable-permission <component-id> WEATHER_API_KEY

File System Operations Component

Here's an example of a component that performs file system operations with appropriate permission controls:

package filesystem:ops;

world filesystem-server {
    export read-file: func(path: string) -> result<string, error-info>;
    export write-file: func(path: string, content: string) -> result<unit, error-info>;
    export list-directory: func(path: string) -> result<list<string>, error-info>;
}

The component would require explicit storage permissions:

# Grant read access to workspace directory
wassette grant-storage-permission <component-id> fs://workspace/** read

# Grant write access to output directory
wassette grant-storage-permission <component-id> fs://output/** write

Performance Characteristics and Optimization

Wassette's performance comes from modern WebAssembly runtimes plus Rust's zero-cost abstractions. The main characteristics:

Memory Efficiency

WebAssembly's linear memory model provides predictable memory usage patterns. Components operate within isolated memory spaces, preventing memory leaks from affecting other components or the host system. Memory overhead is significantly lower than container-based isolation, with typical components requiring only a few megabytes of memory.

Execution Performance

Wasmtime's ahead-of-time compilation and optimization pipeline delivers near-native performance for WebAssembly code. Benchmarks show that well-optimized WebAssembly components can achieve 80-95% of native performance for compute-intensive operations.

Startup Latency

Component instantiation is optimized for low latency, with typical startup times under 10 milliseconds for simple components. This enables responsive tool execution without the overhead associated with container startup or process spawning.

Scalability Characteristics

Wassette's architecture supports horizontal scaling through component isolation. Multiple instances of the same component can run concurrently without interference, and the permission system ensures that resource access remains controlled across all instances.

Integration with MCP Clients

Wassette works with existing MCP clients through a standards-compliant MCP server implementation. Setup varies by client but follows the same pattern:

Visual Studio Code Integration

For VS Code with GitHub Copilot:

# Install Wassette MCP server
code --add-mcp '{"name":"Wassette","command":"wassette","args":["serve","--stdio"]}'

Claude Desktop Integration

Add to Claude's MCP configuration:

{
  "mcpServers": {
    "wassette": {
      "command": "wassette",
      "args": ["serve", "--stdio"]
    }
  }
}

Cursor Integration

Configure in Cursor's settings:

{
  "mcp.servers": {
    "wassette": {
      "command": "wassette serve --stdio"
    }
  }
}

Component Distribution and Registry

Wassette distributes components through OCI (Open Container Initiative) registries, a mechanism most developers already know. Components are packaged as OCI artifacts with cryptographic signatures for integrity verification.

Publishing Components

Components can be published to any OCI-compatible registry:

# Build and publish a component
wasm-tools component new target/wasm32-wasi/release/weather.wasm -o weather.wasm
oras push ghcr.io/username/weather:latest weather.wasm

Component Discovery

Wassette includes a component registry that catalogs available components:

# Search for available components
wassette search-components

# Load a component from the registry
wassette load-component oci://ghcr.io/microsoft/time-server-js:latest

Development Workflow and Tooling

The workflow for building Wassette components is fairly simple:

Language Support

Wassette supports components written in any language that can compile to WebAssembly Components:

Rust: First-class support with cargo component
JavaScript/TypeScript: Via jco (JavaScript Component Tools)
Python: Via componentize-py
Go: Via TinyGo with component model support
C/C++: Via Clang with WASI support

Development Tools

Essential tools for component development:

# Install component development tools
cargo install cargo-component
npm install -g @bytecodealliance/jco
pip install componentize-py

# Create a new Rust component
cargo component new my-tool
cd my-tool
cargo component build

Testing and Debugging

Wassette includes testing and debugging commands:

# Test component locally
wassette test-component ./target/wasm32-wasi/release/my-tool.wasm

# Debug component execution
wassette debug-component <component-id> --verbose

Current Development Status and Roadmap

Wassette is actively developed by Microsoft, with regular releases and community contributions. Where things stand:

Current Status (v0.2.0)

Production Ready: Stable MCP server implementation with comprehensive permission system
Multi-Language Support: Components can be written in Rust, JavaScript, Python, and Go
OCI Integration: Full support for component distribution via OCI registries
Client Compatibility: Works with all major MCP clients including VS Code, Claude, and Cursor

Roadmap and Future Development

Enhanced Security Features: Advanced sandboxing capabilities, formal verification of permission policies, and integration with hardware security modules.

Performance Optimizations: Improved component caching, lazy loading optimizations, and enhanced memory management.

Developer Experience: Integrated development environment support, enhanced debugging tools, and automated component testing frameworks.

Ecosystem Expansion: Broader language support, component composition tools, and marketplace integration for component discovery.

Comparative Analysis with Alternative Solutions

Wassette's approach differs significantly from other MCP deployment strategies:

Container-Based Isolation

Traditional container approaches provide process-level isolation but lack fine-grained permission controls. Containers also incur higher memory overhead and slower startup times compared to WebAssembly components.

Direct Binary Execution

Running MCP servers as native binaries offers maximum performance but provides no security boundaries. This approach is suitable for trusted environments but inappropriate for executing third-party tools.

Centralized WebAssembly Platforms

Some platforms run WebAssembly tools centrally but require custom ABIs and lack interoperability. Wassette's use of the Component Model ensures compatibility across different runtimes and tools.

Conclusion

Wassette's bet is straightforward: run untrusted AI tools inside a WebAssembly sandbox, expose them through MCP, and hand out system access one capability at a time. You get the isolation without giving up the flexibility that made MCP worth using.

The language-agnostic Component Model is the part I find most useful. Existing tools can be recompiled to run in the sandbox, and new ones can treat least privilege as the default rather than something bolted on later.

If you're running third-party MCP tools with full host access today, Wassette is worth a look. That default is the thing worth fixing, and this is a credible way to fix it.

ActivityPub MCP Server: Bridging AI and the Fediverse

c@meron.io (Cameron Rye) — Fri, 02 May 2025 00:00:00 GMT

I built the ActivityPub MCP Server, a Model Context Protocol implementation that lets LLMs like Claude explore and interact with the Fediverse over ActivityPub.

Until now there wasn't a good way for an AI assistant to discover, analyze, and interact with the Fediverse: Mastodon, Pleroma, Misskey, and the other ActivityPub-compatible platforms. This fills that gap.

The Challenge: AI Meets Decentralized Social Networks

The Fediverse runs on open protocols, primarily ActivityPub, instead of a single company's servers. People on different servers and platforms can talk to each other while keeping control of their data and identity.

That decentralization creates a few problems for an AI system:

Discovery: finding relevant actors across thousands of independent instances
Protocol differences: implementations vary in subtle ways
Data access: retrieving distributed social data without hammering servers
Security: talking to untrusted remote servers safely

The server hides that plumbing behind a single interface without giving up what the underlying protocols can do.

Architecture and Design Philosophy

Model Context Protocol Integration

The server implements the complete MCP specification, providing three primary interaction modes:

Resources: Read-only access to Fediverse data with URI-based addressing:

activitypub://remote-actor/{identifier}
activitypub://remote-timeline/{identifier}
activitypub://instance-info/{domain}

Tools: Interactive capabilities for discovery and exploration:

discover-actor: Find and analyze any Fediverse user
fetch-timeline: Retrieve posts from any public timeline
get-instance-info: Analyze server capabilities and statistics
search-instance: Query content across instances
discover-instances: Find servers by topic or category

Prompts: Template-driven exploration patterns:

explore-fediverse: Guided discovery based on interests
compare-instances: Analytical comparison of server communities
discover-content: Topic-based content exploration

WebFinger Discovery Implementation

A WebFinger client handles actor discovery. It runs the resolution that turns a human-readable identifier like user@mastodon.social into an ActivityPub endpoint the code can actually call.

// Simplified WebFinger resolution flow
const actorInfo = await webfingerClient.resolve('user@mastodon.social');
const actorData = await activityPubClient.fetchActor(actorInfo.actorUrl);

The client deals with the cross-domain details:

HTTPS endpoint resolution with fallback mechanisms
CORS handling for browser-based implementations
Rate limiting and respectful server interaction
Error handling for unreachable or misconfigured instances

Technical Implementation Highlights

Performance Optimization Strategies

A few things keep it responsive across a distributed network:

Caching: multiple cache layers that honor ActivityPub cache headers and cut down on repeat network requests:

interface CacheStrategy {
  actorCache: LRUCache<string, Actor>;
  timelineCache: LRUCache<string, OrderedCollection>;
  instanceCache: LRUCache<string, InstanceInfo>;
}

Concurrent requests: independent requests run in parallel, with related ones batched together:

const [actorInfo, timeline, followers] = await Promise.all([
  fetchActor(identifier),
  fetchTimeline(identifier),
  fetchFollowers(identifier)
]);

Resource management: connection pooling and careful memory use so high-volume operations don't fall over.

Security and Privacy Considerations

Security and privacy come from a few layers:

Input validation: every user input and every piece of remote data gets validated before use, which blocks injection and malformed payloads.

Rate limiting: configurable limits that back off based on what a server advertises, so I'm not hammering anyone.

Sanitization: content pulled from remote servers is sanitized to prevent XSS and other content-based attacks.

Read-only by design: the server never stores personal data and never holds a persistent connection to a user account.

Practical Applications and Use Cases

Content Discovery and Analysis

This enables content discovery patterns you can't really do on a centralized platform:

// Discover technology-focused instances
const techInstances = await mcpClient.callTool('discover-instances', {
  topic: 'technology',
  category: 'mastodon',
  size: 'medium'
});

// Analyze community engagement patterns
for (const instance of techInstances) {
  const info = await mcpClient.callTool('get-instance-info', {
    domain: instance.domain
  });
  console.log(`${instance.domain}: ${info.stats.user_count} users`);
}

Cross-Platform Social Research

Researchers and analysts can use the server to study how communities behave across the decentralized web:

Community analysis: compare engagement across instances
Content propagation: track how a post spreads through the Fediverse
Platform diversity: compare the technical and social differences between ActivityPub implementations

AI-Powered Social Discovery

Hooking it up to an LLM means discovery can adapt to what someone's actually interested in:

// AI-guided instance recommendation
const recommendations = await mcpClient.callTool('recommend-instances', {
  interests: ['open source', 'privacy', 'decentralization']
});

Installation and Integration

The server can be installed a few different ways:

Direct Installation

# Install globally for system-wide access
npm install -g activitypub-mcp

# Or use npx for one-time execution
npx activitypub-mcp install

Claude Desktop Integration

To use it with Claude Desktop, add this configuration:

{
  "mcpServers": {
    "activitypub": {
      "command": "npx",
      "args": ["-y", "activitypub-mcp"]
    }
  }
}

Development Integration

The server can be integrated into custom applications through the MCP SDK:

import { MCPClient } from '@modelcontextprotocol/sdk';

const client = new MCPClient({
  serverPath: 'activitypub-mcp'
});

await client.connect();

Future Developments and Roadmap

There's more I want to do here. Planned work:

More protocols: support beyond ActivityPub, like AT Protocol and Nostr.

Analytics: better tools for understanding Fediverse dynamics and community structure.

Posting: secure, user-controlled posting and interaction for AI assistants.

Federation insights: tools for gauging the health and connectivity of the wider network.

Wrap-Up

The server sits between two things I care about: AI assistants and decentralized social networks. Giving an LLM a standard way into the Fediverse opens up social discovery and content analysis without giving up user privacy or platform diversity.

Open protocols and a shared interface are what make this possible. As the Fediverse keeps growing, I think tools like this will matter more for making sense of it.

The source is on GitHub, with docs at cameronrye.github.io/activitypub-mcp. Contributions and feedback are welcome.

The ActivityPub MCP Server is open source under the MIT License. Contributions and feedback are welcome.

Project: ActivityPub MCP Server

c@meron.io (Cameron Rye) — Fri, 02 May 2025 00:00:00 GMT

import MCPToolDemo from '../../components/demos/MCPToolDemo.tsx';

export const activityPubTools = [ { name: 'webfinger', description: 'Discover a user via WebFinger lookup', request: { tool: 'webfinger_lookup', account: '@user@mastodon.social' }, response: { subject: 'acct:user@mastodon.social', links: [{ rel: 'self', type: 'application/activity+json', href: 'https://mastodon.social/users/user' }] } }, { name: 'get_actor', description: 'Fetch an ActivityPub actor profile', request: { tool: 'get_actor', uri: 'https://mastodon.social/users/user' }, response: { type: 'Person', name: 'Example User', preferredUsername: 'user', followers: 1250, following: 340 } }, { name: 'get_outbox', description: 'Get recent posts from an actor', request: { tool: 'get_outbox', actor: 'https://mastodon.social/users/user', limit: 3 }, response: { items: [{ type: 'Note', content: 'Hello Fediverse!', published: '2024-01-20T15:30:00Z' }] } } ];

The ActivityPub MCP Server connects AI assistants to the Fediverse, the decentralized social network that includes Mastodon, Pixelfed, and thousands of other instances. It's built on Fedify, which handles the ActivityPub protocol.

Key Features

Fediverse Access: Connect to any ActivityPub-compatible server
WebFinger Support: Discover users across federated instances
MCP Tools & Prompts: Standardized interface for AI interaction
Fedify Integration: Built on the Fedify framework for reliability

The engineering challenge

ActivityPub is valuable precisely because it is decentralized, but that decentralization creates the core challenge for AI integration. There is no single canonical API surface, implementations vary across servers, and even simple tasks like resolving an account handle require protocol-aware discovery through WebFinger.

The goal of this server was to hide the friction without flattening away the protocol. An assistant should be able to explore the Fediverse as a network of actors, inboxes, outboxes, and objects, not as a brittle collection of server-specific REST calls.

Why Fedify was the right foundation

I built the server on Fedify because correctness mattered more than speed of a one-off integration. Fedify gave me a durable protocol layer for:

WebFinger resolution
ActivityPub actor and object handling
cross-instance compatibility
a cleaner abstraction over the differences between Fediverse implementations

That choice let the MCP layer focus on tool design and response shaping instead of re-implementing protocol details from scratch.

Design tradeoffs

There is a tension between exposing a rich social graph and keeping tool calls understandable for an LLM. I addressed that by making the tools explicit and composable: discover an account, fetch the actor, inspect the outbox, then traverse outward. That produces a better agent experience than trying to hide everything behind one overloaded endpoint.

The other tradeoff was resiliency. In a federated network, partial failure is normal. Different instances may be slow, unavailable, or slightly inconsistent. The server therefore had to prefer graceful degradation and clear error reporting over pretending every node behaves the same way.

Outcome

The hardest constraint turned out to be partial failure. In a federated network some instances are always slow, unreachable, or slightly nonstandard, so the server treats graceful degradation and clear error reporting as core features rather than edge cases. An assistant exploring the Fediverse gets an honest answer about a dead instance instead of a hung request.

Building an Electromagnetic Spectrum Explorer

c@meron.io (Cameron Rye) — Fri, 14 Mar 2025 00:00:00 GMT

I built an interactive explorer for the electromagnetic spectrum. The web stack is ordinary: React and D3. The hard part was fitting a range that runs from femtometers to kilometers onto a single screen without lying about the scale or the physics behind it.

The Educational Challenge of Electromagnetic Radiation

The spectrum is a first-year physics staple, and it's still hard to picture. Wavelengths run from femtometers to kilometers; frequencies run from kilohertz to zettahertz. A textbook diagram flattens all of that into a handful of evenly spaced bands, which hides the logarithmic relationships and says nothing about where any of it turns up in daily life.

So the interface has to stay accurate while still being easy to poke at. Someone using it should walk away with the math linking wavelength, frequency, and energy, plus a feel for where those numbers land in practice, from medical imaging to radio communications.

Scientific Accuracy Requirements

A teaching tool that gets the numbers wrong is worse than none. I used the exact constants NIST publishes and carried their full precision through every calculation:

export const PHYSICS_CONSTANTS = {
  SPEED_OF_LIGHT: 299792458, // m/s (exact)
  PLANCK_CONSTANT: 6.62607015e-34, // J⋅s (exact)
  PLANCK_CONSTANT_EV: 4.135667696e-15, // eV⋅s (exact)
  ELECTRON_VOLT: 1.602176634e-19, // J (exact NIST 2018 value)
};

Every other value in the app is derived from these, so getting them right once keeps the rest of it honest.

Architecture Patterns for Scientific Visualization

Physics Calculation Engine

Every value on screen is derived from a wavelength, which puts the conversion functions at the center of the whole thing. They have to cover the full range without choking on bad input:

export function wavelengthToFrequency(wavelength) {
  if (!isFinite(wavelength) || wavelength <= 0) return NaN;
  return SPEED_OF_LIGHT / wavelength;
}

export function wavelengthToEnergyEV(wavelength) {
  if (!isFinite(wavelength) || wavelength <= 0) return NaN;
  return (PLANCK_CONSTANT_EV * SPEED_OF_LIGHT) / wavelength;
}

Note the guard on the first line of each. A zero or negative wavelength is meaningless, and worse, it produces a plausible-looking wrong number once it flows through a chain of conversions. Returning NaN early kills it at the source.

Logarithmic Scale Visualization

Electromagnetic spectrum visualization requires logarithmic scaling to represent the enormous range of wavelengths and frequencies. The implementation uses D3.js scaling functions combined with custom positioning algorithms:

export function getLogPosition(value, min, max) {
  if (value <= 0 || min <= 0 || max <= 0) return 0;
  const logValue = Math.log10(value);
  const logMin = Math.log10(min);
  const logMax = Math.log10(max);
  return (logValue - logMin) / (logMax - logMin);
}

That normalizes any value to a position between 0 and 1, which is what lets a single bar hold 20+ orders of magnitude, from gamma rays in femtometers to radio waves in kilometers.

Data Architecture for Spectrum Regions

Structured Spectrum Data

Each region of the spectrum is a plain object that carries its own boundaries, a color, and the human-readable content that goes with it:

export const SPECTRUM_REGIONS = [
  {
    id: 'gamma',
    name: 'Gamma Rays',
    color: '#B19CD9',
    wavelengthMin: 1e-15, // 1 fm
    wavelengthMax: 10e-12, // 10 pm
    frequencyMin: 3e19, // 30 EHz
    frequencyMax: 3e23, // 300 ZHz
    energyMin: 124000, // eV (124 keV)
    energyMax: 1e12, // eV (1 TeV)
    description: 'Gamma rays are the most energetic form of electromagnetic radiation.',
    applications: [
      'Cancer treatment (radiotherapy)',
      'Medical imaging (PET scans)',
      'Nuclear medicine'
    ],
    examples: [
      'Cobalt-60 therapy: 1.17 and 1.33 MeV',
      'PET scan tracers: 511 keV'
    ]
  }
  // ... additional regions
];

Keeping the numeric bounds and the descriptive text in one record means a lookup by wavelength hands back the region and everything I need to render its panel. No second join, no separate content file drifting out of sync.

Region Detection Algorithms

Finding the region for a given wavelength is a linear scan behind the same input guard as before:

export function getRegionByWavelength(wavelength) {
  if (!isFinite(wavelength) || wavelength <= 0) {
    return null;
  }

  return SPECTRUM_REGIONS.find(region =>
    wavelength >= region.wavelengthMin && wavelength <= region.wavelengthMax
  ) || null;
}

There are only a handful of regions, so a linear find is plenty. I'd rather keep it obvious than shave microseconds off a loop that runs once per click.

Interactive Conversion Interface Design

Real-time Unit Conversion

The conversion panel has three inputs (wavelength, frequency, energy) that all describe the same photon. Change one and the other two should follow:

function SimpleConversionPanel({ selectedWavelength, onWavelengthChange }) {
  const [wavelengthInput, setWavelengthInput] = useState('');
  const [frequencyInput, setFrequencyInput] = useState('');
  const [energyInput, setEnergyInput] = useState('');

  const handleWavelengthChange = (value) => {
    const wavelength = parseWavelength(value);
    if (!isNaN(wavelength) && wavelength > 0) {
      onWavelengthChange(wavelength);
    }
  };

  // Similar handlers for frequency and energy...
}

The trick is keeping the three in sync without setting off an update loop: wavelength updates frequency, which updates energy, which updates wavelength again. Treating the selected wavelength as the single source of truth and deriving the rest from it avoids that.

Input Parsing and Validation

People type units every way you can imagine, so the parser has to handle unit suffixes and scientific notation:

export function parseWavelength(input) {
  const value = safeParseFloat(input);
  if (isNaN(value)) return NaN;

  const unit = input.toLowerCase().replace(/[0-9.\-+e\s]/g, '');

  switch (unit) {
    case 'nm': return value * 1e-9;
    case 'μm': case 'um': return value * 1e-6;
    case 'mm': return value * 1e-3;
    case 'cm': return value * 1e-2;
    case 'm': return value;
    case 'km': return value * 1e3;
    default: return value; // assume meters if no unit
  }
}

It accepts the common spellings, including both μm and um, and falls back to meters when there's no unit rather than rejecting the input outright.

Educational Interface Patterns

Progressive Disclosure

The educational panel implements progressive disclosure patterns that reveal information based on user interaction and current context:

function SimpleEducationalPanel({ selectedWavelength }) {
  const region = getRegionByWavelength(selectedWavelength);

  if (!region) {
    return <div>Select a wavelength to explore its properties</div>;
  }

  return (
    <div className="educational-panel">
      <h3>{region.name}</h3>
      <p>{region.description}</p>

      <div className="applications">
        <h4>Applications:</h4>
        <ul>
          {region.applications.map((app, index) => (
            <li key={index}>{app}</li>
          ))}
        </ul>
      </div>

      <div className="examples">
        <h4>Real-world Examples:</h4>
        <ul>
          {region.examples.map((example, index) => (
            <li key={index}>{example}</li>
          ))}
        </ul>
      </div>
    </div>
  );
}

The panel only shows what's relevant to the current selection. Pick a wavelength and you get that region's description, applications, and examples. Pick nothing and you get a short prompt instead of an empty box.

Visual Feedback Systems

The spectrum visualization provides immediate visual feedback through color coding, positioning, and scale indicators:

function SimpleSpectrum({ selectedWavelength, onWavelengthChange }) {
  const position = getLogPosition(selectedWavelength, 1e-15, 1e4);
  const region = getRegionByWavelength(selectedWavelength);

  return (
    <div className="spectrum-container">
      <svg width="100%" height="100">
        {SPECTRUM_REGIONS.map(region => (
          <rect
            key={region.id}
            x={getLogPosition(region.wavelengthMin, 1e-15, 1e4) * 100 + '%'}
            width={(getLogPosition(region.wavelengthMax, 1e-15, 1e4) -
                   getLogPosition(region.wavelengthMin, 1e-15, 1e4)) * 100 + '%'}
            height="100%"
            fill={region.color}
            onClick={() => onWavelengthChange(
              (region.wavelengthMin + region.wavelengthMax) / 2
            )}
          />
        ))}

        <line
          x1={position * 100 + '%'}
          x2={position * 100 + '%'}
          y1="0"
          y2="100%"
          stroke="black"
          strokeWidth="2"
        />
      </svg>
    </div>
  );
}

Each region is a colored rectangle placed by its log position, with a vertical line marking the current selection. Clicking a region jumps to its midpoint, which is enough for browsing; the conversion panel is there when you need an exact value.

Testing Strategies for Scientific Applications

Physics Calculation Validation

Tests here check two things at once: that the code runs and that the answer matches the physics. I pin a few known conversions and assert against them within a tolerance:

export function testPhysicsCalculations() {
  const tests = [
    {
      name: 'Visible light wavelength to frequency',
      wavelength: 550e-9, // Green light
      expectedFrequency: 5.45e14, // Hz
      tolerance: 1e12
    },
    {
      name: 'X-ray energy calculation',
      wavelength: 1e-10, // 0.1 nm
      expectedEnergy: 12400, // eV
      tolerance: 100
    }
  ];

  tests.forEach(test => {
    const frequency = wavelengthToFrequency(test.wavelength);
    const energy = wavelengthToEnergyEV(test.wavelength);

    assert(
      Math.abs(frequency - test.expectedFrequency) < test.tolerance,
      `Frequency calculation failed for ${test.name}`
    );
  });
}

Green light at 550 nm should come out near 5.45e14 Hz, and a 0.1 nm X-ray should land around 12400 eV. If either drifts, something in the constants or the math broke, and the test says so before a user ever sees it.

Performance Optimization for Large-Scale Data

Efficient Range Calculations

Showing a wavelength means picking a unit so the number reads cleanly instead of as a wall of exponent. The formatter switches units by magnitude:

export function formatWavelength(wavelength) {
  if (!isFinite(wavelength) || wavelength <= 0) {
    return 'Invalid wavelength';
  }

  if (wavelength >= 1e-3) {
    return wavelength >= 1 ?
      `${wavelength.toExponential(2)} m` :
      `${(wavelength * 1000).toFixed(2)} mm`;
  } else if (wavelength >= 1e-6) {
    return `${(wavelength * 1e6).toFixed(2)} μm`;
  } else if (wavelength >= 1e-9) {
    return `${(wavelength * 1e9).toFixed(2)} nm`;
  } else {
    return `${wavelength.toExponential(2)} m`;
  }
}

Millimeter-scale values read in mm, micron-scale in μm, and nanometer-scale in nm, with exponential notation held back for the extremes.

Deployment and Distribution Patterns

Automated GitHub Pages Deployment

Deployment is a GitHub Actions workflow that builds and pushes to GitHub Pages on every commit to main:

name: Deploy to GitHub Pages
on:
  push:
    branches: [ main ]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Install dependencies
        run: npm install
      - name: Build
        run: npm run build
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

Push to main and the live site updates itself. Nothing to babysit.

Future Directions in Scientific Web Applications

A few things I'd like to add when I get back to it:

Wiring in a physics engine so the visuals can move instead of sitting still.
Shared sessions, so two people can explore and annotate the same view.
Content that adapts to what a learner has already looked at.
Real parity on mobile and VR, not a shrunk-down desktop layout.

None of the groundwork here is exotic. The value was in the discipline: exact constants, log scaling done once and reused, tests that assert physics and not just code paths. That combination carries over to any tool where the numbers have to be right.

Getting Started

Want to explore the electromagnetic spectrum yourself? The application is available at cameronrye.github.io/electromagnetic-spectrum-explorer, and the complete source code can be found at github.com/cameronrye/electromagnetic-spectrum-explorer.

That's the whole thing. The math is exact, the layout is honest about scale, and it all runs in the browser.

The full source, including everything shown here, is on GitHub.

OpenZIM MCP Server: Offline Knowledge for AI Assistants

c@meron.io (Cameron Rye) — Tue, 28 Jan 2025 00:00:00 GMT

Most AI assistants stop being useful the moment they lose internet access. That's a single point of failure, and it shows up in the places where reliability matters most: edge deployments, air-gapped networks, remote sites, anywhere the connection is intermittent or expensive. Offline knowledge access fixes that by letting an assistant keep working regardless of the network.

Connectivity Dependency Analysis

Assuming the network is always there creates real weak points, especially where reliability can't be guaranteed. The cases that come up most:

Aircraft and ships, where connectivity is intermittent, expensive, or restricted by regulation
Remote research stations, field operations, and regions with little infrastructure
Air-gapped networks that block external connectivity for compliance or security
Places where data costs put information out of reach, like many developing markets
Systems that simply have to run without external dependencies

The upside is that a lot of high-value knowledge (encyclopedias, educational material, technical docs) packs down well for offline use, given the right compression and indexing.

OpenZIM Architecture and Compression Technology

The OpenZIM format came out of the Kiwix project, which needed to get educational content to people on slow or nonexistent connections. ZIM files pair heavy compression with a built-in index, so they stay small without giving up fast lookups.

That's how the entire English Wikipedia (articles, metadata, cross-references) fits into a single portable archive you can ship on physical media or pull down over a thin connection.

ZIM Format Technical Advantages

Compression: content-aware algorithms tuned for text push ratios past 10:1
Random access: B-tree indexing gives O(log n) article retrieval without decompressing the whole archive
Metadata: full-text search indices, category hierarchies, and cross-reference graphs travel with the content
Cross-platform: one standardized binary format behaves the same on any OS or hardware

Model Context Protocol Integration Strategy

The Model Context Protocol gives AI systems one consistent interface for talking to outside resources, which turns out to be handy for offline knowledge. Instead of writing a bespoke integration for every data source, you expose it through MCP once and any compatible client can use it.

Here that means an assistant can reach a full knowledge base (encyclopedias, courses, technical docs) with no network at all, and keep working wherever it's deployed.

Building the OpenZIM MCP Server

Performance Engineering Challenges

The hard part is searching a compressed archive of millions of documents and still answering in under a second. It's a classic systems tradeoff: storage efficiency against query speed, inside a memory budget small enough for edge hardware.

The ZIM format solves the indexing half of this problem itself: archives ship with an embedded Xapian full-text index built at creation time, providing fast content location while preserving the storage benefits of compression. The server's job is to expose that index safely through libzim's Python bindings, adding validation, pagination, and caching on top. Condensed from openzim_mcp/zim/search.py, the core search path looks like this:

from libzim.reader import Archive
from libzim.search import Query, Searcher

class _SearchMixin:
    """Full-text search over a ZIM archive's embedded index."""

    def _perform_search(
        self, archive: Archive, query: str, offset: int, limit: int
    ) -> list[dict[str, Any]]:
        searcher = Searcher(archive)
        search = searcher.search(Query().set_query(query))
        total_matches = search.getEstimatedMatches()

        results = []
        for path in search.getResults(offset, min(limit, total_matches)):
            entry = archive.get_entry_by_path(path)
            results.append(
                {
                    "path": path,
                    "title": entry.title,
                    "snippet": self._get_entry_snippet(archive, entry),
                }
            )
        return results

Critical Performance Optimization Strategies

A few patterns did most of the work here:

1. Demand-Driven Resource Loading

Load nothing until someone asks for it. Entry content is never materialized until a client actually requests it: libzim only decompresses the relevant cluster when item.content is accessed, and the result is cached for next time.

def get_zim_entry_data(self, zim_file_path: str, entry_path: str) -> EntryResponse:
    cache_key = f"entry:{zim_file_path}:{entry_path}"
    cached = self.cache.get(cache_key)
    if cached is not None:
        return cached

    with zim_archive(Path(zim_file_path)) as archive:
        entry = archive.get_entry_by_path(entry_path)
        item = entry.get_item()  # cluster decompressed only on access
        content = self.content_processor.process_mime_content(
            bytes(item.content), item.mimetype or ""
        )

    response = build_entry_response(entry, content)
    self.cache.set(cache_key, response)
    return response

(Simplified. The real method also handles redirect chains, content pagination, and a search-based fallback for mismatched entry paths.)

2. Inverted Index Architecture

Because the inverted index ships inside the archive (a Xapian index built when the ZIM file is created), the server never has to build one of its own. It validates that the archive carries a full-text index before searching, and archives without one fall back to a bounded namespace scan rather than failing outright. Title lookups get the same embedded-index treatment through libzim's SuggestionSearcher; the pattern looks like this:

from libzim.suggestion import SuggestionSearcher

def title_suggestions(
    self, archive: Archive, query: str, limit: int
) -> list[str]:
    suggester = SuggestionSearcher(archive)
    suggestions = suggester.suggest(query)
    return list(suggestions.getResults(0, limit))

3. Memory-Mapped I/O Optimization

Let the kernel handle page caching instead of building your own. libzim memory-maps each archive and decompresses content clusters on demand, so the kernel's page cache manages the working set for free. The only knobs the Python layer exposes tune libzim's two internal caches:

# openzim_mcp/zim/archive.py
def configure_libzim_caches(
    cluster_cache_max_size_bytes: Optional[int] = None,
    dirent_cache_max_count: Optional[int] = None,
) -> None:
    """Tune libzim's internal caches.

    The cluster cache (process-global, default 16 MiB) holds
    decompressed content clusters; the dirent cache (per-archive,
    default 512 entries) holds directory entries.
    """

Practical Offline Workflows

Research and Development

Here's how I use the OpenZIM MCP server in my daily workflow:

# AI assistant searching offline Wikipedia
> Search the local Wikipedia for "distributed systems consensus algorithms"

# AI assistant accessing educational content
> Find articles about "rust programming language memory safety" in the offline knowledge base

# AI assistant browsing without internet
> Look up "HTTP/3 protocol specifications" in the local technical documentation

The assistant answers from the local archive, no internet required.

Educational Scenarios

Offline access is especially useful in education:

Classroom environments where internet is restricted or unreliable
Field research where connectivity isn't available
Developing regions where data costs are prohibitive
Security-sensitive environments where external connections aren't allowed

Development in Low-Connectivity Environments

When you're building on a bad connection, having docs and reference material available offline matters a lot:

# Example: AI assistant helping with offline development
def get_documentation(self, topic: str) -> str:
    response = self.zim_ops.search_zim_file_data(self.zim_path, topic, limit=5)

    sections = []
    for result in response["results"]:
        content = self.zim_ops.get_zim_entry(self.zim_path, result["path"])
        sections.append(f"## {result['title']}\n\n{content}")

    return "\n\n".join(sections)

Architecture Patterns for Offline Data Access

Resource-Centric Design

The key insight for offline MCP servers is separating data access from data processing:

from typing import Protocol
from pydantic import BaseModel

class OfflineResource(BaseModel):
    uri: str
    title: str
    description: str | None = None
    content_type: str
    size: int | None = None

class OfflineResourceProvider(Protocol):
    def search_resources(self, query: str) -> list[OfflineResource]: ...
    def get_resource_content(self, uri: str) -> bytes: ...
    def get_resource_metadata(self, uri: str) -> ResourceMetadata: ...

This lets you swap offline data sources (ZIM files, local databases, cached web content) without touching the MCP interface.

Caching Strategy

For offline systems, caching does real work. The cache combines TTL expiry with LRU eviction behind a re-entrant lock, keyed by operation (search_v2b:..., entry:...). Condensed from openzim_mcp/cache.py:

import threading
import time
from typing import Any, Optional

class CacheEntry:
    def __init__(self, value: Any, ttl_seconds: int):
        self.value = value
        self.size_bytes = _approximate_size_bytes(value)
        self.created_at = time.monotonic()
        self.ttl_seconds = ttl_seconds

    def is_expired(self) -> bool:
        return time.monotonic() - self.created_at > self.ttl_seconds

class OpenZimMcpCache:
    def __init__(self, config: CacheConfig):
        self.config = config
        self._cache: dict[str, CacheEntry] = {}
        self._lock = threading.RLock()

    def get(self, key: str) -> Optional[Any]:
        with self._lock:
            entry = self._cache.get(key)
            if entry is None:
                return None
            if entry.is_expired():
                self.delete(key)
                return None
            self._record_access(key)
            return entry.value

    def set(self, key: str, value: Any) -> None:
        with self._lock:
            if len(self._cache) >= self.config.max_size:
                self._evict_lru()
            self._cache[key] = CacheEntry(value, self.config.ttl_seconds)

The full implementation also enforces a byte budget, uses a heap for O(log n) LRU eviction, runs a background cleanup thread for expired entries, and optionally persists the cache to disk across restarts.

Best Practices for Offline MCP Servers

Error Handling for Offline Scenarios

Offline systems have unique error conditions. Each exception carries a machine-readable error code so MCP clients can handle failures programmatically:

class OpenZimMcpError(Exception):
    """Base exception for all OpenZIM MCP-related errors."""

    error_code: str = "OPENZIM_ERROR"

class OpenZimMcpFileNotFoundError(OpenZimMcpError):
    """Raised when a ZIM file is not found."""

    error_code = "OPENZIM_FILE_NOT_FOUND"

class OpenZimMcpArchiveError(OpenZimMcpError):
    """Raised when ZIM archive operations fail."""

    error_code = "OPENZIM_ARCHIVE_ERROR"

class OpenZimMcpTimeoutError(OpenZimMcpError):
    """Base class for timeout-related errors."""

    error_code = "OPENZIM_TIMEOUT"

class ArchiveOpenTimeoutError(OpenZimMcpTimeoutError):
    """Raised when opening a ZIM archive times out."""

    error_code = "OPENZIM_ARCHIVE_OPEN_TIMEOUT"

Configuration for Offline Systems

Offline systems need different configuration considerations. The server uses pydantic-settings models with validated bounds on every field:

from typing import Literal
from pydantic import BaseModel, Field
from pydantic_settings import BaseSettings, SettingsConfigDict

class CacheConfig(BaseModel):
    enabled: bool = True
    max_size: int = Field(default=CACHE.MAX_SIZE, ge=1, le=10000)
    ttl_seconds: int = Field(default=CACHE.TTL_SECONDS, ge=60, le=86400)
    persistence_enabled: bool = Field(default=CACHE.PERSISTENCE_ENABLED)

class OpenZimMcpConfig(BaseSettings):
    model_config = SettingsConfigDict(
        env_prefix="OPENZIM_MCP_", env_nested_delimiter="__"
    )

    allowed_directories: list[str] = Field(default_factory=list)
    cache: CacheConfig = Field(default_factory=CacheConfig)
    tool_mode: Literal["advanced", "simple"] = "simple"
    transport: Literal["stdio", "http", "sse"] = "stdio"

Every field can be overridden through OPENZIM_MCP_-prefixed environment variables, with __ as the nesting delimiter (for example OPENZIM_MCP_CACHE__TTL_SECONDS=600).

Testing Offline Systems

Testing offline systems requires different strategies. With pytest fixtures providing a small test archive, the pattern looks like this:

def test_offline_search(zim_operations, test_zim_path):
    response = zim_operations.search_zim_file_data(
        test_zim_path, "rust programming", limit=10
    )

    assert response["results"]
    assert len(response["results"]) <= 10

def test_cache_behavior(zim_operations, test_zim_path):
    # First access - should hit the ZIM file and populate the cache
    content1 = zim_operations.get_zim_entry(test_zim_path, "A/Rust")

    # Second access - should be served from the cache
    content2 = zim_operations.get_zim_entry(test_zim_path, "A/Rust")

    assert content1 == content2

def test_cache_expiry():
    cache = OpenZimMcpCache(CacheConfig(ttl_seconds=60))
    cache.set("entry:wiki.zim:A/Rust", "<content>")

    assert cache.get("entry:wiki.zim:A/Rust") == "<content>"
    assert cache.get("entry:wiki.zim:A/Missing") is None

The Future of Offline AI

Building openzim-mcp got me thinking about how far offline AI can go. An assistant shouldn't only be smart when it's connected. It should stay useful when the internet is gone.

A few directions I want to take this:

Hybrid online/offline: switch between online and offline sources depending on what's available
Incremental updates: refresh an offline knowledge base without rebuilding it from scratch
Specialized domains: build ZIM files for specific technical fields or industries
Local networks: share knowledge bases across a LAN with no internet

Getting Started with Offline Knowledge

Want to try the OpenZIM MCP server yourself? Here's how to get started:

# Install the server
uv tool install openzim-mcp
# or: pip install openzim-mcp

# Download a ZIM file (example: Simple English Wikipedia)
wget https://download.kiwix.org/zim/wikipedia/wikipedia_en_simple_all.zim

# Point the server at your ZIM directory
openzim-mcp /path/to/zim/files

# Configure your AI assistant to use the offline knowledge base
# (specific steps depend on your MCP client)

# Start exploring offline knowledge
# Try searching for topics you're interested in

There's a lot out there already. You'll find ZIM files for Wikipedia in dozens of languages, plus educational content, technical documentation, and specialized knowledge bases.

Architectural Insights and Design Principles

Offline access turned out to beat the network on more than availability. A curated, high-quality knowledge base often gives more focused, relevant answers than a general web search, and there's no latency or flaky connection to fight.

The problems I ran into (search optimization, caching, memory management) taught me a lot about designing for data access. Tight constraints tend to produce better solutions than open-ended ones. They force you to decide what actually matters and cut the rest.

Want to dig in? The project documentation and the GitHub repository have the full implementation and more examples.

Building a Gopher MCP Server: Bringing 1991's Internet to Modern AI

c@meron.io (Cameron Rye) — Tue, 12 Nov 2024 00:00:00 GMT

I wired Gopher, a protocol from 1991, into an MCP server so AI assistants can read it. Doing that turned out to be a decent lesson in system design. Protocols built on minimalist principles tend to be simpler to run and quicker on the wire than the modern equivalents, and that tradeoff still holds up for distributed systems today.

Historical Context and Protocol Evolution

Gopher showed up early, before the web had won. Instead of hypertext, it organized information into a strict hierarchy: menus of menus, with files at the leaves. It came out of the University of Minnesota, led by Mark McCahill, as a straightforward client-server design built around structured navigation rather than free-form linking.

Through the early 1990s it caught on across universities and research institutions, and for a while it beat the early web on both speed and ease of use. The design leaned on predictable navigation and almost no protocol overhead, which is exactly what you wanted on the slow, bandwidth-starved links of the day.

Protocol Competition and Market Dynamics

HTTP and HTML won anyway, and mostly for reasons that had little to do with technical merit. A few things mattered more:

Licensing: The University of Minnesota's intellectual property stance was ambiguous, and that uncertainty scared off commercial developers.
Media: Gopher was built for text. The commercial internet wanted images, then everything else, and HTML could carry it.
Flexibility: HTTP is stateless and document-oriented, which made dynamic content easy in a way Gopher's fixed hierarchy never did.

It's hard to look at Gopher now without thinking about what the modern web struggles with: page bloat, heavy client-side code, and constant distraction. A lot of what we now call web performance best practice is just Gopher's minimalism arrived at the long way around.

Contemporary Gopher Protocol Revival

Gopher has quietly come back, part of a wider pull toward minimalist computing. The reasons people give tend to be the same handful:

No presentation layer: There's no styling, no layout, no scripts. Just the content.
Tiny on the wire: With almost no protocol features or metadata to send, there's very little overhead.
Trivial to implement: The spec is short enough that you can write a client in an afternoon, and a small surface is a small attack surface.
Easy to navigate: The rigid menu structure means fewer decisions and less to get lost in.

That's what makes it a good fit for MCP. An AI assistant wants clean, structured information, not the noise that comes with most of the modern web. Gopher hands it exactly that.

Model Context Protocol Integration Architecture

MCP sits between an AI model and whatever external resources it needs, and it does so through a capability-based permission model. The model only touches what it's been granted, which is the whole point: let an assistant reach outside itself without handing it the keys to everything.

Explicit permissions and resource isolation are a natural match for how small and constrained Gopher already is. Put the two together and an assistant can read curated, high-quality sources without dragging in the security and complexity of a full web browser.

Building the Gopher MCP Server

Protocol Abstraction Layer

The main design decision in gopher-mcp was to handle a family of related protocols through one abstraction. Gopher and Gemini differ in the details, but they share the same basic interaction model. That overlap is worth factoring out, as long as each protocol keeps room for its own quirks:

class GopherClient(TTLCacheMixin[GopherFetchResponse]):
    """Async client for the Gopher protocol."""

    async def fetch(self, url: str) -> GopherFetchResponse:
        parsed = parse_gopher_url(url)
        ...


class GeminiClient(TTLCacheMixin[GeminiFetchResponse]):
    """Async client for the Gemini protocol (TLS, TOFU certificates)."""

    async def fetch(self, url: str) -> GeminiFetchResponse:
        ...

This is the Strategy pattern, and it earns its keep here. Both clients expose the same async fetch surface and inherit caching from a shared TTLCacheMixin. Adding a protocol means implementing that interface, not editing the core, so I can grow what the server supports without touching the parts that already work.

Gopher Protocol Implementation

The Gopher protocol is refreshingly simple. Here's how a basic client works:

import asyncio


async def fetch_gopher(
    host: str, port: int, selector: str, *, max_bytes: int, timeout: float
) -> bytes:
    """Send a Gopher request and return the raw response bytes."""

    async def _io() -> bytes:
        reader, writer = await asyncio.open_connection(host, port)
        try:
            # Send Gopher request (just the selector + CRLF)
            writer.write(selector.encode("utf-8") + b"\r\n")
            await writer.drain()

            # Read the response in chunks, enforcing the size cap
            chunks: list[bytes] = []
            total = 0
            while chunk := await reader.read(65536):
                total += len(chunk)
                if total > max_bytes:
                    raise GopherProtocolError(
                        f"Response exceeds maximum size of {max_bytes} bytes"
                    )
                chunks.append(chunk)
            return b"".join(chunks)
        finally:
            writer.close()
            await writer.wait_closed()

    return await asyncio.wait_for(_io(), timeout=timeout)

That's the whole protocol: send a selector, read bytes back. No status codes, no headers, no content negotiation. Less to implement, less to send, and less that can go wrong on a slow connection.

Content Type Detection

Gopher uses a simple but effective type system that predates MIME types:

_GOPHER_TYPE_CATEGORY: dict[str, str] = {
    "0": "text",    # Text file
    "1": "menu",    # Directory listing
    "7": "menu",    # Search server
    "9": "binary",  # Binary file
    "g": "binary",  # GIF image
    "I": "binary",  # Image file
    "h": "text",    # HTML document
    # ... more types
}


def gopher_type_category(gopher_type: str) -> str:
    """Return the handling category for a Gopher item type.

    One of "menu", "text", "binary" or "interactive". Unknown
    types default to "text", matching historical behaviour.
    """
    return _GOPHER_TYPE_CATEGORY.get(gopher_type, "text")

Practical Applications

Research and Documentation

The use case I keep coming back to is research. A lot of Gopher servers host high-quality, curated content:

Academic papers: Many universities maintain Gopher archives
Technical documentation: Clean, distraction-free technical docs
Historical archives: Digital libraries and historical collections

When your AI assistant can browse these resources, it's accessing information that's often more reliable and better curated than random web pages.

Development Workflows

Here's a practical example of how I use the Gopher MCP server in my development workflow:

# AI assistant browsing Gopher for technical documentation
> Browse gopher://gopher.floodgap.com/1/world for information about protocol specifications

# AI assistant accessing university research archives
> Search gopher://gopher.umn.edu/ for papers on distributed systems

# AI assistant exploring historical computing resources
> Navigate to gopher://sdf.org/1/users/cat/gopher-history for protocol history

The AI gets clean, focused content without the noise of modern web advertising and tracking.

Architecture Patterns for Protocol Servers

Resource-Centric Design

Building a protocol MCP server taught me the importance of separating concerns:

class MenuResult(BaseModel):
    kind: Literal["menu"] = "menu"
    items: list[GopherMenuItem]
    truncated: bool = False
    request_info: dict[str, Any]


class BinaryResult(BaseModel):
    kind: Literal["binary"] = "binary"
    bytes: int
    mime_type: str | None
    note: str  # binary payloads are described, not returned
    request_info: dict[str, Any]


GopherFetchResponse = MenuResult | TextResult | BinaryResult | ErrorResult

This pattern lets you swap protocol implementations without touching the MCP logic. Want to add Finger? Define its result models and a client that returns them. The MCP layer just serializes whatever comes back.

Async-First Architecture

Protocol servers need to handle multiple concurrent requests efficiently:

class GopherClient(TTLCacheMixin[GopherFetchResponse]):
    async def fetch(self, url: str) -> GopherFetchResponse:
        parsed = parse_gopher_url(url)
        self._validate_security(parsed)

        # Check cache first (TTL expiry, LRU touch)
        if self.cache_enabled:
            cached = self._get_cached_response(url)
            if cached is not None:
                return cached

        # Fetch, bounded by an asyncio.Semaphore when a
        # concurrency cap is configured
        response = await self._bounded_fetch(parsed)

        # Cache non-error responses; the mixin evicts the least
        # recently used entry once max_cache_entries is reached
        if self.cache_enabled and not isinstance(response, ErrorResult):
            self._cache_response(url, response)

        return response

Because everything runs on a single asyncio event loop, the cache is just an OrderedDict with TTL timestamps. No locks required. Concurrency is bounded where it actually matters, at the sockets.

Best Practices for Protocol MCP Servers

Error Handling

Handle errors with context:

class GopherProtocolError(Exception):
    """Raised when a Gopher request cannot be completed."""


class SSRFError(ValueError):
    """Raised when a target host/address is blocked by the SSRF policy."""


class ErrorResult(BaseModel):
    kind: Literal["error"] = "error"
    error: dict[str, str]
    request_info: dict[str, Any]

The client catches SSRFError, GopherProtocolError, and unexpected exceptions at the fetch boundary and converts them into an ErrorResult, so failures surface as structured data the model can reason about rather than an unhandled exception.

Configuration Management

Keep configuration simple but flexible:

from pydantic_settings import BaseSettings, SettingsConfigDict


class GopherConfig(BaseSettings):
    """Gopher client settings, read from GOPHER_* environment variables."""

    model_config = SettingsConfigDict(env_prefix="GOPHER_")

    max_response_size: int = 1024 * 1024  # 1MB
    timeout_seconds: float = 30.0
    cache_ttl_seconds: int = 300  # 5 minutes
    max_cache_entries: int = 1000
    allow_local_hosts: bool = False  # SSRF guard stays on by default

The Future of Alternative Protocols in AI

Building the Gopher MCP server opened my eyes to something interesting: there's a whole ecosystem of alternative protocols that could benefit AI assistants:

Gemini: Gopher's modern successor with TLS and markdown support
Finger: Simple user information protocol
NNTP: Network News Transfer Protocol for accessing Usenet
IRC: Real-time chat protocol integration

Each takes a different angle on sharing information, and each could be worth exposing to an assistant.

Architectural Insights and Design Principles

Building gopher-mcp made the link between protocol complexity and reliability concrete for me. Gopher puts content ahead of presentation, and that happens to be what an AI wants too: give it structured data, skip the multimedia.

Its simplicity also makes it a good place to learn MCP server patterns. With so little protocol to fight, you can concentrate on the parts that actually recur: resource management, caching, and error handling, without drowning in protocol-specific edge cases.

Getting Started

Want to try the Gopher MCP server yourself? Here's how to get started:

# Run the server directly with uv
uvx gopher-mcp

# Or install it with pip
pip install gopher-mcp

# Configure your AI assistant to use it
# (specific steps depend on your MCP client)

# Start exploring Gopher space
# Try gopher://gopher.floodgap.com/ for a good starting point

The Gopher internet is small but surprisingly rich. There's technical documentation, there's poetry, and it all shows up in the same clean, text-first format. After a while, reading it feels like a relief.

Interested in exploring more? Visit the project documentation or check out the GitHub repository for complete implementation details and examples.

Building Model Context Protocol Servers: A Deep Dive

c@meron.io (Cameron Rye) — Thu, 05 Sep 2024 00:00:00 GMT

I've spent more than a decade building distributed systems, and the Model Context Protocol is the first thing in a while that's changed how I think about connecting AI models to the outside world. I've built production MCP servers including gopher-mcp and openzim-mcp, and along the way I landed on a handful of patterns worth writing down.

Update (June 2025): I've split this guide into two shorter articles:

Gopher MCP Server: Bringing 1991's Internet to Modern AI - Focuses on the Gopher protocol, its history, and practical applications
OpenZIM MCP Server: Offline Knowledge for AI Assistants - Covers offline Wikipedia access and ZIM format optimization

Understanding the Model Context Protocol Architecture

Before MCP, wiring an AI model up to an external data source meant a one-off integration every time. MCP replaces that with a formal contract between the model and the resource: a standard way to expose data and tools that doesn't hand the model unchecked access to your system.

It sits between the model and whatever you're integrating, so old protocols and modern APIs look the same from the model's side. None of this is new. It's the same separation-of-concerns thinking distributed systems have relied on for years, pointed at AI tooling.

Strategic Advantages of MCP Implementation

Security: capability-based, with explicit permission boundaries. The model gets exactly the access you grant it, which beats the plugin free-for-all it replaces.
One integration pattern: every resource type is reached the same way, so you're not relearning a new integration shape for each backend.
Room to grow: adding a capability means implementing an interface, not redesigning the server.
Performance hooks built in: caching, connection pooling, and resource lifecycle management are part of the model rather than bolted on later.

Architectural Patterns for Production MCP Systems

Building a couple of MCP servers surfaced the same handful of patterns each time. None of them are specific to MCP; they're standard distributed-systems practice, applied to the job of exposing resources to a model:

1. Resource-Centric Design

The pattern looks like this: Pydantic models for the data contract, a Protocol for the behavior.

from typing import Protocol

from pydantic import BaseModel


class Resource(BaseModel):
    uri: str
    name: str
    description: str | None = None
    mime_type: str | None = None


class ResourceProvider(Protocol):
    async def list_resources(self) -> list[Resource]: ...
    async def read_resource(self, uri: str) -> bytes: ...

That's the Strategy pattern: you can swap the backend at runtime without touching the code that uses it. Keeping discovery (list_resources) separate from access (read_resource) is also what makes caching, load balancing, and failover tractable later, since each concern has one place to live.

2. Protocol Abstraction Layer

gopher-mcp has to speak two protocols, Gopher and Gemini, which made it a good place to work out how to abstract over them instead of writing two disconnected handlers. Both clients expose the same async surface and inherit the same caching behavior, and each is registered as a FastMCP tool (condensed from server.py and the client modules):

class GopherClient(TTLCacheMixin[GopherFetchResponse]):
    """Async Gopher protocol client with caching and safety features."""

    async def fetch(self, url: str) -> GopherFetchResponse: ...


class GeminiClient(TTLCacheMixin[GeminiFetchResponse]):
    """Async Gemini protocol client with TLS, caching and safety features."""

    async def fetch(self, url: str) -> GeminiFetchResponse: ...


@mcp.tool(title="Fetch Gopher resource")
async def gopher_fetch(url: str) -> dict[str, Any]:
    client = await client_manager.get_gopher_client()
    response = await client.fetch(url)
    return response.model_dump()

This is the Open/Closed Principle in practice: open for extension, closed for modification. Adding a protocol means implementing the same client interface, not editing the core, so the parts that already work keep working.

3. Async-First Architecture

A server handling concurrent requests wants sub-millisecond responses for cached resources, and a single blocking I/O call can stall everything queued behind it. So every I/O path in gopher-mcp is async end to end, on Python's asyncio event loop. There's a nice side effect: because the event loop serializes access to shared state, the cache layer needs no locking at all. Both protocol clients inherit the same TTL + LRU cache behavior from a shared mixin (condensed from cache.py):

import time
from collections import OrderedDict
from typing import Generic, TypeVar

V = TypeVar("V")


class TTLCacheMixin(Generic[V]):
    """Shared TTL + LRU cache behavior for the Gopher and Gemini clients."""

    _cache: "OrderedDict[str, _BaseCacheEntry[V]]"

    def _get_cached_response(self, url: str) -> V | None:
        entry = self._cache.get(url)
        if entry is None:
            return None
        if entry.is_expired(time.time()):
            del self._cache[url]
            return None
        self._cache.move_to_end(url)  # mark as most recently used
        return entry.value

    def _cache_response(self, url: str, response: V) -> None:
        if len(self._cache) >= self.max_cache_entries:
            self._cache.popitem(last=False)  # evict the LRU entry
        self._cache[url] = self._cache_entry_cls(
            key=url,
            value=response,
            timestamp=time.time(),
            ttl=self.cache_ttl_seconds,
        )

Case Study: OpenZIM MCP Server Architecture

openzim-mcp searches compressed knowledge bases with millions of articles and needs to return results in under a second. That's the usual storage-versus-speed tradeoff, with a memory budget tight enough to run on modest hardware.

ZIM File Handling

The hard part sounds like it would be searching compressed data without decompressing the whole thing first. It turns out the ZIM format already solves that: each archive ships with an embedded Xapian full-text index, and libzim exposes it directly. So the server doesn't build an index at all; it just drives the one that's already there. The core search path (condensed from openzim-mcp's zim/search.py):

from libzim.search import Query, Searcher


class _SearchMixin:
    def _perform_search(
        self, archive: Archive, query: str, limit: int, offset: int
    ) -> dict[str, Any]:
        searcher = Searcher(archive)
        search = searcher.search(Query().set_query(query))
        total_results = search.getEstimatedMatches()

        results = []
        for entry_id in search.getResults(offset, limit):
            entry = archive.get_entry_by_path(entry_id)
            results.append({"path": entry_id, "title": entry.title})

        return {"query": query, "total": total_results, "results": results}

Performance Tricks I Discovered

Most of the speed comes from four things:

Lazy loading: articles and indexes are read on demand, so startup stays cheap and memory tracks what you actually touch.
The embedded Xapian index: search runs against the full-text index already inside the ZIM archive, reached through libzim, so there's no separate index to build or keep in sync.
Memory-mapped I/O: the kernel's page cache decides what stays in memory, which means no cache layer to write here.
Result caching: paginated search results are cached so a repeated query doesn't pay the full cost twice.

Case Study: Gopher MCP Server Implementation

There's something to learn from old protocols about doing less. Gopher predates most of the complexity we take for granted on the modern web, and that simplicity is exactly what makes it reliable and easy to reason about.

Protocol Implementation

The transport layer (condensed from gopher_transport.py) is about as simple as the protocol. It's a TCP connection, a selector line, and a bounded read:

import asyncio


async def fetch_gopher(
    host: str,
    port: int,
    selector: str,
    *,
    search: str | None = None,
    max_bytes: int = DEFAULT_MAX_RESPONSE_SIZE,
    timeout: float = DEFAULT_TIMEOUT_SECONDS,
) -> bytes:
    async def _io() -> bytes:
        reader, writer = await asyncio.open_connection(host, port)
        try:
            # "selector[<TAB>search]<CR><LF>", UTF-8 encoded
            writer.write(build_request(selector, search))
            await writer.drain()

            chunks: list[bytes] = []
            total = 0
            while True:
                chunk = await reader.read(min(READ_CHUNK, max_bytes - total + 1))
                if not chunk:
                    break
                total += len(chunk)
                if total > max_bytes:
                    raise GopherProtocolError("Response exceeded size limit")
                chunks.append(chunk)
            return b"".join(chunks)
        finally:
            writer.close()
            await writer.wait_closed()

    # One deadline covers connect, send, and read
    return await asyncio.wait_for(_io(), timeout=timeout)

Content Type Detection

Gopher uses a simple but effective type system. In gopher-mcp, the mapping lives in mime.py as plain data:

type_mappings = {
    "0": "text/plain",                # text file
    "1": "text/gopher-menu",          # menu / directory
    "4": "application/mac-binhex40",  # BinHex file
    "7": "text/gopher-menu",          # search server
    "9": "application/octet-stream",  # binary file
    "g": "image/gif",
    "I": "image/jpeg",
    # ... more mappings
}


def guess_mime_type(gopher_type: str, selector: str = "") -> str:
    """Map a Gopher item type to a MIME type.

    The full implementation also refines ambiguous types using the
    selector's file extension (.html, .png, .pdf, ...).
    """
    return type_mappings.get(gopher_type, "application/octet-stream")

Best Practices for MCP Server Development

1. Error Handling

Handle errors with context. gopher-mcp draws a line between internal exceptions and what crosses the tool boundary:

class GopherProtocolError(Exception):
    """Raised internally when a Gopher request cannot be completed."""


class ErrorResult(BaseModel):
    """Structured error payload returned to the model."""

    kind: Literal["error"] = "error"
    error: dict[str, str]

The split matters: transport failures raise GopherProtocolError inside the client, but the tool boundary converts everything into a structured ErrorResult. An exception that escapes an MCP tool is an opaque failure to the calling model; a structured error is something it can reason about and recover from.

2. Configuration Management

Use structured configuration with validation. gopher-mcp builds its config from pydantic-settings models keyed by environment prefix:

from pydantic_settings import BaseSettings, SettingsConfigDict


class GopherConfig(BaseSettings):
    """Gopher client settings, read from GOPHER_* environment variables."""

    model_config = SettingsConfigDict(env_prefix="GOPHER_", env_file=".env")

    max_response_size: int = 1024 * 1024  # 1MB
    timeout_seconds: float = 30.0
    cache_enabled: bool = True
    cache_ttl_seconds: int = 300
    max_cache_entries: int = 1000
    allowed_hosts: list[str] | None = None  # None = allow all
    allow_local_hosts: bool = False  # SSRF protection

Each surface gets its own settings class (GOPHER_*, GEMINI_*, and GOPHER_MCP_* for the server itself), with field validators that parse comma-separated environment values into typed lists.

3. Testing Strategy

Cover the real paths, integration tests included. With pytest and pytest-asyncio, the shape looks like this:

import pytest


def test_gopher_url_parsing() -> None:
    parsed = parse_gopher_url("gopher://example.com/0/about.txt")
    assert parsed.host == "example.com"
    assert parsed.port == 70
    assert parsed.gopher_type == "0"


@pytest.mark.asyncio
async def test_fetch_returns_menu_result() -> None:
    client = GopherClient(cache_enabled=False)
    result = await client.fetch("gopher://gopher.example/")
    assert result.kind == "menu"

Performance Considerations

Memory Management

Use streaming for large resources
Implement proper caching strategies
Monitor memory usage in production

Concurrency

Design for high concurrency from the start
Use appropriate synchronization primitives
Consider backpressure mechanisms

Network Efficiency

Implement connection pooling
Use compression when appropriate
Handle network timeouts gracefully

Deployment and Monitoring

Docker Deployment

# Build stage: produce a wheel from the source tree
FROM python:3.14-slim AS build
RUN pip install --no-cache-dir uv
WORKDIR /src
COPY . .
RUN uv build --wheel --out-dir /dist

# Runtime stage: install just the wheel, run as a non-root user
FROM python:3.14-slim
RUN useradd --create-home --uid 10001 app
COPY --from=build /dist/*.whl /tmp/
RUN pip install --no-cache-dir /tmp/*.whl && rm -f /tmp/*.whl
USER app

EXPOSE 8000
ENTRYPOINT ["gopher-mcp"]
CMD ["--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8000"]

Health Checks

Health checks look different for MCP servers than for web services. Over the stdio transport there's no HTTP surface to probe, so it pays to expose health as a first-class tool the client can call like any other. openzim-mcp ships one as zim_health. The pattern looks like this:

@mcp.tool()
async def health_check() -> dict[str, str]:
    """Lightweight liveness probe callable by any MCP client."""
    return {"status": "ok"}

Future Directions in MCP Architecture

MCP is still young, and there's a lot of room to build on top of it. A few directions I'm watching:

Streaming: backpressure-aware streaming so a large dataset doesn't have to fit in memory to be processed.
Authentication: capability-based security that holds up across multiple MCP servers, not just one.
Federation: service-mesh patterns for running and load-balancing a fleet of MCP servers.
Observability: distributed tracing and metrics for interactions that span several tools.

Strategic Implications and Future Outlook

Two servers in, what strikes me is how ordinary the good decisions are. Start with the smallest version that works. Add observability early, so you can see what production is actually doing. Then iterate on what it shows you.

MCP is on track to become plumbing that a lot of AI systems depend on. That's reason enough to build these servers with the same care you'd give any other piece of infrastructure you expect to keep running.

Dive Deeper

Two more focused guides on building specific kinds of MCP server:

Gopher MCP Server: Bringing 1991's Internet to Modern AI - protocol handlers, Gopher's history, and where alternative internet protocols still make sense
OpenZIM MCP Server: Offline Knowledge for AI Assistants - building offline knowledge systems, ZIM file handling, and AI assistants that work with no network

The complete implementations are on GitHub: gopher-mcp and openzim-mcp.

Well-known URIs: Standardizing Web Metadata Discovery

c@meron.io (Cameron Rye) — Thu, 18 Jan 2024 00:00:00 GMT

Every web developer has run into this: the metadata a site exposes lives in a different place on every site. Where do you find a site's security contact? How do you discover its OAuth endpoints? What about the password-change URL a password manager needs? The web is decentralized by design, and for most of its history that meant each site published this kind of service metadata however it happened to feel like.

RFC 8615, published by the Internet Engineering Task Force (IETF), fixes that. It reserves a single path prefix, /.well-known/, as the place a site publishes machine-readable information about its services and policies. If you know the suffix, you know the URL.

Understanding Well-known URIs

Well-known URIs are defined in RFC 8615. They carve out a namespace under the /.well-known/ path prefix where a site can expose machine-readable information about its services, policies, and capabilities.

The problem behind the spec is a real one. More and more protocols need a piece of information to sit at a predictable location, no matter how a given host organizes the rest of its URLs. Pin that location down once and automated discovery stops being a per-site integration project.

The Technical Foundation

Well-known URIs follow a simple pattern:

https://example.com/.well-known/{service-name}

This structure provides several key advantages:

Predictability: Clients know exactly where to look for specific metadata
Namespace Isolation: The .well-known prefix prevents conflicts with existing site structure
Extensibility: New services can be added without affecting existing implementations
Cross-Origin Compatibility: Standard HTTP mechanisms apply for access control

The Problem Well-known URIs Solve

Before standardization, discovering service metadata required ad-hoc approaches that varied significantly across implementations. Consider these common scenarios:

Security Contact Discovery

Before Well-known URIs:

# Multiple possible locations, no standard format
https://example.com/security
https://example.com/contact/security
https://example.com/about/security-team
https://example.com/responsible-disclosure

With Well-known URIs:

# Single, predictable location with standardized format
https://example.com/.well-known/security.txt

OAuth/OpenID Connect Discovery

Before Well-known URIs:

# Provider-specific discovery mechanisms
https://accounts.google.com/.well-known/openid_configuration
https://login.microsoftonline.com/common/.well-known/openid_configuration
# But many providers used different paths entirely

With Well-known URIs:

# Standardized discovery endpoint
https://any-provider.com/.well-known/openid-configuration

That predictability cuts integration work and lets tooling behave the same way against any provider.

Implementation Architecture

Server Configuration

Implementing well-known URIs requires configuring your web server to serve content from the /.well-known/ directory. Here are examples for common server configurations:

Apache Configuration

# Enable .well-known directory
<Directory "/var/www/html/.well-known">
    Options -Indexes
    AllowOverride None
    Require all granted

    # Set appropriate content types
    <Files "security.txt">
        Header set Content-Type "text/plain; charset=utf-8"
    </Files>

    <Files "openid-configuration">
        Header set Content-Type "application/json; charset=utf-8"
    </Files>
</Directory>

Nginx Configuration

location /.well-known/ {
    root /var/www/html;

    # Security headers
    add_header X-Content-Type-Options nosniff;
    add_header Cache-Control "public, max-age=3600";

    # Content type mapping
    location ~ \.txt$ {
        add_header Content-Type "text/plain; charset=utf-8";
    }

    location ~ /openid-configuration$ {
        add_header Content-Type "application/json; charset=utf-8";
    }
}

Dynamic Implementation

For applications requiring dynamic well-known URI generation:

// Express.js implementation
const express = require('express');
const app = express();

// Well-known URI middleware
app.use('/.well-known', (req, res, next) => {
    // Set security headers
    res.set({
        'X-Content-Type-Options': 'nosniff',
        'Cache-Control': 'public, max-age=3600'
    });
    next();
});

// Security.txt endpoint
app.get('/.well-known/security.txt', (req, res) => {
    res.type('text/plain');
    res.send(`Contact: security@example.com
Expires: 2025-12-31T23:59:59.000Z
Encryption: https://example.com/pgp-key.txt
Preferred-Languages: en
Canonical: https://example.com/.well-known/security.txt`);
});

// OpenID Connect discovery
app.get('/.well-known/openid-configuration', (req, res) => {
    res.json({
        issuer: 'https://example.com',
        authorization_endpoint: 'https://example.com/auth',
        token_endpoint: 'https://example.com/token',
        userinfo_endpoint: 'https://example.com/userinfo',
        jwks_uri: 'https://example.com/.well-known/jwks.json',
        response_types_supported: ['code', 'token', 'id_token'],
        subject_types_supported: ['public'],
        id_token_signing_alg_values_supported: ['RS256']
    });
});

Essential Well-known URIs

IANA keeps the registry of standardized well-known URIs. A few that come up most often:

Security and Policy

security.txt - Security contact information and vulnerability disclosure policies

Contact: security@example.com
Expires: 2025-12-31T23:59:59.000Z
Encryption: https://example.com/pgp-key.txt
Policy: https://example.com/security-policy

change-password - Direct link to password change functionality for password managers

https://example.com/.well-known/change-password
# Redirects to: https://example.com/account/password

Authentication and Identity

openid-configuration - OAuth 2.0/OpenID Connect provider metadata webfinger - Identity discovery for federated protocols host-meta - General host metadata in XML format

Application Integration

apple-app-site-association - iOS Universal Links configuration assetlinks.json - Android App Links verification matrix - Matrix protocol server discovery

Development and Automation

robots.txt equivalent URIs for specialized crawlers nodeinfo - Federated social network metadata timezone - Time zone data distribution

Security Considerations

Well-known URIs come with security benefits and a few risks worth thinking about:

Security Benefits

Standardized Security Contact: The security.txt standard provides a reliable way for security researchers to report vulnerabilities
Reduced Attack Surface: Centralized metadata reduces the need for custom discovery mechanisms
Improved Transparency: Standardized policy disclosure enhances security posture visibility

Potential Risks

Information Disclosure: Well-known URIs may reveal sensitive information about system architecture
Attack Vector Expansion: Improperly configured endpoints could expose internal services
Cache Poisoning: Incorrect caching headers could lead to stale or malicious metadata

Best Practices

# Security-focused well-known configuration
location /.well-known/ {
    # Prevent directory traversal
    location ~ \.\. {
        deny all;
    }

    # Rate limiting
    limit_req zone=wellknown burst=10 nodelay;

    # Security headers
    add_header X-Content-Type-Options nosniff;
    add_header X-Frame-Options DENY;
    add_header Referrer-Policy strict-origin-when-cross-origin;

    # Appropriate caching
    expires 1h;
    add_header Cache-Control "public, immutable";
}

Practical Implementation Guide

Step 1: Create the Well-known Directory Structure

# Create the directory structure
mkdir -p /var/www/html/.well-known

# Set appropriate permissions
chmod 755 /var/www/html/.well-known

Step 2: Implement Security.txt

# Create security.txt file
cat > /var/www/html/.well-known/security.txt << EOF
Contact: mailto:security@example.com
Contact: https://example.com/security-contact
Expires: 2025-12-31T23:59:59.000Z
Encryption: https://example.com/pgp-key.txt
Acknowledgments: https://example.com/security-acknowledgments
Preferred-Languages: en, es
Canonical: https://example.com/.well-known/security.txt
Policy: https://example.com/vulnerability-disclosure-policy
EOF

Step 3: Validation and Testing

#!/usr/bin/env python3
"""
Well-known URI validator script
"""
import requests
import json
from urllib.parse import urljoin

def validate_security_txt(base_url):
    """Validate security.txt implementation"""
    url = urljoin(base_url, '/.well-known/security.txt')

    try:
        response = requests.get(url, timeout=10)
        response.raise_for_status()

        # Check content type
        content_type = response.headers.get('content-type', '')
        if 'text/plain' not in content_type:
            print(f"Warning: Unexpected content-type: {content_type}")

        # Parse and validate required fields
        content = response.text
        required_fields = ['Contact', 'Expires']

        for field in required_fields:
            if field not in content:
                print(f"Error: Missing required field: {field}")
                return False

        print("✓ security.txt validation passed")
        return True

    except requests.RequestException as e:
        print(f"Error accessing security.txt: {e}")
        return False

def validate_openid_configuration(base_url):
    """Validate OpenID Connect configuration"""
    url = urljoin(base_url, '/.well-known/openid-configuration')

    try:
        response = requests.get(url, timeout=10)
        response.raise_for_status()

        # Check content type
        content_type = response.headers.get('content-type', '')
        if 'application/json' not in content_type:
            print(f"Warning: Unexpected content-type: {content_type}")

        # Parse JSON and validate required fields
        config = response.json()
        required_fields = [
            'issuer', 'authorization_endpoint',
            'token_endpoint', 'jwks_uri'
        ]

        for field in required_fields:
            if field not in config:
                print(f"Error: Missing required field: {field}")
                return False

        print("✓ OpenID Connect configuration validation passed")
        return True

    except (requests.RequestException, json.JSONDecodeError) as e:
        print(f"Error accessing OpenID configuration: {e}")
        return False

if __name__ == "__main__":
    base_url = "https://example.com"
    validate_security_txt(base_url)
    validate_openid_configuration(base_url)

Advanced Use Cases

Content Delivery Network Integration

// Cloudflare Workers implementation
addEventListener('fetch', event => {
    event.respondWith(handleRequest(event.request))
})

async function handleRequest(request) {
    const url = new URL(request.url)

    // Handle well-known URIs
    if (url.pathname.startsWith('/.well-known/')) {
        return handleWellKnownRequest(url.pathname)
    }

    // Forward other requests
    return fetch(request)
}

async function handleWellKnownRequest(pathname) {
    const wellKnownRoutes = {
        '/.well-known/security.txt': () => new Response(
            generateSecurityTxt(),
            {
                headers: {
                    'Content-Type': 'text/plain; charset=utf-8',
                    'Cache-Control': 'public, max-age=3600'
                }
            }
        ),

        '/.well-known/openid-configuration': () => new Response(
            JSON.stringify(generateOpenIDConfig()),
            {
                headers: {
                    'Content-Type': 'application/json; charset=utf-8',
                    'Cache-Control': 'public, max-age=3600'
                }
            }
        )
    }

    const handler = wellKnownRoutes[pathname]
    if (handler) {
        return handler()
    }

    return new Response('Not Found', { status: 404 })
}

function generateSecurityTxt() {
    return `Contact: security@example.com
Expires: ${new Date(Date.now() + 365 * 24 * 60 * 60 * 1000).toISOString()}
Encryption: https://example.com/pgp-key.txt
Canonical: https://example.com/.well-known/security.txt`
}

function generateOpenIDConfig() {
    return {
        issuer: 'https://example.com',
        authorization_endpoint: 'https://example.com/oauth/authorize',
        token_endpoint: 'https://example.com/oauth/token',
        userinfo_endpoint: 'https://example.com/oauth/userinfo',
        jwks_uri: 'https://example.com/.well-known/jwks.json',
        response_types_supported: ['code'],
        subject_types_supported: ['public'],
        id_token_signing_alg_values_supported: ['RS256']
    }
}

Monitoring and Analytics

# Well-known URI monitoring script
import requests
import time
import logging
from datetime import datetime, timedelta

class WellKnownMonitor:
    def __init__(self, base_url):
        self.base_url = base_url
        self.logger = logging.getLogger(__name__)

    def check_endpoint(self, path, expected_content_type):
        """Monitor a specific well-known endpoint"""
        url = f"{self.base_url}/.well-known/{path}"

        try:
            start_time = time.time()
            response = requests.get(url, timeout=10)
            response_time = time.time() - start_time

            # Log metrics
            self.logger.info(f"Endpoint: {path}")
            self.logger.info(f"Status: {response.status_code}")
            self.logger.info(f"Response Time: {response_time:.3f}s")
            self.logger.info(f"Content-Type: {response.headers.get('content-type')}")

            # Validate content type
            if expected_content_type not in response.headers.get('content-type', ''):
                self.logger.warning(f"Unexpected content-type for {path}")

            # Check for security headers
            security_headers = [
                'X-Content-Type-Options',
                'Cache-Control'
            ]

            for header in security_headers:
                if header not in response.headers:
                    self.logger.warning(f"Missing security header: {header}")

            return response.status_code == 200

        except requests.RequestException as e:
            self.logger.error(f"Error checking {path}: {e}")
            return False

    def run_checks(self):
        """Run all well-known URI checks"""
        endpoints = [
            ('security.txt', 'text/plain'),
            ('openid-configuration', 'application/json'),
            ('change-password', 'text/html')
        ]

        results = {}
        for path, content_type in endpoints:
            results[path] = self.check_endpoint(path, content_type)

        return results

# Usage
if __name__ == "__main__":
    logging.basicConfig(level=logging.INFO)
    monitor = WellKnownMonitor("https://example.com")
    results = monitor.run_checks()
    print(f"Check results: {results}")

Registry and Standardization Process

The Internet Assigned Numbers Authority (IANA) maintains the official Well-Known URIs registry, which serves as the authoritative source for standardized well-known URI suffixes. This registry ensures global coordination and prevents conflicts between different specifications.

Proposing New Well-known URIs

To propose a new well-known URI, you must follow the IETF specification process:

Draft Specification: Create an Internet-Draft describing the proposed URI and its purpose
Community Review: Submit to the wellknown-uri-review@ietf.org mailing list
IANA Registration: Complete the registration template with required fields
Expert Review: IANA designated experts review the proposal
Publication: Upon approval, the URI is added to the official registry

Registration Template

URI suffix: example-service
Change controller: IETF
Specification document: RFC 8615, Section 3.1
Status: permanent
Related information: Optional additional context

Current Adoption and Future Trends

Adoption is broad at this point:

Industry Adoption

Major Platforms: Google, Microsoft, Apple, and other tech giants extensively use well-known URIs
Security Tools: Security scanners and vulnerability management platforms rely on security.txt
Identity Providers: OAuth and OpenID Connect providers universally implement discovery endpoints
Password Managers: Modern password managers use change-password to send people straight to the right page

Emerging Trends

Federated Protocols: Matrix, Mastodon, and other federated platforms use well-known URIs for server discovery
Privacy Standards: Global Privacy Control (GPC) and similar privacy frameworks adopt well-known URIs
AI and Automation: Machine learning platforms use well-known URIs for model and API discovery
IoT Integration: Internet of Things devices increasingly expose metadata via well-known URIs

Performance and Caching Considerations

Caching strategy matters here:

# Optimal caching headers for well-known URIs
Cache-Control: public, max-age=3600, immutable
ETag: "v1.2.3-20250114"
Last-Modified: Tue, 14 Jan 2025 10:00:00 GMT
Vary: Accept-Encoding

CDN Configuration

# CloudFront distribution configuration
wellknown_cache_behavior:
  path_pattern: "/.well-known/*"
  target_origin_id: "primary-origin"
  viewer_protocol_policy: "redirect-to-https"
  cache_policy:
    default_ttl: 3600
    max_ttl: 86400
    min_ttl: 0
  compress: true
  headers:
    - "Content-Type"
    - "Cache-Control"

Troubleshooting Common Issues

CORS Configuration

// Express.js CORS configuration for well-known URIs
app.use('/.well-known', cors({
    origin: true,
    methods: ['GET', 'HEAD'],
    allowedHeaders: ['Content-Type'],
    maxAge: 3600
}));

Content-Type Issues

# Apache MIME type configuration
<Files "security.txt">
    ForceType text/plain
</Files>

<Files "openid-configuration">
    ForceType application/json
</Files>

<Files "jwks.json">
    ForceType application/json
</Files>

SSL/TLS Considerations

# Nginx SSL configuration for well-known URIs
location /.well-known/ {
    # Allow HTTP for ACME challenges
    if ($request_uri ~ "^/.well-known/acme-challenge/") {
        # ACME challenge can use HTTP
    }

    # Force HTTPS for other well-known URIs
    if ($scheme = http) {
        return 301 https://$server_name$request_uri;
    }
}

Integration with Modern Development Workflows

Docker Implementation

# Dockerfile for well-known URI server
FROM nginx:alpine

# Copy well-known files
COPY .well-known/ /usr/share/nginx/html/.well-known/

# Copy nginx configuration
COPY nginx.conf /etc/nginx/nginx.conf

# Set appropriate permissions
RUN chmod -R 644 /usr/share/nginx/html/.well-known/

EXPOSE 80 443

CMD ["nginx", "-g", "daemon off;"]

Kubernetes Deployment

apiVersion: v1
kind: ConfigMap
metadata:
  name: wellknown-config
data:
  security.txt: |
    Contact: security@example.com
    Expires: 2025-12-31T23:59:59.000Z
    Canonical: https://example.com/.well-known/security.txt

  openid-configuration: |
    {
      "issuer": "https://example.com",
      "authorization_endpoint": "https://example.com/oauth/authorize",
      "token_endpoint": "https://example.com/oauth/token"
    }

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: wellknown-server
spec:
  replicas: 2
  selector:
    matchLabels:
      app: wellknown-server
  template:
    metadata:
      labels:
        app: wellknown-server
    spec:
      containers:
      - name: nginx
        image: nginx:alpine
        ports:
        - containerPort: 80
        volumeMounts:
        - name: wellknown-volume
          mountPath: /usr/share/nginx/html/.well-known
      volumes:
      - name: wellknown-volume
        configMap:
          name: wellknown-config

Conclusion and Strategic Recommendations

The payoff of well-known URIs is boring in the best way: metadata discovery stops being guesswork. Less integration glue, a clearer security posture, tooling that behaves the same everywhere.

If you're rolling these out, here's what I'd do:

Start with Security: Implement security.txt as your first well-known URI to improve security posture
Plan for Scale: Design your implementation to handle high traffic and provide appropriate caching
Monitor Continuously: Implement monitoring to ensure well-known URIs remain accessible and current
Follow Standards: Adhere to IANA registry specifications and IETF best practices
Consider Privacy: Evaluate what information you expose through well-known URIs

The point isn't the individual files. It's that discovery stops depending on convention and starts depending on a spec. Implement these and you're part of a web that machines can navigate without a scraper and a prayer.

As more traffic comes from automated clients rather than people, that predictability is worth a little more every year.

Want to explore more web standards and protocols? Check out my post on building MCP servers for more on connecting open protocols to modern AI.

Project: Aranet

c@meron.io (Cameron Rye) — Mon, 01 Jan 2024 00:00:00 GMT

Aranet is a Rust implementation for connecting to Aranet environmental sensors via Bluetooth Low Energy. The workspace covers the full stack: low-level BLE communication, the user interfaces, and the production monitoring integrations.

Key Features

Multi-sensor support: CO2, temperature, pressure, humidity, radon, and radiation readings from four Aranet device families
Historical data download: Resumable checkpoints, date filters, and incremental sync with local SQLite storage
Passive monitoring: Read BLE advertisements without establishing a device connection
Terminal dashboard: Sparkline charts, CO2/radon threshold alerts, vim keybindings, and CSV export via ratatui
Desktop GUI: Multi-panel egui interface with alert system and system tray
Background service: REST API with WebSocket streaming for real-time data
Observability: Prometheus metrics endpoint with pre-built Grafana dashboard template
IoT integration: MQTT publisher with Home Assistant auto-discovery, InfluxDB export, webhook notifications

Why Rust

Environmental monitoring runs continuously on modest hardware. Rust's zero-cost abstractions and memory safety make it the right choice for a long-running BLE daemon that needs to be reliable without consuming resources. The workspace structure keeps each concern in its own crate while sharing the core protocol implementation across every interface.

Architecture decisions

The seven-crate workspace follows a clear layering:

aranet-types provides platform-agnostic shared types
aranet-core handles all BLE communication and protocol parsing
aranet-store manages local SQLite persistence with deduplication and incremental sync
aranet-service adds the daemon layer with REST, WebSocket, MQTT, Prometheus, and webhook integrations
aranet-cli, aranet-tui, and aranet-gui are thin interfaces over the core and store crates

This separation means adding a new integration or interface requires no changes to the sensor communication layer.

Distribution

The project ships through several channels:

Homebrew: brew tap cameronrye/aranet && brew install aranet
crates.io: cargo install aranet-cli
GitHub Releases: Shell and PowerShell installers, macOS DMG bundles
Docker Compose: Pre-configured stack with Prometheus and Grafana

Outcome

Embedded sensor tooling does not need to be locked behind mobile apps or cloud services. Building up from the BLE packets through storage, APIs, and dashboards in a single Rust workspace gives users full control of their environmental data, and it runs reliably enough to sit under real monitoring infrastructure.

Project: Circle of Fifths

c@meron.io (Cameron Rye) — Mon, 01 Jan 2024 00:00:00 GMT

import CircleOfFifthsDemo from '../../components/demos/CircleOfFifthsDemo.tsx';

A static diagram of the Circle of Fifths can show you that adjacent keys sit a perfect fifth apart, but it cannot let you hear it. This project closes that gap: click any of the twelve keys and the Web Audio API synthesizes the pitch in real time, connecting the circle's geometry to the harmonic relationships it encodes.

Key Features

Interactive Visualization: Click and explore the circle of fifths
Audio Feedback: Hear scales and chords using Web Audio API
Key Relationships: Understand relative majors/minors and chord progressions
Educational Design: Clear visual representation of music theory concepts

Technical Implementation

The Web Audio API provides real-time audio synthesis:

const A4_FREQUENCY = 440; // Hz
const SEMITONE_RATIO = Math.pow(2, 1/12);

function noteToFrequency(note, octave) {
  const noteIndex = ['C', 'C#', 'D', 'D#', 'E', 'F', 
                     'F#', 'G', 'G#', 'A', 'A#', 'B'].indexOf(note);
  const semitonesFromA4 = (octave - 4) * 12 + (noteIndex - 9);
  return A4_FREQUENCY * Math.pow(SEMITONE_RATIO, semitonesFromA4);
}

Each key in the circle is positioned 30 degrees apart, representing the perfect fifth interval that defines the circle's structure.

What was hard

The audio side held the real surprises. Modern browsers start every AudioContext in a suspended state to block autoplay, so the app resumes the context on the first user interaction. Without that pre-warming, the first click on a key would produce silence. Raw oscillator starts and stops also click audibly; shaping each note with a gain envelope that ramps down exponentially makes the tones sound like an instrument instead of a test signal. On the visual side, the circular layout is pure trigonometry: twelve keys at 30-degree intervals with a -90-degree offset to put C at the top. But every key still needed a 44px minimum touch target so the circle stays usable on phones.

Project: Clarissa

c@meron.io (Cameron Rye) — Mon, 01 Jan 2024 00:00:00 GMT

import MCPToolDemo from '../../components/demos/MCPToolDemo.tsx';

export const clarissaTools = [ { name: 'read_file', description: 'Read the contents of a file', request: { tool: 'read_file', path: './src/agent.ts' }, response: { content: 'import { llmClient } from "./llm/client.ts";\nimport { toolRegistry } from "./tools/index.ts";\n...', lines: 203 } }, { name: 'bash', description: 'Execute shell commands', request: { tool: 'bash', command: 'git status --short' }, response: { stdout: ' M src/agent.ts\n?? src/tools/new-tool.ts', exitCode: 0 } }, { name: 'git_diff', description: 'Show changes in the repository', request: { tool: 'git_diff', staged: false }, response: { diff: 'diff --git a/src/agent.ts b/src/agent.ts\n@@ -1,5 +1,6 @@\n+import { memoryManager } from "./memory";', files: 1 } }, { name: 'web_fetch', description: 'Fetch and parse web pages', request: { tool: 'web_fetch', url: 'https://example.com' }, response: { title: 'Example Domain', content: 'This domain is for use in illustrative examples...', status: 200 } } ];

Clarissa is a command-line AI agent built with Bun and Ink. It provides a conversational interface powered by OpenRouter, enabling access to various LLMs like Claude, GPT-4, Gemini, and more. The agent can execute tools, manage files, run shell commands, and integrate with external services via the Model Context Protocol (MCP).

Key Features

ReAct Agent Pattern: Implements the Reasoning + Acting loop for multi-step tasks
Multi-model Support: Switch between Claude, GPT-4, Gemini, Llama, and more via OpenRouter
Tool Execution: Built-in tools for files, Git, shell commands, and web fetching
MCP Integration: Extend with external tools through the Model Context Protocol
Session Persistence: Save and restore conversation history across sessions
Memory System: Remember facts across sessions with /remember and /memories
Context Management: Automatic token tracking and context truncation
Tool Confirmation: Approve or reject potentially dangerous operations

The ReAct Loop

The agent implements an iterative loop where it:

Receives user input and sends it to the LLM with available tool definitions
If the LLM responds with tool calls, executes them and feeds results back
Repeats until the LLM provides a final answer without requesting tools

This pattern enables complex multi-step tasks while maintaining safety through tool confirmation.

Usage Modes

# Interactive mode
clarissa

# One-shot mode
clarissa "What files are in this directory?"

# Piped input
git diff | clarissa "Write a commit message for these changes"

Project: ClarissaBot

c@meron.io (Cameron Rye) — Mon, 01 Jan 2024 00:00:00 GMT

ClarissaBot is a conversational AI assistant that helps users understand vehicle safety information. Rather than training a model on static data, it uses Azure OpenAI's function calling to query live NHTSA (National Highway Traffic Safety Administration) data in real-time.

Key Features

Natural Language Queries: Ask about recalls, safety ratings, or complaints in plain English
Real-time Data: Queries live NHTSA APIs for current information
VIN Decoding: Automatically identifies vehicles from VIN numbers
Streaming Responses: Token-by-token delivery via Server-Sent Events
Context Awareness: Remembers which vehicles you're discussing

NHTSA Tools

The agent has access to five specialized tools:

Tool	Description
`check_recalls`	Find recall campaigns affecting a vehicle
`get_complaints`	View consumer-reported problems
`get_safety_rating`	NCAP crash test ratings (1-5 stars)
`decode_vin`	Extract year/make/model from VIN
`check_investigations`	Active NHTSA defect investigations

Technical Architecture

The backend is built with .NET 10 and uses Azure AI Foundry (Azure OpenAI) for the AI capabilities:

var completion = await _chatClient.CompleteChatStreamingAsync(
    messages, 
    options, 
    cancellationToken
);

await foreach (var update in completion)
{
    foreach (var contentPart in update.ContentUpdate)
    {
        yield return new ContentChunkEvent(contentPart.Text);
    }
}

The React frontend connects via SSE for real-time streaming, showing tool calls and responses as they happen.

Reinforcement Fine-Tuning

The project includes a complete RFT (Reinforcement Fine-Tuning) pipeline with 502 training examples and a Python grader that validates responses against live NHTSA data. This enables training specialized models that stay accurate as vehicle safety data evolves.

Infrastructure

Deployed on Azure Container Apps with infrastructure defined in Bicep:

Managed Identity: RBAC-based authentication to Azure OpenAI, no API keys
Auto-scaling: Scale to zero when idle, burst for traffic
Monitoring: Application Insights for observability
Container Registry: ACR for image management

Project: ClaytonRye.com

c@meron.io (Cameron Rye) — Mon, 01 Jan 2024 00:00:00 GMT

import AccessibilityDemo from '../../components/demos/AccessibilityDemo.astro';

ClaytonRye.com is a digital archive of Clayton Rye's work as an award-winning documentary filmmaker, Vietnam War veteran, and Professor Emeritus at Ferris State University. I built it as a birthday gift. It gathers five decades of documentary work focused on civil rights and social justice.

Key Features

Filmography: Documentation of his award-winning documentaries, including the Detroit Civil Rights Trilogy
Archival Design: Built for long-term preservation and accessibility
Performance Optimized: Static site generation with minimal JavaScript
WCAG AA Compliant: Full accessibility with semantic HTML and keyboard navigation
Structured Data: Schema.org markup for discoverability by researchers and educators

The Documentary Legacy

Clayton Rye's films preserve historical records:

Ten Vietnam Vets: First-hand accounts from fellow veterans, now in university archives
Jim Crow's Museum: PBS documentary exploring racist memorabilia as educational tools
Detroit Civil Rights Trilogy: Three pivotal stories from Michigan's civil rights history

Technical Implementation

The site demonstrates several patterns for archival web design:

Astro Static Generation: Pre-rendered HTML for instant loading
Responsive Images: Modern formats (WebP, AVIF) with optimization
Theme Switching: Light/dark/system mode with localStorage persistence
Video Integration: Lightweight lite-youtube component for embedded content

Read the full story: Building ClaytonRye.com for My Father's 77th Birthday

Project: DosKit

c@meron.io (Cameron Rye) — Mon, 01 Jan 2024 00:00:00 GMT

import DOSKitDemo from '../../components/demos/DOSKitDemo.tsx';

DosKit brings classic DOS software to modern browsers through WebAssembly emulation. Nothing to install and nothing to configure: you click, and it runs.

Key Features

Instant Access: One-click access to DOS software
Browser-Based: Runs entirely in the browser via WebAssembly
Curated Library: Classic demos, games, and applications
Mobile Friendly: Touch controls for mobile devices

Technical Implementation

DosKit uses js-dos, a WebAssembly port of DOSBox, to run x86 DOS binaries directly in the browser:

const dos = await Dos(canvas, {
  wdosboxUrl: '/wdosbox.js',
  autoStart: true
});

await dos.fs.extract('/software.zip');
await dos.main(['-c', 'SOFTWARE.EXE']);

The emulator handles CPU emulation, memory management, and audio/video output, providing an authentic DOS experience without any native installation.

Why this was worth building

A lot of classic software preservation efforts are technically impressive but still inaccessible to most people. If someone has to learn emulator configuration before they can try a demo, the preservation effort has not fully crossed into public accessibility. DosKit was built to reduce that gap to a single click.

Product and engineering tradeoffs

Running old software in the browser sounds simple until you account for startup time, asset packaging, keyboard handling, audio behavior, and mobile input. The experience had to feel immediate enough for casual exploration while still preserving the character of the original software.

That led to a few practical decisions:

keep the launch path short so users reach the software quickly
package software and emulator configuration together instead of expecting manual setup
support touch controls for devices that do not have a physical keyboard
curate the library so the first-run experience highlights software that is historically interesting and technically representative

Product framing

The hard part of DosKit was product framing, not emulation. WebAssembly turns a fiddly setup process into a plain web page, and a curated library keeps a niche corner of computing approachable.

Outcome

What you get is a preservation product that still feels current: fast launch, zero installation, cross-device support, and a clear reason the software matters. The emulator core, the software, and its configuration all ship together as one web page that loads in under three seconds.

Project: Electromagnetic Spectrum Explorer

c@meron.io (Cameron Rye) — Mon, 01 Jan 2024 00:00:00 GMT

import SpectrumMiniDemo from '../../components/demos/SpectrumMiniDemo.astro';

Electromagnetic wavelengths run from femtometers to kilometers, more than twenty orders of magnitude. The core design problem in this explorer was making that entire range navigable on a single screen, which is why everything in the interface, from the spectrum bar to the position marker, is built on logarithmic scaling.

Key Features

Full Spectrum Coverage: From radio waves to gamma rays
Real-Time Visualization: Interactive spectrum display with logarithmic scaling
Unit Conversion: Convert between wavelength, frequency, and energy
Educational Content: Details for each band
Scientific Accuracy: NIST-certified physical constants

Technical Implementation

The physics calculations build on a small set of fixed constants:

export const PHYSICS_CONSTANTS = {
  SPEED_OF_LIGHT: 299792458, // m/s (exact)
  PLANCK_CONSTANT: 6.62607015e-34, // J*s (exact)
  PLANCK_CONSTANT_EV: 4.135667696e-15, // eV*s
};

export function wavelengthToFrequency(wavelength) {
  return SPEED_OF_LIGHT / wavelength;
}

Log scaling is what keeps the whole range usable in one view, from femtometers up to kilometers.

What was hard

Scientific tools punish sloppy numerics. Values near the edges of the spectrum push against JavaScript's floating-point limits, so every calculation validates its inputs and returns NaN early rather than letting a bad value propagate through a chain of conversions into a plausible-looking wrong answer. The conversion panel was the other challenge: wavelength, frequency, and energy are three views of one quantity, so editing any field has to update the other two without triggering an infinite update loop. Input parsing also has to meet users where they are, accepting 550 nm, 5.45e14, or bare meters and normalizing the units before any math runs.

Project: Frostpane

c@meron.io (Cameron Rye) — Mon, 01 Jan 2024 00:00:00 GMT

import FrostpaneDemo from '../../components/demos/FrostpaneDemo.astro';

A convincing frosted glass effect is never one backdrop-filter line. It needs light and dark variants with different opacity and border treatments, a reduced-motion fallback, and a plan for browsers that cannot blur at all. Frostpane packages those decisions into a drop-in stylesheet that weighs under 5KB.

Key Features

Frosted Glass Effects: Backdrop blur and translucent glass surfaces
CSS Custom Properties: 30+ variables for complete customization
SCSS Variables: Full Sass/SCSS support with configurable variables
Smooth Animations: Built-in transitions and animation effects
Zero Dependencies: Lightweight, no JavaScript required
Cross-Browser Support: Graceful fallbacks for older browsers

What was hard

The difficult part of shipping glass effects as a library is everything around the blur. backdrop-filter is expensive to render on lower-powered devices, so Frostpane includes a performance-conscious variant that swaps the blur for a more opaque solid background when prefers-reduced-motion is set. Browsers without backdrop-filter support get a usable solid panel through @supports feature queries rather than broken transparency. And a single recipe cannot serve both color schemes: light surfaces need a brighter, more opaque fill while dark surfaces need a near-black fill with a much fainter border, so the library ships separate light and dark mixins instead of one compromise value.

Customization

Frostpane uses CSS custom properties for easy customization. Override these variables to match your design:

.custom-glass {
  --fp-backdrop-blur: 12px;
  --fp-bg-color: rgba(255, 255, 255, 0.2);
  --fp-border-radius: 16px;
  --fp-filter-saturate: 180%;
  --fp-border-color: rgba(255, 255, 255, 0.3);
}

Quick Start

npm install frostpane

<link rel="stylesheet" href="path/to/frostpane.css">

<div class="glass-container">
  <div class="glass-content">Your content here</div>
</div>

Project: Gopher MCP Server

c@meron.io (Cameron Rye) — Mon, 01 Jan 2024 00:00:00 GMT

import GopherDemo from '../../components/demos/GopherDemo.tsx';

The small internet never went away. Enthusiasts still run thousands of Gopher and Gemini servers full of curated, text-first content (university archives, technical documentation, historical collections) that the modern web does not index. This MCP server hands that world to an AI assistant directly: request a menu, follow a selector, fetch a document, no HTML parsing required.

Key Features

Dual Protocol Support: Access both Gopher and Gemini resources
Cross-Platform: Works on Windows, macOS, and Linux
Safe Browsing: Secure interaction with protocol resources
MCP Integration: Standard Model Context Protocol interface

The Small Internet

Gopher and Gemini represent alternatives to the modern web:

Gopher (1991): Hierarchical, menu-driven protocol predating HTTP
Gemini (2019): Modern minimalist protocol with TLS encryption

Both protocols focus on text content and simple navigation, offering a distraction-free reading experience that many enthusiasts prefer to the modern web.

What was hard

The key design decision was treating Gopher and Gemini as one protocol family behind a shared handler abstraction: each protocol implements the same fetch-and-describe interface, so supporting a new protocol means writing one handler rather than touching the MCP layer. Gopher's type system needed translation too. It predates MIME, marking each item with a single character (0 for text, 1 for menus, I for images), so the server maps those onto MIME types before content reaches the model. Safety came down to refusing to trust remote servers: response size caps, connection timeouts, and content type validation keep a misbehaving host on a 35-year-old protocol from breaking the assistant's session.

Project: OpenZIM MCP Server

c@meron.io (Cameron Rye) — Mon, 01 Jan 2024 00:00:00 GMT

import MCPToolDemo from '../../components/demos/MCPToolDemo.tsx';

export const openzimTools = [ { name: 'search', description: 'Search for articles in the ZIM knowledge base', request: { tool: 'zim_search', query: 'quantum computing', limit: 5 }, response: { results: [{ title: 'Quantum computing', snippet: 'Quantum computing is a type of computation...' }, { title: 'Qubit', snippet: 'A qubit is a quantum bit...' }] } }, { name: 'get_article', description: 'Retrieve the full content of a specific article', request: { tool: 'zim_get_article', path: '/A/Quantum_computing' }, response: { title: 'Quantum computing', content: 'Quantum computing is a type of computation that harnesses quantum mechanical phenomena...', word_count: 8420 } }, { name: 'list_zims', description: 'List all available ZIM files', request: { tool: 'zim_list' }, response: { files: [{ name: 'wikipedia_en_all', articles: 6500000, size: '90GB' }] } } ];

Put a Wikipedia ZIM archive on disk, point the server at it, and Claude can search and read those articles with the network cable unplugged. That is the whole pitch: retrieval that keeps working in air-gapped labs, classrooms with unreliable connectivity, and anywhere a live API is not an option.

Key Features

Offline Knowledge Access: Full Wikipedia and Kiwix content access without internet
High Performance: Fast search across millions of articles
Python-Based: Built with Python for easy deployment and extensibility
MCP Integration: Standard Model Context Protocol interface

Why offline access mattered

Most AI tooling assumes an always-on network connection and a live API behind every retrieval request. That assumption breaks down in classrooms, field work, privacy-sensitive environments, and any air-gapped deployment. OpenZIM MCP was built to prove that high-quality retrieval can still feel immediate when the knowledge base lives on disk instead of behind a network hop.

Performance strategy

The project focused on a few pragmatic constraints:

search should feel interactive even against multi-million-article archives
article retrieval should return clean, model-friendly content instead of raw archival formats
memory usage should stay low enough for modest developer machines and offline appliances

That drove the overall architecture: query the ZIM index efficiently, extract only the article payload that is needed, and normalize the result into an MCP response that is easy for an assistant to consume.

Product decisions

The strongest product decision was to make the server useful without requiring users to think about the details of the ZIM format. Developers care that the knowledge is offline and searchable; they do not want to learn an archive format first. MCP is a good fit here because it lets the complexity live at the boundary while the user gets a stable set of retrieval tools.

Outcome

I care about software that does not collapse the moment it loses the network. Pairing offline archives with an MCP interface makes local knowledge bases feel like first-class infrastructure for AI systems instead of second-best fallbacks.

Project: Retro Floppy

c@meron.io (Cameron Rye) — Mon, 01 Jan 2024 00:00:00 GMT

import RetroFloppyDemo from '../../components/demos/RetroFloppyDemo.tsx';

A 3.5" floppy disk held just 1.44 megabytes, yet it remains one of the most recognizable artifacts in computing. Retro Floppy recreates it as a React component, down to the details people actually remember: the spring-loaded metal shutter, the write-protect tab, the hub ring, and the hand-labeled sticker with its ruled lines.

What was hard

Getting the disk to feel physical came down to a handful of CSS decisions. The metal shutter slides open on hover with a cubic-bezier timing curve tuned to mimic the spring-loaded action of the real mechanism, rather than a stock easing that would read as a generic UI transition. Depth comes from layered gradients and paired inset shadows that suggest molded plastic rather than a flat illustration. And because the disk is interactive, it had to work beyond the mouse: the component exposes a button role, keyboard activation, and ARIA labels so the novelty never costs accessibility.

Theme Customization

Choose from built-in themes or create your own:

import { FloppyDisk, NEON_THEME, RETRO_THEME } from 'retro-floppy';

// Use a built-in theme
<FloppyDisk theme={NEON_THEME} />

// Or create a custom theme
<FloppyDisk theme={{
  diskColor: '#1a1a2e',
  slideColor: '#c0c0c0',
  labelColor: '#ffffff',
  labelBg: '#2d2d44',
}} />

Event Handling

The component supports click and hover events:

<FloppyDisk
  onClick={() => console.log('Disk clicked')}
  onDoubleClick={() => console.log('Disk opened')}
  onHover={(isHovering) => console.log('Hover:', isHovering)}
/>

Key Features

Interactive Design: Realistic floppy disk with sliding metal shutter animation on hover
Built-in Themes: Light, Dark, Neon, Retro, and Pastel themes included
TypeScript Support: Full type definitions with generics for type-safe props
Customizable: CSS custom properties and theme objects for complete control
Accessible: ARIA labels and keyboard navigation support
Multiple Sizes: Tiny, small, medium, and large size variants

Quick Start

npm install retro-floppy

import { FloppyDisk } from 'retro-floppy';
import 'retro-floppy/dist/retro-floppy.css';

function App() {
  return (
    <FloppyDisk
      label={{ name: 'My App', author: 'v1.0' }}
      size="medium"
    />
  );
}

Project: Uzumaki

c@meron.io (Cameron Rye) — Mon, 01 Jan 2024 00:00:00 GMT

import UzumakiDemo from '../../components/demos/UzumakiDemo.astro';

Uzumaki is an interactive spiral visualization app that renders ten mathematical spiral algorithms across web and Apple platforms. Each algorithm produces animated artwork, from the Fibonacci golden spiral to the chaotic Uzumaki pattern.

Spiral Algorithms

Each spiral follows a specific mathematical formula in polar coordinates:

Spiral	Formula	Natural Examples
Fibonacci	r = a * phi^(2*theta/PI)	Nautilus shells, galaxies
Vogel	theta = n * 137.5 deg	Sunflower seeds, pinecones
Archimedean	r = a + b * theta	Watch springs, coiled rope
Fermat	r = a * sqrt(theta)	Optical lenses
Logarithmic	r = a * e^(b*theta)	Hurricane formations
Curlicue	phi = 2PIphi*n^2	Fractal art

Technical Implementation

The web app uses Web Workers with TypedArrays for parallel spiral generation:

function generateSpiralTyped(params: SpiralParams): TypedSpiralPoints {
  const points = createTypedPoints(numSteps);
  const rotation = time * spinRate;

  for (let i = 0; i < numSteps; i++) {
    const theta = i * stepSize + rotation;
    const r = calculateRadius(i * stepSize, params);
    setPoint(points, i, r * Math.cos(theta), r * Math.sin(theta));
  }
  return points;
}

The Swift implementation uses SIMD for vectorized math operations, achieving the same 60fps performance on Apple devices.

Platform Features

Web/PWA: Shareable URLs, keyboard shortcuts, PNG export
iOS/iPadOS: Pinch-to-zoom, pan gestures, full-screen mode
macOS: Menu bar integration, keyboard shortcuts
watchOS: Digital Crown zoom, swipe navigation, complications

Project: Zero Crust POS Simulator

c@meron.io (Cameron Rye) — Mon, 01 Jan 2024 00:00:00 GMT

import ZeroCrustArchDemo from '../../components/demos/ZeroCrustArchDemo.tsx';

Zero Crust is a POS simulator that explores architectural patterns for quick-service restaurant operations. It features dual synchronized windows, modeling the hardware segregation found in production deployments where cashier and customer displays run on separate hardware.

Key Features

Dual-Head Display Simulation: Separate cashier and customer windows with real-time synchronization
Command Pattern IPC: Type-safe, auditable command system with Zod runtime validation
Integer-Only Currency: All monetary values stored in cents to prevent floating-point errors
Architecture Debug Window: Real-time visualization of IPC flow and state changes
Demo Loop: Auto-generates realistic order patterns for continuous operation

Security Model

Zero Crust implements six layers of Electron security:

Electron Fuses: Compile-time security flags that cannot be changed at runtime
Context Isolation: Renderer processes cannot access Node.js APIs directly
Zod Validation: All IPC commands validated with schemas before processing
Sender Verification: IPC handlers validate message origin against allowed sources
Navigation Control: Blocks unauthorized navigation and window.open calls
Permission Denial: Blocks all permission requests by default

The Broadcast Pattern

Instead of delta updates or complex synchronization logic, Zero Crust broadcasts the entire application state on every change:

// BroadcastService.ts - Subscribe and broadcast on change
this.mainStore.subscribe((state) => {
  this.windowManager.broadcastState(state);
});

This "full-state sync" pattern eliminates an entire category of bugs. Renderers always have the complete, consistent picture, and the performance cost is negligible for typical POS cart sizes.

Screenshots