> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ancha.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs describe the Ancha CLI, npm package @ancha-labs/cli, and the hosted workspace at app.ancha.io. Coding agents should start at https://docs.ancha.io/coding-agents. Run the CLI as `ancha` after `npm install -g @ancha-labs/cli`, or as `npx -y @ancha-labs/cli` without installing. Pass --json for machine-readable output, or set ANCHA_JSON=1. Every command ends with a `next:` line naming the next command. Exit codes: 0 pass, 1 a check failed or a comparison regressed, 2 usage, config or authentication error, 3 infrastructure error, 4 unimplemented endpoint with --strict.

# Add people to a saved world

> Create a catalog world with a JSON or YAML people file, inspect it, and update it without changing historical revisions.

A person describes someone your agent can interact with through the world's tools. The person's accounts must already exist in the selected starter data. Saving a person does not create a real account or start an agent.

## Write the people file

Save this as `people.yaml`:

```yaml theme={null}
- ref: laura
  name: Laura
  role: Customer asking for help with an export
  accounts:
    slack: $slack_laura
  knows:
    - id: workspace
      value: Pike Street Dental
      about: which workspace has the problem
```

The file is an array of person definitions. Do not wrap it in `people:`. JSON arrays work too. `$slack_laura` names an account in the Slack starter data; it is not the person's `ref`.

## Create and inspect the world

```bash theme={null}
ancha world create --name "Support with Laura" \
  --tools slack --people people.yaml --json
```

The result includes the world's `id`, `revision`, pinned tool configuration and `people`. Use the returned ID to inspect the saved definition:

```bash theme={null}
ancha world show <world-id> --json
```

Use `--definition configuration.json` instead of `--tools slack` to select a pinned sandbox configuration. `--people` works with either option. It does not configure the model that generates people's replies. When a reply needs a model and none is available, the world reports the missing model.

Ancha rejects malformed files, unknown person fields, duplicate refs and accounts absent from the world's data before saving. An empty array (`[]`) creates a world without people.

## Change people later

Save a world patch as `patch.yaml`:

```yaml theme={null}
people:
  - ref: laura
    name: Laura
    role: Customer asking for help with an export
    accounts:
      slack: $slack_laura
    knows:
      - id: workspace
        value: Pike Street Dental
        about: which workspace has the problem
```

Unlike the creation flag's array, the update file is an object with a `people` field. Pass the revision shown by `world show`:

```bash theme={null}
ancha world update <world-id> --definition patch.yaml --revision <revision>
```

The update creates a new revision. Existing tests and past runs keep their pinned definitions. Set `people: []` in the patch to remove people from the new revision.

See [Worlds](https://docs.ancha.io/concepts/worlds.md) for dataset refs and revisions, and [`ancha world`](https://docs.ancha.io/cli/world) for the command reference.


## Related topics

- [ancha world](https://docs.ancha.io/cli/world.md)
- [Changelog](https://docs.ancha.io/changelog.md)
- [ancha world gen](https://docs.ancha.io/cli/world-gen.md)
- [Worlds](https://docs.ancha.io/concepts/worlds.md)
- [World lifecycle](https://docs.ancha.io/cli/world-lifecycle.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.