Merge branch 'main' of https://github.com/instantOS/instantos.github.io

Author: paperbenni

.vitepress/config.mts

@@ -62,6 +62,7 @@ export default defineConfig({
           items: [
             { text: 'Overview', link: '/archive' },
             { text: 'st terminal', link: '/archive/terminal' },
+            { text: 'instantARCH', link: '/archive/instantarch' },
             { text: 'imosid', link: '/archive/imosid' },
             { text: 'instantTHEMES', link: '/archive/instantthemes' },
             { text: 'Terminal Theme', link: '/archive/terminaltheme' },

archive/instantarch.md

@@ -0,0 +1,12 @@
+## Legacy: `instantARCH` (bash)
+
+`instantARCH` is the older bash-based installer built around `instantmenu`. It
+is still what the `instantos.io/install` script runs and what older instantOS
+ISOs ship with.
+
+- Run from an Arch live ISO with `bash <(curl -L instantos.io/install)`
+- Debug mode: set `INSTALLDEBUG=1` or create `/tmp/installdebug`
+- Optional log tag: put an identifier in `/tmp/debugname`
+
+For deeper development notes, see [instantARCH development docs](/development/instantARCH).
+

docs/hotkeys.md

@@ -5,6 +5,14 @@ They are just for reference, to properly learn instantOS, refer to the documenta
 
 You can access this list by pressing super+F1
 
+
+::: info
+These apply only to the custom window manager/compositor instantWM, which is in
+an experimental state right now. 
+:::
+
+
+
 ## General
 
 | Binding                      | Functionality                                     |

docs/index.md

@@ -11,6 +11,7 @@ it if you prefer that.
 
 - [Keybindings](hotkeys.md)
 - [ins CLI reference](ins.md)
+- [resolvething duplicate and Syncthing conflict cleanup](resolvething.md)
 - [WM configuration](wmsettings.md)
 - [instantwmctl reference](instantwmctl.md)
 - [Programs overview](programs.md)

docs/ins.md

@@ -9,6 +9,7 @@ Some larger `ins` subcommands already have dedicated pages:
 - [ins game](insgame.md)
 - [ins video](insvideo.md)
 - [ins assist](instantassist.md)
+- [ins resolvething](resolvething.md)
 
 This page documents the remaining core commands that were only mentioned indirectly in the site before.
 
@@ -19,6 +20,7 @@ The current instantCLI build exposes these main command groups:
 - `arch`
 - `dot`
 - `game`
+- `resolvething`
 - `doctor`
 - `dev`
 - `launch`

docs/insarch.md

@@ -105,14 +105,3 @@ Show the post-install menu (reboot, shutdown, or continue in live session).
 - `/etc/instant/questions.toml` stores the generated installation answers
 - `/var/log/instantos/install.log` captures the installer logs
 
-## Legacy: `instantARCH` (bash)
-
-`instantARCH` is the older bash-based installer built around `instantmenu`. It
-is still what the `instantos.io/install` script runs and what older instantOS
-ISOs ship with.
-
-- Run from an Arch live ISO with `bash <(curl -L instantos.io/install)`
-- Debug mode: set `INSTALLDEBUG=1` or create `/tmp/installdebug`
-- Optional log tag: put an identifier in `/tmp/debugname`
-
-For deeper development notes, see [instantARCH development docs](/development/instantARCH).

docs/insdot.md

@@ -150,6 +150,124 @@ ins dot add --all .ssh --force
 `--force` only affects the current add operation. It does not change the
 contents of any `.insignore` file.
 
+## Encrypted dotfiles (age)
+
+`ins dot` supports storing tracked sources as `*.age` files while applying
+plaintext to the normal target path in your home directory.
+
+Example source/target mapping:
+
+```text
+repo:   dots/.config/app/secrets.toml.age
+target: ~/.config/app/secrets.toml
+```
+
+### 1. Initialize a local identity
+
+```bash
+ins dot key init
+```
+
+This creates a local age identity at `~/.config/instant/age/identity`.
+
+Identity discovery checks these sources (in priority order):
+
+1. **`$AGE_IDENTITY`** — colon-separated paths to identity files (highest priority)
+2. **`age_identity_files`** — list of identity file paths in `~/.config/instant/dots.toml`
+3. **`~/.config/instant/age/identity`** — single identity file from `ins dot key init`
+4. **`~/.config/instant/age/identities/*`** — every file in the identities directory
+
+`ins dot key identity` prints the machine's public key(s) from any of the
+above paths.
+
+### 2. Authorize recipients in the repository
+
+Each repo stores allowed public keys in `instantdots.toml` under
+`age_recipients`.
+
+```bash
+# Authorize this machine's local public key in the first writable repo
+ins dot key authorize
+
+# Or choose a specific repo
+ins dot key authorize --repo my-dots
+
+# Authorize an explicit key
+ins dot key authorize "age1..."
+```
+
+### 3. Encrypt/decrypt tracked sources
+
+```bash
+# Convert tracked plaintext source -> .age source
+ins dot encrypt ~/.config/app/secrets.toml
+
+# Convert tracked .age source -> plaintext source
+ins dot decrypt ~/.config/app/secrets.toml
+
+# Preview either operation
+ins dot encrypt ~/.config/app/secrets.toml --dry-run
+ins dot decrypt ~/.config/app/secrets.toml --dry-run
+```
+
+Use `--repo <name>` and `--subdir <name>` when the target has multiple possible
+sources.
+
+Important behavior:
+
+- `ins dot encrypt` encrypts the **tracked source content** (repository source
+  is the source of truth), not arbitrary unstaged target edits.
+- If the target exists and has local modifications, encrypt/decrypt aborts so
+  changes are not lost.
+- Both commands stage repository file changes (`old` removed, `new` added).
+- Encrypting does **not** erase old plaintext from git history.
+- Decrypting creates plaintext in the repository; committing that exposes
+  secrets.
+
+### 4. Add new files as encrypted sources
+
+```bash
+# Add a new untracked file directly as encrypted source
+ins dot add ~/.config/app/secrets.toml --encrypt
+
+# Add all untracked files under a directory as encrypted sources
+ins dot add ~/.config/app --all --encrypt
+```
+
+For already tracked encrypted files, normal `ins dot add <path>` updates the
+source by re-encrypting the current target content with the repo's configured
+recipients.
+
+### 5. Rotate/inspect key authorization
+
+```bash
+# Show this machine's local public key(s)
+ins dot key identity
+
+# Show recipient/decryption status
+ins dot key status
+ins dot key status --repo my-dots
+
+# Replace recipients and re-encrypt all tracked .age files in that repo
+ins dot key rotate --repo my-dots --recipients "age1newrecipient..."
+```
+
+`rotate` and `authorize` both verify you can decrypt existing encrypted files
+before rewriting them.
+
+### Apply/status/diff behavior with encrypted sources
+
+- `ins dot apply` decrypts encrypted sources to targets when an identity is
+  available.
+- If identity/decryption is unavailable, encrypted files are skipped and shown
+  as `identity_required` in status.
+- Non-identity encrypted failures (e.g. malformed ciphertext) are shown as
+  `encrypted_error` in status.
+- `ins dot reset` also decrypts encrypted sources back to targets.
+- `ins dot diff` decrypts source content to a temp plaintext file for
+  comparison when possible.
+- `ins dot merge` currently does not support encrypted (`.age`) sources.
+
 
 ## Interactive menu
 
@@ -223,6 +341,12 @@ ignored_paths = [
     "~/.ssh",
     "~/.gnupg"
 ]
+
+# Extra age identity files for decrypting encrypted dotfiles
+# (loaded after $AGE_IDENTITY, before the default paths)
+age_identity_files = [
+    "~/.config/instant/age/work-key"
+]
 ```
 
 ### instantdots.toml
@@ -236,6 +360,9 @@ description = "My configs"     # optional
 read_only = true               # optional, prevents modifications to this repo
 dots_dirs = ["dots", "themes"] # optional, defaults to ["dots"]
 default_active_subdirs = ["dots"] # optional, specifies which dirs are active by default
+age_recipients = [             # optional, recipients for encrypted dotfiles
+    "age1..."
+]
 ```
 
 The `dots_dirs` field defines which subdirectories contain dotfiles. This enables:
@@ -406,4 +533,3 @@ dotfiles from multiple different repositories, something which Stow supports
 very well by accident. 
 
 
-

docs/resolvething.md

@@ -0,0 +1,143 @@
+# ins resolvething
+
+`ins resolvething` helps clean up directories that are synced with Syncthing. It has two jobs:
+
+- find duplicate files and move the redundant copies to trash
+- find Syncthing conflict files and open them next to the original file in a diff editor
+
+It is designed for folders where Syncthing can leave files such as `note.sync-conflict-20240101-ABC.md` or redundant copies in `.stversions`.
+
+## Quick start
+
+Open the interactive menu:
+
+```bash
+ins resolvething menu
+```
+
+Run both cleanup steps for every configured scan directory:
+
+```bash
+ins resolvething all
+```
+
+Preview what would happen before changing files:
+
+```bash
+ins resolvething all --dry-run
+```
+
+Run against one directory without changing the saved configuration:
+
+```bash
+ins resolvething all --dir ~/wiki/vimwiki --dry-run
+```
+
+## Scan directories
+
+`resolvething` reads its configuration from:
+
+```bash
+~/.config/instant/resolvething.toml
+```
+
+The default configuration scans `~/wiki/vimwiki` and treats `md` and `json` files as mergeable conflict files.
+
+Use the menu to add or edit scan directories:
+
+```bash
+ins resolvething menu
+```
+
+Or inspect and edit the config directly:
+
+```bash
+ins resolvething config show
+ins resolvething config edit
+```
+
+Example config:
+
+```toml
+scan_dirs = [
+  { path = "~/wiki/vimwiki", extensions = ["md", "json"] },
+  { path = "~/Documents/notes", extensions = ["txt", "md"] },
+]
+
+# Optional. Defaults to $EDITOR, then nvim.
+editor_command = "nvim"
+```
+
+`extensions` controls conflict-file handling. Use an empty list to scan all plain text files in that scan directory.
+
+## Duplicate cleanup
+
+```bash
+ins resolvething duplicates
+ins resolvething duplicates --dry-run
+ins resolvething duplicates --dir ~/wiki/vimwiki
+```
+
+This command uses `fclones` to group identical files. Redundant files are moved to trash, not permanently deleted.
+
+Some groups can be resolved automatically:
+
+- conflict-file duplicates keep a non-conflict file when one exists, otherwise the newest conflict file
+- duplicate files inside `.stversions` keep the newest version snapshot
+- groups with one regular file and matching `.orig` or `.tmp` copies keep the regular file
+- groups made only of `.tmp` files keep one copy
+
+Ambiguous groups open an interactive picker where you choose which file to keep. Use `--no-auto` to force interactive selection even for groups that are normally safe to resolve automatically.
+
+Use `--show-ignored` to list duplicate groups that were deliberately skipped, such as normal live-file plus `.stversions` snapshot pairs.
+
+## Syncthing conflict cleanup
+
+```bash
+ins resolvething conflicts
+ins resolvething conflicts --dry-run
+ins resolvething conflicts --dir ~/wiki/vimwiki
+```
+
+This command looks for Syncthing conflict filenames, reconstructs the original path, and opens both files in a diff editor. After the editor exits, `resolvething` compares the two files:
+
+- if the original and conflict file now match, the conflict file is moved to trash
+- if they still differ, the conflict is left in place
+- missing, binary, or very large files are skipped
+
+By default the diff editor is `$EDITOR -d`, falling back to `nvim -d`. Set `editor_command` in the config if you want a different editor command.
+
+## Menu
+
+```bash
+ins resolvething menu
+ins resolvething menu --gui
+```
+
+The menu shows every configured scan directory with current duplicate and conflict counts. From there you can:
+
+- resolve everything for one directory
+- resolve only duplicates or only conflicts
+- open the directory
+- edit the conflict extensions
+- change or remove the scan directory
+- add another scan directory
+
+`--gui` opens the menu in a GUI terminal window.
+
+## Command reference
+
+```bash
+ins resolvething duplicates [--dir <path>] [--no-auto] [--show-ignored] [--dry-run]
+ins resolvething conflicts  [--dir <path>] [--dry-run]
+ins resolvething all        [--dir <path>] [--no-auto] [--show-ignored] [--dry-run]
+ins resolvething menu       [--gui]
+ins resolvething config show
+ins resolvething config edit
+```
+
+## Dependencies
+
+Duplicate cleanup requires `fclones`. The interactive flows use `fzf`. If a dependency is missing, `ins` will try to install it through the supported package managers.
+
+Files are moved to trash using `trash`, `gio trash`, or a fallback trash directory under the user data directory.

documentation.md

@@ -35,6 +35,7 @@ it if you prefer that.
 ### Power-User Features
 
 - [instantASSIST](https://instantos.io/youtube/assist)
+- [resolvething duplicate and Syncthing conflict cleanup](https://instantos.io/docs/resolvething)
 - [quickmenu](https://instantos.io/youtube/quickmenu)
 - [visibility options](https://instantos.io/youtube/visibility)
 - [customizing](https://instantos.io/youtube/customize)

faq.md

@@ -39,9 +39,14 @@ everything else the Arch repos are used.
 
 ## Can I install instantos on an encrypted drive
 
-Yes, you can, but it will be a bit of work. 
-The installer does not currently support setting up encryption for you.
-So you will have to select the manual partitioning option and set it up yourself including bootloader setup.
+Yes. During an `ins arch install` with automatic partitioning, the installer
+asks whether you want to enable disk encryption. It uses **LUKS on LVM** with
+a dedicated LUKS container, LVM volume group (`instantOS`), and separate
+logical volumes for swap and root. Encryption is handled automatically —
+partitioning, luksFormat, LVM setup, mkinitcpio hooks (`sd-encrypt`), and
+GRUB boot parameters are all configured for you.
+
+If you prefer to set it up manually, select manual partitioning instead.
 
 ## How do I install instantOS software on a regular Arch