docs: phonological layer page; secryst replaces rababa in About

src/layouts/Base.astro

@@ -115,6 +115,7 @@ const currentPath = Astro.url.pathname
               <li><a href="/maps">Map catalogue</a></li>
               <li><a href="/authorities">Authorities</a></li>
               <li><a href="/docs">Documentation</a></li>
+              <li><a href="/docs/phonological-layer">Phonological layer</a></li>
             </ul>
           </div>
           <div class="footer-col">
@@ -124,6 +125,8 @@ const currentPath = Astro.url.pathname
               <li><a href="https://www.npmjs.com/package/interscript-ts" rel="noreferrer">TypeScript package</a></li>
               <li><a href="https://github.com/interscript/maps" rel="noreferrer">Map corpus</a></li>
               <li><a href="https://github.com/interscript/interscript-ruby" rel="noreferrer">Ruby source</a></li>
+              <li><a href="https://www.secryst.org" rel="noreferrer">secryst crystals</a></li>
+              <li><a href="https://github.com/interscript/interscript-ml" rel="noreferrer">interscript-ml contract</a></li>
             </ul>
           </div>
           <div class="footer-col">

src/pages/about.astro

@@ -33,12 +33,44 @@ import Base from "../layouts/Base.astro"
     <h2>History</h2>
     <p>
       Interscript was started at Ribose in 2019 as a Ruby library and
-      has since grown to include a TypeScript runtime, a research-grade
-      neural diacritizer (rababa), and a public reference site. The map
-      corpus now exceeds 300 systems.
+      has since grown to include TypeScript and Python engines, a public
+      reference site, and an optional phonological layer —
+      <a href="/docs/phonological-layer">interscript-ml</a> (the
+      contract and model zoo) run by the
+      <a href="https://www.secryst.org">secryst</a> crystal family
+      (Ruby · Python · TypeScript). The map corpus now exceeds 300
+      systems.
     </p>
   </section>
 
+  <section>
+    <h2>The ecosystem</h2>
+    <p>
+      Interscript is deliberately layered. The core is deterministic
+      maps and engines. When a map needs undiacritized text vocalized
+      first, it dispatches to an optional crystal:
+    </p>
+    <ul>
+      <li><strong>Maps + engines</strong> —
+        <code>interscript-ruby</code>, <code>interscript-ts</code>,
+        <code>interscript-py</code> — pure deterministic conversion.</li>
+      <li><strong>Contract + zoo</strong> —
+        <a href="https://github.com/interscript/interscript-ml">interscript-ml</a>
+        — the <code>models.yaml</code> index, IMF&nbsp;v1 model format,
+        and golden sets.</li>
+      <li><strong>Crystals</strong> —
+        <a href="https://www.secryst.org">secryst</a>
+        (<code>gem secryst</code> · <code>pip install secryst</code> ·
+        <code>npm i secryst</code>) — local ONNX inference implementing
+        the contract. A crystal has no interscript dependency; an engine
+        without a crystal simply cannot execute maps that declare a
+        vocalization step.</li>
+      <li><strong>Training</strong> —
+        <a href="https://github.com/interscript/interscript-ml-train">interscript-ml-train</a>
+        — teachers whose students enter the zoo.</li>
+    </ul>
+  </section>
+
   <section>
     <h2>Team</h2>
     <p>

src/pages/docs/index.astro

@@ -11,8 +11,11 @@ const docs = renderAsciiDocDir("src/content/docs")
   <section class="quickstart">
     <h2>Getting started</h2>
     <p>
-      Interscript runs in Ruby and TypeScript. Both consume the same
-      authority-backed maps.
+      Interscript runs in Ruby, TypeScript, and Python. All consume the
+      same authority-backed maps. An optional
+      <a href="/docs/phonological-layer">phonological layer</a>
+      (secryst crystals + the interscript-ml contract) recovers vowels
+      and phonemes when a map needs vocalized input.
     </p>
     <div class="runtime-tiles">
       <div class="tile">
@@ -29,6 +32,12 @@ interscript -s bgnpcgn-ukr-Cyrl-Latn-2019 &lt;&lt;&lt; "Антон"
 transliterate("bgnpcgn-ukr-Cyrl-Latn-2019", "Антон")
 // => "Anton"</code></pre>
       </div>
+      <div class="tile">
+        <h3>Phonological layer</h3>
+        <pre><code>gem install secryst
+# or: pip install secryst / npm i secryst</code></pre>
+        <a href="/docs/phonological-layer">How vocalization fits →</a>
+      </div>
     </div>
   </section>
 

src/pages/docs/phonological-layer.astro

@@ -0,0 +1,89 @@
+---
+import Base from "../../layouts/Base.astro"
+---
+
+<Base
+  title="Phonological layer — Interscript"
+  description="How Interscript maps optionally use secryst crystals and the interscript-ml contract to vocalize undiacritized input before transliteration."
+>
+  <h1>Phonological layer</h1>
+
+  <p class="lede">
+    Many writing systems underdetermine pronunciation. Undiacritized Arabic,
+    nikud-less Hebrew, and unsegmented Thai cannot be transliterated
+    unambiguously until the hidden vowels or phonemes are restored. That
+    restoration is the <strong>phonological layer</strong> — optional,
+    independent of the core map engine, and run by the
+    <a href="https://www.secryst.org">secryst</a> crystal family against the
+    <a href="https://github.com/interscript/interscript-ml">interscript-ml</a>
+    contract.
+  </p>
+
+  <section>
+    <h2>How the pieces fit</h2>
+    <pre class="diagram"><code>map (deterministic) ──secryst()──► crystal (ONNX)
+                                      │
+                                      ▼
+                            interscript-ml contract
+                            models.yaml · IMF v1 · goldens</code></pre>
+    <ul>
+      <li><strong>interscript engines</strong> stay pure. A map that needs
+        vocalization declares a <code>secryst</code> (or future
+        <code>vocalize</code>) step; without a crystal installed, that map
+        simply cannot run that step.</li>
+      <li><strong>secryst crystals</strong>
+        (<code>gem secryst</code> · <code>pip install secryst</code> ·
+        <code>npm i secryst</code> resolve a model id through
+        <code>models.yaml</code>, download a sha256-verified IMF&nbsp;v1 zip,
+        cache it under <code>~/.cache/secryst</code>, and run greedy ONNX
+        inference locally. No cloud, no telemetry.</li>
+      <li><strong>interscript-ml</strong> is the contract only: the index,
+        the format, the golden sets, and the model zoo. It depends on
+        nothing. Crystals depend only on it.</li>
+      <li><strong>interscript-ml-train</strong> produces the teachers whose
+        distilled students enter the zoo.</li>
+    </ul>
+  </section>
+
+  <section>
+    <h2>Environment</h2>
+    <table>
+      <thead><tr><th>Variable</th><th>Meaning</th><th>Default</th></tr></thead>
+      <tbody>
+        <tr><td><code>SECRYST_INDEX</code></td><td>Index URL or path</td>
+          <td>interscript-ml <code>models.yaml</code> on GitHub</td></tr>
+        <tr><td><code>SECRYST_CACHE</code></td><td>Artifact cache</td>
+          <td><code>~/.cache/secryst</code></td></tr>
+      </tbody>
+    </table>
+  </section>
+
+  <section>
+    <h2>Further reading</h2>
+    <ul>
+      <li><a href="https://www.secryst.org">secryst.org</a> — crystal primer, API reference, model zoo</li>
+      <li><a href="https://www.secryst.org/spec.html">IMF v1 specification</a> — the normative contract text</li>
+      <li><a href="https://github.com/interscript/interscript-ml/blob/main/SPEC.md">interscript-ml/SPEC.md</a> — canonical source of that text</li>
+      <li><a href="https://github.com/interscript/interscript-ml-train">interscript-ml-train</a> — teachers</li>
+    </ul>
+  </section>
+</Base>
+
+<style>
+  .lede { font-size: 1.1rem; line-height: 1.7; max-width: 70ch; }
+  section { margin: 2.2rem 0; }
+  h2 { font-size: 1.35rem; margin-bottom: 0.6rem; }
+  p, li { line-height: 1.7; max-width: 70ch; }
+  a { color: var(--color-brand); }
+  code { font-size: 0.9em; }
+  .diagram {
+    background: var(--color-surface, #f4f4f5);
+    border: 1px solid var(--color-border, #e4e4e7);
+    border-radius: 8px;
+    padding: 1rem 1.2rem;
+    overflow-x: auto;
+    font-size: 0.85rem;
+  }
+  table { width: 100%; border-collapse: collapse; margin: 1rem 0; font-size: 0.95rem; }
+  th, td { text-align: left; padding: 0.5rem 0.75rem; border-bottom: 1px solid var(--color-border, #e4e4e7); }
+</style>