conductor/docs/USER_GUIDE.md

User Guide

This guide explains how to build and use applications in Conductor. Server installation, TLS, backups, and upgrades belong in the Installation Guide and Operations Guide. Account, credential, and publication administration belong in the Administrator Guide.

Roles and entry points

Visitor	What they can do
Administrator	Author projects, manage stored credentials, test REST actions, inspect execution history, manage users, and publish applications.
User	Sign in, open restricted or public applications from the application catalog, and change their own password.
Anonymous visitor	Open public applications by URL.

There is no public registration page. An administrator creates accounts. Conductor ships with no default username or password.

On a brand-new installation, the first visitor sees Set up Conductor instead of the sign-in form. That one-time screen creates the initial administrator: enter a unique username, an optional display name and contact email, and a confirmed password of at least 12 characters. The new administrator is signed in automatically. If the screen is not present, setup has already been completed; ask an existing administrator for an account.

Sign in and change your password

Open the HTTPS URL supplied by your administrator and sign in with your username and password. After five failed attempts for the same username and client address within one minute, login is temporarily throttled.

Users can expand Change my password below the application catalog. The new password must contain at least 12 characters and differ from the current password. A successful change keeps the current browser signed in and revokes the user's other sessions.

Administrators reset passwords from Users. Profile fields are administrator-managed in this release.

Administrator workspace

Administrators see these areas in the sidebar:

• Visual Editor builds pages and components.
• JSON Editor edits the same canonical project document directly.
• Preview runs the current in-memory project without saving runtime state.
• Actions & Bindings defines REST requests, stored-credential references, variables, and response mappings.
• Execution History shows recent sanitized REST executions.
• Publishing creates and updates runnable application snapshots.
• Users manages local accounts and sessions.

The Projects sidebar item is a placeholder in v1.0.0. Create, save, and load projects from the toolbar in Visual Editor or JSON Editor.

Build a first application

This small workflow creates a page with an input, a button, and a JSON result.

1. Open Visual Editor and select New.
2. Click the project name in the toolbar and give it a meaningful name.
3. In the page ribbon, set the page name and URL slug. Slugs use lowercase letters, numbers, and single hyphens, such as lookup.
4. Click Text Input, Button, and JSON Viewer in the component palette. Move or resize them on the canvas and give each a clear name in Selection, such as itemId, lookupButton, and resultViewer.
5. Open Actions & Bindings, expand REST Actions, and add an action. Choose the HTTP method, enter an absolute http or https endpoint, and use {{components.itemId.value}} in a supported request field when the endpoint needs the entered value.
6. Return to Visual Editor, select the button, and assign its click event to the action.
7. In Actions & Bindings, add a response binding from actions.<action-id>.response.body to components.resultViewer.value with trigger onSuccess.
8. Open Preview, enter a value, and click the button. Resolve any validation errors before continuing.
9. Select Save. Later edits use Update. The dot beside the project name means there are unsaved changes.
10. Ask an administrator to publish the saved project, or use Publishing if you are an administrator.

Use a harmless test API while learning. A Conductor action is a real server-side HTTP request.

Projects and unsaved changes

• New starts a new in-memory document.
• Save validates and creates the project in SQLite.
• Update validates and replaces the saved project.
• Load opens the project picker and loads a saved project.
• Clicking the project name in the toolbar renames it.

New and Load ask before discarding unsaved changes. Failed validation, saving, or loading leaves the last valid in-memory project intact. Preview includes current unsaved edits, but Preview activity never saves component values, responses, loading states, or errors.

Pages

Use the Visual Editor page ribbon to:

• add, duplicate, reorder, or delete pages;
• change the page name and URL slug;
• choose the default page;
• include or hide a page in automatic navigation; and
• assign page lifecycle actions.

A project always has at least one page. Page slugs must be unique. Hiding a page from navigation is not an access-control rule; anyone allowed to use the application can still open its direct URL.

Lifecycle actions behave as follows:

• onLoad runs on the first entry to the page during the current loaded session.
• If a page has no onLoad action, onEnter is the first-entry fallback.
• onEnter runs when the visitor returns to an already visited page.
• A full browser reload starts a new runtime session.

Components

Click a palette item to add it to the active page. Select a component to edit its name, position, size, visibility, type-specific properties, and basic appearance. Component names must be unique within a page. Project-wide unique names are recommended because request templates and binding paths identify components by name without a page qualifier.

Component	Main use
Label	Static text or a response-bound value.
Button	Run one REST action or navigate to another page when clicked.
Text Input	Collect one line of text for a request template.
Text Area	Collect or display multi-line text.
Checkbox	Collect or display a Boolean value.
Radio Group	Choose one configured option.
Dropdown	Choose one configured option; its option list can be populated by a response binding.
Table	Display configured or response-bound rows and expose the selected row at runtime.
JSON Viewer	Display formatted configured data or a REST response.
Status Panel	Display a value plus loading or error state.
Card	Display a titled block of content.

A button's guided click event runs an action or navigates; it does not do both. Deleting a referenced component displays the references that will be affected before confirmation.

REST actions and request values

REST actions are project-level and support GET, POST, PUT, PATCH, and DELETE. Each action defines:

• a stable action ID, name, and optional description;
• an absolute endpoint URL;
• an authentication type and compatible stored-secret reference when required;
• allowed headers, query parameters, and path substitutions; and
• an optional request body for methods that send one.

Use the editor's template suggestions to place runtime values in supported request fields:

{{components.itemId.value}}
{{variables.environment}}

Component values resolve from the page that invoked the action. Variables resolve by name. Treat a page-scoped variable as belonging only to its declared page; v1.0.0 does not yet enforce that ownership when resolving every runtime reference. Do not put passwords, tokens, or API keys into templates, headers, URLs, or project JSON; select a compatible stored secret instead.

Test Action runs the current action configuration through the backend proxy. It is useful for static requests. It does not inject interactive Preview values, so exercise template-driven requests from Preview.

Conductor blocks private and internal destinations unless the server operator has approved the exact origin. See Proxy Security for allowed headers, limits, redirects, and error behavior.

Stored credentials

Administrators create credentials in Actions & Bindings → Secrets. Supported shapes are Basic authentication, Bearer token, API-key header, and API-key query parameter.

Credential values are encrypted server-side and are never displayed again after submission. Projects store only opaque references. Replacing a value requires entering the new credential fields once; deleting a credential is blocked while a saved project action references it. More detail is in the Administrator Guide and Secrets Security Model.

Variables and response bindings

Variables have a type (string, number, boolean, object, or array), an optional default, and either global or page scope. Keep page-scoped variables on their declared page. Runtime values survive navigation within one loaded session and reset on full reload. They are not written back to the project document.

Response bindings run after a successful action and use ordinary dot-separated object paths, not JSONPath. Common sources are:

actions.<action-id>.response
actions.<action-id>.response.body
actions.<action-id>.response.body.<field>

Supported targets are:

Target	Compatible destination
components.<name>.value	Label, Text Area, Checkbox, Radio Group, JSON Viewer, or Status Panel
components.<name>.options	Dropdown; response must be an array of strings or string { "label": ..., "value": ... } objects
components.<name>.rows	Table; response must be an array of objects
variables.<name>	A declared runtime variable; the response value is assigned without coercion or a runtime type check

Use onSuccess for action-response bindings. Table selection uses components.<table-name>.selectedRow with onChange. The guided response-binding editor creates action-response bindings only; use the JSON Editor to add a Table-selection binding, and keep the Table name project-wide unique. Wildcards, filters, transforms, action chains, and arbitrary reactive graphs are not executed in v1.0.0.

Preview and validation

Preview is a read-only runtime view of the current canonical project. It can change ephemeral component and variable values while the Preview remains loaded, but it does not alter or save the authored defaults.

Validation summaries appear in the Visual Editor, Actions & Bindings, JSON Editor, and Preview. Errors block Apply, Save, and Publish. Warnings usually identify compatibility fields that remain readable but are not executed. Fix the named path or reference and validate again.

JSON Editor

The JSON Editor edits the same project document as the Visual Editor.

1. Make changes in the text area.
2. Select Apply to parse and validate them.
3. Return to the Visual Editor or Preview to inspect the result.
4. Select Save or Update to persist it.

Revert discards the JSON Editor's local draft and returns to the current in-memory project. Invalid JSON or semantic references never replace the last valid project. The canonical format is documented in Project Schema; prefer the visual editors for shapes they support.

Published applications

Publishing creates an immutable snapshot of a saved project:

• /apps/<app-slug> opens its default page.
• /apps/<app-slug>/<page-slug> opens a refreshable deep link.
• Public applications are available anonymously and may contain only anonymous REST actions.
• Restricted applications are available to any enabled signed-in user and may use stored credentials.

Saving the source project does not change the live snapshot. Use Republish to release the current saved version. Unpublish makes the URL unavailable without deleting the source project. See the Administrator Guide.

Troubleshooting and limitations

• If an action is blocked, read its safe error code and ask the server operator before requesting an internal-origin exception.
• If a deep link returns a proxy 404, the reverse proxy is not forwarding all paths to Conductor.
• If an old interface remains after an upgrade, perform a hard refresh.
• If Apply, Save, or Publish fails, correct the validation path shown in the interface; the last valid project remains intact.

See Troubleshooting for remedies and Known Limitations for the full v1.0.0 boundary.