codexmgr 0.1.1__tar.gz → 0.1.2__tar.gz

{codexmgr-0.1.1 → codexmgr-0.1.2}/.gitignore

@@ -9,3 +9,7 @@ wheels/
 # Virtual environments
 .venv
 AGENTS.md
+tasks.md
+.thoughts
+.plan
+.agent

{codexmgr-0.1.1 → codexmgr-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codexmgr
-Version: 0.1.1
+Version: 0.1.2
 Summary: Manage project-local Codex configuration from reusable templates
 Keywords: agents,cli,codex,configuration,skills
 Classifier: Development Status :: 4 - Beta
@@ -13,8 +13,10 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
+Requires-Dist: tomlkit>=0.15.0
 Provides-Extra: dev
 Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Requires-Dist: pyyaml>=6.0.3; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # codexmgr
@@ -22,12 +24,14 @@ Description-Content-Type: text/markdown
 `codexmgr` manages project-local Codex configuration from reusable templates.
 It keeps hand-written project instructions in `AGENTS.md` and generated Codex
 configuration in `.codex/` synchronized from a small declarative
-`.codex/codexmgr.toml` file.
+`.codex/codexmgr.toml` file. It can also keep project-local MCP server
+overrides in sync without editing the user Codex config.
 
 The tool is intentionally narrow:
 
 - compose reusable AGENTS.md instruction fragments
 - enable or disable Codex skills per project
+- enable, disable, inspect, and update safe project-local MCP overrides
 - write reproducible lock data for the resolved project configuration
 - run `codex` with project `.codex/config.toml` values translated into `-c`
   overrides
@@ -91,8 +95,10 @@ This updates `.codex/codexmgr.toml`, runs `apply`, writes
 
 - `.codex/codexmgr.toml`: source configuration edited by CLI commands or by
   hand
-- `.codex/codexmgr.lock`: resolved template and skill state written by `apply`
+- `.codex/codexmgr.lock`: resolved template, skill, and MCP state written by
+  `apply`
 - `.codex/config.toml`: Codex config updated with `[[skills.config]]` entries
+  and `[mcp_servers.<id>]` overrides
 - `AGENTS.md`: project instructions, with only the managed block replaced
 
 The managed AGENTS.md block is:
@@ -107,7 +113,8 @@ Manual content outside this block is preserved. If the block is missing,
 
 ## Project Configuration
 
-`.codex/codexmgr.toml` supports AGENTS.md templates and skill state:
+`.codex/codexmgr.toml` supports AGENTS.md templates, skill state, and MCP
+overrides:
 
 ```toml
 [agents_md]
@@ -116,6 +123,11 @@ src = ["coding", "/absolute/or/project-relative/template.toml"]
 [skills]
 enabled = ["review-helper"]
 disabled = ["experimental-skill", "skills/local-disabled"]
+
+[mcp.servers.browsermcp]
+enabled = true
+bearer_token_env_var = "BROWSERMCP_TOKEN"
+env_vars = ["BROWSER_ENV"]
 ```
 
 Named AGENTS.md templates resolve from `$CODEXMGR_HOME/agentsmd/<name>.toml`.
@@ -163,10 +175,31 @@ keeps template mistakes visible during `apply`.
 ```bash
 codexmgr setup
 codexmgr apply
+codexmgr apply --check
+codexmgr apply --diff
+codexmgr cd [--path | --explorer | --terminal]
+codexmgr doctor
+codexmgr status
+codexmgr agentsmd list
+codexmgr agentsmd show <name-or-template-path>
+codexmgr agentsmd validate <name-or-template-path>
 codexmgr agentsmd add [--no-sync] <name-or-template-path>
 codexmgr agentsmd remove [--no-sync] <name-or-template-path>
+codexmgr init-template agentsmd <name>
+codexmgr skill list
 codexmgr skill enable [--no-sync] <name-or-skill-path>
 codexmgr skill disable [--no-sync] <name-or-skill-path>
+codexmgr mcp list
+codexmgr mcp show <server-id>
+codexmgr mcp validate
+codexmgr mcp enable [--no-sync] <server-id>
+codexmgr mcp disable [--no-sync] <server-id>
+codexmgr mcp set-token-env [--no-sync] <server-id> <ENV_VAR>
+codexmgr mcp add-env-var [--no-sync] <server-id> <ENV_VAR>
+codexmgr mcp remove-env-var [--no-sync] <server-id> <ENV_VAR>
+codexmgr mcp set-env-header [--no-sync] <server-id> <HEADER> <ENV_VAR>
+codexmgr mcp unset-env-header [--no-sync] <server-id> <HEADER>
+codexmgr mcp set-field [--no-sync] <server-id> <field> <toml-value>
 codexmgr codex <args...>
 ```
 
@@ -174,8 +207,91 @@ codexmgr codex <args...>
 
 `apply` reads `.codex/codexmgr.toml`, resolves configured sources, writes
 `.codex/codexmgr.lock`, updates `.codex/config.toml` skill entries when a
-`[skills]` table is configured, and refreshes the generated `AGENTS.md` block
-when `[agents_md]` is configured.
+`[skills]` table is configured, writes local `[mcp_servers.<id>]` overrides when
+`[mcp]` is configured, and refreshes the generated `AGENTS.md` block when
+`[agents_md]` is configured.
+
+`apply --check` exits with a failure if generated files are out of sync without
+writing them. `apply --diff` also avoids writing and prints unified diffs for
+the expected generated-file changes.
+
+`cd` launches a shell in `$CODEXMGR_HOME`. Use
+`codexmgr cd --path` to print only the path, `codexmgr cd --explorer` to open
+the directory in a file explorer, and `codexmgr cd --terminal` to open a new
+terminal there.
+
+`doctor` checks project setup, home environment variables, project TOML syntax,
+referenced snippets, enabled skills, and stale generated files.
+
+`status` prints the resolved homes, configured snippets and skills, and whether
+generated files are in sync.
+
+## Project MCP Overrides
+
+`codexmgr mcp ...` edits only project-local configuration:
+
+- source state is stored in `.codex/codexmgr.toml` under
+  `[mcp.servers.<id>]`
+- `apply` writes generated overrides into `.codex/config.toml` under
+  `[mcp_servers.<id>]`
+- `$CODEX_HOME/config.toml` and `~/.codex/config.toml` are never modified
+
+Mutating MCP commands require a project `.codex/` directory and run `apply`
+automatically unless `--no-sync` is passed. They do not create or remove MCP
+server definitions; use `codex mcp add` or direct Codex config editing for the
+base server setup.
+
+List MCP servers available from Codex and show any project override state:
+
+```bash
+codexmgr mcp list
+codexmgr mcp show context7
+codexmgr mcp validate
+```
+
+`codexmgr mcp list` shells out to `codex mcp list --json` for read-only
+discovery. It does not edit user configuration.
+
+Enable or disable an existing server without deleting its definition:
+
+```bash
+codexmgr mcp disable context7
+codexmgr mcp enable context7
+```
+
+Update token and environment references without storing literal token values:
+
+```bash
+codexmgr mcp set-token-env figma FIGMA_TOKEN
+codexmgr mcp add-env-var context7 CONTEXT7_TOKEN
+codexmgr mcp remove-env-var context7 CONTEXT7_TOKEN
+codexmgr mcp set-env-header figma Authorization FIGMA_AUTH_HEADER
+codexmgr mcp unset-env-header figma Authorization
+```
+
+Set a small allowlist of non-secret fields from TOML literals:
+
+```bash
+codexmgr mcp set-field context7 required true
+codexmgr mcp set-field context7 enabled_tools '["search", "open"]'
+codexmgr mcp set-field context7 default_tools_approval_mode '"prompt"'
+```
+
+Supported `set-field` names are `required`, `startup_timeout_sec`,
+`tool_timeout_sec`, `enabled_tools`, `disabled_tools`, and
+`default_tools_approval_mode`. The direct `enable` and `disable` commands manage
+the `enabled` field.
+
+Literal API token writes are intentionally not part of this command surface;
+prefer environment variable references such as `bearer_token_env_var`,
+`env_vars`, and `env_http_headers`.
+
+`agentsmd list` prints the named templates available under
+`$CODEXMGR_HOME/agentsmd` in sorted order.
+
+`agentsmd show` renders one template as AGENTS.md markdown without changing the
+project configuration. `agentsmd validate` loads and renders a template to catch
+TOML or template-shape errors before adding it.
 
 `agentsmd add` validates that the template exists before writing config.
 Repeated adds keep one source entry.
@@ -183,6 +299,12 @@ Repeated adds keep one source entry.
 `agentsmd remove` removes a configured template source and fails if the source
 is not present.
 
+`init-template agentsmd` creates a starter template under
+`$CODEXMGR_HOME/agentsmd` and refuses to overwrite an existing template.
+
+`skill list` prints available `$CODEX_HOME/skills/*/SKILL.md` entries and marks
+configured skills as enabled, disabled, or missing.
+
 `skill enable` and `skill disable` keep enabled and disabled lists mutually
 exclusive. Repeated commands keep one entry.
 
@@ -212,8 +334,8 @@ uv build
 ```
 
 The package is typed (`py.typed`) and the test suite covers CLI behavior,
-template rendering, TOML writing, skill resolution, Codex command generation,
-home-directory resolution, and package metadata.
+template rendering, TOML writing, skill resolution, generated-file sync checks,
+Codex command generation, home-directory resolution, and package metadata.
 
 ## Release Notes
 

{codexmgr-0.1.1 → codexmgr-0.1.2}/README.md

@@ -3,12 +3,14 @@
 `codexmgr` manages project-local Codex configuration from reusable templates.
 It keeps hand-written project instructions in `AGENTS.md` and generated Codex
 configuration in `.codex/` synchronized from a small declarative
-`.codex/codexmgr.toml` file.
+`.codex/codexmgr.toml` file. It can also keep project-local MCP server
+overrides in sync without editing the user Codex config.
 
 The tool is intentionally narrow:
 
 - compose reusable AGENTS.md instruction fragments
 - enable or disable Codex skills per project
+- enable, disable, inspect, and update safe project-local MCP overrides
 - write reproducible lock data for the resolved project configuration
 - run `codex` with project `.codex/config.toml` values translated into `-c`
   overrides
@@ -72,8 +74,10 @@ This updates `.codex/codexmgr.toml`, runs `apply`, writes
 
 - `.codex/codexmgr.toml`: source configuration edited by CLI commands or by
   hand
-- `.codex/codexmgr.lock`: resolved template and skill state written by `apply`
+- `.codex/codexmgr.lock`: resolved template, skill, and MCP state written by
+  `apply`
 - `.codex/config.toml`: Codex config updated with `[[skills.config]]` entries
+  and `[mcp_servers.<id>]` overrides
 - `AGENTS.md`: project instructions, with only the managed block replaced
 
 The managed AGENTS.md block is:
@@ -88,7 +92,8 @@ Manual content outside this block is preserved. If the block is missing,
 
 ## Project Configuration
 
-`.codex/codexmgr.toml` supports AGENTS.md templates and skill state:
+`.codex/codexmgr.toml` supports AGENTS.md templates, skill state, and MCP
+overrides:
 
 ```toml
 [agents_md]
@@ -97,6 +102,11 @@ src = ["coding", "/absolute/or/project-relative/template.toml"]
 [skills]
 enabled = ["review-helper"]
 disabled = ["experimental-skill", "skills/local-disabled"]
+
+[mcp.servers.browsermcp]
+enabled = true
+bearer_token_env_var = "BROWSERMCP_TOKEN"
+env_vars = ["BROWSER_ENV"]
 ```
 
 Named AGENTS.md templates resolve from `$CODEXMGR_HOME/agentsmd/<name>.toml`.
@@ -144,10 +154,31 @@ keeps template mistakes visible during `apply`.
 ```bash
 codexmgr setup
 codexmgr apply
+codexmgr apply --check
+codexmgr apply --diff
+codexmgr cd [--path | --explorer | --terminal]
+codexmgr doctor
+codexmgr status
+codexmgr agentsmd list
+codexmgr agentsmd show <name-or-template-path>
+codexmgr agentsmd validate <name-or-template-path>
 codexmgr agentsmd add [--no-sync] <name-or-template-path>
 codexmgr agentsmd remove [--no-sync] <name-or-template-path>
+codexmgr init-template agentsmd <name>
+codexmgr skill list
 codexmgr skill enable [--no-sync] <name-or-skill-path>
 codexmgr skill disable [--no-sync] <name-or-skill-path>
+codexmgr mcp list
+codexmgr mcp show <server-id>
+codexmgr mcp validate
+codexmgr mcp enable [--no-sync] <server-id>
+codexmgr mcp disable [--no-sync] <server-id>
+codexmgr mcp set-token-env [--no-sync] <server-id> <ENV_VAR>
+codexmgr mcp add-env-var [--no-sync] <server-id> <ENV_VAR>
+codexmgr mcp remove-env-var [--no-sync] <server-id> <ENV_VAR>
+codexmgr mcp set-env-header [--no-sync] <server-id> <HEADER> <ENV_VAR>
+codexmgr mcp unset-env-header [--no-sync] <server-id> <HEADER>
+codexmgr mcp set-field [--no-sync] <server-id> <field> <toml-value>
 codexmgr codex <args...>
 ```
 
@@ -155,8 +186,91 @@ codexmgr codex <args...>
 
 `apply` reads `.codex/codexmgr.toml`, resolves configured sources, writes
 `.codex/codexmgr.lock`, updates `.codex/config.toml` skill entries when a
-`[skills]` table is configured, and refreshes the generated `AGENTS.md` block
-when `[agents_md]` is configured.
+`[skills]` table is configured, writes local `[mcp_servers.<id>]` overrides when
+`[mcp]` is configured, and refreshes the generated `AGENTS.md` block when
+`[agents_md]` is configured.
+
+`apply --check` exits with a failure if generated files are out of sync without
+writing them. `apply --diff` also avoids writing and prints unified diffs for
+the expected generated-file changes.
+
+`cd` launches a shell in `$CODEXMGR_HOME`. Use
+`codexmgr cd --path` to print only the path, `codexmgr cd --explorer` to open
+the directory in a file explorer, and `codexmgr cd --terminal` to open a new
+terminal there.
+
+`doctor` checks project setup, home environment variables, project TOML syntax,
+referenced snippets, enabled skills, and stale generated files.
+
+`status` prints the resolved homes, configured snippets and skills, and whether
+generated files are in sync.
+
+## Project MCP Overrides
+
+`codexmgr mcp ...` edits only project-local configuration:
+
+- source state is stored in `.codex/codexmgr.toml` under
+  `[mcp.servers.<id>]`
+- `apply` writes generated overrides into `.codex/config.toml` under
+  `[mcp_servers.<id>]`
+- `$CODEX_HOME/config.toml` and `~/.codex/config.toml` are never modified
+
+Mutating MCP commands require a project `.codex/` directory and run `apply`
+automatically unless `--no-sync` is passed. They do not create or remove MCP
+server definitions; use `codex mcp add` or direct Codex config editing for the
+base server setup.
+
+List MCP servers available from Codex and show any project override state:
+
+```bash
+codexmgr mcp list
+codexmgr mcp show context7
+codexmgr mcp validate
+```
+
+`codexmgr mcp list` shells out to `codex mcp list --json` for read-only
+discovery. It does not edit user configuration.
+
+Enable or disable an existing server without deleting its definition:
+
+```bash
+codexmgr mcp disable context7
+codexmgr mcp enable context7
+```
+
+Update token and environment references without storing literal token values:
+
+```bash
+codexmgr mcp set-token-env figma FIGMA_TOKEN
+codexmgr mcp add-env-var context7 CONTEXT7_TOKEN
+codexmgr mcp remove-env-var context7 CONTEXT7_TOKEN
+codexmgr mcp set-env-header figma Authorization FIGMA_AUTH_HEADER
+codexmgr mcp unset-env-header figma Authorization
+```
+
+Set a small allowlist of non-secret fields from TOML literals:
+
+```bash
+codexmgr mcp set-field context7 required true
+codexmgr mcp set-field context7 enabled_tools '["search", "open"]'
+codexmgr mcp set-field context7 default_tools_approval_mode '"prompt"'
+```
+
+Supported `set-field` names are `required`, `startup_timeout_sec`,
+`tool_timeout_sec`, `enabled_tools`, `disabled_tools`, and
+`default_tools_approval_mode`. The direct `enable` and `disable` commands manage
+the `enabled` field.
+
+Literal API token writes are intentionally not part of this command surface;
+prefer environment variable references such as `bearer_token_env_var`,
+`env_vars`, and `env_http_headers`.
+
+`agentsmd list` prints the named templates available under
+`$CODEXMGR_HOME/agentsmd` in sorted order.
+
+`agentsmd show` renders one template as AGENTS.md markdown without changing the
+project configuration. `agentsmd validate` loads and renders a template to catch
+TOML or template-shape errors before adding it.
 
 `agentsmd add` validates that the template exists before writing config.
 Repeated adds keep one source entry.
@@ -164,6 +278,12 @@ Repeated adds keep one source entry.
 `agentsmd remove` removes a configured template source and fails if the source
 is not present.
 
+`init-template agentsmd` creates a starter template under
+`$CODEXMGR_HOME/agentsmd` and refuses to overwrite an existing template.
+
+`skill list` prints available `$CODEX_HOME/skills/*/SKILL.md` entries and marks
+configured skills as enabled, disabled, or missing.
+
 `skill enable` and `skill disable` keep enabled and disabled lists mutually
 exclusive. Repeated commands keep one entry.
 
@@ -193,8 +313,8 @@ uv build
 ```
 
 The package is typed (`py.typed`) and the test suite covers CLI behavior,
-template rendering, TOML writing, skill resolution, Codex command generation,
-home-directory resolution, and package metadata.
+template rendering, TOML writing, skill resolution, generated-file sync checks,
+Codex command generation, home-directory resolution, and package metadata.
 
 ## Release Notes
 

{codexmgr-0.1.1 → codexmgr-0.1.2}/pyproject.toml

@@ -1,10 +1,12 @@
 [project]
 name = "codexmgr"
-version = "0.1.1"
+version = "0.1.2"
 description = "Manage project-local Codex configuration from reusable templates"
 readme = "README.md"
 requires-python = ">=3.11"
-dependencies = []
+dependencies = [
+    "tomlkit>=0.15.0",
+]
 keywords = ["codex", "cli", "configuration", "agents", "skills"]
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -24,6 +26,7 @@ codexmgr = "codexmgr.cli:entrypoint"
 [project.optional-dependencies]
 dev = [
     "pytest>=9.0.3",
+    "pyyaml>=6.0.3",
 ]
 
 [build-system]

{codexmgr-0.1.1 → codexmgr-0.1.2}/src/codexmgr/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.1.1"
+__version__ = "0.1.2"

{codexmgr-0.1.1 → codexmgr-0.1.2}/src/codexmgr/agents_file.py

@@ -19,10 +19,24 @@ def write_managed_agents_md(path: Path, generated_markdown: str) -> None:
         None. The file is written with UTF-8 encoding.
     """
     current = path.read_text(encoding="utf-8") if path.exists() else ""
-    updated = _replace_block(current, generated_markdown)
+    updated = render_managed_agents_md(current, generated_markdown)
     path.write_text(updated, encoding="utf-8")
 
 
+def render_managed_agents_md(current: str, generated_markdown: str) -> str:
+    """Render AGENTS.md content with an updated managed block.
+
+    Args:
+        current: Existing AGENTS.md content, or an empty string for a new file.
+        generated_markdown: Markdown content for the managed block.
+
+    Returns:
+        Full AGENTS.md content with the codexmgr managed block replaced or
+        appended.
+    """
+    return _replace_block(current, generated_markdown)
+
+
 def _replace_block(current: str, generated_markdown: str) -> str:
     """Replace or append the generated block in AGENTS.md content.
 

codexmgr-0.1.2/src/codexmgr/agentsmd.py

@@ -0,0 +1,210 @@
+"""Manage configured AGENTS.md template sources and rendered output."""
+
+from pathlib import Path
+from typing import Any
+
+from .agents_file import write_managed_agents_md
+from .errors import CommandError
+from .options import list_toml_options
+from .paths import agents_md_path, config_path, resolve_template
+from .project_config import (
+    agents_md_sources,
+    load_required_project_config,
+    require_codex_dir,
+    set_agents_md_sources,
+)
+from .renderer import render_agents_markdown
+from .toml_io import load_optional_toml_file, load_toml_file, write_toml_file
+
+
+def add_agentsmd(reference: str, cwd: Path, codexmgr_home: Path) -> str:
+    """Add an AGENTS.md template reference to project configuration.
+
+    Args:
+        reference: Named template or TOML path to add.
+        cwd: Project directory whose codexmgr.toml should be updated.
+        codexmgr_home: codexmgr home used to validate named template references.
+
+    Returns:
+        The reference that was added or already present.
+    """
+    require_codex_dir(cwd)
+    resolve_template(reference, cwd, codexmgr_home)
+
+    config = load_optional_toml_file(config_path(cwd))
+    sources = agents_md_sources(config)
+    if reference not in sources:
+        sources.append(reference)
+    set_agents_md_sources(config, sources)
+    write_toml_file(config_path(cwd), config)
+    return reference
+
+
+def remove_agentsmd(source_id: str, cwd: Path) -> str:
+    """Remove an AGENTS.md template reference from project configuration.
+
+    Args:
+        source_id: Source identifier or reference to remove.
+        cwd: Project directory whose codexmgr.toml should be updated.
+
+    Returns:
+        The removed source identifier.
+    """
+    config = load_required_project_config(cwd)
+    sources = agents_md_sources(config)
+    if source_id not in sources:
+        raise CommandError(f"Source not found in codexmgr.toml: {source_id}")
+
+    set_agents_md_sources(config, [source for source in sources if source != source_id])
+    write_toml_file(config_path(cwd), config)
+    return source_id
+
+
+def list_agentsmd_options(codexmgr_home: Path) -> list[str]:
+    """List named AGENTS.md template options available to add.
+
+    Args:
+        codexmgr_home: codexmgr home directory containing the ``agentsmd``
+            template store.
+
+    Returns:
+        Sorted template names that can be passed to ``codexmgr agentsmd add``.
+    """
+    return list_toml_options(codexmgr_home / "agentsmd")
+
+
+def show_agentsmd(reference: str, cwd: Path, codexmgr_home: Path) -> str:
+    """Render one AGENTS.md template reference as markdown.
+
+    Args:
+        reference: Named template or TOML path to render.
+        cwd: Project directory used to resolve path references.
+        codexmgr_home: codexmgr home used to resolve named references.
+
+    Returns:
+        Rendered markdown for the template.
+    """
+    source_id, template_data = _load_template(reference, cwd, codexmgr_home)
+    return render_agents_markdown({source_id: template_data})
+
+
+def validate_agentsmd(reference: str, cwd: Path, codexmgr_home: Path) -> str:
+    """Validate that one AGENTS.md template can be loaded and rendered.
+
+    Args:
+        reference: Named template or TOML path to validate.
+        cwd: Project directory used to resolve path references.
+        codexmgr_home: codexmgr home used to resolve named references.
+
+    Returns:
+        Source identifier for the valid template.
+    """
+    source_id, template_data = _load_template(reference, cwd, codexmgr_home)
+    render_agents_markdown({source_id: template_data})
+    return source_id
+
+
+def init_agentsmd_template(name: str, codexmgr_home: Path) -> Path:
+    """Create a starter named AGENTS.md template.
+
+    Args:
+        name: Bare template name to create.
+        codexmgr_home: codexmgr home where the template should be created.
+
+    Returns:
+        Path to the created template file.
+    """
+    _validate_template_name(name)
+    template_dir = codexmgr_home / "agentsmd"
+    template_dir.mkdir(parents=True, exist_ok=True)
+    path = template_dir / f"{name}.toml"
+    if path.exists():
+        raise CommandError(f"Template already exists: {path}")
+    path.write_text(_starter_template(), encoding="utf-8")
+    return path
+
+
+def resolve_locked_agents_md(
+    config: dict[str, Any],
+    cwd: Path,
+    codexmgr_home: Path,
+) -> dict[str, Any]:
+    """Resolve configured AGENTS.md sources into lock data.
+
+    Args:
+        config: Parsed .codex/codexmgr.toml content.
+        cwd: Project directory used to resolve path sources.
+        codexmgr_home: codexmgr home used to resolve named sources.
+
+    Returns:
+        Resolved source data keyed by source identifier.
+    """
+    locked_sources: dict[str, Any] = {}
+    for reference in agents_md_sources(config):
+        source_id, template_path = resolve_template(reference, cwd, codexmgr_home)
+        if source_id in locked_sources:
+            raise CommandError(f"Duplicate AGENTS.md source identifier: {source_id}")
+        template_data = load_toml_file(template_path)
+        if not template_data:
+            raise CommandError(f"Template is empty: {template_path}")
+        locked_sources[source_id] = template_data
+    return locked_sources
+
+
+def write_agents_md(cwd: Path, locked_sources: dict[str, Any]) -> None:
+    """Write resolved AGENTS.md lock data to the managed block.
+
+    Args:
+        cwd: Project directory whose root AGENTS.md should be updated.
+        locked_sources: Resolved source data keyed by source identifier.
+    """
+    write_managed_agents_md(agents_md_path(cwd), render_agents_markdown(locked_sources))
+
+
+def _load_template(
+    reference: str,
+    cwd: Path,
+    codexmgr_home: Path,
+) -> tuple[str, dict[str, Any]]:
+    """Load a named or path-backed AGENTS.md template.
+
+    Args:
+        reference: Named template or TOML path to load.
+        cwd: Project directory used to resolve path references.
+        codexmgr_home: codexmgr home used to resolve named references.
+
+    Returns:
+        Source identifier and parsed TOML data.
+    """
+    source_id, template_path = resolve_template(reference, cwd, codexmgr_home)
+    template_data = load_toml_file(template_path)
+    if not template_data:
+        raise CommandError(f"Template is empty: {template_path}")
+    return source_id, template_data
+
+
+def _validate_template_name(name: str) -> None:
+    """Validate a starter template name.
+
+    Args:
+        name: Candidate bare template name.
+
+    Returns:
+        None. ``CommandError`` is raised for invalid names.
+    """
+    if not name or "/" in name or "\\" in name or name.endswith(".toml"):
+        raise CommandError(f"Template name must be a bare name: {name}")
+
+
+def _starter_template() -> str:
+    """Return starter TOML content for a new AGENTS.md template.
+
+    Returns:
+        A minimal renderable template document.
+    """
+    return (
+        "[instructions]\n"
+        'text = """\n'
+        "- Replace this with reusable project guidance.\n"
+        '"""\n'
+    )