MaxGhenis · Oct 9, 2026 · Oct 10, 2026 · Oct 10, 2026 · Oct 10, 2026 · Oct 10, 2026
diff --git a/README.md b/README.md
@@ -4,6 +4,7 @@ A comprehensive TAXSIM emulator using the PolicyEngine US federal and state tax
 
 ## Table of Contents
 - [Overview](#overview)
+- [Documentation](#documentation)
 - [Future plans and maintenance](#future-plans-and-maintenance)
 - [Quick Start](#quick-start)
 - [Installation](#installation)
@@ -41,6 +42,14 @@ This project provides a high-fidelity emulator for TAXSIM-35, leveraging PolicyE
 - **Flexible output options**: Standard, full, and text description output formats matching TAXSIM specifications
 - **YAML test generation**: Generate PolicyEngine test cases for reproducibility and validation
 
+## Documentation
+
+- [Input guide](docs/input-guide.md): every input column with its valid values, how blanks and unexpected values are treated, and a worked example that takes a survey file to taxes in Python, Stata and R.
+- [Design](docs/design.md): which engine computes each year, how inputs map to PolicyEngine variables, how outputs are assembled, versions and pinning, and known differences from TAXSIM.
+- [Security and deployment notes](docs/security-and-deployment.md): what uses the network and what doesn't, the full dependency list, the bundled TAXSIM executables, Python versions, and installing without internet access.
+
+The reference tables in these guides are generated from the code, and `tests/test_docs_reference.py` fails when they fall out of date.
+
 ## Future plans and maintenance
 
 We will keep powering the TAXSIM emulator for as long as people need it. Its backend may move to [Axiom](https://axiom.org), our next-generation rules engine, which encodes rules from the law with tests. If it does, the emulator still runs through PolicyEngine's wrappers, and the surfaces below stay backwards compatible. Using PolicyEngine directly adds capabilities beyond the TAXSIM format: benefit programs, and tax calculations that use variables TAXSIM doesn't support.
@@ -262,7 +271,7 @@ The dashboard provides an intuitive interface for researchers and analysts to ex
 
 ## Input Variables
 
-The emulator accepts CSV files with the following variables:
+The [input guide](docs/input-guide.md) is the complete reference, generated from the code. In brief, the emulator accepts CSV files with the following variables:
 
 ### Demographics
 

diff --git a/changelog.d/agency-docs.added.md b/changelog.d/agency-docs.added.md
@@ -0,0 +1 @@
+Add an input guide (every input column, how blanks and unexpected values are treated, and a worked custom-dataset example in Python, Stata and R), a design document, and security and deployment notes under `docs/`. Their reference tables are generated from the code, and new tests fail when they drift, when a run tries to open a network connection, or when the worked example stops running.
diff --git a/changelog.d/pbusinc-self-employment-tax.changed.md b/changelog.d/pbusinc-self-employment-tax.changed.md
@@ -0,0 +1 @@
+Document and test the difference between the emulator and the bundled TAXSIM-35 build in how they tax `pbusinc` and `sbusinc`: the emulator applies self-employment tax, as NBER's input documentation describes, and the build does not (#1254).
diff --git a/changelog.d/r-example-state-codes.fixed.md b/changelog.d/r-example-state-codes.fixed.md
@@ -0,0 +1 @@
+The R package's documentation examples now use the SOI codes for the states they name (5 for California, 33 for New York); they showed 6 (Colorado) and 36 (Ohio).
diff --git a/docs/dependencies/requirements-py3.10.txt b/docs/dependencies/requirements-py3.10.txt
diff --git a/docs/dependencies/requirements-py3.11.txt b/docs/dependencies/requirements-py3.11.txt
diff --git a/docs/dependencies/requirements-py3.12.txt b/docs/dependencies/requirements-py3.12.txt
diff --git a/docs/dependencies/requirements-py3.13.txt b/docs/dependencies/requirements-py3.13.txt
diff --git a/docs/dependencies/requirements-py3.14.txt b/docs/dependencies/requirements-py3.14.txt
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Add an input guide (every input column, how blanks and unexpected values are treated, and a worked custom-dataset example in Python, Stata and R), a design document, and security and deployment notes under `docs/`. Their reference tables are generated from the code, and new tests fail when they drift, when a run tries to open a network connection, or when the worked example stops running.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Document and test the difference between the emulator and the bundled TAXSIM-35 build in how they tax `pbusinc` and `sbusinc`: the emulator applies self-employment tax, as NBER's input documentation describes, and the build does not (#1254).
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		The R package's documentation examples now use the SOI codes for the states they name (5 for California, 33 for New York); they showed 6 (Colorado) and 36 (Ohio).