Unify workspace config paths, adopt XDG defaults, and standardize runtime as mas-runtime-py. (#2)

Centralize filenames and runtime id in mas.runtime.constants; add CI literal
check; migrate all docs to $XDG_* path variables with user-config.md as canonical reference.

Signed-off-by: Jordan Augé <augjorda@cisco.com>

Author: jordanauge

.github/workflows/test.yml

@@ -16,6 +16,7 @@ on:
       - "examples/**"
       - "Taskfile.yml"
       - "pyproject.toml"
+      - "scripts/**"
       - ".github/workflows/test.yml"
   push:
     branches: [ main ]
@@ -48,7 +49,7 @@ jobs:
           sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b "${{ runner.temp }}/bin"
           echo "${{ runner.temp }}/bin" >> "$GITHUB_PATH"
 
-      - name: CI gates (Taskfile ci = verify-unit + verify-functional + validate)
+      - name: CI gates (Taskfile ci = verify:literals + verify-unit + verify-functional + validate)
         run: task ci
 
       - name: Coverage gate (kernel, ctl.workspace, bench pipeline)

Taskfile.yml

@@ -34,6 +34,11 @@ tasks:
       - uv pip install -e library-samples
       - uv pip install pytest pytest-asyncio pytest-cov pytest-timeout import-linter pyyaml click python-dotenv jsonschema httpx certifi truststore pyarrow
 
+  verify:literals:
+    desc: "Forbidden path/id literal gate (scripts/check_literals.py)"
+    cmds:
+      - python3 scripts/check_literals.py
+
   verify-unit:
     desc: "Unit tests — repo gates + v2 lab/bench/core packages"
     deps: [install-dev]
@@ -112,6 +117,7 @@ tasks:
     desc: "CI parity — same gates as .github/workflows/test.yml (unit + functional + dry-run)"
     deps: [install-dev]
     cmds:
+      - task: verify:literals
       - task: verify-unit
       - task: verify-functional
       - task: validate
@@ -163,6 +169,7 @@ tasks:
     cmds:
       - python3 scripts/version_manager.py check
       - task: verify-ctl-env
+      - task: verify:literals
       - task: verify-unit
       - task: verify-functional
       - task: verify-chat-smoke
@@ -185,13 +192,15 @@ tasks:
       - uv pip install -e runtime -e ctl -e library-standard -e lab -e library-eval -e library-lab -e library-samples
 
   docs-gen:
-    desc: "Regenerate docs/packages-reference.md and docs/plugins-reference.md from manifests."
+    desc: "Regenerate docs/packages-reference.md, docs/plugins-reference.md, and path snippets."
     summary: |
-      Reads pyproject.toml files and library.yaml manifests to regenerate two
-      reference pages under docs/.  Run after adding, removing, or renaming
-      any package or plugin.  The generated files are checked-in — commit them
-      together with your manifest changes (required for every PR that touches
-      packages or plugins).
+      Reads pyproject.toml files and library.yaml manifests to regenerate reference
+      pages under docs/, and writes docs/includes/mas-paths.md from runtime path
+      constants (MkDocs pymdownx.snippets).
+      Run after adding, removing, or renaming any package or plugin, or after
+      changing canonical path defaults.  The generated files are checked-in —
+      commit them together with your manifest changes (required for every PR that
+      touches packages, plugins, or path constants).
       Use `python3 scripts/gen_docs.py --check` (or task verify-reproduce) in CI.
     cmds:
       - python3 scripts/gen_docs.py --root . --output-dir docs

ctl/README.md

@@ -73,8 +73,8 @@ Named overlay for A/B configuration without duplicating manifests.
 
 ### Workspace
 
-`~/.mas/config.yaml` and optional `mas-workspace.yaml` — see
-[docs/user-config.md](../docs/user-config.md).
+`$XDG_CONFIG_HOME/mas/config.yaml` and optional project `config.yaml` — see
+[docs/user-config.md](../docs/user-config.md) for the full XDG layout.
 
 ---
 
@@ -140,7 +140,6 @@ Flavours ship in **`library-standard`** and resolve by name:
 |----------|--------|
 | [docs/user-guide.md](docs/user-guide.md) | Operational guide |
 | [docs/developer-guide.md](docs/developer-guide.md) | Manifest and compose extensions |
-| [docs/architecture-v2-compose.md](docs/architecture-v2-compose.md) | Compose pipeline |
 | [../docs/manifests/](../docs/manifests/README.md) | YAML reference |
 | [../docs/libraries.md](../docs/libraries.md) | Package matrix |
 | [../docs/cli/observability.md](../docs/cli/observability.md) | Trace emission and event artifacts |

ctl/docs/architecture-v2-compose.md

@@ -10,10 +10,10 @@ metadata:
 
 spec:
   runtimes:
-    - id: python-v2
+    - id: mas-runtime-py
       layer: ctl.runtime
-      module: mas.ctl.compose.backends.python_v2.PythonV2KernelBackend
-      description: Python Mealy kernel v2 (OSS)
+      module: mas.ctl.compose.backends.mas_runtime_py.MasRuntimePyKernelBackend
+      description: Python Mealy kernel (OSS default)
       status: available
 
   placement:

ctl/docs/schemas/component-registry.yaml

@@ -75,18 +75,20 @@ def index_seeds_in_semantic_memory(
     seeds: list[MemorySeed],
     *,
     agent_id: str = "default",
-    db_path: str = "~/.mas/memory/{agent_id}.sqlite",
+    db_path: str | None = None,
 ) -> None:
     """Index memory_seed entries into SemanticMemoryPlugin's SQLite store."""
     if not seeds:
         return
     try:
         from mas.library.standard.plugins.memory.memory_semantic import SemanticMemoryPlugin
+        from mas.runtime.boundary.memory.semantic import default_store_path
     except ImportError:
         logger.debug("SemanticMemoryPlugin unavailable — skipping seed indexing")
         return
 
-    mem = SemanticMemoryPlugin(db_path=db_path, context_inject=False)
+    resolved = db_path or str(default_store_path(agent_id))
+    mem = SemanticMemoryPlugin(db_path=resolved, context_inject=False)
     mem.agent_id = agent_id
     for seed in seeds:
         payload: dict[str, Any] = {

ctl/src/mas/ctl/adapters/memory_seed.py

@@ -1,6 +1,6 @@
 #  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
 #  SPDX-License-Identifier: Apache-2.0
-"""Bench runner for python-v2 kernel."""
+"""Bench runner for the default ctl runtime."""
 
 from __future__ import annotations
 

ctl/src/mas/ctl/benchmark/__init__.py

@@ -1,6 +1,6 @@
 #  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
 #  SPDX-License-Identifier: Apache-2.0
-"""MAS bench integration — python-v2 kernel path for mas-lab benchmark."""
+"""MAS bench integration — default ctl runtime path for mas-lab benchmark."""
 
 from __future__ import annotations
 
@@ -16,6 +16,8 @@
 from mas.ctl.ui.stdout import StdoutConversationDisplay
 from mas.ctl.workspace.config import UserConfig, WorkspaceConfig, collect_mas_infra_refs, merge_infra_refs
 
+from mas.lab.runners.constants import DEFAULT_LAB_RUNNER_ID
+
 logger = logging.getLogger(__name__)
 
 
@@ -56,7 +58,7 @@ def _memory_seeds_from_run_input(
 class MasBenchRunner:
     """Execute agent prompts via v2 SessionController (bench harness integration)."""
 
-    runner_id: str = "mas-v2"
+    runner_id: str = DEFAULT_LAB_RUNNER_ID
 
     def run(
         self,
@@ -171,11 +173,11 @@ def run(
             content=text,
             status="ok",
             artifacts=artifacts,
-            metadata={"run_seed": run_seed, "kernel": "python-v2", "turns": len(queries)},
+            metadata={"run_seed": run_seed, "turns": len(queries)},
         )
 
 
 def select_mas_runner(*, runtime_id: str | None = None) -> MasBenchRunner:
-    """Return the v2 bench runner."""
+    """Return the default MAS bench runner."""
     _ = runtime_id
     return MasBenchRunner()

ctl/src/mas/ctl/benchmark/runner.py

@@ -9,7 +9,9 @@
 import click
 import yaml
 
+from mas.ctl.cli.runtime_flags import runtime_id_choice
 from mas.ctl.compose.runner import ComposeRequest, compose_run
+from mas.ctl.deployment.runtime_id import DEFAULT_RUNTIME_ID
 from mas.ctl.paths import manifest_cwd, resolve_overlay_path
 
 
@@ -56,8 +58,8 @@ def _compose_run(
 @click.option(
     "--kernel",
     "kernel_backend",
-    default="python-v2",
-    type=click.Choice(["python-v2"], case_sensitive=False),
+    default=DEFAULT_RUNTIME_ID,
+    type=runtime_id_choice(),
 )
 @click.option("--output", "-O", "output_path", default=None, type=click.Path())
 @click.option("--no-validate", is_flag=True, help="Skip manifest validation")
@@ -90,7 +92,7 @@ def compose_cmd(
 @click.command("plan")
 @click.argument("manifest", type=click.Path())
 @click.option("--deployment", "-d", "deployment_path", default=None, type=click.Path())
-@click.option("--kernel", "kernel_backend", default="python-v2")
+@click.option("--kernel", "kernel_backend", default=DEFAULT_RUNTIME_ID, type=runtime_id_choice())
 @click.option("--no-validate", is_flag=True)
 def plan_cmd(
     manifest: str,

ctl/src/mas/ctl/cli/commands/compose.py

@@ -10,6 +10,8 @@
 import yaml
 
 from mas.ctl.cli.obs_flags import observability_options, resolve_observability_config
+from mas.ctl.cli.runtime_flags import runtime_id_choice
+from mas.ctl.deployment.runtime_id import DEFAULT_RUNTIME_ID
 from mas.ctl.executor.run_mas import execute_run_mas
 
 
@@ -22,8 +24,8 @@
 @click.option("--infra-ref", "infra_refs", multiple=True)
 @click.option(
     "--kernel",
-    default="python-v2",
-    type=click.Choice(["python-v2"], case_sensitive=False),
+    default=DEFAULT_RUNTIME_ID,
+    type=runtime_id_choice(),
 )
 @click.option("-i", "--interactive", is_flag=True)
 @click.option(