@engenty/wizards-runtime 0.0.0-stage → 0.7.5

package/apps/runtime/dist/docs/user/models.md

@@ -0,0 +1,156 @@
+---
+title: Models and account
+description: What runs the AI in your wizards – an AI client on your computer, your own API keys, a local model or credits.
+version: 0.5.0
+---
+
+Settings → Models decides what runs the AI in your wizards. On your computer you set it up
+yourself. On engenty.ai the settings belong to the team, and only its admins can change them.
+
+## What the wizards can do
+
+The menu lists five capabilities under “Capabilities”. A dot beside each one shows how it runs:
+green on something of your own, amber on credits, hollow when nothing is set up.
+
+| Capability | Used for | Classes |
+|---|---|---|
+| Text & reasoning | Writing, research and decisions; Goose and the assistant in the editor | Classifier, Standard, High, Highest |
+| Images | Logos, product shots, illustrations | Image |
+| Videos | Short clips from text or an image | Video |
+| Voice | Reading text aloud | Speech |
+| Voice notes | Turning speech into text | Audio |
+
+A capability’s page asks “Who does it?”:
+
+| Choice | What it is | Cost |
+|---|---|---|
+| Your subscription | Claude Code, Codex, Antigravity or Cursor Agent on this computer, using your sign-in there (text; Codex also makes images; Antigravity runs steps without their tools) | Your subscription |
+| Your own API key | OpenAI, Anthropic, Google Gemini, fal.ai, ElevenLabs, Replicate or Vercel AI Gateway | The provider bills your key |
+| Apple Intelligence | The model on this Mac: short texts and decisions (Classifier, Standard) and voice notes. See [Apple Intelligence](#apple-intelligence) | Nothing |
+| Local model | [Ollama](https://ollama.com) on this computer (text) | Nothing |
+| engenty credits | Your account’s credits. engenty chooses the model, or you choose one it offers (FLUX on fal, ElevenLabs voices, Veo …) | Credits |
+
+Below that you choose the provider’s model, and “Try it” makes one real call: a short answer, a
+test image, a voice to hear, a 4-second clip or a transcript. A try costs the same as a real call.
+
+With an account, credits step in where you have nothing of your own set up – for example,
+videos without your own API key. The switch “Credits step in” on the page “engenty credits” turns
+that off. A capability with nothing of its own set up then doesn’t run.
+
+## Apple Intelligence
+
+On a Mac with Apple silicon and macOS 26 or later, the [setup](./first-start.md) and “Text &
+reasoning” offer Apple Intelligence: the model Apple keeps on the Mac. It is there on your
+computer only, not on engenty.ai. Nothing leaves the Mac, you don’t sign in and you pay nothing.
+It needs Apple Intelligence switched on (System Settings → Apple Intelligence & Siri). Until
+then, the choice says why it can’t be used yet: “switched off” or “Apple is still loading the
+model”.
+
+The model is small. It reads at most 4,096 tokens for a prompt and its answer together, and it
+uses no tools. So it takes only the classes Classifier and Standard: decisions, picking values
+out of text and short copy. A step of these classes runs there without its tools (no API calls,
+no web, no lists or documents). A step whose text is too long fails with a note that says so.
+Give such a step the class High, or choose something else for the class. The binding is
+`apple:default`; `apple:tagging` is Apple’s adapter for tagging and extraction.
+
+High and Highest keep what they ran on before: the AI client on this computer, an API key or the
+credits. The page names it under the choice. If you later choose something else for text,
+Classifier and Standard leave Apple Intelligence again.
+
+“Voice notes” offers Apple Intelligence on the same Macs, even with Apple Intelligence switched
+off. The Mac writes a recording down itself (`apple:transcribe`), in the language of the run, and
+it costs nothing. The first note in a language waits while Apple downloads that language. A
+recording from Chrome or Firefox (WebM, Ogg) needs ffmpeg on the Mac, which turns it into WAV
+first. Recordings from Safari and the app need nothing. Without ffmpeg, the page “Voice notes”
+says so.
+
+**In the app.** On an iPhone with iOS 26, the engenty wizards app writes voice notes down on the
+phone. Once Apple Intelligence is switched on, it also answers a run’s short text calls:
+Classifier and Standard steps without tools or files of their own. A run in the cloud then
+spends no credits on them, and that text never leaves the phone. Where the phone doesn’t answer,
+the run uses what these settings say.
+
+## Keys
+
+engenty wizards checks a key with its provider before it stores it. On your computer, keys stay
+in the Keychain on a Mac and in an encrypted file in the data folder elsewhere. On engenty.ai
+they are kept encrypted for the team. They are never in the database, and nobody sees them again.
+
+Under “Access” you find the credits, the AI clients on this computer and each provider you gave
+a key. The other providers are under “More providers”. A provider’s page holds its key, what it
+is used for, and which of its models run on credits without your own API key.
+
+On engenty.ai, your own API keys come with the Pro plan. Without them, runs use the team’s
+credits.
+
+Vercel refuses many models for an AI Gateway key on its free tier. The Models page and the check
+before a run say so, with a link to top up at Vercel.
+
+| Provider | Serves |
+|---|---|
+| OpenAI | Text, images, voice, transcripts |
+| Anthropic | Text |
+| Google Gemini | Text, images, video (Veo), voice, voice notes |
+| fal.ai | Images (FLUX, Recraft, Imagen), video (Veo, Luma, MiniMax), voice, transcripts |
+| ElevenLabs | Voices, transcripts (Scribe) |
+| Replicate | Images, video |
+| Vercel AI Gateway | Many providers’ models with one key, web search |
+
+## Model per class
+
+A step names a class, never a model. For text, “Adjust per class” sets the model of each class:
+
+| Class | Used for |
+|---|---|
+| Classifier | Decisions, picking values out of text |
+| Standard | Short copy, API calls |
+| High | Research, long documents; [Goose](./assistant.md) |
+| Highest | Hard reasoning, code; the assistant in the editor |
+
+You write a model as `vendor/model` for the AI Gateway, with the provider in front for the others
+(`openai:gpt-5.4-mini`, `fal:fal-ai/flux/schnell`, `ollama:qwen3`), or as `credits` /
+`credits:<model>` for the credits.
+
+Some decisions go to a decision model, Jev, wherever one can be reached: decisions in a wizard (a
+branch with a statement, a field shown when the AI finds a statement true) and the check of what
+a Knowledge search found. Jev is reached through an AI Gateway key, a TypeSafe key
+(`TYPESAFE_API_KEY` in the settings file) or an account. Without one of them, the Classifier class
+decides.
+
+## The editor’s chat
+
+Where Claude Code is installed on this computer, “The studio chat uses” (on the page “Text &
+reasoning”) sets what builds your wizards in the editor’s chat:
+
+| Choice | Means |
+|---|---|
+| Model class Highest | The model set for that class |
+| Claude subscription (Claude Code) | Claude Code on this computer builds the wizard, using your sign-in there. Runs still use keys or credits |
+
+## Account
+
+engenty wizards on your computer normally signs in to your account during the setup
+([Install](./install.md)). If you set it up without an account, it stays
+[on your computer only](./local-only.md). With an account you can
+
+- use credits instead of your own API keys (where text, image or video models are missing, the
+  editor’s note about them says so),
+- publish wizards to the cloud, where their links work while your computer is off
+  ([Test and share](./test-and-share.md#in-the-cloud)),
+- connect Gmail, Drive, Calendar and Contacts without a Google client of your own
+  ([Connectors](./connectors.md)).
+
+You sign in under Settings → Account, which opens your browser. In a terminal,
+`wizards account sign-in` does the same. A new account needs an invitation code: enter it under
+“No account yet?”, and “Create account” opens the sign-up with the code filled in
+([Create an account](./create-account.md)). An account starts with credits. Some of them expire
+on a set date, which the settings show. Runs in the cloud are paid from the account’s credits.
+They stop when the credits are used up, until you top up.
+
+While you are signed in, the studio uses the name and email of your account. Settings → Account
+shows them under “Profile”, and you can’t change them there. The avatar carries a small cloud.
+Its menu says “Connected to engenty.ai” and shows your credits, or says “Sign-in expired” when
+you need to sign in again.
+
+Without an account, engenty wizards isn’t connected to anything. Your wizards, the space and its
+files stay on your computer.

package/apps/runtime/dist/docs/user/plugins.md

@@ -0,0 +1,71 @@
+---
+title: Plugins
+description: Add pages, settings and tools for steps to engenty wizards on your computer. What a plugin may do, and how to install one.
+version: 0.5.0
+---
+
+A plugin adds to engenty wizards without changing it:
+
+| It can add | Where you find it |
+|---|---|
+| Tools for AI steps | In a step’s tool list, beside the built-in ones |
+| What every AI step of a space knows | Nowhere: the steps get it, with tools to look things up |
+| A page | Behind an icon in the studio’s app bar |
+| A settings section | In the settings |
+| A section of the space page | In one of the space page’s parts |
+| A part of the space page | In the space’s menu, beside Info & brand, Knowledge and Data |
+| A template | First among the templates of a new wizard |
+| A channel a wizard runs through | Under “How should it run?” on a new wizard, and under “How others reach it” in the share dialog, where “Set up” opens the plugin’s own setup |
+| Something that happens when a run ends, or again and again | Nowhere: it works in the background, for example posts a message |
+
+> A plugin runs with the app’s full rights: it reads your wizards, your results, your settings
+> and the files on your computer. Install only plugins you trust.
+
+## Install one
+
+A plugin is a file or a folder. Put it into the plugins folder of engenty wizards:
+
+```bash
+~/.engenty/wizards/plugins
+```
+
+- engenty wizards notices a new plugin while it runs. You don’t need to restart it.
+- A plugin’s own instructions say which settings it needs. They go into the
+  [settings file](./command-line.md#settings).
+- To use another folder, name it with `PLUGINS_DIR` in the settings file. You can name several,
+  separated by commas. They replace the plugins folder above, so name that one too if you want
+  to keep it.
+
+## See what is installed
+
+Settings → Plugins lists the plugins with their version and the tools they add. The section
+appears once there is a plugin, or a file that looks like one. It also appears while you are
+signed in to an account.
+
+| Button | What it does |
+|---|---|
+| Reload | Loads one plugin again from its files |
+| Look again | Loads all plugins again and finds new ones |
+
+- “The server part didn’t load” or “The studio part didn’t load” says what went wrong with a
+  plugin. The plugin adds nothing until that is fixed.
+- “Not a plugin” lists files in the plugins folder that look like a plugin but aren’t one.
+
+## Remove one
+
+Delete its file or folder. Tables the plugin made in your database stay, with their rows.
+
+## Wizards that use a plugin’s tool
+
+A wizard that lists a plugin’s tool runs only where that plugin is installed. Elsewhere the
+editor shows an issue, and a run stops at that step. Keep that in mind when you export a wizard
+or publish it to the cloud.
+
+## On engenty.ai
+
+engenty installs the plugins in the cloud. Settings → Plugins lists the ones switched on for your
+account.
+
+## Write your own
+
+See the [developer docs](../dev/plugins/index.md).

package/apps/runtime/dist/docs/user/run.md

@@ -0,0 +1,98 @@
+---
+title: Run a wizard
+description: What you see when you open a wizard's link, on a computer or a phone.
+version: 0.5.0
+---
+
+## From the link to the result
+
+1. The link opens the wizard. “Let’s go” starts a run.
+2. Pages ask their questions. “Continue” takes you to the next page, “Back” to the one before.
+3. While an AI step works, the page says what it is doing. The screen stays on.
+4. A review shows what was made. “Looks good” accepts it. “New version” asks for another one,
+   with a note on what should change. “Edit” lets you change a text by hand.
+5. The result page offers the downloads, “Copy text” and “Share”.
+
+If you left a run, you can pick it up again with “Continue your last run”.
+
+## As a chat
+
+Where the owner switched it on, the wizard also runs as a chat, at `…/chat` or straight on its
+link. It asks one question at a time. You answer in the composer or with the replies under the
+question, and every answer stays in the chat. The composer has these buttons:
+
+| Button | Does |
+|---|---|
+| Speaker (“Read aloud”) | Reads what the wizard says aloud, with the browser’s own voice in the wizard’s language. It costs nothing and stays on in this browser |
+| Microphone (“Dictate”, ⌘⇧M, Ctrl⇧M on Windows) | Dictates into the composer. Where the browser can recognise speech, it writes along. Elsewhere the wizard’s own model writes the recording down when you stop, like a voice note |
+| Phone (“Start talking”) | Starts a live conversation: you talk, and the wizard talks back and fills its pages from what you say, one question at a time. Files and signatures stay on the screen, and the wizard tells you so. The button is there only where the owner switched on live voice or the video call for the wizard (always in the owner’s test run), and for now only where the app that runs it has an OpenAI API key under Models |
+| Camera, in a conversation | The wizard sees what you show it (“is the dent on the left?”) and takes photos into a photo field when you hold something still. The small picture shows what it sees |
+
+When a step works on a website, the chat shows that page live with what the wizard just did.
+“Take over” lets you click and type in it yourself while the wizard waits. “Hand back” lets the
+wizard go on from where you left the page.
+
+## As a live conversation
+
+Where the owner switched it on, the wizard opens at `…/talk`, or straight on its link, as a
+live audio screen. “Start talking” begins the conversation. The wizard’s engenty stands alone
+in the middle: it breathes while it speaks and glows while it listens. The whole transcript of
+what either of you said runs under it, with “Mute”, the camera and “Leave” underneath. The chat
+sits beside it as the screen the wizard draws on. If you switch the camera on, it becomes the
+video call below.
+
+## As a video call
+
+Where the owner switched it on, the wizard runs as a call, at `…/video` or straight on its link.
+A stage shows your camera and the wizard’s engenty as the two on the call, with what either of
+you said as captions. The controls underneath are “Mute”, the camera, “Switch camera” on a phone
+and “Leave”. The chat sits beside the stage (under it on a phone) and is the screen the wizard
+draws on: the questions and answers as they go, a photo field filled from the camera, a
+signature or a file where only the screen can take it, and the result at the end.
+
+“Let’s go” starts the run, and “Join” starts the call. Your browser then asks for the microphone
+and the camera. The conversation is the same as the chat’s live voice, with the camera on from
+the start. For now it needs an OpenAI API key under Models.
+
+## On a phone
+
+| The wizard asks for | The phone gives |
+|---|---|
+| Photos | The camera, page after page, or pictures from the library |
+| A paper | The camera as a scanner |
+| A short clip | The camera, up to 30 seconds |
+| A serial or ticket number | “Scan” reads a QR code or barcode |
+| Where you are | “Use my location”, with its accuracy. You can type an address instead |
+| What happened | “Record a voice note”, up to 5 minutes |
+| A sign-off | “Sign here”, with your finger |
+
+Your browser asks before it uses the camera, the microphone or your location. If you denied one,
+allow it in your browser’s site settings (the lock icon in the address bar). Or use the fallback
+the field offers: choose a photo, type the address or choose an audio file.
+
+With “Tell me when it’s done” you can switch apps during a long step: a notification, a sound
+or a buzz brings you back. “Add to home screen” puts the wizard on your phone like an app. On a
+computer, “Bookmark this wizard” shows how to keep it in your bookmarks.
+
+## When the wizard needs you
+
+| It shows | Because | You |
+|---|---|---|
+| A website live, with a sign-in | A step met a login, a captcha or “continue with Google” | Fill in the fields shown, or click and type in the live page itself. Then choose “Sign in” or “I’m signed in”. What you enter goes straight into the page, and the AI never sees it. “Remember this sign-in for next time” stores it encrypted. “Skip” goes on without the site |
+| “The wizard wants to run this in …” | A step wants to change something in a service you connected | Choose “Allow”, “Allow for the rest of this run” or “Don’t allow”. Reading doesn’t ask, deleting always does |
+| “Connect” | The wizard works with your own account of a service | Sign in to the service in a new tab. The connection is kept for your next run |
+
+## What this wizard remembers
+
+A wizard can keep lists, files and connected accounts for your next run. Only you see them.
+The link “What this wizard remembers” below the wizard’s pages shows what is kept, and “Delete
+everything” deletes it. Anything nobody used for 400 days is deleted by itself.
+
+## Share a result
+
+“Share” on the result page makes a link to the result. You can copy it, send it by email or hand
+it to another app. When you ran the wizard over its link, the result and its link are kept for 7
+days. “Withdraw link” ends the link earlier.
+
+Media made by a model carries an “AI-generated” label. Whoever publishes it has to label it as
+AI-generated. The file already carries the marking.

package/apps/runtime/dist/docs/user/server.md

@@ -0,0 +1,52 @@
+---
+title: Run it on a server
+description: One Docker container behind an https proxy, so others can open your wizards' links.
+version: 0.5.0
+---
+
+engenty wizards on your computer answers on `localhost` only. On a server with a public address,
+anyone with a link can run your wizards.
+
+## Start it
+
+You need Docker and an https proxy in front, such as Caddy or Traefik.
+
+```bash
+git clone https://github.com/engenty/wizards.git
+cd wizards
+cp .env.example .env
+```
+
+In `.env`, set `APP_URL` to your https address (the container doesn’t start without it) and add
+a model key. Then:
+
+```bash
+docker compose up -d --build
+docker compose logs
+```
+
+The logs show a link (“Open the studio: …”). Open it once: it signs your browser in.
+
+## What to know
+
+| | |
+|---|---|
+| Port | Point the proxy at port 8891 |
+| Data | Databases and files are on the `/data` volume. Back that volume up |
+| Models | Your own API keys or Ollama. The subscriptions of AI clients live on your own computer, not on a server |
+| PDF, PNG, browser steps, MP4 | Chromium and ffmpeg are in the image |
+| Code & shell | The sandbox is off in this image, so steps can’t use that tool. `compose.yaml` shows how to switch it on |
+| Plugins | Put them in a folder that you mount into the container and name in `PLUGINS_DIR` |
+
+## Update
+
+```bash
+git pull
+docker compose up -d --build
+```
+
+Your data is brought up to date when the container starts.
+
+## Sign in again
+
+The link works once. For a new one, restart the container and read the logs again.

package/apps/runtime/dist/docs/user/space.md

@@ -0,0 +1,126 @@
+---
+title: Space
+description: What your wizards share and produce – who you are, what they look things up in, and the results of their runs.
+version: 0.5.0
+---
+
+Your space holds what all your wizards share, and what they produce. Every AI step knows it, so a
+wizard never has to ask for your company’s name or address.
+
+You open it in two ways:
+
+- The house in the app bar, after the space’s tile, opens the space’s page.
+- The button left of the space’s name in the top bar (“Space menu”) opens the sidebar. It lists “Wizards”,
+  “New wizard” and, under “Space”, the space’s four parts. On a narrow window the sidebar stays
+  closed.
+
+The menu on the left shows the space’s four parts. A part opens its own sections, and the arrow
+at the top leads back. While the sidebar is open, the menu stands in it. On a phone, the parts,
+a part’s sections and the page take turns.
+
+| Part | Sections | Used for |
+|---|---|---|
+| Info & brand | Basics, Facts, Logos, Colours, Brand assets | Who you are and how you look |
+| Knowledge | All, then each category, then the sections plugins add | What every AI step looks things up in |
+| Data | All data, General, then each wizard | Tables and pages the wizards keep |
+| Results | All results, then each wizard | The runs that reached their result |
+
+## Info & brand
+
+Logos, Colours and Brand assets each have an “Add” menu in their head.
+
+| Section | Holds | Used for |
+|---|---|---|
+| Basics | “Title” and “About”: what you do, for whom, and the tone you write in | Texts sound like you. People who run a wizard see the title too |
+| Facts | Labelled values: address, VAT ID, opening hours | Steps use them as written |
+| Logos | One or several, each with a description of what it is for. Upload one, or take it from a web address (“Logo from URL”) | People see the main logo. The description tells a step what a variant is for |
+| Colours | Named colours, each with a note on its use. Add one, or read them off a web page (“Colours from URL”) | The first colour is the accent of documents, dashboards and public pages |
+| Brand assets | Images, videos, audio, PDFs, fonts, Lottie and 3D files, in tabs you can search | AI steps place pictures in documents and choose them by their description |
+
+## Knowledge
+
+Knowledge is the ground truth your wizards’ steps look things up in: pages, tables and files. You
+see here exactly what a step can find. Drop documents on the page, or add a page or a table
+yourself (“New page”, “New table”). A table can be an FAQ, with a question and its answer per row.
+
+- **Documents become pages and tables when they arrive.** A PDF, a Word file or a scan becomes a
+  page. The original stays behind it (“Original”), and the page marks where each page of it
+  begins, so a step can quote “p. 2”. A long document with headings of its own, such as a law or
+  a manual, becomes a page with sub-pages, one per section; “§ 281” in the text links to that
+  sub-page. A workbook becomes a table per sheet, and a CSV becomes one table. What can’t be read
+  stays a file, and steps find it by its name and description. A scan that read badly is marked
+  “Check”.
+- **Categories keep things apart.** A category is a property with a type: a choice (building
+  site, type of funding), a date, a number with its unit, a text, or yes/no. You set them on a
+  page, a table or a file with the chips under its title. When a document arrives, a model fills
+  them in from what it reads. A table’s column can be one. A step filters by them before it
+  searches: “reports of Graz Süd in March” is a filter first.
+- **Each value of a choice** has its contents (everything that has this value) and an overview.
+  A model writes the overview when you ask for it (“Write the overview”). The search finds the
+  overview like a page.
+- **Two spellings of one value** (“Graz-Süd”, “Graz Süd”) are offered for merging on the
+  category’s page. A category that a source proposes stands as “Proposed” until you accept it.
+- **“Try a search…”** searches the way a step does: the filters first, then words and meaning.
+  Then a model asks of each hit whether it answers the question, keeps those that do and says how
+  sure it is. That check is quickest with a decision model, which needs an AI Gateway or TypeSafe
+  key, or an account. Searching by meaning needs an AI Gateway or OpenAI key, or an account;
+  without one, the search finds words only. See [Models and account](./models.md).
+
+A plugin can fill Knowledge from outside, from a website or a folder, for example. What it wrote
+shows where it came from (“From …”). Once you change it by hand, it stays yours, and the plugin
+no longer updates it.
+
+## Data
+
+Data holds the tables and pages of the space and its wizards. Those of the space itself stand
+under “General”, a wizard’s under its name. A wizard fills its own: a shared list becomes one of
+its tables, and a step with the “Pages” tool writes its pages. The columns of a shared list come
+from the wizard. The buttons “Table” and “Page” add one, for the space or for one of its
+wizards.
+
+- **Table**: columns of a type (text, number, date, duration, choice, yes/no) and a row per
+  line. Type into a cell; it is saved when you leave it. A value that doesn’t fit the column is
+  marked and not saved. The heading of a column changes its name and type, and the plus beside
+  the headings adds a column.
+- **Page**: a title and text in Markdown. “Write” edits it, and “Preview” shows it. It is saved
+  as you type.
+
+### On your computer and in the cloud
+
+Data stays where it was written. A wizard’s tables and pages are filled where it runs: on your
+computer by its runs there, in the cloud by the runs over its link. The pages and tables of
+Knowledge, with their categories, go to the cloud with every wizard you publish there. The cloud
+shows them without changing them. Files stay on your computer.
+
+## Results
+
+Results lists every run that reached its result, newest first: of all wizards, or of the one you
+choose in the menu, where the wizard with the latest result stands first. The search finds words
+in the wizard’s name, in what was answered and in what the run produced. The filters keep live or
+test runs, and the last 24 hours, 7 or 30 days. A run opens beside the list as the person saw it,
+with its files.
+
+## Have it filled in
+
+[Goose](./assistant.md), at the bottom of the page, fills in the space for you where it is
+switched on. Tell it about yourselves, name your website or give it files:
+
+> Read our website example.com
+
+It enters what it finds: title, description, logo, colours and facts. You correct the rest.
+
+In the cloud, the first visit to the studio does the same: it asks for your website and your
+first documents. See [Create an account](./create-account.md).
+
+## One space
+
+engenty wizards on your computer has one space, called “My computer” at first (“Mein Computer” in German). On engenty.ai the
+team’s plan says how many spaces it may have. The space’s name in the top bar opens a menu: it
+switches between spaces, “Rename space” renames this one, and “Add space” adds one while the plan
+has room. Each space
+has its own wizards, Info & brand, Knowledge, Data, connectors and results. The account, the
+models and the plugins are the same for every space.
+
+When you publish wizards from your computer with an account signed in, their space shows up in
+the cloud too, marked with a laptop. You can only look at it there: you edit it in engenty
+wizards on your computer, and changes show up in the cloud the next time you publish a wizard.