[ivargr]

Summary

Restructures the model developer docs around whether you already have a model, following the external modeler test in CLIM-1389 and CLIM-1478. Getting Started is now one overview page that sends readers to: a new short "Set up your machine" page, a new "Bring your existing model" guide, and the MLproject tutorial, renamed "Build a new model from a template". Both guides follow three stages: run the model outside Chap, make it Chap-compatible with an MLproject file and chap eval --run-config.as-chapkit, then package it as a Docker image with the compose.yml and GitHub workflows now in the mlproject_template_r and mlproject_template_python repos.

Also: the existing-model guide recommends --run-config.ignore-environment and renv_env/uv_env instead of docker_env, says that train and predict scripts are a recommendation and the chapkit REST API is the only requirement, has a tip on using AI coding agents, and both guides list what the flow does not need (no chapkit install, no Chap server, no chapkit mlproject migrate). The comparison table moved from the tutorial to chapkit.md. "Development tools" moved from the contributor docs to the model developer docs and now points to the webinar guides. The "For experienced modellers" and "For newcomers" pages are removed. The overview says that a Chap-compatible model can be run both with chap eval and from the Modeling App, and "Running Your Own Model" links to the two guides.

Review needed

Review needed: quick-merge

Test plan

• make docs (strict) passes.
• Followed the existing-model flow with the Python template: chap eval --run-config.as-chapkit --run-config.ignore-environment from an activated venv, then docker compose up --build and chap eval against the running service, for both templates. The R scripts outside Docker were not run, since this machine has no R.

[ivargr]

Overview of every problem found in the external modeler test, plus the ones found while fixing them, and how each is addressed. Status as of 5 November.

Problem	Found by	How it's addressed	Where	Status
An AI search invented commands (brew install chapkit, chapkit mlproject migrate, the chap-core docker compose stack)	Boris	An llms.txt for chap.dhis2.org that states the real flow, and a "What you do not need" box in both guides	dhis2-chap/chap-site#15, this PR	Merged / Open
Every page had the same search description	Claude	Each model developer page has its own description, mentioning chapkit, MLproject and chap eval	this PR	Open
The chapkit docs and README never point to the Chap guides	Claude	Pointers from the chapkit front page, MLproject runner guide and README	dhis2-chap/chapkit#158	Open
Found the right guide only by a lucky click on "Chapkit"	Boris	Getting Started overview is the first model developer page	this PR	Open
chap-site deploy failing since 30 Oct (Python 3.15 breaks a docs plugin), so docs changes never went live	Ivar	Deploy workflow pinned to Python 3.13	dhis2-chap/chap-site#16	Merged
Getting Started split readers into "experienced" and "newcomers", and the overview's audience list was empty	Ivar	One overview: do you already have a model, or are you building one? Links to Development tools and Learning modelling	this PR	Open
The overview mentioned chapkit up front and did not say where a model can run	Ivar	Explains both uses: chap eval on your machine, and the Modeling App	this PR	Open
The install page was scary (marketplace, chap-admin); unclear whether to install from PyPI or GitHub	Boris	New "Set up your machine" page with one PyPI install command	this PR	Open
"180 packages, will I break my laptop?"	Boris	The setup page explains they go in a folder of their own	this PR	Open
Docker: why it is needed, and Engine vs Desktop	Boris	Only needed to deploy; Mac and Windows users pointed to Docker Desktop	this PR	Open
The comparison table (Docker, migrate) confused a first-time reader	Boris	Moved from the tutorial to the chapkit reference page	this PR	Open
No path for someone who already has a model	Boris	New "Bring your existing model" guide in three stages: run outside Chap, make Chap-compatible, package as a Docker image	this PR	Open
R and Python run commands shown side by side	Boris	Separate instructions for each language	this PR	Open
R packages not installed ("there is no package called dplyr")	Boris	Install steps in the existing-model guide; renv::restore() first in the tutorial	this PR	Open
An MLproject with docker_env was a dead end	Boris	Develop with --run-config.ignore-environment, then switch to renv_env or uv_env	this PR	Open
No mention that train and predict scripts are only a recommendation	Ivar	Note that the chapkit REST API is the only requirement, with links for advanced users	this PR	Open
No help for people who use AI coding agents	Ivar	Tip box with a ready-to-paste prompt	this PR	Open
A raw traceback buried the docker_env error message	Boris	One-line Error: with exit code 1 and advice to use renv_env/uv_env; CHAP_DEBUG=1 still shows the traceback	#829	Open
bionumpy SyntaxWarnings on every chap command	Boris	Already fixed in chap-core 2.5.1	chap-core 2.5.1	Done
Templates had no easy Docker build and no way to publish the image	Ivar	compose.yml, a CI workflow that runs chap eval against the built image, and a GHCR publish workflow	mlproject_template_r, mlproject_template_python	Done
The R template Dockerfile failed without renv/settings.json	Claude	Copies the whole renv/ folder	mlproject_template_r	Done
The Docker step did not say where the files are or how to publish	Ivar	File table with links, a one-line download command, and the push and GitHub Actions steps	this PR, template READMEs	Open / Done
chap-core's own docker compose up failed (unset .env variables, amd64-only worker image)	Boris	Out of scope: model developers do not need that stack, and the guides now say so	–	Won't fix
Neither scenario re-tested from start to finish	Boris, Ivar	Ivar retests the existing-model and new-model scenarios once the PRs are merged	–	Pending

[claude]

No significant findings. This PR only changes docs. The chap eval flags and the docker_env error text that the new guides quote match the code in chap_core/models/mlproject_chapkit.py and chap_core/api_types.py, and strict make docs passes in CI. Verdict: safe to merge.