mistri 0.5.0 → 0.6.1

data/assets/logo-animated.svg

@@ -0,0 +1,30 @@
+<!-- mistri wordmark (مستری), cut from Noto Nastaliq Urdu Bold to pure
+     paths. Each stroke is addressable: #stroke-1 through #stroke-6,
+     class .glyph, fill inherits currentColor. Edit, recolor, or animate
+     per stroke. -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="-32 -827 2450 1325" role="img" aria-label="mistri">
+  <style>
+    .glyph {
+      opacity: 0;
+      transform: translateY(2%);
+      animation: mistri-reveal 0.9s cubic-bezier(0.2, 0.7, 0.2, 1) forwards;
+    }
+    #stroke-1 { animation-delay: 3.30s; }
+    #stroke-2 { animation-delay: 2.75s; }
+    #stroke-3 { animation-delay: 2.20s; }
+    #stroke-4 { animation-delay: 1.65s; }
+    #stroke-5 { animation-delay: 1.10s; }
+    #stroke-6 { animation-delay: 0.55s; }
+    @keyframes mistri-reveal {
+      to { opacity: 1; transform: translateY(0); }
+    }
+  </style>
+  <g id="wordmark" fill="currentColor">
+    <path id="stroke-1" class="glyph" d="M250 341Q184 341 134.0 309.0Q84 277 56.0 219.5Q28 162 28 88Q28 34 42.5 -37.5Q57 -109 92.5 -194.0Q128 -279 191 -370L217 -355Q170 -273 145.5 -215.0Q121 -157 112.5 -114.0Q104 -71 104 -33Q104 21 126.5 65.5Q149 110 195.5 136.0Q242 162 312 162Q381 162 436.5 139.0Q492 116 531.0 81.5Q570 47 591.0 13.0Q612 -21 612 -42Q612 -62 593.5 -77.0Q575 -92 525 -112Q470 -134 470 -193Q470 -215 479.5 -249.0Q489 -283 505.5 -323.0Q522 -363 543.0 -402.5Q564 -442 586 -476Q630 -544 678.5 -588.0Q727 -632 773 -632Q818 -632 818 -604Q818 -597 813 -584L765 -474L756 -472Q748 -480 725 -480Q701 -480 672.0 -463.5Q643 -447 616.0 -421.0Q589 -395 572.0 -366.5Q555 -338 555 -315Q555 -272 625 -245Q655 -234 668.5 -217.5Q682 -201 682 -169Q682 -129 667.5 -70.0Q653 -11 623.0 54.0Q593 119 548 177Q487 256 409.5 298.5Q332 341 250 341Z"/>
+    <path id="stroke-2" class="glyph" d="M686 438 662 411Q760 325 842.0 211.0Q924 97 1007 -39Q1027 -71 1048.0 -101.0Q1069 -131 1089 -157Q1137 -219 1177.5 -251.0Q1218 -283 1254.5 -294.0Q1291 -305 1327 -305Q1341 -305 1353.5 -298.5Q1366 -292 1366 -275Q1366 -243 1348.5 -213.5Q1331 -184 1303.0 -165.5Q1275 -147 1242 -147Q1193 -147 1156.5 -121.5Q1120 -96 1084.0 -47.5Q1048 1 1000 70Q926 177 852.0 271.0Q778 365 686 438Z"/>
+    <path id="stroke-3" class="glyph" d="M1172 -570Q1150 -592 1129.5 -610.0Q1109 -628 1089 -644V-653Q1099 -667 1116.5 -687.5Q1134 -708 1151.0 -726.0Q1168 -744 1176 -749H1185Q1209 -734 1226.5 -720.5Q1244 -707 1253 -693Q1264 -707 1278.0 -722.5Q1292 -738 1305.0 -750.5Q1318 -763 1324 -767H1332Q1372 -742 1391.5 -722.5Q1411 -703 1411 -683Q1411 -645 1331 -588H1322Q1305 -605 1289.0 -619.5Q1273 -634 1259 -646Q1243 -614 1181 -570Z"/>
+    <path id="stroke-4" class="glyph" d="M1332 -141Q1322 -141 1302.0 -142.5Q1282 -144 1264.0 -145.0Q1246 -146 1242 -146Q1209 -146 1209 -178Q1209 -211 1225.5 -239.5Q1242 -268 1268.5 -286.0Q1295 -304 1326 -304Q1356 -304 1373.5 -301.5Q1391 -299 1416 -299Q1430 -299 1439.5 -292.0Q1449 -285 1449 -267Q1449 -234 1432.5 -205.5Q1416 -177 1389.5 -159.0Q1363 -141 1332 -141Z"/>
+    <path id="stroke-5" class="glyph" d="M1333 -140Q1298 -140 1298 -172Q1298 -204 1314.0 -232.5Q1330 -261 1357.0 -279.5Q1384 -298 1417 -298Q1450 -298 1476.0 -309.5Q1502 -321 1533 -364Q1552 -389 1577 -389Q1593 -389 1613 -379Q1635 -369 1654 -369Q1717 -369 1742 -435L1759 -436Q1779 -410 1812 -410Q1857 -410 1870 -468L1891 -469Q1894 -465 1894 -458Q1907 -447 1927 -447Q1941 -447 1948.5 -435.0Q1956 -423 1956 -408Q1956 -377 1936.5 -358.5Q1917 -340 1894 -340Q1884 -340 1875.0 -343.5Q1866 -347 1858 -353Q1845 -333 1825.0 -319.0Q1805 -305 1779 -305Q1748 -305 1725 -327Q1678 -262 1623 -262Q1595 -262 1574 -274Q1552 -286 1544 -286Q1534 -286 1522.5 -271.5Q1511 -257 1497 -237Q1486 -221 1474.5 -207.0Q1463 -193 1450 -182Q1423 -160 1398.0 -150.0Q1373 -140 1333 -140Z"/>
+    <path id="stroke-6" class="glyph" d="M1893 -340Q1883 -340 1873.5 -350.5Q1864 -361 1864 -379Q1864 -410 1883.5 -428.0Q1903 -446 1926 -446Q1964 -446 2014.5 -468.0Q2065 -490 2108 -549Q2138 -589 2156.0 -611.0Q2174 -633 2188.5 -643.0Q2203 -653 2220 -657Q2227 -671 2239.0 -687.5Q2251 -704 2263.0 -718.5Q2275 -733 2282 -739H2295Q2305 -715 2314.5 -696.0Q2324 -677 2334 -664Q2348 -647 2353.0 -636.5Q2358 -626 2358 -615Q2358 -593 2342.5 -565.0Q2327 -537 2304.5 -516.5Q2282 -496 2260 -496Q2253 -496 2246.5 -496.5Q2240 -497 2234 -500Q2212 -511 2193.0 -516.5Q2174 -522 2159 -522Q2142 -522 2114.0 -496.0Q2086 -470 2054 -437Q2009 -391 1974.5 -365.5Q1940 -340 1893 -340Z"/>
+  </g>
+</svg>

data/assets/logo-dark.svg

@@ -0,0 +1,14 @@
+<!-- mistri wordmark (مستری), cut from Noto Nastaliq Urdu Bold to pure
+     paths. Each stroke is addressable: #stroke-1 through #stroke-6,
+     class .glyph, fill inherits currentColor. Edit, recolor, or animate
+     per stroke. -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="-32 -827 2450 1325" role="img" aria-label="mistri">
+  <g id="wordmark" fill="#f0f6fc">
+    <path id="stroke-1" class="glyph" d="M250 341Q184 341 134.0 309.0Q84 277 56.0 219.5Q28 162 28 88Q28 34 42.5 -37.5Q57 -109 92.5 -194.0Q128 -279 191 -370L217 -355Q170 -273 145.5 -215.0Q121 -157 112.5 -114.0Q104 -71 104 -33Q104 21 126.5 65.5Q149 110 195.5 136.0Q242 162 312 162Q381 162 436.5 139.0Q492 116 531.0 81.5Q570 47 591.0 13.0Q612 -21 612 -42Q612 -62 593.5 -77.0Q575 -92 525 -112Q470 -134 470 -193Q470 -215 479.5 -249.0Q489 -283 505.5 -323.0Q522 -363 543.0 -402.5Q564 -442 586 -476Q630 -544 678.5 -588.0Q727 -632 773 -632Q818 -632 818 -604Q818 -597 813 -584L765 -474L756 -472Q748 -480 725 -480Q701 -480 672.0 -463.5Q643 -447 616.0 -421.0Q589 -395 572.0 -366.5Q555 -338 555 -315Q555 -272 625 -245Q655 -234 668.5 -217.5Q682 -201 682 -169Q682 -129 667.5 -70.0Q653 -11 623.0 54.0Q593 119 548 177Q487 256 409.5 298.5Q332 341 250 341Z"/>
+    <path id="stroke-2" class="glyph" d="M686 438 662 411Q760 325 842.0 211.0Q924 97 1007 -39Q1027 -71 1048.0 -101.0Q1069 -131 1089 -157Q1137 -219 1177.5 -251.0Q1218 -283 1254.5 -294.0Q1291 -305 1327 -305Q1341 -305 1353.5 -298.5Q1366 -292 1366 -275Q1366 -243 1348.5 -213.5Q1331 -184 1303.0 -165.5Q1275 -147 1242 -147Q1193 -147 1156.5 -121.5Q1120 -96 1084.0 -47.5Q1048 1 1000 70Q926 177 852.0 271.0Q778 365 686 438Z"/>
+    <path id="stroke-3" class="glyph" d="M1172 -570Q1150 -592 1129.5 -610.0Q1109 -628 1089 -644V-653Q1099 -667 1116.5 -687.5Q1134 -708 1151.0 -726.0Q1168 -744 1176 -749H1185Q1209 -734 1226.5 -720.5Q1244 -707 1253 -693Q1264 -707 1278.0 -722.5Q1292 -738 1305.0 -750.5Q1318 -763 1324 -767H1332Q1372 -742 1391.5 -722.5Q1411 -703 1411 -683Q1411 -645 1331 -588H1322Q1305 -605 1289.0 -619.5Q1273 -634 1259 -646Q1243 -614 1181 -570Z"/>
+    <path id="stroke-4" class="glyph" d="M1332 -141Q1322 -141 1302.0 -142.5Q1282 -144 1264.0 -145.0Q1246 -146 1242 -146Q1209 -146 1209 -178Q1209 -211 1225.5 -239.5Q1242 -268 1268.5 -286.0Q1295 -304 1326 -304Q1356 -304 1373.5 -301.5Q1391 -299 1416 -299Q1430 -299 1439.5 -292.0Q1449 -285 1449 -267Q1449 -234 1432.5 -205.5Q1416 -177 1389.5 -159.0Q1363 -141 1332 -141Z"/>
+    <path id="stroke-5" class="glyph" d="M1333 -140Q1298 -140 1298 -172Q1298 -204 1314.0 -232.5Q1330 -261 1357.0 -279.5Q1384 -298 1417 -298Q1450 -298 1476.0 -309.5Q1502 -321 1533 -364Q1552 -389 1577 -389Q1593 -389 1613 -379Q1635 -369 1654 -369Q1717 -369 1742 -435L1759 -436Q1779 -410 1812 -410Q1857 -410 1870 -468L1891 -469Q1894 -465 1894 -458Q1907 -447 1927 -447Q1941 -447 1948.5 -435.0Q1956 -423 1956 -408Q1956 -377 1936.5 -358.5Q1917 -340 1894 -340Q1884 -340 1875.0 -343.5Q1866 -347 1858 -353Q1845 -333 1825.0 -319.0Q1805 -305 1779 -305Q1748 -305 1725 -327Q1678 -262 1623 -262Q1595 -262 1574 -274Q1552 -286 1544 -286Q1534 -286 1522.5 -271.5Q1511 -257 1497 -237Q1486 -221 1474.5 -207.0Q1463 -193 1450 -182Q1423 -160 1398.0 -150.0Q1373 -140 1333 -140Z"/>
+    <path id="stroke-6" class="glyph" d="M1893 -340Q1883 -340 1873.5 -350.5Q1864 -361 1864 -379Q1864 -410 1883.5 -428.0Q1903 -446 1926 -446Q1964 -446 2014.5 -468.0Q2065 -490 2108 -549Q2138 -589 2156.0 -611.0Q2174 -633 2188.5 -643.0Q2203 -653 2220 -657Q2227 -671 2239.0 -687.5Q2251 -704 2263.0 -718.5Q2275 -733 2282 -739H2295Q2305 -715 2314.5 -696.0Q2324 -677 2334 -664Q2348 -647 2353.0 -636.5Q2358 -626 2358 -615Q2358 -593 2342.5 -565.0Q2327 -537 2304.5 -516.5Q2282 -496 2260 -496Q2253 -496 2246.5 -496.5Q2240 -497 2234 -500Q2212 -511 2193.0 -516.5Q2174 -522 2159 -522Q2142 -522 2114.0 -496.0Q2086 -470 2054 -437Q2009 -391 1974.5 -365.5Q1940 -340 1893 -340Z"/>
+  </g>
+</svg>

data/assets/logo-light.svg

@@ -0,0 +1,14 @@
+<!-- mistri wordmark (مستری), cut from Noto Nastaliq Urdu Bold to pure
+     paths. Each stroke is addressable: #stroke-1 through #stroke-6,
+     class .glyph, fill inherits currentColor. Edit, recolor, or animate
+     per stroke. -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="-32 -827 2450 1325" role="img" aria-label="mistri">
+  <g id="wordmark" fill="#24292f">
+    <path id="stroke-1" class="glyph" d="M250 341Q184 341 134.0 309.0Q84 277 56.0 219.5Q28 162 28 88Q28 34 42.5 -37.5Q57 -109 92.5 -194.0Q128 -279 191 -370L217 -355Q170 -273 145.5 -215.0Q121 -157 112.5 -114.0Q104 -71 104 -33Q104 21 126.5 65.5Q149 110 195.5 136.0Q242 162 312 162Q381 162 436.5 139.0Q492 116 531.0 81.5Q570 47 591.0 13.0Q612 -21 612 -42Q612 -62 593.5 -77.0Q575 -92 525 -112Q470 -134 470 -193Q470 -215 479.5 -249.0Q489 -283 505.5 -323.0Q522 -363 543.0 -402.5Q564 -442 586 -476Q630 -544 678.5 -588.0Q727 -632 773 -632Q818 -632 818 -604Q818 -597 813 -584L765 -474L756 -472Q748 -480 725 -480Q701 -480 672.0 -463.5Q643 -447 616.0 -421.0Q589 -395 572.0 -366.5Q555 -338 555 -315Q555 -272 625 -245Q655 -234 668.5 -217.5Q682 -201 682 -169Q682 -129 667.5 -70.0Q653 -11 623.0 54.0Q593 119 548 177Q487 256 409.5 298.5Q332 341 250 341Z"/>
+    <path id="stroke-2" class="glyph" d="M686 438 662 411Q760 325 842.0 211.0Q924 97 1007 -39Q1027 -71 1048.0 -101.0Q1069 -131 1089 -157Q1137 -219 1177.5 -251.0Q1218 -283 1254.5 -294.0Q1291 -305 1327 -305Q1341 -305 1353.5 -298.5Q1366 -292 1366 -275Q1366 -243 1348.5 -213.5Q1331 -184 1303.0 -165.5Q1275 -147 1242 -147Q1193 -147 1156.5 -121.5Q1120 -96 1084.0 -47.5Q1048 1 1000 70Q926 177 852.0 271.0Q778 365 686 438Z"/>
+    <path id="stroke-3" class="glyph" d="M1172 -570Q1150 -592 1129.5 -610.0Q1109 -628 1089 -644V-653Q1099 -667 1116.5 -687.5Q1134 -708 1151.0 -726.0Q1168 -744 1176 -749H1185Q1209 -734 1226.5 -720.5Q1244 -707 1253 -693Q1264 -707 1278.0 -722.5Q1292 -738 1305.0 -750.5Q1318 -763 1324 -767H1332Q1372 -742 1391.5 -722.5Q1411 -703 1411 -683Q1411 -645 1331 -588H1322Q1305 -605 1289.0 -619.5Q1273 -634 1259 -646Q1243 -614 1181 -570Z"/>
+    <path id="stroke-4" class="glyph" d="M1332 -141Q1322 -141 1302.0 -142.5Q1282 -144 1264.0 -145.0Q1246 -146 1242 -146Q1209 -146 1209 -178Q1209 -211 1225.5 -239.5Q1242 -268 1268.5 -286.0Q1295 -304 1326 -304Q1356 -304 1373.5 -301.5Q1391 -299 1416 -299Q1430 -299 1439.5 -292.0Q1449 -285 1449 -267Q1449 -234 1432.5 -205.5Q1416 -177 1389.5 -159.0Q1363 -141 1332 -141Z"/>
+    <path id="stroke-5" class="glyph" d="M1333 -140Q1298 -140 1298 -172Q1298 -204 1314.0 -232.5Q1330 -261 1357.0 -279.5Q1384 -298 1417 -298Q1450 -298 1476.0 -309.5Q1502 -321 1533 -364Q1552 -389 1577 -389Q1593 -389 1613 -379Q1635 -369 1654 -369Q1717 -369 1742 -435L1759 -436Q1779 -410 1812 -410Q1857 -410 1870 -468L1891 -469Q1894 -465 1894 -458Q1907 -447 1927 -447Q1941 -447 1948.5 -435.0Q1956 -423 1956 -408Q1956 -377 1936.5 -358.5Q1917 -340 1894 -340Q1884 -340 1875.0 -343.5Q1866 -347 1858 -353Q1845 -333 1825.0 -319.0Q1805 -305 1779 -305Q1748 -305 1725 -327Q1678 -262 1623 -262Q1595 -262 1574 -274Q1552 -286 1544 -286Q1534 -286 1522.5 -271.5Q1511 -257 1497 -237Q1486 -221 1474.5 -207.0Q1463 -193 1450 -182Q1423 -160 1398.0 -150.0Q1373 -140 1333 -140Z"/>
+    <path id="stroke-6" class="glyph" d="M1893 -340Q1883 -340 1873.5 -350.5Q1864 -361 1864 -379Q1864 -410 1883.5 -428.0Q1903 -446 1926 -446Q1964 -446 2014.5 -468.0Q2065 -490 2108 -549Q2138 -589 2156.0 -611.0Q2174 -633 2188.5 -643.0Q2203 -653 2220 -657Q2227 -671 2239.0 -687.5Q2251 -704 2263.0 -718.5Q2275 -733 2282 -739H2295Q2305 -715 2314.5 -696.0Q2324 -677 2334 -664Q2348 -647 2353.0 -636.5Q2358 -626 2358 -615Q2358 -593 2342.5 -565.0Q2327 -537 2304.5 -516.5Q2282 -496 2260 -496Q2253 -496 2246.5 -496.5Q2240 -497 2234 -500Q2212 -511 2193.0 -516.5Q2174 -522 2159 -522Q2142 -522 2114.0 -496.0Q2086 -470 2054 -437Q2009 -391 1974.5 -365.5Q1940 -340 1893 -340Z"/>
+  </g>
+</svg>

data/assets/logo.svg

@@ -0,0 +1,14 @@
+<!-- mistri wordmark (مستری), cut from Noto Nastaliq Urdu Bold to pure
+     paths. Each stroke is addressable: #stroke-1 through #stroke-6,
+     class .glyph, fill inherits currentColor. Edit, recolor, or animate
+     per stroke. -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="-32 -827 2450 1325" role="img" aria-label="mistri">
+  <g id="wordmark" fill="currentColor">
+    <path id="stroke-1" class="glyph" d="M250 341Q184 341 134.0 309.0Q84 277 56.0 219.5Q28 162 28 88Q28 34 42.5 -37.5Q57 -109 92.5 -194.0Q128 -279 191 -370L217 -355Q170 -273 145.5 -215.0Q121 -157 112.5 -114.0Q104 -71 104 -33Q104 21 126.5 65.5Q149 110 195.5 136.0Q242 162 312 162Q381 162 436.5 139.0Q492 116 531.0 81.5Q570 47 591.0 13.0Q612 -21 612 -42Q612 -62 593.5 -77.0Q575 -92 525 -112Q470 -134 470 -193Q470 -215 479.5 -249.0Q489 -283 505.5 -323.0Q522 -363 543.0 -402.5Q564 -442 586 -476Q630 -544 678.5 -588.0Q727 -632 773 -632Q818 -632 818 -604Q818 -597 813 -584L765 -474L756 -472Q748 -480 725 -480Q701 -480 672.0 -463.5Q643 -447 616.0 -421.0Q589 -395 572.0 -366.5Q555 -338 555 -315Q555 -272 625 -245Q655 -234 668.5 -217.5Q682 -201 682 -169Q682 -129 667.5 -70.0Q653 -11 623.0 54.0Q593 119 548 177Q487 256 409.5 298.5Q332 341 250 341Z"/>
+    <path id="stroke-2" class="glyph" d="M686 438 662 411Q760 325 842.0 211.0Q924 97 1007 -39Q1027 -71 1048.0 -101.0Q1069 -131 1089 -157Q1137 -219 1177.5 -251.0Q1218 -283 1254.5 -294.0Q1291 -305 1327 -305Q1341 -305 1353.5 -298.5Q1366 -292 1366 -275Q1366 -243 1348.5 -213.5Q1331 -184 1303.0 -165.5Q1275 -147 1242 -147Q1193 -147 1156.5 -121.5Q1120 -96 1084.0 -47.5Q1048 1 1000 70Q926 177 852.0 271.0Q778 365 686 438Z"/>
+    <path id="stroke-3" class="glyph" d="M1172 -570Q1150 -592 1129.5 -610.0Q1109 -628 1089 -644V-653Q1099 -667 1116.5 -687.5Q1134 -708 1151.0 -726.0Q1168 -744 1176 -749H1185Q1209 -734 1226.5 -720.5Q1244 -707 1253 -693Q1264 -707 1278.0 -722.5Q1292 -738 1305.0 -750.5Q1318 -763 1324 -767H1332Q1372 -742 1391.5 -722.5Q1411 -703 1411 -683Q1411 -645 1331 -588H1322Q1305 -605 1289.0 -619.5Q1273 -634 1259 -646Q1243 -614 1181 -570Z"/>
+    <path id="stroke-4" class="glyph" d="M1332 -141Q1322 -141 1302.0 -142.5Q1282 -144 1264.0 -145.0Q1246 -146 1242 -146Q1209 -146 1209 -178Q1209 -211 1225.5 -239.5Q1242 -268 1268.5 -286.0Q1295 -304 1326 -304Q1356 -304 1373.5 -301.5Q1391 -299 1416 -299Q1430 -299 1439.5 -292.0Q1449 -285 1449 -267Q1449 -234 1432.5 -205.5Q1416 -177 1389.5 -159.0Q1363 -141 1332 -141Z"/>
+    <path id="stroke-5" class="glyph" d="M1333 -140Q1298 -140 1298 -172Q1298 -204 1314.0 -232.5Q1330 -261 1357.0 -279.5Q1384 -298 1417 -298Q1450 -298 1476.0 -309.5Q1502 -321 1533 -364Q1552 -389 1577 -389Q1593 -389 1613 -379Q1635 -369 1654 -369Q1717 -369 1742 -435L1759 -436Q1779 -410 1812 -410Q1857 -410 1870 -468L1891 -469Q1894 -465 1894 -458Q1907 -447 1927 -447Q1941 -447 1948.5 -435.0Q1956 -423 1956 -408Q1956 -377 1936.5 -358.5Q1917 -340 1894 -340Q1884 -340 1875.0 -343.5Q1866 -347 1858 -353Q1845 -333 1825.0 -319.0Q1805 -305 1779 -305Q1748 -305 1725 -327Q1678 -262 1623 -262Q1595 -262 1574 -274Q1552 -286 1544 -286Q1534 -286 1522.5 -271.5Q1511 -257 1497 -237Q1486 -221 1474.5 -207.0Q1463 -193 1450 -182Q1423 -160 1398.0 -150.0Q1373 -140 1333 -140Z"/>
+    <path id="stroke-6" class="glyph" d="M1893 -340Q1883 -340 1873.5 -350.5Q1864 -361 1864 -379Q1864 -410 1883.5 -428.0Q1903 -446 1926 -446Q1964 -446 2014.5 -468.0Q2065 -490 2108 -549Q2138 -589 2156.0 -611.0Q2174 -633 2188.5 -643.0Q2203 -653 2220 -657Q2227 -671 2239.0 -687.5Q2251 -704 2263.0 -718.5Q2275 -733 2282 -739H2295Q2305 -715 2314.5 -696.0Q2324 -677 2334 -664Q2348 -647 2353.0 -636.5Q2358 -626 2358 -615Q2358 -593 2342.5 -565.0Q2327 -537 2304.5 -516.5Q2282 -496 2260 -496Q2253 -496 2246.5 -496.5Q2240 -497 2234 -500Q2212 -511 2193.0 -516.5Q2174 -522 2159 -522Q2142 -522 2114.0 -496.0Q2086 -470 2054 -437Q2009 -391 1974.5 -365.5Q1940 -340 1893 -340Z"/>
+  </g>
+</svg>

data/docs/README.md

@@ -0,0 +1,87 @@
+# Mistri documentation
+
+Mistri is an agent harness for Ruby applications. The
+[project README](../README.md) is the shortest path from installation to a
+working tool-using agent. This directory carries the contracts needed when the
+agent becomes part of a real application.
+
+## Start here
+
+1. Run the [sixty-second example](../README.md#start-in-sixty-seconds).
+2. Read [Tool contracts](tool-contracts.md) before connecting model output to
+   application behavior.
+3. Read [Sessions and control](sessions.md) before making a run durable or
+   accepting approvals from another process.
+4. Read [Reliability](reliability.md) before a tool performs external writes.
+5. Check the [upgrade guide](../UPGRADING.md) before changing Mistri versions.
+
+## Guides
+
+| Guide | Use it when |
+| --- | --- |
+| [Tool contracts](tool-contracts.md) | Defining schemas, validating arguments, gating tools, returning UI data, or handing off a turn |
+| [Sessions and control](sessions.md) | Choosing a store, resuming, steering, approving, compacting, or rendering transcripts |
+| [Context and workspaces](context-and-workspaces.md) | Loading Skills and Definitions, transforming context, storing host-owned memory, or exposing editable documents |
+| [Sub-agents](sub-agents.md) | Delegating into child sessions, dispatching background workers, or exposing worker controls |
+| [MCP](mcp.md) | Connecting Streamable HTTP or stdio servers, OAuth, private networks, or large results |
+| [Reliability](reliability.md) | Handling retries, events, budgets, response limits, cancellation, concurrency, and side effects |
+| [Upgrade guide](../UPGRADING.md) | Moving an existing host between releases |
+| [Changelog](../CHANGELOG.md) | Reading the exact history of every public behavior change |
+
+## Common paths
+
+### Add a durable conversation
+
+Use [`Mistri::Session`](sessions.md#sessions) with a built-in store or a host
+adapter. The store contract is two methods: `append(id, entry)` and `load(id)`.
+
+### Put a human before a write
+
+Declare `needs_approval:` on the tool, route the returned call ID to the human,
+append the decision through a bare Session, and rebuild the current tools and
+policy before calling `resume`. The complete flow is in
+[Human approval](sessions.md#human-approval).
+
+### Stream into a web response
+
+Pass a block to `run`, or use `Mistri::Sinks::SSE` with any IO-like stream.
+Action Cable is an optional sink, not a framework requirement. See
+[Events and sinks](reliability.md#events-and-sinks).
+
+### Connect an MCP server
+
+Build `Mistri::MCP::Client` with exactly one of `url:` or `command:`, then turn
+the remote tools into local tools with `Mistri::MCP.tools`. Start with
+[MCP transports](mcp.md#transports).
+
+### Run work in another agent
+
+Use `Mistri::SubAgent` for a fixed specialist or `Mistri::SubAgent.pack` for a
+host-bounded worker pool. Read the [execution modes](sub-agents.md#execution-modes)
+before adding a queue dispatcher.
+
+### Give the model editable context
+
+Use Skills for on-demand playbooks, Definitions for host-assembled Agent
+configuration, a Workspace for document tools, or `Mistri::Memory` for one
+host-owned value shared across Sessions. The boundaries are in
+[Context and workspaces](context-and-workspaces.md).
+
+## Framework policy
+
+The gem owns mechanism. The host application owns users, authorization,
+business policy, queues, persistence schema, presentation, and the semantics of
+external side effects. Optional adapters are provided for common Rails
+components, but every core contract works without Rails.
+
+## Source landmarks
+
+- [`lib/mistri/agent.rb`](../lib/mistri/agent.rb) owns the run loop.
+- [`lib/mistri/session.rb`](../lib/mistri/session.rb) owns the append-only replay
+  and approval audit.
+- [`lib/mistri/tool.rb`](../lib/mistri/tool.rb) and
+  [`lib/mistri/schema.rb`](../lib/mistri/schema.rb) own tool contracts.
+- [`lib/mistri/mcp/`](../lib/mistri/mcp) contains the MCP client and transports.
+
+For contribution setup and quality gates, see
+[`CONTRIBUTING.md`](../CONTRIBUTING.md).

data/docs/context-and-workspaces.md

@@ -0,0 +1,378 @@
+# Context and workspaces
+
+Mistri keeps several kinds of context separate so the host can give each one
+the right lifetime and authority:
+
+| Mechanism | Purpose | Source lifetime |
+| --- | --- | --- |
+| `system:` | Stable instructions for the Agent | Agent instance |
+| `context:` | Host objects available to tool policy and handlers | Agent instance |
+| `skills:` | Host-curated playbooks loaded by the model on demand | Host files or objects |
+| `transform_context:` | Per-turn view of replay history | Agent instance |
+| Session messages | Durable conversation and control facts | Session store |
+| Workspace | Text the built-in document tools can edit | Workspace backend |
+| `Mistri::Memory` | Host-owned knowledge shared across sessions | Host backend |
+
+Any model-visible Skill, workspace, or memory tool call and result is still an
+ordinary Session message. Reading external context can therefore copy that
+content into the Session log.
+
+Do not put credentials into prompts, Skills, or persisted messages. Pass
+request-scoped identity and services through `context:` and authorize every tool
+at its execution boundary.
+
+## Skills
+
+A Skill is a named playbook with a short description and a full Markdown body.
+Only the descriptions join the system prompt. Mistri adds `read_skill`, and the
+model requests a body when the current task needs it.
+
+Load either `<root>/<name>/SKILL.md` directories or flat `<root>/<name>.md`
+files:
+
+```ruby
+skills = Mistri::Skills.load("app/agent_skills")
+
+agent = Mistri.agent(
+  "claude-opus-4-8",
+  skills: skills,
+  tools: application_tools,
+)
+```
+
+`skills:` also accepts the directory path directly. A Skill file may begin with
+the deliberately small frontmatter contract:
+
+```markdown
+---
+name: incident-review
+description: Review an incident timeline for missing evidence and unsafe claims.
+---
+
+# Incident review
+
+Read the timeline first. Separate observed facts from inference...
+```
+
+Only flat `name` and `description` string fields are interpreted. This is not a
+general YAML configuration surface. Without frontmatter, the file or directory
+name becomes the Skill name.
+
+Skill bodies are instructions, not a security boundary. Load only host-reviewed
+files, keep descriptions specific enough for correct selection, and let tool
+authorization enforce what the model may actually do.
+
+## Definitions
+
+A Definition keeps an Agent's editable prompt and host vocabulary in one
+Markdown file:
+
+```markdown
+---
+role: Trip planner
+model: claude-opus-4-8
+tools:
+  - search_flights
+  - book_hotel
+---
+
+Plan the trip for {first_name}. Confirm constraints before booking.
+```
+
+Load and assemble it through a host registry:
+
+```ruby
+definition = Mistri::Definition.load("app/agents/trip_planner.md")
+tools = definition.tool_names.map { |name| tool_registry.fetch(name) }
+
+agent = Mistri.agent(
+  definition.model,
+  system: definition.render(first_name: traveler.first_name),
+  tools: tools,
+)
+```
+
+`render` raises when a placeholder has no value instead of leaking a literal
+`{first_name}` into the prompt. A nil value renders as empty. `role`, `model`,
+and `tools` have convenience readers; other frontmatter remains available
+through `definition.config` for the host to interpret.
+
+Mistri never resolves a tool name or arbitrary Definition key by itself. The
+host registry is the authority that turns configuration into application code.
+
+## Application context
+
+Pass acting identity and request-scoped services through `context:`:
+
+```ruby
+agent = Mistri.agent(
+  "claude-opus-4-8",
+  tools: tools,
+  context: { actor: current_user, tenant: current_tenant },
+  before_tool: lambda { |call, tool_context|
+    allowed = policy.allowed?(
+      tool_context.app.fetch(:actor),
+      call.name,
+      call.arguments,
+    )
+    next if allowed
+
+    "not authorized"
+  },
+)
+```
+
+Handlers that accept a second argument receive the same
+`Mistri::ToolContext`; `context.app` is exactly the host value. This context is
+not persisted. Rebuild it from current identity and policy before resuming a
+persisted Session. Return a sanitized block reason from `before_tool`; an
+unexpected hook exception is also reported to the model and Session, including
+its class and message.
+
+## Per-turn context transforms
+
+`transform_context:` accepts one callable or an Array. Before every provider
+request, each callable receives the replay Messages and returns the Messages
+that request should see. The transformed view is not appended to the Session.
+
+This seam supports host redaction, retrieval, and deliberate windowing, but it
+is low-level. Preserve message order and every tool-call/result pair. A
+provider will reject a history whose correlation facts were removed.
+
+For periodic instruction reinforcement, use the built-in Reminder:
+
+```ruby
+reminder = Mistri::Reminder.every(
+  3,
+  "Stay within the approved catalog. Verify availability before claiming it.",
+)
+
+agent = Mistri.agent(
+  "claude-opus-4-8",
+  tools: tools,
+  transform_context: reminder,
+)
+```
+
+The reminder counts completed assistant turns, appears only in the provider
+request when due, and never becomes a Session message. Pass `after:` when the
+first reminder should use a different turn boundary.
+
+## Workspaces and document tools
+
+A workspace is a four-method port:
+
+```ruby
+read(path)             # String or nil
+write(path, content)
+delete(path)
+list(prefix = nil)     # sorted path Strings
+```
+
+A backend may additionally claim atomic conditional writes:
+
+```ruby
+atomic_writes? # true
+snapshot(path) # Mistri::Workspace::Snapshot or nil
+compare_and_write(path, content, expected_revision:) # Snapshot
+```
+
+`Snapshot#revision` is an opaque, nonempty String of at most 256 bytes for those
+exact content bytes; Snapshot owns frozen base-String copies of both values.
+`expected_revision: nil` means create only and must conflict if the document
+exists. A non-nil revision must match the latest Snapshot for that path. On
+success, `compare_and_write` returns the content and revision actually committed
+by storage. A conditional mismatch raises `Mistri::WorkspaceConflictError`
+without writing.
+
+`edit_file` retries only that conflict, at most three total attempts, and
+reapplies the anchored replacement to each fresh snapshot. Concurrent changes
+outside the target therefore survive; a target that no longer matches becomes
+the ordinary actionable edit failure. Save, callback, validation, connection,
+and other errors are never retried. If storage transforms the committed bytes,
+the write is not retried or falsely reported as the exact requested
+replacement: the model receives an error-marked result saying the write
+committed and must read the document again. Custom four-method workspaces keep
+their existing behavior unless they explicitly return true from
+`atomic_writes?` and implement both methods.
+
+The conditional protocol is used by `edit_file`. `write_file` remains an
+intentional blind whole-document replacement, and deletion has no conditional
+form. When concurrent writers must preserve unrelated changes, use an anchored
+edit or provide a host tool with a stronger domain contract.
+
+Bind one to the built-in read, write, edit, find, and list tools:
+
+```ruby
+workspace = Mistri::Workspace::Memory.new
+workspace.write("brief.md", "# Launch brief\n")
+
+agent = Mistri.agent(
+  "claude-opus-4-8",
+  tools: Mistri::Tools.files(workspace),
+  system: "Read before editing. Keep the brief concise.",
+)
+```
+
+The tool names deliberately use the familiar file vocabulary even when the
+backend is a database row or host callback.
+
+### Memory workspace
+
+`Mistri::Workspace::Memory` is a mutex-protected document map for tests and
+ephemeral work. Its conditional writes are atomic between threads sharing the
+instance. It is not durable across processes.
+
+### Directory workspace
+
+```ruby
+workspace = Mistri::Workspace::Directory.new("tmp/agent-workspace")
+```
+
+Directory expands model paths under one canonical root, rejects lexical escape,
+refuses traversal through existing file or directory symlinks, and omits
+symlinked entries from listings. The host must keep the root and its tree stable
+for the workspace instance's lifetime. This is not an operating-system sandbox
+against a concurrent process changing filesystem entries, and Directory does
+not claim atomic conditional writes. A correct cross-process implementation
+needs a stable lock namespace and atomic replacement, not a Ruby mutex.
+
+Use a dedicated root with host-owned permissions. Do not point model-controlled
+tools at an application checkout, credential directory, or shared mutable tree.
+
+### Single-value workspace
+
+Wrap one host-owned value, such as a page draft or database column:
+
+```ruby
+workspace = Mistri::Workspace::Single.new(
+  path: "page.html",
+  read: -> { page.reload.draft_html },
+  write: ->(html) { page.update!(draft_html: html) },
+  synchronize: lambda do |&operation|
+    if page.class.connection.transaction_open?
+      raise Mistri::ConfigurationError, "page editor must run outside a transaction"
+    end
+
+    page.with_lock(&operation)
+  end,
+)
+```
+
+The value can be read and rewritten but not deleted. `synchronize:` is
+optional; when supplied, Mistri performs the revision check and write inside
+that host boundary, so `page.with_lock` makes anchored edits atomic across
+application processes. The raw callbacks still own validation, authorization,
+and any database normalization. Without `synchronize:`, Single retains the
+legacy four-method behavior and makes no atomicity claim.
+
+`synchronize:` is an executable host assertion, not merely a mutex callback:
+it must cover the current read, conditional check, write, and committed read
+across every writer that claims the same guarantee. For an Active Record value,
+it must also refuse an already-open host transaction as above. Under MySQL's
+repeatable-read default, joining an earlier transaction can make an ordinary
+reload observe stale bytes even after a locking read.
+
+### Active Record workspace
+
+The optional adapter is not loaded by `require "mistri"`:
+
+```ruby
+require "mistri/workspace/active_record"
+
+workspace = Mistri::Workspace::ActiveRecord.new(
+  AgentDocument,
+  scope: { tenant_id: current_tenant.id },
+)
+```
+
+The host model needs a non-null primary key, non-null `path` and `content`
+columns, non-null columns for every scope key, and a non-partial unique index
+whose columns are exactly the scope plus `path`. Scope values must be singular
+String, Symbol, Numeric, Boolean, Time, or Date equality values, not collections,
+Ranges, subqueries, custom mutable objects, or nil. The adapter verifies the
+model primary key against the database catalog and proves the remaining schema
+facts before claiming atomic writes. It uses the host's Active Record
+connection; Mistri does not require Rails or Active Record as a runtime
+dependency. On PostgreSQL, and on MySQL2 or Trilogy when the table is InnoDB,
+anchored edits use an exact-byte content revision, then a short transaction and
+locking read before `save!`; validations and callbacks still run, and no
+`lock_version` column is required. MyISAM and unrecognized storage engines, as
+well as other adapters, retain the legacy four-method behavior rather than
+advertise an unproved lock. Create-only conditional writes rely on the verified
+unique scope/path index. The adapter copies and freezes the scope Hash plus
+nested Hash, Array, Range, and String values at construction; atomic mode's
+narrower scalar contract keeps its tenant identity stable.
+
+Storage and schema capability are inspected on the first capability check and
+cached thereafter, off the edit path. Bind the workspace before concurrent use,
+keep its model on the same database role and shard, and do not change its table
+or indexes during the workspace's lifetime.
+
+Unsupported storage deliberately keeps the adapter's legacy read/write behavior.
+If lost-update protection is mandatory for your host, assert the capability at
+boot instead of accepting that fallback:
+
+```ruby
+raise "workspace is not atomic" unless workspace.atomic_writes?
+```
+
+Build and run the Agent outside any host Active Record transaction. The adapter
+rejects atomic snapshots and writes when its connection already has an open
+transaction: joining it would let MySQL repeatable-read snapshots stay stale
+across a retry and would extend Mistri's row lock to a boundary it does not own.
+
+## Durable memory across sessions
+
+`Mistri::Memory` is one replaceable text value stored wherever the host chooses:
+
+```ruby
+memory = Mistri::Memory.new(
+  read: -> { organization.agent_memory.to_s },
+  write: ->(text) { organization.update!(agent_memory: text) },
+)
+
+agent = Mistri.agent(
+  "claude-opus-4-8",
+  tools: Mistri::Tools.memory(memory),
+)
+```
+
+The generated `read_memory` and `update_memory` tools make the model read the
+current value and replace it as one coherent document. The host decides scope,
+authorization, size, retention, and conflict handling. Expose only
+`read_memory` when writes are not allowed; when a memory update requires human
+approval, build an equivalent gated Tool around `Memory#replace`. The helper's
+`update_memory` tool is ungated. Memory is not a hidden vector store. Its
+backing value lives outside the Session, but `read_memory` copies the value into
+a persisted tool result and `update_memory` persists the replacement text in
+the tool call.
+
+## Concurrency and delegation
+
+Workspace thread safety is backend-defined. Memory supplies in-process atomic
+writes; supported Active Record storage supplies scoped row-locking semantics;
+Single does so only when `synchronize:` satisfies the contract above. Directory
+and legacy custom workspaces do not turn host resources into transactions.
+Blind writers that ignore the same database locking discipline can still
+overwrite a later committed value; the host owns those external write paths and
+authorization.
+
+Sub-agent tools are ordinary Ruby objects and may close over a workspace. A
+dispatcher therefore requires a host-owned runtime factory; the model has no
+workspace selector. The factory receives the immutable dispatch spec and
+constructs the provider, tools, and workspace inside the worker. Mistri
+enforces the spec's exact tool-name grant, while the host remains responsible
+for whether the reconstructed backend is fresh, shared, transactional, or
+actually isolated. Derive durable workspace scope from trusted identifiers such
+as the child Session ID, reopen that same scope on queue retry, and release
+per-child resources through Runtime's `cleanup:` hook. See
+[Sub-agents](sub-agents.md#execution-modes).
+
+## Related guides
+
+- [Tool contracts](tool-contracts.md)
+- [Sessions and control](sessions.md)
+- [Sub-agents](sub-agents.md)
+- [Reliability](reliability.md)
+- [Upgrading](../UPGRADING.md)