product_tours 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82d70df0c0b3463d2b4e49de5d2d8736c1ef50ab732a86bca87d5fcf2ebe0b51
-  data.tar.gz: 2e010ecadc7381f7176f6525cddc4ed93719dc07528fd4fb17d8c63852abcc24
+  metadata.gz: fab25758d2c1f8d2c5671555ddfcc04a1c473c60271635ec1e1c191bf9791718
+  data.tar.gz: 42217e9e5f0f89d25c5bebafb93ad3918e77933707d98cd4d3277f9cc0e3920e
 SHA512:
-  metadata.gz: f89e331dd2c34ffb12821a5f9159abc39c8f21bd78c6577048cdccf9895bed7eab76048a165234c8dd612f9c22a959440fc5d4d644eaa36807c3c6173a12e8d0
-  data.tar.gz: 3a34a6f113643ba9076c69805e586ca073187124de304f51ef6ebf353b9baba42c3f8c7c0f4a59e8118e9044185adc36bc79b93f4f01334a222336b7eca2c537
+  metadata.gz: 3f2943f106b77da806858a18c719bd63311ad744b1fe08f637a747cf4f0f6dddb89d5399afe53d121acd6bb81da0b9db5cf560c5a307de39d45fe1440c6adc0f
+  data.tar.gz: 75b8e54316db23fecbe7ab4398993afd616893bd8d2bd75e3c4bf0b0c834b65e29f6a6d97ff0d2302736e3067fe2952509677def0bc2abb607a167f0b98e375c

data/AGENTS.md

@@ -0,0 +1,149 @@
+# AGENTS.md
+
+Instructions for coding agents. Two audiences:
+
+- **[Installing product_tours into a Rails app](#installing-into-a-rails-app)** — you are working in a host app and were asked to add product tours, onboarding guides, or video tutorials.
+- **[Working on the gem itself](#working-on-the-gem-itself)** — you are working in this repository.
+
+Requirements: Ruby >= 3.2, Rails >= 7.1. Active Storage only for uploaded videos, Action Text only for rich descriptions — both optional and both degrade rather than raise.
+
+If you are in a host app and this file is not in front of you, it ships inside the gem: `cat "$(bundle show product_tours)/AGENTS.md"`.
+
+---
+
+## Installing into a Rails app
+
+### 1. Install
+
+```bash
+bundle add product_tours
+bin/rails generate product_tours:install
+bin/rails db:migrate
+```
+
+The generator writes `config/initializers/product_tours.rb`, one migration (`product_tours_posts`), and `mount_product_tours at: "/product_tours"` into `config/routes.rb`. **In development the migration also inserts working demo tutorials**, so the modal has something to open before anyone has written content. Read the initializer it wrote — it is the source of truth over any summary of it, including this file.
+
+### 2. Wire the three things the generator cannot
+
+**a. The widget tag**, once, in the layout:
+
+```erb
+<%# app/views/layouts/application.html.erb, before </body> %>
+<%= product_tours_tag %>
+```
+
+The helper is injected into ActionView by the engine — no include, no import, no asset pipeline entry.
+
+**b. A trigger**, wherever the tutorial is useful. This is the part that makes it different from a SaaS tour builder: nothing auto-attaches to DOM nodes, you put the button where it belongs.
+
+```erb
+<button data-product-tour="billing_setup">Watch the billing guide</button>
+```
+
+The value is a tutorial **key**, and the key must exist and be **published** or the trigger does nothing.
+
+**c. `authorize_admin` — do this before deploying.** The dashboard at `/product_tours` defaults to **development only**. It fails closed, so shipping without this is not an open dashboard — it is a 403 reading "Forbidden. Set ProductTours.config.authorize_admin to grant access."
+
+```ruby
+config.authorize_admin = ->(request) { request.env["warden"]&.user&.admin? }
+```
+
+> **`enabled` and `authorize_admin` receive the raw `request`, not a controller.** Writing `->(request) { current_user }` is the most common mistake here — that method does not exist in this scope. Resolve the user *from the request*: Warden env, a signed cookie, `Current.user` if middleware already set it.
+
+```ruby
+# Rails 8 built-in auth
+config.authorize_admin = lambda do |request|
+  token = request.cookies["session_token"]
+  Session.find_signed(token)&.user&.admin? || false
+end
+```
+
+### 3. Verify
+
+```bash
+bin/rails routes | grep product_tours     # engine mounted
+bin/rails product_tours:seed_demo         # refresh demo tutorials in every locale
+```
+
+Then in the running app: open `/product_tours`, confirm the demo tutorials are listed, and click a `data-product-tour` button on one of your own pages.
+
+### Tutorials are content, not code
+
+A tutorial is a row in `product_tours_posts`, written and published in the mounted dashboard. **Do not create tutorials from host-app migrations, seeds, or fixtures** — that is not how this gem is meant to be used, and it puts editorial content in schema history. If the app needs sample content, `bin/rails product_tours:seed_demo` is the supported path.
+
+What a tutorial carries: a `key`, a title, an optional rich description, an optional video, and at most one primary action (a URL, or the key of the next tutorial — that link is what makes a walkthrough). Keys must match `/\A[a-z0-9]+(?:[._-][a-z0-9]+)*\z/` — lowercase, digits, and `. _ -` as separators. `Billing Setup` and `billingSetup` are invalid; `billing_setup` and `billing.step-1` are fine. `status` is `draft` or `published`, and the key is unique **per locale**, which is how translations work: one row per language for the same key, with locale fallback at resolve time.
+
+### Video providers
+
+YouTube, Vimeo, Loom, Tella, Voomly, a direct MP4/WebM URL, or an uploaded file (needs Active Storage). Uploaded videos stream through the engine at `/product_tours/media/:id` — not a public blob URL. Do not build your own blob links.
+
+**The engine edits the app's Content Security Policy.** It appends the providers' embed hosts to `frame-src` (or to `default-src` when `frame-src` is unset) in an initializer that runs after the host's own. That is deliberate — an embed silently blocked by CSP is a bad first five minutes — but know it happens, and do not hand-add those `frame-src` entries yourself. If the app sets its CSP somewhere unusual (a middleware, a per-controller override), that is where a blocked embed will come from.
+
+### Lifecycle events
+
+Subscribe in an initializer; there is no callback config to set.
+
+```ruby
+ActiveSupport::Notifications.subscribe("product_tours.completed") do |*, payload|
+  # payload has the tutorial key and request context
+end
+```
+
+Names: `product_tours.viewed`, `product_tours.dismissed`, `product_tours.completed`, and `product_tours.unresolved_trigger` — the last one fires when a `data-product-tour` button names a key that does not resolve. Subscribe to it in development; it turns "my button does nothing" into a log line naming the key.
+
+### Do not
+
+- **Do not copy the widget JavaScript into `app/javascript`, or add a `<script>` tag for it.** `product_tours_tag` renders what is needed and the engine serves the code. There is no build step and nothing for esbuild/importmap/Tailwind to know about.
+- **Do not create or edit tutorials in code** (see above).
+- **Do not add provider hosts to `frame-src` by hand** — the engine already does it.
+- **Do not serve uploaded videos by blob URL** — the gated media route exists so a leaked signed URL cannot hand over your content.
+- **Do not install Active Storage or Action Text "to make it work"** unless the app actually wants uploads or rich text. Both are optional; the gem checks for them (`Post.video_upload_supported?`, `Post.description_supported?`) and simply offers less.
+
+### Configuration
+
+There are five options. That is the whole surface.
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `authorize_admin` | development only | **Who can read and edit tutorials. Set before deploying.** |
+| `enabled` | everyone | Per-request gate for the widget and its endpoints |
+| `admin_layout` | `product_tours/application` | Render the dashboard inside your admin shell |
+| `mount_path` | `"/product_tours"` | Keep in sync with `mount_product_tours at:` |
+| `storage_service` | app default | Active Storage service for uploaded video (a `storage.yml` key) |
+
+26 locales ship with the gem, RTL included.
+
+### Common failure modes
+
+| Symptom | Cause |
+| --- | --- |
+| The trigger button does nothing | No tutorial with that key, or it is still a draft, or `product_tours_tag` is missing from the layout. Subscribe to `product_tours.unresolved_trigger` to see which |
+| `/product_tours` returns 403 "Set ProductTours.config.authorize_admin to grant access" | Exactly what it says: still at the development-only default |
+| Key rejected on save | It must match `/\A[a-z0-9]+(?:[._-][a-z0-9]+)*\z/` — no capitals, no spaces |
+| Video area blank for an embed | CSP. The engine appends provider hosts to `frame-src`; a policy set outside `config.content_security_policy` will not have them |
+| No upload option on the form | Active Storage not installed |
+| No rich-text editor for the description | Action Text not installed |
+| Duplicate-key error when adding a translation | The key is unique per locale — add the translation from the tutorial page rather than creating a second record by hand |
+
+---
+
+## Working on the gem itself
+
+```bash
+bundle exec rake test            # minitest, dummy app under test/dummy
+bundle exec rubocop              # must be clean
+BUNDLE_GEMFILE=gemfiles/rails_7.1.gemfile bundle exec rake test   # 7.1, 7.2, 8.0, 8.1 in gemfiles/
+```
+
+Layout: `app/` controllers, `Post`, dashboard views · `lib/product_tours/` config, widget JS, seeds, engine, CSP patch · `lib/generators/product_tours/install/` the one generator · `config/locales/` 26 locales · `test/` minitest with `test/dummy` as the host app.
+
+Conventions this codebase holds to — follow them rather than the first thing that works:
+
+- **Optional dependencies are checked, never assumed.** `has_rich_text` is declared only `if respond_to?`, `has_one_attached` only `if defined?(::ActiveStorage)`, and the model exposes `description_supported?` / `video_upload_supported?` so views can offer less instead of raising. An app with neither gem must boot and work.
+- **Triggers are explicit.** The gem never guesses at DOM nodes or auto-starts a tour; a host puts `data-product-tour="key"` where it wants it. A trigger naming a key that does not resolve is instrumented, not silently swallowed.
+- **The widget is plain JS served by the engine** — no build step, no framework, no CDN.
+- **Uploaded media streams through the engine's gate**, never a public blob URL.
+- **The CSP patch is additive.** It appends to existing sources and drops `'none'` rather than replacing a host's policy — do not let it start overwriting directives.
+- **The dummy app pins `config.active_job.queue_adapter = :test`.** Do not remove it or let it drift back to the `:async` default. Attaching a video enqueues Active Storage's analysis job, and `:async` runs it on a background thread that checks out its own connection — writes no test transaction covers, landing in the middle of whatever runs next. That is a suite that fails order-dependently in a test which never created a row, and it is miserable to trace back.
+- Every user-facing change bumps `lib/product_tours/version.rb` and adds a `CHANGELOG.md` entry (Keep a Changelog format) that says what it costs, not only what it adds.
+- Commit messages are prose that explains the tradeoff — read `git log` before writing one.

data/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-08-04
+
+- Added `AGENTS.md`: install and integration instructions written for coding
+  agents — that tutorials are content managed in the dashboard rather than
+  created from migrations, the key format, the request-shaped config lambdas,
+  that the engine appends provider hosts to the app's `frame-src`, and the
+  `product_tours.unresolved_trigger` notification that turns "my button does
+  nothing" into a log line. It ships inside the gem, so
+  `cat "$(bundle show product_tours)/AGENTS.md"` works from a host app.
+- The dummy app pins `queue_adapter = :test` for the test suite. Attaching a
+  video enqueues Active Storage's analysis job, and the default `:async` adapter
+  runs it on a background thread with its own database connection — writes no
+  test transaction covers, which is how a suite starts failing order-dependently
+  in a test that never created a row. No effect on the gem itself.
+
+## [0.1.1] - 2026-08-04
+
+- Reworked the README into an installation-first, skimmable product guide that
+  accurately documents walkthroughs, video providers, translations, demo data,
+  configuration, lifecycle events, security, and intentional non-goals.
+- Replaced the implementation-era PRD with a concise contract for the shipped
+  product boundary and current behavior.
+- Added real desktop dashboard, editor, walkthrough, and mobile screenshots from
+  the seeded dummy application.
+
 ## [0.1.0] - 2026-08-03
 
 - Initial Rails engine, post dashboard, modal widget, video providers,
@@ -37,5 +62,6 @@
 - Removed generic tutorial duplication now that translations provide the only
   intentional content-copying workflow.
 
-[Unreleased]: https://github.com/yshmarov/product_tours/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/yshmarov/product_tours/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/yshmarov/product_tours/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/yshmarov/product_tours/releases/tag/v0.1.0

data/README.md

@@ -1,126 +1,203 @@
 # product_tours
 
+[![Gem Version](https://img.shields.io/gem/v/product_tours)](https://rubygems.org/gems/product_tours)
+[![Downloads](https://img.shields.io/gem/dt/product_tours)](https://rubygems.org/gems/product_tours)
 [![CI](https://github.com/yshmarov/product_tours/actions/workflows/ci.yml/badge.svg)](https://github.com/yshmarov/product_tours/actions/workflows/ci.yml)
-[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](MIT-LICENSE)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](MIT-LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/yshmarov/product_tours?style=social)](https://github.com/yshmarov/product_tours/stargazers)
 
-`product_tours` is a self-hosted Rails engine for in-app product tutorials and
-lightweight multi-step walkthroughs. Your app owns the trigger UI; the gem owns
-the tutorial editor, translations, safe video embeds, and modal navigation.
+**Self-hosted product tours and video tutorials for Rails.** Publish one useful
+guide, open it from any button in your app, or link several guides into a
+Next/Back walkthrough. Your content, videos, translations, and lifecycle events
+stay in your Rails application.
 
-Requires Ruby 3.2+ and Rails 7.1+.
+No SaaS account. No third-party script. No visual page builder trying to attach
+a tooltip to a DOM node that changed last Tuesday.
+
+![A multi-step product tour showing an embedded YouTube tutorial with Back and Next controls](docs/screenshots/01-walkthrough.jpg)
 
 ## Install
 
 ```ruby
+# Gemfile
 gem "product_tours"
 ```
 
 ```bash
+bundle install
 bin/rails generate product_tours:install
 bin/rails db:migrate
 ```
 
-The migration automatically creates ready-to-use demo tutorials in development.
-Production databases are never populated with demo content.
-
-Add the widget before `</body>` in your application layout:
-
 ```erb
+<%# app/views/layouts/application.html.erb, before </body> %>
 <%= product_tours_tag %>
 ```
 
-Use any host-owned button, link, or icon as the trigger:
+Put a trigger wherever the tutorial is useful:
 
 ```erb
-<button class="btn btn-primary" data-product-tour="billing_setup">
-  Watch setup guide
-</button>
+<button data-product-tour="billing_setup">Watch the billing guide</button>
 ```
 
-Create and publish `billing_setup` in the dashboard at `/product_tours`. Keys
-are unique per locale. Draft, missing, invalid, or disabled keys open nothing
-and raise in development/test; production reports them through `Rails.error`
-and `product_tours.unresolved_trigger` instrumentation.
-
-### Host-controlled invocation
-
-The host app decides where and when a guide opens. It can use a visible button,
-compose several buttons into its own Help menu, or activate a hidden trigger
-after page load. For example, Rails flash state and a host Stimulus controller
-can open a guide after a redirect:
-
-```erb
-<% if flash[:product_tour].present? %>
-  <button hidden
-          data-controller="product-tour-autoplay"
-          data-product-tour="<%= flash[:product_tour] %>"></button>
-<% end %>
-```
+That's it. Create and publish `billing_setup` at `/product_tours`, then click
+your button.
+
+The generator writes the initializer and migration, mounts the engine, and
+prints copy-ready demo buttons. In development, the migration also creates a
+small set of working tutorials so you can try the modal immediately.
+
+> [!IMPORTANT]
+> The dashboard defaults to **development only**. Set `authorize_admin` before
+> deploying it — see [Configure](#configure).
+
+Ruby >= 3.2 · Rails >= 7.1 · Active Storage only for uploaded videos · Action
+Text only for rich descriptions.
+
+Installing with a coding agent? Point it at [AGENTS.md](AGENTS.md) — the same
+steps in the order an agent needs them, plus the gates it tends to get wrong and
+the things it should not do. It ships inside the gem, so
+`cat "$(bundle show product_tours)/AGENTS.md"` works from any app that bundles it.
+
+## What you get
+
+| | |
+| --- | --- |
+| **Tutorials** | Title, optional rich description, optional video, one clear primary action |
+| **Walkthroughs** | Link any tutorial to another. Next opens it in place; Back uses modal history |
+| **Video** | YouTube, Vimeo, Loom, Tella, Voomly, direct MP4/WebM, or an upload |
+| **Dashboard** | Published/draft tabs, key search, live preview, explicit publish controls |
+| **Translations** | One record per language, created from the tutorial page, with locale fallback |
+| **Demo data** | Provider examples, a complete multi-step walkthrough, draft and missing-key cases |
+| **Events** | `viewed`, `dismissed`, `completed` through `ActiveSupport::Notifications` |
+| **Deps** | Rails only. Plain JS — no Tailwind, Stimulus, importmap, npm, CDN, or build step |
+| **Auth** | Lambdas over the raw request — Devise, Rails 8 auth, anything |
+| **i18n** | 26 bundled languages, including RTL |
+| **Turbo/CSP** | Turbo Drive, nonce-based CSP, and supported iframe origins out of the box |
+
+## The whole flow
+
+1. A developer places `data-product-tour="some_key"` where help belongs.
+2. An admin creates that key, adds text/video, chooses Draft or Published, and
+   decides what the main button does.
+3. A visitor clicks the host app's button. The gem resolves the current locale,
+   opens its own modal, and emits `product_tours.viewed`.
+4. The main action closes, opens an app page, or continues to another tutorial.
+   Linked tutorials stay in the same modal and get a Back button automatically.
+
+| Product-tour dashboard | Tutorial editor |
+| --- | --- |
+| ![The dashboard with published tutorials on the left and a selected YouTube tutorial on the right](docs/screenshots/02-dashboard.jpg) | ![The editor previewing a YouTube URL and choosing another tutorial as the primary action](docs/screenshots/04-editor.jpg) |
+| The default language is the canonical list. Preview, publish, translate, or edit without a deploy. | Paste a supported URL and the preview appears immediately. Choose URL or upload, then one action. |
+
+<img src="docs/screenshots/03-mobile.jpg" alt="The product tutorial modal filling a mobile viewport with a video and primary action" width="390">
+
+On screens up to 480px the modal becomes a full-screen sheet, respects safe
+areas, and follows `visualViewport` while the mobile keyboard is open.
+
+## Why a gem
+
+| | `product_tours` | Hosted tour SaaS |
+| --- | --- | --- |
+| Cost | Free, MIT | Monthly, usually tied to MAU |
+| Where content lives | Your database | The vendor's |
+| Trigger placement | Your Rails views and product logic | A remote visual builder |
+| Videos | Your URLs or Active Storage | Their upload/storage rules |
+| User/account data | Not collected by the gem | Usually synced for targeting |
+| Analytics | Events for the tool you already use | Another dashboard |
+| Frontend | One same-origin plain-JS file | Third-party script and network calls |
+| If you remove it | Delete the helper and mount | Untangle remote campaigns and targeting |
+
+This is intentionally the reliable half of product tours: self-contained
+guidance modals, not DOM-anchored tooltip choreography.
+
+## Build a walkthrough
+
+Every tutorial has one primary action:
+
+| Choice | What visitors get |
+| --- | --- |
+| **Finish and close** | Emits `completed` and closes the modal |
+| **Continue to another tutorial** | Opens that key in the same modal and adds Back history |
+| **Open a page** | Emits `completed`, then follows a relative path or HTTP(S) URL |
+
+Select **Continue to another tutorial** in the editor and pick a tutorial in the
+same language. Draft targets are selectable while you assemble the walkthrough;
+publish the complete chain before exposing its first trigger.
+
+There is deliberately no Course, Tour, or Step model. Tutorials remain
+independently invokable. The modal remembers only the path the current visitor
+took, so opening a middle tutorial directly never shows a misleading Back
+button.
+
+## Video
+
+Paste any supported HTTPS URL:
+
+| Provider | Accepted examples |
+| --- | --- |
+| YouTube | `youtube.com/watch`, Shorts, Live, embed, `youtu.be` |
+| Vimeo | Public and unlisted links; privacy hashes are preserved |
+| Loom | Share and embed links |
+| Tella | Video links |
+| Voomly | Share, video, and embed links |
+| Direct | URLs ending in `.mp4` or `.webm` |
+
+YouTube, Vimeo, and Loom metadata comes from their oEmbed endpoints. Metadata is
+best-effort: a timeout never prevents you from saving a valid URL. YouTube uses
+`youtube-nocookie.com`; unsupported hosts and lookalike URLs fail closed.
+
+Direct videos seek to an early frame for a useful preview instead of showing an
+empty player.
+
+<details>
+<summary><b>Upload videos or add rich descriptions</b></summary>
+
+Both are optional Rails features:
 
-```js
-// product_tour_autoplay_controller.js in the host app
-connect() {
-  this.element.click()
-}
+```bash
+bin/rails active_storage:install
+bin/rails action_text:install
+bin/rails db:migrate
 ```
 
-The gem deliberately has no page-rule engine, automatic display scheduler,
-resource center, or guides launcher. Those are host navigation and presentation
-choices built from the same `data-product-tour` attribute.
-
-## Tutorials
-
-A tutorial is stored internally as a `ProductTours::Post`. It has a title, key,
-locale, `draft`/`published` status,
-optional video, optional rich description, and one primary action. Video URLs
-support YouTube, Vimeo, Loom, Tella, Voomly, and direct MP4/WebM files.
-
-The dashboard previews a pasted video URL immediately. YouTube, Vimeo, and Loom
-metadata is fetched through oEmbed; the other supported providers still get a
-safe resolved preview. Direct videos seek to an early frame so they do not look
-like an empty player before playback.
+Once the tables exist, the editor offers **Use a video link / Upload a video**
+and a compact rich-text description editor. Uploaded videos are reached through
+the engine's gated media route.
 
-The admin sidebar treats `I18n.default_locale` as the canonical tutorial list.
-The New product tour button always creates that default-language record. Open a
-tutorial to see its existing languages or add another available locale; each
-translation remains an ordinary draft/published `Post` with the same key.
+</details>
 
-When the host has a Rails Content Security Policy, the engine preserves its
-existing `frame-src` entries and automatically adds the supported embed origins.
-For a direct video hosted on a custom origin, the host remains responsible for
-allowing that origin in `media-src` (or can allow HTTPS media generally).
+## Translations
 
-### Link tutorials into a walkthrough
+The dashboard sidebar shows only `I18n.default_locale`. Open a tutorial to see
+every existing language and add another from `I18n.available_locales`.
 
-In the tutorial editor, choose what the primary button does: finish and close,
-open a page, or continue to another tutorial. Continuing opens the selected
-tutorial in the
-same modal and automatically gives visitors a Back button.
+- New product tours always start in the default locale.
+- A translation copies the source into a new **draft** with the same key.
+- The key and language become locked identity; translate, review, then publish.
+- A trigger tries `I18n.locale`, then `I18n.default_locale` only when no current-
+  locale record exists.
+- A draft translation does **not** silently fall back to published English. It
+  stays unavailable until you publish it.
 
-Tutorials remain independently invokable—there is no separate course, step, or
-sequence model. The Back history exists only for the open modal, so a tutorial opened
-directly never shows a misleading Back button.
+This keeps one stable developer key while giving admins an obvious place to
+manage every language.
 
-Video uploads require Active Storage:
-
-```bash
-bin/rails active_storage:install
-bin/rails db:migrate
-```
+## Demo tutorials
 
-Rich descriptions require Action Text:
+Development installs seed the app's default locale automatically. Refresh the
+full idempotent set in English, French, and Bulgarian whenever you like:
 
 ```bash
-bin/rails action_text:install
-bin/rails db:migrate
+bin/rails product_tours:seed_demo
 ```
 
-The post form hides either feature when its Rails framework is not installed.
-
-## Demo tutorials
+The demo includes every video provider, a walkthrough through all of them, a
+direct MP4, a normal URL action, an unpublished key, and an intentionally missing
+key. Running the task again updates those records instead of duplicating them.
 
-The installer seeds the app's default locale in development. Copy the block it
-prints into any ERB view to open every demo entry point immediately:
+<details>
+<summary><b>Copy-ready demo buttons</b></summary>
 
 ```erb
 <div class="product-tours-demo">
@@ -138,48 +215,82 @@ prints into any ERB view to open every demo entry point immediately:
 <%= product_tours_tag %>
 ```
 
-`demo_walkthrough_start` introduces the collection, then continues through the
-YouTube, Vimeo, Loom, Tella, Voomly, and direct-video tutorials before its final
-step. Every transition demonstrates the automatic Back button. The individual
-provider buttons remain available so each video can also be opened directly.
-The final two buttons deliberately exercise unresolved triggers: `demo_draft`
-exists but remains unpublished, while `demo_missing_post` is never seeded.
-
-Refresh the full idempotent demo set in English, French, and Bulgarian at any
-time:
-
-```bash
-bin/rails product_tours:seed_demo
-```
+</details>
 
-Along with the provider examples, it creates `demo_walkthrough_start`,
-`demo_walkthrough_features`, `demo_walkthrough_finish`, and the unpublished
-`demo_draft` in the default demo locales (`en`, `fr`, and `bg`). The missing-key
-button intentionally has no matching record. Running the task again refreshes
-the seeded records instead of duplicating them and prints the copy-ready block
-again. To seed only one locale from application code, call
-`ProductTours::Seeds.load!(locale: :fr)`.
+## Configure
 
-## Configuration
+Everything is optional — a development install works with zero config. In
+`config/initializers/product_tours.rb`:
 
-The installer creates `config/initializers/product_tours.rb`. Important hooks:
+| Option | Default | What it does |
+| --- | --- | --- |
+| `enabled` | everyone | Who can resolve and open published tutorials |
+| `authorize_admin` | development only | **Who can manage content at the mount path** |
+| `admin_layout` | gem layout | Render the dashboard inside your admin shell |
+| `storage_service` | app default | Named Active Storage service for uploaded videos |
+| `mount_path` | `/product_tours` | Keep in sync only when mounting the engine manually |
 
 ```ruby
 ProductTours.configure do |config|
+  config.enabled = ->(request) { request.env["warden"]&.user.present? }
   config.authorize_admin = ->(request) { request.env["warden"]&.user&.admin? }
+  config.admin_layout = "admin/application"
+  config.storage_service = :product_tours
 end
 ```
 
-Tutorial lookup automatically uses the page's current `I18n.locale`, then falls
-back to `I18n.default_locale` when that key has no current-locale record. An
-existing draft translation is not bypassed by the fallback.
+Gates receive the **raw request**, so Devise, Rails 8 authentication, Flipper,
+or your own session model all work without an adapter.
+
+## Trigger it from your own UI
+
+The gem ships no floating launcher. A trigger belongs in the navigation,
+settings card, empty state, or success screen where it makes sense:
+
+```erb
+<a href="#" data-product-tour="invite_team">How team invitations work</a>
+```
+
+Keep `<%= product_tours_tag %>` in the layout when triggers appear across the
+app. When `enabled` returns false, the helper renders nothing and the endpoints
+also reject the request.
+
+<details>
+<summary><b>Open a tutorial after a redirect</b></summary>
+
+The host owns timing. Rails flash plus a tiny Stimulus controller is enough:
+
+```erb
+<% if flash[:product_tour].present? %>
+  <button hidden
+          data-controller="product-tour-autoplay"
+          data-product-tour="<%= flash[:product_tour] %>"></button>
+<% end %>
+```
+
+```js
+// product_tour_autoplay_controller.js in your app
+connect() {
+  this.element.click()
+}
+```
+
+</details>
+
+## Lifecycle events
 
-## Lifecycle Notifications
+The gem persists no analytics, user identity, cookies, progress, or completion
+table. It emits three Rails notifications:
 
-The widget emits `product_tours.viewed`, `product_tours.dismissed`, and
-`product_tours.completed` through `ActiveSupport::Notifications`. The gem does
-not persist analytics and does not depend on Ahoy. `completed` means the visitor
-used the tutorial's primary action; video playback does not imply completion.
+| Event | Meaning |
+| --- | --- |
+| `product_tours.viewed` | The modal became visible and focused |
+| `product_tours.dismissed` | The visitor closed it before using the primary action |
+| `product_tours.completed` | The visitor used the primary action |
+
+Payload: `post_id`, `key`, `locale`, query-free `page_url`, and `source`.
+
+Bridge them to Ahoy—or anything else—in your host app:
 
 ```ruby
 ActiveSupport::Notifications.subscribe(/^product_tours\./) do |name, _start, _finish, _id, payload|
@@ -187,23 +298,67 @@ ActiveSupport::Notifications.subscribe(/^product_tours\./) do |name, _start, _fi
 end
 ```
 
-The host may store these events with Ahoy and attach its own user or account
-context in the subscriber. Persistence, dashboards, identity, and vendor-specific
-integrations remain outside this gem.
+Your subscriber can attach `Current.user` or account context. That identity does
+not need to become product-tour configuration.
+
+## Broken triggers fail loudly, not publicly
+
+`data-product-tour="key"` is a contract between code and dashboard content.
+Invalid, missing, draft, or disabled keys open nothing for the visitor.
+
+- Development/test: raises `ProductTours::UnresolvedTriggerError`.
+- Production: reports through `Rails.error`, logs as a fallback, and emits
+  `product_tours.unresolved_trigger` with `invalid_key`, `missing`,
+  `unpublished`, or `disabled`.
 
-## Scope
+No end user gets a Rails error page because somebody renamed a tutorial.
 
-`product_tours` owns tutorial persistence and editing, safe media rendering, the
-modal experience, linked-tutorial navigation, and lifecycle notifications. The host
-app owns trigger timing and placement, Help/resource menus, analytics storage,
-reporting, and downstream integrations.
+## Security
+
+- Admin authorization runs server-side on every dashboard request.
+- Public resolution returns only published tutorials allowed by `enabled`.
+- Video providers are an HTTPS allowlist; unsupported URLs render no iframe.
+- Action URLs accept relative app paths or HTTP(S), never script schemes.
+- Widget/dashboard assets are same-origin and fingerprinted.
+- Rails CSP nonces are preserved. Supported provider origins are merged into
+  `frame-src` without replacing the host policy.
+- For direct videos on another origin, allow that origin in the host app's
+  `media-src` policy.
+
+## What it doesn't do
+
+No anchored tooltips, selector recorder, page-rule engine, automatic scheduler,
+checklists, persisted progress, analytics dashboard, resource center, AI writer,
+Segment/Mixpanel/Slack integration, or user/account sync.
+
+The host app owns trigger timing and Help navigation. Ahoy or your analytics
+stack owns persistence and reporting. The gem stays small enough to understand.
 
 ## Development
 
 ```bash
-bundle install
 bundle exec rake test
 bundle exec rubocop
 ```
 
-Rails 7.1+ and Ruby 3.2+ are supported.
+CI runs Rails 7.1 / 7.2 / 8.0 / 8.1 against Ruby 3.2 / 3.3 / 3.4.
+
+Bug reports and pull requests are welcome. The most useful report is a real
+Rails app and the exact point where installation or authoring felt confusing.
+
+## Also by the same author
+
+- [testimonials](https://github.com/yshmarov/testimonials) — testimonials,
+  video reviews, and NPS for Rails.
+- [livechat](https://github.com/yshmarov/livechat) — in-app support messaging
+  for Rails.
+- [ideasbugs](https://github.com/yshmarov/ideasbugs) — in-app bug reports and
+  feature requests.
+- [i18n_proofreading](https://github.com/yshmarov/i18n_proofreading) — in-context
+  translation proofreading.
+- [SupeRails](https://superails.com) — Rails screencasts.
+
+## License
+
+MIT. If it saved you a subscription, a
+[⭐](https://github.com/yshmarov/product_tours) is a fair trade.

data/lib/product_tours/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ProductTours
-  VERSION = '0.1.0'
+  VERSION = '0.1.2'
 end

data/lib/product_tours/widget.rb

@@ -16,7 +16,11 @@ module ProductTours
       def dashboard_stylesheet = @dashboard_stylesheet ||= File.read(DASHBOARD_STYLESHEET_SOURCE)
       def fingerprint = @fingerprint ||= Digest::MD5.hexdigest(javascript)
       def dashboard_fingerprint = @dashboard_fingerprint ||= Digest::MD5.hexdigest(dashboard_javascript)
-      def dashboard_stylesheet_fingerprint = @dashboard_stylesheet_fingerprint ||= Digest::MD5.hexdigest(dashboard_stylesheet)
+
+      # Not an endless def like its neighbours: the one-liner is 126 characters.
+      def dashboard_stylesheet_fingerprint
+        @dashboard_stylesheet_fingerprint ||= Digest::MD5.hexdigest(dashboard_stylesheet)
+      end
 
       def snippet(locale:, nonce: nil)
         nonce_attr = nonce ? %( nonce="#{ERB::Util.html_escape(nonce)}") : ''

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: product_tours
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Yaroslav Shmarov
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-03 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -36,6 +35,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- AGENTS.md
 - CHANGELOG.md
 - MIT-LICENSE
 - README.md
@@ -83,6 +83,10 @@ files:
 - config/locales/product_tours.vi.yml
 - config/locales/product_tours.zh-CN.yml
 - config/routes.rb
+- docs/screenshots/01-walkthrough.jpg
+- docs/screenshots/02-dashboard.jpg
+- docs/screenshots/03-mobile.jpg
+- docs/screenshots/04-editor.jpg
 - lib/generators/product_tours/install/install_generator.rb
 - lib/generators/product_tours/install/templates/create_product_tours_posts.rb.tt
 - lib/generators/product_tours/install/templates/initializer.rb
@@ -109,7 +113,6 @@ metadata:
   changelog_uri: https://github.com/yshmarov/product_tours/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/yshmarov/product_tours/issues
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -124,8 +127,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.21
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Self-hosted product tours and video tutorials for Rails apps.
 test_files: []