Add root README/CONTRIBUTING, update gem docs, add gemspec test

- New root README.md describes the monorepo layout (gem/ + docs/) and
  links the per-subproject READMEs.
- New root CONTRIBUTING.md covers the unified workflow: a single PR
  can touch the component (gem/) and its docs example (docs/) since
  the docs app consumes the local gem via path: "../gem".
- gem/AGENTS.md gains a "Monorepo context" section noting that
  component changes should be paired with docs/app/views/docs/
  updates in the same PR.
- gem/CONTRIBUTING.md drops the obsolete instruction to also open a
  PR on ruby-ui/web — that repo is being archived.
- gem/test/gemspec_test.rb is a new regression test that builds the
  .gem and verifies its contents are limited to README, LICENSE,
  and lib/. Catches accidental changes to s.files that would leak
  docs/, test/, or .github/ into the published gem.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: cirdes

CONTRIBUTING.md

@@ -0,0 +1,66 @@
+# Contributing to RubyUI
+
+Thanks for your interest in contributing! This repository is a monorepo containing two sibling projects:
+
+- [`gem/`](gem/) — the `ruby_ui` gem published to rubygems.org.
+- [`docs/`](docs/) — the Rails app that powers https://rubyui.com.
+
+The big advantage of the monorepo: **a single PR can touch both the component and the docs example**. The docs app consumes the local gem via `path: "../gem"`, so any change in `gem/lib/ruby_ui/` is reflected in the running site immediately.
+
+## Development setup
+
+We recommend using the devcontainer for either subproject (each has its own `.devcontainer/`).
+
+```bash
+git clone git@github.com:ruby-ui/ruby_ui.git
+cd ruby_ui
+
+# For gem-only work:
+cd gem
+bundle install
+bundle exec rake
+
+# For docs work:
+cd docs
+bundle install
+pnpm install
+bin/dev
+```
+
+## Workflow
+
+1. Fork and create a feature branch.
+2. Make your changes:
+   - Component or generator changes → `gem/lib/...`, with tests in `gem/test/...`.
+   - Documentation page changes → `docs/app/views/docs/...` or `docs/app/components/...`.
+   - If a component change affects how it's documented, update **both** in the same PR.
+3. Run the relevant test suites:
+   - `cd gem && bundle exec rake` (tests + standardrb).
+   - `cd docs && bin/rails test` and `bundle exec standardrb`.
+4. Open a Pull Request against `main`. Use the PR template and prefix the title with a category in brackets, e.g. `[Feature] Add new variant to Button`.
+
+## Focus areas
+
+We prioritize:
+
+- Improving existing components rather than adding new ones.
+- Preserving the shadcn look and feel.
+- Enhancing documentation.
+- Fixing bugs.
+
+## Code style
+
+- Ruby: [Standard Ruby](https://github.com/standardrb/standard) — `bundle exec standardrb --fix` to auto-fix.
+- JavaScript: kept minimal; Stimulus controllers live alongside the components they belong to.
+
+## Documentation files
+
+The gem ships per-component `*_docs.rb` files (rendering examples) under `gem/lib/ruby_ui/<component>/`. Consumers of the gem can install these into their own Rails app with:
+
+```bash
+bin/rails g ruby_ui:install:docs
+```
+
+Within this monorepo, the **docs app does not run that generator** — it has its own richer view implementations in `docs/app/views/docs/` and `docs/app/components/docs/`. If you change a component's API, update the relevant view in `docs/app/views/docs/<component>.rb` to keep the documentation site accurate.
+
+Thanks for helping make RubyUI better!

README.md

@@ -0,0 +1,51 @@
+# RubyUI
+
+[![CI](https://github.com/ruby-ui/ruby_ui/actions/workflows/ci.yml/badge.svg)](https://github.com/ruby-ui/ruby_ui/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/ruby_ui.svg)](https://rubygems.org/gems/ruby_ui)
+
+Beautifully designed components that you can copy and paste into your apps. Accessible. Customizable. Open Source.
+
+This repository is a **monorepo** with two sibling projects:
+
+```
+ruby_ui/
+├── gem/    # the ruby_ui gem (lib/, generators, tests, gemspec)
+└── docs/   # the Rails app that powers https://rubyui.com
+```
+
+## Quick links
+
+- **Use the gem in your app:** see [`gem/README.md`](gem/README.md).
+- **Documentation site:** https://rubyui.com/docs/introduction
+- **Contributing guide:** [`CONTRIBUTING.md`](CONTRIBUTING.md)
+
+## Layout
+
+| Path | What lives here |
+| --- | --- |
+| [`gem/`](gem/) | The `ruby_ui` gem (`gem build`, `gem release` from this folder). |
+| [`docs/`](docs/) | Rails 8 app for the documentation site. Consumes the local gem via `path: "../gem"`. |
+| [`.github/workflows/ci.yml`](.github/workflows/ci.yml) | Unified CI: gem tests on Ruby 3.3 + 3.4, Rails docs app tests, and a docker-build job that publishes the docs devcontainer to ghcr.io. |
+
+## Development
+
+The two projects are independent for everyday work — pick the one you need:
+
+```bash
+# Gem work
+cd gem
+bundle install
+bundle exec rake          # tests + standardrb
+
+# Docs work (consumes the local gem via path: "../gem")
+cd docs
+bundle install
+pnpm install
+bin/dev                   # http://localhost:3000
+```
+
+Editing files under `gem/lib/ruby_ui/` is reflected immediately when running the docs app — no `bundle update`, no rebuild, no PR coordination across two repos.
+
+## License
+
+Released under the [MIT License](gem/LICENSE.txt).

gem/AGENTS.md

@@ -1,6 +1,15 @@
 # AGENTS.md
 
-This file provides guidance to AI coding agents when working with code in this repository.
+This file provides guidance to AI coding agents working in `gem/` (the gem subproject of the RubyUI monorepo).
+
+## Monorepo context
+
+This file lives in `gem/`, one of two sibling projects in the `ruby-ui/ruby_ui` monorepo:
+
+- `gem/` — this directory; the `ruby_ui` gem (Phlex components, generators, tests).
+- `docs/` — Rails 8 app that powers https://rubyui.com. Consumes the local gem via `path: "../gem"`.
+
+When you change a component here (`gem/lib/ruby_ui/<component>/`), update the matching documentation view in `docs/app/views/docs/<component>.rb` in the same PR.
 
 ## Project Overview
 

gem/CONTRIBUTING.md

@@ -39,7 +39,7 @@ While we don't have specific test coverage requirements, all contributions shoul
 
 ## Documentation
 
-If your changes include new components, modify how components should be used, or add new behaviors, it is highly recommended to also open a PR on the [ruby-ui/web](https://github.com/ruby-ui/web) repository. This ensures the documentation website stays up-to-date with the latest component changes.
+If your changes include new components, modify how components should be used, or add new behaviors, please update the corresponding view in `docs/app/views/docs/<component>.rb` in the same PR — the docs Rails app lives in this same monorepo and consumes the local gem via `path: "../gem"`.
 
 ### Installing Documentation Files
 

gem/test/gemspec_test.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require "rubygems/package"
+require "tmpdir"
+
+class GemspecTest < Minitest::Test
+  GEM_ROOT = File.expand_path("..", __dir__)
+
+  def test_packaged_files_match_allowlist
+    files = build_and_list_files
+
+    refute_empty files, "expected the .gem to ship some files"
+
+    offenders = files.reject { |f| allowed?(f) }
+    assert_empty offenders, <<~MSG
+      ruby_ui.gemspec packaged unexpected files. The gemspec's
+      s.files allowlist must keep these out of the published gem
+      (e.g. files from docs/, test/, .github/, Gemfile, etc.):
+
+        #{offenders.join("\n  ")}
+    MSG
+  end
+
+  def test_includes_readme_and_license_and_lib
+    files = build_and_list_files
+
+    assert_includes files, "README.md"
+    assert_includes files, "LICENSE.txt"
+    assert files.any? { |f| f.start_with?("lib/") }, "expected lib/ files in the gem"
+  end
+
+  private
+
+  def allowed?(path)
+    path == "README.md" || path == "LICENSE.txt" || path.start_with?("lib/")
+  end
+
+  def build_and_list_files
+    Dir.mktmpdir do |tmpdir|
+      gem_path = File.join(tmpdir, "ruby_ui.gem")
+      Dir.chdir(GEM_ROOT) do
+        output = `gem build ruby_ui.gemspec --output #{gem_path} 2>&1`
+        raise "gem build failed:\n#{output}" unless $?.success?
+      end
+      Gem::Package.new(gem_path).map { |entry| entry.full_name }
+    end
+  end
+end