readplace.com

Save articles and web pages to a Readplace reading list and read them back as clean, distraction-free text or an AI TL;DR. Use when a user asks to save a link for later, build a reading list, or pull up something they saved to Readplace.

Web adapter conventions for the application domain. Use when working with HTML templates, CSS styles, client-side JavaScript, or SSR patterns. Triggers on changes to .css, .html, .view.html, .client.js files.

Infrastructure Design

Hypermedia contract between Readplace's hutch server and every client that consumes it — the chrome and firefox extensions, the iOS app, the MCP server, and future clients. Use when adding, renaming, or removing an API capability a client consumes, when the server emits or parses Siren responses, or when any client's navigation/action flow changes.

E2E testing conventions using Playwright and the HATEOAS-based test framework. Use when working with E2E tests, files in e2e/ directories, *.e2e*.ts files, or when test errors mention Playwright, HATEOASClient, NavigationHandler, PageAction, or locator timeouts.

Software design and testing conventions that support testability. Use when writing tests, designing testable code, working with dependency injection, or when test coverage issues arise.

How to add, remove, or edit a Readplace client (browser extension, native app, AI assistant) or its per-client data. Use when the set of supported clients changes — "add an Android app", "ship a Safari extension", "add Perplexity", "remove a client" — or when editing a client's display name, group, store URL, or OAuth identity.

When a code comment may exist and the human-approval gate for adding or keeping one. Use when adding, editing, retaining, or removing any code comment (`//`, `/* */`, `/** */`, `<!-- -->`, `{{!-- --}}`, `#`), when reviewing a diff that touches comments, or when asked to clean up / trim / de-stale / de-time-bind comments. This is the single source of truth for comment policy across the repo.

Blog post authoring conventions. Use when creating, editing, moving, or troubleshooting blog posts. Triggers on blog content work, markdown files intended for the blog, or questions about the /blog route.

Root-cause methodology for distributed pipelines (command → event → handler chains over Lambda + EventBridge + SQS), with the article crawl system as the primary application. Use when a state-machine row is stuck non-terminal (e.g. `crawlStatus='pending'`, `summaryStatus='pending'`), when a canary or SLO times out with the row never transitioning, when one entry point works but another doesn't for the same input (e.g. `/view` vs `/admin/recrawl`), when investigating a multi-Lambda async chain where the first handler logs a clean success, or before bumping Lambda timeouts / SQS visibility / `maxReceiveCount` to "give it more room".

Format git commit messages following Conventional Commits specification. Use when the user asks to commit, create a commit, stage and commit, write a commit message, or mentions "git commit". Applies to all commits in this monorepo.

Guidelines for writing AI agent documentation (skills, CLAUDE.md, README files). Use when creating or updating documentation that will be consumed by AI agents to avoid context window pollution.