# Knowledge Base Conventions

## File Naming

- All entity files: `<entity-id>.yaml`
- Entity IDs: lowercase letters, numbers, hyphens only (kebab-case)
- No leading/trailing hyphens, no double hyphens
- Pattern: `/^[a-z0-9]+(-[a-z0-9]+)*$/`

## Directory Structure

| Path | Contents |
|------|----------|
| `kb/profiles/` | Person entities |
| `kb/experiences/` | Experience entities |
| `kb/skills/` | Skill entities |
| `kb/organizations/` | Organization entities |
| `kb/projects/` | Project entities |
| `kb/certifications/` | Certification entities |
| `kb/tandems/` | Tandem entities |
| `kb/tracking/` | LinkedIn tracking entities |
| `kb/graph-index.yaml` | Central graph index |

## Graph Index Maintenance

- Always update `kb/graph-index.yaml` when entities are added or removed
- Valid relationship types: `has_skill`, `worked_at`, `collaborated_with`, `applied_for`, `partners_with`
- All relationships must reference existing entity IDs
- Rebuild with `src/graph/index-manager.ts` if index drifts out of sync

## Entity Schema Conventions

- Common header on every entity file: `id`, `type`, `created`, `modified`
- Dates in ISO format: `YYYY-MM-DD` or `YYYY-MM`
- Use `null` for open-ended dates (e.g., current role `end: null`)
- YAML files use kebab-case keys (e.g., `skills-used`, `shared-vision`)
- TypeScript uses camelCase (e.g., `skillsUsed`, `sharedVision`)

## Validation Rules

- Always validate entities before writing to disk
- Temporal consistency: start ≤ end (when both are present)
- Tandem entities must have exactly 2 partners
- All referenced entity IDs must exist in the knowledge base
- Use `src/schemas/validate.ts` for programmatic validation