Fluxo de instalação

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]

Fluxo de atualização

Em apothem update --harness X:

Carrega e valida ~/.config/apothem/profile.yaml ou --profile PATH.
Resolve o harness selecionado ou all através do registro central.
Valida o plano completo de materialização antes da primeira escrita.
Chama Adapter.update(profile, project=...).
Relata os resultados criados, atualizados, inalterados, ignorados, com aviso e com erro.

Fluxo de desinstalação

Em apothem uninstall --harness X:

Chama Adapter.uninstall().
O adaptador remove apenas os arquivos que escreveu; o perfil compartilhado YAML e os arquivos não relacionados escritos pelo operador permanecem intocados.
Os armazenamentos de memória, contextos e aprendizado do diretório de trabalho compartilhado são salvos em backup e removidos quando este for o último harness instalado nesse diretório. Eles são removidos no local que a instalação registrou. O diretório plans/ nunca é removido.

Cada adaptador escreve na sua própria raiz de instalação fixa: o diretório pessoal do usuário para os adaptadores de escopo de usuário e o caminho local do projeto para os adaptadores de escopo de projeto. A CLI não expõe uma flag --scope; os adaptadores de escopo de projeto exigem --project <path>. Sete dos adaptadores de escopo de projeto também gravam pastas compartilhadas no diretório pessoal do usuário, como ~/.agents/skills/ e ~/.config/apothem/, antes de gravarem o arquivo do projeto, e --project não altera para onde elas vão. A referência de install as lista. Cada destino é documentado em site/content/docs/harnesses/<harness>.mdx.

Tratamento de erros

As operações de instalação/atualização validam antes de escrever, fazem backup dos destinos correspondentes existentes antes da substituição e mesclam apenas as entradas-filhas gerenciadas pelo Apothem nos diretórios de descoberta compartilhados. --dry-run executa a mesma validação e retorna o resultado que cada escrita teria, como created ou updated, sem criar diretórios ou arquivos.

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

Fluxo de instalação