@bendyline/gezel-service 0.1.0 → 1.0.1

package/dist/handboek-content/README.md

@@ -16,9 +16,12 @@ gezel-roles/     Role articles (curated leads; generated bodies fill gaps)
 craftbooks/      Usually generated; curated overrides welcome
 project-types/   Usually generated; curated overrides welcome
 technical/       Architecture, files on disk, security, CLI
+whats-new/       Release notes — one article per release, newest first
 assets/          Images referenced by articles (incl. assets/poppetje/*.svg)
 ```
 
+`whats-new/` is written by the `release-note` skill (`.claude/skills/release-note/`), which reads the commit range since the previous tag and drafts the article. Read that skill before hand-writing one — the voice is deliberately different from the rest of the Handboek, and the ordering convention below is easy to get wrong.
+
 ## Article format
 
 Squisq-flavored markdown with YAML frontmatter:
@@ -43,8 +46,26 @@ Body prose…
   (curated ids always win).
 
 - `title` — TOC + tab title. Falls back to the first `#` heading.
-- `order` — sort key within the area (generated articles sit at 10).
-- `summary` — one line for the TOC.
+- `order` — sort key within the area, ascending (generated articles sit at 10).
+
+  `whats-new/` inverts this to get newest-first: a release article's order is
+
+  the negated calendar line, so `1.26224` carries `order: -26224`, and the
+
+  section index sits at `-999999`. Nothing else needs touching when a release
+
+  lands — the next article simply sorts above the last one, and the index
+
+  picks it up through `::handboek-whats-new-list`.
+
+- `summary` — one line for the TOC. In `whats-new/` it is also the whole of
+
+  the release in the section's own list, so it is required there and capped
+
+  at 200 characters (enforced by the content lint in
+
+  `packages/service/src/handboek/engine.test.ts`).
+
 - `defaultDuration` — optional seconds-per-block override for the video
 
   playback mode's timing.
@@ -69,6 +90,7 @@ A macro is a leaf directive on its own line. The engine expands it into plain ma
 | `::handboek-craftbook-list{role=…}` | Table of craftbooks (optionally the role's defaults). |
 | `::handboek-installed-models` | Models installed on this device with engine and tier. |
 | `::handboek-project-type-composition{id=…}` | What a project type sets up: crew, craftbooks, toolsets, schedules. |
+| `::handboek-whats-new-list{limit=12}` | Every release in `whats-new/`, newest first, each with its one-line summary. Identical in all three modes. |
 
 ## Conventions
 

package/dist/handboek-content/conceptual/connected-apps.md

@@ -55,3 +55,5 @@ One honest caveat, spelled out next to the switch: Ollama's convention is no pas
 ## Keeping an eye on things
 
 Every chat an app completes through these endpoints is recorded in the **History** tab (look for "App chat" entries), and the tokens they consume count in the **Usage** view — so you can always see who has been using your models, and how much.
+
+If you are developing one of these applications, continue with the technical guide [Building connected apps with gezel-app-sdk](../technical/building-connected-apps-with-gezel-app-sdk.md).

package/dist/handboek-content/technical/building-connected-apps-with-gezel-app-sdk.md

@@ -0,0 +1,144 @@
+---
+id: building-connected-apps-with-gezel-app-sdk
+title: Building connected apps with gezel-app-sdk
+order: 9
+summary: Discover Gezel, ask for user consent, and use local models or product APIs from another app.
+---
+
+# Building connected apps with gezel-app-sdk
+
+`@bendyline/gezel-app-sdk` is for software that runs *beside* Gezel. It lets a desktop or Node application discover the logged-in user's daemon, trust its loopback TLS certificate, ask the user for a scoped connection, remember the issued token securely, and use OpenAI-shaped model APIs.
+
+This differs from `@bendyline/gezel-sdk`, whose scripts run *inside* Gezel's sandbox. A connected app owns its own interface and process. Gezel owns model discovery and downloads, consent, revocation, and the local inference service.
+
+The [Connected apps](../conceptual/connected-apps.md) article explains what the user sees. This article covers the developer side.
+
+## Install and connect
+
+The Node entry requires Node.js 24 or newer:
+
+```bash
+npm install @bendyline/gezel-app-sdk
+```
+
+The normal third-party flow is: detect Gezel, request the narrowest scope, let the user approve in the desktop app, and store the resulting token in the operating system's credential store.
+
+```ts
+import { connect, detectGezel } from '@bendyline/gezel-app-sdk';
+
+// Demo only: this lasts for one process. Replace it with Keychain,
+// Credential Manager, libsecret, or your existing secure credential vault.
+const demoTokens = new Map<string, string>();
+const tokenStorage = {
+  load: (appId: string) => demoTokens.get(appId) ?? null,
+  save: (appId: string, token: string) => demoTokens.set(appId, token),
+  delete: (appId: string) => demoTokens.delete(appId),
+};
+
+const status = await detectGezel();
+if (!status.running) {
+  throw new Error('Start Gezel, then connect this app again.');
+}
+
+const app = await connect({
+  appId: 'acme.notes',
+  appName: 'Acme Notes',
+  scopes: ['openai'],
+  tokenStorage,
+});
+
+const available = await app.models();
+const model = available.data[0];
+if (!model) throw new Error('No Gezel models are available.');
+
+const stream = await app.chat({
+  model: model.id,
+  messages: [{ role: 'user', content: 'Give this note a short title.' }],
+  stream: true,
+});
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
+}
+```
+
+The in-memory map keeps the quickstart self-contained, but a real application must replace it with secure operating-system storage; do not save the token in source code, a project file, or plain-text preferences. `connect()` verifies a stored token still has the requested scopes. If it was revoked or is too narrow, the SDK discards it and starts a fresh visible consent flow.
+
+Call `app.models()` rather than hardcoding a model id. The response is the authoritative list available to this connection and can include both raw models and eligible gezels. Selecting a gezel gives the caller that gezel's character and tuned model, while your app keeps ownership of its interface and conversation loop.
+
+## Consent and scopes
+
+Every connection has a stable `appId`, a user-visible name, and one or more scopes. The user can review and revoke it under **Settings → Connected Apps**.
+
+| Scope | Use it for | Approval |
+| --- | --- | --- |
+| `openai` | Model listing, chat, embeddings, and ensuring a local model is present | Click approval by default |
+| `product` | The ordinary Gezel product API through `@bendyline/gezel-client` | Approval plus a requester-visible verification code |
+| `remote-inference` | Gezel's paired-device inference surface | Click approval by default |
+
+Third-party applications should not request the first-party `cli` scope or call `authorizeLocalOwner()`. Those surfaces are reserved for Gezel's own command line and same-user clients. Ask for `product` only when the application truly needs projects, tasks, gezels, or other product state; add `openai` only if that same application also performs inference.
+
+Stateful scopes require `onVerificationCode`. Show the code in the requesting application so the user can type it into Gezel's approval dialog:
+
+```ts
+import { authorizeLocal } from '@bendyline/gezel-app-sdk';
+
+const authorized = await authorizeLocal({
+  appId: 'acme.editor',
+  appName: 'Acme Editor',
+  scopes: ['product'],
+  tokenStorage,
+  onVerificationCode(code) {
+    showConnectionCode(code);
+  },
+});
+```
+
+The daemon generates the code and never sends it to the Gezel desktop approval surface. This proves that the person approving the grant can also see the application that requested it.
+
+## Use the full product API
+
+The app SDK's `GezelApp` class deliberately stays focused on the OpenAI-compatible surface. When a connected app also needs projects, tasks, chats, scripts, or other Gezel state, use `authorizeLocal()` to obtain the approved transport and pass it to the typed client:
+
+```ts
+import { authorizeLocal } from '@bendyline/gezel-app-sdk';
+import { GezelClient } from '@bendyline/gezel-client/node';
+
+const authorized = await authorizeLocal({
+  appId: 'acme.editor',
+  appName: 'Acme Editor',
+  scopes: ['product'],
+  tokenStorage,
+  onVerificationCode: showConnectionCode,
+});
+
+const client = new GezelClient(authorized);
+const projects = await client.listProjects();
+```
+
+This pairing is the supported route for a rich integration: the app SDK owns discovery, pinned TLS, consent, and scoped credentials; `@bendyline/gezel-client` owns the typed product API. Avoid hand-written `/api` requests when the client already covers the endpoint.
+
+## Model and inference methods
+
+| Method | Purpose |
+| --- | --- |
+| `app.models()` | List the models and gezels exposed to this app |
+| `app.chat()` | OpenAI-compatible chat completion, streaming or complete |
+| `app.embeddings()` | OpenAI-compatible embeddings when the selected provider supports them |
+| `app.ensureModel()` | Make sure a catalog model is installed and warm |
+| `app.streamEnsureEvents()` | Follow model download progress and completion over SSE |
+| `app.revokeMyToken()` | Let the app revoke its own connection |
+
+`detectGezel()` is a useful preflight, but it does not authorize anything. `connect()` returns a ready `GezelApp`; `authorize()` returns the generic base URL, token, and trusted `fetch`; `connectLocal()` combines the full Node-native local flow with non-sensitive daemon diagnostics.
+
+Ordinary third-party apps should ask the user to start Gezel when discovery reports `daemon_not_running`. The optional start-if-missing path is only for native integrations that deliberately bundle the matching `gezeld` package.
+
+## TLS, browsers, and errors
+
+The local daemon uses a per-launch self-signed certificate. The Node SDK reads the public certificate from Gezel's runtime directory and constructs a pinned `fetch`, so you should not disable TLS verification globally or replace the transport with an unpinned client.
+
+A browser cannot read `~/.gezel/runtime/` and cannot perform this local trust setup itself. Use a desktop helper to complete discovery and consent, then pass the resolved address and scoped token to a renderer that imports `GezelApp` from `@bendyline/gezel-app-sdk/browser`. Pure websites should not attempt to bypass the browser's loopback TLS protections.
+
+Catch `GezelSdkError` and branch on its `code`. Common cases include `daemon_not_running`, `user_denied`, `approval_timeout`, `verification_code_handler_required`, `model_not_found`, `embeddings_not_supported`, `missing_scope:<scope>`, and `provider_error`. Treat denial as a normal user choice, and give timeouts and missing-daemon errors an obvious retry path.
+
+The daemon publishes the current public OpenAPI document at unauthenticated `GET /v1/openapi.json`. Use it for route inspection or code generation; use the SDK types for ordinary application code.

package/dist/handboek-content/technical/cli-reference.md

@@ -9,6 +9,15 @@ summary: Headless gezel — start the service, run one-shot work, export docs.
 
 The `gezel` command drives the same service the desktop app uses — handy on servers, in scripts, or when you just live in a terminal.
 
+Install the command-line package with Node.js 24 or newer:
+
+```bash
+npm install -g @bendyline/gezel-cli
+gezel
+```
+
+The CLI is one of Gezel's public JavaScript packages. See [Gezel on npm](npm-packages.md) for the complete package map and the SDKs to use when a shell command is not the right integration boundary.
+
 ## Everyday commands
 
 ```
@@ -37,3 +46,5 @@ gezel handboek export --out ./site
 renders the Handboek — the same articles you're reading now — as a static website, for publishing or offline reading.
 
 Run `gezel --help` (or `--help` on any subcommand) for the full surface.
+
+To automate work *inside* a project, continue with [Writing scripts with gezel-sdk](writing-scripts-with-gezel-sdk.md). To let another application use Gezel, see [Building connected apps with gezel-app-sdk](building-connected-apps-with-gezel-app-sdk.md).

package/dist/handboek-content/technical/how-we-test-models.md

@@ -1,7 +1,7 @@
 ---
 id: how-we-test-models
 title: "How we test models"
-order: 7
+order: 10
 summary: What the model scores mean, how they are measured, and what they don't tell you.
 ---
 # How we test models
@@ -36,13 +36,49 @@ fixing a bug from a description of the symptoms, following a checklist and
 stopping when something looks wrong, turning several documents into one
 reconciled summary.
 
+### Core (11 tests)
+
+| Test | What the task entails |
+|---|---|
+| Tic-tac-toe (`tictactoe`) | Create a new project and build a working two-player tic-tac-toe game in a single HTML file, including a clear win state. |
+| Pet shop (`petshop`) | Build a single-page pet-shop website, generate a custom logo with the image tool, and make sure the page uses that logo. |
+| Tank combat (`tankcombat`) | Build a playable top-down tank game in one HTML file, with keyboard controls, shooting, an enemy tank, and a visible score. |
+| Schema migration (`schema-migration`) | Refactor a small multi-file TypeScript app from one name field to first and last names, preserve every record, add tests and notes, and pass the type check. |
+| Tests as the specification (`failing-tests-spec`) | Work out an order-lifecycle state machine from its tests alone, implement it, and make every test pass without changing the tests. |
+| Debug from symptoms (`symptom-debug`) | Diagnose an undocumented pagination error from the failing output, then fix the implementation without changing the acceptance check. |
+| Data wrangling (`data-wrangle`) | Clean three messy CSV exports, standardise dates and email addresses, remove duplicates, sort the records, and produce the exact required JSON. |
+| Incident postmortem (`incident-postmortem`) | Read five evidence files and write a structured, blame-free postmortem with accurate facts and citations, without inventing unmeasured impact. |
+| Runbook anomaly (`ops-runbook-anomaly`) | Follow a maintenance checklist step by step, verify and record each action, and stop with a grounded report when a planted backup check fails. |
+| Plan and estimate (`plan-and-estimate`) | Produce an office-relocation plan with valid owners, correctly ordered dependencies, risks, and a checkable definition of done for every task. |
+| Conflict synthesis (`conflict-synthesis`) | Reconcile five documents that disagree about a launch date, budget, and owner; show each conflict and use the authoritative answer consistently. |
+
 **The productivity set** is office work — a customer notice written to a hard
 word limit, a meeting turned into an action register, a research brief with
 its sources cited, an A/B test read-out, a spreadsheet model, a slide deck,
 a Word document.
 
+### Productivity (13 tests)
+
+| Test | What the task entails |
+|---|---|
+| Constrained communications (`constrained-comms`) | Write a 140–220 word customer outage notice containing the required facts and disclosures while avoiding banned or unsupported claims. |
+| Plan the week (`craftbook-week-plan`) | Turn eight calendar events into a five-day plan, flag meetings that need preparation, resolve a Tuesday conflict, and protect focus time. |
+| A/B test read-out (`craftbook-ab-test-readout`) | Calculate the experiment results correctly and apply a pre-set decision rule, including a safety measure that overrides an otherwise positive result. |
+| Annotated bibliography (`craftbook-annotated-bibliography`) | Produce six consistently formatted source entries, each with a summary, an evaluation of the source, and its relevance to the question. |
+| Records intake (`records-intake`) | Combine registrations from emails, phone notes, and an old CSV into one correctly shaped, deduplicated record set with standardised dates. |
+| Plan and estimate (`plan-and-estimate`) | Produce an office-relocation plan with valid owners, correctly ordered dependencies, risks, and a checkable definition of done for every task. |
+| Meeting follow-up (`meeting-followup`) | Reconcile a noisy transcript, stale agenda, and current staff list into a decision brief and an exact action register with owners, dates, dependencies, questions, and risks. |
+| Spreadsheet model (`craftbook-spreadsheet-model`) | Calculate the correct roll-ups from seeded records and turn them into a useful spreadsheet-style model and read-out that highlights the main risk. |
+| Conflict synthesis (`conflict-synthesis`) | Reconcile five documents that disagree about a launch date, budget, and owner; show each conflict and use the authoritative answer consistently. |
+| Theme round-trip (`docblocks-theme-roundtrip`) | Read the theme from a brand document, apply it to a presentation, inspect the result, and report only fonts, colours, page counts, and unresolved styles returned by the document tools. |
+| Research to Word (`craftbook-research-to-document`) | Turn reviewed, source-grounded Markdown into a real editable Word document, preview it, and save the finished `.docx` as an artifact. |
+| PowerPoint deck (`craftbook-powerpoint-deck`) | Acquire and cite source material, create an outline, make every slide match it, and save a real editable `.pptx` presentation. |
+| Wikipedia research brief (`wikipedia-research-brief`) | Use a closed local copy of Wikipedia to select the relevant sources and write a cited 700–1,500 word brief with correct chronology and careful treatment of a disputed claim. |
+
 A model gets a score on each set. They measure different things, and it is
-normal for a model to be strong on one and weak on the other.
+normal for a model to be strong on one and weak on the other. Plan and
+estimate and conflict synthesis deliberately appear in both sets because
+they test capabilities that matter to each.
 
 ## What "passed" means
 
@@ -75,8 +111,12 @@ a coin toss that happened to land well.
 Sometimes a run fails for reasons that have nothing to do with the model: the
 graphics driver falls over, the machine runs out of memory, someone stops the
 run. Those attempts are recorded and set aside rather than counted as
-failures. A separate column shows how many were lost that way, so you can see
-when a score rests on fewer attempts than it should.
+failures.
+
+If enough of a model's attempts are lost that its results no longer stand up,
+we leave it out of the table rather than publish a score with a hole in it.
+A missing model means "not measured properly yet", never "measured and found
+wanting".
 
 ## What we deliberately don't claim
 
@@ -86,11 +126,19 @@ task set. Change any of those and you have a different experiment. When a
 model was measured in an earlier round we list it separately and say why —
 we never quietly merge it into a newer table to make the list look fuller.
 
-**We don't rank writing quality.** Alongside the pass/fail checks we ask a
-large AI model to rate qualities like clarity and grounding. Those ratings
-are useful for spotting patterns within a single round, but the rating model
-changes over time, so we do not treat them as a score you can track. Only the
-pass/fail results are.
+**Quality scores are an opinion, not a measurement.** Alongside the pass/fail
+checks we ask a large AI model to rate qualities like clarity, grounding and
+candour, and we publish that as a Quality column. Read it with two caveats.
+
+First, it only covers work that got *produced*. A model that gives up early
+is graded on the few pieces it did finish, so a high quality score over a
+small number of pieces can mean "good when it manages it" rather than
+"good". That is why the count always travels with the score — `6.5/10 (18
+pieces)` next to `6.5/10 (26 pieces)` are not the same claim.
+
+Second, the rating model changes over time, so quality scores are comparable
+*within* a round and not across rounds. The pass/fail results are the ones
+that track.
 
 **A score is not a recommendation for your machine.** Results come from one
 particular computer. A model that scores well on a large desktop may not fit

package/dist/handboek-content/technical/model-scorecard.md

@@ -1,7 +1,7 @@
 ---
 id: model-scorecard
 title: "Model scorecard"
-order: 8
+order: 11
 summary: Measured results for every model we have tested, on both task sets.
 ---
 # Model scorecard
@@ -33,14 +33,32 @@ model, a slide deck, a Word document.
 ## Reading the table
 
 **Tasks passed** counts every attempt across every job in the set. A model
-with `24/33 (73%)` finished 24 of 33 attempts correctly. Below three attempts
-you'll see a raw count instead of a percentage — too small a sample to quote
-as a rate.
-
-**Not measured** counts attempts lost to the machine rather than the model —
-a crashed graphics driver, an out-of-memory kill. Those are removed from both
-sides of the score. A large number here means the model was tested less
-thoroughly than the others, and the score deserves less weight.
+with `24/33 (73%)` finished 24 of 33 attempts correctly. If any job in the
+set ran fewer than three times you'll see a raw count instead of a
+percentage — too small a sample to quote as a rate. A model whose results
+were incomplete is left out of the table entirely rather than shown with a
+gap.
+
+**Quality** is an AI reviewer's opinion of the finished work, and the count
+beside it is how many pieces that opinion covers. It only grades work that
+was actually produced, so a model that fails often is judged on its
+successes alone — `6.5/10 (18 pieces)` is a weaker claim than `6.5/10 (26
+pieces)`. Treat it as colour next to the pass rate, never as a substitute
+for it.
+
+**Reads at / Writes at** are measured speeds on the machine named above:
+how fast the model takes in your documents, and how fast it writes its
+answer. Both matter for how a gezel *feels* — reading speed governs the
+pause before it starts, writing speed governs how fast text appears.
+
+**Context** is the working memory the model was given for these runs — how
+much it can hold at once. **Memory used** is the peak RAM the model and its
+engine actually occupied, which is the number to check against your own
+machine.
+
+**Earlier rounds** appear as separate tables below each set, with their own
+stamps. They are kept apart rather than merged because a change to gezel or
+to the task set can move a score without any model changing.
 
 **Size** is the model's parameter count where we know it. Bigger is often but
 not always better: on office work in particular, some smaller models beat

package/dist/handboek-content/technical/npm-packages.md

@@ -0,0 +1,67 @@
+---
+id: npm-packages
+title: "Gezel on npm: the package map"
+order: 7
+summary: Choose the command line, SDK, daemon, client, or lower-level package for your integration.
+---
+
+# Gezel on npm
+
+The desktop app is the simplest way to use gezel, but the same system is also available as a family of npm packages. You can install the `gezel` command, write a repeatable script, connect another app to local models, embed the daemon, or reuse the schemas and clients that Gezel itself uses.
+
+All eleven packages published from the Gezel repository require Node.js 24 or newer and expose public, semver-versioned contracts. You normally install only the package at the top of your use case; npm brings in its required Gezel dependencies for you.
+
+## Choose your starting point
+
+| You want to… | Start with |
+| --- | --- |
+| Use gezel from a terminal or server | [`@bendyline/gezel-cli`](cli-reference.md) |
+| Write an automation that runs inside Gezel | [`@bendyline/gezel-sdk`](writing-scripts-with-gezel-sdk.md) |
+| Let a desktop or Node app use the user's Gezel models | [`@bendyline/gezel-app-sdk`](building-connected-apps-with-gezel-app-sdk.md) |
+| Call the full daemon API from TypeScript | `@bendyline/gezel-client` |
+| Run or embed a daemon yourself | `@bendyline/gezel-service` together with `@bendyline/gezel-client` |
+| Give an MCP client Gezel's tools | `@bendyline/gezel-mcp` |
+| Share Gezel's schemas or parse its files | `@bendyline/gezel` |
+
+For example, the command-line install is:
+
+```bash
+npm install -g @bendyline/gezel-cli
+gezel
+```
+
+A library belongs in the application that uses it:
+
+```bash
+npm install @bendyline/gezel-app-sdk
+```
+
+## Every published package
+
+| Package | What it does | Who normally installs it directly |
+| --- | --- | --- |
+| `@bendyline/gezel` | Core TypeScript types, Zod schemas, path helpers, the `gezel.md` parser, native-platform helpers, and reusable gate checks. It is the shared wire-contract source of truth. | Library authors who need Gezel's data contracts or on-disk formats. |
+| `@bendyline/gezel-client` | Typed HTTP and event-stream client for the complete `gezeld` product API: projects, gezels, chats, tasks, scripts, models, memories, usage, and more. Its `/node` entry also contains local daemon discovery helpers. | Integrations that already have an authorized connection and need more than the OpenAI-compatible app surface. |
+| `@bendyline/gezel-sdk` | The small, typed API available to TypeScript scripts inside Gezel's sandbox: `defineScript`, `gezel.fs`, `gezel.task`, `gezel.llm`, and the other capability-gated namespaces. | Script and craftbook authors. See [Writing scripts with gezel-sdk](writing-scripts-with-gezel-sdk.md). |
+| `@bendyline/gezel-app-sdk` | Local discovery, pinned TLS, user consent, scoped token storage, model setup, chat, embeddings, and model listing for third-party applications. | Desktop and Node application developers. See [Building connected apps with gezel-app-sdk](building-connected-apps-with-gezel-app-sdk.md). |
+| `@bendyline/gezel-plugin-sdk` | The historical plugin helper surface. It remains supported for compatibility, but new extensions should use `@bendyline/gezel-sdk`. | Maintainers of existing Gezel plugins. |
+| `@bendyline/gezel-catalog` | Loads model definitions, toolsets, connector types, project types, gezel roles, and craftbooks from the separately released Gilde content. | Catalog tooling, tests, and embedders that need to resolve catalog items outside the daemon. |
+| `@bendyline/gezel-connectors-spectral` | An isolated subprocess host for compatible Prismatic components. Keeping it out of the daemon process isolates its SDK and vendored connectors. | Usually nobody directly; `@bendyline/gezel-service` resolves and spawns it. |
+| `@bendyline/gezel-script-stdlib` | The trusted, read-only standard library of gate scripts that ships with Gezel. Its plain TypeScript sources run in place under the `standard` script scope. | Usually the daemon; craftbook authors may inspect it for reusable standard checks. |
+| `@bendyline/gezel-mcp` | The stdio Model Context Protocol server that exposes workspace, memory, artifact, document, task, team, execution, history, and media tools. It calls back into a running daemon. | MCP hosts and custom agent harnesses that need Gezel's tool surface. |
+| `@bendyline/gezel-service` | `gezeld`, the local daemon. It owns state, provider routing, chat sessions, tools, tasks, engines, and the HTTP API, and includes the browser UI and Handboek. | Headless operators and applications deliberately embedding or managing a Gezel daemon. |
+| `@bendyline/gezel-cli` | The `gezel` terminal interface, one-shot runner, service manager, model and engine manager, media commands, and Handboek exporter. It does not expose a supported JavaScript API. | People using [the gezel command line](cli-reference.md). |
+
+## Packages that work together
+
+`@bendyline/gezel-app-sdk` and `@bendyline/gezel-client` solve different halves of a connected application. The app SDK discovers the logged-in user's daemon, pins its loopback certificate, asks for consent, and returns a scoped connection. Pass that connection to `GezelClient` when the application also needs the full product API.
+
+`@bendyline/gezel-service` is the runtime, while `@bendyline/gezel-client` is its supported control surface. Prefer the client over hand-written `/api` calls, and do not assume the service runs inside your process: the desktop app, CLI, and remote deployments all use the same HTTP boundary.
+
+`@bendyline/gezel-sdk` is different from both. Its code runs *inside* Gezel's script sandbox and receives only the capabilities declared by the script. It is for automations attached to projects and craftbooks, not for connecting a separate application.
+
+## The companion Gilde package
+
+`@bendyline/gilde` contains the catalog data: model entries, toolsets, roles, craftbooks, connector types, and project types. It is released from the separate Gilde repository and consumed at an exact version by `@bendyline/gezel-catalog`. Install it directly only when you are working with the catalog content itself; ordinary Gezel consumers receive it through the catalog package.
+
+The Electron app, React UI, VS Code extension, evaluation viewer, and deployment-only ML runtime are private workspaces rather than public npm packages. The desktop app and extension have their own distribution paths, the React UI is bundled into `@bendyline/gezel-service`, and the evaluation and ML workspaces support development and complete application builds.

package/dist/handboek-content/technical/security-model.md

@@ -59,7 +59,15 @@ Some tools deliberately run with more authority. After showing the exact
 command and receiving your approval, **package scripts and installed package
 binaries** (`run_package_script` and `run_npx`) run as your operating-system
 account. They may start other programs, use the network, and read or change
-files outside the project. Third-party MCP servers are also not inside the
+files outside the project. A persistent approval is tied to the exact command,
+its arguments, and the content hashes of local inputs Gezel can identify — such
+as `package.json`, a referenced script, relative static imports, or an installed
+binary entry. Changing one of those files asks for approval again. Commands can
+still discover files dynamically, load implicit configuration, resolve other
+programs through `PATH`, use outside-project or directory/glob inputs, or fetch
+code from the network, so this binding is not a complete dependency graph and
+does not turn package commands into a sandbox.
+Third-party MCP servers are also not inside the
 standalone-script sandbox; because they are unconfined local or remote code,
 Gezel enables them only under the corresponding Security & Compliance setting.
 
@@ -94,6 +102,15 @@ At your direction, Gezel can download additional scripts and tools from NPM
 has experienced compromises. Gezel installs packages with their install-time
 scripts disabled, preventing that common supply-chain execution path.
 
+Gezel's ordinary install flow accepts packages from the NPM registry only: a
+package name plus a version, semver range, or dist-tag. It does not accept a
+URL, Git repository, local file or directory, workspace reference, package
+alias, or command-line option in that field. Installs can target only the
+private package directory of an existing project; project identifiers and the
+resolved destination are checked before the package manager starts. Alternate
+package sources would need a separate, explicitly approved feature with their
+own network and path protections.
+
 What happens later depends on the tool type. A standalone script uses the
 sandbox described above. A package command runs with your account's authority
 after explicit approval. A third-party MCP server is unconfined and requires

package/dist/handboek-content/technical/where-files-live.md

@@ -24,6 +24,9 @@ Everything gezel knows lives in one folder — the **gezel home** — as plain f
       project.json    name, working folder, crew settings
       documents/      About + Mission Objectives
       artifacts/      everything the crew produces
+        shadow/       machine-made markdown twins of workspace documents,
+                      pictures, and recordings (rebuilt automatically —
+                      safe to delete, not a place to put your own files)
   documents/          the shared library
   history.jsonl       the audit log
   logs/               service logs (rolling)

package/dist/handboek-content/technical/writing-scripts-with-gezel-sdk.md

@@ -0,0 +1,106 @@
+---
+id: writing-scripts-with-gezel-sdk
+title: Writing scripts with gezel-sdk
+order: 8
+summary: Build typed, capability-limited automations that run inside a Gezel project.
+---
+
+# Writing scripts with gezel-sdk
+
+A Gezel script is a small TypeScript automation that runs in a sandbox. It can inspect a project, create an artifact, update a task, ask a model a focused question, call an approved tool, or decide whether a craftbook step may advance. The `@bendyline/gezel-sdk` package is the typed bridge between that script and Gezel.
+
+Scripts are project-scoped by default and live as readable files under `~/.gezel/projects/{projectId}/scripts/`. They can be run manually, attached to the start or end of a task step, used as a completion gate, or called by another script.
+
+## Start in the app
+
+Turn on **Settings → About → Advanced → Show advanced features**, then open **Scripts** from the sidebar. Choose a project and select **New script**. You can describe the automation for an AI draft, start from a working template, or begin with the blank skeleton.
+
+The built-in editor supplies autocomplete for the exact SDK version used by the running daemon. Saving checks the metadata, TypeScript syntax, and Node-compatible type syntax; **Run** supplies a form for the inputs declared by the script and shows its output, logs, calls, and errors.
+
+You do not need to install the SDK into each Gezel project. The daemon places its matching SDK in the sandbox at run time. Install `@bendyline/gezel-sdk` in a separate source repository only when that repository authors reusable scripts and should type-check them itself:
+
+```bash
+npm install --save-dev @bendyline/gezel-sdk
+```
+
+## The shape of a script
+
+Every script exports a static `meta` block, reads validated input from `gezel.input`, and stamps one final result with `gezel.output()`. This gate checks that a workspace contains a README before a task step can finish:
+
+```ts
+import {
+  defineScript,
+  gezel,
+  type GateScriptResult,
+  type InferredInput,
+} from '@bendyline/gezel-sdk';
+
+export const meta = defineScript({
+  name: 'require-readme',
+  description: 'Require a README before this step can finish.',
+  kind: 'gate',
+  inputs: {
+    path: {
+      type: 'string',
+      description: 'Workspace-relative README path.',
+      default: 'README.md',
+    },
+  },
+  requires: ['workspace.read'],
+} as const);
+
+const input = gezel.input as InferredInput<typeof meta>;
+const files = await gezel.fs.listAll();
+
+const result: GateScriptResult = files.includes(input.path)
+  ? { decision: 'approve', message: `${input.path} is present.` }
+  : {
+      decision: 'reject',
+      message: `Add ${input.path} with setup and usage instructions, then try again.`,
+    };
+
+gezel.output(result);
+```
+
+The file name is the script's invocation name, so keep it aligned with `meta.name`. Input descriptors drive the manual-run form and `InferredInput`; output descriptors document an action script's result. A gate instead returns `approve` or `reject`. A rejection must include a useful `message` because Gezel gives it directly to the working gezel as the repair instruction.
+
+## Declare capabilities before using them
+
+The `requires` list is both documentation and an enforced permission boundary. A call fails with `CAPABILITY_DENIED` when the matching capability was not declared, and project or installation policy can still deny a declared capability.
+
+| Capability | SDK surface |
+| --- | --- |
+| `workspace.read`, `workspace.write` | `gezel.fs` for project workspace files |
+| `artifacts.read`, `artifacts.write` | `gezel.artifacts` for generated project outputs |
+| `documents.read`, `documents.write` | `gezel.documents` for the shared document library |
+| `tasks.read`, `tasks.write` | `gezel.task` for task records, steps, and notes |
+| `memory.read`, `memory.write` | `gezel.memory` for project memories |
+| `llm` | `gezel.llm.oneShot()` |
+| `network` | `gezel.mcp.call()` and `gezel.http` |
+| `credential:<name>` plus `network` | `gezel.http.authed()` with a project-approved named credential |
+
+`gezel.input`, `gezel.output()`, `gezel.log()`, and `gezel.script.run()` need no capability. A nested script runs under its own metadata and permission set, and nesting is limited to four levels.
+
+Ask only for what the script needs. In particular, use `gezel.fs` for workspace I/O rather than importing Node's `fs`: raw filesystem code runs in an isolated scratch directory and cannot see the project workspace. For authenticated HTTP, the service attaches the named credential and scrubs it from the response; the secret value never enters the script.
+
+## Actions, gates, and hooks
+
+An action script produces ordinary structured output. Declare `outputs` in `meta`, then call `gezel.output()` exactly once with that shape. Actions are useful for reports, task updates, model-assisted transforms, and small integrations.
+
+A gate script sets `kind: 'gate'` and returns a `GateScriptResult`. `approve` allows the step to complete. `reject` holds the step and explains what must change. Optional `goto` routing can send work back to an earlier step, while an approved `handoff` can pass a message and parameters to the next step.
+
+After a script works manually, attach it from a task's step automation controls. Craftbooks can also ship scripts and connect them to step entry, exit, and gate moments. Gezel preserves a trace for each run: input, stamped output, logs, host calls, duration, trigger, and any error.
+
+## Reusable helpers
+
+The package has three public entry points:
+
+| Import | Purpose |
+| --- | --- |
+| `@bendyline/gezel-sdk` | `defineScript`, `gezel`, metadata types, inferred input/output types, and gate result types |
+| `@bendyline/gezel-sdk/checks` | Reusable gate-check predicates, `gateResult()`, and `workspaceFromGezel()` for adapting `gezel.fs` to check helpers |
+| `@bendyline/gezel-sdk/stores` | File-backed `logStore`, `rosterStore`, and integer-cents `ledgerStore` helpers for scripts that maintain structured project state |
+
+The separate `@bendyline/gezel-script-stdlib` package contains Gezel's trusted standard gate scripts. Use those by their `standard` scope when they already express the check you need; write a project script when the behavior belongs to one project, and a reusable craftbook script when it belongs to a workflow others will install.
+
+If the code lives in another application rather than inside Gezel's sandbox, use [gezel-app-sdk](building-connected-apps-with-gezel-app-sdk.md) instead.