A Pasta de Dados e o Formato dos Arquivos

A pasta de dados (no mundo Markdown, também chamada de “vault”) é a pasta em que o TandemLoop salva todos os seus dados. Ela é formada apenas por arquivos de texto comuns — Markdown com cabeçalhos YAML — e fica onde você a colocar durante a configuração — localmente ou no iCloud Drive. Isso a torna legível para outras ferramentas, para agentes de IA e, claro, para você mesmo, em qualquer editor de texto.

Estrutura de pastas

{pasta-de-dados}/
  AGENTS.md                  ← Instruções para agentes de IA
  _inbox/                    ← Tarefas capturadas rapidamente (Caixa de Entrada GTD)
  bereiche/                  ← Suas áreas (uma subpasta para cada)
    {area}/
      area_{slug}.md         ← Metadados da área
      _projects/             ← Projetos da área
      _singles/              ← Tarefas avulsas diretamente na área
      _folders/              ← Pastas opcionais
        {pasta}/
          fld_{slug}.md      ← Metadados da pasta
          _projects/
          _singles/
  _config/                   ← Configuração (etiquetas, atributos, temas, exibição, idioma)
    tags.yaml
    attributes/              ← Atributos personalizados (um arquivo por atributo)
      {chave}.yaml
    themes/                  ← Temas (um arquivo por tema)
      {chave}.yaml
    agent.yaml               ← Última execução do seu agente de IA (escrito pelo agente)
    language.yaml            ← Idioma da pasta de dados
  _views/                    ← Visualizações salvas (também em subpastas)
    vw_{slug}.yaml
  _proposals/                ← Propostas da IA
    prop_{slug}.md
  _archive/                  ← Itens arquivados (não editar manualmente)
  _conflicts/                ← Cópias de conflito do iCloud guardadas
  _system/                   ← Esquema e documentos de referência gerados

Diretórios com o prefixo _ são pastas do sistema e são gerenciados pelo app.

IDs dos itens e prefixos dos nomes de arquivo

Cada item tem, no campo id do Frontmatter, um ID estável baseado em UUID. O nome do arquivo é independente dele e segue um slug legível. Apenas visualizações, pastas de visualizações (vf_…) e propostas têm o slug no ID. Arquivos mais antigos ainda podem ter IDs em forma de slug (por exemplo, area_arbeit).

O contrato de dados

O formato dos arquivos segue três princípios:

Leitura tolerante: o app lê os arquivos mesmo quando faltam campos, há valores de status desconhecidos ou os arquivos vêm de versões anteriores. Assim, um item editado manualmente ou criado por um agente de IA não trava o app inteiro.

Escrita estável: ao atualizar um arquivo, o app preserva a ordem dos campos existentes e as informações já presentes. Campos desconhecidos adicionados por um editor externo são mantidos. Campos acrescentados depois, como um lembrete (remind_at), o app coloca no fim do Frontmatter; campos vazios aparecem como null, e só alguns, como remind_at e repeat:, ficam totalmente ausentes enquanto não estiverem definidos.

Legível por máquinas: como são arquivos Markdown em texto simples, agentes de IA e outras ferramentas podem ler a pasta de dados diretamente. Quais alterações elas podem fazer diretamente está descrito no capítulo Colaboração com Agentes de IA.

Atributos personalizados

Os atributos personalizados (em Ajustes, na seção Atributos) ampliam tarefas, projetos e marcos com campos adicionais. Cada atributo é um pequeno arquivo YAML em _config/attributes/ — o nome do arquivo é a chave do atributo:

key: cliente
name: Cliente
type: select
applies_to:
  - task
  - project
options:
  - ACME
  - Contoso
description: Para qual cliente o trabalho é feito.

Os valores ficam no Frontmatter do arquivo correspondente, em attributes::

attributes:
  cliente: ACME
  orcamento: 12000
  aceite: '2026-11-30'

• Tipos: text, number (número), date ('AAAA-MM-DD'), boolean (Sim/Não), select (uma das opções), url (link).
• As chaves são formadas por letras minúsculas, números e sublinhados e não podem coincidir com um campo integrado, como status ou due_date. Uma chave não pode ser alterada depois.
• Campos vazios não são salvos. Atributos apagados não removem valores — eles permanecem nos arquivos e aparecem no Inspetor como linha somente leitura.
• Nas visualizações, os atributos ficam disponíveis como campos attributes.chave para filtrar, ordenar e agrupar.

Tarefas recorrentes

A regra de repetição fica no Frontmatter da tarefa, em repeat: — por exemplo, toda segunda-feira:

repeat:
  unit: week
  days: [mon]

unit é day, weekday, week, month ou year; opcionalmente, há também every (intervalo), day ou nth + weekday (regras mensais), from: completion (após a conclusão) e until ou count como término. As chaves series, occurrence e next são mantidas pelo próprio app. A referência completa para agentes está em _system/docs/data-model.md.

Temas

Cada tema é um arquivo YAML em _config/themes/ — o nome do arquivo sem extensão é a chave dele (aurora.yaml → aurora). Um tema indica apenas as cores que diferem do padrão:

name: Aurora
description: Petróleo frio com fundos escuros.
appearance: system        # system, light ou dark
font_design: rounded      # default, rounded, serif ou monospaced
colors:
  primary:
    light: "#0F766E"
    dark: "#2DD4BF"
  danger: "#E5484D"       # um único valor vale para claro e escuro

As cores ficam como valor hexadecimal entre aspas; com opacidade, como #RRGGBBAA. Quais chaves de cor existem, quais são derivadas de outras e quais valores padrão valem está em _system/docs/themes.md — o próprio TandemLoop mantém essa referência, para que agentes de IA possam criar temas adequados. Cada dispositivo guarda por conta própria qual tema está ativo; os arquivos de tema sincronizam com a pasta de dados.

O bloco de relações

Todo arquivo de tarefa, projeto, marco e pasta — exceto as tarefas da Caixa de Entrada — contém, no fim do corpo do arquivo, uma seção curta legível por máquinas que guarda os vínculos com os itens superiores como links Markdown relativos — aqui, para uma tarefa no projeto “Website Relaunch”:

<!-- tandemloop:relations:start -->
[Bereich: Arbeit](../../../area_arbeit.md) · [Projekt: Website Relaunch](../prj_website-relaunch.md)
<!-- tandemloop:relations:end -->

Esse bloco é mantido atualizado automaticamente pelo app e não precisa ser editado manualmente; os agentes de IA o omitem em arquivos novos e o removem ao mover itens. Ele torna a hierarquia compreensível para ferramentas e agentes, mesmo sem o índice em memória do app.

Idioma da pasta de dados

Os poucos textos que o próprio TandemLoop escreve nos arquivos — os rótulos do bloco de relações (Bereich: / Area: …), os títulos no histórico de uma tarefa (## Du — 21.3.2026 / ## You — 2026-03-21), as seções de uma proposta (## Diskussion / ## Discussion) e as instruções para agentes de IA (AGENTS.md, _system/docs/) — seguem o idioma da pasta de dados. Ele fica em _config/language.yaml:

language: en

Pastas de dados novas são criadas em inglês; pastas de dados sem esse arquivo (de versões anteriores) continuam em alemão. O idioma da pasta de dados não depende do idioma do dispositivo — assim, todos os dispositivos escrevem os mesmos arquivos. Na leitura, o TandemLoop reconhece as duas variantes.

Vários dispositivos: sincronização pelo iCloud Drive

O TandemLoop não tem servidor próprio e não envia dados pela internet por conta própria. Como sua pasta de dados é uma pasta comum, você a usa em vários dispositivos colocando-a no iCloud Drive. O iCloud mantém os arquivos atualizados entre Mac, iPad e iPhone; o TandemLoop lê a mesma pasta em cada dispositivo e baixa do iCloud os arquivos que faltarem, quando necessário.