# Profiles

Profiles make the workspace reusable across projects, clients, or personal workflows.

Each profile should describe what the project is, where its memory lives, which communication sources matter, which local services are enabled, and how AI clients should access context.

## Current Profile Layout

```text
profiles/
  fidelity/
    profile.md
    services.json
    context-sources.json
  example/
    profile.md
```

## Recommended Future Layout

```text
profiles/<profile>/
  profile.md              # human-readable project profile
  workspace.json          # profile paths and defaults
  services.json           # local services for this profile
  context-sources.json    # communication/source filters

workspaces/<profile>/
  project-knowledge/      # canonical Markdown vault
  inbox/                  # raw evidence for this profile
```

## Profile Files

### `profile.md`

Human-readable summary for agents and developers:

- project name;
- workspace role;
- communication sources;
- work-item system;
- stakeholders or roles;
- important domain themes;
- enabled workflows or skills.

### `workspace.json`

Profile path configuration:

```json
{
  "profile": "example",
  "display_name": "Example Project",
  "knowledge_dir": "workspaces/example/project-knowledge",
  "inbox_dir": "workspaces/example/inbox",
  "index_dir": ".aiw/indexes/example"
}
```

Reusable scripts should resolve these paths through `scripts/aiw/profile.py`.

### `services.json`

Profile-specific local service manifest for `scripts/aiw/services.py`.

Examples:

- context MCP;
- communication proxy/mirror;
- photo inbox;
- future indexer or dashboard services.

### `context-sources.json`

Source filters for profile-bounded reads. For example, a Mattermost profile can define which channels count as high-signal context.

## Adding A New Project

1. Create the isolated profile and workspace:

   ```bash
   python3 scripts/aiw/profile.py create my-project --display-name "My Project"
   ```

2. Define services only for integrations the project actually uses.
3. Put connector secrets in ignored `.env` files.
4. Validate the layout:

   ```bash
   python3 scripts/aiw/profile.py doctor --profile my-project
   ```

5. Build the local index.
6. Connect AI clients through the MCP server.

## Migration Rule

Reusable code should accept a `--profile` argument and resolve paths through profile configuration. Avoid adding hardcoded references to Fidelity, channel names, ticket prefixes, or company-specific folders in generic scripts.