fix: publish agents.yaml JSON Schema + wire editor autocomplete/validation

src/praisonai/praisonai/auto.py

@@ -1107,11 +1107,26 @@ def convert_and_save(self, json_data, merge=False):
                 for task_id, task_details in role_details['tasks'].items():
                     yaml_data['roles'][role_id]['tasks'][task_id] = self._format_task(task_details)
 
-        # Save to YAML file atomically, maintaining the order
-        _atomic_write_text(
-            self.agent_file,
-            lambda f: _yaml_dump(yaml_data, f, allow_unicode=True, sort_keys=False),
-        )
+        # Save to YAML file atomically, maintaining the order. Prepend the
+        # yaml-language-server header so editors give autocomplete / inline
+        # validation for the scaffolded agents.yaml out of the box. A leading
+        # YAML comment is ignored by yaml.safe_load, so execution is unaffected.
+        def _write_with_header(f):
+            try:
+                from .config.schema import AGENTS_SCHEMA_HEADER
+                f.write(AGENTS_SCHEMA_HEADER)
+            except Exception as exc:
+                # Non-fatal: the YAML is still valid/executable without the
+                # editor header, but surface it so a missing schema directive
+                # is diagnosable instead of silently dropped.
+                logger.debug(
+                    "Could not write yaml-language-server schema header to %s: %s",
+                    self.agent_file,
+                    exc,
+                )
+            _yaml_dump(yaml_data, f, allow_unicode=True, sort_keys=False)
+
+        _atomic_write_text(self.agent_file, _write_with_header)
 
     def merge_with_existing_agents(self, new_json_data):
         """

src/praisonai/praisonai/cli/commands/validate.py

@@ -227,7 +227,20 @@ def check(
 
 
 @app.command()
-def schema():
+def schema(
+    agents: bool = typer.Option(
+        False,
+        "--agents",
+        help="Emit the machine-readable JSON Schema for agents.yaml "
+             "(derived from YAMLConfig) instead of the human-readable summary.",
+    ),
+    output: Optional[str] = typer.Option(
+        None,
+        "--output", "-o",
+        help="Write the JSON Schema to a file instead of stdout "
+             "(implies --agents; useful for offline/pinned editor setups).",
+    ),
+):
     """
     Display the YAML configuration schema documentation.
 
@@ -236,10 +249,34 @@ def schema():
     - Task configuration  
     - Workflow configuration
     - Global settings
+
+    With --agents (or --output), emit the machine-readable JSON Schema for
+    agents.yaml so you can point your editor's YAML language server at a local
+    file:
+
+        praisonai validate schema --agents            # print to stdout
+        praisonai validate schema -o agents.schema.json  # write to a file
     """
     from praisonai.config.schema import YAMLConfig, AgentConfig, TaskConfig
     import json
-
+
+    # Emit the machine-readable JSON Schema for offline/pinned editor setups.
+    if agents or output:
+        from praisonai.config.schema import generate_agents_schema
+
+        schema_json = json.dumps(generate_agents_schema(), indent=2)
+        if output:
+            out_path = Path(output)
+            try:
+                out_path.write_text(schema_json + "\n", encoding="utf-8")
+            except OSError as exc:
+                console.print(f"[red]✗ Failed to write {out_path}:[/red] {exc}")
+                sys.exit(1)
+            console.print(f"[green]✓ Wrote agents JSON Schema to[/green] {out_path}")
+        else:
+            sys.stdout.write(schema_json + "\n")
+        return
+
     console.print("[bold cyan]PraisonAI YAML Configuration Schema[/bold cyan]\n")
 
     # Display main sections

src/praisonai/praisonai/config/__init__.py

@@ -17,6 +17,9 @@
     RuntimeConfig,
     CliBackendConfig,
     GlobalConfig,
+    AGENTS_SCHEMA_URL,
+    AGENTS_SCHEMA_HEADER,
+    generate_agents_schema,
 )
 
 from .validator import ConfigValidator
@@ -37,4 +40,7 @@
     'CliBackendConfig',
     'GlobalConfig',
     'ConfigValidator',
+    'AGENTS_SCHEMA_URL',
+    'AGENTS_SCHEMA_HEADER',
+    'generate_agents_schema',
 ]