diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..bb9b8023
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,61 @@
+# Contributing to policyengine
+
+Thank you for your interest in contributing! This page covers how to report problems, get support, and contribute code. For the full development guide (architecture, CI, releases), see [docs/dev.md](docs/dev.md).
+
+## Reporting issues
+
+Please report bugs and request features through [GitHub issues](https://github.com/PolicyEngine/policyengine.py/issues). For bugs, include:
+
+- What you ran (a minimal code snippet is ideal)
+- What you expected and what happened instead, including the full traceback
+- Your `policyengine` version (`pip show policyengine`) and Python version
+
+## Getting support
+
+- Open a [GitHub issue](https://github.com/PolicyEngine/policyengine.py/issues) with a usage question
+- Email [hello@policyengine.org](mailto:hello@policyengine.org)
+
+## Development setup
+
+```bash
+git clone https://github.com/PolicyEngine/policyengine.py.git
+cd policyengine.py
+uv pip install -e ".[dev]"
+```
+
+This installs the shared analysis layer, both country model extras, and the dev dependencies used in CI (pytest, ruff, mypy, towncrier).
+
+Tests require a `HUGGING_FACE_TOKEN` environment variable for downloading datasets:
+
+```bash
+export HUGGING_FACE_TOKEN=hf_...
+make test
+```
+
+Common commands:
+
+```bash
+make format           # ruff format
+make test             # pytest with coverage
+make docs             # build static Quarto HTML docs
+make docs-serve       # preview the docs locally
+```
+
+## Pull requests
+
+1. Fork the repository (or create a branch, if you have write access) and make your changes.
+2. Add a changelog fragment describing the change:
+
+   ```bash
+   # Fragment types: breaking, added, changed, fixed, removed
+   echo "Description of change" > changelog.d/my-branch.fixed.md
+   ```
+
+3. Run `make format` and `make test` locally.
+4. Open a pull request. CI runs lint/format checks, tests on Python 3.13 and 3.14, and a docs build; all required checks must pass before merge.
+
+On merge, the versioning workflow bumps the version, builds the changelog, and creates a GitHub Release.
+
+## Code of conduct
+
+All participants are expected to follow our [Code of Conduct](CODE_OF_CONDUCT.md).
diff --git a/README.md b/README.md
index 4f0d009f..14591a57 100644
--- a/README.md
+++ b/README.md
@@ -69,9 +69,9 @@ population examples. To download the raw `.h5` file directly, see
 ## Documentation
 
 **Core concepts:**
-- [Core concepts](docs/core-concepts.md): Architecture, datasets, simulations, outputs
-- [UK tax-benefit model](docs/country-models-uk.md): Entities, parameters, examples
-- [US tax-benefit model](docs/country-models-us.md): Entities, parameters, examples
+- [Microsimulation](docs/microsim.md): Datasets, simulations, outputs, performance
+- [Country models](docs/countries.md): UK and US entities, defaults, and differences
+- [Model architecture](docs/methodology/model-architecture.md): How rules, data, and simulations fit together
 
 **Examples:**
 - `examples/income_distribution_us.py`: Analyse benefit distribution by decile
diff --git a/changelog.d/fix-joss-review-paper-readme.fixed.md b/changelog.d/fix-joss-review-paper-readme.fixed.md
new file mode 100644
index 00000000..1c3c088b
--- /dev/null
+++ b/changelog.d/fix-joss-review-paper-readme.fixed.md
@@ -0,0 +1 @@
+Fixed broken README links (Documentation core-concepts pages and CONTRIBUTING.md), added a CONTRIBUTING.md contributor guide, and fixed JOSS paper rendering (duplicated figure caption prefix and BibTeX institution fields split on 'and').
diff --git a/paper.bib b/paper.bib
index 2657c605..37450bbd 100644
--- a/paper.bib
+++ b/paper.bib
@@ -117,7 +117,7 @@ @misc{frs2020
 @techreport{niesr2025living,
   title={{UK} Living Standards Review 2025},
   author={Mosley, Max and Wattam, Ryan and Vincent, Carol},
-  institution={National Institute of Economic and Social Research},
+  institution={{National Institute of Economic and Social Research}},
   year={2025},
   url={https://niesr.ac.uk/publications/uk-living-standards-review-2025}
 }
@@ -226,7 +226,7 @@ @misc{pe_usc
 @techreport{beeck2023rac,
   title={Exploring Rules Communication: Moving Beyond Static Documents to Standardized Code for {U.S.} Public Benefits Programs},
   author={Kennan, Ariel and Singh, Lisa and Dammholz, Bianca and Sengupta, Keya and Yi, Jason},
-  institution={Beeck Center for Social Impact and Innovation, Georgetown University},
+  institution={{Beeck Center for Social Impact and Innovation, Georgetown University}},
   year={2023},
   month={6},
   url={https://beeckcenter.georgetown.edu/report/exploring-rules-communication-moving-beyond-static-documents-to-standardized-code-for-u-s-public-benefits-programs/}
@@ -235,7 +235,7 @@ @techreport{beeck2023rac
 @techreport{beeck2025ai,
   title={{AI}-Powered Rules as Code: Experiments with Public Benefits Policy},
   author={Kennan, Ariel and Garcia Guevara, Alessandra and Goodman, Jason},
-  institution={Beeck Center for Social Impact and Innovation, Georgetown University},
+  institution={{Beeck Center for Social Impact and Innovation, Georgetown University}},
   year={2025},
   month={3},
   url={https://beeckcenter.georgetown.edu/report/ai-powered-rules-as-code-experiments-with-public-benefits-policy/}
diff --git a/paper.md b/paper.md
index c469bf0e..b2add309 100644
--- a/paper.md
+++ b/paper.md
@@ -65,7 +65,7 @@ The PolicyEngine software stack has four components. `policyengine-core` provide
 
 This architecture reflects two deliberate trade-offs. Keeping country statutory rules in separate packages, rather than bundling them into a monolithic tool, lets each country model release independently; the cost is that `policyengine` must track and certify compatible combinations. Modeling reforms statically, with optional post-hoc behavioral responses, gives fast and deterministic baselines at the expense of general equilibrium effects, which are better suited to dedicated macroeconomic models.
 
-![Figure 1: PolicyEngine runtime architecture. Inputs (rules, microdata, and behavioral responses) flow through the simulation pipeline to produce structured outputs.](architecture.png){width="100%"}
+![PolicyEngine runtime architecture. Inputs (rules, microdata, and behavioral responses) flow through the simulation pipeline to produce structured outputs.](architecture.png){width="100%"}
 
 For reproducibility, the top-level package acts as a certification boundary across these components. Country data repositories build immutable microdata artifacts and publish release manifests with checksums and the country-model version used during data construction. Bundled country manifests in `policyengine` then certify the runtime bundle: the runtime country-model version, the microdata-package release, the dataset artifact, and the compatibility basis linking that runtime model to the build-time data provenance. Analysts can request a dataset such as `enhanced_frs_2023_24`, while the runtime resolves it to a specific versioned artifact and records both runtime and build-time provenance. The same certification record can be emitted as a TRACE Transparent Research Object declaration [@trace_trov], so the internal bundle and data manifests remain the operational source of truth while a standardized signed provenance document is available for external exchange.