Adom Wiki CLI Design - readme.html

Overview Files Packages Releases Dependencies Issues Breadcrumbs Pull Requests Activity
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>adom-wiki — CLI design</title>
<style>
  :root{
    --bg:#0a0e14; --bg2:#0e131c; --card:#121826; --card2:#161d2e;
    --ink:#e8edf5; --mut:#8b97ac; --dim:#5d6779; --line:#212a3b;
    --teal:#2dd4bf; --blue:#3b82f6; --purple:#a855f7;
    --ok:#34d399; --part:#fbbf24; --new:#fb7185;
  }
  *{box-sizing:border-box}
  html{-webkit-text-size-adjust:100%}
  body{margin:0;background:radial-gradient(1200px 600px at 80% -10%,#10203a 0%,var(--bg) 55%);
    color:var(--ink);font:15px/1.55 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;
    padding:0 0 80px}
  .wrap{max-width:1080px;margin:0 auto;padding:0 18px}
  header{padding:46px 0 26px}
  .kick{font-size:12px;letter-spacing:.18em;text-transform:uppercase;color:var(--teal);font-weight:700}
  h1{margin:.25em 0 .15em;font-size:clamp(30px,7vw,52px);line-height:1.02;letter-spacing:-.02em;
    background:linear-gradient(95deg,var(--teal),var(--blue) 45%,var(--purple));
    -webkit-background-clip:text;background-clip:text;color:transparent}
  h1 .mono{font-family:ui-monospace,SFMono-Regular,Menlo,monospace}
  .tag{color:var(--mut);font-size:clamp(15px,3.6vw,19px);max-width:62ch}
  .thesis{margin-top:22px;background:linear-gradient(180deg,var(--card),var(--bg2));
    border:1px solid var(--line);border-left:3px solid var(--teal);border-radius:14px;padding:16px 18px}
  .thesis b{color:var(--ink)}
  .thesis .mono{color:var(--teal)}
  h2{margin:46px 0 8px;font-size:13px;letter-spacing:.16em;text-transform:uppercase;color:var(--dim)}
  /* legend */
  .legend{display:flex;flex-wrap:wrap;gap:8px 16px;margin:10px 0 4px;font-size:13px;color:var(--mut)}
  .badge{display:inline-flex;align-items:center;gap:6px;font-weight:600;font-size:11.5px;
    padding:2px 8px;border-radius:999px;white-space:nowrap}
  .b-ok{color:#063;background:rgba(52,211,153,.16);border:1px solid rgba(52,211,153,.4)}
  .b-part{color:#7a5a00;background:rgba(251,191,36,.16);border:1px solid rgba(251,191,36,.45)}
  .b-new{color:#7a1330;background:rgba(251,113,133,.16);border:1px solid rgba(251,113,133,.45)}
  .b-ok{color:var(--ok)} .b-part{color:var(--part)} .b-new{color:var(--new)}
  .dot{width:7px;height:7px;border-radius:50%;display:inline-block}
  .d-ok{background:var(--ok)} .d-part{background:var(--part)} .d-new{background:var(--new)}
  /* pillars */
  .pillars{display:grid;grid-template-columns:repeat(auto-fill,minmax(330px,1fr));gap:16px;margin-top:14px}
  .pillar{background:linear-gradient(180deg,var(--card),var(--bg2));border:1px solid var(--line);
    border-radius:16px;overflow:hidden;display:flex;flex-direction:column}
  .pillar .top{padding:15px 16px 13px;border-bottom:1px solid var(--line);
    background:linear-gradient(180deg,rgba(255,255,255,.025),transparent)}
  .pillar .num{font-size:11px;font-weight:800;color:var(--dim);letter-spacing:.1em}
  .pillar h3{margin:2px 0 3px;font-size:20px;letter-spacing:-.01em}
  .pillar h3 .mono{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;
    background:linear-gradient(90deg,var(--teal),var(--blue));-webkit-background-clip:text;background-clip:text;color:transparent}
  .mimics{font-size:12.5px;color:var(--mut)}
  .mimics b{color:var(--ink)}
  .pillar .desc{font-size:12.5px;color:var(--dim);margin-top:5px}
  table{width:100%;border-collapse:collapse;font-size:13px}
  td{padding:8px 10px;border-bottom:1px solid rgba(255,255,255,.045);vertical-align:top}
  tr:last-child td{border-bottom:0}
  .cmd{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:12.5px;color:var(--ink);white-space:normal;overflow-wrap:break-word}
  .cmd .v{color:var(--teal)}
  .cmd .a{color:#bcd0ff}
  .ana{color:var(--dim);font-size:11.5px;font-family:ui-monospace,Menlo,monospace}
  .now{color:var(--mut);font-size:12px}
  .now .mono{font-family:ui-monospace,Menlo,monospace;color:var(--mut)}
  td.st{width:1%;text-align:right;padding-left:8px;overflow-wrap:break-word}
  /* meta + gaps */
  .grid2{display:grid;grid-template-columns:1fr 1fr;gap:16px;margin-top:14px}
  .grid3{display:grid;grid-template-columns:repeat(3,1fr);gap:16px;margin-top:14px}
  .pillar tr.hl td{background:linear-gradient(90deg,rgba(45,212,191,.10),rgba(45,212,191,0));box-shadow:inset 2px 0 0 var(--teal)}
  .pillar tr.hl .now.mono{color:var(--teal)}
  .pillar.admin{border-color:rgba(251,113,133,.4)}
  .pillar.admin .top{background:linear-gradient(180deg,rgba(251,113,133,.07),transparent)}
  .pillar.admin h3 .mono{background:linear-gradient(90deg,#fb7185,#f59e0b);-webkit-background-clip:text;background-clip:text;color:transparent}
  .adminbadge{display:inline-block;margin-left:6px;font-size:10px;font-weight:800;letter-spacing:.06em;
    color:var(--new);background:rgba(251,113,133,.15);border:1px solid rgba(251,113,133,.45);border-radius:999px;padding:2px 7px}
  .term{background:#080b10;border:1px solid var(--line);border-radius:12px;overflow-x:auto;margin:0;
    font:12px/1.6 ui-monospace,SFMono-Regular,Menlo,monospace;color:#aeb9c9;white-space:pre}
  .term .bar{display:block;padding:7px 12px;border-bottom:1px solid var(--line);color:var(--dim);background:rgba(255,255,255,.02)}
  .term .body{display:block;padding:12px 14px}
  .term .c{color:var(--teal)} .term .d{color:#5d6779} .term .y{color:var(--part)}
  .term .p{color:#bcd0ff} .term .r{color:var(--new)} .term .cmd2{color:#e8edf5}
  .plan{display:flex;flex-direction:column;gap:12px;margin-top:14px}
  .phase{background:linear-gradient(180deg,var(--card),var(--bg2));border:1px solid var(--line);
    border-left:3px solid var(--blue);border-radius:14px;padding:14px 16px}
  .phase.t-cli{border-left-color:var(--teal)} .phase.t-both{border-left-color:var(--purple)} .phase.t-srv{border-left-color:var(--new)}
  .phase h4{margin:0 0 3px;font-size:16px;display:flex;flex-wrap:wrap;align-items:center;gap:6px}
  .phase h4 .pid{font-family:ui-monospace,Menlo,monospace;color:var(--teal)}
  .phase .goal{color:var(--mut);font-size:13px;margin:2px 0 6px}
  .phase ul{margin:4px 0 0;padding-left:18px;color:var(--mut);font-size:13px}
  .phase li{margin:3px 0}
  .phase li b{color:var(--ink)}
  .owner{font-size:9.5px;font-weight:800;letter-spacing:.05em;padding:2px 7px;border-radius:999px}
  .o-cli{color:var(--teal);background:rgba(45,212,191,.14);border:1px solid rgba(45,212,191,.4)}
  .o-srv{color:var(--new);background:rgba(251,113,133,.14);border:1px solid rgba(251,113,133,.4)}
  .o-both{color:var(--purple);background:rgba(168,85,247,.14);border:1px solid rgba(168,85,247,.4)}
  .dep{font-size:11px;color:var(--dim);margin-top:7px;font-style:italic}
  .panel{background:linear-gradient(180deg,var(--card),var(--bg2));border:1px solid var(--line);border-radius:16px;padding:16px 18px}
  .panel h4{margin:0 0 10px;font-size:15px}
  .panel ul{margin:0;padding-left:18px;color:var(--mut)}
  .panel li{margin:5px 0}
  .panel li b{color:var(--ink)}
  .pill-row{display:flex;gap:8px;flex-wrap:wrap;margin:8px 0 2px}
  .chip{font-family:ui-monospace,Menlo,monospace;font-size:11.5px;padding:3px 8px;border-radius:7px;
    background:rgba(255,255,255,.04);border:1px solid var(--line);color:var(--mut)}
  .note{font-size:12.5px;color:var(--dim);margin-top:8px}
  .ask{border-left:3px solid var(--purple)}
  .foot{margin-top:40px;color:var(--dim);font-size:12px;border-top:1px solid var(--line);padding-top:16px}
  a{color:var(--blue)}
  .prompts{display:flex;flex-direction:column;gap:14px;margin-top:12px}
  .prompt{background:#0c1119;border:1px solid var(--line);border-radius:12px;overflow:hidden}
  .phead{display:flex;align-items:center;justify-content:space-between;gap:10px;padding:9px 12px;
    background:linear-gradient(180deg,rgba(255,255,255,.03),transparent);border-bottom:1px solid var(--line)}
  .ptitle{font-size:13px;font-weight:700;color:var(--ink)}
  .ptitle .n{color:var(--teal);font-family:ui-monospace,Menlo,monospace}
  .copy{font:600 12px/1 -apple-system,Segoe UI,sans-serif;color:var(--teal);background:rgba(45,212,191,.12);
    border:1px solid rgba(45,212,191,.4);border-radius:7px;padding:6px 13px;cursor:pointer;white-space:nowrap}
  .copy:active{transform:translateY(1px)}
  .copy.done{color:#bff;background:rgba(45,212,191,.28)}
  .prompt pre{margin:0;padding:13px 14px;white-space:pre-wrap;word-break:break-word;
    font:12.5px/1.55 ui-monospace,SFMono-Regular,Menlo,monospace;color:#c7d2e0}
  .prompt.john{border-left:3px solid var(--purple)}
  .prompt.john pre{color:#d8cdea;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;font-size:13.5px;line-height:1.6}
  .vtag{font:600 10px/1 -apple-system,Segoe UI,sans-serif;letter-spacing:.1em;text-transform:uppercase;
    color:var(--purple);background:rgba(168,85,247,.14);border:1px solid rgba(168,85,247,.4);border-radius:999px;padding:3px 8px}
  @media(max-width:820px){ .grid3{grid-template-columns:1fr} }
  @media(max-width:560px){
    .grid2{grid-template-columns:1fr}
    .ana{display:none}
    td{padding:8px 7px}
  }
</style>
</head>
<body>
<div class="wrap">
<header>
  <div class="kick">CLI design proposal</div>
  <h1><span class="mono">adom-wiki</span></h1>
  <div class="tag">One wiki, many tools in one. So: one CLI, nine pillars — each speaks the
    command vocabulary the AI already knows by heart, then adds the moves the household CLIs can't.</div>

  <div class="thesis">
    <b>The thesis.</b> Today <span class="mono">adompkg</span> is a single flat namespace of
    <b>52 verbs</b>, shaped almost entirely like <span class="mono">npm</span> — with git, releases,
    page-ops and hero bolted on as flat commands, and <b>no discussions or PRs at all</b>.
    The proposal: re-cut it as <span class="mono">adom-wiki &lt;pillar&gt; &lt;action&gt;</span>, where each of the
    nine pillars either mirrors the canonical CLI for its domain — <span class="mono">git</span>,
    <span class="mono">npm</span>, <span class="mono">gh&nbsp;release</span>,
    <span class="mono">gh&nbsp;issue</span>, <span class="mono">gh&nbsp;pr</span> — or, where no household name fits
    (presentation, discovery, admin, breadcrumbs), invents a clean Adom-native set. Muscle memory transfers and
    the model can guess the command it's never seen. <span class="mono">adompkg</span> stays as an alias
    for <span class="mono">adom-wiki pkg</span>.
  </div>
</header>

<div class="panel" style="border-left:3px solid var(--ok);background:linear-gradient(180deg,rgba(52,211,153,.09),var(--bg2))">
  <h4 style="margin:0 0 5px">✅ This shipped — <span class="mono">adom-wiki</span> is now the official CLI (v1.0.2)</h4>
  <p style="color:var(--mut);margin:0 0 8px">What was a design doc is now a real binary: <span class="mono">adom-wiki &lt;pillar&gt; &lt;verb&gt;</span>
    with <span class="mono">--json</span> on every command, actionable hints, and the 3-depth <span class="mono">--help</span> — replacing the
    now-deprecated <span class="mono">adompkg</span>. Same registry (<span class="mono">wiki.adom.inc</span>), same signing, nothing breaks.
    Pillars shipped: <b>pkg · repo · release · page · discussion · pr · discover · admin · breadcrumb · family</b>; meta verbs include
    <span class="mono">api</span> + <span class="mono">status</span> (the two highest-leverage adds from the audit below).</p>
  <div class="pill-row">
    <span class="chip">curl -fsSL wiki.adom.inc/download/adom/adom-wiki-cli/1.0.2/adom-wiki-cli-v1.0.2 -o ~/.local/bin/adom-wiki</span>
    <span class="chip">adom-wiki pkg install adom/adom-wiki-cli</span>
  </div>
  <div class="note">Page: <span class="mono">wiki.adom.inc/adom/adom-wiki-cli</span>. The status badges below were the original design vs
    <span class="mono">adompkg</span> — many "new"/"partial" items now ship in adom-wiki 1.0.2. This very page is published &amp; edited with it.</div>
</div>

<h2>Status legend — vs. <span style="text-transform:none;font-family:ui-monospace,Menlo,monospace;color:var(--mut)">adompkg</span> today</h2>
<div class="legend">
  <span><span class="badge b-ok"><span class="dot d-ok"></span>ships</span> exists today (maybe renamed)</span>
  <span><span class="badge b-part"><span class="dot d-part"></span>partial</span> API or half-command exists</span>
  <span><span class="badge b-new"><span class="dot d-new"></span>new</span> not in the CLI yet</span>
</div>

<div class="pillars" id="pillars"></div>

<h2>pkg vs release — what's the difference?</h2>
<div class="grid2">
  <div class="panel" style="border-left:3px solid var(--blue)">
    <h4><span class="mono" style="color:#bcd0ff">pkg</span> — the installable thing</h4>
    <p style="color:var(--mut);margin:.2em 0 .6em">The npm-style package: a <b>source tarball</b> with a manifest,
      semver versions and dependencies. You <span class="cmd"><span class="v">pkg</span> <span class="a">install</span></span> it
      into <span class="mono">adom_modules</span> and other packages depend on it. It's <b>code/skills the machine consumes</b> —
      resolved, deduped, version-pinned.</p>
    <div class="pill-row">
      <span class="chip">install · add · update · why</span>
      <span class="chip">immutable semver</span>
      <span class="chip">dependency graph</span>
    </div>
  </div>
  <div class="panel" style="border-left:3px solid var(--purple)">
    <h4><span class="mono" style="color:#d6b3ff">release</span> — the downloadable thing</h4>
    <p style="color:var(--mut);margin:.2em 0 .6em">Built <b>binary artifacts</b> attached to a version — the
      <span class="mono">.exe</span>/<span class="mono">.dmg</span>/<span class="mono">.tar.gz</span> per platform, with
      release notes. A human <span class="cmd"><span class="v">release</span> <span class="a">download</span></span>s it; you
      don't depend on it. It's the <b>product people run</b>, not the source you import.</p>
    <div class="pill-row">
      <span class="chip">create · upload · download · notes</span>
      <span class="chip">per-platform assets</span>
      <span class="chip">changelog</span>
    </div>
  </div>
</div>
<div class="note" style="margin-top:8px">One page can have <b>both</b>: e.g. Hydrogen Desktop's <span class="mono">pkg</span> is the
  installer skill/source you <span class="mono">install</span>; its <span class="mono">release</span> is the actual
  signed <span class="mono">.exe</span> per OS you <span class="mono">download</span>. Or <b>either alone</b> — a pure skill is pkg-only;
  a pure binary drop is release-only.</div>

<h2>Visibility — public / private on three layers, independently</h2>
<div class="panel" style="border-left:3px solid var(--teal)">
  <p style="color:var(--mut);margin:0 0 10px">Like GitHub's paid granular visibility, each storage layer flips on its own —
    so you can keep <b>source private</b> while the <b>app is freely installable</b> and the <b>binaries public</b>:</p>
  <table style="max-width:640px">
    <tbody>
    <tr><td class="cmd"><span class="v">--source</span> <span class="a">public|private</span></td>
        <td class="now">the git repo / Files tab — browse the actual code</td>
        <td class="st"><span class="badge b-ok"><span class="dot d-ok"></span>ships</span><div class="now mono">--hide-source</div></td></tr>
    <tr><td class="cmd"><span class="v">--pkg</span> <span class="a">public|private</span></td>
        <td class="now">the installable tarball — who can <span class="mono">install</span> it</td>
        <td class="st"><span class="badge b-new"><span class="dot d-new"></span>new</span><div class="now mono">3rd axis</div></td></tr>
    <tr><td class="cmd"><span class="v">--releases</span> <span class="a">public|private</span></td>
        <td class="now">the downloadable binaries</td>
        <td class="st"><span class="badge b-ok"><span class="dot d-ok"></span>ships</span><div class="now mono">--public-releases</div></td></tr>
    </tbody>
  </table>
  <div class="note">Today <span class="mono">adompkg visibility</span> already splits <b>source</b> vs <b>releases</b>
    (<span class="mono">--hide-source</span>, <span class="mono">--public-releases</span>). The new piece is making the
    <b>pkg/install</b> layer a first-class third toggle — e.g. closed-source app, public download, org-only install.</div>
</div>

<h2>Visibility presets — your two real modes, named</h2>
<div class="panel" style="border-left:3px solid var(--teal)">
  <p style="color:var(--mut);margin:0 0 10px">You publish in two recurring shapes — and right now each is assembled by hand
    from scattered flags (<span class="mono">--no-source</span>, <span class="mono">--hide-source</span>,
    <span class="mono">--private</span>). I probed your live repos: the per-axis columns
    <span class="mono">source_visibility</span> / <span class="mono">release_visibility</span> <b>exist but read null</b> on
    hydrogen-desktop &amp; adom-desktop — so the proprietary-source model isn't <i>declared</i>, it's improvised. Fix: name the
    modes as presets that set all three axes at once.</p>
  <table style="max-width:760px">
    <tbody>
    <tr style="color:var(--dim);font-size:11px;text-transform:uppercase;letter-spacing:.08em">
      <td>preset</td><td>source</td><td>install (pkg)</td><td>releases</td><td>your examples</td></tr>
    <tr><td class="cmd"><span class="v">--preset</span> <span class="a">open</span></td>
      <td class="now" style="color:var(--ok)">public</td><td class="now" style="color:var(--ok)">public</td>
      <td class="now" style="color:var(--ok)">public</td><td class="now mono">chip-fetcher</td></tr>
    <tr><td class="cmd"><span class="v">--preset</span> <span class="a">licensed</span></td>
      <td class="now" style="color:var(--new)">org-only</td><td class="now" style="color:var(--ok)">public</td>
      <td class="now" style="color:var(--ok)">public</td><td class="now mono">hydrogen-desktop, adom-desktop</td></tr>
    <tr><td class="cmd"><span class="v">--preset</span> <span class="a">preview</span></td>
      <td class="now" style="color:var(--new)">org-only</td><td class="now" style="color:var(--part)">org-only</td>
      <td class="now" style="color:var(--part)">org-only</td><td class="now mono">adom-usb (WIP, also score −50)</td></tr>
    <tr><td class="cmd"><span class="v">--preset</span> <span class="a">private</span></td>
      <td class="now" style="color:var(--new)">org-only</td><td class="now" style="color:var(--new)">org-only</td>
      <td class="now" style="color:var(--new)">org-only</td><td class="now mono">internal-only tools</td></tr>
    </tbody>
  </table>
  <div class="pill-row" style="margin-top:10px">
    <span class="chip"><span style="color:var(--teal)">adom-wiki page visibility</span> chip-fetcher --preset open</span>
    <span class="chip"><span style="color:var(--teal)">adom-wiki page visibility</span> hydrogen-desktop --preset licensed</span>
  </div>
  <div class="note">Presets are sugar over the three axes (<span class="mono">--source</span> /
    <span class="mono">--pkg</span> / <span class="mono">--releases</span>) — those stay for fine control. This is exactly the
    <b>wiki-visibility</b> archetype split: <i>Open-source Page</i> vs <i>Closed-source Page (private source, public compiled
    app)</i>. Status: source+release axes are schematized (unset today); the install axis and the named presets are new.</div>
</div>

<h2>Archetype-aware scaffolding — Page · Skillpack · Family</h2>
<p style="color:var(--mut);max-width:74ch;margin:.2em 0 0">Your <b>wiki-skillpack</b> defines three repo archetypes. The CLI
  should know them — scaffold the right structure on <span class="mono">init</span>, then <span class="mono">lint</span> that a
  repo stays true to it. Today <span class="mono">init --type app|skill|bootstrap</span> sets the content <i>type</i>, not the
  structural <i>archetype</i>; and <span class="mono">push --check</span> lints files+secrets but doesn't check archetype conformance.</p>
<div class="panel">
  <table>
    <tbody>
    <tr style="color:var(--dim);font-size:11px;text-transform:uppercase;letter-spacing:.08em">
      <td>archetype</td><td>what it is</td><td>proposed command</td><td class="st">state</td></tr>
    <tr><td class="cmd"><span class="v">page</span></td>
      <td class="now">one page = one thing (open or closed source)</td>
      <td class="cmd"><span class="v">init</span> <span class="a">--archetype page</span></td>
      <td class="st"><span class="badge b-part"><span class="dot d-part"></span>partial</span></td></tr>
    <tr><td class="cmd"><span class="v">skillpack</span></td>
      <td class="now">main SKILL.md + N sub-skills, <span class="mono">-skillpack</span> suffix</td>
      <td class="cmd"><span class="v">init</span> <span class="a">--archetype skillpack</span> <span class="now">→ skills/&lt;sub&gt;/ + install.sh + files[]</span></td>
      <td class="st"><span class="badge b-new"><span class="dot d-new"></span>new</span></td></tr>
    <tr><td class="cmd"><span class="v">family</span></td>
      <td class="now">anchor + child pages, joined by family tag + breadcrumbs</td>
      <td class="cmd"><span class="v">init</span> <span class="a">--archetype family</span> · <span class="v">family</span> <span class="a">add-child</span> · <span class="a">anchor</span></td>
      <td class="st"><span class="badge b-new"><span class="dot d-new"></span>new</span></td></tr>
    <tr><td class="cmd"><span class="v">— lint</span></td>
      <td class="now">validate a repo matches its archetype (suffix, layout, family tag, breadcrumbs)</td>
      <td class="cmd"><span class="v">lint</span> <span class="a">&lt;slug&gt;</span> <span class="now">(extends push --check)</span></td>
      <td class="st"><span class="badge b-part"><span class="dot d-part"></span>partial</span></td></tr>
    </tbody>
  </table>
  <div class="note">Recommendation: <b>don't make this a new pillar</b> — archetypes are a cross-cutting structural concern.
    Teach <span class="mono">pkg/repo init</span> the <span class="mono">--archetype</span> flag, add a
    <span class="mono">lint</span> that enforces conformance, and add a small <span class="mono">family</span> verb group for
    anchor/child/breadcrumb wiring (which is also where <b>wiki-breadcrumbs</b> third-party add-on links live).</div>
</div>

<h2>Linting — you're 90% there; you need rules, not plumbing</h2>
<p style="color:var(--mut);max-width:76ch;margin:.2em 0 0">Verdict on your three examples: <b>no new pillar, almost no new
  commands.</b> adompkg already ships a real linter — <span class="mono">lintSecrets · lintTags · lintVersionSync ·
  lintSkillFrontmatter · lintSymlinkConvention · lintSealedSourceInTarball</span> — plus <span class="mono">--skip-lint</span>,
  and the API already returns a coded <b>hints engine</b>. I pulled these live off adom-usb just now:</p>
<pre style="margin:10px 0;padding:12px 14px;background:#0c1119;border:1px solid var(--line);border-radius:10px;
  font:12px/1.5 ui-monospace,Menlo,monospace;color:#c7d2e0;white-space:pre-wrap">{ "code": "NO_DISCOVERY_TRIGGERS", "action": "Add 'discovery_triggers' … to the manifest." }
{ "code": "STALE", "action": "Ship a new release/commit, or deprecate the package…" }   ← level/code/message/action schema</pre>
<p style="color:var(--mut);max-width:76ch;margin:0 0 4px">What's missing: <b>(1)</b> promote <span class="mono">lint</span> to a
  first-class verb (today it only runs inside <span class="mono">push --check</span> / <span class="mono">publish</span>), and
  <b>(2)</b> three new rules for the exact mistakes the AI keeps making. Each rule must fire in <b>both</b> layers — client-side
  for fast CLI feedback <i>and</i> server-side in the hints engine, so the API reprimands even when the AI skips the CLI and POSTs direct.</p>
<div class="panel">
  <table>
    <tbody>
    <tr style="color:var(--dim);font-size:11px;text-transform:uppercase;letter-spacing:.08em">
      <td>rule code</td><td>catches</td><td>the reprimand → fix</td><td class="st">state</td></tr>
    <tr><td class="cmd" style="color:var(--new)">HERO_IN_README</td>
      <td class="now">the hero image embedded in the README body</td>
      <td class="now">"You're showing the hero twice — the page renders it <i>above</i> the README automatically. Drop it from the body; use other screenshots."</td>
      <td class="st"><span class="badge b-new"><span class="dot d-new"></span>new</span></td></tr>
    <tr><td class="cmd" style="color:var(--new)">BINARY_IN_REPO</td>
      <td class="now">executable / archive binaries committed to git (not presentation images)</td>
      <td class="now">"Binaries bloat the repo. A downloadable binary is a <b>release</b> asset; installable code is a <b>pkg</b> tarball. The repo is for source + README images only."</td>
      <td class="st"><span class="badge b-new"><span class="dot d-new"></span>new</span></td></tr>
    <tr><td class="cmd" style="color:var(--new)">PKG_VS_RELEASE</td>
      <td class="now">binary <i>type</i> ↔ target mismatch (sniffed by magic bytes, not extension)</td>
      <td class="now">"This is a Windows PE/.exe → ship it as <span class="mono">release upload --platform windows</span>. An ELF / shebang / JS CLI → that's a <span class="mono">pkg</span>."</td>
      <td class="st"><span class="badge b-new"><span class="dot d-new"></span>new</span></td></tr>
    <tr><td class="cmd" style="color:var(--new)">TITLE_IS_SLUG</td>
      <td class="now">page title is the raw slug / kebab-case (e.g. <span class="mono">adom-desktop</span>), or an <span class="mono">adom-*</span> slug whose title dropped the "Adom" prefix</td>
      <td class="now">"Title is the slug — set a display name: <span class="mono">adom-desktop</span> → <b>Adom Desktop</b>" + a humanized suggestion: Title-Case, keep <span class="mono">Adom</span>, expand known initialisms (USB, LBR→Library, EDA, KiCad)</td>
      <td class="st"><span class="badge b-new"><span class="dot d-new"></span>new</span></td></tr>
    <tr><td class="cmd" style="color:var(--new)">README_SHADOWED</td>
      <td class="now">a commit touches <span class="mono">README.md</span> while <span class="mono">readme.html</span> exists (readme.html wins — the edit won't show)</td>
      <td class="now">"<span class="mono">readme.html</span> is what renders here — your README.md change won't be visible. Edit readme.html, or delete it to fall back to README.md." <span class="d">(also a warning on the /files push response)</span></td>
      <td class="st"><span class="badge b-new"><span class="dot d-new"></span>new</span></td></tr>
    <tr><td class="cmd" style="color:var(--ok)">lintSecrets · lintSealedSourceInTarball · …</td>
      <td class="now" colspan="2">already shipping — secret scan, sealed-source leak guard, frontmatter, tags, version-sync, symlink convention</td>
      <td class="st"><span class="badge b-ok"><span class="dot d-ok"></span>ships</span></td></tr>
    </tbody>
  </table>
  <div class="note"><b>The clever bit (your example 3):</b> the linter sniffs the actual file's <b>magic bytes</b>, not just its
    extension, so it can tell the AI which lane a binary belongs in. <span class="mono">adom-desktop</span> is the textbook case —
    a Windows <span class="mono">.exe</span> installer (→ <b>release</b>, <span class="mono">--platform windows</span>) <i>and</i> a
    Linux CLI for the cloud / WSL2 container (→ <b>pkg</b>, installable). One repo, both lanes — the linter keeps them straight,
    and reprimands the AI the moment it files one as the other. Escape hatches stay (<span class="mono">--skip-lint</span>,
    <span class="mono">--allow-binary</span>) for the rare deliberate case.</div>
  <div class="note" style="margin-top:8px"><b>TITLE_IS_SLUG is live-proven:</b> I probed real pages — <span class="mono">adom-desktop</span> is
    titled literally <span class="mono">"adom-desktop"</span> and <span class="mono">adom-chipsmith</span> shows <span class="mono">"Chipsmith"</span>
    (lost its prefix), while <span class="mono">adom-usb → "Adom USB"</span>, <span class="mono">adom-lbr → "Adom Library"</span>, and
    <span class="mono">adom-concur → "Adom Concur"</span> are correct. The humanizer + a small initialism dictionary makes them consistent;
    the author can always override the suggested casing.</div>
  <div class="note" style="margin-top:8px"><b>README_SHADOWED is live-confirmed:</b> <span class="mono">adom-browser-extension</span> has
    <b>both</b> README.md + readme.html; <span class="mono">GET /pages</span> returns the README.md <i>markdown</i> in <span class="mono">readme</span>
    with no <span class="mono">rendered_readme</span> field — so an author edited README.md ~6 times and <b>none of it showed</b> (readme.html
    was winning, stale). A ~40-token push warning would have saved those six turns — the exact case the <span class="mono">Hints</span> section argues.</div>
</div>

<h2>Three moves the household CLIs can't make</h2>
<div class="grid3">
  <div class="panel ask">
    <h4>📸 Screenshots in discussions</h4>
    <p style="color:var(--mut)"><span class="mono">gh</span> can't attach an image to an issue or comment — so a bug
      report is words about a picture nobody can see. Here every
      <span class="cmd"><span class="v">discussion</span> <span class="a">create</span></span> /
      <span class="cmd"><span class="a">comment</span></span> takes <span class="mono">--image</span>, and the AI or user
      attaches the actual screenshot of the problem.</p>
  </div>
  <div class="panel ask">
    <h4>🖼 Heroes under version control</h4>
    <p style="color:var(--mut)">The hero is the AI-age app icon — and it lives <b>in the git repo</b>
      (<span class="mono">page.json</span> + the image). So it inherits
      <span class="cmd"><span class="v">hero</span> <span class="a">history</span></span>,
      <span class="cmd"><span class="a">blame</span></span> (who changed it),
      <span class="cmd"><span class="a">rollback</span></span> — and a hero change can arrive as a
      <span class="cmd"><span class="v">pr</span></span> you review and merge. No app store versions its icons.</p>
  </div>
  <div class="panel ask">
    <h4>🔭 Discoverable before install</h4>
    <p style="color:var(--mut)">A first-class <span class="mono">discover</span> pillar:
      <span class="cmd"><span class="v">discover</span> <span class="a">find</span></span> by trigger words and
      <span class="cmd"><span class="a">preview</span></span> "what would surface for X, and why" — so a brand-new,
      zero-engagement page is findable the instant it's published, not after it earns stars.</p>
  </div>
</div>

<h2>The trending score — live, and how admins steer it</h2>
<div class="panel" style="border-left:3px solid var(--new)">
  <p style="color:var(--mut);margin:0 0 10px">Each page now carries a real <span class="mono">popularity</span> block —
    earned signals roll into a <span class="mono">composite_score</span>, and an admin can hand-adjust it so the
    <b>adom-screensaver</b> billboards promote the right things. Verified live on <span class="mono">adom-usb</span> today:</p>
  <pre style="margin:0 0 10px;padding:12px 14px;background:#0c1119;border:1px solid var(--line);border-radius:10px;
    font:12.5px/1.5 ui-monospace,Menlo,monospace;color:#c7d2e0;white-space:pre-wrap">"composite_score": 70,  "install_count_30d": 18,  "commit_count_90d": 30,
"manual_score_adjustment": -50,
"manual_score_reason": "Not yet released / WIP quality — keep in wiki but suppress from screensaver promotion"</pre>
  <div class="pill-row">
    <span class="chip" style="color:var(--ok);border-color:rgba(52,211,153,.4)">earned → page star · highfive (user-facing)</span>
    <span class="chip" style="color:var(--new);border-color:rgba(251,113,133,.45)">manual → admin score --adjust (admin-only)</span>
    <span class="chip">surface → /trending (still 404 — see prompt 4)</span>
  </div>
  <div class="note">So scoring has <b>two lanes</b>: signals users legitimately <i>earn</i> (stars, high-fives, installs) live under
    <span class="mono">page</span>; the <b>manual override</b> an admin applies to demote (−) or boost (+) a page lives under
    <span class="mono">admin</span>. The field exists and is populated today — what's missing is a documented write-endpoint + the CLI verb.</div>
</div>

<h2>Homepage rotation + admin scoring — one score, two surfaces</h2>
<div class="panel" style="border-left:3px solid var(--purple)">
  <p style="color:var(--mut);margin:0 0 10px">From the <b>adom-screensaver</b> thread: the screensaver billboards and the wiki
    <b>homepage hero strip</b> should rank by the <b>same transparent, additive score</b>, so the two surfaces never disagree — and
    Colby gets an admin page to see the breakdown and tune it, exactly like the screensaver's <i>Settings → Cache</i> tab. The score is
    a <b>sum of named components</b>, never a black box; both read <span class="mono">popularity.manual_score_adjustment</span> as the
    curation lever.</p>
  <pre style="margin:0 0 10px;padding:12px 14px;background:#0c1119;border:1px solid var(--line);border-radius:10px;
    font:12px/1.55 ui-monospace,Menlo,monospace;color:#c7d2e0;white-space:pre-wrap"><span class="c">screensaver</span> = freshness + novelty<span class="d">(per-viewer)</span> + manual_score_adjustment + jitter
<span class="c">homepage</span>    = w1·recency + w2·normalize(composite_score) + manual_score_adjustment + jitter
<span class="d">freshness curve (shared):  &lt;7d 100 · &lt;30d 60 · &lt;90d 35 · &lt;365d 15 · else 5
homepage is many-viewer → popularity-weighted (w2); per-visitor novelty optional (cookie)</span></pre>
  <table>
    <tbody>
    <tr style="color:var(--dim);font-size:11px;text-transform:uppercase;letter-spacing:.08em">
      <td>piece</td><td>what</td><td class="st">state</td></tr>
    <tr><td class="cmd" style="color:var(--new)">list scores</td>
      <td class="now">expose <span class="mono">composite_score</span> + <span class="mono">manual_score_adjustment</span> + <span class="mono">updated_at</span> on
        <b>page-LIST</b> items. Today only page-detail carries <span class="mono">popularity</span>, so a consumer iterating pages must
        <b>N+1 fetch</b> — the exact turn/call waste the hints section fights. One list call should rank the whole homepage.</td>
      <td class="st"><span class="badge b-new"><span class="dot d-new"></span>new</span></td></tr>
    <tr><td class="cmd" style="color:var(--new)">weights cfg</td>
      <td class="now"><span class="mono">w1</span> (freshness) vs <span class="mono">w2</span> (popularity) as admin config, so Colby dials
        "fresh vs popular" without code. Floor stale/WIP pages via the manual nudge — don't hide them.</td>
      <td class="st"><span class="badge b-new"><span class="dot d-new"></span>new</span></td></tr>
    <tr><td class="cmd" style="color:var(--new)">/admin/scoring</td>
      <td class="now">mirror Settings → Cache: a row per page — hero thumb (+ load-current-on-demand), slug/type/title, the
        <b>full component breakdown summing to the total</b> ("fresh 100 + new 0 − admin 50"), the resulting <b>rank + homepage cutoff</b>,
        and an inline <span class="mono">manual_score_adjustment</span> control (POST <span class="mono">/api/v1/admin/pages/:slug/score</span>)
        that recomputes total + rank live. Sort by total/recency/popularity/slug/type; filter org/type; flag <span class="mono">is_stale</span>.</td>
      <td class="st"><span class="badge b-new"><span class="dot d-new"></span>new</span></td></tr>
    <tr><td class="cmd" style="color:var(--new)">home strip</td>
      <td class="now">cross-fade the top N heroes, re-sort each cycle, consuming the shared score off the (now score-bearing) list endpoint.</td>
      <td class="st"><span class="badge b-new"><span class="dot d-new"></span>new</span></td></tr>
    </tbody>
  </table>
  <div class="note"><b>CLI ties:</b> <span class="mono">admin score</span> is the lever, <span class="mono">admin score list</span> is the
    terminal mirror of <span class="mono">/admin/scoring</span>, and <span class="mono">page trending</span> is the ranked feed the
    homepage consumes. Keeping both surfaces on <b>one documented formula</b> is what keeps the screensaver and the homepage aligned —
    change the weights in one place, both rotations move together.</div>
</div>

<h2>Hero freshness — cheap change-detection for the screensaver</h2>
<div class="panel" style="border-left:3px solid var(--new)">
  <p style="color:var(--mut);margin:0 0 10px"><b>adom-screensaver</b> can't tell if a hero changed without re-downloading the
    whole image (~400 KB each). I probed the live asset to see why:</p>
  <pre style="margin:0 0 10px;padding:12px 14px;background:#0c1119;border:1px solid var(--line);border-radius:10px;
    font:12px/1.5 ui-monospace,Menlo,monospace;color:#c7d2e0;white-space:pre-wrap">HEAD …/files/screenshots/hero.png  →  200
  content-length: 400197          <span style="color:var(--ok)">✓ HEAD works (body-free)</span>
  last-modified:  Tue, 23 Jun … <span style="color:var(--part)">⚠ = serve time, not the 22nd commit — unreliable</span>
  <span style="color:var(--new)">(no etag header)                ✗ no content validator</span></pre>
  <p style="color:var(--mut);margin:0 0 4px">So a HEAD is possible, but there's no <i>trustworthy</i> cheap signal — last-modified
    moves on cache misses, and length only changes if the size does. The fix is two parts, both keyed on the hero's git blob SHA:</p>
  <table style="max-width:820px">
    <tbody>
    <tr style="color:var(--dim);font-size:11px;text-transform:uppercase;letter-spacing:.08em">
      <td>fix</td><td>what</td><td class="st">why it's right</td></tr>
    <tr><td class="cmd" style="color:var(--teal)">ETag + 304</td>
      <td class="now">asset returns <span class="mono">ETag</span> (= blob sha) + a stable <span class="mono">Last-Modified</span>
        (hero's commit time); honor <span class="mono">If-None-Match</span> → <span class="mono">304 Not Modified</span></td>
      <td class="now">saver stores the ETag, sends it, gets a ~0-byte 304 when unchanged — standard HTTP, zero client logic</td></tr>
    <tr><td class="cmd" style="color:var(--teal)">/hero meta</td>
      <td class="now"><span class="mono">GET /api/v1/pages/:slug/hero</span> → <span class="mono">{ sha256, bytes, content_type, updated_at, url }</span>
        where <span class="mono">updated_at</span> = commit time of <span class="mono">hero_path</span> specifically</td>
      <td class="now">one tiny JSON poll; compare <span class="mono">sha256</span> to what you cached — for clients that prefer explicit over HTTP caching</td></tr>
    <tr><td class="cmd" style="color:var(--part)">page hero status</td>
      <td class="now">CLI verb that prints <span class="mono">sha · updated_at · bytes</span> (one HEAD / meta call)</td>
      <td class="now">the AI &amp; saver can check from the CLI without scripting a raw request</td></tr>
    </tbody>
  </table>
  <div class="note">The page object already carries <span class="mono">last_commit_hash</span> / <span class="mono">last_commit_at</span>,
    but those move on <i>any</i> edit — we need the change signal scoped to <span class="mono">hero_path</span> alone. The blob SHA
    is the honest validator: it changes if and only if the image bytes change.</div>
</div>

<h2>Global / meta verbs (cross-cutting)</h2>
<div class="panel">
  <div class="pill-row">
    <span class="chip" style="color:var(--teal);border-color:rgba(45,212,191,.4)">api &lt;path&gt;  →  gh api  · NEW — raw /api/v1 passthrough</span>
    <span class="chip" style="color:var(--teal);border-color:rgba(45,212,191,.4)">status  →  gh status  · NEW — your open PRs/discussions across the wiki</span>
    <span class="chip">auth login · logout · token  →  gh auth  · part (token-file, no login flow)</span>
    <span class="chip">alias set · list  →  gh alias  · new</span>
    <span class="chip">secret set · list · rm  →  gh secret  · part (secrets-list)</span>
    <span class="chip">config get/set  →  npm/gh config  · ships</span>
    <span class="chip">doctor · health · sh-helpers  · ships</span>
    <span class="chip">self-update  →  gh ext upgrade  · ships</span>
  </div>
  <div class="note"><b>api</b> and <b>status</b> are the two highest-leverage adds the gh audit surfaced:
    <span class="mono">api</span> gives the AI a typed escape hatch to any endpoint a verb doesn't cover yet, and
    <span class="mono">status</span> answers "what across the whole wiki needs me right now" — open PRs on my pages,
    unanswered discussions, mentions.</div>
</div>

<h2>The help the AI reads first — progressive disclosure</h2>
<p style="color:var(--mut);max-width:76ch;margin:.2em 0 0">The AI always opens with <span class="mono">--help</span>, so make it the
  best surface in the CLI — and turn the mimic trick into documentation: <b>every line names the CLI it mirrors</b>, so one
  <span class="mono">--help</span> transfers a whole vocabulary. Default to a concise top-level map (don't dump ~80 verbs and burn
  the model's context); offer <span class="mono">--help --all</span> and <span class="mono">--help --json</span> for when it wants the lot.</p>
<div class="grid2">
  <div class="term"><span class="bar">$ <span class="cmd2">adom-wiki --help</span></span><span class="body"><span class="c">adom-wiki</span> — the Adom Wiki CLI · one wiki, eight pillars

<span class="d">USAGE</span>
  adom-wiki <span class="p">&lt;pillar&gt; &lt;verb&gt;</span> [args]
  adom-wiki <span class="p">&lt;pillar&gt;</span> <span class="y">--help</span>        <span class="d">verbs in a pillar</span>
  adom-wiki <span class="y">--help --all</span> | <span class="y">--json</span>  <span class="d">the whole tree</span>

<span class="d">PILLARS                              mirrors</span>
  <span class="c">repo</span>        clone·commit·push·rename     <span class="d">git</span>
  <span class="c">pkg</span>         install·publish·version      <span class="d">npm</span>
  <span class="c">release</span>     create·upload·download       <span class="d">gh release</span>
  <span class="c">discussion</span>  create·comment·pin <span class="y">📸</span>        <span class="d">gh issue</span>
  <span class="c">pr</span>          create·review·merge          <span class="d">gh pr</span>
  <span class="c">page</span>        hero·visibility·star·stats   <span class="d">—</span>
  <span class="c">discover</span>    search·find·triggers         <span class="d">—</span>
  <span class="c">admin</span> <span class="r">🔒</span>   score·feature·hard-delete    <span class="d">superuser</span>

<span class="d">META</span>  api · status · auth · config · doctor · lint · self-update

<span class="d">→</span> adom-wiki <span class="c">pr</span> <span class="y">--help</span>         <span class="d">a pillar's verbs</span>
<span class="d">→</span> adom-wiki <span class="c">pr</span> review <span class="y">--help</span>  <span class="d">one verb: flags + example</span></span></div>

  <div class="term"><span class="bar">$ <span class="cmd2">adom-wiki pr --help</span></span><span class="body"><span class="c">adom-wiki pr</span> — pull requests · mirrors <span class="y">`gh pr`</span>

  <span class="c">create</span>  &lt;slug&gt;          propose changes   <span class="d">gh pr create</span>
  <span class="c">list</span>    &lt;slug&gt;          open PRs          <span class="d">gh pr list</span>
  <span class="c">view</span>    &lt;id&gt;            show a PR         <span class="d">gh pr view</span>
  <span class="c">diff</span>    &lt;id&gt;            proposed diff    <span class="d">gh pr diff</span>
  <span class="c">review</span>  &lt;id&gt; --approve  approve/reject    <span class="d">gh pr review</span>
  <span class="c">comment</span> &lt;id&gt; --image   note +screenshot <span class="d">gh pr comment</span>
  <span class="c">merge</span>   &lt;id&gt;            merge it         <span class="d">gh pr merge</span>
  <span class="c">close</span>   &lt;id&gt;            close, no merge  <span class="d">gh pr close</span>

<span class="d">→</span> adom-wiki <span class="c">pr</span> review <span class="y">--help</span>

<span class="d"># adom-wiki pr review --help</span>
  <span class="c">adom-wiki pr review</span> &lt;id&gt; [<span class="y">--approve</span>|<span class="y">--request-changes</span>] [<span class="y">-b</span> &quot;…&quot;]
  <span class="d">ex:</span> adom-wiki pr review 412 --approve -b &quot;ship it&quot;</span></div>
</div>
<div class="panel" style="margin-top:14px">
  <ul style="margin:0;padding-left:18px;color:var(--mut)">
    <li><b>Three depths.</b> <span class="mono">--help</span> = 8 pillars + meta · <span class="mono">&lt;pillar&gt; --help</span> = its verbs ·
      <span class="mono">&lt;pillar&gt; &lt;verb&gt; --help</span> = flags + a real example the AI can copy.</li>
    <li><b>Knowledge transfer, free.</b> Every line prints its <span class="mono">~ git / npm / gh</span> analog — the help
      literally says "this works like <span class="mono">gh pr</span>," so the model needs no Adom-specific priming.</li>
    <li><b>Full dump on demand.</b> <span class="mono">--help --all</span> (every verb) and <span class="mono">--help --json</span>
      (machine-readable tree) — one parse for an AI that wants the whole surface, without bloating the default.</li>
    <li><b>Did-you-mean.</b> A wrong verb suggests the nearest match (git-style), so a typo self-corrects in one round-trip
      instead of a failed call.</li>
    <li><b>State:</b> adompkg has per-command help today, but no grouped pillar map, no analog hints, no
      <span class="mono">--json</span> tree, no did-you-mean. The help <i>strings</i> mostly exist; the <i>structure</i> is the new work.</li>
  </ul>
</div>

<h2>Hints — the CLI as a just-in-time skill that teaches the AI mid-task</h2>
<p style="color:var(--mut);max-width:80ch;margin:.2em 0 0">No CLI was designed for an AI consumer — they were built for humans who'd read
  the manual once. But an AI never reads the manual; it <b>guesses</b>, then <b>reads 100% of whatever the command prints</b>. That
  flips the design: stdout is the teaching surface. Instead of a giant skill doc loaded every session, the CLI returns
  <b>hints</b> — <i>progressive skill-reveal</i>: exactly the right guidance, at the moment it's relevant, populated with live data.
  The wiki already does this (I pulled <span class="mono">{level,code,message,action}</span> hints live off the API). The move is to
  make it a first-class, everywhere, <b>turn-eliminating</b> design principle.</p>

<div class="panel" style="border-left:3px solid var(--part);background:linear-gradient(180deg,rgba(251,191,36,.06),var(--bg2))">
  <h4 style="margin:0 0 6px">💸 Why this is a money argument, not a polish argument</h4>
  <p style="color:var(--mut);margin:0 0 8px">A hint costs <b>~40 tokens</b> to include and the AI reads it for free (it was reading
    the output anyway). The thing a hint <i>replaces</i> — the AI running another command to discover what the hint would have told
    it — costs a whole <b>round-trip</b>. And here's the killer: near a <b>1M-token context window, every extra turn re-sends the
    entire conversation as input</b> — roughly a million tokens, re-billed, <i>per avoided turn</i>.</p>
  <div class="pill-row">
    <span class="chip" style="color:var(--part);border-color:rgba(251,191,36,.45)">~40 tokens to emit a hint</span>
    <span class="chip" style="color:var(--new);border-color:rgba(251,113,133,.45)">~1,000,000 tokens to re-submit context for one more turn</span>
    <span class="chip" style="color:var(--ok);border-color:rgba(52,211,153,.45)">≈ 25,000× return on a single good hint</span>
  </div>
  <div class="note">At frontier input pricing that's <b>single- to low-double-digit dollars saved per avoided turn</b>. Across one
    long agentic session — dozens of avoided round-trips — that is thousands of dollars, and an agent that finishes in a third of the
    turns. Hints don't just make the CLI nicer; they make it <b>cheaper to operate at scale</b>.</div>
</div>

<p style="color:var(--mut);max-width:80ch;margin:16px 0 6px">Concretely, extend the live hint object with one field — a literal,
  ready-to-run <span class="mono">cmd</span> (and optional <span class="mono">data</span>) — so a hint isn't advice, it's the next
  action, pre-written:</p>
<pre style="margin:0 0 14px;padding:12px 14px;background:#0c1119;border:1px solid var(--line);border-radius:10px;
  font:12px/1.5 ui-monospace,Menlo,monospace;color:#c7d2e0;white-space:pre-wrap">{ "level": "reprimand", "code": "BINARY_IN_REPO",
  "message": "app.exe (PE32) doesn't belong in the git repo.",
  "action": "A Windows binary is a release asset, not repo source.",
  "data":   { "file": "app.exe", "kind": "PE32", "bytes": 8123904 },
  "cmd":    "adom-wiki release upload my-app 1.2.0 app.exe --platform windows" }   ← the AI runs this, no guessing</pre>

<h3 style="font-size:15px;color:var(--ink);margin:6px 0 0">Where hints pay off most</h3>
<div class="panel">
  <table>
    <tbody>
    <tr style="color:var(--dim);font-size:11px;text-transform:uppercase;letter-spacing:.08em">
      <td>situation</td><td>the hint returns…</td><td class="st">saves</td></tr>
    <tr><td class="now"><b>Ambiguous slug</b> — <span class="mono">info chip-fetcher</span> (real: exists under kyle &amp; john)</td>
      <td class="now">the owner list as <span class="mono">data</span> + two ready <span class="mono">cmd</span>s (<span class="mono">info kyle/…</span>, <span class="mono">info john/…</span>)</td>
      <td class="st" style="color:var(--ok)">1–2 turns<br><span class="now">(vs search to find owners)</span></td></tr>
    <tr><td class="now"><b>Version exists</b> — <span class="mono">pkg publish</span> rejected (versions are immutable)</td>
      <td class="now">"1.2.0 is published; bump first" + <span class="mono">cmd: pkg version patch &amp;&amp; pkg publish</span></td>
      <td class="st" style="color:var(--ok)">1–2 turns<br><span class="now">(vs diagnosing the error)</span></td></tr>
    <tr><td class="now"><b>Hero in README</b> — caught on <span class="mono">repo push</span></td>
      <td class="now">reprimand: "rendered twice — drop the &lt;img&gt; from README" + the right <span class="mono">page hero set</span> cmd</td>
      <td class="st" style="color:var(--ok)">a bad publish<br><span class="now">+ human-noticed redo</span></td></tr>
    <tr><td class="now"><b>Proprietary app published fully public</b></td>
      <td class="now">"source will be world-browsable" + <span class="mono">cmd: page visibility … --preset licensed</span></td>
      <td class="st" style="color:var(--ok)">a leak<br><span class="now">+ a rollback</span></td></tr>
    <tr><td class="now"><b>No discovery triggers</b> (real: <span class="mono">NO_DISCOVERY_TRIGGERS</span>)</td>
      <td class="now">"AI agents won't surface this" + <span class="mono">cmd: discover triggers … --add</span></td>
      <td class="st" style="color:var(--ok)">future invisibility<br><span class="now">(silent failure)</span></td></tr>
    <tr><td class="now"><b>Truncated list</b> — <span class="mono">discussion list</span> returns 20 of 412</td>
      <td class="now">"showing 20/412" + <span class="mono">cmd: … --limit 412 --json</span></td>
      <td class="st" style="color:var(--ok)">a blind re-call</td></tr>
    <tr><td class="now"><b>whoami / context priming</b> — real-time orgs &amp; auth state</td>
      <td class="now">your orgs inline as <span class="mono">data</span>, so later <span class="mono">--org</span> needs no lookup</td>
      <td class="st" style="color:var(--ok)">a read call<br><span class="now">on every org op</span></td></tr>
    <tr><td class="now"><b>Hero freshness</b> — <span class="mono">page hero status</span></td>
      <td class="now"><span class="mono">{sha, changed:false}</span> + "send If-None-Match &lt;etag&gt; to skip the download"</td>
      <td class="st" style="color:var(--ok)">a 400 KB<br><span class="now">re-download</span></td></tr>
    <tr><td class="now"><b>Next step</b> — after <span class="mono">repo init</span> (empty repo)</td>
      <td class="now">"repo created, empty" + <span class="mono">cmd: repo push … --files README.md</span></td>
      <td class="st" style="color:var(--ok)">the AI guessing<br><span class="now">the workflow</span></td></tr>
    <tr><td class="now"><b>Affordance reveal</b> — first <span class="mono">discussion create</span></td>
      <td class="now">"you can attach a screenshot with <span class="mono">--image</span>" — reveals a flag the AI didn't know</td>
      <td class="st" style="color:var(--ok)">a worse<br><span class="now">bug report</span></td></tr>
    <tr><td class="now"><b>Solo namespace on create</b> — <span class="mono">repo init</span> / publish under a personal owner (<span class="mono">john/</span>)</td>
      <td class="now">"created under <span class="mono">john/</span> — only you can edit this. Collaborating with someone? Create it under an org, or transfer it" + <span class="mono">cmd: repo transfer … --to-org adom</span>. If the request mentioned working <i>with</i> someone, ask: "this is solo-owned — did you mean to collaborate?"</td>
      <td class="st" style="color:var(--ok)">a re-publish<br><span class="now">+ a transfer<br>+ a frustrated user</span></td></tr>
    </tbody>
  </table>
  <div class="note" style="margin-top:8px"><b>This one's a live miss, not a hypothetical:</b> this very spec was first published to
    <span class="mono">john/adom-wiki-cli-design</span> when the whole point was to collaborate with Colby — locking him out until it was
    transferred to <span class="mono">adom/</span>. A create-time ownership hint (especially one that notices "collaborate with Colby" in
    the intent) would have caught it before the user ever had to notice. <b>Ownership &amp; collaboratability are a hint the wiki should
    volunteer at creation</b>, not something the human re-prompts for.</div>
</div>

<div class="grid2">
  <div class="panel">
    <h4>What makes a hint good (for an AI)</h4>
    <ul style="margin:0;padding-left:18px;color:var(--mut)">
      <li><b>Actionable, not advisory</b> — carry the literal <span class="mono">cmd</span> to run next, fully filled in.</li>
      <li><b>State-aware &amp; self-suppressing</b> — once the AI fixes it, the hint disappears; never nag about what's already done.</li>
      <li><b>Real-time data baked in</b> — the owner list, the latest version, the sha, your orgs — so the answer ships <i>with</i> the hint, not one call later.</li>
      <li><b>Leveled</b> — <span class="mono">info / warn / reprimand / error</span>, so the AI weights them right.</li>
      <li><b>On success AND failure</b>, and always in <span class="mono">--json</span> so they're machine-parseable.</li>
    </ul>
  </div>
  <div class="panel">
    <h4>The reframe</h4>
    <p style="color:var(--mut);margin:0">A skill doc is documentation the AI must <i>load up front and carry</i> — it costs context every
      session whether or not it's needed. <b>Hints are documentation the CLI <i>pushes</i> to the AI exactly when it's relevant,</b>
      already personalized with live data, already written as the next command.</p>
    <p style="color:var(--mut);margin:10px 0 0">So the CLI stops being a tool the AI must <i>know</i>, and becomes a tool that
      <b>teaches itself as it's used</b> — and every hint that lands is a turn that never has to happen.</p>
  </div>
</div>

<h2>Full gh-CLI audit — the rest, and what we skip on purpose</h2>
<p style="color:var(--mut);max-width:74ch;margin:.2em 0 0">Audited every <span class="mono">gh</span> command group against the design.
  The lifecycle verbs above (<span class="mono">discussion edit/reopen/pin/lock</span>,
  <span class="mono">pr review/comment/ready/reopen</span>, <span class="mono">repo edit/archive/sync</span>,
  <span class="mono">release delete-asset/verify</span>) are now folded into their pillars. What's left splits two ways:</p>
<div class="grid2">
  <div class="panel" style="border-left:3px solid var(--teal)">
    <h4>Worth adding (gh has it, we don't yet)</h4>
    <ul>
      <li><b>api</b> — <span class="mono">gh api</span> raw passthrough. The AI's escape hatch. Top pick.</li>
      <li><b>status</b> — <span class="mono">gh status</span> cross-wiki "needs me" dashboard.</li>
      <li><b>search by type</b> — <span class="mono">gh search</span> splits repos/issues/prs/code; our
        <span class="mono">discover search</span> is page-only. Add <span class="mono">--type discussions|prs|files</span>.</li>
      <li><b>label</b> — <span class="mono">gh label</span> for discussion/PR triage, once threads grow.</li>
      <li><b>repo license / gitignore</b> — template scaffolds (the page has a <span class="mono">license</span> field already).</li>
      <li><b>pr revert</b> — <span class="mono">gh pr revert</span>; a one-shot undo of a merged PR (pairs with <span class="mono">repo rollback</span>).</li>
    </ul>
  </div>
  <div class="panel" style="border-left:3px solid var(--dim)">
    <h4>Deliberately out of scope (and why)</h4>
    <ul>
      <li><b>run · workflow · cache · variable</b> — GitHub Actions / CI. The wiki has no build pipeline.</li>
      <li><b>codespace</b> — that's <b>Hydrogen Desktop</b>'s job, not the wiki CLI.</li>
      <li><b>ssh-key · gpg-key · org</b> — handled by <span class="mono">adom-cli</span> at the platform level.</li>
      <li><b>ruleset</b> — branch-protection governance; our model is owner-reviews-PR.</li>
      <li><b>gist</b> — the page is the smallest unit; no lightweight snippet tier.</li>
      <li><b>attestation</b> — partly covered by <span class="mono">pkg vouch</span> + the integrity SHA.</li>
      <li><b>project</b> — kanban boards; a real <i>maybe-later</i>, not a no.</li>
    </ul>
  </div>
</div>

<div class="grid2">
  <div class="panel">
    <h4>What's missing today (the gaps)</h4>
    <ul>
      <li><b>Discussions pillar — 0 commands.</b> The API is live
        (<span class="ana">/discussions</span>, <span class="ana">/replies</span>) but <b>text-only</b> — no image
        attach yet, the one thing a bug report most needs. CLI exposes none.</li>
      <li><b>PR pillar — 0 commands.</b> Create / list / merge / close all exist server-side; no CLI verbs.</li>
      <li><b>Git-native verbs.</b> No <span class="cmd">clone</span>, <span class="cmd">pull</span>,
        <span class="cmd">show</span>, <span class="cmd">mv</span> — editing a page means re-pushing whole files.</li>
      <li><b>Release lifecycle.</b> Have upload/list/notes; missing <span class="cmd">create</span>,
        <span class="cmd">view</span>, <span class="cmd">download</span>, <span class="cmd">edit</span>.</li>
      <li><b>Scoring surface.</b> The <span class="mono">popularity</span> block (composite_score, installs,
        <span class="mono">manual_score_adjustment</span>) is <b>live</b> — but <span class="cmd">star</span> is unwired in the CLI,
        high-five &amp; <span class="mono">/trending</span> are planned/404, and the admin score has no documented write path.</li>
    </ul>
  </div>
  <div class="panel">
    <h4>What today's <span class="mono">adompkg</span> already nails</h4>
    <ul>
      <li><b>The whole <span class="mono">npm</span> surface.</b> install · add · uninstall · update ·
        outdated · list · why · publish · pack · version · dist-tag · deprecate · link · audit · ci — 1:1.</li>
      <li><b>Page git-ops</b> as flat verbs: create · push · log · status · rm · delete/undelete · transfer · reindex.</li>
      <li><b>Hero + visibility</b> already first-class (<span class="cmd">hero</span>, <span class="cmd">visibility</span>).</li>
      <li><b>Adom extras</b> with no npm analog: vouch · verify · bootstrap · doctor · sh-helpers.</li>
    </ul>
    <div class="note">Re-cutting is mostly a <b>namespacing + alias</b> job for these, plus net-new
      <span class="mono">discussion</span> / <span class="mono">pr</span> / git verbs.</div>
  </div>
</div>

<h2>The brief, in John's words</h2>
<p style="color:var(--mut);max-width:70ch;margin:.2em 0 0">The verbatim founder prompts that drove this design —
  the unfiltered intent behind every pillar above. Read these first; the structured asks below are my synthesis of them.</p>
<div class="prompts">

  <div class="prompt john">
    <div class="phead"><span class="ptitle">1 · The CLI vision <span class="vtag">verbatim</span></span>
      <button class="copy">Copy</button></div>
    <pre>can you go read my adom-wiki-skillpack to understand the wiki and then look at adompkg to understand that cli. i'd like to brainstorm a good cli design. i see the wiki as 6 top-level items: a git repo that mimics the git cli, a pkg management system like npm so our pkg system should mimic those known commands, a releases section like github releases and so our commands should mimic github's gh cli, and then a discussion forum which i don't even know if gh supports discussions or posting of issues but if there's something known out there for discussions around repos let me know and we should mimic it, and then a pull request feature so that's like gh too. and then we do have a presentation layer to the wiki that lets us do things like manage hero images which are becoming like our app icons in an ai age and we even have a scoring system so surfaces like adom-screensaver can prioritize what order they show hero image billboards as based on trending and use the high-five and user comments to determine a trending score. so these branches i think should all have a top-level verb in the cli and then under that verb we should mimic the most common thing the ai would know from the internet community like the git cli for that branch or npm common commands from that branch. so could you create an html page that shows the hierarchy of the verbs we should support in our cli that i think we should call adom-wiki? and then compare that to the adompkg cli we have today?</pre>
  </div>

  <div class="prompt john">
    <div class="phead"><span class="ptitle">2 · discover pillar + discussion screenshots <span class="vtag">verbatim</span></span>
      <button class="copy">Copy</button></div>
    <pre>ok, yeah, add discover as a top-level pillar. i like that. and for the discussions, one of the things gh sucks with is not letting the ai or a user ad a screenshot showing the problem they're reporting so we need that to be supported</pre>
  </div>

  <div class="prompt john">
    <div class="phead"><span class="ptitle">3 · hero images under version control <span class="vtag">verbatim</span></span>
      <button class="copy">Copy</button></div>
    <pre>and for hero images, those need to be supported where the adom-wiki leverages the git repo and changelogs so you can rollback changes on the hero image or see if somebody else changed it, or get a pr for it and roll in the hero image pr request</pre>
  </div>

  <div class="prompt john">
    <div class="phead"><span class="ptitle">4 · pkg vs release + 3-layer visibility <span class="vtag">verbatim</span></span>
      <button class="copy">Copy</button></div>
    <pre>and can you help describe a bit better the difference between a pkg and a release? and we need to support public/private independently on the git repo, the pkg, and the release kind of like how github allows that under its paid plan</pre>
  </div>

  <div class="prompt john">
    <div class="phead"><span class="ptitle">5 · the admin negative trending score <span class="vtag">verbatim</span></span>
      <button class="copy">Copy</button></div>
    <pre>colby recently added a negative score i can attach to a wiki page so that the adom-screensaver can calculate a good trending score. this negative score lets an admin downplay certain stuff like adom usb that's new on the wiki but not ready for primetime, so it really shouldn't show up in places yet and get promoted</pre>
  </div>

  <div class="prompt john">
    <div class="phead"><span class="ptitle">6 · CLI to tweak scoring + an admin pillar <span class="vtag">verbatim</span></span>
      <button class="copy">Copy</button></div>
    <pre>so can you add cli commands that would help the ai and a user tweak those? that negative score should be admin only, so we may need an admin pillar</pre>
  </div>

  <div class="prompt john">
    <div class="phead"><span class="ptitle">7 · admin pillar = superuser repo ops <span class="vtag">verbatim</span></span>
      <button class="copy">Copy</button></div>
    <pre>and perhaps the admin pillar can do superuser stuff to repos</pre>
  </div>

  <div class="prompt john">
    <div class="phead"><span class="ptitle">8 · soft/hard delete + rename (mimic gh) <span class="vtag">verbatim</span></span>
      <button class="copy">Copy</button></div>
    <pre>also, i do think we need a soft-delete and a hard-delete in the cli to delete repos. i also think we should be able to rename a repo, but does gh let you do that? cuz we should mimic github</pre>
  </div>

  <div class="prompt john">
    <div class="phead"><span class="ptitle">9 · full gh-CLI audit <span class="vtag">verbatim</span></span>
      <button class="copy">Copy</button></div>
    <pre>and if we were to fully audit against the gh cli, what else might we be missing?</pre>
  </div>

  <div class="prompt john">
    <div class="phead"><span class="ptitle">10 · open vs proprietary visibility + archetypes <span class="vtag">verbatim</span></span>
      <button class="copy">Copy</button></div>
    <pre>i tend to mark some repos as full open-source like chip-fetcher so you get source code and binaries, other's i mark as licensed proprietary where the binaries are free to use by everyone like hydrogen-desktop or adom-desktop, but the source code must be hidden except for adom org members. do we have cli commands that help that definition occur?

also, we have the archetypes that i described in the wiki skillpack. should we make cli commands to support that model/structure/approach?</pre>
  </div>

  <div class="prompt john">
    <div class="phead"><span class="ptitle">11 · the wiki linter (3 examples) <span class="vtag">verbatim</span></span>
      <button class="copy">Copy</button></div>
    <pre>and then i tend to want a linter when using the wiki. do we need any cli commands for these examples below, or are we good with our existing commands:

- when the ai creates a readme, it tends to place the hero image in the readme as well cuz its lazy and thinks "oh, i created a hero image, i should add it to the readme" but the wiki page always shows the hero first and then shows the readme. so the ai constantly screws that up. the wiki cli's and api's should double check for this through a linter pass to reprimand the ai that they made that mistake and to fix it.

- the ai likes to upload binaries into the git repo. we should "lint" for that and reprimand the ai so that git repos don't get filled up with binaries and instead we give hints to the ai that this is what pkg and releases are for.

- some projects like adom-desktop have an exe that is installed on your windows computer, so that's a release, and then they also have a cli for linux that runs in the adom cloud container and wsl2 container in hydrogen-desktop. so that would mean a pkg gets created. can we have a linter or hints that help the ai understand that breakdown? like could the wiki almost test for the type of binary and send back helpful hints or even reprimands depending on what is being created as pkg or releases?</pre>
  </div>

  <div class="prompt john">
    <div class="phead"><span class="ptitle">12 · --help the AI reads first <span class="vtag">verbatim</span></span>
      <button class="copy">Copy</button></div>
    <pre>also i notice the ai always calls the cli first with a --help so can we support that to help the ai know how to use this cli each time where --help literally returns all the verbs available or if that's too much for it at least returns the toplevel verbs with info on how to call help for the sub-verbs?</pre>
  </div>

  <div class="prompt john">
    <div class="phead"><span class="ptitle">13 · hero freshness for the screensaver <span class="vtag">verbatim</span></span>
      <button class="copy">Copy</button></div>
    <pre>one issue i ran into with adom-screensaver is it couldn't easily tell if the hero image was updated, so can we add an api and cli command to check the timestamp or sha of a hero image cuz the ai said that the saver had to re-download the hero image each time to even tell if it was new</pre>
  </div>

  <div class="prompt john">
    <div class="phead"><span class="ptitle">14 · why hints matter (progressive skill-reveal) <span class="vtag">verbatim</span></span>
      <button class="copy">Copy</button></div>
    <pre>is there any way for you to think through the hints that any of these cli verbs could return to help the ai better use them? most cli's were never designed for ai, but we have found that ai guesses at stuff, but then instead of the ai reading a skill documenting the cli, its better to have hints returned in your json responses because the ai always reads all of the cli's output. so hints essentially become progressive skill revealing to the ai at the appropriate time and possibly populated with relevant real-time data. so could you make a section that talks about why hints are so important in the cli and some possible areas where you think the hints could add great value to the ai. remember another goal is help the ai not have to do as many turns. if the ai has a 1M context window and its nearing it, every turn the ai has to do to call another sub cli call results in the 1M context being resubmitted to the ai each time and burning thru tokens. our hints can save $1000's of $'s in tokens.</pre>
  </div>

  <div class="prompt john">
    <div class="phead"><span class="ptitle">15 · homepage rotation + admin scoring (from the screensaver thread) <span class="vtag">verbatim</span></span>
      <button class="copy">Copy</button></div>
    <pre>We're planning the Adom Wiki (wiki.adom.inc). I want two related things folded into the overall plan:
(A) a "featured / trending" rotation of page HERO images on the wiki HOMEPAGE, ordered by a
transparent, component-based score, and (B) an ADMIN page where Colby can SEE that score broken
down per page and tune it — the same way the Adom Screensaver's Settings → Cache tab already shows
me the score it uses to order its billboard rotation. Model it on the screensaver; here's exactly
how that works so you can adapt it.

═══ REFERENCE: how the Adom Screensaver scores its billboard rotation ═══
Each candidate hero (one per wiki page) gets an additive priority score; the rotation plays
highest-first and re-sorts each cycle. The score is deliberately a SUM OF NAMED COMPONENTS so it's
fully explainable (no black box):

  slideScore(page) = freshness + novelty + adminAdjustment + jitter

  • freshness(updated_at):   &lt;7d → 100,  &lt;30d → 60,  &lt;90d → 35,  &lt;365d → 15,  older/unknown → 5
  • novelty(slug):           max(0, 60 − 20 × timesShownToThisViewer)   // never-seen = +60; ~0 after 3 views
  • adminAdjustment:         the wiki's popularity.manual_score_adjustment for that page (e.g. −50)
  • jitter:                  random 0..12   // so ties vary run-to-run and the order isn't frozen

The screensaver READS adminAdjustment from the page-detail API
(popularity.manual_score_adjustment), folds it into the score, and shows the whole breakdown to
the user as "fresh 100 + new 0 − admin 50" with the running total. Example: I just put −50 on the
14 adom-usb pages (via POST /api/v1/admin/pages/:slug/score) and they dropped from 100 → 50 and
sank to the bottom of the rotation, while staying in the wiki. That admin lever + the visible
breakdown is exactly what I want Colby to have for the homepage.

═══ WHAT THE WIKI ALREADY HAS (adompkg 2.46.0) ═══
The page-detail response carries a `popularity` object:
  { star_count, fork_count, install_count_30d, invoke_count_30d, view_count_30d,
    commit_count_90d, discussion_count_30d, composite_score, is_stale, stale_reason,
    last_computed_at, manual_score_adjustment, manual_score_reason }
So composite_score already blends real popularity signals + the manual adjustment and survives
recompute. POST /api/v1/admin/pages/:slug/score {adjustment, reason} sets the manual nudge.
Gap: the page LIST endpoint omits `popularity`, so a consumer iterating the list (the screensaver,
or the homepage) can't see scores without a per-page fetch — please expose manual_score_adjustment
+ composite_score on list items too.

═══ (A) HOMEPAGE ROTATION SCORING ═══
Adapt the screensaver model to a MANY-viewer surface (so popularity matters more than per-user
novelty). Keep the same transparent additive structure + the admin lever:

  homepageScore(page) = w1·recencyBoost(updated_at)        // same freshness curve as above
                      + w2·normalize(composite_score)       // installs/stars/commits/views/discussions
                      + manual_score_adjustment             // Colby's curation nudge (e.g. −50, +100 to feature)
                      + smallJitter                         // keep the daily rotation varied

Rank highest-first, cross-fade N heroes on the homepage trending strip. Make the weights (w1,w2)
config so Colby can dial "freshness vs popularity." Floor stale/WIP pages via the manual nudge
rather than hiding them. (A per-session "don't repeat what this visitor just saw" novelty term is
optional — cookie-based — if you want the screensaver's de-dup feel for repeat visitors.)

═══ (B) ADMIN SCORING PAGE (mirror the screensaver's Settings → Cache tab) ═══
A new admin-only page (e.g. /admin/scoring) listing every page, sortable, each row showing:
  • the page's HERO thumbnail (+ a "load current hero" button to pull the live blob on demand)
  • slug + type capsule + title + brief
  • the FULL score broken into its named components (recency, each popularity signal, composite,
    and the manual adjustment) summing to the total — exactly like "fresh 100 + new 0 − admin 50"
  • the resulting RANK / whether it makes the homepage rotation cutoff
  • an inline control to SET manual_score_adjustment (+ reason), with the new total + rank
    recomputed live on save (calls the existing admin score endpoint)
  • sort by total / recency / popularity / slug / type; filter by org/type; flag is_stale
This is the admin's window into the same scoring the homepage uses — transparency + a tuning lever
in one place, the way the screensaver shows it to me.

═══ DELIVERABLE ═══
Fold (A) + (B) into the overall wiki plan (data model, the list-endpoint score exposure, the
weights config, the /admin/scoring page, and how the homepage trending strip consumes it). When
done, REPLY WITH A PASTE-READY PROMPT summarizing your conclusions + the concrete build steps,
that I can hand to Colby (and back to my screensaver thread so the two scoring models stay aligned).</pre>
  </div>

</div>

<h2>Prompts for Colby — the server-side gaps</h2>
<p style="color:var(--mut);max-width:70ch;margin:.2em 0 0">My synthesis of the brief above into paste-ready asks. Each is
  self-contained, names the live API state, and ends asking for a report-back prompt to wire the CLI side. Tap <b>Copy</b>.</p>
<div class="prompts">

  <div class="prompt">
    <div class="phead"><span class="ptitle"><span class="n">1 ·</span> Discussion image attachments</span>
      <button class="copy">Copy</button></div>
    <pre>Context: Adom Wiki backend (wiki.adom.inc, REST /api/v1). Discussions are live — POST /api/v1/pages/:slug/discussions creates a thread and POST /api/v1/discussions/:id/replies posts a reply — but both are TEXT-ONLY. There is no way to attach an image.

Ask: Add image attachments to discussions AND replies, so a bug report can carry the screenshot of the problem:
- Accept image uploads on create + reply (multipart, or a base64 field alongside the text), store them like page assets, and return their URLs in the payload.
- Allow multiple images per post.
- Render them inline when a thread is fetched (GET /api/v1/pages/:slug/discussions).
- Sane size cap + content-type allowlist (png/jpg/webp/gif).

This unblocks the adom-wiki CLI `discussion create --image` / `comment --image` verbs, and is the one thing GitHub's `gh issue` can't do.

Report back with: the final request/response shape for attaching + reading images, the size/type limits you chose, and a short paste-ready prompt I can drop into the adom-wiki CLI thread to wire it up.</pre>
  </div>

  <div class="prompt">
    <div class="phead"><span class="ptitle"><span class="n">2 ·</span> Independent pkg/install visibility (3rd axis)</span>
      <button class="copy">Copy</button></div>
    <pre>Context: Adom Wiki backend. Page visibility today has TWO independent layers: source (the git repo / Files tab — CLI --hide-source/--show-source) and releases (downloadable binaries — --public-releases/--private-releases).

Ask: Add a THIRD independent visibility axis for the PACKAGE / install layer — who can `adompkg install` the tarball — controllable separately from source and releases, like GitHub's granular per-feature visibility. Combinations we want:
- closed source + public install + public releases  (proprietary app, anyone can install/run)
- public source + org-only install                 (open code, internal distribution)
- any other mix of the three.

Specifically: a per-package visibility field (public | private | org), enforced at the tarball-download + resolve endpoints, independent of source and release visibility, and surfaced in page metadata so the CLI can read + set it.

Report back with: the field name + the endpoint(s) that enforce it, how it interacts with org membership, and a paste-ready prompt for the CLI thread to add `page visibility --pkg public|private|org`.</pre>
  </div>

  <div class="prompt">
    <div class="phead"><span class="ptitle"><span class="n">3 ·</span> Make /discover actually match triggers</span>
      <button class="copy">Copy</button></div>
    <pre>Context: Adom Wiki discovery. GET /api/v1/search?q= works (FTS). GET /api/v1/discover?triggers=&lt;csv&gt; is supposed to surface pages whose declared discovery_triggers match the requested phrases — but today it returns roughly the same fixed ~70-page popular set regardless of the triggers passed, so a brand-new, correct, zero-engagement page is invisible to trigger discovery until it organically earns engagement (backwards — you discover something in order to start using it). discovery_triggers ARE stored server-side (GET /api/v1/packages/:slug/manifest).

Ask:
1. Make /discover?triggers= text-relevance match the requested phrases against each page's manifest discovery_triggers, instead of returning a popular set.
2. Index triggers at publish time so a page is discoverable the instant it's published, zero engagement required.
3. Blend relevance + quality in ranking (relevance surfaces; stars/installs break ties) — a highly-relevant new page should outrank a barely-relevant popular one.
4. Exclude deprecated / soft-deleted / private pages from public discovery.

Report back with: the matching + ranking approach, two example queries with their results, and a paste-ready prompt for the CLI thread to wire `discover find &lt;triggers&gt;` and `discover preview`.</pre>
  </div>

  <div class="prompt">
    <div class="phead"><span class="ptitle"><span class="n">4 ·</span> Smaller gaps (batch — easy first)</span>
      <button class="copy">Copy</button></div>
    <pre>Context: Adom Wiki backend — a batch of smaller gaps the adom-wiki CLI design surfaced. Independent; do the easy ones first.

1. FTS hyphen bug: GET /api/v1/search?q=chip-fetcher errors "no such column: fetcher". Almost every Adom slug is hyphenated — tokenize so hyphens don't break the query.
2. GET /api/v1/trending returns 404. The per-page popularity block (composite_score, install_count_30d, manual_score_adjustment) is already live — so stand up a /trending endpoint that ranks by composite_score (honoring manual_score_adjustment), filterable by type, so adom-screensaver and the homepage can order the hero billboards.
3. Document/expose a WRITE path for manual_score_adjustment + manual_score_reason (the admin negative/positive trending override — it's populated today, e.g. adom-usb = -50, but there's no documented endpoint to set it). This backs the admin-only `admin score --adjust N --reason` verb. Also add a high-five endpoint (POST/DELETE) alongside the existing star endpoints.
4. POST /api/v1/pages/:slug/fork returns 404 — implement fork-to-your-namespace so the standard fork → PR → merge loop works (PRs already work).
5. page.json metadata.discovery_triggers pushed via /files does not persist (reads back as []). Either persist it, or document the manifest as the single source of truth and say so.

Report back with: which items shipped, the request/response shape for each new endpoint, and a paste-ready prompt for the CLI thread covering what's now wired.</pre>
  </div>

  <div class="prompt">
    <div class="phead"><span class="ptitle"><span class="n">5 ·</span> Homepage hero rotation + /admin/scoring (shared with the screensaver)</span>
      <button class="copy">Copy</button></div>
    <pre>Context: Adom Wiki (wiki.adom.inc). The adom-screensaver already ranks its billboard rotation by a transparent, additive, component-based score and reads popularity.manual_score_adjustment as the admin lever (POST /api/v1/admin/pages/:slug/score is live; page-detail carries the full `popularity` object incl. composite_score + manual_score_adjustment). We want the wiki HOMEPAGE to run the SAME model, plus an admin page to see + tune it. Keep the two surfaces on ONE documented formula so they never diverge.

Build:
1. LIST-ENDPOINT SCORE EXPOSURE (do first — everything else needs it). The page LIST endpoint omits `popularity`, so a consumer (homepage strip, screensaver) must N+1 fetch per page. Add composite_score + manual_score_adjustment + updated_at to list items so one call ranks them all.
2. WEIGHTS CONFIG. homepageScore = w1·recency(updated_at) + w2·normalize(composite_score) + manual_score_adjustment + smallJitter. Freshness curve: <7d 100, <30d 60, <90d 35, <365d 15, else 5. Make w1/w2 admin-config so Colby dials freshness vs popularity. Floor stale/WIP pages via the manual nudge, never hide them. (Optional cookie-based per-visitor novelty term for repeat-visitor de-dup.)
3. /admin/scoring PAGE (mirror the screensaver's Settings → Cache tab). One row per page: hero thumbnail (+ load-current-hero-on-demand), slug + type capsule + title + brief, the FULL score broken into named components summing to the total ("fresh 100 + new 0 − admin 50"), the resulting rank + whether it clears the homepage cutoff, and an inline control to set manual_score_adjustment + reason (calls the existing admin score endpoint) recomputing total + rank live. Sortable by total/recency/popularity/slug/type; filter by org/type; flag is_stale.
4. HOMEPAGE TRENDING STRIP. Cross-fade the top N heroes, re-sort each cycle, consuming the shared score off the now-score-bearing list endpoint.

Report back with: the list-item score fields you added, the weights-config shape, the /admin/scoring route + how it recomputes on save, and TWO paste-ready prompts — one for the adom-wiki CLI thread (to wire `admin score list` + `page trending` against the new fields) and one for the adom-screensaver thread (confirming the formula/fields so both rotations stay aligned).</pre>
  </div>

  <div class="prompt">
    <div class="phead"><span class="ptitle"><span class="n">6 ·</span> Platform-aware resolution + self-healing build-back</span>
      <button class="copy">Copy</button></div>
    <pre>Context: Adom Wiki (wiki.adom.inc). The CLI is going native on Windows, macOS, Linux & WSL2, so package/release resolution must be platform-aware AND self-healing. A wiki is third-party contribution — so a missing-platform binary should be something the asking AI can build and contribute back, making the catalog more complete the more it's used (the whole industry's build effort compounds into a shared asset).

Build (applies to BOTH packages and releases):
1. PLATFORM CONTEXT ON EVERY REQUEST. Accept an X-Adom-Platform: &lt;os&gt;-&lt;arch&gt; header (e.g. darwin-arm64, windows-x64), also reflected in the User-Agent. Default install / download / resolve to the caller's platform — never hand a Linux binary to a Windows box.
2. MANIFEST DECLARES AVAILABILITY + BUILDABILITY. Per-package/per-release: `platforms` (which targets are prebuilt), a per-target `build` recipe (the exact command to build it from source), and a `source` ref. This is what the resolver reads.
3. RESOLVE RETURNS A STRUCTURED, AI-ACTIONABLE OUTCOME (hints with literal cmds):
   - have-it      -> the asset for the caller's platform
   - agnostic     -> the platform-agnostic pkg (pure source/skill/JS)
   - needs_build  -> { source.cmd (clone), build.cmd, verify, contribute.cmd } so the AI clones, builds, verifies, and uploads
   - unavailable  -> clear reason (source private / platform unsupported / Windows-only by design)
4. CONTRIBUTE-BACK + PROVENANCE. release upload --platform &lt;x&gt; accepts a community-built binary carrying provenance { built_from_commit, sha256, built_by, toolchain }; serve it as "community-built", promotable to official via an owner/admin vouch (reuse vouch/verify + the integrity SHA) so nobody unknowingly runs a tampered cross-platform binary.

Make every response AI-native: structured, runnable, zero-guess — a missing Mac build should heal in ONE agent loop, not a filed issue.

Report back with: the platform-header + resolve-response shape, the manifest platforms/build/source fields, the contribute-back + provenance model, and a paste-ready prompt for the adom-wiki CLI thread to wire install/download platform resolution + the build-back loop.</pre>
  </div>

  <div class="prompt">
    <div class="phead"><span class="ptitle"><span class="n">7 ·</span> Breadcrumbs — first-class third-party trail markers</span>
      <button class="copy">Copy</button></div>
    <pre>Context: Adom Wiki (wiki.adom.inc). Breadcrumbs let a third party announce a related repo on someone else's ANCHOR page without edit rights (e.g. an OrCAD bridge for adom-desktop, or a community website-surfing skill for chip-fetcher / adom-browser-extension). GET /api/v1/pages/:slug/breadcrumbs is LIVE (returns {"breadcrumbs":[]}); the write path + moderation + ranking are what's missing. This is core to the wiki's third-party-contribution commons — anchors grow ecosystems their owners never manage.

Build:
1. POST WRITE PATH. POST /api/v1/pages/:anchor/breadcrumbs { to_slug, kind, title } from any authenticated user, no edit rights on the anchor required. Validate: the target page exists + is public; dedupe; rate-limit. Read it back on the anchor's breadcrumb list.
2. MODERATION (anchor owner). approve / hide / pin a breadcrumb on a repo you own — spam control for hot anchors like chip-fetcher.
3. RANKING. Rank an anchor's breadcrumbs by the same composite_score (installs/stars/vouch) so the best surface first; support a `kind` filter (bridge | surfing-skill | plugin | ...).
4. AI-FOLLOW. Surface a BREADCRUMBS_AVAILABLE hint (count + a literal follow cmd) on the anchor's page/show response, and a follow/resolve endpoint that returns the target repos (slug + kind + score + a match field) so the AI discovers + follows the trail in ONE call instead of N.
5. PROVENANCE. Record who posted, when, and the target's commit.

Make it AI-native: the AI working with an anchor should be told "there's a trail here, here's how to follow it," and publishing+breadcrumbing a new skill should be a one-flow contribution.

Report back with: the POST + moderation + follow/resolve endpoint shapes, the ranking model, the breadcrumb object fields (incl. kind + provenance), and a paste-ready prompt for the adom-wiki CLI thread to wire breadcrumb post/list/follow/approve/pin.</pre>
  </div>

  <div class="prompt">
    <div class="phead"><span class="ptitle"><span class="n">8 ·</span> Render arbitrary HTML files (not just readme.html)</span>
      <button class="copy">Copy</button></div>
    <pre>Context: Adom Wiki (wiki.adom.inc). readme.html renders nicely, but any OTHER .html file in a repo does not. Probed live on john/adom-browser-extension/files/privacy.html (a privacy policy needed for Google Web Store verification of the extension): the page route wraps it in the wiki's file-viewer chrome and shows the markup as source; the raw API (/api/v1/pages/:slug/files/privacy.html) serves Content-Type: application/octet-stream. So there is NO clean rendered URL to hand Google's verifier.

Build:
1. RENDERED VIEW IN THE FILES TAB. A Rendered/Source toggle for any .html file (sandboxed iframe), generalizing what readme.html already does to every HTML file in the repo.
2. STANDALONE CLEAN URL. A route that serves a repo .html with Content-Type: text/html and NO wiki chrome - e.g. /:owner/:slug/render/:path - a clean public page for external consumers (Google's verifier, sharing). Must work UNAUTHENTICATED for public pages (the verifier won't log in).
3. SECURITY (the reason it's octet-stream today). Render untrusted user HTML SANDBOXED - from a separate content origin/subdomain (the way GitHub serves user content off a distinct domain) or via a sandboxed iframe + strict CSP - never on the main wiki origin where it could touch session cookies.
4. CONTENT-TYPES. Serve repo assets with correct content-type by extension for public pages (text/html, text/css, image/*, application/javascript) so a rendered page's linked assets actually load.

Report back with: the render route, the sandbox/origin model, the content-type handling, whether the standalone URL works unauthenticated for public pages, and a paste-ready prompt for the adom-wiki CLI thread to wire page render &lt;slug&gt; &lt;file.html&gt; (returns the clean URL).</pre>
  </div>

  <div class="prompt">
    <div class="phead"><span class="ptitle"><span class="n">9 ·</span> README.md vs readme.html — warn, don't silently shadow</span>
      <button class="copy">Copy</button></div>
    <pre>Context: Adom Wiki (wiki.adom.inc). When a repo has BOTH README.md and a custom readme.html, the wiki renders readme.html and silently shadows README.md — with zero warning. Confirmed live on adom-browser-extension: it has both files; readme.html is what renders; GET /api/v1/pages/:slug returns `readme` = the README.md *markdown* (so the API misleads — you read it, see your markdown, assume it's live); there is NO rendered_readme / readme_source_path field; and POST /files accepts README.md edits with a 200 and no hint they won't show. Real incident: an author edited README.md ~6 times (retoning the page, swapping the hero, adding sections), pushed each OK, and none of it showed because readme.html was winning with stale content. ~6 wasted round-trips, no signal why.

Build (any/all):
1. WARN ON PUSH. On POST /api/v1/pages/:slug/files, if the commit touches README.md while readme.html exists, return a warning in the 200 response: { "ok": true, "warnings": ["You committed README.md, but readme.html exists and is what renders on this page. Your README.md change will NOT be visible. Edit readme.html, or delete it to fall back to README.md."] }
2. EXPOSE THE WINNER. Add rendered_readme: "readme.html" | "README.md" (and ideally readme_source_path) to GET /api/v1/pages/:slug, so tools/AI can check before editing. Bonus: have `readme` reflect what actually renders, or clearly label which file it is.
3. UI BADGE. In the Files tab / editor, badge the file currently being rendered ("live") so a human sees at a glance which one wins.
4. DOCUMENT PRECEDENCE. State the rule explicitly (readme.html beats README.md, or whatever it actually is) in the wiki API docs AND the adom-wiki skills — today it's tribal knowledge.

This is the textbook case for the wiki's hint/warning layer: a ~40-token warning would have saved ~6 wasted push-turns.

Report back with a paste-ready conclusions prompt summarizing: what you'll implement (push warning? rendered_readme field? UI badge?), the exact response/field shape, the documented precedence rule, and any timeline — so I can update the adom-wiki skills + tooling and the CLI thread can wire a README_SHADOWED lint that mirrors it.</pre>
  </div>

  <div class="prompt">
    <div class="phead"><span class="ptitle"><span class="n">10 ·</span> Discovery at write-time — force the snippet, then simulate it</span>
      <button class="copy">Copy</button></div>
    <pre>Context: Adom Wiki discovery quality. The best moment to author a page's discovery keywords is PUBLISH/PUSH time — the AI writing the repo has full context of the app right then. And the way to make those keywords actually good is to immediately simulate them against the whole corpus and hand the result back, so the AI self-corrects before the write is done. (Depends on /discover actually matching triggers — see the earlier discovery prompt; this is its killer app.) The wiki already stores discovery_triggers + discovery_pitch and emits NO_DISCOVERY_TRIGGERS.

Build:
1. FORCE A DISCOVERY REFRESH ON WRITE. On publish / package update (and optionally push), require fresh discovery_triggers + a discovery pitch/snippet — the phrases a typical Adom user would type that should surface this page. If absent or stale, return a hint the AI must satisfy before the write is considered clean. Elevate the existing NO_DISCOVERY_TRIGGERS nudge to a forced, every-write step.
2. SIMULATE + RETURN AS A HINT. On submit of the triggers, run them against the full corpus and return a DISCOVERY_PREVIEW hint: { your_rank, results_returned, collisions: [ { trigger, competes_with: [...] } ], weak_triggers: [...], unique_wins: [...] } so the AI sees "these triggers return 7 pages, you're #5, you collide with X/Y on 'pcb viewer'" and revises in the same loop.
3. RANK BLEND. Score by relevance + quality (composite_score) so a precise new page can win its own niche; report which triggers the page ranks #1 for vs which it's buried under.
4. AI-NATIVE. Structured hint with the simulated search + a concrete action ("drop generic 'board/viewer', lean into 'tscircuit' where you're #1"). A human would get a report; the AI gets a fix it can apply now.

This turns discovery from set-once-and-rot into self-optimizing-at-every-write — the highest-quality-wiki play.

Report back with: the forced-refresh trigger points, the exact DISCOVERY_PREVIEW hint shape, how rank + collisions are computed, and a paste-ready prompt for the adom-wiki CLI thread to wire discover check &lt;slug&gt; + the publish-time preview.</pre>
  </div>

  <div class="prompt">
    <div class="phead"><span class="ptitle"><span class="n">11 ·</span> Ownership / collaboration hint at repo creation</span>
      <button class="copy">Copy</button></div>
    <pre>Context: Adom Wiki (wiki.adom.inc). When a page/repo is created under a PERSONAL namespace (e.g. john/foo), only that user can edit it — nobody can collaborate until it's transferred to an org. The wiki gives zero signal about this at creation, so an AI happily creates a collaboration-intended page privately and the human only discovers the lockout later. Real incident: this very spec was published to john/adom-wiki-cli-design when the explicit goal was to collaborate with Colby — he was locked out until it was transferred to adom/.

Build:
1. CREATE-TIME OWNERSHIP HINT. On POST /api/v1/pages (and adompkg create / repo init), return a hint stating who can edit it: "Created under john/ (personal) — only you can edit. To collaborate, create under an org or transfer." Include cmd: adompkg transfer <slug> --to-org <org>.
2. COLLABORATION-INTENT NUDGE. If the creation context signals collaboration (a brief/description or the agent's stated intent mentioning another person, "collaborate", "with <name>", "shared"), escalate to a confirmation: "This is solo-owned — did you mean to collaborate? Move it to <org>." The AI should resolve this BEFORE the human ever sees the lockout.
3. SURFACE EDITABILITY. Expose who-can-edit on GET /api/v1/pages/:slug (owner type personal|org, + the editor set) so tools/AI can check and self-correct.
4. EASY FIX PATH. Make transfer-to-org a first-class, hinted one-liner (it exists — adompkg transfer --to-org — just surface it in the hint).

Goal: the human never has to re-prompt the AI or the wiki to "do ownership correctly" — the wiki volunteers it at creation.

Report back with: the create-response hint shape, the who-can-edit field on GET pages, how collaboration-intent is detected/passed, and a paste-ready prompt for the adom-wiki CLI thread to wire the create-time ownership hint + a SOLO_NAMESPACE check.</pre>
  </div>

  <div class="prompt">
    <div class="phead"><span class="ptitle"><span class="n">12 ·</span> README sanitizer strips &lt;video&gt; — allowlist media tags</span>
      <button class="copy">Copy</button></div>
    <pre>The wiki README markdown sanitizer strips <video> tags, so authors can't embed demo videos in a page README. Repro: adom/adom-browser-extension has 5 <video> tags in its README right now (demo/clips/use-case-*.mp4) — the blobs serve fine (HTTP 206, video/mp4, Range supported) but render as 0 video elements.

Fix is in git-wiki lib/templates.js -> MD_SANITIZE_OPTS.allowedTags:
1. Add "video" and "source" to allowedTags.
2. allowedAttributes:
   video:  ["src","controls","muted","autoplay","loop","playsinline","poster","width","height","preload","class"]
   source: ["src","type"]
3. (Optional, wanted) add sandboxed "iframe" for YouTube/Vimeo walkthroughs.

Low-risk: there's already a CSP behind the sanitizer; video/source carry no inline script. Once merged, the adom-browser-extension demos render with zero author changes — please confirm back when it's deployed so I can verify the videos play.</pre>
  </div>

  <div class="prompt">
    <div class="phead"><span class="ptitle"><span class="n">13 ·</span> Rich content rendering — 5 requirements (consolidates 8 + 12)</span>
      <button class="copy">Copy</button></div>
    <pre>Requirements for the new wiki — rich content rendering
(captured while building wiki.adom.inc/adom/adom-browser-extension, where each of these blocked us)

=== TWO HARD REQUIREMENTS ===

1) INLINE VIDEO IN A README.
   Authors must be able to embed a playable &lt;video&gt; in a page's README/markdown. Today the markdown sanitizer STRIPS &lt;video&gt;/&lt;source&gt; (lib/templates.js -> MD_SANITIZE_OPTS.allowedTags has no video/source), so our 5 demo clips vanish on render and we had to fall back to clickable poster images. Blob serving already does HTTP 206 Range on mp4, so playback works the instant the tag survives.
   - Need: allow `video` + `source` (and ideally a sandboxed `iframe` for YouTube/Vimeo) in allowedTags, with allowedAttributes —
       video:  src,controls,muted,autoplay,loop,playsinline,poster,width,height,preload,class
       source: src,type
     (A CSP already backs the sanitizer and video/source carry no inline script, so low-risk.)
   - Also allow a safe inline-style subset (or class-based styling) on img/video — we had to strip border-radius/border because the `style` attribute is filtered out.
   - Acceptance: the 5 &lt;video&gt; tags already in the adom-browser-extension README render as players (mp4s live at demo/clips/use-case-*.mp4).

2) RENDER .html FILES AS HTML (the privacy policy).
   A .html file viewed on the wiki must render as a sandboxed HTML page (with a Rendered/Raw toggle), NOT as raw &lt;pre&gt; source. Today fileView shows any non-md/non-image file as &lt;pre class="file-code"&gt;, so our privacy.html displays as code — only the .md version renders. We need a real, formatted HTML privacy-policy URL for the Chrome Web Store submission.
   - Acceptance: /adom/adom-browser-extension/files/privacy.html shows the formatted policy, not source.

=== RELATED REQUIREMENTS WE ALSO HIT (same theme: serve rich/public content correctly) ===

3) PUBLIC ASSETS ON A CLOSED-SOURCE PAGE.
   With source_visibility=private (public page + private source — our intended shipping state), EVERY repo asset except the registered hero returns 403 to logged-out users — our README images AND demo videos 403'd, so we had to keep the page fully open-source. A public product page with closed source needs its README-/hero-referenced assets (images, videos) to stay PUBLIC while the source code is sealed. Need: auto-whitelist README-referenced assets, or a /public asset dir served regardless of source visibility.

4) ORG-TRANSFER REDIRECT MUST PRESERVE SUBPATHS.
   After transferring a page to an org, the old URL /&lt;user&gt;/&lt;slug&gt;/files/&lt;path&gt; 301-redirects but DROPS the /files/&lt;path&gt; portion and lands on the page root — so every deep link (privacy policy, skill docs, store links) silently breaks. The redirect must preserve the full path: /&lt;olduser&gt;/&lt;slug&gt;/files/&lt;path&gt; -> /&lt;neworg&gt;/&lt;slug&gt;/files/&lt;path&gt;. (Verified live: /john/adom-browser-extension/files/privacy.html 301s to /adom/adom-browser-extension, dropping the file path.)

5) LARGER BINARY UPLOADS.
   The JSON files API returns 413 above ~3.5 MB, so we had to down-res the demo videos to fit. Support multipart/streaming upload (or raise the cap) so demo videos and other assets push at full quality. (Note: the adompkg CLI push already streams multipart up to 100MB — so routing the JSON/base64 + web-UI path through multipart, or raising its cap, closes this.)

Live repro / test page for all of the above: wiki.adom.inc/adom/adom-browser-extension
(README has the stripped &lt;video&gt; tags + poster fallbacks; privacy.html renders as raw code; the page is open-source only because closing the source 403'd the demo assets).

When you've scoped/landed these, send back a paste-ready summary of exactly what changed and the behavior authors can now rely on, so I can flip the extension page over to real inline video + the rendered HTML privacy policy and remove the placeholder workarounds.</pre>
  </div>

</div>

<h2>Native everywhere — the compiled CLI suite</h2>
<p style="color:var(--mut);max-width:80ch;margin:.2em 0 0">The wiki is becoming <b>pervasive</b> — not a cloud-container-only tool.
  You drive it from <b>native Windows</b> while on Cloud / Hydrogen Desktop; <b>Kyle drives it from native macOS</b>; AIs drive it from
  the Adom cloud container and the WSL2 box inside Hydrogen Desktop. So <span class="mono">adom-wiki</span> can't be a Node script that
  assumes a runtime — it ships as a <b>suite of compiled, single-file binaries</b>, one per OS/arch, behaviour-identical, all talking
  to the same <span class="mono">wiki.adom.inc</span> API.</p>

<h3 style="font-size:15px;color:var(--ink);margin:14px 0 0">Why native — who runs it, and where</h3>
<div class="grid2" style="margin-top:8px">
  <div class="panel" style="border-left:3px solid var(--blue)">
    <h4>🪟 John · native Windows (on Cloud / Hydrogen Desktop)</h4>
    <ul style="margin:0;padding-left:18px;color:var(--mut)">
      <li>Just code-signed a Windows <span class="mono">.exe</span>/<span class="mono">.msi</span> installer on the Windows box →
        <span class="mono">adom-wiki release upload … --platform windows</span> straight from PowerShell — <b>no shuttling the signed
        binary into a container</b> first.</li>
      <li>Working in native <b>KiCad / Fusion</b>, export a footprint or 3D model → <span class="mono">adom-wiki search</span> for an
        existing one, or <span class="mono">pkg publish</span> the new one, right there.</li>
      <li>Mid-task <span class="mono">adom-wiki search</span> / <span class="mono">pkg install</span> from a Windows terminal — no
        container round-trip, no latency.</li>
    </ul>
  </div>
  <div class="panel" style="border-left:3px solid var(--teal)">
    <h4>🍎 Kyle · native macOS</h4>
    <ul style="margin:0;padding-left:18px;color:var(--mut)">
      <li>Builds the <b>Mac port of adom-browser-extension</b> → a <span class="mono">.app</span>/<span class="mono">.dmg</span>, then
        <span class="mono">adom-wiki release upload … --platform macos</span> from the Mac terminal (code-signing happens on the Mac).</li>
      <li>Searches and <span class="mono">install</span>s skills, molecules &amp; footprints from the wiki while coding on macOS.</li>
      <li>Opens, reviews &amp; merges <span class="mono">pr</span>s and runs <span class="mono">lint</span> on his own pages — natively, no container.</li>
    </ul>
  </div>
  <div class="panel" style="border-left:3px solid var(--purple)">
    <h4>🖥️ Native apps that consume the wiki (no human at a terminal)</h4>
    <ul style="margin:0;padding-left:18px;color:var(--mut)">
      <li><b>adom-screensaver</b> (a native Windows <span class="mono">.scr</span>) queries the wiki for hero freshness + scoring to order
        its billboards — natively, every cycle, no container to wake.</li>
      <li><b>Hydrogen Desktop</b> (the Win/Mac app) bakes the CLI in to <span class="mono">self-update</span>, install packages, and pull
        heroes for its installer &amp; homepage — natively.</li>
    </ul>
  </div>
  <div class="panel" style="border-left:3px solid var(--dim)">
    <h4>⚙️ Build &amp; CI on every OS</h4>
    <ul style="margin:0;padding-left:18px;color:var(--mut)">
      <li>Windows / macOS / Linux CI runners each publish <b>their</b> per-platform release with the matching native binary —
        the build OS <i>is</i> the release OS, so the CLI has to run there.</li>
      <li>Any AI driving the native desktop (KiCad, Fusion, the real browser) calls the wiki CLI <b>in-place</b> instead of routing every
        wiki action back through the container.</li>
    </ul>
  </div>
</div>

<div class="grid2">
  <div class="panel">
    <h4>The build matrix</h4>
    <table>
      <tbody>
      <tr style="color:var(--dim);font-size:11px;text-transform:uppercase;letter-spacing:.08em"><td>target</td><td>built for</td><td class="st">runtime</td></tr>
      <tr><td class="cmd">windows-x64</td><td class="now">John's native Windows (Cloud Desktop) — PowerShell + cmd</td><td class="st now">none</td></tr>
      <tr><td class="cmd">darwin-arm64</td><td class="now">Kyle's Mac — Apple Silicon</td><td class="st now">none</td></tr>
      <tr><td class="cmd">darwin-x64</td><td class="now">Intel Macs</td><td class="st now">none</td></tr>
      <tr><td class="cmd">linux-x64</td><td class="now">Adom cloud container · CI · WSL2 inside HD</td><td class="st now">none</td></tr>
      <tr><td class="cmd">linux-arm64</td><td class="now">arm cloud / arm WSL2</td><td class="st now">none</td></tr>
      </tbody>
    </table>
    <div class="note">Each is a <b>static single-file executable</b> — no Node, no Bun, nothing to install on the user's machine.</div>
  </div>
  <div class="panel">
    <h4>How — and it dogfoods the wiki</h4>
    <ul style="margin:0;padding-left:18px;color:var(--mut)">
      <li><b>One source, N binaries.</b> adompkg is already JS/ESM → <span class="mono">bun build --compile --target=bun-&lt;os&gt;-&lt;arch&gt;</span>
        cross-builds them all (Bun's already in the toolchain). Reuses the 5,700 lines as-is. <span class="d">(Alt: Node SEA / pkg, or a Rust rewrite — v1 was Rust.)</span></li>
      <li><b>The CLI distributes itself.</b> <span class="mono">adom-wiki</span> is a wiki <b>page</b> whose <b>releases</b> are the
        per-platform binaries (<span class="mono">release upload … --platform windows|macos|linux</span> — the API already supports this),
        and <span class="mono">self-update</span> pulls the matching one. Exactly the pkg-vs-release + multi-platform model from above.</li>
      <li><b>Pre-placed where it's needed.</b> HD's golden image bakes the linux build; native installers drop the win/mac builds on PATH.</li>
    </ul>
  </div>
</div>
<div class="panel" style="border-left:3px solid var(--part);margin-top:14px">
  <h4>What going native forces us to nail</h4>
  <ul style="margin:0;padding-left:18px;color:var(--mut)">
    <li><b>Auth / token store.</b> Off-container there's no <span class="mono">/var/run/adom/api-key</span> — native needs
      <span class="mono">auth login</span> + an OS token store (Keychain / Windows Credential Manager / <span class="mono">~/.config</span>).
      This is the gh-style auth flow flagged <i>partial</i> earlier — native is what makes it mandatory.</li>
    <li><b>Identical surface + hints on every OS</b> — same verbs, same <span class="mono">--json</span>, same hint engine — so an AI behaves the same whether it's on Windows, Mac, the container, or WSL2.</li>
    <li><b>One version of truth.</b> <span class="mono">self-update</span> + <span class="mono">--version</span> keep all binaries on the same wiki release; the wiki is the source of truth, the same way it is for every other package.</li>
  </ul>
</div>

<h2>Platform-aware resolution — and a catalog that heals itself</h2>
<p style="color:var(--mut);max-width:80ch;margin:.2em 0 0">Once the CLI is native everywhere, it has to be <b>smart about platform</b>. Every request announces the caller's
  OS/arch (a <span class="mono">X-Adom-Platform: darwin-arm64</span> header, also in the User-Agent), so the wiki resolves to the
  <i>right</i> artifact — <b>never hand a Linux binary to a Windows box.</b> This is true for <b>packages and releases alike</b> —
  each declares what it has per platform. And when there's no prebuilt binary for the caller's
  platform, the wiki doesn't just 404 — it hands the AI everything it needs to <b>build it and contribute the result back</b>, so the
  next person on that platform gets it prebuilt. The catalog heals through use. This must be <b>AI-native</b>: structured, runnable, in the spec.</p>
<div class="panel">
  <h4>What the wiki returns, by what it finds</h4>
  <table>
    <tbody>
    <tr style="color:var(--dim);font-size:11px;text-transform:uppercase;letter-spacing:.08em"><td>caller asks (platform X)</td><td>wiki finds…</td><td class="st">wiki returns</td></tr>
    <tr><td class="now"><span class="mono">install</span> / <span class="mono">release download</span></td>
      <td class="now">a prebuilt asset for <b>X</b></td>
      <td class="st" style="color:var(--ok)">the asset — done, no guessing</td></tr>
    <tr><td class="now">↳</td>
      <td class="now">a <b>platform-agnostic</b> pkg (pure source / skill / JS)</td>
      <td class="st" style="color:var(--ok)">the pkg — no platform concern</td></tr>
    <tr><td class="now">↳</td>
      <td class="now"><b>no X binary</b>, but source + a build recipe exist</td>
      <td class="st" style="color:var(--part)">a <b>build-it hint</b>: source + build cmd + verify + the contribute-back cmd</td></tr>
    <tr><td class="now">↳</td>
      <td class="now"><b>no X binary</b>, source private / platform unsupported</td>
      <td class="st" style="color:var(--new)">clear "not available for X" + <i>why</i> (Windows-only by design / ask owner)</td></tr>
    </tbody>
  </table>
</div>
<p style="color:var(--mut);max-width:80ch;margin:14px 0 6px">The third row is the magic. A Mac asks for <span class="mono">adom-desktop</span>;
  only windows + linux are prebuilt. Instead of failing, the wiki returns a recipe the AI just <i>runs</i> — and the
  <span class="mono">contribute</span> line means the Mac build now exists for everyone after:</p>
<pre style="margin:0 0 12px;padding:13px 14px;background:#0c1119;border:1px solid var(--line);border-radius:10px;
  font:12px/1.55 ui-monospace,Menlo,monospace;color:#c7d2e0;white-space:pre-wrap"><span class="d">$</span> adom-wiki pkg install adom-desktop        <span class="d"># called from a Mac → X-Adom-Platform: darwin-arm64</span>
{ "status":     "needs_build",
  "reason":     "no prebuilt darwin-arm64 release; windows + linux exist",
  "source":     { "ref": "v1.4.0", "cmd": "adom-wiki repo clone adom-desktop" },
  "build":      { "cmd": "bun build --compile --target=bun-darwin-arm64 ./cli.ts --outfile adom-desktop" },
  "verify":     "./adom-desktop --version        # expect 1.4.0",
  "contribute": "adom-wiki release upload adom-desktop 1.4.0 ./adom-desktop --platform macos",
  "hint":       "No Mac build yet — clone, build, verify, then upload so the next Mac user gets it prebuilt." }</pre>
<div class="grid2">
  <div class="panel">
    <h4>Why this is in the AI spec, not a docs page</h4>
    <p style="color:var(--mut);margin:0">A human hitting "no Mac build" files an issue and waits days. <b>An AI gets a runnable recipe
      and heals the catalog in one loop</b> — clone, build, verify, upload. The response is structured hints with literal
      <span class="mono">cmd</span>s (the same engine as the <span class="mono">Hints</span> section), so it costs the AI zero guess-turns.</p>
  </div>
  <div class="panel">
    <h4>Trust — a contributed binary isn't blindly served</h4>
    <p style="color:var(--mut);margin:0">Each build-back carries <b>provenance</b> — <span class="mono">{ built_from_commit, sha256, built_by, toolchain }</span> —
      and lands as <b>community-built</b>, promotable to official by an owner/admin <span class="mono">vouch</span> (reusing
      <span class="mono">vouch</span> / <span class="mono">verify</span> + the integrity SHA). A Windows user never unknowingly runs a tampered Mac binary.</p>
  </div>
</div>
<div class="note" style="margin-top:8px"><b>Manifest carries the truth:</b> a package declares <span class="mono">platforms</span> (which are prebuilt),
  a per-target <span class="mono">build</span> recipe, and the <span class="mono">source</span> ref — that's what drives the decision tree above.
  <span class="mono">adom-desktop</span> is the canonical case: a Windows <span class="mono">.exe</span> release + a Linux CLI pkg, and a Mac that builds-on-demand
  the first time someone asks.</p></div>

<div class="panel" style="border-left:3px solid var(--purple);background:linear-gradient(180deg,rgba(168,85,247,.06),var(--bg2));margin-top:14px">
  <h4 style="margin:0 0 6px">🌐 The compounding commons — why this <i>is</i> the point of a wiki</h4>
  <p style="color:var(--mut);margin:0 0 8px">A wiki is <b>third-party contribution</b>, and platform build-back is that mechanic at its
    highest leverage. The <b>first</b> Mac user's AI spends the tokens to build <span class="mono">adom-desktop</span> once — and
    <b>every Mac user after gets it instantly prebuilt</b>. The same for every package, every release, every platform.</p>
  <p style="color:var(--mut);margin:0 0 8px">Scale that across the <b>entire electronics industry</b>: every AI and every third-party user that
    builds a missing artifact contributes it back, so <b>the catalog gets more complete the more it's used</b>. The wiki turns the
    industry's distributed token &amp; compute spend into a shared, compounding asset — that spend isn't burned, it's
    <b>deposited back as durable binaries + provenance</b>. We all benefit.</p>
  <div class="pill-row">
    <span class="chip" style="color:var(--purple);border-color:rgba(168,85,247,.45)">more use → more platforms filled in → more value → more use</span>
    <span class="chip">a network effect, paid for by tokens that would've been spent anyway</span>
  </div>
</div>

<h2>Breadcrumbs — third parties extend an anchor, the AI follows the trail</h2>
<p style="color:var(--mut);max-width:80ch;margin:.2em 0 0">A <b>breadcrumb</b> is a small trail-marker a third party drops on
  <i>someone else's</i> anchor repo to announce a related thing they built — a bridge, a surfing skill, a plugin — <b>without edit
  rights</b> on that repo. The anchor surfaces them; the AI sees "there's a trail here" and follows it. <span class="mono">GET
  /api/v1/pages/:slug/breadcrumbs</span> is already live — the write path + moderation is what we firm up. This is the
  <b>compounding commons applied to discovery</b>: an anchor grows an ecosystem its owner never has to manage. <span class="d">(Closest
  known model: webmention / trackback.)</span></p>
<div class="grid2" style="margin-top:10px">
  <div class="panel" style="border-left:3px solid var(--blue)">
    <h4>🔌 adom-desktop · 3rd-party bridges</h4>
    <p style="color:var(--mut);margin:0">We want an <b>OrCAD bridge, a MATLAB bridge, a desktop-oscilloscope bridge</b> — each a repo
      owned &amp; maintained by a third party. adom-desktop can't enumerate them all. Each bridge <b>drops a breadcrumb on
      adom-desktop</b>; an AI working with adom-desktop sees the trail and follows it to the right bridge. No coordination, no edit rights.</p>
  </div>
  <div class="panel" style="border-left:3px solid var(--teal)">
    <h4>🔎 chip-fetcher · community surfing skills</h4>
    <p style="color:var(--mut);margin:0">chip-fetcher crawls <b>thousands of sites</b> — Adom will never build a skill for each. A user
      vibe-prompts a skill while surfing <b>Bosch's electronics site</b>; the AI says "great skill — let's publish it and breadcrumb it
      on chip-fetcher," and <b>every Adom user instantly benefits</b> the next time they hit that site.</p>
  </div>
  <div class="panel" style="border-left:3px solid var(--purple)">
    <h4>🌐 adom-browser-extension · surfing skills for any site</h4>
    <p style="color:var(--mut);margin:0">Same model, <b>any website</b> the extension navigates. The community posts site-navigation
      skills as breadcrumbs on the extension's anchor; the extension's AI follows the trail to the right skill for the site it's on.</p>
  </div>
  <div class="panel" style="border-left:3px solid var(--dim)">
    <h4>🧹 Keeping a hot anchor clean</h4>
    <p style="color:var(--mut);margin:0">A popular anchor (chip-fetcher) will attract spam. Breadcrumbs are <b>open to post</b> but
      <b>owner-moderatable</b> (<span class="mono">approve / hide / pin</span>) and <b>ranked by the same composite_score</b>
      (installs/stars/vouch) — so the best surfing skills surface first and junk sinks.</p>
  </div>
</div>
<p style="color:var(--mut);max-width:80ch;margin:14px 0 6px">AI-native, as ever: the anchor's response carries a hint so the AI
  <i>discovers the trail</i> at the right moment, and contributing back is one flow:</p>
<pre style="margin:0 0 8px;padding:13px 14px;background:#0c1119;border:1px solid var(--line);border-radius:10px;
  font:12px/1.55 ui-monospace,Menlo,monospace;color:#c7d2e0;white-space:pre-wrap"><span class="d">$</span> adom-wiki repo show chip-fetcher        <span class="d"># AI is about to fetch from a new site</span>
{ "hints": [ { "code": "BREADCRUMBS_AVAILABLE", "data": { "count": 37 },
    "message": "37 community surfing skills are breadcrumbed here.",
    "cmd": "adom-wiki breadcrumb follow chip-fetcher --kind surfing-skill --match bosch.com" } ] }

<span class="d"># the user just made a new one — publish + breadcrumb in one flow:</span>
<span class="d">$</span> adom-wiki pkg publish bosch-surf-skill
<span class="d">$</span> adom-wiki breadcrumb post chip-fetcher --to bosch-surf-skill --kind surfing-skill
  <span class="d">→ the commons grows by one; every Adom user benefits next time they hit bosch.com</span></pre>
<div class="note">Breadcrumbs are the discovery glue for the <b>Family</b> archetype with third-party children, and they feed the
  <span class="mono">discover</span> pillar — together they answer "what extends this, and where's the trail?"</div>

<h2>Render any HTML file — static pages, not source dumps</h2>
<p style="color:var(--mut);max-width:80ch;margin:.2em 0 0">The wiki renders <span class="mono">readme.html</span> beautifully — but
  <i>any other</i> <span class="mono">.html</span> file in a repo doesn't render, it gets dumped as source. Real, blocking case:
  <span class="mono">john/adom-browser-extension/files/privacy.html</span> — a privacy policy needed for <b>Google Web Store
  verification</b> of the extension, with nowhere clean to point Google. I probed it:</p>
<pre style="margin:10px 0;padding:12px 14px;background:#0c1119;border:1px solid var(--line);border-radius:10px;
  font:12px/1.5 ui-monospace,Menlo,monospace;color:#c7d2e0;white-space:pre-wrap">GET /john/adom-browser-extension/files/privacy.html
  <span style="color:var(--new)">→ wrapped in wiki file-viewer chrome ("…- privacy.html - Adom Wiki", /static/style.css) — shows markup, doesn't render</span>
GET /api/v1/pages/adom-browser-extension/files/privacy.html
  <span style="color:var(--new)">→ content-type: application/octet-stream — even the raw URL won't render in a browser</span></pre>
<div class="grid2">
  <div class="panel" style="border-left:3px solid var(--teal)">
    <h4>Mode 1 · Rendered in the wiki</h4>
    <p style="color:var(--mut);margin:0">A <b>Rendered / Source toggle</b> on the Files tab for any <span class="mono">.html</span> (sandboxed iframe) —
      generalizing what <span class="mono">readme.html</span> already does to every HTML file. View it nicely <i>inside</i> the wiki.</p>
  </div>
  <div class="panel" style="border-left:3px solid var(--purple)">
    <h4>Mode 2 · Standalone clean URL</h4>
    <p style="color:var(--mut);margin:0">Serve the <span class="mono">.html</span> with <span class="mono">Content-Type: text/html</span> and
      <b>no wiki chrome</b> — e.g. <span class="mono">/john/adom-browser-extension/render/privacy.html</span> — a clean public page for
      external consumers (Google's verifier, sharing, linking). Must work <b>unauthenticated</b> for public pages.</p>
  </div>
</div>
<div class="panel" style="border-left:3px solid var(--new);margin-top:14px">
  <h4>The catch — and almost certainly why it's octet-stream today</h4>
  <p style="color:var(--mut);margin:0">Rendering <b>untrusted user HTML</b> on the main wiki origin, with the visitor's session cookies in
    scope, is an XSS hole. So it must be <b>sandboxed</b>: a separate content origin / subdomain (the way GitHub serves user content off a
    distinct domain) <i>or</i> a sandboxed iframe + strict CSP, so a malicious page can never reach wiki auth. Serving
    <span class="mono">application/octet-stream</span> is the safe-but-useless default; the fix is "render, but sandboxed." A <b>CLI tie:</b>
    <span class="mono">page render &lt;slug&gt; &lt;file.html&gt;</span> returns the clean rendered URL, and lint can flag a linked
    <span class="mono">.html</span> that won't render.</p>
</div>
<div class="panel" style="border-left:3px solid var(--new);margin-top:14px">
  <h4>Sibling gap — the README markdown sanitizer strips media tags</h4>
  <p style="color:var(--mut);margin:0">Same family of problem, different surface: the <b>README markdown</b> sanitizer drops
    <span class="mono">&lt;video&gt;</span> / <span class="mono">&lt;source&gt;</span> (and iframes), so authors can't embed demo videos.
    Verified live — <span class="mono">adom/adom-browser-extension</span> has <b>5 <span class="mono">&lt;video&gt;</span> tags</b> in its
    README and the blobs serve fine (HTTP 206, <span class="mono">video/mp4</span>, Range), yet <b>0 video elements render</b>. The fix is a
    one-line allowlist add (<span class="mono">video</span>, <span class="mono">source</span>, sandboxed <span class="mono">iframe</span> for
    YouTube/Vimeo) in the sanitizer — low risk, since the CSP is already behind it and media tags carry no inline script. → <b>Colby prompt 12.</b></p>
</div>

<h2>Rich content rendering — the 5 author requirements</h2>
<p style="color:var(--mut);max-width:80ch;margin:.2em 0 0">Captured while building the live repro page
  <span class="mono">adom/adom-browser-extension</span>, where each of these blocked shipping. Two hard requirements (inline video +
  real <span class="mono">.html</span> render) plus three that share one theme — <i>serve rich/public content correctly</i>. Marked
  <span style="color:var(--ok)">✓</span> where I reproduced it live. Full detail + the exact sanitizer diff → <b>Colby prompt 13.</b></p>
<div class="panel">
  <table>
    <tbody>
    <tr style="color:var(--dim);font-size:11px;text-transform:uppercase;letter-spacing:.08em"><td>#</td><td>requirement</td><td>acceptance</td><td class="st">repro</td></tr>
    <tr><td class="cmd">1</td>
      <td class="now"><b>Inline <span class="mono">&lt;video&gt;</span> in a README</b> — allow <span class="mono">video</span>/<span class="mono">source</span> (+ sandboxed iframe) and a safe inline-style/class subset on img/video</td>
      <td class="now">the 5 <span class="mono">&lt;video&gt;</span> tags in the abe README render as players</td>
      <td class="st" style="color:var(--ok)">✓ 5→0</td></tr>
    <tr><td class="cmd">2</td>
      <td class="now"><b>Render <span class="mono">.html</span> as sandboxed HTML</b> (Rendered/Raw toggle), not <span class="mono">&lt;pre class="file-code"&gt;</span> source</td>
      <td class="now"><span class="mono">…/files/privacy.html</span> shows the formatted policy (Chrome Web Store needs it)</td>
      <td class="st" style="color:var(--ok)">✓ raw</td></tr>
    <tr><td class="cmd">3</td>
      <td class="now"><b>Public assets on a closed-source page</b> — with <span class="mono">source_visibility=private</span>, every asset but the hero 403s to logged-out users</td>
      <td class="now">README-/hero-referenced imgs+videos stay public while source is sealed (auto-whitelist or a <span class="mono">/public</span> dir)</td>
      <td class="st" style="color:var(--part)">per repro</td></tr>
    <tr><td class="cmd">4</td>
      <td class="now"><b>Org-transfer redirect preserves subpaths</b> — today the 301 drops <span class="mono">/files/&lt;path&gt;</span> and lands on the page root</td>
      <td class="now">deep links (privacy policy, store links, skill docs) survive a transfer</td>
      <td class="st" style="color:var(--ok)">✓ drops</td></tr>
    <tr><td class="cmd">5</td>
      <td class="now"><b>Larger binary uploads</b> — the JSON files API 413s above ~3.5 MB, forcing down-res'd demo videos</td>
      <td class="now">full-res videos/assets push (multipart/streaming or a raised cap)</td>
      <td class="st" style="color:var(--part)">per repro</td></tr>
    </tbody>
  </table>
  <div class="note"><b>#4 bit this very page:</b> moving <span class="mono">adom-wiki-cli-design</span> john→adom broke its old
    <span class="mono">/john/…/files/*</span> deep links (they now drop to the page root) — verified
    <span class="mono">/john/adom-browser-extension/files/privacy.html → 301 /adom/adom-browser-extension</span>.
    <b>#5 note:</b> the <span class="mono">adompkg</span> CLI push already streams multipart up to 100 MB — so the gap is the JSON/base64 +
    web-UI path; routing it through multipart (or raising the cap) closes it. <b>#1 + #2</b> consolidate &amp; expand
    prompts 8 and 12.</div>
</div>

<h2>Discovery at write-time — generate the snippet, then prove it against the corpus</h2>
<p style="color:var(--mut);max-width:80ch;margin:.2em 0 0">The best moment to author a page's discovery keywords is the
  instant of <b>publish</b> — the AI writing the repo has <b>full context of the app right then</b>; nobody will ever understand it
  better. So <span class="mono">publish / push / update</span> should <b>force a fresh discovery snippet</b>: the triggers + pitch a
  typical Adom user would type to surface this page. Set-once-and-rot is how pages go invisible; forcing it on <i>every</i> write keeps
  the wiki's discoverability as good as its latest author. <span class="d">(The wiki already stores
  <span class="mono">discovery_triggers</span> + <span class="mono">discovery_pitch</span> and emits a
  <span class="mono">NO_DISCOVERY_TRIGGERS</span> hint — this elevates that nudge to a forced, every-write step.)</span></p>
<p style="color:var(--mut);max-width:80ch;margin:10px 0 6px">But don't just <i>accept</i> the keywords — <b>prove them.</b> Run the
  proposed triggers against the whole corpus and hand the <b>simulated search result back in the hints</b>, so the AI self-corrects
  before the write is even done:</p>
<pre style="margin:0 0 12px;padding:13px 14px;background:#0c1119;border:1px solid var(--line);border-radius:10px;
  font:12px/1.55 ui-monospace,Menlo,monospace;color:#c7d2e0;white-space:pre-wrap"><span class="d">$</span> adom-wiki pkg publish adom-tsci
{ "ok": true, "hints": [ { "code": "DISCOVERY_PREVIEW",
    "message": "Your 8 triggers were simulated against 1,240 pages.",
    "data": { "your_rank": 5, "results_returned": 7,
              "collisions":    [ { "trigger": "pcb viewer", "competes_with": ["adom-3d-viewer","chipfit"] } ],
              "weak_triggers": ["board","viewer"],
              "unique_wins":   ["tscircuit","autorouter rerun"] },
    "action": "Rank #5 for your OWN triggers — drop generic 'board/viewer', lean into 'tscircuit/autorouter' where you're #1." } ] }</pre>
<div class="grid2">
  <div class="panel" style="border-left:3px solid var(--teal)">
    <h4>Force it at the richest moment</h4>
    <p style="color:var(--mut);margin:0">The AI just built the app — it knows the exact phrases a user would ask for. Capturing the
      snippet <i>then</i>, and re-confirming on every update, beats any after-the-fact SEO. The wiki self-optimizes its own findability,
      authored by whoever understands each page best at the time.</p>
  </div>
  <div class="panel" style="border-left:3px solid var(--purple)">
    <h4>Close the loop with a collision check</h4>
    <p style="color:var(--mut);margin:0">The realization John wants the AI to have — <i>"oh crap, these keywords return 7 apps and I'm
      not even top-3, they collide with X/Y — let me revise"</i> — happens automatically, in the publish loop, instead of after months of
      "why isn't my page found." Discovery fixed before a single user misses it.</p>
  </div>
</div>
<div class="note" style="margin-top:8px"><b>Dependency + payoff:</b> the collision check needs <span class="mono">/discover</span> to actually
  match triggers (Colby prompt 3) — and this is its <b>killer app</b>. It's <span class="mono">discover preview</span> made automatic +
  adversarial, ranked by relevance blended with <span class="mono">composite_score</span>, surfaced via the hint layer. The
  highest-quality-wiki play: the AI determines the best discovery, <i>validated against reality</i>, at the moment of richest context, every write.</div>

<h2>The plan — how this actually gets built</h2>
<p style="color:var(--mut);max-width:78ch;margin:.2em 0 0">Everything above, sequenced. The trick: <b>most of the
  restructure is client-only and ships without touching the backend</b> — so Track A (CLI) starts now, Track B (server) lands
  in parallel, and Track C (distribution — <b>compiling the native suite for every OS</b>) runs cross-cutting alongside both.
  Owner tags: <span class="owner o-cli">CLI</span> client-side only ·
  <span class="owner o-srv">SERVER</span> needs Colby · <span class="owner o-both">BOTH</span> client + server.</p>
<div class="panel" style="border-left:3px solid var(--teal);margin-top:12px">
  <h4 style="margin:0 0 8px">Principles holding it together</h4>
  <ul style="margin:0;padding-left:18px;color:var(--mut)">
    <li><b>Muscle-memory first</b> — <span class="mono">adom-wiki &lt;pillar&gt; &lt;verb&gt;</span>, each pillar mirrors a known CLI;
      <span class="mono">adompkg</span> stays an alias for <span class="mono">pkg</span> so nothing breaks.</li>
    <li><b>CLI wins before server work</b> — re-homing 52 verbs + lighting up discussion/pr over live APIs needs zero backend change.</li>
    <li><b>Two-layer always</b> — lint &amp; reprimands run client-side <i>and</i> in the server hints engine, so direct-API writes get caught too.</li>
    <li><b>Cheap by default</b> — progressive <span class="mono">--help</span>, conditional fetch (ETag/304), metadata over re-download.</li>
    <li><b>No pillar for cross-cutting concerns</b> — visibility presets, archetypes, lint are flags/verbs, not new pillars.</li>
    <li><b>Native everywhere</b> — one behaviour on Windows, macOS, Linux &amp; WSL2; the CLI ships as compiled binaries through the wiki's own releases.</li>
  </ul>
</div>
<div class="plan">

  <div class="phase t-cli">
    <h4><span class="pid">P0</span> Spine — namespace + the help the AI reads first <span class="owner o-cli">CLI</span></h4>
    <div class="goal">The front door. Build it first because it's how every other verb gets discovered.</div>
    <ul>
      <li><span class="mono">adom-wiki</span> entrypoint + pillar router; <span class="mono">adompkg</span> → <span class="mono">adom-wiki pkg</span> alias.</li>
      <li>3-depth <span class="mono">--help</span> (map → pillar verbs → flags+example) with the <b>~ git/npm/gh analog hints</b>.</li>
      <li><span class="mono">--help --all</span> (full tree) + <span class="mono">--help --json</span> (machine-readable) + did-you-mean.</li>
    </ul>
    <div class="dep">depends on: nothing · unblocks: discoverability of everything below</div>
  </div>

  <div class="phase t-cli">
    <h4><span class="pid">P1</span> Re-home the 52 existing verbs into pillars <span class="owner o-cli">CLI</span></h4>
    <div class="goal">Pure reorganization of what already works — fast, low-risk, immediately useful.</div>
    <ul>
      <li>Bucket today's flat commands under <b>repo · pkg · release · page · admin</b>.</li>
      <li>Add git-native verbs the API already supports: <span class="mono">repo clone · show · contributors</span>; split delete into <span class="mono">delete</span> / <span class="mono">delete --hard</span> / <span class="mono">undelete</span>.</li>
      <li>Surface the hidden <span class="mono">platform</span> verb and the admin ops under the <span class="mono">admin</span> pillar.</li>
    </ul>
    <div class="dep">depends on: P0 · all client-side</div>
  </div>

  <div class="phase t-both">
    <h4><span class="pid">★</span> Native suite — compile &amp; distribute <span class="owner o-both">BOTH</span>
      <span class="owner" style="color:var(--purple);background:rgba(168,85,247,.14);border:1px solid rgba(168,85,247,.4)">CROSS-CUTTING</span></h4>
    <div class="goal">Make <span class="mono">adom-wiki</span> runnable natively on every OS John, Kyle &amp; the AIs touch — not just the cloud container.</div>
    <ul>
      <li><b>Bun <span class="mono">--compile</span> cross-build</b> → single-file binaries for windows-x64, darwin-arm64/x64, linux-x64/arm64 from one JS source.</li>
      <li><b>Ship via the wiki's own releases</b> — per-platform assets on the <span class="mono">adom-wiki</span> page (release API already supports <span class="mono">--platform</span>); <span class="mono">self-update</span> pulls the right one; HD golden image bakes the linux build.</li>
      <li><b>Native auth</b> — <span class="mono">auth login</span> + an OS token store (no <span class="mono">/var/run/adom/api-key</span> off-container).</li>
      <li><b>Platform-aware resolution + self-healing build-back</b> — the CLI sends its <span class="mono">X-Adom-Platform</span>; the wiki
        resolves the right artifact for pkg <i>and</i> release, or returns a runnable build-it-and-contribute-back recipe so the catalog heals.</li>
    </ul>
    <div class="dep">cross-cutting · parallels P0–P6 · re-compiles + re-releases on every version · the commons compounds with use</div>
  </div>

  <div class="phase t-both">
    <h4><span class="pid">P2</span> Light up the dead pillars — discussion &amp; pr <span class="owner o-both">BOTH</span></h4>
    <div class="goal">The APIs are live but the CLI exposes nothing. Wrap them; fill the lifecycle gaps server-side.</div>
    <ul>
      <li><b>CLI now:</b> <span class="mono">discussion create/list/view/comment</span>, <span class="mono">pr create/list/view/merge/close</span>, <span class="mono">breadcrumb list</span> — all over live endpoints.</li>
      <li><b>Server:</b> the missing lifecycle — <span class="mono">discussion edit/reopen/pin/lock</span>, <span class="mono">pr review/ready/reopen</span>, single-discussion GET.</li>
    </ul>
    <div class="dep">depends on: P0 · core verbs ship immediately, lifecycle verbs trail the API work</div>
  </div>

  <div class="phase t-both">
    <h4><span class="pid">P3</span> Linter + archetypes <span class="owner o-both">BOTH</span></h4>
    <div class="goal">You already have a linter framework + hints engine — add rules and a verb, mirror to the server.</div>
    <ul>
      <li>Promote <span class="mono">lint</span> to a standalone verb; add <b>HERO_IN_README · BINARY_IN_REPO · PKG_VS_RELEASE</b> (magic-byte) rules.</li>
      <li>Mirror the new rules into the <b>server hints engine</b> so direct-API writes are reprimanded too.</li>
      <li><span class="mono">init --archetype page|skillpack|family</span> scaffolding + archetype-conformance lint + a small <span class="mono">family</span> verb group.</li>
    </ul>
    <div class="dep">depends on: P1 · extends existing lintSecrets/lintSealedSourceInTarball framework</div>
  </div>

  <div class="phase t-srv">
    <h4><span class="pid">P4</span> The visibility model — axes + presets <span class="owner o-srv">SERVER</span></h4>
    <div class="goal">Make your two real modes declarative instead of improvised from scattered flags.</div>
    <ul>
      <li><b>Server:</b> persist the three axes (<span class="mono">source / pkg / releases</span>); add the missing <b>pkg/install</b> axis + org-scoping.</li>
      <li><b>CLI:</b> <span class="mono">page visibility --source/--pkg/--releases</span> + presets <span class="mono">--preset open|licensed|preview|private</span>.</li>
    </ul>
    <div class="dep">depends on: P1 · source/release columns exist but read null today — needs server enforcement</div>
  </div>

  <div class="phase t-srv">
    <h4><span class="pid">P5</span> Scoring + screensaver enablement <span class="owner o-srv">SERVER</span></h4>
    <div class="goal">Unblock adom-screensaver AND the wiki homepage: one shared trending order, an admin tuning page, cheap freshness checks.</div>
    <ul>
      <li><b>manual score write-path</b> + <span class="mono">admin score --adjust N --reason</span> (POST <span class="mono">/api/v1/admin/pages/:slug/score</span> — live, e.g. −50 on adom-usb).</li>
      <li><b>List-endpoint score exposure</b> — <span class="mono">composite_score</span> + <span class="mono">manual_score_adjustment</span> on page-list items, so the homepage/screensaver rank in <b>one call, no N+1</b>.</li>
      <li><b>Shared rotation + <span class="mono">/admin/scoring</span></b> — the transparent additive score (w1/w2 weights config), a homepage hero strip, and an admin page showing the per-page breakdown + live tuning — same model as the screensaver, so they stay aligned.</li>
      <li><span class="mono">GET /trending</span>; high-five endpoint; wire <span class="mono">page star</span>; <b>hero freshness</b> (<span class="mono">ETag</span>/<span class="mono">304</span> + <span class="mono">/hero</span> meta + <span class="mono">page hero status</span>).</li>
    </ul>
    <div class="dep">depends on: P1 · all server-gated · directly fixes the screensaver + homepage pain points; keep the formula identical across both surfaces</div>
  </div>

  <div class="phase t-srv">
    <h4><span class="pid">P6</span> Reach — images, discovery &amp; the gh long-tail <span class="owner o-srv">SERVER</span></h4>
    <div class="goal">The higher-effort wins that make the wiki feel complete.</div>
    <ul>
      <li><b>Discussion image attachments</b> (the thing gh can't do) — server multipart + <span class="mono">discussion/pr comment --image</span>.</li>
      <li><b>Discovery:</b> <span class="mono">/discover</span> trigger matching, <span class="mono">discover preview</span>, FTS hyphen fix, fork endpoint, <b>forced write-time snippet + DISCOVERY_PREVIEW collision/rank hint</b> (self-optimizing discovery).</li>
      <li><b>Breadcrumbs:</b> the write path + moderation + ranking + the AI-follow hint (<span class="mono">breadcrumb post/follow/approve/pin</span>) — the third-party extension commons.</li>
      <li><b>gh long-tail:</b> <span class="mono">api</span> passthrough, <span class="mono">status</span> dashboard, <span class="mono">search --type</span>, labels.</li>
      <li><b>Render any HTML file</b> — sandboxed rendered view + a standalone clean URL (<span class="mono">page render</span>); unblocks privacy-policy / static pages.</li>
      <li><b>README precedence</b> — push warning + <span class="mono">rendered_readme</span> field + UI "live" badge (the README.md-vs-readme.html silent-shadow footgun).</li>
    </ul>
    <div class="dep">depends on: P2 (images), P0 (api/status) · highest effort, do last</div>
  </div>

</div>
<div class="note" style="margin-top:10px">Net: <b>P0–P1 ship with no backend work</b> (the whole restructure + help system), <b>P2–P3 are mostly client</b>
  with server trailing, and <b>P4–P6 are the Colby work order</b> — each one already written as a paste-ready prompt above.</div>

<div class="foot">
  Proposed verb tree for <span class="mono" style="color:var(--teal)">adom-wiki</span> · mapped against
  <span class="mono">adompkg v2.46.0</span> (52 commands) and the live <span class="mono">/api/v1</span> surface.
  Status reflects the wiki as of 2026-06-23 — re-probe <span class="mono">/discover</span>,
  <span class="mono">/trending</span>, fork &amp; high-five before relying on them.
</div>
</div>

<script>
const V=(v,a,rest='')=>`<span class="cmd"><span class="v">${v}</span> <span class="a">${a}</span>${rest?' '+rest:''}</span>`;
const ST={ok:'<span class="badge b-ok"><span class="dot d-ok"></span>ships</span>',
  part:'<span class="badge b-part"><span class="dot d-part"></span>partial</span>',
  new:'<span class="badge b-new"><span class="dot d-new"></span>new</span>'};

const PILLARS=[
 {n:'01',verb:'repo',mimics:'git',desc:'Every page is a real git repo — clone, edit, commit, push, browse history.',
  rows:[
   ['repo','init','&lt;slug&gt;','git init',ST.ok,'create'],
   ['repo','clone','&lt;slug&gt; [dir]','git clone',ST.new,'— (GET /files)'],
   ['repo','add','&lt;files&gt;','git add',ST.part,'folded in push'],
   ['repo','commit','-m "…"','git commit',ST.part,'folded in push'],
   ['repo','push','--files … -m','git push',ST.ok,'push'],
   ['repo','pull','&lt;slug&gt;','git pull',ST.new,'—'],
   ['repo','status','&lt;slug&gt;','git status',ST.ok,'status'],
   ['repo','log','&lt;slug&gt;','git log',ST.ok,'log'],
   ['repo','show','&lt;slug&gt;:&lt;path&gt;','git show',ST.new,'— (GET /files/:p)'],
   ['repo','rm','&lt;slug&gt; &lt;path&gt;','git rm',ST.ok,'rm'],
   ['repo','mv','&lt;a&gt; &lt;b&gt;','git mv',ST.new,'—'],
   ['repo','contributors','&lt;slug&gt;','git shortlog',ST.part,'API only'],
   ['repo','fork','&lt;slug&gt;','gh repo fork',ST.new,'API 404 (planned)'],
   ['repo','rename','&lt;slug&gt; &lt;new&gt;','gh repo rename',ST.new,'no rename yet'],
   ['repo','delete','&lt;slug&gt;','— soft (Adom edge)',ST.ok,'delete (reversible)'],
   ['repo','delete','&lt;slug&gt; --hard','gh repo delete',ST.ok,'delete --hard'],
   ['repo','undelete','&lt;slug&gt;','— (Adom edge)',ST.ok,'undelete'],
   ['repo','edit','&lt;slug&gt; --brief…','gh repo edit',ST.part,'PUT /pages meta'],
   ['repo','archive','&lt;slug&gt; [--off]','gh repo archive',ST.new,'freeze read-only'],
   ['repo','sync','&lt;slug&gt;','gh repo sync',ST.new,'sync fork (w/ fork)'],
   ['repo','transfer','&lt;slug&gt; --to-org','gh repo transfer',ST.ok,'transfer'],
  ]},
 {n:'02',verb:'pkg',mimics:'npm',desc:'adompkg-style package manager — deps, publish, versions. (adompkg = alias.)',
  rows:[
   ['pkg','install','[pkg…]','npm install',ST.ok,'install'],
   ['pkg','add','&lt;pkg&gt; -D','npm install --save',ST.ok,'add'],
   ['pkg','uninstall','&lt;pkg&gt;','npm uninstall',ST.ok,'uninstall'],
   ['pkg','update','[pkg…]','npm update',ST.ok,'update'],
   ['pkg','outdated','','npm outdated',ST.ok,'outdated'],
   ['pkg','list','','npm ls',ST.ok,'list'],
   ['pkg','why','&lt;pkg&gt;','npm why',ST.ok,'why'],
   ['pkg','view','&lt;pkg&gt;','npm view',ST.ok,'view / info'],
   ['pkg','publish','[--ver]','npm publish',ST.ok,'publish'],
   ['pkg','pack','','npm pack',ST.ok,'pack'],
   ['pkg','init','&lt;slug&gt;','npm init',ST.ok,'init'],
   ['pkg','version','&lt;bump&gt;','npm version',ST.ok,'version'],
   ['pkg','dist-tag','add|rm|ls','npm dist-tag',ST.ok,'dist-tag'],
   ['pkg','deprecate','&lt;pkg&gt;@v','npm deprecate',ST.ok,'deprecate'],
   ['pkg','link','&lt;pkg&gt;','npm link',ST.ok,'link / unlink'],
   ['pkg','audit','','npm audit',ST.ok,'audit'],
   ['pkg','ci','--frozen','npm ci',ST.ok,'ci'],
   ['pkg','vouch','&lt;pkg&gt;','—(Adom)',ST.ok,'vouch'],
   ['pkg','verify','&lt;pkg&gt;','—(Adom)',ST.ok,'verify'],
  ]},
 {n:'03',verb:'release',mimics:'gh release',desc:'Versioned downloadable binaries + notes, per platform — like GitHub Releases.',
  rows:[
   ['release','create','&lt;slug&gt; v','gh release create',ST.part,'via upload'],
   ['release','list','&lt;slug&gt;','gh release list',ST.ok,'release list'],
   ['release','view','&lt;slug&gt; v','gh release view',ST.new,'—'],
   ['release','upload','&lt;slug&gt; v &lt;file&gt;','gh release upload',ST.ok,'release upload'],
   ['release','download','&lt;slug&gt; v','gh release download',ST.new,'— (tarball API)'],
   ['release','notes','&lt;slug&gt; v','gh release edit',ST.ok,'release notes'],
   ['release','edit','&lt;slug&gt; v','gh release edit',ST.part,'notes only'],
   ['release','delete','&lt;slug&gt; v','gh release delete',ST.ok,'unpublish'],
   ['release','delete-asset','&lt;slug&gt; v &lt;asset&gt;','gh release delete-asset',ST.new,'—'],
   ['release','verify','&lt;slug&gt; v','gh release verify',ST.part,'integrity SHA'],
  ]},
 {n:'04',verb:'discussion',mimics:'gh issue',desc:'A thread per page — bug reports, Q&A. gh has no native Discussions CLI, so this mirrors gh issue. Key upgrade: every post & reply carries screenshots — gh can\'t, and a bug report without a picture is half a report.',
  rows:[
   ['discussion','create','&lt;slug&gt; -t -b --image &lt;png…&gt;','gh issue create',ST.new,'+img beyond gh'],
   ['discussion','comment','&lt;id&gt; -b --image &lt;png…&gt;','gh issue comment',ST.new,'+img beyond gh'],
   ['discussion','attach','&lt;id&gt; &lt;png&gt;','— (no gh analog)',ST.new,'needs img API'],
   ['discussion','list','&lt;slug&gt;','gh issue list',ST.new,'API live'],
   ['discussion','view','&lt;id&gt;','gh issue view',ST.new,'—'],
   ['discussion','edit','&lt;id&gt; -b','gh issue edit',ST.new,'no API yet'],
   ['discussion','close','&lt;id&gt;','gh issue close',ST.new,'no API yet'],
   ['discussion','reopen','&lt;id&gt;','gh issue reopen',ST.new,'no API yet'],
   ['discussion','pin','&lt;id&gt;','gh issue pin',ST.new,'no API yet'],
   ['discussion','lock','&lt;id&gt;','gh issue lock',ST.new,'no API yet'],
  ]},
 {n:'05',verb:'pr',mimics:'gh pr',desc:'Propose changes to a page you don\'t own; owner reviews & merges. (Fork button still planned.)',
  rows:[
   ['pr','create','&lt;slug&gt;','gh pr create',ST.new,'API live'],
   ['pr','list','&lt;slug&gt;','gh pr list',ST.new,'API live'],
   ['pr','view','&lt;id&gt;','gh pr view',ST.new,'—'],
   ['pr','diff','&lt;id&gt;','gh pr diff',ST.new,'no API yet'],
   ['pr','checkout','&lt;id&gt;','gh pr checkout',ST.new,'no API yet'],
   ['pr','review','&lt;id&gt; --approve','gh pr review',ST.new,'no API yet'],
   ['pr','comment','&lt;id&gt; -b --image','gh pr comment',ST.new,'+img beyond gh'],
   ['pr','ready','&lt;id&gt;','gh pr ready',ST.new,'no API yet'],
   ['pr','merge','&lt;id&gt;','gh pr merge',ST.new,'API: merge'],
   ['pr','close','&lt;id&gt;','gh pr close',ST.new,'API: close'],
   ['pr','reopen','&lt;id&gt;','gh pr reopen',ST.new,'no API yet'],
  ]},
 {n:'06',verb:'page',mimics:'— Adom-native',desc:'The presentation + scoring layer. The hero is the AI-age app icon — and because it lives in the git repo (page.json + the image) it gets history, blame, rollback and PRs for free. Plus the trending signals the screensaver reads.',
  rows:[
   ['page','hero set','&lt;slug&gt; --headline…','— (app icon)',ST.ok,'hero / set-hero'],
   ['page','hero history','&lt;slug&gt;','git log -- page.json',ST.part,'via repo log'],
   ['page','hero blame','&lt;slug&gt;','git blame',ST.new,'who changed it'],
   ['page','hero rollback','&lt;slug&gt; &lt;commit&gt;','git revert',ST.new,'roll hero back'],
   ['page','hero status','&lt;slug&gt;','—',ST.part,'sha/ts — HEAD only, no ETag'],
   ['page','visibility','--source/--pkg/--releases','— (per-layer)',ST.part,'src+rel today'],
   ['page','star','&lt;slug&gt;','npm star / gh',ST.part,'API live, no cmd'],
   ['page','highfive','&lt;slug&gt;','— (reaction)',ST.new,'planned'],
   ['page','stats','&lt;slug&gt;','—',ST.ok,'composite_score + popularity'],
   ['page','trending','[--type]','—',ST.new,'/trending 404'],
   ['page','open','&lt;slug&gt;','gh browse',ST.new,'— (url)'],
   ['page','render','&lt;slug&gt; &lt;file.html&gt;','—',ST.new,'clean rendered URL'],
  ]},
 {n:'07',verb:'discover',mimics:'— Adom-native (1st-class pillar)',desc:'How a page gets FOUND before it\'s ever installed — search + trigger matching. Your wiki-discovery skill makes this peer to the other six; scoring (under page) ranks what it surfaces.',
  rows:[
   ['discover','search','&lt;q&gt;','npm search / gh search',ST.ok,'search (FTS, hyphen bug)'],
   ['discover','find','&lt;triggers&gt;','—',ST.part,'/discover ignores triggers'],
   ['discover','triggers','&lt;slug&gt;','—',ST.part,'set via manifest'],
   ['discover','preview','&lt;trigger&gt;','—',ST.new,'"what surfaces & why"'],
   ['discover','check','&lt;slug&gt;','—',ST.new,'simulate triggers → rank + collisions'],
   ['discover','related','&lt;slug&gt;','—',ST.new,'dep / similar pages'],
  ]},
 {n:'08',verb:'admin',mimics:'— superuser (gh org-admin / npm owner)',adminOnly:true,
  desc:'Elevated ops that bypass ownership — the manual trending score, cross-owner repo surgery, index & release admin. The negative score that keeps WIP pages (e.g. adom-usb, currently −50) out of the screensaver lives here.',
  rows:[
   ['admin','score','&lt;slug&gt; --adjust N --reason','—',ST.part,'manual_score_adjustment (live)'],
   ['admin','score clear','&lt;slug&gt;','—',ST.part,'unset adjustment'],
   ['admin','score list','[--sort total]','—',ST.new,'per-page breakdown → /admin/scoring'],
   ['admin','recompute','&lt;slug&gt;','—',ST.new,'force popularity recompute'],
   ['admin','feature','&lt;slug&gt; [--off]','—',ST.new,'pin / promote on homepage'],
   ['admin','reindex','&lt;slug&gt;','—',ST.ok,'reindex'],
   ['admin','platform','&lt;slug&gt;@v &lt;plat&gt;','—',ST.ok,'platform (hidden today)'],
   ['admin','push','&lt;slug&gt; --owner …','git push (any repo)',ST.part,'push --owner'],
   ['admin','delete','&lt;slug&gt; --hard','—',ST.ok,'hard-delete any page'],
  ]},
 {n:'09',verb:'breadcrumb',mimics:'— Adom-native (~ webmention / trackback)',
  desc:'A third party drops a "trail marker" on someone else\'s anchor repo — a bridge, a surfing skill, a plugin — WITHOUT edit rights. The anchor surfaces them; the AI sees the trail and follows it. This is how an anchor (adom-desktop, chip-fetcher) grows an ecosystem its owner never has to manage.',
  rows:[
   ['breadcrumb','list','&lt;anchor&gt;','— (the AI follows)',ST.ok,'GET live'],
   ['breadcrumb','post','&lt;anchor&gt; --to --kind','—',ST.part,'write-path firming up'],
   ['breadcrumb','follow','&lt;anchor&gt; [--install]','—',ST.new,'resolve/inspect the trail'],
   ['breadcrumb','remove','&lt;id&gt;','—',ST.part,'pull your own'],
   ['breadcrumb','approve','&lt;id&gt;','— (owner)',ST.new,'moderate spam'],
   ['breadcrumb','pin','&lt;id&gt;','— (owner)',ST.new,'feature the best'],
  ]},
];

document.getElementById('pillars').innerHTML = PILLARS.map(p=>`
 <div class="pillar${p.adminOnly?' admin':''}">
   <div class="top">
     <div class="num">PILLAR ${p.n}${p.adminOnly?' <span class="adminbadge">🔒 admin only</span>':''}</div>
     <h3><span class="mono">adom-wiki ${p.verb}</span></h3>
     <div class="mimics">mimics <b>${p.mimics}</b></div>
     <div class="desc">${p.desc}</div>
   </div>
   <table><tbody>
   ${p.rows.map(r=>`<tr class="${/^\+img/.test(r[5])?'hl':''}">
     <td>${V(r[0],r[1],r[2])}<div class="ana">↳ ${r[3]}</div></td>
     <td class="st">${r[4]}<div class="now mono" style="margin-top:4px">${r[5]}</div></td>
   </tr>`).join('')}
   </tbody></table>
 </div>`).join('');

document.querySelectorAll('.copy').forEach(b=>b.addEventListener('click',()=>{
  const txt=b.closest('.prompt').querySelector('pre').textContent;
  const done=()=>{b.textContent='Copied ✓';b.classList.add('done');setTimeout(()=>{b.textContent='Copy';b.classList.remove('done')},1600)};
  if(navigator.clipboard&&navigator.clipboard.writeText){navigator.clipboard.writeText(txt).then(done).catch(()=>fallback(txt,done))}
  else fallback(txt,done);
}));
function fallback(txt,done){const t=document.createElement('textarea');t.value=txt;t.style.position='fixed';t.style.opacity='0';
  document.body.appendChild(t);t.select();try{document.execCommand('copy');done()}catch(e){}document.body.removeChild(t)}
</script>
</body>
</html>