Publish nine docs notebooks and fix doc links and parameter labels

.github/test_outcome_allowlist.toml

@@ -52,6 +52,13 @@ reason = '\.github'
 modes = ["wheel"]
 why = "Tests of the CI scripts in .github skip themselves in an installed wheel, which does not contain .github; they run against the source tree on every PR."
 
+[[allow]]
+nodeid = "policyengine_uk/tests/code_health/test_docs_toc.py"
+outcome = "collect-skipped"
+reason = 'myst\.yml'
+modes = ["wheel"]
+why = "The installed wheel holds neither myst.yml nor the docs, so the documentation table of contents test skips itself there; it runs against the source tree on every PR."
+
 [[allow]]
 nodeid = "policyengine_uk/tests/*"
 outcome = "skipped"

changelog.d/2803.fixed.md

@@ -0,0 +1 @@
+The documentation site now publishes nine programme and validation notebooks it left out, among them Housing Benefit and the childcare entitlements, and lists the gambling duties page. Links on three pages reach their targets, and the model baseline page pins its parameter links to a commit so each line anchor stays on the value it cites. Twelve parameter labels now spell LBTT, LTT, LHA and TV in capitals. The residential SDLT lease rent rates take the unit /1, and the programme registry names HMRC as the agency for Scottish income tax. The childcare examples now state the birth dates and school status behind their amounts, the student loan page describes each plan from the regulations and says Plan 5 carries no liability before 6 April 2026, and the Housing Benefit page gives the 1 July 2026 abolition date with its exceptions.

docs/book/assumptions/takeup-analysis-plan.md

@@ -136,7 +136,7 @@ For each programme above, the analysis should produce:
 Most published reference rates change roughly annually (HMRC's tax
 credit take-up rates stop at 2017 to 2018). The analysis should be
 repeatable, ideally as a notebook under
-[`docs/book/validation/`](../validation/) so future builds can re-run
+[`docs/book/validation/`](https://github.com/PolicyEngine/policyengine-uk/tree/main/docs/book/validation) so future builds can re-run
 it and update the gaps table. A notebook needs its own `file:` entry
 under Validation in `myst.yml` to appear in the docs, since only
 Markdown pages are picked up by folder.

docs/book/programs/gov/dfe/extended-childcare-entitlement.ipynb

@@ -33,11 +33,11 @@
     "Non-working partners may qualify if they receive: **incapacity benefit**, **severe disablement allowance**, **carer's allowance**, **limited capability for work benefit**, or **contribution-based employment and support allowance**.\n",
     "\n",
     "#### Income requirements\n",
-    "Minimum earnings thresholds (per **3 months**) vary by age:\n",
+    "Minimum earnings thresholds (per **3 months**, 2024-25 rates) vary by age:\n",
     "\n",
     "| Age group | Minimum earnings | Weekly equivalent |\n",
     "|-----------|-----------------|-------------------|\n",
-    "| **21+** | **£2,380** | **£183** |\n",
+    "| **21+** | **£2,379** | **£183** |\n",
     "| **18-20** | **£1,788** | **£137** |\n",
     "| **Under 18/Apprentices** | **£1,331** | **£102** |\n",
     "\n",
@@ -104,8 +104,8 @@
     "|-----------|-------------------|---------------|----------------------|-------------------|\n",
     "| 22        | £2,500            | False         | True                 | True              |\n",
     "| 19        | £1,500            | False         | False                | False             |\n",
-    "| 35        | £10,000           | True          | True                 | False             |\n",
-    "| 18        | £1,400            | False         | True                 | True              |\n",
+    "| 35        | £30,000           | True          | True                 | False             |\n",
+    "| 18        | £1,400            | False         | False                | False             |\n",
     "\n",
     "### 4. Overall eligibility determination\n",
     "Managed by [`extended_childcare_entitlement_eligible.py`](https://github.com/PolicyEngine/policyengine-uk/tree/20ed1a9d77a3307b3e2bc4a0986ec606ab7fead9/policyengine_uk/variables/gov/dfe/extended_childcare_entitlement):\n",
@@ -136,12 +136,14 @@
     "\n",
     "The annual model evaluates parameters at January and does not prorate the April or September expansions within a calendar year.\n",
     "\n",
-    "Example table (2024-25 rates, 30 hours used, no targeted hours):\n",
+    "Example table for 2024-25, for a child in England in a working family that uses 30 hours a week and gets no targeted hours. The model's year has three terms, beginning on 1 April 2024, 1 September 2024 and 1 January 2025. Each row gives the child's age on 6 October 2024 and the birth dates that produce its amount. Neither child starts reception before September 2025, and each reaches its age band before 1 April 2024, so each gets hours in all three terms.\n",
     "\n",
-    "| Child age | Total weekly hours | Universal weekly hours | Funding rate | Annual working parent entitlement |\n",
-    "|-----------|-------------------|------------------------|-------------|-------------------|\n",
-    "| 2         | 15                | 0                      | £8.28       | £4,719.6         |\n",
-    "| 3         | 30                | 15                     | £5.88       | £3,351.6         |"
+    "| Child age | Born | School | Total weekly hours | Universal weekly hours | Funding rate | Annual working parent entitlement |\n",
+    "|-----------|------|--------|-------------------|------------------------|-------------|-------------------|\n",
+    "| 2         | 1 January to 31 March 2022 | Starts reception in September 2026 | 15 | 0  | £8.28 | £4,719.60 |\n",
+    "| 3         | 7 October 2020 to 31 March 2021 | Starts reception in September 2025 | 30 | 15 | £5.88 | £3,351.60 |\n",
+    "\n",
+    "A child who reaches the minimum age later in the year, or who starts reception during it, gets fewer funded terms. A 2-year-old born on 1 April 2022 gets working parent hours from September only, £3,146.40. A 3-year-old born on 1 April 2021 gets universal hours from September only: its universal entitlement falls to £2,234.40, and the summer term's 30 hours all count as working parent hours at the age-2 rate, so this column rises to £5,380.80."
    ]
   }
  ],

docs/book/programs/gov/dfe/universal-childcare-entitlement.ipynb

@@ -71,14 +71,16 @@
     "  * Apply appropriate funding rate based on age\n",
     "  * Calculate total annual value\n",
     "\n",
-    "Example table:\n",
+    "Example table for 2024-25, for a child in England. The model's year has three terms, beginning on 1 April 2024, 1 September 2024 and 1 January 2025. Each row gives the child's age on 6 October 2024 and the birth dates that produce its amount. The children aged 3 and 4 turned 3 before 1 April 2024 and start reception in September 2025, so they get universal hours in all three terms. A child who turns 3 later in the year, or who starts reception during it, gets fewer terms: a 3-year-old born on 1 April 2021 gets £2,234.40, and a 4-year-old born on 31 August 2020, who starts reception in September 2024, gets £1,117.20 for the summer term.\n",
+    "\n",
+    "| Child age | Born | School | Is eligible | Weekly hours | Funding rate | Number of weeks | Annual entitlement |\n",
+    "|-----------|------|--------|------------|--------------|--------------|-----------------|-------------------|\n",
+    "| 2         | 1 January to 6 October 2022 | Not yet in reception | False | 0 | £8.28 | 38 | £0 |\n",
+    "| 3         | 7 October 2020 to 31 March 2021 | Starts reception in September 2025 | True | 15 | £5.88 | 38 | £3,351.60 |\n",
+    "| 4         | 1 September to 6 October 2020 | Starts reception in September 2025 | True | 15 | £5.88 | 38 | £3,351.60 |\n",
+    "| 5         | 7 October 2018 to 6 October 2019 | Compulsory school age | False | 0 | £5.88 | 38 | £0 |\n",
     "\n",
-    "| Child age | Is eligible | Weekly hours | Funding rate | Number of weeks | Annual entitlement |\n",
-    "|-----------|------------|--------------|--------------|-----------------|-------------------|\n",
-    "| 2         | False      | 0            | £11.22       | 38             | £0                |\n",
-    "| 3         | True       | 15           | £5.88        | 38             | £3,351.6         |\n",
-    "| 4         | True       | 15           | £5.88        | 38             | £3,351.6         |\n",
-    "| 5         | False      | 0            | £5.88        | 38             | £0                |"
+    "A 2-year-old born from 7 October to 31 December 2021 turns 3 before 1 January 2025, so it gets universal hours in the spring term: £1,117.20."
    ]
   }
  ],

docs/book/programs/gov/dwp/disability-legacy-benefits.md

@@ -1,7 +1,7 @@
 # DLA and Severe Disablement Allowance
 
 PolicyEngine UK models two **legacy** DWP disability benefits alongside
-the current PIP (covered in [its own page](./PIP.ipynb)):
+the current PIP (see [PIP point system](./pip-points-plan.md)):
 
 - **Disability Living Allowance (DLA)** — closed to new working-age
   claims in April 2013 but still paid to existing recipients and to

docs/book/programs/gov/dwp/housing-benefit.ipynb

@@ -24,11 +24,19 @@
     "- **Pension age**: the claimant and any partner have reached the qualifying age for State Pension Credit (State Pension age), or the family is a mixed-age couple that keeps the pension-age route: one entitled to Pension Credit or pension-age Housing Benefit on 14 May 2019 and ever since ([SI 2019/37 art. 4](https://www.legislation.gov.uk/uksi/2019/37/article/4)), or any mixed-age couple not reported on Universal Credit before 15 May 2019 (`meets_pension_credit_age_conditions`). New Housing Benefit claims are open to them ([SI 2014/1230 reg. 6A(4) and (5)](https://www.legislation.gov.uk/uksi/2014/1230/regulation/6A)), and Universal Credit is not, so neither a previous claim nor `would_claim_uc` matters.\n",
     "- **Continuing award**: any other benunit was **already claiming** Housing Benefit (proxied by a positive `housing_benefit_reported`) and is **not claiming Universal Credit**. Working-age families, and mixed-age couples without the saving, cannot make new claims; they claim the Universal Credit housing element instead.\n",
     "\n",
-    "The pension-age test counts the same benunit members as Universal Credit's working-age test, and the continuing-award route requires not claiming Universal Credit, so no benunit receives both. Working-age awards outside specified or temporary accommodation ended on 1 July 2026 in Great Britain ([SI 2025/1148 art. 7](https://www.legislation.gov.uk/uksi/2025/1148/article/7)); PolicyEngine does not yet model that. Claims for specified or temporary accommodation, which remain open at any age, are not modelled.\n",
+    "The pension-age test counts the same benunit members as Universal Credit's working-age test, and the continuing-award route requires not claiming Universal Credit, so no benunit receives both.\n",
+    "\n",
+    "Parliament abolished Housing Benefit in Welfare Reform Act 2012 s. 33(1)(d). Under [SI 2025/1148 art. 7](https://www.legislation.gov.uk/uksi/2025/1148/article/7), the abolition takes effect on 1 July 2026 for each award that hasn't already ended under SI 2014/1230 reg. 7(2), 8(2A) or 46(1)(a) and isn't due to end after a two week run-on (art. 7(1) and (3)), with these exceptions:\n",
+    "\n",
+    "- For a claimant whom the Universal Credit Regulations 2013 reg. 19(1)(b) or (c) (prisoners and others) bar from Universal Credit immediately before 1 July 2026, the award ends on the day after the bar last applies (art. 7(2)).\n",
+    "- The award continues where the claimant's circumstances fall within [SI 2014/1230 reg. 6A(2) to (5)](https://www.legislation.gov.uk/uksi/2014/1230/regulation/6A): specified or temporary accommodation; a single claimant who has reached the qualifying age for State Pension Credit, or a couple or polygamous marriage in which every member has; a claim that reg. 6A(3) allows when a Universal Credit claimant reaches that age; or a mixed-age couple whose older member claims and keeps a saving under SI 2019/37 art. 4(1) (art. 7(4)(a)).\n",
+    "- The award continues where, immediately before 1 July 2026, the claimant has an income-related Employment and Support Allowance award that [art. 3A(2)](https://www.legislation.gov.uk/uksi/2025/1148/article/3A) saves: at that time someone acts for the claimant as an appointee under reg. 57 of the Universal Credit, Personal Independence Payment, Jobseeker's Allowance and Employment and Support Allowance (Claims and Payments) Regulations 2013, or in the six months ending on that day the Secretary of State determined that the claimant would likely need one (art. 7(4)(b)).\n",
+    "\n",
+    "PolicyEngine does not yet model the 1 July 2026 end date: no rule in the model ends a working-age family's continuing award on that date. It also doesn't model claims for specified or temporary accommodation, which reg. 6A(2) keeps open at any age.\n",
     "\n",
     "**Guarantee Credit passport.** If the claimant or partner is in receipt of a guarantee credit (`in_receipt_of_guarantee_credit`: the benunit is eligible for Pension Credit, claims it, and its guarantee credit is positive, so the Pension Credit paid includes a guarantee credit), the whole of their capital and income is disregarded ([SI 2006/214 reg. 26](https://www.legislation.gov.uk/uksi/2006/214/regulation/26); Northern Ireland: [SR 2006/406 reg. 24](https://www.legislation.gov.uk/nisr/2006/406/regulation/24)). `housing_benefit_assessable_capital`, `housing_benefit_tariff_income` and `housing_benefit_applicable_income` are then zero, so the capital limit cannot bite and no income is tapered. A guarantee credit computed for a family that does not claim Pension Credit (`would_claim_pc`), or that PolicyEngine does not treat as eligible for it (`is_pension_credit_eligible`), does not count. The passport applies within the pension-age regulations (`housing_benefit_pension_age_regulations_apply`). `is_pension_credit_eligible` retains mixed-age couples covered by the [SI 2019/37 art. 4](https://www.legislation.gov.uk/uksi/2019/37/article/4) saving through `meets_pension_credit_age_conditions`; these couples keep the passport when they receive Guarantee Credit. When Pension Credit is frozen, receipt follows the baseline award, including its Guarantee Credit component. Savings Credit alone follows the separate assessment in [reg. 27](https://www.legislation.gov.uk/uksi/2006/214/regulation/27), including its capital limit, and does not give this passport.\n",
     "\n",
-    "Take-up is handled per benefit unit by `would_claim_housing_benefit`. In data-built simulations, including the Enhanced FRS, its default is true only for families reporting positive Housing Benefit (d1455, following the CTR survey ruling d1390). In hand-entered household calculations, it is true when the family reports Housing Benefit or its `claims_all_entitled_benefits` flag is true. That flag tests seven reported benefits within the family; it does not test Pension Credit, Child Benefit or Council Tax Reduction. Dataset and situation inputs can override the take-up flag directly."
+    "`would_claim_housing_benefit` decides take-up for each benefit unit. In simulations built from data, including the Enhanced FRS, it defaults to true only for families that report Housing Benefit, the same rule `would_claim_council_tax_reduction` applies to Council Tax Reduction ([#1831](https://github.com/PolicyEngine/policyengine-uk/pull/1831)). In hand-entered household calculations, it is true when the family reports Housing Benefit or its `claims_all_entitled_benefits` flag is true. That flag tests seven reported benefits within the family; it does not test Pension Credit, Child Benefit or Council Tax Reduction. Dataset and situation inputs can override the take-up flag directly."
    ]
   },
   {