vll-config

Run the Vibe Language Learning configuration wizard. Use AskUserQuestion when available (Claude Code); fall back to plain prose questions otherwise.

This wizard has TWO phases. Phase 1 (basic) is required. Phase 2 (advanced) is offered at the end and is optional.

============================================================ PHASE 1 — BASIC WIZARD

Q1. Target language (single select; "Other" free-form is auto-added on Claude Code AskUserQuestion, otherwise prompt for it explicitly):

• Mandarin Chinese
• Japanese
• Korean
• Spanish
• French

After Q1, compute the language slug (lowercase, spaces → hyphens; e.g. "Mandarin Chinese" → "mandarin-chinese", "Japanese" → "japanese", "Korean" → "korean"). Check if flows/<slug>.md exists in this plugin.

If flows/<slug>.md exists: READ the file and follow its instructions for the script question, the transliteration question, and any extra language-specific questions. The language flow file fully owns the language-specific portion of the wizard — do NOT also ask the inline default questions below for that language. After the flow finishes, continue with Q4 (level) and Q5 (on-by-default).

If no flow file exists, use the smart-default branch below for Q2 and Q3 — do NOT ask boilerplate questions when the answer is obvious. Then continue with Q4 and Q5.

Q2 + Q3 (smart default — script + transliteration). Only used when no flow file exists:

Use your knowledge of the chosen language to answer these two questions correctly. The rule is:

• If you are 100% certain of the right answer based on the language alone, set the field silently and do NOT ask the user. Examples:

  • Spanish → script: "Latin", transliteration: false. Ask nothing.
  • French → script: "Latin", transliteration: false. Ask nothing.
  • Italian, German, Portuguese, Dutch, etc. → same; Latin script, no transliteration. Ask nothing.

• If there is any uncertainty — multiple plausible scripts, multiple common transliteration systems, regional variants, or you're not confident the language has a single dominant convention — ask the user. When you ask, use AskUserQuestion (Claude Code) or plain prose elsewhere, and always include an Other free-form option in addition to the concrete choices you list. Examples of cases where you should ask:

  • Vietnamese → Latin with diacritics is standard, but some learners want a transliteration. Ask, give realistic options, include Other.
  • Arabic → multiple transliteration systems (ALA-LC, IJMES, DIN 31635, etc.) and some learners prefer none. Ask script (Arabic vs others), ask transliteration with multiple choices + Other.
  • Hindi → Devanagari is dominant, but multiple transliteration schemes exist (IAST, Hunterian, ITRANS). Ask transliteration with options + Other.
  • A free-form "Other" language the user typed that you don't recognize → ask both script and transliteration, include Other on each.

When asking, make the option labels descriptive and include the most common choices for that language. Save the user's answer to script (free-form string) and transliteration + transliterationName (when applicable). For "no transliteration," save transliteration: false and omit transliterationName.

If unsure whether you're certain, default to asking. Better to confirm than to silently pick wrong.

Q4. Base level (single select):

• beginner | novice | intermediate | advanced | native

Q5. On by default? (yes/no): if yes, every new Claude Code session auto-activates VLL; if no, the user runs /vll on per session.

After Phase 1, compute the per-level defaults:

Level	transliterationDensity	glossDensity	sentenceGlossMode
beginner	always	always	none
novice	always	always	none
intermediate	always	non-trivial	inline-only
advanced	complex	complex	trailing
native	rare	rare	none

Also seed nativeLanguage: "English" and scriptOptions: {} (or whatever the language flow set, e.g. transliterateKanjiOnly).

============================================================ PHASE 2 — ADVANCED OVERRIDES (optional)

Ask: "Customize default density and sentence-gloss settings? (yes/no)"

If no, skip to "Write config" below.

If yes, ask three more questions:

Q6. Transliteration density — when to show transliteration:

• always — every replacement (default for beginner/novice/intermediate)
• non-trivial — skip the most-common words; show on everything from common-but-not-trivial up
• complex — only complex words and above (default for advanced)
• rare — only rare/idiomatic words (default for native)
• never — never show transliteration (forces transliteration off)

Q7. Gloss density — when to show the English gloss (same five tiers as Q6).

Q8. Sentence gloss mode — for full target-language sentences:

• trailing — keep the sentence intact, append (English: …) after
• inline-only — no trailing translation; gloss only words passing the gloss-density filter
• both — inline-gloss complex words AND append a trailing English summary
• none — no English at all

Override the defaults from Phase 1 with the user's answers.

============================================================ WRITE CONFIG

Build the final JSON object:

{
  "configured": true,
  "nativeLanguage": "English",
  "targetLanguage": "<from Q1>",
  "script": "<from Q2 / language flow>",
  "scriptOptions": { "<from language flow if any>": "..." },
  "transliteration": <from Q3>,
  "transliterationName": "<from Q3, omit if transliteration false>",
  "level": "<from Q4>",
  "transliterationDensity": "<from Q6 or default>",
  "glossDensity": "<from Q7 or default>",
  "sentenceGlossMode": "<from Q8 or default>",
  "onByDefault": <from Q5>
}

Resolve the config path (create parent directory if missing):

• Linux/macOS: $XDG_CONFIG_HOME/vibe-language-learning/config.json if XDG_CONFIG_HOME is set, else ~/.config/vibe-language-learning/config.json
• Windows: %APPDATA%\vibe-language-learning\config.json

Use the Write tool to create the file with mode 0600. If a config file already exists, this overwrites it (no merge — the wizard always produces a complete config).

After writing, confirm to the user with the chosen settings in a compact summary. Tell them VLL will activate at the next session start (if onByDefault) or when they run /vll on.