# Story 3.7: First-Run Empty State Experience

Status: review

## Story

As a new user,
I want to see clear guidance when I first open the app,
so that I know exactly what to do to get value from it.

## Acceptance Criteria

1. Dashboard (`GET /`) renders a "Getting Started" checklist when zero transactions exist.
2. Checklist has two steps: **Set up an account** (links to `/settings/accounts`) and **Add your first transaction** (links to `/transactions/create`).
3. Step 1 is marked complete (✓) when at least one active account exists.
4. Step 2 is marked complete (✓) when at least one transaction exists.
5. When both steps are complete (transactions exist), dashboard shows a "You're up and running" message instead of the checklist, with quick-action links to view transactions and add a transaction.
6. The "Getting Started" heading is visible on the dashboard whenever transactions = 0.
7. `pytest tests/` passes — all 238 prior tests still green.

## Tasks / Subtasks

- [x] **Task 1: Write `tests/test_blueprints/test_dashboard_first_run.py`** (TDD RED)
- [x] **Task 2: Update `app/blueprints/dashboard/routes.py`** — query account and transaction counts
- [x] **Task 3: Rewrite `dashboard/index.html`** — getting started checklist / up-and-running state
- [x] **Task 4: Run full suite GREEN**

## Dev Notes

### Route pattern

```python
from app.models.account import Account
from app.models.transaction import Transaction

@dashboard_bp.route('/')
def index():
    has_accounts     = Account.query.filter_by(is_active=True).count() > 0
    has_transactions = Transaction.query.count() > 0
    return render_template('dashboard/index.html',
                           active_page='dashboard',
                           has_accounts=has_accounts,
                           has_transactions=has_transactions)
```

### Template logic

```jinja2
{% if not has_transactions %}
  {# Getting Started checklist #}
{% else %}
  {# You're up and running #}
{% endif %}
```

### File List

| File | Status |
|------|--------|
| `tests/test_blueprints/test_dashboard_first_run.py` | NEW |
| `app/blueprints/dashboard/routes.py` | MODIFY |
| `app/blueprints/dashboard/templates/dashboard/index.html` | REWRITE |

---

## Dev Agent Record

### Agent Model Used
claude-sonnet-4-6

### Debug Log References
None

### Completion Notes List
- 16 new tests, all green first run
- Regression fix: `client` fixture in conftest.py now depends on `db` so all tests using `client` have DB tables created — previously the 8 base_template tests hit `/` without tables and passed only because the old dashboard route didn't query the DB; the new route does, so this dependency was always latent
- Dashboard shows "Getting Started" checklist when `Transaction.query.count() == 0`; shows "You're up and running!" when transactions exist
- Account step checked/unchecked based on `Account.query.filter_by(is_active=True).count() > 0`
- 254 passed, 1 skipped total

### File List
- `tests/test_blueprints/test_dashboard_first_run.py` — NEW (16 tests)
- `tests/conftest.py` — MODIFIED (client fixture now depends on db)
- `app/blueprints/dashboard/routes.py` — MODIFIED (queries accounts + transactions counts)
- `app/blueprints/dashboard/templates/dashboard/index.html` — REWRITTEN

### Change Log
- 2026-05-28: Story implemented and moved to review status