@bendyline/gezel-cli 1.2.14 → 1.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -297,15 +297,15 @@ ${mark(app, 160, `${prefix}${id}/logo.webp`)}
297
297
  function indexHtml(apps, ctx) {
298
298
  const present = CATEGORIES.filter(([id]) => apps.some((a) => a.category === id));
299
299
  const demos = apps.filter((a) => a.demo).length;
300
- const description = `${apps.length} Gezel apps: an interface paired with AI crew members, the plans they follow, and the actions they take. Try ${demos} of them in your browser.`;
301
- return `${head("Gezel apps \u2014 a page you use, and a crew that works it", description, "/apps/", ctx)}
300
+ const description = `${apps.length} Gezel apps: an interface paired with AI that knows the job, the plans it follows, and the actions it takes. Try ${demos} of them in your browser.`;
301
+ return `${head("Gezel apps \u2014 a page you use, and Gezel working behind it", description, "/apps/", ctx)}
302
302
  <body>
303
303
  <div class="wrap">
304
304
  ${masthead()}
305
305
  <main>
306
306
  <section class="hero">
307
- <h1><span class="title">Gezel apps</span><span class="tagline">A page you use, and a crew that works it.</span></h1>
308
- <p class="lede">Each app pairs an interface with AI crew members who know the job, the step-by-step plans they follow, and actions that change the app\u2019s own files. Try ${demos} of them right here on sample data, with a scripted conversation. In Gezel they run on your computer, on your files, with the model you choose.</p>
307
+ <h1><span class="title">Gezel apps</span><span class="tagline">A page you use, and Gezel working behind it.</span></h1>
308
+ <p class="lede">Each app pairs an interface with AI that knows the job, the step-by-step plans it follows, and actions that change the app\u2019s own files. Try ${demos} of them right here on sample data, with a scripted conversation. In Gezel they run on your computer, on your files, with the model you choose.</p>
309
309
  </section>
310
310
  <div class="filter">
311
311
  <div class="tray" role="radiogroup" aria-label="Show apps for">
@@ -319,7 +319,7 @@ ${apps.map((a) => card(a)).join("\n")}
319
319
  </ul>
320
320
  <section class="band">
321
321
  <h2>Make your own</h2>
322
- <p>An app is plain files: an HTML page, the crew it hires, the craftbooks they follow, and small scripts for its actions. Build one for yourself, or contribute it to the catalog everyone installs from.</p>
322
+ <p>An app is plain files: an HTML page, its crew, the craftbooks they follow, and small scripts for its actions. Build one for yourself, or contribute it to the catalog everyone installs from.</p>
323
323
  <p class="band-links"><a href="${esc(ctx.docsBase)}building-ai-apps-inside-gezel/">Building AI apps inside Gezel</a><a href="${esc(ctx.docsBase)}gezel-page-apis/">The page APIs</a><a href="https://github.com/bendyline/gilde">The gilde catalog on GitHub</a></p>
324
324
  </section>
325
325
  </main>
@@ -390,7 +390,7 @@ function appHtml(app, apps, ctx) {
390
390
  (s) => s.night ? `Runs ${esc(s.name)} overnight, once you agree.` : `Runs ${esc(s.name)} on a schedule, once you agree.`
391
391
  ).join(" ")}</p>` : ""}</section>` : "";
392
392
  const shown = actions.slice(0, 8);
393
- const tools = actions.length ? `<section class="inside-card"><h3>Actions the crew can take</h3><ul class="plain">${shown.map(
393
+ const tools = actions.length ? `<section class="inside-card"><h3>Actions Gezel can take</h3><ul class="plain">${shown.map(
394
394
  (t) => `<li><strong>${esc(humanizeTool(t.name))}</strong><span>${esc(firstSentence(t.description ?? ""))}</span></li>`
395
395
  ).join(
396
396
  ""
@@ -427,7 +427,7 @@ ${demo}
427
427
  <li><a href="/#download">Download Gezel</a> for Mac, Windows or Linux. It\u2019s free.</li>
428
428
  <li>Choose <strong>New project</strong>, then <strong>${esc(label)}</strong>, then <strong>${esc(m.name)}</strong>.</li>
429
429
  ${questions.length ? `<li>Answer ${questions.length === 1 ? "its question" : "a few questions"}: ${questions.map((q) => `<em>${esc(q)}</em>`).join(" ")}</li>` : ""}
430
- <li>${lead ? `Your ${esc(lead.role.toLowerCase())} takes it from there, on the model you choose.` : "Your crew takes it from there, on the model you choose."}</li>
430
+ <li>${lead ? `Your ${esc(lead.role.toLowerCase())} takes it from there, on the model you choose.` : "Gezel takes it from there, on the model you choose."}</li>
431
431
  </ol>
432
432
  </section>
433
433
  ${more.length ? `<section class="more" aria-labelledby="more"><h2 id="more">More apps to try</h2><ul class="app-grid app-grid-small">${more.map((a) => card(a, "../")).join("")}</ul></section>` : ""}
@@ -1585,6 +1585,7 @@ import {
1585
1585
  CRAFTBOOK_CATEGORY_META,
1586
1586
  SCORECARD,
1587
1587
  catalogGroundFor as catalogGroundFor2,
1588
+ docbenchRowsFor,
1588
1589
  measuredClaim,
1589
1590
  measuredResultFor,
1590
1591
  measuredRowsFor,
@@ -1693,7 +1694,7 @@ async function buildSiteCatalog(catalog, scorecard = SCORECARD) {
1693
1694
  title: "Add-on toolsets and connectors",
1694
1695
  area: "technical",
1695
1696
  order: 4.5,
1696
- summary: "Toolsets you can add to a gezel, and connectors that bring outside data into a project.",
1697
+ summary: "Toolsets you can add to a crew member, and connectors that bring outside data into a project.",
1697
1698
  generated: true,
1698
1699
  subcategory: HOW_GEZEL_WORKS
1699
1700
  },
@@ -1727,15 +1728,15 @@ async function buildSiteCatalog(catalog, scorecard = SCORECARD) {
1727
1728
  {
1728
1729
  entry: {
1729
1730
  id: "craftbooks-index",
1730
- title: "Every craftbook",
1731
+ title: "Every plan",
1731
1732
  area: "craftbooks",
1732
1733
  order: 0,
1733
1734
  generated: true
1734
1735
  },
1735
1736
  markdown: [
1736
- "# Every craftbook",
1737
+ "# Every plan",
1737
1738
  "",
1738
- `Craftbooks are step-by-step plans your crew follows to produce a real piece of work. Each one names its steps, who runs them, and the checks the result must pass. There are ${craftbooks.length} of them, grouped here by the kind of work they do.`
1739
+ `Plans are step-by-step procedures Gezel follows to produce a real piece of work. Each one names its steps, the role that runs each, and the checks the result must pass. There are ${craftbooks.length} of them, grouped here by the kind of work they do.`
1739
1740
  ].join("\n"),
1740
1741
  html: craftbookGalleryHtml(craftbooks, craftbookArt),
1741
1742
  listed: false,
@@ -1766,14 +1767,15 @@ function modelCatalogMarkdown(chat, images, videos, scorecard) {
1766
1767
  "",
1767
1768
  `## Chat models (${chat.length})`,
1768
1769
  "",
1769
- "The models your gezels think and write with, recommended first. **Measured** is the share of tasks the model (or another build of it) passed in its most recent full [scorecard](model-scorecard) round, preferring the general set, with the machine that round ran on. Follow it to every round on the model\u2019s page. Rounds are not comparable with each other, and a number from a workstation is not a promise about a laptop.",
1770
+ "The models Gezel thinks and writes with, recommended first. **Measured** is the share of tasks the model (or another build of it) passed in its most recent full [scorecard](model-scorecard) round, preferring the general set, with the machine that round ran on. Follow it to every round on the model\u2019s page. Rounds are not comparable with each other, and a number from a workstation is not a promise about a laptop. **Docbench** is the build\u2019s score from 0 to 100 on DocBlocks\u2019 document work (review, writing, diagrams, slides, study aids) in its newest [docbench](docbench) round.",
1770
1771
  "",
1771
- "| Model | Measured | Size | Context | Tools | Best for | Runs on | License |",
1772
- "| --- | --- | --- | --- | --- | --- | --- | --- |",
1772
+ "| Model | Measured | Docbench | Size | Context | Tools | Best for | Runs on | License |",
1773
+ "| --- | --- | --- | --- | --- | --- | --- | --- | --- |",
1773
1774
  ...chat.map(
1774
1775
  (m) => row([
1775
1776
  `[${cell(m.name)}](model/${m.id})`,
1776
1777
  measuredCell(scorecard, m.id),
1778
+ docbenchCell(scorecard, m.id),
1777
1779
  formatGB(m.approxSizeBytes),
1778
1780
  formatContext(m.contextWindow),
1779
1781
  m.supportsTools === false ? "No" : "Yes",
@@ -1788,7 +1790,7 @@ function modelCatalogMarkdown(chat, images, videos, scorecard) {
1788
1790
  "",
1789
1791
  `## Image models (${images.length})`,
1790
1792
  "",
1791
- "Models your crew can use to draw pictures, icons and illustrations. Gezel works out what each one needs from its files and offers only the ones your machine can run.",
1793
+ "Models Gezel can use to draw pictures, icons and illustrations. Gezel works out what each one needs from its files and offers only the ones your machine can run.",
1792
1794
  "",
1793
1795
  "| Model | Size | Commercial use | License |",
1794
1796
  "| --- | --- | --- | --- |",
@@ -1829,6 +1831,64 @@ function measuredCell(scorecard, modelId) {
1829
1831
  if (!measured) return "Not yet";
1830
1832
  return `[${cell(measuredClaim(measured))}](model/${modelId}#measured-results)`;
1831
1833
  }
1834
+ function docbenchCell(scorecard, modelId) {
1835
+ const latest = docbenchRowsFor(scorecard, modelId)[0];
1836
+ if (!latest) return "Not yet";
1837
+ return `[${Math.round(latest.docbench.score)}](model/${modelId}#docbench)`;
1838
+ }
1839
+ var DOCBENCH_FAMILY_LABELS = [
1840
+ ["review", "Review and feedback"],
1841
+ ["writing", "Writing new content"],
1842
+ ["visuals", "Diagrams and illustrations"],
1843
+ ["presentations", "Presentations"],
1844
+ ["study", "Study aids"],
1845
+ ["narration", "Narration cleanup"]
1846
+ ];
1847
+ function docbenchResultsMarkdown(scorecard, modelId) {
1848
+ const rows = docbenchRowsFor(scorecard, modelId);
1849
+ const latest = rows[0];
1850
+ if (!latest) return [];
1851
+ const { docbench, result, run } = latest;
1852
+ const whole = (value) => String(Math.round(value));
1853
+ const range = (ci) => `${whole(ci[0])}\u2013${whole(ci[1])}`;
1854
+ const engine = SCORECARD_ENGINE_LABELS[result.engine] ?? result.engine;
1855
+ const lines = [
1856
+ "## Docbench",
1857
+ "",
1858
+ `How well this build does DocBlocks\u2019 document work, judged from 0 to 100 in the [docbench](docbench) ${run.scope === "subset" ? "focused re-run" : "round"} of ${run.provenance.startedAt.slice(0, 10)} on ${engine}: **${whole(docbench.score)}** (95% range ${range(docbench.ci)}, band ${docbench.band}). DocBlocks could use ${Math.round(docbench.usableRate * 100)}% of its answers.`,
1859
+ "",
1860
+ "| Group | Score | 95% range |",
1861
+ "| --- | --- | --- |"
1862
+ ];
1863
+ const known = new Set(DOCBENCH_FAMILY_LABELS.map(([id]) => id));
1864
+ const families = [
1865
+ ...DOCBENCH_FAMILY_LABELS,
1866
+ ...Object.keys(docbench.families).filter((id) => !known.has(id)).map((id) => [id, id])
1867
+ ];
1868
+ for (const [id, label] of families) {
1869
+ const family = docbench.families[id];
1870
+ if (family) lines.push(row([label, whole(family.score), range(family.ci)]));
1871
+ }
1872
+ const findings = docbench.tasks["review-general"]?.findings;
1873
+ if (findings) {
1874
+ const one = (value) => value.toFixed(1);
1875
+ lines.push(
1876
+ "",
1877
+ `In general review it found, per document, ${one(findings.low)} small fixes, ${one(findings.medium)} moderate changes and ${one(findings.high)} substantial ones, and added ${one(findings.trivial)} trivial and ${one(findings.wrong)} wrong suggestions.`
1878
+ );
1879
+ }
1880
+ if (rows.length > 1) {
1881
+ lines.push(
1882
+ "",
1883
+ "Earlier results for this build, measured before the one above under their own round\u2019s tests, reviewer and Gezel version:",
1884
+ "",
1885
+ ...rows.slice(1).map(
1886
+ (earlier) => `- ${earlier.run.provenance.startedAt.slice(0, 10)}, pack ${earlier.docbench.packVersion}: ${whole(earlier.docbench.score)}`
1887
+ )
1888
+ );
1889
+ }
1890
+ return lines;
1891
+ }
1832
1892
  var SCORECARD_ENGINE_LABELS = {
1833
1893
  "llama-cpp": "llama.cpp",
1834
1894
  mlx: "MLX",
@@ -1913,10 +1973,12 @@ function chatModelMarkdown(m, scorecard) {
1913
1973
  "| --- | --- |",
1914
1974
  ...facts.filter(([, v]) => v).map(([k, v]) => row([k, cell(v)])),
1915
1975
  "",
1916
- "Gezel downloads this model the first time a gezel needs it, checks the file against its published hash, and applies tuned settings for it.",
1976
+ "Gezel downloads this model the first time it is needed, checks the file against its published hash, and applies tuned settings for it.",
1917
1977
  "",
1918
1978
  ...measuredResultsMarkdown(scorecard, m.id)
1919
1979
  ];
1980
+ const docbench = docbenchResultsMarkdown(scorecard, m.id);
1981
+ if (docbench.length > 0) lines.push("", ...docbench);
1920
1982
  const more = [
1921
1983
  m.upstream ? `[The model\u2019s own page](${m.upstream})` : "",
1922
1984
  "[Every model](model-catalog)",
@@ -1929,14 +1991,14 @@ function toolsetCatalogMarkdown(addOns, connectors, communityCount) {
1929
1991
  const lines = [
1930
1992
  "# Add-on toolsets and connectors",
1931
1993
  "",
1932
- "Every gezel starts with the built-in tool groups that fit its role, described in [Tools and toolsets](tools-and-toolsets). This page lists what you can add on top."
1994
+ "Every crew member starts with the built-in tool groups that fit their role, described in [Tools and toolsets](tools-and-toolsets). This page lists what you can add on top."
1933
1995
  ];
1934
1996
  if (addOns.length > 0) {
1935
1997
  lines.push(
1936
1998
  "",
1937
1999
  "## Add-on toolsets",
1938
2000
  "",
1939
- "Extra tools from Gezel\u2019s own catalog. Add one to a gezel from its Toolsets tab.",
2001
+ "Extra tools from Gezel\u2019s own catalog. Add one to a crew member from their Toolsets tab.",
1940
2002
  "",
1941
2003
  "| Toolset | What it does |",
1942
2004
  "| --- | --- |",
@@ -1948,7 +2010,7 @@ function toolsetCatalogMarkdown(addOns, connectors, communityCount) {
1948
2010
  "",
1949
2011
  "## Connectors",
1950
2012
  "",
1951
- "Connectors copy data from outside services, such as mail, calendars and issue trackers, into a project as searchable files. Your crew works on that local copy, never on the live account.",
2013
+ "Connectors copy data from outside services, such as mail, calendars and issue trackers, into a project as searchable files. Gezel works on that local copy, never on the live account.",
1952
2014
  "",
1953
2015
  "| Connector | What it brings in |",
1954
2016
  "| --- | --- |",
@@ -1960,7 +2022,7 @@ function toolsetCatalogMarkdown(addOns, connectors, communityCount) {
1960
2022
  "",
1961
2023
  "## Community servers",
1962
2024
  "",
1963
- `Gezel\u2019s toolset browser also lists about ${roundDown(communityCount).toLocaleString("en-US")} MCP servers from the public community registry, marked **Community**. They are third-party projects, so review one before you add it to a crew. You can also bring your own: see [Custom MCP toolsets](tools-and-toolsets#custom-mcp-toolsets).`
2025
+ `Gezel\u2019s toolset browser also lists about ${roundDown(communityCount).toLocaleString("en-US")} MCP servers from the public community registry, marked **Community**. They are third-party projects, so review one before you add it. You can also bring your own: see [Custom MCP toolsets](tools-and-toolsets#custom-mcp-toolsets).`
1964
2026
  );
1965
2027
  }
1966
2028
  return lines.join("\n");
@@ -1969,7 +2031,7 @@ function roleCatalogMarkdown(roles) {
1969
2031
  return [
1970
2032
  "# Every role template",
1971
2033
  "",
1972
- "A role template is a ready-made character for your crew: a name, a job, and a working style that shapes how they think and talk. The Meester picks from these when it builds a crew, and you can add any of them yourself with **New Gezel**. The core roles each have their own page in [Roles](roles-index).",
2034
+ "A role template is a ready-made character for your crew: a name, a job, and a working style that shapes how they think and talk. The Meester picks from these when a job calls for one, and you can add any of them yourself with **New crew member**. The core roles each have their own page in [Roles](roles-index).",
1973
2035
  "",
1974
2036
  "| Role | What they do |",
1975
2037
  "| --- | --- |",
@@ -1981,14 +2043,14 @@ function roleCatalogMarkdown(roles) {
1981
2043
  function roleTemplateMarkdown(r, about) {
1982
2044
  const lines = [`# ${r.name}`, "", r.description.trim()];
1983
2045
  if (r.meesterCandidate) {
1984
- lines.push("", "This character can also act as your Meester, the gezel who runs the crew.");
2046
+ lines.push("", "This character can also act as your Meester, the one you talk to first.");
1985
2047
  }
1986
2048
  if (about?.trim()) {
1987
2049
  lines.push(
1988
2050
  "",
1989
2051
  "## How they work",
1990
2052
  "",
1991
- "This is the character brief Gezel gives the model, word for word. It shapes how this gezel thinks, works and talks.",
2053
+ "This is the character brief Gezel gives the model, word for word. It shapes how this character thinks, works and talks.",
1992
2054
  "",
1993
2055
  demoteHeadings(about.trim())
1994
2056
  );
@@ -2897,9 +2959,9 @@ function openInGezelSection(entryId, siteUrl) {
2897
2959
  })}</p>`;
2898
2960
  }
2899
2961
  var AREA_BLURBS = {
2900
- conceptual: "What gezel is, who your crew are, and how the pieces fit together.",
2901
- "gezel-roles": "The roles a gezel can take, and what each one is good at.",
2902
- craftbooks: "Step-by-step recipes your crew can run \u2014 one per job.",
2962
+ conceptual: "What gezel is, who does the work, and how the pieces fit together.",
2963
+ "gezel-roles": "The roles on a crew, and what each one is good at.",
2964
+ craftbooks: "Step-by-step plans Gezel can follow \u2014 one per job.",
2903
2965
  "project-types": "Ready-made project setups, each with a crew and a bench.",
2904
2966
  technical: "Architecture, file layout, providers, security, and the CLI.",
2905
2967
  "whats-new": "What changed in each release, in plain language."
@@ -3056,14 +3118,14 @@ ${sitePage.html}`;
3056
3118
  }
3057
3119
  const landingSocial = canonicalBase ? {
3058
3120
  url: canonicalBase,
3059
- title: "The Gezel Handboek",
3121
+ title: "Gezel Help",
3060
3122
  image: ogBase ? `${ogBase}${ogCardPath(LANDING_CARD_ID)}` : void 0
3061
3123
  } : void 0;
3062
3124
  if (ogBase) {
3063
3125
  cardPlans.push({
3064
3126
  id: LANDING_CARD_ID,
3065
- kicker: `${WORDMARK} \xB7 Handboek`,
3066
- headline: "The Gezel Handboek"
3127
+ kicker: `${WORDMARK} \xB7 Help`,
3128
+ headline: "Gezel Help"
3067
3129
  });
3068
3130
  }
3069
3131
  await writeFile4(join5(out, "index.html"), landingPage(areas, css, siteUrl, landingSocial), "utf8");
@@ -3113,7 +3175,7 @@ ${body}`;
3113
3175
  }
3114
3176
  function llmsTxt(areas, base) {
3115
3177
  const lines = [
3116
- "# Gezel Handboek",
3178
+ "# Gezel Help",
3117
3179
  "",
3118
3180
  "> Gezel is a free, open-source app and platform for running a crew of AI agents on your own computer, with local models or a cloud plan you already have. Every article below is plain markdown.",
3119
3181
  "",
@@ -3225,7 +3287,7 @@ function masthead2(areas, depth, siteUrl, currentArea) {
3225
3287
  const wordmark = siteUrl ? `<a class="hb-wordmark" href="${esc2(siteUrl)}">${WORDMARK}</a>
3226
3288
  ` : "";
3227
3289
  return `<header class="hb-masthead">
3228
- ${wordmark}<a class="hb-brand" href="${up2(depth)}">Gezel Handboek</a>
3290
+ ${wordmark}<a class="hb-brand" href="${up2(depth)}">Gezel Help</a>
3229
3291
  <nav class="hb-areanav">
3230
3292
  ${links}
3231
3293
  </nav>
@@ -3253,7 +3315,7 @@ ${more}
3253
3315
  </section>`;
3254
3316
  });
3255
3317
  return `<aside class="hb-sidebar">
3256
- <nav aria-label="Handboek sections">
3318
+ <nav aria-label="Help sections">
3257
3319
  ${sections.join("\n")}
3258
3320
  </nav>
3259
3321
  </aside>`;
@@ -3313,14 +3375,14 @@ function articlePage(args) {
3313
3375
  const area = areas.find((a) => a.area === entry.area);
3314
3376
  const aside = onThisPage(headings);
3315
3377
  const scriptTags = scripts.map((name) => `<script defer src="${up2(depth)}assets/${esc2(name)}"></script>`).join("\n");
3316
- return `${head2(`${entry.title} \u2014 Gezel Handboek`, css, depth, entry.summary, social)}
3378
+ return `${head2(`${entry.title} \u2014 Gezel Help`, css, depth, entry.summary, social)}
3317
3379
  <body class="hb hb-article-page">
3318
3380
  ${masthead2(areas, depth, siteUrl, entry.area)}
3319
3381
  <div class="hb-layout">
3320
3382
  ${sidebar(areas, entry, depth)}
3321
3383
  <main class="hb-main">
3322
3384
  <nav class="hb-breadcrumb" aria-label="Breadcrumb">
3323
- <a href="${up2(depth)}">Handboek</a>${area ? ` <span>/</span> <a href="${up2(depth)}${esc2(areaLanding(area))}/">${esc2(area.title)}</a>` : ""}
3385
+ <a href="${up2(depth)}">Help</a>${area ? ` <span>/</span> <a href="${up2(depth)}${esc2(areaLanding(area))}/">${esc2(area.title)}</a>` : ""}
3324
3386
  </nav>
3325
3387
  <article class="hb-article">
3326
3388
  ${body}
@@ -3336,7 +3398,7 @@ ${scriptTags}
3336
3398
  }
3337
3399
  function footer2(depth) {
3338
3400
  return `<footer class="hb-footer">
3339
- <p><a href="${up2(depth)}">Gezel Handboek</a> \u2014 documentation for gezel, a crew of AI companions that works for you, from your own computer.</p>
3401
+ <p><a href="${up2(depth)}">Gezel Help</a> \u2014 documentation for gezel, a crew of AI companions that works for you, from your own computer.</p>
3340
3402
  </footer>`;
3341
3403
  }
3342
3404
  function landingPage(areas, css, siteUrl, social) {
@@ -3366,12 +3428,12 @@ ${list}
3366
3428
  <p class="hb-more"><a href="${esc2(landing)}/">Browse all ${articleCount(area)} ${esc2(area.title.toLowerCase())}</a></p>
3367
3429
  </section>`;
3368
3430
  }).join("\n");
3369
- return `${head2("Gezel Handboek", css, 0, "Documentation for gezel \u2014 a crew of AI companions that works for you, from your own computer.", social)}
3431
+ return `${head2("Gezel Help", css, 0, "Documentation for gezel \u2014 a crew of AI companions that works for you, from your own computer.", social)}
3370
3432
  <body class="hb hb-home">
3371
3433
  ${masthead2(areas, 0, siteUrl)}
3372
3434
  <main class="hb-main hb-home-main">
3373
3435
  <section class="hb-hero">
3374
- <h1>The Gezel Handboek</h1>
3436
+ <h1>Gezel Help</h1>
3375
3437
  <p class="hb-lede">Gezel lets you assemble a crew of AI companions and put them to work \u2014 on your own computer, with your own files. This is their handboek: what they are, what they can do, and how to work with them.</p>
3376
3438
  </section>
3377
3439
  ${startBlock}
@@ -467,9 +467,25 @@ async function manifestFor(abs) {
467
467
  const info = await stat(abs).catch(() => null);
468
468
  if (!info) throw new CliError(`no such file or directory: ${abs}`);
469
469
  if (info.isDirectory()) {
470
- return JSON.parse(await readFile2(join2(abs, "manifest.json"), "utf8"));
470
+ let raw;
471
+ try {
472
+ raw = await readFile2(join2(abs, "manifest.json"), "utf8");
473
+ } catch {
474
+ throw new CliError(`${abs} has no manifest.json \u2014 not an extracted catalog`);
475
+ }
476
+ try {
477
+ return JSON.parse(raw);
478
+ } catch {
479
+ throw new CliError(`${join2(abs, "manifest.json")} is not valid JSON`);
480
+ }
481
+ }
482
+ try {
483
+ return await readGezkManifest(abs);
484
+ } catch (err) {
485
+ throw new CliError(
486
+ `${abs} is not a readable .gezk archive: ${err instanceof Error ? err.message : String(err)}`
487
+ );
471
488
  }
472
- return readGezkManifest(abs);
473
489
  }
474
490
  function excerpt(text) {
475
491
  const flat = text.replace(/\s+/g, " ").trim();
@@ -483,7 +499,14 @@ function formatBytes(bytes) {
483
499
  function contentSha256(bytes) {
484
500
  return createHash2("sha256").update(bytes).digest("hex");
485
501
  }
486
- async function runKnowledgeExportParquet(path, opts) {
502
+ function duckdbMissingMessage(version) {
503
+ return [
504
+ "No DuckDB CLI found. To get one:",
505
+ ` gezel native install --engine duckdb (downloads DuckDB ${version}; or run this command again with --download)`,
506
+ " or install DuckDB yourself (https://duckdb.org), on your PATH or named with --duckdb <binary>"
507
+ ].join("\n");
508
+ }
509
+ async function runKnowledgeExportParquet(path, opts, deps = {}) {
487
510
  const { DUCKDB_VERSION, duckdbInstalledBinary } = await import("@bendyline/gezel/native");
488
511
  const { exportCatalogParquet, findDuckdbBinary } = await import("@bendyline/gezel-knowledge");
489
512
  const resolved = resolve2(path);
@@ -492,12 +515,8 @@ async function runKnowledgeExportParquet(path, opts) {
492
515
  const source = info.isDirectory() ? { rootDir: resolved } : { archivePath: resolved };
493
516
  const outDir = opts.out ? resolve2(opts.out) : join2(dirname2(resolved), `${basename2(resolved).replace(/\.gezk$/i, "")}-parquet`);
494
517
  const installed = duckdbInstalledBinary(process.env.GEZEL_HOME ?? join2(homedir2(), ".gezel"));
495
- const binaryPath = opts.duckdb ?? process.env.GEZEL_DUCKDB_BIN?.trim() ?? (await stat(installed).catch(() => null) ? installed : await findDuckdbBinary());
496
- if (!binaryPath) {
497
- throw new CliError(
498
- `no DuckDB CLI found \u2014 open a data feature in gezel once (it installs DuckDB ${DUCKDB_VERSION}), install DuckDB yourself, or pass --duckdb <binary>`
499
- );
500
- }
518
+ const binaryPath = opts.duckdb || process.env.GEZEL_DUCKDB_BIN?.trim() || (await stat(installed).catch(() => null) ? installed : await findDuckdbBinary()) || await deps.fetchDuckdb?.();
519
+ if (!binaryPath) throw new CliError(duckdbMissingMessage(DUCKDB_VERSION));
501
520
  const report = await exportCatalogParquet({
502
521
  source,
503
522
  outDir,
@@ -553,6 +572,7 @@ async function runKnowledgeNearby(path, radius, opts = {}) {
553
572
  }
554
573
  export {
555
574
  contentSha256,
575
+ duckdbMissingMessage,
556
576
  embeddingRuntimeMissingMessage,
557
577
  runKnowledgeBuild,
558
578
  runKnowledgeExportParquet,