Installations-Workflow

InstallationsablaufCopy Anchor Link

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]

AktualisierungsablaufCopy Anchor Link

Bei apothem update --harness X:

1. Lädt und validiert ~/.config/apothem/profile.yaml oder --profile PATH.
2. Löst den ausgewählten Harness oder all über die zentrale Registry auf.
3. Validiert den vollständigen Materialisierungsplan vor dem ersten Schreibvorgang.
4. Ruft Adapter.update(profile, project=...) auf.
5. Meldet die Ergebnisse erstellt, aktualisiert, unverändert, übersprungen, Warnung und Fehler.

DeinstallationsablaufCopy Anchor Link

Bei apothem uninstall --harness X:

1. Ruft Adapter.uninstall() auf.
2. Der Adapter entfernt nur die Dateien, die er geschrieben hat; das gemeinsame Profil-YAML und nicht zugehörige, vom Operator verfasste Dateien bleiben unberührt.
3. Das Memory, die Kontexte und die Lernspeicher des gemeinsamen Arbeitsverzeichnisses werden gesichert und entfernt, wenn dies der letzte dort installierte Harness ist. Sie werden an dem Ort entfernt, den die Installation vermerkt hat. Das Verzeichnis plans/ wird nie entfernt.

Geltungsbereich-AuflösungCopy Anchor Link

Jeder Adapter schreibt in seine eigene feste Installationswurzel: das Benutzer-Home für Adapter mit Benutzergeltungsbereich und der projektlokale Pfad für Adapter mit Projektgeltungsbereich. Die CLI stellt kein --scope-Flag bereit; Adapter mit Projektgeltungsbereich erfordern --project <path>. Sieben der Adapter mit Projektgeltungsbereich schreiben außerdem gemeinsame Ordner im Home-Verzeichnis, etwa ~/.agents/skills/ und ~/.config/apothem/, bevor sie die Projektdatei schreiben, und --project ändert nicht, wohin diese gehen. Die Install-Referenz listet sie auf. Jedes Ziel ist unter site/content/docs/harnesses/<harness>.mdx dokumentiert.

FehlerbehandlungCopy Anchor Link

Installations-/Aktualisierungsvorgänge validieren vor dem Schreiben, sichern vorhandene passende Ziele vor dem Ersetzen und führen in gemeinsamen Discovery-Verzeichnissen nur von Apothem verwaltete Untereinträge zusammen. --dry-run führt dieselbe Validierung aus und gibt das Ergebnis zurück, das jeder Schreibvorgang gehabt hätte, etwa created oder updated, ohne Verzeichnisse oder Dateien anzulegen.

Reversibility (backup and rollback)Copy Anchor Link

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