# Coming from Pi

Move a Pi project to Salambo's .salambo/ layout and know what changes.

Salambo builds on Pi's open-source engine and extension conventions, but owns its hosted runtime and supported API surface. Moving a project is not a promise that every Pi coding-agent feature or community package works hosted or in `salambo dev`. See [credits](/docs/credits).

## Mapping

| Existing Pi project                            | Salambo project after import                            |
| ---------------------------------------------- | ------------------------------------------------------- |
| `.pi/settings.json`                            | `.salambo/settings.json`                                |
| `.pi/SYSTEM.md`, `APPEND_SYSTEM.md`            | Same files under `.salambo/`                            |
| `.pi/skills/`, `prompts/`, `extensions/`       | Same directories under `.salambo/`                      |
| Root `AGENTS.md`                               | Stays at the root                                       |
| `@earendil-works/pi-coding-agent` root imports | `@salambo-ai/agent`, for the exported surface it serves |
| Pi coding-agent terminal UI                    | No hosted terminal UI                                   |
| Existing `salambo.yaml`                        | Kept; a missing file gets a starter declaration         |

## Import

Commit or back up first. The command moves files; it does not keep a copy of `.pi/`. From the project folder, logged in to your Salambo workspace:

```bash
salambo import
```

It moves the entries of `.pi/` into `.salambo/`, rewrites imports of exactly `@earendil-works/pi-coding-agent` to `@salambo-ai/agent` in the extensions' source files, and writes `salambo.yaml` only if there is none. It does not rewrite package subpaths, dependency contents, or the project's `package.json` and lockfile: update your development dependencies yourself, then install `@salambo-ai/agent` and its `typebox` peer for your project's checks. It runs no package install and does not certify compatibility.

For local `salambo dev`, install `@salambo-ai/agent` as a dev dependency (`npm install --save-dev @salambo-ai/agent`): without it, `salambo dev` stops with `Cannot find package '@salambo-ai/agent'`. Hosted builds resolve the import themselves, so this concerns local runs only.

### Refusals and how to fix them

Every refusal happens before anything moves, and names what to change. Fix it, then run `salambo import` again.

**Links.** The import doesn't move links. If `.pi` or `salambo.yaml` is a link, or `.pi/` holds one outside a `node_modules` folder, it names every such link and stops:

```text
salambo import doesn't move links, and these are links:
  .pi/prompts/current.md
Replace each link with what it points to, then run salambo import again. Or move the folder yourself (mv .pi .salambo), fix the links, and change the imports of @earendil-works/pi-coding-agent to @salambo-ai/agent.
```

This is deliberately broad: a link that would survive the move is refused too. Either way forward works: replace each link with what it points to and import again, or move the folder by hand, fix the links, and change the imports yourself.

**Dependency links.** Links inside `node_modules` folders in `.pi/` belong to the package manager and don't block the import. One that points into `.pi/` by an absolute path would break after the move, so it stops the import:

```text
These dependency links point into .pi/ by an absolute path, which breaks when .pi/ moves:
  .pi/node_modules/tool
Delete .pi/node_modules (your package manager rebuilds it), run salambo import again, then reinstall in .salambo/.
```

| Refusal                                                                                                   | Fix                                                                                                                             |
| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `salambo import isn't available yet.`                                                                     | Log in to your Salambo workspace (`salambo auth set`); the command is available once your workspace uses the `.salambo/` layout |
| `No .pi/ folder here: run salambo import in the folder of a Pi project.`                                  | Run `salambo import` from the folder of the project that has `.pi/`                                                             |
| `.salambo/ must be a real directory.`                                                                     | Replace it with a real directory                                                                                                |
| `Commit or back up first: salambo import moves files.`                                                    | Commit or back up `.pi/`. Use `--yes` only after making your own backup                                                         |
| `Both .pi/<name> and .salambo/<name> exist. Keep one, then run salambo import again.`                     | Keep one of the two                                                                                                             |
| `salambo import can't read these files as JavaScript or TypeScript:` (each file, line and parser message) | Fix those files                                                                                                                 |
| `.salambo/extensions still imports @earendil-works/pi-coding-agent at:` (each file and line)              | Change each of those imports to `@salambo-ai/agent`                                                                             |
| `This project has .salambo/ but no salambo.yaml.`                                                         | Restore it (`git checkout HEAD -- salambo.yaml`), or copy the one `salambo init <name>` writes in a new folder                  |

A project that already uses only `.salambo/`, with its `salambo.yaml` and no remaining Pi imports, has nothing to import.

### What the import doesn't check

* Links inside `node_modules` folders in `.pi/` are listed, never followed, and only an absolute one into `.pi/` is refused. A relative link in a `node_modules` folder that leaves `.pi/` and comes back in by name (for example `../../.pi/data.txt`) is not checked, and can break after the move. Package managers don't normally write such links, so it's most likely one you made by hand.
* Links outside `.pi/`, other than `salambo.yaml`, that point into it are not checked and can break: after the move, they point at a `.pi/` path that no longer exists. Update them yourself.

When a `node_modules` folder moves, the import says:

```text
Dependencies were moved; if they fail, reinstall them in .salambo/
```

If your dependencies fail after the import, reinstall them in `.salambo/`.

If the import stops part way, it says so: fix the cause it names, then run `salambo import --yes` to finish the move.

When it finishes, review the changes with `git diff`. Do not keep both folders: deploy refuses a project that has both `.pi/` and `.salambo/`.

After the import, your own tsc or editor flags `session_info_changed`, `ctx.ui.notify` and `ctx.ui.setStatus`: they are not available on Salambo. Remove those calls. The deploy's build refuses `session_info_changed`, and any `notify` or `setStatus` call it can see, naming the file and line; a call it can't see fails the tool during a Turn, and the Turn still completes.

## Before the first deploy

Create `sandbox/workspace/` if it is absent, and keep a regular seed file such as `sandbox/workspace/README.md` in it; keep any existing seed files. A standalone Pi project may not have this directory, and the import does not create it. Deploy refuses a missing or excluded seed directory.

Configure the selected model's runtime credential with the [deployment configuration guide](/docs/deploy/configuration); local credentials are not automatically hosted secrets. Then validate and deploy:

```bash
salambo doctor
salambo manifest --path . --json
salambo deploy
```

## Community packages

The import keeps package declarations as written and reports calls that only work in a local Pi terminal; it does not convert every package into a supported hosted module. Hosted resource resolution accepts exact-version npm packages, public HTTPS git sources pinned to full 40-character commits, and repository-relative local directories. Selected resources must still pass the build and profile checks.

No blanket compatibility list is claimed. Native add-ons, CommonJS extension files, theme configuration and blocked install scripts are not a portable hosted extension surface. A package that imports a value `@salambo-ai/agent` does not export can fail the Salambo build. Check dependencies and peer requirements, not just a package's name.

## Hosted versus local

Hosted custom providers, session-writing actions, provider hooks and compaction are not part of `salambo dev`. Locally, custom providers (including CLIProxyAPI), npm, git and local package resources, `exec`, provider, compaction and tree hooks, session-writing actions and other unlisted APIs are refused by name. Project-local supported tools and hooks work. Command, renderer and noninteractive UI calls are accepted without effect; they are not working UI features.

Local execution is not an OS sandbox. Read the exact [warning and local lists](/docs/agent-development/local-validation), the hosted [extension API](/docs/reference/extensions/extension-api), and [Custom providers](/docs/agent-development/custom-providers).

## Models and wire compatibility

A built-in model removed from the catalogue can be refused before upload. Declared custom providers and agents with extensions follow the rules in [Custom providers](/docs/agent-development/custom-providers). `azure-openai-responses` maps silently to `azure` unless the agent declares its own provider with that name.

`runtime` in `salambo.yaml` is optional. `salambo` and the older `pi` spelling select the same runtime; prefer omitting the selector in new configuration. Hook names follow the current engine: register `model_select` and `thinking_level_select` rather than the older update names.