Installation workflow

Install flowCopy 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]

Update flowCopy Anchor Link

On apothem update --harness X:

1. Load and validate ~/.config/apothem/profile.yaml or --profile PATH.
2. Resolve the selected harness or all through the central registry.
3. Validate the full materialization plan before the first write.
4. Call Adapter.update(profile, project=...).
5. Report created, updated, unchanged, skipped, warning, and error outcomes.

Uninstall flowCopy Anchor Link

On apothem uninstall --harness X:

1. Call Adapter.uninstall().
2. The adapter removes only the files it wrote; the shared profile YAML and unrelated operator-authored files are untouched.
3. The shared working directory's memory, contexts, and learning stores are backed up and removed when this is the last harness installed there. They are removed at the location the install recorded. The plans/ directory is never removed.

Scope resolutionCopy Anchor Link

Each adapter writes to its own fixed install root: user-home for user-scope adapters and project-local for project-scope adapters. The CLI does not expose a --scope flag; project-scope adapters require --project <path>. Seven of the project-scope adapters also write shared folders in the user home, such as ~/.agents/skills/ and ~/.config/apothem/, before they write the project file, and --project does not change where those go. The install reference lists them. Each destination is documented at site/content/docs/harnesses/<harness>.mdx.

Error handlingCopy Anchor Link

Install/update operations validate before writing, back up existing matching targets before replacement, and merge only Apothem-managed child entries in shared discovery directories. --dry-run executes the same validation and returns the outcome each write would have, such as created or updated, without creating directories or files.

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