Kora

View saved version →

---
name: kora-cli
description: "Read when installing the Kora CLI (@kora-platform/cli), connecting a terminal or coding agent to Kora SaaS or a self-managed deployment, signing up or logging in, selecting an organization, using organization API keys for direct Platform HTTP API calls, or running kora commands non-interactively."
---

# Kora CLI

`kora` is the command-line client for Kora SaaS and reachable self-managed Kora
deployments. Use this skill when the user wants to manage Kora resources from a
terminal or needs direct Platform HTTP API access with organization API keys.
Installing or operating the deployment itself is the `kora-self-host` skill,
not this one.

Establish the target before giving setup instructions:

- **Kora SaaS** — use the CLI default, `https://kora-eu.raw-labs.com`; do not
  ask the user for a URL. SaaS onboarding provisions the user's organization
  and production environment. Do not run the self-managed installer, use
  `koractl`, or create another organization as part of first-time setup.
- **Self-managed Kora** — the user or operator supplies the deployment URL. If
  the deployment does not exist yet, route installation to `kora-self-host`.
- **Unknown** — use Kora SaaS by default. Ask for a URL only when the user says
  they operate or need to connect to a self-managed deployment.

## Install

```sh
npm install -g @kora-platform/cli
kora --help
```

Requires Node.js >=24.0.0.

## Point The CLI At Kora

Login base URL resolution order, first match wins:

1. `--base-url` flag on `kora auth login` / `kora auth signup`
2. `KORA_BASE_URL` environment variable
3. nearest `.kora/cli.toml` walking up from the working directory
4. `~/.config/kora/config.toml` (respects `XDG_CONFIG_HOME`)
5. Kora SaaS at `https://kora-eu.raw-labs.com`

After login the base URL is stored in the session, so subsequent commands
need no flag. The SaaS default is not written as a config override. Self-managed
local-mode installs serve `http://localhost:3000`. `kora auth signup` remains a
local-account command for self-managed deployments and prompts for a deployment
URL when no override is configured.

## Authentication

`kora auth login` has two flows:

- **Device approval (the SaaS and agent path).** `kora auth login` automatically
  uses browser device approval for the Kora SaaS default, OIDC-only deployments,
  and non-interactive shells such as coding-agent shell tools. `--device` forces
  it for any other configured deployment. The command prints a verification URL
  and confirmation code, then waits:

  ```sh
  kora auth login --base-url http://localhost:3000 --device
  ```

  The user opens `<base-url>/device?code=XXXX-XXXX`, signs in in the browser if
  needed, confirms the code matches the terminal, and approves. In OIDC-only
  deployments, the web login route continues directly to the configured
  identity-provider flow. The CLI then stores the session and the command
  completes on its own. Codes expire after 15 minutes; a denied or expired
  approval fails the command with a clear error. This flow also works on
  OIDC/SSO-only deployments, because authentication happens in the browser.

- **Interactive email/password.** For explicitly configured local or hybrid
  self-managed deployments, plain `kora auth login` prompts for credentials.

When driving Kora SaaS as a coding agent, run `kora auth login`, surface the
printed URL and confirmation code to the user, and wait for the command to
finish. Pass `--base-url` or set `KORA_BASE_URL` only for self-managed Kora.
Confirm with `kora auth whoami`; the session is stored on disk and every later
`kora` command picks it up automatically.

Notes:

- A SaaS user who needs a new account can open
  `https://kora-eu.raw-labs.com/signup` in the same browser. A self-managed user
  can open `<base-url>/signup`. Complete signup, then reopen the device
  verification URL before its code expires. OIDC-only login goes directly to
  provider sign-in and does not promise a Kora-page signup link.
  `kora auth signup` (TTY-only, local email/password accounts) remains
  available for interactive use.
- On a local-mode self-managed install, the first signed-up user becomes
  platform admin. Server installs require SSO sign-in with one of the configured
  verified platform-admin bootstrap emails; unverified local-auth first-user
  bootstrap is limited to local single-machine evaluation.
- Kora SaaS users sign in through its browser/OIDC flow. Opening the SaaS
  `/signup` entry creates or resumes the hosted onboarding flow; the terminal
  does not create the account or initial organization.
- Fully headless CI with no human in the loop: inject a session via
  `KORA_SESSION_JSON_B64` — see `references/auth-and-sessions.md`.

## First SaaS Session, End To End

```sh
npm install -g @kora-platform/cli
kora auth login
kora auth whoami
kora status
```

The device command prints a browser URL and approval code. After approval,
`whoami` must show the organization provisioned by SaaS onboarding. Do not run
`kora org create` as part of SaaS setup; hosted users use the organization
created by onboarding and cannot create additional organizations.

## First Self-Managed Session, End To End

```sh
npm install -g @kora-platform/cli
kora auth login --base-url http://localhost:3000 --device
kora auth whoami
kora org list --json
kora status
```

Create an organization only when the authenticated self-managed deployment has
none for this user and the user explicitly wants one. `kora org create` sets a
new organization active. With access to multiple organizations, switch with
`kora org select <org>` and check with `kora org current` or
`kora auth whoami`.

## Working Conventions

- Append `--json` for machine-readable output. Discover the surface with
  `kora help --json` and `kora help <command-path> --json` instead of
  guessing flags.
- Most commands require an active organization.
- Destructive commands (`kora org delete`, `kora org reset`, and similar)
  prompt for confirmation unless `--yes` is passed.
- Organization API keys (`kora access api-keys create`) authenticate direct
  Platform API HTTP calls; they are not a CLI login method in this release.

## Which Reference To Read Next

- `references/auth-and-sessions.md` — session storage and permissions,
  non-interactive session injection, base-URL precedence detail, OIDC
  behavior, and API keys
- `references/http-api.md` — live OpenAPI discovery, API-key bearer auth,
  roles for common integration calls, and workflow start/run polling examples
- `references/command-map.md` — top-level command families and aliases

Referenced files: 5

View saved version →

---
name: kora-extension-builder
description: "Read when evaluating whether a target Kora deployment supports custom extension packages, creating or changing package source for self-managed Kora, validating or publishing that source, or routing a hosted Kora user to Kora-shipped built-in extensions."
---

# Kora Extension Builder

Use this skill when the user wants to create or change extension package source.
Extension packages are separate source bundles with their own lifecycle; they
are not workflow release-source files.

## Resolve The Target First

Determine the deployment mode before creating files or running package
commands. In Kora Chat, use the deployment mode stated in the operating
context. In an external agent, use an explicit user statement or ask whether
the target is Kora SaaS or self-managed Kora. Do not infer deployment mode from
a hostname.

- **Hosted Kora SaaS:** customer extension-package validation, publication,
  and direct installation are unavailable. Do not create a package that you
  imply can be validated or installed there, and do not run `extensions
  validate` merely to rediscover the restriction. Search installed or
  available Kora-shipped built-ins and route installation/setup to the
  Extensions Settings surface from `kora-product-ui`.
- **Self-managed Kora:** custom packages may be authored. The deployment still
  owns authorization and lifecycle checks; follow the build flow below.
- **Source explicitly intended for a separate self-managed deployment:** you
  may author it while the current chat is hosted, but state that it cannot be
  validated, published, or installed against the hosted organization. Stop
  after source-only checks unless the user supplies an eligible self-managed
  target.

When the extension targets a named third-party product, vendor, API, or public
service, research first. In Kora chat, use `web_search` and then `web_fetch` on
the most relevant official docs or product pages before choosing endpoints,
auth style, request fields, or response fields. Do not design provider-specific
behavior from model memory alone. If web research is unavailable, fails, or does
not find useful official sources, say that plainly and either ask for a docs URL
or continue only with clearly labeled assumptions and a generic adapter shape.

For an eligible self-managed target, an authoring agent can create and edit
extension package source in the workspace, validate it with `kora extensions
validate <path> --json`, and publish it with `kora extensions publish <path>
--json` when the user asks to publish.
Install, permission grants, removal, built-in installation, secrets,
OAuth/callback setup, and extension settings UI are deployment operations, not
extension package source authoring.

## Mental Model

An extension package workspace contains:

```text
extension.yaml
src/**
skills/**
assets/**
README.md
```

`extensions publish` stores an immutable published package. Extension install,
grant, enable/disable, configuration, and removal are environment-scoped
Settings actions.

The manifest declares requested permission limits. Grants are install-owned
approval; do not hard-code approval into package source.

## Build Flow

After resolving an eligible self-managed target, follow this order:

1. Decide what the extension is for: static callable functions, static agent
   tools, dynamic agent tools, install settings, public callbacks, schedules,
   bundled runtime skills, hooks, or a combination of those surfaces. For named
   third-party systems, do the official-source web research above before
   drafting package source.
2. Create a package directory in the workspace, normally under
   `extensions/<package-name>/`.
3. Write `extension.yaml` with package metadata, metadata-only version,
   entrypoint, requested permissions, and timeout limits.
4. Write `src/index.ts` with a default registration function that imports
   `Type` from `@kora/extension-sdk` and registers the needed surfaces.
5. Add package-local skill files under `skills/<skill-name>/SKILL.md` only when
   the installed extension should provide bundled runtime skills.
6. Add package assets under `assets/**` when handlers or bundled skills need
   immutable package-local files.
7. Run `kora extensions validate extensions/<package-name> --json`.
8. Fix validation diagnostics until validation returns `ok: true`.
9. When the user wants an installable package, run
   `kora extensions publish extensions/<package-name> --json`.
10. Tell the user the package is published but not installed yet, then provide
    the Settings route from `kora-product-ui` for installation and setup.

Do not skip from invalid source to install. `extensions publish` runs package
validation again and only stores an immutable published package if the package
is valid.

## Authoring Commands

Use these package lifecycle commands while building package source:

- `kora extensions validate <package-dir> --json`
- `kora extensions publish <package-dir> --json`

Use installed-extension discovery only when package work needs to compare
against an already installed extension:

- `kora extensions search --environment <environment> --name "<wildcard>" --json`
- `kora extensions search --environment <environment> --description "<wildcard>" --json`
- `kora extensions get <extension-name> --environment <environment> --json`

Use progressive disclosure for installed extensions:

1. Search installed extensions by name, title, or description.
2. If the needed extension is absent, search available extensions with
   `kora extensions search --environment <environment> --scope available --name "<wildcard>" --json`
   or `--description "<wildcard>"`; use the returned `nextCommands.install`
   only when the user explicitly wants an install/deployment operation.
3. Once one installed extension is selected, search inside it:
   `kora extensions search <extension-name> --environment <environment> --kind function --description "<wildcard>" --json`.
   The `--kind` value can be `function`, `tool`, `skill`, `function-provider`,
   or `tool-provider`. Use `--name` for exact or wildcard names and
   `--description` for intent/topic search.
4. Fetch the exact contract only for the selected function/tool/skill:
   `kora extensions get <extension-name> --environment <environment> --function <name> --json`.

For a ready installed extension, use `kora extensions invoke <extension-name>
<function-name> --environment <environment> --input @input.json --yes --json`
only when the package task explicitly needs to compare or inspect current
installed behavior. Do not use it as package validation, install setup, or a
replacement for `kora extensions validate`.

After publish in the product chat surface, read `kora-product-ui` and route
installation/setup to its Extensions settings destination. `kora-product-ui`
owns exact Platform UI routes.

Do not mix package authoring with install/configuration changes. In product
chat, route install, grant, enable, disable, delete, and configure actions to
Settings. In an external terminal-agent context, use the full `kora` CLI only
when the user explicitly asks for those deployment operations and the CLI is
authenticated to the target deployment.

## Minimal Function Package

Use this shape when the extension adds a stable callable capability to an
installed environment, such as normalizing a record, generating a summary, or
wrapping a safe API call.

```text
extensions/lead-helper/
  extension.yaml
  src/index.ts
```

```yaml
apiVersion: kora/v1
kind: ExtensionPackage
metadata:
  name: lead-helper
  description: Lead utility functions for workflow service nodes.
spec:
  version: 0.1.0
  entrypoint: src/index.ts
```

```ts
import { Type, type ExtensionHost, type Static } from "@kora/extension-sdk";

const LeadInput = Type.Object(
  { company: Type.String({ minLength: 1 }) },
  { additionalProperties: false }
);
type LeadInput = Static<typeof LeadInput>;

export default function extension(kora: ExtensionHost) {
  kora.registerFunction({
    name: "summarizeLead",
    description: "Summarize a lead record for follow-up.",
    input: LeadInput,
    output: Type.Object({ summary: Type.String() }, { additionalProperties: false }),
    async run(input) {
      const lead = input as LeadInput;
      return { summary: `${lead.company} should be followed up.` };
    }
  });
}
```

Build and publish it with:

```sh
kora extensions validate extensions/lead-helper --json
kora extensions publish extensions/lead-helper --json
```

## Common Extension Shapes

- Static function package: registers `registerFunction` for workflow service
  nodes and agents to call after install.
- Agent tool package: registers `registerTool` when agents should see a
  concrete tool with a fixed schema.
- Dynamic function provider package: registers `registerFunctionProvider` when
  workflow-callable functions depend on install settings, secrets, storage, or
  an external catalog discovered at runtime.
- Dynamic tool provider package: registers `registerToolProvider` when agent
  tools depend on install settings, secrets, storage, or an external catalog
  discovered at runtime.
- Opposite-surface callable: set `exposeAsTool: true` on an individual function
  or function-provider result, or `exposeAsFunction: true` on an individual tool
  or tool-provider result. Both default to false; do not put these flags on the
  provider, manifest, install, Operation, or agent configuration.
- Event descriptor package: registers `registerEvent` when an installed
  extension wants workflow trigger resources to bind to an external event. The
  descriptor defines the event name, payload schema, optional selector schema,
  optional selector-summary redaction fields, and optional managed-provider
  metadata. Managed Composio built-ins use a permissive object payload schema
  because described provider payloads can differ from actual deliveries. The
  descriptor is metadata only; it does not create a callback URL, register a
  webhook handler, start a workflow, or make the extension aware of workflow
  definitions.
- Settings-backed connector: registers `registerSettingsView` plus functions to
  test credentials, save setup state, or open an external setup URL. Use
  `secrets` permission for credentials and keep setup in Settings. Call
  `kora.configureSetup({ required: true })` when setup must complete before
  workflow runtime use. Required setup stays blocked until a setup-safe settings
  function or callback completes setup and calls `ctx.setup.markReady()`.
  Disconnect/reset paths that invalidate shared external credentials must call
  `ctx.setup.markRequired()`; use `ctx.setup.markRequired({ scope: "artifact" })`
  only when invalidation is specific to the current package artifact.
- Callback connector: registers `registerCallback` when an external service
  must call Kora back. Use `callbacks` permission and callback helpers for URLs,
  state, metadata, and HMAC verification. Mark only callbacks that are part of
  required setup as `setup: true`; normal webhook/action callbacks should not be
  setup-safe.
- Scheduled extension: registers `registerSchedule` for recurring extension
  work. Use `schedules` permission and do not start unmanaged background loops.
- Skill package: registers `registerSkill` and includes
  `skills/<root>/SKILL.md` when the installed extension should provide bundled
  runtime skills.

## Validation Summary

`kora extensions validate <path> --json` is the package preflight. It checks:

- package file safety and size limits, manifest shape, and entrypoint existence;
- SDK-typed TypeScript source and registration loading through the trusted
  runtime;
- registration schema shape and cross-references, registered skill files, static
  `outputPersistence` values, registered handler presence, and Ajv-compiled JSON
  Schemas;
- settings-view render output, using in-memory storage, missing secret metadata,
  fake callback metadata, null Cloud context, and blocked network fetch. Render
  handlers must show an unconfigured setup state without contacting external APIs.

Dynamic function and tool providers are validated for registration shape at
package validation time. Their runtime `list` output is validated when Platform
needs to populate a missing provider-owned capability surface in the install
registration snapshot. Discovery is cache-first; empty provider `list` results
are rejected and not persisted.

`kora extensions publish <path> --json` runs the same package validation
before storing an immutable published package. Publish is the strong
server-side gate, not just a file upload. Use it only after validation succeeds
and the user wants a package they can install.

Package validation proves the extension package loads and registers valid
metadata and that registered settings views return valid declarative JSON. It
does not prove every external API path, credential, OAuth callback, or dynamic
provider tool succeeds at runtime. Test external behavior through Settings,
callbacks, capability discovery after setup, and extension-backed workflow-node
tests after install.

`kora test node <workflow-name> <node-id> --workspace <dir> --input @input.json --json`
validates and executes workflow service-node code after an extension is
installed and a service node is bound to an operation that uses it. It does not
validate raw extension package source by itself.

## Authoring Rules

- Keep package source outside workflow release source.
- Validate before publishing.
- Publish before the user installs through Settings.
- Ask the user to review and grant only permissions within the package-declared
  limits in Settings.
- For settings views, define shared button constants and pass them both in
  static `registerSettingsView({ submit, buttons })` metadata and in the
  declarative JSON returned from `render`.
- Use settings view `description`, short `blocks`, field `description`, and
  text/textarea `placeholder` values for setup guidance. Keep labels short and
  mark required fields with `required: true` instead of writing "required" into
  the label.
- Do not call external APIs from settings view render handlers. Use render for
  local setup/status display, and use settings functions/buttons for external
  test, save, OAuth, or provider actions.
- Treat Platform setup lifecycle separately from provider-specific status text.
  Settings views may render "pending", "connected", or provider errors, but
  durable workflow readiness is changed only with `ctx.setup.markReady()` and
  `ctx.setup.markRequired()` from successful handlers. `ctx.setup.markRequired()`
  defaults to install-wide invalidation for shared external credentials.
- Browser callback completion only tells the Settings panel to refresh; it does
  not make setup ready unless the callback handler itself calls
  `ctx.setup.markReady()` after verifying the provider state.
- Treat `ctx.actor` as optional. Callback, schedule, lifecycle, and runtime
  hook handlers must be able to run without a user actor, and storage/secrets
  writes are attributed by the host rather than by extension-supplied user ids.
- Use `outputPersistence: "ephemeral"` for bearer-value outputs only.
- Use operation runtime SDK bindings when workflow service scripts need to call
  installed extension functions.

## Which Reference To Read Next

- `references/manifest-and-entrypoint.md` — manifest, entrypoint, lifecycle
  hooks, domain hooks, registrations, and ephemeral output rules
- `references/functions-and-tools.md` — static functions, static tools, dynamic
  tool providers, provider result schemas, refresh behavior, and collision rules
- `references/settings-callbacks-schedules.md` — bundled runtime skills,
  settings views, form fields, buttons, callbacks, OAuth-style state, HMAC,
  schedules, and human-task notifications
- `references/extension-context.md` — handler context, actor shape, storage,
  secrets, callbacks, locks, schedules, events, audit, same-install function
  invocation, and extension internal isolation

Referenced files: 6

View saved version →

---
name: kora-onboarding-guide
description: "Read when a user asks what Kora is, how Kora works, how to get started, what the main product concepts mean, why Kora exists, or when a first-time chat onboarding prompt asks for an intro. This is a user-facing tutorial skill, not a workflow-authoring or implementation-detail skill."
---

# Kora Onboarding Guide

Use this skill to explain Kora to a first-time builder in product-facing
language. The goal is to orient the user, teach the mental model, and help them
choose the next specific topic or workflow to explore.

Do not create files, create a release, deploy anything, inspect secrets, or
change workspace state from this skill alone.

When the user asks how to start using Kora, distinguish the two product entry
paths before giving commands:

- Kora SaaS users open `https://kora-eu.raw-labs.com/signup` or run
  `kora auth login`; the CLI uses that SaaS origin by default, and onboarding
  provisions their initial organization and production environment.
- Self-managed users install Kora on infrastructure they control through
  `kora-self-host`.

Do not present the self-managed bootstrap as a prerequisite for Kora SaaS. If
the intended deployment mode is unclear, use Kora SaaS; ask about the target
only when the user indicates they operate a self-managed deployment.

Route to a sibling skill when the conversation shifts:

- Building or editing workflow source -> `kora-workflow-builder`.
- Where to click in the product (routes, tabs, menus, settings sections,
  buttons) -> `kora-product-ui`, before naming any of them.
- Custom extension package work -> `kora-extension-builder`, which first checks
  whether the target is eligible; hosted Kora SaaS supports Kora-shipped
  built-ins instead of customer packages.

## Response Shape

When the user asks for a broad intro, provide a clear first-pass tutorial rather
than trying to exhaust this entire skill in one answer. Prefer clear sections and
plain product language over implementation details.

Default broad-intro shape:

1. Start with Kora's product goal.
2. Explain who Kora is for and the adoption path.
3. Cover the core concepts at overview depth.
4. Explain that workflow building and workflow improvement happen
   conversationally in chat.
5. Explain how change control, events, and governance keep the workflow
   inspectable and controlled.
6. End with follow-up questions the user can choose from.

Do not cover every concept in detail unless the user explicitly asks for a deep
dive. Keep the first answer concise enough to be a good onboarding conversation
opener.

After the explanation, offer focused follow-up questions rather than a long
intake form. Good defaults include:

- Want to walk through a concrete example workflow?
- Want to map an existing process into Kora?
- Want to understand orgs, people, agents, capabilities, and operations?
- Want to see how governance, events, releases, and deployments work?
- Want to build your first workflow in chat?

## Base Intro

Kora is a workflow operating system for important operational business
processes.

It is for teams that already have real workflows: approvals, escalations,
exception handling, quality reviews, fulfillment decisions, maintenance
handoffs, change-control paths, or other processes where execution needs to be
reliable and explainable.

Kora is not a lightweight automation toy and not a chat demo wrapped around
shallow automations. Its product promise is controlled execution. Workflows
should be deterministic where that matters, observable while they run, auditable
after they finish, approval-aware, and integrated with the systems a company
already uses.

A good Kora rollout usually starts with one important workflow. First mirror the
existing human process faithfully. Then make it executable, visible, and
auditable. Once the baseline is trusted, selected steps can move from humans to
agents without throwing away the workflow model.

## Who Kora Is For

Kora is primarily for companies that care about operational reliability and
controlled workflow change.

Typical users include:

- forward deployed engineers or technical implementation leads who understand a
  customer's operational process
- operators who need to see runs, tasks, failures, and approvals
- process owners who care about auditability, handoffs, and controlled change
- builders who refine workflows and gradually increase automation depth

Kora is a good fit when the workflow matters enough that the team needs to know
what changed, what ran, who approved, what failed, and which release was live.

## Adoption Path

Explain the adoption path as a sequence:

1. Mirror the existing workflow.
   Start with the real human process. Preserve the important steps, decisions,
   approvals, vetoes, and escalation paths.
2. Prove reliability.
   Make the workflow executable and observable. Use releases, deployments,
   activity, runs, tasks, and failure evidence to build trust.
3. Introduce agents selectively.
   Move one step at a time from human ownership to agent ownership only where it
   is useful and safe. Keep risky or approval-sensitive steps human-owned.
4. Expand.
   After one workflow works, add more workflows, integrations, and deeper
   automation.

The first successful workflow should usually be narrow enough to model and test
clearly, but important enough that observability, approvals, and auditability
matter.

## Core Concepts

Use this as the concept map. Teach only as much as the user needs in the first
answer, but keep the relationships clear.

| Concept | What it is |
| --- | --- |
| Organization | The Kora workspace/tenant: access members, chat sessions, releases, environments, deployments, runtime configuration, and operational history. |
| Access members | Real humans who log in to Kora. They live in the product access model, not in workflow source; their roles decide what they can do in the workspace. |
| Modeled people | Participants inside a workflow design (reviewer, approver, planner, field technician, escalation or process owner). Not login accounts. |
| Agents | AI assignees in the workflow model. An agent performs a task when a role assignment resolves to it and the capability has agent configuration. |
| Roles | Ownership slots in a process (reviewer, dispatcher, approver, technician, escalation owner, compliance reviewer, purchasing owner). A task references a role. |
| Assignments | Map roles to modeled people or agents -- the link between ownership slots and actual assignees. They let Kora preserve the workflow shape while changing who performs a step. |
| Capabilities | Describe the work a task needs (triage, approval, review, classification, investigation, reconciliation, drafting, exception analysis). Can include human guidance, agent instructions, and output rules. |
| Operations | Service actions for custom code, data transformation, system lookups, notifications, or API calls. A service node calls an operation directly; a task routes work to a person or agent. |
| Extensions | How Kora connects to external systems. Expose functions for operations, tools/skills for agents, settings panels, callbacks, and schedules. Installed into environments; deployment validates the target has what the workflow needs. |
| Workflows | The workflow graphs: starts, tasks, service nodes, decisions, gateways, waits, timers, receives, calls to other workflows, and ends. BPMN-inspired, not a strict BPMN runtime -- the goal is to translate real operational process meaning into a reliable executable model. |
| Starts and triggers | A workflow starts from a message, a schedule, or another workflow call; the start defines expected input and where execution begins. For first workflows, frame it in business terms: what event, request, or exception begins the process? |
| Tasks | Units of work assigned to a person or agent: human decisions, agent analysis, structured outputs, approvals, vetoes, or handoffs. Actions are the product surface for pending human tasks. |
| Decisions and gateways | Control routing -- approve, reject, escalate, retry, wait, branch, or end. Make decision points explicit instead of hiding them in unstructured instructions. |
| Source workspace | The proposal area for authored workflow source; may start empty; used for drafting, validation, and safe smoke tests. Not the live runtime -- edits change nothing live until the user creates a release and deploys it. |
| Releases | Immutable snapshots of authored source. Creating one freezes the proposal but makes nothing live. Use them to review, validate, compare, and preserve versions. |
| Environments | Deployment targets and runtime-configuration scopes (e.g. production, staging). Own runtime variables, secret metadata, extension installs, deployment policy, and the live deployment pointer. |
| Deployments | An attempt to apply a release to an environment. Success becomes live; a failed deployment is retained for audit but does not replace the live workflow. Return to an older workflow by deploying that older release again. |
| Runs | Workflow executions. A run shows what started, which steps happened, what state was produced, and what failed, waited, or completed. |
| Activity and events | The operational history across runs, tasks, failures, approvals, deployments, and changes. Part of the product value, not incidental logging. |

Key distinctions to keep clear when teaching:

- The organization (tenant) is not the modeled organization inside a workflow
  release.
- Access members (login accounts, managed in Settings) are not modeled people
  (defined inside a release).
- A task references both a role and a capability; the role assignment decides
  whether the human path or the agent path runs.
- Agents are not the default answer. Make it normal to start with human work,
  move selected steps to agents later, and move them back when needed.

## Conversational Workflow Building

Kora's primary authoring experience is conversational.

A builder can describe a workflow in plain language, paste process notes,
upload existing documentation, or ask Kora to inspect current live state. Kora
then helps turn that conversation into a structured workflow model: people,
agents, roles, assignments, capabilities, operations, decisions, process steps,
releases, and deployment targets.

Useful first messages include:

- "Turn this process into a Kora workflow."
- "Ask me the questions needed to build the first workflow."
- "I will paste process notes. Extract the roles, decisions, approvals, and
  open questions."
- "Start with a mock integration until the real system is connected."
- "Make this approval workflow visible and auditable before we automate it."

Kora should ask focused questions, usually one at a time. The main things to
learn are:

- what starts the workflow
- who participates
- what decisions exist
- what human approvals or vetoes matter
- which systems are involved
- what can fail
- what needs to be visible later
- what should be mocked until a real integration exists
- where the workflow should eventually run

Chat edits are proposals until the user explicitly asks to create a release.
A release freezes the proposal. A deployment makes a release live in an
environment. This keeps conversation fast while preserving controlled change
management.

## Conversational Improvement

Kora is not only for creating the first workflow. Users can improve workflows by
asking for changes in chat.

Examples:

- "Add an approval step before fulfillment."
- "Make this agent step human-owned for now."
- "Explain what changed since the last release."
- "What failed in production?"
- "Where are approvals getting stuck?"
- "Make this workflow safer before we deploy it."
- "Use a mock integration until the real system is connected."
- "Turn these process notes into a first workflow proposal."
- "Compare the live workflow to the release I just created."
- "Draft a safer rollout plan."

As with new workflows, improvements stay proposals until the user creates a
release and deploys it, so iteration stays fast without changing production
behavior.

## Governance, Auditability, And Operational Confidence

Kora is designed for workflows where change control matters.

Important governance surfaces:

- source proposals explain what Kora is drafting
- releases create immutable snapshots
- deployments record what was applied to each environment
- runs show what happened during execution
- tasks show pending human work and completion decisions
- activity and events provide operational history
- failures can be investigated instead of disappearing into logs
- approvals, vetoes, escalations, and agent handoffs stay visible

This model helps teams answer governance questions:

- What release was live in the environment?
- Who or what performed the work?
- Which decision path was taken?
- What input was available at the time?
- What failed, retried, waited, or escalated?
- What changed between the old workflow and the new one?
- Can we safely move this human step to an agent?
- Can we move it back if needed?

The point is not just to automate work. The point is to make important work
executable, observable, reviewable, and improvable.

## Humans And Agents

Explain human and agent ownership as a strength of the product.

Kora should not pressure the user into full autonomy on day one. The safer path
is:

1. model the workflow with human tasks and approvals
2. prove that the workflow runs reliably
3. identify one step where agent help is useful
4. give the agent bounded instructions, tools, and output expectations
5. keep approvals or escalation where risk remains
6. review activity and failures before expanding automation

The same workflow model can support human and agent work. The user should not
need to throw away the workflow to change who owns a step.

## Integrations And External Systems

Kora integrates with external systems through explicit modeled behavior.

Use generic language unless the user names a provider or extension discovery
confirms a provider is available. Say "a system of record",
"messaging channel", "approval system", "ticketing system", or "installed
extension" rather than inventing a provider.

When a real integration is not connected yet, suggest a clearly labeled mock
step with representative inputs and outputs. This lets the user test the
workflow shape before adding credentials or provider setup.

## Good First Use Cases

Good first Kora workflows are important, bounded, and approval-aware.

Examples:

- quality deviation or non-conformance handling
- maintenance or production escalation
- change-control approval
- procurement or fulfillment exception handling
- order exception routing
- field-service escalation
- support escalation with human approval
- compliance review handoff
- incident triage and escalation

The best first workflow usually has:

- a clear trigger
- a known process owner
- one or more human decisions
- a real operational consequence
- a visible success outcome
- enough pain that observability matters
- enough boundaries that it can be modeled safely

## What Not To Do In The Intro

- Do not describe Kora as generic no-code automation.
- Do not imply agents should own the whole workflow immediately.
- Do not blur source proposals, releases, deployments, and live runs.
- Do not say workspace files are already live.
- Do not expose implementation details unless the user asks.
- Do not claim current org state unless you inspected authoritative state.
- Do not name exact UI routes or buttons unless you have read
  `kora-product-ui`.

## Closing Question

End the broad intro with exactly one question:

> What would be most useful to focus on next: a concrete example workflow, the
> core concepts, importing an existing process, or building your first workflow
> in chat?

Referenced files: 2

View saved version →

---
name: kora-product-ui
description: "Use when routing a user to the Platform web UI or naming current app navigation, routes, settings sections, tabs, buttons, or product surfaces."
---

# Kora Product UI

Use this skill before naming a Kora web-app destination. Do not invent
settings, menus, tabs, buttons, or routes. If a surface is not listed here,
say you do not see a current web UI destination for it.

This skill owns product destinations and visible UI labels. It does not own
workflow source authoring, release/deployment command choreography, runtime IO
contracts, or extension package authoring.

## Link Rules

- Use relative Markdown links for Platform UI routes, such as
  `[release detail](/app/releases/<releaseId>)`.
- Do not format UI routes as code when they should be clickable.
- Include query parameters only when they select a real section, tab, focus, or
  environment.
- Route managed runtime artifact inspection and downloads through Platform UI
  surfaces. Do not point users to object-store buckets, storage keys, filesystem
  paths, or signed storage URLs.

## Shell

The app lives under `/app` and uses a left rail.

| Surface | Route | What it owns |
| --- | --- | --- |
| Home | `/app` | Workspace overview, recent health, deployments, runs, events, and links into Releases, Activity, and Environments. |
| Actions | `/app/inbox` | Human work queue and action completion. |
| Deployed workflows | `/app/processes` | Live workflows currently deployed to environments. |
| Releases | `/app/releases` | Immutable release artifacts, release inventory, source import, and deployment targets. |
| Environments | `/app/environments` | Environment inventory, detail, live deployment status, and environment lifecycle. |
| Activity | `/app/activity` | Runs, events, failures, and focused activity by person, agent, capability, or workflow. |
| Settings | `/app/settings?section=workspace` | Workspace, billing, AI usage, access, extensions, variables, secrets, models, artifacts, audit, utilization, plan, and reset sections. |

Workspace and account switching live at the bottom of the rail. Profile is
`/app/profile`, not a Settings section.

## Home

Use `/app` for broad workspace orientation. The page summarizes release and
deployment health, recent runs/events, workspace participants, and quick links
to release inventory, runtime activity, and deployment targets.

## Actions

| Surface | Route | Visible behavior |
| --- | --- | --- |
| Actions list | `/app/inbox` | Pending human actions with owner, capability, due/release, and context columns. |
| Action detail | `/app/tasks/:taskId` | Action overview, guidance, input data, schema-driven completion fields, history, `Open run`, and sometimes `Abort run`. |

Use Actions for human tasks awaiting input or completion. Use Activity for run
history and runtime events.

## Deployed Workflows

| Surface | Route | Visible behavior |
| --- | --- | --- |
| Deployed workflow list | `/app/processes` | Live deployed workflows by environment, release, last deploy time, last run, and run state. |
| Environment filter | `/app/processes?environment=<environmentKey>` | Narrows the deployed workflow table to one environment. |
| Live workflow detail | `/app/workflows/:name?environment=<environmentKey>&releaseId=<releaseId>` | Live workflow graph and release-backed workflow metadata. |

Workflow rows open the live workflow detail. The list and detail surfaces can
start a workflow when a live environment and release are available. Starting a
workflow opens a `Start workflow` dialog; successful starts navigate to
`/app/activity/runs/:runId` with workflow and environment focus.

## Releases

Releases are top-level. They are not under Deployed workflows or Settings.
Creating a release produces an immutable artifact from source. Deploying that
release to an environment is a separate action.

| Surface | Route | Visible behavior |
| --- | --- | --- |
| Release list | `/app/releases` | Release revisions, creation metadata, validation/readiness status, action menu, and source import. |
| Release detail | `/app/releases/:releaseId` | Defaults to Workflows. The left rail switches to release sections. |
| Release workflow detail | `/app/releases/:releaseId?section=workflows&workflow=<workflowName>` | Release workflow graph, source files, assets, and `Start workflow` when deployable context exists. |
| Release triggers | `/app/releases/:releaseId?section=triggers` | Immutable trigger bindings by extension, event, target message, and source path. |
| Release item detail | `/app/releases/:releaseId?section=<section>&item=<itemName>` | Detail for modeled people, agents, roles, assignments, capabilities, operations, or decisions. |
| Release deployments | `/app/releases/:releaseId?section=deployments` | Current deployments and deployment targets for the release. |

Release sections:

| Group | Sections |
| --- | --- |
| Process | Workflows, Triggers, Decisions, Operations |
| Participants | People, Agents |
| Responsibilities | Roles, Assignments, Capabilities |
| Runtime | Deployments |

The Triggers section is an inspection surface. It does not show raw selector,
provider payload, or provider provisioning configuration.

Visible release actions include `Import release`, `Create release from source`
inside the import dialog, opening a release detail, `Deploy to environment...`
from the release list, `Deploy this release...` or `Replace with this
release...` from release deployment targets, the deploy dialog's `Deploy to
environment` confirmation, starting a workflow from a release workflow, and
returning to an older release by deploying that release again.

## Environments

| Surface | Route | Visible behavior |
| --- | --- | --- |
| Environment list | `/app/environments` | Environment inventory and `Add environment`. |
| Environment detail | `/app/environments/:environmentKey` | Deployment history, links to releases and deployed workflows, undeploy controls, and per-deployment trigger route/stream health disclosed from the Triggers column. |

Visible actions include `Add environment`, `View`, `View workflows` when live,
`Rename`, `Archive`, and `Undeploy` from a live deployment row on the
environment detail page. Environment management is owner/admin gated.

Use Environments for environment lifecycle and live deployment status. Use
Settings -> `Environment variables` for runtime configuration values.

## Activity

| Surface | Route | Visible behavior |
| --- | --- | --- |
| Runs tab | `/app/activity` | Default tab. Workflow execution history by environment and release. |
| Events tab | `/app/activity?tab=all` | Runtime events. |
| People tab | `/app/activity?tab=people` | Focus activity for one modeled person. |
| Agents tab | `/app/activity?tab=agents` | Focus activity for one modeled agent. |
| Capabilities tab | `/app/activity?tab=capabilities` | Focus activity for one capability. |
| Workflows tab | `/app/activity?tab=workflows` | Focus activity for one workflow. |
| Failures tab | `/app/activity?tab=failures` | Failed runs and events needing review. |
| Activity run detail | `/app/activity/runs/:runId` | Execution graph, timeline, step details, run metadata, artifacts, and abort controls when allowed. |
| Run detail from Actions | `/app/runs/:runId` | Same run detail view. The action detail `Open run` button uses this path. |

Activity supports query filters such as `environment`, `range`, `focusType`,
`focusValue`, run status/search/sort/pagination filters, and task filters.
When linking, include only the filters needed to land the user in the right
context.

Run detail links back to release, release workflow, environment, and release
deployment surfaces. When a run started from a managed trigger and the trigger
label is known, `Started by` links to the release Triggers section. Use the run
detail page for runtime event timelines, execution graph inspection, step-level
details, and run artifacts.

## Settings

Settings is the owner for workspace and instance configuration. The canonical
general route is `/app/settings?section=workspace`.

### Canonical surface ownership

Route a user decision to exactly one product surface. A second page is valid
only when it serves a different user, answers a different operational question,
and has a distinct data contract. Similar data, a different permission, or an
operator-oriented label is not enough. Extend the canonical surface or delete
the duplicate; do not preserve overlapping pages, reports, or navigation as a
compromise.

| Group | Section | Route | What it owns |
| --- | --- | --- | --- |
| Workspace | General | `/app/settings?section=workspace` | Workspace/org display settings. |
| Workspace | Billing | `/app/settings?section=billing` | Hosted subscription status, member-seat usage, Checkout, and billing portal. Owner gated and absent outside hosted billing compositions. |
| Workspace | AI usage | `/app/settings?section=ai-usage` | Organization Chat and workflow-agent request/token consumption over a visible selectable time range, with surface totals, trend, and Kora catalog model breakdown. It does not show money or purchase controls. |
| Workspace | Members & access | `/app/settings?section=members` | Human members, invites, role changes, invite links, and removals. |
| Workspace | API keys | `/app/settings?section=api-keys` | Organization-scoped API credentials. New tokens are shown only once. |
| Workspace | Extensions | `/app/settings?section=extensions` | Installed extension packages, setup, management, permissions, schedules, and package install flows. |
| Workspace | Environment variables | `/app/settings?section=environment-variables` | Runtime variable inventory, create/edit/delete, and environment filters. |
| Workspace | Secrets | `/app/settings?section=secrets` | Org and environment-scoped secret storage, create/edit/delete, and environment filters. |
| Workspace | Models | `/app/settings?section=models` | Organization model access, optional compatible endpoints, and Chat/workflow defaults. API keys are write-only; compact badges identify defaults; removal is blocked when a live deployment depends on the model. |
| Workspace | Artifacts | `/app/settings?section=artifacts` | Runtime artifact inventory, upload, preview/detail, download, archive, restore, and purge. Owner/admin gated. |
| Workspace | Audit | `/app/settings?section=audit` | Audit/event review, filtering, pagination, and event detail. Owner/admin gated. |
| Instance | Utilization | `/app/settings?section=utilization` | Platform users, activity, sessions, active chat turns, runs in progress, and upgrade readiness. Platform-admin gated. |
| Instance | Plan | `/app/settings?section=license` | Plan/license status and account management link. Platform-admin gated. |
| Danger zone | Reset | `/app/settings?section=danger` | Owner-only `Reset organization workspace`. Clears release history, source storage, environment-scoped configuration, and workspaces. |
| Account | Profile | `/app/profile` | User account profile. Not an embedded Settings section. |

Settings actions:

- Members & access: `Invite`, role changes for non-owner members, `Remove`,
  `Copy link` for created invites, and `Cancel` for pending invites.
- API keys: `Create key`, `Copy`, and `Revoke`.
- Extensions: `Add extension`, `Refresh`, setup, manage, enable/disable,
  delete install, save permissions, run declared settings buttons, and open
  external action windows.
- Environment variables: `Add variable`, edit, delete, search/filter, and
  environment selection in create/edit dialogs.
- Secrets: `Add secret`, edit, delete, search/filter, and environment selection
  in create/edit dialogs.
- Models: `Add model`, set/edit/clear the Chat or workflow default, edit model
  access, and remove model. The first model becomes both defaults when neither
  has been chosen.
- Artifacts: upload, refresh, preview/detail, download, archive, restore,
  purge, and pagination.
- Audit: filtering by category/source/action/resource and selecting an event
  for detail.

Do not confuse access members with release-modeled people. Access members live
in Settings -> `Members & access`; modeled people live inside a release detail.

## Extension Setup Links

For any extension install, setup, connection, permission, schedule, or
management issue, use this exact Markdown link:

```md
[install and configure the extension](/app/settings?section=extensions)
```

## Artifact Surfaces

Use Platform UI routes for managed runtime artifacts:

- Run artifacts: `/app/activity/runs/:runId`, in the run detail artifact
  and step/detail surfaces.
- Task input artifacts: `/app/tasks/:taskId`, in the action detail input
  section.
- Organization artifact inventory: `/app/settings?section=artifacts`.

Start-workflow dialogs can upload supported `x-kora-type: file` inputs before
starting a run. Runtime artifact references in task input data render as
artifact cards. Link to the appropriate UI surface, not to raw object storage.

Referenced files: 2

View saved version →

---
name: kora-self-host
description: "Read when installing, configuring, operating, updating, or debugging a self-managed Kora Platform deployment: the install.sh bootstrap, koractl lifecycle commands (install, configure, start, stop, status, logs, doctor, update), install modes, and license activation."
---

# Kora Self-Host Operations

Use this skill when the user wants to install Kora on a machine they control,
or to operate an existing self-managed deployment. Using a running Kora from
the terminal (signup, login, organizations, workflows) is the `kora-cli`
skill, not this one.

Do not use this skill for Kora SaaS. A SaaS user signs in to an existing
regional Kora service and uses `kora-cli`; they do not run `install.sh`, manage
Docker Compose, activate a deployment license, or use `koractl`. If the target
mode is unclear, ask whether the user wants Kora SaaS or a deployment on
infrastructure they control before running any command.

## Mental Model

A self-managed Kora deployment is a Docker Compose bundle driven entirely by
the single `./koractl` command from the install directory. Operators do not
run `docker compose` directly except through the advanced escape hatch.

Supported platforms: macOS with Docker Desktop or a compatible Docker/Compose
setup, and Linux with Docker Engine plus the Docker Compose plugin. V1 does
not support native Windows, Dockerless runtimes, or bundled native
Postgres/Temporal/OpenSandbox. The installer fails with remediation
text when Docker or the Compose plugin is missing.

Install directory layout (bundle files plus runtime-generated files):

```text
kora-platform/
  koractl
  compose.yaml
  .env.example
  Caddyfile
  opensandbox.toml
  init-db.sql
  temporal/        # bundled schema and namespace setup
  LICENSE.md
  COPYRIGHT
  THIRD_PARTY_NOTICES.md
  .env             # generated configuration
  license/         # license material and deployment token
  state/           # chat workspaces, workflow artifacts
  .rendered/       # rendered OpenSandbox config
```

Do not call Docker cleanup commands directly; `koractl` owns lifecycle details
such as OpenSandbox cleanup and is the supported operator surface.

`license/license-deployment-token` is a bearer secret: keep it owner-readable
only and never log it, commit it, or send it to support. The signed
`license.json` is entitlement material, not a bearer secret.

In the kora-platform source repository, `pnpm dev:up` is the repo-development
path. Never use it for self-managed installs, and never point users at this
skill for repo development.

## Install

The public bootstrap downloads the latest release bundle, verifies its
checksum, extracts it to a temporary directory, and delegates target selection
and installation to the bundled `./koractl bootstrap-install`:

```sh
curl -fsSL https://kora.raw-labs.com/install.sh | bash
```

Online installs use an install session owned by Kora Accounts. Free, Pro,
Teams, and account-managed Enterprise/evaluation are the common online paths,
but the signed connectivity policy rather than the commercial plan label owns
the deployment's Cloud dependency. Without an install-session token, the
terminal prints a Kora Accounts URL; the human completes sign-in, plan
selection, and checkout in the browser while the terminal polls. When Kora
Accounts approves the session, the installer writes the license material and
starts Kora. When driving this as a coding agent: run the command, surface
the printed URL to the user, and wait — browser cancellation or expiry is
reported back to the terminal instead of hanging until the polling timeout.

Pick an install mode up front:

- **local** — one person, one machine. Defaults to
  `$HOME/.kora/kora-platform` and `http://localhost:3000`, plain HTTP, first
  signed-up user becomes platform admin.
- **server** — a VM or host reachable by a team. Defaults to
  `/opt/kora-platform`, HTTPS via Caddy, and requires a login allowlist.
  Server installs require verified SSO admin bootstrap; unverified local-auth
  first-user bootstrap is limited to local single-machine evaluation.
- **offline** — an air-gapped deployment whose license files arrive out of band
  and whose signed connectivity policy does not require Kora Accounts.

For non-interactive automation, pass flags to the bootstrap or set the
matching environment variables:

```sh
curl -fsSL https://kora.raw-labs.com/install.sh | bash -s -- --mode server --dir /opt/kora-platform
```

`--mode` answers the local/server/offline prompt; `--dir` answers the
install-directory prompt. `KORA_INSTALL_MODE` and `KORA_INSTALL_DIR` are the
environment equivalents. `KORA_NONINTERACTIVE=1` makes prompts use defaults
or provided environment values, but a useful fully non-interactive install
still needs explicit values for required server, model, access, and license
configuration.

For a server install without prompts, provide the mode, directory, public
hostname, model settings, verified SSO admin bootstrap config, login allowlist,
and either an install-session token or a plan to complete the printed browser
approval. Server mode requires OIDC or `local+oidc`; local email/password
first-user bootstrap is only for local single-machine evaluation.

```sh
export KORA_NONINTERACTIVE=1
export KORA_PUBLIC_DOMAIN=kora.example.com
export KORA_AUTH_MODE=oidc
export KORA_BOOTSTRAP_ADMIN_EMAILS=admin@example.com
export KORA_AUTH_ALLOWED_EMAILS=admin@example.com,@example.com
export KORA_OIDC_ISSUER=https://idp.example.com
export KORA_OIDC_CLIENT_ID=kora-platform
export KORA_OIDC_CLIENT_SECRET="$OIDC_CLIENT_SECRET"
export KORA_OIDC_REDIRECT_URI=https://kora.example.com/api/v1/auth/oidc/callback
export KORA_OIDC_SCOPES=openid,email,profile
export KORA_OIDC_PROVISIONING=allowlist_user
export KORA_CHAT_MODEL_INPUT=anthropic/claude-opus-4-6
export KORA_CHAT_MODEL_API_KEY_INPUT="$MODEL_PROVIDER_API_KEY"
# Optional: export KORA_CHAT_MODEL_BASE_URL_INPUT=https://gateway.example.com/v1
export KORA_AGENT_MODEL_INPUT=anthropic/claude-opus-4-6
export KORA_AGENT_MODEL_API_KEY_INPUT="$MODEL_PROVIDER_API_KEY"
# Optional: export KORA_AGENT_MODEL_BASE_URL_INPUT=https://gateway.example.com/v1

curl -fsSL https://kora.raw-labs.com/install.sh | \
  bash -s -- --mode server --dir /opt/kora-platform --install-session kora_ins_...
```

`KORA_CHAT_MODEL_INPUT` and `KORA_AGENT_MODEL_INPUT` must be supported
`koractl` Pi model choices. Use `anthropic/claude-opus-4-6` unless the
operator explicitly chooses another listed model. The chat model powers
user-facing conversations in the Kora web UI; the agent model powers Kora agent
execution work, such as coding tasks and automation. Operators can use the same
model and API key for both, or split them for different cost, latency, or
capability settings. `KORA_AGENT_MODEL` is the deployment fallback for
capabilities that omit `agentConfig.model`; organization owners can select the
workflow default and add access for other catalog models in Platform Settings >
Models. The matching deployment-fallback model API
keys are required before install or start can continue; get them from the
selected provider's account/API-key page, such as Anthropic, OpenAI, Google,
xAI, Groq, OpenRouter, Mistral, DeepSeek, Moonshot, or Z.ai.
Use the optional scoped base-URL inputs only for a compatible gateway or private
provider endpoint. Blank keeps the selected provider's native endpoint; never
embed credentials, query strings, or fragments in the URL.

Reruns into an existing install directory must state intent with
`--existing-action` or `KORA_EXISTING_INSTALL_ACTION` (one of `start`,
`update`, `configure`, `relink`, `reinstall`, `cancel`). Other bootstrap
flags are `--install-session <token>`, `--cloud-base-url <url>`, and
`--version <release>`. The version-specific `--apply-0.12-migration` flag is
reserved for the documented partial-0.12 recovery in the update reference.

Mode defaults, install sessions, manual bundle installs, and the required
configuration checklist are in `references/install.md`.

## Verify

After install or any lifecycle change:

```sh
./koractl status
./koractl doctor
```

`status` summarizes the stack as `stopped`, `starting`, `healthy`, or
`unhealthy`, then prints Compose service status and the basic HTTP health
result. `doctor` checks Docker, Compose, env placeholders, license files,
deployment-token permissions, disk/RAM capacity, and public URL consistency,
and prints remediation text instead of stack traces. A healthy local install
serves the web app at `http://localhost:3000`.

## Command Table

```sh
./koractl install
./koractl configure
./koractl configure models
./koractl configure access
./koractl configure license
./koractl start [--apply-0.12-migration]
./koractl stop
./koractl restart [service]
./koractl status
./koractl logs [service]
./koractl doctor
./koractl update [version] [--terminate-running] [--apply-0.12-migration]
./koractl license status
./koractl license activate
./koractl license install-file
./koractl version
```

Advanced support can use `./koractl compose <docker-compose-args...>`, but
prefer the named commands.

## Handoff To Product Use

Once `./koractl status` reports healthy, account and workspace work moves to the
web app at the deployment base URL or to the Kora CLI — read the `kora-cli`
skill. On a local-mode install, the first user to sign up becomes platform
admin. On server installs, sign in with SSO using one of the configured verified
platform-admin bootstrap emails.

## Which Reference To Read Next

- `references/install.md` — mode defaults, online install sessions, manual
  release installs, existing-install reruns, and the required configuration
  checklist
- `references/operate.md` — start/stop/restart semantics, status, logs,
  doctor, model and access configuration, and advanced files
- `references/update-and-license.md` — updates, forward recovery, license
  operations, and deployment-token hygiene

Referenced files: 5

View saved version →

---
name: kora-workflow-builder
description: "Read when creating or changing Kora workflow release source: org-model resources, capabilities, operations, decisions, workflows, service scripts, runtime SDK calls, managed artifacts, validation, release creation, or deployment follow-up. Not for extension package authoring, product UI route lookup, platform inspection, or exact schema lookup."
---

# Kora Workflow Builder

Use this skill when the user wants to create or change workflow release source:
add a role, add a person, introduce a capability, restructure resources, design
a workflow, create an operation, connect service code to an installed extension,
or make a workflow handle runtime inputs, outputs, and managed artifacts.

Describe planned and completed work in product terms -- what the workflow does --
not filenames, paths, YAML kinds, script languages, or runtime SDK wiring, unless
the user asks for implementation detail or you are explaining a failure.

Keep validation and repair loops internal: report the product behavior, the
checks that passed, and only the diagnostics that need user input.

Test results are authoritative. A passed source-validation phase does not
override a failed node execution. Do not infer that an execution-host,
provider, or configuration error is transient; describe it as retryable only
when the structured result explicitly says so. A failed, invalid, or skipped
node test blocks readiness, release creation, and deployment unless the user
explicitly accepts that exact failure after a clear warning.

Do not offer provider-specific destinations such as Slack or email unless the
user named that provider, extension discovery shows the resolved environment
supports it, or the user is explicitly planning missing extension setup. Before
discovery, use generic destinations: run output, a modeled human task, or an
installed extension if available.

This skill is a table of contents. Read the smallest reference that answers the
next question. For exact resource fields, use `kora schema get <resource>
--json`; the CLI schema wins over prose. Schema resource names are lowercase
registry names such as `process`, `operation`, `capability`, and `decision`,
not YAML `kind` values. The user-facing Workflow is authored with the source
schema name `process` and YAML `kind: Process`.

Fresh workflow source has a schema preflight. Before writing a new bundle from
an empty workspace, either start from the complete minimal service workflow in
`references/patterns-and-examples.md` or query the current schemas first:
`manifest`, `organization`, `assignments`, `operation`, and `process`. Query
`role`, `person`, `agent`, `capability`, and `decision` as needed before using
those resources. Use `kora schema get <schema-name> --json` once per schema.
The schema name for `kora.yaml` is `manifest`, not `project`.

## Core Mental Model

The chat source workspace is the source editing area for workflow source files. It may start empty.
The first durable server-side artifact is created with
`kora release create <dir> --json`. Release creation does not create a live
deployment. The target product path is release creation followed by explicit
environment deployment. A deployment is a full release snapshot for that
environment: deploying a release that contains only one new workflow removes any
other workflows from that environment's live set.

Default source resolution:

1. If the workspace already has source files, inspect and edit that workspace
   source.
2. For fresh creation with no existing workspace source, author in the chat
   workspace.
3. For read, add, or modify requests against existing product behavior or
   source, do not guess from an empty workspace. Resolve the intended
   environment from the user request first. If the user names `test`, `staging`,
   `production`, or another environment, use it. Otherwise inspect
   `kora environment list --json`. If exactly one environment exists, use it as
   the default resolved environment; if multiple environments exist, ask which
   environment before materializing release source.
4. For the resolved environment, inspect
   `kora deployment list --environment <environment> --json`.
5. If it has a live deployment, use that live deployment's release as the default
   source and write the frozen source into the workspace with
   `kora release source <release> --out <empty-temp-dir> --json`. Then copy the
   exported files into the chat workspace root before editing.
6. Do not keep edits under temporary folders such as `source/`, `src/`, or
   `project/`; edit workspace-root paths like `org/...`, `processes/...`, and
   `scripts/...` directly.
7. If it has no live deployment, say there is no live release to modify and
   continue only with fresh source or a user-named release.

For read-only inspection of already-created workflow or org-model facts, use
the CLI's release snapshot selectors instead of materializing source:
`--release <release>` for a named immutable release, or
`--environment <environment>` for the selected environment's current live
deployment release.

When adding to an environment that already has a live deployment, start from the
live release source. Before deploying, compare workflow lists; if the new
release drops existing workflows, stop and ask whether removal is intended.

Every workflow source bundle has seven layers you may touch:

1. who does the work: people, agents, roles, assignments
2. what work exists: capabilities and operations
3. how work flows: workflows
4. what external events enter the flow: trigger resources that target workflow messages
5. what external behavior exists: installed extensions, operations, and service scripts
6. what rules apply: decisions
7. what runtime assets support execution: templates, scripts, schemas, docs

Human and agent task nodes depend on this runtime chain:

`role -> capability -> assignment -> workflow task`

If any link is inconsistent, the workflow will not resolve at runtime.
Service nodes are different: they call an `Operation` and do not need roles,
capabilities, agents, or assignments unless the workflow also has human/agent
task nodes. Still create `org/assignments.yaml` for every fresh source bundle; use an
empty `spec.roles: {}` registry when the workflow has no human or agent tasks.

## Runtime Boundary

- The workspace is the proposal surface for authored source -- YAML resources,
  service scripts, templates, and source docs. It is not the live runtime; use
  it for source editing and smoke tests only.
- Extension package source uses the `kora-extension-builder` skill and the
  extension lifecycle, not workflow release source.
- Temporary files, generated outputs, and smoke-test artifacts may exist while
  authoring, but only files accepted by release creation become deployment
  entries.
- Files provided during a conversation are unclassified workspace/input files;
  use them as message context. Copy one into release source only when the user
  explicitly asks; upload it as a managed runtime artifact only when the user
  explicitly asks to use it as workflow/run input.
- `kora` is an authoring and inspection tool, not available inside live
  workflows, operations, scripts, or agent prompts. Do not put `kora` commands
  in workflow YAML, scripts, operations, or agent prompts.
- Service operation scripts run in a separate runtime sandbox with released
  files mounted read-only at `/workspace`. Package installs, node_modules,
  virtualenvs, caches, and build output created while authoring are scratch
  state unless the source bundle has an explicit deterministic packaging
  strategy.

## Environment Discipline

Resolve the intended environment once (see Core Mental Model). Use that same
environment for extension discovery, contract fetches, node tests, release
validation, deployment, and run commands. Do not discover an extension in one
environment and test, release, deploy, or run against another.

For extension-backed service work:

- Verify the selected extension is installed in the resolved environment and
  that `kora extensions get ... --json` reports `state: "ready"`.
- If it is `setup_required`, route the user to Settings setup before publishing
  or running workflow code. If it is `disabled`, tell the user it must be
  enabled. Use the returned `message` as the user-facing explanation.
- If a required provider-backed extension is not installed and ready, stop and
  tell the user exactly which extension/setup is missing. Do not write
  placeholder provider operations, do not substitute unauthenticated direct API
  calls, and do not publish a workflow you expect to fail unless the user
  explicitly asks to continue after that warning.
- To inspect current provider data before authoring, invoke one ready installed
  extension function (`kora extensions invoke <extension-name> <function-name>
  --environment <environment> --input @input.json --yes --json`) after fetching
  its exact schema. Do not create throwaway workflow source just to inspect
  provider data.

## Service Operation Rules

Script-backed service nodes invoke an `Operation`.

- Service scripts import `@kora/runtime-sdk` and use `getInput`,
  `extensions.invoke`, and `emitOutput` for operation input, installed
  extension functions, and stdout JSON. Cloud-backed providers are still
  installed extensions from the script perspective.
- For installed extension calls, normalize the extension response into the
  operation's own stdout shape; do not rely on optional extension fields being
  present or non-null.
- Registered extension function descriptions and schemas are the source of truth
  when authoring operations that call them.
- `paramBindings` shape operation stdin before the script runs.
- Runtime variables and org secrets are declared with `spec.bindings.env` and
  `spec.bindings.secrets`; names and injected env vars must not use the
  reserved `KORA_` prefix.
- Operation scripts can call functions exposed through
  `spec.bindings.extensions`, but they do not read extension storage or
  extension secrets directly.
- When `spec.script.parseStdoutAsJson` is true or omitted, stdout must contain
  exactly one valid JSON value. Log diagnostics to stderr.
- `resultMapping` maps emitted stdout into the service node's declared output.
  Without `resultMapping`, script stdout must be a JSON object that can shallow
  merge into workflow state.
- Optional `resultMapping` fields are skipped only when the source path is
  absent. A present `null` value is mapped and must validate.
- Managed artifact files are separate from stdout. Scripts read artifact inputs
  and write declared artifact outputs through `KORA_ARTIFACT_MANIFEST`
  `localPath` entries; do not persist manifest local paths into workflow state.

## Typical Project Layout

```text
kora.yaml
org/
  org.yaml
  roles/<name>.yaml
  people/<name>.yaml
  agents/<name>.yaml
  assignments.yaml
capabilities/
processes/
operations/
decisions/
triggers/
scripts/
templates/
```

Keep entity names in resource `metadata`, not inferred from filenames.

## Build Order

When creating source from scratch or deliberately restructuring it, prefer
this order so references resolve cleanly. Complete the fresh workflow source
schema preflight before writing the first file.

1. source manifest (`kora.yaml`) and organization (`org/org.yaml`)
2. `org/assignments.yaml` with `spec.roles: {}` for every new source bundle
3. roles, people, agents, and assignment entries only when human/agent tasks need them
4. capabilities
5. installed extensions, operations, and service scripts
6. decisions
7. workflows
8. triggers that bind installed extension events to exactly one workflow message
   start
9. optional templates and supporting docs

## Authoring Discipline

Before editing:

- Inspect the current workspace before assuming files exist.
- Check `kora.yaml` and the target area directly before scaffolding foundational
  files.
- `read` or `ls` the area you plan to change.
- `grep` for references before renaming or deleting anything.

While editing:

- When the user gives a clear intent but omits incidental details, draft a valid
  minimal workflow with reasonable names and a simple message/manual start
  instead of stopping for clarification.
- Keep changes small and scoped.
- Every capability must define at least one of `spec.humanConfig` or
  `spec.agentConfig`. For capability work a person can perform, include at least
  `humanConfig: {}` even when no optional human guidance fields are needed.
- For workflows, author the data contract first. Define `types:` and use only
  the node fields the schema supports.
- Author every workflow as a Process source document under `processes/`, with
  `kind: Process`. `kind: Workflow` and `workflows/` are not source aliases;
  Platform owns internal organization scope injection.
- Treat workflow state as an accumulated top-level object. Each typed node
  output shallow-merges into state.
- Use message starts or `receive` nodes for workflow-level message consumption.
  Use `triggers/*.yaml` only when an installed extension event should start a
  workflow through exactly one message start. Triggers do not resume `receive`
  nodes. A workflow invoked by `call` or
  `call.each` needs a callable manual start marked `internal: true`; call nodes
  name the child with `process`, not `workflow`.
- Use `task.each` or `call.each` for runtime collections.
- For agent output review, put `requiresOutputReview: true` on the producer
  capability and `agentOutputReview` on each ordinary producer `task`. Point it
  directly to an explicit human task; keep approve, reject, revise, apply, and
  escalation behavior in ordinary nodes and gateways. The producer object
  output type must set top-level `additionalProperties: false`. Read
  `references/workflow-flow-nodes.md` before authoring this pattern.
- Use ordinary `next` to a human task when review applies regardless of whether
  the producer is assigned to a person or an agent. Do not use output review as
  tool-call or side-effect authorization; put irreversible actions after an
  explicit human decision.
- Use `call.each` to a child workflow containing producer and review tasks when
  each collection item needs review. A review-required capability is invalid on
  `task.each`.
- For agent tasks that handle file content, use node-level `promptAttachments`
  on `task` / `task.each` for selected top-level file artifact input fields.
  Prefer an earlier extractor service node for PDFs, Office docs, HTML, ZIPs, or
  other binary/rich attachments; attach only the extracted text or image
  artifact to the agent prompt.
- Make operation `resultMapping` and the declared workflow service-node
  `output` type agree.
- Model expected absence explicitly. Optional means absent from the object, not
  `null`, unless the schema deliberately allows `null`.

After meaningful changes:

- There is no validation-only command for uncreated source. Do not invent `kora release
  create --dry-run`, `kora release validate-source`, or similar commands, and
  do not create a release merely to validate a source-only proposal. Inspect
  the touched files and references, run applicable targeted checks, and state
  that full source validation remains deferred until requested release
  creation.
- Run `kora test node <workflow-name> <node-id> --workspace <dir> --input @input.json --environment <environment> --json`
  for touched executable service nodes when you can supply meaningful node
  input.
  Use this before claiming artifact-producing nodes are verified; release
  creation and deployment do not prove artifact capture.
- If a node test ends without an exit code because it was cancelled or timed
  out, do not retry the same node with different workspace or input-path
  variants. Report that targeted check as unverified once.
- Use `kora release create <dir> --json` only when the user asks to create a
  release artifact from source. Then:
  1. Treat release-source or release-readiness diagnostics from that command as
     must-fix items before deployment.
  2. When it succeeds, tell the user the release was created, that it is not live
     yet, and route them with a Markdown link such as
     `[release detail](/app/releases/<release>)`.
  3. Inspect `kora environment list --json` before offering deployment follow-up.
     If exactly one environment is available, default to that named environment
     and ask whether to deploy there. If multiple environments are available, ask
     which environment should receive the release.
  4. Use `kora release validate <release> --environment <environment> --json` to
     check one environment's readiness.
  5. Use `kora environment deploy <environment> <release> --json` only when the
     user asks to deploy a release, and name the target environment in your
     confirmation.
  6. If deployment runs a source-defined workflow-node test gate, report the
     pass count, rate, mode, and threshold from the response. A blocked gate
     leaves the previous deployment live; do not retry with an override or
     claim the release is deployed.
- If a workflow-node smoke test fails, do not publish or deploy unless the user
  explicitly says to proceed anyway after you warn that the workflow is likely
  to fail. Classify the failure before responding: source/validation error,
  missing extension/binding/grant, missing connection/credential, extension
  runtime error, or provider/API error.
- For operations that call installed extension functions, use the visible
  installed-extension discovery commands. Use the `kora-extension-builder`
  skill only when a new extension package source is needed. Release creation
  does not publish, install, or grant extensions; extension package and
  install lifecycle actions are admin/product workflows outside workflow source.
- Do not ask the user to test anything you can safely test yourself in the
  current authoring environment.
- If testing requires user authorization, missing business input, or real
  changes in connected systems, say exactly what remains untested and what user
  action is needed.
- Do not claim release readiness until the requested release creation or
  explicit release validation is clean. Release creation is not a substitute
  for workflow-node smoke tests.
- When reporting success to the user, keep checks and user-visible behavior in
  the foreground. Avoid implementation bullets for scripts, YAML files, runtime
  SDK calls, or command mechanics unless the user asks for them.

Cascading/destructive changes:

- Identify dependents first with `grep`.
- Tell the user what will be affected.
- Get explicit confirmation before destructive removals.
- Update references in one pass, then inspect the updated references and run
  applicable targeted checks.

Reminder: real org membership, runtime facts, workflow runs, tasks, releases,
runtime variables, workflow artifacts, and resource schemas are not in the
workspace. Use `kora` for those.

## Which Reference To Read Next

- `references/org-model-resources.md` — modeled people, roles, agents, and
  assignments
- `references/capability-resource.md` — capability resource shape
- `references/workflow-flow-nodes.md` — workflow node types and flow rules
- `references/patterns-and-examples.md` — common workflow patterns and one
  complete current project example
- `references/installed-extension-discovery.md` — find installed extensions,
  search functions/tools/skills, and fetch one exact callable contract
- `references/operation-and-extension-resources.md` — operations, service
  scripts, and runtime SDK bindings for selected extension functions
- `references/service-io.md` — operation stdin, stdout, `emitOutput`, and
  `resultMapping`
- `references/artifacts.md` — managed artifact declarations, manifests, and
  send-template artifact URLs
- `references/credentials.md` — runtime variables, org-secret bindings, and
  extension secret boundaries
- `references/filesystem.md` — live runtime filesystem and dependency
  availability
- `references/testing.md` — workflow-node and artifact smoke-test routing
- `references/decision-resource.md` — decision resource shape
- `references/agent-config.md` — agent-specific modeling
- `references/yaml-resource-schemas.md` — YAML shape companion

## Typical Task Routing

- "Where should this resource live?" -> `references/org-model-resources.md`
- "How should this workflow be structured?" ->
  `references/workflow-flow-nodes.md`, then
  `references/patterns-and-examples.md`
- "How does a workflow call external behavior?" ->
  `references/installed-extension-discovery.md`, then
  `references/operation-and-extension-resources.md`, then `references/service-io.md`
- "What extension function/tool/skill should this workflow use?" ->
  `references/installed-extension-discovery.md`
- "How should this service script read input or emit output?" ->
  `references/service-io.md`
- "How should this workflow use files or folders at runtime?" ->
  `references/artifacts.md`, then `references/filesystem.md`
- "How should this node be tested?" -> `references/testing.md`
- "What exact fields does resource X support?" ->
  `kora schema get <resource> --json`
- "What is already modeled in this source proposal?" -> inspect the workspace
  files directly

## Out Of Scope

- Extension package authoring, publishing, installing, updating, and granting ->
  the `kora-extension-builder` skill.
- Product UI route lookup, menus, tabs, buttons, and user navigation ->
  the `kora-product-ui` skill.
- Platform inspection -> `kora` with the matching family, driven by the
  bootstrap source-of-truth map.
- Exact resource fields -> `kora schema get <resource> --json`, not skill
  prose.

Referenced files: 16