> ## 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.

# Kairo Packages: Structure, Layout, and Package Kinds

> Understand how Kairo packages work: project layout, the kairo.toml manifest, and the difference between application and library packages.

A **package** is the fundamental unit of code organisation in Kairo. Every Kairo project is a package — it has a name, a version, a declared language version, and a kind that determines how it can be used. Packages own their source files, tests, resources, and documentation under a single root directory, and they declare everything Forge needs to build and publish them through a manifest file called `kairo.toml`.

## Application vs Library packages

Every package declares a `kind` in its manifest. There are two kinds:

<CardGroup cols={2}>
  <Card title="application" icon="rocket">
    A runnable program. Applications declare an entrypoint that Pulse invokes
    at startup. An application package **cannot** be listed as a dependency of
    another package — it is a terminal node in the build graph.
  </Card>

  <Card title="library" icon="book">
    A reusable unit of code. Libraries expose a public API and **can** be
    declared as dependencies by other packages — both other libraries and
    applications. Only libraries may appear in a `[dependencies]` section.
  </Card>
</CardGroup>

<Note>
  Only `library` packages can be used as dependencies. If you attempt to add an
  `application` package as a dependency, Forge will report an error at restore
  time.
</Note>

## Standard project layout

Every Kairo package follows the same top-level directory structure. Forge and Studio both expect this layout, so keeping to it avoids configuration overhead and ensures tooling works correctly out of the box.

```
ProjectName/
  kairo.toml       ← package manifest (required)
  src/             ← production source files (.ak)
  tests/           ← test source files
  resources/       ← runtime assets (images, config, data files, etc.)
  docs/            ← package-level documentation
  examples/        ← standalone sample packages
  build/           ← Forge output — do not edit
  .forge/          ← Forge cache — do not edit
```

Here is what each entry is for:

| Path         | Purpose                                                                                                                                              |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kairo.toml` | The package manifest. Declares identity, dependencies, and (for applications) the entrypoint. Required at the package root.                          |
| `src/`       | All hand-authored production source code. Files here use the `.ak` extension. **Generated files must never be placed in `src/`.**                    |
| `tests/`     | Test source code. Forge discovers and compiles test files from this directory when you run `forge test`.                                             |
| `resources/` | Static assets the application or library needs at runtime — configuration files, data files, localisation strings, and so on.                        |
| `docs/`      | Package-level documentation authored alongside the code.                                                                                             |
| `examples/`  | Standalone example packages that demonstrate how to use the library or application. Each example is its own package and has its own `kairo.toml`.    |
| `build/`     | All compiler output written by `forge build`. Do not edit files here — they are regenerated on every build. Add this directory to your `.gitignore`. |
| `.forge/`    | Internal Forge cache. Do not edit or commit this directory.                                                                                          |

<Warning>
  Never place hand-authored or generated source files inside `build/` or
  `.forge/`. Forge owns those directories entirely and may delete or overwrite
  their contents at any time. Run `forge clean` to remove them safely.
</Warning>

## Module-to-file mapping

Kairo uses **module declarations** as the authoritative source of identity — not the filesystem path. A module's fully qualified name (e.g., `Astra.Customers.Orders`) is what the compiler and other packages use to refer to it. The file path is a hint, not a contract.

That said, you should keep your filesystem layout aligned with your module names. The conventional mapping is:

* Use **lowercase kebab-case** for file names (e.g., `customer-service.ak`, `order-line.ak`).
* A single module may span multiple files; all files contributing to the same module should live in the same directory.
* Directory names should mirror the PascalCase segments of your module names (e.g., module `Astra.Customers.Orders` lives under `src/Astra/Customers/Orders/`).
* Transitive dependencies are **not** implicit source imports — you must explicitly import every module your code depends on, even if it comes from a package you depend on indirectly.

```
src/
  Astra/
    Customers/
      Orders/
        order.ak            ← module Astra.Customers.Orders
        order-line.ak       ← module Astra.Customers.Orders
      customer.ak           ← module Astra.Customers
      customer-service.ak   ← module Astra.Customers
```

<Tip>
  Keeping file names and directory structure closely aligned with module names
  makes navigation predictable and helps Studio's project view stay organised.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Manifest" icon="file-lines" href="/packages/manifest">
    Learn every field in `kairo.toml` — package identity, versioning,
    entrypoints, and runtime configuration.
  </Card>

  <Card title="Dependencies" icon="link" href="/packages/dependencies">
    Declare and lock your dependencies with `[dependencies]` and `forge.lock`.
  </Card>
</CardGroup>