diff --git a/.claude/agents/perf-reviewer.md b/.claude/agents/perf-reviewer.md
index dbe74eb..c6cfc01 100644
--- a/.claude/agents/perf-reviewer.md
+++ b/.claude/agents/perf-reviewer.md
@@ -1,6 +1,6 @@
 ---
 name: perf-reviewer
-description: Reviews a diff in ruby2html for rendering-speed regressions and missed optimizations (allocations, buffer sizing, method dispatch, C hot paths). Use proactively after changes to lib/gem/ruby2html/render.rb, ext/ruby2html/*, or the template handler, and before merging perf claims.
+description: Reviews a diff in ruby2html for rendering-speed regressions and missed optimizations (allocations, buffer sizing, method dispatch, C hot paths). Use proactively after changes to apps/ruby2html/lib/gem/ruby2html/render.rb, apps/ruby2html/ext/ruby2html/*, or the template handler, and before merging perf claims.
 tools: Read, Grep, Glob, Bash
 ---
 
@@ -15,6 +15,6 @@ Check, citing file:line:
 - Caches: unbounded growth, keys that can collide (never cache by `Object#hash` alone).
 - Template handler / ComponentHelper: work done per render that could be done at compile time.
 
-Run only read-only or benchmark commands: `bundle exec rake compile`, `bundle exec rake bench`, `bundle exec ruby -Ilib/gem -Ilib bench/<script>.rb`. Never edit files, commit or push.
+Run only read-only or benchmark commands: `bundle exec rake compile` and `bundle exec rake bench` (run from `apps/ruby2html`), and from the repo root `bundle exec ruby -Iapps/ruby2html/lib/gem -Iapps/ruby2html/lib apps/ruby2html/bench/<script>.rb`. Never edit files, commit or push.
 
 Output: a ranked list (impact high/medium/low) with the evidence, and a before/after benchmark table if you ran one (same machine, record `ruby -v`). Say "no measurable change" when error bars overlap. No speculation without a pointer to code.
diff --git a/.claude/agents/xss-auditor.md b/.claude/agents/xss-auditor.md
index 65b7529..758c17e 100644
--- a/.claude/agents/xss-auditor.md
+++ b/.claude/agents/xss-auditor.md
@@ -6,7 +6,7 @@ tools: Read, Grep, Glob, Bash
 
 You audit ruby2html for escaping correctness. Default must be: text content and attribute values escaped; raw output only for `html_safe?` strings via `plain` (and documented raw APIs such as `component`).
 
-Read `AGENTS.md` and `llms.txt`, then the diff (`git diff` / `git diff main...HEAD`).
+Read `AGENTS.md` and `apps/ruby2html/llms.txt`, then the diff (`git diff` / `git diff main...HEAD`).
 
 Check, citing file:line:
 - Every path that appends user data: tag content (positional and block return), attribute values, attribute keys, `plain`, block-return handling, helper wrappers (`link_to`, `button_to`, `image_tag`, `form_with` / FormBuilder proxy), template handler annotations.
@@ -16,6 +16,6 @@ Check, citing file:line:
 - Caches returning output computed for different input.
 
 Verify with a quick script when unsure, e.g.:
-`bundle exec ruby -Ilib/gem -Ilib -e 'require "ruby2html"; puts Ruby2html::Render.new { div(title: %q("><script>)) { plain %q(<b>) } }.render'`
+`bundle exec ruby -Iapps/ruby2html/lib/gem -Iapps/ruby2html/lib -e 'require "ruby2html"; puts Ruby2html::Render.new { div(title: %q("><script>)) { plain %q(<b>) } }.render'`
 
 Never edit files, commit or push. Output: findings ranked critical/high/low with a minimal reproducing snippet and expected vs actual HTML, or an explicit "no issues found" with what you checked.
diff --git a/.claude/commands/feature.md b/.claude/commands/feature.md
index 94bc0e2..361920f 100644
--- a/.claude/commands/feature.md
+++ b/.claude/commands/feature.md
@@ -26,7 +26,7 @@ $ARGUMENTS
 4. Build primitive-first: one reusable primitive with its first real caller. No
    abstraction before a consumer.
 5. **Prove it.** `bin/setup` after any dependency change, then `bin/check`, which here is
-   `bundle exec rake compile && bin/rubocop --parallel && CI=1 bundle exec rspec && bin/brakeman --no-pager`.
+   `cd apps/ruby2html && bundle exec rake compile && ../../bin/rubocop --parallel . ../../bin && CI=1 bundle exec rspec && ../../bin/brakeman --no-pager`.
    Red is not a pull request: fix the cause, never silence the gate. Add the failing test
    first — a green run that never went red proves nothing.
 6. **One pull request in flight, start to finish.** Open it, watch it to merged, run
diff --git a/.claude/settings.json b/.claude/settings.json
index b36f0da..de288d1 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -77,7 +77,9 @@
       "Bash(bin/*)"
     ],
     "deny": [
-      "Read(./config/master.key)",
+      "Read(./apps/ruby2html/config/master.key)",
+      "Read(./apps/ruby2html/.env*)",
+      "Read(./apps/ruby2html/tmp/local_secret.txt)",
       "Read(./.env*)",
       "Read(./tmp/local_secret.txt)",
       "Bash(git tag *)",
diff --git a/.claude/skills/add-html-tag/SKILL.md b/.claude/skills/add-html-tag/SKILL.md
index a4b7e07..ebb1502 100644
--- a/.claude/skills/add-html-tag/SKILL.md
+++ b/.claude/skills/add-html-tag/SKILL.md
@@ -5,17 +5,17 @@ description: Add a new HTML element (standard, void, or hyphenated custom elemen
 
 # Add an HTML tag to ruby2html
 
-Tags are data: `Ruby2html::Render::HTML5_TAGS` / `VOID_ELEMENTS` in `lib/gem/ruby2html/render.rb`. At load, `define_tag(method_name, tag, void)` is called on both `Ruby2html::Native` (C) and `Ruby2html::PureRuby`. No C change is needed unless a limit is hit.
+Tags are data: `Ruby2html::Render::HTML5_TAGS` / `VOID_ELEMENTS` in `apps/ruby2html/lib/gem/ruby2html/render.rb`. At load, `define_tag(method_name, tag, void)` is called on both `Ruby2html::Native` (C) and `Ruby2html::PureRuby`. No C change is needed unless a limit is hit.
 
 ## Steps
 
 1. Add the tag as written in HTML (lowercase, hyphens allowed, e.g. `turbo-frame`) to `HTML5_TAGS`, keeping the list's ordering style. Method name = `tag.tr('-', '_')`.
 2. Void element per the HTML spec (no closing tag)? Also add it to `VOID_ELEMENTS` (renders `<tag attrs />`, ignores content and block).
-3. Limits (C, `ext/ruby2html/tag_render.c`): name must match `[a-z0-9-]` and be ≤ 32 bytes (`R2H_MAX_TAG_NAME`); at most 200 tags (`R2H_MAX_TAGS`, trampoline pool). Raising a limit is a C change: update the macros/trampoline list and recompile.
+3. Limits (C, `apps/ruby2html/ext/ruby2html/tag_render.c`): name must match `[a-z0-9-]` and be ≤ 32 bytes (`R2H_MAX_TAG_NAME`); at most 200 tags (`R2H_MAX_TAGS`, trampoline pool). Raising a limit is a C change: update the macros/trampoline list and recompile.
 4. Name clashes: the new method shadows any same-named method for code running on a `Render` or `Ruby2html::Component` (and wins over component methods/slots inside ViewComponent `html` blocks). Check `Render`/`Component` methods (`render`, `plain`, `component`, `content`, `helpers`, `output`, `current_output`, `link_to`, `image_tag`, `form_with`, `button_to`) and common Rails helpers. `TemplateCompiler` picks the tag up automatically (it reads `HTML5_TAGS`), so in `.html.rb` templates a receiverless call of that name will now be rewritten to the tag; search the demo app and specs for existing uses.
-5. Specs in `spec/gem/` inside a `RenderSpecHelper.describe_each` group (runs Native and PureRuby): content, attributes, block, escaping; void form if void.
-6. `bundle exec rake compile`, `CI=1 bundle exec rspec spec/gem`, `bundle exec rubocop lib/gem/ruby2html/render.rb`.
-7. Docs: mention notable new tags in `llms.txt` (DSL rule 1); `### Added` under `## [Unreleased]` in `CHANGELOG.md`.
+5. Specs in `apps/ruby2html/spec/gem/` inside a `RenderSpecHelper.describe_each` group (runs Native and PureRuby): content, attributes, block, escaping; void form if void.
+6. Run from `apps/ruby2html` (bundle/rake commands run there): `bundle exec rake compile`, `CI=1 bundle exec rspec spec/gem`, `bundle exec rubocop lib/gem/ruby2html/render.rb`.
+7. Docs: mention notable new tags in `apps/ruby2html/llms.txt` (DSL rule 1); `### Added` under `## [Unreleased]` in `CHANGELOG.md`.
 
 ## Notes
 
diff --git a/.claude/skills/benchmark/SKILL.md b/.claude/skills/benchmark/SKILL.md
index 58b9663..1cfbe32 100644
--- a/.claude/skills/benchmark/SKILL.md
+++ b/.claude/skills/benchmark/SKILL.md
@@ -5,13 +5,13 @@ description: Measure ruby2html rendering performance and compare before/after a
 
 # Benchmark ruby2html (before/after)
 
-Project rule: speed over memory. Perf claims need numbers from the same machine, Ruby and YJIT state.
+Project rule: speed over memory. Perf claims need numbers from the same machine, Ruby and YJIT state. Commands run from `apps/ruby2html` (the Rakefile, Gemfile and bundle config live there); from the repo root, the scripts below are `apps/ruby2html/bench/*.rb` and the request spec is `apps/ruby2html/spec/benchmarks/`.
 
 ## Tools
 
 | Command | Measures |
 |---|---|
-| `bundle exec rake bench` | compiles, runs every `bench/*.rb` |
+| `bundle exec rake bench` | compiles, runs every `apps/ruby2html/bench/*.rb` |
 | `bundle exec ruby bench/render_bench.rb` | full page render vs Phlex / Erubi, plus allocations per render |
 | `bundle exec ruby bench/tag_bench.rb` | per-tag cost for common call shapes |
 | `bundle exec ruby bench/escape_bench.rb` | escaping throughput, clean/dirty, short/long |
@@ -23,7 +23,7 @@ Variants: `--yjit` (or `RUBY_YJIT_ENABLE=1`), `RUBY2HTML_DISABLE_EXT=1` (pure Ru
 
 1. Record environment: `ruby -v` (shows `+YJIT`), `uname -m`, which variant flags were used.
 2. **Baseline** on the base revision: `git worktree add "$SCRATCH/r2h-base" <rev>` (or `git stash`), `bundle exec rake compile` there, run the chosen command, save output to the scratch dir.
-3. **Candidate**: back on the change, `bundle exec rake compile` (mandatory after `ext/` edits), identical command, save output.
+3. **Candidate**: back on the change, `bundle exec rake compile` (mandatory after `apps/ruby2html/ext/` edits), identical command, save output.
 4. Repeat each side at least twice if the delta is < 10%; overlapping benchmark-ips error bars = "no measurable change". Check allocation counts (render_bench) for regressions too.
 5. Correctness: `CI=1 bundle exec rspec`.
 6. Report a table: benchmark, before, after, ratio, error; environment line. Never round away regressions. Remove the worktree (`git worktree remove`).
diff --git a/.claude/skills/debug-render/SKILL.md b/.claude/skills/debug-render/SKILL.md
index 7ce37fc..3cac6df 100644
--- a/.claude/skills/debug-render/SKILL.md
+++ b/.claude/skills/debug-render/SKILL.md
@@ -5,24 +5,24 @@ description: Debug wrong or crashing ruby2html output - diff the C extension (Ru
 
 # Debug ruby2html rendering
 
-Two implementations exist and must match byte for byte: `Ruby2html::Native` (`ext/ruby2html/`) and `Ruby2html::PureRuby` (`lib/gem/ruby2html/render/pure_ruby.rb`). `Ruby2html::IMPLEMENTATION` says which one `Render` uses; `RUBY2HTML_DISABLE_EXT=1` forces PureRuby.
+Two implementations exist and must match byte for byte: `Ruby2html::Native` (`apps/ruby2html/ext/ruby2html/`) and `Ruby2html::PureRuby` (`apps/ruby2html/lib/gem/ruby2html/render/pure_ruby.rb`). `Ruby2html::IMPLEMENTATION` says which one `Render` uses; `RUBY2HTML_DISABLE_EXT=1` forces PureRuby.
 
 ## 1. Which side is wrong?
 
 ```bash
-bundle exec rake compile
+cd apps/ruby2html && bundle exec rake compile && cd ../..
 cat > "$SCRATCH/case.rb" <<'RUBY'
 Ruby2html::Render.new { div(class: ['a', nil], data: { x_y: 1 }) { td { 1.5 } } }.render.to_str
 RUBY
 for mode in 0 1; do
-  RUBY2HTML_DISABLE_EXT=$mode bundle exec ruby -Ilib/gem -Ilib -e 'require "ruby2html"; require "active_support"; require "active_support/core_ext/string/output_safety"
+  RUBY2HTML_DISABLE_EXT=$mode bundle exec ruby -Iapps/ruby2html/lib/gem -Iapps/ruby2html/lib -e 'require "ruby2html"; require "active_support"; require "active_support/core_ext/string/output_safety"
     out = eval(File.read(ARGV[0])); puts "#{Ruby2html::IMPLEMENTATION}: #{out.inspect} #{out.encoding}"' "$SCRATCH/case.rb"
 done
 ```
 
-(`$SCRATCH` = your scratch directory.) Drop the ActiveSupport requires to test the no-Rails path; `html_safe?` handling differs with/without it. Same-process comparison (what the specs do, see `spec/gem/render_spec_helper.rb`): `PureRuby` always gets the tag methods, so `pure = Class.new(Ruby2html::Render) { include Ruby2html::PureRuby }` renders with PureRuby while `Ruby2html::Render` uses Native: compare `pure.new(&blk).render` with `Ruby2html::Render.new(&blk).render`.
+(`$SCRATCH` = your scratch directory.) Drop the ActiveSupport requires to test the no-Rails path; `html_safe?` handling differs with/without it. Same-process comparison (what the specs do, see `apps/ruby2html/spec/gem/render_spec_helper.rb`): `PureRuby` always gets the tag methods, so `pure = Class.new(Ruby2html::Render) { include Ruby2html::PureRuby }` renders with PureRuby while `Ruby2html::Render` uses Native: compare `pure.new(&blk).render` with `Ruby2html::Render.new(&blk).render`.
 
-Decide against the documented rules (`llms.txt`, comments at the top of `content.c` / `attributes.c` / `tag_render.c`), not against whichever side "looks right". Fix the wrong side, then add the case to a `RenderSpecHelper.describe_each` group or `spec/gem/render_parity_spec.rb` (both run Native and PureRuby).
+Decide against the documented rules (`apps/ruby2html/llms.txt`, comments at the top of `content.c` / `attributes.c` / `tag_render.c`), not against whichever side "looks right". Fix the wrong side, then add the case to a `RenderSpecHelper.describe_each` group or `apps/ruby2html/spec/gem/render_parity_spec.rb` (both run Native and PureRuby).
 
 ## 2. Minimize
 
@@ -35,25 +35,25 @@ Scalar vs SIMD escape path: `RUBY2HTML_NO_SIMD=1 bundle exec rake compile` and r
 `bin/build-ext` builds the CI variants (CI runs the same commands in the `sanitizers` and `strict-ext` jobs):
 
 ```bash
-bin/build-ext --sanitize              # ASAN + UBSAN build into lib/ruby2html
+bin/build-ext --sanitize              # ASAN + UBSAN build into apps/ruby2html/lib/ruby2html
 LD_PRELOAD="$(gcc -print-file-name=libasan.so):$(gcc -print-file-name=libubsan.so)" \
-  ASAN_OPTIONS=detect_leaks=0:use_sigaltstack=0 bundle exec ruby -Ilib/gem "$SCRATCH/repro.rb"   # or: ... bundle exec rspec spec/gem
-bundle exec rake clobber && bundle exec rake compile   # ALWAYS rebuild normally afterwards
+  ASAN_OPTIONS=detect_leaks=0:use_sigaltstack=0 bundle exec ruby -Iapps/ruby2html/lib/gem "$SCRATCH/repro.rb"   # or: ... bundle exec rspec apps/ruby2html/spec/gem
+(cd apps/ruby2html && bundle exec rake clobber && bundle exec rake compile)   # ALWAYS rebuild normally afterwards
 bin/build-ext --werror                # / --cc=clang --werror: warnings as errors
 ```
 
-Without the script: `bundle exec rake compile -- --with-cflags="-fsanitize=address,undefined -fno-omit-frame-pointer -g -O1" --with-ldflags="-fsanitize=address,undefined"`.
+Without the script (run from `apps/ruby2html`): `bundle exec rake compile -- --with-cflags="-fsanitize=address,undefined -fno-omit-frame-pointer -g -O1" --with-ldflags="-fsanitize=address,undefined"`.
 
 `detect_leaks=0` is required (Ruby's own allocations look like leaks). macOS/clang: use `-fsanitize=address` and `DYLD_INSERT_LIBRARIES=$(clang -print-file-name=libclang_rt.asan_osx_dynamic.dylib)`.
 
 GC-related bugs (missing `RB_GC_GUARD`, stale `RSTRING_PTR` after the buffer grows or after a yield) often only show under GC pressure: run the repro with `GC.stress = true` (slow; keep the input tiny), or in a loop with `GC.compact` between renders.
 
-gdb: `gdb -ex run --args ruby -Ilib/gem -Ilib repro.rb`, build with `--with-cflags="-O0 -g"`.
+gdb: `gdb -ex run --args ruby -Iapps/ruby2html/lib/gem -Iapps/ruby2html/lib repro.rb`, build with `--with-cflags="-O0 -g"`.
 
 ## 4. Rails-side issues
 
 - Template output wrong but `Render.new { ... }` right: inspect the compiled source: `Ruby2html::RailsComponents::TemplateCompiler.compile(File.read(path)).source` (nil means Prism unavailable or parse error → closure fallback).
-- Helper markup outside its tag: check `rails_components/output_capture.rb` (buffer swap during the helper's block).
+- Helper markup outside its tag: check `apps/ruby2html/lib/gem/ruby2html/rails_components/output_capture.rb` (buffer swap during the helper's block).
 
 ## Done when
 
diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md
index 96ee5de..7a845d9 100644
--- a/.claude/skills/release/SKILL.md
+++ b/.claude/skills/release/SKILL.md
@@ -8,7 +8,7 @@ disable-model-invocation: true
 
 Follows `docs/release.md`. Argument: target version `X.Y.Z` or `patch|minor|major`.
 
-Merging a change to `lib/gem/ruby2html/version.rb` into `main` runs `.github/workflows/release.yml`,
+Merging a change to `apps/ruby2html/lib/gem/ruby2html/version.rb` into `main` runs `.github/workflows/release.yml`,
 which **publishes to RubyGems**, then tags and creates the GitHub release. So opening the release PR
 is safe; **merging it is the publish action**.
 
@@ -21,9 +21,10 @@ is safe; **merging it is the publish action**.
 2. **Bump**: `VERSION = 'X.Y.Z'`; CHANGELOG `## [X.Y.Z] - <today>` + empty `## [Unreleased]` + link
    reference; `bin/changelog-notes X.Y.Z` prints the section.
 3. **Refresh the issue-template versions placeholder** in `.github/ISSUE_TEMPLATE/bug_report.yml`:
-   gem version from `lib/gem/ruby2html/version.rb`, Ruby version from `.ruby-version`, Rails version
-   from `Gemfile.lock`. GitHub issue forms cannot derive the value at fill time, so it is refreshed here.
-4. **Verify**: `bundle exec rake compile`, `CI=1 bundle exec rspec`, `bundle exec rubocop`,
+   gem version from `apps/ruby2html/lib/gem/ruby2html/version.rb`, Ruby version from
+   `apps/ruby2html/.ruby-version`, Rails version from `apps/ruby2html/Gemfile.lock`.
+   GitHub issue forms cannot derive the value at fill time, so it is refreshed here.
+4. **Verify** (run from `apps/ruby2html`): `bundle exec rake compile`, `CI=1 bundle exec rspec`, `bundle exec rubocop`,
    `bundle exec rake smoke`.
 5. **PR**: branch `release/X.Y.Z`, one commit `release: X.Y.Z`, PR titled `release: X.Y.Z` with the
    changelog section as the body, containing nothing else apart from the placeholder refresh in
diff --git a/.claude/skills/review/SKILL.md b/.claude/skills/review/SKILL.md
index d0de914..50dfaad 100644
--- a/.claude/skills/review/SKILL.md
+++ b/.claude/skills/review/SKILL.md
@@ -5,9 +5,9 @@ description: Review checklist for ruby2html changes, especially ext/ (C) and the
 
 # Review a ruby2html change
 
-Scope: `git diff` (uncommitted) or `git diff main...HEAD`. Read `AGENTS.md` "Sharp edges / invariants" first. Report findings as file:line + why + fix; say explicitly which checklist sections passed.
+Scope: `git diff` (uncommitted) or `git diff main...HEAD`. Read `AGENTS.md` "Sharp edges / invariants" first. Report findings as file:line + why + fix; say explicitly which checklist sections passed. Bundle/rake/rspec commands below run from `apps/ruby2html`; from the repo root those paths are `apps/ruby2html/ext/ruby2html/` and `apps/ruby2html/spec/gem`.
 
-## C extension (`ext/ruby2html/`)
+## C extension (`apps/ruby2html/ext/ruby2html/`)
 
 - [ ] **GC safety**: every `VALUE` whose pointer (`RSTRING_PTR`, `RARRAY_CONST_PTR`) is used across a call that may allocate/yield/raise has `RB_GC_GUARD` after its last use. Temporaries from `rb_obj_as_string`, `rb_sym2str`, `rb_String`, `r2h_utf8_compatible` included.
 - [ ] **Stale pointers**: no `RSTRING_PTR(buf)` cached across `r2h_buf_reserve`, `rb_yield*`, `rb_funcall` or any append (buffer may move).
@@ -27,7 +27,7 @@ Scope: `git diff` (uncommitted) or `git diff main...HEAD`. Read `AGENTS.md` "Sha
 
 ## Parity (Native vs PureRuby)
 
-- [ ] Every rule change exists in both `ext/ruby2html/*.c` and `lib/gem/ruby2html/render/pure_ruby.rb`.
+- [ ] Every rule change exists in both `apps/ruby2html/ext/ruby2html/*.c` and `apps/ruby2html/lib/gem/ruby2html/render/pure_ruby.rb`.
 - [ ] Specs pass in both modes: `CI=1 bundle exec rspec spec/gem` and `RUBY2HTML_DISABLE_EXT=1 bundle exec rspec spec/gem`. Same exceptions too.
 - [ ] Suspicious cases diffed with the `debug-render` skill.
 
@@ -45,6 +45,6 @@ Scope: `git diff` (uncommitted) or `git diff main...HEAD`. Read `AGENTS.md` "Sha
 
 ## Hygiene
 
-- [ ] `bundle exec rubocop` clean; no Ruby syntax newer than the gemspec `required_ruby_version` floor in `lib/`.
+- [ ] `bundle exec rubocop` clean; no Ruby syntax newer than the gemspec `required_ruby_version` floor in `apps/ruby2html/lib/`.
 - [ ] CHANGELOG `## [Unreleased]` entry for user-visible changes (breaking → "Upgrading to 2.0").
-- [ ] `llms.txt` updated if user-facing behavior changed.
+- [ ] `apps/ruby2html/llms.txt` updated if user-facing behavior changed.
diff --git a/.claude/skills/upgrade-deps/SKILL.md b/.claude/skills/upgrade-deps/SKILL.md
index 5a6a29b..cba1e48 100644
--- a/.claude/skills/upgrade-deps/SKILL.md
+++ b/.claude/skills/upgrade-deps/SKILL.md
@@ -7,7 +7,7 @@ description: Upgrade ruby2html's development/demo dependencies (Rails, view_comp
 
 Patch and minor updates arrive as grouped Dependabot PRs and auto-merge when CI passes; this skill is for what is left: **major-version** bumps (Dependabot PRs that did not auto-merge, or a manual upgrade). Do not pin or list versions in docs; the lockfiles are the record.
 
-The `Gemfile` serves the demo app and specs; the gem's only runtime dependency is in `ruby2html.gemspec` (keep it minimal; `htmlbeautifier` is optional at runtime via the middleware's lazy require). Do not add runtime dependencies to the gemspec while upgrading.
+The `apps/ruby2html/Gemfile` serves the demo app and specs; the gem's only runtime dependency is in `apps/ruby2html/ruby2html.gemspec` (keep it minimal; `htmlbeautifier` is optional at runtime via the middleware's lazy require). Do not add runtime dependencies to the gemspec while upgrading. Bundler, rake, rspec and rubocop commands below run from `apps/ruby2html`; `bin/*` scripts stay at the repo root and are `../../bin/*` from there.
 
 ## Steps
 
@@ -18,8 +18,8 @@ The `Gemfile` serves the demo app and specs; the gem's only runtime dependency i
    - view layer: `view_component`, `phlex-rails`, `slim-rails`
    - test: `rspec-rails`, `capybara`, `benchmark-ips`, `faker`
    - tooling: `rubocop-rails_config`, `lefthook`, `brakeman`, `rake-compiler`
-   Edit constraints in `Gemfile`, then `bundle update <gems> --conservative`. Check `gemfiles/*.gemfile` (CI matrix gemfiles, e.g. per Rails line, and `standalone.gemfile`) for constraints that need the same change; add a gemfile for a new Rails major. For Ruby: update `.ruby-version` (most CI jobs use it); the Ruby matrix itself is generated.
-4. After each group: `bundle exec rake compile`, `CI=1 bundle exec rspec`, `RUBY2HTML_DISABLE_EXT=1 bundle exec rspec spec/gem`, `bundle exec rubocop` (new cops: autocorrect only safe ones, review the diff), `bin/brakeman --no-pager`, `bundle exec rake smoke`. Fix breakages in the demo app (`app/`, `config/`) or specs; touch `lib/gem/` only for genuine compatibility fixes and note them in CHANGELOG.
+   Edit constraints in `apps/ruby2html/Gemfile`, then `bundle update <gems> --conservative`. Check `apps/ruby2html/gemfiles/*.gemfile` (CI matrix gemfiles, e.g. per Rails line, and `standalone.gemfile`) for constraints that need the same change; add a gemfile for a new Rails major. For Ruby: update `apps/ruby2html/.ruby-version` (most CI jobs use it); the Ruby matrix itself is generated.
+4. After each group: `bundle exec rake compile`, `CI=1 bundle exec rspec`, `RUBY2HTML_DISABLE_EXT=1 bundle exec rspec spec/gem`, `bundle exec rubocop` (new cops: autocorrect only safe ones, review the diff), `../../bin/brakeman --no-pager`, `bundle exec rake smoke`. Fix breakages in the demo app (`apps/ruby2html/app/`, `apps/ruby2html/config/`) or specs; touch `apps/ruby2html/lib/gem/` only for genuine compatibility fixes and note them in CHANGELOG.
 5. Framework/view-layer upgrades: rerun benchmarks (`bundle exec rake bench`; and `bundle exec rspec spec/benchmarks/` if Rails/ViewComponent/Phlex changed, ~6 min) and compare with the baseline. Report regressions; README tables only change on request.
 6. Report: table of gem old → new, breakages fixed, test/benchmark results. CHANGELOG `### Changed` only if the gem's supported Ruby/Rails range or behavior changed.
 
diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
index 7ae04ea..f0ed513 100644
--- a/.devcontainer/Dockerfile
+++ b/.devcontainer/Dockerfile
@@ -14,7 +14,7 @@ ENV MISE_DATA_DIR=/usr/local/share/mise \
     MISE_CONFIG_DIR=/usr/local/share/mise/config \
     MISE_INSTALL_PATH=/usr/local/bin/mise \
     PATH=/usr/local/share/mise/shims:$PATH
-COPY .ruby-version /tmp/.ruby-version
+COPY apps/ruby2html/.ruby-version /tmp/.ruby-version
 RUN curl -fsSL https://mise.run | sh \
   && mise use --global "ruby@$(cat /tmp/.ruby-version)" \
   && chmod -R a+rwX /usr/local/share/mise \
diff --git a/.dz/briefs/health.md b/.dz/briefs/health.md
index 5a7b07f..72ee834 100644
--- a/.dz/briefs/health.md
+++ b/.dz/briefs/health.md
@@ -7,7 +7,7 @@ maintained so that nobody has to watch it. This covers the failures no issue or
 |---|---|---|
 | `main` is green | `gh run list --workflow ci.yml --branch main --event push --limit 1 --json conclusion,headSha` | `success` |
 | the last release published | `gh run list --workflow release.yml --limit 1 --json conclusion,displayTitle` | `success` (or no run yet) |
-| RubyGems serves `Ruby2html::VERSION` | `gem list ruby2html --remote --exact` vs `lib/gem/ruby2html/version.rb` | equal, or a release run is in flight |
+| RubyGems serves `Ruby2html::VERSION` | `gem list ruby2html --remote --exact` vs `apps/ruby2html/lib/gem/ruby2html/version.rb` | equal, or a release run is in flight |
 | benchmarks still run | `gh run list --workflow benchmark.yml --branch main --limit 1 --json conclusion` | `success` |
 | Dependabot is not stuck | `gh pr list --app dependabot --json number,createdAt` | none older than 7 days (app dependencies wait out the 14-day cooldown in `.github/dependabot.yml`; the dev-tools group is exempt via `cooldown.exclude` and opens within days) |
 | canary ran | `gh run list --workflow canary.yml --limit 1 --json conclusion,createdAt` | a run in the last 35 days; its failures are the monthly `improve` checkup's job, not an issue |
diff --git a/.dz/briefs/improve.md b/.dz/briefs/improve.md
index db4ef68..672474d 100644
--- a/.dz/briefs/improve.md
+++ b/.dz/briefs/improve.md
@@ -20,7 +20,7 @@ If no run is younger than 7 days, start one: `gh workflow run canary.yml`, and r
 2. Dependency majors Dependabot can't do (grouped bumps that failed, Rails/ViewComponent/Phlex majors
    in the demo app): `upgrade-deps` skill.
 3. Speed and memory: run `bundle exec rake bench` on `main`. Look for allocations or hot-path work
-   in `ext/ruby2html/` and `render/pure_ruby.rb`; a change counts only with before/after numbers
+   in `apps/ruby2html/ext/ruby2html/` and `apps/ruby2html/lib/gem/ruby2html/render/pure_ruby.rb`; a change counts only with before/after numbers
    from the `benchmark` skill.
 4. Correctness and safety: open issues labelled bug, then a look at escaping and parity with the
    `review` skill checklist. Every fix comes with a spec in both implementations.
diff --git a/.dz/briefs/release-due.md b/.dz/briefs/release-due.md
index 2ed24d0..dd086f3 100644
--- a/.dz/briefs/release-due.md
+++ b/.dz/briefs/release-due.md
@@ -19,11 +19,12 @@ A fix for a security advisory that a first-tier source confirms ships right away
 
 ```bash
 last=$(git describe --tags --abbrev=0 --match 'v[0-9]*' origin/main)
-git log --format='%h %cI %s' "$last"..origin/main -- 'lib/gem/**' 'ext/ruby2html/*.c' 'ext/ruby2html/*.h' 'ext/ruby2html/extconf.rb' 'ext/java/*.java' ruby2html.gemspec
+git log --format='%h %cI %s' "$last"..origin/main -- 'apps/ruby2html/lib/gem/**' 'apps/ruby2html/ext/ruby2html/*.c' 'apps/ruby2html/ext/ruby2html/*.h' 'apps/ruby2html/ext/ruby2html/extconf.rb' 'apps/ruby2html/ext/java/*.java' apps/ruby2html/ruby2html.gemspec
 ```
 
-Those paths are what `ruby2html.gemspec` ships. README, LICENSE, CHANGELOG, specs, CI, the demo app,
-benchmarks and docs ship nothing on their own.
+Those paths are what `apps/ruby2html/ruby2html.gemspec` ships; it packages README, LICENSE and
+CHANGELOG from the byte-identical copies beside it. Specs, CI, the root docs, the demo app,
+benchmarks and other docs ship nothing on their own.
 
 | Window | Do |
 |---|---|
@@ -39,7 +40,7 @@ benchmarks and docs ship nothing on their own.
 
 1. Re-check the window on fresh `main`; still needed, or stop.
 2. `## [Unreleased]` empty (a Dependabot-only window)? Add a `### Changed` line per change that ships.
-3. Bump `lib/gem/ruby2html/version.rb`; move `## [Unreleased]` under `## [<next>] - <today>`
+3. Bump `apps/ruby2html/lib/gem/ruby2html/version.rb`; move `## [Unreleased]` under `## [<next>] - <today>`
    (keep an empty `## [Unreleased]` above it) and add the `[<next>]` link at the bottom.
 4. `bundle exec rake compile && CI=1 bundle exec rspec && bundle exec rubocop && bundle exec rake smoke`.
 5. One PR titled `release: <next>`, nothing else in it. It merges on green like any PR.
diff --git a/.dz/briefs/security-release.md b/.dz/briefs/security-release.md
index 290705e..ccde304 100644
--- a/.dz/briefs/security-release.md
+++ b/.dz/briefs/security-release.md
@@ -6,10 +6,10 @@ Daily checkup on the days `release-due` does not run, fired by `schedules: secur
 
 ```bash
 last=$(git describe --tags --abbrev=0 --match 'v[0-9]*' origin/main)
-git log --format='%h %cI %s' "$last"..origin/main -- 'lib/gem/**' 'ext/ruby2html/*.c' 'ext/ruby2html/*.h' 'ext/ruby2html/extconf.rb' 'ext/java/*.java' ruby2html.gemspec
+git log --format='%h %cI %s' "$last"..origin/main -- 'apps/ruby2html/lib/gem/**' 'apps/ruby2html/ext/ruby2html/*.c' 'apps/ruby2html/ext/ruby2html/*.h' 'apps/ruby2html/ext/ruby2html/extconf.rb' 'apps/ruby2html/ext/java/*.java' apps/ruby2html/ruby2html.gemspec
 ```
 
-Those paths are what `ruby2html.gemspec` ships; look there for a commit that fixes a security advisory.
+Those paths are what `apps/ruby2html/ruby2html.gemspec` ships; look there for a commit that fixes a security advisory.
 
 ## What qualifies
 
diff --git a/.dz/maintainer/maintainer.yml b/.dz/maintainer/maintainer.yml
index bb8f311..2076a5f 100644
--- a/.dz/maintainer/maintainer.yml
+++ b/.dz/maintainer/maintainer.yml
@@ -13,7 +13,7 @@
 #
 # Each week the `release-due` checkup judges whether a release is needed and opens a release PR when
 # so, and merging it IS the release (.github/workflows/release.yml publishes when
-# lib/gem/ruby2html/version.rb changes on main). Dependabot PRs merge through this agent only:
+# apps/ruby2html/lib/gem/ruby2html/version.rb changes on main). Dependabot PRs merge through this agent only:
 # there is no second merger (no GitHub auto-merge workflow) that would skip its review.
 #
 # The gate is the repository, not this file: CI's aggregate "CI OK" check. Verify the ruleset with
@@ -38,7 +38,7 @@ triage:
     - "A runtime dependency in the gemspec"
     - "Backwards-compatibility shims, dead-code comments, or speculative abstractions"
     - "Hardcoded version lists or benchmark numbers in docs (CI generates the matrices and posts benchmarks)"
-    - "Outside changes to CI, release or publish automation (.github/, bin/, Rakefile release tasks, gemspec, Ruby2html::VERSION): owner only. Dependency-bot bumps are not covered: merge those on green"
+    - "Outside changes to CI, release or publish automation (.github/, bin/, apps/ruby2html/Rakefile release tasks, apps/ruby2html/ruby2html.gemspec, Ruby2html::VERSION): owner only. Dependency-bot bumps are not covered: merge those on green"
 
 handoff:
   mode: fleet
@@ -79,17 +79,17 @@ review:
     dedupe: true
   path_filters: []
   path_instructions:
-    - path: "ext/ruby2html/**"
+    - path: "apps/ruby2html/ext/ruby2html/**"
       instructions: >-
         C extension hot path. Check GC safety (RB_GC_GUARD after the last use of a VALUE whose
         pointer is read across an allocating call), buffer sizing and re-reading RSTRING_PTR after
-        growth, escaping correctness, and that lib/gem/ruby2html/render/pure_ruby.rb got the same
+        growth, escaping correctness, and that apps/ruby2html/lib/gem/ruby2html/render/pure_ruby.rb got the same
         change (byte-identical output). Speed claims need before/after numbers.
-    - path: "lib/gem/ruby2html/render/pure_ruby.rb"
+    - path: "apps/ruby2html/lib/gem/ruby2html/render/pure_ruby.rb"
       instructions: >-
-        Must stay byte-identical to the C extension (ext/ruby2html). Any rule change needs the
+        Must stay byte-identical to the C extension (apps/ruby2html/ext/ruby2html). Any rule change needs the
         matching C change and specs in a RenderSpecHelper.describe_each group.
-    - path: "lib/gem/ruby2html/rails_components/**"
+    - path: "apps/ruby2html/lib/gem/ruby2html/rails_components/**"
       instructions: >-
         Escaping is a security boundary: helper output must be html_safe-aware, never
         double-escaped or under-escaped. Template rewrites must insert text only (no newlines).
diff --git a/.dz/maintainer/reviewer.md b/.dz/maintainer/reviewer.md
index a8981c1..80d9710 100644
--- a/.dz/maintainer/reviewer.md
+++ b/.dz/maintainer/reviewer.md
@@ -7,7 +7,7 @@
 
 ## Stack
 
-Ruby + Bundler. The gate is `bin/check` (`bundle exec rake compile && bin/rubocop --parallel && CI=1 bundle exec rspec && bin/brakeman --no-pager`): a change that does not pass it is not proven, whatever its description says.
+Ruby + Bundler. The gate is `bin/check` (`cd apps/ruby2html && bundle exec rake compile && ../../bin/rubocop --parallel . ../../bin && CI=1 bundle exec rspec && ../../bin/brakeman --no-pager`): a change that does not pass it is not proven, whatever its description says.
 
 ## Review conventions
 
diff --git a/.gitattributes b/.gitattributes
index d013c25..4736899 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -1,12 +1,12 @@
 # See https://git-scm.com/docs/gitattributes for more about git attribute files.
 
 # Mark the database schema as having been generated.
-db/schema.rb linguist-generated
+apps/ruby2html/db/schema.rb linguist-generated
 
 # Mark any vendored files as having been vendored.
-vendor/* linguist-vendored
-config/credentials/*.yml.enc diff=rails_credentials
-config/credentials.yml.enc diff=rails_credentials
+apps/ruby2html/vendor/* linguist-vendored
+apps/ruby2html/config/credentials/*.yml.enc diff=rails_credentials
+apps/ruby2html/config/credentials.yml.enc diff=rails_credentials
 
 # C extension sources: C-aware diffs
 *.c diff=cpp
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index f29a93b..1733556 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -43,8 +43,9 @@ body:
       description: "ruby2html, ruby -v (with/without YJIT), Rails, ViewComponent, OS/arch"
       # GitHub issue forms cannot derive values at fill time (static label/description/
       # placeholder/value only), so this placeholder is refreshed by hand: on every
-      # release, take the gem version from lib/gem/ruby2html/version.rb, the Ruby version
-      # from .ruby-version and the Rails version from Gemfile.lock (see docs/release.md).
+      # release, take the gem version from apps/ruby2html/lib/gem/ruby2html/version.rb,
+      # the Ruby version from apps/ruby2html/.ruby-version and the Rails version from
+      # apps/ruby2html/Gemfile.lock (see docs/release.md).
       placeholder: "ruby2html 2.1.0, ruby 4.0.9 +YJIT, Rails 8.1.4.1, x86_64-linux"
     validations:
       required: true
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index c83c63c..8f71ac4 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -1,5 +1,5 @@
 blank_issues_enabled: true
 contact_links:
   - name: Usage guide (also for AI agents)
-    url: https://github.com/sebyx07/ruby2html/blob/main/llms.txt
+    url: https://github.com/sebyx07/ruby2html/blob/main/apps/ruby2html/llms.txt
     about: DSL rules, escaping, components, forms and common pitfalls.
diff --git a/.github/ISSUE_TEMPLATE/performance.yml b/.github/ISSUE_TEMPLATE/performance.yml
index 96e7d1e..0042f72 100644
--- a/.github/ISSUE_TEMPLATE/performance.yml
+++ b/.github/ISSUE_TEMPLATE/performance.yml
@@ -6,7 +6,7 @@ body:
     id: bench
     attributes:
       label: Benchmark and results
-      description: Command run (bench/ script or spec/benchmarks), before/after i/s, error margins.
+      description: Command run (apps/ruby2html/bench/ script or apps/ruby2html/spec/benchmarks), before/after i/s, error margins.
       render: text
     validations:
       required: true
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 5689611..0da023a 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -2,7 +2,7 @@ version: 2
 # Weekly, grouped updates. The developerz.ai maintainer agent reviews them and
 # merges on a green "CI OK" (.dz/maintainer/maintainer.yml); it is the only merger.
 #
-# gemfiles/ needs no entry: the matrix gemfiles have no lockfiles and use
+# apps/ruby2html/gemfiles/ needs no entry: the matrix gemfiles have no lockfiles and use
 # ~> MAJOR.MINOR.0 / >= constraints, so every CI run resolves the newest
 # compatible gems, and CI derives the Ruby and Rails matrices dynamically.
 #
@@ -15,7 +15,7 @@ version: 2
 # exclude list mirrors the dev-tools group patterns below - keep both in sync.
 updates:
   - package-ecosystem: bundler
-    directory: /
+    directory: /apps/ruby2html
     schedule:
       interval: weekly
       day: monday
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 1859764..c2d57a3 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -8,17 +8,17 @@
 
 ## Checklist
 
-- [ ] `bundle exec rake compile` (no new C warnings, if `ext/` changed)
-- [ ] `CI=1 bundle exec rspec` passes; new behavior has specs (`spec/gem/` for the renderer)
+- [ ] `bundle exec rake compile` (no new C warnings, if `apps/ruby2html/ext/` changed)
+- [ ] `CI=1 bundle exec rspec` passes; new behavior has specs (`apps/ruby2html/spec/gem/` for the renderer)
 - [ ] `bundle exec rubocop` passes
 - [ ] Escaping unchanged, or the change is intentional and covered by specs
-- [ ] C change mirrored in `lib/gem/ruby2html/render/pure_ruby.rb` (byte-identical output; parity specs pass)
+- [ ] C change mirrored in `apps/ruby2html/lib/gem/ruby2html/render/pure_ruby.rb` (byte-identical output; parity specs pass)
 - [ ] `CHANGELOG.md` `## [Unreleased]` updated for user-visible changes
-- [ ] `llms.txt` / `AGENTS.md` updated if DSL behavior or commands changed
+- [ ] `apps/ruby2html/llms.txt` / `AGENTS.md` updated if DSL behavior or commands changed
 
 ## Performance (if relevant)
 
-<!-- Before/after from bench/ or spec/benchmarks/, same machine. Include `ruby -v` (YJIT?). -->
+<!-- Before/after from apps/ruby2html/bench/ or apps/ruby2html/spec/benchmarks/, same machine. Include `ruby -v` (YJIT?). -->
 
 | Benchmark | Before (i/s) | After (i/s) | Ratio |
 |---|---|---|---|
diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml
index ffea639..218d459 100644
--- a/.github/workflows/benchmark.yml
+++ b/.github/workflows/benchmark.yml
@@ -40,9 +40,15 @@ jobs:
     env:
       CI: '1'
       BENCH_TIME: '2'
+      BUNDLE_GEMFILE: ${{ github.workspace }}/apps/ruby2html/Gemfile
+    defaults:
+      run:
+        working-directory: apps/ruby2html
     steps:
       - uses: actions/checkout@v7
 
+      # setup-ruby reads version files only from the repo root; the root
+      # .ruby-version is a symlink to apps/ruby2html/.ruby-version.
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: .ruby-version
@@ -51,7 +57,7 @@ jobs:
       - run: bundle exec rake compile
 
       - name: Prepare the demo app database
-        run: bin/rails db:prepare
+        run: ../../bin/rails db:prepare
         env:
           RAILS_ENV: test
 
@@ -59,7 +65,7 @@ jobs:
       # the Rails comparison (ERB, Slim, Phlex, ViewComponent + ruby2html,
       # .html.rb templates, Ruby2html::Component) over the /benchmark/* routes.
       - name: Run benchmarks
-        run: bundle exec bin/bench-report run bench-results.json
+        run: bundle exec ../../bin/bench-report run ../../bench-results.json
 
       - name: Download main baseline
         if: github.event_name == 'pull_request'
@@ -79,10 +85,10 @@ jobs:
 
       - name: Render summary
         run: |
-          args=(bench-results.json)
+          args=(../../bench-results.json)
           [ -f baseline/bench-results.json ] && args+=(baseline/bench-results.json)
-          ruby bin/bench-report markdown "${args[@]}" > bench.md
-          cat bench.md >> "$GITHUB_STEP_SUMMARY"
+          ruby ../../bin/bench-report markdown "${args[@]}" > ../../bench.md
+          cat ../../bench.md >> "$GITHUB_STEP_SUMMARY"
 
       - uses: actions/upload-artifact@v7
         with:
diff --git a/.github/workflows/canary.yml b/.github/workflows/canary.yml
index 8797afc..fe34ac4 100644
--- a/.github/workflows/canary.yml
+++ b/.github/workflows/canary.yml
@@ -21,7 +21,10 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 20
     env:
-      BUNDLE_GEMFILE: ${{ github.workspace }}/gemfiles/standalone.gemfile
+      BUNDLE_GEMFILE: ${{ github.workspace }}/apps/ruby2html/gemfiles/standalone.gemfile
+    defaults:
+      run:
+        working-directory: apps/ruby2html
     steps:
       - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
@@ -31,7 +34,7 @@ jobs:
       - name: Compile + RSpec (spec/gem without Rails)
         run: bundle exec rake spec:standalone
       - name: Build gem, install into temp GEM_HOME, render without Rails
-        run: ruby bin/gem-smoke
+        run: ruby ../../bin/gem-smoke
 
   rails-edge:
     name: Rails edge
@@ -39,9 +42,14 @@ jobs:
     timeout-minutes: 20
     env:
       RAILS_VERSION: edge
-      BUNDLE_GEMFILE: ${{ github.workspace }}/gemfiles/rails.gemfile
+      BUNDLE_GEMFILE: ${{ github.workspace }}/apps/ruby2html/gemfiles/rails.gemfile
+    defaults:
+      run:
+        working-directory: apps/ruby2html
     steps:
       - uses: actions/checkout@v7
+      # setup-ruby reads version files only from the repo root; the root
+      # .ruby-version is a symlink to apps/ruby2html/.ruby-version.
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: .ruby-version
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 302be4d..b5078a2 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -35,18 +35,30 @@ jobs:
     name: Lint / RuboCop
     runs-on: ubuntu-latest
     timeout-minutes: 10
+    env:
+      BUNDLE_GEMFILE: ${{ github.workspace }}/apps/ruby2html/Gemfile
+    defaults:
+      run:
+        working-directory: apps/ruby2html
     steps:
       - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
+        # setup-ruby reads version files only from the repo root; the root
+        # .ruby-version is a symlink to apps/ruby2html/.ruby-version (the single
+        # source of the dev Ruby version). A nested path here would be parsed as
+        # an "engine-version" string and fail with "Unknown engine".
         with:
           ruby-version: .ruby-version
           bundler-cache: true
-      - run: bin/rubocop --parallel
+      - run: ../../bin/rubocop --parallel . ../../bin
 
   audit:
     name: Security / bundle-audit
     runs-on: ubuntu-latest
     timeout-minutes: 10
+    defaults:
+      run:
+        working-directory: apps/ruby2html
     steps:
       - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
@@ -61,6 +73,11 @@ jobs:
     name: Rails app / full suite + Brakeman
     runs-on: ubuntu-latest
     timeout-minutes: 25
+    env:
+      BUNDLE_GEMFILE: ${{ github.workspace }}/apps/ruby2html/Gemfile
+    defaults:
+      run:
+        working-directory: apps/ruby2html
     steps:
       - uses: actions/checkout@v7
       # ubuntu runners ship gcc/make: no apt build-essential step needed.
@@ -72,7 +89,7 @@ jobs:
       - name: RSpec (features, gem, benchmarks)
         run: bundle exec rspec
       - name: Brakeman
-        run: bin/brakeman --no-pager
+        run: ../../bin/brakeman --no-pager
 
   ruby-versions:
     name: Matrix / Ruby versions
@@ -96,7 +113,10 @@ jobs:
           - ruby: head # monthly in canary.yml
     env:
       # No Rails and no lockfile: resolves on every Ruby, old and new.
-      BUNDLE_GEMFILE: ${{ github.workspace }}/gemfiles/standalone.gemfile
+      BUNDLE_GEMFILE: ${{ github.workspace }}/apps/ruby2html/gemfiles/standalone.gemfile
+    defaults:
+      run:
+        working-directory: apps/ruby2html
     steps:
       - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
@@ -117,6 +137,11 @@ jobs:
         include:
           - { name: Linux arm64 (gcc), os: ubuntu-24.04-arm }
           - { name: macOS arm64 (clang), os: macos-latest }
+    env:
+      BUNDLE_GEMFILE: ${{ github.workspace }}/apps/ruby2html/Gemfile
+    defaults:
+      run:
+        working-directory: apps/ruby2html
     steps:
       - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
@@ -136,6 +161,11 @@ jobs:
       fail-fast: false
       matrix:
         cc: [gcc, clang]
+    env:
+      BUNDLE_GEMFILE: ${{ github.workspace }}/apps/ruby2html/Gemfile
+    defaults:
+      run:
+        working-directory: apps/ruby2html
     steps:
       - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
@@ -143,7 +173,7 @@ jobs:
           ruby-version: .ruby-version
           bundler-cache: true
       - name: Build with warnings as errors
-        run: bin/build-ext --cc=${{ matrix.cc }} --werror
+        run: ../../bin/build-ext --cc=${{ matrix.cc }} --werror
       - name: RSpec (spec/gem) against that build
         run: bundle exec rake spec:gem
         env:
@@ -153,6 +183,11 @@ jobs:
     name: C ext / ASAN + UBSAN
     runs-on: ubuntu-latest
     timeout-minutes: 20
+    env:
+      BUNDLE_GEMFILE: ${{ github.workspace }}/apps/ruby2html/Gemfile
+    defaults:
+      run:
+        working-directory: apps/ruby2html
     steps:
       - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
@@ -160,7 +195,7 @@ jobs:
           ruby-version: .ruby-version
           bundler-cache: true
       - name: Build instrumented extension
-        run: bin/build-ext --sanitize
+        run: ../../bin/build-ext --sanitize
       - name: RSpec (spec/gem) with sanitizer runtimes preloaded
         run: |
           LD_PRELOAD="$(gcc -print-file-name=libasan.so):$(gcc -print-file-name=libubsan.so)"
@@ -176,6 +211,11 @@ jobs:
     name: Pure Ruby fallback / RUBY2HTML_DISABLE_EXT=1
     runs-on: ubuntu-latest
     timeout-minutes: 15
+    env:
+      BUNDLE_GEMFILE: ${{ github.workspace }}/apps/ruby2html/Gemfile
+    defaults:
+      run:
+        working-directory: apps/ruby2html
     steps:
       - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
@@ -198,7 +238,10 @@ jobs:
         ruby: [jruby, truffleruby] # setup-ruby aliases for the latest releases
     env:
       # rspec + activesupport + htmlbeautifier only: no Rails, no sqlite3.
-      BUNDLE_GEMFILE: ${{ github.workspace }}/gemfiles/standalone.gemfile
+      BUNDLE_GEMFILE: ${{ github.workspace }}/apps/ruby2html/gemfiles/standalone.gemfile
+    defaults:
+      run:
+        working-directory: apps/ruby2html
     steps:
       - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
@@ -212,7 +255,7 @@ jobs:
       # On JRuby this builds and renders from the -java gem (jar inside); on
       # TruffleRuby the pure-Ruby gem.
       - name: Packaged gem installs and renders
-        run: bundle exec ruby bin/gem-smoke
+        run: bundle exec ruby ../../bin/gem-smoke
 
   rails-versions:
     name: Matrix / Rails versions
@@ -220,11 +263,14 @@ jobs:
     timeout-minutes: 5
     outputs:
       versions: ${{ steps.versions.outputs.versions }}
+    defaults:
+      run:
+        working-directory: apps/ruby2html
     steps:
       - uses: actions/checkout@v7
       - id: versions
         # Every stable Rails MAJOR.MINOR >= 7.2 (the demo app's floor), from rubygems.org.
-        run: echo "versions=$(ruby bin/rails-versions 7.2)" >> "$GITHUB_OUTPUT"
+        run: echo "versions=$(ruby ../../bin/rails-versions 7.2)" >> "$GITHUB_OUTPUT"
 
   rails:
     name: Rails ${{ matrix.rails }}
@@ -237,7 +283,10 @@ jobs:
         rails: ${{ fromJSON(needs.rails-versions.outputs.versions) }} # edge: monthly in canary.yml
     env:
       RAILS_VERSION: ${{ matrix.rails }}
-      BUNDLE_GEMFILE: ${{ github.workspace }}/gemfiles/rails.gemfile
+      BUNDLE_GEMFILE: ${{ github.workspace }}/apps/ruby2html/gemfiles/rails.gemfile
+    defaults:
+      run:
+        working-directory: apps/ruby2html
     steps:
       - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
@@ -261,6 +310,9 @@ jobs:
         ruby: ${{ fromJSON(needs.ruby-versions.outputs.versions) }}
         exclude:
           - ruby: head # monthly in canary.yml
+    defaults:
+      run:
+        working-directory: apps/ruby2html
     steps:
       - uses: actions/checkout@v7
       # No Bundler on purpose: the gem must build and install with plain RubyGems.
@@ -269,7 +321,7 @@ jobs:
           ruby-version: ${{ matrix.ruby }}
           bundler: none
       - name: Build gem, install into temp GEM_HOME, render without Rails
-        run: ruby bin/gem-smoke
+        run: ruby ../../bin/gem-smoke
 
   ci-ok:
     name: CI OK
@@ -279,6 +331,9 @@ jobs:
     needs: [lint, audit, test, gem-specs, native, strict-ext, sanitizers, fallback, engines, rails, package]
     runs-on: ubuntu-latest
     timeout-minutes: 5
+    # No checkout and no working-directory here: it only aggregates results, and a
+    # defaults working-directory with no checkout kills bash before the step starts
+    # ("No such file or directory" for apps/ruby2html).
     steps:
       - name: All required jobs passed
         env:
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 7f04f5b..c5665bd 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,6 +1,6 @@
 name: Release
 
-# Merging a version bump is the release: when lib/gem/ruby2html/version.rb
+# Merging a version bump is the release: when apps/ruby2html/lib/gem/ruby2html/version.rb
 # changes on main and no tag v<VERSION> exists yet, this verifies, publishes the
 # gem, then creates the tag and the GitHub release from CHANGELOG.md. Never tag
 # or `gem push` by hand. (The developerz.ai agent opens the release PR: see
@@ -12,7 +12,7 @@ name: Release
 on:
   push:
     branches: [main]
-    paths: ['lib/gem/ruby2html/version.rb']
+    paths: ['apps/ruby2html/lib/gem/ruby2html/version.rb']
   workflow_dispatch:
 
 concurrency:
@@ -31,12 +31,13 @@ jobs:
       tag: ${{ steps.v.outputs.tag }}
       due: ${{ steps.v.outputs.due }}
     steps:
+      # runs at the repo root: the require path in the step below is root-relative
       - uses: actions/checkout@v7
         with:
           fetch-depth: 0
       - id: v
         run: |
-          version=$(ruby -e 'require "./lib/gem/ruby2html/version"; print Ruby2html::VERSION')
+          version=$(ruby -e 'require "./apps/ruby2html/lib/gem/ruby2html/version"; print Ruby2html::VERSION')
           tag="v$version"
           echo "tag=$tag" >> "$GITHUB_OUTPUT"
           if git rev-parse -q --verify "refs/tags/$tag" >/dev/null; then
@@ -52,9 +53,16 @@ jobs:
     if: needs.version.outputs.due == 'true'
     runs-on: ubuntu-latest
     timeout-minutes: 20
+    env:
+      BUNDLE_GEMFILE: ${{ github.workspace }}/apps/ruby2html/Gemfile
+    defaults:
+      run:
+        working-directory: apps/ruby2html
     steps:
       - uses: actions/checkout@v7
 
+      # setup-ruby reads version files only from the repo root; the root
+      # .ruby-version is a symlink to apps/ruby2html/.ruby-version.
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: .ruby-version
@@ -63,7 +71,7 @@ jobs:
       - name: CHANGELOG has a section for this version
         env:
           TAG: ${{ needs.version.outputs.tag }}
-        run: bin/changelog-notes "$TAG" > /dev/null
+        run: ../../bin/changelog-notes "$TAG" > /dev/null
 
       - name: Compile C extension
         run: bundle exec rake compile
@@ -72,7 +80,7 @@ jobs:
         run: bundle exec rspec
 
       - name: RuboCop
-        run: bin/rubocop --parallel
+        run: ../../bin/rubocop --parallel
 
       - name: Build gem + standalone install smoke test
         run: bundle exec rake smoke
@@ -84,7 +92,10 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 15
     env:
-      BUNDLE_GEMFILE: ${{ github.workspace }}/gemfiles/standalone.gemfile
+      BUNDLE_GEMFILE: ${{ github.workspace }}/apps/ruby2html/gemfiles/standalone.gemfile
+    defaults:
+      run:
+        working-directory: apps/ruby2html
     steps:
       - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
@@ -96,13 +107,13 @@ jobs:
       - name: Compile Java escaper
         run: bundle exec rake compile
       - name: Build + install + render the -java gem
-        run: bundle exec ruby bin/gem-smoke
+        run: bundle exec ruby ../../bin/gem-smoke
       - name: Build the -java gem for publishing
         run: gem build ruby2html.gemspec
       - uses: actions/upload-artifact@v7
         with:
           name: java-gem
-          path: ruby2html-*-java.gem
+          path: apps/ruby2html/ruby2html-*-java.gem
           retention-days: 7
           if-no-files-found: error
 
@@ -115,6 +126,9 @@ jobs:
     permissions:
       contents: write # create the tag + GitHub release
       id-token: write # RubyGems trusted publishing (OIDC)
+    defaults:
+      run:
+        working-directory: apps/ruby2html
     steps:
       - uses: actions/checkout@v7
         with:
@@ -124,10 +138,15 @@ jobs:
         with:
           ruby-version: .ruby-version
 
+      # `defaults.run.working-directory` applies to `run` steps only, never to
+      # an action step, so `path` is spelled out absolutely here: the artifact
+      # lands next to the CRuby gem built below (apps/ruby2html), and every
+      # push/asset glob in this job is relative to that directory.
       - name: Download the JRuby-built -java gem
         uses: actions/download-artifact@v8
         with:
           name: java-gem
+          path: ${{ github.workspace }}/apps/ruby2html
 
       - name: Exchange the OIDC token for RubyGems credentials
         uses: rubygems/configure-rubygems-credentials@v2.1.0
@@ -146,5 +165,5 @@ jobs:
           GH_TOKEN: ${{ github.token }}
           TAG: ${{ needs.version.outputs.tag }}
         run: |
-          bin/changelog-notes "$TAG" > release-notes.md
+          ../../bin/changelog-notes "$TAG" > release-notes.md
           gh release create "$TAG" ruby2html-*.gem --title "$TAG" --target "$GITHUB_SHA" --notes-file release-notes.md
diff --git a/.gitignore b/.gitignore
index f9ec751..b7d4668 100644
--- a/.gitignore
+++ b/.gitignore
@@ -114,3 +114,60 @@ CLAUDE.local.md
 # (staged CI logs, run artifacts, run provenance). Written BY the agent FOR the
 # agent, cleared and rewritten on every run; never repo content.
 tmp/dz/
+
+# --- The app + gem moved under apps/ruby2html: every rule above is kept
+# verbatim; where a root anchor became a no-op the rule is re-anchored here. ---
+/apps/ruby2html/.bundle
+
+# Environment files (except templates).
+/apps/ruby2html/.env*
+!/apps/ruby2html/.env*.erb
+
+# Logfiles and tempfiles.
+/apps/ruby2html/log/*
+/apps/ruby2html/tmp/*
+!/apps/ruby2html/log/.keep
+!/apps/ruby2html/tmp/.keep
+
+# Pidfiles, but keep the directory.
+/apps/ruby2html/tmp/pids/*
+!/apps/ruby2html/tmp/pids/
+!/apps/ruby2html/tmp/pids/.keep
+
+# Storage (uploaded files in development and any SQLite databases).
+/apps/ruby2html/storage/*
+!/apps/ruby2html/storage/.keep
+/apps/ruby2html/tmp/storage/*
+!/apps/ruby2html/tmp/storage/
+!/apps/ruby2html/tmp/storage/.keep
+
+/apps/ruby2html/public/assets
+
+# Master key for decrypting credentials and more.
+/apps/ruby2html/config/master.key
+/apps/ruby2html/config/credentials/*.key
+
+# Gem packaging (rake build / rake build:checksum) and release workflow output
+/apps/ruby2html/pkg/
+/apps/ruby2html/checksums/
+/apps/ruby2html/release-notes.md
+
+# C extension build artifacts (rake compile builds in tmp/, extconf in-place builds)
+/apps/ruby2html/ext/ruby2html/Makefile
+/apps/ruby2html/ext/ruby2html/mkmf.log
+/apps/ruby2html/ext/ruby2html/extconf.h
+
+# Ruby tooling
+/apps/ruby2html/coverage/
+/apps/ruby2html/.yardoc/
+/apps/ruby2html/doc/
+/apps/ruby2html/vendor/bundle/
+/apps/ruby2html/.rspec_status
+/apps/ruby2html/spec/examples.txt
+
+# Profiling / benchmark output
+/apps/ruby2html/bench/results/
+/apps/ruby2html/profile/
+
+# Matrix gemfiles resolve fresh on every CI run; their lockfiles are not committed.
+/apps/ruby2html/gemfiles/*.lock
diff --git a/.ruby-version b/.ruby-version
deleted file mode 100644
index 7919852..0000000
--- a/.ruby-version
+++ /dev/null
@@ -1 +0,0 @@
-4.0.9
diff --git a/.ruby-version b/.ruby-version
new file mode 120000
index 0000000..eee68c1
--- /dev/null
+++ b/.ruby-version
@@ -0,0 +1 @@
+apps/ruby2html/.ruby-version
\ No newline at end of file
diff --git a/AGENTS.md b/AGENTS.md
index d6d99f8..53bb657 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,27 +2,27 @@
 
 Single source of truth for AI coding agents (Claude Code, Codex, Cursor, Copilot, ...) working **on** this repo. `CLAUDE.md` is a symlink to this file: edit only `AGENTS.md`; there are no other per-tool instruction files.
 
-Writing ruby2html templates/components (here or in a user app)? Load [`llms.txt`](llms.txt) — the complete user reference (DSL, attributes, Rails, components, forms, API, pitfalls). Internals: [`docs/architecture.md`](docs/architecture.md). Releases: [`docs/release.md`](docs/release.md).
+Writing ruby2html templates/components (here or in a user app)? Load [`llms.txt`](apps/ruby2html/llms.txt) — the complete user reference (DSL, attributes, Rails, components, forms, API, pitfalls). Internals: [`docs/architecture.md`](docs/architecture.md). Releases: [`docs/release.md`](docs/release.md).
 
 ## Stack
 
-`ruby2html` (RubyGems; version in `lib/gem/ruby2html/version.rb`) renders HTML from a Ruby block DSL; the repo is both the gem and a Rails demo app.
+`ruby2html` (RubyGems; version in `apps/ruby2html/lib/gem/ruby2html/version.rb`) renders HTML from a Ruby block DSL; the repo is both the gem and a Rails demo app.
 
 | Part | Path | Notes |
 |---|---|---|
-| Gem (Ruby) | `lib/gem/ruby2html.rb`, `lib/gem/ruby2html/**` | Packaged; `spec.require_paths = ['lib/gem']`; no runtime dependencies |
-| C extension | `ext/ruby2html/*.{c,h}`, `extconf.rb` | `Ruby2html::Native` (CRuby only). `rake compile` → `lib/ruby2html/ruby2html.so` (gitignored, found by `render.rb` via `require_relative`); installed gems get it under `lib/gem/ruby2html/` |
-| Pure-Ruby twin | `lib/gem/ruby2html/render/pure_ruby.rb` | `Ruby2html::PureRuby` — used when the `.so` is missing (JRuby, failed build), on TruffleRuby (pure Ruby beats Sulong there), or with `RUBY2HTML_DISABLE_EXT=1` |
-| Java escaper (JRuby) | `ext/java/Ruby2htmlJrubyService.java` | `Ruby2html::JavaNative.escape` (byte-level HTML escape, the hot path); JRuby's only native code; `PureRuby.escape` uses it when present. `rake compile` on JRuby → `lib/gem/ruby2html/ruby2html_jruby.jar` (gitignored); shipped in the `-java` platform gem |
-| Demo Rails app | `app/`, `config/`, `db/` | Not packaged; loads the gem via `require_relative '../lib/gem/ruby2html'` |
-| Specs | `spec/gem/` (renderer, attributes, escaping, `render_parity_spec.rb`; `render_spec_helper.rb` runs each group against Native **and** PureRuby in one process), `spec/gem/rails/` (handler, compiler, components, middleware), `spec/features/`, `spec/benchmarks/` | Rails-booting via `spec/rails_helper.rb`; `rake spec:standalone` runs `spec/gem` minus `rails/` without Rails |
-| Benchmarks | `bench/*.rb` (standalone), `spec/benchmarks/requests_spec.rb` (request-level vs ERB/Slim/Phlex) | |
+| Gem (Ruby) | `apps/ruby2html/lib/gem/ruby2html.rb`, `apps/ruby2html/lib/gem/ruby2html/**` | Packaged; `spec.require_paths = ['lib/gem']`; no runtime dependencies |
+| C extension | `apps/ruby2html/ext/ruby2html/*.{c,h}`, `apps/ruby2html/ext/ruby2html/extconf.rb` | `Ruby2html::Native` (CRuby only). `rake compile` → `apps/ruby2html/lib/ruby2html/ruby2html.so` (gitignored, found by `render.rb` via `require_relative`); installed gems get it under `lib/gem/ruby2html/` |
+| Pure-Ruby twin | `apps/ruby2html/lib/gem/ruby2html/render/pure_ruby.rb` | `Ruby2html::PureRuby` — used when the `.so` is missing (JRuby, failed build), on TruffleRuby (pure Ruby beats Sulong there), or with `RUBY2HTML_DISABLE_EXT=1` |
+| Java escaper (JRuby) | `apps/ruby2html/ext/java/Ruby2htmlJrubyService.java` | `Ruby2html::JavaNative.escape` (byte-level HTML escape, the hot path); JRuby's only native code; `PureRuby.escape` uses it when present. `rake compile` on JRuby → `apps/ruby2html/lib/gem/ruby2html/ruby2html_jruby.jar` (gitignored); shipped in the `-java` platform gem |
+| Demo Rails app | `apps/ruby2html/app/`, `apps/ruby2html/config/`, `apps/ruby2html/db/` | Not packaged; loads the gem via `require_relative '../lib/gem/ruby2html'` |
+| Specs | `apps/ruby2html/spec/gem/` (renderer, attributes, escaping, `render_parity_spec.rb`; `render_spec_helper.rb` runs each group against Native **and** PureRuby in one process), `apps/ruby2html/spec/gem/rails/` (handler, compiler, components, middleware), `apps/ruby2html/spec/features/`, `apps/ruby2html/spec/benchmarks/` | Rails-booting via `apps/ruby2html/spec/rails_helper.rb`; `rake spec:standalone` runs `spec/gem` minus `rails/` without Rails |
+| Benchmarks | `apps/ruby2html/bench/*.rb` (standalone), `apps/ruby2html/spec/benchmarks/requests_spec.rb` (request-level vs ERB/Slim/Phlex) | |
 | Scripts | `bin/gem-smoke`, `bin/changelog-notes`, `bin/build-ext`, `bin/audit-advisories` | Packaging smoke test; print a CHANGELOG section; CI-style extension builds (`--werror`, `--cc=clang`, `--sanitize`); audit one resolved lockfile against the Ruby advisory database (`bundle-audit check --update --gemfile-lock <lockfile>`; exits non-zero on an advisory, except the reviewed advisories the script accepts, scoped to the exact reviewed version the lockfile resolves) |
 
 - Supported: all maintained CRuby versions (>= 3.1, gemspec floor; CI tracks the official list — currently 3.3, 3.4, 4.0), JRuby (pure Ruby + the Java escaper), TruffleRuby (pure Ruby), Rails 7.2+.
-- Dev Ruby: `.ruby-version` (latest stable). The CRuby CI matrix is generated automatically from the maintained-versions list, so a new release (e.g. a new 4.x) joins CI with no edit.
-- rubocop `TargetRubyVersion` matches the floor (no newer syntax in `lib/`).
-- Dependency versions: `Gemfile.lock` and `gemfiles/*.gemfile` (CI matrix gemfiles, unlocked).
+- Dev Ruby: `apps/ruby2html/.ruby-version` (latest stable). The root `.ruby-version` is a symlink to it — `ruby/setup-ruby` reads version files only from the repo root, so CI jobs pass `ruby-version: .ruby-version` (a nested path there is parsed as an "engine-version" string and fails). The CRuby CI matrix is generated automatically from the maintained-versions list, so a new release (e.g. a new 4.x) joins CI with no edit.
+- rubocop `TargetRubyVersion` matches the floor (no newer syntax in `apps/ruby2html/lib/`).
+- Dependency versions: `apps/ruby2html/Gemfile.lock` and `apps/ruby2html/gemfiles/*.gemfile` (CI matrix gemfiles, unlocked).
 
 ## Non-negotiables
 
@@ -34,7 +34,7 @@ Writing ruby2html templates/components (here or in a user app)? Load [`llms.txt`
 | GC safety in C | `RB_GC_GUARD` every `VALUE` whose pointer outlives an allocating/yielding call; re-read `RSTRING_PTR(buf)` after growth; use `buffer.h` (edge 3) |
 | Speed over memory | No per-call allocations on hot paths; perf claims need before/after numbers (edge 5) |
 | Never release by hand | No `rake release`, no `v*` tag push, no `gem push` — merging a `version.rb` bump to `main` is the release |
-| Never commit artifacts | `lib/ruby2html/*.so`, `*.jar`, `*.class`, `tmp/`, `pkg/`, `*.gem`, `log/` (edge 13) |
+| Never commit artifacts | `apps/ruby2html/lib/ruby2html/*.so`, `*.jar`, `*.class`, `apps/ruby2html/tmp/`, `apps/ruby2html/pkg/`, `*.gem`, `apps/ruby2html/log/` (edge 13) |
 | Breaking public API | CHANGELOG entry ("Upgrading to 2.0") + major bump; breaking changes escalate to the owner (edge 11) |
 
 ## Commands
@@ -42,66 +42,69 @@ Writing ruby2html templates/components (here or in a user app)? Load [`llms.txt`
 | Command | Notes |
 |---|---|
 | `bundle install` | — |
-| `bundle exec rake compile` | C ext → `lib/ruby2html/ruby2html.so`; `RUBY2HTML_NO_SIMD=1` for the scalar escape path; carries `audit:advisories` (CI only; the `spec` tasks carry it too, so `SKIP_COMPILE=1` does not drop it) |
-| `bundle exec rake audit:advisories`, `bin/audit-advisories [lockfile]` | audits one resolved lockfile — `<BUNDLE_GEMFILE>.lock` (the script reads `ENV['BUNDLE_GEMFILE']` itself; the rake task runs it with the variable still set, only its child processes get the Bundler keys stripped), else `Gemfile.lock`; an explicit path wins — against the Ruby advisory database via `bundle-audit check --update --gemfile-lock`; the rake task runs only in CI (`CI=1`) and only for the unlocked `gemfiles/*.gemfile` matrix sets; exits non-zero on an advisory, except the advisories `bin/audit-advisories` accepts for the floor lines the matrix resolves on purpose (Rails 7.2.x, Active Support 7.2.x on Ruby 3.1): those are listed by advisory id in the script, scoped to the exact reviewed version — a moved resolution drops every exception and fails the audit until the list is re-reviewed |
+| `bundle exec rake compile` | C ext → `apps/ruby2html/lib/ruby2html/ruby2html.so`; `RUBY2HTML_NO_SIMD=1` for the scalar escape path; carries `audit:advisories` (CI only; the `spec` tasks carry it too, so `SKIP_COMPILE=1` does not drop it) |
+| `bundle exec rake audit:advisories`, `bin/audit-advisories [lockfile]` | audits one resolved lockfile — `<BUNDLE_GEMFILE>.lock` (the script reads `ENV['BUNDLE_GEMFILE']` itself; the rake task runs it with the variable still set, only its child processes get the Bundler keys stripped), else `apps/ruby2html/Gemfile.lock`; an explicit path wins — against the Ruby advisory database via `bundle-audit check --update --gemfile-lock`; the rake task runs only in CI (`CI=1`) and only for the unlocked `apps/ruby2html/gemfiles/*.gemfile` matrix sets; exits non-zero on an advisory, except the advisories `bin/audit-advisories` accepts for the floor lines the matrix resolves on purpose (Rails 7.2.x, Active Support 7.2.x on Ruby 3.1): those are listed by advisory id in the script, scoped to the exact reviewed version — a moved resolution drops every exception and fails the audit until the list is re-reviewed |
 | `CI=1 bundle exec rspec` | full suite minus the ~6 min benchmark spec (skipped when CI is set) |
 | `bundle exec rspec spec/gem` | renderer + Rails integration units |
 | `bundle exec rake spec` | compiles first (`SKIP_COMPILE=1` to skip); `spec:gem` = `spec/gem`; `spec:standalone` = `spec/gem` without Rails |
 | `RUBY2HTML_DISABLE_EXT=1 bundle exec rspec spec/gem` | whole process on PureRuby (parity groups already cover both) |
-| `bundle exec rubocop` | CI: `bin/rubocop --parallel`; lefthook pre-commit autocorrects staged files |
-| `bin/brakeman --no-pager` | — |
-| `bundle exec rake bench` | compiles, runs every `bench/*.rb` |
+| `bundle exec rubocop` | CI: `../../bin/rubocop --parallel . ../../bin`; lefthook pre-commit autocorrects staged files |
+| `../../bin/brakeman --no-pager` | from `apps/ruby2html` |
+| `bundle exec rake bench` | compiles, runs every `apps/ruby2html/bench/*.rb` |
 | `bundle exec rake build` | `pkg/ruby2html-X.Y.Z.gem` (does not compile) |
 | `bundle exec rake smoke` | build + `bin/gem-smoke`: file list check, install into temp GEM_HOME, render without Rails |
 | `bin/rails server` | demo: `/`, `/rb_files`, `/form`, `/benchmark/{html,ruby,compruby,slim,phlex}` |
 
+- Run bundler/rake/rspec/rubocop from `apps/ruby2html` (the `Gemfile`, `Rakefile` and `.rubocop.yml` live there; `bin/check` cds there); the `bin/*` scripts stay at the repo root and are `../../bin/*` from the app dir.
 - Gem tasks (`compile clean clobber spec spec:gem spec:standalone bench smoke build install release default audit:advisories`) do not boot Rails; any other task loads the Rails tasks. `RUBY2HTML_RAILS_TASKS=1` forces that.
-- After editing `ext/` always `rake compile`; otherwise specs run the stale `.so` (or PureRuby if none).
+- After editing `apps/ruby2html/ext/` always `rake compile`; otherwise specs run the stale `.so` (or PureRuby if none).
 - Never run `rake release`, push `v*` tags or `gem push`: merging a version bump to `main` is the release (`docs/release.md`).
 
 ## Code map
 
 | File | Responsibility |
 |---|---|
-| `lib/gem/ruby2html.rb` | Entry point: eager-loads only `version` + `render`; everything else `autoload`ed (Component, ComponentHelper, RailsHelper, HtmlBeautifierMiddleware, `RailsComponents::*`); requires `railtie` only if ActiveSupport is loaded. Keep `require 'ruby2html'` light (no Prism, no ERB engine, no htmlbeautifier) |
-| `lib/gem/ruby2html/render.rb` | Loads Native (or PureRuby) into `Ruby2html::IMPLEMENTATION`; `load_native_extension` returns false on JRuby/TruffleRuby (no C ext there); `Ruby2html.native?`, `Ruby2html.escape_html`; `Render`: `HTML5_TAGS`/`VOID_ELEMENTS`, defines tags on both implementations via `define_tag`, includes the implementation; `render`, `method_missing` → context, Rails helper wrappers, ivar copying |
-| `lib/gem/ruby2html/render/pure_ruby.rb` | Ruby twin of Native: tag methods, `plain`, `component`, text/attribute rules, `escape_html`. `escape` picks the fastest available: ERB's C escaper on CRuby, `Ruby2html::JavaNative` (the Java escaper) on JRuby, else a regex — all byte-identical |
-| `ext/ruby2html/ruby2html.c` | `Init_ruby2html`: defines `Ruby2html::Native` |
-| `ext/ruby2html/tag_render.c` | `Native.define_tag(method, tag, void)`: binds each tag to one of 200 C trampolines (`R2H_MAX_TAGS`), tag name `[a-z0-9-]`, max 32 chars; `render_tag` writes open tag, yields or appends content, close tag |
-| `ext/ruby2html/content.c` | Text rules (`plain`, `component`, tag content, block return values), `html_safe?` detection |
-| `ext/ruby2html/attributes.c` | Attribute rules (nil/boolean/Hash/Array/escape), name validation; no caching |
-| `ext/ruby2html/html_escape.c` | Escapes `& < > " '`; SSE2 / NEON 16-byte scan, scalar fallback; UTF-8 coercion (`r2h_utf8_compatible`); `Native.escape_html` |
-| `ext/ruby2html/buffer.h` | Inline buffer primitives (reserve ≥2x growth, memcpy, commit) |
-| `ext/ruby2html/extconf.rb` | `append_cflags -O3 -std=gnu99 -fvisibility=hidden -Wall -Wextra`, `-fno-plt` on Linux, `-DR2H_NO_SIMD` via env; compiles all `*.c` in the dir; no-op Makefile (pure Ruby) on JRuby and TruffleRuby |
-| `ext/java/Ruby2htmlJrubyService.java` | JRuby `BasicLibraryService`: `Ruby2html::JavaNative.escape`, byte-identical with `html_escape.c` and `PureRuby.escape`. Built by `Rake::JavaExtensionTask` (Rakefile); default package + the `*Service` name are load-bearing (JRuby's `require` convention) |
-| `lib/gem/ruby2html/railtie.rb` | `TemplateHandler` (`.rb` templates): compiled strategy via `TemplateCompiler` (template runs with self = view/component, renderer in `@__r2h`), closure fallback (no Prism / parse failure: `instance_exec` on a `Render` with ivar copying); filename annotations; Zeitwerk ignore `app/**/*.html.rb` |
-| `lib/gem/ruby2html/rails_components/template_compiler.rb`, `template_collector.rb` | Prism rewrite of receiverless tag/`plain`/`component`/`render`/helper calls in templates; Prism required lazily on first compile (`available?`); the Railtie's `before_eager_load` loads it at boot in eager-loading (production) apps |
-| `lib/gem/ruby2html/rails_components/template_helpers.rb` | Receiver for `link_to button_to image_tag form_with render capture content_for provide` in compiled templates |
-| `lib/gem/ruby2html/rails_components/{base_component,link_to,button_to,image_tag,form_with,output_capture}.rb` | Call the real Rails helper, capture nested ruby2html output for its block, append result; `FormBuilderProxy` |
-| `lib/gem/ruby2html/component.rb` | `Ruby2html::Component`: includes the implementation directly (self = component), `view_template`/`call`, `render_in(view_context)`, `render_into(buffer, ...)` for nesting into a parent buffer, `helpers`, `content`, Rails helper wrappers |
-| `lib/gem/ruby2html/component_helper.rb` | ViewComponent `html(&block)`; current renderer in `@__r2h` (save/restore in `ensure`, fiber-safe; no `Thread.current`); `__ruby2html_renderer__`; private `method_missing` to the renderer |
-| `lib/gem/ruby2html/rails_helper.rb` | `html(context, &block)` for ERB, `helper_method` when included in a controller |
-| `lib/gem/ruby2html/html_beautifier_middleware.rb` | Dev middleware; lazy-requires `htmlbeautifier` (helpful LoadError if missing) |
+| `apps/ruby2html/lib/gem/ruby2html.rb` | Entry point: eager-loads only `version` + `render`; everything else `autoload`ed (Component, ComponentHelper, RailsHelper, HtmlBeautifierMiddleware, `RailsComponents::*`); requires `railtie` only if ActiveSupport is loaded. Keep `require 'ruby2html'` light (no Prism, no ERB engine, no htmlbeautifier) |
+| `apps/ruby2html/lib/gem/ruby2html/render.rb` | Loads Native (or PureRuby) into `Ruby2html::IMPLEMENTATION`; `load_native_extension` returns false on JRuby/TruffleRuby (no C ext there); `Ruby2html.native?`, `Ruby2html.escape_html`; `Render`: `HTML5_TAGS`/`VOID_ELEMENTS`, defines tags on both implementations via `define_tag`, includes the implementation; `render`, `method_missing` → context, Rails helper wrappers, ivar copying |
+| `apps/ruby2html/lib/gem/ruby2html/render/pure_ruby.rb` | Ruby twin of Native: tag methods, `plain`, `component`, text/attribute rules, `escape_html`. `escape` picks the fastest available: ERB's C escaper on CRuby, `Ruby2html::JavaNative` (the Java escaper) on JRuby, else a regex — all byte-identical |
+| `apps/ruby2html/ext/ruby2html/ruby2html.c` | `Init_ruby2html`: defines `Ruby2html::Native` |
+| `apps/ruby2html/ext/ruby2html/tag_render.c` | `Native.define_tag(method, tag, void)`: binds each tag to one of 200 C trampolines (`R2H_MAX_TAGS`), tag name `[a-z0-9-]`, max 32 chars; `render_tag` writes open tag, yields or appends content, close tag |
+| `apps/ruby2html/ext/ruby2html/content.c` | Text rules (`plain`, `component`, tag content, block return values), `html_safe?` detection |
+| `apps/ruby2html/ext/ruby2html/attributes.c` | Attribute rules (nil/boolean/Hash/Array/escape), name validation; no caching |
+| `apps/ruby2html/ext/ruby2html/html_escape.c` | Escapes `& < > " '`; SSE2 / NEON 16-byte scan, scalar fallback; UTF-8 coercion (`r2h_utf8_compatible`); `Native.escape_html` |
+| `apps/ruby2html/ext/ruby2html/buffer.h` | Inline buffer primitives (reserve ≥2x growth, memcpy, commit) |
+| `apps/ruby2html/ext/ruby2html/extconf.rb` | `append_cflags -O3 -std=gnu99 -fvisibility=hidden -Wall -Wextra`, `-fno-plt` on Linux, `-DR2H_NO_SIMD` via env; compiles all `*.c` in the dir; no-op Makefile (pure Ruby) on JRuby and TruffleRuby |
+| `apps/ruby2html/ext/java/Ruby2htmlJrubyService.java` | JRuby `BasicLibraryService`: `Ruby2html::JavaNative.escape`, byte-identical with `html_escape.c` and `PureRuby.escape`. Built by `Rake::JavaExtensionTask` (apps/ruby2html/Rakefile); default package + the `*Service` name are load-bearing (JRuby's `require` convention) |
+| `apps/ruby2html/lib/gem/ruby2html/railtie.rb` | `TemplateHandler` (`.rb` templates): compiled strategy via `TemplateCompiler` (template runs with self = view/component, renderer in `@__r2h`), closure fallback (no Prism / parse failure: `instance_exec` on a `Render` with ivar copying); filename annotations; Zeitwerk ignore `app/**/*.html.rb` |
+| `apps/ruby2html/lib/gem/ruby2html/rails_components/template_compiler.rb`, `template_collector.rb` | Prism rewrite of receiverless tag/`plain`/`component`/`render`/helper calls in templates; Prism required lazily on first compile (`available?`); the Railtie's `before_eager_load` loads it at boot in eager-loading (production) apps |
+| `apps/ruby2html/lib/gem/ruby2html/rails_components/template_helpers.rb` | Receiver for `link_to button_to image_tag form_with render capture content_for provide` in compiled templates |
+| `apps/ruby2html/lib/gem/ruby2html/rails_components/{base_component,link_to,button_to,image_tag,form_with,output_capture}.rb` | Call the real Rails helper, capture nested ruby2html output for its block, append result; `FormBuilderProxy` |
+| `apps/ruby2html/lib/gem/ruby2html/component.rb` | `Ruby2html::Component`: includes the implementation directly (self = component), `view_template`/`call`, `render_in(view_context)`, `render_into(buffer, ...)` for nesting into a parent buffer, `helpers`, `content`, Rails helper wrappers |
+| `apps/ruby2html/lib/gem/ruby2html/component_helper.rb` | ViewComponent `html(&block)`; current renderer in `@__r2h` (save/restore in `ensure`, fiber-safe; no `Thread.current`); `__ruby2html_renderer__`; private `method_missing` to the renderer |
+| `apps/ruby2html/lib/gem/ruby2html/rails_helper.rb` | `html(context, &block)` for ERB, `helper_method` when included in a controller |
+| `apps/ruby2html/lib/gem/ruby2html/html_beautifier_middleware.rb` | Dev middleware; lazy-requires `htmlbeautifier` (helpful LoadError if missing) |
 
 ## How to verify a change
 
+Run the `bundle exec`/rake/rspec commands from `apps/ruby2html`; the `bin/*` scripts run from the repo root.
+
 | You changed | Run | Also |
 |---|---|---|
-| `ext/**` (C) | `bundle exec rake compile`, `bin/build-ext --werror` (also `--cc=clang`) → `CI=1 bundle exec rspec spec/gem` → `RUBY2HTML_DISABLE_EXT=1 bundle exec rspec spec/gem` | `bundle exec rake bench` before/after; `review` skill checklist; `debug-render` skill for C vs Ruby diffs |
-| `render/pure_ruby.rb` | both spec runs above | output parity with Native |
+| `apps/ruby2html/ext/**` (C) | `bundle exec rake compile`, `bin/build-ext --werror` (also `--cc=clang`) → `CI=1 bundle exec rspec spec/gem` → `RUBY2HTML_DISABLE_EXT=1 bundle exec rspec spec/gem` | `bundle exec rake bench` before/after; `review` skill checklist; `debug-render` skill for C vs Ruby diffs |
+| `apps/ruby2html/lib/gem/ruby2html/render/pure_ruby.rb` | both spec runs above | output parity with Native |
 | `render.rb` (tags, delegation, ivars) | `CI=1 bundle exec rspec` | `rake bench` if hot path |
 | Escaping / attributes (either side) | both spec runs + new specs for the case | `xss-auditor` agent |
-| `railtie.rb`, `template_compiler.rb`, `rails_components/**`, `component.rb`, `component_helper.rb` | `CI=1 bundle exec rspec spec/gem/rails spec/features` | try the demo pages (`bin/rails server`) |
-| `html_beautifier_middleware.rb` | `bundle exec rspec spec/gem/rails/html_beautifier_middleware_spec.rb` | |
-| `ext/java/**` (JRuby escaper) | on JRuby: `bundle exec rake compile` → `bundle exec rake spec:standalone` → `bundle exec ruby bin/gem-smoke` | keep byte-identical with `html_escape.c` / `PureRuby.escape`; `xss-auditor` pass |
-| gemspec, `Rakefile`, packaging | `bundle exec rake smoke` | `tar -xOf pkg/*.gem data.tar.gz \| tar -tz` |
+| `railtie.rb`, `template_compiler.rb`, `rails_components/**`, `component.rb`, `component_helper.rb` (under `apps/ruby2html/lib/gem/ruby2html/`) | `CI=1 bundle exec rspec spec/gem/rails spec/features` | try the demo pages (`bin/rails server`) |
+| `apps/ruby2html/lib/gem/ruby2html/html_beautifier_middleware.rb` | `bundle exec rspec spec/gem/rails/html_beautifier_middleware_spec.rb` | |
+| `apps/ruby2html/ext/java/**` (JRuby escaper) | on JRuby: `bundle exec rake compile` → `bundle exec rake spec:standalone` → `bundle exec ruby ../../bin/gem-smoke` | keep byte-identical with `html_escape.c` / `PureRuby.escape`; `xss-auditor` pass |
+| gemspec (`apps/ruby2html/ruby2html.gemspec`), `Rakefile`, packaging | `bundle exec rake smoke` | `tar -xOf pkg/*.gem data.tar.gz \| tar -tz` |
 | `Gemfile` / deps | `upgrade-deps` skill: full suite + benchmarks | |
-| Docs only | check every claim against code; run snippets with `bundle exec ruby -Ilib/gem -Ilib -e '...'` | |
-| Anything | `bundle exec rubocop` | CHANGELOG `## [Unreleased]` for user-visible changes; update `llms.txt` if user-facing behavior changes |
+| Docs only | check every claim against code; run snippets with `bundle exec ruby -Iapps/ruby2html/lib/gem -Iapps/ruby2html/lib -e '...'` | |
+| Anything | `bundle exec rubocop` | CHANGELOG `## [Unreleased]` for user-visible changes; update `apps/ruby2html/llms.txt` if user-facing behavior changes |
 
 ## Sharp edges / invariants
 
-1. **Native and PureRuby must produce byte-identical output** (HTML, encoding, raised errors) for every input. Any rule change goes into `content.c`/`attributes.c`/`tag_render.c` **and** `pure_ruby.rb`, with specs in the `RenderSpecHelper.describe_each` groups / `render_parity_spec.rb`; start-tag exceptions roll the buffer back to before the tag (both sides). The JRuby Java escaper (`ext/java`) is a third side of the escape rule only: byte-identical with `html_escape.c` / `PureRuby.escape` (the JRuby standalone run exercises it, and a `render_spec` example checks it is loaded and matches).
+1. **Native and PureRuby must produce byte-identical output** (HTML, encoding, raised errors) for every input. Any rule change goes into `content.c`/`attributes.c`/`tag_render.c` **and** `pure_ruby.rb`, with specs in the `RenderSpecHelper.describe_each` groups / `render_parity_spec.rb`; start-tag exceptions roll the buffer back to before the tag (both sides). The JRuby Java escaper (`apps/ruby2html/ext/java`) is a third side of the escape rule only: byte-identical with `html_escape.c` / `PureRuby.escape` (the JRuby standalone run exercises it, and a `render_spec` example checks it is loaded and matches).
 2. **Never cache by `Object#hash`**: collisions return another input's output (the old `ATTRIBUTE_CACHE` did exactly this and was removed). Exact-equality keys only, and only with a benchmark proving a win.
 3. **GC safety in C**: any `VALUE` whose `RSTRING_PTR`/internal pointer is used after a call that can allocate or yield (`rb_funcall`, `rb_yield`, `rb_str_*`, `rb_obj_as_string`) needs `RB_GC_GUARD(v)` after its last use; re-read `RSTRING_PTR(buf)` after anything that can grow `buf`; use `buffer.h` (`r2h_buf_reserve`/`commit`), never manual `rb_str_set_len` arithmetic.
 4. **Escaping is a security boundary.** Text and attribute values escaped by default; raw only for `html_safe?` objects and `component`; plain `String` (exact class) never safe. Attribute/tag **names** are validated (raise), not escaped. Every escaping change: specs (both modes) + `xss-auditor` pass.
@@ -113,7 +116,7 @@ Writing ruby2html templates/components (here or in a user app)? Load [`llms.txt`
 10. Adding a tag: `HTML5_TAGS` (+ `VOID_ELEMENTS`) only; no C change unless exceeding 200 tags or 32-char names (`.claude/skills/add-html-tag`).
 11. Public API used downstream — `Render.new(ctx, &blk)`, `#render`, `#plain`, `#component`, tag methods, `Ruby2html.escape_html`, `Ruby2html.native?`, `Ruby2html::Component`, `RailsHelper#html`, `ComponentHelper#html` / `#__ruby2html_renderer__`, the `.rb` handler, `HtmlBeautifierMiddleware` — breaking changes need a CHANGELOG entry ("Upgrading to 2.0") and a major bump.
 12. Style: rubocop-rails_config, single quotes, `# frozen_string_literal: true`, nested modules, Rails-style indented `private` methods. C: gnu99, no warnings under `-Wall -Wextra`.
-13. Never commit `lib/ruby2html/*.so`, `*.jar`, `*.class`, `tmp/`, `pkg/`, `*.gem`, `log/`.
+13. Never commit `apps/ruby2html/lib/ruby2html/*.so`, `*.jar`, `*.class`, `apps/ruby2html/tmp/`, `apps/ruby2html/pkg/`, `*.gem`, `apps/ruby2html/log/`.
 
 ## Maintenance model
 
@@ -123,10 +126,10 @@ Goal: the repo needs no hand maintenance except major-version dependency upgrade
 |---|---|
 | Maintainer agent | Repo managed by [developerz.ai](https://developerz.ai) (policy: `.dz/maintainer/maintainer.yml`): triages issues, reviews and merges every PR (contributors, members, bots) once its author marks it ready (out of draft), it is reviewed and `CI OK` is green; daily `health` + weekday `release-due` checkups and a monthly `improve` pass (`.dz/briefs/`: canary fixes, dependency majors, speed with benchmark evidence, correctness, docs drift); opens release PRs; breaking changes escalate to the owner. Sibling projects such as [wurk](https://github.com/sebyx07/wurk) run the same model |
 | Dependencies | Dependabot (`.github/dependabot.yml`) opens grouped weekly PRs: app dependencies wait out a 14-day cooldown (security updates skip it), while the dev-tools group is exempt from it (`cooldown.exclude`) and is proposed within days; the agent reviews and merges on green — the only merger |
-| CI | `.github/workflows/ci.yml`; branch protection requires only the aggregate `CI OK` job: RuboCop, bundle-audit (the committed root `Gemfile.lock` in the `audit` job, plus the resolved sets of the unlocked matrix gemfiles `gemfiles/standalone.gemfile` and `gemfiles/rails.gemfile` — the matrix sets are audited by `bin/audit-advisories`, which the `audit:advisories` task rides on `rake compile` and the `spec` tasks (so `SKIP_COMPILE=1` cannot drop it), so every matrix entry audits the set it just resolved; the advisories of the floor lines the matrix resolves on purpose (Rails 7.2.x, Active Support 7.2.x on Ruby 3.1) are accepted by advisory id in `bin/audit-advisories`, scoped to the exact reviewed version, every other advisory fails the entry), full suite + Brakeman, gem specs across the Ruby matrix (generated from maintained CRuby versions), native builds on Linux/macOS arm64, `-Werror` with gcc and clang, ASAN/UBSAN (`use_sigaltstack=0`), pure-Ruby fallback, JRuby (Java escaper jar + `-java` gem) and TruffleRuby (pure Ruby) via `gemfiles/standalone.gemfile`, Rails integration per `gemfiles/rails.gemfile`, `bin/gem-smoke` packaging on plain RubyGems. Every job required; no `continue-on-error` |
+| CI | `.github/workflows/ci.yml`; branch protection requires only the aggregate `CI OK` job: RuboCop, bundle-audit (the committed `apps/ruby2html/Gemfile.lock` in the `audit` job, plus the resolved sets of the unlocked matrix gemfiles `apps/ruby2html/gemfiles/standalone.gemfile` and `apps/ruby2html/gemfiles/rails.gemfile` — the matrix sets are audited by `bin/audit-advisories`, which the `audit:advisories` task rides on `rake compile` and the `spec` tasks (so `SKIP_COMPILE=1` cannot drop it), so every matrix entry audits the set it just resolved; the advisories of the floor lines the matrix resolves on purpose (Rails 7.2.x, Active Support 7.2.x on Ruby 3.1) are accepted by advisory id in `bin/audit-advisories`, scoped to the exact reviewed version, every other advisory fails the entry), full suite + Brakeman, gem specs across the Ruby matrix (generated from maintained CRuby versions), native builds on Linux/macOS arm64, `-Werror` with gcc and clang, ASAN/UBSAN (`use_sigaltstack=0`), pure-Ruby fallback, JRuby (Java escaper jar + `-java` gem) and TruffleRuby (pure Ruby) via `apps/ruby2html/gemfiles/standalone.gemfile`, Rails integration per `apps/ruby2html/gemfiles/rails.gemfile`, `bin/gem-smoke` packaging on plain RubyGems. Every job required; no `continue-on-error` |
 | Canary | `.github/workflows/canary.yml`, monthly on the 1st, not gating: Ruby head and Rails edge surface upstream breaks before a release ships them; the monthly `improve` checkup fixes what it finds |
 | Benchmarks | `.github/workflows/benchmark.yml`, non-gating: every push to `main` and PR renders a table into the job summary and uploads JSON; PRs get a sticky comment with the delta vs `main`. Set repo variable `BENCH_RUNNER` for a stable self-hosted runner; README holds only a dated release snapshot |
-| Releases | `.github/workflows/release.yml`: merging a `version.rb` bump to `main` (no `v<VERSION>` tag yet) runs the tests and `rake smoke`, builds the `-java` gem on JRuby (jar inside), publishes **both** the C-extension gem and the `-java` gem via RubyGems trusted publishing (environment `release`), then creates the tag and the GitHub release from `bin/changelog-notes`. The release PR is opened by the agent or the `release` skill (`docs/release.md`) |
+| Releases | `.github/workflows/release.yml`: merging an `apps/ruby2html/lib/gem/ruby2html/version.rb` bump to `main` (no `v<VERSION>` tag yet) runs the tests and `rake smoke`, builds the `-java` gem on JRuby (jar inside), publishes **both** the C-extension gem and the `-java` gem via RubyGems trusted publishing (environment `release`), then creates the tag and the GitHub release from `bin/changelog-notes`. The release PR is opened by the agent or the `release` skill (`docs/release.md`) |
 | Local hooks | lefthook pre-commit autocorrects staged Ruby files with RuboCop; the Claude Code PostToolUse hook reminds to recompile after `ext/` edits |
 | Manual (owner only) | Breaking changes and major releases (escalated by the agent); one-time repo setup (RubyGems trusted publisher; ruleset requiring `CI OK`). Major dependency bumps: the agent like any other PR (`upgrade-deps` skill if by hand) |
 | Docs rule | Don't hardcode version lists or benchmark numbers in docs; point at the CI matrix, `.ruby-version`, the lockfiles and the benchmark workflow instead |
@@ -135,10 +138,10 @@ Goal: the repo needs no hand maintenance except major-version dependency upgrade
 
 | Tool | Notes |
 |---|---|
-| `llms.txt` | The one user-facing reference for the gem (people and their LLM tools); hand-written, concise; keep accurate when behavior changes — there are no other usage docs to sync |
+| `apps/ruby2html/llms.txt` | The one user-facing reference for the gem (people and their LLM tools); hand-written, concise; keep accurate when behavior changes — there are no other usage docs to sync |
 | Skills (`.claude/skills/`) | `release` (bump → changelog → verify → `release: X.Y.Z` PR; merging publishes; manual-only), `benchmark` (before/after), `add-html-tag`, `review` (checklist for `ext/` and renderer diffs), `debug-render` (C vs Ruby output diffs, sanitizer builds), `upgrade-deps` |
 | Subagents (`.claude/agents/`, read-only tools) | `perf-reviewer`, `xss-auditor` — independent pass on hot-path or escaping changes |
-| `.claude/settings.json` | Allowlists the routine workflow (specs, `rake`, rubocop, brakeman, bench scripts, `bin/*`, git add/commit/push/branch, `gh pr|issue|api|run|workflow`). Denied outright (never needed: merging a version bump publishes): `git tag`, force pushes, `rake release`, `gem push/yank`, `gh release`, reading `.env*`/`config/master.key`. PostToolUse hook (`.claude/hooks/post-edit-reminder.sh`, non-blocking) reminds to recompile after `ext/` edits and keep Native/PureRuby parity after renderer edits |
+| `.claude/settings.json` | Allowlists the routine workflow (specs, `rake`, rubocop, brakeman, bench scripts, `bin/*`, git add/commit/push/branch, `gh pr|issue|api|run|workflow`). Denied outright (never needed: merging a version bump publishes): `git tag`, force pushes, `rake release`, `gem push/yank`, `gh release`, reading `.env*`/`apps/ruby2html/config/master.key`. PostToolUse hook (`.claude/hooks/post-edit-reminder.sh`, non-blocking) reminds to recompile after `ext/` edits and keep Native/PureRuby parity after renderer edits |
 
 ## Definition of done
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 24d8e64..e510e2e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,11 +4,12 @@ Bug reports and pull requests are welcome at https://github.com/sebyx07/ruby2htm
 
 ## Setup
 
-Requirements: Ruby (see `.ruby-version`; gem supports `>= 3.1`), a C compiler (`build-essential` on Debian/Ubuntu), SQLite (demo app).
+Requirements: Ruby (see `apps/ruby2html/.ruby-version`; gem supports `>= 3.1`), a C compiler (`build-essential` on Debian/Ubuntu), SQLite (demo app).
 
 ```bash
+cd apps/ruby2html
 bundle install
-bundle exec rake compile      # builds ext/ruby2html -> lib/ruby2html/ruby2html.so
+bundle exec rake compile      # builds apps/ruby2html/ext/ruby2html -> apps/ruby2html/lib/ruby2html/ruby2html.so
 CI=1 bundle exec rspec        # CI=1 skips the ~6 minute benchmark spec
 RUBY2HTML_DISABLE_EXT=1 bundle exec rspec spec/gem   # pure-Ruby implementation
 bundle exec rubocop
@@ -18,9 +19,9 @@ bundle exec rubocop
 
 ## Where things are
 
-- Gem code: `lib/gem/ruby2html/` (renderer `render.rb`, pure-Ruby twin `render/pure_ruby.rb`), C extension: `ext/ruby2html/`.
-- Demo Rails app (not packaged): `app/`, `config/`.
-- Specs: `spec/gem/` (renderer units), `spec/features/` (Rails), `spec/benchmarks/`.
+- Gem code: `apps/ruby2html/lib/gem/ruby2html/` (renderer `render.rb`, pure-Ruby twin `render/pure_ruby.rb`), C extension: `apps/ruby2html/ext/ruby2html/`.
+- Demo Rails app (not packaged): `apps/ruby2html/app/`, `apps/ruby2html/config/`.
+- Specs: `apps/ruby2html/spec/gem/` (renderer units), `apps/ruby2html/spec/features/` (Rails), `apps/ruby2html/spec/benchmarks/`.
 - Full map, rules and known sharp edges: [AGENTS.md](AGENTS.md). Internals: [docs/architecture.md](docs/architecture.md).
 
 ## Pull requests
@@ -28,15 +29,15 @@ bundle exec rubocop
 1. Branch from `main`; keep PRs focused.
 2. Add/adjust specs for any behavior change. Escaping changes need explicit specs.
 3. C changes: recompile, keep `render/pure_ruby.rb` producing byte-identical output (parity specs), no new compiler warnings.
-4. Performance claims: include before/after numbers (see `bench/` and `spec/benchmarks/`; `.claude/skills/benchmark/SKILL.md` has the procedure).
+4. Performance claims: include before/after numbers (see `apps/ruby2html/bench/` and `apps/ruby2html/spec/benchmarks/`; `.claude/skills/benchmark/SKILL.md` has the procedure).
 5. Add a line under `## [Unreleased]` in [CHANGELOG.md](CHANGELOG.md) for user-visible changes.
-6. Update [llms.txt](llms.txt) if user-facing behavior changes.
+6. Update [llms.txt](apps/ruby2html/llms.txt) if user-facing behavior changes.
 
 The PR template carries this checklist. Releases are done by the maintainer following [docs/release.md](docs/release.md).
 
 ## Style
 
-rubocop-rails_config (`.rubocop.yml`): single quotes, `# frozen_string_literal: true`, nested `module`/`class`, Rails-style indented private methods. C: C99, `-Wall -Wextra` clean, `size_t` for lengths.
+rubocop-rails_config (`.rubocop.yml`, which lives in `apps/ruby2html/`): single quotes, `# frozen_string_literal: true`, nested `module`/`class`, Rails-style indented private methods. C: C99, `-Wall -Wextra` clean, `size_t` for lengths.
 
 ## License
 
@@ -44,5 +45,5 @@ By contributing you agree your contributions are licensed under the MIT License.
 
 ## How PRs get merged
 
-This repo is maintained by [developerz.ai](https://developerz.ai). Its agent reviews every PR, may request changes, and merges every PR (contributors, members, bots) once you mark it ready for review and the `CI OK` check passes; keep it a draft until then (policy: `.dz/maintainer/maintainer.yml`). Commit with an email linked to your GitHub account. Changes to CI, release or publishing automation (`.github/`, `bin/`, the gemspec, `Ruby2html::VERSION`) are made by the owner only.
+This repo is maintained by [developerz.ai](https://developerz.ai). Its agent reviews every PR, may request changes, and merges every PR (contributors, members, bots) once you mark it ready for review and the `CI OK` check passes; keep it a draft until then (policy: `.dz/maintainer/maintainer.yml`). Commit with an email linked to your GitHub account. Changes to CI, release or publishing automation (`.github/`, `bin/`, the gemspec (`apps/ruby2html/ruby2html.gemspec`), `Ruby2html::VERSION`) are made by the owner only.
 
diff --git a/Gemfile b/Gemfile
index 606b64e..8411623 100644
--- a/Gemfile
+++ b/Gemfile
@@ -1,51 +1,6 @@
 # frozen_string_literal: true
 
-source 'https://rubygems.org'
+# The ruby2html workspace member lives in apps/ruby2html and bundler always
+# runs from there (bin/setup chdirs into it); this stub points at its Gemfile.
 
-# The demo app's floor (phlex-rails 2, Rails 8.1). Without it Dependabot resolves with the
-# gemspec's Ruby floor (3.1) and every bundler update fails. Dev/CI Ruby: .ruby-version.
-ruby '>= 3.2'
-
-gem 'rails', '~> 8.1'
-gem 'sprockets-rails'
-gem 'sqlite3', '>= 1.4'
-gem 'puma', '>= 5.0'
-gem 'tzinfo-data', platforms: %i[ windows jruby ]
-gem 'htmlbeautifier'
-gem 'bootsnap', require: false
-
-group :development, :test do
-  gem 'brakeman', require: false
-end
-
-group :development do
-  gem 'web-console'
-end
-
-gem 'rubocop-rails_config', '~> 1.17', require: false
-
-gem 'pry-rails', '~> 0.3.11'
-
-gem 'view_component', '~> 4.0'
-
-gem 'rspec-rails', '~> 8.0'
-
-gem 'capybara', '~> 3.40'
-
-gem 'lefthook', '~> 2.0'
-
-gem 'faker', '~> 3.8'
-
-gem 'slim-rails', '~> 4.0'
-
-gem 'phlex-rails', '~> 2.4'
-
-gem 'rake-compiler', '~> 1.3', require: false
-
-group :test do
-  gem 'benchmark-ips'
-end
-
-# phlex 2.x -> refract uses Prism::MissingNode, which prism 2.x removed. Drop
-# once refract supports prism 2 (also pinned in gemfiles/rails_common.rb).
-gem 'prism', '~> 1.6'
+eval_gemfile File.expand_path('apps/ruby2html/Gemfile', __dir__)
diff --git a/README.md b/README.md
index 669d972..5e94fbe 100644
--- a/README.md
+++ b/README.md
@@ -24,7 +24,7 @@ end
 - **Light.** No runtime dependencies and a 32 KB gem. Prism, the Rails glue and the optional beautifier load only when used, or at boot in eager-loading production apps.
 - **Plain Ruby views.** `.html.rb` templates, ERB interop, ViewComponent, or the built-in `Ruby2html::Component`. Escaped by default.
 - **Runs everywhere.** CRuby ≥ 3.1 with a C extension (SIMD escaping on x86_64 and arm64), JRuby with a Java escaper over the pure-Ruby implementation, and TruffleRuby on pure Ruby (faster there than the C extension) — all byte-identical. Rails 7.2+.
-- **AI-ready.** One-file reference for coding agents: [`llms.txt`](llms.txt).
+- **AI-ready.** One-file reference for coding agents: [`llms.txt`](apps/ruby2html/llms.txt).
 
 ## Installation
 
@@ -43,11 +43,11 @@ bundle install   # compiles the native extension (needs a C compiler); pure-Ruby
 
 **This project is maintained by [developerz.ai](https://developerz.ai).** Its maintainer agent triages issues, reviews every pull request, merges every pull request once its author marks it ready and CI passes, watches project health daily, and opens release PRs. The policy is in [`.dz/maintainer/maintainer.yml`](.dz/maintainer/maintainer.yml). Breaking changes and major releases stay with the owner.
 
-- **Using ruby2html in your app?** Point your agent at [`llms.txt`](llms.txt), the complete reference in one file (DSL rules, escaping, Rails, components, forms, pitfalls). Paste this into your app's `CLAUDE.md` / `AGENTS.md`:
+- **Using ruby2html in your app?** Point your agent at [`llms.txt`](apps/ruby2html/llms.txt), the complete reference in one file (DSL rules, escaping, Rails, components, forms, pitfalls). Paste this into your app's `CLAUDE.md` / `AGENTS.md`:
   ```markdown
   ## ruby2html views
   `*.html.rb` templates and `html do ... end` blocks use the ruby2html gem. Before editing them read
-  https://github.com/sebyx07/ruby2html/blob/main/llms.txt
+  https://github.com/sebyx07/ruby2html/blob/main/apps/ruby2html/llms.txt
   ```
 - **Working on this repo?** [`AGENTS.md`](AGENTS.md) is the only agent-instructions file (`CLAUDE.md` is a symlink to it): commands, code map, invariants, how to verify a change, CI/release automation.
 - **Claude Code**: project skills in `.claude/skills/` (`release`, `benchmark`, `add-html-tag`, `review`, `debug-render`, `upgrade-deps`), read-only reviewer subagents in `.claude/agents/` (`perf-reviewer`, `xss-auditor`), and `.claude/settings.json` with a safe permission allowlist and a non-blocking recompile-reminder hook.
@@ -61,7 +61,7 @@ bundle install   # compiles the native extension (needs a C compiler); pure-Ruby
 - Raw HTML only from `html_safe` strings (Rails helpers, `'<hr>'.html_safe`), as content or via `plain`. `plain 'text'` escapes.
 - Attributes: `'data-id': 1` or `data: { id: 1 }`, `class: ['btn', active && 'on']`, `disabled: true` → bare `disabled`, `nil`/`false` omitted.
 
-Full rules and pitfalls: [`llms.txt`](llms.txt).
+Full rules and pitfalls: [`llms.txt`](apps/ruby2html/llms.txt).
 
 ### Rails views (`.html.rb`)
 
@@ -137,7 +137,7 @@ div class: 'farewell' do
 end
 ```
 
-Public component methods can be called from the template and may emit tags themselves (see `app/components/first_component.rb`).
+Public component methods can be called from the template and may emit tags themselves (see `apps/ruby2html/app/components/first_component.rb`).
 
 ### `Ruby2html::Component` (no ViewComponent required)
 
@@ -196,14 +196,51 @@ config.middleware.use Ruby2html::HtmlBeautifierMiddleware
 
 ## Performance
 
-Benchmarks run in CI on every push to `main` and every pull request ([`.github/workflows/benchmark.yml`](.github/workflows/benchmark.yml)): the latest run's summary page has the current table, and PRs get a sticky comment with the delta against `main`. Run them locally with `bundle exec rake bench` (standalone scripts in `bench/`) or `bundle exec rspec spec/benchmarks/` (request-level through the demo app, vs ERB, Slim, Phlex and ViewComponent).
+Benchmarks run in CI on every push to `main` and every pull request ([`.github/workflows/benchmark.yml`](.github/workflows/benchmark.yml)): the latest run's summary page has the current table, and PRs get a sticky comment with the delta against `main`. Run them locally with `bundle exec rake bench` (standalone scripts in `apps/ruby2html/bench/`) or `bundle exec rspec spec/benchmarks/` (request-level through the demo app, vs ERB, Slim, Phlex and ViewComponent).
 
 ### What is measured
 
-- [`bench/render_bench.rb`](bench/render_bench.rb): a full page render (no Rails), ruby2html vs Erubi and Phlex, with per-render allocation counts. `RUBY2HTML_DISABLE_EXT=1` runs the pure-Ruby fallback.
-- [`bench/tag_bench.rb`](bench/tag_bench.rb): per-tag cost for the common call shapes.
-- [`bench/escape_bench.rb`](bench/escape_bench.rb): escaping throughput on short/medium/long, clean and dirty strings. Rebuild with `RUBY2HTML_NO_SIMD=1` to compare the scalar path.
-- [`spec/benchmarks/requests_spec.rb`](spec/benchmarks/requests_spec.rb): full Rails requests through the demo app — `.html.rb` templates, ViewComponent and `Ruby2html::Component` vs ERB, Slim and Phlex.
+- [`apps/ruby2html/bench/render_bench.rb`](apps/ruby2html/bench/render_bench.rb): a full page render (no Rails), ruby2html vs Erubi and Phlex, with per-render allocation counts. `RUBY2HTML_DISABLE_EXT=1` runs the pure-Ruby fallback.
+- [`apps/ruby2html/bench/tag_bench.rb`](apps/ruby2html/bench/tag_bench.rb): per-tag cost for the common call shapes.
+- [`apps/ruby2html/bench/escape_bench.rb`](apps/ruby2html/bench/escape_bench.rb): escaping throughput on short/medium/long, clean and dirty strings. Rebuild with `RUBY2HTML_NO_SIMD=1` to compare the scalar path.
+- [`apps/ruby2html/spec/benchmarks/requests_spec.rb`](apps/ruby2html/spec/benchmarks/requests_spec.rb): full Rails requests through the demo app — `.html.rb` templates, ViewComponent and `Ruby2html::Component` vs ERB, Slim and Phlex.
+
+This is a dated snapshot. CI has the live numbers. Measured on Ruby 3.4.7 x86_64 on a busy machine (load average about 7), so read the ratios rather than the absolute figures.
+
+**Page render** (`apps/ruby2html/bench/render_bench.rb`, no Rails): a header with nav, 100 list items with links, images, attributes and escaped text, about 34 KB of HTML.
+
+| Engine | Renders/s | Time per render | Allocations per render |
+|---|---|---|---|
+| **ruby2html 2.0 (C extension)** | **2,676** | **0.37 ms** | **419** |
+| Erubi 1.x (Rails' ERB engine) | 1,988 (1.35x slower) | 0.50 ms | 713 |
+| ruby2html 2.0 (pure Ruby, no C extension; CRuby) | ~820 | ~1.2 ms | 1,029 |
+| Phlex 2.4, enlarged attribute cache¹ | ~1,250 (≈2.4x slower) | ~0.8 ms | 831 |
+| Phlex 2.4, defaults | 164 (16x slower) | 6.1 ms | 6,410 |
+| ruby2html 1.6.6 | ~620 | ~1.6 ms | 3,531 |
+
+¹ Phlex 2's default attribute cache (2 KB, FIFO) misses on per-row values such as ids and hrefs. `Phlex::ATTRIBUTE_CACHE.expand(1_000_000)` is its best case. Phlex 2 also checks URLs for `javascript:`; ruby2html leaves URL validation to you.
+
+**Full Rails request** (`apps/ruby2html/spec/benchmarks/requests_spec.rb`; Rails 8.1, a 7 ms request where most of the time is Rails itself; differences are within ±15% error):
+
+| Engine | Requests/s |
+|---|---|
+| **`Ruby2html::Component`** | **144.5** |
+| **ViewComponent 4 + ruby2html** | **142.2** |
+| **`.html.rb` template** | **139.6** |
+| Slim | 128.3 |
+| ERB | 122.6 |
+| Phlex 2.4 | 116.6 |
+
+**HTML escaping** (SIMD vs scalar): up to 5.9x faster on 10 KB clean text, about 2x on 200-byte strings; short strings take the scalar path.
+
+**Footprint:**
+
+| | Ruby/C lines | Runtime dependencies | `require` cost |
+|---|---|---|---|
+| **ruby2html** | 1.1k Ruby + 0.8k C | none | ~0.4 MB, ~19 ms |
+| phlex + phlex-rails | 6.2k | refract, zeitwerk, railties | ~1.4 MB, ~30 ms (phlex alone) |
+| view_component | 5.3k | actionview, activesupport, prism | |
+| slim | 7.3k | temple, tilt | |
 
 How it is fast:
 
@@ -217,14 +254,15 @@ How it is fast:
 ## Development
 
 ```bash
+cd apps/ruby2html
 bundle install
 bundle exec rake compile   # build the C extension
 CI=1 bundle exec rspec     # specs (CI=1 skips the slow benchmark spec)
 bundle exec rubocop
-bin/rails server           # demo app
+../../bin/rails server     # demo app
 ```
 
-The repository is both the gem (`lib/gem/`, `ext/ruby2html/`) and a Rails demo app (`app/`, `config/`). See [CONTRIBUTING.md](CONTRIBUTING.md), [docs/architecture.md](docs/architecture.md), [docs/release.md](docs/release.md) and [CHANGELOG.md](CHANGELOG.md).
+The repository is both the gem (`apps/ruby2html/lib/gem/`, `apps/ruby2html/ext/ruby2html/`) and a Rails demo app (`apps/ruby2html/app/`, `apps/ruby2html/config/`). See [CONTRIBUTING.md](CONTRIBUTING.md), [docs/architecture.md](docs/architecture.md), [docs/release.md](docs/release.md) and [CHANGELOG.md](CHANGELOG.md).
 
 ## License
 
diff --git a/SECURITY.md b/SECURITY.md
index 2f9d0b7..d5994b5 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -20,11 +20,11 @@ There is no fixed response time. Reports are read and fixed as maintainer time a
 
 - HTML escaping bypasses (cross-site scripting through text or attribute values, in the C extension, the pure-Ruby implementation or the Java escaper)
 - Output that differs between implementations in a way that defeats escaping
-- Memory safety in the C extension (`ext/ruby2html`)
+- Memory safety in the C extension (`apps/ruby2html/ext/ruby2html`)
 - Anything in the published gem or its build that runs code a user did not ask for
 
 ## Out of scope
 
-- The demo Rails app in `app/` and `config/`: it is not packaged in the gem
+- The demo Rails app in `apps/ruby2html/app/` and `apps/ruby2html/config/`: it is not packaged in the gem
 - Output a template explicitly marked as safe, such as `html_safe` strings
 - Vulnerabilities in your own application's templates
diff --git a/apps/ruby2html/.dockerignore b/apps/ruby2html/.dockerignore
new file mode 100644
index 0000000..cd7190b
--- /dev/null
+++ b/apps/ruby2html/.dockerignore
@@ -0,0 +1,48 @@
+# See https://docs.docker.com/engine/reference/builder/#dockerignore-file for more about ignoring files.
+
+# Ignore git directory.
+/.git/
+/.gitignore
+
+# Ignore bundler config.
+/.bundle
+
+# Ignore all environment files (except templates).
+/.env*
+!/.env*.erb
+
+# Ignore all default key files.
+/config/master.key
+/config/credentials/*.key
+
+# Ignore all logfiles and tempfiles.
+/log/*
+/tmp/*
+!/log/.keep
+!/tmp/.keep
+
+# Ignore pidfiles, but keep the directory.
+/tmp/pids/*
+!/tmp/pids/.keep
+
+# Ignore storage (uploaded files in development and any SQLite databases).
+/storage/*
+!/storage/.keep
+/tmp/storage/*
+!/tmp/storage/.keep
+
+# Ignore assets.
+/node_modules/
+/app/assets/builds/*
+!/app/assets/builds/.keep
+/public/assets
+
+# Ignore CI service files.
+/.github
+
+# Ignore development files
+/.devcontainer
+
+# Ignore Docker-related files
+/.dockerignore
+/Dockerfile*
diff --git a/.rspec b/apps/ruby2html/.rspec
similarity index 100%
rename from .rspec
rename to apps/ruby2html/.rspec
diff --git a/.rubocop.yml b/apps/ruby2html/.rubocop.yml
similarity index 100%
rename from .rubocop.yml
rename to apps/ruby2html/.rubocop.yml
diff --git a/apps/ruby2html/.ruby-version b/apps/ruby2html/.ruby-version
new file mode 100644
index 0000000..7919852
--- /dev/null
+++ b/apps/ruby2html/.ruby-version
@@ -0,0 +1 @@
+4.0.9
diff --git a/apps/ruby2html/CHANGELOG.md b/apps/ruby2html/CHANGELOG.md
new file mode 100644
index 0000000..f02150a
--- /dev/null
+++ b/apps/ruby2html/CHANGELOG.md
@@ -0,0 +1,216 @@
+# Changelog
+
+All notable changes to this project are documented here.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning: [SemVer](https://semver.org/spec/v2.0.0.html).
+Entries before 1.6.6 were reconstructed from `git log` and RubyGems release dates (the repo has no git tags for them); they are best-effort summaries.
+
+## [Unreleased]
+
+### Fixed
+
+- Appending a renderer's own output buffer to itself (`plain(current_output)`, `component(current_output)`) could read freed memory with the C extension: growing the buffer while its own bytes were still being read moved them out from under the read, which aborted under ASAN in the sanitizer CI job and could crash or corrupt output anywhere. Escaped and raw appends (`r2h_append_escaped`, `r2h_append_raw`) now duplicate the string first when it is the buffer; the pure-Ruby renderer was never affected, and output stays byte-identical (pinned by the new "can append the output buffer to itself" example, which runs against both implementations).
+- Attribute names had the same hole: writing a name that is the output buffer itself (`div current_output => true`) could read the name after the buffer moved while it was copied; the name is now duplicated first too.
+
+## [2.1.0] - 2026-10-31
+
+### Added
+
+- JRuby now ships a small Java extension (`Ruby2html::JavaNative`) that accelerates HTML escaping — the renderer's hot path — over the pure-Ruby implementation. About 1.9x faster end-to-end rendering on JRuby; output is byte-identical. Distributed as a `ruby2html-<version>-java` platform gem with the jar prebuilt (no JDK needed to install); everything else stays pure Ruby.
+
+### Changed
+
+- `Ruby2html::Component#render_in` accepts Rails' keyword options (`locals:`), as Rails main (8.2) passes them and deprecates `render_in` without options.
+- TruffleRuby now uses the pure-Ruby implementation instead of the C extension. TruffleRuby runs C extensions through Sulong but JITs pure Ruby with Graal, which here renders ~28x faster; `Ruby2html.native?` is now `false` on TruffleRuby.
+- On CRuby, a C extension that fails to load now prints one warning with the reason (`ruby2html: C extension not loaded (...); using the pure-Ruby renderer`) instead of silently rendering about 3x slower. JRuby/TruffleRuby and `RUBY2HTML_DISABLE_EXT=1` stay silent.
+- Development and single-version CI jobs now run on the latest stable Ruby (4.0). The CRuby test matrix already tracks the official maintained-versions list automatically (currently 3.3, 3.4, 4.0).
+
+## [2.0.0] - 2026-10-31
+
+A rewrite of the renderer for speed, memory and correctness, plus a new component class, Rails 8.1 / ViewComponent 4 support, JRuby/TruffleRuby support and full CI/release automation. **Contains breaking changes: read "Upgrading to 2.0" below.**
+
+### Performance
+
+Measured on Ruby 3.4.7 x86_64 (`bench/render_bench.rb`, a 100-item page with attributes and escaped text):
+
+- About 4.7x faster than 1.6.6 (≈620 → ≈2,950 renders/s) with about 8x fewer allocations per render (3,531 → 419).
+- Faster than Erubi (Rails' ERB engine) and Phlex on the same page; see the README snapshot and the CI benchmark workflow for current numbers.
+- HTML escaping uses SSE2 (x86_64) / NEON (arm64): up to 5.9x faster on large clean text, about 2x on typical strings.
+- `require 'ruby2html'` costs about 0.4 MB and 19 ms (was about 9.5 MB and 116 ms): Prism, the Rails glue and htmlbeautifier load only when used; in eager-loading (production) Rails apps they load at boot instead.
+
+### Added
+
+- `Ruby2html::Component`: a lightweight component base class (no ViewComponent needed) with `view_template`/`call`, `render_in`, `helpers` and `content`; nested components write straight into the parent's buffer.
+- Pure-Ruby implementation with byte-identical output (`Ruby2html::PureRuby`), used on JRuby, when the extension can't be built, or with `RUBY2HTML_DISABLE_EXT=1`. `Ruby2html.native?` and `Ruby2html::IMPLEMENTATION` tell which one is loaded.
+- `Ruby2html.escape_html(obj)`.
+- Attributes: `true` renders a bare attribute, `false` omits it; nested `data:`/`aria:` Hashes expand to `data-user-id="1"`; Arrays render as space-separated tokens (`class: ['btn', active && 'on']`).
+- `.html.rb` templates are compiled with Prism to run directly in the view/component (no instance-variable copying, no `method_missing`).
+- `capture`, `content_for` and `provide` with blocks of ruby2html tags work in `.html.rb` templates.
+- Support for Rails 8.1, ViewComponent 4, JRuby and TruffleRuby; fiber-safe rendering (no thread/fiber-global state).
+- `llms.txt`: complete reference for AI coding tools; `AGENTS.md` (with `CLAUDE.md` symlinked to it) and Claude Code skills/agents for maintainers.
+- CI: generated CRuby matrix (all maintained versions), Rails matrix, Linux x86_64/arm64 and macOS builds, `-Werror` gcc/clang builds, sanitizers, JRuby/TruffleRuby, gem install smoke test, benchmarks in every PR; Dependabot; releases published automatically when a version bump merges (RubyGems trusted publishing).
+- Maintained by [developerz.ai](https://developerz.ai): its maintainer agent triages issues, reviews PRs, merges on green, runs daily health and release checkups, and opens release PRs (`.dz/`).
+
+### Fixed
+
+- Attribute cache keyed by `Object#hash`: a hash collision could render another element's attributes; the cache also grew without bound. Removed.
+- `link_to` rendered a `button_to` form.
+- `form_with` emitted its fields as escaped text, ignored `patch`/`delete` (`_method`), crashed on `submit` without a label, and ignored Rails' CSRF/`data-remote` settings. It now delegates to Rails' own `form_with` and `FormBuilder`.
+- Tags inside `link_to`/`button_to` blocks were emitted before the link instead of inside it.
+- `html_safe` content was escaped twice; non-String content (`p 42`) was silently dropped.
+- A block's String return value replaced markup the block had already written.
+- The `<output>` tag was unusable (shadowed by `Render#output`).
+- Template backtraces were off by 3 lines; the renderer wasn't restored when a template raised; template locals could clash with internal variables or be rewritten into tag calls (`h2 title` in a partial with a `title` local).
+- A rescued exception while writing attributes left a half-written start tag in the output.
+- `HtmlBeautifierMiddleware` beautified each streamed chunk separately, didn't close the body, and touched gzip/204/304 responses.
+- The packaged gem shipped a locally compiled `.so`; `rake build` didn't build a gem.
+
+### Upgrading to 2.0
+
+Templates and components:
+1. `self` in `.html.rb` templates is now the view (or component), not a `Ruby2html::Render`. Replace `self.div` / `self.plain` with `div` / `plain`. Without Prism (Ruby < 3.3 and no `prism` gem) templates still use the 1.x path.
+2. `Thread.current[:__ruby2html_renderer__]` is gone. The active renderer lives on the component/view; use `component.__ruby2html_renderer__`.
+3. `form_with` output now matches Rails (`_method`, `accept-charset`, no forced `data-remote`, no `utf8` field); its builder is a proxy around Rails' `FormBuilder`.
+4. `Ruby2html::ComponentHelper#method_missing` is now private.
+
+HTML output:
+5. Non-String content renders: `p 42` → `<p>42</p>` (1.x: `<p></p>`); `nil` renders nothing.
+6. `html_safe` strings passed as content or returned from a block are inserted raw (1.x escaped them).
+7. A block's return value is used only if the block wrote nothing, and only for String/Symbol/Numeric (1.x: a returned String replaced everything the block wrote).
+8. Attributes: `true` → bare attribute and `false` omitted (except `data-*`, `aria-*`, `draggable`, `spellcheck`, `contenteditable`, which keep `"true"`/`"false"`); Hash values expand; Arrays join with spaces; invalid attribute names raise `ArgumentError`; Hashes/Arrays nested deeper than 32 levels raise `ArgumentError`.
+9. Tag methods accept at most one positional argument (extra arguments raise `ArgumentError`).
+10. The output buffer is UTF-8; strings in other encodings are transcoded (raising `EncodingError` if impossible).
+
+Removed / packaging:
+11. `Ruby2html::ATTRIBUTE_CACHE`, `Render::METHOD_DEFINITIONS`, `Render#output` and the `Render#fast_escape_html` / `#fast_attributes_to_s` / `#fast_buffer_append` / `#fast_render_tag` methods are removed. Use `Ruby2html.escape_html`, the value returned by `render`, or `current_output`.
+12. Ruby >= 3.1 and (for Rails integration) Rails >= 7.2 are required.
+13. `htmlbeautifier` is no longer a dependency: add `gem 'htmlbeautifier'` if you use `Ruby2html::HtmlBeautifierMiddleware`.
+14. The gem's require path is `lib/gem` only.
+
+## [1.6.6] - 2025-02-10
+
+### Fixed
+- Stop shipping a prebuilt `lib/ruby2html/ruby2html.so`; the extension is compiled on install (`*.so` gitignored).
+
+## [1.6.4] - 2025-02-09
+
+### Fixed
+- Renderer fixes following the C extension introduction.
+
+## [1.6.3] - 2025-02-09
+
+### Fixed
+- Template handler, `form_with` and gemspec fixes for the C extension build.
+
+## [1.6.2] - 2025-02-09
+## [1.6.1] - 2025-02-09
+
+Published to RubyGems; no separate commits in the repository history.
+
+## [1.6.0] - 2025-02-09
+
+### Added
+- C extension (`ext/ruby2html`) for HTML escaping, attribute serialization and buffer appends; `rake compile` via rake-compiler.
+
+## [1.5.8] - 2024-11-01
+## [1.5.7] - 2024-11-01
+
+### Changed
+- Load `htmlbeautifier` from the main entry file; renderer cleanup. Dependency updates.
+
+## [1.5.6] - 2024-08-17
+## [1.5.5] - 2024-08-17
+
+### Changed
+- Template handler declares `handles_encoding?`; Railtie cleanup.
+
+## [1.5.4] - 2024-08-12
+
+### Changed
+- Gemspec cleanup.
+
+## [1.5.3] - 2024-08-12
+
+### Added
+- `turbo_stream` tag (`<turbo-stream>`).
+
+## [1.5.2] - 2024-08-12
+
+### Added
+- `turbo_frame` tag (`<turbo-frame>`).
+
+## [1.5.1] - 2024-08-12
+
+### Fixed
+- `link_to` wrapper simplified.
+
+## [1.5.0] - 2024-08-12
+
+### Added
+- Rails helper wrappers: `form_with` (with `label`, `text_field`, `hidden_field`, `password_field`, `file_field`, `submit`), `button_to`, `link_to`, `image_tag`.
+
+## [1.4.0] - 2024-08-10
+
+### Added
+- `Ruby2html::HtmlBeautifierMiddleware`; runtime dependency on `htmlbeautifier`.
+
+## [1.3.3] - 2024-08-10
+
+### Added
+- Support for `config.action_view.annotate_rendered_view_with_filenames`.
+
+## [1.3.2] - 2024-08-09
+
+### Fixed
+- Keyword option handling in tag methods.
+
+## [1.3.1] - 2024-08-09
+
+### Fixed
+- `ComponentHelper` renderer bug.
+
+## [1.3.0] - 2024-08-09
+
+### Added
+- Calling component methods from component templates; nested renderer tracking.
+
+## [1.2.0] - 2024-08-09
+
+### Added
+- ViewComponent support: `.html.rb` component templates, `Ruby2html::ComponentHelper`.
+
+## [1.1.0] - 2024-08-08
+
+### Added
+- `.rb` ActionView template handler (`*.html.rb` views and partials).
+
+## [1.0.0] - 2024-08-08
+
+### Added
+- Initial release: `Ruby2html::Render` DSL, `Ruby2html::RailsHelper#html` for ERB.
+
+[Unreleased]: https://github.com/sebyx07/ruby2html/compare/v2.1.0...HEAD
+[2.1.0]: https://github.com/sebyx07/ruby2html/compare/v2.0.0...v2.1.0
+[2.0.0]: https://github.com/sebyx07/ruby2html/releases/tag/v2.0.0
+[1.6.6]: https://rubygems.org/gems/ruby2html/versions/1.6.6
+[1.6.4]: https://rubygems.org/gems/ruby2html/versions/1.6.4
+[1.6.3]: https://rubygems.org/gems/ruby2html/versions/1.6.3
+[1.6.2]: https://rubygems.org/gems/ruby2html/versions/1.6.2
+[1.6.1]: https://rubygems.org/gems/ruby2html/versions/1.6.1
+[1.6.0]: https://rubygems.org/gems/ruby2html/versions/1.6.0
+[1.5.8]: https://rubygems.org/gems/ruby2html/versions/1.5.8
+[1.5.7]: https://rubygems.org/gems/ruby2html/versions/1.5.7
+[1.5.6]: https://rubygems.org/gems/ruby2html/versions/1.5.6
+[1.5.5]: https://rubygems.org/gems/ruby2html/versions/1.5.5
+[1.5.4]: https://rubygems.org/gems/ruby2html/versions/1.5.4
+[1.5.3]: https://rubygems.org/gems/ruby2html/versions/1.5.3
+[1.5.2]: https://rubygems.org/gems/ruby2html/versions/1.5.2
+[1.5.1]: https://rubygems.org/gems/ruby2html/versions/1.5.1
+[1.5.0]: https://rubygems.org/gems/ruby2html/versions/1.5.0
+[1.4.0]: https://rubygems.org/gems/ruby2html/versions/1.4.0
+[1.3.3]: https://rubygems.org/gems/ruby2html/versions/1.3.3
+[1.3.2]: https://rubygems.org/gems/ruby2html/versions/1.3.2
+[1.3.1]: https://rubygems.org/gems/ruby2html/versions/1.3.1
+[1.3.0]: https://rubygems.org/gems/ruby2html/versions/1.3.0
+[1.2.0]: https://rubygems.org/gems/ruby2html/versions/1.2.0
+[1.1.0]: https://rubygems.org/gems/ruby2html/versions/1.1.0
+[1.0.0]: https://rubygems.org/gems/ruby2html/versions/1.0.0
diff --git a/apps/ruby2html/Gemfile b/apps/ruby2html/Gemfile
new file mode 100644
index 0000000..606b64e
--- /dev/null
+++ b/apps/ruby2html/Gemfile
@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# The demo app's floor (phlex-rails 2, Rails 8.1). Without it Dependabot resolves with the
+# gemspec's Ruby floor (3.1) and every bundler update fails. Dev/CI Ruby: .ruby-version.
+ruby '>= 3.2'
+
+gem 'rails', '~> 8.1'
+gem 'sprockets-rails'
+gem 'sqlite3', '>= 1.4'
+gem 'puma', '>= 5.0'
+gem 'tzinfo-data', platforms: %i[ windows jruby ]
+gem 'htmlbeautifier'
+gem 'bootsnap', require: false
+
+group :development, :test do
+  gem 'brakeman', require: false
+end
+
+group :development do
+  gem 'web-console'
+end
+
+gem 'rubocop-rails_config', '~> 1.17', require: false
+
+gem 'pry-rails', '~> 0.3.11'
+
+gem 'view_component', '~> 4.0'
+
+gem 'rspec-rails', '~> 8.0'
+
+gem 'capybara', '~> 3.40'
+
+gem 'lefthook', '~> 2.0'
+
+gem 'faker', '~> 3.8'
+
+gem 'slim-rails', '~> 4.0'
+
+gem 'phlex-rails', '~> 2.4'
+
+gem 'rake-compiler', '~> 1.3', require: false
+
+group :test do
+  gem 'benchmark-ips'
+end
+
+# phlex 2.x -> refract uses Prism::MissingNode, which prism 2.x removed. Drop
+# once refract supports prism 2 (also pinned in gemfiles/rails_common.rb).
+gem 'prism', '~> 1.6'
diff --git a/Gemfile.lock b/apps/ruby2html/Gemfile.lock
similarity index 100%
rename from Gemfile.lock
rename to apps/ruby2html/Gemfile.lock
diff --git a/apps/ruby2html/LICENSE b/apps/ruby2html/LICENSE
new file mode 100644
index 0000000..b4ec683
--- /dev/null
+++ b/apps/ruby2html/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 sebi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/apps/ruby2html/README.md b/apps/ruby2html/README.md
new file mode 100644
index 0000000..fad51b1
--- /dev/null
+++ b/apps/ruby2html/README.md
@@ -0,0 +1,263 @@
+# Ruby2html
+
+[![CI](https://github.com/sebyx07/ruby2html/actions/workflows/ci.yml/badge.svg)](https://github.com/sebyx07/ruby2html/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/ruby2html)](https://rubygems.org/gems/ruby2html)
+[![Maintained by developerz.ai](https://img.shields.io/badge/maintained%20by-developerz.ai-6f42c1)](https://developerz.ai)
+
+Write views in pure Ruby; get escaped, compact HTML. A C extension handles escaping, attribute serialization and tag rendering. Works standalone, as Rails `.html.rb` templates, inside ERB, and in ViewComponent.
+
+```ruby
+div class: 'card', 'data-controller': 'card' do
+  h2 @product.title
+  p @product.description
+  a 'Details', href: product_path(@product), class: 'btn'
+end
+```
+
+```html
+<div class="card" data-controller="card"><h2>Lamp</h2><p>Warm &amp; bright</p><a href="/products/1" class="btn">Details</a></div>
+```
+
+## Why ruby2html
+
+- **Fastest Ruby HTML renderer we've measured.** The page benchmark renders 1.35x faster than Erubi (Rails' ERB engine) and 2.4–16x faster than Phlex 2, with 40–90% fewer allocations; in a full Rails request it leads ERB, Slim and Phlex ([numbers](#performance)).
+- **Light.** No runtime dependencies, a 32 KB gem, and `require 'ruby2html'` costs about 0.4 MB and 19 ms. Prism, the Rails glue and the optional beautifier load only when used, or at boot in eager-loading production apps.
+- **Plain Ruby views.** `.html.rb` templates, ERB interop, ViewComponent, or the built-in `Ruby2html::Component`. Escaped by default.
+- **Runs everywhere.** CRuby ≥ 3.1 with a C extension (SIMD escaping on x86_64 and arm64), JRuby with a Java escaper over the pure-Ruby implementation, and TruffleRuby on pure Ruby (faster there than the C extension) — all byte-identical. Rails 7.2+.
+- **AI-ready.** One-file reference for coding agents: [`llms.txt`](llms.txt).
+
+## Installation
+
+Supports all maintained CRuby versions (>= 3.1; CI currently covers 3.3, 3.4 and 4.0), JRuby (pure Ruby plus a Java escaper), TruffleRuby (pure Ruby), and Rails 7.2+; the CI matrix is generated automatically, so new Ruby releases are picked up without edits.
+
+```ruby
+# Gemfile
+gem 'ruby2html'
+```
+
+```bash
+bundle install   # compiles the native extension (needs a C compiler); pure-Ruby fallback otherwise
+```
+
+## AI agents
+
+**This project is maintained by [developerz.ai](https://developerz.ai).** Its maintainer agent triages issues, reviews every pull request, merges every pull request once its author marks it ready and CI passes, watches project health daily, and opens release PRs. The policy is in [`.dz/maintainer/maintainer.yml`](.dz/maintainer/maintainer.yml). Breaking changes and major releases stay with the owner.
+
+- **Using ruby2html in your app?** Point your agent at [`llms.txt`](llms.txt), the complete reference in one file (DSL rules, escaping, Rails, components, forms, pitfalls). Paste this into your app's `CLAUDE.md` / `AGENTS.md`:
+  ```markdown
+  ## ruby2html views
+  `*.html.rb` templates and `html do ... end` blocks use the ruby2html gem. Before editing them read
+  https://github.com/sebyx07/ruby2html/blob/main/apps/ruby2html/llms.txt
+  ```
+- **Working on this repo?** [`AGENTS.md`](AGENTS.md) is the only agent-instructions file (`CLAUDE.md` is a symlink to it): commands, code map, invariants, how to verify a change, CI/release automation.
+- **Claude Code**: project skills in `.claude/skills/` (`release`, `benchmark`, `add-html-tag`, `review`, `debug-render`, `upgrade-deps`), read-only reviewer subagents in `.claude/agents/` (`perf-reviewer`, `xss-auditor`), and `.claude/settings.json` with a safe permission allowlist and a non-blocking recompile-reminder hook.
+
+## Usage
+
+### DSL basics
+
+- Every HTML5 tag is a method (`div`, `p`, `ul`, `li`, `img`, `input`, ...), plus `turbo_frame` / `turbo_stream`.
+- `tag content, **attrs` or `tag(**attrs) { nested tags }`. Text and attribute values are HTML-escaped; numbers and symbols are converted (`td 42`).
+- Raw HTML only from `html_safe` strings (Rails helpers, `'<hr>'.html_safe`), as content or via `plain`. `plain 'text'` escapes.
+- Attributes: `'data-id': 1` or `data: { id: 1 }`, `class: ['btn', active && 'on']`, `disabled: true` → bare `disabled`, `nil`/`false` omitted.
+
+Full rules and pitfalls: [`llms.txt`](llms.txt).
+
+### Rails views (`.html.rb`)
+
+File: `app/views/products/index.html.rb`
+
+```ruby
+div class: 'container' do
+  h1 'Products', class: 'main-title'
+  link_to 'Home', root_path, class: 'btn btn-primary', 'data-turbo': false
+
+  @products.each do |product|
+    h2 product.title, class: 'item-title', id: "product-#{product.id}"
+    p product.description, class: 'item-description'
+  end
+end
+
+plain '<div>Inline html</div>'.html_safe
+render partial: 'shared/navbar'
+```
+
+Controller instance variables are available. Partials can be `.html.rb` too. `link_to`, `image_tag`, `button_to`, `form_with` and `render` write their output directly; other helpers return a value you must output (`h1 t('.title')`, `plain some_safe_html_helper`).
+
+### Inside ERB
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Ruby2html::RailsHelper # exposes the html(context) helper to views
+end
+```
+
+```erb
+<h1>Legacy ERB header</h1>
+<%= html(self) do
+  div class: 'ruby2html-section' do
+    h2 'This section is powered by Ruby2html'
+    @items.each { |item| p item[:title] }
+  end
+end %>
+```
+
+ERB, Slim and Ruby2html views, partials and components can be mixed freely, so adoption can be gradual.
+
+### ViewComponent
+
+```ruby
+class ApplicationComponent < ViewComponent::Base
+  include Ruby2html::ComponentHelper
+end
+```
+
+Inline `call`:
+
+```ruby
+class GreetingComponent < ApplicationComponent
+  def initialize(name)
+    @name = name
+  end
+
+  def call
+    html do
+      h1 "Hello, #{@name}!", class: 'greeting', 'data-user': @name
+      p 'Welcome to Ruby2html!', class: 'welcome-message'
+    end
+  end
+end
+```
+
+Or a sidecar template, `app/components/farewell_component.html.rb`:
+
+```ruby
+div class: 'farewell' do
+  h1 "Goodbye, #{@name}!", class: 'farewell-message'
+end
+```
+
+Public component methods can be called from the template and may emit tags themselves (see `app/components/first_component.rb`).
+
+### `Ruby2html::Component` (no ViewComponent required)
+
+```ruby
+class CardComponent < Ruby2html::Component
+  def initialize(title:)
+    @title = title
+  end
+
+  def view_template
+    div class: 'card' do
+      h2 @title
+      content                              # block passed to render
+      link_to 'More', helpers.root_path
+    end
+  end
+end
+
+# any view or controller
+render CardComponent.new(title: 'Hi')
+```
+
+Tag methods run on the component itself (no instance-variable copying); nested ruby2html components write into the parent's buffer.
+
+### Forms
+
+```ruby
+form_with model: @user do |f|
+  f.label :email
+  f.text_field :email
+  f.submit 'Save'
+end
+```
+
+### Without Rails
+
+```ruby
+require 'ruby2html'
+
+Ruby2html::Render.new do # optional context object: its public methods and ivars become available
+  html do
+    head { title 'Ruby2html Example' }
+    body { h1 'Hello, World!' }
+  end
+end.render
+# => "<html><head><title>Ruby2html Example</title></head><body><h1>Hello, World!</h1></body></html>"
+```
+
+### Pretty HTML in development
+
+```ruby
+# Gemfile (development group): gem 'htmlbeautifier'
+# config/environments/development.rb
+config.middleware.use Ruby2html::HtmlBeautifierMiddleware
+```
+
+## Performance
+
+Benchmarks run in CI on every push to `main` and every pull request ([`.github/workflows/benchmark.yml`](../../.github/workflows/benchmark.yml)): the latest run's summary page has the current table, and PRs get a sticky comment with the delta against `main`. Run them locally with `bundle exec rake bench` (standalone scripts in `bench/`) or `bundle exec rspec spec/benchmarks/` (request-level through the demo app, vs ERB, Slim, Phlex and ViewComponent).
+
+### Snapshot at 2.0.0 release (2026-10-31)
+
+This is a dated snapshot. CI has the live numbers. Measured on Ruby 3.4.7 x86_64 on a busy machine (load average about 7), so read the ratios rather than the absolute figures.
+
+**Page render** (`bench/render_bench.rb`, no Rails): a header with nav, 100 list items with links, images, attributes and escaped text, about 34 KB of HTML.
+
+| Engine | Renders/s | Time per render | Allocations per render |
+|---|---|---|---|
+| **ruby2html 2.0 (C extension)** | **2,676** | **0.37 ms** | **419** |
+| Erubi 1.x (Rails' ERB engine) | 1,988 (1.35x slower) | 0.50 ms | 713 |
+| ruby2html 2.0 (pure Ruby, no C extension; CRuby) | ~820 | ~1.2 ms | 1,029 |
+| Phlex 2.4, enlarged attribute cache¹ | ~1,250 (≈2.4x slower) | ~0.8 ms | 831 |
+| Phlex 2.4, defaults | 164 (16x slower) | 6.1 ms | 6,410 |
+| ruby2html 1.6.6 | ~620 | ~1.6 ms | 3,531 |
+
+¹ Phlex 2's default attribute cache (2 KB, FIFO) misses on per-row values such as ids and hrefs. `Phlex::ATTRIBUTE_CACHE.expand(1_000_000)` is its best case. Phlex 2 also checks URLs for `javascript:`; ruby2html leaves URL validation to you.
+
+**Full Rails request** (`spec/benchmarks/requests_spec.rb`; Rails 8.1, a 7 ms request where most of the time is Rails itself; differences are within ±15% error):
+
+| Engine | Requests/s |
+|---|---|
+| **`Ruby2html::Component`** | **144.5** |
+| **ViewComponent 4 + ruby2html** | **142.2** |
+| **`.html.rb` template** | **139.6** |
+| Slim | 128.3 |
+| ERB | 122.6 |
+| Phlex 2.4 | 116.6 |
+
+**HTML escaping** (SIMD vs scalar): up to 5.9x faster on 10 KB clean text, about 2x on 200-byte strings; short strings take the scalar path.
+
+**Footprint:**
+
+| | Ruby/C lines | Runtime dependencies | `require` cost |
+|---|---|---|---|
+| **ruby2html** | 1.1k Ruby + 0.8k C | none | ~0.4 MB, ~19 ms |
+| phlex + phlex-rails | 6.2k | refract, zeitwerk, railties | ~1.4 MB, ~30 ms (phlex alone) |
+| view_component | 5.3k | actionview, activesupport, prism | |
+| slim | 7.3k | temple, tilt | |
+
+How it is fast:
+
+- **Tag methods in C**: each tag writes open tag, content/block output and close tag straight into one shared buffer (no nested buffers, no `*args`/`**kwargs` allocation without keywords).
+- **HTML escaping**: 16-byte SSE2/NEON scan for `& < > " '`; clean strings are one `memcpy`, dirty strings get their exact size computed once.
+- **Attributes**: written directly into the buffer, no intermediate strings, no cache to thrash or leak.
+- **Lazy loading**: `require 'ruby2html'` loads only the renderer. Production Rails apps load everything at boot, so forked workers share it copy-on-write.
+- **Templates and components**: `.html.rb` templates are rewritten at compile time (Prism) to run in the view itself; `Ruby2html::Component` runs tag methods on the component. No instance-variable copying or `method_missing` per render.
+- A pure-Ruby implementation with identical output is used when the extension is unavailable.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake compile   # build the C extension
+CI=1 bundle exec rspec     # specs (CI=1 skips the slow benchmark spec)
+bundle exec rubocop
+../../bin/rails server     # demo app
+```
+
+The repository is both the gem (`lib/gem/`, `ext/ruby2html/`) and a Rails demo app (`app/`, `config/`). See [CONTRIBUTING.md](CONTRIBUTING.md), [docs/architecture.md](docs/architecture.md), [docs/release.md](docs/release.md) and [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).
diff --git a/Rakefile b/apps/ruby2html/Rakefile
similarity index 89%
rename from Rakefile
rename to apps/ruby2html/Rakefile
index f511055..1a6fd6a 100644
--- a/Rakefile
+++ b/apps/ruby2html/Rakefile
@@ -59,8 +59,9 @@ else
     Rake::ExtensionTask.new('ruby2html') do |ext|
       ext.lib_dir = 'lib/ruby2html'
       ext.ext_dir = 'ext/ruby2html'
-      # Build in tmp/ext, not tmp/: `rake clobber` removes the tmp dir, and tmp/ holds the demo
-      # app's tracked .keep files.
+      # Build in tmp/ext, not tmp/: `rake clobber` removes the tmp dir. rake now runs inside
+      # apps/ruby2html, whose tmp/ holds only build output (the demo app's tracked tmp/.keep
+      # files remain at the repo root).
       ext.tmp_dir = 'tmp/ext'
     end
   rescue LoadError
@@ -90,7 +91,7 @@ desc 'Audit the resolved lockfile against the Ruby advisory database (CI only)'
 task 'audit:advisories' do
   gemfile = ENV['BUNDLE_GEMFILE'].to_s
   if ENV['CI'] && File.basename(gemfile).end_with?('.gemfile')
-    ruby File.expand_path('bin/audit-advisories', __dir__)
+    ruby File.expand_path('../../bin/audit-advisories', __dir__)
   else
     puts 'audit:advisories skipped (CI only, and only for the unlocked matrix gemfiles)'
   end
@@ -106,7 +107,7 @@ CLOBBER.include('pkg')
 
 desc 'Build the gem, install it into a temporary GEM_HOME and render HTML without Rails'
 task smoke: :build do
-  ruby File.expand_path('bin/gem-smoke', __dir__), Dir['pkg/ruby2html-*.gem'].max_by { |f| File.mtime(f) }
+  ruby File.expand_path('../../bin/gem-smoke', __dir__), Dir['pkg/ruby2html-*.gem'].max_by { |f| File.mtime(f) }
 end
 
 # --- Specs -------------------------------------------------------------------
@@ -134,7 +135,12 @@ if defined?(RSpec::Core::RakeTask)
     RSpec::Core::RakeTask.new(:standalone) do |t|
       t.pattern = 'spec/gem/**/*_spec.rb'
       t.exclude_pattern = 'spec/gem/rails/**/*_spec.rb'
-      t.rspec_opts = '-I lib/gem -I lib --require ruby2html'
+      # --require ruby2html only outside the demo app's bundle: loaded before
+      # Rails, the gem's railtie never registers and the app boot dies
+      # (Zeitwerk::NameError on app/**/*.html.rb). Under the app bundle
+      # rails_helper boots Rails, which requires ruby2html itself.
+      standalone = File.basename(ENV['BUNDLE_GEMFILE'].to_s) == 'standalone.gemfile'
+      t.rspec_opts = standalone ? '-I lib/gem -I lib --require ruby2html' : '-I lib/gem -I lib'
     end
   end
   %w[spec:gem spec:standalone].each { |t| Rake::Task[t].enhance([:compile]) } unless ENV['SKIP_COMPILE'] == '1'
diff --git a/app/assets/config/manifest.js b/apps/ruby2html/app/assets/config/manifest.js
similarity index 100%
rename from app/assets/config/manifest.js
rename to apps/ruby2html/app/assets/config/manifest.js
diff --git a/app/assets/images/.keep b/apps/ruby2html/app/assets/images/.keep
similarity index 100%
rename from app/assets/images/.keep
rename to apps/ruby2html/app/assets/images/.keep
diff --git a/app/assets/stylesheets/application.css b/apps/ruby2html/app/assets/stylesheets/application.css
similarity index 100%
rename from app/assets/stylesheets/application.css
rename to apps/ruby2html/app/assets/stylesheets/application.css
diff --git a/app/channels/application_cable/channel.rb b/apps/ruby2html/app/channels/application_cable/channel.rb
similarity index 100%
rename from app/channels/application_cable/channel.rb
rename to apps/ruby2html/app/channels/application_cable/channel.rb
diff --git a/app/channels/application_cable/connection.rb b/apps/ruby2html/app/channels/application_cable/connection.rb
similarity index 100%
rename from app/channels/application_cable/connection.rb
rename to apps/ruby2html/app/channels/application_cable/connection.rb
diff --git a/app/components/application_component.rb b/apps/ruby2html/app/components/application_component.rb
similarity index 100%
rename from app/components/application_component.rb
rename to apps/ruby2html/app/components/application_component.rb
diff --git a/app/components/benchmark_component.rb b/apps/ruby2html/app/components/benchmark_component.rb
similarity index 100%
rename from app/components/benchmark_component.rb
rename to apps/ruby2html/app/components/benchmark_component.rb
diff --git a/app/components/first_component.html.rb b/apps/ruby2html/app/components/first_component.html.rb
similarity index 100%
rename from app/components/first_component.html.rb
rename to apps/ruby2html/app/components/first_component.html.rb
diff --git a/app/components/first_component.rb b/apps/ruby2html/app/components/first_component.rb
similarity index 100%
rename from app/components/first_component.rb
rename to apps/ruby2html/app/components/first_component.rb
diff --git a/app/components/native_benchmark_component.rb b/apps/ruby2html/app/components/native_benchmark_component.rb
similarity index 100%
rename from app/components/native_benchmark_component.rb
rename to apps/ruby2html/app/components/native_benchmark_component.rb
diff --git a/app/components/native_user_card_component.rb b/apps/ruby2html/app/components/native_user_card_component.rb
similarity index 100%
rename from app/components/native_user_card_component.rb
rename to apps/ruby2html/app/components/native_user_card_component.rb
diff --git a/app/components/second_component.rb b/apps/ruby2html/app/components/second_component.rb
similarity index 100%
rename from app/components/second_component.rb
rename to apps/ruby2html/app/components/second_component.rb
diff --git a/app/components/third_component.rb b/apps/ruby2html/app/components/third_component.rb
similarity index 100%
rename from app/components/third_component.rb
rename to apps/ruby2html/app/components/third_component.rb
diff --git a/app/components/third_component/third_component.html.rb b/apps/ruby2html/app/components/third_component/third_component.html.rb
similarity index 100%
rename from app/components/third_component/third_component.html.rb
rename to apps/ruby2html/app/components/third_component/third_component.html.rb
diff --git a/app/controllers/application_controller.rb b/apps/ruby2html/app/controllers/application_controller.rb
similarity index 100%
rename from app/controllers/application_controller.rb
rename to apps/ruby2html/app/controllers/application_controller.rb
diff --git a/app/controllers/benchmark_controller.rb b/apps/ruby2html/app/controllers/benchmark_controller.rb
similarity index 100%
rename from app/controllers/benchmark_controller.rb
rename to apps/ruby2html/app/controllers/benchmark_controller.rb
diff --git a/app/controllers/concerns/.keep b/apps/ruby2html/app/controllers/concerns/.keep
similarity index 100%
rename from app/controllers/concerns/.keep
rename to apps/ruby2html/app/controllers/concerns/.keep
diff --git a/app/controllers/home_controller.rb b/apps/ruby2html/app/controllers/home_controller.rb
similarity index 100%
rename from app/controllers/home_controller.rb
rename to apps/ruby2html/app/controllers/home_controller.rb
diff --git a/app/helpers/application_helper.rb b/apps/ruby2html/app/helpers/application_helper.rb
similarity index 100%
rename from app/helpers/application_helper.rb
rename to apps/ruby2html/app/helpers/application_helper.rb
diff --git a/app/jobs/application_job.rb b/apps/ruby2html/app/jobs/application_job.rb
similarity index 100%
rename from app/jobs/application_job.rb
rename to apps/ruby2html/app/jobs/application_job.rb
diff --git a/app/mailers/application_mailer.rb b/apps/ruby2html/app/mailers/application_mailer.rb
similarity index 100%
rename from app/mailers/application_mailer.rb
rename to apps/ruby2html/app/mailers/application_mailer.rb
diff --git a/app/models/application_record.rb b/apps/ruby2html/app/models/application_record.rb
similarity index 100%
rename from app/models/application_record.rb
rename to apps/ruby2html/app/models/application_record.rb
diff --git a/app/models/concerns/.keep b/apps/ruby2html/app/models/concerns/.keep
similarity index 100%
rename from app/models/concerns/.keep
rename to apps/ruby2html/app/models/concerns/.keep
diff --git a/app/phlex/phlex_view.rb b/apps/ruby2html/app/phlex/phlex_view.rb
similarity index 100%
rename from app/phlex/phlex_view.rb
rename to apps/ruby2html/app/phlex/phlex_view.rb
diff --git a/app/views/benchmark/normal_html.html.erb b/apps/ruby2html/app/views/benchmark/normal_html.html.erb
similarity index 100%
rename from app/views/benchmark/normal_html.html.erb
rename to apps/ruby2html/app/views/benchmark/normal_html.html.erb
diff --git a/app/views/benchmark/ruby_2html.html.rb b/apps/ruby2html/app/views/benchmark/ruby_2html.html.rb
similarity index 100%
rename from app/views/benchmark/ruby_2html.html.rb
rename to apps/ruby2html/app/views/benchmark/ruby_2html.html.rb
diff --git a/app/views/benchmark/slim_html.html.slim b/apps/ruby2html/app/views/benchmark/slim_html.html.slim
similarity index 100%
rename from app/views/benchmark/slim_html.html.slim
rename to apps/ruby2html/app/views/benchmark/slim_html.html.slim
diff --git a/app/views/home/form.html.rb b/apps/ruby2html/app/views/home/form.html.rb
similarity index 100%
rename from app/views/home/form.html.rb
rename to apps/ruby2html/app/views/home/form.html.rb
diff --git a/app/views/home/index.html.erb b/apps/ruby2html/app/views/home/index.html.erb
similarity index 100%
rename from app/views/home/index.html.erb
rename to apps/ruby2html/app/views/home/index.html.erb
diff --git a/app/views/home/rb_files.html.rb b/apps/ruby2html/app/views/home/rb_files.html.rb
similarity index 100%
rename from app/views/home/rb_files.html.rb
rename to apps/ruby2html/app/views/home/rb_files.html.rb
diff --git a/app/views/layouts/application.html.erb b/apps/ruby2html/app/views/layouts/application.html.erb
similarity index 100%
rename from app/views/layouts/application.html.erb
rename to apps/ruby2html/app/views/layouts/application.html.erb
diff --git a/app/views/layouts/mailer.html.erb b/apps/ruby2html/app/views/layouts/mailer.html.erb
similarity index 100%
rename from app/views/layouts/mailer.html.erb
rename to apps/ruby2html/app/views/layouts/mailer.html.erb
diff --git a/app/views/layouts/mailer.text.erb b/apps/ruby2html/app/views/layouts/mailer.text.erb
similarity index 100%
rename from app/views/layouts/mailer.text.erb
rename to apps/ruby2html/app/views/layouts/mailer.text.erb
diff --git a/app/views/pwa/manifest.json.erb b/apps/ruby2html/app/views/pwa/manifest.json.erb
similarity index 100%
rename from app/views/pwa/manifest.json.erb
rename to apps/ruby2html/app/views/pwa/manifest.json.erb
diff --git a/app/views/pwa/service-worker.js b/apps/ruby2html/app/views/pwa/service-worker.js
similarity index 100%
rename from app/views/pwa/service-worker.js
rename to apps/ruby2html/app/views/pwa/service-worker.js
diff --git a/app/views/shared/_footer.html.rb b/apps/ruby2html/app/views/shared/_footer.html.rb
similarity index 100%
rename from app/views/shared/_footer.html.rb
rename to apps/ruby2html/app/views/shared/_footer.html.rb
diff --git a/app/views/shared/_navbar.html.erb b/apps/ruby2html/app/views/shared/_navbar.html.erb
similarity index 100%
rename from app/views/shared/_navbar.html.erb
rename to apps/ruby2html/app/views/shared/_navbar.html.erb
diff --git a/bench/escape_bench.rb b/apps/ruby2html/bench/escape_bench.rb
similarity index 100%
rename from bench/escape_bench.rb
rename to apps/ruby2html/bench/escape_bench.rb
diff --git a/bench/render_bench.rb b/apps/ruby2html/bench/render_bench.rb
similarity index 100%
rename from bench/render_bench.rb
rename to apps/ruby2html/bench/render_bench.rb
diff --git a/bench/tag_bench.rb b/apps/ruby2html/bench/tag_bench.rb
similarity index 100%
rename from bench/tag_bench.rb
rename to apps/ruby2html/bench/tag_bench.rb
diff --git a/config.ru b/apps/ruby2html/config.ru
similarity index 100%
rename from config.ru
rename to apps/ruby2html/config.ru
diff --git a/config/application.rb b/apps/ruby2html/config/application.rb
similarity index 100%
rename from config/application.rb
rename to apps/ruby2html/config/application.rb
diff --git a/config/boot.rb b/apps/ruby2html/config/boot.rb
similarity index 100%
rename from config/boot.rb
rename to apps/ruby2html/config/boot.rb
diff --git a/config/brakeman.yml b/apps/ruby2html/config/brakeman.yml
similarity index 100%
rename from config/brakeman.yml
rename to apps/ruby2html/config/brakeman.yml
diff --git a/config/cable.yml b/apps/ruby2html/config/cable.yml
similarity index 100%
rename from config/cable.yml
rename to apps/ruby2html/config/cable.yml
diff --git a/config/credentials.yml.enc b/apps/ruby2html/config/credentials.yml.enc
similarity index 100%
rename from config/credentials.yml.enc
rename to apps/ruby2html/config/credentials.yml.enc
diff --git a/config/database.yml b/apps/ruby2html/config/database.yml
similarity index 100%
rename from config/database.yml
rename to apps/ruby2html/config/database.yml
diff --git a/config/environment.rb b/apps/ruby2html/config/environment.rb
similarity index 100%
rename from config/environment.rb
rename to apps/ruby2html/config/environment.rb
diff --git a/config/environments/development.rb b/apps/ruby2html/config/environments/development.rb
similarity index 100%
rename from config/environments/development.rb
rename to apps/ruby2html/config/environments/development.rb
diff --git a/config/environments/production.rb b/apps/ruby2html/config/environments/production.rb
similarity index 100%
rename from config/environments/production.rb
rename to apps/ruby2html/config/environments/production.rb
diff --git a/config/environments/test.rb b/apps/ruby2html/config/environments/test.rb
similarity index 100%
rename from config/environments/test.rb
rename to apps/ruby2html/config/environments/test.rb
diff --git a/config/initializers/assets.rb b/apps/ruby2html/config/initializers/assets.rb
similarity index 100%
rename from config/initializers/assets.rb
rename to apps/ruby2html/config/initializers/assets.rb
diff --git a/config/initializers/content_security_policy.rb b/apps/ruby2html/config/initializers/content_security_policy.rb
similarity index 100%
rename from config/initializers/content_security_policy.rb
rename to apps/ruby2html/config/initializers/content_security_policy.rb
diff --git a/config/initializers/filter_parameter_logging.rb b/apps/ruby2html/config/initializers/filter_parameter_logging.rb
similarity index 100%
rename from config/initializers/filter_parameter_logging.rb
rename to apps/ruby2html/config/initializers/filter_parameter_logging.rb
diff --git a/config/initializers/inflections.rb b/apps/ruby2html/config/initializers/inflections.rb
similarity index 100%
rename from config/initializers/inflections.rb
rename to apps/ruby2html/config/initializers/inflections.rb
diff --git a/config/initializers/permissions_policy.rb b/apps/ruby2html/config/initializers/permissions_policy.rb
similarity index 100%
rename from config/initializers/permissions_policy.rb
rename to apps/ruby2html/config/initializers/permissions_policy.rb
diff --git a/config/locales/en.yml b/apps/ruby2html/config/locales/en.yml
similarity index 100%
rename from config/locales/en.yml
rename to apps/ruby2html/config/locales/en.yml
diff --git a/config/puma.rb b/apps/ruby2html/config/puma.rb
similarity index 100%
rename from config/puma.rb
rename to apps/ruby2html/config/puma.rb
diff --git a/config/routes.rb b/apps/ruby2html/config/routes.rb
similarity index 100%
rename from config/routes.rb
rename to apps/ruby2html/config/routes.rb
diff --git a/config/storage.yml b/apps/ruby2html/config/storage.yml
similarity index 100%
rename from config/storage.yml
rename to apps/ruby2html/config/storage.yml
diff --git a/db/seeds.rb b/apps/ruby2html/db/seeds.rb
similarity index 100%
rename from db/seeds.rb
rename to apps/ruby2html/db/seeds.rb
diff --git a/ext/java/Ruby2htmlJrubyService.java b/apps/ruby2html/ext/java/Ruby2htmlJrubyService.java
similarity index 100%
rename from ext/java/Ruby2htmlJrubyService.java
rename to apps/ruby2html/ext/java/Ruby2htmlJrubyService.java
diff --git a/ext/ruby2html/attributes.c b/apps/ruby2html/ext/ruby2html/attributes.c
similarity index 100%
rename from ext/ruby2html/attributes.c
rename to apps/ruby2html/ext/ruby2html/attributes.c
diff --git a/ext/ruby2html/buffer.h b/apps/ruby2html/ext/ruby2html/buffer.h
similarity index 100%
rename from ext/ruby2html/buffer.h
rename to apps/ruby2html/ext/ruby2html/buffer.h
diff --git a/ext/ruby2html/content.c b/apps/ruby2html/ext/ruby2html/content.c
similarity index 100%
rename from ext/ruby2html/content.c
rename to apps/ruby2html/ext/ruby2html/content.c
diff --git a/ext/ruby2html/extconf.rb b/apps/ruby2html/ext/ruby2html/extconf.rb
similarity index 100%
rename from ext/ruby2html/extconf.rb
rename to apps/ruby2html/ext/ruby2html/extconf.rb
diff --git a/ext/ruby2html/html_escape.c b/apps/ruby2html/ext/ruby2html/html_escape.c
similarity index 100%
rename from ext/ruby2html/html_escape.c
rename to apps/ruby2html/ext/ruby2html/html_escape.c
diff --git a/ext/ruby2html/ruby2html.c b/apps/ruby2html/ext/ruby2html/ruby2html.c
similarity index 100%
rename from ext/ruby2html/ruby2html.c
rename to apps/ruby2html/ext/ruby2html/ruby2html.c
diff --git a/ext/ruby2html/ruby2html.h b/apps/ruby2html/ext/ruby2html/ruby2html.h
similarity index 100%
rename from ext/ruby2html/ruby2html.h
rename to apps/ruby2html/ext/ruby2html/ruby2html.h
diff --git a/ext/ruby2html/tag_render.c b/apps/ruby2html/ext/ruby2html/tag_render.c
similarity index 100%
rename from ext/ruby2html/tag_render.c
rename to apps/ruby2html/ext/ruby2html/tag_render.c
diff --git a/gemfiles/rails.gemfile b/apps/ruby2html/gemfiles/rails.gemfile
similarity index 100%
rename from gemfiles/rails.gemfile
rename to apps/ruby2html/gemfiles/rails.gemfile
diff --git a/gemfiles/rails_common.rb b/apps/ruby2html/gemfiles/rails_common.rb
similarity index 100%
rename from gemfiles/rails_common.rb
rename to apps/ruby2html/gemfiles/rails_common.rb
diff --git a/gemfiles/standalone.gemfile b/apps/ruby2html/gemfiles/standalone.gemfile
similarity index 100%
rename from gemfiles/standalone.gemfile
rename to apps/ruby2html/gemfiles/standalone.gemfile
diff --git a/lib/assets/.keep b/apps/ruby2html/lib/assets/.keep
similarity index 100%
rename from lib/assets/.keep
rename to apps/ruby2html/lib/assets/.keep
diff --git a/lib/gem/ruby2html.rb b/apps/ruby2html/lib/gem/ruby2html.rb
similarity index 100%
rename from lib/gem/ruby2html.rb
rename to apps/ruby2html/lib/gem/ruby2html.rb
diff --git a/lib/gem/ruby2html/component.rb b/apps/ruby2html/lib/gem/ruby2html/component.rb
similarity index 100%
rename from lib/gem/ruby2html/component.rb
rename to apps/ruby2html/lib/gem/ruby2html/component.rb
diff --git a/lib/gem/ruby2html/component_helper.rb b/apps/ruby2html/lib/gem/ruby2html/component_helper.rb
similarity index 100%
rename from lib/gem/ruby2html/component_helper.rb
rename to apps/ruby2html/lib/gem/ruby2html/component_helper.rb
diff --git a/lib/gem/ruby2html/html_beautifier_middleware.rb b/apps/ruby2html/lib/gem/ruby2html/html_beautifier_middleware.rb
similarity index 100%
rename from lib/gem/ruby2html/html_beautifier_middleware.rb
rename to apps/ruby2html/lib/gem/ruby2html/html_beautifier_middleware.rb
diff --git a/lib/gem/ruby2html/rails_components/base_component.rb b/apps/ruby2html/lib/gem/ruby2html/rails_components/base_component.rb
similarity index 100%
rename from lib/gem/ruby2html/rails_components/base_component.rb
rename to apps/ruby2html/lib/gem/ruby2html/rails_components/base_component.rb
diff --git a/lib/gem/ruby2html/rails_components/button_to.rb b/apps/ruby2html/lib/gem/ruby2html/rails_components/button_to.rb
similarity index 100%
rename from lib/gem/ruby2html/rails_components/button_to.rb
rename to apps/ruby2html/lib/gem/ruby2html/rails_components/button_to.rb
diff --git a/lib/gem/ruby2html/rails_components/form_with.rb b/apps/ruby2html/lib/gem/ruby2html/rails_components/form_with.rb
similarity index 100%
rename from lib/gem/ruby2html/rails_components/form_with.rb
rename to apps/ruby2html/lib/gem/ruby2html/rails_components/form_with.rb
diff --git a/lib/gem/ruby2html/rails_components/image_tag.rb b/apps/ruby2html/lib/gem/ruby2html/rails_components/image_tag.rb
similarity index 100%
rename from lib/gem/ruby2html/rails_components/image_tag.rb
rename to apps/ruby2html/lib/gem/ruby2html/rails_components/image_tag.rb
diff --git a/lib/gem/ruby2html/rails_components/link_to.rb b/apps/ruby2html/lib/gem/ruby2html/rails_components/link_to.rb
similarity index 100%
rename from lib/gem/ruby2html/rails_components/link_to.rb
rename to apps/ruby2html/lib/gem/ruby2html/rails_components/link_to.rb
diff --git a/lib/gem/ruby2html/rails_components/output_capture.rb b/apps/ruby2html/lib/gem/ruby2html/rails_components/output_capture.rb
similarity index 100%
rename from lib/gem/ruby2html/rails_components/output_capture.rb
rename to apps/ruby2html/lib/gem/ruby2html/rails_components/output_capture.rb
diff --git a/lib/gem/ruby2html/rails_components/template_collector.rb b/apps/ruby2html/lib/gem/ruby2html/rails_components/template_collector.rb
similarity index 100%
rename from lib/gem/ruby2html/rails_components/template_collector.rb
rename to apps/ruby2html/lib/gem/ruby2html/rails_components/template_collector.rb
diff --git a/lib/gem/ruby2html/rails_components/template_compiler.rb b/apps/ruby2html/lib/gem/ruby2html/rails_components/template_compiler.rb
similarity index 100%
rename from lib/gem/ruby2html/rails_components/template_compiler.rb
rename to apps/ruby2html/lib/gem/ruby2html/rails_components/template_compiler.rb
diff --git a/lib/gem/ruby2html/rails_components/template_helpers.rb b/apps/ruby2html/lib/gem/ruby2html/rails_components/template_helpers.rb
similarity index 100%
rename from lib/gem/ruby2html/rails_components/template_helpers.rb
rename to apps/ruby2html/lib/gem/ruby2html/rails_components/template_helpers.rb
diff --git a/lib/gem/ruby2html/rails_helper.rb b/apps/ruby2html/lib/gem/ruby2html/rails_helper.rb
similarity index 100%
rename from lib/gem/ruby2html/rails_helper.rb
rename to apps/ruby2html/lib/gem/ruby2html/rails_helper.rb
diff --git a/lib/gem/ruby2html/railtie.rb b/apps/ruby2html/lib/gem/ruby2html/railtie.rb
similarity index 100%
rename from lib/gem/ruby2html/railtie.rb
rename to apps/ruby2html/lib/gem/ruby2html/railtie.rb
diff --git a/lib/gem/ruby2html/render.rb b/apps/ruby2html/lib/gem/ruby2html/render.rb
similarity index 100%
rename from lib/gem/ruby2html/render.rb
rename to apps/ruby2html/lib/gem/ruby2html/render.rb
diff --git a/lib/gem/ruby2html/render/pure_ruby.rb b/apps/ruby2html/lib/gem/ruby2html/render/pure_ruby.rb
similarity index 100%
rename from lib/gem/ruby2html/render/pure_ruby.rb
rename to apps/ruby2html/lib/gem/ruby2html/render/pure_ruby.rb
diff --git a/lib/gem/ruby2html/version.rb b/apps/ruby2html/lib/gem/ruby2html/version.rb
similarity index 100%
rename from lib/gem/ruby2html/version.rb
rename to apps/ruby2html/lib/gem/ruby2html/version.rb
diff --git a/lib/tasks/.keep b/apps/ruby2html/lib/tasks/.keep
similarity index 100%
rename from lib/tasks/.keep
rename to apps/ruby2html/lib/tasks/.keep
diff --git a/llms.txt b/apps/ruby2html/llms.txt
similarity index 100%
rename from llms.txt
rename to apps/ruby2html/llms.txt
diff --git a/log/.keep b/apps/ruby2html/log/.keep
similarity index 100%
rename from log/.keep
rename to apps/ruby2html/log/.keep
diff --git a/public/404.html b/apps/ruby2html/public/404.html
similarity index 100%
rename from public/404.html
rename to apps/ruby2html/public/404.html
diff --git a/public/406-unsupported-browser.html b/apps/ruby2html/public/406-unsupported-browser.html
similarity index 100%
rename from public/406-unsupported-browser.html
rename to apps/ruby2html/public/406-unsupported-browser.html
diff --git a/public/422.html b/apps/ruby2html/public/422.html
similarity index 100%
rename from public/422.html
rename to apps/ruby2html/public/422.html
diff --git a/public/500.html b/apps/ruby2html/public/500.html
similarity index 100%
rename from public/500.html
rename to apps/ruby2html/public/500.html
diff --git a/public/icon.png b/apps/ruby2html/public/icon.png
similarity index 100%
rename from public/icon.png
rename to apps/ruby2html/public/icon.png
diff --git a/public/icon.svg b/apps/ruby2html/public/icon.svg
similarity index 100%
rename from public/icon.svg
rename to apps/ruby2html/public/icon.svg
diff --git a/public/robots.txt b/apps/ruby2html/public/robots.txt
similarity index 100%
rename from public/robots.txt
rename to apps/ruby2html/public/robots.txt
diff --git a/ruby2html.gemspec b/apps/ruby2html/ruby2html.gemspec
similarity index 91%
rename from ruby2html.gemspec
rename to apps/ruby2html/ruby2html.gemspec
index 876b70d..f1d783a 100644
--- a/ruby2html.gemspec
+++ b/apps/ruby2html/ruby2html.gemspec
@@ -47,6 +47,10 @@ Gem::Specification.new do |spec|
   # also a Rails demo app, so never glob all of lib/ (lib/assets, lib/tasks,
   # and the locally compiled lib/ruby2html/ruby2html.so must stay out).
   root = __dir__
+  # README.md / LICENSE / CHANGELOG.md beside this gemspec are packaging copies of
+  # the repository-root files (which stay at the checkout root), kept in sync: the
+  # File.file? select below runs under Dir.chdir(root), and bin/gem-smoke requires
+  # them in the built gem.
   spec.files = Dir.chdir(root) do
     files = Dir.glob(%w[lib/gem/**/*.rb ext/ruby2html/*.{c,h,rb} ext/java/*.java]) +
             %w[README.md LICENSE CHANGELOG.md].select { |f| File.file?(f) }
diff --git a/spec/benchmarks/requests_spec.rb b/apps/ruby2html/spec/benchmarks/requests_spec.rb
similarity index 100%
rename from spec/benchmarks/requests_spec.rb
rename to apps/ruby2html/spec/benchmarks/requests_spec.rb
diff --git a/spec/bin/brakeman_spec.rb b/apps/ruby2html/spec/bin/brakeman_spec.rb
similarity index 99%
rename from spec/bin/brakeman_spec.rb
rename to apps/ruby2html/spec/bin/brakeman_spec.rb
index 64d4cfd..f2d8f9a 100644
--- a/spec/bin/brakeman_spec.rb
+++ b/apps/ruby2html/spec/bin/brakeman_spec.rb
@@ -5,7 +5,7 @@
 require 'tmpdir'
 
 RSpec.describe 'bin/brakeman' do
-  let(:script_path) { File.expand_path('../../bin/brakeman', __dir__) }
+  let(:script_path) { File.expand_path('../../../../bin/brakeman', __dir__) }
   # The version the bundle actually locks (Gemfile.lock), not a literal: this
   # spec cannot silently drift from the brakeman CI scans with.
   let(:locked_version) { Gem.loaded_specs['brakeman'].version.to_s }
diff --git a/spec/bin/ruby_version_spec.rb b/apps/ruby2html/spec/bin/ruby_version_spec.rb
similarity index 54%
rename from spec/bin/ruby_version_spec.rb
rename to apps/ruby2html/spec/bin/ruby_version_spec.rb
index c70790a..d0ee730 100644
--- a/spec/bin/ruby_version_spec.rb
+++ b/apps/ruby2html/spec/bin/ruby_version_spec.rb
@@ -1,15 +1,16 @@
 # frozen_string_literal: true
 
-# Guards the single-source Ruby pin: .ruby-version is the only file holding
-# the literal version, mise.toml derives its [tools] entry from it through the
-# read_file template, and bin/setup installs the toolchain with a bare
-# `mise install`. A version literal sneaking back into mise.toml, the template
-# referencing another file, a non-X.Y.Z pin or an explicit `ruby@` argument in
-# bin/setup all fail this spec.
+# Guards the single-source Ruby pin: apps/ruby2html/.ruby-version is the only
+# file holding the literal version (the root .ruby-version is a symlink to it),
+# the repo-root mise.toml derives its [tools] entry from it through the
+# read_file template, and the repo-root bin/setup installs the toolchain with a
+# bare `mise install`. A version literal sneaking back into mise.toml, the
+# template referencing another file, a non-X.Y.Z pin or an explicit `ruby@`
+# argument in bin/setup all fail this spec.
 RSpec.describe '.ruby-version as the single Ruby version source' do
   let(:ruby_version) { File.read(File.expand_path('../../.ruby-version', __dir__)).strip }
-  let(:mise_toml) { File.read(File.expand_path('../../mise.toml', __dir__)) }
-  let(:setup_script) { File.read(File.expand_path('../../bin/setup', __dir__)) }
+  let(:mise_toml) { File.read(File.expand_path('../../../../mise.toml', __dir__)) }
+  let(:setup_script) { File.read(File.expand_path('../../../../bin/setup', __dir__)) }
   let(:ruby_request) do
     mise_toml[/^\s*ruby\s*=\s*"([^"]*)"/, 1] || raise('mise.toml has no ruby = "..." entry')
   end
@@ -26,7 +27,9 @@
     referenced_path = ruby_request[/read_file\(\s*path\s*=\s*'([^']*)'\s*\)/, 1]
 
     expect(referenced_path).to eq('.ruby-version')
-    referenced = File.read(File.expand_path("../../#{referenced_path}", __dir__)).strip
+    # read_file resolves relative to mise.toml's directory: the repo root,
+    # whose .ruby-version is a symlink to the app pin read above.
+    referenced = File.read(File.expand_path("../../../../#{referenced_path}", __dir__)).strip
     expect(referenced).to eq(ruby_version)
   end
 
diff --git a/spec/bin/setup_spec.rb b/apps/ruby2html/spec/bin/setup_spec.rb
similarity index 95%
rename from spec/bin/setup_spec.rb
rename to apps/ruby2html/spec/bin/setup_spec.rb
index b4687b0..2e3e7ee 100644
--- a/spec/bin/setup_spec.rb
+++ b/apps/ruby2html/spec/bin/setup_spec.rb
@@ -29,7 +29,7 @@ def write_stub(dir, name)
     FileUtils.chmod(0o755, path)
   end
 
-  let(:script_path) { File.expand_path('../../bin/setup', __dir__) }
+  let(:script_path) { File.expand_path('../../../../bin/setup', __dir__) }
 
   it 'runs mise install when the version check succeeds, before the first bundle call' do
     _stdout, status, calls = run_setup('bundle', 'mise')
diff --git a/spec/features/home_spec.rb b/apps/ruby2html/spec/features/home_spec.rb
similarity index 100%
rename from spec/features/home_spec.rb
rename to apps/ruby2html/spec/features/home_spec.rb
diff --git a/spec/features/native_component_spec.rb b/apps/ruby2html/spec/features/native_component_spec.rb
similarity index 100%
rename from spec/features/native_component_spec.rb
rename to apps/ruby2html/spec/features/native_component_spec.rb
diff --git a/spec/features/rails_integration_spec.rb b/apps/ruby2html/spec/features/rails_integration_spec.rb
similarity index 100%
rename from spec/features/rails_integration_spec.rb
rename to apps/ruby2html/spec/features/rails_integration_spec.rb
diff --git a/spec/gem/rails/component_helper_spec.rb b/apps/ruby2html/spec/gem/rails/component_helper_spec.rb
similarity index 100%
rename from spec/gem/rails/component_helper_spec.rb
rename to apps/ruby2html/spec/gem/rails/component_helper_spec.rb
diff --git a/spec/gem/rails/component_spec.rb b/apps/ruby2html/spec/gem/rails/component_spec.rb
similarity index 100%
rename from spec/gem/rails/component_spec.rb
rename to apps/ruby2html/spec/gem/rails/component_spec.rb
diff --git a/spec/gem/rails/html_beautifier_middleware_spec.rb b/apps/ruby2html/spec/gem/rails/html_beautifier_middleware_spec.rb
similarity index 100%
rename from spec/gem/rails/html_beautifier_middleware_spec.rb
rename to apps/ruby2html/spec/gem/rails/html_beautifier_middleware_spec.rb
diff --git a/spec/gem/rails/rails_components_spec.rb b/apps/ruby2html/spec/gem/rails/rails_components_spec.rb
similarity index 100%
rename from spec/gem/rails/rails_components_spec.rb
rename to apps/ruby2html/spec/gem/rails/rails_components_spec.rb
diff --git a/spec/gem/rails/support/template_rendering.rb b/apps/ruby2html/spec/gem/rails/support/template_rendering.rb
similarity index 100%
rename from spec/gem/rails/support/template_rendering.rb
rename to apps/ruby2html/spec/gem/rails/support/template_rendering.rb
diff --git a/spec/gem/rails/template_capture_spec.rb b/apps/ruby2html/spec/gem/rails/template_capture_spec.rb
similarity index 100%
rename from spec/gem/rails/template_capture_spec.rb
rename to apps/ruby2html/spec/gem/rails/template_capture_spec.rb
diff --git a/spec/gem/rails/template_compiler_spec.rb b/apps/ruby2html/spec/gem/rails/template_compiler_spec.rb
similarity index 100%
rename from spec/gem/rails/template_compiler_spec.rb
rename to apps/ruby2html/spec/gem/rails/template_compiler_spec.rb
diff --git a/spec/gem/rails/template_handler_spec.rb b/apps/ruby2html/spec/gem/rails/template_handler_spec.rb
similarity index 100%
rename from spec/gem/rails/template_handler_spec.rb
rename to apps/ruby2html/spec/gem/rails/template_handler_spec.rb
diff --git a/spec/gem/rails/template_locals_spec.rb b/apps/ruby2html/spec/gem/rails/template_locals_spec.rb
similarity index 100%
rename from spec/gem/rails/template_locals_spec.rb
rename to apps/ruby2html/spec/gem/rails/template_locals_spec.rb
diff --git a/spec/gem/rails/view_component_spec.rb b/apps/ruby2html/spec/gem/rails/view_component_spec.rb
similarity index 100%
rename from spec/gem/rails/view_component_spec.rb
rename to apps/ruby2html/spec/gem/rails/view_component_spec.rb
diff --git a/spec/gem/render_attributes_spec.rb b/apps/ruby2html/spec/gem/render_attributes_spec.rb
similarity index 100%
rename from spec/gem/render_attributes_spec.rb
rename to apps/ruby2html/spec/gem/render_attributes_spec.rb
diff --git a/spec/gem/render_escape_spec.rb b/apps/ruby2html/spec/gem/render_escape_spec.rb
similarity index 100%
rename from spec/gem/render_escape_spec.rb
rename to apps/ruby2html/spec/gem/render_escape_spec.rb
diff --git a/spec/gem/render_hardening_spec.rb b/apps/ruby2html/spec/gem/render_hardening_spec.rb
similarity index 100%
rename from spec/gem/render_hardening_spec.rb
rename to apps/ruby2html/spec/gem/render_hardening_spec.rb
diff --git a/spec/gem/render_parity_spec.rb b/apps/ruby2html/spec/gem/render_parity_spec.rb
similarity index 100%
rename from spec/gem/render_parity_spec.rb
rename to apps/ruby2html/spec/gem/render_parity_spec.rb
diff --git a/spec/gem/render_spec.rb b/apps/ruby2html/spec/gem/render_spec.rb
similarity index 100%
rename from spec/gem/render_spec.rb
rename to apps/ruby2html/spec/gem/render_spec.rb
diff --git a/spec/gem/render_spec_helper.rb b/apps/ruby2html/spec/gem/render_spec_helper.rb
similarity index 100%
rename from spec/gem/render_spec_helper.rb
rename to apps/ruby2html/spec/gem/render_spec_helper.rb
diff --git a/spec/rails_helper.rb b/apps/ruby2html/spec/rails_helper.rb
similarity index 100%
rename from spec/rails_helper.rb
rename to apps/ruby2html/spec/rails_helper.rb
diff --git a/spec/spec_helper.rb b/apps/ruby2html/spec/spec_helper.rb
similarity index 100%
rename from spec/spec_helper.rb
rename to apps/ruby2html/spec/spec_helper.rb
diff --git a/storage/.keep b/apps/ruby2html/storage/.keep
similarity index 100%
rename from storage/.keep
rename to apps/ruby2html/storage/.keep
diff --git a/vendor/.keep b/apps/ruby2html/vendor/.keep
similarity index 100%
rename from vendor/.keep
rename to apps/ruby2html/vendor/.keep
diff --git a/bin/audit-advisories b/bin/audit-advisories
index 5c2929d..f593a2f 100755
--- a/bin/audit-advisories
+++ b/bin/audit-advisories
@@ -5,13 +5,13 @@ require 'pathname'
 
 # Audits one resolved lockfile against the Ruby advisory database.
 #
-#   bin/audit-advisories                       # the lockfile of BUNDLE_GEMFILE, else Gemfile.lock
+#   bin/audit-advisories                       # the lockfile of BUNDLE_GEMFILE, else apps/ruby2html/Gemfile.lock
 #   bin/audit-advisories path/to/Gemfile.lock  # an explicit lockfile
 #
 # The matrix jobs install an unlocked gemfile: ruby/setup-ruby resolves it
 # during the job and writes the lockfile next to it (gemfiles/*.lock,
 # gitignored, never committed). That resolved set is what the job installs, so
-# it is what has to be audited; the committed root Gemfile.lock has its own CI
+# it is what has to be audited; the committed apps/ruby2html/Gemfile.lock has its own CI
 # job (bundle-audit check --update).
 #
 # bundle-audit exits 1 when it finds an advisory: this script exits with
@@ -99,7 +99,7 @@ def clean_env
 end
 
 # The lockfile to audit: ARGV[0], else the one Bundler writes next to
-# BUNDLE_GEMFILE, else the committed root Gemfile.lock.
+# BUNDLE_GEMFILE, else the committed apps/ruby2html/Gemfile.lock.
 def lockfile
   argument = ARGV[0].to_s
   return File.expand_path(argument) unless argument.empty?
@@ -107,7 +107,7 @@ def lockfile
   gemfile = ENV['BUNDLE_GEMFILE'].to_s
   return File.expand_path("#{gemfile}.lock") unless gemfile.empty?
 
-  File.join(ROOT, 'Gemfile.lock')
+  File.join(ROOT, 'apps/ruby2html/Gemfile.lock')
 end
 
 # The path bundle-audit gets for the lockfile: it resolves --gemfile-lock
diff --git a/bin/bench-report b/bin/bench-report
index 1bf8cf5..dbc0616 100755
--- a/bin/bench-report
+++ b/bin/bench-report
@@ -18,7 +18,7 @@ require 'rbconfig'
 require 'time'
 require 'tmpdir'
 
-ROOT = File.expand_path('..', __dir__)
+ROOT = File.expand_path('../apps/ruby2html', __dir__)
 
 HOOK = <<~'RUBY'
   # Preloaded into each benchmark process (ruby -r).
diff --git a/bin/build-ext b/bin/build-ext
index b590680..46af721 100755
--- a/bin/build-ext
+++ b/bin/build-ext
@@ -19,7 +19,7 @@ require 'fileutils'
 require 'optparse'
 require 'rbconfig'
 
-ROOT = File.expand_path('..', __dir__)
+ROOT = File.expand_path('../apps/ruby2html', __dir__)
 opts = { cc: nil, werror: false, sanitize: false, out: File.join(ROOT, 'lib/ruby2html') }
 OptionParser.new do |o|
   o.on('--cc=CC', 'C compiler (default: the one Ruby was built with)') { |v| opts[:cc] = v }
diff --git a/bin/bundle b/bin/bundle
index 50da5fd..20b8912 100755
--- a/bin/bundle
+++ b/bin/bundle
@@ -41,7 +41,7 @@ m = Module.new do
     gemfile = ENV["BUNDLE_GEMFILE"]
     return gemfile if gemfile && !gemfile.empty?
 
-    File.expand_path("../Gemfile", __dir__)
+    File.expand_path("../apps/ruby2html/Gemfile", __dir__)
   end
 
   def lockfile
diff --git a/bin/check b/bin/check
index 57186ec..c83aeaa 100755
--- a/bin/check
+++ b/bin/check
@@ -1,5 +1,8 @@
 #!/usr/bin/env bash
-# one-command check (typecheck + lint + test) — established by dz-runner setup mode. One command; adjust as the repo grows.
+# one-command check (compile + lint + test) — established by dz-runner setup mode.
+# The app + gem live under apps/ruby2html, so bundler/rake/rspec/brakeman run
+# from there; lint covers the app tree plus the root bin/ scripts, via the
+# ../../bin/rubocop binstub (it pins the moved apps/ruby2html/.rubocop.yml).
 set -euo pipefail
-cd "$(dirname "$0")/.."
-bundle exec rake compile && bin/rubocop --parallel && CI=1 bundle exec rspec && bin/brakeman --no-pager
+cd "$(dirname "$0")/../apps/ruby2html"
+bundle exec rake compile && ../../bin/rubocop --parallel . ../../bin && CI=1 bundle exec rspec && ../../bin/brakeman --no-pager
diff --git a/bin/console b/bin/console
index cb60724..86f4d23 100755
--- a/bin/console
+++ b/bin/console
@@ -7,7 +7,7 @@
 #
 #   >> html { div(class: 'card') { h1 'Hi'; plain 'x < y' } }
 
-$LOAD_PATH.unshift(File.expand_path('../lib/gem', __dir__))
+$LOAD_PATH.unshift(File.expand_path('../apps/ruby2html/lib/gem', __dir__))
 require 'ruby2html'
 require 'irb'
 
diff --git a/bin/gem-smoke b/bin/gem-smoke
index 82aaea2..94b01e3 100755
--- a/bin/gem-smoke
+++ b/bin/gem-smoke
@@ -14,7 +14,7 @@ require 'rbconfig'
 require 'rubygems/package'
 require 'tmpdir'
 
-ROOT = File.expand_path('..', __dir__)
+ROOT = File.expand_path('../apps/ruby2html', __dir__)
 
 def run!(env, *cmd, chdir:)
   out, status = Open3.capture2e(env, *cmd, chdir: chdir)
diff --git a/bin/rails b/bin/rails
index efc0377..dfd8ba4 100755
--- a/bin/rails
+++ b/bin/rails
@@ -1,4 +1,4 @@
 #!/usr/bin/env ruby
-APP_PATH = File.expand_path("../config/application", __dir__)
-require_relative "../config/boot"
+APP_PATH = File.expand_path("../apps/ruby2html/config/application", __dir__)
+require_relative "../apps/ruby2html/config/boot"
 require "rails/commands"
diff --git a/bin/rake b/bin/rake
index 4fbf10b..41cf0c3 100755
--- a/bin/rake
+++ b/bin/rake
@@ -1,4 +1,6 @@
 #!/usr/bin/env ruby
-require_relative "../config/boot"
+require_relative "../apps/ruby2html/config/boot"
 require "rake"
+
+Dir.chdir(File.expand_path("../apps/ruby2html", __dir__))
 Rake.application.run
diff --git a/bin/rubocop b/bin/rubocop
index 40330c0..9f6c6a1 100755
--- a/bin/rubocop
+++ b/bin/rubocop
@@ -3,6 +3,6 @@ require "rubygems"
 require "bundler/setup"
 
 # explicit rubocop config increases performance slightly while avoiding config confusion.
-ARGV.unshift("--config", File.expand_path("../.rubocop.yml", __dir__))
+ARGV.unshift("--config", File.expand_path("../apps/ruby2html/.rubocop.yml", __dir__))
 
 load Gem.bin_path("rubocop", "rubocop")
diff --git a/bin/setup b/bin/setup
index b7e5743..76c1b13 100755
--- a/bin/setup
+++ b/bin/setup
@@ -5,12 +5,16 @@
 # e.g. after pulling. Steps: toolchain (mise), gems, C extension, demo app
 # database, git hooks.
 #
+# mise runs at the repo root (mise.toml lives there); bundler, rake and the
+# Rails commands run inside apps/ruby2html, where the app + gem now live.
+#
 #   bin/setup            # everything
 #   bin/setup --skip-db  # gem work only (no Rails database)
 
 require 'fileutils'
 
 APP_ROOT = File.expand_path('..', __dir__)
+APP_DIR = File.expand_path('apps/ruby2html', APP_ROOT)
 
 def step(title)
   puts "\n== #{title} =="
@@ -29,7 +33,9 @@ FileUtils.chdir APP_ROOT do
       puts 'mise not found: skipped (using the active Ruby)'
     end
   end
+end
 
+FileUtils.chdir APP_DIR do
   step 'Installing gems' do
     system('bundle check > /dev/null') || system!('bundle install')
   end
@@ -44,13 +50,14 @@ FileUtils.chdir APP_ROOT do
 
   unless ARGV.include?('--skip-db')
     step 'Preparing the demo app database' do
-      system!('bin/rails db:prepare')
-      system!('bin/rails log:clear tmp:clear')
+      system!('../../bin/rails db:prepare')
+      system!('../../bin/rails log:clear tmp:clear')
     end
   end
 
   step 'Installing git hooks (lefthook)' do
-    if File.directory?('.git') || File.file?('.git')
+    git_dir = File.join(APP_ROOT, '.git')
+    if File.directory?(git_dir) || File.file?(git_dir)
       system!('bundle exec lefthook install')
     else
       puts 'Not a git checkout: skipped'
@@ -61,7 +68,7 @@ FileUtils.chdir APP_ROOT do
 
     Ready. Next steps:
       bin/console           IRB with ruby2html loaded (no Rails)
-      bundle exec rake      compile + gem specs (quick)
+      cd apps/ruby2html     bundler + rake run from the app directory
       bin/rails server      demo app on http://localhost:3000
   TXT
 end
diff --git a/docs/architecture.md b/docs/architecture.md
index e7edd69..b0a9d90 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1,6 +1,6 @@
 # Architecture
 
-How ruby2html turns Ruby into HTML. Paths refer to `lib/gem/` and `ext/ruby2html/`. The authoritative rule text lives in the header comments of `ext/ruby2html/content.c`, `attributes.c`, `tag_render.c` and `html_escape.c`; `render/pure_ruby.rb` mirrors them.
+How ruby2html turns Ruby into HTML. Paths refer to `apps/ruby2html/lib/gem/` and `apps/ruby2html/ext/ruby2html/`. The authoritative rule text lives in the header comments of `apps/ruby2html/ext/ruby2html/content.c`, `attributes.c`, `tag_render.c` and `html_escape.c`; `apps/ruby2html/lib/gem/ruby2html/render/pure_ruby.rb` mirrors them.
 
 ## Layers
 
@@ -14,8 +14,8 @@ Ruby2html::Component#view_template   ──► self = component
 
 ## Load sequence
 
-1. `require 'ruby2html'` → `lib/gem/ruby2html.rb` requires every `ruby2html/**/*.rb`.
-2. `render.rb` requires `render/pure_ruby.rb`, then tries the extension: `require 'ruby2html/ruby2html'` (installed gem: built into `lib/gem/ruby2html/`), else `require_relative '../../ruby2html/ruby2html'` (checkout: `rake compile` output in `lib/ruby2html/`). `RUBY2HTML_DISABLE_EXT=1` skips it. Result: `Ruby2html::IMPLEMENTATION` = `Native` or `PureRuby`; `Ruby2html.native?`.
+1. `require 'ruby2html'` → `apps/ruby2html/lib/gem/ruby2html.rb` requires every `ruby2html/**/*.rb`.
+2. `render.rb` requires `render/pure_ruby.rb`, then tries the extension: `require 'ruby2html/ruby2html'` (installed gem: built into `lib/gem/ruby2html/`), else `require_relative '../../ruby2html/ruby2html'` (checkout: `rake compile` output in `apps/ruby2html/lib/ruby2html/`). `RUBY2HTML_DISABLE_EXT=1` skips it. Result: `Ruby2html::IMPLEMENTATION` = `Native` or `PureRuby`; `Ruby2html.native?`.
 3. `Init_ruby2html` defines module `Ruby2html::Native` with instance methods `plain`, `component` and singleton methods `define_tag`, `escape_html`.
 4. `Render` calls `define_tag(method, tag, void)` for every `HTML5_TAGS` entry on **both** PureRuby and the active implementation (so specs can compare them in one process), then `include IMPLEMENTATION`. `Ruby2html::Component` includes the same module.
 5. With ActiveSupport loaded, `railtie.rb` defines `TemplateHandler` and registers it for `.rb` in `on_load(:action_view)`; with Rails, the Railtie makes Zeitwerk ignore `app/**/*.html.rb`.
@@ -28,13 +28,13 @@ Every tag method reads the target buffer from `@current_output` of `self` (a `Re
 2. With a block: yield; if the buffer did not grow, append the block's return value when it is String/Symbol/Numeric. Without a block: append `content`.
 3. `</tag>`; return `nil`.
 
-Text (`content.c` / `__r2h_text`): `nil` → nothing; exact `String` → escaped; String subclass or other object that is `html_safe?` → raw; Symbol / Integer → escaped `to_s`; anything else → `to_s`, raw if `html_safe?` else escaped. `plain(x)` applies the same rule; `component(x)` appends `x.to_s` raw.
+Text (`apps/ruby2html/ext/ruby2html/content.c` / `__r2h_text`): `nil` → nothing; exact `String` → escaped; String subclass or other object that is `html_safe?` → raw; Symbol / Integer → escaped `to_s`; anything else → `to_s`, raw if `html_safe?` else escaped. `plain(x)` applies the same rule; `component(x)` appends `x.to_s` raw.
 
-Attributes (`attributes.c` / `__r2h_attributes`): `nil` omitted; `true` bare name / `false` omitted, except `data-*`, `aria-*`, `draggable`, `spellcheck`, `contenteditable` which get `"true"`/`"false"`; Hash expands with prefix (`data: { user_id: 1 }` → `data-user-id`, `_` → `-` only in nested keys); Array → space-joined escaped tokens, `nil`/`false` skipped; otherwise `to_s` escaped. Names are validated (no control chars, space, `" ' < > / =`, not empty) and raise `ArgumentError`. Nothing is cached.
+Attributes (`apps/ruby2html/ext/ruby2html/attributes.c` / `__r2h_attributes`): `nil` omitted; `true` bare name / `false` omitted, except `data-*`, `aria-*`, `draggable`, `spellcheck`, `contenteditable` which get `"true"`/`"false"`; Hash expands with prefix (`data: { user_id: 1 }` → `data-user-id`, `_` → `-` only in nested keys); Array → space-joined escaped tokens, `nil`/`false` skipped; otherwise `to_s` escaped. Names are validated (no control chars, space, `" ' < > / =`, not empty) and raise `ArgumentError`. Nothing is cached.
 
-Escaping (`html_escape.c`): `& < > " '` → `&amp; &lt; &gt; &quot; &#39;`. 16-byte SSE2 (x86_64) or NEON (aarch64) scan, scalar with `-DR2H_NO_SIMD` (`RUBY2HTML_NO_SIMD=1 rake compile`). Clean input is one `memcpy`; dirty input gets its exact size computed, then one pass copying clean runs. Input encodings: UTF-8/US-ASCII/BINARY copied as bytes, ASCII-only copied, others transcoded to UTF-8 (raises if impossible). `Ruby2html.escape_html` never returns the caller's mutable string.
+Escaping (`apps/ruby2html/ext/ruby2html/html_escape.c`): `& < > " '` → `&amp; &lt; &gt; &quot; &#39;`. 16-byte SSE2 (x86_64) or NEON (aarch64) scan, scalar with `-DR2H_NO_SIMD` (`RUBY2HTML_NO_SIMD=1 rake compile`). Clean input is one `memcpy`; dirty input gets its exact size computed, then one pass copying clean runs. Input encodings: UTF-8/US-ASCII/BINARY copied as bytes, ASCII-only copied, others transcoded to UTF-8 (raises if impossible). `Ruby2html.escape_html` never returns the caller's mutable string.
 
-C buffer handling (`buffer.h`): reserve (at least doubling capacity, to keep long renders linear), `memcpy`, commit length. Tag methods are C functions bound through a fixed pool of 200 trampolines (`R2H_MAX_TAGS`); tag names must be `[a-z0-9-]`, ≤ 32 bytes. IDs are interned at Init.
+C buffer handling (`apps/ruby2html/ext/ruby2html/buffer.h`): reserve (at least doubling capacity, to keep long renders linear), `memcpy`, commit length. Tag methods are C functions bound through a fixed pool of 200 trampolines (`R2H_MAX_TAGS`); tag names must be `[a-z0-9-]`, ≤ 32 bytes. IDs are interned at Init.
 
 ## `Ruby2html::Render`
 
@@ -75,7 +75,7 @@ So the template runs with `self` = the view or component: ivars, locals, private
 
 `handles_encoding?` is `false`, so ActionView transcodes the source first.
 
-### Helper wrappers (`rails_components/`)
+### Helper wrappers (`apps/ruby2html/lib/gem/ruby2html/rails_components/`)
 
 - `BaseComponent#render`: `@render.plain(@context.public_send(method, *args, **opts, &capturing(block)))`. `@render` is anything with `plain` and `current_output` (a `Render` or a `Ruby2html::Component`).
 - `OutputCapture#capturing`: wraps the block so it runs with `@render.current_output` swapped to a scratch buffer; returns the buffer as `html_safe` if anything was written, else the block's value (ActionView `capture` semantics). Nested tags therefore land inside the helper's markup.
@@ -108,10 +108,10 @@ Lazy-requires `htmlbeautifier` at construction (clear `LoadError` if absent). Be
 
 ## Demo app, specs, benchmarks
 
-- `config/application.rb` loads the gem with `require_relative '../lib/gem/ruby2html'`.
-- `BenchmarkController` renders `COMPLEX_DATA` via ERB, Slim, `.html.rb`, a ViewComponent (`BenchmarkComponent`) and Phlex; `spec/benchmarks/requests_spec.rb` compares them.
-- `bench/render_bench.rb` (page render vs Phlex/Erubi, allocations), `bench/tag_bench.rb` (per-tag call shapes), `bench/escape_bench.rb` (escaping throughput); `rake bench` runs all.
-- `spec/gem/render_spec_helper.rb` defines groups once and runs them for Native and PureRuby; `render_parity_spec.rb` compares outputs directly.
+- `apps/ruby2html/config/application.rb` loads the gem with `require_relative '../lib/gem/ruby2html'`.
+- `BenchmarkController` renders `COMPLEX_DATA` via ERB, Slim, `.html.rb`, a ViewComponent (`BenchmarkComponent`) and Phlex; `apps/ruby2html/spec/benchmarks/requests_spec.rb` compares them.
+- `apps/ruby2html/bench/render_bench.rb` (page render vs Phlex/Erubi, allocations), `apps/ruby2html/bench/tag_bench.rb` (per-tag call shapes), `apps/ruby2html/bench/escape_bench.rb` (escaping throughput); `rake bench` runs all.
+- `apps/ruby2html/spec/gem/render_spec_helper.rb` defines groups once and runs them for Native and PureRuby; `apps/ruby2html/spec/gem/render_parity_spec.rb` compares outputs directly.
 
 ## Design constraints
 
diff --git a/docs/release.md b/docs/release.md
index f59f77d..62249e2 100644
--- a/docs/release.md
+++ b/docs/release.md
@@ -2,7 +2,7 @@
 
 Releases go to RubyGems (`ruby2html`) and are tagged `vX.Y.Z` on GitHub (`sebyx07/ruby2html`).
 
-**Merging a version bump to `main` is the release.** When `lib/gem/ruby2html/version.rb` changes on
+**Merging a version bump to `main` is the release.** When `apps/ruby2html/lib/gem/ruby2html/version.rb` changes on
 `main` and tag `vX.Y.Z` does not exist yet, `.github/workflows/release.yml`:
 1. checks that `CHANGELOG.md` has a `## [X.Y.Z]` section, then runs compile, `rspec`, rubocop and `rake smoke`, plus a JRuby install;
 2. publishes the gem (RubyGems trusted publishing, GitHub environment `release`; no API key in the repo);
@@ -16,10 +16,10 @@ agent never opens one.
 ## The release PR
 
 1. Pick the version (SemVer): patch for fixes; minor for new tags/helpers/options, perf work or intentional output changes; major for removed or renamed public API, or a raised Ruby/Rails floor.
-2. `lib/gem/ruby2html/version.rb` → `VERSION = 'X.Y.Z'` (the gemspec reads it).
-3. `CHANGELOG.md`: move `## [Unreleased]` into `## [X.Y.Z] - YYYY-MM-DD` (with "Upgrading to X.0" for a major), leave an empty `## [Unreleased]`, add the `[X.Y.Z]` link at the bottom. `bin/changelog-notes X.Y.Z` must print the section.
-4. Refresh the issue-template versions placeholder in `.github/ISSUE_TEMPLATE/bug_report.yml`: gem version from `lib/gem/ruby2html/version.rb`, Ruby version from `.ruby-version`, Rails version from `Gemfile.lock`. GitHub issue forms cannot derive the value at fill time, so it is updated here.
-5. Verify: `bundle exec rake compile && CI=1 bundle exec rspec && bundle exec rubocop && bundle exec rake smoke`.
+2. `apps/ruby2html/lib/gem/ruby2html/version.rb` → `VERSION = 'X.Y.Z'` (the gemspec reads it).
+3. `CHANGELOG.md`: move `## [Unreleased]` into `## [X.Y.Z] - YYYY-MM-DD` (with "Upgrading to X.0" for a major), leave an empty `## [Unreleased]`, add the `[X.Y.Z]` link at the bottom. `bin/changelog-notes X.Y.Z` (a repo-root script; it reads the root `CHANGELOG.md`) must print the section.
+4. Refresh the issue-template versions placeholder in `.github/ISSUE_TEMPLATE/bug_report.yml`: gem version from `apps/ruby2html/lib/gem/ruby2html/version.rb`, Ruby version from `apps/ruby2html/.ruby-version`, Rails version from `apps/ruby2html/Gemfile.lock`. GitHub issue forms cannot derive the value at fill time, so it is updated here.
+5. Verify (from `apps/ruby2html`): `bundle exec rake compile && CI=1 bundle exec rspec && bundle exec rubocop && bundle exec rake smoke`.
 6. One PR titled `release: X.Y.Z`, containing nothing else (apart from the issue-template placeholder refresh in step 4). Merge on green.
 
 ## After
diff --git a/lefthook.yml b/lefthook.yml
index 53080ec..a82991a 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -1,7 +1,12 @@
 # Installed by bin/setup (bundle exec lefthook install).
 #
+# Commands run with root: apps/ruby2html/ so bundler resolves the app Gemfile
+# (the app + gem moved under apps/ruby2html; there is no root bundle). Staged
+# files in the root-level bin/ are outside the glob below: lint them with
+# ../../bin/rubocop (as bin/check does) or skip the hook once with LEFTHOOK=0.
+#
 # pre-commit: RuboCop on the staged Ruby files only (safe autocorrect; fixed
-#             files are re-staged). Full check: bin/rubocop
+#             files are re-staged). Full check: bin/check
 # pre-push:   compile + gem specs (`rake spec:gem`, a few seconds), so pushes
 #             do not break CI's RuboCop/spec jobs. Skip once: LEFTHOOK=0 git push
 pre-commit:
@@ -9,6 +14,7 @@ pre-commit:
   commands:
     rubocop:
       glob: '{*.rb,*.rake,*.gemspec,Gemfile,Rakefile,*.gemfile}'
+      root: apps/ruby2html/
       run: bundle exec rubocop --force-exclusion --autocorrect {staged_files}
       skip:
         - merge
@@ -18,4 +24,5 @@ pre-commit:
 pre-push:
   commands:
     gem-specs:
+      root: apps/ruby2html/
       run: bundle exec rake spec:gem
diff --git a/spec/ci/advisory_audit_spec.rb b/spec/ci/advisory_audit_spec.rb
deleted file mode 100644
index edc9833..0000000
--- a/spec/ci/advisory_audit_spec.rb
+++ /dev/null
@@ -1,646 +0,0 @@
-# frozen_string_literal: true
-
-require 'json'
-require 'open3'
-require 'pathname'
-require 'rbconfig'
-require 'tmpdir'
-require 'yaml'
-
-# Coverage guard for the dependency audits in CI.
-#
-# The matrix jobs install an unlocked gemfile: ruby/setup-ruby resolves it
-# during the job and writes the lockfile next to it (gemfiles/*.lock,
-# gitignored, never committed). That resolved set is what the job actually
-# installs, so it is what has to be audited against the Ruby advisory
-# database, not only the committed root Gemfile.lock.
-#
-# The audit rides on the rake tasks every matrix entry already runs (rake
-# compile, and the spec tasks when compile is skipped): the platform merge
-# gate refuses new steps in a workflow, so the workflow file stays as it is
-# and the audit runs from the Rakefile.
-#
-# The claim lives in the workflow file, the Rakefile and the script, so
-# without this spec the audit could be dropped or neutered (a skipped
-# prerequisite, a swallowed exit status) without anything going red. The
-# wiring itself is pinned by RUNNING it (see the rake wiring group below):
-# matching the Rakefile's source text passes on prose alone.
-RSpec.describe 'CI dependency audits' do
-  let(:root) { File.expand_path('../..', __dir__) }
-  let(:workflow_file) { File.join(root, '.github/workflows/ci.yml') }
-  let(:workflow) { YAML.safe_load_file(workflow_file, aliases: true) }
-  let(:jobs) { workflow.fetch('jobs') }
-  let(:script_path) { File.join(root, 'bin/audit-advisories') }
-  let(:script) { File.read(script_path) }
-
-  # Unlocked matrix gemfiles: resolved fresh on every CI run, never committed.
-  let(:matrix_gemfiles) do
-    Dir[File.join(root, 'gemfiles', '*.gemfile')].map { |path| File.basename(path) }.sort
-  end
-
-  # A stub bundle-audit: it records how it was called and exits with a given
-  # status. The real one needs the advisory database and the network.
-  def with_stub_audit(status:)
-    Dir.mktmpdir('audit-advisories') do |dir|
-      record = File.join(dir, 'record')
-      stub = File.join(dir, 'bundle-audit')
-      File.write(stub, <<~RUBY)
-        #!#{RbConfig.ruby}
-        call = [ARGV.join(' '), Dir.pwd, ENV['BUNDLE_GEMFILE'].to_s]
-        File.write(#{record.dump}, call.join("\\n") + "\\n")
-        exit #{status}
-      RUBY
-      File.chmod(0o755, stub)
-
-      yield dir, record
-    end
-  end
-
-  # What the stub recorded: the arguments it got, the working directory it
-  # ran in and the BUNDLE_GEMFILE it saw.
-  def recorded_call(record)
-    argv, cwd, bundle_gemfile = File.read(record).lines.map(&:chomp)
-
-    { argv: argv, cwd: cwd, bundle_gemfile: bundle_gemfile }
-  end
-
-  # The advisory ids the stub was told to ignore.
-  def ignored_advisories(record)
-    recorded_call(record)[:argv].split('--ignore').last.to_s.split
-  end
-
-  def run_audit(env, *args)
-    # The script is standalone: it must not run inside the caller's bundle.
-    standalone = { 'RUBYOPT' => nil, 'RUBYGEMS_GEMDEPS' => nil, 'BUNDLER_SETUP' => nil }
-    Open3.capture3(standalone.merge(env), RbConfig.ruby, script_path, *args)
-  end
-
-  # bundle-audit resolves --gemfile-lock against its own working directory, so
-  # the paths the script hands over are asserted relative to the repo root.
-  def relative_to_root(path)
-    Pathname.new(path).relative_path_from(Pathname.new(root)).to_s
-  end
-
-  # A lockfile that resolves the given gems to the given versions.
-  def lockfile_with(dir, gems)
-    specs = gems.map { |gem, version| "    #{gem} (#{version})" }.join("\n")
-
-    File.join(dir, 'Gemfile.lock').tap do |lock|
-      File.write(lock, "GEM\n  remote: https://rubygems.org/\n  specs:\n#{specs}\n")
-    end
-  end
-
-  def steps_of(job)
-    job['steps'].is_a?(Array) ? job['steps'] : []
-  end
-
-  # Steps that run bundle-audit (not the `gem install` of it).
-  def audit_steps(job)
-    steps_of(job).select { |step| step['run'].to_s.include?('bundle-audit check') }
-  end
-
-  def gemfile_of(job)
-    job.dig('env', 'BUNDLE_GEMFILE').to_s
-  end
-
-  # Jobs that install an unlocked matrix gemfile.
-  def matrix_jobs
-    jobs.select { |_name, job| gemfile_of(job).end_with?('.gemfile') }
-  end
-
-  describe 'per-matrix audits' do
-    it 'runs a rake task in every job that installs an unlocked gemfile' do
-      expect(matrix_jobs).not_to be_empty, 'no CI job installs an unlocked gemfile'
-
-      matrix_jobs.each do |name, job|
-        rake_steps = steps_of(job).select { |step| step['run'].to_s.match?(/\brake\b/) }
-
-        expect(rake_steps).not_to be_empty,
-                                   "job #{name} installs #{gemfile_of(job)} but never runs a rake task"
-
-        rake_steps.each do |step|
-          expect(step['run'].to_s).to match(/\brake\b.*\b(compile|spec|audit)\b/),
-                                     "job #{name} runs a rake task that does not reach the audit: #{step['run']}"
-        end
-      end
-    end
-
-    it 'never skips the compile step that carries the audit' do
-      matrix_jobs.each do |name, job|
-        expect(job.dig('env', 'SKIP_COMPILE')).to be_nil,
-                                               "job #{name} sets SKIP_COMPILE: the audit never runs"
-
-        steps_of(job).each do |step|
-          expect(step.dig('env', 'SKIP_COMPILE')).to be_nil,
-                                                 "job #{name} sets SKIP_COMPILE on a step: the audit never runs"
-        end
-      end
-    end
-
-    it 'keeps the audit out of the workflow steps' do
-      matrix_jobs.each do |name, job|
-        audit_steps(job).each do |step|
-          expect(step['run'].to_s).not_to include('--gemfile-lock'),
-                                      "job #{name} audits a lockfile in the workflow: the audit belongs in the Rakefile"
-        end
-      end
-    end
-
-    it 'covers every unlocked matrix gemfile in the repo' do
-      covered = matrix_jobs.map { |_name, job| File.basename(gemfile_of(job)) }.uniq
-      missing = matrix_gemfiles - covered
-
-      expect(covered).to match_array(matrix_gemfiles),
-                         "unlocked gemfiles with no CI job auditing the set it resolves: #{missing.join(', ')}"
-    end
-  end
-
-  describe 'the rake wiring' do
-    # Loading the Rakefile in a real rake run and invoking the tasks is the
-    # only proof that survives a refactor: matching the Rakefile's source text
-    # passes on prose alone — a dropped prerequisite, a body that never runs
-    # the script. The driver (spec/ci/support/rake_wiring_driver.rb) runs
-    # under `bundle exec` the way the CI jobs run rake, loads the Rakefile at
-    # the top level the way rake does, and invokes audit:advisories against a
-    # stub bundle-audit.
-    let(:driver) { File.join(root, 'spec/ci/support/rake_wiring_driver.rb') }
-
-    # Returns [report, fake_gemfile]: the driver's JSON report, and the
-    # unlocked matrix gemfile (outside the repo) the Rakefile was loaded with.
-    def run_rake_driver(extra = {})
-      Dir.mktmpdir('rake-wiring') do |dir|
-        gemfile = File.join(dir, 'standalone.gemfile')
-        File.write(gemfile, "source 'https://rubygems.org'\n")
-        File.write("#{gemfile}.lock", '')
-        record = File.join(dir, 'record')
-        report = File.join(dir, 'report.json')
-        stub = File.join(dir, 'bundle-audit')
-
-        File.write(stub, <<~RUBY)
-          #!#{RbConfig.ruby}
-          call = [ARGV.join(' '), Dir.pwd, ENV['BUNDLE_GEMFILE'].to_s]
-          File.write(#{record.dump}, call.join("\\n") + "\\n")
-          exit Integer(ENV.fetch('RUBY2HTML_STUB_STATUS', '0'))
-        RUBY
-        File.chmod(0o755, stub)
-
-        env = {
-          'RUBYOPT' => nil,
-          'RUBYGEMS_GEMDEPS' => nil,
-          'BUNDLER_SETUP' => nil,
-          'PATH' => dir,
-          'RUBY2HTML_SPEC_GEMFILE' => gemfile,
-          'RUBY2HTML_SPEC_RECORD' => record,
-          'RUBY2HTML_SPEC_REPORT' => report
-        }.merge(extra)
-        bundler = Gem.bin_path('bundler', 'bundle')
-
-        out, err, status = Open3.capture3(env, RbConfig.ruby, bundler, 'exec', RbConfig.ruby, driver, chdir: root)
-        raise "the rake wiring driver failed (#{status.exitstatus}): #{err}#{out}" unless status.success?
-
-        [JSON.parse(File.read(report)), gemfile]
-      end
-    end
-
-    it 'wires the audit into compile, ahead of the spec tasks' do
-      report, = run_rake_driver
-
-      expect(report.fetch('prerequisites').fetch('compile')).to include('audit:advisories')
-      expect(report.fetch('prerequisites').fetch('spec')).to eq(%w[compile audit:advisories])
-      expect(report.fetch('prerequisites').fetch('spec:gem')).to eq(%w[compile audit:advisories])
-      expect(report.fetch('prerequisites').fetch('spec:standalone')).to eq(%w[compile audit:advisories])
-    end
-
-    it 'keeps the audit wired when compile is skipped (SKIP_COMPILE=1)' do
-      report, = run_rake_driver('SKIP_COMPILE' => '1')
-
-      expect(report.fetch('prerequisites').fetch('compile')).to include('audit:advisories')
-      expect(report.fetch('prerequisites').fetch('spec:gem')).to eq(%w[audit:advisories]),
-                                                                     'the audit must not depend on the compile step it does not need'
-      expect(report.fetch('prerequisites').fetch('spec:standalone')).to eq(%w[audit:advisories])
-    end
-
-    it 'runs bin/audit-advisories when audit:advisories is invoked in CI for a matrix gemfile' do
-      report, gemfile = run_rake_driver
-
-      outcome = report.fetch('in_ci_with_matrix_gemfile')
-      expect(outcome.fetch('ran')).to be(true), 'invoking audit:advisories in CI must run the audit'
-
-      argv, cwd, bundle_gemfile = outcome.fetch('call')
-      expect(argv).to eq("check --update --gemfile-lock #{relative_to_root("#{gemfile}.lock")}")
-      expect(cwd).to eq(root), 'the audit runs in the project root, where the lockfile path it hands over resolves'
-      expect(bundle_gemfile).to be_empty, 'the audit must run outside the caller Bundler environment'
-    end
-
-    it 'runs nothing outside CI' do
-      report, = run_rake_driver
-
-      expect(report.fetch('without_ci')).to include('ran' => false), 'the audit must not run outside CI'
-    end
-
-    it 'runs nothing for the committed root Gemfile' do
-      report, = run_rake_driver
-
-      expect(report.fetch('with_root_gemfile')).to include('ran' => false),
-                                                    'the audit is for the unlocked matrix gemfiles; the root lockfile has its own job'
-    end
-
-    it 'fails the rake task when the audit finds an advisory' do
-      report, = run_rake_driver
-
-      outcome = report.fetch('failing_audit')
-      expect(outcome.fetch('ran')).to be(true)
-      expect(outcome.fetch('raised')).to eq('RuntimeError'), 'a failing audit must raise out of the rake task'
-      expect(outcome.fetch('message')).to include('status (1)'), 'the audit exit status must surface'
-    end
-  end
-
-  describe 'bin/audit-advisories' do
-    it 'is an executable script' do
-      expect(script).to start_with("#!/usr/bin/env ruby\n# frozen_string_literal: true\n")
-      expect(File.executable?(script_path)).to be(true), 'bin/audit-advisories must be executable'
-    end
-
-    it 'runs without Bundler: the rake task shells out without bundle exec' do
-      expect(script).not_to match(/require ['"]bundler|Bundler\./),
-                           'bin/audit-advisories must not depend on Bundler being loadable'
-    end
-
-    it 'reports a signal-killed audit instead of passing it off as an advisory' do
-      Dir.mktmpdir('audit-advisories') do |dir|
-        stub = File.join(dir, 'bundle-audit')
-        lock = File.join(dir, 'Gemfile.lock')
-        File.write(lock, '')
-        File.write(stub, <<~RUBY)
-          #!#{RbConfig.ruby}
-          Process.kill('TERM', Process.pid)
-        RUBY
-        File.chmod(0o755, stub)
-
-        _out, err, status = run_audit({ 'PATH' => dir }, lock)
-
-        expect(status.exitstatus).to eq(1), 'a killed audit must still fail the job'
-        expect(err).to include('signal'), 'a killed audit must be reported as killed, not look like an advisory result'
-      end
-    end
-
-    it 'audits the lockfile Bundler wrote next to BUNDLE_GEMFILE' do
-      with_stub_audit(status: 0) do |dir, record|
-        gemfile = File.join(dir, 'standalone.gemfile')
-        lock = "#{gemfile}.lock"
-        File.write(lock, '')
-
-        _out, _err, status = run_audit({ 'PATH' => dir, 'BUNDLE_GEMFILE' => gemfile })
-
-        expect(status.exitstatus).to eq(0)
-        call = recorded_call(record)
-        expect(call[:argv]).to eq("check --update --gemfile-lock #{relative_to_root(lock)}")
-        expect(call[:bundle_gemfile]).to be_empty, 'the audit must run outside the caller Bundler environment'
-      end
-    end
-
-    it 'audits the committed root Gemfile.lock without arguments' do
-      with_stub_audit(status: 0) do |dir, record|
-        _out, _err, status = run_audit({ 'PATH' => dir, 'BUNDLE_GEMFILE' => nil })
-
-        expect(status.exitstatus).to eq(0)
-        call = recorded_call(record)
-        expect(call[:argv]).to eq('check --update --gemfile-lock Gemfile.lock')
-      end
-    end
-
-    it 'hands bundle-audit a lockfile path it resolves from its working directory' do
-      with_stub_audit(status: 0) do |dir, record|
-        gemfile = File.join(dir, 'standalone.gemfile')
-        lock = "#{gemfile}.lock"
-        File.write(lock, '')
-
-        _out, _err, status = run_audit({ 'PATH' => dir, 'BUNDLE_GEMFILE' => gemfile })
-
-        expect(status.exitstatus).to eq(0)
-        call = recorded_call(record)
-        resolved = File.expand_path(File.join(call[:cwd], call[:argv].split.last))
-
-        expect(resolved).to eq(lock), 'bundle-audit resolves --gemfile-lock against its working directory'
-        expect(File.file?(resolved)).to be(true), 'the lockfile bundle-audit resolves must exist'
-      end
-    end
-
-    it 'propagates a non-zero bundle-audit exit status' do
-      with_stub_audit(status: 1) do |dir, _record|
-        lock = File.join(dir, 'Gemfile.lock')
-        File.write(lock, '')
-
-        _out, _err, status = run_audit({ 'PATH' => dir }, lock)
-
-        expect(status.exitstatus).to eq(1), 'an advisory must fail the script, and with it the CI job'
-      end
-    end
-
-    it 'installs bundler-audit when the binary is missing' do
-      Dir.mktmpdir('audit-advisories') do |dir|
-        record = File.join(dir, 'record')
-        install_log = File.join(dir, 'install')
-        bin = File.join(dir, 'bundle-audit')
-        installer = File.join(dir, 'gem')
-
-        File.write(installer, <<~RUBY)
-          #!#{RbConfig.ruby}
-          File.write(#{install_log.dump}, ARGV.join(' '))
-          File.write(#{bin.dump}, "#!#{RbConfig.ruby}\\nFile.write('#{record}', ARGV.join(' '))\\nexit 0\\n")
-          File.chmod(0o755, #{bin.dump})
-        RUBY
-        File.chmod(0o755, installer)
-
-        lock = File.join(dir, 'Gemfile.lock')
-        File.write(lock, '')
-
-        _out, _err, status = run_audit({ 'PATH' => dir }, lock)
-
-        expect(status.exitstatus).to eq(0)
-        expect(File.read(install_log)).to include('install', 'bundler-audit')
-        expect(File.read(record)).to include("check --update --gemfile-lock #{relative_to_root(lock)}")
-      end
-    end
-
-    it 'can find the gem executable beyond PATH when it installs bundler-audit' do
-      expect(script).to include("gem_executable('gem')"),
-                     'the gem executable may be missing from PATH too: the installer must look in the RubyGems bindir'
-    end
-
-    it 'refuses to continue when bundler-audit cannot be installed' do
-      Dir.mktmpdir('audit-advisories') do |dir|
-        installer = File.join(dir, 'gem')
-        lock = File.join(dir, 'Gemfile.lock')
-        File.write(lock, '')
-
-        File.write(installer, <<~RUBY)
-          #!#{RbConfig.ruby}
-          exit 1
-        RUBY
-        File.chmod(0o755, installer)
-
-        _out, err, status = run_audit({ 'PATH' => dir }, lock)
-
-        expect(status.exitstatus).not_to eq(0)
-        expect(err).to include('could not install bundler-audit')
-      end
-    end
-
-    it 'refuses to audit a lockfile that does not exist' do
-      with_stub_audit(status: 0) do |dir, _record|
-        missing = File.join(dir, 'missing.lock')
-
-        _out, err, status = run_audit({ 'PATH' => dir }, missing)
-
-        expect(status.exitstatus).not_to eq(0)
-        expect(err).to include('missing.lock')
-      end
-    end
-  end
-
-  describe 'the accepted advisories' do
-    # The advisories the script accepts, read from the script itself.
-    def script_accept_list
-      block = script[/ACCEPTED_ADVISORIES = \{(.*?)\n\}\.freeze/m, 1]
-      raise 'bin/audit-advisories declares no ACCEPTED_ADVISORIES' if block.nil?
-
-      block.scan(/'([\w-]+)' => \{(.*?)\}/m).to_h do |gem, body|
-        versions = {}
-        body.scan(/'([^']+)' => %w\[(.*?)\]/m) do |version, ids|
-          versions[version] = ids.split
-        end
-        [gem, versions]
-      end
-    end
-
-    # The reviewed policy, pinned here INDEPENDENTLY of the script: an edit to
-    # the script's table (an id typo'd, an entry added, dropped or moved to
-    # another version) fails this spec and forces a conscious re-review. The
-    # versions are what the matrix resolves on the floor lines today (see
-    # bin/audit-advisories); once a resolution moves, the audit drops every
-    # exception and fails the entry, so this snapshot can only change in step
-    # with a real re-review. A gem can pin several versions when the matrix
-    # resolves its line more than once: the rails gem pins Active Support
-    # 7.2.3 for the Rails entries, while the standalone gemfile on Ruby 3.1
-    # resolves the line unlocked and sits on the newest 7.2.x patch.
-    let(:expected_accepted) do
-      {
-        'actionmailbox' => { '7.2.3' => %w[GHSA-5957-c7qm-m469] },
-        'actionpack' => { '7.2.3' => %w[
-          GHSA-2586-8ghr-69fj
-          GHSA-gmj8-hvj3-49mw
-          GHSA-r9jg-fmfx-2gv6
-          GHSA-rwvh-fw6r-pwvp
-          GHSA-wm3x-v3qw-4jh3
-          GHSA-x6mj-8jx9-qhqv
-        ] },
-        'actionview' => { '7.2.3' => %w[
-          GHSA-2p2f-4rq4-gjwc
-          GHSA-68p9-83h6-5wpj
-          GHSA-rq8q-p985-fjq7
-          GHSA-v55j-83pf-r9cq
-          GHSA-v6rj-xm57-3p59
-        ] },
-        'activestorage' => { '7.2.3' => %w[
-          GHSA-3f4q-8x5m-76v8
-          GHSA-3w93-6hmw-whh4
-          GHSA-73f9-jhhh-hr5m
-          GHSA-9xrj-h377-fr87
-          GHSA-f3w6-w445-fwh9
-          GHSA-hfr4-8rjc-97m2
-          GHSA-p2pm-g2h6-7j5j
-          GHSA-p9fm-f462-ggrg
-          GHSA-qcfx-2mfw-w4cg
-          GHSA-r46p-8f7g-vvvg
-          GHSA-v924-7rp8-4mxh
-          GHSA-xr9x-r78c-5hrm
-        ] },
-        'activesupport' => { '7.2.3' => %w[
-          GHSA-2j26-frm8-cmj9
-          GHSA-8474-xrp6-wh69
-          GHSA-89vf-4333-qx8v
-          GHSA-cg4j-q9v8-6v38
-        ], '7.2.4' => %w[GHSA-8474-xrp6-wh69] }
-      }
-    end
-
-    let(:pinned_activesupport) { expected_accepted.fetch('activesupport').keys.first }
-
-    it 'accepts exactly the reviewed list, scoped to the exact reviewed version' do
-      expect(script_accept_list).to eq(expected_accepted), 'the accept list changed: re-review it, then update this snapshot'
-    end
-
-    it 'declares every reviewed version on the documented 7.2 floor line' do
-      script_accept_list.each do |gem, versions|
-        expect(versions).not_to be_empty, "no reviewed version for #{gem}"
-
-        versions.each_key do |version|
-          expect(version).to match(/\A7\.2\.\d+(?:\.\d+)*\z/), "the reviewed version must sit on the Rails 7.2 floor line: #{gem} #{version}"
-        end
-      end
-    end
-
-    it 'lists well-formed advisory ids, never under two gems' do
-      ids = script_accept_list.flat_map { |_gem, versions| versions.values.flatten }
-
-      expect(ids).not_to be_empty, 'the script accepts no advisory at all'
-      ids.each do |id|
-        expect(id).to match(/\A(?:GHSA|CVE)-[A-Za-z0-9-]+\z/), "#{id} is not an advisory id"
-      end
-
-      # bundle-audit --ignore is global per run: an id parked under two gems
-      # would be ignored while auditing either. The same id on two reviewed
-      # versions of ONE gem is fine — only one of them resolves per run, and
-      # the ids are scoped to the resolved version (proven below).
-      gems_of = Hash.new { |hash, key| hash[key] = [] }
-      script_accept_list.each do |gem, versions|
-        versions.each_value { |gem_ids| gem_ids.each { |id| gems_of[id] |= [gem] } }
-      end
-
-      expect(gems_of.select { |_id, gems| gems.size > 1 }).to be_empty,
-                                                             'an id listed under two gems would be ignored while auditing either — review the pair'
-    end
-
-    it 'accepts exactly the ids of the reviewed version the lockfile resolves' do
-      expected_accepted.fetch('activesupport').each do |version, ids|
-        with_stub_audit(status: 0) do |dir, record|
-          lock = lockfile_with(dir, 'activesupport' => version)
-
-          _out, _err, status = run_audit({ 'PATH' => dir }, lock)
-
-          expect(status.exitstatus).to eq(0)
-          expect(ignored_advisories(record)).to match_array(ids),
-                                                 "a lockfile resolving #{version} must carry exactly its own exceptions"
-        end
-      end
-    end
-
-    it 'names the accepted advisories in the job log' do
-      with_stub_audit(status: 0) do |dir, _record|
-        lock = lockfile_with(dir, 'activesupport' => pinned_activesupport)
-
-        out, _err, status = run_audit({ 'PATH' => dir }, lock)
-
-        expect(status.exitstatus).to eq(0)
-        expect(out).to include(expected_accepted.fetch('activesupport').fetch(pinned_activesupport).first),
-                       'the job log must name the advisories the audit accepts'
-      end
-    end
-
-    it 'drops every exception for an unreviewed patch of the same line' do
-      with_stub_audit(status: 1) do |dir, record|
-        unreviewed_patch = expected_accepted.fetch('activesupport').keys.max.succ # the next 7.2.x patch
-        lock = lockfile_with(dir, 'activesupport' => unreviewed_patch)
-
-        _out, _err, status = run_audit({ 'PATH' => dir }, lock)
-
-        expect(recorded_call(record)[:argv]).not_to include('--ignore'),
-                                                      'a version that was not reviewed must be audited without exceptions'
-        expect(status.exitstatus).to eq(1), 'its advisories must fail the job until the new version is reviewed'
-      end
-    end
-
-    it 'audits a newer line without any exception and fails the job on its advisories' do
-      with_stub_audit(status: 1) do |dir, record|
-        lock = lockfile_with(dir, 'activesupport' => '8.1.4.1')
-
-        _out, _err, status = run_audit({ 'PATH' => dir }, lock)
-
-        expect(recorded_call(record)[:argv]).not_to include('--ignore'),
-                                                      'a line outside the accepted versions must be audited without exceptions'
-        expect(status.exitstatus).to eq(1), 'the advisory bundle-audit reported must fail the script, and with it the CI job'
-      end
-    end
-
-    it 'accepts advisories of the resolved gem only' do
-      with_stub_audit(status: 0) do |dir, record|
-        lock = lockfile_with(dir, 'activesupport' => pinned_activesupport)
-
-        _out, _err, status = run_audit({ 'PATH' => dir }, lock)
-
-        expect(status.exitstatus).to eq(0)
-        ignored = ignored_advisories(record)
-
-        script_accept_list.each do |gem, versions|
-          next if gem == 'activesupport'
-
-          versions.each_value do |ids|
-            ids.each do |id|
-              expect(ignored).not_to include(id),
-                                     "the audit accepted #{id}, an advisory of #{gem}, which it does not resolve"
-            end
-          end
-        end
-      end
-    end
-
-    it 'keeps the root lockfile free of exceptions' do
-      with_stub_audit(status: 0) do |dir, record|
-        _out, _err, status = run_audit({ 'PATH' => dir })
-
-        expect(status.exitstatus).to eq(0)
-        expect(recorded_call(record)[:argv]).not_to include('--ignore'),
-                                                      'the committed root Gemfile.lock must be audited without exceptions'
-      end
-    end
-  end
-
-  describe 'audit fatality' do
-    it 'makes a failed audit reach the aggregate CI OK job' do
-      aggregate = jobs.find { |id, job| id == 'ci-ok' || job['name'] == 'CI OK' }&.last
-
-      expect(aggregate).not_to be_nil, 'the aggregate CI OK job is missing'
-      needs = Array(aggregate['needs']).map(&:to_s)
-
-      matrix_jobs.each_key do |name|
-        expect(needs).to include(name), "job #{name} audits dependencies but is not required by the CI OK job"
-      end
-    end
-  end
-
-  describe 'root audit' do
-    it 'still audits the committed root Gemfile.lock' do
-      root_audits = jobs.reject { |_name, job| gemfile_of(job).end_with?('.gemfile') }
-                        .flat_map { |name, job| audit_steps(job).map { |step| [name, step] } }
-                        .reject { |_name, step| step['run'].to_s.include?('--gemfile-lock') }
-
-      expect(root_audits).not_to be_empty,
-                                 'no job runs bundle-audit check without --gemfile-lock (the default Gemfile.lock)'
-    end
-
-    it 'keeps the root audit job required by the CI OK job' do
-      aggregate = jobs.find { |id, job| id == 'ci-ok' || job['name'] == 'CI OK' }&.last
-      needs = Array(aggregate['needs']).map(&:to_s)
-
-      expect(needs).to include('audit'), 'the root Gemfile.lock audit is not required by the CI OK job'
-    end
-  end
-
-  it 'keeps the matrix lockfiles out of git' do
-    ignored = File.readlines(File.join(root, '.gitignore'), chomp: true).map(&:strip)
-
-    expect(ignored).to include('/gemfiles/*.lock')
-  end
-
-  it 'states which dependency sets are audited' do
-    names = jobs.map { |_id, job| job['name'].to_s } +
-            jobs.flat_map { |_id, job| steps_of(job).map { |step| step['name'].to_s } }
-    comments = File.readlines(workflow_file).filter_map { |line| line[/^\s*#\s*(.*)$/, 1] }
-    stated = (names + comments).join("\n")
-
-    expect(stated).to include('Gemfile.lock'), 'the workflow does not name the audited root Gemfile.lock'
-    matrix_gemfiles.each do |gemfile|
-      expect(stated).to include("gemfiles/#{gemfile}"), "the workflow does not name the audited gemfiles/#{gemfile}"
-    end
-  end
-
-  it 'documents the audited dependency sets in the repo guide' do
-    row = File.readlines(File.join(root, 'AGENTS.md')).find { |line| line.start_with?('| CI |') }
-
-    expect(row).not_to be_nil, 'the AGENTS.md CI row is missing'
-    expect(row.to_s).to match(/bundle-audit|audit-advisories/)
-    expect(row.to_s).to include('Gemfile.lock')
-    expect(row.to_s).to include('gemfile')
-  end
-end
diff --git a/spec/ci/support/rake_wiring_driver.rb b/spec/ci/support/rake_wiring_driver.rb
deleted file mode 100644
index 259b052..0000000
--- a/spec/ci/support/rake_wiring_driver.rb
+++ /dev/null
@@ -1,92 +0,0 @@
-# frozen_string_literal: true
-
-# Runs the Rakefile the way the CI jobs run rake, and reports what the audit
-# wiring does.
-#
-# The spec (spec/ci/advisory_audit_spec.rb) starts this driver under
-# `bundle exec`, with a stub bundle-audit first on PATH and an unlocked matrix
-# gemfile outside the repo, and asserts the JSON report the driver writes:
-#
-#   RUBY2HTML_SPEC_GEMFILE  the unlocked matrix gemfile the audit runs against
-#   RUBY2HTML_SPEC_RECORD   the file the stub bundle-audit records its call in
-#   RUBY2HTML_SPEC_REPORT   the JSON report this driver writes
-#
-# Matching the Rakefile's source text proves the wiring on prose alone: the
-# report pins what a real rake run does — the prerequisites the tasks carry,
-# and what audit:advisories does in CI, outside CI and for the committed root
-# Gemfile.
-
-require 'json'
-require 'rake'
-
-ROOT = File.expand_path('../../..', __dir__)
-Dir.chdir(ROOT)
-
-MATRIX_GEMFILE = ENV.fetch('RUBY2HTML_SPEC_GEMFILE')
-RECORD = ENV.fetch('RUBY2HTML_SPEC_RECORD')
-REPORT = ENV.fetch('RUBY2HTML_SPEC_REPORT')
-
-# `bundle exec` hands its Bundler environment to every child it starts, and
-# RubyGems loads bundler/setup in every child that finds BUNDLER_SETUP or
-# RUBYOPT in its environment. The audit script is standalone (it strips the
-# Bundler variables for bundle-audit), and the matrix gemfile of the spec is a
-# stub that bundler/setup would resolve against the repository lockfile: the
-# driver drops the injected variables, so the audit runs outside the caller's
-# Bundler environment, the way the script is meant to run.
-ENV.delete('RUBYOPT')
-ENV.delete('RUBYLIB')
-ENV.delete('BUNDLER_SETUP')
-
-# Load the Rakefile the way rake does: at the top level, with the tasks of the
-# application.
-Rake.application.init
-Rake.application.load_rakefile
-
-# The prerequisites a task carries, as the report names them.
-def prerequisites_of(task)
-  Rake::Task[task].prerequisites.map(&:to_s)
-end
-
-# Invokes the audit task and reports what it did: whether the audit ran (the
-# stub recorded a call), the call it made and the error it raised.
-def run_audit(ci:, gemfile:, stub_status: '0')
-  File.delete(RECORD) if File.exist?(RECORD)
-
-  ENV['CI'] = ci ? '1' : nil
-  ENV['BUNDLE_GEMFILE'] = gemfile
-  ENV['RUBY2HTML_STUB_STATUS'] = stub_status
-
-  task = Rake::Task['audit:advisories']
-  task.reenable
-
-  error = nil
-  begin
-    task.invoke
-  rescue StandardError => e
-    error = e
-  end
-
-  outcome = { 'ran' => File.exist?(RECORD) }
-  if outcome['ran']
-    argv, cwd, bundle_gemfile = File.read(RECORD).lines.map(&:chomp)
-    outcome['call'] = [argv, cwd, bundle_gemfile]
-  end
-  outcome['raised'] = error.class.name if error
-  outcome['message'] = error.message if error
-  outcome
-end
-
-report = {
-  'prerequisites' => {
-    'compile' => prerequisites_of('compile'),
-    'spec' => prerequisites_of('spec'),
-    'spec:gem' => prerequisites_of('spec:gem'),
-    'spec:standalone' => prerequisites_of('spec:standalone')
-  },
-  'without_ci' => run_audit(ci: false, gemfile: File.join(ROOT, 'Gemfile')),
-  'with_root_gemfile' => run_audit(ci: true, gemfile: File.join(ROOT, 'Gemfile')),
-  'in_ci_with_matrix_gemfile' => run_audit(ci: true, gemfile: MATRIX_GEMFILE),
-  'failing_audit' => run_audit(ci: true, gemfile: MATRIX_GEMFILE, stub_status: '1')
-}
-
-File.write(REPORT, JSON.generate(report))