# Core Requirements

System-wide constraints, data model, and architectural decisions that apply across all features.

---

## Python Version

- **Python 3.11+** required (upgraded from original 3.10+ spec during MVP)
- Uses stdlib `StrEnum` and `tomllib` (3.11+)

## Package Layout

- `src/unfamiliar/` layout with `pyproject.toml`
- Installed globally via `pip install unfamiliar`, not per-codebase

## Storage

- **Central storage:** `~/.unfamiliar/`
  - `config.toml` — provider, preferences (NOT API keys)
  - `standards/` — coding standards for analysis pipeline (universal + per-language)
  - `campaigns/<repo-name>-<hash>/` — per-codebase campaign DB + artifacts
  - `repos/<hash>/config.yaml` — per-repo analysis filter overrides
- **Target repo stays untouched** — no files added to the investigated codebase
- **SQLite** for campaign state; **Markdown** for user-facing artifacts (briefing, summaries)

## Campaign Directory Naming

- Format: `<repo-folder-name>-<first-6-chars-of-SHA256-of-absolute-path>`
- Hash collision: append `-1`, `-2`, etc.

## API Key Security

- API keys resolved **exclusively from environment variables**
- Config file `[api_keys]` support was removed during MVP
- Lookup order: provider-specific env var > generic `UNFAMILIAR_API_KEY` fallback
- Supported vars: `ANTHROPIC_API_KEY`, `ZHIPUAI_API_KEY`

## Data Model (v0.1.0 Schema)

### Entities

- **Campaign** — top-level container, one per codebase. Fields: repo_path, schema_version, mode (default: onboarding), character (default: null), status (initializing|active|closed), theme (locked to "film_noir")
- **Briefing** — 1:1 with Campaign. Fields: summary, tech_stack, security_posture
- **Module** — logical code unit. Fields: name, path, description, file_count, category_relevance, security_relevant
- **Mission** — atomic investigation task. Fields: title, title_plain, description, category (7 categories), difficulty (quick|medium|deep_dive), time_estimate_minutes, completion_condition, security_tag, standard_tag, status (locked|available|in_progress|completed), completion_method, narrative_intro, narrative_outro
- **Mission File Reference** — file+line ranges for a mission. Fields: file_path, line_start, line_end, description, file_hash
- **Mission Chain** — learning sequence. Fields: name, name_plain, description, category, sort_order
- **Chain-Mission Link** (junction) — position field for ordering
- **Mission Prerequisite** (junction) — self-referential on Mission
- **Module-Mission Link** (junction) — is_primary boolean
- **File Snapshot** — file hashes at generation time (stored, not checked until v1.1)

### Forward-Compatible Fields

- `mode` and `character` on Campaign exist in schema but are not exposed in UI
- `schema_version` tracks campaign age for future upgrade path

### Relationships

```
Campaign 1──1 Briefing
Campaign 1──* Module
Campaign 1──* Mission
Campaign 1──* Mission Chain
Campaign 1──* File Snapshot
Mission *──* Mission Chain    (via Chain-Mission Link)
Mission *──* Mission          (via Mission Prerequisite)
Mission 1──* Mission File Reference
Module  *──* Mission          (via Module-Mission Link, one primary per mission)
```

## Investigation Categories

Seven fixed categories (enum, not table):

| Category | Focus |
|----------|-------|
| Architecture | Module structure, entry points, component connections |
| Domain & Business Logic | Core workflows, business rules, failure modes |
| Data Flow | Schema, state, data movement |
| Dependencies | External services, APIs, key libraries, boundaries, config |
| Conventions | Patterns, idioms, error handling, naming |
| Testing | Coverage, quality, untested paths |
| Technical Debt | Code smells, violations, structural risks |

**Security** is a cross-cutting tag, not a separate category. Missions in any category can be flagged security-relevant.

## Token Economy

- **No LLM calls for mission presentation.** Viewing, tracking, completing missions are all local SQLite/Markdown operations
- **MVP completion is always zero-token** (self-report only)
- **Static analysis is always free** — no LLM calls for file scanning, AST parsing, import tracing, git operations
- **All generated content persisted locally** — never re-call LLM for data that's already stored

## Offline Capability

- Once a campaign is generated, all mission work is fully offline
- Operations requiring LLM (initial analysis, staleness refresh, completion summary) fail gracefully with clear message if offline

## Theme Architecture

A theme is a **configuration package**, not a code change:

| Component | What it controls |
|-----------|-----------------|
| TCSS stylesheet | Colors, borders, backgrounds, text styles |
| Command aliases | Themed names for canonical commands |
| Vocabulary | What to call missions, chains, campaign, etc. |
| Narrative config | Tone, title examples, intro/outro styles for LLM prompts |
| Colors, decorations, icons | Theme-specific visual elements |

Adding a new theme = adding a new directory with data files. Zero code changes required.

## Accessibility Foundation

- Strict separation between data/logic and presentation layers (enables future --plain mode)
- Keyboard-only navigation — all TUI functionality accessible without mouse
- `/` key re-focuses command input; arrow keys navigate modal buttons
- All generated artifacts are Markdown (readable in any editor/assistive tool)
