git:20260705.a4019d0 to git:20260719.1748a98

22 added, 1 removed. Audit A to A.

---

name: mental-health-data-nz

- description: Use when Codex needs New Zealand mental-health regulatory data from ODMHAS reports, seclusion/restraint summaries, MH&A KPI Programme indicator metadata, inpatient inspection counts, District Inspector sources, or source caveats for public mental-health transparency work. Read-only, keyless, and stdlib-only.

+ description: "Use when Codex needs New Zealand mental-health regulatory data from ODMHAS reports, seclusion/restraint summaries, MH&A KPI Programme indicator metadata, inpatient inspection counts, District Inspector sources, or source caveats for public mental-health transparency work. Read-only, keyless, and stdlib-only."

+ license: MIT

+ compatibility: "Requires Python 3.10+ and network access for live data"

+ metadata:

+ thecolab.category: "social-policy"

+ thecolab.source_owner: "Ministry of Health"

+ thecolab.source_type: "official"

+ thecolab.auth: "none"

+ thecolab.access_mode: "public-download"

+ thecolab.data_class: "public"

+ thecolab.writes: "false"

+ thecolab.browser: "false"

+ thecolab.risk: "low"

+ thecolab.cache_ttl: "24h"

+ thecolab.schema_version: "1"

+ thecolab.skill_type: "public-download"

+ thecolab.pack: "nz-public-data"

+ thecolab.source_url: "https://www.health.govt.nz/about-us/corporate-publications/mental-health-annual-reports"

+ thecolab.allowed_domains: "www.health.govt.nz,www.mhakpi.health.nz"

+ thecolab.last_verified: "2026-07-19"

+ thecolab.health: "healthy"

+ thecolab.maintainer: "@adam91holt"

---

# Mental Health Data NZ

## Goal

Discover and extract public New Zealand mental-health regulatory data from Manatu Hauora / Health NZ sources without login, API keys, browser automation, or invented PDF-derived rows.

The skill focuses on:

- Office of the Director of Mental Health and Addiction Services (ODMHAS) regulatory reports

- Seclusion/restraint summary tables that are available in report DOCX files

- MH&A KPI Programme public indicator and dashboard metadata

- Section 95 inquiry, section 99 inspection, and District Inspector source discovery

- Clear blocked/manual-export states for PDF-only, chart-only, sign-in, or bot-protected sources

## Use this when

- A user asks for NZ seclusion/restraint trend sources, annual report URLs, or extractable seclusion summary rows

- A workflow needs ODMHAS report metadata, PDF/DOCX links, publication dates, and source caveats

- A user asks about MH&A KPI indicators such as wait times, seclusion, 7-day follow-up, 28-day readmission, whanau engagement, or continuity of care

- A user needs public metadata for KPI dashboards where the dashboard data itself requires registration/sign-in

- A user asks for inpatient inspection, section 95 inquiry, section 99 inspection, or District Inspector regulatory sources

## Do not use this for

- Clinical advice, diagnosis, treatment recommendations, or crisis support

- Private, identifiable, unpublished, or authenticated health records

- PRIMHD custom exports from protected dashboard tools

- Circumventing Cloudflare, CloudFront, CAPTCHA, registration, or sign-in requirements

- Extracting chart-only PDF values unless an official machine-readable or DOCX table is available

## Preferred workflow

1. Run `scripts/cli.py odmhas-reports --json` to list known and discoverable ODMHAS regulatory reports.

2. Run `scripts/cli.py seclusion --year 2023 --json` for extractable DOCX seclusion tables and caveats.

3. Add `--district <name>` when a district/regional service filter is needed; check caveats because adult district event/rate charts may be chart-only.

4. Run `scripts/cli.py kpi list --json` to enumerate public MH&A KPI indicator metadata.

5. Run `scripts/cli.py kpi get <indicator> --json` for a specific indicator page, dashboard links, evidence-review links, and registration caveats.

6. Run `scripts/cli.py inpatient-inspections --year 2023 --json` for section 95/99 table rows and related inspection/District Inspector sources.

7. Run `scripts/cli.py sources --json` or `datasets --json` for source catalogue notes.

8. Include source URLs, extraction status, and caveats in user-facing answers.

## CLI

Run with:

```bash

python3 skills/mental-health-data-nz/scripts/cli.py <command> [flags]

```

## Commands

- `odmhas-reports [--limit N] [--json]` - list ODMHAS regulatory reports with page/PDF/DOCX links

- `seclusion --year YEAR [--district TEXT] [--json]` - extract seclusion summary tables from report DOCX where available

- `kpi list [--json]` - list MH&A KPI Programme public indicators and metadata pages

- `kpi get INDICATOR [--json]` - inspect one KPI indicator page and dashboard/resource links

- `kpi-sources [--json]` - shortcut for KPI source metadata

- `inpatient-inspections [--year YEAR] [--json]` - extract section 95/99 count rows and inspection source links

- `datasets [--json]` / `sources [--json]` - list official source surfaces and caveats

Examples:

```bash

python3 skills/mental-health-data-nz/scripts/cli.py odmhas-reports --json

python3 skills/mental-health-data-nz/scripts/cli.py seclusion --year 2023 --json

python3 skills/mental-health-data-nz/scripts/cli.py seclusion --year 2023 --district Canterbury --json

python3 skills/mental-health-data-nz/scripts/cli.py kpi list --json

python3 skills/mental-health-data-nz/scripts/cli.py kpi get seclusion --json

python3 skills/mental-health-data-nz/scripts/cli.py inpatient-inspections --year 2023 --json

python3 skills/mental-health-data-nz/scripts/cli.py sources --json

```

## Resources

- CLI entrypoint: `scripts/cli.py`

- Smoke test: `scripts/smoke_test.py`

- Source notes and caveats: `references/api-notes.md`

## Notes

- The CLI uses Python standard library modules only (`argparse`, `urllib`, `html.parser`, `zipfile`, `xml.etree.ElementTree`, and `json`).

- Network calls default to a 10-second timeout.

- Health publication pages may return 403 from some hosts; the CLI retains known direct DOCX/PDF report URLs and reports the blocked discovery state.

- KPI dashboards expose public metadata pages, but the data dashboards can require registration/sign-in; the CLI treats those as metadata-only unless a public export is present.