Polish public portfolio docs

Author: CSHF1885

CHANGELOG.md

@@ -25,6 +25,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Scope 3 purchase-ledger example CSV for quick manual testing.
 - GitHub Actions workflow that runs the pytest suite on pushes to `main` and pull requests.
 - Git attributes file to keep text file line endings predictable across Windows and Linux CI.
+- Reviewer-facing portfolio summary in `docs/portfolio-summary.md`.
+- README badges, preview section, and reviewer start guide.
 
 ### Changed
 - Softened documentation claims in `README.md` to clarify prototype status and avoid unsupported certainty.
@@ -34,3 +36,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Tightened README language around framework alignment, factor-library completeness, and formal reporting limitations.
 - Added a faster reviewer-oriented README path with quick-start commands and example-data notes.
 - Clarified Scope 3 upload messaging so unmapped categories are not implied to be successfully mapped.
+
+### Release Checklist
+- [ ] Confirm GitHub Actions test workflow passes on `main`.
+- [ ] Confirm README preview image renders on GitHub.
+- [ ] Publish GitHub release `v0.1.0-carbonaware-mvp`.
+- [ ] Use release title `CarbonAware MVP v0.1.0`.
+- [ ] Include release notes: Initial public MVP release featuring Scope 1, Scope 2, and educational spend-based Scope 3 screening workflows.

README.md

@@ -1,6 +1,11 @@
 # Framework-Aligned Emissions Calculator (CarbonAware MVP)
 
-A lightweight, testable, local-first greenhouse gas (GHG) accounting tool built to convert facility operational activity data into estimated metric tons of carbon dioxide equivalent ($CO_2e$).
+![Tests](https://github.com/coreytshaffer/framework-aligned-emissions-calculator/actions/workflows/tests.yml/badge.svg)
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+![Status](https://img.shields.io/badge/status-MVP-green)
+
+A local-first greenhouse gas emissions calculator that turns facility activity data into transparent Scope 1, Scope 2, and educational Scope 3 screening estimates.
 
 This prototype is designed around the **Greenhouse Gas Protocol Corporate Accounting and Reporting Standard** boundary concepts, separating direct operational emissions (Scope 1), indirect purchased-energy emissions (Scope 2), and an educational spend-based Scope 3 screening workflow. It is not a compliance or certification system.
 
@@ -13,6 +18,46 @@ This prototype is designed around the **Greenhouse Gas Protocol Corporate Accoun
 ---
 
 ## 📖 Table of Contents
+1. [Preview](#-preview)
+2. [Reviewer Start Here](#-reviewer-start-here)
+3. [Core Features](#-core-features)
+4. [Accounting Framework & Methodology](#-accounting-framework--methodology)
+5. [Project Directory Architecture](#-project-directory-architecture)
+6. [Quick Start](#-quick-start)
+7. [Installation & Setup Guide](#-installation--setup-guide)
+8. [Running the Application](#-running-the-application)
+9. [Executing the Test Suite](#-executing-the-test-suite)
+10. [Example Data](#-example-data)
+11. [Operational Assumptions & Boundaries](#-operational-assumptions--boundaries)
+12. [Emission Factors Reference Guide](#-emission-factors-reference-guide)
+13. [Future Roadmap & Architectural Enhancements](#-future-roadmap--architectural-enhancements)
+
+---
+
+## 🖼️ Preview
+
+![CarbonAware MVP dashboard preview](docs/images/dashboard-preview.png)
+
+---
+
+## 🔎 Reviewer Start Here
+
+If you are reviewing this repository quickly:
+
+1. Read the mandatory disclaimer above.
+2. Review `data/emission_factors.json` and `data/scope3_supply_chain_factors.json`.
+3. Inspect `src/emissions_calculator/calculator.py` for Scope 1/2 logic.
+4. Inspect `src/emissions_calculator/scope3_calculator.py` for Scope 3 spend-based screening.
+5. Run `python -m pytest tests/ -q`.
+6. Launch the Streamlit app with `python -m streamlit run app.py`.
+7. Test `examples/sample_facility_inputs.csv`.
+8. Test `examples/sample_scope3_purchases.csv`.
+
+For a concise portfolio explanation, see `docs/portfolio-summary.md`.
+
+---
+
+## 📖 Detailed Table of Contents
 1. [Core Features](#-core-features)
 2. [Accounting Framework & Methodology](#-accounting-framework--methodology)
 3. [Project Directory Architecture](#-project-directory-architecture)
@@ -65,6 +110,10 @@ framework-aligned-emissions-calculator/
   ├── data/
   │   ├── emission_factors.json     # Local database of Scope 1/2 conversion factors and citations
   │   └── scope3_supply_chain_factors.json # Small educational subset of EPA Supply Chain v1.2 factors
+  ├── docs/
+  │   ├── portfolio-summary.md      # Reviewer-oriented project summary
+  │   └── images/
+  │       └── dashboard-preview.png # README dashboard preview image
   ├── src/
   │   └── emissions_calculator/
   │       ├── __init__.py           # Package interfaces exposure

docs/images/dashboard-preview.png

@@ -0,0 +1,54 @@
+# CarbonAware MVP Portfolio Summary
+
+## What This Project Does
+
+CarbonAware is a local-first greenhouse gas emissions calculator that converts facility activity data into estimated metric tons of carbon dioxide equivalent (CO2e).
+
+It currently supports:
+
+- Scope 1 stationary combustion examples: natural gas and diesel fuel.
+- Scope 2 purchased electricity using a generic national grid-average factor.
+- Scope 3 Category 1 purchased goods and services using an educational spend-based screening workflow.
+
+## Why The Scope Boundaries Matter
+
+Scope separation is the core accounting concept this project demonstrates.
+
+- Scope 1 tracks direct emissions from sources owned or controlled by the facility.
+- Scope 2 tracks indirect emissions from purchased energy.
+- Scope 3 tracks value-chain activities outside direct operations, such as supplier purchases.
+
+Keeping these categories separate prevents misleading totals and makes the assumptions behind each estimate easier to inspect.
+
+## Production-Like Parts
+
+- Calculation logic is separated from the Streamlit interface.
+- Emission factors live in JSON data files instead of being hardcoded into UI controls.
+- Exports include factor provenance fields such as source name, factor value, factor year, and factor file.
+- Pytest tests cover core math, scope categorization, factor loading, negative inputs, missing factors, and Scope 3 mapping behavior.
+- GitHub Actions runs the test suite on pushes and pull requests.
+
+## Educational Or Simplified Parts
+
+- The tool is not a certified greenhouse gas inventory system.
+- Scope 2 uses a generic electricity factor rather than regional eGRID subregions.
+- Scope 3 uses a small educational subset of EPA supply-chain factors, not the full factor library.
+- Spend-based Scope 3 estimates are screening estimates, not supplier-specific primary-data accounting.
+- Market-based Scope 2 accounting, renewable energy certificates, and formal inventory management workflows are out of scope for this MVP.
+
+## What Reviewers Should Inspect First
+
+1. `README.md` for the project purpose, disclaimer, setup, and limitations.
+2. `src/emissions_calculator/calculator.py` for Scope 1 and Scope 2 calculation logic.
+3. `src/emissions_calculator/scope3_calculator.py` for spend-based Scope 3 logic and unmapped-spend warnings.
+4. `data/emission_factors.json` and `data/scope3_supply_chain_factors.json` for factor metadata.
+5. `tests/` for automated verification.
+6. `examples/` for CSV input formats.
+
+## Suggested Release Title
+
+CarbonAware MVP v0.1.0
+
+## Suggested Release Notes
+
+Initial public MVP release featuring Scope 1, Scope 2, and educational spend-based Scope 3 screening workflows with provenance-friendly factor metadata, CSV exports, pytest coverage, and GitHub Actions CI.