feat: Phase 6 — documentation, PNG icons, and PWA polish

.github/workflows/deploy.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - main
+  workflow_dispatch:
 
 permissions:
   contents: read

.gitignore

@@ -34,3 +34,7 @@ test-results/
 # Logs
 *.log
 npm-debug.log*
+
+# Lighthouse reports (local only)
+lighthouse-report.json
+lighthouse-report.html

CONTRIBUTING.md

@@ -0,0 +1,76 @@
+# Contributing to SAE Syntax Generator
+
+Thank you for your interest in improving this tool. Contributions from statisticians,
+developers, and domain experts are all welcome.
+
+---
+
+## Code of conduct
+
+Be respectful and constructive. We follow the
+[Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/)
+(v2.1). Harassment of any kind will not be tolerated.
+
+---
+
+## How to open an issue
+
+Go to [GitHub Issues](https://github.com/bakodramane/SAE_Syntax_Generator/issues) and choose
+the most appropriate template:
+
+- **Bug report** — something does not work as documented.
+- **Method correction** — a formula, reference, or caveat in a catalogue entry is wrong.
+- **New method request** — a SAE method is missing from the catalogue.
+- **Documentation improvement** — unclear or missing explanation.
+
+Please include: the browser and OS, the exact steps to reproduce (if a bug), and what you
+expected vs. what happened.
+
+---
+
+## How to submit a pull request
+
+1. Fork the repository and clone your fork.
+2. Create a branch: `git checkout -b fix/my-fix` or `feat/my-feature`.
+3. Make your changes (see *Coding conventions* below).
+4. Run `npm run build`, `npm test`, and `npm run lint` — all must pass.
+5. Open a pull request against `main` with a clear description of what changed and why.
+
+---
+
+## Adding a new SAE method
+
+This is the most common type of contribution. See
+[docs/adding-a-method.md](docs/adding-a-method.md) for a complete step-by-step guide. You
+do not need to touch the engine code; you only create one TypeScript catalogue file.
+
+---
+
+## Coding conventions
+
+- **TypeScript strict mode** — no `any` types; `tsc --noEmit` must pass.
+- **Tailwind CSS** — use utility classes; do not add custom CSS unless unavoidable.
+- **UK English** with the Oxford comma in all user-facing text and documentation.
+- **No comments on obvious code** — only add a comment when the *why* is non-obvious.
+- **Conventional commits** — `feat:`, `fix:`, `test:`, `docs:`, `chore:` prefixes.
+- **No self-merging** — open a pull request and wait for review.
+
+---
+
+## Local development
+
+```bash
+npm install
+npm run dev          # development server with hot reload
+npm test             # Vitest unit tests
+npx playwright test  # end-to-end smoke test
+npm run lint         # ESLint
+npm run build        # production build
+```
+
+---
+
+## Licence
+
+By contributing you agree that your work will be released under the
+[MIT Licence](LICENSE).

README.md

@@ -1,7 +1,105 @@
 # SAE Syntax Generator
 
-A browser-only, offline-capable expert system that recommends small area estimation (SAE) methods and generates ready-to-run R and Stata scripts from a description of your survey microdata.
+A browser-only, offline-capable expert system that recommends small area estimation (SAE)
+methods and generates ready-to-run R and Stata scripts from a description of your survey
+microdata and auxiliary data. No data leaves your machine.
 
 **Live app:** https://bakodramane.github.io/SAE_Syntax_Generator/
 
-> Full setup instructions coming in Phase 6.
+---
+
+## What it does
+
+Small area estimation bridges the gap between nationally representative surveys and the need
+for reliable estimates at district, county, or municipality level. This tool:
+
+1. Lets you describe your data (variable types, what auxiliary data you have, Stata version).
+2. Recommends the most appropriate SAE method from a catalogue of 16 methods.
+3. Generates a complete, commented R script and Stata `.do` file — ready to run with your
+   real variable names filled in.
+
+Target users: statisticians in national statistical offices and development organisations,
+including those working in countries where Stata 14 is the installed standard.
+
+---
+
+## Quick start (local development)
+
+```bash
+git clone https://github.com/bakodramane/SAE_Syntax_Generator.git
+cd SAE_Syntax_Generator
+npm install
+npm run dev          # opens http://localhost:5173/SAE_Syntax_Generator/
+```
+
+Requirements: Node.js ≥ 18.
+
+---
+
+## Running tests
+
+```bash
+npm test             # Vitest unit tests (catalogue schema + engine logic)
+npx playwright test  # Playwright end-to-end smoke test
+```
+
+---
+
+## Building for production
+
+```bash
+npm run build        # outputs to dist/
+npx vite preview     # serve the built app locally
+```
+
+---
+
+## Deployment
+
+The app deploys automatically to GitHub Pages on every merge to `main` via the
+`.github/workflows/deploy.yml` workflow. No manual steps are required.
+
+To deploy a fork to your own GitHub Pages, enable Pages (Settings → Pages → Source: GitHub
+Actions) and push to your `main` branch.
+
+---
+
+## Adding a new SAE method
+
+See [docs/adding-a-method.md](docs/adding-a-method.md) for a step-by-step guide. No engine
+code needs to change — you only create one TypeScript file in `src/catalogue/`.
+
+---
+
+## Stata v14 compatibility
+
+See [docs/stata-v14-notes.md](docs/stata-v14-notes.md) for a full breakdown of which methods
+work on Stata 14, which fall back to the `mixed` command, and which require R.
+
+---
+
+## Project structure
+
+```
+src/
+  catalogue/      # One .ts file per SAE method (human-editable)
+  engine/         # Recommender and code-generation logic
+  types/          # Shared TypeScript interfaces
+docs/
+  adding-a-method.md   # Guide for contributing new methods
+  stata-v14-notes.md   # Stata version compatibility reference
+  SAE-CATALOGUE.md     # Full method taxonomy and design spec
+  PHASES.md            # Build plan and acceptance criteria
+```
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).