diff --git a/AGENTS.md b/AGENTS.md
index 71585d8..27d6fc5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,17 +4,19 @@ Guidance for AI coding agents (Claude Code, Codex, and others) working in this r
## What this is
-A DHIS2 custom app (built on the [DHIS2 Application Platform](https://github.com/dhis2/app-platform)) for viewing, testing and debugging DHIS2 program rules. A user picks a program, opens its registration/event forms, fills them in, and watches program rules evaluate live (hide/show fields and sections, assignments, mandatory, warnings/errors, feedback and indicator messages). Supports DHIS2 2.40 to 2.43 (see `d2.config.js`).
+A DHIS2 custom app (built on the [DHIS2 Application Platform](https://github.com/dhis2/app-platform)) for viewing, testing and debugging DHIS2 program rules. A user picks a program, opens its enrollment and event forms, fills them in, and watches program rules evaluate live (hide/show fields and sections, assignments, mandatory, warnings/errors, feedback and indicator messages). Supports DHIS2 2.40 to 2.43 (see `d2.config.js`).
+
+**The app never saves data.** Its only data write call is the tracker importer dry run (`importMode=VALIDATE`) in `hooks/useServerVerification.ts`, which runs the server's rule engine and validation and persists nothing. One exception lives in the libraries: FILE_RESOURCE and IMAGE field widgets (`-dhis2-ui`, via `useFileResourceUpload` in `-hooks`) upload a picked file immediately with `POST fileResources`, leaving an unassigned file resource on the server. The user docs say so. Keep it that way: do not add calls that post to `tracker` (or any other resource) without `importMode=VALIDATE`.
It consumes five sibling libraries as regular npm dependencies, all published from the separate [`dhis2-form-utils`](https://github.com/nnkogift/dhis2-form-utils) monorepo and versioned in lockstep with this app. **File issues/PRs against the rule engine, hooks, widgets or devtools there, not here.**
-- `@nnkogift/dhis2-form-utils-hooks`: `useEventProgramMetadataQuery`, `useTrackerMetadataQuery`, `useEventForm`, `FormStateProvider`, `useFieldControl`, `useFieldRuleEffect`, `useFormFeedback`, `useRuleEffectTrace`
+- `@nnkogift/dhis2-form-utils-hooks`: `useEventProgramMetadataQuery`, `useTrackerMetadataQuery`, `useEventForm`, `useTrackerForm`, `FormStateProvider`, `useFieldControl`, `useFieldRuleEffect`, `useFieldState`, `useSectionRuleEffect`, `useSectionState`, `useFormFeedback`, `useRuleEffectTrace`
- `@nnkogift/dhis2-form-utils-metadata`: program/program-stage metadata shaping (`selectProgramStage`, `resolveFormSectionLayout`, option group resolution, `ProgramRuleActionType`, metadata types)
- `@nnkogift/dhis2-form-utils-rules`: rule engine runtime types and helpers (`RuleEventInput`, `RuleSupplementaryDataInput`, `feedbackItemKey`, `filterPayload`)
- `@nnkogift/dhis2-form-utils-dhis2-ui`: `D2FieldWidget`, the `@dhis2/ui`-backed field renderer
-- `@nnkogift/dhis2-form-utils-devtools`: rule inspection (`RulesPanel`, `RuleDevtoolsScope` from `/scope`, `createLabelLookup`, `getEffectVariant`, `getEffectVisual`, `EFFECT_ICONS`)
+- `@nnkogift/dhis2-form-utils-devtools`: rule inspection (`RulesPanel`, `ServerEffectsSummary`, `RuleDevtoolsScope` from `/scope`, `createLabelLookup`, `getEffectVariant`/`getEffectVisual`/`EFFECT_ICONS` from `/effect-styles`, the server report types `ServerVerification`/`ServerReportEntry`, and since `0.1.0-alpha.14` the `EFFECT_LEGEND` and `PROVENANCE_TAGS` constants). The `EffectLegend` and `ProvenanceTag` components are bundled but not exported from the package entry in `alpha.14`; export them in `dhis2-form-utils` before using them here.
-This app's own code is thin: routing, DHIS2 API queries (programs list, org units, current-user supplementary data, option groups), UI chrome around the library-produced forms, and tracker/event submission payloads.
+This app's own code is thin: routing, DHIS2 API queries (programs list, accessible and program org units, current-user supplementary data, option groups), UI chrome around the library-produced forms, and the tracker/event payloads sent by the server dry run.
## Commands
@@ -36,7 +38,7 @@ pnpm test -- src/modules/program-playground/hooks/usePublishFormValues.test.ts
pnpm test -- -t "some test name"
```
-CI (`.github/workflows/ci.yml`) runs lint, typecheck, test and build as separate jobs on pushes and PRs to `main`, `alpha` and `beta`. `deploy.yml` and `release.yml` handle deployment and Changesets releases.
+CI (`.github/workflows/ci.yml`) runs lint, test, build and a Fallow audit (fed with test coverage) as separate jobs on pushes and PRs to `main`, `alpha` and `beta`. It does not run `pnpm typecheck`, so run that locally before pushing. `deploy.yml` and `release.yml` handle deployment and Changesets releases.
## Source layout
@@ -57,7 +59,7 @@ src/
### Routing (`src/AppWrapper.tsx`)
-`HashRouter` with three lazily loaded routes: `/` (program list), `/programs/:programId` (playground for one program), `/about`. `SyncUrlWithGlobalShell` keeps the DHIS2 global app shell's URL bar in sync with the hash router.
+`HashRouter` with three lazily loaded routes: `/` (program list), `/programs/:programId` (playground for one program), `/about` (`About.tsx`: app version from `useConfig`, supported DHIS2 range and resource links). The program list page ends with a footer (`program-list/components/ProgramListHelpLinks`) linking to the docs and About. External URLs and the displayed DHIS2 range live in `src/shared/constants/links.ts`; `SUPPORTED_DHIS2_RANGE` there is a hard-coded string, so change it together with `minDHIS2Version`/`maxDHIS2Version` in `d2.config.js`. `SyncUrlWithGlobalShell` keeps the DHIS2 global app shell's URL bar in sync with the hash router.
### Program list flow (`modules/program-list/`)
@@ -67,31 +69,38 @@ src/
### Program playground flow (`modules/program-playground/`)
-`pages/ProgramPage` loads program metadata via `useEventProgramMetadataQuery`, accessible org units via `useAccessibleOrgUnits`, current-user supplementary data (`userGroups`/`userRoles`, required by the rule engine) via `useCurrentUserSupplementaryData`, and option-group codes referenced by rules via `useOptionGroupsSupplementaryData`. `ProgramContextBar` sets org unit, the primary date (enrollment or event date) and a reset (`useProgramPlaygroundState` bumps a `resetKey` that remounts the forms). It then branches on `program.programType`:
+`pages/ProgramPage` gets everything it needs from `hooks/useProgramPageData`: program metadata via `useEventProgramMetadataQuery`, the user's accessible org units via `useAccessibleOrgUnits`, the program's assigned org units via `useProgramOrgUnits`, current-user supplementary data (`userGroups`/`userRoles`, required by the rule engine) via `useCurrentUserSupplementaryData`, and option-group codes referenced by rules via `useOptionGroupsSupplementaryData`. `ProgramContextBar` sets the org unit (`components/orgUnit/OrgUnitSelectorField`, a searchable modal tree limited to the program's org units; `ProgramOrgUnitsContext` lets forms require it before validating or verifying), the primary date (enrollment or event date) and a reset (`useProgramPlaygroundState` bumps a `resetKey` that remounts the forms). It then branches on `program.programType`:
- **`WITHOUT_REGISTRATION`** (event program): renders a single `ProgramStageFormScreen` for the first program stage.
- **`WITH_REGISTRATION`** (tracker program): renders `components/forms/TrackerProgramShell`, the more complex piece:
- Loads tracker-specific metadata (`useTrackerMetadataQuery`): TEAs, sections, tracked entity type.
- - State lives in a per-shell zustand + immer store (`utils/trackerFormsStore.ts`, provided via `components/trackerFormsStoreContext.tsx`): selected slot, draft events per repeatable stage, registration values and per-slot event values.
- - `components/EnrollmentRail` (left nav, with `RailRow` and `RepeatableStageGroup`) switches between the registration form and program-stage event forms. Repeatable stages can hold multiple draft events added via the store's `addEvent`; slots are identified by `TrackerSlot`/`slotKey` (`utils/trackerSlot.ts`).
+ - State lives in a per-shell zustand + immer store (`utils/trackerFormsStore.ts`, provided via `components/trackerFormsStoreContext.tsx`): selected slot, draft events per repeatable stage, registration (enrollment form) values and per-slot event values.
+ - `components/EnrollmentRail` (left nav, with `RailRow` and `RepeatableStageGroup`) switches between the enrollment form (rail row "Enrollment form", `TrackerSlot` kind `registration`) and program-stage event forms. Repeatable stages can hold multiple draft events added via the store's `addEvent`; slots are identified by `TrackerSlot`/`slotKey` (`utils/trackerSlot.ts`).
- **All rendered forms stay mounted simultaneously** (visibility toggled with `hidden` CSS, not conditional rendering) so switching rail rows never discards in-progress input in another form. `TrackerStageFormSlot` fixes each event's date at first render for the same reason.
- - Each form pushes its live values to the store via `usePublishFormValues` (debounced 150ms, uses RHF's `form.subscribe`, not `watch`) so sibling forms see them as `enrollment`/`events` rule-engine inputs. This is what lets a rule on an event form react to a value entered in the registration form, and vice versa.
+ - Each form pushes its live values to the store via `usePublishFormValues` (debounced 150ms, uses RHF's `form.subscribe`, not `watch`) so sibling forms see them as `enrollment`/`events` rule-engine inputs. This is what lets a rule on an event form react to a value entered in the enrollment form, and vice versa.
- `selectEventsExcludingSlot` in `trackerFormsStore.ts` shapes per-slot values into `RuleEventInput[]`, excluding the form's own slot. A `WeakMap` cache keeps unchanged entries referentially stable, and each `TrackerStageFormSlot` subscribes with `useShallow`, so a keystroke in one form does not re-render the others.
### Rule-aware rendering (`modules/program-playground/components/rules/`)
-- `RuleAwareField` wraps every metadata-driven field: pulls `useFieldControl`/`useFieldRuleEffect` from `-hooks`, renders the field's own label (blanking the widget's built-in label to avoid duplication, then wiring `aria-labelledby` back onto whatever DOM node the widget rendered; see the comment in that file for why), a `FieldEffectBadge` when a rule is affecting the field, and either the real `D2FieldWidget` or a `HiddenFieldPlaceholder`/nothing depending on `RuleDisplayContext`'s `ghostsEnabled` flag.
-- `RuleDisplayContext` / `GhostToggleButton` control whether rule-hidden fields/sections render as dashed "ghost" placeholders (`HiddenFieldPlaceholder`, `HiddenSectionPlaceholder`) or are omitted entirely.
+- `RuleAwareField` wraps every metadata-driven field: pulls `useFieldControl`/`useFieldRuleEffect` from `-hooks`, renders the field's own label (blanking the widget's built-in label to avoid duplication, then wiring `aria-labelledby` back onto whatever DOM node the widget rendered; see the comment in that file for why), a `FieldEffectBadge` when a rule is affecting the field, and either the real `D2FieldWidget` or a `HiddenFieldPlaceholder`/nothing depending on `RuleDisplayContext`'s `showHiddenFields` flag.
+- `RuleDisplayContext` / `GhostToggleButton` (the "Show hidden fields" toggle, an `aria-pressed` button) control whether rule-hidden fields and sections render as dashed hidden-field placeholders (`HiddenFieldPlaceholder`, `HiddenSectionPlaceholder`) or are omitted entirely. Call them hidden-field placeholders in UI text and docs, not ghosts.
- `RuleOutputColumn` is the sticky sidebar with separate Feedback and Indicators `RuleOutputCard`s, built from `useFormFeedback`. Each item resolves back to the rule that produced it via `useRuleEffectTrace(feedbackItemKey(item))` + `-devtools`' `createLabelLookup`.
- `LazyRulesPanel` lazy-loads the devtools `RulesPanel` (rule list, trace and dependency graph) with `RulesPanelFallback` as the Suspense fallback. Forms wrap their content in `RuleDevtoolsScope` so the panel can read the form store.
### Forms (`modules/program-playground/components/forms/`)
-`ProgramRegistrationForm`/`ProgramEventForm` are the RHF-backed forms wired to the rule engine through `-hooks` (`useEventForm`, `FormStateProvider`). `EventFormFields`/`RegistrationFormFields` lay out `RuleAwareField`s inside `FormSectionCard`s per `-metadata`'s section/data-element resolution (`resolveFormSectionLayout`, `getProgramStageSectionDataElementIds`). On save, values pass through `-rules`' `filterPayload` (drops rule-hidden values), are validated with the Zod schemas in `utils/trackerPayloads.ts`, and are turned into DHIS2 tracker payloads (`buildEventPayload`, `buildTrackerRegistrationPayload`) posted to the `tracker` resource. Payload building is app-local, not part of the shared libraries. DHIS2 errors are parsed/formatted by `utils/parseDhis2Error.ts` and `utils/formatDhis2Error.ts`.
+`ProgramRegistrationForm` (the enrollment form, `useTrackerForm`) and `ProgramEventForm` (`useEventForm`) are the RHF-backed forms wired to the rule engine through `-hooks` (`FormStateProvider`). `EventFormFields`/`RegistrationFormFields` lay out `RuleAwareField`s inside `FormSectionCard`s per `-metadata`'s section/data-element resolution (`resolveFormSectionLayout`, `getProgramStageSectionDataElementIds`). `ProgramFormActions` renders the buttons below each form. None of them saves anything:
+
+- **Validate form** runs the form's own validation (`utils/validateForm.ts`, `hooks/useFormValidation.ts`) and `ValidationNotice` lists the fields with issues. No request is sent.
+- **Verify with server** (`hooks/useFormServerCheck.ts` over `hooks/useServerVerification.ts`) posts the payload to `tracker` with `importMode=VALIDATE&async=false`. A run that finds problems answers 409 with the report, which `utils/parseRuleValidationReport.ts` parses. `utils/applyServerReport.ts` puts rule errors on the fields they target, and `ServerCheckStatus` shows the rest (including `OtherImportErrors`).
+- **Preview server effects** (enrollment form submit, and the first of the two event form buttons) opens `SaveReviewDialog`, a read-only wrapper around the devtools `ServerEffectsSummary`. It shows the server-side effects (messages, scheduled events) the importer would run and compares them with the last Verify result. It has no post action.
+- **Preview on-complete effects** (event forms only) first runs the completion pass (`hooks/useCompletionPass.ts`): it sets `status` to `COMPLETED`, waits for the rule engine, and collects on-complete warnings/errors and missing mandatory fields (`utils/completionIssues.ts`). If there are issues, `CompletionBanner` offers Back to editing or Complete anyway (when nothing blocks). It then opens the same summary for `COMPLETED`. `hooks/useEventReviewFlow.ts` tracks which status the summary was last opened for, and Verify dry-runs that status.
+
+The dry-run payload is built the way a real save would build it: values pass through `utils/parseFormValues.ts` (`-rules`' `filterPayload` drops rule-hidden values), are validated with the Zod schemas in `utils/trackerPayloads.ts`, and are turned into tracker payloads by `buildEventPayload` / `buildTrackerRegistrationPayload` there. Payload building is app-local, not part of the shared libraries. DHIS2 errors are parsed/formatted by `utils/parseDhis2Error.ts` and `utils/formatDhis2Error.ts`.
### Testing
-Jest + Testing Library; tests sit next to the code as `*.test.ts(x)`. `usehooks-ts` ships ESM-only and is deliberately carved out of the default `transformIgnorePatterns` in `jest.config.js` (pnpm nests it under `.pnpm/`, hence the lookahead pattern). Don't "fix" that by reverting to the default ignore list.
+Jest + Testing Library; tests sit next to the code as `*.test.ts(x)`. `usehooks-ts` and `lodash-es` ship ESM-only and are deliberately carved out of the default `transformIgnorePatterns` in `jest.config.js` (pnpm nests them under `.pnpm/`, hence the lookahead pattern). Don't "fix" that by reverting to the default ignore list.
### Releases
diff --git a/README.md b/README.md
index fb40aa1..1d6f037 100644
--- a/README.md
+++ b/README.md
@@ -2,62 +2,50 @@
[](https://github.com/fallow-rs/fallow)
-This is a playground app for testing and debugging DHIS2 program rules. It exercises the [`@nnkogift/dhis2-form-utils-hooks`](https://www.npmjs.com/package/@nnkogift/dhis2-form-utils-hooks), [`-rules`](https://www.npmjs.com/package/@nnkogift/dhis2-form-utils-rules), and [`-metadata`](https://www.npmjs.com/package/@nnkogift/dhis2-form-utils-metadata) packages against real form configurations, and uses [`@nnkogift/dhis2-form-utils-devtools`](https://www.npmjs.com/package/@nnkogift/dhis2-form-utils-devtools) (rule trace and dependency graph panels) to inspect rule evaluation live.
+A DHIS2 app for testing, validating and debugging program rules against your real form configurations. You pick a program, fill in its enrollment and event forms, and watch the rules evaluate live: hidden fields and sections, assigned values, mandatory fields, warnings and errors, and feedback and indicator messages. A live rule trace and a dependency graph show why each rule fired, or why it did not.
-It consumes those packages as regular npm dependencies, published from the [`dhis2-form-utils`](https://github.com/nnkogift/dhis2-form-utils) monorepo — file issues or PRs against the underlying libraries there.
+
-This project was bootstrapped with [DHIS2 Application Platform](https://github.com/dhis2/app-platform).
+## Who it's for
-## Getting started
+- **Program configurators and implementers** who write program rules and want to see them work before users do.
+- **DHIS2 admins** who need to find out why a rule behaves differently on their instance.
+- **Trainers** who explain program rules and want a safe place to show them in action.
-```bash
-pnpm install
-pnpm dev # start the dev server, proxying against a DHIS2 instance
-pnpm build # production build
-pnpm test # run the test suite
-pnpm lint # eslint + prettier check
-```
-
-## Available Scripts
-
-In the project directory, you can run:
-
-### `pnpm dev`
-
-Runs the app in development mode.
-Open [http://localhost:3000](http://localhost:3000) to view it in the browser.
+## Nothing is saved
-The page will reload if you make edits.
-You will also see any lint errors in the console.
+The playground never saves tracker data, events, enrollments or metadata, and never sends notifications. You can use it on a production server. The one exception: choosing a file in a file or image field uploads that file to the server as an unused file resource, so use a test file on production.
-### `pnpm test`
+- **Validate form** checks the form in your browser and sends nothing.
+- **Verify with server** sends your form to the tracker importer as a dry run (`importMode=VALIDATE`). The server runs its rule engine and validation and reports the result, but stores nothing.
+- **Preview server effects** and **Preview on-complete effects** open a read-only summary of the effects the server would run (messages, scheduled events). They do not post anything.
-Launches the test runner and runs all available tests found in `/src`.
+## Supported DHIS2 versions
-See the section about [running tests](https://platform.dhis2.nu/#/scripts/test) for more information.
+DHIS2 2.40 to 2.43 (`minDHIS2Version` and `maxDHIS2Version` in [`d2.config.js`](d2.config.js)). The app's About page shows the same range and the installed version.
-### `pnpm build`
+## Documentation and install
-Builds the app for production to the `build` folder.
-It correctly bundles React in production mode and optimizes the build for the best performance.
+- User documentation: [prp-docs.nnkogift.dev](https://prp-docs.nnkogift.dev)
+- DHIS2 App Hub (coming soon)
+- Release bundles: the `.zip` attached to each [GitHub release](https://github.com/nnkogift/program-rules-playground/releases)
-The build is minified and the filenames include the hashes.
-A deployable `.zip` file can be found in `build/bundle`!
+## Built on dhis2-form-utils
-See the section about [building](https://platform.dhis2.nu/#/scripts/build) for more information.
+The rule engine, form hooks, field widgets and rule devtools come from the [`dhis2-form-utils`](https://github.com/nnkogift/dhis2-form-utils) libraries (`@nnkogift/dhis2-form-utils-*` on npm). File issues and pull requests for those parts there. This repository holds the app around them.
-### `pnpm deploy`
+## Development
-Deploys the built app in the `build` folder to a running DHIS2 instance.
-This command will prompt you to enter a server URL as well as the username and password of a DHIS2 user with the App Management authority.
-You must run `pnpm build` before running `pnpm deploy`.
+You need Node.js 24 and pnpm.
-See the section about [deploying](https://platform.dhis2.nu/#/scripts/deploy) for more information.
-
-## Learn More
-
-You can learn more about the platform in the [DHIS2 Application Platform Documentation](https://platform.dhis2.nu/).
-
-You can learn more about the runtime in the [DHIS2 Application Runtime Documentation](https://runtime.dhis2.nu/).
+```bash
+pnpm install
+pnpm dev # start the dev server, proxied against a DHIS2 instance
+pnpm test # run the Jest test suite
+pnpm typecheck # tsc --noEmit
+pnpm lint # eslint + prettier check
+pnpm build # production build; the deployable .zip lands in build/bundle
+pnpm changeset # describe your change for the next release
+```
-To learn React, check out the [React documentation](https://reactjs.org/).
+The app is built with the [DHIS2 Application Platform](https://platform.dhis2.nu/). Contributor and agent guidance lives in [`AGENTS.md`](AGENTS.md).