codex-core 0.3.0__tar.gz → 0.5.0__tar.gz

{codex_core-0.3.0 → codex_core-0.5.0}/.gitignore

@@ -202,3 +202,6 @@ gen/
 marimo/_static/
 marimo/_lsp/
 __marimo__/
+
+# graphify
+graphify-out/

codex_core-0.5.0/AGENTS.md

@@ -0,0 +1,11 @@
+## graphify
+
+This component is part of a larger project. It uses a global knowledge graph located at the workspace root (`../graphify-out/`).
+
+Rules:
+- Before answering architecture or codebase questions, read the global report at **`../graphify-out/GRAPH_REPORT.md`** for god nodes and community structure.
+- If `../graphify-out/wiki/index.md` exists, navigate it instead of reading raw files.
+- For cross-module questions, prefer `graphify query`, `graphify path`, or `graphify explain` (run from root or via MCP) over grep.
+- After modifying code files in this session, run `graphify update .` from the **workspace root** to keep the global graph current.
+
+For changes to this package, its consumer skill, installer, or release notes, read [codex-core maintenance](docs/agent-skills/codex-core-maintenance/SKILL.md).

{codex_core-0.3.0 → codex_core-0.5.0}/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.5.0] - 2026-10-09
+
+### Added
+
+- Packaged an optional `codex-core` agent usage skill with focused references and an offline install/update/delete/status tool.
+- Added source-repository maintenance guidance for the package and skill delivery.
+
+### Fixed
+
+- Refresh locked runtime, development, and documentation dependencies to patched releases identified by the release audit.
+- Use `None` as the default logging context value to satisfy the B039 lint rule.
+- Type the healthcheck filter with Loguru's record contract while keeping Loguru optional at runtime.
+- Restrict source distributions to project sources and documentation, excluding local environments and build caches.
+
+## [0.4.0] - 2026-05-20
+
+### Added
+
+- Added async-local logging context helpers and context injection for Loguru records.
+- Added production JSON stdout logging and healthcheck filtering to `setup_logging`.
+
 ## [0.3.0] - 2026-04-04
 
 ### Added

{codex_core-0.3.0 → codex_core-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: codex-core
-Version: 0.3.0
+Version: 0.5.0
 Summary: Core utilities, schemas and settings for Codex WaaS toolkit
 Project-URL: Homepage, https://github.com/codexdlc/codex-core
 Project-URL: Documentation, https://codexdlc.github.io/codex-core/
@@ -17,7 +17,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Requires-Python: >=3.12
-Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic-settings>=2.14.2
 Requires-Dist: pydantic<3.0,>=2.0
 Provides-Extra: dev
 Requires-Dist: bandit>=1.7; extra == 'dev'
@@ -27,12 +27,12 @@ Requires-Dist: pip-audit>=2.7; extra == 'dev'
 Requires-Dist: pre-commit>=3.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
-Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mike>=2.0; extra == 'docs'
 Requires-Dist: mkdocs-include-markdown-plugin; extra == 'docs'
-Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.7.7; extra == 'docs'
 Requires-Dist: mkdocs>=1.5; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
 Provides-Extra: loguru
@@ -64,6 +64,18 @@ pip install "codex-core[loguru]"
 
 Requires Python 3.12 or newer.
 
+## Optional agent skill
+
+Starting with version 0.5.0, the package includes an offline `codex-core` usage skill for coding agents. From the consumer project root, use the same Python environment that has the package installed:
+
+```bash
+python -m pip install "codex-core>=0.5.0"
+python -m codex_core.agent_skills install --project .
+python -m codex_core.agent_skills status --project .
+```
+
+`install` creates a managed copy under `.agents/skills/codex-core/` and a marked instruction in `AGENTS.md`. After upgrading the Python package, run `python -m codex_core.agent_skills update --project .` to refresh the skill. The installer refuses to discard local edits to managed files and preserves unrelated project content. See the [agent skill guide](docs/en/tasks/agent_skills.md) for the full lifecycle, removal, and recovery steps. The canonical editable source is `src/codex_core/agent_skills/resources/` in this repository.
+
 ## Development
 
 ```bash

{codex_core-0.3.0 → codex_core-0.5.0}/README.md

@@ -23,6 +23,18 @@ pip install "codex-core[loguru]"
 
 Requires Python 3.12 or newer.
 
+## Optional agent skill
+
+Starting with version 0.5.0, the package includes an offline `codex-core` usage skill for coding agents. From the consumer project root, use the same Python environment that has the package installed:
+
+```bash
+python -m pip install "codex-core>=0.5.0"
+python -m codex_core.agent_skills install --project .
+python -m codex_core.agent_skills status --project .
+```
+
+`install` creates a managed copy under `.agents/skills/codex-core/` and a marked instruction in `AGENTS.md`. After upgrading the Python package, run `python -m codex_core.agent_skills update --project .` to refresh the skill. The installer refuses to discard local edits to managed files and preserves unrelated project content. See the [agent skill guide](docs/en/tasks/agent_skills.md) for the full lifecycle, removal, and recovery steps. The canonical editable source is `src/codex_core/agent_skills/resources/` in this repository.
+
 ## Development
 
 ```bash

codex_core-0.5.0/docs/agent-skills/codex-core-maintenance/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: codex-core-maintenance
+description: Use when changing codex-core public modules, packaging, release notes, or its consumer skill and offline installer in this source repository.
+---
+
+# codex-core maintenance
+
+This repository is the canonical source of the `codex-core` Python package. Package metadata and build rules are in `pyproject.toml`; public code is under `src/codex_core`. The packaged consumer skill source is `src/codex_core/agent_skills/resources/`. Consumer installations under `.agents/skills/codex-core/` are generated, manifest-owned copies. Edit source here, not a consumer copy or its `.manifest.json`.
+
+For API changes, keep the skill references aligned with shipped public imports and behavior. `BaseDTO` freezes Pydantic fields and masks its string representation; it does not sanitize `model_dump()`. A `PIIRegistry` subclass globally replaces heuristic matching with exact names, so partial declarations affect all DTOs in the process. `BaseCommonSettings` intentionally omits an env-file path and defaults to `debug=True`. `codex_core.common` exposes normalization and logging helpers; Loguru configuration requires the optional extra and is application-owned.
+
+The offline installer entrypoint is `python -m codex_core.agent_skills {install,update,delete,status} --project PATH`. It writes only its manifest-owned skill files and marked `AGENTS.md` block. Preserve unrelated project text and files byte-for-byte. Refuse malformed manifests, symlinks/reparse points, collisions, and changed managed files before mutations; retain rollback protection for ordinary I/O errors. Changes to installer behavior need lifecycle tests and an isolated install from a built artifact.
+
+Before implementation, read the repository `AGENTS.md` and graph report/index as instructed there. From the repository root, relevant checks are `python -m pytest -q`, `python -m ruff check src tests`, `python -m mypy src/codex_core`, and `uv build --no-sources`; use the project's environment where those commands are installed. For package changes, inspect wheel contents and perform an isolated consumer install/update/status/delete from the built wheel. After code changes, run `graphify update .` from the workspace root as `AGENTS.md` directs. Update `CHANGELOG.md` without inventing a release date. Do not commit, tag, or publish as part of ordinary maintenance; those actions belong to the release workflow.

codex_core-0.5.0/docs/en/tasks/agent_skills.md

@@ -0,0 +1,26 @@
+<!-- Type: GUIDE -->
+[🏠 Home](../../index.md) | [🧭 Guide (EN)](../README.md) | [🚀 Getting Started](getting_started.md)
+
+# Optional agent skill
+
+Starting with `codex-core` 0.5.0, the Python package includes an offline usage skill for coding agents. Install the package in the Python environment you will use for the commands below, then run these commands from your consumer project root:
+
+```bash
+python -m pip install "codex-core>=0.5.0"
+python -m codex_core.agent_skills install --project .
+python -m codex_core.agent_skills status --project .
+```
+
+The installer creates `.agents/skills/codex-core/` with a version/hash manifest and adds a marked instruction to `AGENTS.md`. The copy and manifest are managed by the package. Keep application-specific rules in your own project skill or outside the marked block.
+
+Updating the Python package and refreshing the installed skill are separate steps:
+
+```bash
+python -m pip install --upgrade codex-core
+python -m codex_core.agent_skills update --project .
+python -m codex_core.agent_skills status --project .
+```
+
+To remove only installer-owned content, run `python -m codex_core.agent_skills delete --project .`. `install` is safe to repeat when current, and `delete` succeeds when the skill is already absent. `status` exits with code 0 only when the skill is installed and current; it exits with code 1 when absent, outdated, or damaged. The other commands exit with code 1 on an error.
+
+Update and delete refuse to discard changed managed files. Installation also refuses to take over an existing unowned destination or overwrite a colliding file. If a command reports local changes, save them in a project-owned skill, restore the managed files or marked block from a trusted backup of the installed version, and retry. Do not edit the manifest to make changes appear managed, or manually remove the destination to force an update. Unrelated `AGENTS.md` text and unowned files are preserved.

{codex_core-0.3.0 → codex_core-0.5.0}/docs/en/tasks/getting_started.md

@@ -27,6 +27,10 @@ If you want to use the pre-configured Loguru setup, install the optional extra:
 pip install "codex-core[loguru]"
 ```
 
+### Optional agent skill
+
+From version 0.5.0, install the offline coding-agent skill separately after installing the Python package. See [the agent skill guide](agent_skills.md) for installation, updates, removal, and recovery from local edits.
+
 ## First Steps
 
 ### 1. Create a BaseDTO

codex_core-0.5.0/docs/ru/tasks/agent_skills.md

@@ -0,0 +1,26 @@
+<!-- Type: GUIDE -->
+[🏠 На главную](../../index.md) | [🧭 Руководство (RU)](../README.md) | [🚀 Начало работы](getting_started.md)
+
+# Необязательный навык для агентов
+
+Начиная с версии `codex-core` 0.5.0 пакет Python содержит автономный навык использования библиотеки для кодовых агентов. Установите пакет в среду Python, из которой будете запускать команды, затем выполните их из корня проекта-потребителя:
+
+```bash
+python -m pip install "codex-core>=0.5.0"
+python -m codex_core.agent_skills install --project .
+python -m codex_core.agent_skills status --project .
+```
+
+Установщик создаёт `.agents/skills/codex-core/` с манифестом версии и хешей и добавляет помеченную инструкцию в `AGENTS.md`. Копией навыка и манифестом управляет пакет. Правила вашего приложения храните в собственном навыке проекта или вне помеченного блока.
+
+Обновление пакета Python и обновление установленного навыка — отдельные действия:
+
+```bash
+python -m pip install --upgrade codex-core
+python -m codex_core.agent_skills update --project .
+python -m codex_core.agent_skills status --project .
+```
+
+Чтобы удалить только файлы установщика, выполните `python -m codex_core.agent_skills delete --project .`. Повторный `install` допустим, если навык актуален; `delete` также успешно завершается, если навык уже отсутствует. `status` возвращает код 0 только для установленного и актуального навыка; если навык отсутствует, устарел или повреждён, возвращается код 1. Остальные команды возвращают код 1 при ошибке.
+
+Команды `update` и `delete` откажутся удалять изменённые управляемые файлы. Установка также откажется занимать существующий неуправляемый каталог или перезаписывать конфликтующий файл. Если команда обнаружила локальные изменения, сохраните их в собственном навыке проекта, восстановите управляемые файлы или помеченный блок из надёжной резервной копии установленной версии и повторите команду. Не меняйте манифест ради принятия изменений и не удаляйте каталог вручную для принудительного обновления. Остальной текст `AGENTS.md` и неуправляемые файлы сохраняются.

{codex_core-0.3.0 → codex_core-0.5.0}/docs/ru/tasks/getting_started.md

@@ -27,6 +27,10 @@ pip install git+https://github.com/codexdlc/codex-core.git
 pip install "codex-core[loguru]"
 ```
 
+### Необязательный навык для агентов
+
+Начиная с версии 0.5.0 после установки пакета Python можно отдельно установить автономный навык для кодовых агентов. Команды установки, обновления, удаления и восстановления после локальных изменений приведены в [руководстве по навыку](agent_skills.md).
+
 ## Первые шаги
 
 ### 1. Создание BaseDTO

{codex_core-0.3.0 → codex_core-0.5.0}/mkdocs.yml

@@ -62,6 +62,7 @@ nav:
       - Overview: en/README.md
       - Tasks:
           - Getting Started: en/tasks/getting_started.md
+          - Agent Skill: en/tasks/agent_skills.md
       - Architecture:
           - Overview: en/architecture/README.md
           - Core (PII & DTO): en/architecture/platform/core.md
@@ -72,6 +73,7 @@ nav:
       - Обзор: ru/README.md
       - Задачи (Tasks):
           - Начало работы: ru/tasks/getting_started.md
+          - Навык для агентов: ru/tasks/agent_skills.md
       - Архитектура:
           - Обзор: ru/architecture/README.md
           - Core (PII и DTO): ru/architecture/platform/core.md

{codex_core-0.3.0 → codex_core-0.5.0}/pyproject.toml

@@ -21,7 +21,7 @@ classifiers = [
 ]
 dependencies = [
     "pydantic>=2.0,<3.0",
-    "pydantic-settings>=2.0",
+    "pydantic-settings>=2.14.2",
 ]
 
 [project.urls]
@@ -34,7 +34,7 @@ Issues = "https://github.com/codexdlc/codex-core/issues"
 [project.optional-dependencies]
 loguru = ["loguru>=0.7.0"]
 dev = [
-    "pytest>=8.0",
+    "pytest>=9.0.3",
     "pytest-asyncio>=0.23",
     "pytest-cov",
     "ruff>=0.4",
@@ -46,7 +46,7 @@ dev = [
 ]
 docs = [
     "mkdocs>=1.5",
-    "mkdocs-material>=9.0",
+    "mkdocs-material>=9.7.7",
     "mkdocstrings[python]>=0.24",
     "mkdocs-include-markdown-plugin",
     "mike>=2.0",
@@ -58,6 +58,23 @@ source = "vcs"
 [tool.hatch.build.targets.wheel]
 packages = ["src/codex_core"]
 
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+    "/docs",
+    "/tools",
+    "/README.md",
+    "/CHANGELOG.md",
+    "/pyproject.toml",
+    "/uv.lock",
+    "/mkdocs.yml",
+    "/AGENTS.md",
+    "/.python-version",
+    "/.pre-commit-config.yaml",
+    "/.github",
+]
+
 [tool.ruff]
 target-version = "py312"
 line-length = 120

codex_core-0.5.0/src/codex_core/agent_skills/__init__.py

@@ -0,0 +1 @@
+# empty module

codex_core-0.5.0/src/codex_core/agent_skills/__main__.py

@@ -0,0 +1,4 @@
+from codex_core.agent_skills.cli import main
+
+if __name__ == "__main__":
+    main()

codex_core-0.5.0/src/codex_core/agent_skills/cli.py

@@ -0,0 +1,39 @@
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from codex_core.agent_skills.fs_transaction import FSError
+from codex_core.agent_skills.orchestrator import OrchestratorError, check_status, perform_delete, perform_install
+
+
+def main(args: Sequence[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(prog="python -m codex_core.agent_skills")
+    parser.add_argument("action", choices=["install", "update", "delete", "status"])
+    parser.add_argument("--project", required=True, help="Path to project root")
+
+    parsed = parser.parse_args(args)
+
+    project_dir = Path(parsed.project).absolute()
+    if not project_dir.is_dir():
+        print(f"Error: Project directory does not exist or is not a directory: {project_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        if parsed.action == "install":
+            perform_install(project_dir, update=False)
+            print("Installed successfully.")
+        elif parsed.action == "update":
+            perform_install(project_dir, update=True)
+            print("Updated successfully.")
+        elif parsed.action == "delete":
+            perform_delete(project_dir)
+            print("Deleted successfully.")
+        elif parsed.action == "status":
+            is_valid, msg = check_status(project_dir)
+            print(msg)
+            if not is_valid:
+                sys.exit(1)
+    except (OrchestratorError, FSError) as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)

codex_core-0.5.0/src/codex_core/agent_skills/fs_transaction.py

@@ -0,0 +1,174 @@
+"""Same-volume staged writes with best-effort rollback after ordinary I/O errors."""
+
+import errno
+import os
+import shutil
+import stat
+import tempfile
+from contextlib import suppress
+from pathlib import Path
+
+
+class FSError(Exception):
+    pass
+
+
+def validate_no_symlinks(path: Path) -> Path:
+    """Inspect every existing component with lstat, including dangling links."""
+    path = path.absolute()
+    parts = list(reversed((path, *path.parents)))
+    for index, part in enumerate(parts):
+        try:
+            info = part.lstat()
+        except FileNotFoundError:
+            continue
+        except OSError as exc:
+            raise FSError(f"Cannot inspect {part}: {exc}") from exc
+        if stat.S_ISLNK(info.st_mode) or getattr(info, "st_file_attributes", 0) & getattr(
+            stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0
+        ):
+            raise FSError(f"Symlink or reparse point detected: {part}")
+        if index < len(parts) - 1 and not stat.S_ISDIR(info.st_mode):
+            raise FSError(f"Non-directory ancestor: {part}")
+    return path
+
+
+def check_regular_file(path: Path) -> None:
+    validate_no_symlinks(path)
+    try:
+        info = path.lstat()
+    except FileNotFoundError:
+        return
+    except OSError as exc:
+        raise FSError(f"Cannot inspect {path}: {exc}") from exc
+    if not stat.S_ISREG(info.st_mode):
+        raise FSError(f"Not a regular file: {path}")
+
+
+class FSTransaction:
+    def __init__(self, project_dir: Path):
+        self.project_dir = validate_no_symlinks(project_dir)
+        if not self.project_dir.is_dir():
+            raise FSError("Project is not a directory")
+        self.temp_dir = Path(tempfile.mkdtemp(prefix=".codex-core-tx-", dir=self.project_dir))
+        self.backup_dir = self.temp_dir / "backup"
+        self.stage_dir = self.temp_dir / "stage"
+        self.backup_dir.mkdir()
+        self.stage_dir.mkdir()
+        self.to_write: list[tuple[Path, bytes]] = []
+        self.to_delete: list[Path] = []
+        self.to_prune: list[Path] = []
+        self._created_dirs: list[Path] = []
+        self._removed_dirs: list[Path] = []
+        self._snapshots: dict[Path, Path | None] = {}
+        self._retain = False
+
+    def _target(self, target: Path) -> Path:
+        target = validate_no_symlinks(target)
+        if not target.is_relative_to(self.project_dir) or target.is_relative_to(self.temp_dir):
+            raise FSError("Target outside project or inside transaction directory")
+        check_regular_file(target)
+        return target
+
+    def stage_write(self, target: Path, content: bytes) -> None:
+        self.to_write.append((self._target(target), content))
+
+    def stage_delete(self, target: Path) -> None:
+        target = self._target(target)
+        if target.exists():
+            self.to_delete.append(target)
+
+    def stage_prune_empty(self, directory: Path) -> None:
+        directory = validate_no_symlinks(directory)
+        if not directory.is_relative_to(self.project_dir) or directory == self.project_dir:
+            raise FSError("Unsafe directory cleanup target")
+        self.to_prune.append(directory)
+
+    def _make_parent(self, parent: Path) -> None:
+        missing: list[Path] = []
+        current = parent
+        while not current.exists():
+            missing.append(current)
+            current = current.parent
+        for directory in reversed(missing):
+            directory.mkdir()
+            self._created_dirs.append(directory)
+
+    def apply(self) -> None:
+        targets = list(dict.fromkeys([*self.to_delete, *(p for p, _ in self.to_write)]))
+        if len(targets) != len(self.to_delete) + len(self.to_write):
+            raise FSError("A target appears in multiple operations")
+        try:
+            # Snapshot every existing destination before the first mutation.
+            for index, target in enumerate(targets):
+                self._target(target)
+                backup = None
+                if target.exists():
+                    backup = self.backup_dir / f"backup_{index}"
+                    shutil.copy2(target, backup)
+                self._snapshots[target] = backup
+            for index, (_, data) in enumerate(self.to_write):
+                (self.stage_dir / f"write_stg_{index}").write_bytes(data)
+            for target in self.to_delete:
+                target.unlink()
+            for index, (target, _) in enumerate(self.to_write):
+                self._make_parent(target.parent)
+                os.replace(self.stage_dir / f"write_stg_{index}", target)
+            for directory in sorted(set(self.to_prune), key=lambda p: len(p.parts), reverse=True):
+                validate_no_symlinks(directory)
+                try:
+                    directory.rmdir()
+                    self._removed_dirs.append(directory)
+                except FileNotFoundError:
+                    pass
+                except OSError as exc:
+                    if exc.errno not in {errno.ENOTEMPTY, errno.EEXIST} and getattr(exc, "winerror", None) != 145:
+                        raise
+        except Exception as exc:
+            try:
+                self.rollback()
+            except FSError as recovery:
+                self._retain = True
+                raise FSError(
+                    f"Transaction failed: {exc}. Recovery failed: {recovery}. Backups retained at {self.temp_dir}"
+                ) from exc
+            raise FSError(f"Transaction failed and was rolled back: {exc}") from exc
+
+    def rollback(self) -> None:
+        errors: list[str] = []
+        for directory in reversed(self._removed_dirs):
+            try:
+                directory.mkdir(exist_ok=True)
+            except Exception as exc:
+                errors.append(f"{directory}: {exc}")
+        for target, backup in reversed(list(self._snapshots.items())):
+            try:
+                if backup is None:
+                    if target.exists():
+                        target.unlink()
+                else:
+                    self._make_parent(target.parent)
+                    # Copy leaves the sole recovery copy intact if restoration fails.
+                    shutil.copy2(backup, target)
+            except Exception as exc:
+                errors.append(f"{target}: {exc}")
+        for directory in reversed(self._created_dirs):
+            with suppress(OSError):
+                directory.rmdir()
+        if errors:
+            raise FSError("; ".join(errors))
+
+    def cleanup(self) -> None:
+        if self._retain:
+            return
+        root = self.temp_dir.absolute()
+        if root.parent != self.project_dir or not root.name.startswith(".codex-core-tx-"):
+            raise FSError("Unsafe transaction cleanup path")
+        validate_no_symlinks(root)
+        shutil.rmtree(root)
+
+    def __enter__(self) -> "FSTransaction":
+        return self
+
+    def __exit__(self, _type: object, _value: object, _traceback: object) -> None:
+        self.cleanup()

codex_core-0.5.0/src/codex_core/agent_skills/manifest_rules.py

@@ -0,0 +1,153 @@
+"""Validation of the installer-owned manifest and AGENTS.md block."""
+
+import hashlib
+import json
+import re
+from typing import Any
+
+MARKER_START = b"<!-- codex-core:skill:start -->"
+MARKER_END = b"<!-- codex-core:skill:end -->"
+MANIFEST_NAME = ".manifest.json"
+SKILL_ID = "codex-core"
+_INSTRUCTION = b"Use [codex-core](.agents/skills/codex-core/SKILL.md) for codex_core work."
+_HASH = re.compile(r"[0-9a-f]{64}\Z")
+_INVALID_WINDOWS = set('<>:"\\|?*')
+
+
+class ManifestError(Exception):
+    pass
+
+
+def hash_content(content: bytes) -> str:
+    return hashlib.sha256(content).hexdigest()
+
+
+def validate_normalized_posix_path(path_str: str) -> None:
+    if not isinstance(path_str, str) or not path_str or path_str.startswith("/"):
+        raise ManifestError(f"Invalid relative path: {path_str!r}")
+    for segment in path_str.split("/"):
+        if (
+            not segment
+            or segment in {".", ".."}
+            or segment[-1] in ". "
+            or any(c in _INVALID_WINDOWS or ord(c) < 32 for c in segment)
+        ):
+            raise ManifestError(f"Invalid path segment: {path_str!r}")
+        device = segment.split(".", 1)[0].upper()
+        if device in {"CON", "PRN", "AUX", "NUL"} or re.fullmatch(r"(?:COM|LPT)[1-9]", device):
+            raise ManifestError(f"Windows device path: {path_str!r}")
+
+
+def _validate_file_names(names: set[str]) -> None:
+    if "SKILL.md" not in names:
+        raise ManifestError("SKILL.md missing")
+    aliases: set[str] = set()
+    for name in names:
+        validate_normalized_posix_path(name)
+        if name.rsplit("/", 1)[-1].casefold() in {MANIFEST_NAME.casefold(), "agents.md"}:
+            raise ManifestError(f"Reserved owned path: {name}")
+        alias = name.casefold()
+        if alias in aliases:
+            raise ManifestError(f"Case alias: {name}")
+        aliases.add(alias)
+    for alias in aliases:
+        parts = alias.split("/")
+        if any("/".join(parts[:i]) in aliases for i in range(1, len(parts))):
+            raise ManifestError(f"File and parent conflict: {alias}")
+
+
+def _unique_pairs(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in result:
+            raise ManifestError(f"Duplicate JSON key: {key}")
+        result[key] = value
+    return result
+
+
+def parse_manifest(content: bytes) -> dict[str, Any]:
+    try:
+        data = json.loads(content.decode("utf-8"), object_pairs_hook=_unique_pairs)
+    except (UnicodeError, ValueError, TypeError) as exc:
+        raise ManifestError("Malformed manifest JSON") from exc
+    if not isinstance(data, dict) or set(data) != {"version", "skill", "package_version", "files", "agents_created"}:
+        raise ManifestError("Invalid manifest schema")
+    if (
+        data["version"] != "1.0"
+        or data["skill"] != SKILL_ID
+        or not isinstance(data["package_version"], str)
+        or not data["package_version"]
+    ):
+        raise ManifestError("Invalid manifest identity")
+    if type(data["agents_created"]) is not bool or not isinstance(data["files"], dict):
+        raise ManifestError("Invalid manifest fields")
+    files = data["files"]
+    _validate_file_names(set(files))
+    for name, digest in files.items():
+        if not isinstance(digest, str) or not _HASH.fullmatch(digest):
+            raise ManifestError(f"Invalid SHA256 hash for {name}")
+    return data
+
+
+def build_manifest(package_version: str, files: dict[str, bytes], agents_created: bool = False) -> bytes:
+    _validate_file_names(set(files))
+    if not package_version:
+        raise ManifestError("Missing package version")
+    data = {
+        "version": "1.0",
+        "skill": SKILL_ID,
+        "package_version": package_version,
+        "files": {name: hash_content(value) for name, value in sorted(files.items())},
+        "agents_created": agents_created,
+    }
+    return json.dumps(data, indent=2, ensure_ascii=False).encode("utf-8")
+
+
+def _block_bounds(content: bytes) -> tuple[int, int, bool] | None:
+    body = content[3:] if content.startswith(b"\xef\xbb\xbf") else content
+    if body.count(MARKER_START) != body.count(MARKER_END) or body.count(MARKER_START) > 1:
+        raise ManifestError("Missing or duplicate AGENTS.md marker")
+    if MARKER_START not in body:
+        return None
+    start = body.index(MARKER_START)
+    end = body.index(MARKER_END, start) if MARKER_END in body[start:] else -1
+    if end < 0 or (start and body[start - 1 : start] != b"\n"):
+        raise ManifestError("Malformed AGENTS.md block")
+    newline = b"\r\n" if body[start + len(MARKER_START) :].startswith(b"\r\n") else b"\n"
+    for separator in (True, False):
+        metadata = b"<!-- codex-core:skill:separator=" + (b"1" if separator else b"0") + b" -->"
+        expected = newline.join((MARKER_START, metadata, _INSTRUCTION, MARKER_END))
+        if body[start : start + len(expected)] == expected:
+            finish = start + len(expected)
+            if body[finish : finish + len(newline)] == newline:
+                finish += len(newline)
+            elif finish != len(body):
+                raise ManifestError("Malformed AGENTS.md block ending")
+            if separator and (start == 0 or body[start - len(newline) : start] != newline):
+                raise ManifestError("Malformed AGENTS.md separator")
+            offset = 3 if content.startswith(b"\xef\xbb\xbf") else 0
+            return start + offset, finish + offset, separator
+    raise ManifestError("AGENTS.md instruction modified or corrupt")
+
+
+def has_valid_agents_block(content: bytes) -> bool:
+    return _block_bounds(content) is not None
+
+
+def update_agents_md_bytes(content: bytes, remove: bool = False) -> bytes:
+    bounds = _block_bounds(content)
+    if bounds is not None:
+        start, end, separator = bounds
+        if remove:
+            if separator:
+                start -= 2 if content[start - 2 : start] == b"\r\n" else 1
+            return content[:start] + content[end:]
+        return content
+    if remove:
+        return content
+    body = content[3:] if content.startswith(b"\xef\xbb\xbf") else content
+    newline = b"\r\n" if b"\r\n" in body else b"\n"
+    separator = bool(body and not body.endswith(b"\n"))
+    metadata = b"<!-- codex-core:skill:separator=" + (b"1" if separator else b"0") + b" -->"
+    block = newline.join((MARKER_START, metadata, _INSTRUCTION, MARKER_END)) + newline
+    return content + (newline if separator else b"") + block