fix: README.md file

Author: KyleFe

README.md

@@ -99,7 +99,7 @@ folder with that name and generates everything inside it.
 Copier asks a series of questions to configure your project. Each question
 has a default value -- press Enter to accept it, or type your own answer.
 ```
-Project name (e.g. inflation-analysis)
+Project name (e.g. inflation-db)
 > inflation-analysis
 
 Python package name
@@ -112,10 +112,10 @@ Author email
 > kyle.fe0212@gmail.com
 
 Python version
-> 3.11
+> 3.13
 
 Short project description
-> Modelling exchange rate pass-through to core inflation
+> Analysis of exchange rate pass-through to core inflation
 
 License (MIT / Apache-2.0 / Proprietary)
 > MIT
@@ -146,7 +146,7 @@ Two of the prompts can be confusing at first:
 the folder name, `pyproject.toml`, `README.md`, and documentation. It
 typically uses hyphens as separators.
 ```
-Example: inflation-db
+Example: inflation-analysis
 ```
 
 **Python package name** is the importable name of your package in Python
@@ -166,25 +166,150 @@ uses underscores (how Python refers to it).
 
 ---
 
-### Step 4 -- Set up your new project
+### Step 4 -- Set up your virtual environment and install dependencies
 
-Navigate into your newly generated project folder and run the setup steps:
+After Copier generates your project, navigate into it and run:
 ```bash
 cd your-project-name
-
-# Install all dependencies into a local .venv folder
 poetry install --with dev
+```
+
+This does three things:
+
+1. Creates a `.venv/` folder inside your project -- this is your virtual
+   environment, an isolated Python installation specific to this project.
+   Every project gets its own `.venv/` so packages never conflict across
+   projects.
+
+2. Installs all packages listed in `pyproject.toml` into `.venv/`.
+
+3. Generates `poetry.lock` -- a file that pins the exact version of every
+   package installed, including transitive dependencies. This ensures anyone
+   else who clones the project gets identical installs. This file should be
+   committed to Git.
+
+After running `poetry install`, your project folder will contain:
+```
+your-project-name/
+├── .venv/          -- virtual environment (gitignored, never committed)
+├── poetry.lock     -- lockfile (committed to Git)
+```
+
+VS Code will detect `.venv/` automatically and use it as the Python
+interpreter for the project.
+
+---
+
+## Default packages
+
+Every project generated from this template includes a baseline set of
+packages that cover the most common development needs:
+
+### Data manipulation and analysis
+| Package | Purpose |
+|---|---|
+| numpy | Numerical computing, arrays, linear algebra |
+| pandas | DataFrames, tabular data manipulation |
+| scipy | Scientific computing, statistics, optimisation |
+| statsmodels | Statistical models and hypothesis testing |
+| scikit-learn | Machine learning models and utilities |
+
+### Visualisation
+| Package | Purpose |
+|---|---|
+| matplotlib | Core plotting library |
+| matplotlib-inline | Inline plot rendering in notebooks |
+| seaborn | Statistical visualisation built on matplotlib |
+| plotly | Interactive charts and dashboards |
+
+### Notebooks and kernels
+| Package | Purpose |
+|---|---|
+| ipykernel | Jupyter kernel support |
+| jupyter | Jupyter notebook environment |
+| jupyterlab | Modern Jupyter interface |
+
+### Spreadsheet and file handling
+| Package | Purpose |
+|---|---|
+| openpyxl | Read and write Excel files |
+| et-xmlfile | XML file handling (openpyxl dependency) |
+| fonttools | Font file handling |
+| packaging | Version and package utilities |
+| pyarrow | Apache Arrow, Parquet file support |
+
+### Utilities
+| Package | Purpose |
+|---|---|
+| loguru | Simple, powerful logging |
+| tqdm | Progress bars for loops |
+| rich | Rich text and formatting in the terminal |
+| python-dateutil | Extended date and time utilities |
+
+### Conditional packages (added based on your answers)
+| Package | Condition |
+|---|---|
+| duckdb | Added when `use_duckdb = yes` |
+| python-dotenv | Added when `use_dotenv = yes` |
+| nbstripout | Added when `use_notebooks = yes` |
+| mkdocs-material, mkdocstrings | Added when `use_docs = yes` |
+
+---
+
+## Adding packages to your project
+
+The default packages cover common needs, but every project will require
+additional dependencies specific to what it does. Use Poetry to add them:
+```bash
+# Add a core dependency (used by the project itself)
+poetry add requests
+poetry add httpx
+poetry add sqlalchemy
+
+# Add a dev-only dependency (only used during development)
+poetry add pytest-mock --group dev
+poetry add ipdb --group dev
+
+# Add a docs dependency
+poetry add mkdocs-awesome-pages-plugin --group docs
+```
+
+When you run `poetry add`, Poetry automatically:
+- Adds the package to `pyproject.toml`
+- Resolves a compatible version
+- Installs it into `.venv/`
+- Updates `poetry.lock`
+
+To remove a package:
+```bash
+poetry remove requests
+```
+
+To see all installed packages:
+```bash
+poetry show
+```
+
+---
 
-# Install pre-commit hooks so checks run on every git commit
+### Step 5 -- Install pre-commit hooks
+```bash
 poetry run pre-commit install
+```
 
-# Confirm everything is working
+This activates the pre-commit hooks so that every time you run `git commit`,
+Ruff and Mypy run automatically and block the commit if there are any issues.
+You only need to run this once per project, after cloning or generating it.
+
+### Step 6 -- Confirm everything is working
+```bash
 make ci
 ```
 
-If `make ci` passes with no errors, your project is fully set up.
+If this passes with no errors, your project is fully set up and ready for
+development.
 
-### Step 5 -- Initialise Git and push to GitHub
+### Step 7 -- Initialise Git and push to GitHub
 ```bash
 git init
 git branch -m master main
@@ -215,7 +340,9 @@ your-project-name/
 │   │   ├── bug_report.yml
 │   │   └── feature_request.yml
 │   └── PULL_REQUEST_TEMPLATE.md
+├── .venv/                       # virtual environment (auto-created, gitignored)
 ├── pyproject.toml               # Poetry, Ruff, Mypy, pytest config
+├── poetry.lock                  # exact dependency versions (commit this)
 ├── .pre-commit-config.yaml      # pre-commit hooks
 ├── .gitignore
 ├── Makefile                     # shorthand commands
@@ -226,17 +353,94 @@ your-project-name/
 
 ---
 
-## Common commands (in generated projects)
+## Makefile commands
+
+The `Makefile` provides shorthand commands so you do not have to remember or
+type out full tool invocations. Instead of `poetry run ruff check .` you just
+run `make lint`.
 
-All projects include a `Makefile` with these shortcuts:
+### Command reference
+```bash
+make install
+```
+Runs `poetry install --with dev`. Use this when setting up the project for
+the first time, or after pulling changes that added new dependencies to
+`pyproject.toml`. It installs everything into `.venv/` and updates
+`poetry.lock`.
 ```bash
-make install    # install all dependencies via Poetry
-make lint       # run Ruff linter
-make format     # run Ruff formatter
-make typecheck  # run Mypy type checker
-make test       # run pytest with coverage report
-make ci         # run all of the above in sequence
+make lint
 ```
+Runs `ruff check .`. Scans all Python files for code quality issues --
+unused imports, bad patterns, style violations. Does not modify any files,
+only reports problems. Use this to see what needs fixing before committing.
+```bash
+make format
+```
+Runs `ruff format .`. Automatically rewrites your Python files to conform
+to the project's style rules -- indentation, line length, quote style, etc.
+Run this before committing to ensure consistent formatting.
+```bash
+make typecheck
+```
+Runs `mypy src`. Statically analyses your code for type errors without
+executing it. Catches bugs like passing the wrong type to a function before
+they cause a runtime failure. Run this after writing new code or updating
+function signatures.
+```bash
+make test
+```
+Runs `pytest` with coverage reporting. Executes all tests in `tests/unit/`
+and `tests/integration/`, prints which lines of code are not covered by
+tests, and fails if coverage drops below 80%. Run this to verify nothing is
+broken before committing or opening a PR.
+```bash
+make ci
+```
+Runs lint, format check, typecheck, and test in sequence. This mirrors
+exactly what GitHub Actions runs on every push. If `make ci` passes locally,
+your push will pass CI. Run this before pushing to catch issues early.
+
+---
+
+### Daily development workflow
+
+Here is how the Makefile commands fit into a typical development session:
+
+**Starting work**
+```bash
+# If dependencies have changed since you last worked on the project
+make install
+```
+
+**While writing code**
+```bash
+# After writing a new function or module
+make typecheck       # catch type errors immediately
+
+# Before committing
+make format          # auto-fix formatting
+make lint            # check for any remaining issues
+make test            # confirm nothing is broken
+```
+
+**Before pushing or opening a PR**
+```bash
+# Run the full suite to confirm everything passes
+make ci
+```
+
+**Typical commit rhythm**
+```bash
+make format          # fix formatting automatically
+make ci              # confirm everything passes
+git add .
+git commit -m "feat: describe what you did"
+git push
+```
+
+The pre-commit hooks will also run Ruff and Mypy automatically on
+`git commit`, so `make format` and `make lint` act as a first pass before
+the hooks fire.
 
 ---
 

pyproject.toml

@@ -8,6 +8,38 @@ packages = [{include = "{{ package_name }}", from = "src"}]
 
 [tool.poetry.dependencies]
 python = "^{{ python_version }}"
+
+# Data manipulation & analysis
+numpy = ">=1.26"
+pandas = ">=2.0"
+scipy = ">=1.12"
+statsmodels = ">=0.14"
+scikit-learn = ">=1.4"
+
+# Visualisation
+matplotlib = ">=3.8"
+matplotlib-inline = ">=0.1"
+seaborn = ">=0.13"
+plotly = ">=5.20"
+
+# Notebooks & kernels
+ipykernel = ">=6.0"
+jupyter = ">=1.0"
+jupyterlab = ">=4.0"
+
+# Spreadsheet & file handling
+openpyxl = ">=3.1"
+et-xmlfile = ">=1.1"
+fonttools = ">=4.50"
+packaging = ">=24.0"
+pyarrow = ">=15.0"
+
+# Utilities
+loguru = ">=0.7"
+tqdm = ">=4.66"
+rich = ">=13.0"
+python-dateutil = ">=2.9"
+
 {% if use_duckdb %}
 duckdb = ">=0.10.0"
 {% endif %}
@@ -22,7 +54,6 @@ ruff = ">=0.4"
 mypy = ">=1.0"
 pre-commit = ">=3.0"
 {% if use_notebooks %}
-jupyter = ">=1.0"
 nbstripout = ">=0.7"
 {% endif %}