` containing flash message block and `{% block content %}` - [x] Flash messages rendered via `get_flashed_messages(with_categories=True)` — all 4 category classes - [x] JS script tags for `chart-defaults.js`, `modal.js`, `loading.js` (stubs exist; implemented Story 2.4) - [x] **Task 4: Implement `app/templates/errors/404.html`** (AC: 4) - [x] `{% extends 'base.html' %}` - [x] `{% block title %}404 Not Found — Financials{% endblock %}` - [x] `{% block content %}` with clear 404 message and "Go to Dashboard" link - [x] **Task 5: Implement `app/templates/errors/500.html`** (AC: 4) - [x] `{% extends 'base.html' %}` - [x] `{% block title %}500 Server Error — Financials{% endblock %}` - [x] `{% block content %}` with user-friendly error message - [x] **Task 6: Update `app/__init__.py` error handlers** (AC: 5) - [x] Add `render_template` to Flask import - [x] Replace `return 'Not Found', 404` with `return render_template('errors/404.html'), 404` - [x] Replace `return 'Internal Server Error', 500` with `return render_template('errors/500.html'), 500` - [x] **Task 7: Write smoke tests in `tests/test_blueprints/test_base_template.py`** (AC: 2, 3, 5, 6) - [x] `test_index_returns_200_with_html` — `GET /` → 200, response contains ` import _bp # noqa: F401` in their `routes.py` — NO actual route functions. Calling `url_for('transactions.transactions_list')` when `transactions_list` doesn't exist raises `werkzeug.routing.exceptions.BuildError` and crashes the template render. **Correct pattern for nav links in `base.html`:** ```html Transactions ``` **NOT:** ```html Transactions ``` Use `url_for('dashboard.index')` ONLY for the dashboard link — it has a real route. Use `url_for('static', filename='...')` for CSS/JS assets — always safe. All other nav links: hardcoded paths matching blueprint URL prefixes. **URL path map:** | Section | Path | Blueprint | |---------|------|-----------| | Dashboard | `{{ url_for('dashboard.index') }}` | `dashboard` (has route) | | Transactions | `/transactions/` | `transactions` | | Budgets | `/budgets/` | `budgets` | | Bills | `/bills/` | `bills` | | Paydown | `/paydown/` | `paydown` | | Import | `/import/` | `import_pdf` | | Analytics | `/analytics/` | `analytics` | | Settings | `/settings/` | `settings` | As each blueprint gains a real index route in later stories, their nav link can be converted to `url_for()`. Do NOT do this eagerly — only convert when the endpoint exists. --- ### Exact `app/templates/base.html` Implementation ```html {# base.html — Application shell template. Active page convention (AR-8, architecture.md): EVERY render_template() call in every blueprint MUST pass active_page=''. Blueprint names to use: 'dashboard', 'transactions', 'budgets', 'bills', 'paydown', 'import_pdf', 'analytics', 'settings' The nav uses this variable to set aria-current="page" on the active link. Enforced by: tests/test_blueprints/test_base_template.py Flash message categories (AR-14): 'success' → flash-success (green) 'error' → flash-error (red) 'warning' → flash-warning (amber) 'info' → flash (blue, base class only) Use only these 4. Any other category will render unstyled. #} {% block title %}Financials{% endblock %} {# Primer CSS — local copy. File is downloaded in Story 2.3 (static/vendor/primer/primer.css). This link is correct; the file simply won't exist until Story 2.3 runs. #} {# Domain semantic tokens — stub in Story 2.1, fully implemented in Story 2.3 #} {# App-specific styles — stub in Story 2.1, fully implemented in Story 2.3 #} {# Skip to main content — accessibility (WCAG 2.1 AA) #}

{# ── Sidebar Navigation (240px fixed) ────────────────────────────── #} {# ── Main Content Area ─────────────────────────────────────────── #}

{# Flash messages — AR-14: categories are success / error / warning / info only #} {% with messages = get_flashed_messages(with_categories=True) %} {% if messages %} {% for category, message in messages %}

{% endfor %} {% endif %} {% endwith %} {% block content %}{% endblock %}

{# JS utilities — stubs in Story 2.1; fully implemented in Story 2.4 #} ``` --- ### Exact `app/templates/errors/404.html` Implementation ```html {% extends 'base.html' %} {% block title %}404 Not Found — Financials{% endblock %} {% block content %}

404 — Page Not Found

The page you're looking for doesn't exist.

← Go to Dashboard {% endblock %} ``` --- ### Exact `app/templates/errors/500.html` Implementation ```html {% extends 'base.html' %} {% block title %}500 Server Error — Financials{% endblock %} {% block content %}

500 — Server Error

Something went wrong on our end. Please try again.

← Go to Dashboard {% endblock %} ``` --- ### Exact `app/blueprints/dashboard/templates/dashboard/index.html` ```html {% extends 'base.html' %} {% block title %}Dashboard — Financials{% endblock %} {% block content %}

Dashboard

Your financial overview will appear here. Full implementation in Epic 8.

{% endblock %} ``` --- ### Exact `app/blueprints/dashboard/routes.py` Update ```python from flask import render_template from app.blueprints.dashboard import dashboard_bp @dashboard_bp.route('/') def index(): """Dashboard placeholder — Story 8 implements the full dashboard.""" return render_template('dashboard/index.html', active_page='dashboard') ``` --- ### Exact `app/__init__.py` Error Handler Update In `create_app()`, replace the two error handlers at the bottom: ```python # BEFORE (Story 1.5 stub): @app.errorhandler(404) def not_found(e): return 'Not Found', 404 @app.errorhandler(500) def server_error(e): return 'Internal Server Error', 500 ``` ```python # AFTER (Story 2.1): @app.errorhandler(404) def not_found(e): return render_template('errors/404.html'), 404 @app.errorhandler(500) def server_error(e): return render_template('errors/500.html'), 500 ``` Also add `render_template` to the Flask import at the top of `create_app()` (or import it inside the error handlers — either works; importing inside the function avoids polluting the module namespace): ```python # Option A: add to module-level import (preferred) from flask import Flask, render_template # Option B: import inside factory function def create_app(config=None): from flask import render_template ... ``` Actually the simplest is to import at the top of `create_app()`: ```python def create_app(config=None): from flask import render_template app = Flask(__name__) ... ``` Or even simpler — since `render_template` is a top-level Flask import, add it to the existing `from flask import Flask` line: ```python from flask import Flask, render_template ``` --- ### Exact `tests/test_blueprints/test_base_template.py` Implementation ```python """ Smoke tests for base.html — AC 2, 3, 5, 6 (Story 2.1). Tests that: - GET / returns 200 with full HTML (not plain text) - All 8 nav sections are linked in the response - active_page='dashboard' marks the dashboard link with aria-current="page" - 404 renders an HTML template (not plain "Not Found" text) - All 4 flash categories render correctly """ import pytest class TestBaseTemplate: def test_index_returns_200_with_html(self, client): resp = client.get('/') assert resp.status_code == 200 assert b'` as landmark region Note: The inline `style=` attributes used in this story's base.html implementation are intentional placeholders. Story 2.3 adds `tokens.css` / `app.css` with proper Primer CSS classes. Story 2.3 can refactor `base.html` to use proper Primer class names (e.g., `ActionList`, `d-flex`) once the CSS is available. ### Files Modified in This Story | File | Status | Notes | |------|--------|-------| | `app/templates/base.html` | **MODIFY** | Replace stub with full implementation | | `app/templates/errors/404.html` | **MODIFY** | Replace stub with base.html-extending template | | `app/templates/errors/500.html` | **MODIFY** | Replace stub with base.html-extending template | | `app/__init__.py` | **MODIFY** | Add `render_template` import; update 404/500 handlers | | `app/blueprints/dashboard/routes.py` | **MODIFY** | Use render_template instead of plain text return | | `app/blueprints/dashboard/templates/dashboard/index.html` | **NEW** | Minimal dashboard template extending base.html | | `tests/test_blueprints/test_base_template.py` | **NEW** | Smoke tests for nav, active_page, error pages, flash | ## Dev Agent Record ### Agent Model Used claude-sonnet-4-6 ### Debug Log References - **DEBUG-001**: `TemplateNotFound: dashboard/index.html` during Task 8 test run. Root cause: `Blueprint('dashboard', __name__)` was missing `template_folder='templates'`. Fix: updated `app/blueprints/dashboard/__init__.py` to `Blueprint('dashboard', __name__, template_folder='templates')`. Blueprint-local templates require explicit `template_folder` declaration; without it Flask only searches the app-level `templates/` directory. ### Completion Notes List - Implemented full HTML5 shell in `base.html` with sidebar nav (240px fixed), skip-to-main accessibility link, flash message block (all 4 categories: success/error/warning/info), `{% block content %}`, and JS stub script tags. - Used hardcoded URL paths for 7 of 8 nav items (all except dashboard). Only `url_for('dashboard.index')` is safe because that is the only blueprint stub with a real named route function. Using `url_for()` for blueprints with no route functions raises `BuildError` at template render time. - `active_page` convention documented in Jinja2 comment block at top of `base.html` per AR-8. Every `render_template()` call must pass `active_page=''`. - Flash categories mapped to Primer CSS classes: `flash-success`, `flash-error`, `flash-warning`, and `flash` (base class only for 'info'). Role set to `alert` for errors, `status` for all others. - Error handlers updated in `app/__init__.py` to use `render_template('errors/404.html')` and `render_template('errors/500.html')`. - TDD: all 8 tests written and confirmed FAILING (red phase) before any template implementation. All 8 now PASS (green phase). No regressions — 45 passed, 1 skipped across full suite. - Flash message injection in tests uses `client.session_transaction()` to set `sess['_flashes'] = [(category, message)]` — Flask's internal storage format. ### File List - `app/blueprints/dashboard/templates/dashboard/index.html` — NEW - `app/blueprints/dashboard/__init__.py` — MODIFIED (added `template_folder='templates'`) - `app/blueprints/dashboard/routes.py` — MODIFIED (render_template + active_page) - `app/templates/base.html` — MODIFIED (full implementation replacing stub) - `app/templates/errors/404.html` — MODIFIED (full template replacing stub) - `app/templates/errors/500.html` — MODIFIED (full template replacing stub) - `app/__init__.py` — MODIFIED (render_template import + error handler templates) - `tests/test_blueprints/test_base_template.py` — NEW ### Change Log - 2026-05-27: Story 2.1 implemented — base.html shell, dashboard template, error pages, flash rendering, active_page convention, smoke tests. 45 passed, 1 skipped. Status → review.