From e5eb0379c59ad7fa5524f9282270e92d67a7ca0e Mon Sep 17 00:00:00 2001 From: Aly Raffauf Date: Mon, 3 Aug 2026 08:48:40 -0400 Subject: [PATCH] Document local folder inventory imports --- README.md | 35 ++++++++++++++++------------------- docs/architecture.md | 3 ++- 2 files changed, 18 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 329fa2a..4b11c9b 100644 --- a/README.md +++ b/README.md @@ -134,36 +134,33 @@ Symbolic links are ignored: they are not synced and produce no error. Non-Unicode filenames are rejected rather than lossily renamed during synchronization. -## Configure folders declaratively +## Import local folders -`appa config` registers folders from a TOML file instead of one command at a -time. It is useful for provisioning, backups, or version-controlling your -setup. The commands write to local state directly, so stop the daemon first -and pass `--offline`. +`appa config` manages a non-secret local folder inventory. It is useful for +provisioning or recreating local folder paths and modes. It does not contain +invitations, folder IDs, capabilities, membership, or any other shared-folder +state. Join shared folders with an invitation instead. -Write a template from your current folders +Write an inventory from your current folders ```sh -appa --offline config init +appa --offline config template ``` -This writes `appa.toml` (the default path) with one `[[folders]]` entry per -folder. Each entry has a `path` and optional `name`, `folder_id`, -`capability_env`, and `mode`. Joined folders must set both `folder_id` and -`capability_env`. Keep capability secrets in the named environment variable, -not in the file. `mode` is `send_receive` (the default), `send_only`, or -`receive_only`. +This writes `appa.toml` by default with one `[[folders]]` entry per folder. +Each entry has a `path`, optional `name`, and local `mode`. `mode` is +`send_receive` by default, `send_only`, or `receive_only`. -Validate, preview, and apply +Validate and import ```sh -appa --offline config check -appa --offline config audit -appa --offline config apply +appa --offline config validate +appa --offline config import ``` -`apply` registers new folders and updates the mode of existing ones. Start the -daemon afterward; it picks up registered folders within a second. +`import` registers new folders and updates the local mode of existing ones. It +does not remove folders that are absent from the inventory. Start the daemon +afterward; it picks up registered folders within a second. ## Change folders while Appa runs diff --git a/docs/architecture.md b/docs/architecture.md index 044d046..8cac475 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -69,7 +69,8 @@ variables, but it never stores a capability itself. The state directory is intentionally separate from synchronized folders. To remove a folder's synchronization state without touching its files, use -`appa forget ` or `appa leave `. +`appa forget `. This is a local operation and does not alter remote +membership. ## Version boundaries -- 2.51.2