# profiles/

Where soul profiles live. Each profile is one directory under `profiles/<name>/`
containing a `profile.yaml`. The schema for that file is documented in
[`SCHEMA.md`](./SCHEMA.md).

## Layout

```
profiles/
├── SCHEMA.md          # field-by-field reference + example
├── schema.json        # JSON Schema (draft-07) for tooling
├── _types.ts          # TypeScript types consumed by bin/cli/
├── _cache/            # npx-skill fetch cache, populated by `soul use`; gitignored
├── _active/           # symlink to the currently-active global profile; gitignored
├── _examples/         # tiny test-fixture profiles, NOT installed
└── <name>/            # one directory per real profile
    ├── profile.yaml
    └── README.md
```

## What a profile is

A profile bundles three kinds of capability that a Claude Code or Codex session
should see together:

- **skills** — local (from `soul/skills/`), npx-fetched, or plugin-namespaced
- **mcps** — server IDs from `soul/mcps/configs/`, materialized as `.mcp.json`
- **env** — optional environment variables the agents need

Profiles can `inherits` from one other profile to share a common baseline.
Inheritance depth is capped at 3; cycles are an error.

## What goes where

| Path                     | Owner       | Notes                                            |
|--------------------------|-------------|--------------------------------------------------|
| `profiles/<name>/profile.yaml` | profile author | Hand-written or generated by `soul new`    |
| `profiles/_cache/*`      | `soul use`  | Auto-populated; never edit by hand               |
| `profiles/_active/current` | `soul use --global` | Symlink to active profile; gitignored  |
| `profiles/_examples/*`   | repo        | Fixtures used by tests; safe to extend           |

## Reading further

- [`SCHEMA.md`](./SCHEMA.md) — full field reference
- [`../docs/profiles/quickstart.md`](../docs/profiles/quickstart.md) — 3-command happy path
- [`../docs/profiles/auto-generation.md`](../docs/profiles/auto-generation.md) — `soul scan` and `soul new`
- [`../docs/profiles/anatomy.md`](../docs/profiles/anatomy.md) — deep dive on a real profile
- [`../docs/profiles/troubleshooting.md`](../docs/profiles/troubleshooting.md) — `soul doctor` and common errors

## Adding a profile

See [`../CONTRIBUTING.md`](../CONTRIBUTING.md) § "Adding a profile". The short version:

```bash
soul new my-profile --from-scan --auto      # bucket discovered skills automatically
soul validate my-profile                    # check
soul use my-profile --here                  # activate in CWD
```
