codecell-germany/facilioo-agent-skill

facilioo-agent-cli

Quando usar

Use esta skill quando uma tarefa exigir trabalho real dentro do Facilioo e a superfície preferida for um fluxo de trabalho via terminal, em vez da interface web.

Use-a especialmente quando um agente precisar:

• autenticar-se no Facilioo a partir do terminal,
• construir contexto em torno de uma propriedade, entrada, unidade ou contato,
• inspecionar inquéritos, processos, ordens de serviço, compromissos, tarefas de usuário, avisos ou notificações,
• baixar ou enviar documentos,
• trabalhar com uma pauta ou protocolo de conferência,
• realizar atualizações protegidas sem improvisar chamadas HTTP brutas.

Pré-condições

• Trate facilioo-agent-cli como a superfície do produto.
• Primeiro, verifique se ele existe no PATH:
  • facilioo-agent-cli --help
  • facilioo-agent-skill --help
• Se estiver ausente, instale-o através do pacote público:
  • npm install -g @codecell-germany/facilioo-agent-skill
  • facilioo-agent-skill install --force
• Não ignore a CLI pública acessando dist/ local do repositório, pastas ocultas de ferramentas Codex ou shims locais antigos.
• Não comece com chamadas Swagger ad-hoc quando a CLI já expuser o fluxo de trabalho.

Detecção de primeira execução

Execute isto antes de qualquer trabalho real no Facilioo:

facilioo-agent-cli auth status --json
facilioo-agent-cli doctor --profile auth --json

Considere o ambiente como não pronto se alguma das seguintes condições for verdadeira:

• a CLI está ausente
• nenhuma sessão persistida existe
• o método de autenticação configurado é login com chave de API, mas nenhuma chave de API está disponível
• doctor falha
• o usuário diz que esta é a primeira configuração

Se a configuração estiver incompleta, mude imediatamente para o modo de onboarding. Não comece com context, ops, documents ou conferences.

Modo de onboarding

Esta é a ordem exata para a primeira execução de um usuário novo ou parcialmente configurado:

1. Informe ao usuário que a configuração ainda não está completa.
2. Imprima o guia de configuração embutido no idioma preferido do usuário:
   • Inglês: facilioo-agent-cli setup --language en
   • Alemão: facilioo-agent-cli setup --language de
3. Colete apenas os valores estáticos primeiro:
   • FACILIOO_BASE_URL
   • FACILIOO_API_VERSION
   • FACILIOO_AUTH_METHOD
4. Use como padrão o fluxo de senha local quando um humano estiver presente no terminal:
   • facilioo-agent-cli auth login --method password --interactive --persist
5. Use login com chave de API apenas se o usuário desejar explicitamente uma configuração técnica ou orientada à automação:
   • FACILIOO_API_KEY
   • facilioo-agent-cli auth login --method api-key --persist
6. Nunca peça por:
   • tokens de acesso
   • tokens de atualização
   • cookies brutos do navegador
7. Após o login, execute novamente:
   • facilioo-agent-cli auth status --json
   • facilioo-agent-cli doctor --profile core-read --json
8. Só então prossiga para comandos de negócio.

Fluxo de trabalho principal

1. Validar configuração:
   • facilioo-agent-cli auth status --json
   • facilioo-agent-cli doctor --profile core-read --json
2. Construir contexto:
   • facilioo-agent-cli context lookup --search "Musterstraße 12" --json
   • facilioo-agent-cli context property --id 123 --include entrances,units,tenant,documents,ops --json
   • facilioo-agent-cli context unit --id 456 --include documents,ops --json
3. Trabalhar filas operacionais:
   • facilioo-agent-cli ops inbox --property-id 123 --json
   • facilioo-agent-cli ops processes search --property-id 123 --open-only --json
   • facilioo-agent-cli ops tasks mine --json
   • facilioo-agent-cli ops notifications mine --json
4. Trabalhar documentos:
   • facilioo-agent-cli documents search --property-id 123 --search "Versicherung" --json
   • facilioo-agent-cli documents download --id 5001 --output /absolute/path/file.pdf --json
5. Trabalhar conferências:
   • facilioo-agent-cli conferences search --property-id 123 --json
   • facilioo-agent-cli conferences protocol --id 7001 --json

Salvaguardas

• Operações de leitura são seguras por padrão.
• Gravações exigem:
  • --execute --confirm-write yes
• Toda exclusão exposta exige:
  • --execute --allow-delete --confirm-delete yes
• Use --preview antes de alterações ou exclusões sensíveis.
• Login com senha é apenas interativo e deve ser concluído localmente por um humano em um TTY real.
• auth export é opcional e deve ser usado apenas quando outro processo precisar explicitamente de exportações de ambiente.
• Não cole tokens em prompts, tickets, chats ou capturas de tela.
• Não trate caminhos de API brutos como a rota normal quando um comando de alto nível existir.

Regra de exclusão

A regra de exclusão é global nesta skill, não apenas específica a um processo.

Exemplos:

facilioo-agent-cli ops processes delete --id 987 --preview --json
facilioo-agent-cli ops processes delete --id 987 --execute --allow-delete --confirm-delete yes --json

facilioo-agent-cli documents delete --id 5001 --preview --json
facilioo-agent-cli documents delete --id 5001 --execute --allow-delete --confirm-delete yes --json

Se o usuário não tiver aprovado explicitamente uma exclusão, não a execute.

Referências

• Manual de onboarding do agente: references/agent-onboarding.md
• Visão geral principal: references/overview.md
• Folha de consulta de comandos: references/command-cheatsheet.md
• Configuração de primeira execução: references/facilioo-first-run.md