I expected a fast car. I didn’t expect one with ten compressed-air propulsion nozzles using SpaceX-derived technology, plus an underbody suction system capable, according to Elon Musk, of pulling up to 2 G. During the demo, Tesla announced zero to 60 miles per hour, nearly 97 km/h, in 0.81 seconds. It did not disclose the measurement protocol.

This is the future I wanted to see.

The entire demonstration is in Tesla’s official livestream. Road & Track measured and described the maneuvers, while TechCrunch detailed the three versions: Performance with active aerodynamics and suction, Thrust with rear thrusters, and Rocket with a ten-nozzle propulsion system and a single seat.

Of course, we watched a prototype in a controlled demonstration. Tesla expects production to begin in 2028, and the Rocket version is not approved for public-road use. Still, an actual car left the ground, rotated, and landed. I watched it live from my office. It was spectacular.

While Musk was landing rockets and making cars fly, I was doing something far smaller and more mundane: fiddling with my websites.

Six sites in about a day

Before the Tesla event, I spent the entire day redesigning six sites:

• Akita’s AI Lair, now matching the look of my new book, Competent Enough;
• ai-memory;
• ai-jail;
• The M.Akita Chronicles newsletter;
• the newsletter archive;
• and this blog, AkitaOnRails.com.

They all started with variations of that default theme Claude makes. Dark background, purple or blue gradient, huge sans-serif type, rounded cards, a glow behind something. It works. It has also become so common that you can spot a “site made by Claude” before reading the title.

I had already tried asking Claude for different designs. It changed the color, moved the cards around, and delivered the same visual grammar. I posted some screens and the result of the change on Twitter. I’m no web designer, and for a while I accepted “it works.” Yesterday I got tired of it.

Someone suggested Stitch by Google. It’s an experimental Google Labs tool that turns instructions and images into editable interfaces and front-end code. The first version launched in 2025 on top of Gemini; the current version has become a design canvas with an agent, prototypes, and export to a DESIGN.md that other agents can follow.

I signed up, got the API token, and went to work. Stitch generated visual directions. Claude Code and Codex brought those directions into the real repositories, adapted the components, fixed responsiveness, replaced images, adjusted SEO, tested, and deployed. When one quota ran out, I continued with the other.

The six sites come from five repositories. Looking at them side by side made one thing clear: Stitch responds much better when it receives a concrete metaphor, the audience, and what the product needs to communicate. ai-memory became a memory archive. ai-jail became a cinematic prison. AI Lair adopted a 1950s and 1960s world’s fair, drawn from my book cover. The newsletter became a late-night broadcast, and this blog became an editorial archive. Five different identities instead of five variations of Claude’s same gradient.

The pretty prototype is the easy part. The job only ends when the visual language reaches internal pages, the article, the book reader, email, legal pages, error states, and mobile. That’s what the agents did inside the repositories. On ai-memory, for example, verification covered 102 pages in six languages, light and dark themes, desktop and mobile. On The M.Akita Chronicles, the same design had to work across signup, archive, newsletter detail, podcast, and the email template. A Stitch mockup solves none of that by itself.

Each site went through several rounds of prototypes. Some looked awful. Others had one good idea surrounded by bad decisions. I told the agents to throw them away, preserve one part, mix it with another attempt, and start over. Code is cheap now, so there is no reason to fall in love with the first version.

The result won’t win a design award. A professional designer would still find hundreds of things to improve. I know I could take it further by spending a few more days. It looks much better than it did, though, and for now it is competent enough.

Six existing sites redesigned, responsive, with SEO, image generation and replacement, HTML, CSS, and JavaScript adjustments, testing, and production deployment. One person. About a day. A year ago, that package would have taken weeks or months.

Keep the scale in perspective: these are small sites, mostly landing pages and content pages. Nobody is rebuilding Amazon.com’s entire collection of pages and systems in a day. The experiment shows how much repetitive work has already moved out of the way within a scope that one experienced person can understand and review. Large projects remain large, full of private rules, old integrations, strange states, and decisions that do not fit in a prompt.

Even the first proofreading pass can be automated

As part of the same process, I had agents review the sites as different readers. This wasn’t grammar correction. I wanted to know what someone would understand in the first few seconds, where they would get lost, which promise would sound suspicious, and whether they could complete a task without already knowing the product.

On ai-jail, I used two isolated sessions. One played a skeptical engineer who approves every prompt and had never heard of the project. The other was a non-engineer managing eight developers, trying to decide whether to approve the tool for the company. On ai-memory, I used three: an engineer learning AI tools, a manager evaluating a pilot, and a parent with no agent experience who worried about AGI and jobs. Each one read the site without seeing the others’ reports.

Anyone can do the same thing. Run the application locally or open a preview deployment, start fresh sessions, and give each agent a concrete task. A basic prompt can look like this:

Open this site on desktop and mobile: [URL].

You are [persona], know [context], and have never seen this product.
Your goal is [specific decision or task].

Navigate as this person. Do not read code or internal documentation first.
Record:
- what you understood in the first ten seconds;
- what you think the product does and who it is for;
- where you did not know the next step;
- contradictory, absolute, or hard-to-believe promises;
- terms the site uses before explaining them;
- reading, keyboard, contrast, touch, and responsiveness problems;
- what would stop you from trying, buying, or approving it.

For every finding, show the page and visible evidence.
Separate factual bugs, usability problems, and subjective preferences.
Do not propose a broad redesign. Suggest the smallest change that solves the problem.

I prefer three independent sessions over an agent roundtable. Once one reads another’s report, it starts agreeing by inertia. A separate session can then consolidate repeated points, discard matters of taste, and check every claim against the code and product documentation. A review can flag a sentence as wrong; it has no authority to invent the right one.

The most useful results tend to fall into four groups: positioning, information order, path to the first action, and trust. Traditional automated tests still handle broken links, contrast, accessibility, overflow, and error states. The persona tells you that a technically accessible button appeared five screens below where the person needed it.

During the ai-jail proofreading, both profiles agreed that the site took too long to show a concrete risk and started speaking like engineering documentation too early. The threat of a poisoned page moved directly below the hero. New sections explained “What changes on day one” and “For the person who must approve this,” including operating cost, limitations, and the keys a company actually exposes. The review also caught a technically incorrect claim repeated across several pages: the network does not stay entirely off by default. The agent’s own API host and, on Linux, registries remain accessible. This kind of reading catches documentation bugs too.

The ai-memory report found permissions described in contradictory ways, privacy promises that were too absolute, and the basic explanation buried under advanced features. During the second round, the profiles noticed that remote-access instructions told users to use HTTP before requiring TLS, that an unauthenticated curl promised the wrong response, and that important choices appeared far too late on mobile. The collection guide moved from about 4,364 pixels from the top to 1,617; the individual and team paths moved from 5,300 to 2,489. That’s an objective improvement born from simulated reading.

In the AI Lair redesign, the new-reader review reorganized the entry path. A later revision made it explicit that my setup with multiple agents and two monitors is a mature configuration, not a requirement for starting. One person, one project, and one agent are enough. It also produced a pilot plan for managers: a reversible task, non-sensitive data, an acceptance criterion, deadline, budget, and measurement. The next audit found invalid ARIA and an animation that hid the opening copy from assistive technologies; the fix took axe-core from four serious violations to zero.

Simulated personas still fall far short of human feedback. They carry the models’ same biases, may agree with the prompt, never feel the irritation of someone who lost twenty minutes, and never take the risk of entering their own credit card. The reports serve as hypotheses. A real user will always find the case that I, the agent, and the test suite failed to imagine.

Before the first user exists, however, the alternative is usually no review at all. Two or three independent readings already catch contradictory promises, unexplained jargon, buried information, and a flow that only makes sense to its author. These readings cost little and make the product less stupid before it reaches actual people.

HTML was never programming

For years, I watched people perform some remarkable mental gymnastics to argue that “HTML is a programming language” and therefore anyone who writes HTML is a programmer.

HTML is markup: it describes a document’s structure. CSS describes presentation. That has value, requires knowledge, and can become terribly complex. Accidental complexity does not turn markup into programming.

There is no shame in that. I started building sites in the 1990s. I received a Photoshop layout and turned it into HTML. I sliced images, built tables, adjusted pixels, opened the result in multiple browsers, went back, and tried again. It was honest work and paid my bills.

It was also basically mechanical work: copy, paste, adjust, look, repeat. Exactly the category computers should automate.

Today I still chose the visual direction, rejected bad proposals, decided what each site needed to communicate, and recognized when the result was good enough. The agents handled the grunt work. This should have happened years ago.

The bubble delayed automation

For much of the 2010s, US interest rates stayed near zero. Cheap money flooded funds, startups, and large companies. Hiring more people was easy, and the market absorbed any amount of manual labor disguised as engineering.

Low rates explain only part of tech’s expansion. A field breaking hiring records has little incentive to eliminate its own repetitive work. If you can put fifty more people to work assembling screens, you put fifty more people to work assembling screens.

Anyone who attended my talks at tech events in the 2010s may remember Constraint == Innovation. Yes, the original title used two equal signs. I gave that talk at DevConf 2019, the 83 slides are on my SlideShare, and I had already written the same argument in 2013 in “Constraints are liberating: less is more”.

It’s the old maxim: necessity is the mother of invention. Constraints force choices. Choices force priorities. When the conventional path cannot fit the money, deadline, or available capacity, someone has to find another path. That’s where real innovation often comes from.

Money funds expensive research, buys equipment, and gives people time to experiment. Excess money without pressure for results does something else: it hides inefficiency with brute force. There is no need to automate, simplify, or discover a better solution while you can keep hiring and growing the spreadsheet. Too much abundance turns a technical problem into an operating expense and postpones the difficult decision.

I repeated this warning at the beginning of 2026: the programming bubble managed to replace efficiency with volume. Constraints returned when cheap money ended. Coincidentally, agents arrived at the same time and gave companies a practical way to automate the mechanical work they had spent a decade scaling through hiring.

That’s how we spent a decade recreating the same admin dashboard and calling it innovation. Every week brought the next front-end savior: React, Angular, Vue, Svelte, another bundler, another framework on top of the framework. They are useful tools in the right context, but none addressed the obvious question: why is a human still hand-writing the thousandth variation of the same form?

The hiring bubble burst in 2022 and ended the party. At the end of that year, ChatGPT brought language models to the public. GPT-2, just to keep the chronology straight, had come out in 2019. Four years after ChatGPT, agentic programming became a normal work tool.

Any task that consists of copying a pattern, adapting an example, running it, looking at the error, and trying again is already within these agents’ reach. Front-end is the most visible target because it accumulated an absurd amount of this work. The rest of programming has no mystical shield. Plenty of back-end work is CRUD, glue between APIs, and repetitive configuration. That will be automated too.

Fine by me. Programming was never about typing code. Programming is making a computer do something useful.

VS Code is the new punch card

I wrote about exactly this in April in “VS Code Is the New Punch Card”.

For decades, the interface between intention and computer kept changing. First you connected wires and switches. Then you punched cards. Then you wrote Assembly, C, high-level languages, frameworks, and configuration. Each generation looked at the previous one and automated another layer of manual work.

No sane person would argue today that operating a card punch was the essence of computer science. It was the available interface. Typing every tag and CSS rule into VS Code was also the available interface.

Now I describe the intention, show references, evaluate the result, and tell the agent to fix it. I still need to understand browsers, networks, caching, accessibility, semantics, responsiveness, and SEO. Without the fundamentals, I couldn’t tell whether the agent delivered a solution or a pretty time bomb. The keyboard lost importance; judgment gained it.

Today, every Tier A model I test, from Claude to Kimi, can reliably execute the mechanical front-end work that appeared in these six projects. I can say without hesitation that any front-end task that merely turns an already-made decision into code is automatable. They needed direction to create the six designs. None required me to hand-write the flexbox, breakpoint, or component I had already explained.

That covers an enormous share of the work while leaving the most valuable part. Someone still has to know the framework’s tradeoffs, understand the browser, choose the architecture, notice when a library is being forced against its design, and find out why an apparently correct solution breaks under a particular combination of device, language, state, and real data. The agent writes the code; an experienced professional provides direction, limits the damage, and owns the result.

Front-end still exists. The excess mechanical work and the people hired only to follow a finished recipe lose value. A great front-end professional can direct agents and deliver far more than they could alone. A mediocre professional who spent years mistaking component typing for engineering will compete for fewer openings. The market gets smaller and more selective, with its best professionals producing more. The goal remains what it always was: get close to the top, where judgment and experience still make a difference.

And it doesn’t stop at the browser. Pick the framework: Android with Flutter or Kotlin, iOS with Swift and SwiftUI, desktop with Rust/Tauri, Flutter, C#, or Electron. Modern agents generally know the components, build tools, tests, and peculiarities of these platforms. They still need direction, feedback, and verification, just as they do on the web front-end. The mechanical part is already automatable.

I tested this in my own small open-source projects. FrankYomik has a Flutter client for Android and Linux, plus the server and extension. Frank Sherlock is a Rust/Tauri desktop app that produces an AppImage for Linux, a DMG for macOS, and a .exe installer for Windows. I also built Frank Karaoke in Flutter for Android and FRANK MANGA+ in Rust/Tauri for desktop. There are several others on my GitHub.

None came out perfect from the first prompt. Flutter and Tauri gave me trouble, especially on the early projects. Reliable means the agent can move forward, receive a correction, create tests, fix what broke, and reach a working application without making me take over the manual typing. After testing web, Android, and desktop across different stacks, I’m very satisfied with the result. The pattern repeats: mechanical work became agent work.

At two in the morning, I had agents making the final adjustments to this blog without losing pace. That’s what I need.

When the web still didn’t know what it was

At the peak of the dot-com bubble, career designers were creating websites. The web had not yet decided how a page should work, so there was real room to experiment. It was often ugly and almost always heavy, but actual creation was happening.

The iPhone opened another window in 2007. Suddenly everything had to fit on a small screen, respond to touch, and work without a mouse. Years of experimentation followed before the market settled on a reasonably stable grammar for navigation, gestures, forms, and content.

Today nobody needs to rediscover a menu, a list, a checkout, or an article page. The patterns are documented, millions of examples are public, and models have seen more interfaces than any person could study in a lifetime.

The most valuable work remains: understanding the product, the person who will use it, the constraints, and what deserves to appear first. Converting a finished decision into hundreds of predictable lines has become a perfect candidate for automation.

Jobs disappear. Others appear

The world has never stopped to preserve a job function.

Punch-card operators entered data and programs on paper cards. Telephone operators physically connected calls. Typists kept offices running. Linotype operators cast lines of hot metal to print newspapers. Technology reduced or eliminated these occupations at scale. The Bureau of Labor Statistics’ current list of fastest-declining occupations still includes data entry keyers, typists, and telephone operators. Nobody proposes bringing them back to protect jobs.

At the same time, jobs appeared that a person in 1926 could not even name: mobile developer, SRE, experience designer, Internet video creator, cloud specialist, machine learning engineer. The web itself killed old work and opened an entire industry.

The real story is messier than the caricature. The ILO shows that technology tends to automate tasks without necessarily eliminating entire occupations. Some functions shrink, others change, and new jobs appear. That statistical consolation does nothing for the person who became obsolete today. The individual has to react before the economic average reacts for them.

Compare 2026 with 1926, three years before the crash of 1929. It looks like another planet, even though a century is very little on history’s scale. No contract guarantees that your current function will survive the next ten years, much less the next forty.

How does a junior gain experience now?

It will get harder. The old ladder began with someone paying a beginner to assemble simple screens, fix CSS, and copy components. An agent does much of that faster and cheaper. No company has an obligation to preserve inefficient work as a training program.

Beginners will have to build their own ladder with real projects and problems they are responsible for. That includes reading the code the agent generated, breaking and repairing it, studying documentation and source code, writing tests, and contributing to open projects. An agent gives any student access to an amount of practice that once required a team. Anyone who uses that access only to generate code they do not understand will remain a junior for a long time.

The market will reward people who make that extra effort. It always has. When someone asks how a junior can gain experience without the easy tasks, the hidden question is often different: “how do I get a better salary without doing the hard work of getting good?” The easy position, with rising pay and little pressure, was a distortion of the bubble. Adapting includes accepting that entry has become more competitive.

My career never stayed in one place

I started with multimedia and static websites. Then I worked in a digital agency, enterprise consulting, SAP integration, startups, video, education, and now AI. In my Akitando episode about SAP, I tell part of that phase when I had to learn a world completely different from what I had done before.

I lived through the dot-com crash, the 2008 crisis, and the end of the zero-rate bubble. I survived because I never treated my current function as a permanent identity. I kept studying, gaining experience, and changing direction.

A productive career should not consist of repeating the same mechanical task for decades. If your value depends on the market continuing to pay someone to push tags and pixels by hand, the problem did not begin with AI. The problem was betting that the present would last forever.

Many people understand “being prepared” as studying the bare minimum required for today’s open position. That’s the fastest recipe for becoming obsolete. Do the short-term work, but study beyond it. Learn the things that seem useless today. Fundamentals, operating systems, networks, databases, business, economics, history. You don’t know which combination will save your career five years from now.

I spent years talking about this on Akitando. Revisit the I Warned You and Which course should I take? playlists. If you have to start with one video, start with the Definitive Guide to Learning How to Learn. No course can save someone who still outsources their own learning.

The world has no shortage of opportunity. Most people feel they never get one because they are always unprepared when it appears. Once the opportunity lands in front of you, it is too late to start preparing.

So I won’t mourn the fact that this package of six small sites, which used to take weeks or months, fit into about a day. I’m happy as hell. I gained time to think about what to build, experiment more, and throw away bad versions without wasting weeks of my life.

Today I watched a car spin in midair and land. In about a day, I put six sites with new designs into production without writing most of the HTML and CSS. The future I wanted did not arrive perfect, cheap, or evenly distributed. It arrived far enough for me to work with it.

Accept what ended. Study what comes next. Be ready before the next opportunity appears.

And the recommendation comes right up front, because it’s the reason this article exists: don’t use other people’s skills. Read that again. My skills are published on my my-skills repository and the repo description warns you: “not tailored for general usage”. They’re there so you can read the reasoning, understand the structure, and go build your own. Copying somebody’s skill and running it blind is the digital equivalent of signing a contract without reading it. Worse: it’s installing someone else’s instructions to run with your permissions, on your repositories, with your tokens. That’s prompt injection you install voluntarily and say thank you for.

What a skill really is

No magic involved. A skill is a directory with a SKILL.md inside: a header with name and description, and a body of text that is, essentially, a well-written prompt about how to execute a task. Sometimes it ships with a scripts/ folder of helper scripts, so the LLM doesn’t have to recreate them from scratch every time.

Skills are just prompts.

That’s it. A prompt you versioned, refined, and kept one command away. The only difference between a skill and that giant prompt you paste into the chat every day is that the skill lives in a file, with a name, and the agent knows it exists.

And here’s the answer to the question everybody asks: “doesn’t that fill the context with junk?” The good news is the harnesses do this right. Claude Code uses what Anthropic calls progressive disclosure: at session start, only each skill’s name and description go into the system prompt. The SKILL.md body only loads when the agent decides to invoke the skill. OpenCode does the same: lists name and description, loads content on demand through its own tool. Anthropic itself documents the design: metadata first, body only when needed.

That solves the text cost, but only half the problem. Every installed skill still takes a line in the listing, and more importantly: it competes for the agent’s attention when it decides which tool to use. Anthropic again, on the engineering blog: “more tools don’t always lead to better outcomes”, and their official recommendation is a few well-designed tools for high-impact workflows. My version of that rule is more acidic:

An idle skill is debt.

You change your process, the skill ages, and one day the agent executes a rule that no longer makes sense in your workflow. Fewer skills, better written, reviewed often.

The only third-party skill that survived here

Having said all that, it would be hypocritical to pretend I live on homemade skills alone. One survived my scrutiny and runs on every post on this blog: Humanizer.

It exists because the Wikipedia community maintains a public, brutally honest catalog called Signs of AI writing, kept by WikiProject AI Cleanup, documenting the “tells” of AI-generated text one by one: the rule of three, the “not just X, but also Y”, the puffery, the emoji-decorated bullet. Humanizer turns that catalog into a procedure: the agent receives the text, marks the tells from strongest to weakest, rewrites preserving every supported claim (losing a fact is an error, inventing a fact is an error), and does a final read-aloud check. Without changing what was said, only how it was said.

If you produce content, you know why I insist: text that smells like AI is becoming the new “Dear Sir”, the mark of a rushed form letter. I run Humanizer on every article before publishing, including this one. But note the detail: I merged version 3.0.0 into my repo, with my own adjustments. I read the source material before trusting it. That’s the pattern.

What I do with this every day

Now the practical part. I maintain and monitor over 40 repositories on GitHub. My own projects, forks I maintain, tools that became daily dependencies. To stay sane, my second monitor runs tclock (my fork of clock-tui, with Evangelion themes, because why not) and next to it ghpending, a Rust CLI that lists open issues and PRs from all my repos at once.

In the photo you can see: ai-memory and ai-usagebar with open PRs and issues. Every morning I open the harness on each project with ai-memory run in its directory. ai-memory deserves a paragraph: it’s my long-term memory project for agents, a persistent Markdown wiki that captures session observations, consolidates decisions and gotchas into pages, keeps workstreams across sessions and handoffs between agents. Every project of mine has its own memory, with the architectural decisions and the traps only that codebase has. Without it, every agent session starts from zero like an intern with amnesia.

From there the daily ritual is almost childishly simple. I write, literally:

run pr-audit and iss-audit, then run github-resolution

When a release is ripe, I add then run the release skill. On days when the only queue is Dependabot’s automatic bumps, it’s run pr-bump and release and done. One line of instruction from me. The heavy lifting lives in the skills. Let’s get to them.

pr-audit

PR audit before merge, and the central principle is: evidence over narrative. Nothing the contributor wrote is treated as truth; everything is a claim to verify, with a claims ledger (confirmed, partial, unsupported). The rest of the skill is a hostile checklist:

• Change gate: hunk inventory looking for executable bits, symlinks, bidirectional characters, homoglyphs, pull_request_target workflows, unpinned actions, typosquat dependencies, lockfile drift.
• Credentials: unexplained credential access is an instant blocker. Execution happens in an isolated worktree, with no host credentials.
• Semver: the changelog category is a version gate; breaking changes go in major, never in patch. A rule that has saved me more than once.
• Prompt injection: text inside a PR trying to “change the audit rules” is just one more suspicious data point to investigate. It’s an audit finding, obviously.

iss-audit

The same distrust, applied to issues:

• Never run a command copied from an issue. Attachments only go through an isolated scanner.
• Formal separation between what was observed, what was expected, the reporter’s diagnosis, and the proposed fix.
• Reproduction with synthetic data in a disposable sandbox, with resource limits for DoS claims.

And two golden rules I love: “a number that moves is not a pinned number” (async lag looks like a bug) and “the obvious owner may be innocent” (query the suspect population; if it comes back empty, the cause is elsewhere).

github-resolution

The execution phase: turning what the audit approved into merged code. The rules:

• Only execute approved tickets, one at a time, with a regression test written before the fix. “Slop is a defect”: no speculative abstraction, no TODOs, no drive-by refactors, no weakened tests.
• If I resolved more than three tickets in a session, run the post-audit over the whole range before pushing, no exceptions.
• A ticket closes when the fix is merged with green CI on that exact SHA, never left hanging waiting for a release.
• Every unresolved issue gets logged with the reason. Compressing it into a number is forbidden.

pr-bump

The fast path for Dependabot’s dependency bumps. The rule that saves me the most time: batch, never serialize. Instead of merging PR by PR, one consolidated bundle update to the latest compatible versions, a single CI pass for the whole set, fix forward on whatever breaks.

But there’s a supply-chain floor:

• Every dependency must resolve on the public registry (rubygems, npm, pypi) with the expected name, version, and checksum.
• Git source, path source, typosquat-adjacent name, new install hook: full stop, it goes to a complete audit.

bundler-audit will happily pass a well-formed trojanized gem. That’s exactly the case the floor covers.

release

Cut a version only when I ask. The iron rules:

• The version comes from the changelog classification: fixes go in patch, additive changes in minor, breaking in major. A number that conflicts with the classification forces me to confirm; silent bumps are forbidden.
• Green CI gate on the tag’s exact SHA. Never tag with pending or skipped CI.
• Annotated tag, updated changelog.
• Never rewrite a published tag. Never cut a release nobody asked for.

The numbers, because numbers don’t argue

Counting right now, on the day I write this article, across just three projects (ai-memory, ai-usagebar and ai-jail):

• ai-memory: 430 merged PRs, 260 closed issues
• ai-usagebar: 137 merged PRs, 34 closed issues
• ai-jail: 42 merged PRs, 81 closed issues

Total: 609 merged PRs and 375 closed issues, over a thousand items. Nearly all of that was handled by these skills, with me supervising and deciding. One person, no team, keeping three active projects at this volume. That’s the multiplier.

And they weren’t born ready

Open the my-skills commit history and you see skills being polished the hard way. July starts the repo with the basic audits. Late July: “harden audit skills and add security audit”. August: “consolidate agent skills from all harnesses into this repo” and, days later, github-resolution is born as the execution phase of the audits. September: “fold in release-discipline and audit lessons”.

And just yesterday, look at the level of fine-tuning in pr-bump: “batch all bump PRs into one consolidated verification pass, fix forward on failures” and “require deferred/declined PRs be left in a clean state”. Two rules that became skill text. Neither came from a blog post or somebody’s opinion: they came from me face-planting into the exact error the rule now prevents.

Every line in these skills is a scar.

That’s how you write a good prompt: watch the result, decide to adjust, adjust again.

Skills are little. Knowledge is a lot.

Now the counterpoint, because I don’t want you leaving here thinking skills are the answer to everything. I depend on them very little. What actually carries my workflow is something else.

Every project of mine has its own AGENTS.md, instructions specific to that code, and its ai-memory memory with decisions and gotchas. And the pattern I use most day to day isn’t even a skill: it’s pointing at a living example. When I wanted automated AUR packaging for clock-tui, I didn’t write a “how to make an AUR package” skill. I opened the harness and said:

make a similar github action to build and publish AUR packages
as we did in ~/Projects/ai-memory

The agent went there, read the workflow that works, and reproduced the pattern in the new project. A skill for that would be worse: AUR changes, GitHub Actions changes, the example gets stale. A living example in a repo I maintain is always up to date by definition, because when it breaks, I fix it.

Every project becomes its own knowledge base.

And this generalizes, because harnesses can consume any text base. My entire Linux PC is documented and reinstallable from a config repo of mine, and my homeserver is fully described in runbooks. Those two are not on GitHub: they live on a private Gitea server I maintain, because that’s the kind of thing I don’t want leaking in public. When I want to change something at home, I say:

add integration to my Plex server as documented in my homelab runbooks

That’s not a skill. It’s organized, versioned, searchable knowledge. Skills are for procedures that repeat the same way. Knowledge is for everything else.

The recommendation worth more than any skill

If you take a single practice from this article, take this one: have your agent write down everything that didn’t become code. The research it did, the decision you made and why, the comparison with the rejected alternative. Without that, the knowledge evaporates at the end of the session.

My ai-memory, for instance, has a docs folder with competitor research I commissioned before every big decision:

• The Karpathy wiki pattern, the project’s intellectual origin.
• A 2026 landscape survey, covering Zep/Graphiti, Letta, Mem0, and Google’s Open Knowledge Format.
• Deep dives on each competitor: Hindsight (the one with a paper and funding, which ended up validating my design bets), cognee (pretty graph pipeline, ugly gateway bug), agentmemory (I kept the ideas, threw out the substrate), basic-memory.
• And my favorite, the MemPalace autopsy: 47k stars, viral, and a tracker clogged with index corruption and lost data. The fairy tale in reverse that confirmed for me why compiling memory beats stockpiling verbatim.

Dozens of documents like that. Every hour of research an agent did for me became a permanent asset, reusable in any new project. The more you produce and document, the more intelligence you accumulate.

It’s compound interest for knowledge.

Nobody knows what you need

And there the circle closes, back to where we started: why I don’t recommend copying anybody’s skills, mine included.

Because my PR audit skill is molded around my projects, my languages, my risks, my level of supply-chain paranoia. It reflects what I, Fabio, maintaining the repositories I maintain, on the infra I have, with the goals I have, needed to write into it. Your project has another stack, other risks, another tolerance level. You may need checks I don’t, and vice versa. Experience is only relevant to whoever lived through its constraints. That changes from person to person, and that’s exactly why a third-party skill used blind is a gamble.

That’s the thesis of my 2019 video, Don’t Outsource Your Decisions: the most important lesson of your life (in Portuguese): nobody but you knows what you need.

I don’t ask anybody. I research, I build mine, and the skills are the versioned record of my decisions. The beauty of LLMs is they speed this process up tenfold: the research that took a week now takes an afternoon, and the cost of building your own tool fell through the floor.

A good skill is your own. Mine are on my-skills so you can read the reasoning. Then close the tab and write yours. I don’t waste time asking for other people’s opinions. Neither should you.

Email has always been the most annoying piece of this puzzle. My old workflow was to open Thunderbird, let it pull everything from Gmail over IMAP, and back up the ~/.thunderbird directory. Works, but it’s manual, tedious (remembering to open Thunderbird every so often), and locked to Thunderbird itself: if I want to read those emails in another client, they’re sitting in some proprietary internal format.

After a while it clicked: Linux has had native email support forever. The modern protocols (IMAP, SMTP) are open standards. And the local storage format, Maildir, has been around and working well since the 90s. Thunderbird isn’t needed for any of this.

What is Maildir

Maildir was created by Daniel J. Bernstein (djb) as part of qmail in 1995. The idea was to fix the file-locking pain of the mbox format, where the entire mailbox is a single file and two processes writing at the same time could corrupt the whole thing. In Maildir, each message becomes a separate file inside a three-subdirectory structure:

• tmp/ — where the email is written while being delivered
• new/ — newly arrived messages, not yet seen
• cur/ — messages the client has already seen, with flags encoded in the filename (:2,S = seen, :2,F = flagged, etc.)

Delivery is atomic: the MTA writes the message into tmp/, then does a rename() into new/. rename() on a POSIX filesystem is atomic, so there’s no corruption window. No locking, no corruption, and every email is just a plain-text file you can read with cat, index with grep, or version with git if you feel like it.

Thirty years later, it’s still the default local format for most Linux email clients. And it’s the format I’ll use to mirror Gmail.

The tool: mbsync (isync)

The bridge between Gmail’s IMAP and the local Maildir is mbsync, the binary in the isync package. It reads a simple config (~/.config/isyncrc), connects to Gmail’s IMAP, and copies the messages to disk. What makes it different from offlineimap (the better-known alternative) is that mbsync is written in C, it’s significantly faster on large mailboxes, and it has fewer weird edge cases with Gmail.

The config is straightforward. Here’s a sketch of what my ~/.config/isyncrc looks like (no password, obviously):

IMAPAccount my-account
Host imap.gmail.com
User you@example.com
PassCmd "/home/akitaonrails/.config/mbsync/bin/mbsync-password you@example.com"
TLSType IMAPS
CertificateFile /etc/ssl/certs/ca-certificates.crt
AuthMechs LOGIN

IMAPStore my-remote
Account my-account

MaildirStore my-local
SubFolders Verbatim
Path ~/.local/share/mail/mbsync/you.example.com/
Inbox ~/.local/share/mail/mbsync/you.example.com/INBOX

Channel my-backup
Far :my-remote:
Near :my-local:
Patterns * !"[Gmail]/Trash" !"[Gmail]/Spam" !"[Gmail]/Drafts"
Create Near
Sync Pull New Flags
Expunge None
Remove None

Three things worth flagging in that config:

1. Sync Pull: only pulls from the server to local. Nothing I do in the Maildir propagates back to Gmail. That’s accident protection (if I delete a file locally, it doesn’t disappear from Gmail).
2. Expunge None + Remove None: if a message disappears from Gmail (someone deleted it or Google decided to move it nowhere), it stays in my Maildir. The backup accumulates history, it doesn’t mirror the current state.
3. PassCmd instead of a plaintext password: the password goes through a script that does secret-tool lookup against the desktop keyring. No password sitting in a config file on disk.

The password block

The mbsync-password script is a tiny wrapper that isolates the secret:

#!/usr/bin/env bash
set -euo pipefail
account="${1:?usage: mbsync-password ACCOUNT}"
password="$(secret-tool lookup service mbsync account "$account" 2>/dev/null || true)"
[ -z "$password" ] && { echo "missing keyring secret for $account" >&2; exit 1; }
printf '%s' "$password"

The password gets stored once with secret-tool store --label="mbsync gmail" service mbsync account you@example.com. Modern Gmail requires a specific app password (16 characters, generated at myaccount.google.com/apppasswords) because it no longer accepts plain basic auth — you don’t paste your Google password there, you paste a key generated exclusively for the app, revocable any time without touching the rest of your account.

Automation with a systemd user timer

To avoid running mbsync by hand, I set up two systemd user units. First the service, which is just a call to the wrapper script:

# ~/.config/systemd/user/mbsync-backup.service
[Unit]
Description=Mirror Gmail accounts locally with mbsync
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
ExecStart=%h/.config/mbsync/bin/mbsync-run

And the timer that fires the service periodically:

# ~/.config/systemd/user/mbsync-backup.timer
[Unit]
Description=Run mbsync periodically

[Timer]
OnBootSec=10m
OnUnitActiveSec=30m
Persistent=true
Unit=mbsync-backup.service

[Install]
WantedBy=timers.target

OnBootSec=10m waits 10 minutes after boot before the first run (avoids fighting with network-online early in the session). OnUnitActiveSec=30m refires 30 minutes after each run completes. Persistent=true makes the timer catch up: if the machine was off when it would’ve fired, it runs at the next boot instead of skipping. The wrapper itself grabs flock so two mbsync runs never overlap, so if a sync ever takes longer than 30 minutes the next one just waits. Everything logs to ~/.local/state/mbsync/mbsync.log.

To manage the timer, the basic commands:

# Re-read the unit files after creating/editing
systemctl --user daemon-reload

# Start now + enable for the next boot
systemctl --user enable --now mbsync-backup.timer

# Check whether the timer is active and when it fires next
systemctl --user status mbsync-backup.timer
systemctl --user list-timers mbsync-backup.timer

# Trigger an immediate sync without waiting for the interval
systemctl --user start mbsync-backup.service

# Tail the logs in real time
journalctl --user -u mbsync-backup.service -f

# Inspect the status of the last service run
systemctl --user status mbsync-backup.service

# To shut the whole thing down
systemctl --user disable --now mbsync-backup.timer

For the timer to keep running when you’re not logged in (handy on a desktop that stays up 24/7), enable linger once: sudo loginctl enable-linger $USER. Without that, user units only run while you have an active session.

Enable it, check the status once to make sure it’s green, and forget it exists.

Backing up the Maildir with restic

Now that Gmail is mirrored under ~/.local/share/mail/, it rides into the same backup pipeline as the rest of my home directory. I use restic to push encrypted snapshots to the NAS. Restic is incremental via content-addressable storage, so adding 100MB of email to today’s snapshot costs basically the delta, not the full 100MB every time. For the off-site copy, my Synology NAS already has the Glacier Backup package built in, which handles pushing encrypted snapshots to AWS Glacier without me having to configure anything beyond the bucket and the key. The Maildir rides along on the same plan, so the off-site backup is essentially free in terms of extra configuration.

Maildir is friendly to incremental backup by construction: every email is an immutable file (the filename doesn’t even change after download, except for the seen/flagged flag bit). Restic dedups perfectly. A 5GB mailbox snapshot has near-zero marginal cost after the first one.

The open-format upside: many clients

Here’s the part that sealed it for me. Maildir is an open standard, so any client that speaks Maildir reads the same backup. I can:

• Open it in mutt or neomutt when I want something quick in the terminal.
• Open it in aerc when I want a more modern TUI.
• Point Thunderbird or Claws Mail at ~/.local/share/mail/... when I want a GUI.
• Migrate to a different client down the road without an export/import dance.

The emails are mine. They live on my disk. In a plain text format, readable by anything.

Bonus: scripts and bots read directly

A less obvious consequence: if I want to build a filter, a bot, a classifier, or anything that touches the emails, I don’t need to go through Gmail OAuth, create a Google Cloud project, manage refresh tokens, deal with quotas — none of it. I just read the Maildir.

Python has native Maildir support in the standard library’s mailbox module. A trivial example to list subjects from the inbox:

import mailbox
from email.header import decode_header

inbox = mailbox.Maildir("/home/akitaonrails/.local/share/mail/mbsync/you.example.com/INBOX")

for key, msg in inbox.iteritems():
    subject = msg.get("Subject", "")
    sender = msg.get("From", "")
    # decode_header handles Subject in UTF-8 / latin-1 / etc
    decoded = "".join(
        part.decode(enc or "utf-8") if isinstance(part, bytes) else part
        for part, enc in decode_header(subject)
    )
    print(f"{sender[:40]:<40}  {decoded[:60]}")

Runs in milliseconds, consumes zero API quota, has no rate limit, never needs a credential refresh. It’s just file reads. If you want to build something more serious (attachment parsing, LLM-based classification, automated rules), the same principle holds.

Summary

The combination that finally let me relax about this:

• mbsync (isync) pulls from Gmail’s IMAP into a local Maildir, automatically via a systemd timer.
• Maildir keeps the open format, one file per email, pull-only protects against accidental deletion.
• restic snapshots the Maildir to the NAS with ridiculous deduplication, and Synology’s Glacier Backup carries that off-site as an encrypted copy.
• Free choice of mail client — mutt, neomutt, aerc, Thunderbird, Claws, anything reads it.
• Light automation — bot or script reads straight off disk, no OAuth, no API.

Gmail becomes just a convenient web interface for reading and replying. The real ownership of the emails sits on my disk, replicated to the NAS, replicated to an encrypted off-site backup. If Google shuts my account down tomorrow (it’s happened to people), I lose the interface but keep the entire history. For me, this is the definitive way to handle it. Recommended.

I know there are plenty of tools that solve this. But I wanted something dead simple and fast to run in the terminal so I can see pending work across all my projects at once. So I built it: ghpending.

Runs on Linux and macOS. I tested on Linux (Arch + Omarchy) but haven’t run it on macOS yet. If you try it there and hit a bug, file an issue at github.com/akitaonrails/ghpending/issues.

Install

Three paths, pick whichever fits your setup.

Via Homebrew (macOS or Linux):

brew tap akitaonrails/tap && brew install ghpending

Via Cargo:

cargo install ghpending

Via mise:

mise use -g github:akitaonrails/ghpending

Upgrading

# Homebrew
brew upgrade ghpending

# Cargo
cargo install ghpending --force

# mise
mise upgrade ghpending

# From source
cd ghpending && git pull && cargo install --path .

Usage

Four commands. The normal flow is to run ghpending add once to set up which repos you want to track, then just ghpending whenever you want to see the digest.

ghpending add    # pick repos from a GitHub user or org to track
ghpending        # print the digest of open issues and PRs
ghpending list   # show tracked repos
ghpending rm     # remove repos from tracking via interactive menu

add asks for a user or organization, lists their public repos, and lets you check off the ones you want to follow. The username gets saved, so re-running add skips that prompt.

The main command (ghpending with no args) fetches every tracked repo concurrently and prints the table with open issues and PRs.

GitHub token (optional)

It works without auth, but GitHub caps anonymous traffic at 60 requests per hour. To raise that ceiling to 5,000 req/h, export a token:

GITHUB_TOKEN=$(gh auth token) ghpending

It’s read silently at startup, no config needed.

Where the config lives

• Linux: ~/.config/ghpending/config.toml
• macOS: ~/Library/Application Support/ghpending/config.toml

You can edit it directly if you want to reorder repos or change the user. Shape:

user = "akitaonrails"
repos = ["akitaonrails/ai-memory", "akitaonrails/ai-jail"]

Why this CLI exists

The honest answer: tools I build for myself, I use. Tools written by other people always come with some friction (web login, a different architectural opinion, a feature I wanted missing or one I didn’t want included). Since the goal was to reduce the friction of checking 30 repos a week, 200 lines of Rust on a Saturday afternoon beat learning a new stack.

Now I’m hoping I can respond to contributors faster. If you find it useful, it’s MIT licensed, PRs are welcome.

On my YouTube channel I even used old games to teach computer science fundamentals. In this Akitando episode about Super Mario and old computers, I explain the 6502, memory maps, the PPU, hardware constraints, and why those games were programmed the way they were. If you never watched it, start there:

The problem is always the same: every few years I decide to set up a new emulation machine, download the main emulators again, and there I go repeating the same masochistic ritual. PCSX2, RPCS3, Eden, Azahar, Dolphin, RetroArch, Flycast, shadPS4, and so on. Each one with its quirks. Each one with its own particular way of wasting hours of your life.

In theory, setting all this up should be fun. In practice, it takes days. And that’s not an exaggeration. Dolphin still manages to be one of the worst because GameCube and Wii controller setups have no standard. RPCS3 requires per-game tuning. Eden needs DLC, updates and cheats in the right place. shadPS4 is a festival of trial and error. When I’d finally finish configuring everything, I didn’t feel like playing anything anymore. I just wanted to close the menus and go do something else.

I’ve been known to say that maybe the fun was the tuning itself. I don’t think that anymore. After repeating this process too many times, I’m done. I want to play the games, not fill out forms hidden inside emulator GUIs.

The problem was never Linux

I’ve solved this kind of thing in different ways in the past. Years ago I ran Linux on the host and a virtualized Windows with GPU passthrough to play inside the VM. At the time that made sense. I made a whole video about it:

But that was before Valve, Proton, modern Wine and the whole open source community pushed the Linux desktop to a much better place. Today you can avoid Windows in most cases. In the other video below I explain the evolution of CPU, GPU, OpenGL, Vulkan, and why we ended up here:

My gaming mini-PC with the RTX 4090 is still my main Steam machine, especially now that I’ve built a proper sim racing cockpit. On it I use EmuDeck, which was born to automate installing and configuring emulators on the Steam Deck, then grew Windows support, and helps cut the complexity of setting up this kind of environment. But my main desktop is also way too powerful to leave underused. It has an RTX 5090, and today I use that GPU mostly to test LLMs and for benchmarking, as I wrote in Testing Open Source and Commercial LLMs. Leaving it idle for gaming would be a waste.

Only on Linux I wanted something else. I didn’t want a black box doing everything for me without me knowing exactly what was being changed, especially on my main PC, which is my work machine. I wanted my own setup, handmade in the right sense: not clicking GUI by GUI, but understanding what’s being configured, keeping the files under my control, and being able to rebuild everything the way I like. I know the NixOS folks will jump in here to say “just use Nix” — I’ll explain why I ruled that out below. I also didn’t want to turn my work machine into a carnival of emulator packages, GTK themes, wrappers, launchers, weird runtimes and configs buried in ~/.config. Nor did I want dual boot or a VM. In 2026, the best answer for this, in my opinion, is Distrobox.

From what the project itself explains, Distrobox is a wrapper on top of podman, docker or lilipod to create containers tightly integrated with the host, with access to HOME, Wayland/X11, audio, USB devices, external storage and GPU. In other words: exactly the kind of pragmatic isolation I wanted. It’s not a security boundary, and the project site makes that clear. Don’t use it thinking about high-security sandboxing. Use it thinking about separating environments without paying the price of a VM.

And before anyone repeats the usual confusion: a container is not a virtual machine. I explain this calmly in this other episode:

The setup

The idea is simple: a vanilla Arch Linux inside a Distrobox called gaming, with NAS paths mounted read-only, Steam library accessible where it makes sense, and all emulators installed inside. Since the container has access to the NVIDIA GPU, audio, USB and other peripherals, I can separate work and gaming on the same machine without practical performance penalty.

The initial bootstrap looks roughly like this:

distrobox create --name gaming --image archlinux:latest --nvidia \
  --home /mnt/data/distrobox/gaming \
  --volume /mnt/data/steam:/mnt/data/steam \
  --volume /mnt/terachad/Emulators:/mnt/terachad/Emulators:ro

Even that first step has a catch. archlinux:latest inside Distrobox comes without [multilib] in pacman.conf, with a misconfigured sudoers, and with the old --nvidia problem: the host driver libs get bind-mounted read-only, so any install that depends on nvidia-utils breaks with file conflicts. Just that alone is the kind of headache that, a few years ago, would make me open half a dozen tabs, a bunch of terminals, and spend a whole night in trial and error.

This time I did it differently.

Claude Code as an infrastructure assistant

I’ve been getting more and more comfortable using Claude Code as my infrastructure assistant on my personal machines. I wouldn’t do this blindly on a client server. But on my own machine, in an environment I can destroy and rebuild however many times I want, it makes all the sense in the world. I wrote about this in Migrating my Home Server with Claude Code, when I used Claude to install and configure openSUSE MicroOS, Docker, NFS, firewall, hardening, and all the rest without me having to remember annoying shell commands.

So I thought: why not do the same thing here?

That’s exactly what I did. I started with a sequence of objective prompts, always asking for two things at once: do the work, and document enough for me to rebuild everything later. The most important history ended up in docs/distrobox-gaming-prompts.md.

A clarification worth making: those prompts on GitHub aren’t my raw messages, the way they came out in real time. After everything worked, I asked Claude itself to rewrite the prompts in a much more organized and detailed way, purely for documentation. The original prompts were much simpler and much less specific. I described the goal and let Claude figure out paths, config files, formats and commands on its own.

The first prompt created the box with --nvidia, a separate --home, and correct mounts. The second solved the three classic problems of Arch inside Distrobox: sudo, multilib, and the nvidia-utils dummy package. The third installed the gaming base, including a detail I would have easily forgotten if I was doing it by hand: pipewire-pulse, needed so several emulators don’t end up mute or out of sync.

The point isn’t the text itself. The point is the method. I don’t need to remember the exact order, the precise options, or where the docs for each detail are. I describe the goal and let the agent carry the piano. I stay in the tech-lead role: watching, reviewing, course-correcting when needed, and telling it to keep going.

The GitHub project

The setup lives in akitaonrails/distrobox-gaming, structured as an Ansible project. 17 roles cover everything from box creation, package bootstrap, config seeding, DLC installation, controller setup, to post-setup verification. The main playbooks are:

• site.yml: full setup from scratch
• reset-configs.yml: reset configs only (useful when you want to wipe tuning and redeploy)
• backup.yml / restore.yml: container snapshot and restore via podman commit
• refresh-shadps4.yml: standalone shadPS4 update
• install-xenia.yml: optional Xenia Manager install (Wine prefix)

Full walkthrough is in docs/rebuild-runbook.md. Package decisions (why AUR instead of Flatpak, for example) are in docs/distrobox-gaming-packages.md.

Why not Nix?

Someone will ask. “You’re recreating a reproducible environment. Why not use NixOS, or at least nix-shell/flakes?”

I considered and ruled it out. The emulator ecosystem I need lives on the AUR. AUR -bin packages are wrappers around AppImages that ship the official upstream binary without compiling anything. rpcs3-bin, pcsx2-latest-bin, eden-bin, duckstation-qt-bin, shadps4-bin — these binaries track upstream practically on release day. On Nixpkgs, many of these emulators are weeks or months behind release, and some don’t exist. Creating a Nix overlay for every emulator I need, maintaining it, and dealing with compatibility patches when upstream changes is work I don’t want to have.

There’s also the mental model. I don’t want to learn the Nix language, the derivation system and the evaluation model just to set up a personal gaming environment. I already know Ansible, roles are folders with YAML tasks, and debugging is ansible-playbook -vvv. When something goes wrong, I read the error, open the task that failed, and know exactly where to fix it. If I needed the same level of reproducibility at scale, across a cluster, with atomic rollback, then Nix would have an argument. For a distrobox with emulators on my personal machine, Ansible solves it with much less friction.

Flatpak was also tested and ruled out. Flatpak’s bwrap (bubblewrap) doesn’t nest properly inside Docker’s mount namespaces, so Flatpak apps simply don’t run inside distrobox. The alternative would be installing Flatpak on the host, but then you’re back to polluting the work machine with gaming packages. Plus, Flatpak versions of emulators lag well behind AUR — the AUR’s pcsx2-latest-bin tracks the 2.7.x AppImage, while Flathub still ships v2.6.3.

Platforms covered

The setup covers 12 platforms today:

RetroArch comes on top to cover the rest (NES, SNES, Genesis, N64, arcade, etc.), with 21 buildbot cores and 8 asset packs (databases, shaders, cheats, overlays, autoconfig).

Frontend is ES-DE. Custom system definitions live in ansible/group_vars/all/esde.yml, and each emulator comes with a wrapper that sets the right GPU environment variables (more on that in a sec).

GPU hardforce for NVIDIA

On a hybrid system with NVIDIA dGPU + AMD iGPU (my case on the desktop), Vulkan sometimes picks the iGPU on its own and you end up with an emulator running at 15 fps while the 5090 sits idle. The fix is to force NVIDIA’s Vulkan ICD in every launcher.

Each desktop entry rendered by Ansible exports VK_ICD_FILENAMES pointing to NVIDIA’s ICD, and the ES-DE wrapper does the same before launching any core. Combined with the --nvidia flag at box creation, which bind-mounts host drivers read-only, the result is predictable: Vulkan always on the NVIDIA dGPU, regardless of system state at runtime.

This mostly matters for hybrid setups. On a desktop with a single GPU, the ICD filtering is placebo, but it doesn’t hurt.

PS2: PCSX2 with per-game tuning

The Gran Turismo line is my declared addiction. Each version needs its own specific tweak. The PCSX2 setup today has sane global configs (Vulkan, 4x SSAA, widescreen 16:9, Xbox-style bindings, FXAA + PCRTC antiblur, 16x anisotropic, Automatic deinterlace) and per-game INIs for the titles I actually play:

• Gran Turismo 3 A-spec (SCUS-97102 + bundle PBPX-95503): widescreen pnach, optional retexture pack (disabled by default because NFS streaming causes flicker in car-showcase cutscenes)
• Gran Turismo 4 USA (SCUS-97328): Silentwarior112 HD HUD, full retexture pack, Silent’s trigger/cam patches, widescreen pnach
• Gran Turismo 4 Spec II (SCUS-97436, CRC 4CE521F2): special case — the vanilla GT4 HD packs are linked via symlink because Spec II has the same structure but a different CRC. Widescreen pnach renamed to match the CRC. Deinterlace mode 8 (Adaptive TFF), ShadeBoost tuning (+10 saturation, +3 brightness, +2 contrast) to fix pause-interlace ghosting and the anemic upscale saturation
• Enthusia Professional Racing (SLUS-20967): HD textures + widescreen
• Ridge Racer V (SLUS-20002): widescreen + no-interlace pnach

Silent’s and community pnach files are downloaded automatically by the pcsx2_textures role, which also deploys the cheats pack from the NAS and installs the Spec II HD packs via symlink. Widescreen is enabled per-CRC via gamesettings (PCSX2 identifies games by CRC before applying pnach).

On PCSX2 versioning: the AUR’s pcsx2-latest-bin tracks the 2.7.x line, which is where all the modern features live (texture replacement, FXAA, PCRTC antiblur). The default pcsx2 in Arch repos is still on 2.6.3. The gap is over 250 commits of fixes and new features.

PS3: RPCS3 with curated per-game configs

RPCS3 has an annoying detail: per-game configs live in ~/.config/rpcs3/custom_configs/config_<SERIAL>.yml. The file format has a version, and if you hand-write YAML with the wrong version, RPCS3 silently rejects it and falls back to defaults. That cost me time to figure out.

The rpcs3_per_game_configs role handles it like this:

1. Queries the RPCS3 community compatibility DB for recommended presets per title
2. Applies curated overrides on top for titles I know need specific tuning (typically GT5 and GT6)
3. Saves the YAML with the exact filename convention (config_<SERIAL>.yml, config_ prefix mandatory)

For the Gran Turismo line:

• GT5 (BCUS98114, BCES00569): Resolution Scale 300%, Shader Precision Ultra, Force High Precision Z, SPU XFloat Accurate, Multithreaded RSX. The combo kills the typical RSX dithering without breaking the GT-series safety config (WCB/RCB off).
• GT6 (BCES01893 + regional variants): special case, version pinned to v1.05. Patches 1.06+ regress with black surfaces on cars in the garage menu. The extract_ps3_dlc.py script has a per-title PATCH ceiling specifically to pin GT6 at 1.05 even when PSN serves newer patches. Also, Force CPU Blit is mandatory (without it, full-screen flicker). The trade-off is that the rear-view mirror stays permanently black — turning WCB on would restore the mirror but downgrade to native 720p. I’ll take no mirror.

More details on those two in docs/gt5-rpcs3.md and docs/gt6-rpcs3.md.

PS3 update checker

To avoid opening RPCS3’s GUI and clicking Download Game Updates game by game, I wrote a Python script: check_ps3_updates.py. It walks the games installed in dev_hdd0/game, parses PARAM.SFO to get the current version per title, queries the PSN update server (a0.ww.np.dl.playstation.net), and compares against the local patch cache. --list shows the diff; --download fetches what’s missing. --max-version respects per-title ceilings (e.g., 1.05 for GT6).

The first scan of my library found 51 of 72 games with updates available, 69 patches missing locally, ~24 GB in total. GT6 alone had 16 missing patches from 1.07 to 1.22, which I skipped for the reasons above.

Patches arrive as PSN packages type 0x0001 without encryption, so extract_ps3_dlc.py handles the install. Standard call:

distrobox enter gaming -- python3 scripts/extract_ps3_dlc.py \
  "/mnt/terachad/Emulators/EmuDeck/roms_heavy/ps3-DLC" \
  --dest "/mnt/data/distrobox/gaming/.config/rpcs3/dev_hdd0/game"

Tracking PS3 DLC versions manually, game by game through RPCS3, is impractical. It becomes an infinite to-do list, and you only find out there was a 1.22 patch when the game crashes.

PS1: DuckStation per-game

The Gran Turismo trilogy starts on PS1, and quality there only goes up if you enable the right things:

• Gran Turismo (SCUS-94949): DuckStation’s built-in WidescreenHack (no cheat exists for this game), PGXP enabled
• Gran Turismo 2 Simulation (SCUS-94455): widescreen cheat + 8 MB RAM cheat (fixes audio issues on crowded tracks), JINC2 filter
• Gran Turismo 2 Arcade (SCUS-94488): same treatment as Simulation

Global defaults: Vulkan, 8x upscale, JINC2 as the default filter.

GT2 cheats come from a widescreen-fixes repo and are linked automatically into DuckStation’s cheats folder.

Switch: Eden with DLC, update and cheats

On Switch, eden-bin is the emulator. The integration automates three things I used to do by hand:

1. DLC and update install: the install_dlcs role points to the dumps directory on the NAS, identifies .nsp/.nsz/.xci/.xcz files, and installs everything into ~/.local/share/eden/nand/user/Contents/registered/. If the dump is messy (patches and DLC mixed in a flat folder), the reorganize_switch_nsps.py script sorts everything by Title ID first.

2. Atmosphere cheats: Atmosphere-format cheats get symlinked into Eden’s load path (~/.local/share/eden/load/<TITLE_ID>/cheats/). The switch_cheats role handles this for every title covered by the NAS pack.

3. Update checker: check_switch_updates.py lists titles with updates available against what’s installed locally. Useful so I don’t miss important patches for games still getting updates.

A detail that burned me: QT_STYLE_OVERRIDE needs to be unset before launching eden-bin, otherwise it conflicts with Kvantum and breaks the UI. The wrapper does the unset before exec.

Xbox 360: Xenia Manager via Wine

Xbox 360 is still rough territory on Linux. There’s no decent native emulator. The best route today is Xenia running through Wine, managed by Xenia Manager.

This is opt-in in my setup. The install-xenia.yml playbook creates a dedicated Wine prefix, downloads Xenia Manager, and registers launchers. It’s not part of the main site.yml because not everyone wants Wine in the mix.

Project Forza Plus (Forza Motorsport 2/3/4)

Old Forza is still the king of previous-gen simcade. Running FM2/3/4 on Xenia requires the Project Forza Plus community mods: compatibility patches, performance mods, specific title-update installs. I documented the process in docs/project-forza.md.

Project Gotham Racing 3 and 4

PGR3 runs reasonably well on Xenia Canary. PGR4 needs a specific tweak: render_target_path_vulkan = "fsi" in the config, otherwise some races break with visual artifacts. Setup documented in docs/xbox360-pgr.md. PGR4 audio on NVIDIA still has an XMA decoding issue that produces intermittent garbage. There’s an open xenia-canary issue, no resolution so far.

Batch Title Updates

Title Updates for Xbox 360 games were distributed via Xbox Live, which has been shut down. The alternative is archive.org, which has the complete catalog preserved. I wrote scripts/download-xbox360-tus.py to automate:

distrobox enter gaming -- python3 scripts/download-xbox360-tus.py \
  --src /mnt/terachad/Emulators/EmuDeck/roms_heavy/xbox360 \
  --dest /mnt/terachad/Emulators/EmuDeck/roms_heavy/xbox360-updates \
  --dry-run

The script needs the internetarchive CLI authenticated (ia configure once, stores the token). It scans the games folder, matches against the archive.org manifest (cached locally), prioritizes by region (USA > World > Europe > Japan), and downloads via ia download --checksum with automatic retry. The resulting .zip files go to Xenia Manager via Manage → Install Content, which extracts into the correct directory (000B0000/).

Full setup in docs/xbox360-title-updates.md.

Steam in the distrobox

Since Proton became a first-class citizen on Linux, it makes sense to have Steam in the gaming box too. I added the steam package via Ansible (which pulls in multilib and 32-bit deps), mounted /mnt/data/steam read-write so the library persists outside the container, and created a host-side launcher.

In practice, this lets me run Steam games via Proton side-by-side with emulation, without switching environments. The mini-PC with the RTX 4090 is still the main Steam machine in the sim racing cockpit. The desktop is fallback and a test environment.

Shell and controllers

Minimal in-box shell

When I distrobox enter gaming, I want a decent prompt even for quick troubleshooting. I installed zsh + starship with a minimal config, zero exotic plugins. It’s not my full dev setup, it’s just “a prompt that shows path and git branch without embarrassing me”.

Dolphin and the modern-controller hell

Dolphin has always been the king of manual friction. If you use a modern controller, like my 8BitDo Ultimate 2, you have to remember how I like the GameCube mapping, how I adapt the Wii Remote, when to use a Nunchuk profile, when to switch to Classic Controller. I don’t have the patience to rebuild that by hand every time. Profiles are pre-built in config/emulator-overrides/dolphin/Profiles/ and copied by the seed_configs role. Details in docs/controller-hotkeys.md.

A few stumbles that stuck around

Not everything became magic. Emulation always has banana peels.

Flycast, for example, has an irritating trap. The emu.cfg file uses rend.* keys inside the [config] section. If you create a separate [rend] section, it looks right, but the emulator just ignores it and later rewrites everything with mediocre defaults. The fix became a dedicated wrapper at $DG_BOX_HOME/bin/flycast-hires:

$DG_BOX_HOME/bin/flycast-hires \
  -config config:pvr.rend=4 \
  -config config:rend.Resolution=2880 \
  -config config:rend.EmulateFramebuffer=no \
  -config config:rend.WideScreen=yes

Details in docs/flycast-resolution.md.

shadPS4 is still far from a closed case. The current setup is focused on Driveclub, with a mirrored config, XML patch and sys_modules links from firmware 11.00. And that wasn’t random: I really like Driveclub. It’s practically the only game still stuck on PS4 that I really wanted to get running properly. I’ve seen several YouTube videos showing the game working, but so far I haven’t been able to get it running satisfactorily on Linux myself. Documented in docs/driveclub-shadps4.md. The good part is that I no longer depend on muscle memory to remember how to launch it, with which patch, in which folder, with which modules. The bad part is that PS4 emulation is still PS4 emulation. No script makes upstream mature faster. If anyone knows how to close this setup on Linux, check the project on GitHub and send a PR.

Ridge Racer V has car-texture flickering documented in PCSX2 issues (#3639, #13729). The Hardware renderer is acceptable for a racing game where you’re not standing still admiring the model. Software renderer fixes it but kills performance. I chose to live with the flicker.

The real gain isn’t just automation

It’d be easy to sum this up as “look how cool, I used AI to automate shell scripts”. That’s not it.

The real gain is more mundane and more important: I stopped spending mental energy on manual work. I didn’t have to remember rare commands. I didn’t have to keep dozens of tabs of wiki, issue, forum, README. I didn’t have to leave half a dozen terminals scattered tailing logs while I try to remember which hidden GUI option the emulator insists on overwriting on the first boot. I started working in conversation.

I tell the agent the goal. It looks up the files, reads the logs, finds the right config format, compares defaults, proposes fixes, writes scripts, validates paths, checks UID/GID, verifies broken symlinks, generates wrappers, exports launchers. I’m still responsible for decisions, of course. But I stopped being a typist of rare commands.

That’s the point that interests me most about using coding agents on Linux. They dramatically reduce the entry friction. A lot of people bounce off the Linux desktop not because the system is incapable, but because the tuning curve has historically been too irritating. Having an assistant capable of reading docs, cross-referencing configs, proposing automation and executing under supervision changes that game.

If you want to reproduce

The repo was published for this:

git clone https://github.com/akitaonrails/distrobox-gaming.git
cd distrobox-gaming/ansible
ansible-galaxy collection install -r collections/requirements.yml
cp host_vars/localhost.yml.example host_vars/localhost.yml
$EDITOR host_vars/localhost.yml  # adjust paths for your machine
ansible-playbook site.yml

Xenia is opt-in:

ansible-playbook install-xenia.yml

Read the README.md and docs/rebuild-runbook.md first. I don’t distribute ROMs, BIOS, firmware or keys. The repo only detects, links and configures what you already have on your own machine.

If you prefer the Claude Code route

My recommendation is simple:

1. Start with the goal, not the command. “I want an Arch distrobox with NVIDIA GPU, separate home, ROMs read-only and Steam rw” beats dumping a half shell command without context.
2. Always ask it to document what it’s doing. If it works, promote the result to a script or role. If you don’t document, you just manufactured a throwaway hack.
3. Work in phases. Box creation. Bootstrap. Emulator config. Launcher export. Verification. That’s exactly how I broke down the problem.
4. Ask for objective checks. command -v, file existence, broken symlinks, UID/GID, ROM paths, audio, GPU. The best automation is the one that fails early.
5. Don’t use the agent as a command parrot. Use it as a technical assistant. You still review the decisions and tell it to adjust course.

For me, that was the gain. I went from zero to a much more complete emulation machine without having to customize everything by hand, GUI by GUI, one window at a time. And this time, I finished with energy left to do what I wanted from the start.

Play.

And don’t forget to subscribe to my new newsletter The M.Akita Chronicles!

–

Every Rails project starts the same way: you build an admin panel. Active Admin, Administrate, or some homegrown CRUD. Tables, forms, buttons. And every week, you end up using 5% of the screens you built.

Now picture your admin panel as a conversation. You paste a link; the system processes it. You type /week and see the summary. /approve and the newsletter is scheduled. /ask akita how does the podcast pipeline work? and an AI explains the architecture of your own system to you.

That’s Discord as an operational interface. It’s not a hack — it’s the best CRUD interface there is for a team of one.

Why Discord Instead of a Web Admin?

Let’s be honest about what an admin panel demands:

1. Authentication: login, session, CSRF, password reset
2. Authorization: roles, permissions, who can do what
3. UI: tables, pagination, forms, client-side validation
4. Deployment: another route, another controller, another set of tests
5. Mobile: responsive? App? PWA?

And what Discord already gives you for free:

1. Auth: Discord handles it. You just check the author_id
2. Authorization: a list of admin IDs and you’re done
3. UI: embeds with colors, fields, thumbnails, reactions as status
4. Deployment: zero. Uses what’s already deployed
5. Mobile: native iOS and Android app, push notifications

The trade-off? It doesn’t fit everything. A complex CRUD with 20-field forms? Better off with a web admin. But for command/response operations — which are 90% of what you do day to day — Discord is unbeatable.

discordrb: A Gem That Works

The discordrb gem (shardlab fork, version 3.7.2) is the most mature one for Ruby. It’s not perfect — it has its quirks. But it genuinely works in production.

The minimal setup:

bot = Discordrb::Bot.new(
  token: token,
  intents: Discordrb::INTENTS[:server_messages] |
           Discordrb::INTENTS[:direct_messages] |
           (1 << 15)  # message_content intent
)

bot.message do |event|
  # Every message flows through here
end

bot.run

That (1 << 15) is the Message Content Intent. Without it, your bot receives events but event.content comes in empty. You need to enable it in the Discord Developer Portal > Bot > Privileged Gateway Intents. That’s the first trap that catches everyone.

I won’t walk through how to set up a Discord bot, there are plenty of tutorials for that already, easy to find online. I’ll focus only on my use case as an example.

Pattern 1: Parser + Dispatcher

Mixing command parsing with business logic is a recipe for spaghetti. Split it into three layers:

Discord Event → Parser → Dispatcher → Job/Service

The runner (the thing that talks to the Discord API) is deliberately dumb:

bot.message do |event|
  next if event.author.bot_account?

  parsed = SlashCommandParser.parse(event.content, attachments: urls)

  case parsed
  when SlashCommandParser::Command
    CommandDispatcher.dispatch(parsed, channel_id: channel_id)
    event.message.react("\u{2705}")  # checkmark
  when SlashCommandParser::Submission
    ProcessMessageJob.perform_later(url: parsed.url, tags: parsed.tags)
    event.message.react("\u{1F916}")  # robot
  end
rescue StandardError => e
  event.message.react("\u{274C}")  # red X
end

Three instant visual results: checkmark (command accepted), robot (URL being processed), red X (error). The user knows what happened without waiting for any text response.

The parser returns typed objects, not strings. The dispatcher runs a giant case but each handler is an isolated method. Each handler calls a job or service. No business logic in the runner.

Evolution: Discord Application Commands

The initial version parsed raw text — the user typed /week and the parser interpreted it. It works, but it has limits: no autocomplete, no argument validation, no inline documentation.

Discord has a native Application Commands system — slash commands registered with the API that show up with autocomplete, description, and typed parameters. When the user types /, Discord displays every available command with its description.

bot.register_application_command(:week, "List this week's stories", server_id: guild_id)
bot.register_application_command(:approve, "Approve newsletter for sending", server_id: guild_id)
bot.register_application_command(:ask, "Ask AI a question", server_id: guild_id) do |cmd|
  cmd.string("question", "Your question", required: true)
  cmd.string("personality", "AI personality", choices: { "Akita" => "akita", "Marvin" => "marvin" })
end

The handler uses bot.application_command instead of parsing text:

bot.application_command(:week) do |event|
  CommandDispatcher.dispatch_week(channel_id: event.channel.id)
  event.respond(content: "Listing stories...")
end

Both systems coexist: Application Commands for those who prefer autocomplete, raw text for those who prefer typing fast. The dispatcher is the same — the only difference is how the command arrives.

Pattern 2: Reactions as Status

The most underrated feature of Discord for bots is reactions. They’re instant visual feedback that doesn’t pollute the channel with messages:

• Checkmark = command received and queued
• Robot = async processing started
• Red X = error (details in the embed that follows)

The user pastes a link. Sees the robot appear. 30 seconds later, a rich embed shows up with title, summary, image and AI commentary. If something fails, a red embed appears with the error message.

That beats any loading spinner in a web UI.

Pattern 3: Rich Embeds as Dashboard

Discord embeds are surprisingly powerful:

embed = {
  title: "Story Preview",
  url: source_url,
  color: 0xFF4500,           # orange-red for high priority
  description: summary,
  thumbnail: { url: image },  # article image
  fields: [
    { name: "M.Akita diz", value: akita_comment, inline: false },
    { name: "M.Arvin diz", value: marvin_comment, inline: false },
    { name: "File", value: "`stories/2026-02-16-titulo.md`", inline: false }
  ],
  footer: { text: "fire high | tech_news | verified" }
}

Discordrb::API::Channel.create_message(token, channel_id, "", false, [embed])

Colors signal priority (red = high, amber = medium, green = low). The footer shows score, section and fact-check status all on a single line. You glance at it and know the state of things.

For reports, multiple embeds side by side (Discord accepts up to 10 per message) work as a mini-dashboard. The /week command lists every story with inline actions — /load @a3f2b1 to see details, /delete @a3f2b1 to remove it. The hash is stable (based on the file path), so it doesn’t shift when you delete another story.

Pattern 4: Context Per Channel

When the user types /load #3, the #3 refers to the most recent listing. But what if two channels are being used at the same time?

class ChannelContext < ApplicationRecord
  EXPIRY_DURATION = 2.hours

  def self.for_channel(channel_id)
    find_or_create_by!(channel_id: channel_id.to_s)
  end

  def set_week_stories!(hash)
    update!(week_stories_json: hash.to_json, expires_at: EXPIRY_DURATION.from_now)
  end

  def resolve_story_reference(ref)
    if ref.match?(/\A@[a-f0-9]+\z/i)
      # Hash reference (stable across re-listings)
      hash = ref.delete("@").downcase
      week_stories.values.find { |path| md5_prefix(path) == hash }
    elsif ref.match?(/\A#?\d+\z/)
      week_stories[ref.delete("#")]
    end
  end
end

Each channel has its own context with a 2-hour expiration. /week stores the number→file mapping. Then /load #3 queries that context. If it expired, the bot says “run /week first”.

And the most useful detail: hash-based references (@a3f2b1) instead of numbers. When you delete story #2, #3 becomes #2 — but the hash @a3f2b1 still points to the same file. That avoids the classic “I deleted the wrong one because the list shifted”.

Pattern 5: Simple Admin Check

No complex RBAC. A list of IDs:

ADMIN_COMMANDS = %i[delete update_score approve newsletter publish_blog].freeze

def self.dispatch(command, channel_id:, author_id:)
  if ADMIN_COMMANDS.include?(command.type) && !admin?(author_id)
    send_error(channel_id, "Permission denied. Admin privileges required.")
    return
  end
  # ...
end

def self.admin?(author_id)
  admin_ids = ENV["DISCORD_ADMIN_USER_IDS"].to_s.split(",")
  return true if admin_ids.empty?  # dev: no IDs = everything allowed
  admin_ids.include?(author_id)
end

In dev, without DISCORD_ADMIN_USER_IDS set, everything is allowed. In production, it’s a list of Discord user IDs. No database, no roles table, no middleware. Ten lines handle authorization.

Pattern 6: Async Operations with Feedback

Slow operations (generating an image, processing an article, calling an AI) go to background jobs. Visual feedback comes in three beats:

def self.handle_ask(personality, question, attachments, channel_id)
  # 1. Immediate feedback: "I'm thinking"
  thinking_id = DiscordNotifier.send_message(channel_id, content: "Thinking...")

  # 2. Job does the heavy lifting in the background
  AskJob.perform_later(
    question,
    channel_id: channel_id,
    thinking_message_id: thinking_id
  )
end

# In AskJob:
def perform(question, channel_id:, thinking_message_id: nil)
  result = AiChat.ask_multimodal(question, tools: [GenerateImageTool])

  # 3. Remove "Thinking..." and show result
  DiscordNotifier.delete_message(channel_id, thinking_message_id)
  DiscordNotifier.send_message(channel_id, content: "**Marvin:** #{result[:text]}")
end

The “Thinking…” shows up instantly, the job runs in the background, and when it finishes the temporary message disappears and the real result appears. If the job fails, “Thinking…” disappears and an error embed shows up.

Without this, the user sends a question and stares at the screen not knowing if the bot heard them. Terrible UX.

Pattern 7: RubyLLM + Tool Calling on Discord

The most powerful part: giving the LLM tools. /ask has three tools available: GenerateImageTool (generates images via Gemini), WebSearchTool (searches the web via Brave Search), and WebFetchTool (fetches and summarizes web pages). The LLM decides on its own which one to use based on the question. When the user asks “generate an image of a cat programming”, the LLM picks the right tool:

class GenerateImageTool < RubyLLM::Tool
  description "Generate an image using Gemini. Use when the user asks to create or draw."
  param :prompt, desc: "Image description"
  param :aspect_ratio, desc: "1:1 or 16:9", required: false

  def execute(prompt:, aspect_ratio: "1:1")
    image_data = ImageGenerator.generate(prompt: prompt)
    return "Failed to generate image" unless image_data

    path = save_temp_file(image_data)
    Thread.current[:generated_images] << path

    "Image generated successfully. Tell the user it's ready."
  end
end

The Thread.current[:generated_images] is the trick to pass data back from the tool to the job. The LLM calls the tool during chat.ask, the tool saves the file and registers the path. After chat.ask returns, the job grabs the paths and sends them to Discord as file uploads.

Why thread-local and not a direct return? Because the LLM can call multiple tools within a single response, and the tool’s return value goes back to the LLM (not to your code) — the LLM decides what to say to the user. Thread-local is the side channel for your code to know what happened.

Pattern 8: Production Status Notifications

Every content generation job notifies a dedicated channel:

module DiscordStatus
  def notify_start(label)
    DiscordNotifier.send_to_status_channel("Starting #{label}...")
  end

  def notify_done(label)
    DiscordNotifier.send_to_status_channel("#{label} complete.")
  end

  def notify_error(label, error)
    DiscordNotifier.send_to_status_channel("#{label} FAILED: #{error}")
  end
end

The status channel is separate from the operations channel. When the 8 content generation jobs run on Sunday at 5pm, the status channel turns into a real-time log:

Starting Anime Ranking...
Starting Hacker News...
Starting YouTube Digest...
Anime Ranking complete.
YouTube Digest complete.
Hacker News complete.
Starting Market Recap...  (wave 2, after world events)
...

In the morning, if something went wrong, you open Discord on your phone and you know exactly what — no SSH into the server, no grep in logs.

And when the bot restarts after a deploy:

bot.ready do |_event|
  status_channel = ENV["DISCORD_STATUS_CHANNEL_ID"]
  DiscordNotifier.send_message(status_channel, content: "Bot reconnected and ready.")
end

Simple, but you know the deploy worked without checking anything.

Pattern 9: Cross-App Communication

The system has two Rails apps that need to talk to each other. The newsletter needs to notify Discord when it finishes assembling an edition. But the newsletter has no Discord connection — marvin-bot is the one that does.

Solution: HTTP relay.

# In the newsletter — send it to marvin-bot
class DiscordRelayClient
  def self.send_embed(title:, description:, color:)
    post("/api/discord_notify",
      type: "embed",
      payload: { title: title, description: description, color: color }
    )
  end
end

# In marvin-bot — receive it and forward to Discord
class Api::DiscordNotifyController < ApplicationController
  def create
    case params[:type]
    when "embed"
      DiscordNotifier.send_embed(status_channel, params[:payload])
    when "message"
      DiscordNotifier.send_message(status_channel, content: params[:payload][:content])
    end
  end
end

The newsletter speaks HTTP. marvin-bot translates it to Discord. A shared ADMIN_TOKEN authenticates. Every method rescues errors and returns nil — if Discord is down, the newsletter doesn’t lock up. Fire and forget.

But there’s a second, more interesting cross-app flow: the podcast trigger. When the newsletter is approved, it needs to tell marvin-bot to generate the podcast:

# In the newsletter — trigger podcast generation on marvin-bot
class MarvinBotClient
  def self.trigger_podcast(date:)
    post("/api/trigger/podcast", date: date.to_s)
  end
end

That kicks off an entire pipeline on marvin-bot: two-pass LLM script → per-turn TTS on the GPU → assembly with loudnorm → S3 upload. And the newsletter’s PublishAndSendJob waits (via retry_on PodcastNotReady) until the podcast is ready. Two apps, two backend languages (Ruby and Python), connected by fire-and-forget HTTP with result polling. It’s not elegant — but it works every single week with no intervention.

Pattern 10: Integrated Cost Tracking

Every AI call is tracked with tokens and estimated cost:

def self.create_chat(caller:, model:, provider:)
  chat = RubyLLM.chat(model: model, provider: provider)
  chat.on_end_message do |message|
    ApiUsage.create!(
      caller_name: caller,
      input_tokens: message.input_tokens,
      output_tokens: message.output_tokens,
      cost_usd: estimate_cost(model, message)
    )
  end
  chat
end

And on Discord: /cost shows spending by month, year, and by provider. No separate dashboard, no Grafana, nothing. One command and the information that matters.

Pattern 11: Never Fail Silently

This is the pattern I should have implemented from the start, but I only learned it the hard way — in production.

The project has ~10 daily jobs that fetch data from external sources (Hacker News, GitHub Trending, Morningstar, etc.) and post embeds to Discord. Each client follows a “defensive” pattern:

# The pattern that LOOKS right:
class DailyDevClient
  def self.fetch_popular(limit: 10)
    response = HTTParty.get(API_URL, headers: { "Authorization" => "Bearer #{token}" })
    return [] unless response.success?
    parse(response.body)
  rescue StandardError => e
    Rails.logger.warn("DailyDevClient failed: #{e.message}")
    []
  end
end

# And in the job:
class DailyDailyDevJob < ApplicationJob
  def perform
    posts = DailyDevClient.fetch_popular(limit: 10)
    return if posts.empty?  # ← THE PROBLEM
    # ... posts embed to Discord
  end
end

This code never crashes. Never raises an exception. Never fills the log with errors. It’s the most “robust” code possible.

It’s also completely useless for diagnosis. When I deployed and ran the daily jobs manually, only one of ten worked. But there was no error in the logs. None. return [] unless response.success? swallowed the HTTP 401 without logging. return if posts.empty? discarded the result without telling anyone. All green, all silent, zero data.

The fix has two parts:

Part 1: Clients log the HTTP code:

unless response.success?
  Rails.logger.warn("DailyDevClient: API returned HTTP #{response.code}")
  return []
end

It sounds obvious, but it’s easy to forget when you write return [] as a defensive reflex. response.code is the information that distinguishes “expired token” (401) from “rate limited” (429) from “API down” (503). Without it, everything looks the same: empty array.

Part 2: Jobs warn on Discord when they have no data:

module DailyDiscordEmbed
  def report_empty(title)
    Rails.logger.warn("#{self.class.name}: #{title} returned no results")
    channel_id = Rails.application.config.discord.channel_ids.first
    return unless channel_id.present?

    embed = {
      title: "⚠️ #{title}",
      description: "#{self.class.name} returned no results. Check logs.",
      color: 0xFFA500,  # orange = warning, not red = error
      timestamp: Time.current.iso8601
    }
    DiscordNotifier.send_embed(channel_id, embed)
  rescue StandardError => e
    Rails.logger.error("#{self.class.name} empty report failed: #{e.message}")
  end
end

Now when a daily job brings back no data:

def perform
  posts = DailyDevClient.fetch_popular(limit: 10)
  if posts.empty?
    report_empty("daily.dev Popular")
    return
  end
  # ...
end

An orange embed appears on Discord. In the morning, I open the channel and see: “⚠️ daily.dev Popular returned no results”. I check the logs and find: “DailyDevClient: API returned HTTP 401”. Expired token. Fixed in 2 minutes.

Without this pattern, I would have discovered it weeks later — when someone asked “why are there never any daily.dev posts?”.

The lesson: rescue => [] is not error handling. It’s error hiding. Every failure point needs two signals: a log with the technical detail (HTTP code, exception message) and a visual notification in the channel where you’re already looking (Discord). If the bot IS your operational interface, bot failures need to show up ON the interface.

Pattern 12: Conversations With Memory (Multi-Turn /ask)

The first version of /ask created a brand new RubyLLM::Chat on every invocation. It worked, but it was like talking to someone with amnesia:

/ask what is Ruby?
→ Ruby is a programming language created by Matz in 1995...

/ask compare it with Python
→ Compare what with Python? Could you be more specific?

ruby_llm already keeps history internally — every chat.ask() appends to the message list and sends the full context to the model. What was missing was persisting the Chat object between invocations.

The solution is an in-memory store with three safeguards:

class AskSessionStore
  MAX_SESSIONS = 100       # total across all users
  SESSION_TTL = 2.hours    # inactivity timeout
  MAX_MESSAGES = 50        # ~25 exchanges, then auto-reset

  Session = Struct.new(:chat, :last_used, keyword_init: true)

  def get_or_create(author_id, personality, system_prompt:, tools:)
    synchronize do
      cleanup_expired
      key = [author_id, personality]

      if (session = @sessions[key])
        session.last_used = Time.current
        if session.chat.messages.length > MAX_MESSAGES
          @sessions.delete(key)
          return create_session(key, system_prompt: system_prompt, tools: tools)
        end
        session.chat
      else
        evict_oldest if @sessions.size >= MAX_SESSIONS
        create_session(key, system_prompt: system_prompt, tools: tools)
      end
    end
  end
end

The key is (author_id, personality) — each user has separate sessions for Marvin and for Akita. Volatile on purpose: restart the server, lose the history. No database, no serialization, no complexity. It’s working memory, not persistence.

/ask clear resets the session. Without it, there’s no way to “start over” when the conversation gets tangled.

Now:

/ask what is Ruby?
→ Ruby is a programming language created by Matz in 1995...

/ask compare it with Python
→ Ruby and Python have similar philosophies — both prioritize programmer
  happiness — but Ruby embraces blocks and metaprogramming while Python
  prefers explicitness...

The LLM knows “compare” refers to Ruby because the session history includes the previous question. That’s the difference between a chatbot and an assistant.

Pattern 13: Registering Application Commands (Native Autocomplete)

The Application Commands section above showed the simplified concept. In practice, registering 18 commands with subcommands, typed parameters and choices demands a dedicated structure. Here’s how the project handles it.

The Problem With Raw Text

When the bot only parses text, the user has to memorize the syntax:

/update score #1 #2 #3 high       ← works
/update score #1 #2 #3 alta       ← fails silently
/update scoree #1 high             ← ignored

No autocomplete, no parameter validation, no inline documentation. The user types / and has no idea what’s available.

The DiscordCommands Module

All command definitions live in a separate module with two public methods: register! (registers the commands with the Discord API) and setup_handlers! (wires the handlers to the bot):

module DiscordCommands
  SCORE_CHOICES  = { "High" => "high", "Medium" => "medium", "Low" => "low" }.freeze
  SECTION_CHOICES = {
    "Tech" => "tech", "Global" => "global", "Financial" => "financial",
    "Q&A" => "qa", "Entertainment" => "entertainment", "Open Source" => "opensource",
    "Product" => "product", "Book" => "book"
  }.freeze
  PERSONALITY_CHOICES = { "Marvin (default)" => "marvin", "Akita" => "akita" }.freeze

  def self.register!(bot)
    server_id = Rails.application.config.discord.server_id
    sid = server_id.present? ? server_id.to_i : nil

    register_week(bot, sid)
    register_add(bot, sid)
    register_update(bot, sid)
    register_ask(bot, sid)
    # ... 14 more commands
  end

  def self.setup_handlers!(bot)
    setup_week_handlers(bot)
    setup_add_handler(bot)
    setup_update_handlers(bot)
    setup_ask_handlers(bot)
    # ... 14 more handlers
  end
end

Guild vs Global

The server_id (or sid) controls the registration scope. With server_id, the command shows up instantly on the specified server. Without it, the command is global — available on every server, but can take up to an hour to propagate.

For a private bot doing internal operations, always go guild-scoped. The DISCORD_SERVER_ID env var is set at deploy time:

sid = server_id.present? ? server_id.to_i : nil
bot.register_application_command(:week, "Story list and weekly report", server_id: sid)

If sid is nil, discordrb registers globally. In dev it’s convenient; in production, guild-scoped is faster and lets you have different commands per server.

Anatomy of a Command

The simplest method — no parameters:

def self.register_count(bot, sid)
  bot.register_application_command(:count, "Show story count for this week", server_id: sid)
end

With typed parameters:

def self.register_add(bot, sid)
  bot.register_application_command(:add, "Submit a URL for the newsletter", server_id: sid) do |cmd|
    cmd.string(:url, "The URL to submit", required: true)
    cmd.string(:tags, "Tags (e.g. #tech #high)")
    cmd.string(:comment, "Optional comment about this link")
  end
end

Discord renders this as an inline form: required url field, optional tags and comment. The user sees each parameter’s description as they fill it in.

Subcommands: Grouping Actions

Complex commands use subcommands. /update on its own does nothing — the user has to pick what to update:

def self.register_update(bot, sid)
  bot.register_application_command(:update, "Update story properties", server_id: sid) do |cmd|
    cmd.subcommand(:score, "Update story priority score") do |sub|
      sub.string(:stories, "Story numbers (e.g. #1 #2 #3 or 1,2,3)", required: true)
      sub.string(:level, "Priority level", required: true, choices: SCORE_CHOICES)
    end
    cmd.subcommand(:tag, "Update story section tag") do |sub|
      sub.string(:stories, "Story numbers (e.g. #1 #2 #3 or 1,2,3)", required: true)
      sub.string(:section, "Section tag", required: true, choices: SECTION_CHOICES)
    end
    cmd.subcommand(:image, "Update story image") do |sub|
      sub.string(:stories, "Story numbers (e.g. #1 #2 #3 or 1,2,3)", required: true)
      sub.attachment(:file, "Image file (omit for AI generation)")
    end
    # ... more subcommands: title, description, comment, source
  end
end

When the user types /update, Discord shows a list of subcommands: score, tag, title, description, comment, image, source. Pick score and the stories field (free text) and level field (dropdown with High/Medium/Low) appear. Syntax errors become impossible.

Choices: Native Dropdowns

The SCORE_CHOICES hash becomes a dropdown on Discord. The key is the visible label (“High”), the value is what arrives in the handler (“high”):

SCORE_CHOICES = { "High" => "high", "Medium" => "medium", "Low" => "low" }.freeze

# In the registration:
sub.string(:level, "Priority level", required: true, choices: SCORE_CHOICES)

The user doesn’t have to remember whether it’s “high”, “HIGH”, “alta”, or “3”. Pick it from the dropdown and done. That eliminates an entire category of input errors.

Attachments: File Uploads

Discord supports attachment-type parameters — the user can drag a file straight into the command:

cmd.subcommand(:image, "Update story image") do |sub|
  sub.string(:stories, "Story numbers (e.g. #1 #2 #3 or 1,2,3)", required: true)
  sub.attachment(:file, "Image file (omit for AI generation)")
end

In the handler, the resolved attachments come through as Discord CDN URLs:

def self.resolve_attachments(event)
  return [] unless event.resolved&.attachments&.any?
  event.resolved.attachments.values.map(&:url)
end

Lifecycle: Where to Register, Where to Wire Handlers

This is the point that confuses people most. The handlers have to be registered before bot.run. The registration with the Discord API can happen inside bot.ready (which fires after the WebSocket connection):

class MarvinBotRunner
  def self.run!
    bot = Discordrb::Bot.new(token: token, intents: ...)

    # 1. Handlers BEFORE bot.run (otherwise the bot doesn't know how to respond)
    DiscordCommands.setup_handlers!(bot)

    bot.ready do |_event|
      # 2. API registration AFTER connection (idempotent, safe on reconnect)
      DiscordCommands.register!(bot)
    end

    bot.run
  end
end

Why inside bot.ready? Because the bot can reconnect (Discord closes WebSockets periodically). register! is idempotent — registering the same command twice doesn’t duplicate it, it just updates. Putting it in ready makes sure the commands exist even after a reconnect.

Bridge: Application Command → CommandDispatcher

The most elegant part of the architecture: the Application Command handler has no business logic. It translates Discord’s parameters into the format the CommandDispatcher already expects:

def self.dispatch_interaction(event, type, match: [nil], attachments: [])
  event.respond(content: "\u{2705}", ephemeral: true)  # checkmark visible only to the author
  command = SlashCommandParser::Command.new(
    type: type,
    args: { match: match, attachments: attachments }
  )
  CommandDispatcher.dispatch(command,
    channel_id: event.channel.id.to_s,
    message_id: nil,
    author_id: event.user.id.to_s
  )
rescue StandardError => e
  Rails.logger.error("Discord interaction error (#{type}): #{e.message}")
end

Each subcommand handler is a one-liner that assembles the args and calls dispatch_interaction:

bot.application_command(:update).subcommand(:score) do |event|
  stories = event.options["stories"]
  level = event.options["level"]
  dispatch_interaction(event, :update_score, match: [nil, stories, nil, level])
end

CommandDispatcher doesn’t know if the command came from raw text or from an Application Command. Same logic, same authorization, same jobs. No duplicated code.

The Result

The project registers 18 Application Commands with combinations of subcommands, typed parameters, dropdowns and file uploads. The user types / and sees everything available with descriptions. Pick a command and Discord guides you field by field. Syntax errors are impossible — Discord validates before sending.

And both systems coexist: people who prefer autocomplete use Application Commands, people who prefer to type fast use raw text. CommandDispatcher receives both the same way. Adding a new command means adding a register_*, a setup_*_handler, and a dispatcher method — without touching the runner.

The discordrb Pitfalls

It’s not all roses. Some real pain points:

Gateway disconnects: The WebSocket to Discord drops every once in a while. discordrb reconnects automatically, but your bot.ready and bot.message handlers need to be resilient to reconnects.

Message Content Intent: Since 2022, bots in more than 75 servers need approval to read message content. For private bots (which is the case for internal operations), that’s a non-issue. But if you plan to distribute the bot, get ready for paperwork.

API Rate Limits: Discord rate-limits per route. Sending 10 embeds at once to the same channel? You’ll hit the limit. discordrb handles rate limits internally, but calls that are too fast cause visible delays.

Embed Limits: Title max 256 chars. Description 4096. Field value 1024. Exceeded them? Silent error. Always truncate before sending.

File Uploads: 25MB limit on the free plan, 50MB with Nitro. For AI-generated images that’s never an issue, but if you’re shipping PDFs or audio, be careful.

When NOT to Use Discord as Admin

• Complex forms: editing 15 fields on a record? Web screen
• Bulk operations: importing a CSV with 1000 records? Script
• Data visualization: charts, analytical dashboards? Grafana/Metabase
• Multi-step approval: workflows with 5 approval stages? You need persisted state

But for day-to-day operations — curating content, approving newsletters, monitoring jobs, checking costs, talking to AI — Discord is the most productive interface I’ve ever used. And the best part: the subscribers will never know their weekly newsletter was curated by a guy typing commands into Discord on his phone while drinking coffee.

Conclusion

Using Discord as an admin panel isn’t laziness — it’s pragmatism. The best interface is the one you already use all day long. Auth, push notifications, mobile, rich formatting, file sharing — all free. You only build the business logic.

The ruby_llm gem with tool calling takes the bot from “command executor” to “assistant that thinks”. Add session memory and it thinks and remembers. When the LLM can generate images, search the web, keep context across questions, and answer questions about the architecture of its own system — that’s when it stops being CRUD and becomes a co-pilot.

And the Parser → Dispatcher → Job pattern keeps everything testable. The parser knows nothing about Discord. The dispatcher knows nothing about AI. The jobs know nothing about the interface. Swap any one of those layers and the others don’t even notice.

In the end, the best admin UI is the one that doesn’t need a separate deploy. And the worst bug is the one that fails in silence — if the bot is your operational interface, the bot’s failures need to show up on the interface, not hidden away in a log nobody reads.

And don’t forget to subscribe to my new newsletter The M.Akita Chronicles!

–

Ten years ago, fetching data from a website was trivial. Four lines of Ruby: Net::HTTP.get, Nokogiri parse, CSS selector, done. The whole world was open to any script with a decent User-Agent.

Today? Half the sites I need to read to put together my newsletter return “Are you a robot?” for any conventional HTTP request. The other half renders the content entirely in JavaScript — there’s no HTML at all in the server response. And the most paranoid ones combine both.

My goal was to create a daily routine so that M.arvin would deliver the top news to me in the morning on my Discord. That way I wouldn’t have to go hunting for the news of the day. Sounded simple… at first.

This post is about how I went from “one HTTP call” to “packing an entire Chromium into Docker” — and why this is the reality of any project that needs to read the web programmatically in 2026.

The Golden Age: Simple HTTP

Let’s start with what still works. Some services offer structured data with zero resistance:

# RSS feeds: the most resilient format on the web
uri = URI("https://news.google.com/rss/search?q=when:24h+allinurl:reuters.com/world")
xml = Net::HTTP.get(uri)
doc = REXML::Document.new(xml)
doc.get_elements("//item").each do |item|
  title = item.get_text("title").to_s
  url   = item.get_text("link").to_s
end

# Public APIs: clean JSON, documented, stable
response = HTTParty.get("https://api.jikan.moe/v4/top/anime?filter=airing")
animes = response.parsed_response["data"]

# GitHub trending: server-rendered HTML with no protection
html = HTTParty.get("https://github.com/trending").body
doc = Nokogiri::HTML(html)
repos = doc.css("article.Box-row")

Hacker News, GitHub Trending, anime APIs, RSS feeds, Project Gutenberg — they all work with a GET and a parser. No JavaScript, no implicit authentication, no fingerprinting. Just like the web was supposed to be.

The problem is that these are the exception. Sites with financial data, exclusive news, or premium content — exactly the data that matters most — are increasingly armored.

The First Obstacle: SPAs and JavaScript Rendering

When the server returns something like:

<html>
<body>
  <div id="root"></div>
  <script src="/app-3fa8c2.js"></script>
</body>
</html>

Your Net::HTTP.get returns exactly that: an empty div and a link to a 2 MB bundle. The real content — articles, prices, lists — is assembled in the browser by React, Vue, Angular, or the framework of the week.

For a script, this page is useless. To extract the content, you need to execute the JavaScript. That means running a real browser.

In the Ruby world, the answer is the ferrum gem — a CDP (Chrome DevTools Protocol) client that controls Chromium programmatically:

browser = Ferrum::Browser.new(headless: "new", timeout: 30)
browser.go_to("https://www.morningstar.com/markets")
browser.network.wait_for_idle  # wait for JS to finish loading
html = browser.body  # now the DOM is populated
browser.quit

That browser.body returns the HTML after the JavaScript has executed. The same data you see in the browser, now accessible to your parser.

But here’s where the headache begins: you need a Chromium binary available on the system. In Docker, that means adding ~300MB to the image. On the server, that’s one more dependency to manage. And the latency of opening a browser, navigating, waiting for JS to render, and extracting the HTML — we’re talking 3 to 10 seconds per page, instead of the 200ms of an HTTP GET.

The project uses this as the main strategy in ArticleFetcher: first it tries with a browser (to catch SPAs), then falls back to simple HTTP (to grab OpenGraph metadata when the browser fails). Most of the links that readers send in Discord are from sites that render with JavaScript, so browser-first pays off.

The Second Obstacle: Bot Detection

Opening a page with headless Chromium solves the JavaScript problem. But it solves 50% of the sites — not 100%. Because there’s an entire industry dedicated to distinguishing real browsers from automated browsers.

What Headless Chrome Reveals

Chromium in headless mode is almost identical to regular Chrome. Almost. The differences are subtle, but enough for detection:

1. navigator.webdriver — In any Chrome controlled by automation, this property returns true. In normal browsers, undefined. It’s the most obvious flag.

2. navigator.plugins — Normal Chrome has 3-5 plugins (PDF viewer, etc.). Headless returns an empty array. Bot detected.

3. navigator.userAgentData — The Client Hints API. Real Chrome returns brands, platform, mobile flag. Headless may not have that.

4. WebGL fingerprint — The WebGL renderer in a headless Chrome returns “SwiftShader” (software renderer). Real Chrome returns “NVIDIA GeForce” or “Intel Iris” or whatever. Bot detected.

5. Timing and behavior — Real browsers take time to load. They scroll. They move the mouse. They have focus events. A script that does go_to → body in 2 seconds doesn’t look like a human.

The solution is what I call StealthBrowser — a wrapper that injects JavaScript patches before any script on the page runs:

class StealthBrowser
  STEALTH_JS = <<~JS
    // Remove the automation flag
    Object.defineProperty(navigator, 'webdriver', { get: () => false });

    // Simulate real plugins
    Object.defineProperty(navigator, 'plugins', {
      get: () => [
        { name: 'Chrome PDF Plugin', filename: 'internal-pdf-viewer' },
        { name: 'Chrome PDF Viewer', filename: 'mhjfbmdgcfjbbpaeojofohoefgiehjai' },
        { name: 'Native Client', filename: 'internal-nacl-plugin' }
      ]
    });

    // Simulate a real WebGL renderer
    const getParameter = WebGLRenderingContext.prototype.getParameter;
    WebGLRenderingContext.prototype.getParameter = function(p) {
      if (p === 37445) return 'Google Inc. (NVIDIA)';
      if (p === 37446) return 'ANGLE (NVIDIA, GeForce GTX 1080 ...)';
      return getParameter.call(this, p);
    };

    // Client Hints API (absent in headless = bot signal)
    if (!navigator.userAgentData) {
      Object.defineProperty(navigator, 'userAgentData', {
        get: () => ({
          brands: [
            { brand: 'Chromium', version: '131' },
            { brand: 'Google Chrome', version: '131' }
          ],
          mobile: false, platform: 'Linux'
        })
      });
    }
  JS

  def self.fetch(url, name:, wait_for: nil)
    browser = Ferrum::Browser.new(headless: "new", timeout: 30,
      browser_options: {
        "disable-blink-features" => "AutomationControlled",
        "user-agent" => REAL_USER_AGENT
      })

    # Inject BEFORE any script on the page runs
    browser.page.command("Page.addScriptToEvaluateOnNewDocument", source: STEALTH_JS)

    browser.go_to(url)
    yield browser
  ensure
    browser&.quit
  end
end

The key trick is Page.addScriptToEvaluateOnNewDocument — a CDP command that registers JavaScript to be executed before any script on the page. That means when the bot detector runs, it sees the fake values we injected, not the real ones. And disable-blink-features=AutomationControlled removes the navigator.webdriver flag at the browser level, even before JavaScript.

This works for most sites. Morningstar, Hindenburg Research, generic news sites — they pass with the stealth. Yahoo Finance needs more — TLS fingerprinting that blocks even Chromium without crumb authentication. But the stealth browser handles the bulk.

The Third Obstacle: DataDome and Anti-Bot CDPs

And now we get to the pros. DataDome, Cloudflare Turnstile, PerimeterX, Akamai Bot Manager — services specialized in detecting automation. And they play at a completely different level.

Reuters, for example, uses DataDome. When I tried to hit reuters.com/world/ with StealthBrowser, I got back a 1,500-byte page with a JavaScript captcha. All the navigator.webdriver, WebGL, plugin patches — useless.

Why? Because DataDome doesn’t just check JavaScript properties. It detects the automation protocol itself.

The Fundamental Problem with CDP

When Ferrum (or Puppeteer, or Playwright) controls a Chrome, it does so via the Chrome DevTools Protocol — CDP. And the first thing Ferrum does when connecting is send Runtime.enable — a command that enables runtime evaluation in the browser.

The problem is that Runtime.enable changes the observable behavior of the browser. Specifically, it activates internal interceptors that can be detected via console.debug. DataDome uses this: it does a console.debug with a getter that watches whether the runtime is intercepting. If it is — and with CDP it always is — bot detected.

// What DataDome does (simplified):
let detected = false;
const el = document.createElement('div');
Object.defineProperty(el, 'id', {
  get: () => { detected = true; return 'test'; }
});
console.debug(el);
// If Runtime.enable is active, the getter is triggered
// In a normal browser, it isn't

This is not something you can patch with JavaScript. Runtime.enable is sent by Ferrum before any script runs — it’s part of the automation protocol. To fix this, you’d have to modify Ferrum to not send that command, which would break most of the gem’s functionality.

The Alternatives (and Why None Are Ideal)

I researched extensively. The options:

1. nodriver (Python): Uses Chrome via CDP without Runtime.enable. No equivalent in Ruby. And even so, it’s in a cat-and-mouse race with DataDome.

2. curl-impersonate: Does TLS fingerprinting identical to Chrome without opening a browser. Good for sites with TLS detection, useless for SPAs.

3. Scraping APIs (ScraperAPI, ZenRows): Outsource the problem. They work, but they cost money and add latency and dependency.

4. Fork Ferrum: Modify the gem to optionally not send Runtime.enable. Technically viable, but endless maintenance.

5. Google News RSS: Google has already read Reuters. The result is in a public RSS feed. No JavaScript, no DataDome, no browser.

Option 5 won. For Reuters, I traded all the headless browser complexity for:

class ReutersClient
  RSS_URL = "https://news.google.com/rss/search?q=when:24h+allinurl:reuters.com/world"

  def self.fetch_headlines(limit: 10)
    xml = Net::HTTP.get(URI(RSS_URL))
    doc = REXML::Document.new(xml)
    doc.get_elements("//item").first(limit).filter_map do |item|
      title = item.get_text("title")&.to_s&.strip
      url   = item.get_text("link")&.to_s&.strip
      next if title.blank? || url.blank?
      { title: title.sub(/\s*-\s*Reuters\s*\z/, ""), url: url, category: nil }
    end
  rescue StandardError => e
    Rails.logger.warn("ReutersClient failed: #{e.message}")
    []
  end
end

Simple. Reliable. Zero browser dependencies. The Google News link redirects to the original article when the reader clicks — works perfectly for a newsletter.

Not every scraping problem needs a scraping solution. Sometimes the data is already available in an accessible format — you just have to find it.

The Fourth Obstacle: Sites That Change Structure (Daily)

Even when scraping works, maintenance never stops. Morningstar is a textbook case — because it made me get it wrong twice before reaching a resilient solution.

Attempt 1: Select by DOM Hierarchy

Originally, the article links were inside <h2> and <h3>:

<h2><a href="/markets/article-slug">Article Title</a></h2>

One day later: zero results. Morningstar changed the structure to flat links with specific CSS classes — no heading elements:

<a class="mdc-basic-feed-item__mdc" href="/markets/article-slug">
  <header><h3>Article Title</h3></header>
  <div class="mdc-metadata__mdc">Author · Date</div>
</a>

Attempt 2: Select by CSS Class

The obvious fix: swap DOM hierarchy for CSS selectors based on the component class:

ARTICLE_CSS = "a.mdc-basic-feed-item__mdc, a.mdc-card--link__mdc"
doc.css(ARTICLE_CSS).each { |link| ... }

It worked. For exactly one day. Then: zero results again. Morningstar — like many modern sites with CSS-in-JS frameworks — generates class names dynamically. What was mdc-basic-feed-item__mdc became something else. And it may become something else tomorrow.

This is increasingly common. Sites using CSS Modules, styled-components, or Tailwind with JIT generate random hashes in class names as part of the build. Every time the site deploys, the classes change. Your hardcoded selector is a time bomb.

Attempt 3: Don’t Rely on Any Class Name

The final solution is to flip the logic: instead of telling the parser which classes to look for, let the parser discover which links are articles based on structural properties that don’t change:

1. Article links have long URLs: /news/why-stock-market-is-up-today-2026-02-17 vs. navigation links like /markets or /tools
2. Article links are grouped: they appear in lists, feeds, grids — multiple links with the same CSS class
3. Article links have descriptive titles: long text, not short labels like “Markets” or “Tools”

The algorithm:

def self.parse_html(html, limit)
  doc = Nokogiri::HTML(html)

  # 1. Collect all internal <a> with href, class, and enough text
  candidates = doc.css("a[href]").filter_map do |link|
    href = link["href"].to_s.strip
    css_class = link["class"].to_s.strip
    next if href.blank? || css_class.blank?
    next unless internal_href?(href)

    path = extract_path(href)
    segments = path.split("/").reject(&:empty?)
    next if segments.length < 2  # nav links have 1 segment: /markets

    title = extract_title(link)
    next if title.blank? || title.length < 10

    { title: title, url: absolutize(href), css_class: css_class, slug_length: path.length }
  end

  # 2. Group by CSS class
  groups = candidates.group_by { |c| c[:css_class] }

  # 3. Filter: minimum 3 links in the group (article clusters, not stray links)
  # 4. Pick the group with the highest average slug length
  best = groups
    .select { |_cls, items| items.length >= 3 }
    .max_by { |_cls, items| items.sum { |i| i[:slug_length] }.to_f / items.length }

  return [] unless best

  best[1].map { |c| c.slice(:title, :url) }.uniq { |a| a[:url] }.first(limit)
end

What saves this approach: no class name is hardcoded. Morningstar can rename every class tomorrow and the parser will keep working — because it discovers the article pattern through structure, not through names.

What’s stable on a site:

• Article URLs are always longer than navigation URLs (that’s architectural, not cosmetic)
• Articles are always grouped under the same component (that’s UX, not implementation)
• Article titles are descriptive (that’s editorial, not technical)

What’s not stable:

• CSS class names (change on every build)
• DOM hierarchy (changes on every redesign)
• data-* attributes (change as the frontend team decides)

Bottom line: don’t try to identify elements by name — identify them by behavior. Article links behave differently from navigation links in measurable ways (URL length, clustering, title), and those properties are inherent to what the element IS, not to how it was implemented.

The Reliability Hierarchy

After hours of banging my head, a hierarchy of data sources became obvious:

The rule: always prefer the simplest source that works. If the site has RSS, use RSS. If it has an API, use the API. Only go to the headless browser when there’s no alternative.

In the project, the distribution ended up like this:

Simple HTTP (Net::HTTP or HTTParty):

• Google News RSS (Reuters world headlines)
• Hacker News RSS (top stories)
• HackerNoon RSS (top stories)
• dev.to API (trending articles)
• Jikan API (anime rankings)
• YouTube Data API (videos)
• Yahoo Finance news RSS

Headless browser (StealthBrowser + Ferrum):

• Morningstar (SPA + dynamic components)
• Yahoo Finance charts (TLS fingerprinting + crumb auth)
• FinViz market map (canvas rendering)
• Generic reader articles (any URL could be an SPA)
• Hindenburg Research (JavaScript-rendered)

In other words: most data sources work without a browser. The browser is needed for a handful of problem sites — but those sites are the ones that cause the most trouble.

The Real Cost

Let’s be practical about what “packing a Chrome” means:

Docker image: +300MB. Chromium and its dependencies (fonts, graphics libs, sandbox) are huge. In an optimized Dockerfile with multi-stage build:

# Install Chromium and minimal dependencies
RUN apt-get install -y chromium fonts-liberation libnss3 libatk-bridge2.0-0 \
    libdrm2 libxkbcommon0 libgbm1

Memory: Each Chromium instance consumes 200-400MB of RAM. If you have 3 parallel workers, that’s 1.2GB just for browsers. On a 2GB VPS, that’s 60% of the memory.

Latency: A page that takes 200ms via HTTP takes 3-8 seconds via headless browser (process boot, navigation, JS execution, network idle). For 10 data sources, that’s 30-80 seconds instead of 2.

Stability: Chromium can crash, hang, or leak memory. A 30-second timeout with cleanup in ensure is mandatory:

def self.fetch(url, name:)
  browser = create(name: name)
  browser.go_to(url)
  yield browser
ensure
  browser&.quit  # ALWAYS quit, even on exception
end

If you don’t quit, the Chromium process stays hanging around burning CPU and memory. I’ve had a server with 15 zombie Chrome processes eating 3GB of RAM because an ensure was missing.

The Future (Or: It’s Going to Get Worse)

The trend is clear: sites are getting harder to access programmatically. Every quarter, the DataDomes and Cloudflares of the world add new detection techniques. Headless Chrome gets more similar to real Chrome — but the detectors keep up.

The web that was born open and machine-readable is becoming a walled garden. Even RSS, which is trivial to implement and useful to everyone, is being abandoned by many sites — because they don’t want their data read outside the context (and the ads) of the original site.

For anyone building systems that aggregate information, the playbook is:

1. Use APIs and feeds whenever they exist. More stable, faster, more respectful
2. Keep a stealth browser for SPAs that have no alternative
3. Never hardcode CSS selectors. Sites with CSS-in-JS change class names on every deploy. Identify elements by structural properties (URL length, clustering, title size) that survive redesigns
4. Detect blocks and fail gracefully — og:description as fallback, title extracted from the URL as a last resort
5. Never depend on a single access method. The site that works today may block tomorrow
6. Accept that some sites are inaccessible. If DataDome won’t allow it, the data will have to come from another source

The web in 2026 is a battlefield between those who want to read and those who want to control the reading. But in the long run, the creativity of those who want to access data wins — but it costs more effort every year. And, contrary to what I thought at the beginning: it’s never simple.

I still don’t fully understand how much of a difference it makes, but both OpenCode and Crush support Language Servers (LSPs), so I thought it’d be cool to have it configured. Here’s my ~/.config/crush/crush.json:

{
  "$schema": "https://charm.land/crush.json",
  "default_provider": "openrouter",
  "providers": {
    "openrouter": {
      "api_key": "sk-..."
    },
    "lmstudio": {
      "name": "LM Studio",
      "base_url": "http://localhost:1234/v1/",
      "type": "openai",
      "models": [
        {
          "name": "gpt-oss-120b",
          "id": "gpt-oss:120b",
          "context_window": 100000,
          "default_max_tokens": -1,
          "supports_tools": true
        },
        {
          "name": "gpt-oss-20b",
          "id": "gpt-oss:20b",
          "context_window": 130000,
          "default_max_tokens": -1,
          "supports_tools": true
        },
        {
          "name": "zai-org/glm-4.6v-flash",
          "id": "glm-4.6v-flash",
          "context_window": 130000,
          "default_max_tokens": -1,
          "supports_tools": true
        },
        {
          "name": "deepseek-coder-v2-lite-instruct",
          "id": "deepseek-coder-v2-lite-instruct",
          "context_window": 64000,
          "default_max_tokens": -1,
          "supports_tools": true
        },
        {
          "id": "qwen/qwen3-coder-30b",
          "name": "qwen3-coder-30b",
          "context_window": 120000,
          "default_max_tokens": -1,
          "supports_tools": true
        }
      ]
    },
    "ollama": {
      "type": "openai-compat",
      "base_url": "http://127.0.0.1:11434/v1",
      "api_key": "ollama",
      "models": [
        {
          "name": "glm-4.7-flash",
          "id": "glm-4.7-flash",
          "context_window": 65536,
          "default_max_tokens": -1,
          "supports_tools": true
        },
        {
          "name": "gpt-oss-20b",
          "id": "gpt-oss:20b",
          "context_window": 64000,
          "default_max_tokens": -1,
          "supports_tools": true
        },
        {
          "id": "qwen3-nuclear",
          "name": "qwen3-nuclear",
          "context_window": 120000,
          "default_max_tokens": -1,
          "supports_tools": true
        },
        {
          "id": "qwen3-coder:30b",
          "name": "qwen3-coder:30b",
          "context_window": 120000,
          "default_max_tokens": -1,
          "supports_tools": true
        },
        {
          "id": "qwen2.5-coder:32b",
          "name": "qwen2.5-coder:32b",
          "context_window": 32768,
          "default_max_tokens": -1,
          "supports_tools": true
        },
        {
          "id": "deepseek-coder-v2:16b",
          "name": "deepseek-coder-v2:16b",
          "context_window": 128000,
          "default_max_tokens": -1,
          "supports_tools": true
        },
        {
          "id": "glm-4.7:cloud",
          "name": "glm-4.7:cloud",
          "context_window": 128000,
          "default_max_tokens": -1,
          "supports_tools": true
        }
      ]
    }
  },
  "lsp": {
    "gopls": {
      "command": "gopls"
    },
    "rust-analyzer": {
      "command": "rust-analyzer"
    },
    "ruby-lsp": {
      "command": "ruby-lsp"
    },
    "solargraph": {
      "command": "solargraph",
      "args": [
        "stdio"
      ]
    },
    "pylsp": {
      "command": "pylsp"
    },
    "pyright": {
      "command": "pyright-langserver",
      "args": [
        "--stdio"
      ]
    },
    "elixir-ls": {
      "command": "elixir-ls"
    },
    "docker-langserver": {
      "command": "docker-langserver",
      "args": [
        "--stdio"
      ],
      "languages": [
        "dockerfile"
      ]
    },
    "bash-language-server": {
      "command": "bash-language-server",
      "args": [
        "start"
      ]
    },
    "marksman": {
      "command": "marksman",
      "args": [
        "server"
      ]
    },
    "typescript-language-server": {
      "command": "typescript-language-server",
      "args": [
        "--stdio"
      ]
    },
    "vscode-html-language-server": {
      "command": "vscode-html-language-server",
      "args": [
        "--stdio"
      ]
    },
    "vscode-css-language-server": {
      "command": "vscode-css-language-server",
      "args": [
        "--stdio"
      ]
    },
    "vscode-json-language-server": {
      "command": "vscode-json-language-server",
      "args": [
        "--stdio"
      ]
    },
    "yaml-language-server": {
      "command": "yaml-language-server",
      "args": [
        "--stdio"
      ]
    },
    "taplo": {
      "command": "taplo",
      "args": [
        "lsp",
        "stdio"
      ]
    }
  },
  "mcp": {
    "blender": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "blender-mcp"
      ]
    }
  }
}

Note that I primarily use Claude Opus 4.5 via OpenRouter and I have LM Studio and Ollama configured as providers for testing other open source models.

I also use Mise to organize the programming languages I use.

But now you need to install the LSPs for each language. I don’t know of a better way to manage this the same way Mason does in Neovim. So I made a script to install everything for me (on my Arch Linux). For that I created this script ~/.local/bin/install-lsps.sh:

#!/usr/bin/env bash
set -euo pipefail

# LSP Installer for Arch Linux with Mise
# Installs major LSPs using native package managers or yay
# Only installs LSPs for languages that are already installed

GREEN='\033[0;32m'
BLUE='\033[0;34m'
YELLOW='\033[1;33m'
RED='\033[0;31m'
NC='\033[0m'

info() { echo -e "${BLUE}[INFO]${NC} $1"; }
success() { echo -e "${GREEN}[OK]${NC} $1"; }
warn() { echo -e "${YELLOW}[SKIP]${NC} $1"; }
skip_lang() { echo -e "${RED}[LANG]${NC} $1 not installed, skipping LSPs"; }

command_exists() { command -v "$1" &>/dev/null; }

# ─────────────────────────────────────────────────────────────
# Language detection helpers
# ─────────────────────────────────────────────────────────────
has_c()       { command_exists gcc || command_exists clang; }
has_rust()    { command_exists rustc || command_exists cargo; }
has_go()      { command_exists go; }
has_python()  { command_exists python || command_exists python3; }
has_node()    { command_exists node || command_exists npm; }
has_java()    { command_exists java || command_exists javac; }
has_kotlin()  { command_exists kotlin || command_exists kotlinc; }
has_ruby()    { command_exists ruby; }
has_php()     { command_exists php; }
has_lua()     { command_exists lua || command_exists luajit; }
has_zig()     { command_exists zig; }
has_haskell() { command_exists ghc || command_exists stack || command_exists cabal; }
has_elixir()  { command_exists elixir || command_exists iex; }
has_scala()   { command_exists scala || command_exists sbt; }
has_dotnet()  { command_exists dotnet; }
has_ocaml()   { command_exists ocaml || command_exists opam; }
has_clojure() { command_exists clojure || command_exists clj || command_exists lein; }
has_nix()     { command_exists nix; }
has_terraform() { command_exists terraform || command_exists tofu; }
has_latex()   { command_exists latex || command_exists pdflatex || command_exists xelatex; }
has_docker()  { command_exists docker || command_exists podman; }
has_ansible() { command_exists ansible; }
has_sql()     { command_exists psql || command_exists mysql || command_exists sqlite3; }
has_bash()    { command_exists bash; }

# ─────────────────────────────────────────────────────────────
# Package installation helpers
# ─────────────────────────────────────────────────────────────
install_pacman() {
    local pkg="$1"
    if pacman -Qi "$pkg" &>/dev/null; then
        warn "$pkg already installed"
    else
        sudo pacman -S --noconfirm --needed "$pkg" && success "$pkg" || warn "Failed: $pkg"
    fi
}

install_yay() {
    local pkg="$1"
    if ! command_exists yay; then
        warn "yay not found, skipping $pkg"
        return
    fi
    if yay -Qi "$pkg" &>/dev/null; then
        warn "$pkg already installed"
    else
        yay -S --noconfirm --needed "$pkg" && success "$pkg" || warn "Failed: $pkg"
    fi
}

install_npm() {
    local pkg="$1"
    if npm list -g "$pkg" &>/dev/null 2>&1; then
        warn "$pkg already installed"
    else
        npm install -g "$pkg" && success "$pkg" || warn "Failed: $pkg"
    fi
}

install_pipx() {
    local pkg="$1"
    if ! command_exists pipx; then
        pip install --user pipx 2>/dev/null || {
            pip install --user "$pkg" && success "$pkg" || warn "Failed: $pkg"
            return
        }
    fi
    if pipx list 2>/dev/null | grep -q "$pkg"; then
        warn "$pkg already installed"
    else
        pipx install "$pkg" && success "$pkg" || warn "Failed: $pkg"
    fi
}

install_go() {
    local pkg="$1"
    local name="${pkg##*/}"
    name="${name%%@*}"
    
    # Check if binary already exists in GOPATH/bin
    local gobin="${GOBIN:-${GOPATH:-$HOME/go}/bin}"
    if [[ -x "$gobin/$name" ]]; then
        warn "$name already installed"
        return
    fi
    
    go install "$pkg" && success "$name" || warn "Failed: $name"
}

install_gem() {
    local pkg="$1"
    if gem list -i "^${pkg}$" &>/dev/null; then
        warn "$pkg already installed"
    else
        gem install "$pkg" && success "$pkg" || warn "Failed: $pkg"
    fi
}

# ─────────────────────────────────────────────────────────────
# C/C++ LSPs
# ─────────────────────────────────────────────────────────────
install_c_lsps() {
    if ! has_c; then
        skip_lang "C/C++ (gcc/clang)"
        return
    fi
    info "Installing C/C++ LSPs..."
    install_pacman clang  # includes clangd
}

# ─────────────────────────────────────────────────────────────
# Rust LSPs
# ─────────────────────────────────────────────────────────────
install_rust_lsps() {
    if ! has_rust; then
        skip_lang "Rust"
        return
    fi
    info "Installing Rust LSPs..."
    
    if command_exists rustup; then
        rustup component add rust-analyzer 2>/dev/null && success "rust-analyzer (rustup)" || install_pacman rust-analyzer
    else
        install_pacman rust-analyzer
    fi
}

# ─────────────────────────────────────────────────────────────
# Go LSPs
# ─────────────────────────────────────────────────────────────
install_go_lsps() {
    if ! has_go; then
        skip_lang "Go"
        return
    fi
    info "Installing Go LSPs..."
    
    install_go golang.org/x/tools/gopls@latest
    install_go github.com/go-delve/delve/cmd/dlv@latest
    install_go github.com/nametake/golangci-lint-langserver@latest
}

# ─────────────────────────────────────────────────────────────
# Python LSPs
# ─────────────────────────────────────────────────────────────
install_python_lsps() {
    if ! has_python; then
        skip_lang "Python"
        return
    fi
    info "Installing Python LSPs..."
    
    # Prefer npm pyright (faster updates) if node available
    if has_node; then
        install_npm pyright
    else
        install_pipx pyright
    fi
    
    install_pipx python-lsp-server
    install_pipx ruff-lsp
}

# ─────────────────────────────────────────────────────────────
# Node.js/TypeScript LSPs
# ─────────────────────────────────────────────────────────────
install_node_lsps() {
    if ! has_node; then
        skip_lang "Node.js"
        return
    fi
    info "Installing Node.js/TypeScript LSPs..."
    
    install_npm typescript
    install_npm typescript-language-server
    install_npm vscode-langservers-extracted  # HTML, CSS, JSON, ESLint
    install_npm "@tailwindcss/language-server"
    install_npm "@vue/language-server"
    install_npm svelte-language-server
    install_npm graphql-language-service-cli
    install_npm "@prisma/language-server"
    install_npm emmet-ls
}

# ─────────────────────────────────────────────────────────────
# Java LSPs
# ─────────────────────────────────────────────────────────────
install_java_lsps() {
    if ! has_java; then
        skip_lang "Java"
        return
    fi
    info "Installing Java LSPs..."
    install_yay jdtls
}

# ─────────────────────────────────────────────────────────────
# Kotlin LSPs
# ─────────────────────────────────────────────────────────────
install_kotlin_lsps() {
    if ! has_kotlin; then
        skip_lang "Kotlin"
        return
    fi
    info "Installing Kotlin LSPs..."
    install_yay kotlin-language-server
}

# ─────────────────────────────────────────────────────────────
# Ruby LSPs
# ─────────────────────────────────────────────────────────────
install_ruby_lsps() {
    if ! has_ruby; then
        skip_lang "Ruby"
        return
    fi
    info "Installing Ruby LSPs..."
    install_gem solargraph
    install_gem ruby-lsp
}

# ─────────────────────────────────────────────────────────────
# PHP LSPs
# ─────────────────────────────────────────────────────────────
install_php_lsps() {
    if ! has_php; then
        skip_lang "PHP"
        return
    fi
    if ! has_node; then
        warn "PHP LSP (intelephense) requires npm, skipping"
        return
    fi
    info "Installing PHP LSPs..."
    install_npm intelephense
}

# ─────────────────────────────────────────────────────────────
# Lua LSPs
# ─────────────────────────────────────────────────────────────
install_lua_lsps() {
    if ! has_lua; then
        skip_lang "Lua"
        return
    fi
    info "Installing Lua LSPs..."
    install_pacman lua-language-server
}

# ─────────────────────────────────────────────────────────────
# Zig LSPs
# ─────────────────────────────────────────────────────────────
install_zig_lsps() {
    if ! has_zig; then
        skip_lang "Zig"
        return
    fi
    info "Installing Zig LSPs..."
    install_pacman zls
}

# ─────────────────────────────────────────────────────────────
# Haskell LSPs
# ─────────────────────────────────────────────────────────────
install_haskell_lsps() {
    if ! has_haskell; then
        skip_lang "Haskell"
        return
    fi
    info "Installing Haskell LSPs..."
    install_yay haskell-language-server
}

# ─────────────────────────────────────────────────────────────
# Elixir LSPs
# ─────────────────────────────────────────────────────────────
install_elixir_lsps() {
    if ! has_elixir; then
        skip_lang "Elixir"
        return
    fi
    info "Installing Elixir LSPs..."
    install_yay elixir-ls
}

# ─────────────────────────────────────────────────────────────
# Scala LSPs
# ─────────────────────────────────────────────────────────────
install_scala_lsps() {
    if ! has_scala; then
        skip_lang "Scala"
        return
    fi
    info "Installing Scala LSPs..."
    install_yay metals
}

# ─────────────────────────────────────────────────────────────
# C# / F# (.NET) LSPs
# ─────────────────────────────────────────────────────────────
install_dotnet_lsps() {
    if ! has_dotnet; then
        skip_lang ".NET (C#/F#)"
        return
    fi
    info "Installing .NET LSPs..."
    install_yay omnisharp-roslyn
    install_yay fsautocomplete
}

# ─────────────────────────────────────────────────────────────
# OCaml LSPs
# ─────────────────────────────────────────────────────────────
install_ocaml_lsps() {
    if ! has_ocaml; then
        skip_lang "OCaml"
        return
    fi
    info "Installing OCaml LSPs..."
    if command_exists opam; then
        opam install ocaml-lsp-server -y && success "ocaml-lsp-server" || warn "Failed"
    else
        install_yay ocaml-lsp-server
    fi
}

# ─────────────────────────────────────────────────────────────
# Clojure LSPs
# ─────────────────────────────────────────────────────────────
install_clojure_lsps() {
    if ! has_clojure; then
        skip_lang "Clojure"
        return
    fi
    info "Installing Clojure LSPs..."
    install_yay clojure-lsp-bin
}

# ─────────────────────────────────────────────────────────────
# Nix LSPs
# ─────────────────────────────────────────────────────────────
install_nix_lsps() {
    if ! has_nix; then
        skip_lang "Nix"
        return
    fi
    info "Installing Nix LSPs..."
    install_pacman nil
}

# ─────────────────────────────────────────────────────────────
# Bash LSPs
# ─────────────────────────────────────────────────────────────
install_bash_lsps() {
    if ! has_bash; then
        skip_lang "Bash"
        return
    fi
    info "Installing Bash LSPs..."
    install_pacman bash-language-server
}

# ─────────────────────────────────────────────────────────────
# Terraform LSPs
# ─────────────────────────────────────────────────────────────
install_terraform_lsps() {
    if ! has_terraform; then
        skip_lang "Terraform"
        return
    fi
    info "Installing Terraform LSPs..."
    install_pacman terraform-ls
}

# ─────────────────────────────────────────────────────────────
# LaTeX LSPs
# ─────────────────────────────────────────────────────────────
install_latex_lsps() {
    if ! has_latex; then
        skip_lang "LaTeX"
        return
    fi
    info "Installing LaTeX LSPs..."
    install_pacman texlab
}

# ─────────────────────────────────────────────────────────────
# Docker LSPs
# ─────────────────────────────────────────────────────────────
install_docker_lsps() {
    if ! has_docker; then
        skip_lang "Docker"
        return
    fi
    info "Installing Docker LSPs..."
    install_yay dockerfile-language-server
}

# ─────────────────────────────────────────────────────────────
# Ansible LSPs
# ─────────────────────────────────────────────────────────────
install_ansible_lsps() {
    if ! has_ansible; then
        skip_lang "Ansible"
        return
    fi
    if ! has_node; then
        warn "Ansible LSP requires npm, skipping"
        return
    fi
    info "Installing Ansible LSPs..."
    install_npm "@ansible/ansible-language-server"
}

# ─────────────────────────────────────────────────────────────
# SQL LSPs
# ─────────────────────────────────────────────────────────────
install_sql_lsps() {
    if ! has_sql; then
        skip_lang "SQL (psql/mysql/sqlite)"
        return
    fi
    info "Installing SQL LSPs..."
    install_pacman sqls
}

# ─────────────────────────────────────────────────────────────
# Generic config file LSPs (always install)
# ─────────────────────────────────────────────────────────────
install_generic_lsps() {
    info "Installing generic config LSPs (YAML, TOML, JSON, Markdown, XML)..."
    install_pacman yaml-language-server
    install_pacman taplo               # TOML
    install_pacman marksman            # Markdown
    install_yay lemminx                # XML
}

# ─────────────────────────────────────────────────────────────
# Main
# ─────────────────────────────────────────────────────────────
main() {
    echo "═══════════════════════════════════════════════════════════"
    echo "         LSP Installer for Arch Linux + Mise"
    echo "    (Only installs LSPs for detected languages)"
    echo "═══════════════════════════════════════════════════════════"
    echo
    
    # Language-specific LSPs
    install_c_lsps
    install_rust_lsps
    install_go_lsps
    install_python_lsps
    install_node_lsps
    install_java_lsps
    install_kotlin_lsps
    install_ruby_lsps
    install_php_lsps
    install_lua_lsps
    install_zig_lsps
    install_haskell_lsps
    install_elixir_lsps
    install_scala_lsps
    install_dotnet_lsps
    install_ocaml_lsps
    install_clojure_lsps
    install_nix_lsps
    install_bash_lsps
    install_terraform_lsps
    install_latex_lsps
    install_docker_lsps
    install_ansible_lsps
    install_sql_lsps
    
    echo
    # Always-useful LSPs for config files
    install_generic_lsps
    
    echo
    echo "═══════════════════════════════════════════════════════════"
    success "LSP installation complete!"
    echo "═══════════════════════════════════════════════════════════"
}

main "$@"