docs / guide / The Cajeta Guide

03 — Your first project

Chapter 02 built and ran hello. Now look at what init actually created, and what else the toolchain can make.

The layout

hello/
├── cajeta.json                          # the manifest
├── src/main/cajeta/<package>/*.cajeta   # sources, dirs mirror packages
└── build/                               # outputs (gitignored)

The manifest

cajeta.json has three parts:

• details — name, version, description, license.
• settings — capabilities (see chapter 04), dependencies, repositories, and settings.build.entry-method (com.example.basic.Main::main) — the presence of an entry method is what makes this a binary project.
• tasks — named action pipelines. The archetype ships build, test, clean, lint, and release; you add your own. cajeta tasks lists them:

$ cajeta tasks
  build    Local development build
  clean    Wipe build outputs
  lint     Run native + plugin lint actions
  release  Release build + ship
  test     Unit tests with coverage instrumentation

Project types

cajeta init --list:

A library is the same project minus the entry method:

$ cajeta init library greetlib && cd greetlib
$ cajeta build
# → build/archive/greetlib-0.1.0.cja

cajeta install publishes the .cja into your local repository so sibling projects can depend on it before it’s ever published remotely.

Every artifact kind

The package action turns build outputs into distributables. Shipped today:

Deferred (the build tool rejects these with a “deferred slice” error for now): deb, rpm, msi, app-bundle, pkg, dmg, appimage, flatpak, snap.

The wider command surface

One binary does everything; unknown subcommands fall through to your manifest’s tasks (that’s how cajeta run works when a run task exists — chapter 04).

cajeta --help shows the same list.

Skills, for AI coding agents

The same skills the search-skill / get-skills commands return are also served over the Model Context Protocol by cajeta compiler-mcp — a stdio server built into the compiler, exposing searchSkills, listSkills, and getSkills. Register it with your agent (this repo ships a .mcp.json doing exactly that) and the agent can look up authoritative guidance for a class, package, or language topic before it writes code, instead of guessing.

The corpus is embedded in the binary, so it works with no project, no lockfile, and no network — more than 180 skills covering the language itself (cajeta.language), the toolchain (cajeta.toolchain), and every stdlib package.

Your library ships skills too. Skills are part of the .cja archive format, not a compiler privilege: write them as skills/*.md at your package root, and cajeta build validates, indexes, and embeds them beside the bitcode. Anyone who resolves your dependency gets your guidance offline, pinned to the version they resolved, discoverable by name.

mylib.cja
├── … compiled bitcode members
├── skills/index.json
├── skills/opening-files.md
└── skills/retry-policy.md

The format is a Markdown body under YAML frontmatter (id, applies-to, title, description) — see Skills for the authoring levels and the review checklist, and CompilerMcp for the server’s tools and lifecycle.

For the longer walk — dependencies, publishing, uber-archives end to end — see the build tool reference.

Next: Running your application.

Source: docs/guide/03-your-first-project.md · 3 min · 708 words