Why
The README currently has zero badges. For a portfolio-grade repo demonstrating the full lifecycle (data platform → forecasting → registry → RAG → agents → React dashboard), a tasteful badge surface at the top of the README is high-leverage discoverability:
- Reviewers see the tech stack at a glance (the README's "Features" + "Project Structure" lists are great but require reading)
- License / version / CI status are conventional GitHub-README metadata that scanners and tools rely on
- The visual style (shields.io `for-the-badge` variant — orange/red HTML5-shield example) is the de-facto standard on portfolio repos in 2026
Scope
Insert one badges block between the tagline (`Portfolio-grade end-to-end retail demand forecasting system.`) and the `## Features` heading in `README.md`. Five rows:
- Status (4 badges): License (MIT) · Version (dynamic from GitHub releases) · CI (dynamic from `ci.yml` on `dev`) · Python 3.12+
- Backend: FastAPI · Pydantic v2 · SQLAlchemy 2.0 · PostgreSQL 16 · pgvector · Alembic · structlog
- Frontend: React 19 · TypeScript · Vite 7 · Tailwind CSS 4 · shadcn/ui · TanStack Query
- ML / AI: scikit-learn · LightGBM · XGBoost · PydanticAI · OpenAI · Anthropic · Ollama
- Tooling: Docker · uv · pnpm · GitHub Actions · ruff · mypy · pytest
All badges use `style=for-the-badge` and match brand colors (HTML5 orange equivalent for each tech). Dynamic badges (CI, version) read from this repo so they self-update without further edits.
Out of scope
- No SVG/PNG asset commits — every badge resolves through shields.io
- No changes to `docs/` deep-dive files — those are reference docs, not portfolio surface
- No frontend / app code changes
Approach
- Branch: `docs/readme-tech-stack-badges` off `dev`
- One commit: `docs(docs): add tech-stack badges to README (shields.io for-the-badge) (#NNN)`
- Validation: curl-HEAD each shields URL for 200; render check via the GitHub markdown preview on the PR
References
Why
The README currently has zero badges. For a portfolio-grade repo demonstrating the full lifecycle (data platform → forecasting → registry → RAG → agents → React dashboard), a tasteful badge surface at the top of the README is high-leverage discoverability:
Scope
Insert one badges block between the tagline (`Portfolio-grade end-to-end retail demand forecasting system.`) and the `## Features` heading in `README.md`. Five rows:
All badges use `style=for-the-badge` and match brand colors (HTML5 orange equivalent for each tech). Dynamic badges (CI, version) read from this repo so they self-update without further edits.
Out of scope
Approach
References