Overview collection

182 Technical articles

• NutsNews App Store Privacy Policy UpdateThis update strengthens the /privacy page for App Store review by matching the current iOS app behavior more clearly.
• NutsNews Privacy Policy UpdateThis update adds a public privacy policy page for App Store submission and links it from the fixed site footer.
• NutsNews Production Infinite Scroll FixThis update fixes the homepage infinite scroll behavior where local development loads more stories, but production stops after the first set of cards.
• NutsNews final CI fixThis patch fixes two CI/local issues after the home/contact update:
• NutsNews Home Button + Contact Text UpdateThis bundle updates:
• NutsNews Web Offline E2E FixThis patch updates the mocked public web flow test so it no longer assumes the mock article title is globally unique on the homepage.
• NutsNews Worker Offline E2E FixThis update fixes the Worker Offline E2E Regression after the summary translation language set expanded to:
• NutsNews GitHub Actions UpdateThis bundle adds the missing GitHub Actions and support scripts for NutsNews.
• NutsNews Hydration Language FixThis update fixes a homepage hydration mismatch caused by the hero tagline reading localStorage during the first client render.
• NutsNews IssueThis update implements issue #116 with a new admin free-tier guardrails dashboard and adds a fully mocked public web end-to-end regression test.
• NutsNews Platform Improvement Issues BundleThis bundle adds a script that creates a platform-grade backlog of GitHub issues for NutsNews.
• NutsNews Cloudflare Turnstile UpdateThis bundle adds Cloudflare Turnstile to the NutsNews contact form.
• NutsNews Worker Acceptance FixThis update fixes a Worker path that could make new accepted stories fail to show up after the translation/KV/Redis updates.
• Archived Root-Level Update NotesThis folder contains one-off update/fix README files that were previously left in the repository root by generated code-update bundles.
• NutsNews Web Offline E2E Footer Contact Locator FixThis update fixes another Playwright strict-mode locator in the fully offline Web E2E regression test.
• NutsNews Web Offline E2E Footer Navigation Wait FixThis update makes the offline web E2E footer navigation checks less flaky on GitHub Actions.
• NutsNews Web Offline E2E Page Locator FixThis update tightens the offline Web E2E checks for About, Privacy, and Contact pages.
• NutsNews Web Offline E2E Search Strict Locator FixThis update fixes the offline web E2E regression after the settings-locator fix by scoping the search submit and close buttons to the search dialog.
• NutsNews Web Offline E2E Settings CI FixThis update stabilizes the fully mocked Web Offline E2E regression in GitHub Actions.
• NutsNews Web Offline E2E Startup FixThis fixes Error: spawn npm ENOENT in scripts/web_offline_e2e_regression.mjs.
• axe Accessibility CI with Playwrightaxe Accessibility CI is the automated accessibility safety net for the NutsNews web app.
• Cloudflare Cache ObservabilityIssue #91 adds a dedicated cache observability layer for NutsNews public routes.
• Cloudflare KV Worker State for NutsNewsThis update adds an optional Cloudflare Workers KV binding named NUTSNEWS_KV to the RSS shard Workers.
• CodeQL Security ScanNutsNews uses GitHub CodeQL for security scanning.
• Controller and Shard OperationsArchitecture status: this document describes the current legacy Cloudflare
• NutsNews Database ResiliencyLast verified: 2026-07-26
• Dependency Update RoutineThis document defines the repeatable dependency update process for NutsNews.
• Deployment ChecklistThis checklist explains how to safely deploy NutsNews across the web app, Worker shards, controller Worker, Cloudflare cache, and post-deploy verification.
• NutsNews Free-Tier GuardrailsIssue #116 adds a dedicated admin dashboard at /admin/guardrails for cost forecasting and free-tier risk monitoring.
• NutsNews GitHub Actions AutomationThis update adds the missing GitHub Actions around build safety, operations, backups, feed quality, translations, image coverage, links, sitemap/robots, and release notes.
• Grafana Cloud Backup MonitoringNutsNews uses Grafana Cloud Explore and Prometheus/PromQL to inspect home-server backup metrics before turning them into a dashboard.
• Home Server Local AI ProviderNutsNews can now review candidate RSS articles using a home-server local AI stack instead of sending every candidate directly to OpenAI.
• NutsNews Incident Response PolicyIssue: https://github.com/ramideltoro/nutsnews/issues/111
• Card Date Source Bottom ReadmeMoves the article date and source to the bottom row of each article card, with date on the bottom-left and source on the bottom-right.
• NutsNews iOS Cache UpdateThis bundle adds a 15-minute on-device disk cache for /api/articles responses.
• NutsNews iOS Card Button Glow UpdateThis update makes the card action buttons glow when tapped.
• NutsNews iOS Detail Thumbnail Crop UpdateThis bundle updates the article detail screen opened from Read Story.
• NutsNews iOS Hamburger Menu PatchThis patch moves the main header actions into one hamburger menu on the top left.
• NutsNews iOS Image Resolution Troubleshooting UpdateThis bundle shows each article thumbnail's pixel resolution directly on the card image.
• NutsNews iOS iPad Landscape Compact Card UpdateThis update changes article cards only on iPad in landscape mode.
• NutsNews iOS iPad Landscape Story No-Scroll UpdateThis update changes the story page only on iPad in landscape mode.
• NutsNews iOS iPad Original Story True Fullscreen FixThis update fixes the iPad original-story browser still appearing as a small centered popup.
• NutsNews iOS iPad Settings Fullscreen UpdateThis update changes settings presentation only on iPad.
• NutsNews iOS iPad Story Fullscreen UpdateThis update changes story presentation only on iPad.
• NutsNews iOS Like Glow UpdateThis bundle updates the article card like interaction.
• NutsNews iOS Like Toggle UpdateThis update makes the Like buttons toggle liked state.
• NutsNews iOS New Themes UpdateThis update adds three new selectable app themes to NutsNews iOS and wires them into the existing theme system.
• NutsNews iOS Persistent Likes UpdateThis update makes liked stories persist and stay synchronized between the home feed and story page.
• NutsNews iOS Remove Story Top Share UpdateThis bundle removes the top-right share icon from the article story page toolbar.
• NutsNews iOS Safari Delegate Build FixThis fixes the Swift build error in SafariView.swift.
• NutsNews iOS — Saved Stories Thumbnail Ratio PatchThis patch updates the Saved Stories screen so saved-story thumbnails render with the same stable 3:2 thumbnail frame used by the home feed cards.
• NutsNews iOS Scroll Fade UpdateThis bundle updates the home feed so article cards fade, scale slightly, and lift into place while scrolling.
• NutsNews iOS Scroll Twitch FixThis bundle fixes the scroll twitch caused by thumbnail cards changing height after async image metadata checks completed.
• NutsNews iOS Search Button Next to Settings PatchThis UI-only patch moves the full archive search icon from the right side of the home header to the left side, directly next to the Settings gear.
• NutsNews iOS Settings Button Glow UpdateThis update makes the home-page Settings button glow when tapped.
• NutsNews iOS Settings Text CleanupThis bundle cleans up the settings UI text.
• NutsNews iOS — Story Notes Stable Key PatchThis patch fixes story notes so a note is attached to the same article no matter where the article is opened from.
• NutsNews iOS Story Page Glow + Like UpdateThis update adds more story-page interactions and glow feedback.
• NutsNews iOS Theme Transition Glow UpdateThis update adds a theme-change glow animation on the Theme settings page.
• NutsNews iOS Thumbnail Crop UpdateThis bundle removes the troubleshooting image-resolution badge and changes wide thumbnails to display in a cropped 3:2 image area.
• Google Lighthouse CI OnboardingGoogle Lighthouse CI is the NutsNews automated quality check for public web pages.
• Local AI Deployment LockNutsNews Worker shards must use the home-server local AI provider first.
• Migration Release GateThis runbook defines the database release contract introduced by nutsnews#109.
• NutsNews Backend Backup And Restore BaselineThis documents the backup and restore policy for ramideltoro/nutsnews-backend before any production backend state is stored on 65.75.201.18.
• NutsNews Backend Cleanup MaintenanceBackend issue ramideltoro/nutsnews-backend#41 adds fixed-purpose disk and
• NutsNews Backend Health ReportNutsNews now has a daily backend checkup. It looks at the backend server, writes down what looks healthy or needs attention, and can email the report without changing the server.
• NutsNews Backend OpenAI Maintenance RobotThis page documents the daily maintenance robot owned by
• NutsNews Backend PostgreSQL Primary And Supabase Hot StandbyArchitecture status: backend PostgreSQL is the production read/write primary.
• NutsNews Backend Recovery WorkflowsThis page documents the fixed-purpose recovery workflows for
• NutsNews Backend Security BaselineThis tracks backend host security desired state for ramideltoro/nutsnews-backend and 65.75.201.18.
• NutsNews Backend Service BaselineThis documents the read-only service baseline attestation for ramideltoro/nutsnews-backend and 65.75.201.18.
• NutsNews Cache Safety UpdateThis update prevents stale browser-cached page shells from causing UI problems immediately after a deploy.
• NutsNews Supabase Backup AutomationThis runbook documents the production Supabase backup automation for NutsNews.
• NutsNews Dual-Target Web DeploymentThis guide defines how one reviewed commit from ramideltoro/nutsnews is
• NutsNews Grafana Cloud ObservabilityArchitecture status: Grafana Cloud resources are centralized in
• NutsNews Infra Operations PlatformThis explains how the NutsNews infrastructure repo is supposed to make one small VPS behave like a boringly reliable production platform, which is the dream. Boring infrastructure…
• NutsNews Operations Portal v1This explains the first real Ops Portal layer for the NutsNews VPS: a read-only amber dashboard, a local status collector, opt-in email alerts/reports, encrypted backup status, ma…
• NutsNews Protected Ansible Apply WorkflowThis explains the first protected GitHub Actions workflow that can run the Ansible VPS baseline against vps.nutsnews.com. It is a production mutation path, so it wears a seatbelt,…
• NutsNews Release PipelineCurrent as of July 18, 2026.
• NutsNews Supabase Standby Restricted ProbeThis is the shared operations guide for proving Supabase standby credential and
• Vercel-to-VPS environment synchronizationNutsNews keeps one source of truth with two deployment targets:
• NutsNews VPS Ansible BootstrapThis explains the first Ansible baseline for the primary NutsNews VPS. It is the careful part before the flashy part: make the server boring, reachable, patched, logged, and recov…
• NutsNews VPS BackupsThis is the setup and operations guide for encrypted VPS backups to OneDrive.
• NutsNews VPS Disaster RecoveryThis is the rebuild runbook for moving NutsNews to another VPS provider after a serious host failure or provider migration.
• NutsNews VPS Health Endpoint NetworkThis document defines the intended production network boundary for the
• NutsNews VPS MaintenanceThis is the canonical operator guide for routine VPS package maintenance and
• VPS production runtime 500 incidentThe VPS website failed because its deployment settings and database were not
• NutsNews VPS RestoreThis is the restore runbook for encrypted VPS restic backups.
• NutsNews VPS Runtime Environment IsolationNutsNews has separate production and staging runtime identities. Production
• NutsNews VPS Service FoundationThis explains the next layer in the NutsNews VPS platform: Docker Engine, Docker Compose, the /opt/nutsnews runtime layout, a small zram fallback, Caddy, public infrastructure hea…
• NutsNews VPS Staging Access And Credential BoundaryStatus: complete. Cloudflare and VPS staging infrastructure are live, the
• NutsNews VPS Same-Host Staging Capacity BudgetThe production VPS can host a tightly bounded staging application, but this
• NutsNews Immutable Staging DeploymentThe Deploy Verified NutsNews Staging Candidate workflow in
• NutsNews Worker Local AI LockThe public web repo does not deploy the ingestion Workers. Worker shard deployment lives in ramideltoro/nutsnews-worker.
• NutsNews Worker-Uplift Operation MapThis page links the shared documentation hub to the backend-owned operation map
• NutsNews Worker-Uplift RabbitMQ Capacity And SecurityStatus: approved for ramideltoro/nutsnews-worker#79 on 2026-07-23.
• NutsNews Worker-Uplift RabbitMQ MetricsStatus: backend collection path completed for ramideltoro/nutsnews-worker#87
• NutsNews Worker-Uplift RabbitMQ OperationsStatus: implemented for ramideltoro/nutsnews-worker#84 on 2026-07-23.
• NutsNews Worker-Uplift RabbitMQ ProvisioningStatus: implementation target for ramideltoro/nutsnews-worker#80,
• NutsNews Worker-Uplift RabbitMQ RecoveryStatus: implemented for ramideltoro/nutsnews-worker#83.
• NutsNews Worker-Uplift Service RuntimeStatus: implemented for ramideltoro/nutsnews-worker#85 on 2026-07-23.
• NutsNews Worker-Uplift Shadow RuntimeThis document records the backend-owned shadow runtime for
• NutsNews Worker-Uplift Telemetry ScopeStatus: approved for ramideltoro/nutsnews-worker#144 on 2026-07-23.
• ObservabilityNutsNews is built with observability from the start.
• OperationsThis document explains how NutsNews is operated and maintained.
• Oracle Local AI Provider> **Current production note:** NutsNews currently uses the home-server local AI setup documented in Home Server Local AI Provider. This Oracle document remains as an alternative r…
• PageSpeed Insights for NutsNewsPageSpeed Insights is the manual production performance check for NutsNews after major UI changes.
• Performance and ResiliencyNutsNews is designed to stay fast, reliable, and inexpensive as traffic and RSS volume grow.
• NutsNews Platform Improvement Issue BacklogThis backlog was generated from a scan of the NutsNews main branch plus the current open GitHub Issues page. It avoids recreating already-visible issues such as database planning,…
• Production Readiness DashboardNutsNews has an admin-only production readiness scorecard at /admin/readiness.
• Project OverviewNutsNews is a calm, mobile-first positive news platform powered by automation, AI curation, serverless infrastructure, CDN caching, centralized observability, and a private admin …
• NutsNews API Compatibility ContractsNutsNews treats its deployed response behavior as a compatibility contract. The iOS app consumes the public article and search APIs, so a field removal, type change, status change…
• Public API PlanRelated issue: ramideltoro/nutsnews#39
• Public Feed Snapshot and Edge FallbackArchitecture status: Supabase public_feed_snapshot remains the current
• NutsNews DocumentationWelcome to the NutsNews documentation hub.
• Release Notes WorkflowRelated issue: ramideltoro/nutsnews#32
• NutsNews issueGenerated on 2026-07-20 for ramideltoro/nutsnews#282.
• Runtime Feature FlagsNutsNews uses a small Supabase-backed runtime flag table to pause two documented behaviors without redeploying the Next.js app or Cloudflare Worker.
• Security CI ScansNutsNews uses GitHub Actions and repository security settings to catch dependency, workflow, secret, and supply-chain risks before release.
• Security HardeningIssue #106 adds a focused security pass for the NutsNews web app.
• NutsNews Service Level ObjectivesIssue: https://github.com/ramideltoro/nutsnews/issues/89
• Snyk Security ScanNutsNews uses Snyk as an extra dependency scanner alongside Dependabot and CodeQL.
• Supabase Restore ProcedureThis runbook explains how to restore the NutsNews Supabase database after a crash, bad deploy, hacked data, bad migration, or accidental delete.
• Supabase RLS Regression TestsNutsNews now has a local database check that makes sure public readers can only see the safe news data, while private tables and write actions stay locked.
• Troubleshooting GuideThis guide helps diagnose common production problems in NutsNews from one place.
• Accepted articles require translations before publishingThis update makes the Worker treat accepted articles as translation_pending until every enabled summary language has a saved row in article_summaries.
• GitHub Actions SHA Pinning and Vercel Staged PromotionNutsNews now locks GitHub Actions to exact code snapshots and keeps Vercel
• Article translation backfill issueThis update documents the production article summary translation backfill completed for ramideltoro/nutsnews#282 on 2026-07-20.
• Update: axe Playwright Accessibility CIThis update adds automated accessibility regression checks for the NutsNews web app using Playwright and @axe-core/playwright.
• Backend translation publish guardThis update documents the backend compatibility API guard for ramideltoro/nutsnews-backend#263.
• NutsNews backfill continue-on-error updateThis update changes scripts/backfill_article_summaries.mjs so a bad translation row does not stop the whole backfill.
• Backfill repeat fixThis update fixes two translation backfill problems:
• Cloudflare Production Cache Purge UpdateThis update adds automatic full Cloudflare cache purge after a successful production deployment.
• Edge Feed Snapshot Admin Health UpdateThis update improves the /admin/edge-snapshot dashboard so it can explain Worker fallback problems instead of only showing a generic HTTP error.
• Edge Feed Snapshot Health UpdateThis update makes the Cloudflare Worker edge snapshot fallback easier to diagnose and harder to deploy incorrectly.
• Feed Ingestion Regression TestsIssue #211 adds fixture-driven regression coverage for feed ingestion contracts in the app repository.
• NutsNews Footer Search Menu PatchThis is a UI-only patch that keeps the existing /api/search backend but moves search out of the home feed.
• NutsNews Footer Search Thumbnail PatchThis is a small UI-only patch for the existing centered footer search modal.
• NutsNews full archive home search updateThis update keeps full archive search in the backend, but changes the website UX so search happens directly on the home page instead of sending visitors to a separate /search page.
• Full Archive Search UpdateThis bundle adds backend-supported archive search to NutsNews web.
• Greek language hydration fixThis update fixes a React hydration warning that appeared after selecting Greek and reloading the home page.
• Greek Language Hydration Lint FixThis update keeps the ThemeSwitcher hydration-safe without violating the React hooks lint rule.
• NutsNews Home Search Box Layout PatchThis is a UI-only patch for the full archive search box on the home page.
• Issue 104 Edge Feed Snapshot Fallback UpdateThis update implements GitHub issue #104.
• Lighthouse CI Documentation UpdateThis update documents the correct Google Lighthouse CI onboarding flow for NutsNews.
• NutsNews local-first AI fallback updateThis update makes the Worker support a full local-first AI flow:
• NutsNews home-server translation fallback updateThis update changes new Worker-generated article translations so the home server is tried before OpenAI.
• VPS and Vercel Production Lockstep UpdateProduction deployments now stay in lockstep: VPS and Vercel Production must both pass on the same locked release identity, and deployment failure on either side triggers the fixed…
• Mandatory NutsNews Docs PolicyThis update documents the REQUIRED policy that every NutsNews change MUST update this documentation repository.
• NutsNews3 translation diagnostics query hotfixThis hotfix updates the diagnostic scripts to be safer with large audit windows.
• NutsNews3 Translation Diagnostics UpdateThis bundle is intended for the clean clone at:
• Production Promotion Timing UpdateProduction release promotion now records timing for each major phase and reports
• Publishing Visibility Cache And DB Alignment UpdateNew stories were saved, but the front page was showing an old copy. We cleared the website caches and checked that the Worker and website are using the same backend database path …
• NutsNews Qwen Summary Length UpdateThis update makes accepted Qwen/Ollama AI article summaries return in the 240-300 character range.
• NutsNews Settings Language Polish UpdateThis is a small follow-up to the settings menu update.
• NutsNews Settings Menu UpdateThis update reorganizes the footer Settings panel into a two-level menu.
• Staging Bundle Marker Refresh UpdateThe VPS staging deploy bundle now stays tied to the infra commit that production
• Staging-Qualified Production Promotion UpdateCurrent note: this file describes the earlier July 2026 staging-qualified VPS
• Swiss German, German, and Greek Language UpdateThis update adds three NutsNews languages across the web UI and article translation pipeline:
• NutsNews Translation All-in-One UpdateThis replaces the earlier translation recovery/diagnostics bundles with one cleaner update.
• NutsNews Translation Diagnostics UpdateThis update is intentionally diagnostic-first. It does not assume that missing translated cards should be blindly backfilled before you understand why they were missed.
• NutsNews Translation Recovery Guard UpdateThis update fixes the failure mode where a newly accepted article can appear in English before French/Japanese summary rows exist.
• NutsNews Local AI Summary Length UpdateThis update fixes the local AI review path so accepted article summaries stop coming back in the old short 150-160 character style.
• UptimeRobot Documentation UpdateThis update adds a dedicated UptimeRobot onboarding guide for NutsNews.
• Vercel Production Build Shell Env, Remote Staging, and Bypass Smoke FixThe production deploy robot failed because it could not find the shell program
• Vercel Promotion Rollback Guard UpdateInfra promotion now locates Vercel production deploy runs by source commit
• VPS Health Build Target Contract UpdateThe shared VPS image now treats /healthz as a cached build identity surface.
• VPS Release Smoke Health Target Fix> Superseded note: the current shared VPS image build contract uses /healthz
• Worker local-first AI and diagnostic logging updateThis update makes Cloudflare Workers try local AI first for article review/classification and summary translation when LOCAL_AI_URL + LOCAL_AI_API_KEY are configured. If local AI …
• Worker Summary Translation Subrequest Budget UpdateThe Worker was trying too many summary translation recovery tasks in one invocation. With 20 RSS feed fetches plus dozens of OpenAI/local AI translation calls and Supabase writes,…
• Worker summary translation task limit fixThis update makes SUMMARY_TRANSLATION_LIMIT control the number of translation tasks per Worker invocation directly.
• Worker Translation Diagnostic Samples UpdateThis update makes Worker translation failures easier to debug.
• NutsNews Worker Upstash Redis UpdateThis update adds optional Upstash Redis support to the Cloudflare Worker shard refresh flow.
• UptimeRobot OnboardingThis guide explains how to onboard NutsNews to UptimeRobot without accidentally triggering article refresh work.
• Vercel Preview Smoke TestThis regression runs against the real Vercel Preview deployment created for a pull request.
• VPS Alert Email PolicyThis runbook defines how the NutsNews Ops Portal turns read-only VPS status into useful email alerts without turning changing measurements into inbox noise.
• NutsNews Web Offline E2E Regression TestThis test runs the real Next.js web app against mocked Supabase/PostgREST, Turnstile, and Resend services.
• Web Public Reader Smoke TestNutsNews uses a dedicated Playwright smoke test to verify critical public reader flows with offline mock services.
• Web Visual Regression TestsNutsNews uses Playwright screenshot snapshots to catch public layout regressions that smoke, accessibility, and API tests can miss.
• Worker Backpressure and Lock SafetyArchitecture status: this document describes legacy Cloudflare Worker
• Worker GitHub Actions PipelineThis repo now has one guarded Worker pipeline for pull requests and post-merge Cloudflare deploys.
• NutsNews Worker Fully Offline E2E Regression TestThis test runs the real Cloudflare Worker locally and mocks every external service it normally depends on.