diff --git a/.claude/skills/hotwire-docs/SKILL.md b/.claude/skills/hotwire-docs/SKILL.md new file mode 100644 index 00000000..91923696 --- /dev/null +++ b/.claude/skills/hotwire-docs/SKILL.md @@ -0,0 +1,50 @@ +--- +name: hotwire-docs +description: Use when asked about Turbo (Turbo Drive, Turbo Frames, Turbo Streams, ActionCable-broadcasted streams) or Stimulus (controllers, targets, actions, values, outlets) — including "how do I do X with Turbo/Stimulus", debugging a Turbo Stream broadcast, or wiring up a Stimulus controller. Always consult the official Hotwire docs rather than answering from memory alone, since Turbo/Stimulus APIs and idioms have shifted across versions and this project has no SPA framework — all interactivity goes through Hotwire. +--- + +# Hotwire (Turbo + Stimulus) documentation lookup + +This project (HostedGPT) uses Hotwire (Turbo + Stimulus) for all frontend interactivity — no SPA +framework. Streaming chat updates arrive via Turbo Stream broadcasts over ActionCable, rendered +from server-side partials (see `app/views/messages/_message.html.erb` and `CLAUDE.md`). Trained +knowledge about Turbo/Stimulus can be stale or blend behavior across versions — check the official +docs before relying on specifics. + +## Sources + +- **Turbo Handbook & reference**: https://turbo.hotwired.dev + - Overview: https://turbo.hotwired.dev/handbook/introduction + - Drive: https://turbo.hotwired.dev/handbook/drive + - Frames: https://turbo.hotwired.dev/handbook/frames + - Streams: https://turbo.hotwired.dev/handbook/streams + - Reference (attributes, actions, events): https://turbo.hotwired.dev/reference/attributes +- **Stimulus Handbook & reference**: https://stimulus.hotwired.dev + - Overview: https://stimulus.hotwired.dev/handbook/introduction + - Controllers/targets/actions/values/outlets: https://stimulus.hotwired.dev/handbook/hello-stimulus + - Reference: https://stimulus.hotwired.dev/reference/controllers + +## When to look things up + +Use `WebFetch` against the sources above when: +- You need the exact Turbo Stream action list/syntax (`append`, `prepend`, `replace`, `update`, + `remove`, `before`, `after`, `refresh`) or how targeting (`target=`/`targets=`) works. +- You're unsure how Turbo Frame lazy-loading, `data-turbo-*` attributes, or navigation + interception behaves. +- You're writing or debugging a Stimulus controller and need exact lifecycle callback names, + target/value/outlet declaration syntax, or action descriptor syntax (`event->controller#method`). +- The user asks "how do I do X with Turbo/Stimulus" and it's not already answered by this + project's own patterns in `CLAUDE.md`. + +Skip the lookup for questions answered faster by reading this codebase directly — e.g. how this +app's own streaming job builds and broadcasts updates is answered by +`app/services/ai_backend/`, `GetNextAIMessageJob`, and the `_message.html.erb` partials, not the +Hotwire docs. + +## Applying this project's conventions + +The Hotwire docs describe the general framework; this project's own streaming architecture (see +`CLAUDE.md`'s "Message generation flow") governs how it's actually used here — e.g. partial +updates are broadcast roughly every 100ms during streaming and only persisted once the stream +finishes. Confirm Turbo/Stimulus behavior against the docs, but follow this repo's existing +patterns for where controllers and broadcasts live. diff --git a/.claude/skills/rails-docs/SKILL.md b/.claude/skills/rails-docs/SKILL.md new file mode 100644 index 00000000..c6beafb4 --- /dev/null +++ b/.claude/skills/rails-docs/SKILL.md @@ -0,0 +1,50 @@ +--- +name: rails-docs +description: Use when asked about any Rails-specific topic — ActiveRecord, routing, controllers, views, mailers, jobs, Action Cable, Action Text, Active Storage, migrations, validations, callbacks, associations, caching, security, or Rails internals — including "how do I do X in Rails", debugging Rails behavior, or checking whether an API/option still exists or changed in Rails 8. Always consult the official guides and API docs rather than answering from memory alone, since trained knowledge can be stale or wrong about version-specific details, and this project pins Rails 8.0. +--- + +# Rails official documentation lookup + +This project (HostedGPT) runs Rails 8.0, per the project's `CLAUDE.md`. Trained knowledge about +Rails APIs can be outdated, mixed across versions, or simply wrong on specifics (option names, +defaults, deprecations, callback ordering, etc.). Before answering a Rails-specific question or +relying on a Rails API's exact behavior, check the official docs rather than guessing. + +## Sources + +- **Guides** (concepts, how-tos, conventions): https://guides.rubyonrails.org + - Version-pinned guides are available at `https://guides.rubyonrails.org/v8.0/.html` + if you need to confirm you're reading the Rails 8.0 version rather than edge/main. +- **API reference** (exact method signatures, options, source): https://api.rubyonrails.org + - Version-pinned API docs: `https://api.rubyonrails.org/v8.0/` + +## When to look things up + +Use `WebFetch` against the sources above when: +- The question is about a specific Rails API's options, defaults, or behavior (e.g. "does + `has_many` support `:strict_loading`?", "what does `config.active_record.encryption` need?"). +- You're unsure whether something changed between Rails versions (deprecated, renamed, new in 8.0). +- You're about to write code that depends on exact method signatures, callback ordering, or + routing/DSL syntax you're not fully certain of. +- The user asks a "how do I do X in Rails" question that isn't already answered by this project's + own conventions in `CLAUDE.md`. + +Skip the lookup for things you can verify faster by reading this codebase directly (e.g. "how does +this app handle streaming?" — that's answered by `app/services/ai_backend/`, not the guides), or for +very basic Ruby/Rails knowledge you're confident hasn't changed across versions. + +## How to look things up + +1. Identify the right guide or API page (e.g. Active Record Associations, Action Mailer Basics). +2. Fetch it with `WebFetch`, preferring the `/v8.0/` pinned URL when version accuracy matters. +3. If the guide doesn't have the exact method signature, cross-check `api.rubyonrails.org` for the + precise method/class documentation. +4. Prefer the official source over Stack Overflow, blog posts, or other secondary sources when they + conflict. + +## Applying this project's conventions + +Official Rails docs describe what's *possible*; they don't override this project's own patterns. +After confirming Rails behavior, still follow `CLAUDE.md`'s conventions — e.g. provider logic goes +in `app/services/ai_backend/`, soft deletion via `deleted_at` + `not_deleted` scopes, feature flags +via `Feature.?`/`Setting.`, and don't hard-code model lists (`models.yml` instead). diff --git a/.claude/skills/tailwind-docs/SKILL.md b/.claude/skills/tailwind-docs/SKILL.md new file mode 100644 index 00000000..358c1ab0 --- /dev/null +++ b/.claude/skills/tailwind-docs/SKILL.md @@ -0,0 +1,37 @@ +--- +name: tailwind-docs +description: Use when asked about Tailwind CSS — utility classes, responsive/state variants, `tailwind.config.js` theme customization, `@apply`, dark mode, or "how do I style X with Tailwind". Always consult the official Tailwind docs rather than answering from memory alone, since utility class names and config syntax have changed between Tailwind v3 and v4, and this project pins Tailwind v3 (via `tailwindcss-rails` gem, config in `config/tailwind.config.js`). +--- + +# Tailwind CSS documentation lookup + +This project (HostedGPT) styles its Hotwire-rendered views with Tailwind CSS via the +`tailwindcss-rails` gem (`~> 2.7`, see `Gemfile`), which bundles **Tailwind CSS v3** — it still +uses a JS config file at `config/tailwind.config.js`, not Tailwind v4's CSS-first `@theme` +config. This matters because Tailwind v4 renamed/changed a number of utilities and the config +approach entirely, so answers pulled from memory can silently mix v3 and v4 syntax. + +## Sources + +- **Docs**: https://tailwindcss.com/docs + - The current site defaults to the latest major version's docs. If a page's syntax looks like + v4 (e.g. CSS `@import "tailwindcss"` / `@theme` blocks, no `tailwind.config.js`), that's a + mismatch with this project — look for the v3 equivalent or verify against the + `config/tailwind.config.js` file already in this repo, which follows v3 conventions. + - The docs site also has a version switcher; prefer the v3 docs when available/linked from a + page (URLs are sometimes of the form `https://v3.tailwindcss.com/docs/...`). + +## When to look things up + +Use `WebFetch` when: +- You need the exact utility class name/values for something (spacing scale, color palette, + arbitrary value syntax) rather than guessing. +- You're customizing `config/tailwind.config.js` (theme extension, plugins, safelist) and need + the v3 config shape. +- You're unsure whether a utility/variant exists in v3 (e.g. some newer utilities and variants + were only added in v4). + +Skip the lookup for basic, version-stable utilities you're confident about (e.g. `flex`, +`items-center`, `p-4`), or when the existing codebase already shows the exact class/pattern to +follow — check `app/views/` and `config/tailwind.config.js` for this project's own conventions +first.