> ## Documentation Index
> Fetch the complete documentation index at: https://docs.astrakairo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Studio: The Official Kairo Development Environment

> Studio is the official IDE for Kairo, providing editing, diagnostics, refactoring, and Forge workflow integration in one environment.

Studio is the official integrated development environment for Kairo. It brings together editing, live diagnostics, intelligent completions, safe refactoring, and direct Forge workflow integration into a single environment purpose-built for the Kairo package model. Rather than treating the build system and the editor as separate concerns, Studio treats them as one: the same semantic analysis that powers `forge check` drives the diagnostics you see as you type, and every Forge operation is available without leaving the IDE.

<Note>
  Studio is under active development. Features and UI are subject to change as
  the language and toolchain mature. Consult the release notes for your
  installed version for the definitive list of supported capabilities.
</Note>

## Features

### Editing and navigation

<CardGroup cols={2}>
  <Card title="Syntax highlighting" icon="paintbrush">
    Full syntax highlighting for `.ak` source files, `kairo.toml` manifests,
    and `forge.lock`.
  </Card>

  <Card title="Navigation" icon="compass">
    Go-to-definition, find-all-references, and symbol search across the entire
    package (or workspace).
  </Card>

  <Card title="Search" icon="magnifying-glass">
    Full-text and symbol-aware search scoped to source, tests, or the whole
    workspace.
  </Card>

  <Card title="Formatting" icon="align-left">
    Automatic code formatting and non-semantic hygiene fixes on save or on
    demand.
  </Card>
</CardGroup>

### Diagnostics and completions

Studio keeps its diagnostic view continuously aligned with Forge semantics. The errors and warnings you see in the editor are the same diagnostics `forge check` produces — there is no separate "Studio linter" with different rules.

* **Live diagnostics** — errors, warnings, and notes appear inline as you edit, sourced from the same analysis pipeline as Forge.
* **Completion** — context-aware suggestions for identifiers, module members, keywords, and import paths.
* **Signature help** — function parameter hints displayed as you type call expressions.
* **Hover info** — type information, documentation, and declaration details on hover.

### Refactoring

Studio supports safe, preview-first refactoring operations that update all affected references across the package or workspace before making any change:

<CardGroup cols={2}>
  <Card title="Rename" icon="pencil">
    Rename any symbol — function, type, module, variable — and Studio
    propagates the change to every reference, including import paths and
    cross-file usages.
  </Card>

  <Card title="Move" icon="arrow-right-arrow-left">
    Move a declaration to a different module or file. Studio updates all
    import paths and references automatically.
  </Card>
</CardGroup>

Every refactoring operation shows you a **preview** of all proposed changes before applying them. You review and confirm the diff; Studio does not apply anything silently in the background.

<Warning>
  Studio will never silently rewrite your source files, manifests, or package
  structure. Quick fixes and refactorings always require explicit confirmation.
  Background processes do not mutate source.
</Warning>

### Scaffolding and templates

Studio provides template and scaffolding workflows to help you create new packages, modules, and common code patterns without writing boilerplate by hand:

* Create a new application or library package from a template, with `kairo.toml` pre-populated.
* Add a new module file with the correct declaration stub and file name convention.
* Generate test stubs for existing modules.

### Forge workflow integration

You can trigger every Forge command from within Studio without switching to a terminal:

| Forge command   | Studio action            |
| --------------- | ------------------------ |
| `forge restore` | Restore dependencies     |
| `forge check`   | Check project            |
| `forge build`   | Build project            |
| `forge test`    | Run tests                |
| `forge package` | Package for distribution |
| `forge publish` | Publish to registry      |
| `forge clean`   | Clean build output       |

Studio also surfaces Forge diagnostics inline — if `forge build` produces an error in a source file, Studio highlights the relevant line and shows the diagnostic code (`FRG`, `SYN`, `BCK`, or `PLS`) alongside the message.

<Note>
  Studio does not bypass `forge.lock` or any other package resolution rules
  when invoking Forge. Every build triggered from within Studio is governed by
  the same deterministic pipeline as a manual `forge build` on the command line.
</Note>

### Debugging

Studio includes a debugging UX for stepping through Kairo application execution:

* Set breakpoints in source files.
* Inspect local variables, call stacks, and execution state at breakpoints.
* Step over, step into, and step out of function calls.
* Evaluate expressions in the context of a paused execution.

### Project view

Studio's project view distinguishes between different categories of files so you always know what you own and what is generated:

| Category         | Description                                                      |
| ---------------- | ---------------------------------------------------------------- |
| **Authored**     | Source files you wrote — `src/`, `tests/`, `docs/`, `resources/` |
| **Generated**    | Files produced by code generators or tooling (never in `src/`)   |
| **Build output** | Artifacts in `build/` and cache in `.forge/`                     |

## Rooting Studio at your project

Studio must be rooted at the right file to provide full package-aware tooling:

* **Single-package project** — open the directory containing `kairo.toml`. Studio will discover and index the package.
* **Multi-package workspace** — open the directory containing `workspace.toml`. Studio will discover all member packages and show them in a unified project view, with cross-package navigation and refactoring working across the whole workspace.

<Tip>
  If you open a subdirectory that doesn't contain a `kairo.toml` or
  `workspace.toml`, Studio will operate in a limited mode without package
  context. Always open at the package or workspace root for the full experience.
</Tip>

## Extensions

Studio supports extensions that add new capabilities to the IDE — additional language support, custom views, external tool integrations, and more. Extensions may augment Studio's behaviour, but they operate within firm boundaries:

* Extensions **cannot** redefine language semantics, type-checking rules, or build behaviour.
* Extensions **cannot** change how Forge resolves dependencies or produces artifacts.
* Extensions **cannot** alter Pulse runtime contract handling.
* Extensions must respect Studio's policy of no silent source mutations.

The core Kairo experience — language rules, build pipeline, runtime behaviour — is defined by the language specification, Forge, and Pulse. Extensions layer on top without undermining that foundation.

## Next steps

<CardGroup cols={2}>
  <Card title="Forge" icon="hammer" href="/toolchain/forge">
    Learn the full Forge command suite that Studio orchestrates.
  </Card>

  <Card title="Overview" icon="boxes-stacked" href="/packages/overview">
    Understand the package structure and project layout Studio is built around.
  </Card>
</CardGroup>