What needs documenting

PR netclaw-dev/netclaw#1610 now changes both the netclaw model workflow and the canonical model configuration shape. The docs site’s CLI reference and model-configuration guide need to cover named model definitions, role assignment, metadata overrides, and backwards-compatible migration.

Named model definitions and role references

Model-owned configuration is stored independently from role assignment:

{
  "Models": {
    "Definitions": {
      "qwen-vl-local": {
        "Provider": "vllm",
        "ModelId": "qwen-vl",
        "ContextWindow": 32768,
        "InputModalities": "Text, Image",
        "OutputModalities": "Text"
      }
    },
    "Roles": {
      "Main": "qwen-vl-local",
      "Fallback": "fallback-model"
    }
  }
}

• Definitions own Provider, ModelId, ContextWindow, provenance, and modality overrides.
• Main, Fallback, and Compaction reference definitions by name.
• Switching a role from model A to B and back to A does not alter A’s definition or lose its overrides.
• An absent optional property means runtime capability detection. There are no hidden tombstone values, so hand-edited JSON remains understandable.
• Provider discovery may seed a newly created definition, but it does not rewrite an existing definition or repopulate an intentionally absent property.

Metadata override flags

• --context-window <tokens> — set the context-window clamp; takes precedence over provider detection and skips the metadata probe.
• --clear-context-window — remove the persisted clamp so runtime detection resolves it.
• --input-modalities <list> / --output-modalities <list> — set comma-separated named flags (Text, Image, Audio, Video). Raw integers are rejected. These flags do not skip model validation/probing.
• --clear-modalities — remove persisted modality overrides so runtime detection resolves them.

Set and clear operations edit the selected model definition. Ordinary role reassignment changes only the role reference.

Backwards-compatible upgrade and migration

• Upgraded daemons continue accepting the legacy inline Models.Main / Fallback / Compaction shape.
• Merely starting the upgraded daemon does not rewrite a legacy configuration.
• The first explicit model-writing operation, or netclaw doctor --fix, migrates legacy roles into named definitions.
• Migration is deterministic and preserves the effective provider, model ID, context window, modalities, and provenance.
• Before migration, Netclaw creates netclaw.json.legacy-models.bak for rollback to an older binary.
• Conflicting legacy roles for the same (provider, model ID), mixed legacy/named shapes, or unresolved role references fail loudly instead of choosing silently.
• Downgrading after migration requires restoring the .legacy-models.bak file first.

Environment-variable examples and migration guard

Update examples to use the named shape:

export NETCLAW_Models__Definitions__claude__Provider="openrouter"
export NETCLAW_Models__Definitions__claude__ModelId="anthropic/claude-sonnet-4"
export NETCLAW_Models__Roles__Main="claude"

Legacy environment-only deployments remain readable. However, an explicit file migration is rejected while legacy NETCLAW_Models__Main__*, Fallback, or Compaction overrides are present, because those variables would create an ambiguous mixed shape after restart. The operator must convert those variables to Definitions / Roles first.

Recovery and diagnostics

• model list reports invalid or unresolved configuration with a clear error directing the operator to netclaw doctor / doctor --fix.
• The model-manager TUI surfaces invalid named references instead of displaying them as an empty configuration.
• A selected legacy or named entry with an unreadable modality/provenance value can be repaired by model set while retaining independently readable fields such as ContextWindow.

Suggested placement

• Model/provider setup guide: canonical JSON, role-switch behavior, and override flags.
• CLI reference: all model set flags and clear semantics.
• Upgrade/migration guide: legacy acceptance, explicit migration, backup, rollback, and environment-variable conversion.

The in-agent source material is updated in feeds/skills/.system/files/netclaw-operations/references/providers.md, and the repository configuration reference is updated in docs/spec/configuration.md.

Source PR: netclaw-dev/netclaw#1610
OpenSpec change: preserve-model-definitions-across-role-switches