Update to Kora

{
  "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.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 299
    },
    {
      "relative_path": "assets/kora-mark.png",
      "size_in_bytes": 24826
    },
    {
      "relative_path": "references/auth-and-sessions.md",
      "size_in_bytes": 4519
    },
    {
      "relative_path": "references/command-map.md",
      "size_in_bytes": 2592
    },
    {
      "relative_path": "references/http-api.md",
      "size_in_bytes": 2326
    }
  ],
  "name": "kora-cli",
  "skill_md_contents": "---\nname: kora-cli\ndescription: \"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.\"\n---\n\n# Kora CLI\n\n`kora` is the command-line client for Kora SaaS and reachable self-managed Kora\ndeployments. Use this skill when the user wants to manage Kora resources from a\nterminal or needs direct Platform HTTP API access with organization API keys.\nInstalling or operating the deployment itself is the `kora-self-host` skill,\nnot this one.\n\nEstablish the target before giving setup instructions:\n\n- **Kora SaaS** — use the CLI default, `https://kora-eu.raw-labs.com`; do not\n  ask the user for a URL. SaaS onboarding provisions the user's organization\n  and production environment. Do not run the self-managed installer, use\n  `koractl`, or create another organization as part of first-time setup.\n- **Self-managed Kora** — the user or operator supplies the deployment URL. If\n  the deployment does not exist yet, route installation to `kora-self-host`.\n- **Unknown** — use Kora SaaS by default. Ask for a URL only when the user says\n  they operate or need to connect to a self-managed deployment.\n\n## Install\n\n```sh\nnpm install -g @kora-platform/cli\nkora --help\n```\n\nRequires Node.js >=24.0.0.\n\n## Point The CLI At Kora\n\nLogin base URL resolution order, first match wins:\n\n1. `--base-url` flag on `kora auth login` / `kora auth signup`\n2. `KORA_BASE_URL` environment variable\n3. nearest `.kora/cli.toml` walking up from the working directory\n4. `~/.config/kora/config.toml` (respects `XDG_CONFIG_HOME`)\n5. Kora SaaS at `https://kora-eu.raw-labs.com`\n\nAfter login the base URL is stored in the session, so subsequent commands\nneed no flag. The SaaS default is not written as a config override. Self-managed\nlocal-mode installs serve `http://localhost:3000`. `kora auth signup` remains a\nlocal-account command for self-managed deployments and prompts for a deployment\nURL when no override is configured.\n\n## Authentication\n\n`kora auth login` has two flows:\n\n- **Device approval (the SaaS and agent path).** `kora auth login` automatically\n  uses browser device approval for the Kora SaaS default, OIDC-only deployments,\n  and non-interactive shells such as coding-agent shell tools. `--device` forces\n  it for any other configured deployment. The command prints a verification URL\n  and confirmation code, then waits:\n\n  ```sh\n  kora auth login --base-url http://localhost:3000 --device\n  ```\n\n  The user opens `<base-url>/device?code=XXXX-XXXX`, signs in in the browser if\n  needed, confirms the code matches the terminal, and approves. In OIDC-only\n  deployments, the web login route continues directly to the configured\n  identity-provider flow. The CLI then stores the session and the command\n  completes on its own. Codes expire after 15 minutes; a denied or expired\n  approval fails the command with a clear error. This flow also works on\n  OIDC/SSO-only deployments, because authentication happens in the browser.\n\n- **Interactive email/password.** For explicitly configured local or hybrid\n  self-managed deployments, plain `kora auth login` prompts for credentials.\n\nWhen driving Kora SaaS as a coding agent, run `kora auth login`, surface the\nprinted URL and confirmation code to the user, and wait for the command to\nfinish. Pass `--base-url` or set `KORA_BASE_URL` only for self-managed Kora.\nConfirm with `kora auth whoami`; the session is stored on disk and every later\n`kora` command picks it up automatically.\n\nNotes:\n\n- A SaaS user who needs a new account can open\n  `https://kora-eu.raw-labs.com/signup` in the same browser. A self-managed user\n  can open `<base-url>/signup`. Complete signup, then reopen the device\n  verification URL before its code expires. OIDC-only login goes directly to\n  provider sign-in and does not promise a Kora-page signup link.\n  `kora auth signup` (TTY-only, local email/password accounts) remains\n  available for interactive use.\n- On a local-mode self-managed install, the first signed-up user becomes\n  platform admin. Server installs require SSO sign-in with one of the configured\n  verified platform-admin bootstrap emails; unverified local-auth first-user\n  bootstrap is limited to local single-machine evaluation.\n- Kora SaaS users sign in through its browser/OIDC flow. Opening the SaaS\n  `/signup` entry creates or resumes the hosted onboarding flow; the terminal\n  does not create the account or initial organization.\n- Fully headless CI with no human in the loop: inject a session via\n  `KORA_SESSION_JSON_B64` — see `references/auth-and-sessions.md`.\n\n## First SaaS Session, End To End\n\n```sh\nnpm install -g @kora-platform/cli\nkora auth login\nkora auth whoami\nkora status\n```\n\nThe device command prints a browser URL and approval code. After approval,\n`whoami` must show the organization provisioned by SaaS onboarding. Do not run\n`kora org create` as part of SaaS setup; hosted users use the organization\ncreated by onboarding and cannot create additional organizations.\n\n## First Self-Managed Session, End To End\n\n```sh\nnpm install -g @kora-platform/cli\nkora auth login --base-url http://localhost:3000 --device\nkora auth whoami\nkora org list --json\nkora status\n```\n\nCreate an organization only when the authenticated self-managed deployment has\nnone for this user and the user explicitly wants one. `kora org create` sets a\nnew organization active. With access to multiple organizations, switch with\n`kora org select <org>` and check with `kora org current` or\n`kora auth whoami`.\n\n## Working Conventions\n\n- Append `--json` for machine-readable output. Discover the surface with\n  `kora help --json` and `kora help <command-path> --json` instead of\n  guessing flags.\n- Most commands require an active organization.\n- Destructive commands (`kora org delete`, `kora org reset`, and similar)\n  prompt for confirmation unless `--yes` is passed.\n- Organization API keys (`kora access api-keys create`) authenticate direct\n  Platform API HTTP calls; they are not a CLI login method in this release.\n\n## Which Reference To Read Next\n\n- `references/auth-and-sessions.md` — session storage and permissions,\n  non-interactive session injection, base-URL precedence detail, OIDC\n  behavior, and API keys\n- `references/http-api.md` — live OpenAPI discovery, API-key bearer auth,\n  roles for common integration calls, and workflow start/run polling examples\n- `references/command-map.md` — top-level command families and aliases\n"
}