conlanggen 0.4.2__tar.gz

conlanggen-0.4.2/.gitattributes

@@ -0,0 +1,6 @@
+# Normalise line endings in the repository so checksums match across platforms.
+* text=auto eol=lf
+
+*.png binary
+*.jpg binary
+*.pdf binary

conlanggen-0.4.2/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: ci
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  test:
+    # Reproducibility is a hard invariant and the bytes on disk are the artifact
+    # users get, so the suite runs on more than the author's platform. A passing
+    # Linux-only run would not catch a platform-dependent newline or path.
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Type-check
+        run: mypy src
+      - name: Test
+        run: pytest
+      - name: Build (sdist is platform-independent)
+        # Built on one platform only: the sdist and wheel must not vary by runner,
+        # so building per-matrix would create artifacts that differ for no reason.
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        with:
+          name: dist
+          path: dist/

conlanggen-0.4.2/.github/workflows/release.yml

@@ -0,0 +1,89 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    # A release is gated on the full matrix, not just the version being cut.
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Type-check
+        run: mypy src
+      - name: Test
+        run: pytest
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      # Job-level `permissions` *replace* the workflow-level ones (unspecified
+      # scopes become `none`), so `contents: read` must be listed here too or
+      # actions/checkout in this job cannot read the repo.
+      contents: read
+      # Required for OIDC trusted publishing: no API token is stored anywhere.
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Check tag matches project version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version="$(python -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text(encoding='utf-8'))['project']['version'])")"
+          if [ "$tag" != "$version" ]; then
+            echo "tag $tag does not match project version $version" >&2
+            exit 1
+          fi
+          echo "publishing $version"
+
+      - name: Build
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Show OIDC token claims (debug)
+        continue-on-error: true
+        run: |
+          python - <<'PY'
+          import base64, json, os, urllib.request
+          url = os.environ["ACTIONS_ID_TOKEN_REQUEST_URL"] + "&audience=pypi"
+          req = urllib.request.Request(
+              url,
+              headers={"Authorization": "bearer " + os.environ["ACTIONS_ID_TOKEN_REQUEST_TOKEN"]},
+          )
+          token = json.load(urllib.request.urlopen(req))["value"]
+          payload = token.split(".")[1]
+          payload += "=" * (-len(payload) % 4)
+          print(json.dumps(json.loads(base64.urlsafe_b64decode(payload)), indent=2))
+          PY
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

conlanggen-0.4.2/.gitignore

@@ -0,0 +1,22 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual environments
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+coverage.xml
+.coverage
+
+# Generated output
+out/
+*.local.yaml

conlanggen-0.4.2/.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.11.2
+    hooks:
+      - id: mypy
+        additional_dependencies: ["pydantic>=2.7", "pyyaml>=6", "types-PyYAML>=6"]

conlanggen-0.4.2/CONTEXT.md

@@ -0,0 +1,67 @@
+# CONTEXT — domain model and vocabulary
+
+Shared language for this project. Update it when terminology shifts; the terms
+here are load-bearing in code, specs, and issues.
+
+## Core objects
+
+| Term | Definition |
+| --- | --- |
+| **Spec** | What the user writes (`spec/*.yaml`). Partial by design; omitted fields are sampled. |
+| **Model** | The canonical JSON (`Language`) produced by a run. Single source of truth; every view is rendered from it. |
+| **Lexeme** | A dictionary entry: id, gloss, part of speech, and a **root**. |
+| **Root** | The bare, citation form of a lexeme. |
+| **Affix** | A generated prefix/suffix with a gloss (e.g. `PL`) and the parts of speech it applies to. |
+| **Allomorph** | A conditioned surface form of an affix, used when the primary form would be illegal in context. |
+| **Adposition** | A generated, invariable word (pos `adp`) for a place/direction relation (`in`, `above`, `toward`…). Its order is fixed by word order: pre- for VO, post- for OV. |
+| **Oblique** | An optional clause adjunct: an adposition plus a bare noun, appended after the object. |
+| **Noun phrase** | A head noun plus optional modifiers (adjectives, possessor, apposition, an adpositional phrase), built on demand. Modifiers sit on the head's side, fixed by head direction. |
+| **Clause** | A predicate with its arguments, linearised on demand: **transitive** (subject + object) or **intransitive** (one argument, which takes the alignment's intransitive case: `NOM` if accusative, `ABS` if ergative). |
+| **Copula** | A generated `be` word (pos `cop`) that predicates a complement. It draws verb morphology (past/future, agreement) by sharing the verb classes, but is not a content verb. |
+| **Predication** | A copular clause: subject + copula + a bare predicative complement (adjective or noun). Existential *there is* is paraphrased as this shape plus a locative oblique. |
+| **Aspect** | A verb category stacked with tense: **progressive** and **perfect** affixes. Pluperfect is `past + perfect`; "had been …-ing" is `past + perfect + progressive`. |
+| **Conjunction** | A generated, invariable connective (`and`, `but`, `then`, `so`; pos `conj`) that joins clauses. |
+| **Sentence** | Two or more clauses joined by **parataxis** (juxtaposition) or a conjunction; relatives and reported speech ride on parataxis. Built on demand, not stored. |
+| **WordRecord** | A surface form plus its morphemes, syllables, and tags (`CIT`, `PL`). |
+| **Origin** | Where a value came from: `specified`, `sampled`, or `derived`. |
+| **Lock** | An entry the user pinned. Locked entries survive re-sampling. |
+| **Seed** | Integer driving all sampling. Same spec + seed ⇒ identical bytes. |
+
+## Phonology
+
+| Term | Definition |
+| --- | --- |
+| **Inventory** | The consonants and vowels a language uses. Symbols are user-facing; v1 has no feature layer beneath them. A spec may declare the inventory phonemic (`ipa: true`), in which case each symbol is an IPA phoneme. |
+| **Orthography** | The romanised spelling derived from an IPA inventory (symbol → spelling). A *view* of the phonemic form, stored on the inventory and on each lexeme/word; absence means the symbol spells itself. |
+| **Syllable template** | A shape over `C` and `V` slots, e.g. `CVC`, with a sampling weight. |
+| **Phonotactics** | The legality rules: a word is legal iff its `C`/`V` skeleton can be partitioned into the templates with allowed onsets/codas. Constraints bind *during* the search, so the verdict never depends on which partition is found first. |
+| **Segment** | One inventory symbol, possibly multi-character (`sh`, `ch`). |
+
+## Process
+
+| Term | Definition |
+| --- | --- |
+| **Generate** | `spec → model`. Samples the gaps, assigns stable per-item seeds, assembles word forms. |
+| **Stable per-item seeding** | Each item hashes its own label into its RNG, so generating one extra word never reshuffles the others. |
+| **Lint** | Machine-checkable invariants run after generation. Errors mark a model `invalid`; warnings do not. |
+| **Render** | Model → Markdown dictionary + grammar sketch. Never hand-maintained. |
+| **Bench** | Adapter + plausibility scorecard against the real Kah dictionary. Reported, never a pass/fail gate. |
+| **Lineage** | Proto-language/rule hooks carried in the schema for phase-2 diachrony. |
+
+## Translation pipeline
+
+| Term | Definition |
+| --- | --- |
+| **Pipeline command** | One of `conlang new` / `grow` / `translate` / `validate-translation` / `extras` — the repeatable way to build a generated language and translate the fixed story into it. |
+| **Workspace** | The standard home of a generated language: `MISSION`/`NOTES`/`README`/`RESOURCES`, `spec/`, `out/`, `reference/`, `learning-records/`, and the bundled story. One per language. |
+| **Composer** | The library object (`conlang.Composer`) that realises a token (`gloss.TAG…`) as a surface word the model licenses, and reads a surface back to its gloss. |
+| **Gloss script** | A hand-authored TSV (`index<TAB>gloss`) that `translate` composes into a translation. |
+| **Port** | Re-composing a translation from a sibling language's gloss column instead of writing a gloss script. |
+| **Portability** | The grammar-match check that decides port vs hand-translate: alignment + word order (adposition/modifier order asserted) and the source's tag vocabulary present in the target. |
+
+## Non-negotiable invariants
+
+1. **Reproducibility is hard.** Same spec + seed produces byte-identical output.
+2. **The model is the source of truth.** Views are derived; never edit a view.
+3. **Lint never crashes a run.** Broken languages are generated and reported.
+4. **Kah data stays out of the repo.** The benchmark reads a local cache at runtime.

conlanggen-0.4.2/LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2026 Brian McKeen
+
+Contact: bmckeen1919@gmail.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Note on third-party data: this project does not include the Kwesho Kah
+dictionary or grammar, which are the copyrighted work of Kwesho. The Kah
+benchmark reads them from a local cache at runtime and they are not distributed
+here. See README.md.

conlanggen-0.4.2/PKG-INFO

@@ -0,0 +1,377 @@
+Metadata-Version: 2.5
+Name: conlanggen
+Version: 0.4.2
+Summary: A partial-spec conlang generator: specify what you care about, sample the rest.
+Project-URL: Homepage, https://github.com/bmckeen1919-lab/conlanggen
+Project-URL: Repository, https://github.com/bmckeen1919-lab/conlanggen
+Project-URL: Issues, https://github.com/bmckeen1919-lab/conlanggen/issues
+Author: Brian McKeen
+License: MIT License
+        
+        Copyright (c) 2026 Brian McKeen
+        
+        Contact: bmckeen1919@gmail.com
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+        ---
+        
+        Note on third-party data: this project does not include the Kwesho Kah
+        dictionary or grammar, which are the copyrighted work of Kwesho. The Kah
+        benchmark reads them from a local cache at runtime and they are not distributed
+        here. See README.md.
+License-File: LICENSE
+Keywords: conlang,linguistics,procedural-generation,worldbuilding
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-pyyaml>=6; extra == 'dev'
+Provides-Extra: phoible
+Provides-Extra: wals
+Description-Content-Type: text/markdown
+
+# conlang
+
+A partial-spec constructed-language generator.
+
+You describe only what you care about — phonology, syllable shapes, a handful of
+words — and the generator **samples the rest** from typologically-plausible
+defaults. Same spec plus same seed always produces byte-identical output, and
+sampled entries can be locked so they survive re-sampling.
+
+```text
+spec (YAML) ──▶ generate ──▶ model (canonical JSON) ──▶ render ──▶ dictionary + grammar sketch
+                                   │
+                                   ├── lint   (machine-checkable invariants)
+                                   └── bench  (plausibility scorecard vs. Kah)
+```
+
+The model JSON is the single source of truth; the dictionary, grammar sketch,
+and any future views are rendered from it.
+
+## Install
+
+```powershell
+pip install conlanggen
+```
+
+The distribution is `conlanggen`, but the import package and the command are both
+`conlang` — `import conlang`, `conlang generate`.
+
+## Quickstart
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
+
+# Generate from the example spec, and render a Markdown dictionary.
+.\.venv\Scripts\python.exe -m conlang.cli generate --spec spec\example.yaml --render
+
+# Happy with it? Freeze it into an explicit spec so the values stick.
+conlang accept --model out\veshtari.json
+```
+
+Output lands in `out/`: a model JSON and a rendered `.md`.
+
+```powershell
+# Re-lint or re-render an existing model.
+conlang lint --model out\veshtari.json
+conlang render --model out\veshtari.json --out out\veshtari.md
+```
+
+## Translating a fixed story
+
+The toolkit ships a repeatable pipeline for translating the fixed 111-sentence
+story *The Quiet Morning* into a **generated** language: `conlang new` → `grow` →
+`translate` → `validate-translation` → `extras`. The runbook is
+[`docs/pipeline.md`](docs/pipeline.md).
+
+## Writing a spec
+
+Everything is optional. Omitted fields are sampled.
+
+```yaml
+name: Veshtari
+seed: 42
+
+phonology:
+  consonants: [p, t, k, m, n, s, l, r, v, sh, ch]
+  vowels: [a, e, i, o, u]
+
+syllables: [CV, CVC, V]   # C = consonant slot, V = vowel slot
+word_count: 150
+
+lexicon:                  # pin specific words; they are locked by default
+  - gloss: water
+    root: vela
+```
+
+Accepted keys: `name`, `seed`, `phonology.{consonants,vowels,ipa,orthography}`,
+`syllables`, `concepts`, `word_count`, `lexicon`, `affixes`, `onsets`, `codas`,
+`forbidden`.
+
+An explicit, unsized `lexicon` is treated as the complete word list (that is
+what `accept` writes back); otherwise the built-in concept list is used and
+`word_count` trims or extends it.
+
+If your `syllables` include `CCV`/`CCVC`, the generator samples a legal onset
+set unless you supply `onsets` yourself, and `accept` records whichever was
+used so a frozen spec regenerates identically.
+
+### IPA inventories
+
+By default a symbol *is* its spelling (`sh` is written `sh`). Set
+`phonology.ipa: true` to declare the inventory phonemic: each symbol is an IPA
+phoneme, and the tool derives a romanised **orthography** for the dictionary.
+
+```yaml
+name: Shibo
+seed: 11
+
+phonology:
+  ipa: true
+  consonants: [p, t, k, ʃ, tʃ, m, n, s, l]
+  vowels: [a, e, i, o, u]
+  orthography:        # optional; corrects or extends the built-in defaults
+    tʃ: ch
+    ʃ: sh
+```
+
+`/ʃ/` spells `sh` and `/tʃ/` spells `ch` from a built-in table; anything absent
+spells itself, so a plain Latin inventory is unchanged. `orthography` overrides
+the table (set an entry back to its own symbol to cancel a default), and the
+resolved map is stored on the inventory. The dictionary and word-form tables
+then show a `spelling` column beside the `ipa` one, and `accept` writes the map
+back so a frozen spec regenerates identically. Lint warns on a map entry that is
+not an inventory symbol, or two symbols that would spell the same thing.
+
+## Freezing a language (`accept`)
+
+A partial spec samples whatever you leave out. Once you like the result,
+`conlang accept` writes it back as a **fully-explicit spec**: the phonology,
+syllable shapes, constraints, affixes, and every root become pinned entries.
+Regenerating from that spec reproduces the same language exactly — sampled
+values now survive re-sampling, and changing the seed can no longer disturb
+them.
+
+```powershell
+conlang generate --spec spec\example.yaml --out out\veshtari.json
+conlang accept  --model out\veshtari.json --out spec/veshtari.yaml
+conlang generate --spec spec/veshtari.yaml --out out/veshtari.json
+```
+
+Two fields legitimately change across the round trip: `origin` becomes
+`specified` for every accepted entry (it is pinned now, not sampled), and
+`spec_hash` changes because the spec text is different. Everything linguistic
+is identical, and `tests/test_invariants.py` asserts exactly that.
+
+## Guarantees and lint rules
+
+Reproducibility is the one **hard** guarantee: `spec + seed ⇒ identical bytes`.
+Everything else is reported by `lint` as errors or warnings, and a broken
+language is still generated (conlangers want to explore broken states).
+
+| rule | severity | meaning |
+| --- | --- | --- |
+| `schema` | error/warning | schema version present and known |
+| `lexeme.root` | error | lexeme has a non-empty root |
+| `phonotactics.lexeme` | error | every root is a legal word |
+| `phonotactics.word` | error | every inflected form is a legal word |
+| `lexicon.homophones` | warning | two roots collide (Kah has polysemy too) |
+| `morphology.paradigm` | warning | a word is missing a form for a category its class realises |
+| `morphology.class` | error | a word names an inflection class the language does not define |
+| `lexicon.nonempty` | warning | the lexicon is empty |
+| `orthography.unknown` | warning | the spelling map names a symbol that is not in the inventory |
+| `orthography.collision` | warning | two symbols would spell the same thing |
+
+Every rule above has a test in `tests/test_lint.py`, `tests/test_lint_invariants.py`,
+or `tests/test_morphology.py`.
+
+## Phonotactics
+
+A word is legal when its `C`/`V` skeleton can be partitioned into the language's
+syllable templates **and** every resulting onset and coda is allowed. Two details
+matter more than they look:
+
+- **Constraints are checked while syllabifying, not after.** A word often has
+  several valid partitions; `deplango` is `de|plan|go` with legal onsets, and
+  also `de|pla|ngo` with an illegal one. Verdict must depend on the phonology,
+  not on which partition the search happens to return first.
+- **Onsets and codas are compared by segment, not by string.** An onset of
+  `ny` + `m` renders as `"nym"` — three characters, two segments. Matching
+  strings would silently reject legal words in any language with a digraph.
+
+When a template set admits onset clusters (`CCV`, `CCVC`), the generator samples
+a legal onset set and **builds roots from it**, so generated words are legal by
+construction rather than by luck. `constraints.onsets` in the model records what
+was sampled; an explicit `onsets` in the spec always wins.
+
+Affixes carry **allomorphs**: conditioned surface forms. A single form cannot
+serve both consonant-final and vowel-final roots, because the root's coda plus a
+consonant-initial affix resyllabify into an onset cluster. When the primary form
+would be illegal, `build_words` uses the first alternative that is legal — which
+is what real languages do. It is a rare fallback (~2 in 8,500 affixed forms), but
+without it those words would be illegal and lint would fail the language.
+
+## The Kah benchmark
+
+Kah (Kwesho's language) is hand-made, so the benchmark does **not** try to
+regenerate it. It does two things:
+
+1. **Adapter fixture** — parses the real Kwesho dictionary cache into the model
+   schema, proving the schema can represent real data.
+2. **Plausibility scorecard** — compares a generated language against Kah.
+
+The scorecard deliberately reports **three separate numbers**, because a word can
+fail for two unrelated reasons and collapsing them makes the report unreadable:
+
+| metric | question |
+| --- | --- |
+| symbol coverage | which Kah sounds does this language have? |
+| usable sounds | how many Kah headwords use only sounds this language has? |
+| legal shapes | of those, how many fit the phonotactics? |
+
+Scoring the built-in `kah` preset against Kah is circular, so the report says so
+explicitly when it detects it. Treat the scorecard as a lever, not a target: the
+presets are deliberately small, and a language that only allows `CV` syllables is
+a legitimate (if monotonous) language type, not a bug to tune away.
+
+```powershell
+conlang bench --spec spec\example.yaml
+# or point at a cache explicitly:
+conlang bench --spec spec\example.yaml --kah C:\path\to\kah-lexicon.txt
+```
+
+Kah's dictionary is Kwesho's copyrighted work and is **never** vendored into this
+repository. Without `--kah`, the benchmark looks for the glossary at a per-user
+cache path (`%LOCALAPPDATA%\conlang\kah-lexicon.txt` on Windows,
+`~/.cache/conlang/kah-lexicon.txt` elsewhere, or `$XDG_CACHE_HOME/conlang/`);
+override it with `--kah` or `CONLANG_KAH_LEXICON`.
+
+On the reference machine, the adapter parses **8,153** entries with a **97.8%**
+validity rate.
+
+## Evolving a language
+
+A generated model can be the parent of a daughter, evolved by ordered sound
+changes. A rule is `old > new` (`new` empty deletes the segment), optionally
+conditioned by an environment after `/`. The environment names the context on
+each side of the target, with `_` marking the target slot, `#` the word boundary,
+and `V`/`C` the vowel/consonant classes:
+
+```powershell
+conlang generate --spec spec\example.yaml --out out\proto.json
+conlang evolve --model out\proto.json --rule "a > e" --rule "p > f / V_V" --out out\daughter.json
+conlang evolve --model out\proto.json --rule "t > d / #_" --rule "s > z / V_" --out out\voiced.json
+```
+
+`V_V` is "between vowels", `#_` is word-initial, `_#` is word-final. Rules are
+applied left to right so a later rule sees an earlier one's output (feeding).
+
+The daughter is a full model: its inventory gains any new sounds, its lexicon
+and affixes are rewritten, and its word forms are rebuilt. It records where it
+came from in `lineage`:
+
+```json
+"lineage": { "parent": "proto", "rules": ["a > e", "p > f / V_V"] }
+```
+
+That is the whole point of the field: the derivation is data, so a daughter can
+itself be evolved, and `accept` keeps the chain across a round trip. Mergers
+introduced by a change show up as `lexicon.homophones` warnings, never errors.
+
+## Syntax
+
+Each language samples a constituent order (`SOV`, `SVO`, or `VSO`, weighted
+toward the first two) and an alignment (`accusative` or `ergative`). Both are
+recorded in the model and survive `accept`. A transitive clause is linearised
+from the lexicon and inflected: the subject and object take case by alignment
+(accusative marks `NOM`/`ACC`; ergative marks `ERG`/`ABS`) and the verb agrees
+with the subject:
+
+```python
+from conlang.syntax import sample_clause
+words, gloss = sample_clause(language)
+# e.g. (['pyople', 'klavragprekbra', 'blonyto'], 'water.ERG say.3SG fire.ABS')
+```
+
+Case and agreement are applied when the clause is built, not woven into every
+word's standing paradigm — a deliberate split, so a noun's form count does not
+double again for case.
+
+## Layout
+
+```text
+src/conlang/
+  model/        canonical pydantic schema (the source of truth)
+  sampling/     deterministic RNG, inventory presets, concepts, defaults
+  phonology/    tokenization, syllabification, legality checks
+  lexicon/      seeded root generation, stable per-item seeding
+  morphology/   affixes, inflection classes, and word-form assembly
+  soundchange/  ordered sound changes; derive a daughter language
+  syntax/       word order, alignment, simple clause linearisation
+  render/       Markdown dictionary + grammar sketch
+  lint/         machine-checkable invariants
+  bench/        Kah adapter + scorecard
+  cli.py        thin command-line view over the library
+```
+
+## Development
+
+```powershell
+.\.venv\Scripts\python.exe -m pytest
+.\.venv\Scripts\python.exe -m ruff check .
+.\.venv\Scripts\python.exe -m mypy src
+```
+
+## Roadmap
+
+Shipped so far:
+
+- **Phonology** — inventory, phonotactics, seeded word generation.
+- **IPA inventories** — declare the inventory phonemic (`ipa: true`) and the tool
+  derives a romanised orthography alongside the phonemic forms.
+- **Morphology** — affix breadth, inflection classes, and stacking (a word can
+  carry several categories at once).
+- **Diachrony** — `conlang evolve`: ordered sound changes derive a daughter
+  language, now with **environments** (`p > f / V_V`, `#`, `_`), and the chain
+  recorded in `lineage`.
+- **Syntax** — sampled word order and alignment, case marking with subject
+  agreement, the **predication tier** (adpositions, noun phrases, intransitives,
+  copula/existential), **clause sequencing** (parataxis and conjunctions), and
+  **aspect** (progressive/perfect, stacking with tense).
+- **Translation pipeline** — `conlang new` / `grow` / `translate` /
+  `validate-translation` / `extras`: build a generated language and translate the
+  fixed story into it, including a grammar-match **port** from a sibling language.
+
+Next:
+
+- Optional data packs: PHOIBLE (inventories) and WALS (typology) as CC-BY
+  adapters behind the built-in defaults.
+- Semantics/pragmatics and writing systems (deferred from v1).
+
+## License
+
+MIT (code). Kah dictionary and grammar content remains Kwesho's and is not part
+of this repository.