fix: correct skill examples and API docs for article/gloss alignment

- world → le + monde: both words linked (article is part of noun phrase)
- interlinear gloss: source→gloss adjacent (gapPx 12, showConnectors false),
  translation below; gloss tokens colored via connections to source
- updated /api page example and skill SKILL.md + references/api.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: dani-polani

bitext/src/routes/api/+page.svelte

@@ -164,12 +164,13 @@
     "lines": ["Hello world", "Bonjour le monde"],
     "alignments": [
       [0, 0, 1, 0],
+      [0, 1, 1, 1],
       [0, 1, 1, 2]
     ]
   }'`}</pre>
 	<p class="mt-2 text-sm text-gray-500 dark:text-gray-400">
-		Links "Hello" → "Bonjour" (word 0 → word 0) and "world" → "monde" (word 1 → word 2; "le" is
-		word 1, "monde" is word 2).
+		Links "Hello" → "Bonjour" (word 0 → word 0). "world" → "le" + "monde" (words 1 and 2) — the
+		French article is part of the noun phrase, so both words share the same color.
 	</p>
 
 	<h3 class={subheadingClass}>Example — many-to-one (one word maps to several)</h3>
@@ -426,23 +427,24 @@
   -H "Content-Type: application/json" \\
   -d '{
     "lines": [
-      "Я ходил",
-      "I have been going",
-      "1SG.NOM PST.IPFV"
+      { "text": "Я ходил", "sizePx": 40 },
+      { "text": "1SG.NOM PST.IPFV", "sizePx": 22 },
+      { "text": "I have been going", "sizePx": 36 }
     ],
     "alignments": [
-      [0, 0, 1, 0],
-      [0, 1, 1, 1],
-      [0, 1, 1, 2],
-      [0, 1, 1, 3]
+      [0, 0, 1, 0], [0, 0, 1, 1],
+      [0, 1, 1, 2], [0, 1, 1, 3]
     ],
     "pairs": [
-      { "upper": 1, "lower": 2, "gapPx": 60, "showConnectors": false }
+      { "upper": 0, "lower": 1, "gapPx": 12, "showConnectors": false },
+      { "upper": 1, "lower": 2, "gapPx": 80, "showConnectors": false }
     ]
   }'`}</pre>
 	<p class="mt-2 text-sm text-gray-500 dark:text-gray-400">
-		Connectors are drawn between lines 0–1. Line 2 is a gloss row with a smaller gap and no
-		connectors.
+		Gloss is adjacent to source (lines 0–1) with a 12 px gap and hidden arcs — tokens are colored
+		but no lines are drawn. Dots in the gloss text are split characters: <span class={codeClass}>"1SG.NOM"</span>
+		becomes two tokens (word 0 = <em>1SG</em>, word 1 = <em>NOM</em>). The free translation sits
+		below with a larger gap.
 	</p>
 
 	<!-- ── Word indices ────────────────────────────────────────── -->

word-aligner-skill.zip

@@ -45,6 +45,16 @@ If uncertain about tokenization, call `GET https://aligner.tinygods.dev/api/alig
 }
 ```
 
+**One-to-many** (article + noun both correspond to one source word): include both target words.
+
+```json
+{
+  "lines": ["Hello world", "Bonjour le monde"],
+  "alignments": [[0,0,1,0], [0,1,1,1], [0,1,1,2]]
+}
+```
+"world" maps to both "le" (word 1) and "monde" (word 2) — they share a color.
+
 **RTL language** (Hebrew, Arabic, etc.): use a `LineInput` object with `"rtl": true` and a matching font.
 
 ```json
@@ -57,16 +67,30 @@ If uncertain about tokenization, call `GET https://aligner.tinygods.dev/api/alig
 }
 ```
 
-**3 lines with a gloss row**: add `pairs` to hide connectors on the gloss pair.
+**Interlinear gloss**: place the gloss line directly under the source (adjacent), connect source→gloss tokens, hide the arcs with `showConnectors: false`, use a small gap (12px). Put the free translation below the gloss with a larger gap and no connectors.
+
+`"1SG.NOM PST.IPFV"` — dots are default split chars, so this yields 4 tokens: `1SG`[0] `NOM`[1] `PST`[2] `IPFV`[3].
 
 ```json
 {
-  "lines": ["Я ходил", "I have been going", "1SG.NOM PST.IPFV"],
-  "alignments": [[0,0,1,0], [0,1,1,1], [0,1,1,2], [0,1,1,3]],
-  "pairs": [{"upper": 1, "lower": 2, "gapPx": 60, "showConnectors": false}]
+  "lines": [
+    {"text": "Я ходил", "sizePx": 40},
+    {"text": "1SG.NOM PST.IPFV", "sizePx": 22},
+    {"text": "I have been going", "sizePx": 36}
+  ],
+  "alignments": [
+    [0,0,1,0], [0,0,1,1],
+    [0,1,1,2], [0,1,1,3]
+  ],
+  "pairs": [
+    {"upper": 0, "lower": 1, "gapPx": 12, "showConnectors": false},
+    {"upper": 1, "lower": 2, "gapPx": 80, "showConnectors": false}
+  ]
 }
 ```
 
+Gloss tokens inherit colors from their source-word group. Arcs are hidden on both pairs; only the color coding is visible.
+
 ## Full parameter reference
 
 See [references/api.md](references/api.md) for the complete parameter tables: `LineInput`, `SettingsInput` (palette, lineStyle, lineThickness, lineOpacity, background, theme, showNumbers, colorTokensByLink), and `PairInput` (gapPx, showConnectors).

word-aligner-skill/SKILL.md

@@ -92,13 +92,14 @@ Returns the same `{ "url": "..." }` response. Useful for opening the editor pre-
 
 ## Examples
 
-### Simple two-language alignment
+### Simple two-language alignment (article + noun both linked to one source word)
 ```json
 {
   "lines": ["Hello world", "Bonjour le monde"],
-  "alignments": [[0,0,1,0], [0,1,1,2]]
+  "alignments": [[0,0,1,0], [0,1,1,1], [0,1,1,2]]
 }
 ```
+"world" maps to both "le" (word 1) and "monde" (word 2) — they share a color.
 
 ### Custom visual style (vivid, dark)
 ```json
@@ -134,16 +135,25 @@ Returns the same `{ "url": "..." }` response. Useful for opening the editor pre-
 }
 ```
 
-### Three lines — source + translation + gloss
+### Three lines — source + gloss + free translation
+Gloss is adjacent to source (lines 0–1), arcs hidden but colors shown. Translation is below.
+Dots in gloss are split chars: `"1SG.NOM PST.IPFV"` → tokens `1SG`[0] `NOM`[1] `PST`[2] `IPFV`[3].
+
 ```json
 {
   "lines": [
-    "Я ходил",
-    "I have been going",
-    "1SG.NOM PST.IPFV"
+    {"text": "Я ходил", "sizePx": 40},
+    {"text": "1SG.NOM PST.IPFV", "sizePx": 22},
+    {"text": "I have been going", "sizePx": 36}
+  ],
+  "alignments": [
+    [0,0,1,0], [0,0,1,1],
+    [0,1,1,2], [0,1,1,3]
   ],
-  "alignments": [[0,0,1,0], [0,1,1,1], [0,1,1,2], [0,1,1,3]],
-  "pairs": [{"upper": 1, "lower": 2, "gapPx": 60, "showConnectors": false}]
+  "pairs": [
+    {"upper": 0, "lower": 1, "gapPx": 12, "showConnectors": false},
+    {"upper": 1, "lower": 2, "gapPx": 80, "showConnectors": false}
+  ]
 }
 ```