Add READMEs.

diff --git a/README.md b/README.md
new file mode 100644 (file)
index 0000000..6940232
--- /dev/null
+++ b/README.md
@@ -0,0 +1,76 @@
+# ustaxlib
+
+This project provides modules for modeling the US tax system for individuals. The `ustaxlib/core`
+module provides a generic framework for defining tax return forms. And peer modules like
+`ustaxlib/fed2019` provide forms for specific revisions/years of tax returns.
+
+There is a peer project [ustaxviewer](https://github.com/rsesek/ustaxviewer) that can render a tax
+return as HTML.
+
+## Core
+
+The `ustaxlib/core` module provides a very simple data model for tax returns:
+
+- `TaxReturn`: An abstract class that is the root of the object graph. It holds at least one
+    `Person` and several `Form`s.
+- `Person`: A person for whom the `TaxReturn` is being computed.
+- `Form`: An abstract class that represents a single form in the tax system. Holds one or more
+    `Line`s. `Form`s optionally take an input object, the values of which are typically exposed
+    by an `InputLine`.
+- `Line`: An abstract class, with several concrete subclasses provided by core, that corresponds to
+    a single line on a tax system form. A `Line`'s parametrized type corresponds to the type of
+    value that is computed by it. Examples are:
+   - `ComputedLine`: Uses a function to produce a value.
+   - `ReferenceLine`: Returns the value of a specific line of a `Form`.
+   - `InputLine`: Returns the value of a `Form`'s input.
+   - `AccumulatorLine`: Some `Form`s can have multiple instances in a `TaxReturn`, and this line
+       sums a specific line for all instances of that form type.
+
+The core module provides what is effectively a specialized spreadsheet. Rather than sheets and rows,
+there are forms and lines. A `TaxReturn` provides a way to find forms by their type, and a `Form`
+provides access to the values computed by `Line`s.
+
+## Models
+
+Currently ustaxlib supports the following models:
+
+- [**fed2019**](src/fed2019/README.md)
+
+## Getting Started
+
+To start using the software, create a new, private NPM project, and install the necessary
+dependencies. This will also install the HTML viewer. Then copy an example file and run the viewer
+with it.
+
+    npm init
+    # answer questions
+    npm i ts-node typescript ustaxlib ustaxviewer
+    cp node_modules/ustaxlib/examples/fed2019.ts .
+    npx ustaxviewer-ts fed2019.ts
+
+## Contributing
+
+Contributions to address bugs and not-supported forms or situations are welcome. Only forms for
+individuals are accepted (no estates, trusts, businesses, etc.). Please include tests with your
+contribution and keep your commit history clean.
+
+Issues should be filed on [GitHub](https://github.com/rsesek/ustaxlib).
+
+## Anticipated Answers
+
+### Why?
+
+This project can be used to check the values produced by other tax software, to model expected tax
+liability throughout the year, or to learn about the US tax system.
+
+### Should I use this to file my own tax returns?
+
+Please, heck no. There are guaranteed to be bugs in this software. The models do not support every
+and situation. This software is provided with no warranty.
+
+### How well does it work?
+
+I have run my personal income tax information through the fed2019 model and received identical
+results to the commercial tax prep software I'm using to actually file my tax returns. My situation
+is moderately complex, and it exercises most of the forms in the fed2019 module. Your results may
+vary.

diff --git a/src/fed2019/README.md b/src/fed2019/README.md
new file mode 100644 (file)
index 0000000..d29ece4
--- /dev/null
+++ b/src/fed2019/README.md
@@ -0,0 +1,42 @@
+# ustaxlib/fed2019
+
+Forms for US tax year 2019.
+
+# Supported Scenarios
+
+This supports the following filing statues:
+
+- Single
+- Married Filing Joint
+- Married Filing Separate
+
+# Supported Forms
+
+The following forms are at least partially supported:
+
+- **Form 1040:** Individual income tax return
+- **Schedule 1:** Additional income and adjustments
+- **Schedule 2:** Additional taxes
+- **Schedule 3:** Additional credits and payments
+- **Schedule B:** _This form is not directly modeled, and instead the computations are done on
+    1040._
+- **Schedule D:** Capital gains and losses
+- **Form 1099-B:** Proceeds from broker transactions
+- **Form 1099-DIV:** Dividend income
+- **Form 1099-INT:** Interest income
+- **Form 1099-R:** Retirement account distributions
+- **Form 1116:** Foreign tax credit
+- **Form 8606:** Nondeductible IRAs
+- **Form 8949:** Sales and dispositions of capital assets
+- **Form 8959:** Additional medicare tax
+- **Form 8960:** Net investment income tax
+- **Form 8995:** Qualified business income deduction _for REIT dividends only_
+- **W2:** Wages
+
+However several credits and situations are not supported. Check the code file for each form for details.
+
+# Warning
+
+The U.S. tax code is incredibly complicated. This software is meant to help understand how the tax
+system works, to verify output from other software (assuming that __this__ software is correct), and
+to model/project various tax situations.