@andespindola/crow-skills 0.10.1 → 0.11.0

package/crow_skills/cli.py

@@ -9,22 +9,99 @@ from . import __version__
 from . import autoupdate
 from . import broadcast
 from . import events
+from . import groups as groups_mod
 from . import guide
 from . import hook
 from . import integrations
 from . import progress
 from . import resources
+from . import machine
+from . import ui
 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", "guide", "integrations", "mode", "autoupdate"}
+MUTATIONS = {"install", "update", "uninstall", "rollback", "recover", "guide", "integrations", "mode", "autoupdate", "setup", "upgrade"}
+
+
+TRUST_HELP = "Não habilitar/aprovar os hooks do crow-skills nos CLIs (padrão: habilita)"
+
+# Per-command help: what it is for and real examples (crow-skills help <cmd> or <cmd> --help).
+COMMANDS = {
+    "setup": ("Detecta os CLIs de agente desta máquina (Claude Code, Codex, Gemini CLI, Antigravity, Devin, Uniflow, tmux) e "
+              "configura cada um no escopo do usuário: todas as skills do catálogo, guia, integrações, hooks do modo crow "
+              "habilitados, modo crow e autoupdate. Rodar de novo só corrige o que mudou.",
+              ["crow-skills setup --dry-run", "crow-skills setup --yes", "crow-skills setup --agents claude,codex --yes",
+               "crow-skills setup --skills crow-behaviour,crow-debug --no-autoupdate --yes"]),
+    "upgrade": ("Atualiza o próprio crow-skills (Homebrew, npm ou checkout git) e, em seguida, skills, guias, integrações e "
+                "hooks de todo agente configurado. Skills editadas localmente nunca são sobrescritas.",
+                ["crow-skills upgrade --dry-run", "crow-skills upgrade --yes", "crow-skills upgrade --skills-only --yes"]),
+    "help": ("Ajuda curta, por tarefa; help <comando> detalha um comando e help flags lista as flags globais.",
+             ["crow-skills help", "crow-skills help setup", "crow-skills help flags"]),
+    "list": ("Lista o catálogo de skills da fonte atual.", ["crow-skills list", "crow-skills list --json"]),
+    "groups": ("Grupos de skills pré-definidos no catálogo, para install --group e setup --group (todas = o catálogo inteiro; "
+               "a crow-behaviour entra com qualquer grupo).", ["crow-skills groups", "crow-skills groups --json"]),
+    "agents": ("Agentes detectados (PATH e diretórios); não prova que as skills carregam.", ["crow-skills agents --json"]),
+    "status": ("Instalações, guias, integrações, modo e autoupdate, por agente.", ["crow-skills status", "crow-skills status --agents claude"]),
+    "doctor": ("Como status, com healthy true/false: skills editadas/ausentes, guia alterado, hooks não aprovados, transação pendente.",
+               ["crow-skills doctor", "crow-skills doctor --json"]),
+    "info": ("Detalhes de uma skill do catálogo.", ["crow-skills info crow-backend"]),
+    "related": ("Handoffs, overlays e disponibilidade de complementos de uma skill.", ["crow-skills related crow-backend --agents claude --global"]),
+    "install": ("Instala skills escolhidas em agentes e escopo explícitos, com preview, backup e transação.",
+                ["crow-skills install crow-behaviour --agents claude,codex --global --dry-run",
+                 "crow-skills install --group essencial --agents claude --global --yes",
+                 "crow-skills install --group web,qualidade --agents codex --global --yes",
+                 "crow-skills install --all --agents claude --global --yes",
+                 "crow-skills install crow-debug --agents gemini --project . --yes"]),
+    "update": ("Atualiza skills gerenciadas para a revisão da fonte atual (sem self-upgrade; para tudo, use upgrade).",
+               ["crow-skills update --all --agents claude --global --yes", "crow-skills update crow-debug --agents codex --global --dry-run"]),
+    "uninstall": ("Remove skills gerenciadas, com backup; edições locais exigem --overwrite-modified.",
+                  ["crow-skills uninstall crow-debug --agents claude --global --yes"]),
+    "guide": ("Instruções gerenciadas para o agente usar as skills (só --global).",
+              ["crow-skills guide status", "crow-skills guide install --agents claude --global --yes"]),
+    "integrations": ("Status lines, hooks do modo crow, comando /crow e segmento tmux (só --global).",
+                     ["crow-skills integrations status", "crow-skills integrations install --global --yes"]),
+    "progress": ("Painel de progresso da execução crow-behaviour (ledger, barras, tokens).",
+                 ["crow-skills progress", "crow-skills progress --watch"]),
+    "mode": ("Liga/desliga a crow-behaviour em todas as sessões e CLIs, a partir do próximo prompt.",
+             ["crow-skills mode", "crow-skills mode off", "crow-skills mode on"]),
+    "events": ("Barramento de eventos dos hooks (crow-event/1) para terminais.",
+               ["crow-skills events", "crow-skills events tail --limit 20", "crow-skills events tail --follow"]),
+    "broadcast": ("Sessões vivas dos CLIs, arquivos em edição, conflitos e reservas.",
+                  ["crow-skills broadcast", "crow-skills broadcast claim src/api --ttl 30m", "crow-skills broadcast release --all"]),
+    "resources": ("Memória, pressão, agentes em execução e paralelismo recomendado (somente leitura).",
+                  ["crow-skills resources", "crow-skills resources --exec-prefix"]),
+    "autoupdate": ("Agenda a atualização diária e no login (o mesmo fluxo de upgrade) ou roda agora.",
+                   ["crow-skills autoupdate on --yes", "crow-skills autoupdate status", "crow-skills autoupdate run --yes"]),
+    "rollback": ("Desfaz uma transação concluída (skills e o guia ligado a ela).", ["crow-skills rollback --transaction <id> --yes"]),
+    "recover": ("Conclui ou desfaz uma transação interrompida.", ["crow-skills recover --dry-run", "crow-skills recover --yes"]),
+}
+
+
+class Formatter(argparse.RawDescriptionHelpFormatter):
+    def add_usage(self, usage, actions, groups, prefix=None):
+        return super().add_usage(usage, actions, groups, "uso: " if prefix is None else prefix)
 
 
 class Parser(argparse.ArgumentParser):
+    def __init__(self, *args, **kwargs):
+        kwargs.setdefault("formatter_class", Formatter)
+        super().__init__(*args, **kwargs)
+        self._positionals.title = "argumentos"
+        self._optionals.title = "opções"
+        for action in self._actions:
+            if isinstance(action, argparse._HelpAction):
+                action.help = "Mostra esta ajuda e sai"
+
     def error(self, message):
-        raise CrowError("usage", message)
+        raise CrowError("usage", ui.translate_usage(message))
+
+
+def command_parser(sub, name, parents, aliases=()):
+    text, examples = COMMANDS[name]
+    return sub.add_parser(name, parents=parents, aliases=list(aliases), help=text, description=text,
+                          epilog="exemplos:\n" + "\n".join("  $ " + e for e in examples))
 
 
 def parser():
@@ -38,24 +115,46 @@ def parser():
         ("--project", {"help": "Diretório físico do projeto"}),
         ("--dest", {"help": "Diretório de skills explícito, para outro host"}),
         ("--json", {"action": "store_true", "help": "Envelope JSON; nunca abre prompts"}),
-        ("--non-interactive", {"action": "store_true"}),
+        ("--non-interactive", {"action": "store_true", "help": "Nunca perguntar; sem --yes, mutações falham"}),
         ("--yes", {"action": "store_true", "help": "Aplicar o escopo explícito sem prompt"}),
         ("--dry-run", {"action": "store_true", "help": "Preview sem gravar estado ou instalar"}),
         ("--fetch", {"action": "store_true", "help": "Buscar origin explicitamente; não cria clone"}),
     ]:
         common.add_argument(flag, default=argparse.SUPPRESS, **kwargs)
-    p = Parser(prog="crow-skills", parents=[common], description="Instale pacotes crow completos, por agente e revisão, sem executar scripts de skills.")
+    common._optionals.title = "flags globais (crow-skills help flags)"
+    p = Parser(prog="crow-skills", parents=[common], add_help=False,
+               description="Instale pacotes crow completos, por agente e revisão, sem executar scripts de skills.")
+    p.add_argument("-h", "--help", dest="show_help", action="store_true", default=argparse.SUPPRESS,
+                   help="Ajuda curta, por tarefa")
     p.add_argument("--version", action="store_true")
-    sub = p.add_subparsers(dest="command")
-    for name in ("list", "agents", "status", "doctor"):
-        sub.add_parser(name, parents=[common])
+    sub = p.add_subparsers(dest="command", title="comandos", metavar="<comando>")
+    child = command_parser(sub, "setup", [common], aliases=("init",))
+    child.add_argument("--skills", help="Só estas skills (separadas por vírgula); padrão: todo o catálogo")
+    child.add_argument("--group", help="Só estes grupos (separados por vírgula; veja crow-skills groups); padrão: todas")
+    child.add_argument("--no-autoupdate", action="store_true", help="Não ligar o autoupdate")
+    child.add_argument("--replace", action="store_true", help="Autorizar backup e substituição de pacote/guia não gerenciado")
+    child.add_argument("--overwrite-modified", action="store_true", help="Autorizar backup e substituição de skills/guias editados")
+    child.add_argument("--no-trust", action="store_true", help=TRUST_HELP)
+    child.add_argument("--no-probe", action="store_true", help=argparse.SUPPRESS)
+    child = command_parser(sub, "upgrade", [common])
+    child.add_argument("--skills-only", action="store_true", help="Só skills/guias/hooks, sem atualizar o crow-skills")
+    child.add_argument("--no-self", action="store_true", help="Igual a --skills-only")
+    child.add_argument("--git-pull", action="store_true", help="Checkout git: git pull --ff-only se estiver limpo em main/master")
+    child.add_argument("--no-trust", action="store_true", help=TRUST_HELP)
+    child = command_parser(sub, "help", [common])
+    child.add_argument("topic", nargs="?", help="Comando, ou flags")
+    for name in ("list", "groups", "agents", "status", "doctor"):
+        command_parser(sub, name, [common])
     for name in ("info", "related"):
-        child = sub.add_parser(name, parents=[common])
+        child = command_parser(sub, name, [common])
         child.add_argument("name")
     for name in ("install", "update", "uninstall"):
-        child = sub.add_parser(name, parents=[common])
+        child = command_parser(sub, name, [common])
         child.add_argument("skills", nargs="*")
         child.add_argument("--all", action="store_true", help="Todos do catálogo (install) ou gerenciados (update/uninstall)")
+        if name == "install":
+            child.add_argument("--group", help="Grupos pré-definidos, separados por vírgula (crow-skills groups); "
+                                               "todas = catálogo inteiro; crow-behaviour sempre entra")
         if name != "uninstall":
             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")
@@ -63,24 +162,26 @@ def parser():
         child.add_argument("--no-guide", action="store_true", help="Não aplicar/atualizar/remover o guia do agente (--global)")
         child.add_argument("--no-integrations", action="store_true",
                            help="Não aplicar/remover as integrações de interface (status line, tmux) em --global")
-    child = sub.add_parser("guide", parents=[common], help="Instruções gerenciadas para o agente usar as skills instaladas")
+        if name != "uninstall":
+            child.add_argument("--no-trust", action="store_true", help=TRUST_HELP)
+    child = command_parser(sub, "guide", [common])
     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")
-    child = sub.add_parser("integrations", parents=[common], help="Status line/tmux que mostram a execução crow-behaviour ativa")
+    child = command_parser(sub, "integrations", [common])
     child.add_argument("action", choices=("install", "status", "uninstall"))
-    child = sub.add_parser("progress", parents=[common], help="Painel de progresso da execução crow-behaviour (ledger, barras, tokens)")
+    child.add_argument("--no-trust", action="store_true", help=TRUST_HELP)
+    child = command_parser(sub, "progress", [common])
     child.add_argument("--watch", action="store_true", help="Redesenhar até a execução terminar ou Ctrl-C")
     child.add_argument("--run", help="ID da execução; padrão: a ativa mais recente do diretório")
     child.add_argument("--cwd", help="Diretório da execução; padrão: o atual")
-    child = sub.add_parser("mode", parents=[common], help="Liga/desliga o modo crow (crow-behaviour) em todas as sessões e CLIs")
+    child = command_parser(sub, "mode", [common])
     child.add_argument("action", nargs="?", default="status", choices=("on", "off", "status", "toggle"))
-    child = sub.add_parser("events", parents=[common], help="Barramento de eventos dos hooks (crow-event/1) para terminais")
+    child = command_parser(sub, "events", [common])
     child.add_argument("action", nargs="?", default="snapshot", choices=("snapshot", "tail"))
     child.add_argument("--limit", type=int, default=50, help="tail: quantos eventos (padrão 50; 0 = todos os retidos)")
     child.add_argument("--follow", action="store_true", help="tail: transmitir eventos novos em JSONL até Ctrl-C")
-    child = sub.add_parser("broadcast", parents=[common],
-                           help="crow-broadcast: sessões vivas dos CLIs, arquivos em edição, conflitos e reservas")
+    child = command_parser(sub, "broadcast", [common])
     child.add_argument("action", nargs="?", default="status", choices=("status", "list", "claim", "release", "watch"))
     child.add_argument("targets", nargs="*", help="claim: caminhos, globs ou área; release: ids das reservas")
     child.add_argument("--ttl", default="30m", help="claim: validade (ex.: 30m, 2h; máximo 24h)")
@@ -93,19 +194,21 @@ def parser():
     child.add_argument("--all", action="store_true", help="release: todas as reservas desta sessão")
     child.add_argument("--interval", type=float, default=2.0, help=argparse.SUPPRESS)
     child.add_argument("--max-frames", type=int, default=None, help=argparse.SUPPRESS)
-    child = sub.add_parser("resources", parents=[common],
-                           help="Memória, pressão, agentes em execução e paralelismo recomendado (somente leitura)")
+    child = command_parser(sub, "resources", [common])
     child.add_argument("--no-processes", action="store_true", help="Não varrer os processos dos CLIs de agente (mais rápido)")
     child.add_argument("--exec-prefix", action="store_true",
                        help="Só imprimir o prefixo que roda um job pesado em prioridade baixa neste sistema (taskpolicy/nice/ionice/start /low)")
-    child = sub.add_parser("autoupdate", parents=[common], help="Atualização diária e no login do crow-skills e das skills gerenciadas")
+    child = command_parser(sub, "autoupdate", [common])
     child.add_argument("action", choices=("on", "off", "status", "run"))
     child.add_argument("--git-pull", action="store_true", help="on: também atualizar um checkout git limpo em main/master (git pull --ff-only)")
     child.add_argument("--skills-only", action="store_true", help="run: só atualizar as skills, sem atualizar o crow-skills")
     child.add_argument("--no-self", action="store_true", help="run: igual a --skills-only")
+    child.add_argument("--no-trust", action="store_true", help=TRUST_HELP)
     for name in ("rollback", "recover"):
-        child = sub.add_parser(name, parents=[common])
+        child = command_parser(sub, name, [common])
         child.add_argument("--transaction", required=name == "rollback")
+    p.common = common
+    p.commands = sub.choices
     return p
 
 
@@ -301,7 +404,12 @@ def integrations_preview(args, home, store, plan):
     if getattr(args, "project", None) or getattr(args, "dest", None):
         return {"changes": [], "skipped": [{"integration": "*", "reason": "Integrações de interface só existem no escopo do usuário (--global)."}],
                 "disabled": True}
-    return integrations.sync(store, home, integration_agents(args, home, store, plan), dry_run=True)
+    return integrations.sync(store, home, integration_agents(args, home, store, plan), dry_run=True, trust=trusting(args))
+
+
+def trusting(args):
+    """Hooks are enabled/approved in each CLI unless --no-trust."""
+    return not getattr(args, "no_trust", False)
 
 
 def integration_agents(args, home, store, plan=None, selected=None):
@@ -318,7 +426,7 @@ def integration_agents(args, home, store, plan=None, selected=None):
 
 def integrations_command(args, home, store, interactive):
     if args.action == "status":
-        return {"integrations": integrations.status(store, home)}
+        return {"integrations": integrations.status(store, home, probe=False)}
     if not getattr(args, "global_scope", False):
         raise CrowError("usage", "integrations " + args.action + " exige --global explícito (único escopo suportado).")
     wanted = []
@@ -327,12 +435,12 @@ def integrations_command(args, home, store, interactive):
     if args.action == "install" and not wanted:
         raise CrowError("guide_requires_skill", "crow-behaviour não está instalada para nenhum agente; instale antes: "
                         "crow-skills install crow-behaviour --agents claude --global --yes")
-    preview = integrations.sync(store, home, wanted, dry_run=True)
+    preview = integrations.sync(store, home, wanted, dry_run=True, trust=trusting(args))
     if preview["changes"]:
         authorize(args, interactive, preview)
     if getattr(args, "dry_run", False):
         return {**preview, "applied": False}
-    return {**integrations.sync(store, home, wanted), "applied": True}
+    return {**integrations.sync(store, home, wanted, trust=trusting(args)), "applied": True}
 
 
 def progress_command(args, home):
@@ -354,7 +462,7 @@ def mode_command(args, home):
         wanted = args.action if args.action != "toggle" else ("off" if current["mode"] == "on" else "on")
         current = hook.write_mode(home, wanted, "cli")
     try:
-        installed = [r["integration"] for r in integrations.status(Store(home), home)
+        installed = [r["integration"] for r in integrations.status(Store(home), home, probe=False)
                      if r["status"] == "installed" and r["integration"].endswith(("-hooks", "-statusline", "-command", "tmux-status"))]
     except CrowError:
         installed = []
@@ -522,12 +630,13 @@ def autoupdate_command(args, home, store, interactive):
     if args.action == "status":
         return autoupdate.status(store, home)
     if args.action == "run":
-        authorize(args, interactive, {"autoupdate": "run", "self_upgrade": not (args.skills_only or args.no_self)})
+        self_step = not (args.skills_only or args.no_self)
+        authorize(args, interactive, {"autoupdate": "run", "self_upgrade": self_step})
         if getattr(args, "dry_run", False):
-            return {"install": autoupdate.detect(), "applied": False,
-                    "would": ["atualizar o crow-skills" if not (args.skills_only or args.no_self) else None,
-                              "update --global das skills gerenciadas, por agente"]}
-        return autoupdate.run(store, home, self_step=not (args.skills_only or args.no_self))
+            preview = autoupdate.preview(store, home, self_step=self_step, trust=trusting(args))
+            return dict(preview, summary=machine.upgrade_summary(preview.get("skills", []), True))
+        done = autoupdate.run(store, home, self_step=self_step, trust=trusting(args))
+        return dict(done, summary=machine.upgrade_summary(done["lastRun"].get("skills", []), False))
     if args.action == "on":
         preview = autoupdate.turn_on(store, home, dry_run=True, git_pull=args.git_pull)
         if any(c["action"] != "unchanged" for c in preview["changes"]):
@@ -589,26 +698,130 @@ def uniflow_notice(home, store, targets, plan):
                 native[row["target"]]["skills"].append({"name": row["name"], "status": row["status"]})
     if not native:
         return {"native_duplicates": [], "uninspected": uninspected}
-    agents = sorted({a for n in native.values() for a in n["agents"]})
-    managed = sorted({s["name"] for n in native.values() for s in n["skills"] if s["status"] != "unmanaged"})
+    # One command per destination with only the names physically managed there: crossing names and agents
+    # would reach a Uniflow link (or an absent name) in another CLI and abort the uninstall.
+    # Destinations with the same names share one command (the usual case keeps its single command).
+    groups = {}
+    for item in native.values():
+        managed = tuple(sorted({s["name"] for s in item["skills"] if s["status"] != "unmanaged"}))
+        if managed:
+            groups.setdefault(managed, []).extend(a for a in item["agents"] if a not in groups.get(managed, []))
+    commands = ["crow-skills uninstall " + " ".join(names_) + " --agents " + ",".join(sorted(agents_)) + " --global"
+                for names_, agents_ in groups.items()]
     return {"native_duplicates": list(native.values()), "uninspected": uninspected,
             "note": "effect=skipped: o Uniflow não cria o link de um nome que o agente já tem nativo, e essa cópia vale no lugar do "
                     "store. effect=both: o Uniflow liga o store em ~/.codex/skills e o Codex também lê ~/.agents/skills, então vê as "
                     "duas cópias. Nada foi removido. Remover a cópia nativa de crow-behaviour remove também o guia daquele agente.",
-            "suggested_command": ("crow-skills uninstall " + " ".join(managed) + " --agents " + ",".join(agents) + " --global")
-            if managed else None}
+            "suggested_commands": commands, "suggested_command": " && ".join(commands) if commands else None}
+
+
+def pick(source):
+    """Terminal picker without dependencies: a group number or name, todas, or skill names. Default: essencial."""
+    available = groups_mod.load(source)
+    default = next((g["name"] for g in available if g["name"] == "essencial"), groups_mod.ALL)
+    print("Grupos de skills (a crow-behaviour entra com qualquer grupo):", file=sys.stderr)
+    for n, group in enumerate(available, 1):
+        print(terminal("  " + str(n).rjust(2) + ". " + group["name"].ljust(11) + " " + str(len(group["skills"])).rjust(2) +
+                       " skills  " + group["description"]), file=sys.stderr)
+    print("  " + str(len(available) + 1).rjust(2) + ". escolher skills individualmente", file=sys.stderr)
+    answer = prompt("Número(s) ou nome(s) separados por vírgula [" + default + "]:").strip()
+    tokens = [t.strip() for t in answer.split(",") if t.strip()] or [default]
+    if tokens == [str(len(available) + 1)]:
+        for name, item in source.catalog.items():
+            print(terminal(name + " — " + item.get("title", name)), file=sys.stderr)
+        tokens = [t.strip() for t in prompt("Skills separadas por vírgula:").split(",") if t.strip()]
+        if not tokens:
+            raise CrowError("usage", "Nenhuma skill selecionada.")
+    by_number = {str(n): g["name"] for n, g in enumerate(available, 1)}
+    chosen_groups = [by_number.get(t, t) for t in tokens if t in by_number or t in {g["name"] for g in available}]
+    skills = [t for t in tokens if t not in by_number and t not in {g["name"] for g in available}]
+    for name in skills:
+        source.require(name)
+    names = groups_mod.resolve(source, ",".join(chosen_groups)) if chosen_groups else []
+    names = list(dict.fromkeys(names + skills))
+    if not names:
+        raise CrowError("usage", "Nenhuma skill selecionada.")
+    return names, ",".join(chosen_groups) or None
+
+
+def unmanaged_projections(store, home, rows):
+    """A Uniflow link to a store entry crow-skills does not manage is not an install (same rule as setup)."""
+    if not any(r["status"] == "uniflow_link" for r in rows):
+        return rows
+    managed = guide.store_managed(home, store)
+    disabled = machine.store_disabled(home, store)
+    for row in rows:
+        if row["status"] == "uniflow_link" and row["name"] in disabled:
+            # Managed by crow-skills but disabled by Uniflow: reported as such, never as unmanaged (no --replace).
+            row.update(status="disabled", projection="uniflow_link_disabled",
+                       note="Desabilitada no Uniflow (SKILL.md.disabled no store); reabilite no Uniflow para usar.")
+        elif row["status"] == "uniflow_link" and row["name"] not in managed:
+            row.update(status="unmanaged", projection="uniflow_link_unmanaged",
+                       note="Link do Uniflow para um pacote do store que o crow-skills não gerencia; não conta como instalada. "
+                            "Revise o store e, para gerenciá-lo com backup: crow-skills setup --agents uniflow --replace --yes")
+    return rows
+
+
+def group_coverage(rows):
+    """Per destination, which catalog groups are fully or partially installed (best effort)."""
+    try:
+        available = [g for g in groups_mod.load(Source(DEFAULT_SOURCE)) if g["name"] != groups_mod.ALL]
+    except (CrowError, OSError):
+        return []
+    by_target = {}
+    for row in rows:
+        item = by_target.setdefault(row["target"], {"target": row["target"], "agents": row["agents"], "names": set()})
+        if row["name"] and row["status"] in ("installed", "modified", "disabled", "uniflow_link"):
+            item["names"].add(row["name"])
+    return [{"target": v["target"], "agents": v["agents"],
+             "groups": [c for c in groups_mod.coverage(available, v["names"]) if c["state"] != "absent"]}
+            for v in by_target.values() if v["names"]]
+
+
+def groups_command(args):
+    source = Source(getattr(args, "source", DEFAULT_SOURCE), getattr(args, "ref", "HEAD"), getattr(args, "fetch", False))
+    available = groups_mod.load(source)
+    return {"revision": source.revision, "groups": available, "always": groups_mod.BEHAVIOUR,
+            "note": "crow-behaviour entra com qualquer grupo; handoffs de outros grupos são sugeridos, não instalados "
+                    "(use --with-handoffs)."}
+
+
+def help_command(args, home, topic=None):
+    """Short, task-oriented help; help <command> for one command; help flags for the global flags."""
+    p = parser()
+    if topic in (None, "", "help") and getattr(args, "command", None) in (None, "help"):
+        line, status = machine.status_line(home)
+        return {"topic": None, "sections": [{"title": t, "commands": [{"name": n, "summary": d, "example": e} for n, d, e in items]}
+                                             for t, items in ui.SECTIONS],
+                "status": status, "_status_line": line, "text": None}
+    if topic == "flags":
+        return {"topic": "flags", "text": ui.flags_help(p.common._actions)}
+    name = "setup" if topic == "init" else topic
+    if name not in p.commands:
+        raise CrowError("usage", "Comando desconhecido: " + str(topic) + ".")
+    return {"topic": name, "text": p.commands[name].format_help(), "examples": COMMANDS.get(name, ("", []))[1]}
 
 
 def run(args):
+    if getattr(args, "command", None) == "init":
+        args.command = "setup"
+    if getattr(args, "show_help", False):
+        return help_command(args, checked(getattr(args, "home", Path.home())), args.command)
     if args.version:
         return {"version": __version__}
-    if not args.command:
-        raise CrowError("usage", "Escolha um comando; use crow-skills --help.")
     home = checked(getattr(args, "home", Path.home()))
+    if not args.command or args.command == "help":
+        return help_command(args, home, getattr(args, "topic", None))
     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", "guide")):
+    if args.command == "setup":
+        return machine.setup(args, home, store, interactive)
+    if args.command == "upgrade":
+        return machine.upgrade(args, home, store, interactive)
+    if getattr(args, "fetch", False) and (getattr(args, "dry_run", False) or args.command not in ("install", "update", "list", "info", "related", "guide", "groups")):
         raise CrowError("usage", "--fetch requer um comando com fonte e não pode ser combinado com --dry-run.")
+    if args.command == "groups":
+        return groups_command(args)
     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":
@@ -633,25 +846,31 @@ def run(args):
         return autoupdate_command(args, home, store, interactive)
     if args.command in ("status", "doctor"):
         targets = scope(args, home, read=True)
-        rows = store.status(targets)
+        rows = unmanaged_projections(store, home, store.status(targets))
         pending = [t["id"] for t in store.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 []
         try:
-            ui = integrations.status(store, home) if global_view else []
+            # Only doctor asks the CLIs (codex app-server writes under ~/.codex); status stays read-only.
+            ui = integrations.status(store, home, probe=args.command == "doctor") if global_view else []
         except CrowError as exc:
             ui = [{"integration": "*", "status": "unsafe", "note": str(exc)}]
         result = {"installations": rows, "guides": guides, "integrations": ui, "pending_transactions": pending,
                   "mode": hook.read_mode(home), "activation_verified": False,
                   "reload_hint": "Peça ao host para recarregar/listar skills; reinicie a sessão se necessário."}
+        result["groups"] = group_coverage(rows)
         try:
             result["autoupdate"] = autoupdate.status(store, home) if global_view else None
         except CrowError as exc:
             result["autoupdate"] = {"enabled": None, "healthy": False, "error": exc.code}
+        hooks = [r for r in ui_rows(ui) if r.get("status") == "installed" and isinstance(r.get("enabled"), dict)]
+        result["hooks"] = [{"integration": r["integration"], "agents": r.get("agents"), "state": r["enabled"].get("state"),
+                            "fix": r["enabled"].get("fix")} for r in hooks]
         if args.command == "doctor":
             result.update(healthy=not pending and all(r["status"] not in ("modified", "missing", "unsafe", "external_link") for r in rows + guides)
-                          and (result["autoupdate"] or {}).get("healthy", True) is not False,
+                          and (result["autoupdate"] or {}).get("healthy", True) is not False
+                          and all(h["state"] not in machine.BAD_HOOKS for h in result["hooks"]),
                           agents=inventory(home))
         return result
     if args.command in ("rollback", "recover"):
@@ -698,18 +917,20 @@ def run(args):
         return {"revision": source.revision, "skill": source.catalog[args.name],
                 "relationships": relationship_view(source, args.name, store, targets)}
     targets = scope(args, home, interactive)
-    names = args.skills
-    if names and args.all:
-        raise CrowError("usage", "Use nomes ou --all, não ambos.")
+    names = list(args.skills)
+    group = getattr(args, "group", None)
+    if (names or group) and args.all:
+        raise CrowError("usage", "Use nomes/--group ou --all, não ambos.")
+    selection = None
+    if group is not None:
+        selection = groups_mod.parse(group)
+        names = list(dict.fromkeys(names + groups_mod.resolve(source, group)))
     if args.command == "install" and not names and not args.all:
         if not interactive:
-            raise CrowError("usage", "Escolha nomes de skills ou --all.")
-        for name, item in source.catalog.items():
-            print(terminal(name + " — " + item.get("title", name)), file=sys.stderr)
-        names = prompt("Skills separadas por vírgula:").split(",")
-        names = [n.strip() for n in names if n.strip()]
-        if not names:
-            raise CrowError("usage", "Nenhuma skill selecionada.")
+            raise CrowError("usage", "Escolha as skills: nomes, --group ou --all (ex.: crow-skills install --group essencial "
+                            "--agents claude --global --yes; grupos: crow-skills groups).")
+        names, selection = pick(source)
+        selection = groups_mod.parse(selection) if selection else None
     if args.command == "uninstall" and not names and not args.all:
         raise CrowError("usage", "Uninstall exige nomes explícitos ou --all.")
     if args.command == "install" and args.all:
@@ -726,6 +947,8 @@ def run(args):
     ui = integrations_preview(args, home, store, plan)
     summary = {"changes": plan["changes"], "revision": source.revision if source else None,
                "relationships": {n: source.related(n) for n in names} if source else {},
+               **({"groups": selection, "suggested_handoffs": groups_mod.suggested_handoffs(source, names)}
+                  if selection and not getattr(args, "with_handoffs", False) else {}),
                "guides": guides, "integrations": ui, "handoffs_are_optional": True, "activation_verified": False}
     notice = uniflow_notice(home, store, targets, plan) if args.command != "uninstall" else None
     if notice is not None:
@@ -738,7 +961,7 @@ def run(args):
         if not ui.get("disabled"):
             # Best effort after the skills/guide transactions; a refusal is reported, never undoes them.
             try:
-                summary["integrations"] = integrations.sync(store, home, integration_agents(args, home, store))
+                summary["integrations"] = integrations.sync(store, home, integration_agents(args, home, store), trust=trusting(args))
             except (CrowError, OSError) as exc:
                 summary["integrations"] = {"changes": [], "skipped": [{"integration": "*", "reason": "Integrações não aplicadas (" +
                                                                        (str(exc) or "falha de gravação") + "); skills e guia mantidos."}]}
@@ -748,10 +971,84 @@ def run(args):
                             "Operação de arquivos concluída; carregamento/ativação devem ser conferidos no host.")}
 
 
-def emit(command, data, machine):
-    envelope = {"schema_version": 1, "ok": True, "command": command, "data": data}
-    if machine:
+def ui_rows(rows):
+    return [r for r in rows if isinstance(r, dict)]
+
+
+def public_data(data):
+    return {k: v for k, v in data.items() if not k.startswith("_")} if isinstance(data, dict) else data
+
+
+def render_status(data, doctor=False, stream=None):
+    stream = stream or sys.stdout
+    mode = (data.get("mode") or {}).get("mode", "?")
+    auto = data.get("autoupdate") or {}
+    lines = [ui.paint(hook.indicator(mode, ui.unicode_on(stream)), "bold", stream) + " · autoupdate " +
+             ("ligado" if auto.get("enabled") else "desligado") + " · crow-skills " + __version__, ""]
+    by_target = {}
+    for row in data["installations"]:
+        item = by_target.setdefault(row["target"], {"agents": row["agents"], "ok": 0, "via": 0, "bad": [], "kept": []})
+        if row.get("projection") == "uniflow_link_unmanaged":
+            item["kept"].append(row["name"] + " link do Uniflow não gerenciado (crow-skills setup --agents uniflow --replace --yes)")
+        if row["status"] == "uniflow_link":
+            item["ok"] += 1
+            item["via"] += 1  # projected by Uniflow from its store: installed for this CLI
+        elif row["status"] in ("installed", "disabled"):
+            item["ok"] += 1
+        elif row["status"] in ("modified", "missing", "unsafe", "external_link"):
+            item["bad"].append((row["name"] or "raiz") + " " + row["status"])
+    rows = [[ui.mark("fail" if v["bad"] else ("warn" if v["kept"] else "ok"), stream), ",".join(v["agents"]),
+             str(v["ok"]) + " skills" + (" (" + str(v["via"]) + " via uniflow)" if v["via"] else ""),
+             "; ".join(v["bad"] + v["kept"])] for v in by_target.values() if v["ok"] or v["bad"] or v["kept"]]
+    if rows:
+        lines += ui.table(rows, ["", "agente", "instaladas", "problemas"], stream)
+        cover = [[",".join(c["agents"]), ", ".join(g["group"] + (" ✓" if g["state"] == "complete" and ui.unicode_on(stream) else
+                                                               " completo" if g["state"] == "complete" else
+                                                               " " + str(g["installed"]) + "/" + str(g["total"]))
+                                                   for g in c["groups"])] for c in data.get("groups") or [] if c["groups"]]
+        if cover:
+            lines += ["", "  Grupos (completos ✓ ou parciais n/total):" if ui.unicode_on(stream) else "  Grupos:"]
+            lines += ui.table(cover, stream=stream, indent="    ")
+    else:
+        lines.append("  Nenhuma skill instalada; comece com: crow-skills setup --yes")
+    guides = [g for g in data.get("guides", []) if g.get("status") != "absent"]
+    if guides:
+        lines.append("")
+        lines += ui.table([[ui.mark("ok" if g["status"] == "installed" else ("warn" if g["status"] == "outdated" else "fail"), stream),
+                            "guia " + g["agent"], ui.word(g["status"]), ui.clean(g.get("note") or "")] for g in guides], stream=stream)
+    hooks = data.get("hooks") or []
+    if hooks:
+        lines.append("")
+        lines += ui.table([[ui.mark("ok" if h["state"] in ("trusted", "not_required") else
+                                    ("fail" if h["state"] in machine.BAD_HOOKS else "warn"), stream),
+                            h["integration"], ui.word(h["state"]),
+                            ui.clean(h.get("fix") or "")] for h in hooks], stream=stream)
+    if data.get("pending_transactions"):
+        lines += ["", ui.mark("fail", stream) + " Transação pendente: crow-skills recover --yes"]
+    if doctor:
+        lines += ["", (ui.mark("ok", stream) + " healthy") if data.get("healthy") else
+                  (ui.mark("fail", stream) + " não saudável; detalhes: crow-skills doctor --json")]
+    return "\n".join(lines)
+
+
+def render_help(data, stream=None):
+    if data.get("topic") is None:
+        return ui.top_help(__version__, stream, data.get("_status_line"))
+    return data["text"].rstrip("\n")
+
+
+def emit(command, data, as_json):
+    envelope = {"schema_version": 1, "ok": True, "command": command, "data": public_data(data)}
+    if as_json:
         print(json.dumps(envelope, ensure_ascii=False, separators=(",", ":")))
+    elif command == "help":
+        print(render_help(data))
+    elif command == "setup":
+        print(machine.render_setup(data))
+    elif command == "upgrade" or (command == "autoupdate" and isinstance(data, dict) and "summary" in data):
+        print(machine.render_upgrade(data))
+    elif command in ("status", "doctor"):
+        print(render_status(data, doctor=command == "doctor"))
     elif command == "progress":
         if data is not None:
             print(data["text"] or "crow: nenhuma execução registrada neste diretório.")
@@ -771,6 +1068,13 @@ def emit(command, data, machine):
     elif command == "events":
         if data is not None:
             print(data["text"] if "text" in data else "\n".join(json.dumps(e, ensure_ascii=False) for e in data["events"]))
+    elif command == "groups":
+        lines = []
+        for g in data["groups"]:
+            lines.append(ui.paint(g["name"], "cyan") + " (" + str(len(g["skills"])) + ") — " + terminal(g["description"]))
+            lines.append("    " + ", ".join(g["skills"]))
+        lines += ["", "crow-behaviour entra com qualquer grupo. Ex.: crow-skills install --group essencial --agents claude --global --yes"]
+        print("\n".join(lines))
     elif command == "list":
         print("Fonte: " + data["revision"])
         for item in data["skills"]:
@@ -781,31 +1085,41 @@ def emit(command, data, machine):
 
 def main(argv=None):
     argv = list(sys.argv[1:] if argv is None else argv)
-    machine = "--json" in argv
+    as_json = "--json" in argv
     command = None
     try:
         args = parser().parse_args(argv)
         command = args.command or ("version" if args.version else None)
+        if command == "init":
+            command = "setup"
+        if command is None or getattr(args, "show_help", False):
+            command = "help"
         result = run(args)
-        emit(command, result, machine)
+        emit(command, result, as_json)
+        if command in ("setup", "upgrade") and isinstance(result, dict) and result.get("healthy") is False:
+            return 1
         return 0
+    except SystemExit as exc:  # <command> --help printed by argparse
+        return exc.code if isinstance(exc.code, int) else 0
     except CrowError as exc:
-        if machine:
+        if as_json:
             print(json.dumps({"schema_version": 1, "ok": False, "command": command,
                               "error": {"code": exc.code, "message": str(exc)}}, ensure_ascii=False))
         else:
-            print(f"Erro [{exc.code}]: {exc}", file=sys.stderr)
+            print(ui.error_text(exc.code, str(exc), command, sys.stderr), file=sys.stderr)
         return 2 if exc.code == "usage" else 1
     except (OSError, ValueError, KeyError, TypeError) as exc:
         # No traceback or subprocess stderr in machine output; credentials stay external.
-        if machine:
+        if as_json:
             print(json.dumps({"schema_version": 1, "ok": False, "command": command,
                               "error": {"code": "io_error", "message": "Falha de leitura/gravação ou estado inválido; nenhuma conclusão de sucesso."}}))
         else:
-            print("Falha de leitura/gravação ou estado inválido. Confira permissões, origem e transações pendentes.", file=sys.stderr)
+            print(ui.error_text("io_error", "Falha de leitura/gravação ou estado inválido.", command, sys.stderr) +
+                  "\n  Para corrigir: confira permissões e transações pendentes (crow-skills doctor; crow-skills recover --yes)",
+                  file=sys.stderr)
         return 1
     except KeyboardInterrupt:
-        if machine:
+        if as_json:
             print(json.dumps({"schema_version": 1, "ok": False, "command": command,
                               "error": {"code": "interrupted", "message": "Operação interrompida; confira status/recover."}}))
         return 130