DEV Community

30 Domain Templates for Your LLM Knowledge Base: Skip the Setup, Start Capturing

Paul Chen — Tue, 15 Sep 2026 01:17:15 +0000

The hardest part isn't the LLM layer

The hardest part of building an LLM knowledge base for a specific domain isn't wiring up the models, it's encoding how that domain thinks. A compliance analyst's knowledge base needs every obligation mapped to a specific regulation, every control to an owner, every exception to an approver. A clinical wiki needs evidence grades on every claim. A DevOps runbook system needs incident timelines and rollback steps. The query routing, intake form fields, and quality standards are all different — and none of that comes pre-configured.

Most teams spend the first two weeks not capturing knowledge but arguing about structure: what pages should exist, how routing should decompose, which source types need their own forms. By the time those questions are settled, content has already been ingested into the wrong shape and needs to be redone.

synthadoc install --template solves this in one command.

What a Domain Template Actually Provides

A domain template is not a demo or a sample dataset. It is a pre-made structural skeleton for a specific knowledge domain - everything that governs how knowledge is organized, ingested, and queried, without any of the actual content.

One install command gives you six structural components:

1. Query routing table (ROUTING.md)

The map that tells the query engine which branches of your wiki to search based on the nature of the question. A finance/investment template routes "capital structure questions" to debt financing and covenant pages, while routing "valuation questions" to financial models and comparable companies. Writing this from scratch requires domain knowledge most developers building a knowledge system do not have — and the gap shows up as poor retrieval quality until someone with that expertise intervenes.

2. Domain-tuned agent guidelines

Each template ships with CLAUDE.md, AGENTS.md, and GEMINI.md in the wiki root — the standard files that AI coding assistants (Claude Code, Gemini CLI, GitHub Copilot Agents) read automatically when active in a directory. The domain guidelines are injected into each file, so any AI tool you already use becomes domain-aware the moment it opens the wiki.

Here is what the clinical healthcare template puts in those files:

Cite clinical guidelines by issuing body, title, year, and recommendation strength (Grade A/B/C or Level 1/2/3). Note evidence quality for every clinical claim: RCT, meta-analysis, cohort study, expert consensus, or case report. Never store identifiable patient data in wiki pages.

Compare that to the compliance template:

Map every compliance obligation to the specific regulation, rule, or contractual requirement that creates it. Track controls with the control owner, testing frequency, and last test date. Distinguish between legal requirements (non-negotiable) and internal policy requirements (adjustable). Note jurisdiction and regulated entity for every obligation.

When a compliance analyst has Claude Code running in their wiki directory and asks it to help write a page or interpret a lint warning, it already knows that regulatory citations need jurisdiction-level specificity and that control owners must be named — without configuring anything.

3. Scaffold stub pages

8–12 stub pages covering the core knowledge areas of the domain — empty frames with the right titles, frontmatter, and a  zone marker that separates content you write (preserved) from content the weekly scaffold job refreshes (generated). The structural skeleton maintains itself without ever overwriting your edits.

4. Blank intake forms (template-*.md)

Structured markdown forms in raw_sources/ for each document type common to the domain. A finance/investment install includes forms for deal memos, company profiles, and due diligence checklists — the same fields a professional would populate in any standard memo, now wired directly into the ingest pipeline.

5. Pre-validated seed sources (seeds.md)

Curated ingest commands for public-domain reference sources - all checked for accessibility and domain appropriateness before the template was released. For finance/investment, these include SEC investor education materials and Federal Reserve H.15 interest rate releases. For healthcare/clinical, clinical guideline registries and evidence-based medicine references. Real domain context before your proprietary content lands.

6. Scheduled maintenance jobs

A weekly lint run (Sunday 2:00 AM) and a weekly scaffold job (Sunday 3:00 AM), pre-registered at install time. Neither requires manual intervention once the wiki is running.

Template Library: 30 Domains, 9 Categories

The selection reflects domains where knowledge is both high-stakes (wrong answers have real consequences) and naturally document-heavy (the source material already exists - it is just not queryable). Finance, healthcare, and legal are the clearest examples. Technology and research are the next tier, where the cost of an engineer not knowing the current incident runbook, or a researcher duplicating a failed experiment, is concrete and measurable.

From Install to First Query

Getting a domain-template wiki to the point where it can answer real questions takes less than an hour.

Step 1: Install

synthadoc templates list          # browse all 30 options
synthadoc install my-wiki --target ~/wikis --template finance/investment
synthadoc serve my-wiki

The install creates a standard wiki then applies the template: routing table, agent guidelines, stub pages, intake forms, and seeds. Staging is enabled by default — every ingested page goes to a candidates queue for review before entering the live wiki.

Step 2: Ingest seed sources and your own documents

# From seeds.md — authoritative public reference material
synthadoc ingest "https://www.investor.gov/introduction-investing" -w my-wiki

# Your own sources — batch ingest everything in raw_sources/ at once
synthadoc ingest raw_sources/ --batch -w my-wiki

Step 3: Review candidates in Obsidian

Open the Obsidian plugin and run Synthadoc: Candidates: review candidate pages... from the Command Palette. The modal lists every staged page with its slug, colour-coded confidence badge (high / medium / low), and ingest timestamp — promote what passes your bar, discard what does not.

Step 4: Run lint

synthadoc lint run -w my-wiki

Lint validates every page against the domain guidelines, checks citations, and flags orphans and contradictions. Clean draft pages are promoted to active automatically. After lint, your wiki is queryable.

What Happens After

Once the wiki is active, maintenance is driven by the web UI rather than by you remembering to check things. After every query or lint run, the engine reads its own output and pre-fills the input box with the highest-priority next action — if it found stale pages, the prompt says "Re-ingest these pages"; if re-ingest just finished, it says "Run lint to promote them"; if contradictions surfaced, it queues the resolver. You confirm and it runs. No command to remember, no separate dashboard to check.

Behind that interface, the agentic layer handles:

Contradiction resolution — conflicting pages are identified, original sources retrieved, resolution proposed interactively
Re-ingest on source updates — stale pages refreshed with a before/after diff for your approval
Broken wikilink repair — dead links scanned and repaired automatically
Citation integrity — claims audited against source documents; drift flagged for re-ingest
Sensitive data handling — sanitizer strips PII at ingest time; synthadoc retract rolls back a source and all pages citing it if something slips through
Scheduled lint and scaffold — weekly jobs keep the knowledge graph healthy without intervention

The goal: after the first few days of populating your wiki, the agentic layer handles the maintenance work that would otherwise require a dedicated knowledge engineer.

Quick Reference

synthadoc templates list                          # browse the library
synthadoc install <name> --template <cat/domain>  # install with a template
synthadoc templates sync -w <wiki>                # sync after an upgrade

Release notes (v1.3.3)
Full template docs: template/readme in the installed package

Synthadoc is an open-source LLM knowledge compilation engine, it ingests your sources, compiles them into a queryable, citation-backed wiki, and keeps it consistent and self-growing over time. The domain template library ships in every install, no additional packages required.

Google Brings Deep Research to Gemini Live for Voice-Based Research Conversations

Ali Farhat — Tue, 15 Sep 2026 01:15:31 +0000

Google has confirmed that Gemini Live now supports Deep Research, allowing people to request and discuss in-depth research reports through voice conversations. The integration brings one of Gemini's research capabilities into its live, conversational interface, making it possible to explore a subject without first typing a detailed prompt.

The update is particularly relevant for people who research while travelling, between meetings, or away from a desk. Google's Back to School 2026 announcement says users can request and talk through Deep Research reports with Gemini Live while on the go. Gemini Live's overview page also lists Deep Research among the experience's supported capabilities.

Deep Research began as a standalone Gemini Advanced capability in 2024 and later evolved into Deep Research Max in 2026. Its arrival in Gemini Live extends that research function into a voice modality: users can initiate research and continue the conversation around the resulting report rather than treating the report as a static output.

What the Gemini Live integration changes

The key change is not simply voice input. Gemini Live combines voice conversation with access to Deep Research reports, so a user can ask for a topic to be investigated and then talk through the report in the same interaction. That can make early-stage research more practical when a keyboard is inconvenient or when a question develops through discussion.

For businesses, the most credible near-term use is faster research intake. A manager preparing for a customer meeting, a marketer exploring a subject for an editorial brief, or a founder assessing a new market can use a live conversation to frame a research task and interrogate the findings. The final report can then inform a document or Drive-based research asset, although Google has not detailed a specific end-to-end content workflow for Gemini Live in the supplied materials.

Gemini Live also has a broader set of capabilities, including voice-driven task execution across Google apps, real-time visual information and memory of prior conversations. These capabilities can complement voice-based research, but they should not be confused with Deep Research itself.

Workflow element	Gemini Live status	Practical implication
Deep Research	Users can request and discuss research reports by voice	Research can begin and be explored during an on-the-go conversation
Google app task execution	Part of Gemini Live's broader feature set	Voice interactions can extend beyond research where supported Google app actions are relevant
Real-time visual information	Part of Gemini Live's broader feature set	Live conversations can incorporate visual context separately from a research report
Gems and Notebooks in an active Live session	Not available during active Live mode	Teams relying on those tools need to plan work outside the active voice session

Where voice research may fit in everyday work

The integration is best viewed as a front end for research exploration, not a replacement for editorial review or business judgment. Potential uses include:

Developing a research brief before writing a campaign, proposal or presentation.
Exploring unfamiliar customer, market or product topics while commuting or travelling.
Talking through a research report to identify follow-up questions before moving findings into a shared document.
Giving a team member a hands-free way to start a research task before formalizing the work in an existing content or planning process.

The value is likely to depend on whether the report reaches the people and systems that need it next. Companies should define how voice-generated research moves into their normal review, documentation and approval process, rather than assuming that a useful conversation alone creates a finished deliverable.

Availability, pricing and workflow limits

Google's Back to School update includes a one-year Google AI Pro offer in the United States for eligible college students. That is the explicit onboarding and licensing context supplied with the announcement. It does not establish general business pricing, enterprise pricing, availability in every region or eligibility for organizations outside that student offer.

There is also an important product limitation for teams building repeatable research workflows. During an active Gemini Live session, Live mode does not provide access to Gems or Notebooks. A business that organizes research in notebooks or uses advanced project structures should account for that boundary. The Live conversation may be useful for initiating and discussing research, while related organization work may need to happen before or after the voice session.

Google's wider Deep Research documentation and developer resources describe connections to Workspace surfaces and an API, suggesting a longer-term path toward more integrated research workflows. However, the supplied material does not specify how an individual business should configure those workflows, what controls apply to corporate data, or which Deep Research and Gemini Live features are available in each market.

For companies, the sensible question is not whether voice is inherently better than typing. It is whether voice removes friction at a useful stage of the research process. Teams that routinely lose ideas, questions or research momentum away from their desks may find that it does. Teams with strict requirements for project organization, data handling or repeatable publication workflows will need more implementation detail from Google before relying on the feature as a core process.

If your team wants to turn AI research into a dependable business process, Scalevise can help map the right tools, handoffs and safeguards around the work. Our AI consultancy services focus on practical use cases that reduce manual effort without forcing teams to abandon the systems they already use. Identify where voice-based research can add value, define a workable review path, and avoid building a workflow around features that do not fit your needs. Request an AI consultation.

Frequently Asked Questions

What is the Gemini Live Deep Research integration?

It lets users request and discuss Deep Research reports through Gemini Live's voice-based conversational experience.

Can Gemini Live users talk through a Deep Research report?

Yes. Google says users can request and talk through Deep Research reports with Gemini Live while on the go.

What pricing or offer has Google announced?

Google's Back to School 2026 update includes a one-year Google AI Pro offer in the United States for eligible college students. The supplied information does not specify general business or enterprise pricing.

Can users access Gems or Notebooks during an active Gemini Live session?

No. Live mode does not grant access to Gems or Notebooks during an active Live session.

Conclusion

Deep Research in Gemini Live makes Google's research capability more conversational and mobile. It could reduce friction when users need to initiate or explore research away from a keyboard, but its practical value for businesses will depend on how reports are reviewed, organized and carried into existing workflows. The current announcement confirms the voice integration, while broader pricing, regional availability and business data controls remain areas to watch.

O que descobri medindo o Core Web Vitals de um portal de notícias em hospedagem compartilhada

Ary Ribeiro — Tue, 15 Sep 2026 01:11:51 +0000

Sete dias medindo um portal de notícias em WordPress numa hospedagem compartilhada. As três causas reais estavam fora da lista de suspeitos do Google, e o painel de diagnóstico apontou a imagem errada duas vezes.

A apuração é do Direto Notícias, portal de Guarapari, no Espírito Santo. Os números foram medidos entre 6 e 14 de setembro de 2026 e estão datados por isso.

O portal estava reprovado no Core Web Vitals do Google no celular. O maior elemento da tela levava 2,8 segundos para aparecer, contra o limite de 2,5. Isso barra a entrada no Discover, que é de onde vem tráfego de descoberta para veículo pequeno.

A parte fácil do diagnóstico o próprio Google entrega: o relatório aponta JavaScript bloqueando a renderização, imagens pesadas e refluxo forçado. A parte difícil é descobrir qual desses itens é a causa e qual é sintoma. Passei sete dias medindo, e as três causas reais não estavam na lista de suspeitos.

Primeira: o site gastava o servidor gerando páginas para ninguém

O plugin de cache tinha uma fila de pré-carregamento ligada. Ela completava entre 130 e 180 páginas a cada quinze minutos, o dia inteiro, com quase sete mil pendentes e mais de dois mil erros acumulados.

Numa hospedagem compartilhada, isso não é otimização, é concorrência. Medi a home já em cache respondendo em 1,2 segundo enquanto a fila trabalhava. A mesma home, com a fila parada, responde em 0,22.

O detalhe que quase me enganou: eu achava que a página estava fria. Não estava. O arquivo de cache tinha sido gravado horas antes. O servidor é que estava ocupado.

Segunda: 100% dos cliques de celular caíam em matérias, e nenhum na home

Puxei o Search Console por página e por dispositivo. Em 28 dias, todos os cliques de celular vindos da busca caíram em matérias espalhadas pelo acervo. A home recebeu zero.

Isso inverte a estratégia inteira. Eu vinha otimizando a home, que é o que todo mundo mede. Quem decide a nota de campo é o acervo, e o acervo estava sempre frio: cada publicação limpava o cache do site todo, o portal publica dezenas de textos por dia, e o cache vive sete dias.

A correção foi cirúrgica, por filtro: publicação nova limpa home e categoria; atualização de texto limpa apenas aquela matéria. Mais um aquecedor que mantém quentes as matérias que o Google efetivamente manda gente, com a lista vinda do próprio Search Console.

E uma regra que ficou: disparar uma requisição não é aquecer. Requisição não bloqueante com tempo limite curto é descartada pela hospedagem antes de o cache gravar. Só o arquivo em disco prova. O aquecedor confere a data do arquivo e registra se gravou ou não.

Terceira: a capa invisível que era baixada com prioridade máxima

O tema imprimia a imagem de destaque num bloco próprio, acima do texto. Meses antes, uma regra de CSS tinha escondido esse bloco em todos os aparelhos, porque a mesma foto já aparecia no corpo da matéria.

Esconder por CSS não impede o download. O navegador baixava 24 KB com prioridade alta para uma imagem que ninguém via, disputando banda com a foto que o leitor realmente enxerga.

Fica a lição: compare sempre o que está visível com o que está sendo baixado. São listas diferentes, e a segunda é a que custa.

O painel de causas do Google apontou a imagem errada. Duas vezes

O relatório do PageSpeed acusava a capa da matéria de "elemento de imagem sem tamanho definido", e depois o logotipo do cabeçalho.

Testei segurando cada imagem por seis segundos com o navegador controlado e medindo a caixa antes e depois de carregar. Nos dois casos a caixa já estava reservada, porque os atributos de largura e altura geram proporção. Falso positivo nos dois.

A causa real só apareceu ao instrumentar o próprio navegador com observador de deslocamento de layout, processador estrangulado e rede lenta, olhando quais nós se moviam. Eram dois:

A fonte dos títulos. Em Arial o título ocupava três linhas; quando a fonte condensada chegava, virava duas, e tudo abaixo subia trinta pixels. Resolvido com pré-carregamento da fonte e uma fonte reserva com métrica ajustada, para as duas ocuparem a mesma altura.
O anúncio automático, que insere um bloco entre a foto e o primeiro parágrafo depois de a página já estar montada. Esse eu não toquei: é a receita do veículo.

O que eu mediria diferente da próxima vez

Nota de laboratório é ruído quando há anúncio. A mesma matéria, sem nenhuma mudança no código, deu 89 e depois 66 em rodadas seguidas, só porque o anúncio sorteado travou a thread por mais tempo. Compare tempo de carregamento e deslocamento de layout, nunca a nota.
Medir logo após limpar o cache mede página fria. Duas medições minhas foram para o lixo por isso.
Amostra de um não mede nada. Registrei como lição que o compressor de imagens não gerava formato moderno para miniaturas. Uma semana depois conferi mês a mês e estava errado: ele gera. Minha conclusão tinha saído de um único arquivo, e esse arquivo era de um lote que nunca chegou a ser processado. Voltei e corrigi o registro.
Campo é janela de 28 dias. Nada do que se faz hoje aparece antes de semanas. No dia das mudanças o número de campo até piorou, porque a janela ainda carregava os dias ruins.

Onde chegou

No laboratório, em celular: a home saiu de 93 para 97 e a matéria passou a carregar o maior elemento em 2,2 segundos, contra 2,4 a 2,6 antes. O bloqueio de renderização caiu de cerca de dois segundos para pouco mais de um. As imagens do acervo recente passaram a ser servidas em formato moderno, com 29% menos peso.

O número que decide, o de campo, só será lido no começo de outubro. Até lá, não se mexe em mais nada, porque cada mudança nova suja a leitura.

Se o assunto for útil, o portal fica em diretonoticias.com.br e a página de transparência explica quem o mantém e como ele se financia.

Harness engineering doesn't mean building your own harness

Tilde A. Thurium — Tue, 15 Sep 2026 01:04:48 +0000

It means giving the agent enough context to do the right thing

For this week's Agent Factory podcast, I interviewed Ryan Lopopolo, the engineer who coined the term "agentic harness."

What's in the video

How to Stop Writing Code Manually: Ryan explains how to sculpt smaller feedback loops into long-horizon agentic workflows via harness engineering
Harness, Deconstructed: Billy Jacobson delivers a code walkthrough of a simple harness, exploring linear and closed-loop styles.
The Three-Layer Stack: Smitha Kolan breaks down how to use Gemini 3.8 Flash, Antigravity Boost, and the Google Skills GitHub repo to configure memory, tools, and guardrails.

The thing that struck me was how many best practices for scaling software engineering teams also apply to coding agents.

How much code are you writing manually these days? Let me know in the comments!

Google Just Closed Another Scraping Door. Here's the Cheap Way Around It.

goodpa — Tue, 15 Sep 2026 01:00:43 +0000

Hook

Google Search is rewriting organic result links to google.com/goto?url=…. The destination isn't in the query string anymore — it's an opaque reference you can only resolve by asking Google (read the Location header, don't follow the redirect). As of late August 2026, it shows up consistently when you're logged out or in private mode.

If you build anything on top of search-result HTML, this is the latest rent increase. Google already removed &num=100 and tightened BotGuard/SearchGuard. The pattern is obvious: make naive SERP scraping slower, noisier, and easier to detect.

Why cross-border sellers feel this first

Solo sellers and small agencies are the most exposed, because SERP scraping is the cheapest tool we reach for:

Rank tracking for your own listings
Keyword and demand research before sourcing
Competitor price/title monitoring across marketplaces

None of that is evil. But most of it was built on the assumption that reading a search page was free. That assumption is what's being revoked.

The three-tier response

Tier 1 — Own your data first. Your best rank signal isn't scraped — it's first-party. Search Console, your storefront analytics, and your marketplace's official APIs tell you what actually converts. Scraped rankings are a proxy; your own conversion data is ground truth.

Tier 2 — Use official APIs where they exist. Marketplaces, ad platforms, and logistics providers increasingly expose structured endpoints. They cost money and have limits, but they're stable, and stability is the point.

Tier 3 — If you must scrape, do it like you're being audited. Resolve links properly (read Location, don't follow), rate-limit hard, cache aggressively, and log provenance for every field. Accept that this is an arms race you don't win — you just stay one revision behind.

The uncomfortable part

Every anti-scraping move is really a pricing signal. Google isn't trying to stop you; it's trying to make you pay — in latency, in detection risk, in engineering hours. Once you price that in, a lot of "free" data turns out to be expensive.

The sellers who win the next cycle won't be the best scraper operators. They'll be the ones whose growth doesn't collapse when a door closes.

Takeaway

Audit your stack this week and label every data source "owned / licensed / scraped." For each scraped source, name the official API or first-party signal that could replace it. You don't have to switch today — you just need to know which door is load-bearing before it closes.

I built a bilingual quote estimator that runs entirely in the browser

Maxime Brodeur — Tue, 15 Sep 2026 00:46:26 +0000

Many service websites make visitors send an email before giving them any price context. I wanted a smaller middle ground: show a useful ballpark estimate immediately, then let the visitor start a conversation with the details already organized.

I built QuoteKit for freelance developers, designers, and small studios.

What the visitor can do

choose a starting package, add-ons, extra pages, and a timeline;
see an itemized estimate update instantly;
switch between English and French;
download a plain-text summary, print or save a PDF, or open a prepared email draft.

Why I kept it static

The runtime is four files: index.html, styles.css, config.js, and app.js. It runs on static hosting with no backend, build step, account, API key, or runtime dependency.

The business owner edits package names, prices, add-ons, currency, tax settings, recipient email, and default language in config.js. The visitor's notes and contact details stay in the browser unless they choose to email, download, or print them.

The email action uses mailto: and opens a draft in the visitor's email client. It never sends automatically. I also label the total as an estimate so the page starts a pricing conversation instead of pretending to generate a binding quote.

I used Codex as a coding collaborator for implementation and QA. The delivered page contains no AI model or external AI API.

Try the flow

Live demo: https://www.nexushub.nexus/studio/demos/quotekit

I would especially value feedback from people who sell services online: does an instant ballpark estimate qualify a lead, or does it anchor the conversation too early?

For anyone who wants to adapt it for their own business or client projects, the editable source ZIP is $12 USD with a reusable commercial buyer license. Delivery is by email within 24 hours: https://buy.stripe.com/6oU4gA6SE9KPawh7hu4gg00

"Do you use AI?" is a process question. He answered a status question.

Fuyuki0 — Tue, 15 Sep 2026 00:40:05 +0000

I saw someone tell this story recently, so I am going by their telling of it.

They were in an interview. The interviewer asked: "do you use AI?"

They took it badly. The way they told it, the question itself was out of
line - an attempt to catch them out. So they answered with a question of
their own: are you going to use a stove instead of a microwave? The world
moves forward. They will stop making stoves eventually.

They told the story as a win. I do not think it was one, and it took me a
while to work out why. It is not because using AI is wrong, or because
answering back in an interview is wrong. It is that a specific and very
common mistake is happening in that exchange, and I have made it myself.

They answered a question nobody asked

"Do you use AI?" is a question about method. It has a boring, factual
answer: yes, here, for these things, and I check it like this.

What they heard was "are you a real engineer?" That is a question about
status, and status questions feel like they need to be won rather than
answered.

The gap between those two readings is where the whole thing goes wrong. The
interviewer asked about a tool. The candidate defended an identity. And once
you are defending an identity, the actual content of your answer stops
mattering to you - which is a shame, because it still matters to the person
across the table.

Why the misread is reasonable

It would be easy to say they were being oversensitive. I do not think that
is fair, because the question genuinely has a charge on it now.

"Do you use AI" in 2022 was small talk. Today it is a question people ask to
find out which side you are on, and it gets asked from both directions.
Somewhere there is an interviewer who wants to hear "no, I write everything
myself" and somewhere there is another who wants to hear "yes, constantly,
I ship three times faster". Both of those interviewers exist and neither of
them is signposted.

So the candidate is not paranoid. They are guessing which room they are
standing in, under time pressure, with a job on the line. That is a real
problem and it is worth naming rather than mocking.

But guessing wrong has a cost, and the cost here was the whole answer.

The analogy argues against him

This is the part I keep coming back to.

Stove versus microwave is not old versus new. They are not the same
appliance. A microwave reheats things quickly and unevenly. A stove sears,
reduces, browns, holds a temperature. Every professional kitchen has both,
and nobody in one thinks the microwave is winning.

So the analogy, chosen to prove that the interviewer was behind the times,
quietly concedes the interviewer's point: what you actually want in a kitchen
is somebody who knows which one this dish needs. That is precisely what the
question was trying to find out.

An analogy that feels like it ends the argument is worth checking twice. This
one ends it in favour of the other person.

"The world moves forward" is a way of not answering

The second half - "they will stop making stoves" - is an inevitability
argument, and inevitability arguments have a particular smell in interviews.

The question was about your practice. The answer was about history's
direction. Those are not the same subject, and swapping one for the other
is one of the oldest ways to avoid saying something specific.

It also cannot be wrong, which is the problem. "Things will keep changing" is
true in every possible world, so it tells the listener nothing about you. An
interviewer is not collecting predictions. They are trying to work out what
you will be like on a Tuesday when something breaks.

What the boring answer would have sounded like

Something like: "yes, daily. It writes most of the first draft. I read all of
it, I am careful with anything touching auth or money, and I have been burned
by it inventing a library function that did not exist, so I check the imports
first now."

That is not an impressive answer. It is specific, it admits a scar, and it
shows a line. It would have taken twenty seconds and it answers the question
that was actually asked.

The instinct that specificity is weakness gets a lot of good engineers in
trouble. In an interview, specificity is the entire product.

Who can afford to fire back

One more thing, and it is uncomfortable.

Answering an interviewer with a rhetorical question is a status move, and
status moves are priced. If you are senior, scarce, and the company needs you
more than you need them, it reads as confidence and it often works. If you
are not, the same words read as brittle.

Nothing about that is fair. It is just how the room works, and it is worth
knowing the price before you spend it.

Where the line actually is

The line has quietly moved, and it is no longer usage.

Nobody serious is being judged for using AI in 2026. What people are being
judged on is where they put the check: what they read, what they refuse to
ship without understanding, and whether they can tell when the output is
confidently wrong.

That is a much harder thing to interview for than yes or no, which is
probably why interviewers keep reaching for the crude version of the
question. If you get the crude version, answer the real one anyway. You will
be the only candidate that day who does. :)

I Pinned 31 GitHub Actions to Commit SHAs. One Major Tag Was Two Versions Stale.

James Joyner — Tue, 15 Sep 2026 00:39:08 +0000

Yesterday I pinned 31 GitHub Actions to commit SHAs for a set of workflows I was packaging. Every SHA was resolved from the upstream repository rather than copied from a README or a tutorial, and the process turned up three things worth writing down — including one action whose v3 major tag is two full major versions behind its newest release.

Here is how to pin correctly, without the API and without trusting anyone's blog post, and what the exercise found.

Why the SHA, not the tag

uses: actions/checkout@v7 runs whatever commit the v7 tag points to at the moment your job starts. The maintainer moves that tag for every patch release — which is the feature — and anyone who takes over the repository or a maintainer's account can move it too — which is the problem. A commit SHA cannot be moved. Pinning to it means the code that runs is the code you reviewed, until you change the pin.

The convention is the SHA plus the release in a comment, so a human can still read the file:

uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

Dependabot's github-actions ecosystem updates both halves together, so pinning does not cost you updates.

Resolving a SHA without the API

The GitHub REST API is rate-limited to 60 unauthenticated requests an hour, and resolving one pin can take three calls (release → tag → annotated tag object). git ls-remote over HTTPS has no such limit and needs no token:

git ls-remote --tags https://github.com/actions/checkout | grep -E 'refs/tags/v7(\.0\.1)?(\^\{\})?$'

3d3c42e5aac5ba805825da76410c181273ba90b1    refs/tags/v7
3d3c42e5aac5ba805825da76410c181273ba90b1    refs/tags/v7.0.1

Two facts in two lines: the v7 major tag and the v7.0.1 release point at the same commit, so v7 currently means 7.0.1, and that is the SHA to pin.

One subtlety. Some projects use annotated tags, which are objects of their own; ls-remote then prints two lines for one tag — the tag object and, with a ^{} suffix, the commit it points to. You want the ^{} one:

006b7ce8314066bdf1765b4500370d40fa6917a3    refs/tags/v0.24.2
3ad7283483fc7af8ff2b4ea19663c2d5ca935e26    refs/tags/v0.24.2^{}

Pin 3ad7283…, not 006b7ce…. A tag-object SHA in a uses: line fails with "unable to resolve action" — a confusing error for a correct-looking pin.

I wrapped this in a short script: for each repository, take the highest vN tag, its peeled commit, and whichever vX.Y.Z tag shares that commit. Thirty-one actions in about a minute.

What the exercise found

1. A major tag that is two majors stale. actions/dependency-review-action@v3 resolves to a commit with no v3.x.y release tag at all — the newest release is v5.0.0. The v3 tag was never advanced to anything after v3's last patch, so anyone still on @v3 is on an unmaintained line and does not know it. Pin v5.0.0 (a1d282b36b6f3519aa1f3fc636f609c47dddb294).

2. A major tag that lags its own releases. sigstore/cosign-installer@v3 points at v3.9.1; the newest release is v4.1.2. Not wrong, but "I'm on the latest major" is a belief that a major tag does not support. Only the release list does.

3. No major tag at all. aquasecurity/trivy-action publishes only exact versions (0.35.0), no floating v0. A workflow written as @master — and there are many — is pinned to a branch, the one thing worse than a tag.

None of this is visible from inside a workflow file. It is visible in about a second from ls-remote.

The rest of the checklist that goes with pins

Pinning is one line of a security posture, and on its own it is the least important line. The workflows I was packaging apply the same six things everywhere, and if you copy nothing else from this post, copy this block:

permissions:
  contents: read              # read-only by default; widen per job, never here

concurrency:
  group: ci-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}   # cancel CI, never a deploy

jobs:
  test:
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false   # the token is not written to .git/config

      - name: Use a branch name safely
        env:
          REF: ${{ github.head_ref }}  # context values go through env…
        run: echo "building $REF"      # …never interpolated into the script

And the two rules that are about events, not syntax: nothing that publishes or deploys runs on pull_request, and pull_request_target is not used at all. A fork's pull request gets a read-only token and no secrets — GitHub enforces that — but only if you never reach for the trigger that gives it your secrets back.

Each of those has a free lesson behind it — pinning, least-privilege permissions, workflow security — and a lab where you find all of them missing from a workflow that looks fine: secure an unsafe workflow.

Where the 31 pins ended up

The workflows were for a product I released yesterday: the GitHub Actions Production Workflow Vault — twenty workflows (CI for Python, Node, Go, Java and .NET; Docker build-and-test, GHCR and multi-arch publishing; Terraform PR validation; Ansible with Molecule; CodeQL, dependency review, gitleaks, SBOM and attestations; release, Pages, Kubernetes; AWS, Azure and GCP via OIDC), three reusable workflows and a composite action, with every one of those six rules applied and the full pin table in the docs, verification method included. It is $19.99 once, no subscription, and it comes with the honest caveat that no workflow works unmodified — every file marks what to change.

If you would rather do it yourself, the ls-remote command above and the six lines of YAML are the whole method. Pin today; let Dependabot keep it current.

Part 1 - The Why: Why Architecture Matters on the Frontend

Jorge Castillo — Tue, 15 Sep 2026 00:38:27 +0000

Most modern React applications start out as triumphs of developer velocity. You spin up a project with Vite, pull in a few UI libraries, throw together some useEffect hooks, and ship features in hours. But as team size grows and feature complexity scales, that initial speed decays into structural inertia.

Suddenly, simple UI tweaks break unrelated business workflows, refactoring network calls requires rewriting component tests, and adding a new state variable feels like diffusing a bomb.

This degradation isn't caused by bad developers or missing framework features—it is the direct consequence of accidental coupling. In this first installment of our series, we unpack why unmanaged dependencies destroy frontend maintainability, analyze the true cost of framework lock-in, and introduce the core rules that keep your domain logic bulletproof over time.

🛑 The "Fat Component" Anti-Pattern

In typical React applications, components naturally become magnets for every operational concern in the system. Consider a standard component responsible for checking out a shopping cart:

// ❌ Accidental Coupling: Everything living inside the UI layer
export const CheckoutButton = ({ cartId }: { cartId: string }) => {
  const [loading, setLoading] = useState(false);

  const handleCheckout = async () => {
    setLoading(true);

    // 1. Fetching raw data directly from an API endpoint
    const res = await fetch(`/api/carts/${cartId}`);
    const cart = await res.json();

    // 2. Business Rule: Carts over $100 get free shipping, but require a minimum of 2 items
    let shippingFee = 15;

    if (cart.total > 100 && cart.items.length >= 2) {
      shippingFee = 0;
    }

    // 3. Interfacing with local storage caching directly
    localStorage.setItem('last_checkout_total', cart.total + shippingFee);

    // 4. Executing payment network mutation
    await fetch('/api/checkout', {
      method: 'POST',
      body: JSON.stringify({ cartId, amount: cart.total + shippingFee }),
    });

    setLoading(false);
  };

  return <button onClick={handleCheckout}>{loading ? 'Processing...' : 'Checkout'}</button>;
};

When UI components coordinate HTTP requests, evaluate domain rules, mutate local browser storage, and manage rendering logic simultaneously, you incur severe architectural liabilities:

Framework Lock-in: Your core business calculations (e.g., shipping rules) are tangled directly inside React lifecycle hooks and synthetic event handlers. Switching frameworks or reusing logic outside React becomes impossible.
Brittle Testing: To test whether the shipping rule works, you can't simply run a 2-millisecond unit test. You must mock fetch, mock localStorage, render a React DOM node, and simulate user clicks.
Data Schema Leakage: When backend API response schemas change, your presentation code breaks instantly across dozens of UI components.

💸 The High Cost of UI-Centric Architecture

Why do codebases decay so rapidly when business logic lives inside presentation components? Let's break down the technical debt multiplier:

Problem Domain	UI-Centric Approach	Clean Architecture Approach
Testing Overhead	Heavy reliance on JSDOM, React Testing Library, and complex mock providers.	Fast unit tests in pure TypeScript without DOM or network dependencies.
API Instability	Breaking API payload changes require sweeping refactors across UI components.	Mappers isolate external API contracts from internal domain entities.
State Management Drift	Logic gets duplicated across React state, Redux, Zustand, and query caches.	Application state logic is centralized inside explicit Use Cases.
Framework Upgrades	Major React version jumps or migration to SSR risk breaking business rules.	Core business rules have zero dependencies on React or any third-party framework.

🎯 The Core Architectural Principle: The Dependency Rule

To eliminate accidental coupling, we apply the Dependency Rule, the central pillar of Clean Architecture:

Source code dependencies must point inward, toward high-level policies.

flowchart TB
    subgraph UI["UI & Frameworks<br/>(React, Browser APIs, HTTP)"]
        direction TB
    end

    UI -.-> Outer["Outer Layer (Volatile)"]
    UI --> Adapters

    subgraph Adapters["Infrastructure Adapters<br/>(Fetch Client, IndexedDB, LocalStorage)"]
        direction TB
    end

    Adapters -.-> AdapterLabel["Adapter Layer"]
    Adapters --> UseCases

    subgraph UseCases["Application Use Cases<br/>(Commands & Queries)"]
        direction TB
    end

    UseCases -.-> Orchestration["Orchestration"]
    UseCases --> Core

    subgraph Core["Core Domain<br/>(Entities & Business Rules)"]
        direction TB
    end

    Core -.-> Inner["Inner Layer (Stable)"]

    style UI fill:#f9f9f9,stroke:#333,stroke-width:2px
    style Adapters fill:#e8f4f8,stroke:#333,stroke-width:2px
    style UseCases fill:#e8f8e8,stroke:#333,stroke-width:2px
    style Core fill:#f8e8e8,stroke:#333,stroke-width:2px

The Inviolable Rule

Nothing in an inner layer can know anything about something in an outer layer.

The Domain Layer (Entities, Value Objects) knows nothing about Use Cases, REST APIs, or React.
The Application Layer (Use Cases, Ports) knows nothing about React components or specific database drivers.
The Presentation & Infrastructure Layers (React UI, Axios, IndexedDB) depend inward on abstract interfaces defined by the application layer.

By forcing dependencies to point strictly inward, your core business rules become completely decoupled from UI frameworks, state management libraries, and external APIs.

🔄 Inversion of Control in Action

How does an inner layer trigger an operation (like fetching a record or storing a token) without knowing about the concrete driver executing it? Through Inversion of Control (IoC) via Ports & Adapters.

Instead of importing an HTTP client directly inside a business rule, the Application layer defines an abstract Port (an interface):

// 1. Application Port (Owned by the core application)
export interface ICartRepository {
  getById(cartId: string): Promise<Cart>;
  save(cart: Cart): Promise<void>;
}

The outer Infrastructure layer implements this port via an Adapter:

// 2. Infrastructure Adapter (Outer layer)
export class ApiCartRepository implements ICartRepository {
  async getById(cartId: string): Promise<Cart> {
    const res = await fetch(`/api/carts/${cartId}`);
    const data = await res.json();
    return CartMapper.toDomain(data); // Maps API schema to pure Domain Entity
  }

  async save(cart: Cart): Promise<void> {
    await fetch('/api/checkout', {
      method: 'POST',
      body: JSON.stringify(CartMapper.toDTO(cart)),
    });
  }
}

Because the core domain relies solely on the ICartRepository interface, you can swap ApiCartRepository for an InMemoryCartRepository during testing or an IndexedDBCartRepository for offline support without modifying a single line of business logic.

🧪 Testing as an Architectural Indicator

One of the most immediate feedback loops of a Clean Architecture setup is test suite velocity.

When your business logic is decoupled from React and browser APIs, testing a complex domain feature doesn't require launching a headless browser or mounting virtual DOM trees.

// ✅ Pure Unit Test: Zero DOM, zero network mocks, runs in milliseconds
describe('Cart Shipping Calculation', () => {
  it('should apply free shipping for orders over $100 with at least 2 items', () => {
    const cart = Cart.create({ items: [itemA, itemB], totalAmount: 120 });

    expect(cart.calculateShippingFee()).toBe(0);
  });

  it('should charge shipping for orders over $100 with less than 2 items', () => {
    const cart = Cart.create({ items: [itemA], totalAmount: 150 });

    expect(cart.calculateShippingFee()).toBe(15);
  });
});

Because this test interacts purely with TypeScript domain objects, hundreds of business rule scenarios can execute in a fraction of a second in your CI/CD pipeline—giving your team instant feedback without test flakiness.

📢 Up Next...

Decoupling logic from the UI sounds great in theory, but how do you physically organize a codebase to enforce these boundaries without falling into folder chaos?

Coming up next in Part 2: The How — Architectural Layers & Domain-Driven Design. We will examine how to structure a domain-driven codebase in strict TypeScript, build pure Domain Entities and Value Objects, and implement CQRS workflows using application-owned ports.

Explore the reference implementation anytime on GitHub:

👉 github.com/schorts99/React-Clean-Architecture

Forecasting the NFL GOAT QB with Artificial Intelligence: The 2026 Update

Bart Czernicki — Tue, 15 Sep 2026 00:37:29 +0000

Last year I wrote an article that used an AI system to research and predict the probability of Patrick Mahomes surpassing Tom Brady as the greatest NFL quarterback. Last year's Forecasting the NFL GOAT Quarterback with Artificial Intelligence put Patrick Mahomes' chance of eventually surpassing Tom Brady at 30%. The approach used ChatGPT's AI deep research, career projections, and a judgment about how fans and analysts might ultimately compare their legacies.

Part 1 introduced the research concepts and their limitations. This follow-up concentrates on what changed, makes the probability calculation explicit, and refreshes the same ten career metrics.

A few notes before reading the AI analysis:

This year I updated the analysis after the 2025-2026 season, before Kansas City's Monday Night Football game. Why the wait? As you may note, Patrick Mahomes is coming off of a major injury and I wanted to have an accurate sense of the latest information. Information cutoff: September 14, 2026, before Kansas City's season opener. Career statistics include the completed 2025 NFL season; recovery and roster information extend through this cutoff. No performance from Kansas City's 2026 opener enters the analysis.
The 2026 updated assessment uses agentic OpenAI Codex (Deep Research doesn't exist anymore) as the research harness.
Now that we have two data points, I asked AI to create a chart. It added an assumption sensitivity range alongside the point estimate.

Note: Everything below this line has been generated by OpenAI's Codex AI system using GPT-6-Astra (Ultra mode).

What changed after the 2025 season?

Mahomes finished 2025 with 3,587 passing yards, 22 touchdowns, 11 interceptions, and an 89.6 passer rating in 14 games. NFL career statistics

His career now stands at 35,939 regular-season passing yards and 267 touchdowns. The championship and postseason baselines did not advance: three Super Bowl wins, three Super Bowl MVPs, a 17–4 playoff record, and 46 playoff touchdown passes. Chiefs player biography

Kansas City finished 6–11, scoring 362 points and allowing 328. That +34 differential complicates any simple claim that the team had collapsed. The Chiefs also went 1–9 in games decided by eight points or fewer. Those totals reconcile against the completed schedule and the team's season-opening preview.

My interpretation is that another poor year is possible, but the win-loss record alone overstates the evidence for permanent decline. A rebound in close games is plausible; it is not guaranteed.

The larger new uncertainty is physical. Mahomes injured his left knee in the December 14 loss to the Chargers that eliminated Kansas City. He underwent surgery the next day; NFL reporting identified repairs to both the ACL and LCL. The team was already losing its postseason opportunity when the injury occurred, so the entire season cannot be attributed to his absence. NFL surgery report

There is also encouraging current evidence. The September 12 injury report records full participation with no game designation, and the NFL reports that Mahomes is cleared to start against Denver. Clearance resolves availability for the opener; it does not establish restored mobility or years of future durability. Chiefs injury report, NFL return update

The surrounding team has changed, too. Eric Bieniemy returned as offensive coordinator, Travis Kelce returned for 2026, and Kansas City added Kenneth Walker while trading Trent McDuffie. These moves create plausible improvement paths and new uncertainties. They do not establish how competitive the roster will be a decade from now. Coaching announcement, Kelce announcement, roster transactions

Updated career projections

The career projections summarize the central scenarios and weights explained below. For every metric, I assign an illustrative average within each scenario, then calculate its weighted average. These profiles are assumptions, not empirical estimates of quarterback aging.

Historical baselines: Chiefs biography, NFL Brady retirement summary, and postseason comparison. Mahomes' Pro Bowl total remains six; the 2026 announcement lists him as an alternate.

Turning the GOAT question into explicit scenarios

The question remains: When Mahomes' career is over, how likely is broad agreement among fans and analysts that he ranks above Brady? There is no official GOAT award or fixed voting population. The forecast describes an eventual legacy judgment, not simply the probability of winning eight championships.

I divide the remaining possibilities into four mutually exclusive groups based on final Super Bowl wins. Each receives a weight and a conditional chance of achieving consensus GOAT status. The latter considers the wider career profile, including awards, longevity, production, and playoff performance.

Every weight and conditional probability below is a judgment call. The sources establish the evidence; they do not supply these percentages. This is a reproducible scenario assessment, not a fitted statistical model or a Monte Carlo simulation.

Final Super Bowl wins	Illustrative remaining seasons	Scenario weight	GOAT chance within scenario	Contribution to total
3–4	7	60%	2%	1.2 percentage points
5	10	24%	25%	6.0 percentage points
6	12	11%	60%	6.6 percentage points
7+	14	5%	90%	4.5 percentage points

The 3–4-title group receives the largest weight because a lost postseason opportunity, uncertain sustained recovery, and finite career length make repeated future championships difficult. It includes early retirement as well as long careers with limited further team success. Seven remaining seasons is an illustrative average, not a minimum.

The five-title group assumes a successful return, about another decade of play, and two additional championships. That would create a serious GOAT argument, while leaving a substantial championship gap.

The illustrative six-title and seven-plus profiles assume increasingly exceptional longevity and repeated championship contention. Their careers extend into the early or mid-forties; the titles could also arrive sooner. Even seven titles do not mechanically settle a debate about eras, supporting casts, and individual performance.

This still assigns 40% to at least two more championships, 16% to at least three, and 5% to at least four. It retains considerable upside, informed by Mahomes' established postseason ceiling and the possibility of a strong recovery. The evidence supports those possibilities; the exact allocations remain contestable.

The conditional approach keeps achievements connected: the strongest championship outcomes also carry longer careers and stronger statistical profiles. It avoids treating recovery, playoff appearances, awards, and titles as independent events.

What would change the forecast next?

A sustained return to effective movement, strong passing production, and reliable availability would support shifting weight toward the upper scenarios. So would evidence that the offense can remain productive as personnel change. One impressive game would provide much less information than a healthy, effective season.

Persistent limitations, further missed time, or declining effectiveness would push weight toward the lower group. Another missed postseason would consume another championship opportunity, although the underlying performance would still matter when assessing future prospects.

A championship would directly change the starting point. It would also justify rebuilding the scenario distribution instead of adding a fixed number of percentage points. Awards and postseason efficiency would help distinguish team success from Mahomes' individual contribution.

Sources and reproducibility

Sources were checked September 14, 2026, subject to the pre-opener cutoff.

Bart Czernicki, Part 1, March 11, 2025; edited March 14.
Chiefs and NFL, Mahomes biography and season statistics, historical tables.
Chiefs, 2025 schedule, historical table; Week 1 preview, September 13, 2026.
NFL, surgery report, December 15, 2025; return update, September 12, 2026.
Chiefs, injury report, September 12, 2026.
Chiefs, Bieniemy appointment, January 23; Kelce return, March 11; roster moves, updated through March 20, 2026.
Kevin Patra, NFL, Brady retirement summary, February 1, 2023; StatMuse, playoff comparison.
Chiefs, Pro Bowl selections, December 23, 2025.

Final probability assessment

The updated assessment is approximately 18%, with an 8%–33% assumption sensitivity range. That leaves a meaningful path to the top, but the central outlook is less favorable. These are subjective estimates, not measured frequencies or betting odds.

The calculation is:

P(GOAT) = Σ[P(scenario) × P(GOAT | scenario)]

(0.60 × 0.02) + (0.24 × 0.25) + (0.11 × 0.60) + (0.05 × 0.90) = 0.183

That produces 18.3%, rounded to 18%.

Sensitivity of the estimate

The arithmetic is exact given the assumptions. The assumptions are uncertain.

For sensitivity analysis, I change both the distribution of football outcomes and the standards that might shape the eventual legacy judgment. Each row below follows the same scenario order: 3–4 / 5 / 6 / 7+ titles.

Assumption case	Scenario weights	Conditional GOAT chances	Calculated result
Pessimistic	72% / 20% / 6% / 2%	1% / 15% / 45% / 80%	8.02%
Central	60% / 24% / 11% / 5%	2% / 25% / 60% / 90%	18.30%
Optimistic	45% / 28% / 17% / 10%	4% / 35% / 70% / 95%	33.00%

The resulting 8%–33% assumption sensitivity range is not a confidence interval. It does not mean a statistical procedure has located the true probability with a stated coverage rate. It shows how far the answer moves under these selected alternative judgments.

Changing only the football scenario weights gives 11.84%–27.10%. Changing only the conditional legacy judgments gives 13.15%–23.25%. Both sources of uncertainty matter, and other reasonable assumptions could produce results outside the displayed range.

Forecast	Headline estimate	Assumption sensitivity range
2025, Part 1	30%	Not reported
2026, this update	18%	8%–33%

The bars use rounded headline estimates: a decrease of 12 percentage points. The unrounded calculation changes by 11.7 points.

The 2025 estimate remains the original 30%; I have not reconstructed it using today's method. Consequently, this comparison reflects both new evidence and a methodological change. It cannot isolate the effect of the 2025 season, demonstrate improved forecasting skill, or establish that last year's estimate was wrong. The eventual outcome remains unresolved.

That is the practical value of this AI-assisted update: current evidence, visible assumptions, and calculations that can be inspected. Both the remaining football career and the eventual public judgment remain uncertain.

My updated estimate of Mahomes eventually surpassing Brady as the consensus NFL GOAT quarterback is 18%.

Docker for Developers: Containers, Images, and Compose Explained

Aditya Rawas — Tue, 15 Sep 2026 00:37:18 +0000

Originally published at adityarawas.in

If you've ever heard "works on my machine" — Docker is the solution. Docker lets you package your application and all its dependencies into a single unit called a container that runs identically everywhere: your laptop, a teammate's Linux machine, or a cloud server.

This guide explains containers from first principles, then walks through building, running, and composing Docker-based applications — with a real Node.js example throughout.

Containers vs Virtual Machines

Before Docker, the standard way to isolate software environments was a Virtual Machine (VM). A VM emulates an entire computer — CPU, memory, disk, and a full operating system — on top of a hypervisor.

Containers are fundamentally different:

	Virtual Machine	Docker Container
OS	Full guest OS per VM	Shares host OS kernel
Size	Gigabytes	Megabytes
Startup	Minutes	Milliseconds
Isolation	Strong (hardware-level)	Good (process-level)
Performance	~10-15% overhead	Near native

A container is just a process running on the host OS, isolated using two Linux kernel features:

Namespaces — isolate the process's view of the system (filesystem, network, PID, users)
cgroups — limit the process's resource usage (CPU, memory, I/O)

Docker provides the tooling to create, run, and manage these containers.

Core Concepts

Images

A Docker image is a read-only template that defines everything needed to run your application: the OS base layer, runtime, dependencies, app code, and startup command.

Images are built in layers. Each instruction in a Dockerfile adds a layer on top of the previous one. Layers are cached and shared — if 10 images all use the same Node.js base layer, that layer is stored once on disk.

Containers

A container is a running instance of an image. You can run many containers from the same image simultaneously. The container adds a thin writable layer on top of the image layers for any changes made at runtime.

Image (read-only layers):
  ubuntu:22.04 base
  node:20 runtime
  npm install output
  app source code

Container (writable layer on top):
  runtime logs, temp files, etc.

Registry

Images are stored in a registry. Docker Hub is the default public registry. Private registries include AWS ECR, GitHub Container Registry, and Google Artifact Registry.

Installing Docker

Download Docker Desktop from docker.com. It includes the Docker daemon, CLI, and Docker Compose.

Verify the installation:

docker --version
# Docker version 27.x.x

docker run hello-world
# Pulls the hello-world image and runs it — confirms Docker is working

Essential Docker Commands

# Images
docker pull node:20-alpine       # Download an image
docker images                    # List local images
docker rmi node:20-alpine        # Remove an image

# Containers
docker run node:20-alpine node --version   # Run a command in a container
docker run -it ubuntu bash                 # Interactive terminal
docker ps                                  # List running containers
docker ps -a                               # List all containers (including stopped)
docker stop <id>                           # Stop a container
docker rm <id>                             # Remove a stopped container

# Logs and inspection
docker logs <id>                           # View container output
docker exec -it <id> sh                    # Shell into a running container
docker inspect <id>                        # Full container metadata

Writing a Dockerfile

A Dockerfile is a text file with instructions for building an image. Each instruction becomes a layer.

Here's a production-ready Dockerfile for a Node.js application:

# Stage 1: Install dependencies
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --only=production

# Stage 2: Build (if needed — e.g. TypeScript)
FROM node:20-alpine AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

# Stage 3: Production image
FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production

# Copy only what's needed
COPY --from=deps /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
COPY package.json ./

EXPOSE 3000
CMD ["node", "dist/index.js"]

This uses a multi-stage build — a critical pattern for production images:

The deps and builder stages contain dev tools and source files
The final runner stage only has the compiled output and production dependencies
The final image is dramatically smaller because the intermediate stages are discarded

Common Dockerfile Instructions

Instruction	Purpose
`FROM`	Base image to build from
`WORKDIR`	Set the working directory for subsequent instructions
`COPY`	Copy files from host into the image
`RUN`	Execute a command during build (creates a new layer)
`ENV`	Set environment variables
`EXPOSE`	Document the port the app listens on (doesn't publish it)
`CMD`	Default command to run when the container starts
`ENTRYPOINT`	Fixed command (CMD becomes arguments to it)

Building and Running Your Image

# Build the image — tag it with -t
docker build -t my-app:latest .

# Run a container from it
docker run -d \
  --name my-app \
  -p 3000:3000 \
  --env-file .env \
  my-app:latest

Flags explained:

-d — detached mode (runs in background)
--name my-app — give the container a name
-p 3000:3000 — map port 3000 on the host to port 3000 in the container
--env-file .env — load environment variables from a file

The `.dockerignore` File

Just like .gitignore, a .dockerignore file tells Docker what to exclude when copying files into the image:

node_modules
.git
.env
dist
*.log
.DS_Store

Always add node_modules — if it's not ignored, Docker copies your local modules into the image before running npm ci, which bloats the image and can cause platform-specific binary conflicts.

Volumes: Persisting Data

Containers are ephemeral — when a container is removed, all its data is gone. Volumes solve this by mounting storage that lives outside the container lifecycle.

# Named volume — Docker manages the storage location
docker run -d \
  --name my-postgres \
  -v postgres-data:/var/lib/postgresql/data \
  -e POSTGRES_PASSWORD=secret \
  postgres:16

# Bind mount — maps a host directory into the container (useful in development)
docker run -d \
  -v $(pwd)/src:/app/src \
  -p 3000:3000 \
  my-app:dev

Use named volumes in production (Docker manages them, they survive container restarts). Use bind mounts in development (changes to host files are immediately reflected in the container).

Networking

Containers can communicate with each other through Docker networks.

# Create a network
docker network create my-network

# Connect containers to it
docker run -d --network my-network --name app my-app:latest
docker run -d --network my-network --name db postgres:16

# Inside the app container, connect to Postgres using its container name as hostname
# postgresql://db:5432/mydb

Containers on the same network can reach each other by container name — Docker's internal DNS resolves them automatically.

Docker Compose: Multi-Container Applications

Real applications have multiple services — a web server, a database, a cache. Docker Compose lets you define and run all of them with a single file.

# docker-compose.yml
services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://postgres:secret@db:5432/myapp
      - REDIS_URL=redis://cache:6379
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
    volumes:
      - ./src:/app/src   # hot reload in development

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: myapp
      POSTGRES_PASSWORD: secret
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  cache:
    image: redis:7-alpine
    volumes:
      - redis-data:/data

volumes:
  postgres-data:
  redis-data:

docker compose up -d          # Start all services in the background
docker compose logs -f app    # Follow logs for the app service
docker compose down           # Stop and remove containers
docker compose down -v        # Also remove volumes (WARNING: deletes data)

With this setup, a new developer on your team only needs to run docker compose up to get a fully working local environment — no manual database installation, no version conflicts.

Layer Caching: Making Builds Fast

Docker caches each layer. If a layer's instruction and its inputs haven't changed, Docker reuses the cached layer instead of re-running the instruction. This makes rebuilds fast.

The order of instructions matters — put the things that change least at the top:

# Good — dependencies rarely change, so this layer is cached on most rebuilds
COPY package.json package-lock.json ./
RUN npm ci

# Source code changes often — copy it after installing dependencies
COPY . .

If you copy the entire source first and then run npm ci, every code change invalidates the npm install layer and triggers a full reinstall.

Production Best Practices

Use specific image tags, not latest:

# Bad — unpredictable, breaks builds when the image updates
FROM node:latest

# Good — deterministic builds
FROM node:20.17-alpine3.20

Run as a non-root user:

RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser

Don't store secrets in images: Use environment variables or secret management tools (AWS Secrets Manager, HashiCorp Vault). Never COPY .env into an image.

Scan images for vulnerabilities:

docker scout cves my-app:latest

Keep images small: Use Alpine-based images (node:20-alpine instead of node:20). Alpine is ~5MB vs ~150MB for the Debian-based default. Use multi-stage builds to exclude build tools from the final image.

Key Takeaways

A container is an isolated process — it shares the host OS kernel but has its own filesystem, network, and process space via Linux namespaces and cgroups.
A Docker image is a read-only stack of layers; a container adds a writable layer on top.
The Dockerfile defines how to build your image — put slow-changing layers (dependencies) before fast-changing ones (source code) to maximize cache hits.
Multi-stage builds keep production images small by separating build-time tools from runtime output.
Volumes persist data beyond a container's lifecycle — use named volumes in production, bind mounts in development.
Docker Compose orchestrates multi-container applications with a single YAML file, making local development reproducible.
Always use specific image tags, non-root users, and externalized secrets in production.

The Paperclip That Arrived Twenty Years Too Early

Alice Severi Gonçalves — Tue, 15 Sep 2026 00:37:14 +0000

In the collective memory of personal computing, the conversation about Microsoft almost always circles back to a punchline. Someone brings up Windows Vista, someone else mentions Internet Explorer, and inevitably, everyone laughs about Clippy.

They remember the googly eyes, the frantic tapping against the inside of the monitor glass, and that patronizing prompt: "It looks like you’re writing a letter." To a generation navigating Office 97 in high-pressure cubicles on tight deadlines, he was an infuriating digital backseat driver.

My memory of that era has always looked fundamentally different.

I grew up with the privilege of running fully licensed, retail installations of Windows rather than cracked, fragile builds.
To a child sitting in front of Word 97, exploring an operating system purely out of curiosity, Clippit—his actual, forgotten name—was never an irritation.

He was an ambient companion who made the machine feel alive.

It took me years to discover that the rest of the world hated him.

Looking back with an understanding of software architecture, the tragedy of Clippit was not that the concept was foolish; it was that it was wildly premature.

Beneath the cartoon sprite lay Microsoft Research’s Project Lumière—an astonishingly ambitious effort to apply Bayesian probability to real-time human intent.

Decades before modern transformers, neural networks, or massive compute clusters, Microsoft attempted to build an agentic assistant that ran on single-core processors and sixteen megabytes of RAM. Clippit quietly observed keystrokes, calculated the statistical likelihood of your next action, and tried to surface relevant tools before you had to hunt through dense menus.

Where Clippit collapsed was not in his algorithmic ambition, but in the fragile psychology of interface design. Leaning into social-actor theory—the idea that humans instinctively anthropomorphize interactive technology—Microsoft gave the assistant an expressive face and physical gestures. But an agent that interrupts your workflow with moderate probabilistic accuracy is infinitely more aggravating than a static toolbar.

When Clippit guessed wrong, he did not fail discreetly. He broke your train of thought, seized the cursor, and demanded social bandwidth without possessing the semantic comprehension to earn it.
He was an ambient agent stranded in an era of manual tools.

Clippit was not intelligent.

He was not particularly accurate.

He was often distracting.

And yet, looking back, I find it difficult to laugh at him. Not because he succeeded, but because he was attempting something that the technology of his era could not possibly support.

The paperclip sitting beside a blank Word document in 1997 was trying to do something remarkably similar to what modern AI assistants are attempting today: understand intent, reduce friction, and help people work with
technology in a more natural way.

The difference is that Clippit was trying to achieve it with a fraction of the computing power, memory, data, and contextual awareness that modern systems take for granted.

For most people, Clippy became a joke. For Microsoft, he became a lesson.

The company spent the next three decades refining the same idea through different products and technological eras. Cortana taught Microsoft that users prefer to ask for assistance rather than have it imposed on them.

Copilot is teaching Microsoft how critical context, memory, and restraint are when coexisting with a user's workflow.

Seen from that perspective, Clippit was not a dead end. He was a prototype.

The paperclip failed so that future assistants could learn when to speak, when to remain silent, and how to fit naturally into the work people were already doing. Maybe that is why I still remember him so fondly.

When I was a child sitting in front of Word 97, Clippit felt like a glimpse of the future. At the time, that future never quite arrived.

Now, nearly thirty years later, I can open Word, work with Copilot, and watch an assistant help organize ideas, refine drafts, and recall context across past conversations. For the first time, that old vision feels technically possible.

And the more I think about it, the harder it becomes to see Clippit as a failure.

Perhaps he was simply the first draft.

About This Series: First Drafts of the Future

Rather than cataloging Microsoft through missteps, this series re-examines the visionary ideas Microsoft conceptualized years—and sometimes decades—before the hardware, software architecture, or user culture was ready to sustain them.