ratatui_ruby-devtools 0.1.3 → 0.2.0

data/lib/ratatui_ruby/devtools/templates/AGENTS.md.erb

@@ -1,5 +1,5 @@
 <!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-FileCopyrightText: <%= year %> <%= copyright_holder %>
   SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
@@ -9,57 +9,130 @@
 
 Project Name: <%= gem_name %>
 
-Description: Part of the RatatuiRuby ecosystem.
+Description: <%= description %>
+
+## Stability & Compatibility
+
+<%- unless update_mode -%>
+- **Project Status:** Pre-1.0.
+- **Breaking Changes:** Backward compatibility is **NOT YET** a priority. You are encouraged to refactor APIs for better ergonomics and performance even if it breaks existing code.
+<%- end -%>
+- **Requirement:** All breaking changes **MUST** be explicitly documented in the [CHANGELOG.md](CHANGELOG.md)'s **Unreleased** section. Migration guides in `doc/` are expected for releases with significant numbers of breaking changes.
 
 ## 1. Standards
 
 ### STRICT REQUIREMENTS
 
+- **Check Before Implementing:** FIRST check tests for existing coverage. If it works, say so and point to the test.
 - Every file MUST begin with an SPDX-compliant header. Use `<%= license %>` for code; `CC-BY-SA-4.0` for documentation. `reuse annotate` can help you generate the header. **For Ruby files**, wrap SPDX comments in `#--` / `#++` to hide them from RDoc output.
 - Every line of Ruby MUST be covered by tests that would stand up to mutation testing.
   - Tests must be meaningful and verify specific behavior or rendering output; simply verifying that code "doesn't crash" is insufficient and unacceptable.
-- **Pre-commit:** Use `agent_rake` to ensure commit-readiness. See Tools for detailed instructions.
+  - **Prefer snapshot tests** (`assert_snapshots`, plural) over manual assertions for UI output. Snapshots are self-documenting and easier to maintain.
+<%- if has_rust -%>
+- Every line of Rust MUST be covered by tests that would stand up to mutation testing.
+  - Tests must be meaningful; simply verifying that code "doesn't crash" or "compiles" is insufficient and unacceptable.
+  - Each widget implementation must have a `tests` module with unit tests verifying basic rendering.
+<%- end -%>
+- **Pre-commit:** Use `bundle exec agent_rake` to ensure commit-readiness. See Tools for detailed instructions.
 - **Git Pager:** ALWAYS set `PAGER=cat` for ALL `git` commands (e.g., `PAGER=cat git diff`). This is mandatory.
 
 ### Tools
 
 - **NEVER** run `bundle exec rake` directly. **NEVER** run `bundle exec ruby -Ilib:test ...` directly.
-- **ALWAYS use `agent_rake`** (provided by the `ratatui_ruby-devtools` gem) for running tests, linting, or checking compilation.
+- **ALWAYS use `bundle exec agent_rake`** (provided by the `ratatui_ruby-devtools` gem) for running tests, linting, or checking compilation.
   - **Usage:**
-    - Runs default task (compile + test + lint): `agent_rake`
-    - Runs specific task: `agent_rake test:ruby` (for example)
+    - Runs default task (compile + test + lint): `bundle exec agent_rake`
+    - Runs specific task: `bundle exec agent_rake test:ruby` (for example)
+- **Snapshot Testing:** When tests fail due to intentional behavior changes (not bugs), update snapshots:
+  - **Command:** `UPDATE_SNAPSHOTS=1 bundle exec agent_rake test:ruby`
+  - This regenerates all `snapshot/*{txt,ansi}` files to match current output
+  - **When to use:** After modifying rendering, changing default values, or updating UI behavior
+  - **When NOT to use:** For actual test failures that indicate bugs in your code
+  - After updating, verify the changes make sense by reviewing the diff of `.snapshot` files
 - **Setup:** `bin/setup` must handle Bundler dependencies.
 - **Git:** ALWAYS set `PAGER=cat` with `git`. **THIS IS CRITICAL!**
+- **Rake:** Our rake tasks use `git ls-files`, so errors happen when you move or delete files. In this case, ask the user to stage changes for you.
 
 ### Ruby Standards
 
-- Use `Data.define` for all value objects (Ruby 3.2+).
-- Define types in `.rbs` files. Don't use `untyped` just because it's easy; be comprehensive and accurate.
-- Every public Ruby class/method must be documented for humans in RDoc.
+- Use `Data.define` for all value objects (Ruby 3.2+). (Prefer `class Foo < Data.define()` over `Foo = Data.define() do`).
+- Define types in `.rbs` files. Don't use `untyped` just because it's easy; be comprehensive and accurate. Do not include `initialize` in `.rbs` files; use `self.new` for constructors instead.
+- Every public Ruby class/method must be documented for humans in RDoc (preferred)--**not** YARD--or markdown files (fallback), and must have `*.rbs` types defined.
+- Every significant architectural and design decision must be documented for contributors in markdown files. Mermaid is allowed.
+<%- if has_rust -%>
+- **Rust-backed methods:** For methods implemented in Rust (magnus bindings), use RDoc directives instead of empty method bodies. Use `##` followed by `:method:`, `:call-seq:`, and prose. End with `(Native method implemented in Rust)`.
+<%- end -%>
 
-## 2. Committing
+<%- if has_rust -%>
+### Rust Standards
 
-- Who commits: DON'T stage (DON'T `git add`) unless explicitly instructed. DON'T commit unless explicitly instructed. DO suggest a commit message when you finish.
-- **Format:**
-    - Format: Use [Conventional Commits](https://www.conventionalcommits.org/).
-    - Body: Explanation if necessary (wrap at 72 chars).
-        - **DON'T list the files changed or the edits made in the body.**
-        - **DON'T use markdown syntax** (no backticks, no bolding, no lists, no links).
+- **Crate Type:** `cdylib`.
+- **Bindings:** Use [magnus](https://github.com/matsadler/magnus).
+- **Platform:** Support macOS (Apple Silicon), Linux, and Windows.
 
-## 3. Definition of Done (DoD)
+<%- end -%>
+## 2. Configuration & Tooling
 
-Before considering a task complete:
+### Development Environment
 
-1. **Default Rake Task Passes:** Run `agent_rake` (no args). Confirm it passes with ZERO errors.
-2. **Documentation Updated:** If public APIs changed, update relevant docs.
-3. **Changelog Updated:** If public APIs changed, update CHANGELOG.md's **Unreleased** section.
-4. **Commit Message Suggested:** Include a suggested commit message block.
+- **Scripting Preference:** Simple `sed` or shell one-liners are fine. When a one-off script grows to multiple lines of logic, prefer a temporary rake task or `ruby -e '...'` over a multi-line shell script in a string. Ruby's `File.read`/`File.write`, `Dir.glob`, and regex handle complex transformations more cleanly.
 
-### Type Conventions
+### Documentation
 
-- `lib/`, `ext/`, `sig/`: Use `feat`, `fix`, `refactor`, `perf` as appropriate.
-- `bin/`, `tasks/`, `.builds/`, CI/CD: Use `chore` for tooling internal to developing this gem. Use `feat`/`fix` for user-facing executables or changes that affect downstream users.
-- `examples/`: Always `docs` (documentation by example).
-- `test/`: Use `test` for new/changed tests, or match the type of the code being tested.
-- `doc/`: Always `docs`.
+- **The `doc/` folder contains source markdown files** that are included in RDoc output.
+- Documentation should separate "User Guide" (for application developers) from "Contributor Guide" (for library developers).
+- DON'T write .md files for something RDoc (Ruby)<%= has_rust ? " or rustdoc (Rust)" : "" %> can generate. DO use RDoc<%= has_rust ? " and rustdoc" : "" %> for documentation.
 
+## 3. Committing
+
+- Who commits: DON'T stage (DON'T `git add`) unless explicitly instructed. DON'T commit unless explicitly instructed. DO suggest a commit message when you finish, even if not instructed.
+- When: Before reporting the task as complete to the user, suggest the commit message.
+- What: Consider not what you remember, but EVERYTHING in the `git diff` and `git diff --cached`.
+- **Format:**
+    - Format: Use [Conventional Commits](https://www.conventionalcommits.org/).
+    - Body: Explanation if necessary (wrap at 72 chars).
+        - Explain why this is the implementation, as opposed to other possible implementations.
+        - Skip the body entirely if it's rote, a duplication of the diff, or otherwise unhelpful.
+        - **DON'T list the files changed or the edits made in the body.** Don't provide a bulleted list of changes. Use prose to explain the problem and the solution.
+        - **DON'T use markdown syntax** (no backticks, no bolding, no lists, no links). The commit message must be plain text.
+- **Type conventions by directory:**
+    - `lib/`, `ext/`, `sig/`: Use `feat`, `fix`, `refactor`, `perf` as appropriate.
+    - `bin/`, `tasks/`, CI/CD: Use `chore` for tooling internal to developing this gem. Use `feat`/`fix` for user-facing executables or changes that affect downstream users.
+    - `examples/`: Always `docs` (documentation by example).
+    - `test/`: Use `test` for new/changed tests, or match the type of the code being tested.
+    - `doc/`: Always `docs`.
+
+## 4. Changelog
+
+- Follow [Semantic Versioning](https://semver.org/)
+- Follow the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) specification.
+- **What belongs in CHANGELOG:** Only changes that affect **application developers** or **higher-level library developers** who use or depend on `<%= gem_name %>`:
+    - New public APIs or widget parameters
+    - Backwards-incompatible type signature changes, or behavioral additions to type signature changes
+    - Observable behavior changes (rendering, styling, layout)
+    - Deprecations and removals
+    - Breaking changes
+- **What does NOT belong in CHANGELOG:** Internal or non-behavioral changes that don't affect downstream users:
+    - Test additions or improvements
+    - Documentation updates, RDoc fixes, markdown clarifications
+    - Refactors of internal code
+    - New or modified example code
+    - Internal tooling, CI/CD, or build configuration changes
+    - Code style or linting changes
+    - Performance improvements that affect applications
+- Changelogs should be useful to downstream developers (both app and library developers), not simple restatements of diffs or commit messages.
+- The Unreleased section MUST be considered "since the last git tag". Therefore, if a change was done in one commit and undone in another (both since the last tag), the second commit should remove its changelog entry.
+- **Location:** New entries ALWAYS go in `## [Unreleased]`. Never edit past version sections (e.g., `## [0.4.0]`)—those are frozen history.
+
+## 5. Definition of Done (DoD)
+
+Before considering a task complete and returning control to the user, you **MUST** ensure:
+
+0. **Production Ready:** RBS types are complete and accurate (no `untyped`), errors are handled with good DX, documentation follows guidelines, high code quality (no "pre-existing debt" excuses).
+1.  **Default Rake Task Passes:** Run `bundle exec agent_rake` (no args). Confirm it passes with ZERO errors **or warnings**.
+  - You will save time if you run `bundle exec agent_rake rubocop:autocorrect` first.
+  - If you think the rake is looking for deleted files, STOP EVERYTHING and tell the user.
+2.  **Documentation Updated:** If public APIs or observable behavior changed, update relevant RDoc, `doc/` files, `README.md`.
+3.  **Changelog Updated:** If public APIs, observable behavior, or gemspec dependencies have changed, update [CHANGELOG.md](CHANGELOG.md)'s **Unreleased** section.
+4.  **Commit Message Suggested:** You **MUST** ensure the final message to the user includes a suggested commit message block. This is NOT optional.
+  - You MUST also check `git log -n1` to see the current standard AI footer ("Generated  with" and "Co-Authored-By") and include it in your suggested message.

data/lib/ratatui_ruby/devtools/templates/CODE_OF_CONDUCT.md.erb

@@ -0,0 +1,44 @@
+<!--
+SPDX-FileCopyrightText: <%= Time.now.year %> <%= copyright_holder %>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# **<%= gem_name %>** Code of Conduct
+
+This project is intended to be a safe, productive collaboration, and
+contributors are expected to adhere to the [Ruby Community Conduct
+Guideline](https://www.ruby-lang.org/en/conduct/).
+
+For your convenience, it is reproduced below. If this document ever falls out of
+date and/or conflicts with the linked [Ruby Community Conduct
+Guideline](https://www.ruby-lang.org/en/conduct/) document, the linked document
+takes precedence.
+
+
+<!--
+SPDX-FileCopyrightText: 2016 Yukihiro Matsumoto <matz@netlab.jp>
+SPDX-License-Identifier: BSD-2-Clause
+-->
+
+
+## The Ruby Community Conduct Guideline
+
+> **We have picked the following conduct guideline based on an early proposed
+> draft of the PostgreSQL CoC, for Ruby developers community for safe, productive
+> collaboration. Each Ruby related community (conference etc.) may pick their own
+> Code of Conduct.**
+> 
+> This document provides community guidelines for a safe, respectful, productive,
+> and collaborative place for any person who is willing to contribute to the Ruby
+> community. It applies to all "collaborative space", which is defined as
+> community communications channels (such as mailing lists, submitted patches,
+> commit comments, etc.).
+> 
+> - Participants will be tolerant of opposing views.
+> 
+> - Participants must ensure that their language and actions are free of personal
+> attacks and disparaging personal remarks.
+> 
+> - When interpreting the words and actions of others, participants should always
+> assume good intentions.
+> 
+> - Behaviour which can be reasonably considered harassment will not be tolerated.

data/lib/ratatui_ruby/devtools/templates/CONTRIBUTING.md.erb

@@ -0,0 +1,80 @@
+<!--
+  SPDX-FileCopyrightText: <%= Time.now.year %> <%= copyright_holder %>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Contributing
+
+This guide walks you through setting up a development environment for
+<%= gem_display_name %>. By the end, you will have a working test suite on macOS, Linux,
+or Windows.
+
+## Prerequisites
+
+The only prerequisite is [mise](https://mise.jdx.dev/installing-mise.html), a
+dev tool manager. It installs Ruby, <%= has_rust ? "Rust, " : "" %>Python, and pre-commit hooks
+according to `mise.toml`.
+
+## Setup
+
+Clone the repository and run the setup script for your platform.
+
+### macOS / Linux
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: <%= Time.now.year %> <%= copyright_holder %>
+  SPDX-License-Identifier: MIT-0
+-->
+```sh
+bin/setup
+```
+<!-- SPDX-SnippetEnd -->
+
+### Windows (PowerShell)
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: <%= Time.now.year %> <%= copyright_holder %>
+  SPDX-License-Identifier: MIT-0
+-->
+```powershell
+bin/setup.ps1
+```
+<!-- SPDX-SnippetEnd -->
+
+Both scripts install <%= has_rust ? "Rust, " : "" %>Python, Bundler, and gem dependencies. On macOS
+and Linux, mise handles everything including Ruby. On Windows, the script
+installs Ruby via [RubyInstaller](https://rubyinstaller.org/) (winget) since
+mise cannot compile working Ruby on Windows. RubyInstaller bundles the MSYS2
+devkit for native gem compilation.<%= has_rust ? " If Visual Studio Build Tools are missing\n(Rust depends on them), the script offers to install them via winget." : "" %>
+
+## Running Tests
+
+The default Rake task runs lint fixes, the test suite, code quality tools,
+license checks, and the Steep type checker:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: <%= Time.now.year %> <%= copyright_holder %>
+  SPDX-License-Identifier: MIT-0
+-->
+```sh
+bundle exec rake
+```
+<!-- SPDX-SnippetEnd -->
+
+## Community
+
+Active development happens on the `trunk` branch. The `stable` branch tracks
+releases only. Use `trunk` for contributions.
+
+The [discussion forum](https://forum.setdef.com/tags/c/<%= gem_name.tr('_', '-') %>/discussion)
+is the best place to ask questions, share patches, and get feedback. Report bugs
+on the [bug tracker](https://forum.setdef.com/tags/c/<%= gem_name.tr('_', '-') %>/bug). Follow
+[announcements](https://forum.setdef.com/tags/c/<%= gem_name.tr('_', '-') %>/announcement)
+for release notes. All participants follow the
+[Code of Conduct](./CODE_OF_CONDUCT.md).
+
+File issues for the underlying Rust library at
+[ratatui/ratatui](https://github.com/ratatui/ratatui).

data/lib/ratatui_ruby/devtools/templates/Gemfile.erb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 #--
+<%# REUSE-IgnoreStart -%>
 # SPDX-FileCopyrightText: <%= Time.now.year %> <%= copyright_holder %>
-# REUSE-IgnoreStart
 # SPDX-License-Identifier: <%= license %>
-# REUSE-IgnoreEnd
+<%# REUSE-IgnoreEnd -%>
 #++
 
 source "https://rubygems.org"

data/lib/ratatui_ruby/devtools/templates/README.md.erb

@@ -5,27 +5,60 @@
 # <%= gem_name %>
 
 [![
-builds.sr.ht status](https://builds.sr.ht/~kerrick/<%= gem_name %>.svg)](https://builds.sr.ht/~kerrick/<%= gem_name %>?) [![
-License](https://img.shields.io/badge/dynamic/regex?url=https%3A%2F%2Fgit.sr.ht%2F~kerrick%2F<%= gem_name %>%2Fblob%2Fstable%2F<%= gem_name %>.gemspec&search=spec%5C.license%20%3D%20%22(.*)%22&replace=%241&label=License&color=a2c93e)](https://spdx.org/licenses/<%= license %>.html) [![
+CI](https://github.com/<%= github_repo %>/actions/workflows/ci.yml/badge.svg)](https://github.com/<%= github_repo %>/actions/workflows/ci.yml) [![
+License](https://img.shields.io/badge/License-<%= license %>-a2c93e)](https://spdx.org/licenses/<%= license %>.html) [![
 Gem Total Downloads](https://img.shields.io/gem/dt/<%= gem_name %>)](https://rubygems.org/gems/<%= gem_name %>) [![
 Gem Version](https://img.shields.io/gem/v/<%= gem_name %>)](https://rubygems.org/gems/<%= gem_name %>) [![
-Mailing List: Discussion](https://img.shields.io/badge/mailing_list-discussion-5865F2.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0iaWNvbiBpY29uLXRhYmxlciBpY29ucy10YWJsZXItb3V0bGluZSBpY29uLXRhYmxlci1tYWlsIj48cGF0aCBzdHJva2U9Im5vbmUiIGQ9Ik0wIDBoMjR2MjRIMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMyA3YTIgMiAwIDAgMSAyIC0yaDE0YTIgMiAwIDAgMSAyIDJ2MTBhMiAyIDAgMCAxIC0yIDJoLTE0YTIgMiAwIDAgMSAtMiAtMnYtMTB6IiAvPjxwYXRoIGQ9Ik0zIDdsOSA2bDkgLTYiIC8+PC9zdmc+Cg==)](https://lists.sr.ht/~kerrick/ratatui_ruby-discuss) [![
-Mailing List: Development](https://img.shields.io/badge/mailing_list-development-4954d5.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0iaWNvbiBpY29uLXRhYmxlciBpY29ucy10YWJsZXItb3V0bGluZSBpY29uLXRhYmxlci1tYWlsIj48cGF0aCBzdHJva2U9Im5vbmUiIGQ9Ik0wIDBoMjR2MjRIMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMyA3YTIgMiAwIDAgMSAyIC0yaDE0YTIgMiAwIDAgMSAyIDJ2MTBhMiAyIDAgMCAxIC0yIDJoLTE0YTIgMiAwIDAgMSAtMiAtMnYtMTB6IiAvPjxwYXRoIGQ9Ik0zIDdsOSA2bDkgLTYiIC8+PC9zdmc+Cg==)](https://lists.sr.ht/~kerrick/ratatui_ruby-devel) [![
-Mailing List: Announcements](https://img.shields.io/badge/mailing_list-announcements-3b44ac.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0iaWNvbiBpY29uLXRhYmxlciBpY29ucy10YWJsZXItb3V0bGluZSBpY29uLXRhYmxlci1tYWlsIj48cGF0aCBzdHJva2U9Im5vbmUiIGQ9Ik0wIDBoMjR2MjRIMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMyA3YTIgMiAwIDAgMSAyIC0yaDE0YTIgMiAwIDAgMSAyIDJ2MTBhMiAyIDAgMCAxIC0yIDJoLTE0YTIgMiAwIDAgMSAtMiAtMnYtMTB6IiAvPjxwYXRoIGQ9Ik0zIDdsOSA2bDkgLTYiIC8+PC9zdmc+Cg==)](https://lists.sr.ht/~kerrick/ratatui_ruby-announce)
+Discussion](https://img.shields.io/badge/forum-discussion-5865F2.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0iaWNvbiBpY29uLXRhYmxlciBpY29ucy10YWJsZXItb3V0bGluZSBpY29uLXRhYmxlci1tYWlsIj48cGF0aCBzdHJva2U9Im5vbmUiIGQ9Ik0wIDBoMjR2MjRIMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMyA3YTIgMiAwIDAgMSAyIC0yaDE0YTIgMiAwIDAgMSAyIDJ2MTBhMiAyIDAgMCAxIC0yIDJoLTE0YTIgMiAwIDAgMSAtMiAtMnYtMTB6IiAvPjxwYXRoIGQ9Ik0zIDdsOSA2bDkgLTYiIC8+PC9zdmc+Cg==)](https://forum.setdef.com/tags/c/<%= gem_name.tr('_', '-') %>/discussion) [![
+Bug Reports](https://img.shields.io/badge/forum-bug_reports-4954d5.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0iaWNvbiBpY29uLXRhYmxlciBpY29ucy10YWJsZXItb3V0bGluZSBpY29uLXRhYmxlci1tYWlsIj48cGF0aCBzdHJva2U9Im5vbmUiIGQ9Ik0wIDBoMjR2MjRIMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMyA3YTIgMiAwIDAgMSAyIC0yaDE0YTIgMiAwIDAgMSAyIDJ2MTBhMiAyIDAgMCAxIC0yIDJoLTE0YTIgMiAwIDAgMSAtMiAtMnYtMTB6IiAvPjxwYXRoIGQ9Ik0zIDdsOSA2bDkgLTYiIC8+PC9zdmc+Cg==)](https://forum.setdef.com/tags/c/<%= gem_name.tr('_', '-') %>/bug) [![
+Announcements](https://img.shields.io/badge/forum-announcements-3b44ac.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0iaWNvbiBpY29uLXRhYmxlciBpY29ucy10YWJsZXItb3V0bGluZSBpY29uLXRhYmxlci1tYWlsIj48cGF0aCBzdHJva2U9Im5vbmUiIGQ9Ik0wIDBoMjR2MjRIMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMyA3YTIgMiAwIDAgMSAyIC0yaDE0YTIgMiAwIDAgMSAyIDJ2MTBhMiAyIDAgMCAxIC0yIDJoLTE0YTIgMiAwIDAgMSAtMiAtMnYtMTB6IiAvPjxwYXRoIGQ9Ik0zIDdsOSA2bDkgLTYiIC8+PC9zdmc+Cg==)](https://forum.setdef.com/tags/c/<%= gem_name.tr('_', '-') %>/announcement)
 
 
 ## Introduction
 
-**<%= gem_name %>** is a gem in the [RatatuiRuby ecosystem](https://sr.ht/~kerrick/ratatui_ruby/).
+**<%= gem_name %>** is a gem in the [RatatuiRuby ecosystem](https://www.ratatui-ruby.dev).
 **ratatui_ruby** is a community wrapper that is not affiliated with [the Ratatui team](https://github.com/orgs/ratatui/people).
 
 > [!WARNING]
 > **<%= gem_name %>** is currently in **PRE-RELEASE**. The API will change rapidly, even between minor and patch versions.
 
-**[Why RatatuiRuby?](https://man.sr.ht/~kerrick/ratatui_ruby/why.md)** — Native Rust performance, zero runtime overhead, and Ruby's expressiveness. [See how we compare](https://man.sr.ht/~kerrick/ratatui_ruby/why.md) to CharmRuby, raw Rust, and Go.
+**[Why RatatuiRuby?](https://www.ratatui-ruby.dev/docs/trunk/doc/getting_started/why_md.html)** — Native Rust performance, zero runtime overhead, and Ruby's expressiveness. [See how we compare](https://www.ratatui-ruby.dev/docs/trunk/doc/getting_started/why_md.html) to CharmRuby, raw Rust, and Go.
 
-Please join the **announce** mailing list at https://lists.sr.ht/~kerrick/ratatui_ruby-announce to stay up-to-date on new releases and announcements. See the [`trunk` branch](https://git.sr.ht/~kerrick/<%= gem_name %>/tree/trunk) for pre-release updates.
+Please follow the [announcements](https://forum.setdef.com/tags/c/<%= gem_name.tr('_', '-') %>/announcement) to stay up-to-date on new releases. See the [`trunk` branch](https://github.com/<%= github_repo %>/tree/trunk) for pre-release updates.
 
+----
+
+## Quick Links
+
+### The Ecosystem
+
+**RatatuiRuby:** [Core engine](https://www.ratatui-ruby.dev)
+• **Rooibos:** [MVU architecture](https://www.rooibos.run)
+• **Kit:** [Component architecture](https://sr.ht/~kerrick/ratatui_ruby/#chapter-3-the-object-path--kit) (Planned)
+• **DSL:** [Glimmer syntax](https://sr.ht/~kerrick/ratatui_ruby/#chapter-4-the-syntax) (Planned)
+• **Framework:** [Omakase framework](https://sr.ht/~kerrick/ratatui_ruby/#chapter-5-the-framework) (Planned)
+• **UI:** [Polished widgets](https://sr.ht/~kerrick/ratatui_ruby#chapter-6-licensing) (Planned)
+• **UI Pro:** [More polished widgets](https://sr.ht/~kerrick/ratatui_ruby#chapter-6-licensing) (Planned)
+
+### For App Developers
+
+**Get Started:** [Quickstart](https://www.ratatui-ruby.dev/docs/trunk/doc/getting_started/quickstart_md.html)
+• [Examples](https://www.ratatui-ruby.dev/docs/trunk/examples/app_all_events/README_md.html)
+⸺ **Stay Informed:** [Announcements](https://forum.setdef.com/tags/c/<%= gem_name.tr('_', '-') %>/announcement)
+• [FAQ](https://www.ratatui-ruby.dev/docs/trunk/doc/troubleshooting/index_md.html)
+⸺ **Reach Out:** [Forum](https://forum.setdef.com/c/<%= gem_name.tr('_', '-') %>)
+• [Bug Tracker](https://forum.setdef.com/tags/c/<%= gem_name.tr('_', '-') %>/bug)
+
+### For Contributors
+
+**Get Started:** [Contributing Guide](./CONTRIBUTING.md)
+• [Code of Conduct](./CODE_OF_CONDUCT.md)
+⸺ **Stay Informed:** [Announcements](https://forum.setdef.com/tags/c/<%= gem_name.tr('_', '-') %>/announcement)
+• [FAQ](https://www.ratatui-ruby.dev/docs/trunk/doc/troubleshooting/index_md.html)
+⸺ **Reach Out:** [Forum](https://forum.setdef.com/c/<%= gem_name.tr('_', '-') %>)
+• [Bug Tracker](https://forum.setdef.com/tags/c/<%= gem_name.tr('_', '-') %>/bug)
+
+----
 
 ## Compatibility
 
@@ -98,18 +131,18 @@ _Because this gem is in pre-release, it lacks documentation. Please check the so
 | [Application Architecture](./doc/concepts/application_architecture.md) | Patterns for scaling your app |
 | [Guides](./doc/index.md) | Tutorials, examples, and more |
 | API Reference | To generate full RDoc documentation, run `bundle exec rake rdoc` |
-| [Wiki](https://man.sr.ht/~kerrick/ratatui_ruby) | Learn more about the RatatuiRuby ecosystem |
+| [Ecosystem](https://www.ratatui-ruby.dev) | Learn more about the RatatuiRuby ecosystem |
 
 
 ## Contributing
 
-Bug reports and pull requests are welcome on [sourcehut](https://sourcehut.org) at https://sr.ht/~kerrick/ratatui_ruby/. This project is intended to be a safe, productive collaboration, and contributors are expected to adhere to the [Code of Conduct](https://man.sr.ht/~kerrick/ratatui_ruby/code_of_conduct.md).
+The [discussion forum](https://forum.setdef.com/tags/c/<%= gem_name.tr('_', '-') %>/discussion) is the best place to ask questions, share patches, and get feedback. Report bugs on the [bug tracker](https://forum.setdef.com/tags/c/<%= gem_name.tr('_', '-') %>/bug). All participants follow the [Code of Conduct](./CODE_OF_CONDUCT.md).
 <% if has_rust %>
 
-Issues for the underlying Rust library should be filed in their issue tracker.
+Issues for the underlying Rust library should be filed at [ratatui/ratatui](https://github.com/ratatui/ratatui).
 <% end %>
 
-Want to help develop **<%= gem_name %>**? Check out the [contribution guide on the wiki](https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md).
+Want to help develop **<%= gem_name %>**? Check out the [contribution guide](./CONTRIBUTING.md).
 
 **Note**: Active development happens on the `trunk` branch. Use `trunk` if you are a contributor or want the latest cutting-edge features. `stable` is for stable releases only.
 
@@ -124,4 +157,4 @@ Documentation is [CC-BY-SA-4.0](./LICENSES/CC-BY-SA-4.0.txt). Build tooling and
 
 Some parts of this program are copied from other sources under appropriate reuse licenses, and the copyright belongs to their respective owners. See the [REUSE Specification – Version 3.3](https://reuse.software/spec-3.3/) for details.
 
-This program was created with significant assistance from multiple LLMs. The process was human-controlled through creative prompts, with human contributions to each commit. See commit footers for model attribution. [declare-ai.org](https://declare-ai.org/1.0.0/creative.html)
+This program was created with significant assistance from multiple LLMs. The process was human-controlled through creative prompts, with human contributions to each commit. See commit footers for model attribution. [declare-ai.org](https://declare-ai.org/1.0.0/creative.html)

data/lib/ratatui_ruby/devtools/templates/REUSE.toml.erb

@@ -1,7 +1,7 @@
+<%# REUSE-IgnoreStart -%>
 # SPDX-FileCopyrightText: <%= Time.now.year %> <%= copyright_holder %>
-# REUSE-IgnoreStart
 # SPDX-License-Identifier: <%= license %>
-# REUSE-IgnoreEnd
+<%# REUSE-IgnoreEnd -%>
 
 version = 1
 

data/lib/ratatui_ruby/devtools/templates/Rakefile.erb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 #--
+<%# REUSE-IgnoreStart -%>
 # SPDX-FileCopyrightText: <%= Time.now.year %> <%= copyright_holder %>
-# REUSE-IgnoreStart
 # SPDX-License-Identifier: <%= license %>
-# REUSE-IgnoreEnd
+<%# REUSE-IgnoreEnd -%>
 #++
 
 require "bundler/gem_tasks"
@@ -22,8 +22,8 @@ Rake::ExtensionTask.new("<%= gem_name.tr('-', '_') %>") do |ext|
   ext.lib_dir = "lib/<%= gem_name.tr('-', '/') %>"
 end
 
-task default: %w[compile lint:fix test lint reuse]
+task default: %w[compile lint:fix install:force test lint reuse steep]
 <%- else -%>
 
-task default: %w[lint:fix test lint reuse]
+task default: %w[lint:fix install:force test lint reuse steep]
 <%- end -%>

data/lib/ratatui_ruby/devtools/templates/bin/setup.erb

@@ -1,24 +1,34 @@
 #!/usr/bin/env bash
+<%# REUSE-IgnoreStart -%>
 # SPDX-FileCopyrightText: <%= Time.now.year %> <%= copyright_holder %>
-# REUSE-IgnoreStart
 # SPDX-License-Identifier: <%= license %>
-# REUSE-IgnoreEnd
+<%# REUSE-IgnoreEnd -%>
 
 set -euo pipefail
 IFS=$'\n\t'
 set -vx
 
-if command -v mise >/dev/null 2>&1; then
-  mise install
-  mise x -- pip install reuse
-  mise x -- bundle install
+if ! command -v mise >/dev/null 2>&1; then
+  echo "mise isn't installed. Please install it to continue." >&2
+  exit 1
+fi
+
+mise install
+<%- if has_rust -%>
+mise x -- rustup component add rustfmt clippy
+<%- end -%>
+mise x -- pip install reuse
+mise x -- gem install bundler:4.0.3
+
+if [ "${CI:-}" = "true" ]; then
+  bundle config set --local frozen 'true'
+fi
+
+mise x -- bundle install
+
+if [ "${CI:-}" != "true" ]; then
   pre-commit install
-  mise x -- reuse download --all
-  bundle exec rake sourcehut
 <%- if has_rdoc -%>
   bundle exec rake rdoc
 <%- end -%>
-else
-  echo "mise isn't installed. Please install it to continue." >&2
-  exit 1
 fi

data/lib/ratatui_ruby/devtools/templates/bin/setup.ps1.erb

@@ -0,0 +1,105 @@
+<%# REUSE-IgnoreStart -%>
+# SPDX-FileCopyrightText: <%= Time.now.year %> <%= copyright_holder %>
+# SPDX-License-Identifier: <%= license %>
+<%# REUSE-IgnoreEnd -%>
+
+$ErrorActionPreference = "Stop"
+Set-StrictMode -Version Latest
+
+if (-not (Get-Command mise -ErrorAction SilentlyContinue)) {
+  Write-Error "mise isn't installed. Please install it to continue: https://mise.jdx.dev"
+  exit 1
+}
+
+# Read the Ruby version from mise.toml so we install the matching RubyInstaller.
+$rubyVersion = (Select-String -Path mise.toml -Pattern 'ruby\s*=\s*"([^"]+)"').Matches.Groups[1].Value
+$rubyMajorMinor = ($rubyVersion -split '\.')[0..1] -join '.'
+
+# mise cannot compile Ruby from source on Windows (ruby-build produces broken
+# native extension support). Install Ruby via RubyInstaller, which bundles the
+# MSYS2 devkit for native gem compilation.
+if (-not (Get-Command ruby -ErrorAction SilentlyContinue) -or -not ((ruby --version) -match $rubyMajorMinor)) {
+  Write-Host "Ruby $rubyMajorMinor is required but not installed."
+  if ($env:CI -ne "true") {
+    $answer = Read-Host "Install it now via RubyInstaller (winget)? This will require administrator privileges. [Y/n]"
+    if ($answer -and $answer -notmatch '^[Yy]') {
+      Write-Error "Cannot continue without Ruby."
+      exit 1
+    }
+  }
+  winget install --id "RubyInstallerTeam.RubyWithDevKit.$rubyMajorMinor" --accept-source-agreements --accept-package-agreements
+  # Refresh PATH so ruby is available
+  $env:Path = [System.Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path", "User")
+}
+
+<%- if has_rust -%>
+# Rust's default MSVC target requires Visual Studio Build Tools with the
+# C++ workload.
+$vsWhere = "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe"
+if (-not (Test-Path $vsWhere) -or -not (& $vsWhere -products * -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -property installationPath)) {
+  Write-Host "Visual Studio Build Tools with C++ workload is required for Rust compilation."
+  if ($env:CI -ne "true") {
+    $answer = Read-Host "Install it now via winget? This will require administrator privileges. [Y/n]"
+    if ($answer -and $answer -notmatch '^[Yy]') {
+      Write-Error "Cannot continue without Visual Studio Build Tools."
+      exit 1
+    }
+  }
+  winget install Microsoft.VisualStudio.2022.BuildTools --override "--wait --passive --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"
+}
+
+<%- end -%>
+# Create .mise.local.toml (gitignored) with Windows-specific overrides:
+#   - disable_tools: prevents mise from installing its own (broken) Ruby
+if (-not (Test-Path .mise.local.toml) -or -not (Select-String -Path .mise.local.toml -Pattern 'disable_tools' -Quiet)) {
+  $localToml = @"
+
+[settings]
+disable_tools = ["ruby"]
+"@
+  Add-Content -Path .mise.local.toml -Value $localToml
+}
+
+# mise handles Python and pre-commit. Ruby is disabled above.
+mise install
+<%- if has_rust -%>
+mise x -- rustup target add x86_64-pc-windows-gnu
+mise x -- rustup component add rustfmt clippy
+<%- end -%>
+mise x -- python -m pip install reuse
+
+# pip installs scripts (like reuse.exe) to Python's Scripts directory,
+# which mise does not add to PATH.
+if (-not (Select-String -Path .mise.local.toml -Pattern '\[env\]' -Quiet -ErrorAction SilentlyContinue)) {
+  $scriptsDir = (mise x -- python -c "import sysconfig; print(sysconfig.get_path('scripts'))").Trim()
+  $envToml = @"
+
+[env]
+_.path = ["$($scriptsDir -replace '\\', '/')"]
+"@
+<%- if has_rust -%>
+  if ($env:RI_DEVKIT) {
+    $msysRoot = (Join-Path $env:RI_DEVKIT "ucrt64") -replace '\\', '/'
+    $envToml += @"
+
+BINDGEN_EXTRA_CLANG_ARGS = "-include stdbool.h --target=x86_64-w64-mingw32 --sysroot=$msysRoot -I$msysRoot/include"
+CARGO_BUILD_TARGET = "x86_64-pc-windows-gnu"
+"@
+  }
+<%- end -%>
+  Add-Content -Path .mise.local.toml -Value $envToml
+}
+gem install bundler:4.0.3
+
+if ($env:CI -eq "true") {
+  bundle config set --local frozen true
+}
+
+bundle install
+
+if ($env:CI -ne "true") {
+  pre-commit install
+<%- if has_rdoc -%>
+  bundle exec rake rdoc
+<%- end -%>
+}

data/lib/ratatui_ruby/devtools/templates/doc/custom.css.erb

@@ -1,9 +1,9 @@
+<%# REUSE-IgnoreStart -%>
 /*
  * SPDX-FileCopyrightText: <%= Time.now.year %> <%= copyright_holder %>
- * REUSE-IgnoreStart
  * SPDX-License-Identifier: <%= license %>
- * REUSE-IgnoreEnd
  */
+<%# REUSE-IgnoreEnd -%>
 
 img {
   max-width: 100%;
@@ -21,4 +21,4 @@ img {
 img[src*="images/"] {
   display: block;
   margin: 2em auto;
-}
+}

data/lib/ratatui_ruby/devtools/templates/doc/getting_started/quickstart.md.erb

@@ -50,7 +50,7 @@ Now that you've seen what **<%= gem_name %>** can do:
 
 - **Deep dive**: Read the [Application Architecture](../concepts/application_architecture.md) guide for scaling patterns
 - **Test your TUI**: See the [Testing Guide](../concepts/application_testing.md) for snapshot and style assertions
-- **Avoid common mistakes**: See [Terminal Output During TUI Sessions](https://man.sr.ht/~kerrick/ratatui_ruby/troubleshooting/tui_output.md) to prevent screen corruption
+- **Avoid common mistakes**: See [Terminal Output During TUI Sessions](https://www.ratatui-ruby.dev/docs/trunk/doc/troubleshooting/tui_output_md.html) to prevent screen corruption
 - **Explore the API**: Browse the [full documentation](../index.md)
-- **Learn the philosophy**: Read [Why RatatuiRuby?](https://man.sr.ht/~kerrick/ratatui_ruby/why.md) for comparisons and design decisions
-- **Get help**: Join the [discussion mailing list](https://lists.sr.ht/~kerrick/ratatui_ruby-discuss)
+- **Learn the philosophy**: Read [Why RatatuiRuby?](https://www.ratatui-ruby.dev/docs/trunk/doc/getting_started/why_md.html) for comparisons and design decisions
+- **Get help**: Join the [discussion forum](https://forum.setdef.com/c/<%= gem_name.tr('_', '-') %>)