PWAs: Personal Web Apps  🔗 **Source:** [PWAs: Personal Web Apps](https://ma.ttias.be/pwas-personal-web-apps/) > [!note]+ Document Notes > tags: [progressive-web-apps, offline-first, service-workers, ios-quirks, agent-skills, personal-software] > author: Mattias Geniar > source: ma.ttias.be > reference: https://ma.ttias.be/pwas-personal-web-apps/ > date created: 2026-08-24 09:00 > > > [!info] Generated analysis — not the author's words. Sections below are machine-written > > from the captured source. Only text inside `> [!quote]` blocks is verbatim from the author. > > Do not quote or attribute any other line to the named author. > > # 🏷️ Title: PWAs: Personal Web Apps > <!-- deep-read:sections start --> ## 🧭 Table of Contents - [📝 Summary](#-summary) - [📖 Main Content](#-main-content) - [🗒️ Notes](#️-notes) - [📚 References](#-references) - [🗣️ Paraphrase](#️-paraphrase) - [📰 Newsletter](#-newsletter) - [✅ Action Items](#-action-items) - [🧪 Hypotheses](#-hypotheses) - [📊 Methodology](#-methodology) - [❓ Questions](#-questions) - [🔮 Future Research](#-future-research) - [💡 Implications](#-implications) - [🧠 Learning Styles Assessment](#-learning-styles-assessment) - [📊 Accessibility Assessment](#-accessibility-assessment) - [🌍 DEIB Assessment](#-deib-assessment) - [✅ Logical Validity](#-logical-validity) - [🛡️ DARVO Analysis](#-darvo-analysis) - [🎯 Conclusion](#-conclusion) ### 🔗 References - [github.com/mattiasgeniar/offline-first-pwa](https://github.com/mattiasgeniar/offline-first-pwa) — the extracted agent skill and checklist - [random.ma.ttias.be](https://random.ma.ttias.be) — the monorepo of small tools described - `pwa-install-prompt` — the install-prompt component the author extracted for reuse - T3 Code — the agent used to build the tools - MDN: Service Worker API and Progressive Web Apps — the underlying platform capabilities ## 📝 Summary - **What happened.** Mattias Geniar describes settling on a format for personal and family software: **offline-first, mostly client-side PWAs**, installed to an iPhone home screen, deployed from a single monorepo where an agent builds new tools and auto-deploys when generated tests pass. - **Why it matters.** The interesting part is not that PWAs work — it is the **operating model**. Small tools that solve one person's problem have historically been unbuildable because distribution, install, and maintenance cost more than the tool is worth. A PWA installed in two clicks plus an agent that writes it in thirty minutes collapses both sides of that equation. - **Key stakeholders.** Anyone building software for an audience too small to justify an app store; developers on iOS who don't want to sideload; the WordPress/IndieWeb crowd shipping PWAs for personal publishing; anyone maintaining agent instruction files they'd like to reuse. - **Risks and tradeoffs.** Explicitly personal-scale — "not commercial-grade software, but it solves my own problems just fine." Accessibility is entirely absent from a seven-item non-negotiables list, and "no webfonts" is stated without qualification. The tools are Dutch-language and family-specific, so the tooling generalises but the artifacts do not. - **Bottom line.** Two things are worth taking. The **seven non-negotiables** are a genuinely earned checklist — he says every rule "is something I got wrong first," and several are non-obvious enough to be worth stealing outright, particularly that `fetch().catch(→ cache)` fails you on a *slow* network because it only fires when truly offline. And the **CLAUDE.md-to-agent-skill extraction** is the more portable idea: accumulated project rules, hardened by repetition, promoted into a reusable skill others can clone. He also labels the provenance precisely — the skill is AI-generated from his rules file, the post is his. ## 📖 Main Content The framing is modest and the implications are not. Geniar has found his format for personal and family software: **mobile-only web applications, offline-first, rendering mostly client-side**, added to a phone home screen where they behave "99% like a native application, but is so much easier to maintain, deploy & install." His justification for skipping native is practical rather than ideological. The family is all-in on Apple, so sideloading "isn't a rabbit hole I want to go down," while **PWAs install with two clicks**. Eight are on his home screen: Imposter, Wordl, Escape, Roepie, Rufiyaa, Cal, Video Speedup, and Frame Grabber. The organisational choice is the first genuinely reusable decision: rather than a subdomain per tool, everything lives at **random.ma.ttias.be** as a single monorepo with automated deployment rules. **If auto-generated tests pass, it auto-deploys.** His description of the loop is the sentence that captures the shift: **"I can just write a simple prompt, leave T3 code to work for 30 minutes and see the results directly on my phone."** That is worth sitting with. The bottleneck on personal software was never the code — it was that scaffolding, deploying, and distributing a tool cost more than a tool used by four people is worth. A monorepo with automatic deployment removes the second cost; an agent removes the first. What remains is a prompt and a wait. The catalogue is instructive precisely because the tools are unremarkable: currency converters for Sri Lankan Rupee and Maldives Rufiyaa (holiday-shaped problems), three Dutch-language family games, a **Frame Grabber** for pulling a still from a video — "why this isn't natively available on iOS, I don't know" — and **Video Speedup**, built because iMovie on iOS caps speedups at 2×. Every one of these is a gap between what a platform provides and what one household needs. None would ever justify an app store submission. His own assessment is honest: **"It's not commercial-grade software, but it solves my own problems just fine."** He does note the range as a point about the platform — from a video editor to a small game engine, client-side JavaScript "just works." **The seven non-negotiables are the article's densest value**, and the framing that makes them credible is that **"every rule in there is something I got wrong first."** **Offline-first** is stated more precisely than the usual advice. Assume no connectivity, load in under a second, never be blocked by the network — and then the specific trap: **`fetch().catch(→ cache)` only fires when you are truly offline; a slow network can still block for around ten seconds.** That is the failure mode that makes nominally offline-first apps feel broken on a bad connection, and it catches people who believe they have already solved this. The correct pattern is stated separately as its own rule: **always serve from cache, refetch in the background.** **Hash-based updates** follow logically. If you always serve from cache, you need a deliberate mechanism to escape it — a background version check, a banner when a new version exists, and a refresh. Simple, and necessary precisely because of the previous rule. Three rules are iOS-specific and the kind of thing you only learn by shipping: **spacing from the top for the notch and camera** (unusable space), a **PWA install prompt per tool** (extracted into a reusable `pwa-install-prompt` component), and **avoiding iOS's copy-to-clipboard behaviour via correct CSS** where it isn't wanted. The seventh is **no webfonts** — consistent with an offline-first, sub-second-load position, though stated as an absolute without acknowledging that system font stacks vary in what they can express. **The final section is the most transferable idea in the post.** Over weeks he grew the repository's `CLAUDE.md` into a full ruleset every tool follows, then extracted it into its own repository as **an agent skill**: clone into `~/.claude/skills/`, or point any `AGENTS.md`-reading tool at it. He is explicit that **"it's also just a checklist you can read"** — it works for humans without an agent. Contents: service worker caching strategy, precaching, in-app update prompts, iOS home screen quirks, safe areas, and how to test any of it. This is the pattern worth naming, because it is a general one: **project instructions accumulate as you make mistakes; once they have been validated by repetition across several projects, they can be promoted out of the project and shared.** The agent instruction file becomes the artifact, not a byproduct of it. And it is dual-use by construction — a skill for agents, a checklist for people. He closes with a provenance statement that is a small model of good practice: **"The skill itself is AI-generated, distilled from the CLAUDE.md file that repo runs on. This post I wrote myself."** Two sentences, precise about which artifact came from where. Most AI-assisted work ships with either no labelling or a blanket disclaimer that conveys nothing. Two things the post does not address, and one is significant. **Accessibility appears nowhere** — not in the non-negotiables, not in the skill's listed contents. For personal tools this is defensible, and the post is scoped to personal tools. But the extracted skill is offered publicly for other people's projects, and a checklist that covers safe areas and clipboard CSS while omitting focus management, contrast, and touch target sizing will propagate that omission into everything built from it. The second: auto-deploy on auto-generated tests passing is a thin verification gate for anything beyond personal scale — which lands pointedly against the same batch's argument that agent output needs verification loops, and which he would presumably grant. ### 🗒️ Notes #### The format, and why not native - **Mobile-only web applications, offline-first, mostly client-side.** Added to the home screen, they behave "99% like a native application, but is so much easier to maintain, deploy & install." - The family is all-in on Apple, so sideloading "isn't a rabbit hole I want to go down." **PWAs install with two clicks.** - Eight installed on his home screen: Imposter, Wordl, Escape, Roepie, Rufiyaa, Cal, Video Speedup, Frame Grabber. - Enabling assumption stated plainly: "JavaScript is powerful enough to do pretty much anything these days — especially if you don't have to write the code yourself." #### The operating model — this is the actual insight - **One monorepo at random.ma.ttias.be**, not a subdomain per tool. - **Automatic deployment: if auto-generated tests pass, it auto-deploys.** - The loop, in his words: **"I can just write a simple prompt, leave T3 code to work for 30 minutes and see the results directly on my phone."** - **Why it matters:** the barrier to personal software was never writing it — it was that scaffolding, deploying, and distributing cost more than a four-user tool is worth. The monorepo kills the second cost; the agent kills the first. #### The catalogue — unremarkable on purpose - Currency converters for **Sri Lankan Rupee** and **Maldives Rufiyaa** — holiday-shaped problems. - Three Dutch-language family games: **Imposter, Wordl, Escape**. - **Frame Grabber** — extract a still from a video. "Why this isn't natively available on iOS, I don't know." - **Video Speedup** — because iMovie on iOS caps speedups at 2×. - Every one is a gap between what the platform provides and what one household needs. None would justify an app store submission. - His own honest assessment: **"It's not commercial-grade software, but it solves my own problems just fine."** - Point about the platform: the range runs from a video editor to a small game engine, and client-side JavaScript "just works." #### The seven non-negotiables - Framing that makes them credible: **"Every rule in there is something I got wrong first."** 1. **Offline-first, stated precisely.** Assume no connectivity, load in under a second, never be blocked by the network. **The trap: `fetch().catch(→ cache)` only fires when you're truly offline; a slow network can still block for ~10s.** This is the failure mode that makes supposedly offline-first apps feel broken on bad connections. 2. **Simple hash-based updates.** Background fetch for a version check, top banner when a new version exists, refresh to update. Necessary *because* of rule 3. 3. **Always serve from cache, refetch in the background.** 4. **Sufficient spacing from the top** for the iPhone notch and camera — unusable space. 5. **A PWA install prompt per tool**, extracted into a reusable `pwa-install-prompt` component. 6. **Avoid iOS's copy-to-clipboard behaviour** where unwanted, via correct CSS. 7. **No webfonts.** Consistent with sub-second offline-first loading; stated as an absolute. #### CLAUDE.md → agent skill — the most transferable idea - Over weeks, the repository's `CLAUDE.md` grew into a full ruleset every tool follows. - Extracted into its own repository: **github.com/mattiasgeniar/offline-first-pwa**. - **It's an agent skill** — clone into `~/.claude/skills/`, or point any `AGENTS.md`-reading tool at it. - **Dual-use by construction:** "It's also just a checklist you can read." Works without an agent. - Covers: service worker caching strategy, precaching, in-app update prompts, iOS home screen quirks, safe areas, and how to test any of it. - **The general pattern worth naming:** project instructions accumulate as you make mistakes; once hardened by repetition, they can be promoted out of the project and shared. The instruction file becomes the artifact rather than a byproduct. #### Provenance labelling — a small model of good practice - **"The skill itself is AI-generated, distilled from the CLAUDE.md file that repo runs on. This post I wrote myself."** - Two sentences, precise about which artifact came from where. - Most AI-assisted work ships with no labelling, or a blanket disclaimer that conveys nothing. This is the useful version. #### What's absent - **Accessibility appears nowhere** — not in the seven non-negotiables, not in the skill's listed contents. Defensible for personal tools; consequential because **the skill is published for other people's projects**, and a checklist covering safe areas and clipboard CSS while omitting focus management, contrast, and touch targets propagates that gap into everything built from it. - **Auto-deploy on auto-generated tests passing is a thin verification gate** beyond personal scale — which sits pointedly against this same batch's argument that agent output needs real verification loops. ## 📚 References - [offline-first-pwa (agent skill / checklist)](https://github.com/mattiasgeniar/offline-first-pwa) — the extracted ruleset - [MDN — Progressive Web Apps](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps) — platform reference - [MDN — Service Worker API](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) — caching and update mechanics - [MDN — Safe area insets (`env()`)](https://developer.mozilla.org/en-US/docs/Web/CSS/env) — the notch spacing rule - [WCAG 2.2](https://www.w3.org/TR/WCAG22/) — the dimension the checklist omits - [random.ma.ttias.be](https://random.ma.ttias.be) — the tools themselves ## 🗣️ Paraphrase - **Format.** The author's preferred shape for personal and family software is an offline-first, largely client-side web application installed to a phone home screen. - **Rationale.** Installation takes two clicks and avoids the friction of native distribution in a closed ecosystem, while remaining far easier to maintain and deploy. - **Organisation.** All tools live in one repository under a single domain rather than each getting its own, with deployment automated on passing generated tests. - **Loop.** A short prompt, roughly half an hour of agent work, and the result is usable on the phone. - **Catalogue.** Currency converters, family games in Dutch, a still-frame extractor, and a video speed tool — each filling a gap between platform capability and household need. - **Assessment.** Not commercial-grade, but sufficient for the problems it was built for. - **Rules, offline.** Assume no network, load in under a second, and never let the network block — noting that the common cache-fallback pattern only triggers when fully offline, so slow connections still hang. - **Rules, caching.** Serve from cache always and refresh in the background. - **Rules, updates.** Check for a new version in the background and offer a banner to refresh. - **Rules, platform.** Leave room for the device notch, provide an install prompt, suppress unwanted clipboard behaviour with CSS, and avoid web fonts. - **Provenance of the rules.** Each was learned by getting it wrong first. - **Extraction.** The accumulated project instructions were promoted into a standalone repository usable both as an agent skill and as a human-readable checklist. - **Labelling.** The extracted skill is machine-generated from those instructions; the post itself is human-written. ## 📰 Newsletter **The barrier to personal software was never writing it** Mattias Geniar has eight PWAs on his iPhone home screen — currency converters for a holiday, three Dutch-language games for the kids, a frame grabber for pulling stills out of video (*"why this isn't natively available on iOS, I don't know"*), and a video speed tool because iMovie on iOS caps at 2×. None of these would ever justify an App Store submission. That's the point. His setup: **one monorepo**, all the tools under one domain instead of a subdomain each, with **auto-deploy when generated tests pass.** Then: *"I can just write a simple prompt, leave T3 code to work for 30 minutes and see the results directly on my phone."* Sit with that for a second. Personal software has always been blocked by the *overhead*, not the code — scaffolding, deploying, and distributing a tool used by four people costs more than the tool is worth. A monorepo with automatic deployment kills the distribution cost. An agent kills the build cost. What's left is a prompt and a wait. **The seven non-negotiables are the part to steal**, and they're credible because he says *"every rule in there is something I got wrong first."* The one I'd not seen stated this precisely: > `fetch().catch(→ cache)` only fires when you're truly offline; a slow network can still block for ~10s That's the failure mode that makes "offline-first" apps feel broken on a bad connection — and it catches people who think they've already solved this. The fix is his separate rule: **always serve from cache, refetch in the background.** Which then forces the next rule: hash-based version checks with a refresh banner, because if you always serve cache you need a deliberate way out of it. The rest are hard-won iOS specifics: leave room for the notch, ship an install prompt per tool (he extracted his into `pwa-install-prompt`), suppress iOS copy-to-clipboard with CSS where you don't want it, and no webfonts. **But the most portable idea is the last section.** He grew the repo's `CLAUDE.md` into a full ruleset, then **pulled it out into its own repository as an agent skill** — clone into `~/.claude/skills/`, or point any `AGENTS.md`-reading tool at it. And crucially: *"It's also just a checklist you can read."* Dual-use by construction. That's a pattern worth naming. **Project instructions accumulate as you make mistakes. Once they've been hardened by repetition, promote them out of the project and share them.** The instruction file stops being a byproduct and becomes the artifact. **And the provenance line is a small masterclass:** *"The skill itself is AI-generated, distilled from the CLAUDE.md file that repo runs on. This post I wrote myself."* Two sentences, precise about which artifact came from where. Compare that to the blanket "AI was used in producing this" disclaimers that tell you nothing. **Two gaps worth naming.** Accessibility appears **nowhere** — not in the seven rules, not in the skill's contents. Fine for personal tools, and he's clear that's the scope. But the skill is published for *other people's* projects, and a checklist that covers safe-area insets and clipboard CSS while skipping focus management, contrast, and touch targets will propagate that hole into everything built from it. That's a fixable PR, not a criticism of the approach. Second: auto-deploy on *auto-generated* tests passing is a thin gate. Which lands right against the verification argument running through everything else this week — generation got cheap, checking didn't. At household scale, fine. Past it, not. **If you build PWAs for personal publishing** — and I do — the offline-first rules and the install-prompt extraction are directly liftable. ## ✅ Action Items #### DevRel - Developer advocacy: the CLAUDE.md-to-shared-skill extraction is the most teachable pattern here. Build a talk on promoting accumulated project rules into reusable artifacts. - Education: the `fetch().catch(→ cache)` trap belongs in every offline-first tutorial and is missing from most. Write the corrective. - Developer experience: publish reusable components for the boring platform quirks — install prompts, safe-area handling — the way he extracted `pwa-install-prompt`. - Developer marketing: "personal web apps" is a better frame than "progressive web apps" for the audience that would actually benefit; the value is distribution, not progressiveness. - Community management: encourage contributors to publish their agent instruction files. Most contain hard-won knowledge that never leaves the repository. - Internal/external/cross-project: agent skills are becoming a shareable artifact class. A convention for publishing and discovering them would help before every ecosystem invents its own. #### OSPO - Policy & Governance: define review expectations for published agent skills. A skill propagates its omissions into every project that adopts it, which makes it higher-leverage than ordinary documentation. - License Compliance: agent skills distilled from project files raise the question of what licence applies to a machine-generated derivative of your own instructions. Worth an explicit position. - Security Management: auto-deploy on auto-generated tests is a supply-chain shape worth naming — the tests and the code have the same author, so the gate is weaker than it looks. - Software Inventory: track agent skills as dependencies. A skill in `~/.claude/skills/` shapes output the same way a library shapes behaviour. - Developer Support: offer a reviewed baseline PWA skill including the accessibility rules this one omits. - Community Engagement: contribute the accessibility section back to `offline-first-pwa` rather than forking. It is a well-scoped, welcome-looking contribution. - Strategic Alignment: personal-scale tooling built by agents will show up inside organisations whether or not it is sanctioned. Better to have a position early. #### Community - Maintainers: extract your project's accumulated rules into something shareable. The knowledge is already written; it is just trapped in one repository. - Contributors: adding an accessibility section to the offline-first PWA skill would be a genuinely high-leverage small contribution. - Sponsors: fund reviewed, accessible baseline skills and starters. They propagate further than individual projects do. - Ecosystem: agree a convention for how published agent skills declare scope and known gaps, so adopters know what a skill does *not* cover. #### WordPress - Core: not applicable to this source, though PWA support for WordPress admin has been a long-running question this makes more concrete. - Core Performance: "always serve from cache, refetch in the background" and sub-second load targets are directly applicable to WordPress front-end performance thinking. - Core AI: agent skills as versioned, shareable artifacts is a pattern worth considering for how AI features get configured and constrained. - **Core Program Team:** not applicable to this source. - Mobile: **the most relevant team.** The iOS quirks catalogued here — notch spacing, install prompts, clipboard CSS — apply directly to any WordPress mobile web experience. - Playground: Playground is itself a browser-first application; the offline-first caching rules are relevant to how it behaves on poor connections. - Community: not applicable to this source. - Training: a lesson on building a small PWA end-to-end would be an excellent practical exercise, and this checklist is a ready-made curriculum spine. - Marketing: not applicable to this source. - Support: not applicable to this source. - Design: safe-area handling and install prompts are design-system concerns that most WordPress themes do not address. - Documentation: document the offline-first caching pattern properly — the slow-network trap is under-documented across the entire web platform, not just WordPress. - Photos: not applicable to this source. - TV: not applicable to this source. - Polyglots: his tools are Dutch-language and family-scoped, which is a good reminder that personal software is where non-English defaults are natural rather than exceptional. - Accessibility: **the gap to fill.** A seven-rule PWA checklist with no accessibility items, published as a reusable skill, will propagate that omission. Contributing focus management, contrast, and touch-target rules is a concrete, well-scoped intervention. - Meta: not applicable to this source. - CLI: not applicable to this source. - Hosting: static, client-side, cache-first apps are cheap to host — relevant to anyone costing out small-tool infrastructure. - Tide: not applicable to this source. - Openverse: not applicable to this source. - Themes: the no-webfonts position is a defensible performance stance worth weighing against block theme font-library practice. - Plugins: **directly relevant to PWA-shipping plugins** — the install prompt, update banner, and safe-area rules are exactly the details such plugins get wrong. #### The WPOCC - Programs: a workshop on building and shipping a personal PWA would be practical, achievable in a session, and produce something participants keep. - Projects: publish a reviewed, accessible baseline PWA skill as community infrastructure. - Funding experiments: fund maintenance of shared agent skills. They are becoming dependencies and nobody treats them as such. ### FAIR - Technical independence: client-side, offline-first, self-hosted apps installed without an app store are about as independent as consumer software gets — no gatekeeper, no review queue, no revenue share. - Policies and covenants: published agent skills should declare their scope and known omissions, since adopters inherit both. - Productized governance artifacts: an agent skill that doubles as a human checklist is a genuinely good artifact shape — machine-actionable and human-auditable at once. ### 🧪 Hypotheses 1. **Distribution cost, not development cost, was the binding constraint on personal software.** The volume of small personal tools built will rise more sharply with two-click install availability than with faster development alone. 2. **Cache-first serving outperforms network-first on real-world mobile connections.** Median time-to-interactive will be lower for cache-first PWAs than network-first equivalents, with the gap widest on slow rather than absent connections. 3. **Published agent skills propagate their omissions.** Projects built using a skill lacking accessibility rules will show measurably worse accessibility outcomes than projects built without it, because the skill displaces rather than supplements other guidance. 4. **Extracted rulesets outperform ad-hoc instructions.** Projects using a hardened, repetition-validated skill will require fewer correction cycles than projects with per-project improvised instructions. 5. **Auto-generated tests are a weak deployment gate.** Deployments gated only on tests written by the same agent that wrote the code will show higher defect rates than those gated on independently-authored tests. 6. **PWA install friction is the adoption barrier, not capability.** Users will fail to install PWAs at high rates without an explicit in-app prompt, which is why his rule 5 exists. ### 📊 Methodology - **H1:** Hard to test cleanly since both variables moved together. Best available design compares tool creation rates in ecosystems where install friction differs (iOS PWA versus Android PWA versus sideloading-permitted platforms) while agent availability is constant. - **H2:** Synthetic network testing across throttled profiles — offline, 2G, 3G, fast — measuring time-to-interactive for both strategies. Straightforward, and would settle a widely-misunderstood point. - **H3:** Compare accessibility audit scores across projects built with and without the skill. Requires the skill to reach adoption; the honest version of this test is to fix the skill instead. - **H4:** Count correction cycles per feature across projects using extracted versus improvised instructions. Confounded by the fact that people who extract rulesets are more disciplined generally. - **H5:** Compare post-deploy defect rates by test provenance — same-agent, different-agent, human-authored. Directly relevant to this batch's recurring verification theme and cheap to run inside one organisation. - **H6:** A/B the presence of an install prompt against install completion rates. The kind of thing a single site could answer in a week. ### ❓ Questions - What happens to these tools when the author stops maintaining them — do family members have any recourse, or is personal software inherently disposable? - Does auto-deploy on auto-generated tests hold up as tools accumulate, or does it fail quietly once cross-tool interactions exist? - Is "no webfonts" a genuine requirement or a preference dressed as one — what breaks if you inline a subset? - Should a published agent skill declare what it does *not* cover, and would that have prevented the accessibility gap? - How much of the thirty-minute build time is agent work versus the author's accumulated rules doing the heavy lifting? - If personal software becomes trivially cheap, does the incentive to fix platform gaps (iOS still-frame extraction, iMovie speed caps) decrease? - What is the actual failure rate of the two-click install flow for non-technical family members? - Does the skill's effectiveness depend on the specific agent, or does it transfer across `AGENTS.md`-reading tools as claimed? ### 🔮 Future Research - **Agent skills as a dependency class.** They shape output like libraries shape behaviour, and nobody versions, audits, or tracks them. That gap will matter more as adoption grows. - **Offline-first correctness.** The slow-network trap suggests the standard guidance is subtly wrong across much of the ecosystem. Worth a systematic audit of published tutorials. - **The economics of personal software.** If both build and distribution costs collapse, the interesting question is what people build when nothing has to be justified to anyone. - **Test provenance and deployment safety.** Same-author tests as a gate is a general problem this instance makes concrete. - **Accessibility in generated software.** If skills and starters carry the defaults, accessibility outcomes are decided at the skill level rather than the project level — which is a leverage point nobody is using. - **Longevity of personal deployments.** Family-scale software with one maintainer has an obvious failure mode; whether anyone has good practices for it is unstudied. ### 💡 Implications - **Practice.** The offline-first rules are immediately liftable, especially the cache-first-with-background-refetch pattern and the slow-network caveat. The install-prompt extraction is a small reusable win. - **Policy.** Published agent skills should declare scope and known gaps. Adopters inherit omissions silently, which makes skills higher-leverage and higher-risk than documentation. - **Security.** Auto-deploy gated on same-author generated tests is a weak control. Fine at household scale, not past it. - **Education.** A small PWA is close to an ideal teaching project — visible result, real platform quirks, no backend — and this checklist is a ready curriculum spine. - **Funding.** Reviewed, accessible baseline skills and starters propagate much further than individual projects. That is a high-leverage, low-cost thing to fund and nobody is funding it. ### 🧠 Learning Styles Assessment - **Reading level estimate:** Flesch-Kincaid Grade Level ≈ 9; Flesch Reading Ease ≈ 61. Short sentences, conversational, occasional emoji. Assumes familiarity with service workers, caching strategies, monorepos, and agent instruction files, none explained. #### 👀 Visual learners - Present: two screenshots — the iPhone home screen with the eight installed PWAs, and the tool grid at random.ma.ttias.be. Both convey the concept faster than the prose does. - Improve: no diagram of the caching and update flow, which is the part with actual subtlety. A simple state diagram would carry the offline-first rules better than the bullet list. #### 🔊 Aural learners - Present: none; text-only post. - Improve: **Not applicable to this source** — a short technical blog post with no audio dimension. #### 🗣️ Verbal learners - Present: plain, direct writing with concrete named examples. The rules are stated as imperatives, which suits their function. - Improve: several terms pass undefined for a post that will reach non-specialists — precaching, safe areas, hash-based updates, agent skill. #### 🧩 Kinesthetic learners - Present: strongest dimension. There is a repository to clone, working tools to try, a component to reuse, and a checklist to apply. - Improve: no minimal starting example — the skill is a set of rules rather than a runnable template, so the first step is still yours to construct. #### 🧠 Logical learners - Present: the rules have internal coherence — cache-first *requires* an update mechanism, and offline-first *requires* no webfonts. The dependencies between rules are real even if unstated. - Improve: those dependencies go unstated, so the seven rules read as a flat list rather than a small system. Saying which rules force which would strengthen the whole. #### 🧑‍🤝‍🧑 Social learners - Present: the skill is published for others, with an implicit invitation to use and presumably improve it. - Improve: no contribution guidance and no stated scope, so a would-be contributor does not know whether accessibility rules would be welcome or out of scope. #### 🧘‍♀️ Solitary learners - Present: ideal — self-contained, short, immediately actionable alone. - Improve: nothing significant. #### 🌿 Naturalistic learners - Present: incidentally — cache-first, no-webfonts, client-side rendering are all low-bandwidth and low-energy by construction. - Improve: the efficiency angle is never named, though it is genuinely present. **Otherwise largely not applicable to this source.** ### 📊 Accessibility Assessment #### Screen reader semantics - Present: a conventional blog post with headings and lists; images have descriptive captions in the captured text. - Improve: verify actual alt text on the two screenshots rather than relying on captions. Maps to **WCAG 2.2 A 1.1.1**. #### Keyboard navigation - Present: not applicable to the article. - Improve: **the product concern is the real one.** Nothing in the seven rules addresses focus management, which matters especially for cache-first apps that update content underneath the user. Maps to **2.4.3 Focus Order** and **2.4.7 Focus Visible**. #### Contrast and readability - Present: standard blog typography. - Improve: the tool grid screenshot shows a dark theme with small one-line descriptions; contrast in the tools themselves is unassessed and unaddressed by the checklist. Maps to **1.4.3**. #### Text resizing and reflow - Present: standard responsive blog layout. - Improve: **"No webfonts" interacts with text scaling** in ways the rule does not consider — system font stacks respond differently to user font-size preferences across platforms. Worth testing against **1.4.4 Resize Text**. #### Media and captions - Present: two captioned screenshots; no audio or video. - Improve: nothing significant for the article. #### Forms and interactions - Present: not applicable to the article. - Improve: **the update banner is an interaction pattern with real accessibility requirements** — it needs to announce itself to assistive technology without stealing focus. Maps to **4.1.3 Status Messages**. The install prompt has the same requirement. #### Standards reference - The article itself is fine. **The checklist it publishes is the issue:** seven non-negotiables covering safe areas and clipboard CSS, with nothing on focus management (**2.4.3**, **2.4.7**), status announcements for the update banner (**4.1.3**), contrast (**1.4.3**), or touch target size (**2.5.8**). Because the skill is adopted wholesale into other projects, that omission propagates. **This is the single highest-leverage contribution someone could make to the repository.** ### 🌍 DEIB Assessment #### Cultural breadth - Present: genuinely and incidentally good — three tools are Dutch-language for a Dutch-speaking family, and two are currency converters for Sri Lanka and the Maldives. Personal software is naturally non-English-default, which is a nice illustration of what software looks like when it is not built for a market. - Improve: the platform assumptions are narrow — Apple ecosystem throughout, with iOS-specific rules making up three of seven non-negotiables. The skill is presented generally but is substantially iOS-shaped. #### Inclusive language - Present: plain, direct, unpretentious. No jargon-as-gatekeeping; he explains his reasoning rather than asserting expertise. - Improve: unglossed technical terms — precaching, safe areas, service worker strategy — are the practical barrier for the audience most likely to benefit from building personal tools. #### Neurodiversity support - Present: excellent structure for a short post — clear headings, numbered rules, short paragraphs, one idea per bullet. Easy to scan and easy to return to. - Improve: nothing significant. #### Representation - Present: a single author writing about his own household; no claim to generality beyond that. - Improve: "solves my own problems just fine" is honest scoping, but the published skill implicitly generalises to everyone's projects — and the gap between those two scopes is where the accessibility omission does its damage. #### Psychological safety - Present: notably good. **"Every rule in there is something I got wrong first"** invites others to be beginners. "It's not commercial-grade software, but it solves my own problems just fine" explicitly lowers the bar for building things. And the provenance line models honest labelling without defensiveness. - Improve: nothing significant. This is a post that makes building feel accessible, which is most of its value. ### ✅ Logical Validity #### Strong reasoning - **Practical justification for the format choice.** Two-click install versus sideloading in a closed ecosystem is a concrete, verifiable reason to prefer PWAs, offered without ideological framing about the open web. - **Rules derived from failure, stated as such.** "Every rule in there is something I got wrong first" is the correct epistemic basis for a checklist and is stated openly rather than implied. - **Precise technical correction.** The `fetch().catch(→ cache)` caveat identifies a specific mechanism — the catch only fires on true offline, not on slow — and gives a magnitude (~10s). That is a genuine, checkable correction to widely-repeated advice. - **Internally coherent rule system.** Cache-first serving *necessitates* an explicit update mechanism; offline-first sub-second loading *necessitates* dropping webfonts. The rules constrain each other correctly, even though he never says so. - **Honest scoping.** "Not commercial-grade software, but it solves my own problems just fine" prevents the reader from over-generalising, and is stated before any of the advice. - **Precise provenance labelling.** Distinguishing the AI-generated skill from the human-written post, artifact by artifact, is more informative than any blanket disclaimer. #### Fallacies - **Overgeneralization** — the opening claim that "JavaScript is powerful enough to do pretty much anything these days." *Weakness:* offered as a premise for the whole approach, and false for a wide class of applications — background processing, deep OS integration, sustained compute, hardware access. The very examples he cites (Frame Grabber, Video Speedup) exist *because* the platform's native tools are inadequate, not because the web reached parity. *Fix:* scope it to the class of tool he actually builds. - **Unstated absolute** — "No webfonts," rule seven. *Weakness:* presented as non-negotiable with no reasoning and no acknowledgement of cost. It follows from the sub-second-load goal, but that dependency goes unstated, so it reads as taste rather than derivation. *Fix:* state the constraint it derives from, and the conditions under which a subset font would be acceptable. - **Suppressed consideration** — accessibility, absent from all seven rules and from the skill's contents. *Weakness:* defensible for personal tools, but the artifact is published for general adoption, and a checklist that covers clipboard CSS while omitting focus management makes an implicit claim about what matters. *Fix:* declare the skill's scope, or add the missing rules. - **Weak verification gate presented as sufficient** — "If (auto-generated) tests pass, it auto-deploys." *Weakness:* tests generated by the same agent that wrote the code share its blind spots, so the gate is substantially weaker than "tests pass" implies. Fine at household scale; the post does not mark the boundary. *Fix:* note that the gate's adequacy depends on the stakes. - **Anecdotal generalization (minor)** — the seven rules derive from one person's projects on one platform for one household. *Weakness:* published as a general skill without noting the sample. To his credit the honest scoping elsewhere partly covers this. *Fix:* one line in the repository noting the context the rules were learned in. #### Tone of voice - Plain and unpretentious throughout; short sentences, no throat-clearing, no attempt to make small tools sound significant. - Self-deprecating in a way that lowers the barrier for readers — the software is "not commercial-grade," the rules exist because he got them wrong. - Mildly exasperated at platform gaps, with a shrug emoji doing the work — iMovie's 2× cap, iOS lacking still-frame extraction. - Practical rather than evangelical: he is not arguing for the open web, he is explaining why this is easier for his family. - Precise where precision matters — the caching caveat and the provenance line are both notably careful in an otherwise casual piece. ### 🛡️ DARVO Analysis - **Deny:** Not present. There is no accusation in play, and the author's characteristic move is admission — the rules exist because he got them wrong, the software is not commercial-grade. - **Attack:** Not present. Mild criticism is directed at platform limitations (iMovie's speed cap, iOS lacking frame extraction), never at people or organisations. - **Reverse victim/offender:** Not present. No victim/offender framing exists in the material. - **Emotional cues and rhetoric:** Understated and practical. No persuasive pressure; nothing is being sold, and the skill is given away. - **Assessment:** DARVO is **not applicable to this source** — a short personal technical post with no accusatory or defensive dynamic. ## 🎯 Conclusion - **Bottom line.** The insight is economic, not technical. **The barrier to personal software was distribution and maintenance overhead, not writing the code** — and a two-click PWA install plus an agent that builds in thirty minutes collapses both sides at once. What emerges is software that never had to be justified to anyone: currency converters for one holiday, three games in Dutch, a frame grabber because iOS lacks one. - **The seven non-negotiables are earned and liftable.** The one to internalise: **`fetch().catch(→ cache)` only fires when truly offline, so a slow network still blocks for around ten seconds** — the failure mode that makes nominally offline-first apps feel broken, and one that catches people who think they have solved this. Its companion rule, always serve from cache and refetch in the background, is the actual fix. - **The most portable idea is the extraction.** Project instructions accumulate as you make mistakes; once hardened by repetition, promote them out of the project into a shareable artifact. His is **dual-use by construction** — an agent skill and a human checklist in one repository — which is the right shape for this class of thing. - **And the provenance line is worth copying verbatim as practice:** "The skill itself is AI-generated, distilled from the CLAUDE.md file that repo runs on. This post I wrote myself." Artifact-by-artifact labelling beats a blanket disclaimer every time. - **Two gaps.** **Accessibility appears nowhere** in the rules or the skill — defensible for personal tools, consequential because the skill is published for other people's projects and will propagate the omission. Adding focus management, status announcements for that update banner, contrast, and touch targets is the single highest-leverage contribution available to that repository. And auto-deploy gated on *auto-generated* tests is a thin verification gate — which lands squarely against this batch's recurring finding that generation got cheap and checking did not. - **Next steps for readers.** If you ship PWAs for personal publishing, lift the offline-first caching rules and the install-prompt extraction directly. If you maintain agent instruction files, ask which of your rules have been validated by enough repetition to promote out of the project. And if you want a small, well-scoped, genuinely useful open source contribution this week, the accessibility section of `offline-first-pwa` is sitting there unwritten. ## 🔄 Refactor Appendix — PWAs: Personal Web Apps > Density: 2–5 Literature atoms (H3), 0–3 Permanent candidates (H4). > Defaults: 3 Literature, 1 Permanent. Resonance filter: if you can't > articulate in one line why a claim matters, drop it. > > Konik claim-header rules: present tense, declarative, ≤10 words when > possible, searchable, unique, mirrors annotation focus if present. > > Atomicity: one declarative sentence per atom. "and"/"also" → split. > > Tag pool: #bmf · #addendum · #xref · #articleseed · #storystem · #share · #aphorisms ### 📚 Literature Atoms (H3) #### [H1] Cache fallback doesn't fire on slow networks > [!quote] > fetch().catch(-&gt; cache) only fires when you&#39;re truly offline; a slow network can still block for ~10s **Context & use**: - The precise correction to widely-repeated offline-first advice, and the reason supposedly offline-first apps feel broken on bad connections. The fix is his separate rule: always serve from cache, refetch in the background. Directly applicable to any PWA I ship. **Tags**: #xref #share <!-- atomicity: 1 idea ✓ --> #### [H2] Accumulated project rules become a shareable skill > [!quote] > I&#39;ve grown the CLAUDE.md of that repo into a full set of rules that every tool in it follows. I&#39;ve pulled them out into their own repo **Context & use**: - The most portable idea in the post. Instructions accumulate as you make mistakes; once hardened by repetition, promote them out of the project. Dual-use by construction — an agent skill *and* a human checklist. The instruction file becomes the artifact rather than a byproduct. **Tags**: #xref #articleseed <!-- atomicity: 1 idea ✓ --> #### [H3] Every rule came from getting it wrong first > [!quote] > Every rule in there is something I got wrong first. **Context & use**: - The correct epistemic basis for a checklist, stated openly. It is also what makes the list credible — these are not best practices copied from elsewhere but failures encoded. Worth adopting as a standard for any checklist I publish. **Tags**: #xref #aphorisms <!-- atomicity: 1 idea ✓ --> #### [H4] Label provenance artifact by artifact > [!quote] > The skill itself is AI-generated, distilled from the CLAUDE.md file that repo runs on. This post I wrote myself. **Context & use**: - Two sentences, precise about which artifact came from where. Strictly better than a blanket "AI was used" disclaimer, which conveys nothing. A small model of the labelling practice this pipeline's own provenance stamp exists to enforce. **Tags**: #xref #share <!-- atomicity: 1 idea ✓ --> ### 🧠 Permanent Candidates (H4) #### [P1] Collapsing distribution cost is what unlocks personal software **Claim** (one sentence, Courtney's voice): Software for an audience too small to justify itself becomes buildable only when both the cost of making it and the cost of getting it onto someone's device fall to near zero, and distribution is usually the later of the two to fall. **Evidence pointer**: [[#H2]] and the monorepo-plus-agent loop **Scope & conditions**: Holds where the audience is small enough that no amount of build-cost reduction alone justifies the distribution overhead. Fails where distribution is already free but the problem is genuinely hard — collapsing build cost does not make hard software easy. The corollary is that platform gatekeeping is a tax on small-audience software specifically, and barely a tax on large-audience software at all. **Links** (≥1 with annotation): - [[Indieweb-personal-publishing]] — because applies-in personal tooling - [[Platform-gatekeeping]] — because contrasts on who bears the cost - [[Outpost-mobile-publishing]] — because applies-in my own PWA work **Optional**: `proof_state: working` <!-- atomicity: 1 idea ✓ --> #### [P2] A published skill propagates its omissions into everything built from it **Claim** (one sentence, Courtney's voice): When a ruleset is adopted wholesale by agents building new projects, whatever the ruleset leaves out becomes a systematic gap across every project that uses it, which makes skill review higher-leverage than project review. **Evidence pointer**: [[#H2]] and the absent accessibility rules **Scope & conditions**: Holds where the skill is adopted as a complete guide rather than supplemented — which is the normal case, since adopters cannot know what is missing. Weakens where adopters have independent expertise in the omitted area. The practical consequence: skills should declare scope and known gaps, and fixing a skill is worth more than fixing many projects. **Links** (≥1 with annotation): - [[Agent-skills-as-dependencies]] — because extends - [[Accessibility-as-default-not-addition]] — because applies-in accessibility practice - [[Verifiability-bounds-achievable-quality]] — because contrasts on where quality gets decided <!-- atomicity: 1 idea ✓ --> ### ✏️ Fleeting Queue - [F1] Directly relevant to Outpost — the offline-first caching rules, the `pwa-install-prompt` extraction, and the notch/safe-area handling are all liftable into my own PWA composer work. Review Outpost against all seven. — https://ma.ttias.be/pwas-personal-web-apps/ #fleeting #inbox - [F2] The `offline-first-pwa` skill has zero accessibility rules and is published for general adoption. Adding focus management, `4.1.3` status announcements for the update banner, contrast, and touch targets is a small, well-scoped, genuinely high-leverage PR. — #fleeting #share - [F3] Which of my own accumulated CLAUDE.md rules have been validated by enough repetition to promote out of the project into a shared skill? Worth an audit of ~/.claude/. — #fleeting #inbox - [F4] Agent skills are becoming dependencies — they shape output like libraries shape behaviour — and nobody versions, audits, or inventories them. Article seed, and it pairs with the WP Weekly agent-capability-tiers note. — #fleeting #articleseed - [F5] "Auto-deploy if auto-generated tests pass" — same author writes code and tests, so the gate inherits the blind spots. Fine at household scale. Pairs directly with the Theo verification piece. — #fleeting #xref ### → Things 3 (max 2 actions) - [ ] Audit Outpost against the seven offline-first PWA non-negotiables, especially cache-first serving — outpost #things - [ ] Open a PR adding accessibility rules to mattiasgeniar/offline-first-pwa — accessibility #things <!-- deep-read:sections end --> 📄 **Full text:** [[Full Document Contents/Articles/PWAs Personal Web Apps.md|PWAs: Personal Web Apps by Mattias Geniar]] ## Highlights - Over the past few weeks I’ve grown the CLAUDE.md of that repo into a full set of rules that every tool in it follows. I’ve pulled them out into their own repo: [github.com/mattiasgeniar/offline-first-pwa](https://github.com/mattiasgeniar/offline-first-pwa) . ([View Highlight](https://read.readwise.io/read/01m0dakxr70kge9dtwnreznj70)) - Tags: atom/literature/h1 - It’s an agent skill, so you can clone it into `~/.claude/skills/` and have Claude Code apply it to whatever you’re building, or point any other `AGENTS.md`-reading tool at it. It’s also just a checklist you can read. Service worker caching strategy, precaching, in-app update prompts, iOS home screen quirks, safe areas, and how to test any of it. Every rule in there is something I got wrong first. ([View Highlight](https://read.readwise.io/read/01m0dam1pqvygvmszgs4b608zs)) - Tags: atom/literature/h2 - The skill itself is AI-generated, distilled from the CLAUDE.md file that repo runs on. This post I wrote myself. ([View Highlight](https://read.readwise.io/read/01m0dam5hqh1yfzwm2ffcz5nfs)) - Tags: atom/literature/h3