@engenty/wizards-runtime 0.0.0-stage → 0.7.5

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

@@ -0,0 +1,220 @@
+---
+title: Steps
+description: What a wizard is made of – pages, AI steps, generated media, widgets, reviews and the result.
+version: 0.5.0
+---
+
+A wizard runs its steps from top to bottom. The last step is always the result.
+
+| Step | What it does |
+|---|---|
+| Page | Asks the person: one to five fields |
+| AI step | Does a task with tools: research, read documents, call an API, work in a connected service |
+| Generate | Makes one thing: an image, a video, a voice-over, a document or a dashboard |
+| Widget | Shows an interactive view built once for this wizard: a map, a timeline, a calculator, a film |
+| View | Shows the results in the wizard’s own look: key figures, facts, a list, a chart |
+| Film | Has the AI client on your computer make a film as code, rendered to an MP4 |
+| Review | Shows what earlier steps made. The person accepts it, edits it or asks for a new version |
+| Result | The last page: what the person can download or share |
+
+## Pages
+
+A page has a title, up to five fields and a button. Each field has a kind:
+
+| Kind | The person |
+|---|---|
+| Short text, Long text, Number, Date, Email, Link | types a value |
+| Choice, Multiple choice, Yes/no, Colour | chooses |
+| Image upload | takes or uploads photos, one or several, in an order they can change |
+| File upload | uploads documents. The camera can scan papers and record a short clip |
+| Line items (table) | fills rows with amounts. The wizard works out net, VAT and total |
+| Location | taps “Use my location” or types an address |
+| Voice note | records up to 5 minutes. The wizard writes down what was said before the next step reads it. You choose who writes it down under Voice notes in [Models](./models.md); a Mac can do it itself |
+| Signature | signs with a finger |
+| Appointment | chooses one of the free times offered, shown by day |
+| Connect an account | connects their own account of a service, for example their mailbox |
+| Saved list | checks, corrects and extends a list the wizard keeps for them |
+
+A text field can have a “Scan” button that fills it from a QR code or barcode.
+
+A field can start with a value an earlier step proposed. A line-items field, for example, shows
+the positions an AI step looked up, for the person to correct.
+
+A field can be shown only under a condition (“Show only when”): “Street and town” only when the
+person chose delivery, “Which allergy?” only when they ticked “Allergies”. The condition can
+read another field of the same page, and the field then appears as the person answers. It can
+also read anything known before the page. A hidden field is not required and is not kept.
+
+The choices of a choice field can come from earlier data (“Choices from earlier data”) instead
+of a fixed list: the suppliers a research step found, one column of a table it made, or a column
+of a list the wizard keeps. The fixed choices stand in while that data is empty. When the choices are the rows of a table, each
+can show as a card with a picture, a line or two of text and “Details” to open its page.
+
+An appointment field takes its times the same way, usually from an AI step that looked up the
+free times in a calendar. The times show in the calendar’s own time zone, grouped by day.
+
+A field can also be left to the AI. The AI reads what was answered and found so far, and shows
+the field when it finds a statement true (“The complaint is about a damaged article”). Fields
+that are alternatives of each other form a group, and the AI shows the one that fits (“How
+should we reach the person?”). The AI decides once, when the run reaches the page. A page whose
+fields the AI chooses holds up to 12 of them and shows at most five.
+
+## AI steps
+
+An AI step has instructions and the tools you allow it:
+
+| Tool | Lets the step |
+|---|---|
+| Web search | search the web |
+| Read web pages | open and read a page |
+| Browser | click and type on websites, take screenshots, download files. The person types a login themselves; the model never sees it |
+| Code & shell | run code in a sandbox, where engenty wizards has one |
+| Images | make images while it works |
+| API | call an HTTP API |
+| Pages | write pages of the wizard in Markdown, kept for every later run, and read them and the pages of the space’s Knowledge |
+
+Every AI step can also read and write the wizard’s lists, list its files and read documents:
+PDFs, scans and photos, Word, Excel, CSV and saved mails. Where the space has Knowledge, the step
+searches it too. Every AI step also knows the space’s Info & brand: its title, what it says
+about itself, its facts and colours.
+
+Further tools come from three places:
+
+- **The person’s accounts**: connectors the wizard uses, where the person connects their own
+  account during the run. The step gets the service’s actions as tools. Reading is free; before
+  anything changes in the person’s account, they are asked. See [Connectors](./connectors.md).
+- **Connected systems** (MCP servers) of the space, where you allow them on the step.
+- **Plugins** installed in engenty wizards. See [Plugins](./plugins.md).
+
+### Model class
+
+A step names the kind of model it needs, never a model:
+
+| Class | For |
+|---|---|
+| Classifier | Routing, yes/no, picking from options, pulling a few values out of text. Cheapest |
+| Standard | Short copy, calling an API, reformatting |
+| High | Research with tools, long documents, weighing many sources. The default |
+| Highest | Hard reasoning or code. Several times the cost of High |
+
+On a Mac, Classifier and Standard can run on [Apple Intelligence](./models.md#apple-intelligence).
+It is free and stays on your computer, but it handles only short texts and no tools. There, give
+a step that calls an API or reads documents the class High.
+
+Images, video, voice notes and voice-overs have classes of their own. You choose which model
+serves a class under [Models and account](./models.md). “Thinking effort” sets how much effort
+the model puts in. Leave it on “Automatic” unless a step is clearly trivial or clearly hard.
+
+### What a step hands on
+
+A step’s output is text, Markdown or structured data with named fields: a text, a number, a
+list, a table, a yes/no answer, a choice or a score on a scale (“low, medium, high”). Later
+steps use these, and branches decide on them.
+
+## Generate
+
+| Makes | Options |
+|---|---|
+| Image | Aspect ratio, style, a reference image to start from |
+| Video | Aspect ratio, 4 to 10 seconds, 720p or 480p, a reference image |
+| Voice | The exact text read aloud, and how to speak it |
+| Document | A template: invoice, offer, briefing, letter, report or free |
+| Dashboard | An HTML page with the figures of earlier steps |
+
+An image or video step can make one result per entry, at most eight: per uploaded photo, per
+image of an earlier step, or per row of a table. In a review the person can have single results
+made again.
+
+## Views
+
+A view shows what the run found in the wizard’s own look, on any screen: key figures, a list of
+facts, a list of results with pictures, a table or a simple chart (bars, a line, a ring). It is
+built from a fixed set of parts that the assistant writes once, and every run brings new data.
+It costs nothing to show.
+
+A view can also leave some of its parts to the AI, for example a chart only when there is
+something to compare. And an AI step can lay out a view of its own result, which reviews and the
+result page then show instead of a plain table.
+
+For anything the parts cannot show, such as a map or an animation, use a widget.
+
+## Widgets
+
+A widget is an interactive HTML view written once into the wizard’s files. Every run only brings
+new data, so it costs nothing to show and looks the same every time. A widget can also be a
+film: its timeline is then rendered to an MP4 with sound. Ask the assistant for one in the chat.
+
+## Films
+
+A film step hands a brief, the run’s material (voice-overs, pictures, uploads, texts) and the
+space’s brand to the AI client installed on your computer (Claude Code). The client writes the
+film as code, looks at its frames and fixes them. engenty wizards then renders the MP4: 16:9,
+9:16 or square. A film step runs only where Claude Code is set up with your subscription, never
+on credits or in the cloud, and it takes 10 to 40 minutes. The voice comes from a generate step
+before it.
+
+## Reviews
+
+A review shows what earlier steps made. Depending on its settings, the person can edit the text
+(“Text can be edited directly”) or ask for a new version with a note on what should change (“Ask
+for a new variant”). A list shown in a review is edited in place. A list with files is checked
+row by row, each row beside its document.
+
+## The result
+
+Each entry of the result page names a step and the formats the person can download:
+
+| From | Formats |
+|---|---|
+| Image | PNG (several: a ZIP) |
+| Video | MP4 (several: a ZIP) |
+| Voice | MP3 |
+| Document | PDF, Word, HTML, Markdown, PNG |
+| Dashboard | HTML, PDF, PNG |
+| Widget | HTML, PNG, PDF, JSON; MP4 when it animates. As a film: MP4, PNG |
+| View | JSON |
+| Film | MP4 |
+| AI step, text | Markdown, text, Word, PDF, HTML |
+| AI step, data | JSON, CSV, Excel, Markdown |
+| AI step, collected files | ZIP |
+| List | Excel, CSV, JSON, Markdown; ZIP with the files its rows name |
+
+## Branches
+
+A step can send the run somewhere else when a condition holds: a field is or is not a value, is
+one of several, is filled in or empty, is greater or less than a number, or contains a value. A
+condition can also read what an AI step found, how sure the AI was of a decision, or how many
+rows a list the wizard keeps has. Several conditions on one branch must all hold. The first
+branch that matches wins; otherwise the step’s “otherwise” branch, or else the next step,
+follows. The diagram shows the branches with their conditions.
+
+A branch can also be decided by the AI: instead of a condition it has a statement (“The person
+wants a refund, not an exchange”). When no condition matched, the AI reads what was answered and
+found so far and takes the branch whose statement is true; if none clearly is, the next step
+follows. All such branches of a step cost one small decision together.
+
+A branch back to an earlier step makes a loop, for example “write, check, write again until the
+check passes”. A loop stops after the number of times you allow, at most ten if you set nothing.
+The step that runs again sees what it made the last time.
+
+An AI step can also work through a list: once per row of a table an earlier step made, or per
+row of a list the wizard keeps, at most 20 rows. Its results come together in one table.
+
+## What a wizard keeps
+
+- **Lists** hold rows between runs, separately for each person who runs the wizard: the
+  receipts already booked, the customers already written to.
+- **Shared lists** hold one set of rows for every run: requests, sign-ups, a log. The person
+  running the wizard never sees them; you find them under Space → Data, below the wizard, and
+  in the editor under “Memory”.
+- **Connected accounts and sign-ins** are kept for the person’s next run.
+
+The person sees and deletes all of it under “What this wizard remembers”. See
+[Run a wizard](./run.md).
+
+## AI media
+
+Images, clips, voice-overs and films a model made or changed carry a marking in their file, and
+every page lays an “AI-generated” or “AI-modified” label over them (EU AI Act, Art. 50). Nothing
+is drawn into an image. A film shows the label in the picture, since it leaves the page as a
+video file.

package/apps/runtime/dist/docs/user/test-and-share.md

@@ -0,0 +1,224 @@
+---
+title: Test and share
+description: Try the wizard, publish it, and hand out its link or put it on a website.
+version: 0.5.0
+---
+
+## Test
+
+“Test” in the editor starts a run of the draft, just as a person would see it. Test runs are
+listed under “Runs”. A test spends what a real run spends: your model’s usage, or credits. A test
+run reads the wizard’s memory, but it writes into a copy of its own, which goes with the run.
+
+Where runs spend credits, each AI step shows an estimate. At first it is a formula. After five
+runs it is measured from the latest ones.
+
+## Publish
+
+A wizard goes live the first time you share it. “Share” publishes the draft as version 1 as the
+dialog opens, and the dialog says “Published when you shared it”. Nobody has the link yet, and
+“Only you” under “Access” keeps it closed. A draft with issues is not published: the dialog lists
+what to fix first, with “Let the assistant fix it”.
+
+After that, the editor’s top bar shows “Publish changes” whenever the draft differs from the
+version people run. It opens a dialog with these parts:
+
+| Part | Says |
+|---|---|
+| What changed | The wizard’s own settings, each step by its title (new, removed, or which of its parts changed: fields, instructions, result …), the order of the steps and the files |
+| Tested | Whether a test run used exactly this draft: “Tested 4 minutes ago – with these changes” with “See the run”, or “Not tested with these changes yet.” with “Test now” |
+| Notes | Anyone in the middle of a run carries on with the version they started. Where the cost changed, it says what a run costs now. With an account, it says that the version also arrives in your account’s cloud |
+
+“Publish” makes the draft the next version, and the link stays the same. Issues stop it, as on
+the first share. The editor’s top bar and the wizard’s card on the start page say where it runs:
+
+| It says | Means |
+|---|---|
+| “Not published yet” in the editor, “Draft” on the card | Only you can run it, as a test. Sharing it publishes it |
+| “Live · version 3” in the editor, “Live” on the card | The link runs this version. With a cloud icon, it runs on engenty.ai for everyone with the link |
+| “Live · 1 note” | It runs in the cloud, but one step does less there (see “Share”) |
+| “Local” | It is published on your computer without an account. The link only answers on this computer, while engenty wizards is running |
+| “On its way to the cloud” | The version hasn’t arrived on engenty.ai yet. The studio tries again by itself |
+| “Not in the cloud” | engenty.ai doesn’t run this version. “Share” says why and what helps |
+
+On a card, “Link” copies the address others can open, and the arrow opens it. A wizard that
+runs only on this computer has no address for others. Its “Link” says so and explains how an
+account gives it one, and the arrow opens it here.
+
+The ⋯ menu on a card and in the editor has “Duplicate”, “Export as a wizard file (.wizard)” and
+“Delete”.
+
+## Share
+
+“Share” says who may open the wizard and how others reach it, and it copies the link.
+
+| Part | Does |
+|---|---|
+| Access | With “Anyone with the link”, anyone can open and fill it in, up to the runs a day set under “Settings”. “Only you” switches the link off: everyone else sees a notice, and you test in the studio |
+| How others reach it | The channels the wizard runs as (see below), grouped by kind: in the browser, on the phone, by message. A browser channel has its own link, and a message channel its keyword and number. Each row copies its own. “Change” lets you choose the channels, from the same list as for a new wizard |
+| QR code | One of the links as a QR code to download or print, and the wizard’s ID for the mobile app |
+| Website | The code for a website (see below). For WordPress, it offers the plugin, or the wizard as a package that runs without an account, with what it lacks there: see [WordPress](./wordpress.md#without-an-account) |
+| Copy link | The link people open. It opens the first browser channel, and the wizard offers the others on its first page |
+| Settings (the gear) | “Limit per day” (50 runs unless you change it, with what that costs at most), each message channel’s keyword, and “Create a new link”: the old link and its QR code stop working, in the cloud too |
+
+Where the draft has changes, the dialog says so at the top and leads to “Publish changes”.
+
+One visitor can start 6 runs an hour.
+
+### Channels
+
+A wizard can run page by page, as a chat, as a live conversation on top of the chat, or as a
+video call on a stage with the chat beside it. In a conversation or a call, the person talks,
+and the wizard talks back and sees the camera. For now, both need an OpenAI API key under
+Models. A plugin can add further ways, such as a kiosk page or a messenger.
+
+A wizard you start on the “New wizard” page runs step by step unless you choose more under “How
+should it run?”. A wizard without its own choice, such as one from a template or an import, has
+the step-by-step page and the chat switched on. You can change the channels later under “Change”
+in the share dialog.
+
+Where a channel can’t take a step, the step goes to the wizard’s page. The person gets a link for
+a photo, a signature or a sign-in, and comes back afterwards. If nobody can hand a step off (for
+example, one that takes minutes on a channel that can’t wait), the row shows “Not possible: …”
+under the channel’s name. A channel that still needs something says so in its row:
+
+| The row says | What you can do |
+|---|---|
+| “Not set up yet” | “Set up” opens the channel’s settings inside the dialog. “Back” returns to the rows |
+| “Waiting” | Nothing for now. The channel is waiting for something, for example a number that was requested |
+| “Not in your plan” | “See {plan}” or “See the plans” shows the plan that has it |
+
+The cards on the start page show the channels that are on as small icons, the link’s channel
+first. Once wizards with two or more statuses are in the space, a row of pills above the cards
+narrows them to one status: “Draft”, “Local”, “Live” or “Not in the cloud”.
+
+The link opens the first browser channel that is on. The others answer under their own address
+(`/steps`, `/chat`, `/talk` for live voice, `/video` for the video call) and are offered on the
+wizard’s first page, for example “Or: Chat”. An address that is switched off sends people to
+the link instead.
+
+### WhatsApp, SMS and calls
+
+On engenty.ai a wizard can also run in a WhatsApp chat, by text message and as a phone call,
+where the team’s plan includes them. These channels are not part of the open source engenty
+wizards. On your computer, you get them through your account in the cloud.
+
+When you switch one on for a wizard, its row in the share dialog shows the number and the
+**keyword**. Whoever sends the keyword to the number starts the wizard. “Link” copies a link that
+writes the message, and the QR code view draws it. You change the keyword under “Settings”.
+
+- **WhatsApp**: one field per message, buttons for up to three choices and a list for more. The
+  person sends a photo or a file in the chat, “send location” for a place, and a voice message
+  for a text field. A free message can go out within 24 hours of the person’s last one. A wizard
+  that finishes later reaches back with an approved template, or waits for the person’s next
+  message.
+- **SMS**: text only. Choices come as numbered lines, answered with the number, and a place as a
+  typed address. Long texts come as their gist, and every picture, document and the whole result
+  as links.
+- **Calls**: the speech model talks, as the chat’s live voice does. It asks for one field at a
+  time, reads out the choices and reads email addresses and numbers back. If several wizards are
+  on for calls, the call first asks which one.
+
+What a channel can’t take (a signature or a sign-in, and by text or phone also a photo or a
+file) arrives as a link to the wizard’s page. The conversation goes on once it has been filled in
+there. “stop” ends a run in a chat, and the keyword starts a new one.
+
+### Who can open the link
+
+engenty wizards on your computer only answers on `localhost`. The link works on that computer,
+not for anyone else. To let others run the wizard:
+
+| Way | How |
+|---|---|
+| The cloud | Sign in with an [account](./create-account.md). Every version that goes live (the first share, and each “Publish”) then also goes to engenty.ai. Its link there runs on the account’s credits, even while your computer is off |
+| Your own server | [Run engenty wizards on a server](./server.md) with a public https address |
+
+### In the cloud
+
+Once you sign in to an account under Settings → Account, every version that goes live also
+arrives on engenty.ai. Your avatar then carries a small cloud, and its menu says “Connected to
+engenty.ai” with your credits. The share dialog gives the wizard’s address at engenty.ai, which
+stays the same when you publish again. Where the cloud doesn’t run this version, the dialog says
+so at the top:
+
+| It shows | Means |
+|---|---|
+| “Version 3 doesn’t run in the cloud.” | Something the wizard needs is missing there. The list says what, and the version before keeps running |
+| “Send again” | The last version didn’t arrive, or the space changed. When engenty.ai was the problem, the studio tries again by itself and says when |
+
+Without an account, the dialog says that the wizard runs only on this computer (“Only on this
+computer” under “Access”). It greys out the ways others reach it and offers “Sign in” and “Create
+account”. “Website” still gives you the WordPress package.
+
+What goes to the cloud and what stays:
+
+| Goes to the cloud | Stays on your computer |
+|---|---|
+| The published version and its files | Drafts and the chat with the assistant |
+| The space’s name, what it says about itself, its colours, facts and logo | Runs and results on your computer |
+| The space’s own tables and pages | What the wizards keep: their lists and notes |
+| How the link is shared: on or off, runs a day, channels | Connected accounts, keys, the space’s knowledge and its connected systems |
+
+At engenty.ai/studio you see the space and its runs there. A small laptop icon marks the space,
+and a note says “You edit this space in engenty wizards on your computer.” The studio there
+doesn’t edit it. An account holds one space from one computer. On a new computer, the share
+dialog offers “Replace that space”, which removes the old computer’s wizards and their links from
+the cloud.
+
+When you delete a wizard here, its copy in the cloud is deleted too. When you switch its link
+off here, it is switched off there as well.
+
+### Embed in a website
+
+Under “Website”, the share dialog gives you code to paste into a page’s HTML. Where the wizard
+has both the step-by-step page and the chat on, you first choose what the website shows:
+
+| What does the website show? | Shows |
+|---|---|
+| Step-by-step wizard | The wizard page by page |
+| Chat | The wizard as a chat, 640 px high (`data-height` changes that) |
+
+| Where on the page? | Shows |
+|---|---|
+| In the page | The wizard in that place on the page, as tall as its content |
+| Behind a button | Step by step only: a button in that place that opens the wizard in a window over the page |
+| As a chat button | Chat only: the wizard’s engenty in the bottom right corner. The chat opens above it |
+| As a bubble | Step by step only: a round button at the bottom right of the page that opens the wizard in a window over the page. It is best put in the site’s footer |
+
+```html
+<script async src="https://example.com/embed.js" data-wizard="TOKEN"></script>
+<script async src="https://example.com/embed.js" data-wizard="TOKEN" data-mode="modal" data-label="Start"></script>
+<script async src="https://example.com/embed.js" data-wizard="TOKEN" data-runner="chat"></script>
+<script async src="https://example.com/embed.js" data-wizard="TOKEN" data-mode="popout"></script>
+<script async src="https://example.com/embed.js" data-wizard="TOKEN" data-mode="bubble" data-label="Questions?" data-text="A quote in 2 minutes"></script>
+```
+
+The code only works once the wizard is published and open to anyone with the link. A chat in the
+page that is switched off for the wizard shows the step-by-step page instead. The chat button
+always opens the chat.
+
+| Attribute | Does |
+|---|---|
+| `data-label` | The button’s words. Beside the chat button, a short label. For the bubble, its name for screen readers |
+| `data-text` | A short line beside the bubble |
+| `data-color` | The colour of the chat button and of the bubble |
+| `data-height` | The height of a chat in the page, in px |
+| `data-page` | The page a run is started on, kept with its result. Without it, the page’s own address is used |
+
+Your website’s own styles reach the button through the class `engenty-wizard-button`, the chat
+button through `engenty-wizard-launcher` and the bubble through `engenty-wizard-bubble`. A page
+shows only one bubble: a second bubble tag does nothing.
+
+On WordPress the plugin writes this code for you, and its results show the page: see
+[WordPress](./wordpress.md).
+
+## Results people share
+
+On the result page, a person can share what they got as a link. The result of a run over the
+wizard’s link, and the link to it, are deleted after 7 days. The person can withdraw the link
+earlier.
+
+## Move a wizard
+
+Export it as a wizard file (`.wizard`) from its ⋯ menu, and import it in another studio or in
+the WordPress plugin. See [Build a wizard](./build-a-wizard.md#take-it-with-you).

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

@@ -0,0 +1,67 @@
+---
+title: Troubleshooting
+description: What to do when a link no longer works, a client shows as not signed in, or an export fails.
+version: 0.5.0
+---
+
+`wizards doctor` checks engenty wizards on your computer and says what is wrong. Start there.
+
+## Starting and signing in
+
+| What you see | What to do |
+|---|---|
+| “This link is no longer valid. Run wizards open to get a new one.” | The link works once. `wizards open` gives this browser a new one |
+| “engenty wizards isn’t answering” | It has stopped or is restarting. `wizards status` says whether it is running; `wizards start` starts it |
+| `wizards`: command not found | Open a new terminal, or run `~/.local/bin/wizards` |
+| “This browser isn’t signed in” | The browser has no sign-in for engenty wizards on this computer, for example after you cleared cookies. Run `wizards open` |
+| “The studio runs at another address” | Open the address the page names, or set `APP_URL` in `~/.engenty/wizards/.env` to the address you open |
+| Port 24368 is taken | engenty wizards uses the next free port. To fix the port, set `API_PORT` in `~/.engenty/wizards/.env` |
+
+## Models
+
+| What you see | What to do |
+|---|---|
+| An AI client shows as not signed in | Sign it in on the setup page or under Settings → Models, or in your own terminal (`claude`, `codex login`). Then click “Check again” |
+| “Signed in with an API key from your shell, not the subscription.” | The client runs on that key, not on your subscription. “Sign in here” switches it |
+| “The test didn’t work” | The message names the reason. Check the key, or sign the client in again |
+| “Models are missing” in the editor | A step needs a model that isn’t set up here, often for video or audio. Add a key under Settings → Models |
+| A template says “Not set up here” | It is the same: the template needs a model that isn’t set up |
+| No Apple Intelligence in the setup or under Models | It needs a Mac with Apple silicon on macOS 26 or later. It is offered on your computer only, not on engenty.ai |
+| Apple Intelligence “switched off” or “Apple is still loading the model” | Switch it on under System Settings → Apple Intelligence & Siri, or wait until the Mac has the model. The studio checks again after a minute |
+| A step on Apple Intelligence fails because the text is too long | The model takes 4,096 tokens for prompt and answer together. Give the step the class High, or choose another model for its class under Settings → Models. See [Apple Intelligence](./models.md#apple-intelligence) |
+| A voice note the Mac writes down fails in Chrome or Firefox | Their recordings need ffmpeg on the Mac: install it, or set `FFMPEG_PATH` |
+
+## Running wizards
+
+| What you see | What to do |
+|---|---|
+| PDF or PNG export, or a step on a website, fails | `wizards doctor` names the browser engenty wizards uses. Install Chrome, Edge or Chromium (on a Mac also Brave), or set `CHROME_PATH` to one; see [Settings](./command-line.md#settings) |
+| A widget offers no video | Install ffmpeg, or set `FFMPEG_PATH` |
+| “This wizard isn’t available right now.” | The link is switched off, or the account the wizard runs on has no credits left. See [Test and share](./test-and-share.md) |
+| “This wizard has reached its limit for today. Try again tomorrow.” | The link’s runs for the day are used up; the day starts at midnight UTC. Raise “Limit per day” under Settings (the gear) in the share dialog |
+| “You’ve started a lot of runs just now. Try again in an hour.” | One visitor started more runs in an hour than the link allows (`LIMIT_VISITOR_RUNS_PER_HOUR`, see [Settings](./command-line.md#settings)) |
+| “This wizard doesn’t exist or was deleted.” | It is not published, or its link was replaced by a new one |
+| Others can’t open the link | engenty wizards on your computer answers on `localhost` only. See [who can open the link](./test-and-share.md#who-can-open-the-link) |
+| The chat has no phone button, or “Join” stays grey | A live conversation needs “Live voice” or “Video call” switched on for the wizard (see [Channels](./test-and-share.md#channels); your own test run always has it) and an OpenAI API key under Settings → Models |
+| The camera, microphone or location doesn’t work | Allow it in the browser’s site settings (the lock icon in the address bar) |
+| A connector says “not set up” | engenty wizards needs an OAuth client for it. See [Connectors](./connectors.md) |
+| A step stops at a plugin’s tool | That plugin is not installed here. See [Plugins](./plugins.md) |
+
+## Updating
+
+| What you see | What to do |
+|---|---|
+| “The update failed. Details are in logs/update.log.” | The reason is in `~/.engenty/wizards/logs/update.log`. Run `wizards update` in a terminal to see it as it happens |
+| A template says “Needs a newer version” | Update with `wizards update` |
+
+## Still stuck
+
+`wizards logs` shows the last lines engenty wizards printed, with keys and tokens taken out. Open
+an issue at [github.com/engenty/wizards](https://github.com/engenty/wizards/issues) with what
+`wizards doctor` prints and the lines that matter.
+
+If this computer is signed in to an [account](./models.md#account), `wizards report` sends the
+status, the model settings (never a key) and the last 500 log lines to engenty. It names the
+report’s ID: give that ID when you ask for help. Nothing is sent unless you run the command. If
+this computer isn’t signed in, the command tells you so: sign in under Settings → Account or with
+`wizards account sign-in`.

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

@@ -0,0 +1,121 @@
+---
+title: WordPress
+description: Put wizards on a WordPress site with the plugin “engenty wizards” – connect, read the site in, place a wizard, read results in the admin.
+version: 0.5.0
+---
+
+The plugin **engenty wizards** puts the wizards of an engenty.ai account on a WordPress site and
+shows what visitors left in the WordPress admin. The wizards run on engenty.ai: WordPress keeps
+the plugin’s settings and the connection, but no answers. On WordPress 7.0 a wizard can also run
+on the site itself, with the site’s own AI provider and no account ([below](#without-an-account)).
+
+| | |
+|---|---|
+| WordPress | 6.6 or newer; 7.0 or newer for wizards without an account |
+| PHP | 8.1 or newer, nothing else on the host |
+| Site address | https, so you can sign in to engenty.ai from the admin |
+| Account | Free or above on engenty.ai; Contacts and Appointments need Pro |
+
+## Install
+
+Download `engenty-wizards.zip`, either in the studio under Settings → Integrate → WordPress
+(“Download engenty-wizards.zip”) or from the
+[releases](https://github.com/engenty/engenty-wizards-wp-plugin/releases/latest). Upload it in
+WordPress under **Plugins → Add New → Upload Plugin** and activate it. The menu **engenty** then
+opens.
+
+## Connect
+
+On **engenty → Overview** you have two ways in:
+
+- **Create your own AI** offers a free account on engenty.ai: **Create a free account**.
+- **Sign in**, under “Already have an engenty account?”, uses an account you already have.
+
+engenty.ai asks you to allow the site access and sends you back. Your WordPress email address
+goes along as a suggestion. The site is then connected as you: **Settings → Connection** shows
+the account, team and plan, and **Disconnect** ends the connection and revokes the access.
+
+**By hand:** for your own engenty server, or where signing in through the browser doesn’t work,
+enter an **Address** and an **API key** under **Settings → Connect by hand**. On engenty.ai you
+create the key under Account. On your own server you create it under Settings → Integrate, with
+an app’s “Connect with the address and an API key” (see
+[AI apps](./ai-apps.md#an-app-on-another-computer)).
+
+The plugin connects to an account on engenty.ai, not to engenty wizards on your computer. If you
+build on your computer, sign in to your account there and publish your wizards. You then choose
+them in WordPress.
+
+## Set up
+
+After you connect, the overview walks you through three steps.
+
+| Step | What happens |
+|---|---|
+| Read the website | The plugin reads the site from inside WordPress: name, tagline, logo, the theme’s colours, email and phone from the imprint and contact pages, the shop’s address with WooCommerce, and the published pages as text. You untick what shouldn’t go. The rest fills in the space’s details where they are empty and goes into its [knowledge](./space.md#knowledge) as pages. engenty then reads the imprint and contact pages for the address, VAT ID, opening hours and who runs the business |
+| Create the first wizard | A template becomes a wizard and goes live in one click |
+| Put on the website | As a bubble on every page, on a new page (a draft with the wizard’s block, for you to publish), or placed by you (see below) |
+
+Reading the site and making wizards in WordPress needs Pro. On Free you build in
+[engenty wizards on your computer](./install.md) and publish to your account. The wizards then
+show up in WordPress.
+
+## Put a wizard on a page
+
+| Way | |
+|---|---|
+| Block **engenty Wizard** | Choose the wizard and how it shows: **In the text**, **Button + window** or **Bubble bottom right**, with a label, a line beside the bubble and a colour. With “In the text”, the editor shows a wizard from the account itself |
+| Shortcode | `[engenty_wizard id="ID" mode="modal" label="Start a request"]`. `id` is the wizard’s ID or the token of its link; `mode` is `inline`, `modal` or `bubble`; `text` and `color` work as in the block |
+| Elementor | The widget **engenty Wizard**, with the block’s choices |
+| PHP | `<?php engenty_wizard( 'ID', [ 'mode' => 'inline' ] ); ?>` in a theme template |
+| Bubble | **Settings → Bubble on every page**: one wizard at the bottom right of every page except the ones you leave out, with an optional line beside it and your colour |
+
+A wizard’s drawer under **Wizards** has the shortcode and the PHP line ready to copy. For a wizard
+from the account, each way writes the share dialog’s
+[website code](./test-and-share.md#embed-in-a-website) with the page’s address, so a result says
+which page it was started on.
+
+## Results, contacts, appointments
+
+| Page | Shows | Plan |
+|---|---|---|
+| Results | What visitors left: when, which wizard, the email address and first answers, the page. A result opens with all answers, what the wizard made and its downloads | every plan |
+| Contacts | The leads your wizards collected, with search and the wizard they came through | Pro, Team |
+| Appointments | Upcoming, past and cancelled bookings in the space’s calendar | Pro, Team |
+
+You set who sees these pages under **Settings → Access to results, contacts and appointments**.
+Administrators always see them, and editors do from the start. engenty.ai keeps a visitor’s
+result for 7 days.
+
+## Without an account
+
+A WordPress 7.0 site with its own AI provider (WordPress → **Settings → Connectors**: OpenAI,
+Anthropic, Google, or Ollama through its provider plugin) runs wizards by itself. It needs no
+account and no credits: the provider bills the site’s key. On **engenty → Overview**, **Create
+your own AI** offers the account first and, below it, **Local, with your own AI provider**.
+**Set up locally** then takes you through three steps: the provider (with a test), the wizards
+and the website.
+
+| | |
+|---|---|
+| Wizards | The templates that come with the plugin, chosen from the gallery, or a wizard file (`.wizard`) from a wizard’s share dialog in the studio (“Website” → “Without an account: as a package”). You take it in with **Import** on the **Wizards** page |
+| What runs | Pages and their fields; photos go to the provider where it takes images. AI steps, which can also read a web page or call a public API where the step names `web_fetch` or `http` (the site does that itself). Decisions, branches, reviews and views. Documents and dashboards as HTML. Results as Markdown, text, CSV or JSON, HTML as a page to print, and a PDF of a written text, made in the visitor’s browser. A document’s PDF comes from the browser’s print |
+| What doesn’t | Voice notes, sign-ins to connected accounts, choosing an appointment time, list fields, and a file a later step reads. Web search, the browser, code and image tools, connected systems (MCP servers) and plugin steps (Contacts, Appointments and the like). Widgets, films, and images, video and voice made by a model. Lists and the wizard’s memory. Word, Excel and other downloads |
+| The check | The share dialog’s package view and, in the plugin, the gallery, the **Wizards** page and the import say for each wizard whether it “Runs there as is”, “Runs with less” or “Needs an account”. They list what it lacks in the gallery’s words (“not set up”, “works without”). With less, a choice on a page that leads to something the site lacks is closed there (“Not available here right now”), and a format falls away. The import refuses only a wizard that needs an account. A wizard that needs a plugin only behind a choice runs with less, with that choice closed |
+| Knowledge | In the package view, **Take the knowledge along** puts the space’s pages into the package as files (up to 2 MB, each page up to 60,000 characters). It is a snapshot of the day it was packed. On the site, an AI step first gets the wizard’s own text files, then the pages that match the step best (its instructions and the answers so far), up to 60,000 characters in all |
+| From the account | On a connected site with a provider, a published wizard’s drawer offers **Run here**. Its published version comes over and runs on the site with the site’s provider, without credits, and its results stay in WordPress. **Run through engenty.ai** switches back, and **Reload** fetches the published version again |
+| Results | Kept in WordPress under **Results**, for 90 days unless **Keep results** says otherwise. Nothing goes to engenty.ai |
+| Limits | 6 runs an hour per visitor and 50 a day per wizard, plus a honeypot. 60 seconds per AI step, up to 600 for a slow local model (the setting also raises the Ollama provider plugin’s own limit) |
+
+The settings for all of this are under **Settings → Standalone wizards**: the limits, how long
+results are kept, whether photos go to the provider, and the switch that lets wizards read web
+pages and call public APIs. The visitor’s browser follows the wizard’s flow and draws every page.
+WordPress keeps the wizard’s prompts and the run, and asks the provider for each AI step through
+its AI Client. Both kinds can be on one site: under **Wizards**, the ones that run on the site
+are marked **Local**.
+
+## Privacy
+
+Visitors talk to engenty.ai directly from the frame the wizard runs in. Name engenty in your
+privacy statement: **Settings → Privacy** has a sentence to start from. Wizards that run on the
+site send the visitors’ answers to the site’s AI provider instead. For those, the settings give
+a sentence that names the provider.