> ## 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.
# Forge: Kairo's Build, Package, and Publish Toolchain
> Use Forge to check, build, test, package, and publish your Kairo projects with a predictable, manifest-driven, reproducible pipeline.
Forge is the all-in-one tool for working with Kairo packages. It acts as compiler, build system, package manager, and publish pipeline in a single CLI. Every operation Forge performs follows the same deterministic, manifest-driven pipeline — starting from `kairo.toml`, resolving the dependency graph from `forge.lock`, collecting source files, and producing well-structured output in `build/`. Whether you are iterating on a library or shipping an application to production, Forge is the tool you reach for.
## Command overview
| Command | What it does |
| --------------- | --------------------------------------------------------------------------------- |
| `forge restore` | Resolves declared dependencies and writes `forge.lock`. |
| `forge check` | Validates source and reports diagnostics; stops before generating any artifacts. |
| `forge build` | Runs the full compilation pipeline through artifact and metadata generation. |
| `forge test` | Compiles and runs the test suite. |
| `forge package` | Packages the project for distribution. |
| `forge publish` | Publishes the package to the registry. |
| `forge clean` | Removes `build/` and `.forge/`; never touches source, manifests, or `forge.lock`. |
## Commands in detail
### `forge restore`
```bash theme={null}
forge restore
```
Resolves the dependency graph declared in `[dependencies]` and writes `forge.lock`. Run this command whenever you add, remove, or change a dependency in `kairo.toml`. All other Forge commands read from the lockfile, so `forge.lock` must be up to date before you build.
Forge does **not** search parent directories for a `kairo.toml` in v0.1. Run
all Forge commands from the package root (the directory containing
`kairo.toml`) or the workspace root (the directory containing
`workspace.toml`).
***
### `forge check`
```bash theme={null}
forge check
```
Runs every stage of the build pipeline up to — but not including — artifact generation. Forge validates your manifest, restores dependencies from `forge.lock`, collects source files, lexes and parses them, performs semantic analysis, and runs the type checker. If any stage produces a diagnostic at `error` severity, Forge reports it and stops. No files are written to `build/`.
Because `forge check` produces no output artifacts, it is fast and safe to run frequently. Use it as your tight feedback loop while writing code.
Run `forge check` on every save or as a pre-commit hook. It gives you the
same diagnostic quality as a full build without the overhead of code
generation.
***
### `forge build`
```bash theme={null}
forge build
```
Runs the full build pipeline from manifest loading through to output writing. Forge loads your manifest, restores from `forge.lock`, collects and parses all source, performs semantic analysis and type checking, plans artifact output, runs code generation, and writes the final artifacts and metadata to `build/`.
The complete pipeline in order:
Forge reads and validates `kairo.toml`.
Forge reads `forge.lock` and resolves the full dependency graph.
Forge discovers all `.ak` source files under `src/`.
Source text is tokenised.
Source tokens are parsed into a structured representation of the program.
Module declarations, name bindings, and scope rules are validated.
All expressions and declarations are type-checked.
Forge determines what output files to produce and where.
Forge generates runtime artifacts and metadata.
Final artifacts are written to `build/`.
***
### `forge test`
```bash theme={null}
forge test
```
Compiles the project and the test suite under `tests/`, then runs all discovered tests. Diagnostics from test compilation are reported the same way as production source diagnostics.
***
### `forge package`
```bash theme={null}
forge package
```
Builds the project (equivalent to `forge build`) and then bundles the resulting artifacts, metadata, and any declared resources into a distributable package archive. Run this before `forge publish` or when you want to inspect the exact artifact set that would be published.
***
### `forge publish`
```bash theme={null}
forge publish
```
Packages the project and uploads it to the Kairo package registry. Publishing a version is **irreversible** — once a version is published, its content is immutable. Increment your version in `kairo.toml` before running `forge publish` for every new release.
Published package versions cannot be changed or deleted. Always verify your
package with `forge package` and test it thoroughly before publishing.
***
### `forge clean`
```bash theme={null}
forge clean
```
Deletes the `build/` and `.forge/` directories, removing all compiled artifacts and cached intermediate data. Use `forge clean` when you need a completely fresh build state.
`forge clean` **never** touches:
* Source files under `src/`, `tests/`, `resources/`, or `docs/`
* `kairo.toml` or `workspace.toml`
* `forge.lock`
* `examples/` packages
## Diagnostic codes
Forge and the Kairo toolchain emit structured diagnostics with a severity level and a prefixed code. The prefix identifies which subsystem produced the diagnostic:
| Prefix | Subsystem | Examples |
| ------ | ---------------------------------------------------- | ----------------------------- |
| `FRG` | Forge (manifest, dependency resolution, build graph) | `FRG-0042` conflict error |
| `SYN` | Syntax (lexer, parser) | `SYN-0010` unexpected token |
| `BCK` | Code generation and artifact emission | `BCK-0001` unsupported target |
| `PLS` | Pulse (runtime contract, entrypoint validation) | `PLS-0003` contract mismatch |
Diagnostic severities:
| Severity | Meaning |
| --------- | ------------------------------------------------------ |
| `error` | Build cannot proceed past this stage. |
| `warning` | Build continues; the issue should be addressed. |
| `note` | Informational context attached to an error or warning. |
## Build output locations
| Path | Contents |
| --------- | ----------------------------------------------------------------------------------------------------------------------- |
| `build/` | Compiled artifacts, generated metadata, and packaged output produced by `forge build` and `forge package`. Do not edit. |
| `.forge/` | Internal Forge cache (incremental compilation data, dependency downloads). Do not edit or commit. |
Add both `build/` and `.forge/` to your `.gitignore`. Only `forge.lock`
belongs in source control from Forge's working files.
## Best practices
* **Run `forge check` often.** It is the fastest way to get diagnostic feedback without committing to a full build. Use it in your editor integration and as a pre-commit hook.
* **Commit `forge.lock`.** The lockfile is the single source of truth for your dependency graph. Without it, builds are not reproducible.
* **Never edit `build/` or `.forge/` by hand.** Forge owns these directories and overwrites them freely. Use `forge clean` if you need a reset.
* **Increment your version before publishing.** Published versions are immutable. A version bump is the only way to ship a change.
* **Use `forge package` to inspect before you publish.** Review the artifact bundle to confirm it contains exactly what you expect.
## Next steps
Run your compiled Kairo application with the Pulse runtime.
Understand how Forge resolves and locks your dependency graph.