random_name_generator 4.0.3 → 4.0.5

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.3)
+    random_name_generator (4.0.5)
       slop (~> 4.10)
 
 GEM

data/README.md

@@ -41,7 +41,7 @@ Or install it yourself as:
 generate a first and last name for you:
 
 ```shell
-$> exe/random_name_generator [-egrkfcxdß?]
+$> exe/random_name_generator [-egrkbfcxdß?]
 ```
 
 You can also install it so that it's instantly available to you:
@@ -59,8 +59,10 @@ RandomNameGenerator comes with several styles of syllable files:
 [Fantasy](https://github.com/folkengine/random_name_generator/blob/master/lib/languages/fantasy.txt),
 [Goblin](https://github.com/folkengine/random_name_generator/blob/master/lib/languages/goblin.txt),
 [Roman](https://github.com/folkengine/random_name_generator/blob/master/lib/languages/roman.txt),
+[Klingon](https://github.com/folkengine/random_name_generator/blob/master/lib/languages/klingon.txt),
+[Welsh](https://github.com/folkengine/random_name_generator/blob/master/lib/languages/welsh.txt),
 and
-[Klingon](https://github.com/folkengine/random_name_generator/blob/master/lib/languages/klingon.txt).
+[Belter](https://github.com/folkengine/random_name_generator/blob/master/lib/languages/belter.txt).
 By default it uses Fantasy. Instantiate RandomNameGenerator and then
 call compose on the object to generate a random name. If you don't pass
 in the number of syllables you want for your name to compose, it will
@@ -148,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.
@@ -183,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/exe/random_name_generator

@@ -12,6 +12,7 @@ opts = Slop.parse do |o|
   o.bool "-g", "--goblin", "Use Goblin syllable file"
   o.bool "-r", "--roman", "Use Roman syllable file"
   o.bool "-k", "--klingon", "Use Klingon syllable file"
+  o.bool "-b", "--belter", "Use Belter syllable file"
   o.bool "-f", "--flipmode", "Flip mode in effect"
   o.bool "-c", "--cyrillic", "Use Cyrillic mode"
   o.bool "-x", "--xrated", "Generate Curse words [NEEDS WORK]"
@@ -30,6 +31,7 @@ else
   lang = RandomNameGenerator::GOBLIN if opts.goblin?
   lang = RandomNameGenerator::ROMAN if opts.roman?
   lang = RandomNameGenerator::KLINGON if opts.klingon?
+  lang = RandomNameGenerator::BELTER if opts.belter?
   lang = RandomNameGenerator::CURSE if opts.xrated?
   lang = RandomNameGenerator::DEMONIC if opts.demonic?
   lang = RandomNameGenerator::GERMAN_CURSE if opts.german_curse?

data/lib/languages/belter.txt

@@ -0,0 +1,102 @@
+-bel
+-ber
+-bos
+-che
+-da +c
+-du
+-fel
+-gut
+-im
+-ka
+-kep
+-ko
+-kop
+-kow
+-mal
+-mi +c
+-nak
+-oye
+-pash
+-pel
+-pom
+-sa +c
+-sab
+-sha
+-shu
+-ta
+-teng
+-tich
+-to
+-tu
+-wel
+-xa
+-xi
+-ya +c
+-ze
+al
+ang
+at
+be
+da
+deng
+do
+eng
+ere -c
+ga
+im -c
+ka
+ken
+la
+lom
+low
+lu
+ma
+mang
+mi
+na
+nga
+ok
+ol
+pa
+ra
+sa
+se
+sha
+shi
+ta
+teng
+ti
+to
+tu
+un
+wa
+we
+xa
+ya
++a -c
++ang
++atna
++da
++deng
++eng -c
++im -c
++ing
++kang
++lowda
++mang
++na
++nya
++owda -c
++pa
++ra
++sa
++shang
++ta
++teng
++tim
++to
++tu
++wa
++wala
++xa
++ya