codexmgr 0.2.1__tar.gz → 0.4.0__tar.gz

{codexmgr-0.2.1 → codexmgr-0.4.0}/PKG-INFO

@@ -1,7 +1,8 @@
 Metadata-Version: 2.4
 Name: codexmgr
-Version: 0.2.1
+Version: 0.4.0
 Summary: Manage project-local Codex configuration from reusable templates
+Project-URL: Repository, https://github.com/JulianKimmig/codexmgr/
 Keywords: agents,cli,codex,configuration,skills
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
@@ -24,9 +25,9 @@ Description-Content-Type: text/markdown
 # codexmgr
 
 `codexmgr` manages reusable Codex project setup. Keep shared `AGENTS.md`
-snippets, skills, hooks, custom agents, rule files, packages, and safe MCP
-overrides in one manager home, then sync the selected pieces into each project
-from `.codex/codexmgr.toml`.
+snippets, skills, hooks, custom agents, rule files, packages, and reusable MCP
+source files in one manager home, then sync the selected pieces into each
+project from `.codex/codexmgr.toml`.
 
 The tool is for people who use Codex in several repositories and do not want to
 copy the same agent instructions by hand. When a shared rule changes, update it
@@ -37,9 +38,9 @@ Use `codexmgr` when a project should:
 - build `AGENTS.md` from reusable instruction snippets
 - share skills, hooks, custom agents, and rule files across repositories
 - enable packaged Codex setups made from those reusable pieces
-- keep project MCP overrides out of the user-level Codex config
+- keep reusable MCP server definitions out of the user-level Codex config
 - check whether generated Codex files match the project config
-- run `codex` with project `.codex/config.toml` values passed as `-c` overrides
+- run `codex` with the project `.codex` directory as its local Codex home
 
 The basic model has three parts:
 
@@ -91,7 +92,8 @@ codexmgr setup
 ```
 
 `setup` creates `.codex/`, creates `.codex/codexmgr.toml` if it is missing, and
-runs `apply`. Existing project config is preserved.
+runs `apply`. Existing project config is preserved. Apply also creates or
+refreshes codexmgr's managed block in `.codex/.gitignore`.
 
 Create a reusable `AGENTS.md` snippet in the manager home. This command creates
 `$CODEXMGR_HOME/agentsmd/coding.toml` and refuses to overwrite an existing file:
@@ -145,10 +147,13 @@ file for you, and you can also edit it by hand when that is clearer.
 
 `apply` resolves the source config and may write or update these managed files:
 
+- `.codex/.gitignore`: preserves manual rules outside its managed block,
+  ignores every unknown `.codex` entry by default, and explicitly exposes the
+  codexmgr-owned files and directories listed below
 - `.codex/codexmgr.lock`: resolved AGENTS.md, agent, skill, hook, rule, and MCP
   state
 - `.codex/config.toml`: project-local Codex config, including generated
-  `[[skills.config]]` entries and `[mcp_servers.<id>]` overrides
+  `[[skills.config]]` entries and `[mcp_servers.<id>]` server definitions
 - `.codex/hooks.json`: generated hook config for enabled reusable hook bundles
 - `.codex/hooks/<name>`: copied support files for enabled hook bundles
 - `.codex/agents/<name>.toml`: copied custom-agent definitions
@@ -170,7 +175,7 @@ Manual content outside this block is preserved. If the block is missing,
 
 `.codex/codexmgr.toml` can opt into each resource type independently. A minimal
 file may only contain `[agents_md]`; larger projects can add skills, custom
-agents, hooks, reusable rules, and MCP overrides as needed. Package commands
+agents, hooks, reusable rules, and MCP sources or overlays as needed. Package commands
 write those same tables rather than a separate package table.
 
 ```toml
@@ -188,6 +193,8 @@ disabled = ["experimental-hook"]
 [rules]
 enabled = ["react/", "python/testing.md"]
 disabled = ["react/materials/"]
+[mcp]
+enabled = ["browsermcp"]
 [mcp.servers.browsermcp]
 enabled = true
 bearer_token_env_var = "BROWSERMCP_TOKEN"
@@ -232,6 +239,9 @@ Rule refs resolve under `$CODEXMGR_HOME/rules/` and use POSIX-style relative
 paths. Folder refs have a trailing slash and copy regular files recursively into
 `.rules/` while preserving relative paths.
 
+Rule listings are grouped by folder. `codexmgr rules list` prints an indented
+tree, while the TUI Rules screen shows the same refs in a collapsible tree.
+
 File rule refs copy one file. Extensionless refs prefer an existing `<ref>.md`.
 Enabled refs expand first, then disabled file or folder refs remove entries from
 that candidate set.
@@ -292,7 +302,8 @@ These commands run `apply` automatically unless `--no-sync` is passed.
 
 `codexmgr tui` opens a Textual-based terminal UI for project-local
 configuration. It shows `AGENTS.md` snippets, skills, hooks, custom agents,
-rules, packages, and MCP server enable overrides in selectable lists.
+packages, and reusable MCP sources in selectable lists. Rules are shown
+in a collapsible folder tree.
 
 Changes are staged in memory while you navigate. Press `s` to save; the save
 writes `.codex/codexmgr.toml` once and runs `apply` once unless `--no-sync` was
@@ -300,7 +311,9 @@ used.
 
 For resources with explicit enable and disable lists, `space` cycles the
 highlighted row through available, enabled, and disabled states. Package
-profiles appear as separate selectable rows under their package.
+profiles appear as separate selectable rows under their package. In the Rules
+tree, cycling a file or folder node updates the full canonical rule ref behind
+that basename label.
 
 ```bash
 codexmgr tui
@@ -312,9 +325,10 @@ The dashboard shows generated-file sync state. By default it lists stale
 generated paths; with `--show-diff`, it shows unified diffs for the staged
 configuration.
 
-MCP editing in the TUI is intentionally limited to the project-local `enabled`
-override. Advanced MCP fields remain available through the `codexmgr mcp ...`
-commands.
+MCP editing in the TUI is intentionally limited to loading and unloading
+reusable `$CODEXMGR_HOME/mcp/*.toml` sources. Advanced per-server overlay fields
+remain available through the `codexmgr mcp ...` commands or direct
+`.codex/codexmgr.toml` edits.
 
 ## Template Format
 
@@ -358,6 +372,12 @@ managed project files, and refreshes generated state.
 writing them. `apply --diff` also avoids writing and prints unified diffs for
 the expected generated-file changes.
 
+The `.codex/.gitignore` managed block uses a default-ignore rule rather than a
+list of known runtime filenames. New caches, databases, sessions, and other
+state created by future Codex versions therefore remain outside Git without a
+codexmgr update. Project configuration, custom agents, and hook support files
+remain visible to Git.
+
 `doctor` checks project setup, home environment variables, project TOML syntax,
 referenced snippets, enabled skills, enabled custom agents, enabled hook
 bundles, enabled rules, and stale generated files.
@@ -421,8 +441,9 @@ codexmgr rules enable [--no-sync] <rule-ref> [...]
 codexmgr rules disable [--no-sync] <rule-ref> [...]
 ```
 
-`skill list`, `agents list`, `hooks list`, and `rules list` print available
-resources and mark configured entries as enabled, disabled, or missing.
+`skill list`, `agents list`, and `hooks list` print available resources and
+mark configured entries as enabled, disabled, or missing. `rules list` prints
+the same state in an indented folder hierarchy.
 
 Enable commands validate manager-home sources when the source type must already
 exist. Enable and disable lists stay mutually exclusive, and repeated commands
@@ -449,14 +470,23 @@ Codex wrapper command:
 
 ```bash
 codexmgr codex <args...>
+codexmgr codex --simple <args...>
 ```
 
-`codexmgr codex` applies the current project config, flattens
-`.codex/config.toml` into `-c key=value` overrides, and forwards the remaining
-arguments to the real `codex` command.
+By default, `codexmgr codex` applies the current project config, launches the
+real `codex` command with `CODEX_HOME` set to `<project>/.codex`, and forwards
+Codex arguments unchanged. Codex reads `.codex/config.toml` directly, so
+user-provided `-c` and `--config` arguments retain their normal Codex behavior.
+
+The wrapper links the global authentication file into `.codex/auth.json`. It
+uses `CODEX_GLOBAL_AUTH` when that variable is non-empty and otherwise uses
+`$HOME/.codex/auth.json`. A missing auth source produces a warning but does not
+stop Codex, which can then authenticate normally.
 
-User-provided `-c` or `--config` overrides are merged after project config.
-Scalar values replace earlier values, while list values append.
+Use `--simple` immediately after `codex` to run the basic command without
+applying project state, changing the child `CODEX_HOME`, or managing an auth
+link. This launch wrapper is intentionally CLI-only because the TUI does not
+embed or proxy external terminal sessions.
 
 The wrapper can run with a just-in-time package/profile overlay without changing
 `.codex/codexmgr.toml`. Put Codex arguments after `--` when using this syntax:
@@ -465,40 +495,62 @@ The wrapper can run with a just-in-time package/profile overlay without changing
 codexmgr codex --package repo-rules --profile strict python -- exec "review this"
 ```
 
-## Project MCP Overrides
+## Project MCP Sources
 
-`codexmgr mcp ...` edits only project-local configuration:
+`codexmgr mcp ...` loads reusable MCP definitions from `$CODEXMGR_HOME/mcp`
+into project-local configuration:
 
-- source state is stored in `.codex/codexmgr.toml` under
-  `[mcp.servers.<id>]`
-- `apply` writes generated overrides into `.codex/config.toml` under
+- reusable source state is stored in `.codex/codexmgr.toml` under `[mcp]`
+- per-project server overlays are stored under `[mcp.servers.<id>]`
+- `apply` writes generated server definitions 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.
+automatically unless `--no-sync` is passed.
 
-List MCP servers available from Codex and show any project override state:
+Create reusable source files in the same `mcp_servers` shape Codex reads from
+`config.toml`:
+
+```toml
+# ~/.codexmgr/mcp/browsermcp.toml
+[mcp_servers.browsermcp]
+command = "browsermcp"
+args = ["--port", "3000"]
+env_vars = ["BROWSERMCP_TOKEN"]
+```
+
+List reusable sources and show project state:
 
 ```bash
 codexmgr mcp list
-codexmgr mcp show context7
+codexmgr mcp show browsermcp
 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:
+Enable or disable reusable sources for the current project:
 
 ```bash
-codexmgr mcp disable context7
-codexmgr mcp enable context7
+codexmgr mcp enable browsermcp context7
+codexmgr mcp disable browsermcp
+```
+
+`disable` unloads the source from `[mcp].enabled`. It does not keep a generated
+server definition with `enabled = false`.
+
+Use `[mcp.servers.<id>]` for project-local overlays. Overlays merge after source
+files, so they can override or add fields:
+
+```toml
+[mcp]
+enabled = ["browsermcp"]
+
+[mcp.servers.browsermcp]
+enabled = false
+bearer_token_env_var = "BROWSERMCP_TOKEN"
 ```
 
-Update token and environment references without storing literal token values:
+Update common token and environment references from the CLI:
 
 ```bash
 codexmgr mcp set-token-env figma FIGMA_TOKEN
@@ -508,7 +560,7 @@ 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:
+Set a small allowlist of overlay fields from TOML literals:
 
 ```bash
 codexmgr mcp set-field context7 required true
@@ -518,12 +570,11 @@ 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.
+`default_tools_approval_mode`.
 
-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`.
+Source files and hand-written overlays can use the full Codex `mcp_servers`
+shape. Prefer environment variable references such as `bearer_token_env_var`,
+`env_vars`, and `env_http_headers` for secrets.
 
 ## Development
 

{codexmgr-0.2.1 → codexmgr-0.4.0}/README.md

@@ -1,9 +1,9 @@
 # codexmgr
 
 `codexmgr` manages reusable Codex project setup. Keep shared `AGENTS.md`
-snippets, skills, hooks, custom agents, rule files, packages, and safe MCP
-overrides in one manager home, then sync the selected pieces into each project
-from `.codex/codexmgr.toml`.
+snippets, skills, hooks, custom agents, rule files, packages, and reusable MCP
+source files in one manager home, then sync the selected pieces into each
+project from `.codex/codexmgr.toml`.
 
 The tool is for people who use Codex in several repositories and do not want to
 copy the same agent instructions by hand. When a shared rule changes, update it
@@ -14,9 +14,9 @@ Use `codexmgr` when a project should:
 - build `AGENTS.md` from reusable instruction snippets
 - share skills, hooks, custom agents, and rule files across repositories
 - enable packaged Codex setups made from those reusable pieces
-- keep project MCP overrides out of the user-level Codex config
+- keep reusable MCP server definitions out of the user-level Codex config
 - check whether generated Codex files match the project config
-- run `codex` with project `.codex/config.toml` values passed as `-c` overrides
+- run `codex` with the project `.codex` directory as its local Codex home
 
 The basic model has three parts:
 
@@ -68,7 +68,8 @@ codexmgr setup
 ```
 
 `setup` creates `.codex/`, creates `.codex/codexmgr.toml` if it is missing, and
-runs `apply`. Existing project config is preserved.
+runs `apply`. Existing project config is preserved. Apply also creates or
+refreshes codexmgr's managed block in `.codex/.gitignore`.
 
 Create a reusable `AGENTS.md` snippet in the manager home. This command creates
 `$CODEXMGR_HOME/agentsmd/coding.toml` and refuses to overwrite an existing file:
@@ -122,10 +123,13 @@ file for you, and you can also edit it by hand when that is clearer.
 
 `apply` resolves the source config and may write or update these managed files:
 
+- `.codex/.gitignore`: preserves manual rules outside its managed block,
+  ignores every unknown `.codex` entry by default, and explicitly exposes the
+  codexmgr-owned files and directories listed below
 - `.codex/codexmgr.lock`: resolved AGENTS.md, agent, skill, hook, rule, and MCP
   state
 - `.codex/config.toml`: project-local Codex config, including generated
-  `[[skills.config]]` entries and `[mcp_servers.<id>]` overrides
+  `[[skills.config]]` entries and `[mcp_servers.<id>]` server definitions
 - `.codex/hooks.json`: generated hook config for enabled reusable hook bundles
 - `.codex/hooks/<name>`: copied support files for enabled hook bundles
 - `.codex/agents/<name>.toml`: copied custom-agent definitions
@@ -147,7 +151,7 @@ Manual content outside this block is preserved. If the block is missing,
 
 `.codex/codexmgr.toml` can opt into each resource type independently. A minimal
 file may only contain `[agents_md]`; larger projects can add skills, custom
-agents, hooks, reusable rules, and MCP overrides as needed. Package commands
+agents, hooks, reusable rules, and MCP sources or overlays as needed. Package commands
 write those same tables rather than a separate package table.
 
 ```toml
@@ -165,6 +169,8 @@ disabled = ["experimental-hook"]
 [rules]
 enabled = ["react/", "python/testing.md"]
 disabled = ["react/materials/"]
+[mcp]
+enabled = ["browsermcp"]
 [mcp.servers.browsermcp]
 enabled = true
 bearer_token_env_var = "BROWSERMCP_TOKEN"
@@ -209,6 +215,9 @@ Rule refs resolve under `$CODEXMGR_HOME/rules/` and use POSIX-style relative
 paths. Folder refs have a trailing slash and copy regular files recursively into
 `.rules/` while preserving relative paths.
 
+Rule listings are grouped by folder. `codexmgr rules list` prints an indented
+tree, while the TUI Rules screen shows the same refs in a collapsible tree.
+
 File rule refs copy one file. Extensionless refs prefer an existing `<ref>.md`.
 Enabled refs expand first, then disabled file or folder refs remove entries from
 that candidate set.
@@ -269,7 +278,8 @@ These commands run `apply` automatically unless `--no-sync` is passed.
 
 `codexmgr tui` opens a Textual-based terminal UI for project-local
 configuration. It shows `AGENTS.md` snippets, skills, hooks, custom agents,
-rules, packages, and MCP server enable overrides in selectable lists.
+packages, and reusable MCP sources in selectable lists. Rules are shown
+in a collapsible folder tree.
 
 Changes are staged in memory while you navigate. Press `s` to save; the save
 writes `.codex/codexmgr.toml` once and runs `apply` once unless `--no-sync` was
@@ -277,7 +287,9 @@ used.
 
 For resources with explicit enable and disable lists, `space` cycles the
 highlighted row through available, enabled, and disabled states. Package
-profiles appear as separate selectable rows under their package.
+profiles appear as separate selectable rows under their package. In the Rules
+tree, cycling a file or folder node updates the full canonical rule ref behind
+that basename label.
 
 ```bash
 codexmgr tui
@@ -289,9 +301,10 @@ The dashboard shows generated-file sync state. By default it lists stale
 generated paths; with `--show-diff`, it shows unified diffs for the staged
 configuration.
 
-MCP editing in the TUI is intentionally limited to the project-local `enabled`
-override. Advanced MCP fields remain available through the `codexmgr mcp ...`
-commands.
+MCP editing in the TUI is intentionally limited to loading and unloading
+reusable `$CODEXMGR_HOME/mcp/*.toml` sources. Advanced per-server overlay fields
+remain available through the `codexmgr mcp ...` commands or direct
+`.codex/codexmgr.toml` edits.
 
 ## Template Format
 
@@ -335,6 +348,12 @@ managed project files, and refreshes generated state.
 writing them. `apply --diff` also avoids writing and prints unified diffs for
 the expected generated-file changes.
 
+The `.codex/.gitignore` managed block uses a default-ignore rule rather than a
+list of known runtime filenames. New caches, databases, sessions, and other
+state created by future Codex versions therefore remain outside Git without a
+codexmgr update. Project configuration, custom agents, and hook support files
+remain visible to Git.
+
 `doctor` checks project setup, home environment variables, project TOML syntax,
 referenced snippets, enabled skills, enabled custom agents, enabled hook
 bundles, enabled rules, and stale generated files.
@@ -398,8 +417,9 @@ codexmgr rules enable [--no-sync] <rule-ref> [...]
 codexmgr rules disable [--no-sync] <rule-ref> [...]
 ```
 
-`skill list`, `agents list`, `hooks list`, and `rules list` print available
-resources and mark configured entries as enabled, disabled, or missing.
+`skill list`, `agents list`, and `hooks list` print available resources and
+mark configured entries as enabled, disabled, or missing. `rules list` prints
+the same state in an indented folder hierarchy.
 
 Enable commands validate manager-home sources when the source type must already
 exist. Enable and disable lists stay mutually exclusive, and repeated commands
@@ -426,14 +446,23 @@ Codex wrapper command:
 
 ```bash
 codexmgr codex <args...>
+codexmgr codex --simple <args...>
 ```
 
-`codexmgr codex` applies the current project config, flattens
-`.codex/config.toml` into `-c key=value` overrides, and forwards the remaining
-arguments to the real `codex` command.
+By default, `codexmgr codex` applies the current project config, launches the
+real `codex` command with `CODEX_HOME` set to `<project>/.codex`, and forwards
+Codex arguments unchanged. Codex reads `.codex/config.toml` directly, so
+user-provided `-c` and `--config` arguments retain their normal Codex behavior.
+
+The wrapper links the global authentication file into `.codex/auth.json`. It
+uses `CODEX_GLOBAL_AUTH` when that variable is non-empty and otherwise uses
+`$HOME/.codex/auth.json`. A missing auth source produces a warning but does not
+stop Codex, which can then authenticate normally.
 
-User-provided `-c` or `--config` overrides are merged after project config.
-Scalar values replace earlier values, while list values append.
+Use `--simple` immediately after `codex` to run the basic command without
+applying project state, changing the child `CODEX_HOME`, or managing an auth
+link. This launch wrapper is intentionally CLI-only because the TUI does not
+embed or proxy external terminal sessions.
 
 The wrapper can run with a just-in-time package/profile overlay without changing
 `.codex/codexmgr.toml`. Put Codex arguments after `--` when using this syntax:
@@ -442,40 +471,62 @@ The wrapper can run with a just-in-time package/profile overlay without changing
 codexmgr codex --package repo-rules --profile strict python -- exec "review this"
 ```
 
-## Project MCP Overrides
+## Project MCP Sources
 
-`codexmgr mcp ...` edits only project-local configuration:
+`codexmgr mcp ...` loads reusable MCP definitions from `$CODEXMGR_HOME/mcp`
+into project-local configuration:
 
-- source state is stored in `.codex/codexmgr.toml` under
-  `[mcp.servers.<id>]`
-- `apply` writes generated overrides into `.codex/config.toml` under
+- reusable source state is stored in `.codex/codexmgr.toml` under `[mcp]`
+- per-project server overlays are stored under `[mcp.servers.<id>]`
+- `apply` writes generated server definitions 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.
+automatically unless `--no-sync` is passed.
 
-List MCP servers available from Codex and show any project override state:
+Create reusable source files in the same `mcp_servers` shape Codex reads from
+`config.toml`:
+
+```toml
+# ~/.codexmgr/mcp/browsermcp.toml
+[mcp_servers.browsermcp]
+command = "browsermcp"
+args = ["--port", "3000"]
+env_vars = ["BROWSERMCP_TOKEN"]
+```
+
+List reusable sources and show project state:
 
 ```bash
 codexmgr mcp list
-codexmgr mcp show context7
+codexmgr mcp show browsermcp
 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:
+Enable or disable reusable sources for the current project:
 
 ```bash
-codexmgr mcp disable context7
-codexmgr mcp enable context7
+codexmgr mcp enable browsermcp context7
+codexmgr mcp disable browsermcp
+```
+
+`disable` unloads the source from `[mcp].enabled`. It does not keep a generated
+server definition with `enabled = false`.
+
+Use `[mcp.servers.<id>]` for project-local overlays. Overlays merge after source
+files, so they can override or add fields:
+
+```toml
+[mcp]
+enabled = ["browsermcp"]
+
+[mcp.servers.browsermcp]
+enabled = false
+bearer_token_env_var = "BROWSERMCP_TOKEN"
 ```
 
-Update token and environment references without storing literal token values:
+Update common token and environment references from the CLI:
 
 ```bash
 codexmgr mcp set-token-env figma FIGMA_TOKEN
@@ -485,7 +536,7 @@ 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:
+Set a small allowlist of overlay fields from TOML literals:
 
 ```bash
 codexmgr mcp set-field context7 required true
@@ -495,12 +546,11 @@ 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.
+`default_tools_approval_mode`.
 
-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`.
+Source files and hand-written overlays can use the full Codex `mcp_servers`
+shape. Prefer environment variable references such as `bearer_token_env_var`,
+`env_vars`, and `env_http_headers` for secrets.
 
 ## Development
 

{codexmgr-0.2.1 → codexmgr-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codexmgr"
-version = "0.2.1"
+version = "0.4.0"
 description = "Manage project-local Codex configuration from reusable templates"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -21,6 +21,9 @@ classifiers = [
     "Typing :: Typed",
 ]
 
+[project.urls]
+Repository = "https://github.com/JulianKimmig/codexmgr/"
+
 [project.scripts]
 codexmgr = "codexmgr.interface.cli:entrypoint"
 

{codexmgr-0.2.1 → codexmgr-0.4.0}/src/codexmgr/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.1"
+__version__ = "0.4.0"

codexmgr-0.4.0/src/codexmgr/agents/file.py

@@ -0,0 +1,43 @@
+"""Helpers for preserving manual AGENTS.md content around a managed block."""
+
+from pathlib import Path
+
+from ..core.managed_text import render_managed_block
+
+BEGIN_MARKER = "<!-- BEGIN CODEXMGR GENERATED -->"
+END_MARKER = "<!-- END CODEXMGR GENERATED -->"
+
+
+def write_managed_agents_md(path: Path, generated_markdown: str) -> None:
+    """Write generated markdown into the CODEXMGR managed block.
+
+    Args:
+        path: Project AGENTS.md path to create or update.
+        generated_markdown: Markdown content to place inside the managed block.
+
+    Returns:
+        None. The file is written with UTF-8 encoding.
+    """
+    current = path.read_text(encoding="utf-8") if path.exists() else ""
+    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 render_managed_block(
+        current,
+        generated_markdown,
+        begin_marker=BEGIN_MARKER,
+        end_marker=END_MARKER,
+        artifact_name="AGENTS.md",
+    )