diff --git a/pr-32/index.html b/pr-32/index.html
new file mode 100644
index 0000000..4289963
--- /dev/null
+++ b/pr-32/index.html
@@ -0,0 +1,8 @@
+<!doctype html><meta charset=utf-8>
+<title>lgx doc-test reports — pr-32</title>
+<style>body{font:16px system-ui;margin:40px;max-width:640px}a{color:#2563eb}</style>
+<h1>lgx doc-test reports</h1>
+<p><strong>pr-32</strong> · commit <code>d23ef9a</code></p><ul>
+<li><a href="./ubuntu-latest/">ubuntu-latest</a></li>
+<li><a href="./macos-latest/">macos-latest</a></li>
+</ul>
diff --git a/pr-32/macos-latest/index.html b/pr-32/macos-latest/index.html
new file mode 100644
index 0000000..b936b2b
--- /dev/null
+++ b/pr-32/macos-latest/index.html
@@ -0,0 +1,325 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Tutorial Execution Report</title>
+<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
+<style>
+  :root {
+    --bg: #0d1117; --panel: #161b22; --border: #30363d;
+    --text: #c9d1d9; --muted: #8b949e; --accent: #58a6ff;
+    --pass: #2ea043; --fail: #f85149; --info: #d29922;
+    --code-bg: #0b0f14;
+  }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; background: var(--bg); color: var(--text);
+    font: 14px/1.55 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  }
+  header {
+    position: sticky; top: 0; z-index: 10; background: var(--panel);
+    border-bottom: 1px solid var(--border); padding: 12px 20px;
+    display: flex; align-items: center; gap: 16px; flex-wrap: wrap;
+  }
+  header h1 { font-size: 16px; margin: 0; font-weight: 600; }
+  .pill { padding: 2px 10px; border-radius: 999px; font-size: 12px; font-weight: 600; }
+  .pill.pass { background: rgba(46,160,67,.15); color: var(--pass); }
+  .pill.fail { background: rgba(248,81,73,.15); color: var(--fail); }
+  .pill.skip { background: rgba(210,153,34,.15); color: var(--info); }
+  select { background: var(--bg); color: var(--text); border: 1px solid var(--border); border-radius: 6px; padding: 4px 8px; }
+  main { max-width: 1600px; margin: 0 auto; padding: 16px; }
+  .tutorial-title { font-size: 20px; font-weight: 700; margin: 24px 0 8px; color: #fff; }
+  .row {
+    display: grid; grid-template-columns: 1fr 1fr; gap: 0;
+    border: 1px solid var(--border); border-radius: 8px; margin: 10px 0; overflow: hidden;
+  }
+  .row.preamble, .row.section { grid-template-columns: 1fr; }
+  .col { padding: 14px 18px; min-width: 0; }
+  .col.left { border-right: 1px solid var(--border); }
+  .row.preamble .col.left, .row.section .col.left { border-right: none; }
+  .col.right { background: var(--panel); }
+  /* A row containing any failed step is tinted red end-to-end so it's
+     impossible to miss when scanning the report. */
+  .row.has-fail { border-color: var(--fail); box-shadow: 0 0 0 1px var(--fail); }
+  .row.has-fail .col.left { background: rgba(248,81,73,.07); border-right-color: var(--fail); }
+  .row.has-fail .col.right { background: rgba(248,81,73,.12); }
+  .col-label { font-size: 11px; text-transform: uppercase; letter-spacing: .06em; color: var(--muted); margin-bottom: 8px; }
+  .md :first-child { margin-top: 0; }
+  .md h1 { font-size: 22px; } .md h2 { font-size: 18px; } .md h3 { font-size: 15px; }
+  .md pre { background: var(--code-bg); border: 1px solid var(--border); border-radius: 6px; padding: 12px; overflow-x: auto; }
+  .md code { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12.5px; }
+  .md :not(pre) > code { background: rgba(110,118,129,.2); padding: .15em .4em; border-radius: 4px; }
+  .md table { border-collapse: collapse; margin: 8px 0; }
+  .md th, .md td { border: 1px solid var(--border); padding: 5px 10px; }
+  .md blockquote { border-left: 3px solid var(--border); margin: 8px 0; padding: 2px 12px; color: var(--muted); }
+  .md img { width: 100%; height: auto; border: 1px solid var(--border); border-radius: 6px; }
+  .exec { margin-bottom: 14px; }
+  .exec:last-child { margin-bottom: 0; }
+  .exec-head { display: flex; align-items: center; gap: 8px; margin-bottom: 6px; }
+  .badge { font-size: 11px; font-weight: 700; padding: 1px 8px; border-radius: 4px; }
+  .badge.pass { background: rgba(46,160,67,.15); color: var(--pass); }
+  .badge.fail { background: rgba(248,81,73,.15); color: var(--fail); }
+  .badge.info { background: rgba(210,153,34,.15); color: var(--info); }
+  .kind { font-size: 11px; color: var(--muted); text-transform: uppercase; letter-spacing: .05em; }
+  .note { color: var(--muted); font-size: 12.5px; margin-bottom: 6px; }
+  pre.cmd { background: var(--code-bg); border: 1px solid var(--border); border-left: 3px solid var(--accent); border-radius: 6px; padding: 10px 12px; margin: 0 0 6px; overflow-x: auto; white-space: pre-wrap; word-break: break-word; }
+  pre.output { background: #010409; border: 1px solid var(--border); border-radius: 6px; padding: 10px 12px; margin: 0; overflow-x: auto; max-height: 360px; overflow-y: auto; color: #b9c1ca; }
+  pre.cmd, pre.output { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; line-height: 1.45; }
+  .empty { color: var(--muted); font-style: italic; font-size: 12.5px; }
+  details summary { cursor: pointer; color: var(--accent); font-size: 12px; margin-bottom: 4px; }
+  /* GitHub-style permalinks: every heading carries a link icon in the left
+     gutter (revealed on hover/focus) that copies a deep link to that section.
+     scroll-margin-top keeps the target clear of the sticky header. */
+  .heading-anchored { position: relative; scroll-margin-top: 76px; }
+  a.anchor {
+    position: absolute; left: -18px; top: 0; width: 16px; height: 1.55em;
+    display: inline-flex; align-items: center; justify-content: center;
+    color: var(--muted); opacity: 0; text-decoration: none;
+    transition: opacity .1s ease-in;
+  }
+  a.anchor svg { width: 14px; height: 14px; display: block; }
+  .heading-anchored:hover > a.anchor, a.anchor:focus { opacity: 1; }
+  a.anchor:hover { color: var(--accent); }
+  .heading-anchored.flash { animation: flash 1.4s ease-out; border-radius: 4px; }
+  @keyframes flash {
+    from { background: rgba(88,166,255,.28); box-shadow: 0 0 0 4px rgba(88,166,255,.28); }
+    to { background: transparent; box-shadow: 0 0 0 4px transparent; }
+  }
+  #toast {
+    position: fixed; left: 50%; bottom: 24px; transform: translateX(-50%);
+    background: var(--panel); border: 1px solid var(--border); color: var(--text);
+    border-radius: 6px; padding: 7px 14px; font-size: 12.5px; z-index: 20;
+    opacity: 0; pointer-events: none; transition: opacity .15s ease-in-out;
+  }
+  #toast.show { opacity: 1; }
+</style>
+</head>
+<body>
+<header>
+  <h1>Tutorial Execution Report</h1>
+  <span id="summary"></span>
+  <label style="margin-left:auto; font-size:12px; color:var(--muted)">Tutorial
+    <select id="picker"></select>
+  </label>
+</header>
+<main id="main"></main>
+<div id="toast" role="status" aria-live="polite"></div>
+
+<script id="report-data" type="application/json">{"generated_platform": "Darwin", "summary": {"passed": 25, "failed": 0, "skipped": 0}, "tutorials": [{"meta": {"name": "Packaging a Module with lgx", "platform": "Darwin (ext=dylib)", "release": "(none)"}, "rows": [{"md": "# Packaging a Module with lgx\n\n[`lgx`](https://github.com/logos-co/logos-package) is the Logos **package tool**.\nAn `.lgx` file is just a **gzipped tar archive** with a `manifest.json` at its root\nand one or more platform payloads under `variants/<platform>/`. `lgx` is the CLI that\nbuilds, inspects, extracts, merges, and (in the companion\n[signing doc-test](lgx-signing.md)) signs those archives \u2014 a self-contained C++ tool\nwith no Qt and no module runtime behind it.\n\nThis doc-test builds **this** `lgx` commit and drives the full packaging lifecycle:\n\n1. Build the `lgx` CLI from this repository's flake.\n2. `create` an empty package and read its `manifest`.\n3. `add` this machine's platform variant and `verify` the result.\n4. `extract` a variant back out, and inspect the raw archive with `tar`.\n5. `merge` two single-variant packages into one multi-variant `.lgx`.\n\nEvery command is the real binary built from the commit under test, so a green run is\nevidence that this change keeps the packaging workflow working end-to-end.\n\n**What you'll build:** A `greeter.lgx` package built, inspected, and extracted with `lgx`, plus a multi-variant `widget.lgx` assembled with `lgx merge`.\n\n**What you'll learn:**\n\n- What an `.lgx` package is on disk (a gzipped tar of a manifest + a `variants/` tree)\n- How to create a package and read its manifest with `lgx create` / `lgx manifest`\n- How to add a platform variant, verify structural validity, and extract it back out\n- How to merge per-platform single-variant packages into one multi-variant `.lgx`\n\n## Prerequisites\n\n- **Nix** with flakes enabled. Install from [nixos.org](https://nixos.org/download.html), then enable flakes:\n\n```bash\nmkdir -p ~/.config/nix\necho 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf\n```\n\nVerify: `nix flake --help >/dev/null 2>&1 && echo \"Flakes enabled\"`\n\n- A Linux or macOS machine.", "execs": []}, {"md": "## Step 1: Build the lgx CLI\n\n`lgx` ships as a C++ CLI. Build it straight from the flake's `#lgx` output and\nlink the result as `./lgx`, so the binary lands at `./lgx/bin/lgx`.\n\n> The `` in the URL is what pins the build to a specific commit: the\n> doc-test runner expands it to a concrete ref. Locally that is this checkout's\n> `HEAD` (see `run.sh`); in CI it is the commit being tested. With no pin it falls\n> back to the latest `master`. Developing against a local checkout? Replace the\n> GitHub reference with `.`, e.g. `nix build '.#lgx' -o lgx`.", "execs": []}, {"md": "### 1.1 Build lgx\n\n```bash\n# From inside the clone this is simply: nix build '.#lgx' -o lgx\nnix build 'github:logos-co/logos-package/5627ae3aeace560fd8c64d79d38f46e7cf94cf3b#lgx' -o lgx\n```\n\nThe `-o lgx` flag names the result symlink, so the executable is at `./lgx/bin/lgx`.", "execs": [{"kind": "run", "cmd": "nix build 'github:logos-co/logos-package/5627ae3aeace560fd8c64d79d38f46e7cf94cf3b#lgx' -o lgx", "status": "pass", "exit_code": 0, "output": "unpacking 'github:logos-co/logos-package/5627ae3aeace560fd8c64d79d38f46e7cf94cf3b' into the Git cache...\nunpacking 'github:logos-co/logos-nix/6e0f4a7120fced10829b0b3a698ff619a11d4605?narHash=sha256-Bl1A0UgsIXioZw5uEW8Jl5u7FfZcFMnpYlpsdezFwK0%3D' into the Git cache...\ncopying path '/nix/store/jc3mfa7ybzh32bkvdj5xiib1vkx8jy6x-source' from 'https://cache.nixos.org'...\nthis derivation will be built:\n  /nix/store/wngw026cncn02w32n403j453fp74qc96-lgx-0.1.0.drv\nthese 84 paths will be fetched (173.9 MiB download, 1.2 GiB unpacked):\n  /nix/store/6623n7vqivvdc0qpskgjjr3kaxlia2vc-adv_cmds-231-ps\n  /nix/store/rhlyld20zdzdi5wghb4b12gw52s9whr9-apple-sdk-11.3\n  /nix/store/k385hp16fsc8llfacr3phmmwnlfymdrz-bash-5.3p3\n  /nix/store/7q428fv2c4hy8qi1sj6n1djgrpc0i5ls-bzip2-1.0.8\n  /nix/store/vi2yr1i69n1gmqf7v3qj7sfa589rsnzg-bzip2-1.0.8-bin\n  /nix/store/rh7pmsjn8q2hgfnc77f2hn33k03bva79-cctools-1010.6\n  /nix/store/d7b7ms0zqg4ncv2gp26kss9frcg99nz2-cctools-1010.6-libtool\n  /nix/store/y7sd8l0kx34yply8v0x8ly9zxpf97798-cctools-binutils-darwin-1010.6\n  /nix/store/y9wq3jvp6qqgy9x3k4nb2rzpgz34l2ya-cctools-binutils-darwin-wrapper-1010.6\n  /nix/store/50cb6vjpl9drrqmi72s6w5rbhfr6phkl-clang-19.1.7\n  /nix/store/n9w4rvalqxk7anhbc4h0wgj0szf7773x-clang-19.1.7-lib\n  /nix/store/zzx6cfl99zknfrj9v7lmrshwzslfjv26-clang-wrapper-19.1.7\n  /nix/store/qvv2ddin29xa8fqmsv567b6xlnhbvpv0-cmake-3.31.7\n  /nix/store/hl1ndryiac3l9f15nwsgz4h2sp3qnp2s-compiler-rt-libc-19.1.7\n  /nix/store/71r56z118j50ia5n1rd79d7qyyhaxf33-compiler-rt-libc-19.1.7-dev\n  /nix/store/wbs75n9ffs3ac1pmn4fc7wqs0m9r1z3c-coreutils-9.7\n  /nix/store/g318mf5rmq4w6qip6livrf7m6n356x93-cpp-semver-0.4.0\n  /nix/store/fx3nf7w0slbr0b648ahym3i19rnw4w9p-cups-headers-2.4.12\n  /nix/store/dkkc865vbxyfpiac28qlhr4i98swvsg6-curl-8.14.1\n  /nix/store/9h9zdg66b3mc87ibp1rwlsvivdd4xnf7-diffutils-3.12\n  /nix/store/9ik0ckpp6md91npq2hmpfjr25k3ky9gy-ed-1.21.1\n  /nix/store/p4cjkwfg0asgf46wpmgajf9cadfjz9wm-expand-response-params\n  /nix/store/vqgjcq5f69y38smh376f07wx7l9n1vsj-expat-2.7.1\n  /nix/store/a53hizw26hv9z8k6hgml55shi3aym3xh-file-5.45\n  /nix/store/w4p211279zwl31c6qq4pxn3qldh4qad1-findutils-4.10.0\n  /nix/store/7hwv75x7zqw0bzyrg0b3n86ilafx4qbd-gawk-5.3.2\n  /nix/store/cwdz2vy0kkc17aw2s1b3sw7wspy8rs7j-gettext-0.25.1\n  /nix/store/fs5knwhd8fhm7gjj5wq39j5sc5rr15fv-gmp-with-cxx-6.3.0\n  /nix/store/vlzn94lra1hhzvhihqv8p63pkd2x1vvl-gnu-config-2024-01-01\n  /nix/store/l3hfn2n5c4p1i32vmvhvy0qbscy5jdil-gnugrep-3.12\n  /nix/store/sjxx5p05vzq7xam62h21cyzkbyb1amvd-gnumake-4.4.1\n  /nix/store/zanfww82nmlb4b7mgblb779awsqb5rj7-gnused-4.9\n  /nix/store/3l2jw31r5051xiwmz5gr2d71lwb8zv5d-gnutar-1.35\n  /nix/store/bn33dkib2hvgwpndi2128m1rsgs7irmf-gtest-1.17.0\n  /nix/store/xqqw33hbphc98vblpyikjvnaxdv0f7xj-gtest-1.17.0-dev\n  /nix/store/aclgh7rs80wmap44vb8z0jkskmkl8pzd-gzip-1.14\n  /nix/store/lxzs5j6ywzl51jnd093diy1v9i7260rz-icu4c-76.1\n  /nix/store/0pr4q85wdnizd5rfvx1z9g16p6hvsmg1-icu4c-76.1-dev\n  /nix/store/2m9qm23q9pw260raj6gpgbmkabcly0lr-krb5-1.22.1-lib\n  /nix/store/6x0pcc2q0hmzac95h8p7frwdxn59iwq6-ld64-954.16\n  /nix/store/70pf25spmjkr7acamim84a3scdkqj8j1-ld64-954.16-lib\n  /nix/store/iwqcclph84i55jsxn0qzamcplyygf3p5-libSystem-B\n  /nix/store/aa65a7kmpyj0ddlvbwslpj2jclqbg6q3-libarchive-3.8.1-lib\n  /nix/store/8qhdaryhrcvz2mfgvhci2j63qa22bjsl-libcxx-19.1.7\n  /nix/store/797z3fy28rz9hd7k7jr1hysq9mhjvggb-libcxx-19.1.7-dev\n  /nix/store/vzzkad9sba320sc46r3bfadxf1z1cg7c-libffi-39\n  /nix/store/clci1zxqwa39qp135b1lfbbwad9qa4g0-libiconv-109\n  /nix/store/7s8gizw7d3hw8wyf7npayp5dk47727mz-libiconv-109-dev\n  /nix/store/xbpw0yw65al9vrnskqw9zycxlw0r2h1c-libresolv-83\n  /nix/store/r3hk1845bif5qyfx0kanmw9dc0cfh0vh-libresolv-83-dev\n  /nix/store/yqikabmbgn1i9yc8jr6rf83984h9x6pv-libsbuf-14.1.0\n  /nix/store/92hlm24jgcqgpxnznd762j4xss51g1hx-libsbuf-14.1.0-dev\n  /nix/store/5gavp9kbhxmxx3zaj7ajblk463432any-libsodium-1.0.20\n  /nix/store/8lr8mcmajchrv5ahskzxmhihbjn7wy7p-libsodium-1.0.20-dev\n  /nix/store/jr2qzdy39pzmnp8jy9sp9ksapq47r1by-libssh2-1.11.1\n  /nix/store/bgiq9nq4q4vh4dv8x1yqynjz792qhwgm-libutil-72\n  /nix/store/5i7n3axk65fm14q3aywqg6pdch4y3zfl-libuv-1.51.0\n  /nix/store/d7f41cas0kczsdys7iwxhg9fimmihim8-libxml2-2.14.5\n  /nix/store/6hl85jp06hsq7jwrhk1zfbsjfb6dd589-llvm-19.1.7\n  /nix/store/v2idjbn6l30pvsz2z0cy5gc4924fqfj2-llvm-19.1.7-lib\n  /nix/store/pqj6qk91cwlcm1ihc5i2d6vdc77sh9rv-locale-118\n  /nix/store/r2nxv2gamv2hi4s6klngl1gnw72smn59-ncurses-6.5\n  /nix/store/lh9ma31109cr25ykqgs0vbymqxczaqif-ncurses-6.5-dev\n  /nix/store/13pdaf0m6d7d29qjmdvz9gzikzy5fxa7-ncurses-6.5-man\n  /nix/store/z7ykjqpqb63b0lw3g29vdmwhdg1gdfiz-nghttp2-1.66.0-lib\n  /nix/store/9qf4kqgd8j9psfplj573llnnvp87q2dn-ninja-1.13.1\n  /nix/store/hs7wcady8i97dqq7qiaiaq05srnq6yih-nlohmann_json-3.11.3\n  /nix/store/0ais7wnqw8xzj0331c2jka53s6g14wqb-openssl-3.5.1\n  /nix/store/lf4h22kw1rk5gyljkg3i0fd81s7ydm32-patch-2.8\n  /nix/store/9akz133p77hk9dn1q5j66pg5vnz0hj2k-pcre2-10.44\n  /nix/store/cmq2lpf0bimpb8m50dfy16c1qvf4si9g-pkg-config-0.29.2\n  /nix/store/yc7mj2h6kh2cm4h61v57c5qmycaq4x2z-pkg-config-wrapper-0.29.2\n  /nix/store/9gycarnn8b2k0dgi437wvdldc71dxn8j-ps-adv_cmds-231\n  /nix/store/6sgicjkxi7k4mcv2h6hx724wkjj9jz7a-rhash-1.4.4\n  /nix/store/pgrkqlci4gld1kp0qdhjzp1zazxblj2b-stdenv-darwin\n  /nix/store/hxgvkw7zy1m413j3rv2s2268zdq6wc47-update-autotools-gnu-config-scripts-hook\n  /nix/store/14apxzkjrmn9vnm4av5yy4nli1bayx66-xar-minimal-501-lib\n  /nix/store/yj80w3ph1aj452z6bvc4gld85a1393aj-xcbuild-0.1.1-unstable-2019-11-20\n  /nix/store/bqmp8jcg2acdx48rkcqfjkaiabydfqz6-xcbuild-0.1.1-unstable-2019-11-20-xcrun\n  /nix/store/5bqq0ws6akawcx31shp9bl2v1b2jdchv-xz-5.8.1\n  /nix/store/4r0yd8fwb7g1xqz85w6jnhvcs8hy4yj5-xz-5.8.1-bin\n  /nix/store/nx8r6a40877h1dmb8cm7lhl1ch2yb4jc-zlib-1.3.1\n  /nix/store/ypda0r27k1fg2zz7daqmhqgxdqff8jg4-zlib-1.3.1-dev\n  /nix/store/lik04w1qipzcdpzclr8z44bzm9xfmvii-zstd-1.5.7\ncopying path '/nix/store/k385hp16fsc8llfacr3phmmwnlfymdrz-bash-5.3p3' from 'https://cache.nixos.org'...\ncopying path '/nix/store/g318mf5rmq4w6qip6livrf7m6n356x93-cpp-semver-0.4.0' from 'https://logos-co.cachix.org'...\ncopying path '/nix/store/hs7wcady8i97dqq7qiaiaq05srnq6yih-nlohmann_json-3.11.3' from 'https://cache.nixos.org'...\ncopying path '/nix/store/vqgjcq5f69y38smh376f07wx7l9n1vsj-expat-2.7.1' from 'https://cache.nixos.org'...\ncopying path '/nix/store/7hwv75x7zqw0bzyrg0b3n86ilafx4qbd-gawk-5.3.2' from 'https://cache.nixos.org'...\ncopying path '/nix/store/zanfww82nmlb4b7mgblb779awsqb5rj7-gnused-4.9' from 'https://cache.nixos.org'...\ncopying path '/nix/store/8qhdaryhrcvz2mfgvhci2j63qa22bjsl-libcxx-19.1.7' from 'https://cache.nixos.org'...\ncopying path '/nix/store/iwqcclph84i55jsxn0qzamcplyygf3p5-libSystem-B' from 'https://cache.nixos.org'...\ncopying path '/nix/store/5i7n3axk65fm14q3aywqg6pdch4y3zfl-libuv-1.51.0' from 'https://cache.nixos.org'...\ncopying path '/nix/store/5gavp9kbhxmxx3zaj7ajblk463432any-libsodium-1.0.20' from 'https://cache.nixos.org'...\ncopying path '/nix/store/pqj6qk91cwlcm1ihc5i2d6vdc77sh9rv-locale-118' from 'https://cache.nixos.org'...\ncopying path '/nix/store/6sgicjkxi7k4mcv2h6hx724wkjj9jz7a-rhash-1.4.4' from 'https://cache.nixos.org'...\ncopying path '/nix/store/6623n7vqivvdc0qpskgjjr3kaxlia2vc-adv_cmds-231-ps' from 'https://cache.nixos.org'...\ncopying path '/nix/store/nx8r6a40877h1dmb8cm7lhl1ch2yb4jc-zlib-1.3.1' from 'https://cache.nixos.org'...\ncopying path '/nix/store/7q428fv2c4hy8qi1sj6n1djgrpc0i5ls-bzip2-1.0.8' from 'https://cache.nixos.org'...\ncopying path '/nix/store/fx3nf7w0slbr0b648ahym3i19rnw4w9p-cups-headers-2.4.12' from 'https://cache.nixos.org'...\ncopying path '/nix/store/p4cjkwfg0asgf46wpmgajf9cadfjz9wm-expand-response-params' from 'https://cache.nixos.org'...\ncopying path '/nix/store/vzzkad9sba320sc46r3bfadxf1z1cg7c-libffi-39' from 'https://cache.nixos.org'...\ncopying path '/nix/store/clci1zxqwa39qp135b1lfbbwad9qa4g0-libiconv-109' from 'https://cache.nixos.org'...\ncopying path '/nix/store/xbpw0yw65al9vrnskqw9zycxlw0r2h1c-libresolv-83' from 'https://cache.nixos.org'...\ncopying path '/nix/store/yqikabmbgn1i9yc8jr6rf83984h9x6pv-libsbuf-14.1.0' from 'https://cache.nixos.org'...\ncopying path '/nix/store/13pdaf0m6d7d29qjmdvz9gzikzy5fxa7-ncurses-6.5-man' from 'https://cache.nixos.org'...\ncopying path '/nix/store/vi2yr1i69n1gmqf7v3qj7sfa589rsnzg-bzip2-1.0.8-bin' from 'https://cache.nixos.org'...\ncopying path '/nix/store/r2nxv2gamv2hi4s6klngl1gnw72smn59-ncurses-6.5' from 'https://cache.nixos.org'...\ncopying path '/nix/store/z7ykjqpqb63b0lw3g29vdmwhdg1gdfiz-nghttp2-1.66.0-lib' from 'https://cache.nixos.org'...\ncopying path '/nix/store/a53hizw26hv9z8k6hgml55shi3aym3xh-file-5.45' from 'https://cache.nixos.org'...\ncopying path '/nix/store/8lr8mcmajchrv5ahskzxmhihbjn7wy7p-libsodium-1.0.20-dev' from 'https://cache.nixos.org'...\ncopying path '/nix/store/92hlm24jgcqgpxnznd762j4xss51g1hx-libsbuf-14.1.0-dev' from 'https://cache.nixos.org'...\ncopying path '/nix/store/r3hk1845bif5qyfx0kanmw9dc0cfh0vh-libresolv-83-dev' from 'https://cache.nixos.org'...\ncopying path '/nix/store/0ais7wnqw8xzj0331c2jka53s6g14wqb-openssl-3.5.1' from 'https://cache.nixos.org'...\ncopying path '/nix/store/9akz133p77hk9dn1q5j66pg5vnz0hj2k-pcre2-10.44' from 'https://cache.nixos.org'...\ncopying path '/nix/store/9gycarnn8b2k0dgi437wvdldc71dxn8j-ps-adv_cmds-231' from 'https://cache.nixos.org'...\ncopying path '/nix/store/5bqq0ws6akawcx31shp9bl2v1b2jdchv-xz-5.8.1' from 'https://cache.nixos.org'...\ncopying path '/nix/store/ypda0r27k1fg2zz7daqmhqgxdqff8jg4-zlib-1.3.1-dev' from 'https://cache.nixos.org'...\ncopying path '/nix/store/4r0yd8fwb7g1xqz85w6jnhvcs8hy4yj5-xz-5.8.1-bin' from 'https://cache.nixos.org'...\ncopying path '/nix/store/9ik0ckpp6md91npq2hmpfjr25k3ky9gy-ed-1.21.1' from 'https://cache.nixos.org'...\ncopying path '/nix/store/vlzn94lra1hhzvhihqv8p63pkd2x1vvl-gnu-config-2024-01-01' from 'https://cache.nixos.org'...\ncopying path '/nix/store/aclgh7rs80wmap44vb8z0jkskmkl8pzd-gzip-1.14' from 'https://cache.nixos.org'...\ncopying path '/nix/store/hxgvkw7zy1m413j3rv2s2268zdq6wc47-update-autotools-gnu-config-scripts-hook' from 'https://cache.nixos.org'...\ncopying path '/nix/store/lf4h22kw1rk5gyljkg3i0fd81s7ydm32-patch-2.8' from 'https://cache.nixos.org'...\ncopying path '/nix/store/l3hfn2n5c4p1i32vmvhvy0qbscy5jdil-gnugrep-3.12' from 'https://cache.nixos.org'...\ncopying path '/nix/store/fs5knwhd8fhm7gjj5wq39j5sc5rr15fv-gmp-with-cxx-6.3.0' from 'https://cache.nixos.org'...\ncopying path '/nix/store/hl1ndryiac3l9f15nwsgz4h2sp3qnp2s-compiler-rt-libc-19.1.7' from 'https://cache.nixos.org'...\ncopying path '/nix/store/lxzs5j6ywzl51jnd093diy1v9i7260rz-icu4c-76.1' from 'https://cache.nixos.org'...\ncopying path '/nix/store/797z3fy28rz9hd7k7jr1hysq9mhjvggb-libcxx-19.1.7-dev' from 'https://cache.nixos.org'...\ncopying path '/nix/store/bgiq9nq4q4vh4dv8x1yqynjz792qhwgm-libutil-72' from 'https://cache.nixos.org'...\ncopying path '/nix/store/bn33dkib2hvgwpndi2128m1rsgs7irmf-gtest-1.17.0' from 'https://cache.nixos.org'...\ncopying path '/nix/store/9qf4kqgd8j9psfplj573llnnvp87q2dn-ninja-1.13.1' from 'https://cache.nixos.org'...\ncopying path '/nix/store/lik04w1qipzcdpzclr8z44bzm9xfmvii-zstd-1.5.7' from 'https://cache.nixos.org'...\ncopying path '/nix/store/xqqw33hbphc98vblpyikjvnaxdv0f7xj-gtest-1.17.0-dev' from 'https://cache.nixos.org'...\ncopying path '/nix/store/wbs75n9ffs3ac1pmn4fc7wqs0m9r1z3c-coreutils-9.7' from 'https://cache.nixos.org'...\ncopying path '/nix/store/9h9zdg66b3mc87ibp1rwlsvivdd4xnf7-diffutils-3.12' from 'https://cache.nixos.org'...\ncopying path '/nix/store/w4p211279zwl31c6qq4pxn3qldh4qad1-findutils-4.10.0' from 'https://cache.nixos.org'...\ncopying path '/nix/store/71r56z118j50ia5n1rd79d7qyyhaxf33-compiler-rt-libc-19.1.7-dev' from 'https://cache.nixos.org'...\ncopying path '/nix/store/2m9qm23q9pw260raj6gpgbmkabcly0lr-krb5-1.22.1-lib' from 'https://cache.nixos.org'...\ncopying path '/nix/store/70pf25spmjkr7acamim84a3scdkqj8j1-ld64-954.16-lib' from 'https://cache.nixos.org'...\ncopying path '/nix/store/jr2qzdy39pzmnp8jy9sp9ksapq47r1by-libssh2-1.11.1' from 'https://cache.nixos.org'...\ncopying path '/nix/store/dkkc865vbxyfpiac28qlhr4i98swvsg6-curl-8.14.1' from 'https://cache.nixos.org'...\ncopying path '/nix/store/lh9ma31109cr25ykqgs0vbymqxczaqif-ncurses-6.5-dev' from 'https://cache.nixos.org'...\ncopying path '/nix/store/cwdz2vy0kkc17aw2s1b3sw7wspy8rs7j-gettext-0.25.1' from 'https://cache.nixos.org'...\ncopying path '/nix/store/7s8gizw7d3hw8wyf7npayp5dk47727mz-libiconv-109-dev' from 'https://cache.nixos.org'...\ncopying path '/nix/store/d7f41cas0kczsdys7iwxhg9fimmihim8-libxml2-2.14.5' from 'https://cache.nixos.org'...\ncopying path '/nix/store/cmq2lpf0bimpb8m50dfy16c1qvf4si9g-pkg-config-0.29.2' from 'https://cache.nixos.org'...\ncopying path '/nix/store/yc7mj2h6kh2cm4h61v57c5qmycaq4x2z-pkg-config-wrapper-0.29.2' from 'https://cache.nixos.org'...\ncopying path '/nix/store/14apxzkjrmn9vnm4av5yy4nli1bayx66-xar-minimal-501-lib' from 'https://cache.nixos.org'...\ncopying path '/nix/store/aa65a7kmpyj0ddlvbwslpj2jclqbg6q3-libarchive-3.8.1-lib' from 'https://cache.nixos.org'...\ncopying path '/nix/store/v2idjbn6l30pvsz2z0cy5gc4924fqfj2-llvm-19.1.7-lib' from 'https://cache.nixos.org'...\ncopying path '/nix/store/yj80w3ph1aj452z6bvc4gld85a1393aj-xcbuild-0.1.1-unstable-2019-11-20' from 'https://cache.nixos.org'...\ncopying path '/nix/store/qvv2ddin29xa8fqmsv567b6xlnhbvpv0-cmake-3.31.7' from 'https://cache.nixos.org'...\ncopying path '/nix/store/bqmp8jcg2acdx48rkcqfjkaiabydfqz6-xcbuild-0.1.1-unstable-2019-11-20-xcrun' from 'https://cache.nixos.org'...\ncopying path '/nix/store/sjxx5p05vzq7xam62h21cyzkbyb1amvd-gnumake-4.4.1' from 'https://cache.nixos.org'...\ncopying path '/nix/store/3l2jw31r5051xiwmz5gr2d71lwb8zv5d-gnutar-1.35' from 'https://cache.nixos.org'...\ncopying path '/nix/store/0pr4q85wdnizd5rfvx1z9g16p6hvsmg1-icu4c-76.1-dev' from 'https://cache.nixos.org'...\ncopying path '/nix/store/n9w4rvalqxk7anhbc4h0wgj0szf7773x-clang-19.1.7-lib' from 'https://cache.nixos.org'...\ncopying path '/nix/store/6x0pcc2q0hmzac95h8p7frwdxn59iwq6-ld64-954.16' from 'https://cache.nixos.org'...\ncopying path '/nix/store/6hl85jp06hsq7jwrhk1zfbsjfb6dd589-llvm-19.1.7' from 'https://cache.nixos.org'...\ncopying path '/nix/store/d7b7ms0zqg4ncv2gp26kss9frcg99nz2-cctools-1010.6-libtool' from 'https://cache.nixos.org'...\ncopying path '/nix/store/rh7pmsjn8q2hgfnc77f2hn33k03bva79-cctools-1010.6' from 'https://cache.nixos.org'...\ncopying path '/nix/store/50cb6vjpl9drrqmi72s6w5rbhfr6phkl-clang-19.1.7' from 'https://cache.nixos.org'...\ncopying path '/nix/store/y7sd8l0kx34yply8v0x8ly9zxpf97798-cctools-binutils-darwin-1010.6' from 'https://cache.nixos.org'...\ncopying path '/nix/store/rhlyld20zdzdi5wghb4b12gw52s9whr9-apple-sdk-11.3' from 'https://cache.nixos.org'...\ncopying path '/nix/store/y9wq3jvp6qqgy9x3k4nb2rzpgz34l2ya-cctools-binutils-darwin-wrapper-1010.6' from 'https://cache.nixos.org'...\ncopying path '/nix/store/zzx6cfl99zknfrj9v7lmrshwzslfjv26-clang-wrapper-19.1.7' from 'https://cache.nixos.org'...\ncopying path '/nix/store/pgrkqlci4gld1kp0qdhjzp1zazxblj2b-stdenv-darwin' from 'https://cache.nixos.org'...\nbuilding '/nix/store/wngw026cncn02w32n403j453fp74qc96-lgx-0.1.0.drv'...\n", "note": ""}]}, {"md": "### 1.2 Confirm it runs\n\n```bash\n./lgx/bin/lgx --version\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx --version", "status": "pass", "exit_code": 0, "output": "lgx version 0.1.0\n", "note": ""}]}, {"md": "## Step 2: Detect the platform variant\n\nAn `.lgx` package carries one or more **platform variants** \u2014 `linux-x86_64`,\n`darwin-arm64`, and so on \u2014 each holding the payload for that platform. Detect this\nmachine's variant once (and the matching shared-library extension, `.so` on Linux /\n`.dylib` on macOS) and stash both in files so the packaging steps below can reuse\nthem.", "execs": []}, {"md": "### 2.1 Write the variant and library extension to ./variant and ./ext\n\n```bash\ncase \"$(uname -s) $(uname -m)\" in\n  \"Linux x86_64\")   echo linux-x86_64  > variant; echo so    > ext ;;\n  \"Linux aarch64\")  echo linux-arm64   > variant; echo so    > ext ;;\n  \"Darwin arm64\")   echo darwin-arm64  > variant; echo dylib > ext ;;\n  \"Darwin x86_64\")  echo darwin-x86_64 > variant; echo dylib > ext ;;\n  *) echo \"unsupported platform: $(uname -sm)\" >&2; exit 1 ;;\nesac\necho \"variant: $(cat variant)  ext: $(cat ext)\"\n\n```", "execs": [{"kind": "run", "cmd": "case \"$(uname -s) $(uname -m)\" in\n  \"Linux x86_64\")   echo linux-x86_64  > variant; echo so    > ext ;;\n  \"Linux aarch64\")  echo linux-arm64   > variant; echo so    > ext ;;\n  \"Darwin arm64\")   echo darwin-arm64  > variant; echo dylib > ext ;;\n  \"Darwin x86_64\")  echo darwin-x86_64 > variant; echo dylib > ext ;;\n  *) echo \"unsupported platform: $(uname -sm)\" >&2; exit 1 ;;\nesac\necho \"variant: $(cat variant)  ext: $(cat ext)\"\n", "status": "pass", "exit_code": 0, "output": "variant: darwin-arm64  ext: dylib\n", "note": ""}]}, {"md": "## Step 3: Create a package\n\n`lgx create <name>` writes an empty skeleton package \u2014 a `manifest.json` with\nsensible defaults plus an empty `variants/` directory \u2014 to `<name>.lgx`.", "execs": []}, {"md": "### 3.1 Create greeter.lgx\n\n```bash\n./lgx/bin/lgx create greeter\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx create greeter", "status": "pass", "exit_code": 0, "output": "Created package: greeter.lgx\n", "note": ""}]}, {"md": "### 3.2 Read the fresh manifest\n\n`lgx manifest` prints the embedded `manifest.json` in human-readable form. A\nfreshly created package starts at version `0.0.1`, manifest schema `0.3.0`, with\nno type, no variants, and no signature yet.\n\n```bash\nlgx manifest greeter.lgx\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx manifest greeter.lgx", "status": "pass", "exit_code": 0, "output": "Name:           greeter\nDisplay name:   (unset \u2014 falls back to name)\nVersion:        0.0.1\nManifest ver.:  0.3.0\nType:           (unset)\nCategory:       (unset)\nAuthor:         (unset)\nVariants:       (none)\nDependencies:   (none)\nSigned:         no\n", "note": ""}]}, {"md": "## Step 4: Add a platform variant\n\n`lgx add` drops a payload into the package under `variants/<variant>/` and records\nthe entry point in the manifest's `main` map. We add a stub shared library for this\nmachine's variant. (In a real build the payload is the module's compiled `.so` /\n`.dylib`; `lgx` does not load it \u2014 it just packages it.)", "execs": []}, {"md": "### 4.1 Add this machine's variant\n\n```bash\n# On Linux x86_64 this expands to:\necho 'stub library' > libgreeter.so\nlgx add greeter.lgx --variant linux-x86_64 --files libgreeter.so\n```\n\nConfirm the archive layout \u2014 a `manifest.json` beside the `variants/` tree:\n\n```bash\ntar -tzf greeter.lgx\n```\n\n```\nmanifest.json\nvariants/\nvariants/<platform>/\nvariants/<platform>/libgreeter.so   # .dylib on macOS\n```", "execs": [{"kind": "run", "cmd": "V=\"$(cat variant)\"; E=\"$(cat ext)\"\necho 'stub library' > \"libgreeter.$E\"\n./lgx/bin/lgx add greeter.lgx --variant \"$V\" --files \"libgreeter.$E\"\n", "status": "pass", "exit_code": 0, "output": "Added variant 'darwin-arm64' to greeter.lgx\n", "note": ""}, {"kind": "run", "cmd": "tar -tzf greeter.lgx", "status": "pass", "exit_code": 0, "output": "manifest.json\nvariants/\nvariants/darwin-arm64/\nvariants/darwin-arm64/libgreeter.dylib\n", "note": ""}]}, {"md": "### 4.2 See the variant in the manifest\n\nThe manifest now lists the variant and points its `main` entry at the file we\nadded. A content hash (`Root hash`) is recomputed on every save.\n\n```bash\nlgx manifest greeter.lgx\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx manifest greeter.lgx", "status": "pass", "exit_code": 0, "output": "Name:           greeter\nDisplay name:   (unset \u2014 falls back to name)\nVersion:        0.0.1\nManifest ver.:  0.3.0\nType:           (unset)\nCategory:       (unset)\nAuthor:         (unset)\nRoot hash:      d05451f2b5e0896b9a9b16c7a5564939245d2ca563f9d1f16e7339e0e0406787\nVariants:       darwin-arm64\n                darwin-arm64 -> libgreeter.dylib\nDependencies:   (none)\nSigned:         no\n", "note": ""}]}, {"md": "## Step 5: Verify the package\n\n`lgx verify` validates a package against the LGX spec \u2014 it recomputes the content\nhashes (the Merkle tree) and checks them against the manifest, then reports the\nsignature state. Our package is unsigned, so verification passes and notes it is\nunsigned. The exit code is `0` on success, so `verify` is safe to gate CI on.", "execs": []}, {"md": "### 5.1 Verify greeter.lgx\n\n```bash\nlgx verify greeter.lgx\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx verify greeter.lgx", "status": "pass", "exit_code": 0, "output": "Package structure is valid: greeter.lgx\nPackage is unsigned\n", "note": ""}]}, {"md": "## Step 6: Extract a variant\n\n`lgx extract` unpacks a variant's payload back onto disk \u2014 the inverse of `add`.\nFiles land under `<output>/<variant>/`.", "execs": []}, {"md": "### 6.1 Extract this machine's variant\n\n```bash\nlgx extract greeter.lgx --variant linux-x86_64 --output ./extracted\n```\n\nThe payload is now on disk under `./extracted/<variant>/`:\n\n```bash\nls ./extracted/<variant>\n```", "execs": [{"kind": "run", "cmd": "V=\"$(cat variant)\"\n./lgx/bin/lgx extract greeter.lgx --variant \"$V\" --output ./extracted\n", "status": "pass", "exit_code": 0, "output": "Extracted variant 'darwin-arm64' to ./extracted\n", "note": ""}, {"kind": "run", "cmd": "V=\"$(cat variant)\"\nls \"./extracted/$V\"\n", "status": "pass", "exit_code": 0, "output": "libgreeter.dylib\n", "note": ""}]}, {"md": "## Step 7: Merge per-platform packages\n\nReal releases ship one `.lgx` covering every platform. A common pattern is to build\na **single-variant** package on each platform's CI runner, then `lgx merge` them\ninto one multi-variant archive. The inputs must share identical metadata (only the\nvariant-specific `main` entries differ). We simulate it here by hand-building a\nLinux and a macOS package for the same module and merging them.", "execs": []}, {"md": "### 7.1 Build two single-variant packages\n\n```bash\n# A Linux-only package...\n./lgx/bin/lgx create widget && mv widget.lgx widget-linux.lgx\necho 'linux stub' > libwidget.so\n./lgx/bin/lgx add widget-linux.lgx --variant linux-x86_64 --files libwidget.so\n\n# ...and a macOS-only package for the same module.\n./lgx/bin/lgx create widget && mv widget.lgx widget-darwin.lgx\necho 'darwin stub' > libwidget.dylib\n./lgx/bin/lgx add widget-darwin.lgx --variant darwin-arm64 --files libwidget.dylib\n\n```", "execs": [{"kind": "run", "cmd": "# A Linux-only package...\n./lgx/bin/lgx create widget && mv widget.lgx widget-linux.lgx\necho 'linux stub' > libwidget.so\n./lgx/bin/lgx add widget-linux.lgx --variant linux-x86_64 --files libwidget.so\n\n# ...and a macOS-only package for the same module.\n./lgx/bin/lgx create widget && mv widget.lgx widget-darwin.lgx\necho 'darwin stub' > libwidget.dylib\n./lgx/bin/lgx add widget-darwin.lgx --variant darwin-arm64 --files libwidget.dylib\n", "status": "pass", "exit_code": 0, "output": "Created package: widget.lgx\nAdded variant 'linux-x86_64' to widget-linux.lgx\nCreated package: widget.lgx\nAdded variant 'darwin-arm64' to widget-darwin.lgx\n", "note": ""}]}, {"md": "### 7.2 Merge them into one .lgx\n\n`lgx merge` writes a single package carrying both variants. The variants are\nlisted alphabetically in the summary.\n\n```bash\nlgx merge widget-linux.lgx widget-darwin.lgx -o widget.lgx\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx merge widget-linux.lgx widget-darwin.lgx -o widget.lgx", "status": "pass", "exit_code": 0, "output": "Merged 2 packages into widget.lgx (darwin-arm64, linux-x86_64)\n", "note": ""}]}, {"md": "### 7.3 Confirm both variants are present\n\nThe merged manifest carries both platforms, and the package verifies:\n\n```bash\nlgx manifest widget.lgx\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx manifest widget.lgx", "status": "pass", "exit_code": 0, "output": "Name:           widget\nDisplay name:   (unset \u2014 falls back to name)\nVersion:        0.0.1\nManifest ver.:  0.3.0\nType:           (unset)\nCategory:       (unset)\nAuthor:         (unset)\nRoot hash:      0a75dda1458cfde4e1d28487da541307631fab66c797942c4e5f0ce9fe4a23d8\nVariants:       darwin-arm64, linux-x86_64\n                darwin-arm64 -> libwidget.dylib\n                linux-x86_64 -> libwidget.so\nDependencies:   (none)\nSigned:         no\n", "note": ""}]}, {"md": "```bash\nlgx verify widget.lgx\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx verify widget.lgx", "status": "pass", "exit_code": 0, "output": "Package structure is valid: widget.lgx\nPackage is unsigned\n", "note": ""}]}, {"md": "## Recap\n\nYou built `lgx` from this commit and ran a full packaging lifecycle \u2014 creating a\npackage, adding a platform variant, verifying it, extracting it, and merging\nper-platform packages into one multi-variant `.lgx`:\n\n| Command | What it does |\n|---|---|\n| `create <name>` | Write an empty skeleton `<name>.lgx` |\n| `add <pkg> -v <variant> -f <path>` | Add a payload for a variant (records `main`) |\n| `manifest <pkg> [--json]` | Print the embedded `manifest.json` (`--json` for raw bytes) |\n| `verify <pkg>` | Validate structure + content hashes, report signature state |\n| `extract <pkg> -v <variant> -o <dir>` | Unpack a variant's payload to disk |\n| `merge <pkg\u2026> -o <out>` | Combine single-variant packages into one multi-variant `.lgx` |\n\nSigning, signature inspection, and trusted-key management are covered in the\ncompanion [signing doc-test](lgx-signing.md).", "execs": []}]}, {"meta": {"name": "Signing and Trusting an lgx Package", "platform": "Darwin (ext=dylib)", "release": "(none)"}, "rows": [{"md": "# Signing and Trusting an lgx Package\n\n[`lgx`](https://github.com/logos-co/logos-package) packages can be **signed** so\nconsumers can verify who produced them. Signing uses an **Ed25519** keypair whose public\nhalf is published as a [`did:jwk:`](https://github.com/quartzjer/did-jwk/blob/main/spec.md)\ndecentralized identifier; `lgx sign` writes a `manifest.sig` next to the manifest, and\n`lgx verify` checks it. A **keyring** of trusted DIDs lets `verify` go one step further\nand report whether the signer is one you trust.\n\nThis doc-test builds **this** `lgx` commit and runs the full signing-and-trust lifecycle:\n\n1. Build `lgx` and create a small package to sign.\n2. `keygen` an Ed25519 keypair (printing its `did:jwk:` DID).\n3. `sign` the package and inspect the signature with `manifest` and `signature`.\n4. `verify` it \u2014 first as an *untrusted* signer, then after adding the DID to a keyring.\n\nEvery key directory is passed explicitly (`--output-dir`, `--keys-dir`, `--keyring-dir`)\nso the whole flow is self-contained and never touches your real `~/.config/logos`.\n\n**What you'll build:** A signed `greeter.lgx`, an Ed25519 signing key, and a trusted-key keyring that makes `lgx verify` recognise the signer.\n\n**What you'll learn:**\n\n- How to generate an Ed25519 signing keypair and its `did:jwk:` DID with `lgx keygen`\n- How to sign a package and read back its signature with `lgx sign` / `lgx signature`\n- How `lgx verify` reports signature validity and distinguishes trusted from untrusted signers\n- How to manage trusted DIDs with `lgx keyring add` / `list`\n\n## Prerequisites\n\n- **Nix** with flakes enabled. Install from [nixos.org](https://nixos.org/download.html), then enable flakes:\n\n```bash\nmkdir -p ~/.config/nix\necho 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf\n```\n\nVerify: `nix flake --help >/dev/null 2>&1 && echo \"Flakes enabled\"`\n\n- A Linux or macOS machine.", "execs": []}, {"md": "## Step 1: Build lgx and create a package to sign\n\nBuild the `lgx` CLI from this commit, then create a one-variant package \u2014 the thing\nwe will sign. (The [packaging doc-test](lgx-cli.md) covers `create` / `add` in\ndetail; here they are just setup.)\n\n> The `` placeholder pins the build to the commit under test (this\n> checkout's `HEAD` locally, the PR/push commit in CI). Against a local checkout use\n> `nix build '.#lgx' -o lgx`.", "execs": []}, {"md": "### 1.1 Build lgx\n\n```bash\n# From inside the clone this is simply: nix build '.#lgx' -o lgx\nnix build 'github:logos-co/logos-package/5627ae3aeace560fd8c64d79d38f46e7cf94cf3b#lgx' -o lgx\n```", "execs": [{"kind": "run", "cmd": "nix build 'github:logos-co/logos-package/5627ae3aeace560fd8c64d79d38f46e7cf94cf3b#lgx' -o lgx", "status": "pass", "exit_code": 0, "output": "", "note": ""}]}, {"md": "### 1.2 Create and populate greeter.lgx\n\nDetect this machine's variant (and shared-library extension), create the\npackage, and add a stub payload so there is content to sign.\n\n```bash\nlgx create greeter\necho 'stub library' > libgreeter.so          # .dylib on macOS\nlgx add greeter.lgx --variant linux-x86_64 --files libgreeter.so\n```", "execs": [{"kind": "run", "cmd": "case \"$(uname -s) $(uname -m)\" in\n  \"Linux x86_64\")   V=linux-x86_64;  E=so ;;\n  \"Linux aarch64\")  V=linux-arm64;   E=so ;;\n  \"Darwin arm64\")   V=darwin-arm64;  E=dylib ;;\n  \"Darwin x86_64\")  V=darwin-x86_64; E=dylib ;;\n  *) echo \"unsupported platform: $(uname -sm)\" >&2; exit 1 ;;\nesac\n./lgx/bin/lgx create greeter\necho 'stub library' > \"libgreeter.$E\"\n./lgx/bin/lgx add greeter.lgx --variant \"$V\" --files \"libgreeter.$E\"\n", "status": "pass", "exit_code": 0, "output": "Created package: greeter.lgx\nAdded variant 'darwin-arm64' to greeter.lgx\n", "note": ""}]}, {"md": "## Step 2: Generate a signing key\n\n`lgx keygen` creates an Ed25519 keypair and writes three files \u2014 the secret key\n(`.jwk`), the public key (`.pub`), and the DID string (`.did`). It prints the\n`did:jwk:` DID to stdout. We point `--output-dir` at a local `./keys` directory and\nstash the DID in a file so later steps can refer to it.", "execs": []}, {"md": "### 2.1 Run keygen into ./keys\n\n`keygen` prints the DID to stdout and also writes it to `./keys/demo-key.did`. We\ncopy that file to `./did.txt` so later steps can pass the exact DID without\nre-deriving it.\n\n```bash\nlgx keygen --name demo-key --output-dir ./keys\n# \u2192 did:jwk:eyJjcnYiOiJFZDI1NTE5Ii...   (also saved to ./keys/demo-key.did)\n```\n\nThe keypair now lives under `./keys/` as `demo-key.{jwk,pub,did}`. The `.jwk`\nfile is the **secret** key \u2014 keep it safe; only the DID is meant to be shared.", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx keygen --name demo-key --output-dir ./keys\ncp ./keys/demo-key.did did.txt\n", "status": "pass", "exit_code": 0, "output": "did:jwk:eyJjcnYiOiJFZDI1NTE5Iiwia3R5IjoiT0tQIiwieCI6IlYyR1YteTFPRlJiaFBQVHF3ZTVHUlRPSWFZUHFWckJVRUxOcnZVaG5fSG8ifQ\nKeypair generated: ./keys/demo-key.{jwk,pub,did}\n", "note": ""}]}, {"md": "## Step 3: Sign the package\n\n`lgx sign` validates the package, then writes a `manifest.sig` containing the\nsigner's DID, an Ed25519 signature over the manifest bytes, and optional\nself-asserted signer metadata (`--name` / `--url`). We pass `--keys-dir ./keys` so it\nfinds the key we just generated.", "execs": []}, {"md": "### 3.1 Sign greeter.lgx\n\n```bash\nlgx sign greeter.lgx --key demo-key --keys-dir ./keys \\\n  --name \"Logos Demo\" --url \"https://logos.co\"\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx sign greeter.lgx --key demo-key --keys-dir ./keys \\\n  --name \"Logos Demo\" --url \"https://logos.co\"\n", "status": "pass", "exit_code": 0, "output": "Package signed: greeter.lgx\nSigner DID: did:jwk:eyJjcnYiOiJFZDI1NTE5Iiwia3R5IjoiT0tQIiwieCI6IlYyR1YteTFPRlJiaFBQVHF3ZTVHUlRPSWFZUHFWckJVRUxOcnZVaG5fSG8ifQ\n", "note": ""}]}, {"md": "### 3.2 See the signature in the manifest\n\n`lgx manifest` now reports the package as signed, along with the signer's DID and\nself-asserted name/URL.\n\n```bash\nlgx manifest greeter.lgx\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx manifest greeter.lgx", "status": "pass", "exit_code": 0, "output": "Name:           greeter\nDisplay name:   (unset \u2014 falls back to name)\nVersion:        0.0.1\nManifest ver.:  0.3.0\nType:           (unset)\nCategory:       (unset)\nAuthor:         (unset)\nRoot hash:      d05451f2b5e0896b9a9b16c7a5564939245d2ca563f9d1f16e7339e0e0406787\nVariants:       darwin-arm64\n                darwin-arm64 -> libgreeter.dylib\nDependencies:   (none)\nSigned:         yes\nSigner DID:     did:jwk:eyJjcnYiOiJFZDI1NTE5Iiwia3R5IjoiT0tQIiwieCI6IlYyR1YteTFPRlJiaFBQVHF3ZTVHUlRPSWFZUHFWckJVRUxOcnZVaG5fSG8ifQ\nSigner name:    Logos Demo (self-asserted)\nSigner URL:     https://logos.co (self-asserted)\n", "note": ""}]}, {"md": "### 3.3 Read the raw signature\n\n`lgx signature` prints the raw `manifest.sig` JSON \u2014 byte-identical to the file\ninside the `.lgx`. It carries the algorithm, the signer DID, the base64\nsignature, and the signer metadata. Unsigned packages print nothing and exit 0,\nso tooling tells \"unsigned\" from \"error\" by the exit status, not the output.\n\n```bash\nlgx signature greeter.lgx\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx signature greeter.lgx", "status": "pass", "exit_code": 0, "output": "{\n  \"algorithm\": \"ed25519\",\n  \"did\": \"did:jwk:eyJjcnYiOiJFZDI1NTE5Iiwia3R5IjoiT0tQIiwieCI6IlYyR1YteTFPRlJiaFBQVHF3ZTVHUlRPSWFZUHFWckJVRUxOcnZVaG5fSG8ifQ\",\n  \"linkedDids\": [],\n  \"signature\": \"7NUMEcuTSFdtQsAZLrdzPAi88gJbwE88rdUkH7nB0u7snvntoKgPjqiKgtpQh3m58vaYAIJjyW25+Movqzz0AA==\",\n  \"signer\": {\n    \"name\": \"Logos Demo\",\n    \"url\": \"https://logos.co\"\n  },\n  \"version\": 1\n}", "note": ""}]}, {"md": "## Step 4: Verify an untrusted signer\n\n`lgx verify` always checks structure and (for signed packages) the signature itself.\nTrust is separate: with no matching entry in the keyring, the signature is reported\n**valid** but the signer is flagged as **not** trusted. We point `--keyring-dir` at an\nempty `./trusted` directory to make that explicit.", "execs": []}, {"md": "### 4.1 Verify against an empty keyring\n\n```bash\nmkdir -p trusted\nlgx verify greeter.lgx --keyring-dir ./trusted\n```", "execs": [{"kind": "run", "cmd": "mkdir -p trusted\n./lgx/bin/lgx verify greeter.lgx --keyring-dir ./trusted\n", "status": "pass", "exit_code": 0, "output": "Package structure is valid: greeter.lgx\nSignature is valid\nSigner DID: did:jwk:eyJjcnYiOiJFZDI1NTE5Iiwia3R5IjoiT0tQIiwieCI6IlYyR1YteTFPRlJiaFBQVHF3ZTVHUlRPSWFZUHFWckJVRUxOcnZVaG5fSG8ifQ\nSigner name (self-asserted): Logos Demo\nSigner URL (self-asserted): https://logos.co\nSigner DID is NOT in trusted keyring\n", "note": ""}]}, {"md": "## Step 5: Trust the signer\n\n`lgx keyring add` records a DID as trusted under a short name. We add the DID we\nstashed earlier (still in `did.txt`) to the `./trusted` keyring, then list it.", "execs": []}, {"md": "### 5.1 Add the DID to the keyring\n\n```bash\nlgx keyring add logos-demo \"$DID\" \\\n  --display-name \"Logos Demo\" --url \"https://logos.co\" --dir ./trusted\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx keyring add logos-demo \"$(cat did.txt)\" \\\n  --display-name \"Logos Demo\" --url \"https://logos.co\" --dir ./trusted\n", "status": "pass", "exit_code": 0, "output": "Added trusted key: logos-demo\nDID: did:jwk:eyJjcnYiOiJFZDI1NTE5Iiwia3R5IjoiT0tQIiwieCI6IlYyR1YteTFPRlJiaFBQVHF3ZTVHUlRPSWFZUHFWckJVRUxOcnZVaG5fSG8ifQ\n", "note": ""}]}, {"md": "### 5.2 List trusted keys\n\n```bash\nlgx keyring list --dir ./trusted\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx keyring list --dir ./trusted", "status": "pass", "exit_code": 0, "output": "logos-demo (Logos Demo)\n  DID: did:jwk:eyJjcnYiOiJFZDI1NTE5Iiwia3R5IjoiT0tQIiwieCI6IlYyR...\n  URL: https://logos.co\n  Added: 2026-08-10T22:18:34Z\n", "note": ""}]}, {"md": "## Step 6: Verify a trusted signer\n\nRe-run `verify` against the populated keyring. Now that the signer's DID is trusted,\n`verify` adds a final line naming the trusted key \u2014 the same valid signature, now\nrecognised.", "execs": []}, {"md": "### 6.1 Verify against the populated keyring\n\n```bash\nlgx verify greeter.lgx --keyring-dir ./trusted\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx verify greeter.lgx --keyring-dir ./trusted", "status": "pass", "exit_code": 0, "output": "Package structure is valid: greeter.lgx\nSignature is valid\nSigner DID: did:jwk:eyJjcnYiOiJFZDI1NTE5Iiwia3R5IjoiT0tQIiwieCI6IlYyR1YteTFPRlJiaFBQVHF3ZTVHUlRPSWFZUHFWckJVRUxOcnZVaG5fSG8ifQ\nSigner name (self-asserted): Logos Demo\nSigner URL (self-asserted): https://logos.co\nSigner is trusted: logos-demo\n", "note": ""}]}, {"md": "## Recap\n\nYou built `lgx` from this commit and ran the full signing-and-trust lifecycle \u2014\ngenerating a key, signing a package, inspecting the signature, and verifying it both\nas an untrusted and a trusted signer:\n\n| Command | What it does |\n|---|---|\n| `keygen --name <n> --output-dir <dir>` | Generate an Ed25519 keypair; print its `did:jwk:` DID |\n| `sign <pkg> --key <n> --keys-dir <dir> [--name \u2026] [--url \u2026]` | Write `manifest.sig` with the signer's DID |\n| `signature <pkg>` | Print the raw `manifest.sig` JSON (unsigned \u2192 empty + exit 0) |\n| `verify <pkg> [--keyring-dir <dir>]` | Validate structure + signature; report trust |\n| `keyring add <name> <did> [--dir <dir>]` | Trust a DID under a short name |\n| `keyring list [--dir <dir>]` | List trusted DIDs |\n\nCreating, adding variants, extracting, and merging packages are covered in the\ncompanion [packaging doc-test](lgx-cli.md).", "execs": []}]}]}</script>
+<script>
+  const DATA = JSON.parse(document.getElementById("report-data").textContent);
+  if (window.marked) { marked.setOptions({ gfm: true, breaks: false }); }
+  const mdToHtml = (s) => window.marked ? marked.parse(s || "") : ("<pre>" + (s || "") + "</pre>");
+
+  const sum = DATA.summary;
+  document.getElementById("summary").innerHTML =
+    `<span class="pill pass">${sum.passed} passed</span> ` +
+    (sum.failed ? `<span class="pill fail">${sum.failed} failed</span> ` : "") +
+    (sum.skipped ? `<span class="pill skip">${sum.skipped} skipped</span>` : "");
+
+  const picker = document.getElementById("picker");
+  DATA.tutorials.forEach((t, i) => {
+    const o = document.createElement("option");
+    o.value = i; o.textContent = t.meta.name; picker.appendChild(o);
+  });
+
+  function execHtml(e) {
+    const badge = `<span class="badge ${e.status}">${e.status.toUpperCase()}</span>`;
+    const kind = `<span class="kind">${e.kind}${e.exit_code !== undefined ? " · exit " + e.exit_code : ""}</span>`;
+    let h = `<div class="exec"><div class="exec-head">${badge}${kind}</div>`;
+    if (e.note) h += `<div class="note">${escapeHtml(e.note)}</div>`;
+    if (e.cmd) h += `<pre class="cmd">${escapeHtml(e.cmd)}</pre>`;
+    const out = (e.output || "").trim();
+    if (out) {
+      const long = out.split("\n").length > 12;
+      if (long) {
+        h += `<details><summary>output (${out.split("\n").length} lines)</summary><pre class="output">${escapeHtml(out)}</pre></details>`;
+      } else {
+        h += `<pre class="output">${escapeHtml(out)}</pre>`;
+      }
+    }
+    h += `</div>`;
+    return h;
+  }
+
+  function escapeHtml(s) {
+    return String(s).replace(/[&<>]/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" }[c]));
+  }
+
+  function render(idx) {
+    const t = DATA.tutorials[idx];
+    const main = document.getElementById("main");
+    main.innerHTML = "";
+    const h = document.createElement("div");
+    h.className = "tutorial-title";
+    h.textContent = t.meta.name + "  —  " + t.meta.platform;
+    main.appendChild(h);
+
+    t.rows.forEach(row => {
+      const isStructural = row.execs.length === 0 &&
+        (/^#\s|^##\s/.test(row.md.trim()));
+      const div = document.createElement("div");
+      const hasExec = row.execs.length > 0;
+      const hasFail = row.execs.some(e => e.status === "fail");
+      div.className = "row" + (hasExec ? "" : (isStructural ? " section" : " preamble")) +
+        (hasFail ? " has-fail" : "");
+
+      const left = document.createElement("div");
+      left.className = "col left";
+      left.innerHTML = `<div class="md">${mdToHtml(row.md)}</div>`;
+      div.appendChild(left);
+
+      if (hasExec || !isStructural) {
+        const right = document.createElement("div");
+        right.className = "col right";
+        if (hasExec) {
+          right.innerHTML = `<div class="col-label">Executed</div>` +
+            row.execs.map(execHtml).join("");
+        } else {
+          right.innerHTML = `<div class="col-label">Executed</div>` +
+            `<div class="empty">No commands run for this step.</div>`;
+        }
+        div.appendChild(right);
+      }
+      main.appendChild(div);
+    });
+
+    addAnchors(main, slug(t.meta.name));
+  }
+
+  function slug(s) {
+    return String(s).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  }
+
+  // Octicon "link" — the same glyph GitHub puts next to markdown headings.
+  const LINK_ICON =
+    '<svg viewBox="0 0 16 16" aria-hidden="true"><path fill="currentColor" d=' +
+    '"M7.775 3.275a.75.75 0 0 0 1.06 1.06l1.25-1.25a2 2 0 1 1 2.83 2.83l-2.5 2.5a2 2 0 0 1-2.83 0 ' +
+    '.75.75 0 0 0-1.06 1.06 3.5 3.5 0 0 0 4.95 0l2.5-2.5a3.5 3.5 0 0 0-4.95-4.95l-1.25 1.25Zm-4.69 ' +
+    '9.64a2 2 0 0 1 0-2.83l2.5-2.5a2 2 0 0 1 2.83 0 .75.75 0 0 0 1.06-1.06 3.5 3.5 0 0 0-4.95 0l-2.5 ' +
+    '2.5a3.5 3.5 0 0 0 4.95 4.95l1.25-1.25a.75.75 0 0 0-1.06-1.06l-1.25 1.25a2 2 0 0 1-2.83 0Z"></path></svg>';
+
+  // Give every heading a stable slug id (deduplicated the way GitHub does, with
+  // -1/-2 suffixes) and a permalink whose href is "#<tutorial>/<heading>".
+  function addAnchors(container, tutSlug) {
+    const used = new Map();
+    const nodes = container.querySelectorAll(
+      ".tutorial-title, .md h1, .md h2, .md h3, .md h4, .md h5, .md h6"
+    );
+    nodes.forEach(node => {
+      const text = node.textContent.trim();
+      const isTitle = node.classList.contains("tutorial-title");
+      let href = "#" + tutSlug;
+      if (!isTitle) {
+        const base = slug(text) || "section";
+        const n = (used.get(base) || 0) + 1;
+        used.set(base, n);
+        node.id = n > 1 ? base + "-" + n : base;
+        href += "/" + node.id;
+      }
+      node.classList.add("heading-anchored");
+      const a = document.createElement("a");
+      a.className = "anchor";
+      a.href = href;
+      a.title = "Copy link to this section";
+      a.setAttribute("aria-label", "Permalink: " + text);
+      a.innerHTML = LINK_ICON;
+      node.insertBefore(a, node.firstChild);
+    });
+  }
+
+  let toastTimer = null;
+  function toast(msg) {
+    const el = document.getElementById("toast");
+    el.textContent = msg;
+    el.classList.add("show");
+    clearTimeout(toastTimer);
+    toastTimer = setTimeout(() => el.classList.remove("show"), 1600);
+  }
+
+  // navigator.clipboard needs a secure context; reports are often opened over
+  // file://, so fall back to the old execCommand path there.
+  function copyText(text) {
+    if (navigator.clipboard && window.isSecureContext) {
+      navigator.clipboard.writeText(text).then(
+        () => toast("Link copied"),
+        () => toast(text)
+      );
+      return;
+    }
+    const ta = document.createElement("textarea");
+    ta.value = text;
+    ta.style.position = "fixed";
+    ta.style.opacity = "0";
+    document.body.appendChild(ta);
+    ta.select();
+    let ok = false;
+    try { ok = document.execCommand("copy"); } catch (e) { ok = false; }
+    document.body.removeChild(ta);
+    toast(ok ? "Link copied" : text);
+  }
+
+  function scrollToId(id) {
+    if (!id) { window.scrollTo(0, 0); return; }
+    const el = document.getElementById(id);
+    if (!el) return;
+    el.scrollIntoView({ block: "start" });
+    el.classList.remove("flash");
+    void el.offsetWidth;  // restart the animation on a repeat click
+    el.classList.add("flash");
+  }
+
+  document.addEventListener("click", ev => {
+    const a = ev.target.closest && ev.target.closest("a.anchor");
+    if (!a) return;
+    ev.preventDefault();
+    const href = a.getAttribute("href");
+    copyText(location.href.split("#")[0] + href);
+    if (location.hash === href) scrollToId(a.parentNode.id);
+    else location.hash = href;  // hashchange scrolls
+  });
+
+  // "#<tutorial>" (name, slug, or index) optionally followed by "/<heading>".
+  function parseHash() {
+    const raw = decodeURIComponent(location.hash.replace(/^#/, ""));
+    if (!raw) return { idx: 0, frag: "" };
+    const cut = raw.indexOf("/");
+    const tut = cut >= 0 ? raw.slice(0, cut) : raw;
+    const frag = cut >= 0 ? raw.slice(cut + 1) : "";
+    if (/^\d+$/.test(tut) && +tut < DATA.tutorials.length) return { idx: +tut, frag };
+    const i = DATA.tutorials.findIndex(
+      t => slug(t.meta.name) === tut || t.meta.name === tut
+    );
+    if (i >= 0) return { idx: i, frag };
+    // No tutorial matched: treat a bare hash as a heading in the current one.
+    return { idx: currentIdx >= 0 ? currentIdx : 0, frag: cut >= 0 ? frag : raw };
+  }
+
+  let currentIdx = -1;
+  function show(idx, frag) {
+    if (idx !== currentIdx) {
+      picker.value = idx;
+      render(idx);
+      currentIdx = idx;
+    }
+    if (frag) requestAnimationFrame(() => scrollToId(frag));
+  }
+  picker.addEventListener("change", () => {
+    location.hash = slug(DATA.tutorials[+picker.value].meta.name);
+    show(+picker.value);
+  });
+  window.addEventListener("hashchange", () => {
+    const h = parseHash();
+    show(h.idx, h.frag);
+  });
+  const initial = parseHash();
+  show(initial.idx, initial.frag);
+  // Inlined screenshots have no intrinsic size until decoded, so the first
+  // scroll can land short; re-anchor once everything has loaded.
+  if (initial.frag) {
+    window.addEventListener("load", () => scrollToId(initial.frag), { once: true });
+  }
+</script>
+</body>
+</html>
diff --git a/pr-32/ubuntu-latest/index.html b/pr-32/ubuntu-latest/index.html
new file mode 100644
index 0000000..38b7af4
--- /dev/null
+++ b/pr-32/ubuntu-latest/index.html
@@ -0,0 +1,325 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Tutorial Execution Report</title>
+<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
+<style>
+  :root {
+    --bg: #0d1117; --panel: #161b22; --border: #30363d;
+    --text: #c9d1d9; --muted: #8b949e; --accent: #58a6ff;
+    --pass: #2ea043; --fail: #f85149; --info: #d29922;
+    --code-bg: #0b0f14;
+  }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; background: var(--bg); color: var(--text);
+    font: 14px/1.55 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  }
+  header {
+    position: sticky; top: 0; z-index: 10; background: var(--panel);
+    border-bottom: 1px solid var(--border); padding: 12px 20px;
+    display: flex; align-items: center; gap: 16px; flex-wrap: wrap;
+  }
+  header h1 { font-size: 16px; margin: 0; font-weight: 600; }
+  .pill { padding: 2px 10px; border-radius: 999px; font-size: 12px; font-weight: 600; }
+  .pill.pass { background: rgba(46,160,67,.15); color: var(--pass); }
+  .pill.fail { background: rgba(248,81,73,.15); color: var(--fail); }
+  .pill.skip { background: rgba(210,153,34,.15); color: var(--info); }
+  select { background: var(--bg); color: var(--text); border: 1px solid var(--border); border-radius: 6px; padding: 4px 8px; }
+  main { max-width: 1600px; margin: 0 auto; padding: 16px; }
+  .tutorial-title { font-size: 20px; font-weight: 700; margin: 24px 0 8px; color: #fff; }
+  .row {
+    display: grid; grid-template-columns: 1fr 1fr; gap: 0;
+    border: 1px solid var(--border); border-radius: 8px; margin: 10px 0; overflow: hidden;
+  }
+  .row.preamble, .row.section { grid-template-columns: 1fr; }
+  .col { padding: 14px 18px; min-width: 0; }
+  .col.left { border-right: 1px solid var(--border); }
+  .row.preamble .col.left, .row.section .col.left { border-right: none; }
+  .col.right { background: var(--panel); }
+  /* A row containing any failed step is tinted red end-to-end so it's
+     impossible to miss when scanning the report. */
+  .row.has-fail { border-color: var(--fail); box-shadow: 0 0 0 1px var(--fail); }
+  .row.has-fail .col.left { background: rgba(248,81,73,.07); border-right-color: var(--fail); }
+  .row.has-fail .col.right { background: rgba(248,81,73,.12); }
+  .col-label { font-size: 11px; text-transform: uppercase; letter-spacing: .06em; color: var(--muted); margin-bottom: 8px; }
+  .md :first-child { margin-top: 0; }
+  .md h1 { font-size: 22px; } .md h2 { font-size: 18px; } .md h3 { font-size: 15px; }
+  .md pre { background: var(--code-bg); border: 1px solid var(--border); border-radius: 6px; padding: 12px; overflow-x: auto; }
+  .md code { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12.5px; }
+  .md :not(pre) > code { background: rgba(110,118,129,.2); padding: .15em .4em; border-radius: 4px; }
+  .md table { border-collapse: collapse; margin: 8px 0; }
+  .md th, .md td { border: 1px solid var(--border); padding: 5px 10px; }
+  .md blockquote { border-left: 3px solid var(--border); margin: 8px 0; padding: 2px 12px; color: var(--muted); }
+  .md img { width: 100%; height: auto; border: 1px solid var(--border); border-radius: 6px; }
+  .exec { margin-bottom: 14px; }
+  .exec:last-child { margin-bottom: 0; }
+  .exec-head { display: flex; align-items: center; gap: 8px; margin-bottom: 6px; }
+  .badge { font-size: 11px; font-weight: 700; padding: 1px 8px; border-radius: 4px; }
+  .badge.pass { background: rgba(46,160,67,.15); color: var(--pass); }
+  .badge.fail { background: rgba(248,81,73,.15); color: var(--fail); }
+  .badge.info { background: rgba(210,153,34,.15); color: var(--info); }
+  .kind { font-size: 11px; color: var(--muted); text-transform: uppercase; letter-spacing: .05em; }
+  .note { color: var(--muted); font-size: 12.5px; margin-bottom: 6px; }
+  pre.cmd { background: var(--code-bg); border: 1px solid var(--border); border-left: 3px solid var(--accent); border-radius: 6px; padding: 10px 12px; margin: 0 0 6px; overflow-x: auto; white-space: pre-wrap; word-break: break-word; }
+  pre.output { background: #010409; border: 1px solid var(--border); border-radius: 6px; padding: 10px 12px; margin: 0; overflow-x: auto; max-height: 360px; overflow-y: auto; color: #b9c1ca; }
+  pre.cmd, pre.output { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; line-height: 1.45; }
+  .empty { color: var(--muted); font-style: italic; font-size: 12.5px; }
+  details summary { cursor: pointer; color: var(--accent); font-size: 12px; margin-bottom: 4px; }
+  /* GitHub-style permalinks: every heading carries a link icon in the left
+     gutter (revealed on hover/focus) that copies a deep link to that section.
+     scroll-margin-top keeps the target clear of the sticky header. */
+  .heading-anchored { position: relative; scroll-margin-top: 76px; }
+  a.anchor {
+    position: absolute; left: -18px; top: 0; width: 16px; height: 1.55em;
+    display: inline-flex; align-items: center; justify-content: center;
+    color: var(--muted); opacity: 0; text-decoration: none;
+    transition: opacity .1s ease-in;
+  }
+  a.anchor svg { width: 14px; height: 14px; display: block; }
+  .heading-anchored:hover > a.anchor, a.anchor:focus { opacity: 1; }
+  a.anchor:hover { color: var(--accent); }
+  .heading-anchored.flash { animation: flash 1.4s ease-out; border-radius: 4px; }
+  @keyframes flash {
+    from { background: rgba(88,166,255,.28); box-shadow: 0 0 0 4px rgba(88,166,255,.28); }
+    to { background: transparent; box-shadow: 0 0 0 4px transparent; }
+  }
+  #toast {
+    position: fixed; left: 50%; bottom: 24px; transform: translateX(-50%);
+    background: var(--panel); border: 1px solid var(--border); color: var(--text);
+    border-radius: 6px; padding: 7px 14px; font-size: 12.5px; z-index: 20;
+    opacity: 0; pointer-events: none; transition: opacity .15s ease-in-out;
+  }
+  #toast.show { opacity: 1; }
+</style>
+</head>
+<body>
+<header>
+  <h1>Tutorial Execution Report</h1>
+  <span id="summary"></span>
+  <label style="margin-left:auto; font-size:12px; color:var(--muted)">Tutorial
+    <select id="picker"></select>
+  </label>
+</header>
+<main id="main"></main>
+<div id="toast" role="status" aria-live="polite"></div>
+
+<script id="report-data" type="application/json">{"generated_platform": "Linux", "summary": {"passed": 25, "failed": 0, "skipped": 0}, "tutorials": [{"meta": {"name": "Packaging a Module with lgx", "platform": "Linux (ext=so)", "release": "(none)"}, "rows": [{"md": "# Packaging a Module with lgx\n\n[`lgx`](https://github.com/logos-co/logos-package) is the Logos **package tool**.\nAn `.lgx` file is just a **gzipped tar archive** with a `manifest.json` at its root\nand one or more platform payloads under `variants/<platform>/`. `lgx` is the CLI that\nbuilds, inspects, extracts, merges, and (in the companion\n[signing doc-test](lgx-signing.md)) signs those archives \u2014 a self-contained C++ tool\nwith no Qt and no module runtime behind it.\n\nThis doc-test builds **this** `lgx` commit and drives the full packaging lifecycle:\n\n1. Build the `lgx` CLI from this repository's flake.\n2. `create` an empty package and read its `manifest`.\n3. `add` this machine's platform variant and `verify` the result.\n4. `extract` a variant back out, and inspect the raw archive with `tar`.\n5. `merge` two single-variant packages into one multi-variant `.lgx`.\n\nEvery command is the real binary built from the commit under test, so a green run is\nevidence that this change keeps the packaging workflow working end-to-end.\n\n**What you'll build:** A `greeter.lgx` package built, inspected, and extracted with `lgx`, plus a multi-variant `widget.lgx` assembled with `lgx merge`.\n\n**What you'll learn:**\n\n- What an `.lgx` package is on disk (a gzipped tar of a manifest + a `variants/` tree)\n- How to create a package and read its manifest with `lgx create` / `lgx manifest`\n- How to add a platform variant, verify structural validity, and extract it back out\n- How to merge per-platform single-variant packages into one multi-variant `.lgx`\n\n## Prerequisites\n\n- **Nix** with flakes enabled. Install from [nixos.org](https://nixos.org/download.html), then enable flakes:\n\n```bash\nmkdir -p ~/.config/nix\necho 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf\n```\n\nVerify: `nix flake --help >/dev/null 2>&1 && echo \"Flakes enabled\"`\n\n- A Linux or macOS machine.", "execs": []}, {"md": "## Step 1: Build the lgx CLI\n\n`lgx` ships as a C++ CLI. Build it straight from the flake's `#lgx` output and\nlink the result as `./lgx`, so the binary lands at `./lgx/bin/lgx`.\n\n> The `` in the URL is what pins the build to a specific commit: the\n> doc-test runner expands it to a concrete ref. Locally that is this checkout's\n> `HEAD` (see `run.sh`); in CI it is the commit being tested. With no pin it falls\n> back to the latest `master`. Developing against a local checkout? Replace the\n> GitHub reference with `.`, e.g. `nix build '.#lgx' -o lgx`.", "execs": []}, {"md": "### 1.1 Build lgx\n\n```bash\n# From inside the clone this is simply: nix build '.#lgx' -o lgx\nnix build 'github:logos-co/logos-package/5627ae3aeace560fd8c64d79d38f46e7cf94cf3b#lgx' -o lgx\n```\n\nThe `-o lgx` flag names the result symlink, so the executable is at `./lgx/bin/lgx`.", "execs": [{"kind": "run", "cmd": "nix build 'github:logos-co/logos-package/5627ae3aeace560fd8c64d79d38f46e7cf94cf3b#lgx' -o lgx", "status": "pass", "exit_code": 0, "output": "unpacking 'github:logos-co/logos-package/5627ae3aeace560fd8c64d79d38f46e7cf94cf3b' into the Git cache...\nunpacking 'github:logos-co/logos-nix/6e0f4a7120fced10829b0b3a698ff619a11d4605?narHash=sha256-Bl1A0UgsIXioZw5uEW8Jl5u7FfZcFMnpYlpsdezFwK0%3D' into the Git cache...\ncopying path '/nix/store/jc3mfa7ybzh32bkvdj5xiib1vkx8jy6x-source' from 'https://cache.nixos.org'...\nthis derivation will be built:\n  /nix/store/nq0i0y7mbarzl33wqqgr4y04ypvaig9q-lgx-0.1.0.drv\nthese 70 paths will be fetched (108.0 MiB download, 489.5 MiB unpacked):\n  /nix/store/3apspx5fhyb83153axf1b80ifiklgjbh-acl-2.3.2\n  /nix/store/877drgyy4926ps2qfraaxsd49w90bwiz-attr-2.5.2\n  /nix/store/q7sqwn7i6w2b67adw0bmix29pxg85x3w-bash-5.3p3\n  /nix/store/c43ry7z24x3jhnjlj4gpay8a4g2p3x1h-binutils-2.44\n  /nix/store/d6h99jhxcpi2b09n3kgw75jx99aslxv2-binutils-2.44-lib\n  /nix/store/l19cddv64i52rhcwahif8sgyrd3mhiqb-binutils-wrapper-2.44\n  /nix/store/x1nn5jrx1im7wmmn1xmpjvyf072s5k75-bzip2-1.0.8\n  /nix/store/6yjb3zdj448rm8qsmpiq3f67kvj5683a-bzip2-1.0.8-bin\n  /nix/store/a94d5zmalqava26y3hqsnj5l11l5kl5y-cmake-3.31.7\n  /nix/store/8ksax0a2mxglr5hlkj2dzl556jx7xqn5-coreutils-9.7\n  /nix/store/9kqdjbbsmhkf2cs45w041pbncljyvz7f-cpp-semver-0.4.0\n  /nix/store/222cks9f8yjhdvyk4x8iyp05pyci5xpj-curl-8.14.1\n  /nix/store/s2fvny566vls74p4qm9v3fdqd741fh3f-diffutils-3.12\n  /nix/store/xxris3l81hc2c8ibx8fcyimwqpvfh2pp-ed-1.21.1\n  /nix/store/7k857h95ra7vwwsay8mz5han65f9n4cq-expand-response-params\n  /nix/store/wdbr9yrvz0vgsii826wlidr48m7rafdf-expat-2.7.1\n  /nix/store/v40ijzz8p2fpk9ihjck3a1ncqaqfmn3c-file-5.45\n  /nix/store/l964krgbp613d5jxga2vy5qdssj7zfzj-findutils-4.10.0\n  /nix/store/03nvbw411p097h6yxjghc33rbcrjfb9d-gawk-5.3.2\n  /nix/store/82kmz7r96navanrc2fgckh2bamiqrgsw-gcc-14.3.0\n  /nix/store/41ym1jm1b7j3rhglk82gwg9jml26z1km-gcc-14.3.0-lib\n  /nix/store/8zm936ys1dkqv2710j0w09r2mk0kj5n9-gcc-14.3.0-libgcc\n  /nix/store/95k9rsn1zsw1yvir8mj824ldhf90i4qw-gcc-wrapper-14.3.0\n  /nix/store/776irwlgfb65a782cxmyk61pck460fs9-glibc-2.40-66\n  /nix/store/4jxivbjpr86wmsziqlf7iljlwjlxz8bh-glibc-2.40-66-bin\n  /nix/store/gf3wh0x0rzb1dkx0wx1jvmipydwfzzd5-glibc-2.40-66-dev\n  /nix/store/jbi3k3zbljsd340mrkpqwm4q4qm9bbkw-gmp-6.3.0\n  /nix/store/b7pkrm3rv0sydsppr9abs4qsmcm7a4rv-gmp-with-cxx-6.3.0\n  /nix/store/k0190hq0n1n89h6rxkpkbgrqx5vj0mg5-gnu-config-2024-01-01\n  /nix/store/vlckk0vnmawq9wwh7ndkrwxlpv4h29yh-gnugrep-3.12\n  /nix/store/aqdvlkh0jdwkc22hh5vr9sl6qlw5ha74-gnumake-4.4.1\n  /nix/store/pmhkmqy0vxk47r6ndh0azybhf6gs6k25-gnused-4.9\n  /nix/store/8av8pfs7bnyc6hqj764ns4z1fnr9bva1-gnutar-1.35\n  /nix/store/1ispb16svjqwv4l2amy4jfygy5k8pkdr-gtest-1.17.0\n  /nix/store/i4jy5k3i83gdcz76d7i7ymp500rz63pw-gtest-1.17.0-dev\n  /nix/store/8gsxxh82rf957ffbsk0q9670nhvl5lia-gzip-1.14\n  /nix/store/w24hkb1b9v50r3sgpvmk8kwyi04x7imq-icu4c-76.1\n  /nix/store/083x1zrd8rnrkq1plphxvc2vdzgk8dvj-icu4c-76.1-dev\n  /nix/store/h9hb4qj3k5gijb365kgqmkib7p2fkqzh-isl-0.20\n  /nix/store/1vw3n1caad61rdg020qgsil21db98x7j-keyutils-1.6.3-lib\n  /nix/store/jlf1dhlhcn8xk3swlxc9y3a0yrina46w-krb5-1.22.1-lib\n  /nix/store/flqs48a2h0jbls6k3las4qgq7yhbickc-libarchive-3.8.1-lib\n  /nix/store/wwqyxsvmg41q5ckfvvv6wa50nwvz9dv4-libidn2-2.3.8\n  /nix/store/5q5z85zacyhr098ixzlqqagd1fzngp6y-libmpc-1.3.1\n  /nix/store/0ncz9ijx5slwskb2bbbacygs8apnm6rg-libsodium-1.0.20\n  /nix/store/b6h4f5dcyn0dbi8a9b6nk8z6k7isjrvk-libsodium-1.0.20-dev\n  /nix/store/va3w14p49xm87pnmxavk4j3imnqzb03m-libssh2-1.11.1\n  /nix/store/7ndy5820h69n1pgd13viph1qjq6zhhkj-libunistring-1.3\n  /nix/store/c829k68fsf2pz2hd4acar8plin4dn78z-libuv-1.51.0\n  /nix/store/zamqz08gyq11cbbi2f3ciwmynkvsfk5n-libxml2-2.14.5\n  /nix/store/cl6lxy8k94czd0v02m8db9xahrpzlfz4-linux-headers-6.16\n  /nix/store/0wsd373lycsq0g3lav7gpmldw99g0sqf-mpfr-4.2.2\n  /nix/store/did4qx8g0fx4kyiyk9imhbbyhdg8mjba-nghttp2-1.66.0-lib\n  /nix/store/7bgiqc706pzzb1gmwgpzdfg491w4a8nx-ninja-1.13.1\n  /nix/store/r82wggrhgs0v2kkp0f2g9jplc4mfh2gq-nlohmann_json-3.11.3\n  /nix/store/gi615r79j260ihhzdkhrg6qva9wfrbyy-openssl-3.5.1\n  /nix/store/856i1ajaci3kmmp15rifacfz3jvn5l3q-patch-2.8\n  /nix/store/gx2l0rnp3qcnysdddkg9dqnh2mz6w08k-patchelf-0.15.2\n  /nix/store/y667mbdld0s8rmb2i493ldyfh3lsgk1y-pcre2-10.44\n  /nix/store/4my6a75b8p1w734w7crqfw69jw7xarla-pkg-config-0.29.2\n  /nix/store/05h9vfzhqf7l6w1xczixici2ldw9y788-pkg-config-wrapper-0.29.2\n  /nix/store/d72w1pf3fjmfz1l5fyd3y06l4cfsp740-rhash-1.4.4\n  /nix/store/jrw7q6v8q74hhv43zgpq7i4jmxj9nwlj-stdenv-linux\n  /nix/store/jwjq0fjgn7d00kswhaw2m8hbgws5vbi4-update-autotools-gnu-config-scripts-hook\n  /nix/store/0ja5daq2yay3svg6f48spyfby7pgy5bm-xgcc-14.3.0-libgcc\n  /nix/store/mjszfnqrfid0c9b4dnaydkz43cmg23k7-xz-5.8.1\n  /nix/store/y9kgzp85ykrhd7l691w4djx121qygy68-xz-5.8.1-bin\n  /nix/store/09sifcahf0j1xnw80k9l33jzcs1p2qbw-zlib-1.3.1\n  /nix/store/29mcvdnd9s6sp46cjmqm0pfg4xs56rik-zlib-1.3.1-dev\n  /nix/store/bxn7mqdrckhjkmvy5ynhybmj0lmdlgb4-zstd-1.5.7\ncopying path '/nix/store/9kqdjbbsmhkf2cs45w041pbncljyvz7f-cpp-semver-0.4.0' from 'https://logos-co.cachix.org'...\ncopying path '/nix/store/r82wggrhgs0v2kkp0f2g9jplc4mfh2gq-nlohmann_json-3.11.3' from 'https://cache.nixos.org'...\ncopying path '/nix/store/8zm936ys1dkqv2710j0w09r2mk0kj5n9-gcc-14.3.0-libgcc' from 'https://cache.nixos.org'...\ncopying path '/nix/store/k0190hq0n1n89h6rxkpkbgrqx5vj0mg5-gnu-config-2024-01-01' from 'https://cache.nixos.org'...\ncopying path '/nix/store/cl6lxy8k94czd0v02m8db9xahrpzlfz4-linux-headers-6.16' from 'https://cache.nixos.org'...\ncopying path '/nix/store/0ja5daq2yay3svg6f48spyfby7pgy5bm-xgcc-14.3.0-libgcc' from 'https://cache.nixos.org'...\ncopying path '/nix/store/7ndy5820h69n1pgd13viph1qjq6zhhkj-libunistring-1.3' from 'https://cache.nixos.org'...\ncopying path '/nix/store/jwjq0fjgn7d00kswhaw2m8hbgws5vbi4-update-autotools-gnu-config-scripts-hook' from 'https://cache.nixos.org'...\ncopying path '/nix/store/wwqyxsvmg41q5ckfvvv6wa50nwvz9dv4-libidn2-2.3.8' from 'https://cache.nixos.org'...\ncopying path '/nix/store/776irwlgfb65a782cxmyk61pck460fs9-glibc-2.40-66' from 'https://cache.nixos.org'...\ncopying path '/nix/store/877drgyy4926ps2qfraaxsd49w90bwiz-attr-2.5.2' from 'https://cache.nixos.org'...\ncopying path '/nix/store/x1nn5jrx1im7wmmn1xmpjvyf072s5k75-bzip2-1.0.8' from 'https://cache.nixos.org'...\ncopying path '/nix/store/q7sqwn7i6w2b67adw0bmix29pxg85x3w-bash-5.3p3' from 'https://cache.nixos.org'...\ncopying path '/nix/store/41ym1jm1b7j3rhglk82gwg9jml26z1km-gcc-14.3.0-lib' from 'https://cache.nixos.org'...\ncopying path '/nix/store/xxris3l81hc2c8ibx8fcyimwqpvfh2pp-ed-1.21.1' from 'https://cache.nixos.org'...\ncopying path '/nix/store/wdbr9yrvz0vgsii826wlidr48m7rafdf-expat-2.7.1' from 'https://cache.nixos.org'...\ncopying path '/nix/store/7k857h95ra7vwwsay8mz5han65f9n4cq-expand-response-params' from 'https://cache.nixos.org'...\ncopying path '/nix/store/03nvbw411p097h6yxjghc33rbcrjfb9d-gawk-5.3.2' from 'https://cache.nixos.org'...\ncopying path '/nix/store/4jxivbjpr86wmsziqlf7iljlwjlxz8bh-glibc-2.40-66-bin' from 'https://cache.nixos.org'...\ncopying path '/nix/store/jbi3k3zbljsd340mrkpqwm4q4qm9bbkw-gmp-6.3.0' from 'https://cache.nixos.org'...\ncopying path '/nix/store/aqdvlkh0jdwkc22hh5vr9sl6qlw5ha74-gnumake-4.4.1' from 'https://cache.nixos.org'...\ncopying path '/nix/store/1vw3n1caad61rdg020qgsil21db98x7j-keyutils-1.6.3-lib' from 'https://cache.nixos.org'...\ncopying path '/nix/store/pmhkmqy0vxk47r6ndh0azybhf6gs6k25-gnused-4.9' from 'https://cache.nixos.org'...\ncopying path '/nix/store/0ncz9ijx5slwskb2bbbacygs8apnm6rg-libsodium-1.0.20' from 'https://cache.nixos.org'...\ncopying path '/nix/store/zamqz08gyq11cbbi2f3ciwmynkvsfk5n-libxml2-2.14.5' from 'https://cache.nixos.org'...\ncopying path '/nix/store/c829k68fsf2pz2hd4acar8plin4dn78z-libuv-1.51.0' from 'https://cache.nixos.org'...\ncopying path '/nix/store/did4qx8g0fx4kyiyk9imhbbyhdg8mjba-nghttp2-1.66.0-lib' from 'https://cache.nixos.org'...\ncopying path '/nix/store/6yjb3zdj448rm8qsmpiq3f67kvj5683a-bzip2-1.0.8-bin' from 'https://cache.nixos.org'...\ncopying path '/nix/store/gi615r79j260ihhzdkhrg6qva9wfrbyy-openssl-3.5.1' from 'https://cache.nixos.org'...\ncopying path '/nix/store/y667mbdld0s8rmb2i493ldyfh3lsgk1y-pcre2-10.44' from 'https://cache.nixos.org'...\ncopying path '/nix/store/3apspx5fhyb83153axf1b80ifiklgjbh-acl-2.3.2' from 'https://cache.nixos.org'...\ncopying path '/nix/store/856i1ajaci3kmmp15rifacfz3jvn5l3q-patch-2.8' from 'https://cache.nixos.org'...\ncopying path '/nix/store/4my6a75b8p1w734w7crqfw69jw7xarla-pkg-config-0.29.2' from 'https://cache.nixos.org'...\ncopying path '/nix/store/d72w1pf3fjmfz1l5fyd3y06l4cfsp740-rhash-1.4.4' from 'https://cache.nixos.org'...\ncopying path '/nix/store/mjszfnqrfid0c9b4dnaydkz43cmg23k7-xz-5.8.1' from 'https://cache.nixos.org'...\ncopying path '/nix/store/09sifcahf0j1xnw80k9l33jzcs1p2qbw-zlib-1.3.1' from 'https://cache.nixos.org'...\ncopying path '/nix/store/h9hb4qj3k5gijb365kgqmkib7p2fkqzh-isl-0.20' from 'https://cache.nixos.org'...\ncopying path '/nix/store/b6h4f5dcyn0dbi8a9b6nk8z6k7isjrvk-libsodium-1.0.20-dev' from 'https://cache.nixos.org'...\ncopying path '/nix/store/8gsxxh82rf957ffbsk0q9670nhvl5lia-gzip-1.14' from 'https://cache.nixos.org'...\ncopying path '/nix/store/0wsd373lycsq0g3lav7gpmldw99g0sqf-mpfr-4.2.2' from 'https://cache.nixos.org'...\ncopying path '/nix/store/8av8pfs7bnyc6hqj764ns4z1fnr9bva1-gnutar-1.35' from 'https://cache.nixos.org'...\ncopying path '/nix/store/gf3wh0x0rzb1dkx0wx1jvmipydwfzzd5-glibc-2.40-66-dev' from 'https://cache.nixos.org'...\ncopying path '/nix/store/d6h99jhxcpi2b09n3kgw75jx99aslxv2-binutils-2.44-lib' from 'https://cache.nixos.org'...\ncopying path '/nix/store/29mcvdnd9s6sp46cjmqm0pfg4xs56rik-zlib-1.3.1-dev' from 'https://cache.nixos.org'...\ncopying path '/nix/store/v40ijzz8p2fpk9ihjck3a1ncqaqfmn3c-file-5.45' from 'https://cache.nixos.org'...\ncopying path '/nix/store/05h9vfzhqf7l6w1xczixici2ldw9y788-pkg-config-wrapper-0.29.2' from 'https://cache.nixos.org'...\ncopying path '/nix/store/vlckk0vnmawq9wwh7ndkrwxlpv4h29yh-gnugrep-3.12' from 'https://cache.nixos.org'...\ncopying path '/nix/store/y9kgzp85ykrhd7l691w4djx121qygy68-xz-5.8.1-bin' from 'https://cache.nixos.org'...\ncopying path '/nix/store/5q5z85zacyhr098ixzlqqagd1fzngp6y-libmpc-1.3.1' from 'https://cache.nixos.org'...\ncopying path '/nix/store/c43ry7z24x3jhnjlj4gpay8a4g2p3x1h-binutils-2.44' from 'https://cache.nixos.org'...\ncopying path '/nix/store/82kmz7r96navanrc2fgckh2bamiqrgsw-gcc-14.3.0' from 'https://cache.nixos.org'...\ncopying path '/nix/store/1ispb16svjqwv4l2amy4jfygy5k8pkdr-gtest-1.17.0' from 'https://cache.nixos.org'...\ncopying path '/nix/store/b7pkrm3rv0sydsppr9abs4qsmcm7a4rv-gmp-with-cxx-6.3.0' from 'https://cache.nixos.org'...\ncopying path '/nix/store/w24hkb1b9v50r3sgpvmk8kwyi04x7imq-icu4c-76.1' from 'https://cache.nixos.org'...\ncopying path '/nix/store/7bgiqc706pzzb1gmwgpzdfg491w4a8nx-ninja-1.13.1' from 'https://cache.nixos.org'...\ncopying path '/nix/store/gx2l0rnp3qcnysdddkg9dqnh2mz6w08k-patchelf-0.15.2' from 'https://cache.nixos.org'...\ncopying path '/nix/store/bxn7mqdrckhjkmvy5ynhybmj0lmdlgb4-zstd-1.5.7' from 'https://cache.nixos.org'...\ncopying path '/nix/store/8ksax0a2mxglr5hlkj2dzl556jx7xqn5-coreutils-9.7' from 'https://cache.nixos.org'...\ncopying path '/nix/store/i4jy5k3i83gdcz76d7i7ymp500rz63pw-gtest-1.17.0-dev' from 'https://cache.nixos.org'...\ncopying path '/nix/store/jlf1dhlhcn8xk3swlxc9y3a0yrina46w-krb5-1.22.1-lib' from 'https://cache.nixos.org'...\ncopying path '/nix/store/va3w14p49xm87pnmxavk4j3imnqzb03m-libssh2-1.11.1' from 'https://cache.nixos.org'...\ncopying path '/nix/store/flqs48a2h0jbls6k3las4qgq7yhbickc-libarchive-3.8.1-lib' from 'https://cache.nixos.org'...\ncopying path '/nix/store/s2fvny566vls74p4qm9v3fdqd741fh3f-diffutils-3.12' from 'https://cache.nixos.org'...\ncopying path '/nix/store/l964krgbp613d5jxga2vy5qdssj7zfzj-findutils-4.10.0' from 'https://cache.nixos.org'...\ncopying path '/nix/store/222cks9f8yjhdvyk4x8iyp05pyci5xpj-curl-8.14.1' from 'https://cache.nixos.org'...\ncopying path '/nix/store/a94d5zmalqava26y3hqsnj5l11l5kl5y-cmake-3.31.7' from 'https://cache.nixos.org'...\ncopying path '/nix/store/l19cddv64i52rhcwahif8sgyrd3mhiqb-binutils-wrapper-2.44' from 'https://cache.nixos.org'...\ncopying path '/nix/store/083x1zrd8rnrkq1plphxvc2vdzgk8dvj-icu4c-76.1-dev' from 'https://cache.nixos.org'...\ncopying path '/nix/store/95k9rsn1zsw1yvir8mj824ldhf90i4qw-gcc-wrapper-14.3.0' from 'https://cache.nixos.org'...\ncopying path '/nix/store/jrw7q6v8q74hhv43zgpq7i4jmxj9nwlj-stdenv-linux' from 'https://cache.nixos.org'...\nbuilding '/nix/store/nq0i0y7mbarzl33wqqgr4y04ypvaig9q-lgx-0.1.0.drv'...\n", "note": ""}]}, {"md": "### 1.2 Confirm it runs\n\n```bash\n./lgx/bin/lgx --version\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx --version", "status": "pass", "exit_code": 0, "output": "lgx version 0.1.0\n", "note": ""}]}, {"md": "## Step 2: Detect the platform variant\n\nAn `.lgx` package carries one or more **platform variants** \u2014 `linux-x86_64`,\n`darwin-arm64`, and so on \u2014 each holding the payload for that platform. Detect this\nmachine's variant once (and the matching shared-library extension, `.so` on Linux /\n`.dylib` on macOS) and stash both in files so the packaging steps below can reuse\nthem.", "execs": []}, {"md": "### 2.1 Write the variant and library extension to ./variant and ./ext\n\n```bash\ncase \"$(uname -s) $(uname -m)\" in\n  \"Linux x86_64\")   echo linux-x86_64  > variant; echo so    > ext ;;\n  \"Linux aarch64\")  echo linux-arm64   > variant; echo so    > ext ;;\n  \"Darwin arm64\")   echo darwin-arm64  > variant; echo dylib > ext ;;\n  \"Darwin x86_64\")  echo darwin-x86_64 > variant; echo dylib > ext ;;\n  *) echo \"unsupported platform: $(uname -sm)\" >&2; exit 1 ;;\nesac\necho \"variant: $(cat variant)  ext: $(cat ext)\"\n\n```", "execs": [{"kind": "run", "cmd": "case \"$(uname -s) $(uname -m)\" in\n  \"Linux x86_64\")   echo linux-x86_64  > variant; echo so    > ext ;;\n  \"Linux aarch64\")  echo linux-arm64   > variant; echo so    > ext ;;\n  \"Darwin arm64\")   echo darwin-arm64  > variant; echo dylib > ext ;;\n  \"Darwin x86_64\")  echo darwin-x86_64 > variant; echo dylib > ext ;;\n  *) echo \"unsupported platform: $(uname -sm)\" >&2; exit 1 ;;\nesac\necho \"variant: $(cat variant)  ext: $(cat ext)\"\n", "status": "pass", "exit_code": 0, "output": "variant: linux-x86_64  ext: so\n", "note": ""}]}, {"md": "## Step 3: Create a package\n\n`lgx create <name>` writes an empty skeleton package \u2014 a `manifest.json` with\nsensible defaults plus an empty `variants/` directory \u2014 to `<name>.lgx`.", "execs": []}, {"md": "### 3.1 Create greeter.lgx\n\n```bash\n./lgx/bin/lgx create greeter\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx create greeter", "status": "pass", "exit_code": 0, "output": "Created package: greeter.lgx\n", "note": ""}]}, {"md": "### 3.2 Read the fresh manifest\n\n`lgx manifest` prints the embedded `manifest.json` in human-readable form. A\nfreshly created package starts at version `0.0.1`, manifest schema `0.3.0`, with\nno type, no variants, and no signature yet.\n\n```bash\nlgx manifest greeter.lgx\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx manifest greeter.lgx", "status": "pass", "exit_code": 0, "output": "Name:           greeter\nDisplay name:   (unset \u2014 falls back to name)\nVersion:        0.0.1\nManifest ver.:  0.3.0\nType:           (unset)\nCategory:       (unset)\nAuthor:         (unset)\nVariants:       (none)\nDependencies:   (none)\nSigned:         no\n", "note": ""}]}, {"md": "## Step 4: Add a platform variant\n\n`lgx add` drops a payload into the package under `variants/<variant>/` and records\nthe entry point in the manifest's `main` map. We add a stub shared library for this\nmachine's variant. (In a real build the payload is the module's compiled `.so` /\n`.dylib`; `lgx` does not load it \u2014 it just packages it.)", "execs": []}, {"md": "### 4.1 Add this machine's variant\n\n```bash\n# On Linux x86_64 this expands to:\necho 'stub library' > libgreeter.so\nlgx add greeter.lgx --variant linux-x86_64 --files libgreeter.so\n```\n\nConfirm the archive layout \u2014 a `manifest.json` beside the `variants/` tree:\n\n```bash\ntar -tzf greeter.lgx\n```\n\n```\nmanifest.json\nvariants/\nvariants/<platform>/\nvariants/<platform>/libgreeter.so   # .dylib on macOS\n```", "execs": [{"kind": "run", "cmd": "V=\"$(cat variant)\"; E=\"$(cat ext)\"\necho 'stub library' > \"libgreeter.$E\"\n./lgx/bin/lgx add greeter.lgx --variant \"$V\" --files \"libgreeter.$E\"\n", "status": "pass", "exit_code": 0, "output": "Added variant 'linux-x86_64' to greeter.lgx\n", "note": ""}, {"kind": "run", "cmd": "tar -tzf greeter.lgx", "status": "pass", "exit_code": 0, "output": "manifest.json\nvariants/\nvariants/linux-x86_64/\nvariants/linux-x86_64/libgreeter.so\n", "note": ""}]}, {"md": "### 4.2 See the variant in the manifest\n\nThe manifest now lists the variant and points its `main` entry at the file we\nadded. A content hash (`Root hash`) is recomputed on every save.\n\n```bash\nlgx manifest greeter.lgx\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx manifest greeter.lgx", "status": "pass", "exit_code": 0, "output": "Name:           greeter\nDisplay name:   (unset \u2014 falls back to name)\nVersion:        0.0.1\nManifest ver.:  0.3.0\nType:           (unset)\nCategory:       (unset)\nAuthor:         (unset)\nRoot hash:      d6f9791116bf7a8458fdb72f0e3973a5d4ab60bf66fc885b9e8410b69b9c6b19\nVariants:       linux-x86_64\n                linux-x86_64 -> libgreeter.so\nDependencies:   (none)\nSigned:         no\n", "note": ""}]}, {"md": "## Step 5: Verify the package\n\n`lgx verify` validates a package against the LGX spec \u2014 it recomputes the content\nhashes (the Merkle tree) and checks them against the manifest, then reports the\nsignature state. Our package is unsigned, so verification passes and notes it is\nunsigned. The exit code is `0` on success, so `verify` is safe to gate CI on.", "execs": []}, {"md": "### 5.1 Verify greeter.lgx\n\n```bash\nlgx verify greeter.lgx\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx verify greeter.lgx", "status": "pass", "exit_code": 0, "output": "Package structure is valid: greeter.lgx\nPackage is unsigned\n", "note": ""}]}, {"md": "## Step 6: Extract a variant\n\n`lgx extract` unpacks a variant's payload back onto disk \u2014 the inverse of `add`.\nFiles land under `<output>/<variant>/`.", "execs": []}, {"md": "### 6.1 Extract this machine's variant\n\n```bash\nlgx extract greeter.lgx --variant linux-x86_64 --output ./extracted\n```\n\nThe payload is now on disk under `./extracted/<variant>/`:\n\n```bash\nls ./extracted/<variant>\n```", "execs": [{"kind": "run", "cmd": "V=\"$(cat variant)\"\n./lgx/bin/lgx extract greeter.lgx --variant \"$V\" --output ./extracted\n", "status": "pass", "exit_code": 0, "output": "Extracted variant 'linux-x86_64' to ./extracted\n", "note": ""}, {"kind": "run", "cmd": "V=\"$(cat variant)\"\nls \"./extracted/$V\"\n", "status": "pass", "exit_code": 0, "output": "libgreeter.so\n", "note": ""}]}, {"md": "## Step 7: Merge per-platform packages\n\nReal releases ship one `.lgx` covering every platform. A common pattern is to build\na **single-variant** package on each platform's CI runner, then `lgx merge` them\ninto one multi-variant archive. The inputs must share identical metadata (only the\nvariant-specific `main` entries differ). We simulate it here by hand-building a\nLinux and a macOS package for the same module and merging them.", "execs": []}, {"md": "### 7.1 Build two single-variant packages\n\n```bash\n# A Linux-only package...\n./lgx/bin/lgx create widget && mv widget.lgx widget-linux.lgx\necho 'linux stub' > libwidget.so\n./lgx/bin/lgx add widget-linux.lgx --variant linux-x86_64 --files libwidget.so\n\n# ...and a macOS-only package for the same module.\n./lgx/bin/lgx create widget && mv widget.lgx widget-darwin.lgx\necho 'darwin stub' > libwidget.dylib\n./lgx/bin/lgx add widget-darwin.lgx --variant darwin-arm64 --files libwidget.dylib\n\n```", "execs": [{"kind": "run", "cmd": "# A Linux-only package...\n./lgx/bin/lgx create widget && mv widget.lgx widget-linux.lgx\necho 'linux stub' > libwidget.so\n./lgx/bin/lgx add widget-linux.lgx --variant linux-x86_64 --files libwidget.so\n\n# ...and a macOS-only package for the same module.\n./lgx/bin/lgx create widget && mv widget.lgx widget-darwin.lgx\necho 'darwin stub' > libwidget.dylib\n./lgx/bin/lgx add widget-darwin.lgx --variant darwin-arm64 --files libwidget.dylib\n", "status": "pass", "exit_code": 0, "output": "Created package: widget.lgx\nAdded variant 'linux-x86_64' to widget-linux.lgx\nCreated package: widget.lgx\nAdded variant 'darwin-arm64' to widget-darwin.lgx\n", "note": ""}]}, {"md": "### 7.2 Merge them into one .lgx\n\n`lgx merge` writes a single package carrying both variants. The variants are\nlisted alphabetically in the summary.\n\n```bash\nlgx merge widget-linux.lgx widget-darwin.lgx -o widget.lgx\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx merge widget-linux.lgx widget-darwin.lgx -o widget.lgx", "status": "pass", "exit_code": 0, "output": "Merged 2 packages into widget.lgx (darwin-arm64, linux-x86_64)\n", "note": ""}]}, {"md": "### 7.3 Confirm both variants are present\n\nThe merged manifest carries both platforms, and the package verifies:\n\n```bash\nlgx manifest widget.lgx\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx manifest widget.lgx", "status": "pass", "exit_code": 0, "output": "Name:           widget\nDisplay name:   (unset \u2014 falls back to name)\nVersion:        0.0.1\nManifest ver.:  0.3.0\nType:           (unset)\nCategory:       (unset)\nAuthor:         (unset)\nRoot hash:      0a75dda1458cfde4e1d28487da541307631fab66c797942c4e5f0ce9fe4a23d8\nVariants:       darwin-arm64, linux-x86_64\n                darwin-arm64 -> libwidget.dylib\n                linux-x86_64 -> libwidget.so\nDependencies:   (none)\nSigned:         no\n", "note": ""}]}, {"md": "```bash\nlgx verify widget.lgx\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx verify widget.lgx", "status": "pass", "exit_code": 0, "output": "Package structure is valid: widget.lgx\nPackage is unsigned\n", "note": ""}]}, {"md": "## Recap\n\nYou built `lgx` from this commit and ran a full packaging lifecycle \u2014 creating a\npackage, adding a platform variant, verifying it, extracting it, and merging\nper-platform packages into one multi-variant `.lgx`:\n\n| Command | What it does |\n|---|---|\n| `create <name>` | Write an empty skeleton `<name>.lgx` |\n| `add <pkg> -v <variant> -f <path>` | Add a payload for a variant (records `main`) |\n| `manifest <pkg> [--json]` | Print the embedded `manifest.json` (`--json` for raw bytes) |\n| `verify <pkg>` | Validate structure + content hashes, report signature state |\n| `extract <pkg> -v <variant> -o <dir>` | Unpack a variant's payload to disk |\n| `merge <pkg\u2026> -o <out>` | Combine single-variant packages into one multi-variant `.lgx` |\n\nSigning, signature inspection, and trusted-key management are covered in the\ncompanion [signing doc-test](lgx-signing.md).", "execs": []}]}, {"meta": {"name": "Signing and Trusting an lgx Package", "platform": "Linux (ext=so)", "release": "(none)"}, "rows": [{"md": "# Signing and Trusting an lgx Package\n\n[`lgx`](https://github.com/logos-co/logos-package) packages can be **signed** so\nconsumers can verify who produced them. Signing uses an **Ed25519** keypair whose public\nhalf is published as a [`did:jwk:`](https://github.com/quartzjer/did-jwk/blob/main/spec.md)\ndecentralized identifier; `lgx sign` writes a `manifest.sig` next to the manifest, and\n`lgx verify` checks it. A **keyring** of trusted DIDs lets `verify` go one step further\nand report whether the signer is one you trust.\n\nThis doc-test builds **this** `lgx` commit and runs the full signing-and-trust lifecycle:\n\n1. Build `lgx` and create a small package to sign.\n2. `keygen` an Ed25519 keypair (printing its `did:jwk:` DID).\n3. `sign` the package and inspect the signature with `manifest` and `signature`.\n4. `verify` it \u2014 first as an *untrusted* signer, then after adding the DID to a keyring.\n\nEvery key directory is passed explicitly (`--output-dir`, `--keys-dir`, `--keyring-dir`)\nso the whole flow is self-contained and never touches your real `~/.config/logos`.\n\n**What you'll build:** A signed `greeter.lgx`, an Ed25519 signing key, and a trusted-key keyring that makes `lgx verify` recognise the signer.\n\n**What you'll learn:**\n\n- How to generate an Ed25519 signing keypair and its `did:jwk:` DID with `lgx keygen`\n- How to sign a package and read back its signature with `lgx sign` / `lgx signature`\n- How `lgx verify` reports signature validity and distinguishes trusted from untrusted signers\n- How to manage trusted DIDs with `lgx keyring add` / `list`\n\n## Prerequisites\n\n- **Nix** with flakes enabled. Install from [nixos.org](https://nixos.org/download.html), then enable flakes:\n\n```bash\nmkdir -p ~/.config/nix\necho 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf\n```\n\nVerify: `nix flake --help >/dev/null 2>&1 && echo \"Flakes enabled\"`\n\n- A Linux or macOS machine.", "execs": []}, {"md": "## Step 1: Build lgx and create a package to sign\n\nBuild the `lgx` CLI from this commit, then create a one-variant package \u2014 the thing\nwe will sign. (The [packaging doc-test](lgx-cli.md) covers `create` / `add` in\ndetail; here they are just setup.)\n\n> The `` placeholder pins the build to the commit under test (this\n> checkout's `HEAD` locally, the PR/push commit in CI). Against a local checkout use\n> `nix build '.#lgx' -o lgx`.", "execs": []}, {"md": "### 1.1 Build lgx\n\n```bash\n# From inside the clone this is simply: nix build '.#lgx' -o lgx\nnix build 'github:logos-co/logos-package/5627ae3aeace560fd8c64d79d38f46e7cf94cf3b#lgx' -o lgx\n```", "execs": [{"kind": "run", "cmd": "nix build 'github:logos-co/logos-package/5627ae3aeace560fd8c64d79d38f46e7cf94cf3b#lgx' -o lgx", "status": "pass", "exit_code": 0, "output": "", "note": ""}]}, {"md": "### 1.2 Create and populate greeter.lgx\n\nDetect this machine's variant (and shared-library extension), create the\npackage, and add a stub payload so there is content to sign.\n\n```bash\nlgx create greeter\necho 'stub library' > libgreeter.so          # .dylib on macOS\nlgx add greeter.lgx --variant linux-x86_64 --files libgreeter.so\n```", "execs": [{"kind": "run", "cmd": "case \"$(uname -s) $(uname -m)\" in\n  \"Linux x86_64\")   V=linux-x86_64;  E=so ;;\n  \"Linux aarch64\")  V=linux-arm64;   E=so ;;\n  \"Darwin arm64\")   V=darwin-arm64;  E=dylib ;;\n  \"Darwin x86_64\")  V=darwin-x86_64; E=dylib ;;\n  *) echo \"unsupported platform: $(uname -sm)\" >&2; exit 1 ;;\nesac\n./lgx/bin/lgx create greeter\necho 'stub library' > \"libgreeter.$E\"\n./lgx/bin/lgx add greeter.lgx --variant \"$V\" --files \"libgreeter.$E\"\n", "status": "pass", "exit_code": 0, "output": "Created package: greeter.lgx\nAdded variant 'linux-x86_64' to greeter.lgx\n", "note": ""}]}, {"md": "## Step 2: Generate a signing key\n\n`lgx keygen` creates an Ed25519 keypair and writes three files \u2014 the secret key\n(`.jwk`), the public key (`.pub`), and the DID string (`.did`). It prints the\n`did:jwk:` DID to stdout. We point `--output-dir` at a local `./keys` directory and\nstash the DID in a file so later steps can refer to it.", "execs": []}, {"md": "### 2.1 Run keygen into ./keys\n\n`keygen` prints the DID to stdout and also writes it to `./keys/demo-key.did`. We\ncopy that file to `./did.txt` so later steps can pass the exact DID without\nre-deriving it.\n\n```bash\nlgx keygen --name demo-key --output-dir ./keys\n# \u2192 did:jwk:eyJjcnYiOiJFZDI1NTE5Ii...   (also saved to ./keys/demo-key.did)\n```\n\nThe keypair now lives under `./keys/` as `demo-key.{jwk,pub,did}`. The `.jwk`\nfile is the **secret** key \u2014 keep it safe; only the DID is meant to be shared.", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx keygen --name demo-key --output-dir ./keys\ncp ./keys/demo-key.did did.txt\n", "status": "pass", "exit_code": 0, "output": "did:jwk:eyJjcnYiOiJFZDI1NTE5Iiwia3R5IjoiT0tQIiwieCI6IllwcTdEcXVqX0ZZZC14Sk1KZEJTRjdtSW1GWjBGNG9pR0Q5T1U5MGVkaGsifQ\nKeypair generated: ./keys/demo-key.{jwk,pub,did}\n", "note": ""}]}, {"md": "## Step 3: Sign the package\n\n`lgx sign` validates the package, then writes a `manifest.sig` containing the\nsigner's DID, an Ed25519 signature over the manifest bytes, and optional\nself-asserted signer metadata (`--name` / `--url`). We pass `--keys-dir ./keys` so it\nfinds the key we just generated.", "execs": []}, {"md": "### 3.1 Sign greeter.lgx\n\n```bash\nlgx sign greeter.lgx --key demo-key --keys-dir ./keys \\\n  --name \"Logos Demo\" --url \"https://logos.co\"\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx sign greeter.lgx --key demo-key --keys-dir ./keys \\\n  --name \"Logos Demo\" --url \"https://logos.co\"\n", "status": "pass", "exit_code": 0, "output": "Package signed: greeter.lgx\nSigner DID: did:jwk:eyJjcnYiOiJFZDI1NTE5Iiwia3R5IjoiT0tQIiwieCI6IllwcTdEcXVqX0ZZZC14Sk1KZEJTRjdtSW1GWjBGNG9pR0Q5T1U5MGVkaGsifQ\n", "note": ""}]}, {"md": "### 3.2 See the signature in the manifest\n\n`lgx manifest` now reports the package as signed, along with the signer's DID and\nself-asserted name/URL.\n\n```bash\nlgx manifest greeter.lgx\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx manifest greeter.lgx", "status": "pass", "exit_code": 0, "output": "Name:           greeter\nDisplay name:   (unset \u2014 falls back to name)\nVersion:        0.0.1\nManifest ver.:  0.3.0\nType:           (unset)\nCategory:       (unset)\nAuthor:         (unset)\nRoot hash:      d6f9791116bf7a8458fdb72f0e3973a5d4ab60bf66fc885b9e8410b69b9c6b19\nVariants:       linux-x86_64\n                linux-x86_64 -> libgreeter.so\nDependencies:   (none)\nSigned:         yes\nSigner DID:     did:jwk:eyJjcnYiOiJFZDI1NTE5Iiwia3R5IjoiT0tQIiwieCI6IllwcTdEcXVqX0ZZZC14Sk1KZEJTRjdtSW1GWjBGNG9pR0Q5T1U5MGVkaGsifQ\nSigner name:    Logos Demo (self-asserted)\nSigner URL:     https://logos.co (self-asserted)\n", "note": ""}]}, {"md": "### 3.3 Read the raw signature\n\n`lgx signature` prints the raw `manifest.sig` JSON \u2014 byte-identical to the file\ninside the `.lgx`. It carries the algorithm, the signer DID, the base64\nsignature, and the signer metadata. Unsigned packages print nothing and exit 0,\nso tooling tells \"unsigned\" from \"error\" by the exit status, not the output.\n\n```bash\nlgx signature greeter.lgx\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx signature greeter.lgx", "status": "pass", "exit_code": 0, "output": "{\n  \"algorithm\": \"ed25519\",\n  \"did\": \"did:jwk:eyJjcnYiOiJFZDI1NTE5Iiwia3R5IjoiT0tQIiwieCI6IllwcTdEcXVqX0ZZZC14Sk1KZEJTRjdtSW1GWjBGNG9pR0Q5T1U5MGVkaGsifQ\",\n  \"linkedDids\": [],\n  \"signature\": \"B/+LL/CwuJUyrzuja37FAEurjgaQ9fcNso08gyu7HrQ8uQuzXt+W+Q49oEKdlqJYqg3kDjfWs893JnaxgBTNBw==\",\n  \"signer\": {\n    \"name\": \"Logos Demo\",\n    \"url\": \"https://logos.co\"\n  },\n  \"version\": 1\n}", "note": ""}]}, {"md": "## Step 4: Verify an untrusted signer\n\n`lgx verify` always checks structure and (for signed packages) the signature itself.\nTrust is separate: with no matching entry in the keyring, the signature is reported\n**valid** but the signer is flagged as **not** trusted. We point `--keyring-dir` at an\nempty `./trusted` directory to make that explicit.", "execs": []}, {"md": "### 4.1 Verify against an empty keyring\n\n```bash\nmkdir -p trusted\nlgx verify greeter.lgx --keyring-dir ./trusted\n```", "execs": [{"kind": "run", "cmd": "mkdir -p trusted\n./lgx/bin/lgx verify greeter.lgx --keyring-dir ./trusted\n", "status": "pass", "exit_code": 0, "output": "Package structure is valid: greeter.lgx\nSignature is valid\nSigner DID: did:jwk:eyJjcnYiOiJFZDI1NTE5Iiwia3R5IjoiT0tQIiwieCI6IllwcTdEcXVqX0ZZZC14Sk1KZEJTRjdtSW1GWjBGNG9pR0Q5T1U5MGVkaGsifQ\nSigner name (self-asserted): Logos Demo\nSigner URL (self-asserted): https://logos.co\nSigner DID is NOT in trusted keyring\n", "note": ""}]}, {"md": "## Step 5: Trust the signer\n\n`lgx keyring add` records a DID as trusted under a short name. We add the DID we\nstashed earlier (still in `did.txt`) to the `./trusted` keyring, then list it.", "execs": []}, {"md": "### 5.1 Add the DID to the keyring\n\n```bash\nlgx keyring add logos-demo \"$DID\" \\\n  --display-name \"Logos Demo\" --url \"https://logos.co\" --dir ./trusted\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx keyring add logos-demo \"$(cat did.txt)\" \\\n  --display-name \"Logos Demo\" --url \"https://logos.co\" --dir ./trusted\n", "status": "pass", "exit_code": 0, "output": "Added trusted key: logos-demo\nDID: did:jwk:eyJjcnYiOiJFZDI1NTE5Iiwia3R5IjoiT0tQIiwieCI6IllwcTdEcXVqX0ZZZC14Sk1KZEJTRjdtSW1GWjBGNG9pR0Q5T1U5MGVkaGsifQ\n", "note": ""}]}, {"md": "### 5.2 List trusted keys\n\n```bash\nlgx keyring list --dir ./trusted\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx keyring list --dir ./trusted", "status": "pass", "exit_code": 0, "output": "logos-demo (Logos Demo)\n  DID: did:jwk:eyJjcnYiOiJFZDI1NTE5Iiwia3R5IjoiT0tQIiwieCI6Illwc...\n  URL: https://logos.co\n  Added: 2026-08-10T22:17:19Z\n", "note": ""}]}, {"md": "## Step 6: Verify a trusted signer\n\nRe-run `verify` against the populated keyring. Now that the signer's DID is trusted,\n`verify` adds a final line naming the trusted key \u2014 the same valid signature, now\nrecognised.", "execs": []}, {"md": "### 6.1 Verify against the populated keyring\n\n```bash\nlgx verify greeter.lgx --keyring-dir ./trusted\n```", "execs": [{"kind": "run", "cmd": "./lgx/bin/lgx verify greeter.lgx --keyring-dir ./trusted", "status": "pass", "exit_code": 0, "output": "Package structure is valid: greeter.lgx\nSignature is valid\nSigner DID: did:jwk:eyJjcnYiOiJFZDI1NTE5Iiwia3R5IjoiT0tQIiwieCI6IllwcTdEcXVqX0ZZZC14Sk1KZEJTRjdtSW1GWjBGNG9pR0Q5T1U5MGVkaGsifQ\nSigner name (self-asserted): Logos Demo\nSigner URL (self-asserted): https://logos.co\nSigner is trusted: logos-demo\n", "note": ""}]}, {"md": "## Recap\n\nYou built `lgx` from this commit and ran the full signing-and-trust lifecycle \u2014\ngenerating a key, signing a package, inspecting the signature, and verifying it both\nas an untrusted and a trusted signer:\n\n| Command | What it does |\n|---|---|\n| `keygen --name <n> --output-dir <dir>` | Generate an Ed25519 keypair; print its `did:jwk:` DID |\n| `sign <pkg> --key <n> --keys-dir <dir> [--name \u2026] [--url \u2026]` | Write `manifest.sig` with the signer's DID |\n| `signature <pkg>` | Print the raw `manifest.sig` JSON (unsigned \u2192 empty + exit 0) |\n| `verify <pkg> [--keyring-dir <dir>]` | Validate structure + signature; report trust |\n| `keyring add <name> <did> [--dir <dir>]` | Trust a DID under a short name |\n| `keyring list [--dir <dir>]` | List trusted DIDs |\n\nCreating, adding variants, extracting, and merging packages are covered in the\ncompanion [packaging doc-test](lgx-cli.md).", "execs": []}]}]}</script>
+<script>
+  const DATA = JSON.parse(document.getElementById("report-data").textContent);
+  if (window.marked) { marked.setOptions({ gfm: true, breaks: false }); }
+  const mdToHtml = (s) => window.marked ? marked.parse(s || "") : ("<pre>" + (s || "") + "</pre>");
+
+  const sum = DATA.summary;
+  document.getElementById("summary").innerHTML =
+    `<span class="pill pass">${sum.passed} passed</span> ` +
+    (sum.failed ? `<span class="pill fail">${sum.failed} failed</span> ` : "") +
+    (sum.skipped ? `<span class="pill skip">${sum.skipped} skipped</span>` : "");
+
+  const picker = document.getElementById("picker");
+  DATA.tutorials.forEach((t, i) => {
+    const o = document.createElement("option");
+    o.value = i; o.textContent = t.meta.name; picker.appendChild(o);
+  });
+
+  function execHtml(e) {
+    const badge = `<span class="badge ${e.status}">${e.status.toUpperCase()}</span>`;
+    const kind = `<span class="kind">${e.kind}${e.exit_code !== undefined ? " · exit " + e.exit_code : ""}</span>`;
+    let h = `<div class="exec"><div class="exec-head">${badge}${kind}</div>`;
+    if (e.note) h += `<div class="note">${escapeHtml(e.note)}</div>`;
+    if (e.cmd) h += `<pre class="cmd">${escapeHtml(e.cmd)}</pre>`;
+    const out = (e.output || "").trim();
+    if (out) {
+      const long = out.split("\n").length > 12;
+      if (long) {
+        h += `<details><summary>output (${out.split("\n").length} lines)</summary><pre class="output">${escapeHtml(out)}</pre></details>`;
+      } else {
+        h += `<pre class="output">${escapeHtml(out)}</pre>`;
+      }
+    }
+    h += `</div>`;
+    return h;
+  }
+
+  function escapeHtml(s) {
+    return String(s).replace(/[&<>]/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" }[c]));
+  }
+
+  function render(idx) {
+    const t = DATA.tutorials[idx];
+    const main = document.getElementById("main");
+    main.innerHTML = "";
+    const h = document.createElement("div");
+    h.className = "tutorial-title";
+    h.textContent = t.meta.name + "  —  " + t.meta.platform;
+    main.appendChild(h);
+
+    t.rows.forEach(row => {
+      const isStructural = row.execs.length === 0 &&
+        (/^#\s|^##\s/.test(row.md.trim()));
+      const div = document.createElement("div");
+      const hasExec = row.execs.length > 0;
+      const hasFail = row.execs.some(e => e.status === "fail");
+      div.className = "row" + (hasExec ? "" : (isStructural ? " section" : " preamble")) +
+        (hasFail ? " has-fail" : "");
+
+      const left = document.createElement("div");
+      left.className = "col left";
+      left.innerHTML = `<div class="md">${mdToHtml(row.md)}</div>`;
+      div.appendChild(left);
+
+      if (hasExec || !isStructural) {
+        const right = document.createElement("div");
+        right.className = "col right";
+        if (hasExec) {
+          right.innerHTML = `<div class="col-label">Executed</div>` +
+            row.execs.map(execHtml).join("");
+        } else {
+          right.innerHTML = `<div class="col-label">Executed</div>` +
+            `<div class="empty">No commands run for this step.</div>`;
+        }
+        div.appendChild(right);
+      }
+      main.appendChild(div);
+    });
+
+    addAnchors(main, slug(t.meta.name));
+  }
+
+  function slug(s) {
+    return String(s).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  }
+
+  // Octicon "link" — the same glyph GitHub puts next to markdown headings.
+  const LINK_ICON =
+    '<svg viewBox="0 0 16 16" aria-hidden="true"><path fill="currentColor" d=' +
+    '"M7.775 3.275a.75.75 0 0 0 1.06 1.06l1.25-1.25a2 2 0 1 1 2.83 2.83l-2.5 2.5a2 2 0 0 1-2.83 0 ' +
+    '.75.75 0 0 0-1.06 1.06 3.5 3.5 0 0 0 4.95 0l2.5-2.5a3.5 3.5 0 0 0-4.95-4.95l-1.25 1.25Zm-4.69 ' +
+    '9.64a2 2 0 0 1 0-2.83l2.5-2.5a2 2 0 0 1 2.83 0 .75.75 0 0 0 1.06-1.06 3.5 3.5 0 0 0-4.95 0l-2.5 ' +
+    '2.5a3.5 3.5 0 0 0 4.95 4.95l1.25-1.25a.75.75 0 0 0-1.06-1.06l-1.25 1.25a2 2 0 0 1-2.83 0Z"></path></svg>';
+
+  // Give every heading a stable slug id (deduplicated the way GitHub does, with
+  // -1/-2 suffixes) and a permalink whose href is "#<tutorial>/<heading>".
+  function addAnchors(container, tutSlug) {
+    const used = new Map();
+    const nodes = container.querySelectorAll(
+      ".tutorial-title, .md h1, .md h2, .md h3, .md h4, .md h5, .md h6"
+    );
+    nodes.forEach(node => {
+      const text = node.textContent.trim();
+      const isTitle = node.classList.contains("tutorial-title");
+      let href = "#" + tutSlug;
+      if (!isTitle) {
+        const base = slug(text) || "section";
+        const n = (used.get(base) || 0) + 1;
+        used.set(base, n);
+        node.id = n > 1 ? base + "-" + n : base;
+        href += "/" + node.id;
+      }
+      node.classList.add("heading-anchored");
+      const a = document.createElement("a");
+      a.className = "anchor";
+      a.href = href;
+      a.title = "Copy link to this section";
+      a.setAttribute("aria-label", "Permalink: " + text);
+      a.innerHTML = LINK_ICON;
+      node.insertBefore(a, node.firstChild);
+    });
+  }
+
+  let toastTimer = null;
+  function toast(msg) {
+    const el = document.getElementById("toast");
+    el.textContent = msg;
+    el.classList.add("show");
+    clearTimeout(toastTimer);
+    toastTimer = setTimeout(() => el.classList.remove("show"), 1600);
+  }
+
+  // navigator.clipboard needs a secure context; reports are often opened over
+  // file://, so fall back to the old execCommand path there.
+  function copyText(text) {
+    if (navigator.clipboard && window.isSecureContext) {
+      navigator.clipboard.writeText(text).then(
+        () => toast("Link copied"),
+        () => toast(text)
+      );
+      return;
+    }
+    const ta = document.createElement("textarea");
+    ta.value = text;
+    ta.style.position = "fixed";
+    ta.style.opacity = "0";
+    document.body.appendChild(ta);
+    ta.select();
+    let ok = false;
+    try { ok = document.execCommand("copy"); } catch (e) { ok = false; }
+    document.body.removeChild(ta);
+    toast(ok ? "Link copied" : text);
+  }
+
+  function scrollToId(id) {
+    if (!id) { window.scrollTo(0, 0); return; }
+    const el = document.getElementById(id);
+    if (!el) return;
+    el.scrollIntoView({ block: "start" });
+    el.classList.remove("flash");
+    void el.offsetWidth;  // restart the animation on a repeat click
+    el.classList.add("flash");
+  }
+
+  document.addEventListener("click", ev => {
+    const a = ev.target.closest && ev.target.closest("a.anchor");
+    if (!a) return;
+    ev.preventDefault();
+    const href = a.getAttribute("href");
+    copyText(location.href.split("#")[0] + href);
+    if (location.hash === href) scrollToId(a.parentNode.id);
+    else location.hash = href;  // hashchange scrolls
+  });
+
+  // "#<tutorial>" (name, slug, or index) optionally followed by "/<heading>".
+  function parseHash() {
+    const raw = decodeURIComponent(location.hash.replace(/^#/, ""));
+    if (!raw) return { idx: 0, frag: "" };
+    const cut = raw.indexOf("/");
+    const tut = cut >= 0 ? raw.slice(0, cut) : raw;
+    const frag = cut >= 0 ? raw.slice(cut + 1) : "";
+    if (/^\d+$/.test(tut) && +tut < DATA.tutorials.length) return { idx: +tut, frag };
+    const i = DATA.tutorials.findIndex(
+      t => slug(t.meta.name) === tut || t.meta.name === tut
+    );
+    if (i >= 0) return { idx: i, frag };
+    // No tutorial matched: treat a bare hash as a heading in the current one.
+    return { idx: currentIdx >= 0 ? currentIdx : 0, frag: cut >= 0 ? frag : raw };
+  }
+
+  let currentIdx = -1;
+  function show(idx, frag) {
+    if (idx !== currentIdx) {
+      picker.value = idx;
+      render(idx);
+      currentIdx = idx;
+    }
+    if (frag) requestAnimationFrame(() => scrollToId(frag));
+  }
+  picker.addEventListener("change", () => {
+    location.hash = slug(DATA.tutorials[+picker.value].meta.name);
+    show(+picker.value);
+  });
+  window.addEventListener("hashchange", () => {
+    const h = parseHash();
+    show(h.idx, h.frag);
+  });
+  const initial = parseHash();
+  show(initial.idx, initial.frag);
+  // Inlined screenshots have no intrinsic size until decoded, so the first
+  // scroll can land short; re-anchor once everything has loaded.
+  if (initial.frag) {
+    window.addEventListener("load", () => scrollToId(initial.frag), { once: true });
+  }
+</script>
+</body>
+</html>
