random_name_generator 4.0.4 → 4.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d87857214e4e8fc700351d66eaf1c4858b8b3eff7149d00355abdfc7d2388f2a
-  data.tar.gz: d8ef37050bbdd23e0be3dd44f708b840033da928a6db157e7e73237cc4d2201c
+  metadata.gz: 0a9a162ecd9a8953ea3383bc847dcc18a8a61506b5802ea4cd8f94daeaaf5f9b
+  data.tar.gz: 746bcfeb89b0506e7cb7f03e92f6805efc9d2493fd603bd46b363f24888089f0
 SHA512:
-  metadata.gz: 8eafd322e156f87f867941204975a214686cb24fee1dbdd676e2a3b2d3ddb58ba596f04d27b35437eb9d3baf13456a0a0fc164fb34b60037c5cc351b405b0ffe
-  data.tar.gz: df1c293f18705b8eac7d46c8f3beac17f7d9fedd312a9fd2ab0f12a57c25d5af5ce9c0cc3b7523999a1072e2e0f6ee2b4e81e94921104e6f9da83ae0a0eef289
+  metadata.gz: bc4d3f93f9945579b0e984ee0badd0c6ba96e52fa52239eee8300d6b17d0490f2390337b695e8fc34fde8eca49c6b9bd9197a5403c5538967f0c6d2244743b6b
+  data.tar.gz: 4af48dfe789cd3517f0256418f3378a0ba078c2c9b55acbad2dfbc6353b6a9f1d0453778b67c2afe8c56963018cedc66fc54c9dba4b09b048c0dd3f484ff364f

data/.okf/decisions/index.md

@@ -0,0 +1,5 @@
+# Decisions
+
+* [Randomness is injected, never global](injected-randomness.md) - generators take a `random:` keyword so specs can seed them; `srand` and global state are banned.
+* [slop is a runtime dependency](slop-runtime-dependency.md) - the CLI ships inside the gem, so its option parser must be in the gemspec.
+* [Ruby 3.4 is the floor](ruby-3-4-minimum.md) - version 4.0.0 dropped Ruby 3.0–3.3; CI tests 3.4, 4.0, and head.

data/.okf/decisions/injected-randomness.md

@@ -0,0 +1,41 @@
+---
+type: Decision
+title: Randomness is injected, never global
+description: Generators take a `random:` keyword so specs can seed them; `srand` and global state are banned.
+tags: [decision, testing, api]
+timestamp: 2026-07-26T00:00:00Z
+---
+
+# Decision
+
+Every sampling point that can be controlled takes an injected `Random`:
+
+```ruby
+RandomNameGenerator::Generator.new(lang, random: Random.new(seed))
+RandomNameGenerator.pick_number_of_syllables(random: Random.new(seed))
+```
+
+`Generator` stores it as `@rnd` and passes it to every `Array#sample` call in
+the composition path. Specs that need determinism pass a seeded `Random` —
+they never call `srand` or otherwise touch global randomness.
+
+# Why
+
+Global `srand` is process-wide: one spec seeding it changes the behavior of
+every later example, and parallel or reordered runs stop being reproducible.
+An injected `Random` scopes determinism to the object that needs it.
+
+# Limits
+
+Two entry points remain non-seedable because they sample the *language* with a
+bare `Array#sample`: `RandomNameGenerator.flip_mode` and
+`.flip_mode_cyrillic`. Their specs assert on type and shape rather than on a
+specific name. Also note that `compose` with no argument draws its syllable
+count from `pick_number_of_syllables`'s **default** `Random.new` — for a fully
+deterministic name, pass the count explicitly.
+
+See [Generator](/library/generator.md) and [the module](/library/module.md).
+
+# Citations
+
+[1] [CLAUDE.md — Conventions](https://github.com/folkengine/random_name_generator/blob/main/CLAUDE.md)

data/.okf/decisions/ruby-3-4-minimum.md

@@ -0,0 +1,34 @@
+---
+type: Decision
+title: Ruby 3.4 is the floor
+description: Version 4.0.0 dropped Ruby 3.0–3.3; CI tests 3.4, 4.0, and head.
+tags: [decision, ruby, ci]
+timestamp: 2026-07-26T00:00:00Z
+---
+
+# Decision
+
+`required_ruby_version >= 3.4.0` as of gem version **4.0.0** (2026-07-18).
+`.tool-versions` pins the development interpreter to `ruby 3.4.10`, and
+RuboCop's `TargetRubyVersion` is `3.4`.
+
+Support for Ruby 3.0 through 3.3 was dropped in the same release, alongside
+dependency bumps (`rake ~> 13.4`, `rexml`, `concurrent-ruby`).
+
+# CI matrix
+
+`.github/workflows/ruby.yml` runs the full gate on `3.4`, `4.0`, and `head`.
+`head` is `continue-on-error: true` — it exists to catch 4.1 regressions early
+without letting a broken nightly red the build. See
+[build and test](/development/build-and-test.md).
+
+# Implications
+
+The floor is a hard constraint on new code: 3.4-and-later syntax is fine, and
+the four decimal places of `.tool-versions` should track whatever patch the
+CI `3.4` job resolves to. Raising the floor again is a **major** version bump.
+
+# Citations
+
+[1] [CHANGELOG.md — 4.0.0](https://github.com/folkengine/random_name_generator/blob/main/CHANGELOG.md)
+[2] [.github/workflows/ruby.yml](https://github.com/folkengine/random_name_generator/blob/main/.github/workflows/ruby.yml)

data/.okf/decisions/slop-runtime-dependency.md

@@ -0,0 +1,34 @@
+---
+type: Decision
+title: slop is a runtime dependency
+description: The CLI ships inside the gem, so its option parser must be in the gemspec — a Gemfile entry is invisible to installed gems.
+tags: [decision, packaging, cli]
+timestamp: 2026-07-26T00:00:00Z
+---
+
+# Decision
+
+`slop ~> 4.10` is declared with `spec.add_dependency` in
+`random_name_generator.gemspec`, not merely in the `Gemfile`.
+
+# Why
+
+`exe/random_name_generator` ships as a gem executable and does
+`require "slop"` at the top. A `Gemfile` entry only affects development in
+this checkout; it is not carried into the published gem. Without the gemspec
+dependency, `gem install random_name_generator` followed by
+`random_name_generator -g` fails with `LoadError` on a machine that happens
+not to have slop.
+
+The gemspec carries an inline comment saying exactly this, so the classification
+survives future dependency cleanups.
+
+# Scope
+
+This applies to anything the shipped [CLI](/interfaces/cli.md) or `lib/`
+requires at runtime. Test and lint tooling (rspec, rubocop, reek, rake) stays
+in the Gemfile — those are correctly development-only.
+
+# Citations
+
+[1] [random_name_generator.gemspec](https://github.com/folkengine/random_name_generator/blob/main/random_name_generator.gemspec)

data/.okf/development/build-and-test.md

@@ -0,0 +1,55 @@
+---
+type: Playbook
+title: Build, test, and lint
+description: The commands that gate a change, and what each one enforces.
+tags: [development, testing, ci]
+timestamp: 2026-07-26T00:00:00Z
+---
+
+# The gate
+
+```shell
+bundle exec rake        # => spec, then rubocop
+```
+
+`rake default` is `%i[spec rubocop]`. Reek is wired as its own task
+(`rake reek`, `fail_on_error: true`) but is **not** part of the default task —
+run it deliberately.
+
+| Command | Purpose |
+|---------|---------|
+| `bundle exec rspec` | Tests. One example: `bundle exec rspec spec/random_name_generator_spec.rb:42`. |
+| `bundle exec rubocop` | Lint. `-A` to autocorrect. |
+| `bundle exec reek` | Smell detection, configured by `config.reek`. |
+| `bin/console` | IRB with the gem loaded. |
+| `bundle exec rake build` | Builds the `.gem` into `pkg/`. |
+| `bundle exec exe/random_name_generator -g` | Run the [CLI](/interfaces/cli.md) from the checkout. |
+
+# Test layout
+
+- `spec/random_name_generator_spec.rb` — module constants, factory methods,
+  and `Generator` behavior. Generators for the four base languages are built
+  once in a `before(:all)` block.
+- `spec/random_name_generator/syllable_spec.rb` — parsing and adjacency rules.
+- `spec/languages/*.txt` — fixtures that pin format edges (blank lines, a
+  one-syllable-per-bucket file, every flag combination, and an unsatisfiable
+  file that must raise). See
+  [the syllable file format](/formats/syllable-file-format.md).
+
+`spec_helper.rb` disables RSpec monkey patching, forces `expect` syntax, and
+persists example status to `.rspec_status`.
+
+# CI
+
+`.github/workflows/ruby.yml` runs `bundle exec rake` on pushes to `main`,
+`v*` tags, and every pull request, against a matrix of Ruby `3.4`, `4.0`, and
+`head`. The `head` job is `continue-on-error` — a broken nightly must not red
+the run — and installs uncached with the latest bundler, since pairing a fixed
+gem cache with a moving interpreter causes `CorruptBundlerInstallError`.
+
+Overcommit hooks are configured in `.overcommit.yml`.
+
+# Citations
+
+[1] [Rakefile](https://github.com/folkengine/random_name_generator/blob/main/Rakefile)
+[2] [.github/workflows/ruby.yml](https://github.com/folkengine/random_name_generator/blob/main/.github/workflows/ruby.yml)

data/.okf/development/conventions.md

@@ -0,0 +1,58 @@
+---
+type: Convention
+title: Code conventions
+description: Style, smell, and testing rules this repo enforces — RuboCop is the source of truth.
+tags: [development, style, lint]
+timestamp: 2026-07-26T00:00:00Z
+---
+
+# RuboCop is the arbiter
+
+`.rubocop.yml` settles style questions; don't relitigate them in review.
+
+| Setting | Value |
+|---------|-------|
+| `TargetRubyVersion` | 3.4, `NewCops: enable` |
+| String literals | **double quotes** (including in interpolation) |
+| `Layout/LineLength` | 180 |
+| `Metrics/MethodLength` | 11 |
+| `Metrics/ClassLength` | disabled |
+| `Metrics/BlockLength` | excluded for `spec/**/*` |
+| `Style/HashSyntax` | shorthand `either` |
+
+Plugins: `rubocop-rspec`, `rubocop-rake`.
+
+RSpec cops are relaxed where the existing spec style needs it —
+`BeforeAfterAll` and `InstanceVariable` are disabled (the specs build shared
+generators in `before(:all)`), `MultipleExpectations` is off, and
+`NestedGroups` allows 5.
+
+Every source file carries `# frozen_string_literal: true`.
+
+# Reek
+
+`config.reek` disables `IrresponsibleModule` and `TooManyMethods`, caps
+instance variables at 10, and caps statements at 8 (excluding `initialize`).
+Where a class legitimately exceeds a smell threshold, it carries an inline
+`:reek:` annotation rather than a config exemption — e.g. `:reek:TooManyConstants`
+on [the module](/library/module.md) and `:reek:TooManyMethods` on
+[Syllable](/library/syllable.md).
+
+# Testing
+
+- `expect` syntax only; monkey patching disabled.
+- Fixtures live in `spec/languages/`, never inline.
+- Never use `srand` or global randomness for determinism — pass a seeded
+  `Random`. See [injected randomness](/decisions/injected-randomness.md).
+
+# Shape of the code
+
+Pure file-in / string-out: no network, no threads, no mutable global state
+beyond the shared `File` constants. Keeping it that way is what makes the
+library trivially embeddable.
+
+# Citations
+
+[1] [.rubocop.yml](https://github.com/folkengine/random_name_generator/blob/main/.rubocop.yml)
+[2] [config.reek](https://github.com/folkengine/random_name_generator/blob/main/config.reek)
+[3] [CLAUDE.md](https://github.com/folkengine/random_name_generator/blob/main/CLAUDE.md)

data/.okf/development/index.md

@@ -0,0 +1,5 @@
+# Development
+
+* [Build, test, and lint](build-and-test.md) - the commands that gate a change, and what each one enforces.
+* [Code conventions](conventions.md) - style, smell, and testing rules; RuboCop is the source of truth.
+* [Releasing the gem](release.md) - version bump, changelog, and the rake release path to RubyGems.

data/.okf/development/release.md

@@ -0,0 +1,44 @@
+---
+type: Playbook
+title: Releasing the gem
+description: Version bump, changelog, and the rake release path to RubyGems.
+resource: https://rubygems.org/gems/random_name_generator
+tags: [development, release, packaging]
+timestamp: 2026-07-26T00:00:00Z
+---
+
+The gem is published as
+[random_name_generator](https://rubygems.org/gems/random_name_generator) under
+LGPL-3.0. Current version: **4.0.4** (`lib/random_name_generator/version.rb`).
+
+# Steps
+
+1. Bump `RandomNameGenerator::VERSION` in `lib/random_name_generator/version.rb`
+   — the gemspec reads it, so it is the single source of truth.
+2. Add a CHANGELOG entry under a `## <version> - <YYYY-MM-DD>` heading.
+3. Run the gate: `bundle exec rake` (see
+   [build and test](/development/build-and-test.md)).
+4. `bundle exec rake release` — tags, pushes commits and the tag, and pushes
+   the `.gem` to RubyGems. Pushing a `v*` tag also triggers CI.
+
+`rubygems_mfa_required` is set in the gemspec metadata, so the push requires
+MFA.
+
+# Packaging notes
+
+- `spec.files` comes from `git ls-files`, minus `test/`, `spec/`, and
+  `features/` — an untracked language file will **not** ship.
+- `bindir` is `exe`; executables are derived from tracked files there.
+- `required_ruby_version >= 3.4.0` — see
+  [the Ruby floor](/decisions/ruby-3-4-minimum.md).
+- `slop ~> 4.10` is a runtime dependency, not a development one — see
+  [why](/decisions/slop-runtime-dependency.md).
+
+`bundle exec rake install` installs the gem locally, which is how you get a
+bare `random_name_generator` command on `PATH` for testing the
+[CLI](/interfaces/cli.md).
+
+# Citations
+
+[1] [random_name_generator.gemspec](https://github.com/folkengine/random_name_generator/blob/main/random_name_generator.gemspec)
+[2] [CHANGELOG.md](https://github.com/folkengine/random_name_generator/blob/main/CHANGELOG.md)

data/.okf/formats/index.md

@@ -0,0 +1,3 @@
+# Formats
+
+* [Syllable file format (.txt)](syllable-file-format.md) - line-oriented grammar for language files: one syllable per line, a position sigil, and optional adjacency flags.

data/.okf/formats/syllable-file-format.md

@@ -0,0 +1,69 @@
+---
+type: File Format
+title: Syllable file format (.txt)
+description: Line-oriented grammar for language files — one syllable per line, a position sigil, and optional adjacency flags.
+tags: [format, domain, languages]
+timestamp: 2026-07-26T00:00:00Z
+---
+
+The syllable file is the domain data of this project; everything in
+`lib/` is machinery for reading it. The format is deliberately plain text so a
+language can be authored, diffed, and reviewed by hand.
+
+# Schema
+
+One syllable per line. Blank lines are ignored. Leading/trailing whitespace is
+stripped and the whole line is downcased.
+
+```
+[sigil]syllable [flag] [flag]
+```
+
+| Element | Values | Meaning |
+|---------|--------|---------|
+| sigil | `-` | Prefix — may only appear first in a name. |
+| | `+` | Suffix — may only appear last. |
+| | *(none)* | Middle. |
+| syllable | any characters | The text contributed to the name. |
+| flags | `+v` | The **next** syllable must start with a vowel. |
+| | `+c` | The next syllable must start with a consonant. |
+| | `-v` | The **previous** syllable must end with a vowel. |
+| | `-c` | The previous syllable must end with a consonant. |
+
+Flags are whitespace-separated and order-independent. `+v`/`+c` are mutually
+exclusive (first wins), as are `-v`/`-c`.
+
+```
+-ang +c      prefix "ang", next syllable must begin with a consonant
+bryn         middle, unconstrained
++wen -c      suffix "wen", only after a syllable ending in a consonant
+```
+
+# Authoring constraints
+
+- **All three buckets must be non-empty.** A file with no suffixes cannot
+  compose a name of two or more syllables.
+- **Flags must be satisfiable.** If some syllable's `+v` has no vowel-initial
+  candidate in the middle or suffix bucket, composition raises `ArgumentError`
+  at generation time, not load time — see [Generator](/library/generator.md).
+  Sparse buckets plus aggressive flags is the usual cause.
+- Use flags only where the phonetics actually demand them. Most lines in the
+  bundled languages carry none.
+
+# Where the files live
+
+Curated languages are in `lib/languages/`; edgier or less polished sets are in
+`lib/languages/experimental/`. Cyrillic variants use the `-ru.txt` suffix and
+rely on `Syllable`'s Cyrillic character classes. See the
+[language catalog](/languages/catalog.md) and
+[adding a language](/languages/adding-a-language.md).
+
+Test fixtures in `spec/languages/` exercise the edges of the format:
+`test-blank.txt` (blank lines), `test-micro.txt` (one syllable per bucket, no
+trailing newline), `test-tiny.txt` (every flag combination), and
+`test-incompatible.txt` (a file whose flags cannot be satisfied).
+
+# Citations
+
+[1] [Syllable class documentation](https://github.com/folkengine/random_name_generator/blob/main/lib/random_name_generator/syllable.rb)
+[2] [java-random-name-generator](https://github.com/folkengine/java-random-name-generator) — the port's origin; the format is inherited from it.

data/.okf/index.md

@@ -0,0 +1,19 @@
+---
+okf_version: '0.1'
+---
+
+# random_name_generator Knowledge Bundle
+
+Knowledge about the `random_name_generator` Ruby gem — how names are composed
+from syllable files, what ships, and how to work on it.
+
+* [Overview](overview.md) - the project at a glance: shape, properties, and where to start.
+
+# Areas
+
+* [library/](library/) - the Ruby API: module, Generator, Syllable.
+* [formats/](formats/) - the syllable file format that drives everything.
+* [languages/](languages/) - the shipped syllable files and how to add one.
+* [interfaces/](interfaces/) - the command line executable.
+* [development/](development/) - build, test, lint, and release.
+* [decisions/](decisions/) - choices worth not re-deriving.

data/.okf/interfaces/cli.md

@@ -0,0 +1,65 @@
+---
+type: CLI
+title: random_name_generator (executable)
+description: The slop-based command line interface — one boolean flag per language, printing a two-name pair.
+resource: https://github.com/folkengine/random_name_generator/blob/main/exe/random_name_generator
+tags: [cli, interface]
+timestamp: 2026-07-26T00:00:00Z
+---
+
+```shell
+$ bundle exec exe/random_name_generator [-egrkbfcxdß?]
+$ random_name_generator --german-curse     # after `bundle exec rake install`
+Dummkopfischpopelsepp Schnoddmistmann
+```
+
+The script always prints **two** composed names separated by a space —
+a first and last name — each with a randomly drawn syllable count.
+
+# Flags
+
+| Flag | Long | Selects |
+|------|------|---------|
+| `-e` | `--elven` | `ELVEN` (or `ELVEN_RU` with `-c`) |
+| `-g` | `--goblin` | `GOBLIN` / `GOBLIN_RU` |
+| `-r` | `--roman` | `ROMAN` / `ROMAN_RU` |
+| `-k` | `--klingon` | `KLINGON` |
+| `-b` | `--belter` | `BELTER` |
+| `-x` | `--xrated` | `CURSE` *[NEEDS WORK]* |
+| `-d` | `--demonic` | `DEMONIC` |
+| `-ß` | `--german-curse` | `GERMAN_CURSE` *[NEEDS WORK]* |
+| `-c` | `--cyrillic` | Switches to the Cyrillic branch; alone it means `FANTASY_RU`. |
+| `-f` | `--flipmode` | Random language per name; honors `-c`. |
+| `-?` | `--help` | Prints the slop usage block. |
+
+With no flags, the default is `FANTASY`.
+
+# Selection semantics
+
+Language selection is a straight run of `if` assignments against a `lang`
+variable initialized to `FANTASY`, split into a Cyrillic and a non-Cyrillic
+branch. Consequences worth knowing:
+
+- **Last flag in source order wins**, not last on the command line —
+  `-e -g` yields Goblin because the `GOBLIN` assignment comes after `ELVEN`.
+- The Cyrillic branch only knows Elven, Goblin, and Roman, so `-c -k`,
+  `-c -b`, `-c -d` etc. fall through to `FANTASY_RU`.
+- `-f` short-circuits language selection entirely; `-?` short-circuits
+  everything but `-f`.
+- There is **no flag for Welsh** — see the
+  [language catalog](/languages/catalog.md).
+
+The CLI exposes no syllable-count option; every name uses
+`RandomNameGenerator.pick_number_of_syllables`.
+
+# Packaging
+
+Option parsing uses [slop](https://rubygems.org/gems/slop), which is therefore
+a **runtime** dependency of the gem, not merely a Gemfile entry — see
+[that decision](/decisions/slop-runtime-dependency.md). The gemspec sets
+`bindir = "exe"` and derives `executables` from the tracked files under it.
+
+# Citations
+
+[1] [exe/random_name_generator](https://github.com/folkengine/random_name_generator/blob/main/exe/random_name_generator)
+[2] [README — Installation](https://github.com/folkengine/random_name_generator/blob/main/README.md)

data/.okf/interfaces/index.md

@@ -0,0 +1,3 @@
+# Interfaces
+
+* [random_name_generator (executable)](cli.md) - the slop-based command line interface: one boolean flag per language, printing a two-name pair.

data/.okf/languages/adding-a-language.md

@@ -0,0 +1,59 @@
+---
+type: Playbook
+title: Adding a language
+description: The five touch points a new syllable file has to reach, and the lang-gen skill that automates them.
+tags: [languages, playbook, contributing]
+timestamp: 2026-07-26T00:00:00Z
+---
+
+A language is not just a file — it has to be registered, exercised, and
+documented. Missing one of these is the usual review comment.
+
+# Steps
+
+1. **Write the `.txt`.** Follow the
+   [syllable file format](/formats/syllable-file-format.md). Curated languages
+   go in `lib/languages/`; edgy or unpolished ones in
+   `lib/languages/experimental/`. Cyrillic variants take the `-ru.txt` suffix.
+2. **Register the `File` constant** in `lib/random_name_generator.rb`, grouped
+   with its peers (plain / Cyrillic / experimental).
+3. **Add a CLI flag** in `exe/random_name_generator` if the language is
+   user-facing — both the `o.bool` declaration and the assignment in the
+   correct branch of the Cyrillic conditional. See [the CLI](/interfaces/cli.md).
+4. **Add a spec** to `spec/random_name_generator_spec.rb`. A smoke test that
+   composes names at each syllable count is enough to catch an unsatisfiable
+   flag set, which otherwise only surfaces at runtime.
+5. **Document it** — README (with a link to the file) and CHANGELOG.
+
+# Verification
+
+Beyond the spec, check that all three buckets are non-empty and that names
+actually compose at 1..5 syllables:
+
+```shell
+bundle exec ruby -Ilib -e '
+  require "random_name_generator"
+  g = RandomNameGenerator.new(RandomNameGenerator::WELSH)
+  (1..5).each { |n| puts "#{n}: #{Array.new(5) { g.compose(n) }.join(" ")}" }
+'
+```
+
+Then run the gate: `bundle exec rake` — see
+[build and test](/development/build-and-test.md).
+
+# The lang-gen skill
+
+`.claude/skills/lang-gen/SKILL.md` automates the whole flow from a plain-English
+theme, e.g. `/lang-gen Klingon words of joy`. It derives the slug, constant,
+and destination directory (routing edgy themes to `experimental/`), authors the
+three buckets with adjacency flags, performs steps 2–5, and samples names to
+verify. `GERMAN_CURSE` was generated this way.
+
+A portable text version of the same prompt lives at
+`docs/superpowers/specs/2026-07-19-lang-gen-portable-prompt.md` for use outside
+Claude Code.
+
+# Citations
+
+[1] [CLAUDE.md — Adding a language](https://github.com/folkengine/random_name_generator/blob/main/CLAUDE.md)
+[2] [README — lang-gen](https://github.com/folkengine/random_name_generator/blob/main/README.md)

data/.okf/languages/catalog.md

@@ -0,0 +1,70 @@
+---
+type: Catalog
+title: Language catalog
+description: Every bundled syllable file — its constant, path, CLI flag, and bucket sizes.
+tags: [languages, data, catalog]
+timestamp: 2026-07-26T00:00:00Z
+---
+
+Fourteen syllable files ship with the gem. Each is bound to a `File` constant
+on [the module](/library/module.md) and, where user-facing, to a
+[CLI](/interfaces/cli.md) flag.
+
+# Curated languages
+
+| Constant | File | CLI | pre / mid / suf |
+|----------|------|-----|-----------------|
+| `FANTASY` | `lib/languages/fantasy.txt` | *(default)* | 179 / 153 / 18 |
+| `ELVEN` | `lib/languages/elven.txt` | `-e` | 36 / 21 / 27 |
+| `GOBLIN` | `lib/languages/goblin.txt` | `-g` | 19 / 13 / 16 |
+| `ROMAN` | `lib/languages/roman.txt` | `-r` | 15 / 10 / 10 |
+| `KLINGON` | `lib/languages/klingon.txt` | `-k` | 40 / 35 / 36 |
+| `BELTER` | `lib/languages/belter.txt` | `-b` | 35 / 40 / 27 |
+| `WELSH` | `lib/languages/welsh.txt` | *(none)* | 35 / 32 / 24 |
+
+`WELSH` is reachable from the library but has **no CLI flag** — the one gap
+between the constant set and `exe/random_name_generator`.
+
+# Cyrillic variants
+
+Same four base styles, transliterated into Cyrillic syllables. They work
+because `Syllable::VOWELS` and `CONSONANTS` include the Cyrillic alphabet
+(see [Syllable](/library/syllable.md)).
+
+| Constant | File | CLI | pre / mid / suf |
+|----------|------|-----|-----------------|
+| `FANTASY_RU` | `lib/languages/fantasy-ru.txt` | `-c` | 180 / 157 / 19 |
+| `ELVEN_RU` | `lib/languages/elven-ru.txt` | `-c -e` | 36 / 21 / 27 |
+| `GOBLIN_RU` | `lib/languages/goblin-ru.txt` | `-c -g` | 19 / 13 / 16 |
+| `ROMAN_RU` | `lib/languages/roman-ru.txt` | `-c -r` | 15 / 10 / 10 |
+
+The Cyrillic set is what `-c` selects, and it is also the pool for
+`RandomNameGenerator.flip_mode_cyrillic`. `KLINGON`, `BELTER`, and `WELSH`
+have no Cyrillic counterpart, so `-c -k` silently yields `FANTASY_RU`.
+
+# Experimental languages
+
+Edgier, less curated sets under `lib/languages/experimental/`. Opt-in only.
+
+| Constant | File | CLI | pre / mid / suf |
+|----------|------|-----|-----------------|
+| `CURSE` | `experimental/curse.txt` | `-x` | 24 / 7 / 32 |
+| `DEMONIC` | `experimental/demonic.txt` | `-d` | 111 / 64 / 73 |
+| `GERMAN_CURSE` | `experimental/german-curse.txt` | `-ß` | 105 / 98 / 127 |
+
+`CURSE` and `GERMAN_CURSE` are marked `[NEEDS WORK]` in the CLI help.
+`CURSE`'s middle bucket holds only 7 syllables, so names of three or more
+syllables repeat heavily. `GERMAN_CURSE` was produced by the `lang-gen` skill
+and is the worked example for [adding a language](/languages/adding-a-language.md).
+
+# Flip mode
+
+`RandomNameGenerator.flip_mode` samples only `FANTASY`, `ELVEN`, `GOBLIN`, and
+`ROMAN` — the four original styles. New languages are **not** picked up by
+flip mode automatically; the arrays in `lib/random_name_generator.rb` are
+hard-coded.
+
+# Citations
+
+[1] [lib/random_name_generator.rb](https://github.com/folkengine/random_name_generator/blob/main/lib/random_name_generator.rb)
+[2] [README — Usage](https://github.com/folkengine/random_name_generator/blob/main/README.md)

data/.okf/languages/index.md

@@ -0,0 +1,4 @@
+# Languages
+
+* [Language catalog](catalog.md) - every bundled syllable file: its constant, path, CLI flag, and bucket sizes.
+* [Adding a language](adding-a-language.md) - the five touch points a new syllable file has to reach, and the lang-gen skill that automates them.

data/.okf/library/generator.md

@@ -0,0 +1,82 @@
+---
+type: Ruby Class
+title: RandomNameGenerator::Generator
+description: Reads a syllable file into three buckets and assembles a name by walking prefix → middles → suffix.
+resource: https://github.com/folkengine/random_name_generator/blob/main/lib/random_name_generator.rb
+tags: [ruby, api, core]
+timestamp: 2026-07-26T00:00:00Z
+---
+
+The workhorse class. One `Generator` wraps one language file; `compose` may be
+called repeatedly on the same instance.
+
+# Construction
+
+```ruby
+Generator.new(language = RandomNameGenerator::FANTASY, random: Random.new)
+```
+
+`initialize` calls the private `refresh`, which reads every non-blank line of
+the language `File`, turns it into a [Syllable](/library/syllable.md), and
+pushes it into `@pre_syllables`, `@sur_syllables`, or `@mid_syllables`
+according to `prefix?`/`suffix?`. It then rewinds the file handle — necessary
+because the language constants are shared open `File` objects
+(see [the module](/library/module.md)).
+
+Blank lines are skipped, so a syllable file may be visually grouped by bucket.
+
+# Composition algorithm
+
+`compose_array(count)` returns an array of `Syllable`; `compose(count)` maps it
+to strings, joins, and `capitalize`s the result.
+
+1. Sample a prefix from `pre_syllables`.
+2. If `count < 2`, return just that prefix — a one-syllable name.
+3. Append `count - 2` middles, each chosen from the candidates in
+   `mid_syllables` compatible with the syllable before it.
+4. Append one suffix from `sur_syllables`, compatible with the last middle.
+
+So a name is always *prefix + (count-2) middles + suffix*, and a two-syllable
+name is prefix + suffix with no middle at all. `count` defaults to
+`RandomNameGenerator.pick_number_of_syllables`.
+
+Note that `compose` capitalizes the joined string, which in Ruby also
+**downcases the remainder** — and `Syllable` already downcases its input, so
+generated names are always `Titlecase`.
+
+# Failure mode
+
+`determine_next_syllable` raises `ArgumentError` when no candidate in the
+bucket is compatible with the current syllable:
+
+```
+No syllable in <path> is compatible with "<syllable>" — check its +v/+c/-v/-c flags
+```
+
+This is the practical hazard when authoring a language: over-constrained
+adjacency flags, or a bucket too small to satisfy them. `spec/languages/test-incompatible.txt`
+is the fixture that pins this behavior. See
+[the syllable file format](/formats/syllable-file-format.md).
+
+# Public surface
+
+| Member | Notes |
+|--------|-------|
+| `#compose(count = …)` | Capitalized `String`. |
+| `#compose_array(count = …)` | `Array<Syllable>`. |
+| `#language` | The `File` it was built from. |
+| `#pre_syllables` / `#mid_syllables` / `#sur_syllables` | The parsed buckets — useful in specs to assert a file loaded as intended. |
+| `#to_s` | `"RandomNameGenerator::Generator (goblin.txt)"` — basename only. |
+
+# Examples
+
+```ruby
+# Deterministic: seed the injected Random, and pass an explicit count so the
+# count itself is not drawn from global randomness.
+rng = RandomNameGenerator::Generator.new(RandomNameGenerator::ELVEN, random: Random.new(42))
+rng.compose(3)
+```
+
+# Citations
+
+[1] [lib/random_name_generator.rb](https://github.com/folkengine/random_name_generator/blob/main/lib/random_name_generator.rb)

data/.okf/library/index.md

@@ -0,0 +1,7 @@
+# Library
+
+The Ruby API, from the outside in.
+
+* [RandomNameGenerator (module)](module.md) - top-level facade: language constants, factory methods, and the syllable-count distribution.
+* [RandomNameGenerator::Generator](generator.md) - reads a syllable file into three buckets and assembles a name by walking prefix → middles → suffix.
+* [RandomNameGenerator::Syllable](syllable.md) - parses one line of a language file into a syllable plus its position and adjacency rules.

data/.okf/library/module.md

@@ -0,0 +1,69 @@
+---
+type: Ruby Module
+title: RandomNameGenerator (module)
+description: Top-level facade — holds one File constant per language, factory methods, and the syllable-count distribution.
+resource: https://github.com/folkengine/random_name_generator/blob/main/lib/random_name_generator.rb
+tags: [ruby, api, entrypoint]
+timestamp: 2026-07-26T00:00:00Z
+---
+
+`RandomNameGenerator` is a module, not a class. It exists to (a) name every
+bundled syllable file as a constant, and (b) act as a static factory for
+[Generator](/library/generator.md), which does the actual work.
+
+# Language constants
+
+Each language is an **open `File` object** created at load time from
+`lib/languages/`, not a path string:
+
+```ruby
+GOBLIN = File.new("#{dirname}/languages/goblin.txt")
+```
+
+That has two consequences worth knowing: the file handles are opened when the
+module is required, and `Generator#refresh` must `rewind` the handle after
+reading so a second `Generator` on the same constant still sees content. See
+the [language catalog](/languages/catalog.md) for the full list.
+
+# API
+
+| Method | Purpose |
+|--------|---------|
+| `RandomNameGenerator.new(language = FANTASY, random: Random.new)` | Static factory returning a `Generator`. Not a constructor — the module has no instances. |
+| `RandomNameGenerator.flip_mode` | `Generator` over a random pick of `FANTASY`, `ELVEN`, `GOBLIN`, `ROMAN`. |
+| `RandomNameGenerator.flip_mode_cyrillic` | Same, over the four `*_RU` constants. |
+| `RandomNameGenerator.pick_number_of_syllables(random: Random.new)` | Samples the default syllable count. |
+
+`flip_mode` and `flip_mode_cyrillic` take no `random:` keyword — they use
+`Array#sample` with global randomness for the language pick, so they are not
+seedable. Only `.new` and `pick_number_of_syllables` accept an injected
+`Random`; see [injected randomness](/decisions/injected-randomness.md).
+
+# Syllable-count distribution
+
+`pick_number_of_syllables` samples from a literal weighted array rather than
+computing a distribution:
+
+```ruby
+[2, 2, 2, 2, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 4, 4, 4, 5]
+```
+
+That is 4/18 twos, 10/18 threes, 3/18 fours, 1/18 fives — three-syllable names
+are the common case by design.
+
+# Examples
+
+```ruby
+require "random_name_generator"
+
+rng = RandomNameGenerator.new(RandomNameGenerator::GOBLIN)
+puts rng.compose(3)
+
+flip = RandomNameGenerator.flip_mode
+puts flip.compose
+```
+
+# Citations
+
+[1] [lib/random_name_generator.rb](https://github.com/folkengine/random_name_generator/blob/main/lib/random_name_generator.rb)
+[2] [README — Usage](https://github.com/folkengine/random_name_generator/blob/main/README.md)

data/.okf/library/syllable.md

@@ -0,0 +1,83 @@
+---
+type: Ruby Class
+title: RandomNameGenerator::Syllable
+description: Parses one line of a language file into a syllable plus its position and adjacency rules, and answers compatibility questions.
+resource: https://github.com/folkengine/random_name_generator/blob/main/lib/random_name_generator/syllable.rb
+tags: [ruby, api, parsing]
+timestamp: 2026-07-26T00:00:00Z
+---
+
+`Syllable` absorbs all the parsing complexity of the
+[syllable file format](/formats/syllable-file-format.md) so that
+[Generator](/library/generator.md) only has to sample from arrays and ask
+`compatible?`. It is not meant to be called directly in normal use.
+
+Extracting this class is the main structural departure from the Java original
+the gem was ported from.
+
+# Parsing
+
+`Syllable.new(args)` accepts a `String` line, or another `Syllable` (which
+clones it via `#raw`). The line is stripped, **downcased**, and split on
+whitespace:
+
+- token 0 is the syllable, matched against `/([+-]?)(.+)/` — a leading `-`
+  sets `prefix?`, a leading `+` sets `suffix?`, anything else is a middle;
+- remaining tokens are flags, order-independent.
+
+An empty syllable raises `ArgumentError, "Empty String is not allowed."`.
+Note that flags are matched by exact token, so an unrecognized flag is
+silently ignored rather than rejected.
+
+# Compatibility
+
+Two independent rules decide whether syllable B may follow syllable A —
+`A.compatible?(B)` is false if either fails:
+
+| Rule | Source | Meaning |
+|------|--------|---------|
+| next | `A`'s `+v` / `+c` | B must *start* with a vowel / consonant. |
+| previous | `B`'s `-v` / `-c` | A must *end* with a vowel / consonant. |
+
+Both requirements default to `:letter` (unconstrained). Within each pair the
+parse is `if/elsif`, so a line carrying both `+v` and `+c` keeps only `+v`,
+and one carrying both `-v` and `-c` keeps only `-v`.
+
+# Character classes
+
+`VOWELS` and `CONSONANTS` are frozen arrays of single-character strings
+covering Latin, extended IPA-ish, and Cyrillic letters — this is what lets the
+Cyrillic language files work with the same engine. Membership is tested on
+`syllable[0]` and `syllable[-1]`.
+
+`y` is deliberately in **both** sets: as a semivowel it satisfies either a
+`+v` or a `+c` requirement. A character in *neither* set (a digit, an
+apostrophe) makes both `vowel_last?` and
+`consonant_last?` false, which means it can never violate a `-v`/`-c`
+requirement — such a syllable is universally acceptable as a predecessor.
+
+# Public surface
+
+| Member | Notes |
+|--------|-------|
+| `#compatible?(next)` / `#incompatible?(next)` | The pair used by `Generator`. |
+| `#prefix?` / `#suffix?` | Bucket assignment. |
+| `#vowel_first?` / `#consonant_first?` / `#vowel_last?` / `#consonant_last?` | Class membership of the first/last character. |
+| `#next_syllable_universal?`, `#next_syllable_must_start_with_vowel?`, `#next_syllable_must_start_with_consonant?` | Reads of `next_syllable_requirement`. |
+| `#previous_syllable_universal?`, `#previous_syllable_must_end_with_vowel?`, `#previous_syllable_must_end_with_consonant?` | Reads of `previous_syllable_requirement`. |
+| `#raw` | The original stripped line — including sigil and flags. |
+| `#to_s` / `#to_str` | The bare syllable text; `to_str` makes it implicitly coercible in string ops. |
+
+# Examples
+
+```ruby
+s = RandomNameGenerator::Syllable.new("-foo +c")
+s.prefix?                                   # => true
+s.to_s                                      # => "foo"
+s.raw                                       # => "-foo +c"
+s.next_syllable_must_start_with_consonant?  # => true
+```
+
+# Citations
+
+[1] [lib/random_name_generator/syllable.rb](https://github.com/folkengine/random_name_generator/blob/main/lib/random_name_generator/syllable.rb) — the class doc there is the authoritative statement of the rules.

data/.okf/log.md

@@ -0,0 +1,9 @@
+# Update Log
+
+## 2026-07-26
+* **Initialization**: Scaffolded the bundle with `okf_init.py` and replaced the placeholder concept with a real [overview](/overview.md).
+* **Creation**: Documented the Ruby API — [module](/library/module.md), [Generator](/library/generator.md), [Syllable](/library/syllable.md).
+* **Creation**: Captured the [syllable file format](/formats/syllable-file-format.md), the [language catalog](/languages/catalog.md) (14 files, bucket sizes as of gem 4.0.4), and [adding a language](/languages/adding-a-language.md).
+* **Creation**: Documented the [CLI](/interfaces/cli.md), including flag precedence, Cyrillic fall-through, and the missing Welsh flag.
+* **Creation**: Established development playbooks — [build and test](/development/build-and-test.md), [conventions](/development/conventions.md), [release](/development/release.md).
+* **Creation**: Recorded three decisions — [injected randomness](/decisions/injected-randomness.md), [slop as a runtime dependency](/decisions/slop-runtime-dependency.md), [the Ruby 3.4 floor](/decisions/ruby-3-4-minimum.md).

data/.okf/overview.md

@@ -0,0 +1,59 @@
+---
+type: Project
+title: random_name_generator
+description: Ruby gem that composes names from per-language syllable files, shipping a library API and a CLI.
+resource: https://github.com/folkengine/random_name_generator
+tags: [ruby, gem, overview]
+timestamp: 2026-07-26T00:00:00Z
+---
+
+A Ruby gem (3.4+) that builds names — Elven, Goblin, Roman, Klingon, Belter,
+Welsh, and more — by assembling syllables drawn from plain-text language files.
+It is a port of
+[java-random-name-generator](https://github.com/folkengine/java-random-name-generator),
+which descends from Sinipull's GPL'd post on codecall.net. Published as
+[random_name_generator](https://rubygems.org/gems/random_name_generator) under
+LGPL-3.0.
+
+# Shape
+
+```
+lib/languages/*.txt        the domain data — syllables + adjacency flags
+lib/random_name_generator/syllable.rb   parses one line
+lib/random_name_generator.rb            constants, factories, Generator
+exe/random_name_generator               slop-based CLI
+```
+
+The whole system is one idea: a **syllable file** is a list of prefixes,
+middles, and suffixes, each optionally constrained by what may precede or
+follow it. Everything else reads that file and samples from it.
+
+| Layer | Concept |
+|-------|---------|
+| Data format | [Syllable file format](/formats/syllable-file-format.md) |
+| Parsing | [Syllable](/library/syllable.md) |
+| Composition | [Generator](/library/generator.md) |
+| Public API | [RandomNameGenerator module](/library/module.md) |
+| Command line | [CLI](/interfaces/cli.md) |
+| The data itself | [Language catalog](/languages/catalog.md) |
+
+# Properties
+
+- **Pure**: file in, string out. No network, no threads, no global mutable
+  state beyond the shared `File` constants.
+- **Seedable**: randomness is injected, not global — see
+  [that decision](/decisions/injected-randomness.md).
+- **Extensible by data**: adding a language means adding a text file and
+  wiring it up, not changing the algorithm. See
+  [adding a language](/languages/adding-a-language.md).
+
+# Working here
+
+`bundle exec rake` is the gate (spec then rubocop) —
+see [build and test](/development/build-and-test.md) and
+[conventions](/development/conventions.md).
+
+# Citations
+
+[1] [README.md](https://github.com/folkengine/random_name_generator/blob/main/README.md)
+[2] [RandomNameGeneratorHub](https://github.com/folkengine/RandomNameGeneratorHub) — ports in other languages.

data/AI-BOM.md

@@ -1,6 +1,6 @@
 # AI Bill of Materials — random_name_generator
 
-_Last updated: 2026-07-19 · random_name_generator v4.0.2_
+_Last updated: 2026-07-26 · random_name_generator v4.0.5_
 
 An inventory of every AI component associated with this repository — development
 tools used to build it, AI-generated content shipped within it, and external AI
@@ -20,6 +20,7 @@ to provenance.
 | Tool | Vendor | Role | Notes |
 |------|--------|------|-------|
 | Claude Code | Anthropic | AI coding assistant | Introduced in 4.0.0; drives the [`lang-gen`](./.claude/skills/lang-gen/SKILL.md) skill and general maintenance |
+| `okf` skill | — | Knowledge-bundle authoring | External Claude Code skill; authored and maintains the [`.okf/`](./.okf/index.md) bundle. Not vendored in this repo |
 
 ---
 
@@ -43,6 +44,9 @@ All output was human-reviewed before commit.
 | [`lang-gen`](./.claude/skills/lang-gen/SKILL.md) | Claude Code skill | — | Generates a fully integrated language from a plain-English theme |
 | [German Curse](./lib/languages/experimental/german-curse.txt) (`GERMAN_CURSE`) | Language syllable file | `lang-gen` | Experimental; seeded from real roots, extended with invented syllables |
 | [Demonic](./lib/languages/experimental/demonic.txt) (`DEMONIC`) | Language syllable file | `lang-gen` | Experimental; completed from infernal-name source lists |
+| [Welsh](./lib/languages/welsh.txt) (`WELSH`) | Language syllable file | `lang-gen` | Added in 4.0.4; seeded from real Welsh name roots |
+| [Belter](./lib/languages/belter.txt) (`BELTER`) | Language syllable file | `lang-gen` | Added in 4.0.4; Belter creole (The Expanse), an invented language |
+| [`.okf/`](./.okf/index.md) | Knowledge bundle | `okf` skill | Added in 4.0.5; 14 OKF concept files across 6 areas — the API, syllable format, CLI, and decisions |
 | [Portable lang-gen prompt](./docs/superpowers/specs/2026-07-19-lang-gen-portable-prompt.md) | Text prompt | — | LLM-agnostic version of the skill |
 
 ---
@@ -81,5 +85,6 @@ no network calls and requires no API keys. None are planned.
 |----------|---------|
 | [`docs/AUDIT_Fable_5.md`](./docs/AUDIT_Fable_5.md) | Full-codebase audit with empirically verified findings |
 | [`.claude/skills/lang-gen/SKILL.md`](./.claude/skills/lang-gen/SKILL.md) | The lang-gen language-generation skill |
+| [`.okf/index.md`](./.okf/index.md) | AI-authored knowledge bundle; [`.okf/log.md`](./.okf/log.md) is its change log |
 | [`README.md`](./README.md) | Project overview, including the lang-gen workflow |
 | [`docs/superpowers/specs/2026-07-19-lang-gen-portable-prompt.md`](./docs/superpowers/specs/2026-07-19-lang-gen-portable-prompt.md) | Paste-into-any-LLM version of the prompt |

data/CHANGELOG.md

@@ -1,5 +1,63 @@
 ## Version 4
 
+## 4.0.5 - unreleased
+
+- Added an [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+  knowledge bundle in `.okf/` — 14 concept files across 6 areas covering the
+  Ruby API, the syllable file format, the language catalog, the CLI, the
+  development playbooks, and three recorded decisions.
+- Expanded `CLAUDE.md` with the project's architecture, conventions, and the
+  rules for consulting and maintaining the knowledge bundle.
+- Documented the bundle in `README.md`.
+
+## 4.0.4 - 2026-07-19
+
+- Added the Welsh language (`WELSH`), seeded from real Welsh name roots.
+  Note: no CLI flag was wired up for it — reachable from the library only.
+- Added the Belter language (`BELTER`), the creole from The Expanse, with a
+  `-b`/`--belter` CLI flag.
+- Both files were generated with the `lang-gen` skill.
+
+## 4.0.3 - 2026-07-19
+
+Fixes from the first full-codebase audit (see [`docs/AUDIT_Fable_5.md`](./docs/AUDIT_Fable_5.md)).
+
+- **`slop` is now a runtime dependency** in the gemspec rather than a Gemfile
+  entry, so the installed CLI actually starts.
+- **Fixed `compose(1)` crashing**: `compose_array` returns `[@pre]` for counts
+  below 2 instead of a `String`, making the return type honest.
+- **Fixed blank lines in language files**: `refresh` now strips before the
+  empty check.
+- **Fixed a potential infinite loop**: `determine_next_syllable` pre-filters
+  compatible candidates instead of rejection-sampling, and raises
+  `ArgumentError` naming the file and syllable when no candidate exists.
+- **Cyrillic and German letters are now classified**: added Cyrillic vowels and
+  consonants plus `ö`, `ü`, `ß`, so the `+v`/`+c`/`-v`/`-c` flags in the four
+  `*-ru.txt` files and in `german-curse.txt` are actually enforced. They were
+  silent no-ops before.
+- Fixed the broken `Syllable` clone constructor and a malformed
+  `raise ArgumentError`.
+- Documented the intentional dual classification of `y` as both vowel and
+  consonant.
+- Added `spec/languages/test-blank.txt` and `test-incompatible.txt` fixtures,
+  plus an adjacency spec that walks composed names pairwise.
+- Corrected the README syllable range to "between 2 and 5" and fixed four
+  "eyllable" typos.
+
+## 4.0.2 - 2026-07-19
+
+- Added a `-d`/`--demonic` CLI flag for the experimental `DEMONIC` language,
+  which had shipped without a way to select it from the command line.
+- Added a `-k`/`--klingon` CLI flag for `KLINGON`, likewise unreachable before.
+
+## 4.0.1 - 2026-07-19
+
+- Added the `lang-gen` skill, which generates a fully integrated language from
+  a plain-English theme.
+- Added the experimental German Curse language (`GERMAN_CURSE`) via `lang-gen`,
+  with a `-ß`/`--german-curse` CLI flag.
+- Added a portable, LLM-agnostic version of the `lang-gen` prompt in `docs/`.
+
 ## 4.0.0 - 2026-07-18
 
 - Raised minimum required Ruby version to 3.4.0 (dropping 3.0–3.3 support).
@@ -7,8 +65,31 @@
 - Bumped dependencies: `rake` (~> 13.4), `rexml`, `concurrent-ruby`.
 - Updated CI workflow and Rubocop settings.
 
+## Version 3
+
+## 3.0.0 - 2024-10-05
+
+- Bumped the major version to mark the removal of Ruby 2.x support.
+
 ## Version 2
 
+## 2.1.1 - 2024-10-05
+
+- Added Ruby 3.3.5 to the CI matrix.
+- Updated Rubocop settings and applied the resulting style fixes across the
+  specs.
+- Moved `spec/syllable_spec.rb` to `spec/random_name_generator/syllable_spec.rb`.
+
+## 2.1.0 - 2023-12-17
+
+- Added a devcontainer (`.devcontainer/`) for containerized development.
+- Updated the CI workflow and Rubocop settings.
+- Refreshed dependencies.
+
+## 2.0.1 - 2021-08-08
+
+- Updated dependencies.
+
 ## 2.0.0 - 2021-03-28
 
 - Major Refactor

data/CLAUDE.md

@@ -0,0 +1,49 @@
+# CLAUDE.md
+
+## Project
+
+`random_name_generator` — a Ruby gem (Ruby 3.4.10) that builds names by assembling
+syllables from per-language `.txt` files. Ships a library API and a `slop`-based CLI
+(`exe/random_name_generator`).
+
+## Commands
+
+- **Full check (the gate):** `bundle exec rake` — runs `spec` then `rubocop`.
+- **Tests:** `bundle exec rspec` — one line: `bundle exec rspec spec/random_name_generator_spec.rb:42`
+- **Lint:** `bundle exec rubocop` (auto-fix `-A`) · **Smells:** `bundle exec reek`
+- **Console:** `bin/console` · **Build:** `bundle exec rake build`
+- **Run CLI:** `bundle exec exe/random_name_generator -g`
+
+## Architecture
+
+- `lib/random_name_generator.rb` — the module. Each language is a `File` constant, e.g.
+  `GOBLIN = File.new(".../goblin.txt")`. `Generator` reads it and composes a name.
+- `lib/random_name_generator/syllable.rb` — parses one line: `-` = first, `+` = last,
+  else middle; `+v/+c/-v/-c` are vowel/consonant adjacency rules (see class doc).
+- `lib/languages/*.txt` — the domain data: plain, Cyrillic (`*-ru.txt`), `experimental/`.
+- `exe/random_name_generator` — CLI; flags (`-e/-g/-r/-k/-b/-c/-x/-d/-ß`) pick a constant.
+
+## Conventions
+
+- **Randomness is injected:** `Generator.new(lang, random: Random.new)`. For deterministic
+  specs pass a seeded `Random.new(seed)` — never `srand` or global state.
+- **`slop` is a runtime dep** (in the gemspec, not just the Gemfile) — the installed CLI needs it.
+- **RuboCop is source of truth** (`.rubocop.yml`): double quotes, LineLength 180, MethodLength 11.
+  RSpec: `expect` only. Test fixtures live in `spec/languages/`.
+- Pure file-in/string-out: no network, no threads.
+
+## Adding a language
+
+`.txt` file → `File` constant → CLI flag (if user-facing) → spec → README + CHANGELOG.
+The `lang-gen` skill automates this.
+
+## Knowledge bundle
+
+`.okf/` is an [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+bundle (markdown + YAML frontmatter) carrying the detail this file compresses: the
+syllable-file grammar, per-language bucket counts, CLI selection quirks, and the
+reasoning behind the conventions above. Start at `.okf/index.md`.
+
+- **Consult it** before changing the composition algorithm, the syllable format, or the CLI.
+- **Maintain it:** when a change invalidates a concept, update that file's body and
+  `timestamp`, then append a dated entry to `.okf/log.md`. The `okf` skill covers the flow.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    random_name_generator (4.0.4)
+    random_name_generator (4.0.5)
       slop (~> 4.10)
 
 GEM

data/README.md

@@ -150,9 +150,18 @@ call `$❯ rake reek`
 Bug reports and pull requests are welcome on GitHub at
 https://github.com/folkengine/random_name_generator.
 
+### Knowledge bundle
+
+This project uses the [`.okf/`](.okf/index.md) as an
+[Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+reference to how the code is structured. It documents the syllable file
+grammar, a catalog of every bundled language with its constant and flag,
+how composition and its failure modes work, and the reasoning behind
+conventions such as injected randomness.
+
 ## Skills
 
-This ships with a skill designed to work with [Claude Code](https://claude.com/claude-code) 
+Version 4.x of this library ships with a skill designed to work with [Claude Code](https://claude.com/claude-code) 
 and other LLMs under `.claude/skills/`.
 
 - [lang-gen](.claude/skills/lang-gen/SKILL.md): Generate a new random_name_generator language from a free-text theme (e.g. "german curse words"), assembles flagged pre/mid/sur syllable collections, registers the File constant, adds a smoke spec and README entry, and samples names to verify.
@@ -185,6 +194,14 @@ This will:
 6. Verify that all three buckets are non-empty, then sample
    composed names so you can eyeball the result.
 
+Here's a sample:
+
+```txt
+Parmaqo'ochu'
+Hiqejajvam
+Tiq'emey
+```
+
 The experimental [German Curse](lib/languages/experimental/german-curse.txt)
 language was generated this way.
 

data/lib/random_name_generator/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RandomNameGenerator
-  VERSION = "4.0.4"
+  VERSION = "4.0.5"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: random_name_generator
 version: !ruby/object:Gem::Version
-  version: 4.0.4
+  version: 4.0.5
 platform: ruby
 authors:
 - folkengine
@@ -38,12 +38,35 @@ files:
 - ".devcontainer/devcontainer.json"
 - ".github/workflows/ruby.yml"
 - ".gitignore"
+- ".okf/decisions/index.md"
+- ".okf/decisions/injected-randomness.md"
+- ".okf/decisions/ruby-3-4-minimum.md"
+- ".okf/decisions/slop-runtime-dependency.md"
+- ".okf/development/build-and-test.md"
+- ".okf/development/conventions.md"
+- ".okf/development/index.md"
+- ".okf/development/release.md"
+- ".okf/formats/index.md"
+- ".okf/formats/syllable-file-format.md"
+- ".okf/index.md"
+- ".okf/interfaces/cli.md"
+- ".okf/interfaces/index.md"
+- ".okf/languages/adding-a-language.md"
+- ".okf/languages/catalog.md"
+- ".okf/languages/index.md"
+- ".okf/library/generator.md"
+- ".okf/library/index.md"
+- ".okf/library/module.md"
+- ".okf/library/syllable.md"
+- ".okf/log.md"
+- ".okf/overview.md"
 - ".overcommit.yml"
 - ".rspec"
 - ".rubocop.yml"
 - ".tool-versions"
 - AI-BOM.md
 - CHANGELOG.md
+- CLAUDE.md
 - Gemfile
 - Gemfile.lock
 - LICENSE