@andespindola/crow-skills 0.1.0

package/crow_skills/storage.py

@@ -0,0 +1,396 @@
+"""Managed copies, local-edit protection and recoverable multi-target transactions.
+
+Locks coordinate this CLI's writers. They are not a sandbox against a hostile
+process running as the same OS user; agent runtimes must not mutate a target
+concurrently. Backups live beside, never inside, the skill discovery directory.
+"""
+from contextlib import contextmanager
+from datetime import datetime, timezone
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import stat
+import uuid
+
+from .source import CrowError, MAX_FILE, MAX_PACKAGE, MAX_FILES, SHA, digest, file_entry, safe_relative, valid_name
+
+
+def checked(path):
+    path = Path(os.path.abspath(Path(path).expanduser()))
+    for part in reversed((path, *path.parents)):
+        if part.is_symlink():
+            raise CrowError("unsafe_destination", "Symlink no destino/estado; use um caminho físico explícito.")
+    return path
+
+
+def ensure_dir(path, mode=0o700):
+    path = checked(path)
+    path.mkdir(mode=mode, parents=True, exist_ok=True)
+    if not path.is_dir():
+        raise CrowError("unsafe_destination", "Diretório esperado no destino/estado.")
+    return path
+
+
+def private_dir(path):
+    path = ensure_dir(path)
+    if path.stat().st_uid != os.getuid():
+        raise CrowError("unsafe_state", "Diretório reservado pertence a outro usuário.")
+    path.chmod(0o700)
+    return path
+
+
+def snapshot(path):
+    """Hash complete trees including empty dirs; reject links/special files."""
+    path = checked(path)
+    if not path.exists():
+        return None
+    if not path.is_dir():
+        raise CrowError("unsafe_destination", "O destino de uma skill não é um diretório regular.")
+    result, total = {}, 0
+    for root, dirs, files in os.walk(path, followlinks=False):
+        for name in sorted(dirs + files):
+            p = Path(root) / name
+            rel = p.relative_to(path).as_posix()
+            safe_relative(rel)
+            info = p.lstat()
+            if stat.S_ISDIR(info.st_mode):
+                result[rel] = {"kind": "dir"}
+            elif stat.S_ISREG(info.st_mode):
+                total += info.st_size
+                if info.st_size > MAX_FILE or total > MAX_PACKAGE or len(result) >= MAX_FILES * 2:
+                    raise CrowError("package_limit", "Destino excede os limites de leitura segura.")
+                result[rel] = file_entry(p.read_bytes(), bool(info.st_mode & 0o111))
+            else:
+                raise CrowError("unsafe_destination", "Symlink ou arquivo especial encontrado no pacote instalado.")
+    return dict(sorted(result.items()))
+
+
+def atomic_json(path, data):
+    path = checked(path)
+    ensure_dir(path.parent)
+    temp = path.parent / ("." + path.name + "." + uuid.uuid4().hex)
+    try:
+        with temp.open("x", encoding="utf-8") as f:
+            os.chmod(temp, 0o600)
+            json.dump(data, f, ensure_ascii=False, sort_keys=True, indent=2)
+            f.write("\n")
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(temp, path)
+        # Persist directory entries on POSIX as well as JSON file contents.
+        fd = os.open(path.parent, os.O_RDONLY)
+        try:
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+    finally:
+        temp.unlink(missing_ok=True)
+
+
+def read_json(path):
+    path = checked(path)
+    try:
+        if not path.is_file() or path.stat().st_size > 16 * 1024 * 1024:
+            raise ValueError("size/type")
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (ValueError, OSError) as exc:
+        raise CrowError("invalid_state", "Estado/registro transacional inválido; nenhuma alteração aplicada.") from exc
+
+
+def validate_entries(entries):
+    if not isinstance(entries, dict) or len(entries) > MAX_FILES * 2:
+        raise CrowError("invalid_state", "Inventário inválido no estado.")
+    for name, value in entries.items():
+        safe_relative(name)
+        if not isinstance(value, dict):
+            raise CrowError("invalid_state", "Registro de arquivo inválido.")
+        if value == {"kind": "dir"}:
+            continue
+        if (set(value) != {"kind", "sha256", "executable"} or value["kind"] != "file" or
+                not isinstance(value["sha256"], str) or not re.fullmatch(r"[a-f0-9]{64}", value["sha256"]) or
+                not isinstance(value["executable"], bool)):
+            raise CrowError("invalid_state", "Hash/tipo de arquivo inválido no estado.")
+
+
+def validate_state(data, target):
+    try:
+        if (data["schema_version"] != 1 or data["target"] != str(target) or
+                not isinstance(data["installed"], dict) or len(data["installed"]) > 1000):
+            raise ValueError("schema")
+        for name, record in data["installed"].items():
+            valid_name(name)
+            validate_entries(record["entries"])
+            if not SHA.fullmatch(record["revision"]) or digest(record["entries"]) != record["package_sha256"]:
+                raise ValueError("hash")
+    except (KeyError, TypeError, ValueError) as exc:
+        raise CrowError("invalid_state", "Manifesto inválido ou associado a outro destino.") from exc
+    return data
+
+
+class Store:
+    def __init__(self, home):
+        self.home = checked(home)
+        self.root = self.home / ".local/state/crow-skills"
+
+    def state_path(self, target):
+        key = hashlib.sha256(str(checked(target)).encode()).hexdigest()
+        return self.root / "targets" / key / "state.json"
+
+    def state(self, target):
+        target = checked(target)
+        path = checked(self.state_path(target))
+        if not path.exists():
+            return {"schema_version": 1, "target": str(target), "installed": {}}
+        return validate_state(read_json(path), target)
+
+    def transactions(self):
+        directory = checked(self.root / "transactions")
+        return [self.journal(p.stem) for p in sorted(directory.glob("*.json"))] if directory.exists() else []
+
+    def journal(self, txid):
+        if not re.fullmatch(r"[a-f0-9]{32}", txid):
+            raise CrowError("invalid_transaction", "ID de transação inválido.")
+        data = read_json(self.root / "transactions" / (txid + ".json"))
+        try:
+            if data["id"] != txid or data["phase"] not in ("prepared", "restoring", "committed", "rolled_back"):
+                raise ValueError("phase")
+            targets = data["before"]
+            if not isinstance(targets, dict) or set(targets) != set(data["after"]):
+                raise ValueError("targets")
+            for target, before in targets.items():
+                if str(checked(target)) != target:
+                    raise ValueError("path")
+                validate_state(before, target)
+                validate_state(data["after"][target], target)
+            for item in data["items"]:
+                if item["target"] not in targets:
+                    raise ValueError("item target")
+                valid_name(item["name"])
+                for key in ("old", "new"):
+                    if item[key] is not None:
+                        validate_entries(item[key])
+        except (ValueError, KeyError, TypeError) as exc:
+            raise CrowError("invalid_transaction", "Registro transacional inconsistente; recuperação recusada.") from exc
+        return data
+
+    def pending(self):
+        return [t for t in self.transactions() if t["phase"] in ("prepared", "restoring")]
+
+    @contextmanager
+    def lock(self):
+        try:
+            import fcntl
+        except ImportError as exc:
+            raise CrowError("unsupported_platform", "Mutações requerem locks POSIX (macOS/Linux).") from exc
+        private_dir(self.root)
+        path = checked(self.root / "lock")
+        fd = os.open(path, os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0), 0o600)
+        try:
+            try:
+                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except BlockingIOError as exc:
+                raise CrowError("busy", "Outra operação crow-skills está em execução neste perfil.") from exc
+            yield
+        finally:
+            os.close(fd)
+
+    @staticmethod
+    def work(target, txid):
+        target = checked(target)
+        key = hashlib.sha256(str(target).encode()).hexdigest()[:20]
+        return checked(target.parent / ".crow-skills" / key / txid)
+
+    def plan(self, command, names, targets, source=None, replace=False, overwrite=False):
+        if self.pending():
+            raise CrowError("recovery_required", "Há uma transação interrompida. Execute recover antes de alterar instalações.")
+        packages, before, after, items, output = {}, {}, {}, [], []
+        for target_info in targets:
+            target = checked(target_info["path"])
+            if target.exists() and not target.is_dir():
+                raise CrowError("unsafe_destination", "Raiz de skills não é diretório.")
+            if target == self.home or target == Path(target.anchor) or self.root.is_relative_to(target):
+                raise CrowError("unsafe_destination", "Destino amplo demais ou contém o estado do instalador.")
+            if source and target.is_relative_to(source.path):
+                raise CrowError("unsafe_destination", "Não instale sobre o próprio repositório fonte.")
+            state = self.state(target)
+            key = str(target)
+            before[key] = state
+            after[key] = json.loads(json.dumps(state))
+            selected = list(names) if names else list(state["installed"])
+            for name in selected:
+                valid_name(name)
+                record = state["installed"].get(name)
+                current = snapshot(target / name)
+                if command != "install" and record is None:
+                    raise CrowError("not_managed", "Skill não gerenciada neste destino: " + name)
+                if record and current != record["entries"] and not overwrite:
+                    raise CrowError("local_changes", "Skill modificada/ausente: " + name + ". Revise; --overwrite-modified autoriza preservar backup e substituir/remover.")
+                if not record and current is not None and not replace:
+                    raise CrowError("unmanaged_conflict", "Destino já existe e não é gerenciado: " + name + ". Use --replace após revisar.")
+                new = None
+                if command != "uninstall":
+                    if record and command == "update" and record.get("source") != str(source.path):
+                        raise CrowError("source_mismatch", "Update requer a mesma origem; selecione --source explicitamente.")
+                    if name not in packages:
+                        packages[name] = source.package(name)
+                    new = packages[name].entries
+                if (record and command != "uninstall" and current == new
+                        and record["revision"] == source.revision and record.get("source") == str(source.path)):
+                    output.append({"name": name, "target": key, "agents": target_info["agents"], "action": "unchanged"})
+                    continue
+                action = "remove" if command == "uninstall" else ("replace" if current is not None else "install")
+                items.append({"name": name, "target": key, "old": current, "new": new})
+                output.append({"name": name, "target": key, "agents": target_info["agents"], "action": action})
+                if command == "uninstall":
+                    after[key]["installed"].pop(name)
+                else:
+                    after[key]["installed"][name] = {
+                        "revision": source.revision, "source": str(source.path), "entries": new,
+                        "package_sha256": digest(new), "agents": target_info["agents"],
+                        "installed_at": datetime.now(timezone.utc).isoformat(),
+                    }
+        return {"before": before, "after": after, "items": items, "packages": packages, "changes": output}
+
+    def apply(self, plan):
+        if not plan["items"]:
+            return None
+        with self.lock():
+            if self.pending():
+                raise CrowError("recovery_required", "Recuperação pendente; nenhuma alteração aplicada.")
+            for target, state in plan["before"].items():
+                if self.state(target) != state:
+                    raise CrowError("changed_during_plan", "O estado mudou após o preview; execute novamente.")
+            for item in plan["items"]:
+                if snapshot(Path(item["target"]) / item["name"]) != item["old"]:
+                    raise CrowError("changed_during_plan", "Um destino mudou após o preview; execute novamente.")
+            txid = uuid.uuid4().hex
+            data = {k: plan[k] for k in ("before", "after", "items")}
+            data.update(id=txid, phase="prepared", created_at=datetime.now(timezone.utc).isoformat())
+            journal = self.root / "transactions" / (txid + ".json")
+            try:
+                for target in plan["before"]:
+                    work = self.work(target, txid)
+                    private_dir(work.parent.parent)
+                    private_dir(work.parent)
+                    work.mkdir(mode=0o700)
+                    (work / "old").mkdir()
+                    (work / "new").mkdir()
+                for item in plan["items"]:
+                    if item["new"] is not None:
+                        new = self.work(item["target"], txid) / "new" / item["name"]
+                        plan["packages"][item["name"]].materialize(new)
+                        if snapshot(new) != item["new"]:
+                            raise CrowError("staging_failed", "Cópia staged não corresponde ao pacote validado.")
+                atomic_json(journal, data)
+                for item in plan["items"]:
+                    target = checked(item["target"])
+                    ensure_dir(target)
+                    dest = target / item["name"]
+                    work = self.work(target, txid)
+                    if snapshot(dest) != item["old"]:
+                        raise CrowError("changed_during_install", "Destino alterado durante instalação.")
+                    if item["old"] is not None:
+                        os.replace(dest, work / "old" / item["name"])
+                    if item["new"] is not None:
+                        os.replace(work / "new" / item["name"], dest)
+                for target, state in data["after"].items():
+                    atomic_json(self.state_path(target), state)
+                data["phase"] = "committed"
+                atomic_json(journal, data)
+            except (Exception, KeyboardInterrupt):
+                if journal.exists():
+                    # Leave the prepared journal on failure; recover will not overwrite edits.
+                    self._restore(data)
+                else:
+                    for target in plan["before"]:
+                        work = self.work(target, txid)
+                        if work.exists():
+                            shutil.rmtree(work)
+                raise
+            return txid
+
+    def _restore(self, data):
+        """Validate every target/backup before changing any during recovery."""
+        operations = []
+        for target, before in data["before"].items():
+            current = self.state(target)
+            if current != before and current != data["after"][target]:
+                raise CrowError("recovery_conflict", "Manifesto mudou após a transação; recuperação recusada.")
+        for item in reversed(data["items"]):
+            dest = checked(Path(item["target"]) / item["name"])
+            old = self.work(item["target"], data["id"]) / "old" / item["name"]
+            backup = snapshot(old)
+            current = snapshot(dest)
+            if backup is not None:
+                if backup != item["old"] or current not in (None, item["new"]):
+                    raise CrowError("recovery_conflict", "Backup/destino diverge; recuperação não sobrescreverá alterações locais.")
+                operations.append((dest, old))
+            elif item["old"] is None:
+                if current not in (None, item["new"]):
+                    raise CrowError("recovery_conflict", "Novo destino foi alterado; recuperação recusada.")
+                operations.append((dest, None))
+            elif current != item["old"]:
+                raise CrowError("recovery_conflict", "Backup original ausente; recuperação recusada.")
+        # A rollback is itself a multi-target mutation. Persist its intent before
+        # the first restore, so a second interruption remains recoverable.
+        data["phase"] = "restoring"
+        atomic_json(self.root / "transactions" / (data["id"] + ".json"), data)
+        for dest, backup in operations:
+            if dest.exists():
+                shutil.rmtree(dest)
+            if backup is not None:
+                os.replace(backup, dest)
+        for target, state in data["before"].items():
+            atomic_json(self.state_path(target), state)
+        data["phase"] = "rolled_back"
+        atomic_json(self.root / "transactions" / (data["id"] + ".json"), data)
+
+    def rollback(self, txid, recovery=False):
+        with self.lock():
+            data = self.journal(txid)
+            expected = ("prepared", "restoring") if recovery else ("committed",)
+            if data["phase"] not in expected:
+                raise CrowError("invalid_transaction", "Estado da transação incompatível com a operação.")
+            if not recovery and self.pending():
+                raise CrowError("recovery_required", "Resolva transações interrompidas primeiro.")
+            if not recovery:
+                for target, state in data["after"].items():
+                    if self.state(target) != state:
+                        raise CrowError("rollback_conflict", "Há mudanças posteriores; rollback antigo recusado.")
+            self._restore(data)
+
+    def status(self, targets, names=()):
+        rows = []
+        for target_info in targets:
+            target = checked(target_info["path"])
+            if target.exists() and not target.is_dir():
+                rows.append({"name": None, "target": str(target), "agents": target_info["agents"],
+                             "status": "unsafe", "revision": None, "activation_verified": False,
+                             "note": "Raiz de skills não é diretório; instalação recusada neste destino."})
+                continue
+            state = self.state(target)
+            found = set(state["installed"]) | set(names)
+            if target.is_dir():
+                found.update(p.name for p in target.iterdir() if p.name.startswith("crow-"))
+            for name in sorted(found):
+                try:
+                    valid_name(name)
+                except CrowError:
+                    rows.append({"name": name, "target": str(target), "agents": target_info["agents"],
+                                 "status": "unmanaged", "revision": None, "activation_verified": False,
+                                 "note": "Nome externo ao catálogo: não gerenciado nem removido por este CLI."})
+                    continue
+                record = state["installed"].get(name)
+                try:
+                    entries = snapshot(target / name)
+                    status = ("absent" if entries is None else "unmanaged") if record is None else (
+                        "missing" if entries is None else "installed" if entries == record["entries"] else "modified")
+                except CrowError:
+                    status = "unsafe"
+                rows.append({"name": name, "target": str(target), "agents": target_info["agents"],
+                             "status": status, "revision": record.get("revision") if record else None,
+                             "activation_verified": False})
+        return rows

package/docs/cli-security.md

@@ -0,0 +1,33 @@
+# Revisão de segurança do CLI
+
+## Fronteiras e controles do plano
+
+Ativos: skills já existentes, alterações locais, scripts/recursos completos, estado de instalação, credenciais Git externas e arquivos fora dos destinos autorizados.
+
+Fronteiras: catálogo/objetos Git são dados; escolha explícita do usuário/agente define destinos e operações; host interpreta as skills somente depois da instalação. O CLI não interpreta diretivas de SKILL.md como comandos e não executa scripts/dependency installers.
+
+Checklist aplicável: autorização por escopo e flags (sim); validação de nomes/refs/paths e tipos (sim); saída JSON e Git sem shell (sim); segredos fora de código/logs (sim); rollback, limites e concorrência (sim); dependências Python externas (nenhuma). Auth de servidor, SQL, TLS de serviço, CORS, JWT e sessão web não se aplicam a este processo local. Git fetch usa autenticação/transportes do Git do operador e não imprime stderr; não há token próprio.
+
+## Caminhos de ataque e verificação
+
+| Caminho | Controle e evidência a executar |
+|---|---|
+| Nome ou recurso escapando da pasta | Allowlist de nome, caminhos relativos normalizados, recusa de `..`, absoluto, controles e symlinks; testes de fonte/caminho |
+| Execução de script/hook durante instalação | Leitura Git inerte, sem checkout/exec de pacote, hooks/replace-objects desabilitados; copiar script sentinela sem execução |
+| Fonte diferente sob SHA aparente | Objetos do commit fixado e Git replace desabilitado; inventário/hashes completos, identidade de origem persistida |
+| Apagar/substituir terceiros ou edições | Manifesto por destino, preflight, --replace/--overwrite-modified explícitos, backup; testes de conflito/edições/arquivos extras |
+| Symlink/arquivo especial no destino ou estado | Checagem de componentes e scan de árvore, sem seguir links; testes de ancestor, link interno e FIFO |
+| Erro no segundo agente após mudar o primeiro | Staging, journal prévio e restauração; injeção de erro no segundo rename |
+| Interrupção após renames parciais | Journal preparado bloqueia novas mutações, recover valida e restaura; interrupção simulada e teste de edições pós-crash |
+| Rollback antigo apagando versão nova | Comparação de estado posterior e inventário antes de restaurar; teste de transação subsequente |
+| Dois instaladores concorrentes | Lock POSIX por perfil; segundo processo real deve retornar busy |
+| Preview ou list instalando silenciosamente | Sem gravação/lock/fetch no dry-run, flags explícitas em mutações; testes de diretório vazio e fetch proibido |
+| Metadados de complementaridade virando instalação em massa | Relacionamentos opcionais, --with-handoffs direto e explícito, sem expansão de overlays; teste de conjunto exato |
+
+Esta tabela define ameaça/controle, não é um certificado de segurança. Resultados executados e revisão independente são registrados separadamente na entrega. Persistem limites de processos hostis do mesmo usuário, filesystem/hardware, confiança no clone/configuração Git escolhido e efeitos que o host venha a permitir ao executar uma skill após instalada.
+
+## Snapshot npm
+
+O launcher usa spawn sem shell e Python isolado (`-I`), evitando import do cwd/PYTHONPATH. Não há dependências npm nem hooks de instalação. Prepack verifica bytes commitados e rejeita arquivos extras nas globs de publicação; caches Python são explicitamente excluídos. O smoke valida o tarball inteiro contra allowlist/hashes antes de instalar em perfil isolado. Checksums não provam autoria: distribuição depende da integridade/autorização do registro npm. Publicação deve ser escopada e restricted, sem fallback público.
+
+Resultados, falhas corrigidas e limites: [avaliação do CLI](evaluations/2026-10-20-cli.md).

package/docs/cli.md

@@ -0,0 +1,138 @@
+# crow-skills CLI 0.1.0
+
+CLI local-first para humanos e agentes. Python 3.10+, sem bibliotecas Python externas; Git é necessário para fontes em clone, não para o snapshot npm. O launcher npm requer Node 18+. Mutações suportadas em macOS/Linux (locks POSIX). Não instala nem configura um agente, não executa scripts das skills e não muda modelos, prompts ou permissões.
+
+## Executar
+
+No clone existente:
+
+```sh
+./bin/crow-skills --help
+python3 -m crow_skills list
+```
+
+O launcher do checkout pode ser referenciado por um symlink em um diretório já presente no PATH. Ele depende do caminho do checkout. Usar Git em um clone existente preserva a autenticação Git já configurada, inclusive para este repositório privado.
+
+### Pacote npm privado
+
+Nome: `@andespindola/crow-skills`; `publishConfig.access` é `restricted`. Isso não equivale a `private:true`, que impediria qualquer publicação. A publicação exige autorização/entitlement da conta npm; nunca faça fallback para public.
+
+Depois de a versão estar publicada e a conta estar autenticada com acesso:
+
+```sh
+npm install -g @andespindola/crow-skills
+crow-skills list
+npx --yes @andespindola/crow-skills related crow-backend --json
+```
+
+Para testar/distribuir o arquivo local sem registry:
+
+```sh
+npm pack
+npm install -g ./andespindola-crow-skills-0.1.0.tgz --ignore-scripts
+```
+
+O pacote contém o CLI Python e todas as skills do commit, com `release.json` de hashes. Não requer acesso ao GitHub ou clone para list/install. O launcher Node encaminha argumentos sem shell para Python em modo isolado, evitando imports pelo diretório do chamador/PYTHONPATH. `CROW_SKILLS_PYTHON` pode apontar para outro executável Python 3.10+. Não há dependências npm nem hooks de instalação que instalem skills automaticamente.
+
+`npm pack` roda um prepack de desenvolvimento que recusa payload não commitado e gera o snapshot. O arquivo enviado inclui somente o payload allowlisted, não análises, testes, notas, ambiente ou credenciais. A integridade do transporte/origem continua sendo responsabilidade do npm e do registro confiável; checksums locais não substituem assinatura/autenticidade.
+
+## Instalar
+
+Sem argumentos, `crow-skills install` em terminal interativo mostra catálogo e pede skills, agentes e escopo; depois apresenta o plano e pede aplicação. Não assume todos os agentes nem instalação global.
+
+```sh
+crow-skills install crow-behaviour --agents claude,codex --global --dry-run
+crow-skills install crow-behaviour --agents claude,codex --global --yes
+crow-skills install crow-debug --agents gemini,devin --project . --yes
+crow-skills install crow-debug --dest /caminho/do/host/skills --yes
+```
+
+`--dest` indica uma raiz de skills explícita para outro host; não promete compatibilidade/ativação nesse host. Escolha somente um escopo: `--global`, `--project PATH` ou `--dest PATH`. Não combine `--dest` com `--agents`.
+
+`--all` seleciona explicitamente todas as skills do catálogo em install. Sem `--all`, só os nomes pedidos são instalados. Cada pacote inteiro é copiado: referências, scripts, assets e metadata, preservando hashes e executabilidade. Dependências externas não são baixadas nem executadas pelo instalador.
+
+## Complementaridade
+
+```sh
+crow-skills list
+crow-skills info crow-backend --agents claude --global
+crow-skills related crow-behaviour --agents codex --global --json
+crow-skills install crow-backend --with-handoffs --agents claude --global --dry-run
+```
+
+O catálogo declara `role`, `owns` e `next`, com um owner por artefato. `composition.overlays` declara modos transversais, como crow-behaviour. `info`/`related` mostram handoffs de saída, consumidores, overlays aplicáveis, escopos coordenáveis e presença/integridade nos destinos selecionados. São sugestões de composição, não dependências, garantia de disponibilidade de ferramentas ou uma ordem para carregar toda a biblioteca.
+
+`--with-handoffs` inclui apenas os `next` diretos das skills explicitamente selecionadas. Não percorre ciclos/transitividade, não instala consumidores e não expande overlays para todo o catálogo. Relevância por intenção continua sendo decisão do usuário/agente; o CLI não inventa um roteador semântico por palavras-chave.
+
+## Origem e versões
+
+```sh
+crow-skills list --source /caminho/do/clone --ref main --json
+crow-skills install crow-debug --agents claude --global --ref COMMIT_OU_TAG --yes
+crow-skills update --agents claude --global --fetch --ref origin/main --yes
+```
+
+A fonte em checkout deve ser um clone Git já existente. O padrão é o checkout que contém o CLI e `--ref HEAD`. Toda operação fixa a referência em SHA completo e lê os objetos desse commit, sem checkout e sem arquivos não commitados. Na distribuição npm, o padrão é o snapshot incluído, verificado por hashes e associado a esse SHA; outras refs/fetch exigem `--source` apontando para clone Git. O CLI não cria clones, worktrees ou repos temporários.
+
+`--fetch` busca `origin` somente quando solicitado, usando credenciais Git externas; não atualiza o checkout. É incompatível com `--dry-run`. Sem fetch, uma ref remota pode estar desatualizada. Git replace-objects e hooks não são usados para interpretar a fonte; erros de Git não imprimem stderr que possa conter credenciais. URL arbitrária/credencial não é argumento suportado de `--source`.
+
+Atualização é explícita. `update` sem nomes atualiza apenas instalações gerenciadas nos destinos selecionados; não instala o catálogo inteiro. A origem deve corresponder à registrada. Mudança intencional de origem requer install/revisão explícita, não troca silenciosa durante update.
+
+No npm, primeiro atualize o pacote npm e então execute o update das skills, ou escolha uma fonte Git explicitamente. Com npx, o caminho de cache pode mudar entre versões; nesse caso, use install explícito para revisar/registrar a nova origem em vez de contornar source_mismatch.
+
+## Estado, conflitos e recuperação
+
+```sh
+crow-skills status --agents claude,codex --global
+crow-skills doctor --agents claude,codex --global --json
+crow-skills uninstall crow-debug --agents claude --global --yes
+crow-skills rollback --transaction ID_RETORNADO --dry-run
+crow-skills rollback --transaction ID_RETORNADO --yes
+crow-skills recover --dry-run
+crow-skills recover --yes
+```
+
+- Manifestos/locks/journals ficam sob `~/.local/state/crow-skills/`, separados da descoberta de skills. Não se escreve `manifest.json` dentro de `.claude/skills`.
+- Staging e backups ficam no diretório reservado `.crow-skills/` ao lado da raiz de skills, na mesma filesystem para permitir renames, nunca dentro dela. Backups são privados e retidos; não há expiração automática nesta versão.
+- Todos os destinos passam por preflight antes de aplicar. Renames são atômicos por pasta; uma operação com múltiplos destinos não é um único rename atômico global. Erros comuns provocam restauração; interrupções deixam journal recuperável, bloqueando novas mutações até `recover`.
+- `recover` restaura o estado anterior, não tenta terminar silenciosamente a instalação. A própria restauração tem um estado pendente `restoring`, permitindo retomada se também for interrompida. Confere arquivos/backup antes de substituir. Se houver edições após a interrupção, recusa e conserva os dados para resolução manual.
+- `rollback` funciona sobre uma transação concluída sem alterações posteriores no estado/artefatos afetados. Uma transação antiga não sobrescreve uma nova.
+- Um destino não gerenciado exige `--replace` em install. Edições locais, arquivos extras ou ausência de pacote gerenciado bloqueiam update/uninstall. `--overwrite-modified` é autorização explícita para preservar backup e substituir/remover o pacote afetado.
+- Uninstall só remove nomes gerenciados. Sem nomes exige `--all` explícito. Não elimina skills de terceiros nem diretórios alheios.
+- Symlinks nos destinos/estado, recursos com travessia, submódulos, symlinks de fonte e arquivos especiais são recusados. Use caminhos físicos. Esta versão não oferece instalação por symlink.
+
+Transações protegem contra falhas comuns/interrupção de processo, não contra toda falha de hardware/filesystem. Locks coordenam processos deste CLI no mesmo perfil, não um processo hostil ou editor concorrente com as mesmas permissões do usuário. Não edite a instalação enquanto a operação estiver aplicando.
+
+## Automação por agente
+
+```sh
+crow-skills install crow-behaviour --agents claude,codex --global --non-interactive --yes --json
+```
+
+Flags comuns funcionam antes ou depois do subcomando. `--json` implica ausência de prompts. Mutações não interativas exigem `--yes`; caso contrário, retornam erro sem instalar. `--dry-run` faz preview sem gravar estado nem instalar; ele não é autorização para aplicar depois sem nova checagem.
+
+Envelope stdout estável:
+
+```json
+{"schema_version":1,"ok":true,"command":"install","data":{"applied":true}}
+```
+
+Erros retornam `ok:false` e `error.code/message`. Saídas reais incluem alterações, SHA, transação e `activation_verified:false`; o exemplo acima abrevia esses campos. Exit codes: 0 sucesso/preview, 1 conflito/falha operacional, 2 uso inválido, 130 interrupção. Doctor retorna `healthy:false` para instalações alteradas/ausentes/inseguras ou recuperação pendente; o agente deve verificar esse campo, não apenas o exit code.
+
+`--home PATH` seleciona um perfil isolado para testes/ambientes alternativos, incluindo estado e destinos globais. Não é sandbox: `--dest` e `--project` continuam sendo caminhos explícitos fora desse perfil, se fornecidos.
+
+## Adaptadores e descoberta
+
+| Adaptador | Usuário | Projeto |
+|---|---|---|
+| codex | `~/.agents/skills` | `.agents/skills` |
+| claude | `~/.claude/skills` | `.claude/skills` |
+| gemini | `~/.gemini/skills` | `.gemini/skills` |
+| devin | `~/.config/devin/skills` (ou XDG_CONFIG_HOME) | `.devin/skills` |
+| shared | `~/.agents/skills` | `.agents/skills` |
+
+Codex/shared são deduplicados quando apontam para o mesmo diretório. O diretório compartilhado também pode ser lido por outros hosts; não é isolamento entre agentes. `.codex/skills` é uma localização legada encontrada em ambientes existentes; o adaptador usa a localização moderna documentada. Para um destino legado específico, use `--dest` explicitamente.
+
+`agents` só verifica PATH e caminhos, sem iniciar agente/LLM. `status`/`doctor` conferem arquivos e estado de instalação, não provam carregamento, ativação, independência dos workers ou execução correta da skill. Gemini oferece `/skills reload`; para outros hosts, confira sua lista/reload ou reinicie a sessão conforme a versão. Nenhum hook ou system prompt é alterado para forçar uso.
+
+Fontes primárias consultadas em 2026-10-20: [Codex](https://learn.chatgpt.com/docs/build-skills#where-codex-loads-local-skills), [Claude](https://code.claude.com/docs/en/skills), [Gemini](https://geminicli.com/docs/cli/using-agent-skills/), [Devin](https://docs.devin.ai/cli/extensibility/skills/overview).

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@andespindola/crow-skills",
+  "version": "0.1.0",
+  "description": "Versioned, complementary agent skills with a protected multi-agent installer",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/andersonflima/crow-skills.git"
+  },
+  "bin": {
+    "crow-skills": "bin/npm-crow-skills.cjs"
+  },
+  "files": [
+    "bin/npm-crow-skills.cjs",
+    "crow_skills/*.py",
+    "catalog.json",
+    "skills/**",
+    "release.json",
+    "docs/cli.md",
+    "docs/cli-security.md",
+    "!**/__pycache__/**",
+    "!**/*.pyc"
+  ],
+  "scripts": {
+    "prepack": "python3 scripts/build_release.py",
+    "test": "python3 scripts/check.py && python3 -m unittest discover -s tests -v"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org/"
+  }
+}