@engenty/wizards-runtime 0.0.0-stage → 0.7.5

package/apps/runtime/dist/docs/dev/plugins/tools.md

@@ -0,0 +1,139 @@
+---
+title: Tools
+description: A tool an AI step can call – how to register it, how a wizard lists it, and what the model sees.
+version: 0.5.0
+---
+
+A tool is a function an AI step may call while it works. The model decides when, from the
+tool’s description.
+
+```ts
+server.registerTool({
+  name: "lookup",
+  title: "Contacts",
+  description:
+    "Looks a person up by email among the people who ran a wizard of this space before.",
+  inputSchema: z.object({ email: z.string().email() }),
+  execute: async ({ email }) => {
+    const [found] = await db()
+      .select()
+      .from(person)
+      .where(eq(person.email, email.toLowerCase()));
+    return found ? { known: true, name: found.name, lastWizard: found.wizard } : { known: false };
+  },
+});
+```
+
+| Field | |
+|---|---|
+| `name` | Lower case, digits and `_`, starting with a letter, at most 40 characters. Unique in the plugin, its [space tools](./space.md#a-block-for-every-ai-step) included |
+| `title` | What the editor calls it. Default: the name |
+| `description` | For the model: what the tool does and when to use it. The assistant reads it too when it builds a wizard |
+| `inputSchema` | A zod schema. `.describe()` on a field tells the model what to put there |
+| `execute(input, step)` | Returns what the model gets back: anything that can be JSON |
+
+## Names
+
+| Where | The tool is called |
+|---|---|
+| A step’s `tools` in a wizard | `contacts.lookup`: `<plugin id>.<tool name>` |
+| The model | `contacts_lookup`. A `-` in the plugin’s id becomes `_`: `run-log.recent` is `run_log_recent` |
+| The editor | Its `title` |
+
+## What `execute` knows
+
+The second argument is the step that calls the tool:
+
+| | |
+|---|---|
+| `step.runId`, `step.stepId` | The run and the step |
+| `step.tenantId` | The tenant |
+| `step.space` | `{ id, name }`: the space of the step’s wizard |
+| `step.project` | The same as `step.space`, by its older name |
+| `step.wizard` | `{ id, title }` |
+| `step.mode` | `"test"` for a test run from the studio, else `"live"`. Keep what a test run makes apart, such as a booking or a message to someone outside |
+| `step.signal` | Aborted when the run is cancelled. Pass it to `fetch` |
+| `step.emit(message)` | Tells the person what the step is doing right now |
+
+`server.getTenantDb()` inside `execute` is the database of the tenant the run belongs to.
+
+```ts
+execute: async ({ url }, step) => {
+  await step.emit("Asking the price list …");
+  const response = await fetch(url, { signal: step.signal });
+  return response.json();
+},
+```
+
+## Errors
+
+An error thrown in `execute` does not fail the step. The model gets `{ "error": "<message>" }`
+as the tool’s result, with the first 400 characters of the message, and can try again or work
+around it. Throw errors whose message says what was wrong with the input.
+
+## In a wizard
+
+A step lists the tool beside the built-in ones:
+
+```json
+"tools": ["web_search", "contacts.lookup"]
+```
+
+- The editor offers the tools of the tenant’s plugins in every AI step.
+- The assistant and the MCP authoring guide list them with their descriptions.
+- A draft with a step that lists a tool this tenant does not have shows an issue.
+- A run fails at the step that names such a tool, with “This step needs the tool “…”. The
+  plugin “…” isn’t installed here.” A wizard that uses a plugin’s tool runs only where that
+  plugin is installed. Keep that in mind before you publish a wizard to the cloud or export it.
+- The model has to call the tools. Apple Intelligence on a Mac calls none: a step whose class it
+  answers (Classifier, Standard) runs from its prompt alone. A step that needs the tool runs on
+  High, or a [call without a model](#called-without-a-model) does the job.
+
+### Called without a model
+
+Where a step only fetches data and hands it on unchanged, it can call the tool itself: no model
+picks the tool, and no model copies its answer.
+
+```json
+{
+  "id": "known",
+  "type": "agent",
+  "title": "Known contact",
+  "call": {
+    "tool": "contacts.lookup",
+    "input": { "email": "{{steps.ask.email}}" }
+  },
+  "output": {
+    "format": "json",
+    "fields": [
+      { "id": "known", "kind": "yesno" },
+      { "id": "name", "kind": "text" }
+    ]
+  }
+}
+```
+
+- The tool’s answer is the step’s json output, as it is. An answer that is not an object (a
+  list, a text) is kept as `{ "result": … }`. `output.fields` name the keys later steps read,
+  so the editor and the checks know them.
+- String inputs are templates. A template that fills in to a number or to `true`/`false` is
+  passed as one, and an empty one is left out. The input is checked against the tool’s schema.
+- What the tool throws, or an answer that is only `{ "error": … }`, is the step’s error. A tool
+  this tenant does not have fails the step too.
+- It costs no credits and answers as fast as the tool: the free times of a calendar in under a
+  second instead of half a minute.
+
+## While a step runs
+
+A step that is running keeps the tools it started with. When a plugin loads again, the change
+reaches the next step.
+
+## Write a good tool
+
+- One job per tool. Two small tools are easier for a model to choose between than one with a
+  `mode` field.
+- Describe the result as well as the input: “returns the working days as a number”.
+- Return data, not prose. The step writes the sentences.
+- Bound what it returns: a `limit` with a maximum, the newest 50 rows.
+- A tool that changes something outside says so in its description. There is no
+  ask-the-person-first for plugin tools: the step runs them without asking.

package/apps/runtime/dist/docs/dev/wizard-format.md

@@ -0,0 +1,125 @@
+---
+title: The wizard format
+description: A wizard as JSON and as a .wizard file, its JSON Schema, and checking it with wizards validate.
+version: 0.5.13
+---
+
+A wizard is one JSON document, its **definition**. The studio exports it as a `.wizard` file
+and imports one back. You can write either by hand or with a tool, check it in your editor
+against a JSON Schema, and check it completely with `wizards validate`.
+
+The code that defines the format and checks it is also under the
+[MIT licence](https://github.com/engenty/wizards/blob/main/packages/shared/LICENSE-MIT), so any
+tool may read and write wizards.
+
+## The definition
+
+```json
+{
+  "$schema": "https://engenty.ai/schema/v1/wizard.json",
+  "version": 1,
+  "title": "Create an invoice",
+  "description": "A finished invoice from a few details.",
+  "avatar": "round",
+  "lang": "en",
+  "steps": [ … ]
+}
+```
+
+`steps` run from top to bottom, and the last one is always a `result` step. The schema below
+lists the step types and their fields. The studio’s MCP tool `get_authoring_guide` explains them
+with a complete example.
+
+`lang` is the language the wizard speaks to people, as a two-letter code: `en`, `de`, `it`, `fr`
+and so on. The schema checks the shape of the code; `wizards validate` and the studio check that
+it names a real language. It sets the runner’s own words and how numbers and dates are written.
+Without it, the language is read from the wizard’s own words, and English is the default where
+they are not clearly German.
+
+`version` is the definition’s version. It changes only with a breaking change; the schemas of
+each version stay online in their own folder (`/schema/v1/`, `/schema/v2/`, …).
+
+## The `.wizard` file
+
+The file is a zip with two things in it:
+
+| Path | What it holds |
+|---|---|
+| `wizard.json` | The manifest: the definition, plus what the wizard needs from its space |
+| `files/…` | The wizard’s workspace: widget pages, templates, images. At most 200 files and 25 MB |
+| `files/knowledge/…` | Only when the export was asked for it: the space’s Knowledge pages as Markdown files, one per page, with its title in front. A website runs the wizard with them, without the space |
+
+```json
+{
+  "$schema": "https://engenty.ai/schema/v1/wizard-package.json",
+  "format": "engenty-wizard",
+  "version": 1,
+  "definition": { … },
+  "connectors": [{ "id": "billomat", "name": "Billomat", "domain": "billomat.com" }],
+  "mcpServers": [{ "id": "notion", "name": "Notion" }]
+}
+```
+
+`connectors` and `mcpServers` (the space’s connected systems) name what the wizard’s steps use
+from its space, without addresses or credentials. When the space you import into lacks one, the
+import says so.
+
+`knowledge` (`{ "pages": 12, "truncated": false }`) is there when the export took the space’s
+pages along. It says how many there are and whether the cap of about 2 MB left some out. The
+share dialog’s website package does this with “Take the knowledge along”.
+
+The import also takes a `wizard.json` on its own, or a definition on its own.
+The file’s media type is `application/vnd.engenty.wizard+zip`.
+
+## JSON Schema
+
+| For | Schema |
+|---|---|
+| A definition | [`https://engenty.ai/schema/v1/wizard.json`](https://engenty.ai/schema/v1/wizard.json) |
+| `wizard.json` in a package | [`https://engenty.ai/schema/v1/wizard-package.json`](https://engenty.ai/schema/v1/wizard-package.json) |
+
+Put the address under `"$schema"`, and editors such as VS Code complete keys and mark mistakes
+as you type. The studio’s export writes it into every `wizard.json`.
+
+The schemas are written from the code that reads wizards, so they match it. They are stricter
+in one way: a key the app does not know is an error. The app would drop such a key without a
+word.
+
+`wizards validate` checks what a JSON Schema cannot say: unique ids, steps and fields that refer
+to each other, templates that name answers that exist by then, and files in the workspace.
+
+## `wizards validate`
+
+```bash
+wizards validate invoice.wizard
+```
+
+It checks a wizard the way the studio’s import does, without a running studio and without an
+account. It takes any number of paths:
+
+| Path | Read as |
+|---|---|
+| `invoice.wizard` | A package |
+| `invoice/` or `invoice/wizard.json` | An unpacked package, its workspace under `invoice/files/` |
+| `invoice.json` | A definition on its own, or a `wizard.json` |
+
+```text
+✗ invoice.json 2 issues
+  The last step must be a result step.
+  "{{nope}}" refers to a field that is not asked before "g".
+```
+
+A wizard without issues gets a ✓ with its number of steps and files. `--json` prints the
+results as JSON. The exit code is `0` when every wizard is fine, `1` when one has issues and `2`
+when no path was given. That is enough for a check in CI:
+
+```bash
+npx wizards validate wizards/*.wizard
+```
+
+`npx wizards` installs engenty wizards into `~/.engenty/wizards` first, the first time. To check
+without an install, on Node.js 24.11 or newer, run the runtime from npm directly:
+`npx -p @engenty/wizards-runtime wizards validate wizards/*.wizard`.
+
+The import checks what belongs to the space, because only the space has it: its connectors and
+their actions, its connected systems (MCP servers) and its plugins’ tools.

package/apps/runtime/dist/docs/meta.json

@@ -0,0 +1,3 @@
+{
+  "pages": ["user", "dev"]
+}

package/apps/runtime/dist/docs/user/ai-apps.md

@@ -0,0 +1,112 @@
+---
+title: AI apps
+description: Run and build your wizards inside Claude Desktop, Cursor, Codex and other AI apps.
+version: 0.5.0
+---
+
+Settings → Integrate brings your wizards to where you work. engenty wizards is an MCP server: an
+AI app that adds it gets the tools to find, run and build wizards. Under “Share”, the same page
+has the WordPress plugin: see [WordPress](./wordpress.md).
+
+## What an app can do
+
+| In the chat | How |
+|---|---|
+| Run a wizard | “Start one of my engenty wizards.” The app asks the wizard’s questions, shows the review and hands over the downloads. Only published wizards run |
+| See the wizard itself | Apps that support MCP Apps show the wizard as a widget, page by page, and you answer there |
+| Build a wizard | “Use engenty wizards to build a wizard that reads amount, date and sender from an invoice PDF.” |
+| Change one | The app can create, change and publish wizards, find templates and connectors, and read and write a wizard’s files |
+
+- A run in a chat spends what any run of the wizard spends, and so does a test run.
+- What a chat can’t fill in (files, recordings, signatures, line items) you fill in on the run’s
+  page in the browser. The app gives you the link.
+- What an app writes shows up live in an open editor, marked with the app’s name (“Via …”).
+
+## Apps
+
+| App | Shows the wizard as a widget | Name for the command |
+|---|---|---|
+| Claude Desktop | yes | `claude-desktop` |
+| Claude Code | no, a run comes as text | `claude-code` |
+| Codex · ChatGPT app | no | `codex` |
+| Cursor | yes | `cursor` |
+| VS Code (Copilot) | yes | `vscode` |
+| Windsurf | no | `windsurf` |
+| Antigravity | no | `antigravity` |
+| Goose | yes | `goose` |
+| OpenClaw | no | `openclaw` |
+| LM Studio | no | `lm-studio` |
+| claude.ai, ChatGPT | yes | not on your computer, see below |
+
+## Add an app
+
+Settings → Integrate opens on the apps found on this computer. Each one has a button and says
+where it stands: “Works”, “Added, not tested yet” or “Not set up yet”. The dots in the menu say
+the same.
+
+Choose an app and follow its numbered steps:
+
+1. **Add to …** writes engenty wizards into the app’s settings. You need no key and no port: the
+   app starts engenty wizards itself.
+2. **Restart …**, or reload the app’s MCP servers. The page notices by itself when the app
+   checks in.
+3. **Try it in the chat**: “Which wizards do I have in engenty?”
+
+Once the app has used a tool, the page says “Works” and offers first sentences to try, with your
+own wizards’ names.
+
+From a terminal, this command does the same as step 1:
+
+```bash
+wizards connect
+```
+
+It adds every AI app found on this computer. To add only some apps, name them. To take an app
+out again, use `disconnect`:
+
+```bash
+wizards connect cursor codex
+wizards disconnect cursor
+```
+
+- The app’s settings file as it was before is kept beside it as `<file>.before-engenty`.
+- If Claude Desktop is running, the command asks you to quit it first: it writes its settings
+  from memory while it runs and would overwrite the change.
+- A settings file that isn’t plain JSON is left alone. The command prints the entry for you to
+  paste in yourself.
+
+## An app on another computer
+
+Under the steps, “Connect with the address and an API key” is for an app that runs elsewhere.
+The API key is shown once and goes straight into the command or settings entry the page shows.
+
+- Each API key signs in one app and has full rights. Treat it like a password.
+- The page lists the API keys with their last use. When you delete one, that app is signed out.
+
+## Apps on the web
+
+claude.ai and ChatGPT connect from their makers’ servers, and so do Claude Desktop’s
+connectors. They can’t reach your computer, so for them your wizards run on engenty.ai.
+
+- **In the studio on engenty.ai**, the page walks you through it: open the app’s connector
+  settings, enter the name and the address `https://engenty.ai/api/mcp`, click “Connect”, sign
+  in to engenty and choose “Allow”. You need no key.
+- **On your computer**, connect your engenty account first (“Connect to engenty.ai”). The wizards
+  you publish then go to engenty.ai, and claude.ai connects there. If you’d rather not use an
+  account, use Claude Desktop on this computer.
+
+The consent page names the team the access is for and the address it goes back to. An app that
+only named itself is marked “Name given by the app itself”.
+
+You disconnect an app at engenty.ai under Account → Connected apps. Its access ends within half
+a minute, even with a token it already holds.
+
+## The Claude Code plugin
+
+If engenty wizards has a public https address, Claude Code can also install a plugin. It adds
+the `/wizard` command and the skills to build and use wizards:
+
+```bash
+claude plugin marketplace add <your address>/api/claude-plugin/marketplace.json
+claude plugin install engenty-wizards@engenty
+```

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

@@ -0,0 +1,77 @@
+---
+title: Goose, the help assistant
+description: The chat at the bottom of every studio page. Goose knows engenty wizards, sees the page you are on, shows you where things are and fills in the space.
+version: 0.5.0
+---
+
+Goose is still being tried out and doesn’t show in every studio yet. Where it is switched on, it
+works as described here.
+
+Goose stands at the bottom of every page of the studio except the editor, which has a chat of its
+own: the assistant that builds your wizard. Goose runs on the High class of Text & reasoning:
+your subscription, your own API keys or your credits ([Models and account](./models.md)).
+
+| Ask it | Goose |
+|---|---|
+| How something works | Reads this guide (the version you installed) and links the page |
+| Where something is | Opens the page and points at the place |
+| About your account | Looks up your plan, credits and what you used. It never buys or upgrades anything |
+| About templates | Searches the templates and shows the ones it recommends as cards under its answer. A card opens the template, and you start a wizard from it there |
+| About your wizards | Looks at their runs, the failed ones too |
+| About models | Says which models are set up here, and what is missing |
+| To fill in the space | Reads a website or your files ([Space](./space.md#have-it-filled-in)) |
+
+Goose sees the page you write from: where you are, what is open and what the page shows. It may
+put a value into a field for you; you check it and save. It doesn’t click buttons.
+
+## Where it stands
+
+| | |
+|---|---|
+| At the bottom | The default. Click the field, and the chat rises above it |
+| Closed | ✕ in the header closes it to “Ask Goose” at the lower right. A click opens the chat where it last stood. On Data and Results it starts there |
+| Sidebar | Beside the page, in a window 1,520 pixels wide or more |
+
+The buttons in the chat’s header (“As a sidebar”, “Dock at the bottom”) switch between them. The
+studio remembers your choice.
+
+At the bottom, you can move the chat out of the way of what it covers: drag it by its grip, or by
+Goose sitting on top of it. It stays where you put it. Near the bottom it snaps to the middle or
+the right. Near the right side, higher up, it becomes the sidebar, and the sidebar’s grip pulls it
+out again. A dashed outline shows where it will snap. The handle on top of the chat sets how tall
+the chat history is; a click on it folds the history away.
+
+## Writing while it works
+
+You can keep writing while Goose answers. What you send waits above the field:
+
+| | |
+|---|---|
+| Enter | Goose reads it before its next step. It keeps to what you asked before unless the new message changes it |
+| ⌘↩ (Ctrl+↩) | It goes out as the next question once the answer is done |
+| “Send now” | Stops Goose and sends it at once |
+
+While Goose answers and the field is empty, the stop button stands where “Send” does.
+
+## One chat
+
+You have one chat. It is the same on every page and in every space, after a reload and on another
+device. Nobody else in the team sees it.
+
+- **“New chat”** (the pen in the header, or the menu at the chat’s name) clears the chat at once
+  and summarises the old one in the background. Goose keeps the summaries of your last chats in
+  mind.
+- **“Earlier chats”** lists the closed ones, for you to read. Ask about something you discussed
+  before, and Goose searches them.
+
+## Live chat
+
+**“Talk”** stands where “Send” does while the field is empty. The chat becomes a call: you speak,
+a pause sends what you said, and Goose reads its answer aloud. Then it listens again. If you talk
+over it, it stops speaking.
+
+- Chrome and Safari turn your speech into text themselves. Other browsers record it, and your
+  model for voice notes writes it down.
+- Goose reads its answers with your computer’s voices, or with the speech model where one is set
+  up (the speaker button in the call).
+- Everything said stays in the chat as messages.

package/apps/runtime/dist/docs/user/build-a-wizard.md

@@ -0,0 +1,116 @@
+---
+title: Build a wizard
+description: Describe what the wizard should do, or start from a template. Then change it in the chat or step by step.
+version: 0.5.0
+---
+
+## Start one
+
+“New wizard” on the list of your wizards, or in the sidebar, opens the page “What should your
+wizard do?”. It gives you three ways in:
+
+| Way | How |
+|---|---|
+| Describe it | Write what the wizard should do in your own words and click “Build wizard” |
+| A template | Choose one under “Or start from a template”. Search, or narrow the list by industry, result and capability |
+| A wizard file | “Import a wizard file”, at the foot of the page, takes a `.wizard` file someone exported |
+
+A description that works says who enters what, what the wizard does with it, and what comes out:
+
+> Customers enter their product and audience. The wizard researches competitors and writes a
+> positioning briefing as a PDF.
+
+You can change everything afterwards in the chat.
+
+### Before you build
+
+- **How it runs.** “Runs as” above the text field says how people will reach the wizard: as a
+  “Step-by-step wizard” unless you choose otherwise. The + beside it asks “How should it run?”
+  and lists the other channels this studio offers, for example “Chat”, “Live voice” or “Video
+  call”. One channel always stays on. The assistant builds the wizard for what you chose.
+- **Files.** Attach examples, price lists or screenshots with the + in the text field, or paste
+  or drop them there. They go into the wizard’s files, and the assistant looks at them.
+- **Dictation.** The microphone button lets you speak instead of type.
+- **Similar wizards.** While you type, the page lists up to ten of your own wizards and templates
+  that come close. “Open” opens one of yours, and “Use” starts from a template. This way you
+  don’t build again what is already there.
+
+### Templates
+
+- A template shows how the wizard runs, how long a run takes, what it costs and what it needs
+  before you start from it with “Start with this template”.
+- “Not set up here” names a model that isn’t set up on this computer yet, for example for video.
+  Set it up under [Models and account](./models.md), or choose another template.
+- A template marked “Pro” needs plugins that come with Pro on engenty.ai.
+- A star keeps a template on this computer, so you can use it without a connection.
+- A wizard started from a template is your copy. Later changes to the template don’t touch it.
+
+## The editor
+
+| Part | What it is for |
+|---|---|
+| The diagram, left | The steps as a flow with their branches. Click a step to open it |
+| Chat | Say what should change. The assistant edits the flow and tells you what it did |
+| Steps | One step at a time: its texts, fields, tools and model class. Move it up or down, or delete it |
+| Files | Files the wizard uses on every run, like widget code, libraries or price lists. Upload your own or let the assistant write them |
+| Memory | What the wizard knows across all its runs: the notes that AI steps with the “Pages” tool read and add to, and the tables of its shared lists |
+| Runs | The test runs and live runs of this wizard |
+
+On a phone or a narrow window the panels sit in a sheet over the bottom of the diagram. Drag its handle to make it taller, or tap
+it to fold it away.
+
+A click on the wizard’s name in the top bar opens its own settings: its title, description and
+greeting, its avatar, and the language it speaks to people in. With “Automatic, from its texts”
+the wizard speaks the language its texts are written in.
+
+The ⋯ button in the top bar (“More”) duplicates the wizard, exports it, or deletes it. Only
+whoever manages the team can delete a wizard. The same menu is on the wizard’s card in the list.
+
+### In the chat
+
+- Write what should be different: “Ask for the delivery date on the first page”, “Add a review
+  before the PDF”.
+- Attach files the assistant should look at: an example document, a price list, a screenshot.
+- Dictate instead of typing with the microphone button.
+- If the connection drops, what was already built is saved. Send your message again.
+
+### Step by step
+
+Open a step from the diagram or under “Steps”. What you can set depends on its type: see
+[Steps](./steps.md).
+
+“Add step” on a step in the diagram, or under “Steps”, puts a new step after it. Say what it
+should do and choose its kind, or leave it to “AI chooses”. Then say when it runs: “Always”,
+“Only if…” a condition holds, or when “AI decides…”. “Create” lets the assistant build the step
+in the chat. “Insert empty” adds a blank step of the kind you choose, for you to fill in.
+
+## When the wizard needs fixes
+
+A draft may be incomplete while you work on it. Before you test or share, the editor lists what
+is missing, for example a step that uses an answer that is only asked later, or a tool that isn’t
+installed here. “Let the assistant fix it” hands that list to the chat.
+
+If a step needs a model that isn’t set up here, the editor names the step and the model, and
+“Set up models” takes you there. If every path of the wizard needs that model, the wizard can’t
+start. If only one branch needs it, choose another path when you test.
+
+## What makes a good wizard
+
+- Write for people who are not technical: use plain words, and phrase titles as questions.
+- Keep to few pages, one theme per page and at most five fields. Ask only what the result needs.
+- Put a review before anything expensive, such as video, and before the final result.
+- Let the phone do the typing: a photo instead of a description, the location instead of an
+  address form, a voice note instead of a long text.
+- Put money in a line-items field. The wizard works out net, VAT and total itself; a model never
+  does.
+- Facts from the web need a research step before the step that writes.
+
+## Take it with you
+
+“Export as a wizard file (.wizard)” in the wizard’s ⋯ menu downloads its steps and its files as
+one file. “Import a wizard file” on the “New wizard” page of any studio takes it in.
+
+The share dialog downloads a wizard file too, under “Website” → “Without an account: as a
+package”. It holds the published version, or the draft while there is none, for a WordPress site
+that runs it without an account. With “Take the knowledge along”, the space’s pages go with it
+as files. See [WordPress](./wordpress.md#without-an-account).

package/apps/runtime/dist/docs/user/command-line.md

@@ -0,0 +1,83 @@
+---
+title: Command line
+description: The wizards command – start, setup, status, update – and the settings file on your computer.
+version: 0.5.0
+---
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `wizards` | Shows what is running, and a menu. While it runs, you can open the studio, restart or stop it; while it doesn’t, “Start in the background” or “Start in this terminal”. Then “Update”, which restarts it into the new version, “Start at login”, “Connect AI apps”, “Account”, “Status”, “Setup”, “Uninstall” and “Help”. The first time, the setup runs first. It needs a terminal |
+| `wizards start` | Starts it and opens the studio. It runs in that terminal, and Ctrl-C stops it. The first time, the setup runs first |
+| `wizards studio` | Opens the studio in your browser. If it isn’t running, it starts in the background first |
+| `wizards setup` | Runs the guided setup again: your account, an AI client, the browser and ffmpeg, start at login, your AI apps. `--local` leaves the account out ([Local only](./local-only.md)) |
+| `wizards account` | Shows the account this computer is signed in to: who, which team, the credits. `sign-in` shows a link and a code and opens your browser; `sign-out` disconnects this computer |
+| `wizards open` | Signs this browser in to the running studio. `--print` only prints the link; it works once, within a minute |
+| `wizards status` | Shows what is installed and running, with the browser it uses for PDF, PNG and websites |
+| `wizards doctor` | Shows the status and checks for problems |
+| `wizards logs [n]` | Prints the last lines engenty wizards printed while running (100, or `n` up to 2000). Keys and tokens are taken out |
+| `wizards report` | Sends the status, the model settings (never a key) and the last 500 log lines to your [account](./models.md#account), so support can see what went wrong. Nothing is sent unless you run it. The command names the report’s ID. If this computer isn’t signed in, it tells you to sign in under Settings → Account or with `wizards account sign-in` |
+| `wizards stop` | Stops it, with any other copy of it still running in the background. Your data is kept. AI apps that use your wizards start it again when you use one there |
+| `wizards restart` | Stops it and starts it again; after an update, that is the new version. If it isn’t running, it starts in the background |
+| `wizards update` | Installs the latest version |
+| `wizards autostart on` / `off` | Starts it when you log in, or stops doing so. It is a LaunchAgent on macOS and a systemd user service on Linux |
+| `wizards connect [app …]` | Adds your wizards to your [AI apps](./ai-apps.md): every app found, or the ones you name |
+| `wizards disconnect [app …]` | Takes them out again |
+| `wizards mcp` | Runs the MCP server over stdio. AI apps start it; you don’t |
+| `wizards uninstall` | Takes engenty wizards off this computer. It shows what it will remove first and asks about your data on its own; your data is kept unless you choose to delete it. `--dry-run` only shows the plan, `--yes` asks nothing and keeps your data, `--yes --delete-data` deletes it too. See [Remove](./install.md#remove) |
+| `wizards validate <path …>` | Checks wizards without the studio: `.wizard` files, unpacked wizard files, or a wizard’s JSON. `--json` prints the problems as JSON. A space’s connectors and plugins are checked when you import it |
+
+| Option | What it does |
+|---|---|
+| `--yes`, `-y` | Asks nothing and installs nothing optional |
+| `--local` | Sets up without an account, so nothing leaves this computer ([Local only](./local-only.md)) |
+| `--client <name>` | Installs this AI client without asking: `codex`, `claude`, `antigravity`, `cursor` |
+| `--no-open` | Starts without opening the browser |
+| `--background`, `-s` | Starts it in the background (`--service` still works): detached from the terminal, and the command returns. `wizards stop` stops it, and its output goes to `logs/runtime.log` |
+| `--version`, `-v` | Prints the version |
+| `--help`, `-h` | Lists every command |
+
+When you start it in a terminal, it runs while that terminal is open, and Ctrl-C stops it. With
+`wizards start --background` it keeps running after the terminal closes. If it is already
+running, `wizards start` opens the running one instead of starting a second.
+
+## Where things are
+
+| Path | What it holds |
+|---|---|
+| `~/.engenty/wizards` | Everything engenty wizards installed. `ENGENTY_HOME` moves `~/.engenty` |
+| `~/.engenty/wizards/data` | Your wizards, results and files. See [Your data](./data.md) |
+| `~/.engenty/wizards/.env` | The settings file |
+| `~/.engenty/wizards/plugins` | [Plugins](./plugins.md) on this computer |
+| `~/.engenty/wizards/logs` | Logs: `install.log`, `update.log`, `runtime.log` when it runs in the background, `autostart.log` when a Mac starts it at login |
+| `~/.engenty/wizards/tools`, `runtime` | Its own Node.js, and engenty wizards itself |
+| `~/.engenty/wizards/bin/wizards` | The command; `~/.local/bin/wizards` links to it |
+
+## Settings
+
+You change most settings in the studio. The settings file `~/.engenty/wizards/.env` holds what
+the studio doesn’t: one `NAME=value` per line. Restart engenty wizards after a change.
+
+| Setting | What it does | Default |
+|---|---|---|
+| `APP_URL` | The address you open. Links and sign-ins use it | `http://localhost:24368` |
+| `API_PORT` | The port | `24368`; if it is taken, the next free one up to `24387` |
+| `CHROME_PATH` | The browser for PDF and PNG exports and steps on websites: Chrome, Edge, Chromium or Brave | The first one found: on a Mac Google Chrome, Microsoft Edge, Chromium or Brave in `/Applications` or `~/Applications`; on Linux `google-chrome`, `chromium`, `chromium-browser` or `microsoft-edge` on the PATH. `wizards status` names it |
+| `FFMPEG_PATH` | ffmpeg for MP4 videos | `ffmpeg` |
+| `OLLAMA_URL` | Where Ollama answers | `http://127.0.0.1:11434/v1` |
+| `PLUGINS_DIR` | Folders with plugins, comma-separated. If you set it, it replaces the default | `~/.engenty/wizards/plugins` |
+| `PLUGINS_WATCH` | With `0`, plugins no longer load again when their files change | `1` |
+| `GEOCODER_URL` | Finds the place of a location (street, town). If it is not set, a location is only coordinates, and no position leaves your computer | not set |
+| `LIMIT_DEFAULT_DAILY_RUNS` | How many runs a day a shared link allows, unless the wizard sets its own limit | `50` |
+| `LIMIT_VISITOR_RUNS_PER_HOUR` | How many runs one visitor can start in an hour | `6` |
+| `RESULT_TTL_DAYS` | How many days the result of a run over a wizard’s link is kept | `7` |
+| `STORE_TTL_DAYS` | How many days what a wizard keeps for a person stays when nobody uses it | `400` |
+
+The OAuth clients of the built-in connectors go here too: see [Connectors](./connectors.md).
+Every setting, with what it is for, is in
+[.env.example](https://github.com/engenty/wizards/blob/main/.env.example).
+
+The command passes engenty wizards only a short list of your terminal’s variables. A key your
+shell exports for another project doesn’t reach it: put it into the settings file, or enter it
+in the studio.