docs: Document DoctorContractProtocol runtime migration + new doctor subcommands (PraisonAI PR #2075)

[MervinPraison]

Context

PraisonAI PR #2075 (link) shipped a new doctor runtime configuration migration framework plus several new health-check subcommands. None of this is currently reflected in the docs.

Tracks upstream issue: MervinPraison/PraisonAI#1941
Merged commit: 2b3957a49f31dd362cdb2d0aafdafd9799a6d62d

---

Summary of what shipped (from SDK source)

1. New runtime SDK exports

File: src/praisonai-agents/praisonaiagents/runtime/__init__.py

New public symbols re-exported from praisonaiagents.runtime:

Symbol	Type	Purpose
DoctorContractProtocol	Protocol (runtime_checkable)	Contract third-party plugins implement to provide custom config migration rules
Finding	dataclass	Result of a rule's collect_findings() call
get_default_registry()	function	Returns singleton DoctorRulesRegistry
register_rule(rule)	function	Register a rule on the default registry
get_rules()	function	List registered rules (auto-loads built-ins + plugins)
collect_findings(config)	function	Aggregate findings from every registered rule
apply_fixes(config)	function	Apply fixes from every registered rule

Source files added:

• praisonaiagents/runtime/doctor_protocol.py — Finding, DoctorContractProtocol
• praisonaiagents/runtime/doctor_registry.py — DoctorRulesRegistry, plugin discovery via entry point praisonai.doctor_contracts
• praisonaiagents/runtime/builtin_rules.py — CliBackendMigrationRule (built-in)

2. Finding dataclass

@dataclass
class Finding:
    rule_id: str
    severity: str                # "warning" | "error" | "info"
    message: str
    fix_description: Optional[str] = None
    context: Optional[Dict[str, Any]] = None

3. DoctorContractProtocol (the plugin contract)

@runtime_checkable
class DoctorContractProtocol(Protocol):
    @property
    def rule_id(self) -> str: ...
    def collect_findings(self, config: Dict[str, Any]) -> List[Finding]: ...
    def apply_fix(self, config: Dict[str, Any]) -> Dict[str, Any]: ...

Plugins are discovered via the entry-point group praisonai.doctor_contracts (importlib.metadata, with pkg_resources fallback).

4. Built-in rule: CliBackendMigrationRule

• rule_id = "cli_backend_migration"
• Detects cli_backend: ... at the top level and inside roles.<role_name> of an agents.yaml.
• Migrates it to models.default.runtime: <value> (preserving the same value, with a small mapping table for known IDs: claude-code, openai-gpt, anthropic, gemini).

5. New CLI: praisonai doctor runtime

File: src/praisonai/praisonai/cli/commands/doctor.py

praisonai doctor runtime [OPTIONS]

Flag	Default	Purpose
--team TEXT	—	Team YAML file to validate
--workflow TEXT	—	Workflow YAML file to validate (future)
--fix / (none)	False	Apply migration fixes
--dry-run / --execute	--dry-run	Show changes vs apply changes (with timestamped backup)
--json	False	JSON output
--deep	False	Enable deeper probes
--file, -f TEXT	search agents.yaml/agents.yml/config.yaml/config.yml in cwd	Config file to check

Behavior (from runtime_migration_checks.py):

• Without --fix: reports WARN with how many legacy configs found + suggests praisonai doctor runtime --fix.
• With --fix and --dry-run: reports preview of changes; suggests --fix --execute.
• With --fix --execute: writes migrated YAML, leaves a <stem>.backup.<YYYYMMDD_HHMMSS>.yaml next to the original.
• If --file is supplied but the file does not exist: ERROR, severity HIGH.
• If no config file is found: SKIP.

6. Additional new doctor subcommands shipped in the same PR

These are typer wrappers that forward to the existing doctor handler:

Command	Help text
praisonai doctor docker	Check Docker installation and configuration
praisonai doctor llm-providers	Check LLM providers configuration
praisonai doctor memory-store	Check memory store backends
praisonai doctor metadata-store	Check metadata store configuration

All accept --deep and --json (except metadata-store, which is --json only).

7. Improved error messaging

doctor now distinguishes "module missing" from "module failed" in its error output (per the PR's "Bug Fixes" entry).

---

Documentation gap analysis

Searched docs repo. Current state:

Doc	Status	Mentions new behaviour?
docs/cli/doctor.mdx	exists	❌ No runtime, docker, llm-providers, memory-store, metadata-store subcommands
docs/cli/doctor-cli.mdx	exists	❌ Same as above
docs/features/cli-backend-protocol.mdx	exists	❌ No mention that cli_backend is now migratable via doctor
docs/features/yaml-configuration-reference.mdx	exists	❌ Still lists cli_backend without a deprecation/migration pointer
docs/features/doctor-migration.mdx (or similar)	does not exist	❌ No coverage of DoctorContractProtocol / Finding / plugin entry point

A repo-wide search for DoctorContractProtocol returns 0 hits in the docs repo.

---

Work to do

This needs both new content and updates. Per AGENTS.md, place all new pages under docs/features/ (never docs/concepts/).

A. NEW page — docs/features/doctor-runtime-migration.mdx

Agent-centric, user-friendly. Frontmatter:

---
title: "Runtime Config Migration"
sidebarTitle: "Runtime Migration"
description: "Migrate legacy cli_backend YAML to model-scoped runtime config with praisonai doctor"
icon: "stethoscope"
---

Must cover, in this order:

1. One-sentence opener. "praisonai doctor runtime detects legacy cli_backend fields in your agent YAML and migrates them to the new models.<default>.runtime field."

2. Hero Mermaid diagram (LR) using the standard palette (#8B0000, #189AB4, #10B981, #F59E0B, #6366F1, white text, #7C90A0 strokes) — show: agents.yaml (legacy cli_backend) → doctor scan → findings → --fix --execute → migrated yaml + backup.

3. Quick Start (<Steps>):

   • Step "Scan only": praisonai doctor runtime — show output snippet (WARN: Found N legacy configuration(s)…).
   • Step "Preview fix (dry-run)": praisonai doctor runtime --fix — preview of changes.
   • Step "Apply fix with backup": praisonai doctor runtime --fix --execute — note backup filename pattern <stem>.backup.<YYYYMMDD_HHMMSS>.yaml.
   • Step "Target a specific file": praisonai doctor runtime --fix --execute --file my-agents.yaml.

4. What gets migrated — show a before/after YAML pair:

   Before:

   cli_backend: claude-code
   roles:
     researcher:
       cli_backend: openai-gpt

   After:

   models:
     default:
       runtime: claude-code
   roles:
     researcher:
       models:
         default:
           runtime: openai-gpt

5. How it works — sequence diagram: user → praisonai doctor runtime → registry → built-in rule + plugin rules → findings → optional apply + YAML backup.

6. Flags reference table for praisonai doctor runtime (copy from the table above).

7. Writing a custom rule (plugin authors) — show DoctorContractProtocol implementation and the praisonai.doctor_contracts entry-point registration in pyproject.toml:

   from praisonaiagents.runtime import DoctorContractProtocol, Finding, register_rule
   
   class MyRule:
       @property
       def rule_id(self) -> str:
           return "my_org.deprecate_foo"
       def collect_findings(self, config):
           if "foo" in config:
               return [Finding(rule_id=self.rule_id, severity="warning",
                               message="`foo` is deprecated, use `bar` instead",
                               fix_description="Rename foo → bar")]
           return []
       def apply_fix(self, config):
           if "foo" in config:
               config["bar"] = config.pop("foo")
           return config

   [project.entry-points."praisonai.doctor_contracts"]
   my_org_foo = "my_pkg.rules:MyRule"

8. Programmatic API — friendly imports:

   from praisonaiagents.runtime import collect_findings, apply_fixes

   Show collect_findings(yaml_dict) and apply_fixes(yaml_dict) returning a new dict.

9. Best Practices (<AccordionGroup> × 3–4): run --dry-run first, commit before --execute, keep backups, prefer entry-point registration over manual register_rule() in apps.

10. Related (<CardGroup cols={2}>): /docs/cli/doctor, /docs/features/cli-backend-protocol.

B. UPDATE — docs/cli/doctor.mdx

In the Subcommands table, add rows:

Subcommand	Description
docker	Check Docker installation and configuration
llm-providers	Check LLM providers configuration
memory-store	Check memory store backends
metadata-store	Check metadata store configuration
runtime	Check runtime configuration and migrate legacy cli_backend settings

Add a new "Runtime Migration" example section that shows praisonai doctor runtime, … --fix, … --fix --execute, and … --file ./teams/agents.yaml. Add a sentence pointing to the new /docs/features/doctor-runtime-migration page.

C. UPDATE — docs/cli/doctor-cli.mdx

Add CLI-reference snippets for the same four subcommands plus runtime, mirroring the style of the existing Database Checks, MCP Checks, etc. sections. Document all flags from the table above.

D. UPDATE — docs/features/cli-backend-protocol.mdx

Add a top-of-page <Warning> (or <Info>) callout:

cli_backend at the agent/YAML root is now a legacy field. Prefer models.<default>.runtime. Run praisonai doctor runtime --fix --execute to migrate existing YAML automatically. See Runtime Config Migration.

E. UPDATE — docs/features/yaml-configuration-reference.mdx

In the YAML field table, mark cli_backend as "Legacy — see models.<default>.runtime and /docs/features/doctor-runtime-migration".

F. docs.json navigation

Add docs/features/doctor-runtime-migration under the Features group (never under Concepts — docs/concepts/ is human-only per AGENTS.md).

---

SDK source-of-truth references (read before writing)

All paths in MervinPraison/PraisonAI@main:

• src/praisonai-agents/praisonaiagents/runtime/__init__.py — re-exports
• src/praisonai-agents/praisonaiagents/runtime/doctor_protocol.py — Finding, DoctorContractProtocol
• src/praisonai-agents/praisonaiagents/runtime/doctor_registry.py — registry + plugin discovery
• src/praisonai-agents/praisonaiagents/runtime/builtin_rules.py — CliBackendMigrationRule
• src/praisonai/praisonai/cli/commands/doctor.py — typer subcommands and flag wiring
• src/praisonai/praisonai/cli/features/doctor/checks/runtime_migration_checks.py — actual check + backup logic
• src/praisonai-agents/tests/unit/test_runtime_doctor.py — behavioral truth (use to derive examples; do not invent behavior not covered by tests)

---

Style requirements (from AGENTS.md)

• Place new file in docs/features/, never in docs/concepts/.
• Mintlify frontmatter (title, sidebarTitle, description, icon: "stethoscope").
• Hero Mermaid diagram using the standard color palette and white text.
• Use <Steps> for Quick Start, <AccordionGroup> for Best Practices, <CardGroup> for Related.
• Friendly imports only: from praisonaiagents.runtime import ... — no deep submodule paths.
• Agent-centric framing: open with the user's CLI command, not internal class names.
• No forbidden phrases ("In this section…", "As you can see…", etc.).
• Add the new page to docs.json under the existing Features group.

---

Acceptance criteria

• New page docs/features/doctor-runtime-migration.mdx created and matches AGENTS.md structure (hero diagram, Quick Start, How It Works, Flags, Custom Rule, Programmatic API, Best Practices, Related).
• docs/cli/doctor.mdx updated with the 5 new subcommands.
• docs/cli/doctor-cli.mdx updated with new subcommand reference sections.
• docs/features/cli-backend-protocol.mdx updated with deprecation/migration callout.
• docs/features/yaml-configuration-reference.mdx cli_backend row updated.
• docs.json navigation includes the new page under the Features group.
• All code examples copy-paste run; no placeholder values.
• No edits under docs/concepts/, docs/js/, or docs/rust/.

[MervinPraison]

🤖 Auto-triaging with Claude. Analyzing issue and implementing a fix...

Claude will:

1. Classify this issue
2. Search codebase for root cause
3. Implement a minimal fix following AGENTS.md
4. Create a PR with the changes

[MervinPraison]

Claude finished @MervinPraison's task —— View job • claude/issue-727-20260622-2355 • [Create PR ➔](https://github.com/MervinPraison/PraisonAIDocs/compare/main...claude/issue-727-20260622-2355?quick_pull=1&title=Issue%20%23727%3A%20Changes%20from%20Claude&body=This%20PR%20addresses%20issue%20%23727%0A%0AGenerated%20with%20%5BClaude%20Code%5D(https%3A%2F%2Fclaude.ai%2Fcode)

---

Documentation Updates Complete ✅

All tasks completed:

• Setup git identity
• Read AGENTS.md for style guidelines
• Read existing docs for context
• Create docs/features/doctor-runtime-migration.mdx — new page with hero Mermaid diagram, Quick Start (Steps), before/after YAML migration, How It Works sequence diagram, flags reference, custom rule authoring with DoctorContractProtocol, programmatic API, Best Practices, and Related cards
• Update docs/cli/doctor.mdx — added docker, llm-providers, memory-store, metadata-store, runtime to subcommands table + example sections
• Update docs/cli/doctor-cli.mdx — added Runtime Migration Checks section with flags table + new subcommand reference sections
• Update docs/features/cli-backend-protocol.mdx — added <Warning> callout marking cli_backend as legacy with migration pointer
• Update docs/features/yaml-configuration-reference.mdx — marked cli_backend row as Legacy with pointer to new migration guide
• Update docs.json navigation — added doctor-runtime-migration under Integration & Infrastructure Features group
• Commit, push, and create PR

PR: #730
| Branch: claude/issue-727-20260622-2355