[DevelopmentCats]

What changes

The gpt-oss tiktoken vocab and parser flags and the Qwen3.5 chat template patch lived in Go (internal/resolve/tiktoken.go, internal/hf/hf.go). They are now files in catalogue/model-types/, one per HuggingFace model_type:

• gpt_oss.json: fetch o200k_base.tiktoken and cl100k_base.tiktoken, set TIKTOKEN_ENCODINGS_BASE, add the tool-call and reasoning parsers (first value the installed vLLM registers).
• qwen3_5.json, qwen3_5_moe.json: the chat template fix for the system-message check.
• deepseek_v4.json (new, covers V4 Flash, Pro and Flash Vision): --tokenizer-mode deepseek_v4 and the deepseek_v4 tool-call and reasoning parsers. The repos ship no chat template and their cards don't name these flags, so profiles from new couldn't render chat requests.

internal/modeltype loads and validates them. A local file in ~/.config/vllm-helper/model-types.d/ adds a model type, or replaces a shipped one with the same id. Bad local files are skipped with a warning, and doctor lists them.

New commands: model-types list and model-types show <id>, both with --json.

TestNoGoCodeRepeatsAShippedModelType fails if Go code names a shipped model type id.

Behaviour differences

• The template fix only applies to qwen3_5 and qwen3_5_moe repos. Before, any repo whose template matched the text was patched.
• gpt-oss profiles carry TIKTOKEN_ENCODINGS_BASE in the profile. Setup no longer creates tiktoken-encodings or writes the variable to config.env. Existing config.env lines still work.
• Doctor no longer reports harmony_vocab.
• The notes printed when preparing a gpt-oss profile come from the catalogue file, so the wording changed.

Checks

• go vet ./... (linux and darwin/arm64), go test -race ./... (skipping TestProbeReportsThisMachine, which fails in this VM on main too)
• go run ./scripts/gendocs with no diff, prettier --check .
• tools/recipediff: same 4 undeclared differences as main
• Manually: a local model-types.d/gpt_oss.json replaced the shipped entry, a broken file was skipped with a warning

[Copilot]

🟡 Changes recommended

Unquoted catalogue values can break saved-profile argument parsing, and non-vLLM engines silently ignore accepted file and environment rules.

3 open issues

• Quote catalogue values before serializing EXTRA_ARGS · New
• Apply model-type file and environment rules to MLX profiles · New
• Use valid IDs so fixtures reach their intended validation checks · New

What changed in this PR

Moves architecture-specific behavior from Go into catalogue/model-types/, continuing #59’s separation of catalogue data from runtime logic.

Changes:

• Adds validated model-type definitions and local overrides for file downloads, parser flags, and chat-template fixes.
• Integrates rules into profile preparation, moves tokenizer environment settings into profiles, and adds model-types list/show.
• Updates tests, doctor output, documentation, and contributor guidance.

File	Description
internal/​vllm/​validate.go	Adds flag and parser-value acceptance checks.
internal/​resolve/​tiktoken.go	Removes hardcoded harmony preparation.
internal/​resolve/​tiktoken_internal_test.go	Removes tests replaced by catalogue-driven coverage.
internal/​resolve/​resolve.go	Applies model-type rules during profile preparation.
internal/​resolve/​resolve_internal_test.go	Tests profile environment and architecture-scoped patches.
internal/​resolve/​modeltype.go	Implements rule-driven arguments, downloads, and template fixes.
internal/​resolve/​modeltype_internal_test.go	Tests downloads and parser selection.
internal/​profile/​profile.go	Writes environment settings into profiles.
internal/​modeltype/​modeltype.go	Defines and validates the model-type registry.
internal/​modeltype/​modeltype_internal_test.go	Tests definitions, validation, overrides, and catalogue boundaries.
internal/​modeltype/​local.go	Loads local overrides and records errors.
internal/​hf/​hf.go	Separates template fetching from patch logic.
internal/​hf/​hf_internal_test.go	Updates coverage for template fetching.
internal/​cli/​setup.go	Removes global tokenizer directory setup and configuration.
internal/​cli/​root.go	Loads model types and registers their commands.
internal/​cli/​root_internal_test.go	Updates the expected command set.
internal/​cli/​modeltypescmd.go	Adds list/show commands with JSON output.
internal/​cli/​detectcmds.go	Reports local definition errors; removes harmony-vocab reporting.
docs/​reference/​cli/​model-types/​show.md	Adds generated show-command reference.
docs/​reference/​cli/​model-types/​list.md	Adds generated list-command reference.
docs/​reference/​cli/​model-types.md	Adds generated model-types command reference.
docs/​reference/​cli.md	Links the new command group.
docs/​model-types.md	Documents rules and local overrides.
docs/​manifest.json	Routes the new documentation pages.
docs/​install.md	Removes the global tokenizer setting from the configuration table.
CHANGELOG.md	Records new commands and behavior changes.
catalogue/​model-types/​README.md	Explains how to add model-type definitions.
catalogue/​model-types/​qwen3_5.json	Defines the Qwen3.5 template fix.
catalogue/​model-types/​qwen3_5_moe.json	Defines the Qwen3.5 MoE template fix.
catalogue/​model-types/​gpt_oss.json	Defines harmony vocabulary and parser requirements.
catalogue/​catalogue.go	Embeds and exposes model-type definitions.
AGENTS.md	Documents the package layout and model-type guardrail.

_{Review effort: Balanced}