La cartella dati e il formato dei file

La cartella dati (nel mondo Markdown chiamata anche “vault”) è la cartella in cui TandemLoop salva tutti i tuoi dati. È composta esclusivamente da normali file di testo, Markdown con intestazioni YAML, e si trova dove la scegli durante la configurazione: in locale o in iCloud Drive. Per questo è leggibile da altri strumenti, dagli agenti IA e naturalmente da te con qualsiasi editor di testo.

Struttura delle cartelle

{cartella dati}/
  AGENTS.md                  ← Istruzioni per gli agenti IA
  _inbox/                    ← Attività aggiunte al volo (Inbox GTD)
  bereiche/                  ← Le tue aree (una sottocartella ciascuna)
    {area}/
      area_{slug}.md         ← Metadati dell'area
      _projects/             ← Progetti dell'area
      _singles/              ← Attività singole direttamente nell'area
      _folders/              ← Cartelle facoltative
        {cartella}/
          fld_{slug}.md      ← Metadati della cartella
          _projects/
          _singles/
  _config/                   ← Configurazione (tag, attributi, temi, aspetto, lingua)
    tags.yaml
    attributes/              ← Attributi personalizzati (un file per attributo)
      {chiave}.yaml
    themes/                  ← Temi (un file per tema)
      {chiave}.yaml
    agent.yaml               ← Ultimo ciclo del tuo agente IA (lo scrive l'agente)
    language.yaml            ← Lingua della cartella dati
  _views/                    ← Viste salvate (anche in sottocartelle)
    vw_{slug}.yaml
  _proposals/                ← Proposte dell'IA
    prop_{slug}.md
  _archive/                  ← Entità archiviate (non modificare a mano)
  _conflicts/                ← Copie di conflitto di iCloud salvate
  _system/                   ← Schema e documenti di riferimento generati

Le directory con prefisso _ sono cartelle di sistema gestite dall’app.

ID delle entità e prefissi dei nomi dei file

Ogni entità ha nel campo id del suo frontmatter un ID stabile basato su UUID. Il nome del file ne è indipendente e segue uno slug leggibile. Solo viste, cartelle di viste (vf_…) e proposte contengono il proprio slug nell’ID. I file più vecchi possono avere ancora ID basati sullo slug (ad es. area_arbeit).

Il contratto dei dati

Il formato dei file segue tre principi:

Lettura tollerante: l’app legge i file anche quando mancano dei campi, contengono valori di stato sconosciuti o provengono da versioni precedenti. Così un elemento modificato a mano o creato da un agente IA non blocca l’intera app.

Scrittura stabile: quando aggiorna un file, l’app mantiene l’ordine dei campi esistenti e le informazioni presenti. I campi sconosciuti aggiunti da un editor esterno restano invariati. I campi aggiunti in seguito, come un promemoria (remind_at), l’app li accoda alla fine del frontmatter; i campi vuoti compaiono come null, solo alcuni come remind_at e repeat: mancano del tutto finché non sono impostati.

Leggibile dalle macchine: trattandosi di file Markdown in testo semplice, gli agenti IA e altri strumenti possono leggere direttamente la cartella dati. Quali modifiche possono apportare direttamente è descritto nel capitolo Collaborare con gli agenti IA.

Attributi personalizzati

Gli attributi personalizzati (nelle impostazioni, in Attributi) aggiungono campi ad attività, progetti e traguardi. Ogni attributo è un piccolo file YAML in _config/attributes/; il nome del file è la chiave dell’attributo:

key: cliente
name: Cliente
type: select
applies_to:
  - task
  - project
options:
  - ACME
  - Contoso
description: Per quale cliente viene svolto il lavoro.

I valori si trovano nel frontmatter del rispettivo file, sotto attributes::

attributes:
  cliente: ACME
  budget: 12000
  collaudo: '2026-11-30'

• Tipi: text, number (numero), date ('AAAA-MM-GG'), boolean (Sì/No), select (una delle opzioni), url (link).
• Le chiavi sono composte da lettere minuscole, cifre e trattini bassi e non possono coincidere con un campo integrato come status o due_date. Una chiave non può essere modificata in seguito.
• I campi vuoti non vengono salvati. Gli attributi eliminati non rimuovono i valori: restano nei file e compaiono nell’Inspector come riga di sola lettura.
• Nelle viste gli attributi sono disponibili come campi attributes.chiave per filtrare, ordinare e raggruppare.

Attività ricorrenti

La regola di ripetizione si trova nel frontmatter dell’attività, sotto repeat:; ad esempio ogni lunedì:

repeat:
  unit: week
  days: [mon]

unit è day, weekday, week, month o year; facoltativamente si aggiungono every (intervallo), day oppure nth + weekday (regole mensili), from: completion (dal completamento) e until o count come fine. Le chiavi series, occurrence e next sono gestite dall’app. Il riferimento completo per gli agenti si trova in _system/docs/data-model.md.

Temi

Ogni tema è un file YAML in _config/themes/; il nome del file senza estensione è la sua chiave (nordlicht.yaml → nordlicht). Un tema indica solo i colori che si discostano da quelli predefiniti:

name: Nordlicht
description: Petrolio freddo con superfici scure.
appearance: system        # system, light o dark
font_design: rounded      # default, rounded, serif o monospaced
colors:
  primary:
    light: "#0F766E"
    dark: "#2DD4BF"
  danger: "#E5484D"       # un solo valore vale per chiaro e scuro

I colori sono indicati come valore esadecimale tra virgolette, con opacità come #RRGGBBAA. Quali chiavi di colore esistono, quali derivano da altre e quali valori predefiniti valgono è descritto in _system/docs/themes.md: TandemLoop mantiene aggiornato questo riferimento, così gli agenti IA possono progettare temi adatti. Il tema attivo viene salvato da ogni dispositivo per conto proprio; i file dei temi invece si sincronizzano con la cartella dati.

Il blocco delle relazioni

Ogni file di attività, progetto, traguardo e cartella (tranne le attività dell’Inbox) contiene alla fine del corpo una breve sezione leggibile dalle macchine, che salva il collegamento al livello superiore come link Markdown relativi, qui per un’attività nel progetto “Website-Relaunch”:

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

L’app mantiene aggiornato questo blocco automaticamente e non è necessario modificarlo a mano; gli agenti IA lo omettono nei nuovi file e lo rimuovono quando spostano un file. Rende ricostruibile la collocazione gerarchica per strumenti e agenti anche senza l’indice in memoria dell’app.

Lingua della cartella dati

I pochi testi che TandemLoop scrive da sé nei file (le etichette nel blocco delle relazioni (Bereich: / Area: …), le intestazioni nella cronologia di un’attività (## Du — 21.3.2026 / ## You — 2026-03-21), le sezioni di una proposta (## Diskussion / ## Discussion) e le istruzioni per gli agenti IA (AGENTS.md, _system/docs/)) seguono la lingua della cartella dati. È indicata in _config/language.yaml:

language: en

Le cartelle dati create da zero sono in inglese; quelle senza questo file (da versioni precedenti) restano in tedesco. La lingua della cartella dati non dipende dalla lingua del dispositivo: così tutti i dispositivi scrivono gli stessi file. In lettura TandemLoop riconosce entrambe le varianti.

Più dispositivi: sincronizzazione tramite iCloud Drive

TandemLoop non ha un server proprio e di sua iniziativa non trasmette dati in rete. Poiché la tua cartella dati è una normalissima cartella, la usi su più dispositivi mettendola in iCloud Drive. iCloud mantiene aggiornati i file tra Mac, iPad e iPhone; TandemLoop legge la stessa cartella su ogni dispositivo e scarica da iCloud i file mancanti quando servono.