Add small guide with supported scenarios for drawdown illustrations

docs/sipp-illustrations/Basics.md

@@ -17,7 +17,7 @@ The illustration allows one product and/or provider to be compared to another, a
 
 ## Current supported scope
 
-At present, the illustration service only supports accumulation SIPPs. Support for benefit crystallisations and drawdown transfers will be available in future releases. 
+At present, the illustration service only supports key features illustrations for both accumulation and decumulation SIPPs. Support for SMPI illustrations will be available in future releases. 
 
 The illustrations service supports the following capabilities for accumulation:
 - Member information
@@ -36,6 +36,30 @@ The illustrations service supports the following capabilities for accumulation:
   - Individual assets
   - Investment fees (initial and OCF)
 
+And for decumulation, supports the following:
+- Member information
+- Transfers
+  - Single or multiple
+- Fees
+  - Adviser
+  - Provider
+  - DFM
+- Valuations
+  - Value of the accumulation pot
+  - Value of the decumulation pot
+- Investment selection
+  - Model
+  - Individual assets
+  - Investment fees (initial and OCF)
+- Benefit crystallizations
+  - Flexi-access only
+  - Tax-free cash can be taken as a lump sum, or in instalments
+- Taxable income schedules
+  - Single or multiple
+  - Can have varying payout schedules / frequencies
+
+Note that accumulation and decumulation illustrations are both requested and retrieved from different API endpoints with different request bodies and responses.
+
 ## How to produce an illustration
 
 The below diagram represents the process flow for generating an illustration.

docs/sipp-illustrations/Drawdown-scenarios.md

@@ -0,0 +1,26 @@
+---
+tags: [SIPP Illustrations]
+---
+
+# Drawdown Scenarios
+
+## Supported scenarios
+
+Currently, we only support **flexi-access** and the following scenarios when generating decumulation illustrations:
+
+- Taking the crystallized funds in one lump sum payment
+- Taking both the tax-free and taxable income in equal instalments over one year
+- Taking the tax-free income instantly (with taxable income being taken on flexible schedules)
+
+Note that tax-free income **must** be paid out within one year of crystallization, and so we can only illustrate it being taken in either monthly instalments or one lump sum. We currently do not support illustrating behaviours such as taking tax-free income only in instalments (phased PCLS).
+
+These different scenarios can be generated by changing the crystallization behaviour on requests. Specifically:
+
+- The `proportion` changes how much of the accumulation pot is being moved to drawdown.
+- The `amountPerCrystallization` changes how much is being crystallized in the illustration when the `proportion` is `Partial`.
+- The `payoutStrategy` changes how the crystallization is paid out as follows:
+    - `AllCashImmediately`: Pays the entire crystallization out as one lump sum payment. Separate taxable income schedules cannot be specified.
+    - `AllCashMonthlyOverOneYear`: Pays the entire crystallization out over one year in monthly instalments. Separate taxable income schedules cannot be specified.
+    - `TaxFreeCashImmediately`: Pays all of the tax-free income over one year in monthly instalments. Separate taxable income schedules can be specified, or left empty if the intent is to keep the taxable income.
+
+We also support using existing crystallized funds, which are already in drawdown, to make additional payments out. However, it is assumed that all tax-free cash has already been paid out or is in the process of being paid out, and will not be included. in the illustration. In this case, the  `crystallizationBehaviour` will be `null`.

docs/sipp-illustrations/FAQs.md

@@ -7,7 +7,7 @@ tags: [SIPP Illustrations]
 
 ## Does the illustration service support drawdown illustrations?
 
-At present, the illustration service only supports accumulation illustrations. Illustrations for drawdown and drawdown transfer will be added in the future. 
+Yes, both accumulation and decumulation (drawdown) illustrations are supported.
 
 ## Does the illustration service support fee tiering?