Merge 1.7.4 — Rounding Out the Sounds

Author: vladimir-ciroos

Book/CONLANG_DEVELOPMENT/CONLANG_DEVELOPMENT.pdf

@@ -12,6 +12,7 @@ Add `--help` to any command for its full signature.
 #section("Setup")
 
 / `init <name>`: Create a language sub-book with its five chapters.
+/ `scaffold --from "<description>" [--out F]`: (AI) Propose a starter phoneme inventory from a short description, as pasteable Phonology-chapter HJSON (preview-only).
 / `list`: List every defined language with summary counts.
 / `doctor <lang> [--json]`: A health check — phonotactic and lexical problems plus how much of your manuscript's language-words the lexicon already covers.
 
@@ -68,6 +69,7 @@ Add `--help` to any command for its full signature.
 
 / `metrics <lang> [--json]`: Quantitative sound-system metrics — phoneme entropy, the Zipf fit, phonotactic saturation, mora weight.
 / `naturalness <lang> [--json]`: Judge the phoneme inventory against cross-linguistic tendencies (voicing symmetry, place coverage, near-universals, size) into a 0–1 score.
+/ `suggest-phonemes <lang> [--json]`: Recommend phonemes that would round out the inventory (voiced counterparts, missing near-universals). Advisory.
 / `pairs <lang> [--limit N] [--json]`: Find minimal pairs and the distinctive feature each turns on — the functional load of your contrasts.
 / `harmony <lang> [--json]`: Detect vowel harmony (backness, rounding) by how consistently a word's vowels agree.
 / `distribution <lang> [--json]`: Where each phoneme appears (onset / nucleus / coda, word edges) and any restricted distributions.

Book/CONLANG_DEVELOPMENT/chapters/a-command-reference.typ

@@ -210,7 +210,7 @@
     #place(bottom + center, dy: -30mm, align(center)[
       #text(font: body_family, size: 10pt, fill: ink_smoke, book_author)
       #v(2mm)
-      #text(font: body_family, size: 9pt, fill: ink_smoke, book_year + " · examples assume Inkhaven 1.7.3 or newer")
+      #text(font: body_family, size: 9pt, fill: ink_smoke, book_year + " · examples assume Inkhaven 1.7.4 or newer")
     ])
   ]
   pagebreak()

Book/CONLANG_DEVELOPMENT/design.typ

@@ -1,6 +1,6 @@
 [package]
 name = "inkhaven"
-version = "1.7.3"
+version = "1.7.4"
 edition = "2024"
 # Rust 1.85 stabilised edition 2024. Bump alongside any toolchain-only
 # feature usage (let-else / chained-comparisons / etc. are already stable).

Cargo.lock

@@ -0,0 +1,45 @@
+# Inkhaven 1.7.4 — Rounding Out the Sounds
+
+_Two more phonology tools that go from analysis to advice: a recommender that
+tells you what your inventory is missing, and an AI scaffold that proposes a
+starter inventory from a description. This rounds out the linguistic layer's
+phonology work. No new runtime crates._
+
+## What is your inventory missing?
+
+`naturalness` (1.7.1) tells you where your inventory has gaps. `suggest-phonemes`
+tells you what would fill them:
+
+```sh
+inkhaven language suggest-phonemes Eldar
+```
+
+Through the distinctive-feature matrix it recommends the **voiced counterpart**
+missing beside a voiceless obstruent (a `/ɡ/` for your `/k/`), and any
+**near-universal segment** the inventory lacks. Every suggestion is advisory — a
+"you could add this" — and changes nothing.
+
+## A starter inventory from a description
+
+Beginning a language from a blank page is the hardest part. `scaffold` gives you
+somewhere to start:
+
+```sh
+inkhaven language scaffold --from "a flowing, vowel-rich island language"
+```
+
+The model proposes a coherent starter phoneme inventory and a few syllable
+templates, which Inkhaven **validates by parsing it back** (so it never emits
+something malformed) and prints as pasteable Phonology-chapter HJSON. It is
+preview-only: create a language with `inkhaven language init <name>` and drop the
+block into its Phonology chapter. `--out` writes it to a file.
+
+## Dependencies & compatibility
+
+**No new runtime crates.** Everything is additive — two new `language`
+subcommands (`suggest-phonemes`, `scaffold`); existing projects and languages are
+unchanged. The companion book's command reference is updated to match.
+Warning-free (binary and tests). Test suite → 2514.
+
+Every prior release lives under
+[`Documentation/RELEASE_NOTES/`](.).

Cargo.toml

@@ -21,34 +21,34 @@ one HJSON line away.
 
 ![Inkhaven screenshot](screen.png)
 
-## Latest release · 1.7.3 — The Analyst's Bench
+## Latest release · 1.7.4 — Rounding Out the Sounds
 
-Read the full notes: [`Documentation/RELEASE_NOTES/1.7.3.md`](Documentation/RELEASE_NOTES/1.7.3.md)
+Read the full notes: [`Documentation/RELEASE_NOTES/1.7.4.md`](Documentation/RELEASE_NOTES/1.7.4.md)
 
-Three more read-only analyses round out the phonology bench, plus a one-page grammar
-sketch that gathers the whole suite into a single readable overview. **No new runtime
-crates.** Test suite → 2511, warning-free.
+Two more phonology tools that go from analysis to advice: a recommender for what your
+inventory is missing, and an AI scaffold that proposes a starter inventory from a
+description. **No new runtime crates.** Test suite → 2514, warning-free.
 
-### Vowel harmony & positional distribution
+### What is your inventory missing?
 
-`inkhaven language harmony <lang>` measures how consistently a word's vowels agree on
-backness and rounding — a *strong*/*tendency*/*none* verdict for vowel harmony.
-`inkhaven language distribution <lang>` reports *where* each phoneme appears (onset /
-nucleus / coda, word edges) and surfaces **restricted distributions** — the consonant
-confined to codas, or barred from a word edge.
+`inkhaven language suggest-phonemes <lang>` recommends the phonemes that would round out
+the inventory — the voiced counterpart missing beside a voiceless obstruent, a
+near-universal segment the inventory lacks — via the distinctive-feature matrix. Advisory;
+changes nothing.
 
-### A one-page sketch
+### A starter inventory from a description
 
-`inkhaven language sketch <lang>` assembles the phonology, typology and lexicon analyses
-into three short prose paragraphs — the analysis dashboard as a page you can read.
-Deterministic, needs no provider, always current; `--out` writes it to a file.
+`inkhaven language scaffold --from "a flowing, vowel-rich island language"` asks the model
+for a coherent starter phoneme inventory and syllable templates, **validates it by parsing
+it back**, and prints it as pasteable Phonology-chapter HJSON. Preview-only — a place to
+start a new language from a blank page.
 
 ### Dependencies & compatibility
 
-**No new runtime crates.** Everything is additive — three new `language` subcommands
-(`harmony`, `distribution`, `sketch`); existing projects and languages are unchanged. The
+**No new runtime crates.** Everything is additive — two new `language` subcommands
+(`suggest-phonemes`, `scaffold`); existing projects and languages are unchanged. The
 companion book's command reference is updated to match. Warning-free (binary and tests).
-Test suite → 2511.
+Test suite → 2514.
 
 Every prior release lives under
 [`Documentation/RELEASE_NOTES/`](Documentation/RELEASE_NOTES/).

Documentation/RELEASE_NOTES/1.7.4.md

@@ -223,6 +223,37 @@ fn print_harmony(language: &str, r: &HarmonyReport) {
     }
 }
 
+/// LING-1 Wave-2 — `inkhaven language suggest-phonemes <lang>`: recommend
+/// phonemes that would round out the inventory (voiced counterparts, missing
+/// near-universals), via the feature matrix. Advisory; changes nothing.
+pub(crate) fn suggest_phonemes(project: &Path, language: &str, json: bool) -> Result<()> {
+    let (store, hierarchy, lang_book) = open_lang_book(project, language)?;
+    let phon = load_phonology(&store, &hierarchy, &lang_book)?.unwrap_or_default();
+    let report = crate::conlang::suggest::suggest(&phon);
+
+    if json {
+        println!(
+            "{}",
+            serde_json::to_string_pretty(&report)
+                .map_err(|e| Error::Store(format!("serializing suggestions: {e}")))?
+        );
+        return Ok(());
+    }
+
+    println!("phoneme suggestions · {language}");
+    if report.phoneme_count == 0 {
+        println!("  (no phoneme inventory — define one in the Phonology chapter)");
+    } else if report.suggestions.is_empty() {
+        println!("  the inventory is well-rounded — nothing obvious to add.");
+    } else {
+        for s in &report.suggestions {
+            println!("      + /{}/  — {}", s.ipa, s.reason);
+        }
+        println!("  (advisory — add any you like in the Phonology chapter; nothing changed.)");
+    }
+    Ok(())
+}
+
 /// LING-1 L-P4 — `inkhaven language sketch <lang>`: a one-page, deterministic
 /// overview of the language, assembling the whole analysis suite into prose.
 pub(crate) fn sketch(project: &Path, language: &str, out: Option<&str>) -> Result<()> {

README.md

@@ -191,6 +191,12 @@ pub fn run(project: &Path, cmd: LanguageCommand) -> Result<()> {
             distribution(project, &language, json)
         }
         LanguageCommand::Sketch { language, out } => sketch(project, &language, out.as_deref()),
+        LanguageCommand::SuggestPhonemes { language, json } => {
+            suggest_phonemes(project, &language, json)
+        }
+        LanguageCommand::Scaffold { from, out, provider } => {
+            scaffold_from(project, &from, out.as_deref(), provider.as_deref())
+        }
         LanguageCommand::Trace { language, rule, limit, json } => {
             trace(project, &language, &rule, limit, json)
         }

src/cli/language/metrics.rs

@@ -8,6 +8,66 @@ use crate::error::{Error, Result};
 
 use super::*;
 
+const SCAFFOLD_SYSTEM: &str = "You are a phonologist scaffolding a starter phoneme inventory for a \
+constructed language from a short description. Output ONLY a single HJSON block in EXACTLY this shape, \
+no prose before or after:\n\
+{\n  phonemes: [\n    { ipa: \"p\", kind: \"consonant\" }\n    { ipa: \"a\", kind: \"vowel\" }\n  ]\n  \
+classes: { C: [\"p\", \"t\", \"k\"], V: [\"a\", \"i\", \"u\"] }\n  templates: [ { role: \"root\", pattern: \"CVCV\" } ]\n}\n\
+Use only standard IPA symbols in the `ipa` fields. Choose an inventory (roughly 12–28 phonemes) and a few \
+syllable templates that fit the described character. Keep it coherent and typologically plausible.";
+
+/// LING-1 L-P4 — `inkhaven language scaffold --from "<description>"`: AI-propose a
+/// starter phoneme inventory (as pasteable Phonology-chapter HJSON) from a short
+/// description. Preview-only: it prints (or writes with `--out`) a validated
+/// block; it never touches an existing language.
+pub(crate) fn scaffold_from(
+    project: &Path,
+    description: &str,
+    out: Option<&str>,
+    provider: Option<&str>,
+) -> Result<()> {
+    let layout = ProjectLayout::new(project);
+    layout.require_initialized()?;
+    let cfg = Config::load_layered(&layout.config_path())?;
+    let ai = crate::ai::AiClient::from_config(&cfg.llm)?;
+    let (model, _env) = ai.resolve_provider(&cfg.llm, provider)?;
+    eprintln!("inkhaven language scaffold · model: {model}");
+
+    let raw = crate::ai::stream::collect_blocking(
+        ai.client.clone(),
+        model.to_string(),
+        Some(SCAFFOLD_SYSTEM.to_string()),
+        format!("Description: {description}"),
+    )
+    .map_err(Error::Config)?;
+
+    // Validate: the proposal must parse as a Phonology, or we don't emit garbage.
+    let phon = crate::conlang::Phonology::from_hjson(&raw)
+        .map_err(|e| Error::Config(format!("the model's proposal did not parse: {e}")))?
+        .ok_or_else(|| Error::Config("the model produced an empty inventory".to_string()))?;
+
+    let block = crate::language_entry::extract_hjson_block(&raw).unwrap_or(raw.trim()).trim();
+    match out {
+        Some(path) => {
+            crate::io_atomic::write(Path::new(path), format!("{block}\n").as_bytes())
+                .map_err(|e| Error::Config(format!("write {path}: {e}")))?;
+            eprintln!(
+                "wrote a {}-phoneme starter inventory to {path}",
+                phon.phonemes.len()
+            );
+        }
+        None => {
+            eprintln!(
+                "proposed a {}-phoneme inventory — create a language with `inkhaven language init \
+                 <name>` and paste this into its Phonology chapter:\n",
+                phon.phonemes.len()
+            );
+            println!("{block}");
+        }
+    }
+    Ok(())
+}
+
 /// Open a project and resolve a language sub-book under the `Language`
 /// system book. The shared front-half of every conlang command — returns the
 /// open `Store` (kept alive for the DuckDB lock), the loaded `Hierarchy`, and