pathly-adapters 2.9.0__tar.gz → 2.9.2__tar.gz

{pathly_adapters-2.9.0 → pathly_adapters-2.9.2}/PKG-INFO

@@ -1,13 +1,12 @@
-Metadata-Version: 2.4
-Name: pathly-adapters
-Version: 2.9.0
-Summary: Pathly adapter installer — stitches and deploys agent files to AI host tools.
-Requires-Python: >=3.11
-Requires-Dist: pyyaml>=6.0
-Requires-Dist: flask>=2.3
-Requires-Dist: mcp>=1.0.0
-Provides-Extra: dev
-Requires-Dist: pytest>=8; extra == "dev"
-Requires-Dist: build; extra == "dev"
-Requires-Dist: twine; extra == "dev"
-Requires-Dist: jsonschema>=4; extra == "dev"
+Metadata-Version: 2.4
+Name: pathly-adapters
+Version: 2.9.2
+Summary: Pathly adapter installer — stitches and deploys agent files to AI host tools.
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: flask>=2.3
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: jsonschema>=4; extra == "dev"

{pathly_adapters-2.9.0 → pathly_adapters-2.9.2}/README.md

@@ -1,153 +1,153 @@
-# pathly-adapters
-
-Stitches Pathly agent files and installs them into AI host tools (Claude Code, Codex, Copilot).
-
-## Install (end users)
-
-Requires Python 3.11+. Install [pipx](https://pipx.pypa.io) if you don't have it:
-
-```bash
-pip install pipx
-pipx ensurepath
-```
-
-Then install Pathly:
-
-```bash
-pipx install pathly-adapters
-```
-
-`pipx` keeps the package in its own isolated environment and puts `pathly-setup` on your PATH automatically — no virtual environment to manage, no activation step.
-
-## Quick start
-
-```bash
-pathly-setup --dry-run    # preview what will be installed
-pathly-setup --apply      # install into all detected hosts
-```
-
-That's it. Pathly detects Claude Code, Codex, and Copilot automatically.
-
-Then open Claude Code in your project directory and start:
-
-```
-/pathly start            ← welcome screen + pick what to do
-/pathly go               ← describe what you want; director routes it
-/pathly build            ← implement next conversation
-/pathly end              ← retro + archive
-```
-
-All commands go through `/pathly`. See [docs/FLOW_DIAGRAM.md](docs/FLOW_DIAGRAM.md) for the full command reference.
-
-> **Tip:** `/start` and `/pathly start` are equivalent. `/pathly` dispatches to the same skill; direct invocation skips the dispatcher.
-
-## All commands
-
-```bash
-pathly-setup                        # detect hosts; launch interactive menu
-pathly-setup --dry-run              # preview what would be written
-pathly-setup --apply                # install into all detected hosts
-pathly-setup claude --apply         # install for Claude Code only
-pathly-setup codex --apply          # install for Codex only
-pathly-setup copilot --apply        # install for Copilot / VS Code only
-pathly-setup --repair               # overwrite Pathly-owned files
-pathly-setup --force                # overwrite all files, even non-Pathly-owned
-pathly-setup --uninstall            # remove all Pathly-owned files
-pathly-events summary <feature>     # print token/cost table for a pipeline run
-pathly-state <feature>              # print current FSM state for a feature
-pathly-tokens                       # print token/cost summary across all pipeline runs
-pathly-validate-flow <flow.yaml>    # validate a flow YAML against the FSM schema
-```
-
-`--dry-run` never writes. `--apply` is required for any writes.
-
-## Supported Hosts
-
-| Host | Detected by | Installed locations |
-|------|-------------|---------------------|
-| `claude` | `~/.claude/` directory exists | `~/.claude/agents/` (behavioral contracts)<br>`~/.claude/skills/` (skill folders) |
-| `codex` | Codex config directory exists | `~/.codex/agents/` + `~/.codex/skills/` + local plugin marketplace |
-| `copilot` | VS Code + Copilot detected | `~/.vscode/extensions/pathly/agents/`<br>`~/.vscode/extensions/pathly/skills/` |
-
-## How It Works
-
-1. **Detect** — scans for installed hosts on the current machine.
-2. **Stitch** — combines `core/agents/` and `core/skills/` content with adapter-specific `_meta/<name>.yaml` to produce deployable agent and skill files (frontmatter + body + spawn section).
-3. **Materialize** — writes stitched files to the host config location. A manifest tracks Pathly-owned files; `--repair` overwrites owned files, `--force` overwrites everything. Install is atomic — if anything fails, already-written files are rolled back.
-4. **Register Codex plugin** - for Codex installs, writes `~/.codex/pathly-marketplace`, enables `pathly@pathly-local`, and refreshes the marketplace through the Codex CLI when available.
-
-## FSM HTTP Server
-
-Pathly skills communicate with the Python FSM engine over HTTP, not MCP. The server runs locally on port 8765 and is auto-started by the `fsm-call` skill when needed — no manual setup required.
-
-```
-POST http://127.0.0.1:8765/next_action       ← get current state + agent instructions
-POST http://127.0.0.1:8765/complete_stage    ← advance FSM to next state
-POST http://127.0.0.1:8765/record_activity   ← write telemetry to ~/.pathly/activity.jsonl
-GET  http://127.0.0.1:8765/events/stream     ← SSE stream of EVENTS.jsonl (used by Studio)
-GET  http://127.0.0.1:8765/health            ← liveness check
-```
-
-Start it manually if needed:
-```bash
-pathly-fsm-http
-# or: python -m pathly_orchestrator.http_server
-```
-
-The `fsm-call` skill (shared by all FSM-using skills) handles health-check, auto-start, and the HTTP POST — skills never call the server directly.
-
-## Development setup
-
-```bash
-git clone <repo>
-cd pathly-adapters
-python -m venv .venv
-.venv\Scripts\activate      # Windows
-# source .venv/bin/activate  # macOS/Linux
-pip install -e ".[dev]"
-pytest
-```
-
-To build and publish a new release:
-
-```bash
-python -m build
-twine upload dist/*
-```
-
-## Docs
-
-| Doc | What's in it |
-|---|---|
-| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Adapter surfaces per host (Claude, Codex, Copilot), deployment structure, how skills/agents are materialized, host detection, installed manifests |
-| [docs/FLOW_DIAGRAM.md](docs/FLOW_DIAGRAM.md) | How a user invokes Pathly from each host, install flow, what files get deployed where, host-specific entry points |
-| [docs/PATHLY_ARCHITECTURE.md](docs/PATHLY_ARCHITECTURE.md) | install_cli packages, pathly_data layout, stitch pipeline, resource loading, host adapter structure, pyproject entry points |
-| [docs/INSTALLER_DESIGN.md](docs/INSTALLER_DESIGN.md) | Design goals, implementation phases, subagent policy, user stories, main risks |
-| [docs/MULTI_TOOL_DESIGN.md](docs/MULTI_TOOL_DESIGN.md) | Current adapter structure, source-of-truth rules, current adapters, installed manifests, future adapter work |
-| [docs/PRODUCTION_READINESS.md](docs/PRODUCTION_READINESS.md) | Adapter release criteria: install checks for each host, pathly-setup flags, package build/publish, marketplace manifests |
-| [docs/SECURITY.md](docs/SECURITY.md) | Hook injection risks, subprocess calls in installer, file write safety, trust boundaries, marketplace manifest integrity |
-| [docs/SYSTEM_REVIEW.md](docs/SYSTEM_REVIEW.md) | Adapter strengths, risks, design decisions, hardening recommendations |
-| [src/pathly_data/core/SKILLS_OVERVIEW.md](src/pathly_data/core/SKILLS_OVERVIEW.md) | Full reference for all 29 user-facing Pathly skills with ASCII flow diagrams |
-
-For engine-specific docs (FSM, orchestrator, state machine, team-flow driver):
-see [github.com/hamilton-sky/pathly](https://github.com/hamilton-sky/pathly) — `pathly-engine/docs/` folder.
-
-## Release Status
-
-Stable (2.9.0). Core install path (`--dry-run`, `--apply`, `--uninstall`) is verified with full rollback on failure. Copilot destination paths follow the VS Code Copilot agent spec and may require `--repair` after a VS Code update.
-
-**2.9.0 changes:** FSM and telemetry transport moved from MCP to HTTP. All skills now use the shared `fsm-call` skill which auto-starts the HTTP server. `mcp_config.py` removed; no MCP servers are registered during install.
-
-## Known Limitations
-
-- **Windows: broken stub if you previously ran `pip install pathly-adapters` directly** — a bare `pip install` (outside pipx) leaves a `pathly-setup.exe` stub in the global Python Scripts directory that shadows the pipx version and throws `ModuleNotFoundError: No module named 'install_cli'`. Fix: delete the stub at `%LOCALAPPDATA%\Programs\Python\Python3XX\Scripts\pathly-setup.exe` and its matching `~athly_adapters-*.dist-info` folder in `site-packages`, then open a fresh terminal. Always use `pipx install pathly-adapters` as documented.
-
-- **Codex install unverified on a clean machine** — the Codex adapter is committed and `pathly-setup codex --apply` runs without error, but a full clean-machine smoke test has not been completed. Use Codex support at your own risk until this is confirmed.
-
-- **Copilot paths may need `--repair` after a VS Code update** — Pathly installs agent files to the VS Code Copilot agent spec path, which may change between VS Code versions. Run `pathly-setup --repair` after a VS Code update if Copilot agents stop appearing.
-
-- **Hook path validation requires Python 3.9+** — hook scripts use `Path.is_relative_to()`, introduced in Python 3.9. The project already requires Python 3.11+, so this is always satisfied.
-
-- **Hooks require `PATHLY_PROJECT_ROOT`** — hook scripts (`classify_feedback.py`, `inject_feedback_ttl.py`) read the `PATHLY_PROJECT_ROOT` environment variable to locate the active project's `plans/` directory. If this variable is not set, hooks exit immediately without performing any action.
-
-- **Hook parity gap** — Pathly hooks run automatically only under Claude Code. Codex and Copilot VS Code require manual install; see [Hook surface coverage](docs/SECURITY.md#hook-surface-coverage).
+# pathly-adapters
+
+Stitches Pathly agent files and installs them into AI host tools (Claude Code, Codex, Copilot).
+
+## Install (end users)
+
+Requires Python 3.11+. Install [pipx](https://pipx.pypa.io) if you don't have it:
+
+```bash
+pip install pipx
+pipx ensurepath
+```
+
+Then install Pathly:
+
+```bash
+pipx install pathly-adapters
+```
+
+`pipx` keeps the package in its own isolated environment and puts `pathly-setup` on your PATH automatically — no virtual environment to manage, no activation step.
+
+## Quick start
+
+```bash
+pathly-setup --dry-run    # preview what will be installed
+pathly-setup --apply      # install into all detected hosts
+```
+
+That's it. Pathly detects Claude Code, Codex, and Copilot automatically.
+
+Then open Claude Code in your project directory and start:
+
+```
+/pathly start            ← welcome screen + pick what to do
+/pathly go               ← describe what you want; director routes it
+/pathly build            ← implement next conversation
+/pathly end              ← retro + archive
+```
+
+All commands go through `/pathly`. See [docs/FLOW_DIAGRAM.md](docs/FLOW_DIAGRAM.md) for the full command reference.
+
+> **Tip:** `/start` and `/pathly start` are equivalent. `/pathly` dispatches to the same skill; direct invocation skips the dispatcher.
+
+## All commands
+
+```bash
+pathly-setup                        # detect hosts; launch interactive menu
+pathly-setup --dry-run              # preview what would be written
+pathly-setup --apply                # install into all detected hosts
+pathly-setup claude --apply         # install for Claude Code only
+pathly-setup codex --apply          # install for Codex only
+pathly-setup copilot --apply        # install for Copilot / VS Code only
+pathly-setup --repair               # overwrite Pathly-owned files
+pathly-setup --force                # overwrite all files, even non-Pathly-owned
+pathly-setup --uninstall            # remove all Pathly-owned files
+pathly-events summary <feature>     # print token/cost table for a pipeline run
+pathly-state <feature>              # print current FSM state for a feature
+pathly-tokens                       # print token/cost summary across all pipeline runs
+pathly-validate-flow <flow.yaml>    # validate a flow YAML against the FSM schema
+```
+
+`--dry-run` never writes. `--apply` is required for any writes.
+
+## Supported Hosts
+
+| Host | Detected by | Installed locations |
+|------|-------------|---------------------|
+| `claude` | `~/.claude/` directory exists | `~/.claude/agents/` (behavioral contracts)<br>`~/.claude/skills/` (skill folders) |
+| `codex` | Codex config directory exists | `~/.codex/agents/` + `~/.codex/skills/` + local plugin marketplace |
+| `copilot` | VS Code + Copilot detected | `~/.vscode/extensions/pathly/agents/`<br>`~/.vscode/extensions/pathly/skills/` |
+
+## How It Works
+
+1. **Detect** — scans for installed hosts on the current machine.
+2. **Stitch** — combines `core/agents/` and `core/skills/` content with adapter-specific `_meta/<name>.yaml` to produce deployable agent and skill files (frontmatter + body + spawn section).
+3. **Materialize** — writes stitched files to the host config location. A manifest tracks Pathly-owned files; `--repair` overwrites owned files, `--force` overwrites everything. Install is atomic — if anything fails, already-written files are rolled back.
+4. **Register Codex plugin** - for Codex installs, writes `~/.codex/pathly-marketplace`, enables `pathly@pathly-local`, and refreshes the marketplace through the Codex CLI when available.
+
+## FSM HTTP Server
+
+Pathly skills communicate with the Python FSM engine over HTTP, not MCP. The server runs locally on port 8765 and is auto-started by the `fsm-call` skill when needed — no manual setup required.
+
+```
+POST http://127.0.0.1:8765/next_action       ← get current state + agent instructions
+POST http://127.0.0.1:8765/complete_stage    ← advance FSM to next state
+POST http://127.0.0.1:8765/record_activity   ← write telemetry to ~/.pathly/activity.jsonl
+GET  http://127.0.0.1:8765/events/stream     ← SSE stream of EVENTS.jsonl (used by Studio)
+GET  http://127.0.0.1:8765/health            ← liveness check
+```
+
+Start it manually if needed:
+```bash
+pathly-fsm-http
+# or: python -m pathly_orchestrator.http_server
+```
+
+The `fsm-call` skill (shared by all FSM-using skills) handles health-check, auto-start, and the HTTP POST — skills never call the server directly.
+
+## Development setup
+
+```bash
+git clone <repo>
+cd pathly-adapters
+python -m venv .venv
+.venv\Scripts\activate      # Windows
+# source .venv/bin/activate  # macOS/Linux
+pip install -e ".[dev]"
+pytest
+```
+
+To build and publish a new release:
+
+```bash
+python -m build
+twine upload dist/*
+```
+
+## Docs
+
+| Doc | What's in it |
+|---|---|
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Adapter surfaces per host (Claude, Codex, Copilot), deployment structure, how skills/agents are materialized, host detection, installed manifests |
+| [docs/FLOW_DIAGRAM.md](docs/FLOW_DIAGRAM.md) | How a user invokes Pathly from each host, install flow, what files get deployed where, host-specific entry points |
+| [docs/PATHLY_ARCHITECTURE.md](docs/PATHLY_ARCHITECTURE.md) | install_cli packages, pathly_data layout, stitch pipeline, resource loading, host adapter structure, pyproject entry points |
+| [docs/INSTALLER_DESIGN.md](docs/INSTALLER_DESIGN.md) | Design goals, implementation phases, subagent policy, user stories, main risks |
+| [docs/MULTI_TOOL_DESIGN.md](docs/MULTI_TOOL_DESIGN.md) | Current adapter structure, source-of-truth rules, current adapters, installed manifests, future adapter work |
+| [docs/PRODUCTION_READINESS.md](docs/PRODUCTION_READINESS.md) | Adapter release criteria: install checks for each host, pathly-setup flags, package build/publish, marketplace manifests |
+| [docs/SECURITY.md](docs/SECURITY.md) | Hook injection risks, subprocess calls in installer, file write safety, trust boundaries, marketplace manifest integrity |
+| [docs/SYSTEM_REVIEW.md](docs/SYSTEM_REVIEW.md) | Adapter strengths, risks, design decisions, hardening recommendations |
+| [src/pathly_data/core/SKILLS_OVERVIEW.md](src/pathly_data/core/SKILLS_OVERVIEW.md) | Full reference for all 29 user-facing Pathly skills with ASCII flow diagrams |
+
+For engine-specific docs (FSM, orchestrator, state machine, team-flow driver):
+see [github.com/hamilton-sky/pathly](https://github.com/hamilton-sky/pathly) — `pathly-engine/docs/` folder.
+
+## Release Status
+
+Stable (2.9.0). Core install path (`--dry-run`, `--apply`, `--uninstall`) is verified with full rollback on failure. Copilot destination paths follow the VS Code Copilot agent spec and may require `--repair` after a VS Code update.
+
+**2.9.0 changes:** FSM and telemetry transport moved from MCP to HTTP. All skills now use the shared `fsm-call` skill which auto-starts the HTTP server. `mcp_config.py` removed; no MCP servers are registered during install.
+
+## Known Limitations
+
+- **Windows: broken stub if you previously ran `pip install pathly-adapters` directly** — a bare `pip install` (outside pipx) leaves a `pathly-setup.exe` stub in the global Python Scripts directory that shadows the pipx version and throws `ModuleNotFoundError: No module named 'install_cli'`. Fix: delete the stub at `%LOCALAPPDATA%\Programs\Python\Python3XX\Scripts\pathly-setup.exe` and its matching `~athly_adapters-*.dist-info` folder in `site-packages`, then open a fresh terminal. Always use `pipx install pathly-adapters` as documented.
+
+- **Codex install unverified on a clean machine** — the Codex adapter is committed and `pathly-setup codex --apply` runs without error, but a full clean-machine smoke test has not been completed. Use Codex support at your own risk until this is confirmed.
+
+- **Copilot paths may need `--repair` after a VS Code update** — Pathly installs agent files to the VS Code Copilot agent spec path, which may change between VS Code versions. Run `pathly-setup --repair` after a VS Code update if Copilot agents stop appearing.
+
+- **Hook path validation requires Python 3.9+** — hook scripts use `Path.is_relative_to()`, introduced in Python 3.9. The project already requires Python 3.11+, so this is always satisfied.
+
+- **Hooks require `PATHLY_PROJECT_ROOT`** — hook scripts (`classify_feedback.py`, `inject_feedback_ttl.py`) read the `PATHLY_PROJECT_ROOT` environment variable to locate the active project's `plans/` directory. If this variable is not set, hooks exit immediately without performing any action.
+
+- **Hook parity gap** — Pathly hooks run automatically only under Claude Code. Codex and Copilot VS Code require manual install; see [Hook surface coverage](docs/SECURITY.md#hook-surface-coverage).

{pathly_adapters-2.9.0 → pathly_adapters-2.9.2}/pyproject.toml

@@ -1,48 +1,48 @@
-[build-system]
-requires = ["setuptools>=68", "wheel"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "pathly-adapters"
-version = "2.9.0"
-description = "Pathly adapter installer — stitches and deploys agent files to AI host tools."
-requires-python = ">=3.11"
-dependencies = ["pyyaml>=6.0", "flask>=2.3", "mcp>=1.0.0"]
-
-[project.optional-dependencies]
-dev = ["pytest>=8", "build", "twine", "jsonschema>=4"]
-
-[project.scripts]
-pathly-setup = "install_cli.__main__:main"
-pathly-tokens = "pathly_telemetry.report:main"
-pathly-events = "pathly_orchestrator.eventlog:_cli"
-pathly-state = "pathly_orchestrator.eventlog:_state_cli"
-pathly-fsm-http = "pathly_orchestrator.http_server:main"
-pathly-validate-flow = "pathly_orchestrator.state:validate_flow_cli"
-pathly-run = "pathly_orchestrator.runner:main"
-pathly-status = "pathly_orchestrator.status_cli:main"
-pathly-log = "pathly_orchestrator.log_cli:main"
-pathly-back = "pathly_orchestrator.back_cli:main"
-pathly-ff   = "pathly_orchestrator.ff_cli:main"
-pathly-studio = "pathly_studio_cli.install:main"
-pathly-design = "pathly_data.core.design.cli:main"
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-pythonpath = ["src"]
-addopts = ["-p", "no:cacheprovider"]
-
-[tool.setuptools.packages.find]
-where = ["src"]
-include = ["install_cli*", "pathly_telemetry*", "pathly_data*", "pathly_orchestrator*", "pathly_hooks*", "pathly_studio_cli*"]
-
-[tool.setuptools.package-data]
-"pathly_data" = [
-    "core/**/*",
-    "core/design/data/**/*",
-    "core/design/scripts/**/*",
-    "adapters/**/*",
-    "adapters/claude/.claude-plugin/*",
-    "adapters/codex/.codex-plugin/*",
-    "schemas/*.json",
-]
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pathly-adapters"
+version = "2.9.2"
+description = "Pathly adapter installer — stitches and deploys agent files to AI host tools."
+requires-python = ">=3.11"
+dependencies = ["pyyaml>=6.0", "flask>=2.3"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "build", "twine", "jsonschema>=4"]
+
+[project.scripts]
+pathly-setup = "install_cli.__main__:main"
+pathly-tokens = "pathly_telemetry.report:main"
+pathly-events = "pathly_orchestrator.eventlog:_cli"
+pathly-state = "pathly_orchestrator.eventlog:_state_cli"
+pathly-fsm-http = "pathly_orchestrator.http_server:main"
+pathly-validate-flow = "pathly_orchestrator.state:validate_flow_cli"
+pathly-run = "pathly_orchestrator.runner:main"
+pathly-status = "pathly_orchestrator.status_cli:main"
+pathly-log = "pathly_orchestrator.log_cli:main"
+pathly-back = "pathly_orchestrator.back_cli:main"
+pathly-ff   = "pathly_orchestrator.ff_cli:main"
+pathly-studio = "pathly_studio_cli.install:main"
+pathly-design = "pathly_data.core.design.cli:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = ["-p", "no:cacheprovider"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["install_cli*", "pathly_telemetry*", "pathly_data*", "pathly_orchestrator*", "pathly_hooks*", "pathly_studio_cli*"]
+
+[tool.setuptools.package-data]
+"pathly_data" = [
+    "core/**/*",
+    "core/design/data/**/*",
+    "core/design/scripts/**/*",
+    "adapters/**/*",
+    "adapters/claude/.claude-plugin/*",
+    "adapters/codex/.codex-plugin/*",
+    "schemas/*.json",
+]

{pathly_adapters-2.9.0 → pathly_adapters-2.9.2}/setup.cfg

@@ -1,4 +1,4 @@
-[egg_info]
-tag_build = 
-tag_date = 0
-
+[egg_info]
+tag_build = 
+tag_date = 0
+

{pathly_adapters-2.9.0 → pathly_adapters-2.9.2}/src/install_cli/__main__.py

@@ -1,4 +1,4 @@
-from .setup_command import main
-
-if __name__ == "__main__":
-    main()
+from .setup_command import main
+
+if __name__ == "__main__":
+    main()

pathly_adapters-2.9.2/src/install_cli/materialize.py

@@ -0,0 +1,160 @@
+import hashlib
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+MANIFEST_NAME = ".pathly-manifest.json"
+
+
+def _hash_files_dict(files: dict) -> str:
+    return hashlib.sha256(json.dumps(files, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+
+
+def _load_manifest(dest: Path) -> dict:
+    manifest_path = dest / MANIFEST_NAME
+    if manifest_path.exists():
+        try:
+            data = json.loads(manifest_path.read_text(encoding="utf-8"))
+            if "_manifest_version" not in data:
+                raise ValueError("Manifest missing _manifest_version field")
+            files = data.get("files", {})
+            if data.get("_manifest_hash", "") != _hash_files_dict(files):
+                raise ValueError("Manifest hash mismatch — file may be corrupted or tampered")
+            return data
+        except (json.JSONDecodeError, OSError):
+            return {"files": {}}
+    return {"files": {}}
+
+
+def _save_manifest(dest: Path, manifest: dict) -> None:
+    dest.mkdir(parents=True, exist_ok=True)
+    manifest["_manifest_version"] = "1"
+    manifest["_manifest_hash"] = _hash_files_dict(manifest["files"])
+    (dest / MANIFEST_NAME).write_text(
+        json.dumps(manifest, indent=2), encoding="utf-8"
+    )
+
+
+def materialize(
+    files: dict[str, str],
+    dest: Path,
+    *,
+    repair: bool = False,
+    force: bool = False,
+    dry_run: bool = False,
+) -> list[str]:
+    """Copy stitched agent files to dest. Returns list of filenames written (or would-write)."""
+    manifest = _load_manifest(dest)
+    owned = set(manifest["files"].keys())
+    written: list[str] = []
+
+    for name, content in files.items():
+        target = dest / name
+        # Guard against path traversal (e.g. name = "../../etc/passwd")
+        if not target.resolve().is_relative_to(dest.resolve()):
+            raise ValueError(
+                f"Path traversal detected: {name!r} escapes destination {dest}"
+            )
+        if target.exists():
+            if name in owned and not repair:
+                continue
+            if name not in owned and not force:
+                continue
+
+        written.append(name)
+        if not dry_run:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(content, encoding="utf-8")
+            manifest["files"][name] = datetime.now(timezone.utc).isoformat()
+
+    if not dry_run and written:
+        _save_manifest(dest, manifest)
+
+    return written
+
+
+def materialize_flows(
+    dest: Path,
+    *,
+    repair: bool = False,
+    force: bool = False,
+    dry_run: bool = False,
+) -> list[str]:
+    """Copy *.flow.yaml files from the installed package to dest. Returns list of filenames written.
+
+    Flow YAMLs are always authoritative — repair=True is forced so that
+    re-running the installer keeps installed flows in sync with the source
+    without requiring an explicit --repair flag.
+    """
+    from .resources import core_flows_path
+
+    flows_src = core_flows_path()
+    files: dict[str, str] = {
+        f.name: f.read_text(encoding="utf-8")
+        for f in sorted(flows_src.glob("*.flow.yaml"))
+    }
+    return materialize(files, dest, repair=True, force=force, dry_run=dry_run)
+
+
+def uninstall(dest: Path, *, dry_run: bool = False, confirm_manifest: bool = False) -> list[str]:
+    """Remove all Pathly-owned files from dest using the manifest.
+
+    Returns list of filenames removed (or would-remove in dry_run).
+    If manifest entries are missing from disk and confirm_manifest is False,
+    prints a warning to stderr and aborts without deleting anything.
+    If confirm_manifest is True, missing entries are skipped and deletion proceeds.
+    """
+    manifest_path = dest / MANIFEST_NAME
+    if not manifest_path.exists():
+        print(f"  [warn] No manifest at {manifest_path} — nothing to uninstall.", file=sys.stderr)
+        return []
+
+    manifest = _load_manifest(dest)
+    removed: list[str] = []
+    missing: list[str] = []
+
+    # Pass 1: validate all entries before touching the filesystem.
+    # This prevents partial deletion when a manifest is tampered.
+    for name in list(manifest["files"]):
+        target = dest / name
+        if not target.resolve().is_relative_to(dest.resolve()):
+            raise ValueError(
+                f"Path traversal detected in manifest: {name!r} escapes destination {dest}"
+            )
+        if not target.exists():
+            missing.append(name)
+
+    if missing and not confirm_manifest:
+        print(
+            f"  [warn] Aborting uninstall — the following manifest entries are not found on disk:\n"
+            + "\n".join(f"    {name}" for name in missing),
+            file=sys.stderr,
+        )
+        return []
+
+    # Pass 2: all entries are clean — perform deletions.
+    missing_set = set(missing)
+    for name in list(manifest["files"]):
+        if name in missing_set:
+            continue
+        target = dest / name
+        removed.append(name)
+        if not dry_run:
+            try:
+                target.unlink()
+            except FileNotFoundError:
+                pass
+            # Remove empty parent directories (nested skill dirs)
+            try:
+                target.parent.rmdir()
+            except OSError:
+                pass
+
+    if not dry_run:
+        try:
+            manifest_path.unlink()
+        except FileNotFoundError:
+            pass
+
+    return removed