# Bundled Starter Elements

## Purpose

This directory contains **default example elements** that ship with the DollhouseMCP NPM package. These are NOT user-generated files - they are part of the product.

## What Are Bundled Elements?

On first run, DollhouseMCP copies these example elements to the user's local portfolio (`~/.dollhouse/portfolio/`) to provide:

1. **Working examples** - Users can immediately try personas, skills, and templates
2. **Learning material** - See proper element structure and metadata
3. **Quick start** - No empty portfolio on first install

### First-Run Process

When a user installs DollhouseMCP via NPM:

1. **User installs**: `npm install @dollhousemcp/mcp-server`
2. **First launch**: User starts DollhouseMCP for the first time
3. **Empty portfolio detected**: System checks `~/.dollhouse/portfolio/` and finds it empty
4. **Bundled elements copied**: DefaultElementProvider copies files from `data/` → user portfolio
5. **User customizes**: User can now modify their local copies without affecting the originals

**Important**: The bundled elements in `data/` remain unchanged. Users work with *copies* in their portfolio.

## Directory Structure

```
data/
├── personas/       Example AI behavioral profiles
├── skills/         Example discrete capabilities
├── templates/      Example reusable content structures
├── agents/         Example goal-oriented decision makers
├── memories/       Example persistent context storage
└── ensembles/      Example combined element orchestration
```

## Important Distinctions

| This Directory (data/) | User Portfolio (~/.dollhouse/portfolio/) |
|------------------------|------------------------------------------|
| ✅ In git repository   | ❌ NOT in repository                     |
| ✅ Ships with NPM      | ❌ Local user storage only               |
| ✅ Read-only examples  | ✅ User's active elements                |
| ✅ Version controlled  | ❌ .gitignored                           |

## For Developers

### NPM Package Inclusion

These files are explicitly included in package.json:

```json
"files": [
  "data/personas/**/*.md",
  "data/skills/**/*.md",
  "data/templates/**/*.md",
  "data/agents/**/*.md",
  "data/memories/**/*.md",
  "data/ensembles/**/*.md"
]
```

### Loading Mechanism

See `src/portfolio/DefaultElementProvider.ts` for the implementation:

- **Population logic** (`populateDefaultElements()` around line 947): Main function that orchestrates copying bundled elements to user portfolio
- **File copying** (`copyElementFiles()` around line 679): Copies individual files while preserving existing user modifications
- **Directory detection** (`findDataDirectory()` around line 190): Locates bundled data in NPM installation or git repository
- **Development vs production mode** (lines 35-122): See below for detailed explanation

#### Development vs Production Modes

The loading mechanism behaves differently based on the environment:

**Production Mode** (NPM installation, no `.git` directory):
- ✅ Bundled elements ARE loaded by default
- Users get starter examples on first run
- Provides immediate value for new installations

**Development Mode** (Git clone, `.git` directory present):
- ❌ Bundled elements are NOT loaded by default
- Prevents test/example data from polluting developer's portfolio
- Developers can override with `DOLLHOUSE_LOAD_TEST_DATA=true` environment variable

This distinction ensures:
- End users get a great first-run experience with examples
- Developers working on the codebase don't get unwanted test data in their personal portfolio
- Test elements (marked with metadata) are blocked in production for security

### Testing

`test/__tests__/basic.test.ts` (lines 33-57) verifies:
- Required directories exist (including `data/personas`)
- Expected example files are present (e.g., `creative-writer.md`)
- Proper structure is maintained

## Common Misconceptions

❌ "data/ should be in .gitignore" - **NO**, these are bundled examples, not user data
❌ "This is test data" - **NO**, this is production starter content
❌ "This is my local portfolio" - **NO**, your portfolio is in `~/.dollhouse/`

## Contributing New Examples

When adding new bundled elements:

1. Follow existing element structure (YAML frontmatter + Markdown)
2. Keep examples simple and educational
3. Test that DefaultElementProvider can load them
4. Update this README if adding new element types