random_name_generator 4.0.3 → 4.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7374613642f2111c5c4f4cff427d6ee2c88a99cacc5d4755b2eed1584c293b7
-  data.tar.gz: 78e17730bcaa7e74632f7c2063caeb0f4b31cc7f8de61435ca872969dede788c
+  metadata.gz: 0a9a162ecd9a8953ea3383bc847dcc18a8a61506b5802ea4cd8f94daeaaf5f9b
+  data.tar.gz: 746bcfeb89b0506e7cb7f03e92f6805efc9d2493fd603bd46b363f24888089f0
 SHA512:
-  metadata.gz: 409911e7d194ebabe10d1d88d44df023a6025092100885db770742f0f4a1b1fe3a538a37f67a20fb966a67f7d415c5d541311c232ab981bed751c387f4e7b231
-  data.tar.gz: b60b0794a0fb21bfd45c3b641bc16a9a5f38fe9d105a86ca73e63ad80a6e130376ad377a124b76df5d148037b9503a963caafbbe143150c511c377da3e834add
+  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.