Flux d'installation

flowchart TD
    accTitle: Apothem install workflow
    accDescr: Top-down flowchart of the apothem install command from CLI invocation through adapter lookup, profile load, adapter install call, native config write, and a follow-up apothem verify check that the operator runs.
    A[apothem install --harness X] --> B[Resolve adapter through registry]
    B --> C[Load and validate profile YAML<br/>before writes]
    C --> D[Adapter.install(profile, project)]
    D --> E[Write native config and support cohorts]
    E --> F[Operator runs: apothem verify --harness X]
    F --> G{All checks pass?}
    G -- yes --> H[Done]
    G -- no --> I[Report failures]

Flux de mise à jour

Lors de apothem update --harness X :

Charge et valide ~/.config/apothem/profile.yaml ou --profile PATH.
Résout l'environnement sélectionné ou all via le registre central.
Valide le plan de matérialisation complet avant la première écriture.
Appelle Adapter.update(profile, project=...).
Rapporte les résultats créés, mis à jour, inchangés, ignorés, avec avertissement et avec erreur.

Flux de désinstallation

Lors de apothem uninstall --harness X :

Appelle Adapter.uninstall().
L'adaptateur supprime uniquement les fichiers qu'il a écrits ; le profil partagé YAML et les fichiers non liés rédigés par l'opérateur restent intacts.
La mémoire, les contextes et les magasins d'apprentissage du répertoire de travail partagé sont sauvegardés, puis supprimés lorsque c'est le dernier environnement installé dans ce répertoire. Ils sont supprimés à l'emplacement enregistré lors de l'installation. Le répertoire plans/ n'est jamais supprimé.

Chaque adaptateur écrit dans sa propre racine d'installation fixe : le répertoire personnel de l'utilisateur pour les adaptateurs de portée utilisateur et le chemin local du projet pour les adaptateurs de portée projet. La CLI n'expose pas d'option --scope ; les adaptateurs de portée projet exigent --project <path>. Sept des adaptateurs de portée projet écrivent aussi des dossiers partagés dans le répertoire personnel de l'utilisateur, comme ~/.agents/skills/ et ~/.config/apothem/, avant d'écrire le fichier de projet, et --project ne change pas l'emplacement de ceux-ci. La référence d'install les énumère. Chaque destination est documentée dans site/content/docs/harnesses/<harness>.mdx.

Gestion des erreurs

Les opérations d'installation et de mise à jour valident avant d'écrire, sauvegardent les cibles correspondantes existantes avant le remplacement, et ne fusionnent que les entrées enfants gérées par Apothem dans les répertoires de découverte partagés. --dry-run exécute la même validation et renvoie le résultat que chaque écriture aurait produit, tel que created ou updated, sans créer de répertoires ni de fichiers.

Reversibility (backup and rollback)

Every install pass is reversible. Replaced bytes are captured into the Apothem backup root and the pass is recorded in the harness ledger under a ULID install id; apothem rollback selects a recorded pass and restores those captured backups.

%% provenance: hand-authored %%
%% verified: 2026-07-06 %%
%% cross-reference: this page's Error handling section (back up before replace); /docs/cli-reference/rollback %%
flowchart LR
    accTitle: Apothem backup and rollback lifecycle
    accDescr: At install time each replaced target's prior bytes are captured into the Apothem backup root and the pass is recorded in the harness ledger under a ULID install id. The rollback command selects a recorded install pass by latest or install-id, restores every captured backup from the backup root, and appends a rollback record to the ledger.
    subgraph Install
        direction TB
        I1["Back up existing targets<br/>before replacement"] --> I2["Apothem backup root"]
        I1 --> I3["Ledger install record<br/>ULID install-id"]
    end
    subgraph Rollback
        direction TB
        R1["Select install pass<br/>--last or --install-id ULID"] --> R2["Restore captured backups<br/>from the backup root"]
        R2 --> R3["Append rollback record<br/>to the harness ledger"]
    end
    I2 -.->|captured bytes| R2
    I3 -.->|resolves pass| R1

Flux d'installation