From 46dfcc856b694c301852689342c0957643b522ea Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 26 Sep 2026 02:09:41 +0000 Subject: [PATCH] Give the docs folder a more polished layout Add a docs index page with a card layout, give each reference doc an icon title, a navigation row, and a tagline, and turn key notes and warnings into GitHub callouts. Section headings are unchanged so existing anchor links keep working. release-notes.md is left as is because it becomes the GitHub release text. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BUhabxL4SPejg19jgbSyYN --- README.md | 1 + docs/README.md | 66 +++++++++++++++++++++++++++++++++ docs/development.md | 19 +++++++--- docs/history/SETTINGS-UPDATE.md | 3 +- docs/history/UI-POLISH.md | 5 ++- docs/installation.md | 23 ++++++++---- docs/operations.md | 18 +++++++-- docs/releases.md | 29 +++++++++------ docs/setup-and-workspaces.md | 17 +++++++-- docs/user-guide.md | 12 ++++-- 10 files changed, 156 insertions(+), 37 deletions(-) create mode 100644 docs/README.md diff --git a/README.md b/README.md index e34b564..8a1be9d 100644 --- a/README.md +++ b/README.md @@ -172,6 +172,7 @@ Open `http://127.0.0.1:4173` for a browser preview with sample data. Desktop ope | | | | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | | πŸ“– **[Wiki: how to use Command Center](https://github.com/Commanderx-code/command-center/wiki)** | A step-by-step guide to every page and feature, plus troubleshooting. | +| πŸ“š **[Documentation index](docs/README.md)** | Every reference doc in one place. | | πŸ“₯ [Installation](docs/installation.md) | Packages, requirements, checksums, and source builds. | | 🧭 [User guide](docs/user-guide.md) | Features, integrations, command behavior, and local data. | | πŸ§‘β€πŸ’» [Development](docs/development.md) | Repository layout, checks, and Toolbox updates. | diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..645f40b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,66 @@ +
+ +Command Center icon + +# Command Center documentation + +Reference docs for installing, using, and developing Command Center.
+Looking for a step-by-step walkthrough? Read the **[πŸ“– Wiki guide](https://github.com/Commanderx-code/command-center/wiki)**. + +[🏠 Back to the README](../README.md) + +
+ +## πŸ‘€ Using Command Center + + + + + + + + + + +
+

πŸ“¦ Installation

+ Release packages, requirements, checksum and provenance verification, and building from source. + 		+

🧭 User guide

+ Features, connecting your setup, how commands run, local data, and every page in detail. +
+

πŸ” Workflows and profiles

+ Maintenance recipes, machine profiles, personal Toolbox folders, recovery tests, and notifications. + 		+

🚚 Setup and workspaces

+ Setup bundles between machines, the first-run wizard, project workspaces, and keyboard navigation. +
+ +## πŸ› οΈ Building and releasing + + + + + + +
+

πŸ› οΈ Development

+ Architecture, local checks, updating Commander Toolbox, packaging, the wiki, and screenshots. + 		+

πŸš€ Releases and updates

+ Source updates and rollback, preparing a release, packaging CI, and the AUR package. +
+ +## πŸ—‚οΈ Also in this folder + +| Path | What it is | +| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| πŸ“ [`release-notes.md`](release-notes.md) | Notes for the current release. `npm run release:draft` uses them as the GitHub release text. | +| πŸ“– [`wiki/`](wiki/) | Source of the [GitHub wiki](https://github.com/Commanderx-code/command-center/wiki), published by the `Publish wiki` workflow. | +| πŸ–ΌοΈ [`images/`](images/) | Screenshots used by the README and wiki. | +| πŸ—„οΈ [`history/`](history/) | Historical development notes. They describe earlier versions and may no longer match the app. | + +
+
+See also: πŸ“ Changelog Β· 🀝 Contributing Β· πŸ” Security Β· 🧾 Third-party notices +
diff --git a/docs/development.md b/docs/development.md index 24636ba..1a8ae6b 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,6 +1,8 @@ -# Development +# πŸ› οΈ Development -[← Command Center](../README.md) Β· [Installation](installation.md) Β· [Contributing](../CONTRIBUTING.md) +[🏠 README](../README.md)  Β·  [πŸ“š Docs](README.md)  Β·  [πŸ“¦ Installation](installation.md)  Β·  [🀝 Contributing](../CONTRIBUTING.md) + +> _Architecture, checks, Toolbox updates, packaging, and docs._ ## Architecture @@ -39,7 +41,8 @@ The **Security audit** workflow runs `cargo audit --file src-tauri/Cargo.lock` a Workflow actions are pinned to full commit SHAs, with the version in a trailing comment. Dependabot (`.github/dependabot.yml`) opens grouped weekly updates for Actions, npm, and Cargo; review an Action update's release before merging it. The Commander Toolbox pin is excluded; update it with `scripts/pin-toolbox.mjs`. -Tests do not push real repositories, run personal backups, activate Home Manager, or execute real Toolbox installers. UI changes should also be checked visually in the browser preview and, for native behavior, in the desktop app. +> [!NOTE] +> Tests do not push real repositories, run personal backups, activate Home Manager, or execute real Toolbox installers. UI changes should also be checked visually in the browser preview and, for native behavior, in the desktop app. ## Updating Commander Toolbox @@ -61,11 +64,17 @@ npm run desktop:package Tauri writes `.deb` and `.rpm` packages under `src-tauri/target/release/bundle/`. Keep versions aligned in `package.json`, `package-lock.json`, `src-tauri/Cargo.toml`, `src-tauri/Cargo.lock`, and `src-tauri/tauri.conf.json` when preparing a version bump. -Release packages come from CI, which builds on Ubuntu 22.04 and declares a glibc 2.35 floor. A local `desktop:package` build on a newer distribution links against its newer glibc, so `scripts/verify-packages.py` correctly rejects it as a release candidate. See [Releases](releases.md#package-validation-and-distribution-ci). +> [!IMPORTANT] +> Release packages come from CI, which builds on Ubuntu 22.04 and declares a glibc 2.35 floor. A local `desktop:package` build on a newer distribution links against its newer glibc, so `scripts/verify-packages.py` correctly rejects it as a release candidate. See [Releases](releases.md#package-validation-and-distribution-ci). ## Wiki -The [GitHub wiki](https://github.com/Commanderx-code/command-center/wiki) is published from `docs/wiki/`. Edit the pages there and open a pull request; after it merges, the `Publish wiki` workflow copies them to the wiki. Edits made directly in the wiki are overwritten the next time that page changes here. Page links use wiki names such as `[Settings](Settings)`, so they only resolve on the wiki itself. `Home.md`, `_Sidebar.md`, and `_Footer.md` are the landing page, sidebar, and footer. +The [GitHub wiki](https://github.com/Commanderx-code/command-center/wiki) is published from `docs/wiki/`. Edit the pages there and open a pull request; after it merges, the `Publish wiki` workflow copies them to the wiki. + +> [!WARNING] +> Edits made directly in the wiki are overwritten the next time that page changes here. + +Page links use wiki names such as `[Settings](Settings)`, so they only resolve on the wiki itself. `Home.md`, `_Sidebar.md`, and `_Footer.md` are the landing page, sidebar, and footer. ## Documentation screenshots diff --git a/docs/history/SETTINGS-UPDATE.md b/docs/history/SETTINGS-UPDATE.md index f0e4e93..f2db5ec 100644 --- a/docs/history/SETTINGS-UPDATE.md +++ b/docs/history/SETTINGS-UPDATE.md @@ -1,4 +1,5 @@ -> Historical development notes. These describe an earlier version and may no longer match the app. See the [current user guide](../user-guide.md) for supported behavior. +> [!WARNING] +> **Historical development notes.** These describe an earlier version and may no longer match the app. See the [current user guide](../user-guide.md) for supported behavior. # Basic settings update diff --git a/docs/history/UI-POLISH.md b/docs/history/UI-POLISH.md index 4bb60c0..00ab4a5 100644 --- a/docs/history/UI-POLISH.md +++ b/docs/history/UI-POLISH.md @@ -1,4 +1,5 @@ -> Historical development notes. These describe an earlier version and may no longer match the app. See the [current user guide](../user-guide.md) for supported behavior. +> [!WARNING] +> **Historical development notes.** These describe an earlier version and may no longer match the app. See the [current user guide](../user-guide.md) for supported behavior. # Settings and UI polish @@ -7,6 +8,7 @@ Existing settings are migrated through defaults; editor, terminal, and scan folder choices are retained. New preferences in Settings: + - Theme: Dark, Light, or System (follows desktop color scheme). - Text size: Standard or Larger. - Repository layout: Cards or List. @@ -26,6 +28,7 @@ Search shortcut: Ctrl+K (Cmd+K in a browser on macOS); Escape clears search. Errors remain visible until dismissed or replaced by a later notification. Validation: + - `node --test tests/*.test.mjs` β€” preferences migration, normalization, simultaneous status badges, error-state filtering, and stable sorting. - `npm run check` and `npm run build`. diff --git a/docs/installation.md b/docs/installation.md index 65f4b74..7c70cf4 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,12 +1,15 @@ -# Installation +# πŸ“¦ Installation -[← Command Center](../README.md) Β· [User guide](user-guide.md) Β· [Development](development.md) +[🏠 README](../README.md)  Β·  [πŸ“š Docs](README.md)  Β·  [🧭 User guide](user-guide.md)  Β·  [πŸ› οΈ Development](development.md) + +> _Release packages, verification, and building from source._ ## Release packages Download a package and `SHA256SUMS` from the [GitHub releases page](https://github.com/Commanderx-code/command-center/releases/latest). -Packages target **Linux x86_64 / amd64** and require **GTK 3, WebKitGTK 4.1, and glibc 2.35 or newer** from 0.6.0 (0.5.x packages require glibc 2.39). Packages declare these dependencies. Both packages are built once on Ubuntu 22.04, then installed and launched on Ubuntu 22.04, Debian 12, Ubuntu 24.04, and Fedora 43. See the release notes for the workflow run. ARM, Windows, and macOS packages are not currently published. +> [!IMPORTANT] +> Packages target **Linux x86_64 / amd64** and require **GTK 3, WebKitGTK 4.1, and glibc 2.35 or newer** from 0.6.0 (0.5.x packages require glibc 2.39). Packages declare these dependencies. Both packages are built once on Ubuntu 22.04, then installed and launched on Ubuntu 22.04, Debian 12, Ubuntu 24.04, and Fedora 43. See the release notes for the workflow run. ARM, Windows, and macOS packages are not currently published. To verify a downloaded package, put it and `SHA256SUMS` in the same directory and run: @@ -42,9 +45,13 @@ On Arch or an Arch-based system such as Garuda (0.6.0 and later): sudo pacman -U ./command-center-0.7.1-1-x86_64.pkg.tar.zst ``` -The Arch package is built from the release tag with `packaging/aur/PKGBUILD` in a clean Arch container and tracks current Arch libraries; update your system before installing it. To build it yourself instead, run `makepkg -si` from a copy of `packaging/aur/`. +> [!TIP] +> The Arch package is built from the release tag with `packaging/aur/PKGBUILD` in a clean Arch container and tracks current Arch libraries; update your system before installing it. To build it yourself instead, run `makepkg -si` from a copy of `packaging/aur/`. + +Launch **Command Center** from your application menu. -Launch **Command Center** from your application menu. Run the app as your normal user, without `sudo`. +> [!WARNING] +> Run the app as your normal user, without `sudo`. ## From source on Arch/Garuda @@ -88,7 +95,8 @@ The per-user installer writes `~/.local/bin/command-center`, an icon, and a desk | `npm run desktop:install` | Release executable and per-user application-menu entry. | | `npm run desktop:package` | `.deb` and `.rpm` files in `src-tauri/target/release/bundle/`. | -The browser preview uses sample repositories and configurations. It cannot run Git operations, access backups, launch applications, or save real configuration files. Source changes rebuild automatically; refresh the browser to load them. +> [!NOTE] +> The browser preview uses sample repositories and configurations. It cannot run Git operations, access backups, launch applications, or save real configuration files. Source changes rebuild automatically; refresh the browser to load them. ## Connect integrations @@ -96,4 +104,5 @@ After installation, open **Settings β†’ System integrations**. Command Center ca Git, Home Manager, Restic, Ghostty, Fastfetch, and backup helpers are used when installed and configured. They are not all required to open the app. See the [user guide](user-guide.md#connect-your-setup) for each integration. -File restores require **Restic 0.17 or newer** for its no-overwrite protection; Command Center checks support before preparing a restore. Some distributions ship an older Restic independently of Command Center. +> [!NOTE] +> File restores require **Restic 0.17 or newer** for its no-overwrite protection; Command Center checks support before preparing a restore. Some distributions ship an older Restic independently of Command Center. diff --git a/docs/operations.md b/docs/operations.md index 871a28b..9294a7a 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -1,6 +1,8 @@ -# Workflows, profiles, and recovery verification +# πŸ” Workflows, profiles, and recovery verification -[← Command Center](../README.md) Β· [User guide](user-guide.md) +[🏠 README](../README.md)  Β·  [πŸ“š Docs](README.md)  Β·  [🧭 User guide](user-guide.md) + +> _Maintenance recipes, machine profiles, personal tools, recovery tests, and notifications._ ## Maintenance workflows @@ -16,7 +18,12 @@ The weekly maintenance example checks local backup-drive readiness, runs the per A machine profile is a named, ordered setup recipe for a workstation, laptop, or new install. Add repository clones, Toolbox installers, configuration operations, and other steps through the same editor. Set a profile-specific dotfiles checkout and Home Manager flake profile, or leave them blank to use Settings. These overrides apply only to that profile's reviewed commands. -**Review profile** shows whether each command can be prepared on the current machine. Optional path checks show **Present Β· inspect before skipping** when a file or directory exists. Presence does not establish that the right version or content is installed. **Skip inspected step** requires confirmation. Missing prerequisites can be satisfied by earlier steps; the app rechecks each command immediately before execution. +**Review profile** shows whether each command can be prepared on the current machine. Optional path checks show **Present Β· inspect before skipping** when a file or directory exists. + +> [!CAUTION] +> Presence does not establish that the right version or content is installed. + +**Skip inspected step** requires confirmation. Missing prerequisites can be satisfied by earlier steps; the app rechecks each command immediately before execution. Profiles operate on the local computer. They do not connect to remote machines, automatically replace configuration files, or bypass Toolbox installer prompts. Clone destinations must be new directories. Recipes and personal tools live in `operations.json`. In 0.5.0, [setup bundles](setup-and-workspaces.md) include them; preference-only Settings exports still do not. @@ -44,7 +51,10 @@ The prerequisite field checks whether the executable is available. It does not i The test uses `restic dump` to restore the selected file into a temporary directory, compares its SHA-256 against the saved baseline, and removes its temporary copy on normal completion. It never overwrites the original. A mismatch or missing file fails visibly in Activity. Abrupt process termination or power loss can leave a temporary copy for normal system temporary-file cleanup. -Recent recovery results include the baseline ID, result, and timestamp. The baseline selector maps IDs to recorded files and dates. Results follow Activity's 100-job retention. Success proves recovery of that selected file from that snapshot using the current credentials; it does not certify all snapshots, all files, or a bootable system restore. A file changed after recording may legitimately mismatch another snapshot. +Recent recovery results include the baseline ID, result, and timestamp. The baseline selector maps IDs to recorded files and dates. Results follow Activity's 100-job retention. + +> [!NOTE] +> Success proves recovery of that selected file from that snapshot using the current credentials; it does not certify all snapshots, all files, or a bootable system restore. A file changed after recording may legitimately mismatch another snapshot. ## Change timeline diff --git a/docs/releases.md b/docs/releases.md index 2912ea7..55bafe4 100644 --- a/docs/releases.md +++ b/docs/releases.md @@ -1,4 +1,8 @@ -# Releases and updates +# πŸš€ Releases and updates + +[🏠 README](../README.md)  Β·  [πŸ“š Docs](README.md)  Β·  [πŸ“¦ Installation](installation.md)  Β·  [πŸ› οΈ Development](development.md) + +> _Updating an installed app, cutting a release, and the packaging CI._ ## Installing a published release @@ -18,7 +22,8 @@ chmod +x ~/.local/bin/command-center.rollback mv -- ~/.local/bin/command-center.rollback ~/.local/bin/command-center ``` -This rolls back the binary only, not settings or user data. It applies to the normal local installation, not package-manager installations. No automatic package-manager upgrade, signature verification, or background download is provided. +> [!NOTE] +> This rolls back the binary only, not settings or user data. It applies to the normal local installation, not package-manager installations. No automatic package-manager upgrade, signature verification, or background download is provided. ## Preparing a release as maintainer @@ -32,22 +37,24 @@ npm run release:draft -- v0.7.1 The draft command requires an authenticated GitHub CLI (`gh`). It checks for a clean working tree and a matching local/remote tag and runs the checks and tests. It then finds the successful **Linux packages** run for the tagged commit, downloads that run's `packages` and `arch-package` artifacts, verifies their checksums, verifies each package's build provenance attestation (signed by that run's `attest` job for this tag and commit, on a GitHub-hosted runner), writes one `SHA256SUMS` covering the `.deb`, `.rpm`, and Arch package, and creates an **unpublished** GitHub release. The release notes are docs/release-notes.md plus a build-and-validation section linking the workflow run. If CI has not passed for the tag, no draft is created. The command never builds release packages locally: a build on a newer distribution such as Garuda would require a newer glibc than the packages declare. It does not push tags or publish the draft. Download and verify the hosted assets and test the app on your machine before publishing. -The app discovers only published releases. Building a package, creating a tag, or preparing a draft does not publish a release. +> [!IMPORTANT] +> The app discovers only published releases. Building a package, creating a tag, or preparing a draft does not publish a release. ## Package validation and distribution CI The **Linux packages** workflow runs these jobs: -| Job | What it does | -| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| `tests` | JavaScript and Rust tests and clippy as a normal user on Ubuntu 24.04. | -| `build` | Builds the `.deb` and `.rpm` once in an `ubuntu:22.04` container (glibc 2.35), validates them, and uploads the `packages` artifact with `SHA256SUMS`. | -| `install-deb` | Installs that `.deb` on Ubuntu 22.04, Debian 12, and Ubuntu 24.04 and runs a 20-second launch check under a virtual display as an ordinary user. | -| `install-rpm` | Installs that `.rpm` on Fedora 43 and runs the same launch check. | +| Job | What it does | +| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `tests` | JavaScript and Rust tests and clippy as a normal user on Ubuntu 24.04. | +| `build` | Builds the `.deb` and `.rpm` once in an `ubuntu:22.04` container (glibc 2.35), validates them, and uploads the `packages` artifact with `SHA256SUMS`. | +| `install-deb` | Installs that `.deb` on Ubuntu 22.04, Debian 12, and Ubuntu 24.04 and runs a 20-second launch check under a virtual display as an ordinary user. | +| `install-rpm` | Installs that `.rpm` on Fedora 43 and runs the same launch check. | | `arch` | Builds `packaging/aur/PKGBUILD` in a clean `archlinux` container, lints the recipe and package with namcap, installs, and launches it. Tag pushes build the recipe unmodified from its release tag (the pkgver must match the tag) and upload the `arch-package` artifact; other pushes build the pushed commit. | -| `attest` | Tag pushes only, after every build and install job passes: downloads the `packages` and `arch-package` artifacts, rechecks their checksums, and signs SLSA build provenance for the `.deb`, `.rpm`, and Arch package with `actions/attest`. It is the only job with signing permissions. | +| `attest` | Tag pushes only, after every build and install job passes: downloads the `packages` and `arch-package` artifacts, rechecks their checksums, and signs SLSA build provenance for the `.deb`, `.rpm`, and Arch package with `actions/attest`. It is the only job with signing permissions. | -These are installation and launch checks, not end-to-end validation of system-changing workflows. +> [!NOTE] +> These are installation and launch checks, not end-to-end validation of system-changing workflows. `scripts/verify-packages.py` checks package metadata and payloads, then compares the glibc floor declared in `tauri.conf.json` with the highest glibc symbol version the binary actually requires. It fails if the binary needs a newer glibc than the packages declare. It then stages named assets and checksums in `artifacts/release/`. To raise or lower the floor, change the build container and both `depends` entries together. diff --git a/docs/setup-and-workspaces.md b/docs/setup-and-workspaces.md index 0256d76..080545f 100644 --- a/docs/setup-and-workspaces.md +++ b/docs/setup-and-workspaces.md @@ -1,12 +1,20 @@ -# Setup bundles, onboarding, and project workspaces +# 🚚 Setup bundles, onboarding, and project workspaces -These features are available in **Command Center 0.5.0** and later. Merge imports and automatic recovery of interrupted imports require **0.6.0**. +[🏠 README](../README.md)  Β·  [πŸ“š Docs](README.md)  Β·  [🧭 User guide](user-guide.md)  Β·  [πŸ” Workflows](operations.md) + +> _Move your setup between machines, first-run setup, and per-project workspaces._ + +> [!NOTE] +> These features are available in **Command Center 0.5.0** and later. Merge imports and automatic recovery of interrupted imports require **0.6.0**. ## Move a setup between machines Open **Settings β†’ Setup & portability β†’ Export setup bundle**. Review the full JSON before exporting it to Downloads. The bundle contains saved settings, scan roots and discovered repository paths, repository favorites/groups/launch profiles/tasks/services, maintenance workflows, machine profiles, personal tools, notification preferences, and Toolbox favorites. Unsaved form drafts are not included. -It does not copy repository contents, backups, credential files, activity logs, recovery baselines, or configuration-file contents. Password-file paths and wallet identifiers are removed, along with remote Restic addresses that might contain credentials. Saved commands and workflow input values are included verbatim: inspect them for private values before sharing the file. +It does not copy repository contents, backups, credential files, activity logs, recovery baselines, or configuration-file contents. Password-file paths and wallet identifiers are removed, along with remote Restic addresses that might contain credentials. + +> [!WARNING] +> Saved commands and workflow input values are included verbatim: inspect them for private values before sharing the file. On the destination, choose **Import setup bundle**, then set the destination home folder. The preview rewrites the source home prefix and `~/` in structured paths, including scan roots, working directories, integration paths, workflow paths, and workspace keys. It leaves other absolute paths, URLs, command text, and arbitrary input values unchanged. Review those values for machine-specific references. Missing repositories are remembered for discovery but are not cloned; use a reviewed machine-profile clone step if needed. @@ -17,7 +25,8 @@ Choose an import method: The preview shows the exact result that will be saved. A confirmation checkbox is required. Editing the home folder or changing the method refreshes the preview and clears the checkbox. The backend validates the bundle again when applying it and rejects the import if this machine's saved setup changed after the preview. Unknown bundle versions, invalid definitions, path collisions, and files over 2 MB are rejected. Current local password-file/wallet connections are retained. A local Restic path in the bundle replaces the current repository path; an omitted remote connection keeps the current connection. -No imported command runs automatically. Both setup bundles and preference imports retain this machine’s existing backup health helper, including an empty value. Configure that automatic helper separately in Settings after reviewing its executable. The app reloads after importing, clears old workflow progress, and offers setup review on the dashboard. A running job blocks import. +> [!IMPORTANT] +> No imported command runs automatically. Both setup bundles and preference imports retain this machine’s existing backup health helper, including an empty value. Configure that automatic helper separately in Settings after reviewing its executable. The app reloads after importing, clears old workflow progress, and offers setup review on the dashboard. A running job blocks import. Before replacing files, the app saves the previous bytes to a private `setup-backups/before-import-.json` file under its local app-data directory, then records that backup in `setup-import-journal.json`. Settings shows the backup path after reload. Ordinary write failures roll back completed replacements immediately. diff --git a/docs/user-guide.md b/docs/user-guide.md index e3a198b..6c5308c 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -1,6 +1,8 @@ -# User guide +# 🧭 User guide -[← Command Center](../README.md) Β· [Installation](installation.md) Β· [Development](development.md) +[🏠 README](../README.md)  Β·  [πŸ“š Docs](README.md)  Β·  [πŸ“¦ Installation](installation.md)  Β·  [πŸ› οΈ Development](development.md) + +> _Features, integrations, command behavior, and local data._ ## Features @@ -40,7 +42,8 @@ Future catalog updates require updating the pinned revision in `src-tauri/Cargo. ## Operational behavior -Every operation displays its exact command and working directory for review. Repository Git credentials use existing helpers; SSH uses batch mode so unavailable authentication fails visibly instead of waiting for an invisible terminal prompt. +> [!IMPORTANT] +> Every operation displays its exact command and working directory for review. Repository Git credentials use existing helpers; SSH uses batch mode so unavailable authentication fails visibly instead of waiting for an invisible terminal prompt. Background jobs show output and a recorded exit status. Full recovery backups use a terminal and write a completion receipt back to the app; terminal input/output is not captured. If the terminal closes without a receipt, use **Terminal closed? Stop monitoring** only after checking that the workflow has stopped. Closing the app normally is blocked while a job is running. After a crash, previously running jobs are marked interrupted; inspect the command before retrying. @@ -48,7 +51,8 @@ Background jobs show output and a recorded exit status. Full recovery backups us Repository actions (fetch, pull, push, staging, commits, branches, stashes) and project tasks run alongside each other when they use different repositories. Everything else, including Toolbox installers, backups and restores, Home Manager, updates, workflows, personal tools, and quick actions, is a workstation task: one runs at a time, but it can run alongside repository jobs in other folders. Two jobs never run in the same working directory at once, and the embedded terminal holds one interactive session. External-terminal jobs do not use the embedded terminal. A job that has to wait says which running job it is waiting for. Each job is stopped individually from Activity; the tray shows how many are running. -Restore destinations must be nonexistent directories beneath your home with an existing parent. Restore uses `--overwrite never` and `--verify`. Include fields accept Restic patterns; leaving them blank restores the whole snapshot. This is file recovery into a staging folder, not automatic OS replacement or a bootable disk-image restore. +> [!NOTE] +> Restore destinations must be nonexistent directories beneath your home with an existing parent. Restore uses `--overwrite never` and `--verify`. Include fields accept Restic patterns; leaving them blank restores the whole snapshot. This is file recovery into a staging folder, not automatic OS replacement or a bootable disk-image restore. Configuration saves check the loaded revision and source path, validate the proposed content, save the previous contents, and replace the source atomically. The review screen displays both old and proposed content. Ghostty edits retain unrelated lines. Fastfetch edits preserve JSONC comments outside rewritten properties and retain custom module options; reordering rewrites the modules array. Previews are illustrative rather than a terminal emulator or executable Fastfetch session.