# Project structure

Know which files builders own, which files Salambo compiles, and which paths exist only at runtime.

A Salambo project describes agent behavior and sandbox inputs. It is not a replacement agent server: Salambo runs the model loop in the hosted worker.

## Recommended layout

```text
support-agent/
├── .pi/
│   ├── settings.json
│   ├── SYSTEM.md
│   ├── skills/
│   │   └── incident-triage/
│   │       └── SKILL.md
│   ├── prompts/
│   │   └── incident-report.md
│   └── extensions/
│       └── support-tools.mjs
├── sandbox/
│   ├── packages.json
│   └── workspace/
│       └── README.md
├── salambo.yaml
└── package.json
```

## What each path owns

| Path                    | Builder responsibility                                                   |
| ----------------------- | ------------------------------------------------------------------------ |
| `.pi/SYSTEM.md`         | Base purpose, rules, and response expectations                           |
| `.pi/settings.json`     | Standard Pi model and thinking-level defaults                            |
| `.pi/skills/`           | Reusable, immutable instruction packages                                 |
| `.pi/prompts/`          | Named prompt templates                                                   |
| `.pi/extensions/`       | Sandbox-hosted Pi extensions                                             |
| `sandbox/packages.json` | Versioned APT, npm, and Python packages installed into the managed image |
| `sandbox/workspace/`    | Seed files copied only into new run workspaces                           |
| `salambo.yaml`          | Deployment, image, region, egress, environment, and secrets              |

## Build-time and runtime paths

The source path and runtime path are intentionally different:

| Source                  | Hosted behavior                               | Mutability               |
| ----------------------- | --------------------------------------------- | ------------------------ |
| `.pi/SYSTEM.md`         | Compiled into the deployment manifest         | Immutable per deployment |
| `.pi/skills/`           | Projected as agent resources                  | Read-only                |
| `.pi/extensions/`       | Loaded by the sandbox extension host          | Read-only                |
| `sandbox/packages.json` | Installed while the deployment image is built | Read-only at runtime     |
| `sandbox/workspace/`    | Copied to `/workspace` for a new run          | Mutable and checkpointed |

Only `/workspace` is builder-owned mutable state. Platform runtime files are not exposed through managed agent file tools.

## Files Salambo generates

`salambo manifest` compiles source files into a deployment manifest containing normalized model settings, instructions, skills, prompts, tool declarations, hook subscriptions, and workspace policy. Do not edit the compiled manifest manually.

## What does not belong here

* Salambo, storage, or provider credentials in source files
* Code that expects access to trusted worker memory
* Mutable customer work under the immutable `.pi/` source tree

Next, [write agent instructions](/docs/agent-development/skills-prompts) and [choose the built-in tools](/docs/agent-development/settings) needed to carry them out.