brainy/PHILOSOPHY.md

# 🧠 Brainy Philosophy & Design Principles

## Core Philosophy
**"Simple for beginners, powerful for experts"**

## Design Principles

### 1. **Beginner-Friendly by Default**
- If no arguments provided → Interactive mode with helpful prompts
- Clear, simple language (no jargon)
- Helpful examples shown automatically
- Smart defaults that "just work"

### 2. **Clean, Simple Language**
```bash
# Good - Clear and simple
brainy add "John works at Acme Corp"
brainy search "Who works at Acme?"
brainy augment neural-import data.csv

# Bad - Technical and confusing
brainy insert --vector-dimension=384 --graph-node="person" 
brainy query --similarity-threshold=0.8 --facet-filter='{"type":"person"}'
```

### 3. **Progressive Disclosure**
- Start simple, reveal complexity only when needed
- Basic usage requires no configuration
- Advanced features available but not required

### 4. **Interactive When Uncertain**
```bash
$ brainy add
? What would you like to add? › John Smith is a developer
? Add any tags or categories? (optional) › person, developer
✅ Added successfully!

$ brainy search
? What are you looking for? › developers
? How many results? (10) › 5
🔍 Found 5 matches...
```

### 5. **Consistent Brain Metaphor**
- **Brainy** = The brain (whole system)
- **Cortex** = Orchestrator (coordinates everything)
- **Neural Import** = Understanding data (neural processing)
- **Augmentations** = Brain capabilities (vision, hearing, memory, etc.)

### 6. **One Way to Do Things**
- Single clear path for common tasks
- No duplicate commands or confusing aliases
- If there are options, make the best one the default

### 7. **Helpful Error Messages**
```bash
# Good
❌ Can't find data.csv
💡 Did you mean data.json? Or try: brainy import --help

# Bad
Error: ENOENT no such file or directory
```

### 8. **Smart Defaults**
- Auto-detect file types
- Infer intent from context
- Use Neural Import by default for understanding data
- Automatic augmentation discovery

## CLI Command Philosophy

### Core Commands (Simple Verbs)
```bash
brainy init        # Start here
brainy add         # Add data
brainy search      # Find data
brainy chat        # Talk to your data
```

### Augmentation Commands (Clear Actions)
```bash
brainy augment                    # List/manage augmentations
brainy augment add neural-import  # Add an augmentation
brainy augment remove notion-sync # Remove an augmentation
```

### Interactive Examples
```bash
# No arguments = Interactive mode
$ brainy add
? What would you like to add? › [waiting for input]

# With arguments = Direct mode
$ brainy add "Sarah is a designer at StartupXYZ"
✅ Added!

# Help is conversational
$ brainy help add
📝 Add data to your brain

Examples:
  brainy add "John works at Acme"
  brainy add data.csv
  brainy add --interactive

Just run 'brainy add' for interactive mode!
```

## Code Philosophy

### Function Names
```typescript
// Good - Clear and simple
brain.add(data)
brain.search(query)
cortex.process(augmentation)

// Bad - Technical and verbose
brain.insertVectorWithGraphRelationships(data)
brain.executeMultiDimensionalQuery(query)
cortex.executeAugmentationPipeline(augmentation)
```

### API Design
```typescript
// Good - Progressive enhancement
brain.add("simple text")                    // Works
brain.add("text", { category: "person" })   // More control
brain.add("text", metadata, options)        // Full control

// Bad - All or nothing
brain.add(text, vector, metadata, options, callback)
```

## Documentation Philosophy

### README Structure
1. **What it is** (one sentence)
2. **Quick start** (3 commands max)
3. **Simple examples** (real-world use)
4. **Going deeper** (advanced features)

### Example First
Always show the example before explaining:
```bash
# Add a person
brainy add "Alice is a product manager"

# Find them later
brainy search "product manager"
```

## Testing Philosophy
- Test the beginner path first
- Interactive mode must always work
- Examples in docs must be runnable
- Error messages must be helpful

## Remember
- **If it's not simple, it's not ready**
- **The best interface is no interface** (smart defaults)
- **Show, don't tell** (examples > explanations)
- **Beginner's mind** (always ask: would a newcomer understand this?)