Clarify workspace-core as the chat-host onramp

Make the recommended MCP profile visible from the first help and docs pass without changing 3.x behavior.

Rework  help, top-level docs, public-contract wording, and shipped MCP/OpenAI examples so  is the recommended first profile while  stays the compatibility default for full-surface hosts.

Bump the package and catalog to 3.8.0, mark the roadmap milestone done, and add regression coverage for the new MCP help and docs alignment. Validation included uv lock, targeted profile/help tests, make check, make dist-check, and a real guest-backed  server smoke.

src/pyro_mcp/api.py

@@ -463,6 +463,11 @@ class Pyro:
         )
 
     def create_server(self, *, profile: McpToolProfile = "workspace-full") -> FastMCP:
+        """Create an MCP server for one of the stable public tool profiles.
+
+        `workspace-full` remains the default for 3.x compatibility. New chat
+        hosts should usually start with `profile="workspace-core"`.
+        """
         normalized_profile = _validate_mcp_profile(profile)
         enabled_tools = set(_PROFILE_TOOLS[normalized_profile])
         server = FastMCP(name="pyro_mcp")

src/pyro_mcp/cli.py

@@ -746,13 +746,14 @@ def _build_parser() -> argparse.ArgumentParser:
         help="Run the MCP server.",
         description=(
             "Run the MCP server after you have already validated the host and "
-            "guest execution with `pyro doctor` and `pyro run`."
+            "guest execution with `pyro doctor` and `pyro run`. Start most "
+            "chat hosts with `workspace-core`."
         ),
         epilog=dedent(
             """
             Examples:
-              pyro mcp serve --profile vm-run
               pyro mcp serve --profile workspace-core
+              pyro mcp serve --profile vm-run
               pyro mcp serve --profile workspace-full
             """
         ),
@@ -762,18 +763,23 @@ def _build_parser() -> argparse.ArgumentParser:
     mcp_serve_parser = mcp_subparsers.add_parser(
         "serve",
         help="Run the MCP server over stdio.",
-        description="Expose pyro tools over stdio for an MCP client.",
+        description=(
+            "Expose pyro tools over stdio for an MCP client. "
+            "`workspace-core` is the recommended first profile for most chat hosts."
+        ),
         epilog=dedent(
             """
-            Example:
+            Recommended first start:
               pyro mcp serve --profile workspace-core
 
             Profiles:
-              vm-run: only the vm_run tool
-              workspace-core: vm_run plus the practical workspace chat loop
-              workspace-full: the full stable workspace surface
+              workspace-core: recommended default for normal persistent chat editing
+              vm-run: smallest one-shot-only surface
+              workspace-full: advanced 3.x compatibility surface for shells, services,
+                snapshots, secrets, network policy, and disk tools
 
-            Use this from an MCP client config after the CLI evaluation path works.
+            `workspace-full` remains the default in 3.x for compatibility, but most new
+            chat hosts should start with `workspace-core`.
             """
         ),
         formatter_class=_HelpFormatter,
@@ -783,8 +789,9 @@ def _build_parser() -> argparse.ArgumentParser:
         choices=PUBLIC_MCP_PROFILES,
         default="workspace-full",
         help=(
-            "Expose only one model-facing tool profile. "
-            "`workspace-full` preserves the current full MCP surface."
+            "Expose only one model-facing tool profile. `workspace-core` is the "
+            "recommended first profile for most chat hosts; `workspace-full` "
+            "preserves the current full MCP surface for 3.x compatibility."
         ),
     )
 

src/pyro_mcp/server.py

@@ -13,7 +13,11 @@ def create_server(
     *,
     profile: McpToolProfile = "workspace-full",
 ) -> FastMCP:
-    """Create and return a configured MCP server instance."""
+    """Create and return a configured MCP server instance.
+
+    `workspace-full` remains the default for 3.x compatibility. New chat hosts
+    should usually start with `profile="workspace-core"`.
+    """
     return Pyro(manager=manager).create_server(profile=profile)
 
 

src/pyro_mcp/vm_environments.py

@@ -19,7 +19,7 @@ from typing import Any
 from pyro_mcp.runtime import DEFAULT_PLATFORM, RuntimePaths
 
 DEFAULT_ENVIRONMENT_VERSION = "1.0.0"
-DEFAULT_CATALOG_VERSION = "3.7.0"
+DEFAULT_CATALOG_VERSION = "3.8.0"
 OCI_MANIFEST_ACCEPT = ", ".join(
     (
         "application/vnd.oci.image.index.v1+json",