@andespindola/crow-skills 0.1.0 → 0.3.0

package/README.md

@@ -25,7 +25,7 @@ Exemplos:
 
 ## Instalação e portabilidade
 
-O pacote de cada skill é somente sua pasta em `skills/`. O [CLI crow-skills](docs/cli.md) instala cópias completas e versionadas em agentes/escopos explícitos, com preview, saída JSON, detecção de conflitos e recuperação. Requer Python 3.10+; Git para fontes em clone, Node 18+ para o launcher npm; mutações em macOS/Linux. A distribuição npm privada `@andespindola/crow-skills` inclui um snapshot completo das skills, sem clone ou hooks que as instalem automaticamente.
+O pacote de cada skill é somente sua pasta em `skills/`. O [CLI crow-skills](docs/cli.md) instala cópias completas e versionadas em agentes/escopos explícitos, com preview, saída JSON, detecção de conflitos e recuperação. Requer Python 3.10+; Git para fontes em clone, Node 18+ para o launcher npm; mutações em macOS/Linux. A distribuição npm privada `@andespindola/crow-skills` inclui um snapshot completo das skills, sem clone ou hooks que as instalem automaticamente. Em `--global`, instalar a crow-behaviour também grava o guia aditivo do agente (claude, codex, gemini, devin) para usar as skills; `--no-guide` desliga.
 
 ```sh
 ./bin/crow-skills list

package/catalog.json

@@ -12,7 +12,7 @@
     {
       "name": "crow-behaviour",
       "title": "Atuação coordenada",
-      "description": "Aplique um modo de atuação orientado a orquestração, profundidade e verificação em tarefas substantivas. Decomponha, delegue com as capacidades reais do agente e sintetize evidências. Em conversa ou ajustes triviais, responda diretamente; não simule agentes nem altere permissões.",
+      "description": "Use PROATIVAMENTE, sem o usuário pedir, sempre que a tarefa for substantiva — multi-etapa, com exploração/decisões, mexendo em vários arquivos ou componentes, ou exigindo verificação antes de entregar (implementar uma feature, refatorar, depurar, auditar, revisar, migrar, pesquisar a fundo). Ao ativar: decomponha o trabalho, delegue com as capacidades reais do runtime, verifique de forma adversarial e sintetize evidências. NÃO ative em conversa, explicação curta ou ajuste trivial/local — nesses casos responda direto. Não simule agentes nem altere permissões.",
       "role": "coordinator",
       "owns": "execution-ledger",
       "next": []

package/crow_skills/__init__.py

@@ -1,3 +1,3 @@
 """Portable, local-first installer for the crow-skills catalogue."""
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"

package/crow_skills/cli.py

@@ -1,16 +1,18 @@
 """Human and agent CLI. Noninteractive mutations require explicit --yes."""
 import argparse
 import json
+import os
 from pathlib import Path
 import sys
 
 from . import __version__
+from . import guide
 from .agents import AGENTS, destinations, inventory
 from .source import CrowError, Source, valid_name
 from .storage import Store, checked
 
 DEFAULT_SOURCE = Path(__file__).resolve().parents[1]
-MUTATIONS = {"install", "update", "uninstall", "rollback", "recover"}
+MUTATIONS = {"install", "update", "uninstall", "rollback", "recover", "guide"}
 
 
 class Parser(argparse.ArgumentParser):
@@ -51,6 +53,11 @@ def parser():
             child.add_argument("--replace", action="store_true", help="Autorizar substituição com backup de pacote não gerenciado")
             child.add_argument("--with-handoffs", action="store_true", help="Incluir apenas handoffs diretos opcionais do catálogo")
         child.add_argument("--overwrite-modified", action="store_true", help="Autorizar backup e substituição/remoção de edições locais")
+        child.add_argument("--no-guide", action="store_true", help="Não aplicar/atualizar/remover o guia do agente (--global)")
+    child = sub.add_parser("guide", parents=[common], help="Instruções gerenciadas para o agente usar as skills instaladas")
+    child.add_argument("action", choices=("install", "status", "uninstall"))
+    child.add_argument("--replace", action="store_true", help="Autorizar backup e substituição de conteúdo não gerenciado no caminho do guia")
+    child.add_argument("--overwrite-modified", action="store_true", help="Autorizar backup e substituição/remoção de guia editado")
     for name in ("rollback", "recover"):
         child = sub.add_parser(name, parents=[common])
         child.add_argument("--transaction", required=name == "rollback")
@@ -113,6 +120,119 @@ def relationship_view(source, name, store, targets):
             "meaning": "Handoffs e overlays são complementos opcionais, não dependências nem ordem automática de execução."}
 
 
+def guide_command(args, home, store, interactive):
+    if getattr(args, "project", None) or getattr(args, "dest", None):
+        raise CrowError("unsupported_guide", "Guias só têm mecanismo nativo verificado no escopo do usuário; use --global. "
+                        "Escopo de projeto e --dest não são suportados.")
+    agents = getattr(args, "agents", None)
+    if args.action == "status":
+        rows = guide.status(store, home, guide.select(agents) if agents else list(guide.MECHANISMS))
+        return {"guides": rows, "pending_transactions": [t["id"] for t in store.pending()], "activation_verified": False}
+    if not getattr(args, "global_scope", False):
+        raise CrowError("usage", "guide " + args.action + " exige --global explícito (único escopo verificado).")
+    if not agents and interactive:
+        agents = prompt("Agentes separados por vírgula (" + ",".join(guide.MECHANISMS) + "):")
+    selected = guide.select(agents)
+    source = None
+    if args.action == "install":
+        source = Source(getattr(args, "source", DEFAULT_SOURCE), getattr(args, "ref", "HEAD"), getattr(args, "fetch", False))
+    plan = guide.plan(store, args.action, selected, home, source, args.replace, args.overwrite_modified)
+    summary = {"changes": plan["changes"], "revision": source.revision if source else None,
+               "additive": True, "activation_verified": False}
+    if getattr(args, "dry_run", False):
+        summary["preview"] = plan["previews"]
+    if plan["items"]:
+        authorize(args, interactive, summary)
+    txid = None if getattr(args, "dry_run", False) else guide.apply(store, plan, home)
+    return {**summary, "transaction": txid, "dry_run": getattr(args, "dry_run", False),
+            "applied": not getattr(args, "dry_run", False),
+            "reload_hint": ("Somente preview; nada gravado." if getattr(args, "dry_run", False) else
+                            "Abra uma sessão nova do CLI para carregar as instruções; o carregamento não é verificado por este comando.")}
+
+
+GUIDE_HINT = (" O guia do agente é aplicado junto com as skills em --global; revise e use --replace ou "
+              "--overwrite-modified conforme o caso, ou --no-guide para não alterar o guia. Nada foi alterado.")
+
+
+def guide_sync(args, home, store, command, targets, plan, source):
+    """Plan the guide changes that follow a skills plan, before anything is written.
+
+    Returns (report, guide plan or None). A refused guide raises, so the command
+    fails as a whole with no partial state.
+    """
+    report = {"changes": [], "skipped": [], "transaction": None}
+    selected = [a for t in targets for a in t["agents"]]
+    if getattr(args, "no_guide", False):
+        report["skipped"] = [{"agent": a, "reason": "--no-guide: guia não alterado."} for a in selected]
+        return report, None
+    if getattr(args, "project", None) or getattr(args, "dest", None):
+        report["skipped"] = [{"agent": a, "reason": "Sem mecanismo de guia verificado fora do escopo do usuário; "
+                              "guia aplicado só com --global."} for a in selected]
+        return report, None
+    for agent in selected:
+        if agent not in guide.MECHANISMS:
+            report["skipped"].append({"agent": agent, "reason": guide.UNVERIFIED.get(agent, "Sem mecanismo de guia verificado.")})
+    state = guide.load_state(store)
+    touched = {}
+    for item in plan["items"]:
+        added, removed = touched.setdefault(os.path.abspath(item["target"]), (set(), set()))
+        (removed if item["new"] is None else added).add(item["name"])
+    actions, skills_after = {}, {}
+    for agent, mech in guide.MECHANISMS.items():
+        path = os.path.abspath(destinations(agent, home)[0]["path"])
+        record = state["guides"].get(agent)
+        if agent not in selected and not (record and path in touched):
+            continue
+        added, removed = touched.get(path, (set(), set()))
+        after = sorted((set(guide.managed_skills(agent, home, store)) | added) - removed)
+        if mech["kind"] == "toml" and guide.tomllib is None:
+            report["skipped"].append({"agent": agent, "reason": "Python 3.11+ (tomllib) é necessário para editar config.toml; guia não alterado."})
+        elif "crow-behaviour" in after and (record or command != "uninstall"):
+            actions[agent], skills_after[agent] = "install", after
+        elif record and "crow-behaviour" in removed:
+            actions[agent] = "uninstall"
+        elif record and "crow-behaviour" not in after:
+            report["skipped"].append({"agent": agent, "reason": "crow-behaviour ausente; guia mantido. Confira crow-skills guide status."})
+        elif not record and command != "uninstall":
+            report["skipped"].append({"agent": agent, "reason": "crow-behaviour não ficará instalada para " + agent + "; guia não aplicado."})
+    if not actions:
+        return report, None
+    if source is None and "install" in actions.values():
+        source = Source(getattr(args, "source", DEFAULT_SOURCE), getattr(args, "ref", "HEAD"))
+    try:
+        gplan = guide.plan(store, actions, list(actions), home, source, getattr(args, "replace", False),
+                           args.overwrite_modified, skills_after)
+    except CrowError as exc:
+        raise CrowError(exc.code, str(exc) + GUIDE_HINT) from exc
+    report["changes"] = gplan["changes"]
+    report["revision"] = source.revision if source else None
+    if getattr(args, "dry_run", False):
+        report["preview"] = gplan["previews"]
+    return report, gplan
+
+
+def apply_chain(store, plan, gplan, home):
+    """Skills first, then the guide; a failed guide rolls the skills back."""
+    txid = store.apply(plan)
+    if gplan is None:
+        return txid, None
+    try:
+        return txid, guide.apply(store, gplan, home, linked=txid)
+    except (Exception, KeyboardInterrupt) as exc:
+        if txid:
+            try:
+                store.rollback(txid)
+            except CrowError as inner:
+                raise CrowError("partial_state", "Guia falhou e as skills da transação " + txid + " não puderam ser desfeitas (" +
+                                str(inner) + "). Execute crow-skills recover; ele desfaz o guia e as skills ligadas.") from exc
+        raise
+
+
+def linked_guides(store, txid):
+    """Committed guide transactions that completed the given skills transaction."""
+    return [t["id"] for t in store.transactions() if t.get("kind") == "guide" and t.get("linked") == txid and t["phase"] == "committed"]
+
+
 def run(args):
     if args.version:
         return {"version": __version__}
@@ -121,18 +241,24 @@ def run(args):
     home = checked(getattr(args, "home", Path.home()))
     store = Store(home)
     interactive = sys.stdin.isatty() and not getattr(args, "non_interactive", False) and not getattr(args, "json", False)
-    if getattr(args, "fetch", False) and (getattr(args, "dry_run", False) or args.command not in ("install", "update", "list", "info", "related")):
+    if getattr(args, "fetch", False) and (getattr(args, "dry_run", False) or args.command not in ("install", "update", "list", "info", "related", "guide")):
         raise CrowError("usage", "--fetch requer um comando com fonte e não pode ser combinado com --dry-run.")
     if args.command == "agents":
         return {"agents": inventory(home), "note": "Detecção por PATH/diretórios não comprova carregamento da skill."}
+    if args.command == "guide":
+        return guide_command(args, home, store, interactive)
     if args.command in ("status", "doctor"):
         targets = scope(args, home, read=True)
         rows = store.status(targets)
         pending = [t["id"] for t in store.pending()]
-        result = {"installations": rows, "pending_transactions": pending,
+        global_view = not (getattr(args, "project", None) or getattr(args, "dest", None))
+        names = [n.strip() for n in getattr(args, "agents", "").split(",")] if getattr(args, "agents", None) else list(guide.MECHANISMS)
+        guides = guide.status(store, home, names) if global_view else []
+        result = {"installations": rows, "guides": guides, "pending_transactions": pending,
                   "activation_verified": False, "reload_hint": "Peça ao host para recarregar/listar skills; reinicie a sessão se necessário."}
         if args.command == "doctor":
-            result.update(healthy=not pending and all(r["status"] not in ("modified", "missing", "unsafe") for r in rows), agents=inventory(home))
+            result.update(healthy=not pending and all(r["status"] not in ("modified", "missing", "unsafe") for r in rows + guides),
+                          agents=inventory(home))
         return result
     if args.command in ("rollback", "recover"):
         if any(getattr(args, k, None) for k in ("agents", "dest", "project", "global_scope")):
@@ -142,12 +268,28 @@ def run(args):
         expected = ("prepared", "restoring") if args.command == "recover" else ("committed",)
         if any(t["phase"] not in expected for t in transactions):
             raise CrowError("invalid_transaction", "Transação incompatível com a operação.")
-        summary = {"transactions": [{"id": t["id"], "targets": list(t["before"])} for t in transactions]}
+        # install/update/uninstall chain a skills transaction and a guide transaction
+        # (journal field "linked"). Undo both together: the guide first on rollback;
+        # on recover, an interrupted guide also undoes the skills it completed.
+        follow = []
+        if args.command == "rollback":
+            before_ids = [g for txid in ids for g in linked_guides(store, txid)]
+            ids, transactions = before_ids + ids, [store.journal(t) for t in before_ids] + transactions
+        else:
+            follow = [t["linked"] for t in transactions if t.get("linked")
+                      and store.journal(t["linked"])["phase"] == "committed"]
+        view = lambda t: {"id": t["id"], "kind": t.get("kind", "skills"),
+                          "targets": [i["path"] for i in t["items"]] if t.get("kind") == "guide" else list(t["before"])}
+        summary = {"transactions": [view(t) for t in transactions]}
+        if follow:
+            summary["then_rollback"] = [view(store.journal(t)) for t in follow]
         if transactions:
             authorize(args, interactive, summary)
         if not getattr(args, "dry_run", False):
             for txid in ids:
                 store.rollback(txid, recovery=args.command == "recover")
+            for txid in follow:
+                store.rollback(txid)
         return {**summary, "dry_run": getattr(args, "dry_run", False), "applied": not getattr(args, "dry_run", False)}
     source = None
     if args.command != "uninstall":
@@ -185,12 +327,15 @@ def run(args):
             source.require(name)
             names.extend(n for n in source.catalog[name]["next"] if n not in names)
     plan = store.plan(args.command, names, targets, source, getattr(args, "replace", False), args.overwrite_modified)
+    guides, gplan = guide_sync(args, home, store, args.command, targets, plan, source)
     summary = {"changes": plan["changes"], "revision": source.revision if source else None,
                "relationships": {n: source.related(n) for n in names} if source else {},
-               "handoffs_are_optional": True, "activation_verified": False}
-    if plan["items"]:
+               "guides": guides, "handoffs_are_optional": True, "activation_verified": False}
+    if plan["items"] or (gplan and gplan["items"]):
         authorize(args, interactive, summary)
-    txid = None if getattr(args, "dry_run", False) else store.apply(plan)
+    txid = None
+    if not getattr(args, "dry_run", False):
+        txid, guides["transaction"] = apply_chain(store, plan, gplan, home)
     return {**summary, "transaction": txid, "dry_run": getattr(args, "dry_run", False),
             "applied": not getattr(args, "dry_run", False),
             "reload_hint": ("Somente preview; nada instalado." if getattr(args, "dry_run", False) else

package/crow_skills/guide.py

@@ -0,0 +1,585 @@
+"""Managed, additive agent guidance in each CLI's native always-loaded location.
+
+Only mechanisms proven with a sentinel in a fresh interactive session of the
+CLI are supported, all of them at user scope and all additive: the CLI keeps
+loading its existing base/shared prompt next to this guide. Shared prompts
+(for example a ~/.claude/CLAUDE.md symlink) and their targets are never
+written, and mechanisms that replace a base prompt are not used.
+
+Ownership: a whole file that this CLI creates (claude, gemini, devin) or a
+single marked block holding one top-level key in a config file (codex). The
+rest of a shared config file is preserved byte for byte.
+"""
+from copy import deepcopy
+from datetime import datetime, timezone
+import hashlib
+import os
+from pathlib import Path
+import re
+import stat
+import uuid
+
+try:  # Python 3.11+; required only to verify config.toml edits.
+    import tomllib
+except ImportError:  # pragma: no cover - CI and supported hosts have 3.11+
+    tomllib = None
+
+from .agents import destinations
+from .source import CrowError, SHA
+from .storage import atomic_json, checked, private_dir, read_json
+
+HEADER = "<!-- Gerenciado por crow-skills guide. Não edite; use crow-skills guide install/uninstall. -->"
+BEGIN = "# >>> crow-skills guide (gerenciado; use crow-skills guide uninstall) >>>"
+END = "# <<< crow-skills guide <<<"
+TOML_KEY = "developer_instructions"
+MAX_CONFIG = 4 * 1024 * 1024
+HEX = re.compile(r"[a-f0-9]{64}\Z")
+PRESERVED = re.compile(r"[a-f0-9]{32}/[a-z]+\.bak\Z")
+
+# path is relative to the user's home. All entries were verified on 2026-10-21
+# with a sentinel loaded in a fresh session alongside the existing base prompt.
+MECHANISMS = {
+    "claude": {"kind": "file", "path": ".claude/rules/crow-skills.md", "frontmatter": False,
+               "label": "Claude Code", "invoke": "/{name}",
+               "load": "use a ferramenta Skill com o nome da skill ou digite /nome"},
+    "codex": {"kind": "toml", "path": ".codex/config.toml", "label": "Codex CLI", "invoke": "${name}",
+              "load": "mencione $nome ou abra o SKILL.md dela pela lista de skills disponíveis"},
+    "gemini": {"kind": "file", "path": ".gemini/config/rules/crow-skills.md", "frontmatter": True,
+               "label": "Antigravity CLI, agy", "invoke": "/{name}",
+               "load": "use a ferramenta de skills do agy ou digite /nome"},
+    "devin": {"kind": "file", "path": ".devin/rules/crow-skills.md", "frontmatter": True,
+              "label": "Devin CLI", "invoke": "/devin:{name}",
+              "load": "use a ferramenta de skills do Devin ou digite /devin:nome"},
+}
+UNVERIFIED = {
+    "shared": "shared é um diretório de skills, não um CLI; não há onde gravar instruções.",
+}
+# Shared prompt files (often symlinks into ~/.config/uniflow) and their targets.
+PROTECTED = (".claude/CLAUDE.md", ".codex/AGENTS.md", ".codex/AGENTS.override.md", ".gemini/GEMINI.md",
+             ".config/devin/CLAUDE.md", ".config/devin/AGENTS.md", ".config/uniflow")
+
+
+def sha(data):
+    if data is None:
+        return None
+    if isinstance(data, str):
+        data = data.encode("utf-8")
+    return hashlib.sha256(data).hexdigest()
+
+
+def now():
+    return datetime.now(timezone.utc).isoformat()
+
+
+def select(agents):
+    if not agents:
+        raise CrowError("usage", "Selecione --agents; não há instalação implícita em todos os agentes.")
+    names = agents.split(",") if isinstance(agents, str) else list(agents)
+    result = []
+    for name in (n.strip() for n in names):
+        if name in UNVERIFIED:
+            raise CrowError("unsupported_guide", "Sem mecanismo verificado para " + name + ": " + UNVERIFIED[name])
+        if name not in MECHANISMS:
+            raise CrowError("unsupported_guide", "Sem mecanismo nativo verificado para '" + name +
+                            "'. Suportados: " + ",".join(MECHANISMS) + ".")
+        if name not in result:
+            result.append(name)
+    return result
+
+
+def protect(path, home):
+    """Refuse symlinked components, shared prompts and anything inside their targets."""
+    path = checked(path)
+    for rel in PROTECTED:
+        guard = Path(os.path.abspath(home / rel))
+        guards = {guard}
+        if os.path.lexists(guard):
+            guards.add(Path(os.path.realpath(guard)))
+        for item in guards:
+            if path == item or path.is_relative_to(item):
+                raise CrowError("protected_path", "Arquivo de prompt compartilhado (ou alvo dele) não é gravado: " + str(path))
+    return path
+
+
+def read_regular(path):
+    if not os.path.lexists(path):
+        return None
+    info = path.lstat()
+    if not stat.S_ISREG(info.st_mode):
+        raise CrowError("unsafe_destination", "Destino do guia não é arquivo regular: " + str(path))
+    if info.st_nlink > 1:
+        raise CrowError("unsafe_destination", "Destino do guia tem hard links; recusado: " + str(path))
+    if info.st_size > MAX_CONFIG:
+        raise CrowError("unsafe_destination", "Destino do guia excede o limite de leitura segura.")
+    return path.read_bytes()
+
+
+def write_atomic(path, data, mode):
+    temp = path.parent / ("." + path.name + ".crow-" + uuid.uuid4().hex)
+    try:
+        fd = os.open(temp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0), 0o600)
+        with os.fdopen(fd, "wb") as f:
+            f.write(data)
+            f.flush()
+            os.fsync(f.fileno())
+        os.chmod(temp, mode)
+        os.replace(temp, path)
+        fd = os.open(path.parent, os.O_RDONLY)
+        try:
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+    finally:
+        if os.path.lexists(temp):
+            temp.unlink()
+
+
+# --- content -----------------------------------------------------------------
+
+def clean(text):
+    return "".join(c for c in str(text) if c.isprintable()).replace("'''", "'").replace("-->", "->")
+
+
+def managed_skills(agent, home, store):
+    """crow-* packages this CLI manages for the agent (edited copies still count)."""
+    target = destinations(agent, home)[0]
+    return sorted(r["name"] for r in store.status([target], ()) if r["status"] in ("installed", "modified"))
+
+
+def present_skills(agent, home, store, catalog):
+    return [n for n in managed_skills(agent, home, store) if n in catalog]
+
+
+def render_body(agent, catalog, revision, skills):
+    mech = MECHANISMS[agent]
+    invoke = mech["invoke"].format
+    specialists = [n for n in skills if n != "crow-behaviour"]
+    example = " (por exemplo, " + invoke(name=specialists[0]) + ")" if specialists else ""
+    lines = [
+        "# Crow skills neste agente (" + mech["label"] + ")",
+        "",
+        "Gerado por crow-skills guide a partir do catálogo " + revision[:12] + ". Complementa as instruções do usuário e do projeto; havendo conflito, elas prevalecem.",
+        "",
+        "## crow-behaviour: quando aplicar",
+        "- Tarefa substantiva (várias etapas ou partes, exploração e decisões, mudanças em vários arquivos ou componentes, ou entrega que exige verificação): carregue a skill crow-behaviour ANTES de começar, por iniciativa própria, sem esperar pedido. Para carregar, " + mech["load"] + "; por exemplo, " + invoke(name="crow-behaviour") + ". Siga-a até a entrega.",
+        "- Vale também quando a entrega é só um plano, um diagnóstico ou uma revisão, ou quando não há código no diretório: depurar, auditar, investigar, migrar ou planejar uma mudança com várias etapas continua sendo tarefa substantiva.",
+        "- Conversa, pergunta factual curta ou ajuste trivial e local: responda direto, sem carregá-la.",
+        "",
+        "## Skills especialistas",
+    ]
+    lines += [
+        "- Antes de executar, consulte a lista de skills disponíveis neste agente e carregue pelo nome a especialista cujo domínio corresponde à tarefa" + example + ". Se a tarefa cruzar domínios, combine as pertinentes; a crow-behaviour coordena, a especialista executa.",
+        "- Handoffs entre skills são sugestões opcionais, não dependências; não carregue a biblioteca inteira.",
+        "- Se uma skill não estiver disponível no host, diga isso e siga sem ela; nunca simule o conteúdo de uma skill que não carregou.",
+        "",
+        "## Crow skills gerenciadas neste agente",
+    ]
+    for name in skills:
+        lines.append("- " + invoke(name=name) + " — " + clean(catalog[name].get("title") or catalog[name]["owns"]))
+    return "\n".join(lines) + "\n"
+
+
+def managed_content(agent, body):
+    """Exact bytes owned by this CLI: a whole file, or one marked TOML block."""
+    mech = MECHANISMS[agent]
+    if mech["kind"] == "toml":
+        if "'''" in body or any(not (c.isprintable() or c in "\n\t") for c in body):
+            raise CrowError("invalid_guide", "Conteúdo do guia não cabe numa string TOML literal.")
+        return BEGIN + "\n" + TOML_KEY + " = '''\n" + body + "'''\n" + END + "\n"
+    front = "---\ntrigger: always_on\n---\n\n" if mech["frontmatter"] else ""
+    return front + HEADER + "\n\n" + body
+
+
+# --- codex config.toml block ------------------------------------------------------
+
+def parse_toml(text):
+    if tomllib is None:
+        raise CrowError("unsupported_platform", "Python 3.11+ (tomllib) é necessário para editar config.toml com verificação.")
+    try:
+        return tomllib.loads(text)
+    except tomllib.TOMLDecodeError as exc:
+        raise CrowError("invalid_config", "config.toml não é TOML válido; nada alterado.") from exc
+
+
+def find_block(text):
+    """Return (start, end) offsets of the managed block, or None."""
+    begins = [m.start() for m in re.finditer(r"(?m)^" + re.escape(BEGIN) + r"\n", text)]
+    ends = [m.end() for m in re.finditer(r"(?m)^" + re.escape(END) + r"\n", text)]
+    if not begins and not ends:
+        return None
+    if len(begins) != 1 or len(ends) != 1 or ends[0] <= begins[0]:
+        raise CrowError("guide_corrupted", "Marcadores do bloco crow-skills em config.toml estão incompletos ou duplicados; revise manualmente.")
+    return begins[0], ends[0]
+
+
+def decode(data):
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise CrowError("invalid_config", "config.toml não é UTF-8; nada alterado.") from exc
+
+
+def toml_block(data):
+    if data is None:
+        return None
+    text = decode(data)
+    span = find_block(text)
+    return text[span[0]:span[1]] if span else None
+
+
+def toml_compose(old_bytes, old_block, new_block, body=None):
+    """Remove the existing managed block and prepend the new one; verify parse."""
+    text = decode(old_bytes) if old_bytes is not None else ""
+    if old_block is not None:
+        start, end = find_block(text)
+        text = text[:start] + text[end:]
+    base = parse_toml(text)
+    if TOML_KEY in base:
+        raise CrowError("unmanaged_conflict", "config.toml já define " + TOML_KEY + " fora do bloco gerenciado; remova ou mova antes. Nada alterado.")
+    result = (new_block or "") + text
+    parsed = parse_toml(result)
+    expected = dict(base)
+    if new_block is not None:
+        expected[TOML_KEY] = body if body is not None else parse_toml(new_block)[TOML_KEY]
+    if parsed != expected:
+        raise CrowError("invalid_config", "Edição do config.toml não preservou o restante do arquivo; nada alterado.")
+    return result.encode("utf-8")
+
+
+# --- state ----------------------------------------------------------------------
+
+def state_path(store):
+    return store.root / "guides" / "state.json"
+
+
+def validate_state(data):
+    try:
+        if data["schema_version"] != 1 or not isinstance(data["guides"], dict):
+            raise ValueError("schema")
+        for agent, record in data["guides"].items():
+            if agent not in MECHANISMS or record["mechanism"] != MECHANISMS[agent]["kind"]:
+                raise ValueError("agent")
+            if (not isinstance(record["path"], str) or not HEX.fullmatch(record["sha256"]) or
+                    not SHA.fullmatch(record["revision"]) or not isinstance(record["skills"], list) or
+                    not all(isinstance(d, str) for d in record.get("created_dirs", [])) or
+                    not isinstance(record.get("created_file", False), bool)):
+                raise ValueError("record")
+            preserved = record.get("preserved")
+            if preserved is not None and (not HEX.fullmatch(preserved["sha256"]) or
+                                          not PRESERVED.fullmatch(preserved.get("backup") or "")):
+                raise ValueError("preserved")
+    except (KeyError, TypeError, ValueError) as exc:
+        raise CrowError("invalid_state", "Estado de guias inválido; nenhuma alteração aplicada.") from exc
+    return data
+
+
+def load_state(store):
+    path = checked(state_path(store))
+    if not path.exists():
+        return {"schema_version": 1, "guides": {}}
+    return validate_state(read_json(path))
+
+
+def validate_journal(data, txid):
+    try:
+        if data["id"] != txid or data["phase"] not in ("prepared", "restoring", "committed", "rolled_back"):
+            raise ValueError("phase")
+        validate_state(data["before"])
+        validate_state(data["after"])
+        if "linked" in data and not re.fullmatch(r"[a-f0-9]{32}", data["linked"] or ""):
+            raise ValueError("linked")
+        if not isinstance(data["items"], list) or not data["items"]:
+            raise ValueError("items")
+        for item in data["items"]:
+            if item["agent"] not in MECHANISMS or item["kind"] != MECHANISMS[item["agent"]]["kind"]:
+                raise ValueError("agent")
+            if str(checked(item["path"])) != item["path"]:
+                raise ValueError("path")
+            for key in ("old_sha", "new_sha"):
+                if item[key] is not None and not HEX.fullmatch(item[key]):
+                    raise ValueError("sha")
+            for key in ("old_block", "new_block"):
+                if item[key] is not None and not isinstance(item[key], str):
+                    raise ValueError("block")
+            if item["backup"] is not None and not re.fullmatch(r"[a-z]+\.bak", item["backup"]):
+                raise ValueError("backup")
+            item.setdefault("removed_dirs", [])
+            for key in ("created_dirs", "removed_dirs"):
+                if not isinstance(item[key], list) or not all(isinstance(d, str) and str(checked(d)) == d for d in item[key]):
+                    raise ValueError("dirs")
+    except (KeyError, TypeError, ValueError) as exc:
+        raise CrowError("invalid_transaction", "Registro transacional de guia inconsistente; recuperação recusada.") from exc
+    return data
+
+
+# --- plan / apply / restore -----------------------------------------------------------
+
+def current(agent, home):
+    """(path, file bytes, managed bytes-or-text) for an agent; never follows links."""
+    mech = MECHANISMS[agent]
+    path = protect(home / mech["path"], home)
+    data = read_regular(path)
+    if mech["kind"] == "toml":
+        return path, data, toml_block(data)
+    return path, data, data.decode("utf-8", "replace") if data is not None else None
+
+
+def plan(store, action, agents, home, source=None, replace=False, overwrite=False, skills_after=None):
+    """Plan guide changes. action is "install"/"uninstall" or a {agent: action} map.
+
+    skills_after maps an agent to the managed skills it will have once a pending
+    skills transaction applies; without it the current installation is used.
+    """
+    if store.pending():
+        raise CrowError("recovery_required", "Há uma transação interrompida. Execute recover antes de alterar instalações.")
+    actions = action if isinstance(action, dict) else {agent: action for agent in agents}
+    before = load_state(store)
+    after = deepcopy(before)
+    items, changes, payload, previews = [], [], {}, {}
+    for agent in agents:
+        action = actions[agent]
+        mech = MECHANISMS[agent]
+        path, data, managed = current(agent, home)
+        record = before["guides"].get(agent)
+        if record and record["path"] != str(path):
+            raise CrowError("invalid_state", "Guia registrado em outro caminho para " + agent + "; revise o estado.")
+        managed_sha = sha(managed)
+        if action == "uninstall":
+            if not record:
+                raise CrowError("not_managed", "Guia não gerenciado para " + agent + "; nada removido.")
+            if managed_sha != record["sha256"] and not overwrite:
+                raise CrowError("local_changes", "Guia de " + agent + " alterado/ausente. Revise; --overwrite-modified autoriza backup e remoção.")
+            new_managed, body, skills = None, None, None
+            original = preserved_original(store, record)
+        else:
+            if "crow-behaviour" not in source.catalog:
+                raise CrowError("invalid_catalog", "Catálogo sem crow-behaviour.")
+            if skills_after is not None and agent in skills_after:
+                skills = [n for n in skills_after[agent] if n in source.catalog]
+            else:
+                skills = present_skills(agent, home, store, source.catalog)
+            if "crow-behaviour" not in skills:
+                raise CrowError("guide_requires_skill", "crow-behaviour não está instalada para " + agent +
+                                "; instale antes: crow-skills install crow-behaviour --agents " + agent + " --global --yes")
+            body = render_body(agent, source.catalog, source.revision, skills)
+            new_managed = managed_content(agent, body)
+            previews[agent] = new_managed
+            if record and managed_sha == sha(new_managed):
+                after["guides"][agent].update(revision=source.revision, skills=skills)
+                changes.append({"agent": agent, "path": str(path), "mechanism": mech["kind"], "action": "unchanged"})
+                continue
+            if record and managed_sha != record["sha256"] and not overwrite:
+                raise CrowError("local_changes", "Guia de " + agent + " alterado/ausente desde a instalação. Revise; --overwrite-modified autoriza backup e substituição.")
+            if not record and managed is not None and not replace:
+                raise CrowError("unmanaged_conflict", "Já existe conteúdo não gerenciado em " + str(path) + ". Revise; --replace autoriza backup e substituição.")
+        if mech["kind"] == "toml":
+            new_data = toml_compose(data, managed, new_managed, body)
+            if new_data == b"" and new_managed is None and record.get("created_file", False):
+                new_data = None  # This CLI created the file and only our block is left: remove it.
+        elif new_managed is not None:
+            new_data = new_managed.encode("utf-8")
+        else:
+            new_data = original  # Uninstall: put back what --replace displaced, or remove our file.
+        created = []
+        if new_data is not None:
+            parent = path.parent
+            while not parent.exists() and parent != home and home in parent.parents:
+                created.append(str(parent))
+                parent = parent.parent
+        mode = stat.S_IMODE(path.lstat().st_mode) if data is not None else (0o600 if mech["kind"] == "toml" else 0o644)
+        items.append({"agent": agent, "kind": mech["kind"], "path": str(path), "old_sha": sha(data), "new_sha": sha(new_data),
+                      "old_block": managed if mech["kind"] == "toml" else None,
+                      "new_block": new_managed if mech["kind"] == "toml" else None,
+                      "mode": mode, "backup": None, "created_dirs": created,
+                      "removed_dirs": record.get("created_dirs", []) if action == "uninstall" else []})
+        payload[agent] = (data, new_data)
+        if action == "uninstall":
+            after["guides"].pop(agent)
+            act = "remove"
+        else:
+            entry = {"path": str(path), "mechanism": mech["kind"], "sha256": sha(new_managed),
+                     "revision": source.revision, "skills": skills, "installed_at": now(),
+                     "created_dirs": created + (record.get("created_dirs", []) if record else [])}
+            if mech["kind"] == "toml":
+                entry["created_file"] = record.get("created_file", False) if record else data is None
+            if record and record.get("preserved"):
+                entry["preserved"] = record["preserved"]
+            elif not record and data is not None and mech["kind"] == "file":
+                entry["preserved"] = {"sha256": sha(data)}  # backup id is set by apply()
+            after["guides"][agent] = entry
+            act = "replace" if managed is not None else "install"
+        changes.append({"agent": agent, "path": str(path), "mechanism": mech["kind"], "action": act,
+                        "edits": "bloco " + TOML_KEY + " marcado" if mech["kind"] == "toml" else "arquivo próprio"})
+    return {"before": before, "after": after, "items": items, "payload": payload, "changes": changes, "previews": previews}
+
+
+def apply(store, plan_data, home, linked=None):
+    """Apply a guide plan; linked is the skills transaction this one completes."""
+    if not plan_data["items"]:
+        if plan_data["after"] != plan_data["before"]:
+            with store.lock():
+                if load_state(store) != plan_data["before"]:
+                    raise CrowError("changed_during_plan", "O estado mudou após o preview; execute novamente.")
+                atomic_json(state_path(store), plan_data["after"])
+        return None
+    with store.lock():
+        if store.pending():
+            raise CrowError("recovery_required", "Recuperação pendente; nenhuma alteração aplicada.")
+        if load_state(store) != plan_data["before"]:
+            raise CrowError("changed_during_plan", "O estado mudou após o preview; execute novamente.")
+        for item in plan_data["items"]:
+            if sha(read_regular(protect(Path(item["path"]), home))) != item["old_sha"]:
+                raise CrowError("changed_during_plan", "Um destino mudou após o preview; execute novamente.")
+        for item in plan_data["items"]:
+            # A skills transaction applied after planning may have created parents
+            # (for example ~/.claude); this transaction does not own those.
+            existing = [d for d in item["created_dirs"] if os.path.lexists(d)]
+            if existing:
+                item["created_dirs"] = [d for d in item["created_dirs"] if d not in existing]
+                entry = plan_data["after"]["guides"].get(item["agent"])
+                if entry is not None:
+                    entry["created_dirs"] = [d for d in entry["created_dirs"] if d not in existing]
+        txid = uuid.uuid4().hex
+        backups = private_dir(store.root / "guide-backups") / txid
+        backups = private_dir(backups)
+        for item in plan_data["items"]:
+            old, _ = plan_data["payload"][item["agent"]]
+            if old is not None:
+                item["backup"] = item["agent"] + ".bak"
+                write_atomic(backups / item["backup"], old, 0o600)
+                kept = plan_data["after"]["guides"].get(item["agent"], {}).get("preserved")
+                if kept is not None and "backup" not in kept:
+                    kept["backup"] = txid + "/" + item["backup"]
+        data = {"id": txid, "kind": "guide", "phase": "prepared", "created_at": now(),
+                "before": plan_data["before"], "after": plan_data["after"], "items": plan_data["items"]}
+        if linked:
+            data["linked"] = linked
+        journal = store.root / "transactions" / (txid + ".json")
+        atomic_json(journal, data)
+        try:
+            for item in plan_data["items"]:
+                path = protect(Path(item["path"]), home)
+                if sha(read_regular(path)) != item["old_sha"]:
+                    raise CrowError("changed_during_install", "Destino do guia alterado durante a instalação.")
+                _, new = plan_data["payload"][item["agent"]]
+                if new is None:
+                    if os.path.lexists(path):
+                        path.unlink()
+                    remove_empty(item["removed_dirs"])
+                else:
+                    for directory in reversed(item["created_dirs"]):
+                        os.mkdir(directory, 0o755)
+                    write_atomic(path, new, item["mode"])
+            atomic_json(state_path(store), plan_data["after"])
+            data["phase"] = "committed"
+            atomic_json(journal, data)
+        except (Exception, KeyboardInterrupt):
+            restore(store, data, home)
+            raise
+        return txid
+
+
+def restore(store, data, home):
+    """Return every guide to its pre-transaction content, refusing over later edits."""
+    state = load_state(store)
+    if state != data["before"] and state != data["after"]:
+        raise CrowError("recovery_conflict", "Estado de guias mudou após a transação; recuperação recusada.")
+    backups = store.root / "guide-backups" / data["id"]
+    operations = []
+    for item in reversed(data["items"]):
+        path = protect(Path(item["path"]), home)
+        now_data = read_regular(path)
+        now_sha = sha(now_data)
+        if now_sha == item["old_sha"]:
+            continue
+        old = None
+        if item["old_sha"] is not None:
+            old = read_regular(checked(backups / item["backup"]))
+            if sha(old) != item["old_sha"]:
+                raise CrowError("recovery_conflict", "Backup do guia ausente ou alterado; recuperação recusada.")
+        if now_sha == item["new_sha"]:
+            operations.append((path, old, item))
+        elif item["kind"] == "toml" and now_data is not None and toml_block(now_data) == item["new_block"]:
+            # Codex rewrote other parts of config.toml: undo only our block.
+            operations.append((path, toml_compose(now_data, item["new_block"], item["old_block"]), item))
+        else:
+            raise CrowError("recovery_conflict", "Guia de " + item["agent"] + " mudou após a transação; recuperação não sobrescreverá alterações.")
+    data["phase"] = "restoring"
+    atomic_json(store.root / "transactions" / (data["id"] + ".json"), data)
+    for path, content, item in operations:
+        if content is None:
+            if os.path.lexists(path):
+                path.unlink()
+        else:
+            for directory in reversed(item["removed_dirs"]):
+                if not os.path.lexists(directory):
+                    os.mkdir(directory, 0o755)
+            write_atomic(path, content, item["mode"])
+    for item in data["items"]:
+        remove_empty(item["created_dirs"])
+    atomic_json(state_path(store), data["before"])
+    data["phase"] = "rolled_back"
+    atomic_json(store.root / "transactions" / (data["id"] + ".json"), data)
+
+
+def preserved_original(store, record):
+    """Bytes that --replace displaced for this guide, verified against the state; None if nothing was displaced."""
+    kept = record.get("preserved")
+    if not kept:
+        return None
+    data = read_regular(checked(store.root / "guide-backups" / kept["backup"]))
+    if sha(data) != kept["sha256"]:
+        raise CrowError("recovery_conflict", "Backup do conteúdo original substituído por --replace está ausente ou alterado; nada removido.")
+    return data
+
+
+def remove_empty(directories):
+    """Remove directories this CLI created, deepest first, only while empty."""
+    for directory in directories:
+        try:
+            os.rmdir(checked(directory))
+        except OSError:
+            pass  # Not empty or already gone: never remove foreign content.
+
+
+def rollback(store, data, home, recovery=False):
+    if not recovery and load_state(store) != data["after"]:
+        raise CrowError("rollback_conflict", "Há mudanças posteriores nos guias; rollback antigo recusado.")
+    restore(store, data, home)
+
+
+# --- status ---------------------------------------------------------------------
+
+def status(store, home, agents):
+    state = load_state(store)
+    rows = []
+    for agent in agents:
+        if agent not in MECHANISMS:
+            continue
+        mech = MECHANISMS[agent]
+        record = state["guides"].get(agent)
+        row = {"agent": agent, "path": str(home / mech["path"]), "mechanism": mech["kind"],
+               "revision": record["revision"] if record else None, "activation_verified": False}
+        try:
+            path, data, managed = current(agent, home)
+            parsed = parse_toml(decode(data)) if mech["kind"] == "toml" and data is not None else {}
+            if record is None:
+                row["status"] = "unmanaged" if managed is not None or TOML_KEY in parsed else "absent"
+            elif managed is None:
+                row["status"] = "missing"
+            elif sha(managed) != record["sha256"]:
+                row["status"] = "modified"
+            elif mech["kind"] == "toml" and parsed.get(TOML_KEY) != parse_toml(managed).get(TOML_KEY):
+                row["status"] = "modified"
+                row["note"] = "Bloco gerenciado não está mais no nível superior do config.toml."
+            elif managed_skills(agent, home, store) != record["skills"]:
+                row["status"] = "outdated"
+                row["note"] = "Skills instaladas mudaram; execute crow-skills guide install para regenerar."
+            else:
+                row["status"] = "installed"
+        except CrowError as exc:
+            row["status"] = "unsafe"
+            row["note"] = str(exc)
+        rows.append(row)
+    return rows
+

package/crow_skills/storage.py

@@ -154,6 +154,9 @@ class Store:
         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"))
+        if isinstance(data, dict) and data.get("kind") == "guide":
+            from .guide import validate_journal
+            return validate_journal(data, txid)
         try:
             if data["id"] != txid or data["phase"] not in ("prepared", "restoring", "committed", "rolled_back"):
                 raise ValueError("phase")
@@ -356,6 +359,9 @@ class Store:
                 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 data.get("kind") == "guide":
+                from .guide import rollback
+                return rollback(self, data, self.home, recovery)
             if not recovery:
                 for target, state in data["after"].items():
                     if self.state(target) != state:

package/docs/cli-security.md

@@ -22,6 +22,8 @@ Checklist aplicável: autorização por escopo e flags (sim); validação de nom
 | 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 |
+| Guia de agente sobrescrevendo prompt compartilhado ou config alheia | Só mecanismos aditivos verificados; recusa de symlinks, hard links, prompts compartilhados e seus alvos; bloco TOML marcado validado por parse, chave alheia nunca editada; testes de symlink, hard link, chave estrangeira e remoção byte a byte |
+| Install/update aplicando o guia de forma parcial ou sobre conteúdo alheio | Guia planejado e conferido antes de gravar skills; recusa falha o comando inteiro sem estado parcial; falha do guia desfaz as skills; transações encadeadas (`linked`) com rollback/recover conjuntos; `--no-guide` explícito; mesmas proteções de Uniflow/symlink/hard link; testes de recusa, falha, interrupção e rollback |
 | 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.

package/docs/cli.md

@@ -1,6 +1,6 @@
-# crow-skills CLI 0.1.0
+# crow-skills CLI 0.3.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.
+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 o agente, não executa scripts das skills e não muda modelos, prompts base ou permissões. Instruções de uso das skills (o guia do agente, abaixo) são gravadas pelo comando `guide` e, por padrão, por `install`/`update`/`uninstall` em `--global` quando a crow-behaviour fica instalada para um agente com mecanismo verificado; `--no-guide` desliga isso.
 
 ## Executar
 
@@ -17,6 +17,8 @@ O launcher do checkout pode ser referenciado por um symlink em um diretório já
 
 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.
 
+A publicação é feita pelo workflow `.github/workflows/publish.yml` ao empurrar uma tag `vX.Y.Z` igual à `version` do `package.json` (ou por `workflow_dispatch` em `main`). Ele autentica por Trusted Publishing (OIDC), sem token npm em secret, e roda check, testes e o teste de instalação isolada antes de `npm publish`. O trusted publisher do pacote no npmjs.com deve apontar para `andersonflima/crow-skills` e `publish.yml`.
+
 Depois de a versão estar publicada e a conta estar autenticada com acesso:
 
 ```sh
@@ -29,7 +31,7 @@ Para testar/distribuir o arquivo local sem registry:
 
 ```sh
 npm pack
-npm install -g ./andespindola-crow-skills-0.1.0.tgz --ignore-scripts
+npm install -g ./andespindola-crow-skills-0.3.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.
@@ -49,6 +51,8 @@ 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`.
 
+Em `--global`, quando o resultado deixa a crow-behaviour instalada para claude, codex, gemini ou devin, o mesmo comando aplica ou regenera o guia desse agente (veja [Instruções para o agente](#instruções-para-o-agente-guide)); `--no-guide` desliga esse passo.
+
 `--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
@@ -96,6 +100,7 @@ crow-skills recover --yes
 - 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.
+- `install`/`update`/`uninstall` que também alteram o guia gravam duas transações encadeadas: skills e depois guia, com o journal do guia apontando a de skills (`linked`). As duas IDs saem no resultado (`transaction` e `guides.transaction`). Se o guia falhar, as skills dessa execução são desfeitas antes do erro. `rollback` da transação de skills desfaz primeiro o guia ligado; `rollback` da transação de guia desfaz só o guia. `recover` de um guia interrompido também desfaz as skills ligadas (`then_rollback` no preview). Uma interrupção exatamente entre as duas deixa as skills aplicadas e o guia `outdated`/`absent`, sem journal pendente: repita o comando ou faça rollback da transação de skills.
 - `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.
@@ -133,6 +138,43 @@ Erros retornam `ok:false` e `error.code/message`. Saídas reais incluem alteraç
 
 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.
+`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 base é alterado para forçar uso; o guia abaixo, aplicado por padrão em `--global` e desligável com `--no-guide`, é aditivo.
 
 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).
+
+## Instruções para o agente (guide)
+
+```sh
+crow-skills install crow-behaviour --agents claude,codex,gemini,devin --global --yes   # aplica o guia junto
+crow-skills install crow-behaviour --agents claude --global --no-guide --yes            # só a skill
+crow-skills guide install --agents claude,codex,gemini,devin --global --dry-run
+crow-skills guide install --agents claude,codex,gemini,devin --global --yes
+crow-skills guide status
+crow-skills guide uninstall --agents codex --global --yes
+```
+
+`guide` grava, no mecanismo nativo e sempre carregado de cada CLI, instruções curtas em pt-BR para o agente usar as skills instaladas: carregar a crow-behaviour por iniciativa própria antes de tarefas substantivas (várias etapas ou partes, decisões, vários arquivos, verificação), responder direto em conversa ou ajuste trivial, consultar a lista de skills disponíveis no agente (crow ou não) e carregar a especialista pertinente pelo nome. O conteúdo é gerado do catálogo e das skills gerenciadas pelo CLI naquele agente, com a forma de invocação dele. Exige a crow-behaviour instalada para o agente.
+
+Aplicação automática (padrão em `install`, `update` e `uninstall` com `--global`, desligada por `--no-guide`):
+
+- O guia é planejado junto com as skills, a partir do conjunto de skills que o agente terá depois do comando, e conferido antes de gravar qualquer coisa. Install/update que deixam a crow-behaviour instalada aplicam o guia ou o regeneram; mudança de outra skill gerenciada regenera um guia já instalado (também quando a mudança chega pelo diretório compartilhado `~/.agents/skills`, que é o do codex). Uninstall da crow-behaviour remove o guia, devolvendo o arquivo que `--replace` havia deslocado; uninstall de outra skill regenera o guia instalado e nunca cria um novo.
+- Recusa do guia (arquivo não gerenciado sem `--replace`, guia editado/ausente sem `--overwrite-modified`, chave `developer_instructions` alheia, symlink, hard link, prompt compartilhado ou Uniflow) falha o comando inteiro, com código do guia e sugestão de `--replace`, `--overwrite-modified` ou `--no-guide`, sem gravar skills nem guia. Em install/update, `--replace` e `--overwrite-modified` valem para skills e guia.
+- `shared`, `--project` e `--dest` não têm mecanismo: o comando segue e informa em `guides.skipped`. Sem Python 3.11+ (tomllib), o guia do codex também é pulado e informado.
+- `--dry-run` inclui `guides.changes` e `guides.preview` (conteúdo que seria gravado). A saída JSON traz `guides` com `changes`, `skipped`, `revision` e `transaction`.
+
+| Agente | Mecanismo (usuário) | Propriedade |
+|---|---|---|
+| claude | `~/.claude/rules/crow-skills.md` | arquivo próprio |
+| codex | chave `developer_instructions` no topo de `~/.codex/config.toml` | bloco marcado; o restante do arquivo fica intacto |
+| gemini (Antigravity `agy`) | `~/.gemini/config/rules/crow-skills.md`, `trigger: always_on` | arquivo próprio |
+| devin | `~/.devin/rules/crow-skills.md`, `trigger: always_on` | arquivo próprio |
+
+Cada mecanismo foi verificado em 2026-10-21 (Claude Code 2.1.304, Codex CLI 0.163.0, agy 1.4.3, Devin CLI 3000.11.92) com uma sentinela carregada numa sessão nova junto do prompt base já existente: os mecanismos são aditivos. Versões futuras dos CLIs podem mudar isso; confira abrindo uma sessão nova. O comando não inicia agentes e retorna `activation_verified:false`.
+
+- Só `--global` é suportado. No comando `guide`, `--project`, `--dest` e `shared` são recusados com `unsupported_guide`, porque não há mecanismo verificado.
+- Nunca grava em symlinks, em arquivos com hard links, em prompts compartilhados (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.gemini/GEMINI.md`, `~/.config/devin/CLAUDE.md`), em `~/.config/uniflow/` ou nos alvos desses links. Não usa mecanismos que substituem o prompt base (como `model_instructions_file` ou `AGENTS.override.md`).
+- No Codex, uma chave `developer_instructions` definida fora do bloco é recusada sempre, mesmo com `--replace`. A edição é validada por parse TOML (Python 3.11+): o restante do arquivo precisa continuar idêntico. Uninstall devolve o arquivo byte a byte.
+- Arquivo existente não gerenciado exige `--replace`; guia editado ou ausente exige `--overwrite-modified`. Ambos guardam backup privado em `~/.local/state/crow-skills/guide-backups/`. O uninstall devolve o arquivo que `--replace` substituiu (conferido pelo SHA-256 do backup), em vez de apagá-lo, e mantém um `config.toml` que já existia, mesmo vazio.
+- Transações usam o mesmo journal, lock, `rollback` e `recover` das skills. Se o Codex reescrever outras partes do `config.toml` depois, o rollback desfaz só o bloco.
+- `status`/`doctor` mostram `guides`: `installed`, `outdated` (as skills gerenciadas mudaram com `--no-guide` ou fora do CLI; rode `guide install` ou `update` de novo), `modified`, `missing`, `unmanaged`, `absent` ou `unsafe`. Doctor fica `healthy:false` para `modified`, `missing` e `unsafe`.
+- Diretórios de regras criados pelo comando são removidos no uninstall se estiverem vazios.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/crow-skills",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Versioned, complementary agent skills with a protected multi-agent installer",
   "license": "UNLICENSED",
   "repository": {

package/release.json

@@ -3,7 +3,7 @@
     "README.md": {
       "executable": false,
       "kind": "file",
-      "sha256": "50387f058109b5451ba40c07230d73ecbdf63a5f71c320150b0c83705ce2ed3a"
+      "sha256": "b354e9907359550f40b94ab52fb3a38162a7cdf950d33de419f51e82e8b1423e"
     },
     "bin/npm-crow-skills.cjs": {
       "executable": true,
@@ -13,12 +13,12 @@
     "catalog.json": {
       "executable": false,
       "kind": "file",
-      "sha256": "96eb202af8bc22443c11947e56332d3fd04d1e1a72eef0348521dbefee32f101"
+      "sha256": "07c01ffc61cab5c6c7f3c2374110705dc8746c8267bb5a0c25f88c8b601f2242"
     },
     "crow_skills/__init__.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "aad4c7d8944057606a7770888c318f903003eef953b00c8bba24a808acf5a36a"
+      "sha256": "f81792d3fad0ea3fdeb96616d1df41e0f9cf811e1aee8e48946ffc7077a8469b"
     },
     "crow_skills/__main__.py": {
       "executable": false,
@@ -33,7 +33,12 @@
     "crow_skills/cli.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "5f62c76d4b35d5101da97d4c90af2a2dbf580b81b3eb545b1fd25917adbe36ae"
+      "sha256": "9aa14347630210decb6a4e4fc58f1910dbeb53ec6907d1cf819939b7419e4df4"
+    },
+    "crow_skills/guide.py": {
+      "executable": false,
+      "kind": "file",
+      "sha256": "65b93fff61c496f7d3e1b3b32eadb008ba3a9cfd543a4db53f73becdb4ceec6f"
     },
     "crow_skills/npm_entry.py": {
       "executable": false,
@@ -48,22 +53,22 @@
     "crow_skills/storage.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "4ddc2ee88d3fab2cd008bf588627ef12ec0ae36744ccabb5e5235a209c7253b4"
+      "sha256": "2c3823f783c1da2f971860e6207a5146275e105fab74a7aa54e57033cd3993f0"
     },
     "docs/cli-security.md": {
       "executable": false,
       "kind": "file",
-      "sha256": "639cfe05dea16b4bcee8d8f790b2de915ff69333aac3b128d76ee3a049c04428"
+      "sha256": "33eebc401bf86443569f011b9987d7e954a9f5b5ade6bb2e18e26055b9ed74f2"
     },
     "docs/cli.md": {
       "executable": false,
       "kind": "file",
-      "sha256": "92653a908c3f9dea3ab9f03a0f2806315ad533ed20859ca3459c0d05472a0890"
+      "sha256": "a0af861933004eac9581215fd5a27312e0127cf1e21f9e8bac12b957200c5fdb"
     },
     "package.json": {
       "executable": false,
       "kind": "file",
-      "sha256": "ab5e5fef04a9577dc5fcc82ba2676b842687d7b4e9c302fffa1dc2658bbe78e3"
+      "sha256": "4985632e9d45f238022af574b5533c0df90e509276decac44f90a3e37c7973ec"
     },
     "skills/crow-accessibility/SKILL.md": {
       "executable": false,
@@ -93,7 +98,7 @@
     "skills/crow-behaviour/SKILL.md": {
       "executable": false,
       "kind": "file",
-      "sha256": "0e146a38ad24bd59d1552a80d27dae9f40f3734570df4935132a68e8d7f8e15c"
+      "sha256": "d58086484a9e914f4e1b4dbded62834fd9105a5df10076888852b8ed5ed5d303"
     },
     "skills/crow-behaviour/agents/openai.yaml": {
       "executable": false,
@@ -601,7 +606,7 @@
       "sha256": "a04946ef7637e0d3fbaedc650b4ddcba9c8f7c71708e837c7e44779d7d6263ca"
     }
   },
-  "revision": "51620c2ae9d08b1288dfa7d569087b455d46ed5c",
+  "revision": "d5b45e0d80d58a203ff86a9f4211fbd63a57d655",
   "schema_version": 1,
-  "version": "0.1.0"
+  "version": "0.3.0"
 }

package/skills/crow-behaviour/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: crow-behaviour
-description: "Aplique um modo de atuação orientado a orquestração, profundidade e verificação em tarefas substantivas. Decomponha, delegue com as capacidades reais do agente e sintetize evidências. Em conversa ou ajustes triviais, responda diretamente; não simule agentes nem altere permissões."
+description: "Use PROATIVAMENTE, sem o usuário pedir, sempre que a tarefa for substantiva — multi-etapa, com exploração/decisões, mexendo em vários arquivos ou componentes, ou exigindo verificação antes de entregar (implementar uma feature, refatorar, depurar, auditar, revisar, migrar, pesquisar a fundo). Ao ativar: decomponha o trabalho, delegue com as capacidades reais do runtime, verifique de forma adversarial e sintetize evidências. NÃO ative em conversa, explicação curta ou ajuste trivial/local — nesses casos responda direto. Não simule agentes nem altere permissões."
 ---
 
 # Atuação coordenada