[agentry] Add install manifest/lock for MAP-managed provider surfaces

[azalio]

Source

Local source note: /Users/azalio/Downloads/Telegram Desktop/medium-agent-rag-batch-20260629/we-built-pip-for-ai-coding-agents-meet-agentry-65dd8f30f662.md, extracted from Medium article "We Built pip for AI Coding Agents — Meet agentry" (https://medium.com/@korotkin/we-built-pip-for-ai-coding-agents-meet-agentry-65dd8f30f662).

Source-specific idea used here: agentry treats agent skills/agents/commands/hooks/MCP servers as package-like components with a declaration file, lockfile, local store, idempotent sync, and deterministic installs into provider-native layouts.

Relevant source takeaways

• AI agent components drift because Claude, Codex, Cursor, Gemini, OpenCode, etc. use different folders and formats.
• A package-manager model fixes this with a declarative source of intent, lockfile with exact resolved versions/SHAs, local store, and idempotent sync.
• The useful MAP slice is not to vendor agentry or replace mapify init; it is to make MAP's own installed provider surface auditable as a whole, not only per file.
• The article's lockfile idea maps cleanly to MAP upgrades: users should know exactly which template version/hash installed each generated file and whether the target tree matches that resolved intent.

Repo evidence

• README.md:51-64 documents two provider install paths: default Claude via mapify init, and Codex via mapify init . --provider codex.
• README.md:193 documents that Claude installs .claude/skills/map-*/SKILL.md, while Codex installs .agents/skills/, .codex/agents/, .codex/config.toml, hooks, and shared .map/scripts/.
• src/mapify_cli/delivery/providers.py:21-39 defines a provider abstraction whose install() returns only category counts.
• src/mapify_cli/delivery/providers.py:49-70 installs Claude categories; src/mapify_cli/delivery/providers.py:77-99 installs Codex files. There is no aggregate install manifest or lock artifact returned/written by the provider abstraction.
• src/mapify_cli/delivery/managed_file_copier.py:1-18 already provides per-file metadata, template hashes, drift detection, backups, and fence-aware merge. That proves MAP has file-level ownership primitives, but not an install-level lock describing the resolved surface.
• Tests such as tests/test_managed_file_copier.py cover per-file hash/metadata/drift behavior, not a whole-install manifest/lock.

Existing issue search

Commands/searches used:

• gh issue list --state all --limit 120 --search "agentry OR package manager OR lockfile OR lock file OR install manifest OR uninstall OR reversible config OR provider sync OR component registry OR catalog"
• gh issue list --state all --limit 120 --search "managed file copier OR MAP-MANAGED OR drift detection OR fence-aware merge OR statusline OR mcp json"
• gh issue list --state all --limit 120 --search "provider target OR Cursor Gemini OpenCode provider OR provider integrations OR provider portability OR codex claude cursor"

Related issue checked:

• Codex hooks.json generator writes unsupported _map_managed top-level key #270 is closed and fixed Codex hooks.json unsupported _map_managed plus merge preservation. It is a specific Codex schema bug, not a general install lock/manifest.

No existing issue found for an aggregate MAP install lock or reproducible provider-surface manifest.

Why this is not already covered

Per-file MAP-MANAGED metadata can detect whether a single generated file drifted, but it cannot answer package-manager questions:

• Which provider targets were installed in this project?
• Which exact mapify version/template hashes make up this installed surface?
• Which files/config entries should exist after sync?
• Which generated files are orphaned after a template is removed?
• Is this checkout's agent surface reproducible from a recorded lock?

That is the gap agentry highlights.

Problem

mapify init writes many provider-specific surfaces, but MAP has no committed install lock/manifest summarizing the resolved generated component set. This makes upgrades and cross-machine verification harder: maintainers can inspect files one-by-one, but cannot run a single deterministic check that the installed Claude/Codex surface matches the resolved MAP package version/template set.

Proposed slice

Add a MAP-owned install manifest/lock artifact for generated provider surfaces.

Concrete shape:

• Write a committed, deterministic artifact such as .map/mapify.lock.json or .map/install-manifest.json during mapify init / provider install.
• Include at minimum: mapify version, provider target(s), template source path, destination path, content hash/template hash, management mode (full, fenced, config-merge, local-only), and whether the destination is expected to be committed or local/gitignored.
• Add a mapify sync/check-installed command that compares the current tree with the lock and reports: missing managed files, orphaned managed files, drifted managed regions, provider mismatch, and unsupported stale config metadata.
• Keep per-file metadata as the local drift primitive; the manifest is the aggregate package-manager view.
• Do not introduce external package sources in this slice; this is only for MAP's own generated components.

Acceptance criteria

• mapify init writes a deterministic install manifest/lock for Claude and Codex provider installs.
• The manifest records every MAP-managed file installed by the provider plus config-merge/local-only entries such as statusline or MCP merge when applicable.
• A check command can fail on missing/orphaned/drifted installed surfaces without reading arbitrary hidden folders by hand.
• Tests cover Claude install, Codex install, re-init idempotency, template removal/orphan detection, and drift detection via existing per-file metadata.
• Docs explain what to commit and what remains local/gitignored.

Guardrails

• Do not replace mapify init with a general external package manager.
• Do not require agentry or network access.
• Do not store secrets or local absolute paths in committed lock artifacts; local-only entries must be redacted or written to a gitignored sidecar.
• Do not treat the lock as permission to overwrite user edits silently; existing drift/backup behavior remains.