docs: fix what no longer matches lazysecrets, and say each thing once (#74)

Fixes:
- A newer release shows in the status pane (`↑ v0.2.0`), not the footer.
- The account in `lazysecrets list` is plain `Azure` with one az account; `Azure:<user>/<tenant>` only with several.
- Sharing lists subscription, workspace and scope links, and opening takes Azure portal links.
- `--timeout` and `--clipboard-clear` are documented, next to their config keys.
- `--kind`'s description reads, and says `vault` covers scopes and repo files.
- `lazysecrets -h` lists `list`'s `--stars`, `--notes`, `--recent` and `--expiry`.
- README typos; "Supported platforms" is "Sources".

Trimmed:
- An option is documented on its topic's page; config.md's example keeps the general ones and links the rest.
- The fzf picker lives in docs/integration.md; the README keeps a link and the screenshot.
- The clipboard clear, reveal timeout, per-account stars, Azure's "no extra requests" and `open --action` are each said once.
- The status pane's contents are a list; build sizes and PR-title spellings are gone from development.md.

Reviewed-on: #74
Co-authored-by: Karl-Einar Bergstrøm <karl-einarb@outlook.com>

README.md

@@ -7,24 +7,23 @@ A terminal UI for finding, reading and sharing secrets. Inspired by the fantasti
 ## Main features
 
 - **Read-only**: lazysecrets never creates, changes or deletes a secret.
-  That's by design and may stay that way.
 - **Zero setup**: uses the logins you already have (`az`, the Databricks
   CLI, `sops`, `git`). No config file needed.
 - **Search everything**: `ctrl+s` searches every source at once, with
   fzf-style matching.
 - **Share links**: Share `lazysecrets://` links with colleagues.
-- **Neovim integration**: via [lazysecrets.nvim](https://github.com/karleinarb/lazysecrets.nvim)
 - **Careful with values**: values stay hidden until you reveal them, and
   copied values are cleared from the clipboard after 30 seconds.
-- **Scriptable**: `lazysecrets get <link>` prints a value for scripts and
-  pipes.
+- **Scriptable**: `get`, `list` and `open` for scripts, fzf and editor
+  pickers; [lazysecrets.nvim](https://github.com/karleinarb/lazysecrets.nvim)
+  for Neovim.
 - **Favourites**: star the secrets you use most for easy access.
 - **Expiry warnings**: secrets, keys and certificates that expire soon are
   marked, listed together in the status pane.
 - **Your way**: rebind any key, pick a theme, and add custom commands to run
   on a secret.
 - **Try it first**: `lazysecrets --demo` runs on built-in sample data.
-- **Supported platforms**: Azure Key Vault, Databricks secret scopes, and SOPS and `.env` files in your git repos. 
+- **Sources**: Azure Key Vault, Databricks secret scopes, and SOPS and `.env` files in your git repos.
 
 > **Early development:** expect rough edges. See [CHANGELOG.md](CHANGELOG.md) for what's new.
 
@@ -45,9 +44,8 @@ Both approaches will install the latest release from [GitHub](https://github.com
 `sh -s -- v0.2.0` installs a given version, `LAZYSECRETS_INSTALL_DIR`
 somewhere else.
 
-lazysecrets looks for a newer release once a day: the footer then shows
-`↑ v0.2.0`, and `U` shows its changelog and updates in place (or run
-`lazysecrets update`).
+`U` (or `lazysecrets update`) updates in place when there's a newer
+release.
 
 Or build it yourself:
 `go install git.kebcloud.no/keb/lazysecrets/cmd/lazysecrets@latest`.
@@ -70,30 +68,20 @@ use most:
 | `l` / `h` | the details of what's selected / back |
 | `/` | filter the list you're in |
 | `space` | reveal / hide the value |
-| `y` | copy the value (cleared from the clipboard after 30s) |
+| `y` | copy the value |
 | `ctrl+s` | Go to: search everything and jump there |
 | `f` / `F` | star / your favourites |
 | `s` | copy a link to share |
 | `?` | every key, searchable |
 | `q` | quit |
 
-
 ## Integration
-Lazysecret let you integrate it into your workflows by `lazysecrets` `list`/`get`/`open`
 
-Here is an example of implementing a picker in `fzf`:
-```sh
-lazysecrets list | fzf --ansi --delimiter='\t' --with-nth='2..-3' --nth='2..' --accept-nth=-1 \
-  --header 'enter: link · ctrl-o: open · ctrl-y: copy value · ctrl-x: copy and close' \
-  --bind 'ctrl-o:become(lazysecrets open --action go --account {-2} {-1})' \
-  --bind 'ctrl-y:execute-silent(lazysecrets get --account {-2} {-1} | pbcopy)+change-header(Copied the value of {3})' \
-  --bind 'ctrl-x:become(lazysecrets get --account {-2} {-1} | pbcopy)'
-```
+`lazysecrets list`, `get` and `open` plug lazysecrets into fzf, editor
+pickers and scripts: see [Integration](docs/integration.md#an-fzf-picker).
 
 ![fzf-example](docs/assets/fzf-example.png)
 
-More defails in the [Integration](docs/integration.md) docs
-
 ## Docs
 
 - [Keys](docs/keys.md): every key, Go to, the layout, and rebinding keys

cmd/lazysecrets/main.go

@@ -150,6 +150,7 @@ func run() error {
                                   for scripts: VAR=$(lazysecrets get <ref>)
   lazysecrets [flags] list [--kind secret,…] [--cached] [--max-age 2m] [--format text|json]
                           [--color always|never] [--icons=false] [--errors=false]
+                          [--stars=false] [--notes=false] [--recent] [--expiry=false]
                                   print every source, vault and secret it can
                                   find, one per line, for fzf and pickers:
                                   what's cached at once, then what loads

docs/azure.md

@@ -16,7 +16,7 @@ A service principal is used instead when `AZURE_CLIENT_ID`,
 On an account's group row, the fourth pane shows who it signs in as: name,
 user, tenant, object ID, whether the session used MFA, directory roles
 (built-in ones by name) and its subscriptions, read from az's account list
-and the token lazysecrets already has: no requests of their own. `y` on
+and the token lazysecrets already has. `y` on
 the row copies the object ID, the one access policies and role
 assignments ask for; `l` goes into the pane, where `j`/`k` pick any
 field, `/` filters them (`/tenant`) and `y` copies the selected one.
@@ -67,9 +67,8 @@ fetched. `v` lists an item's versions. Items expiring within
 
 The status pane (`0`) lists them across every vault loaded, opened or
 cached, soonest first, and its line counts them (`⚠ 3 expiring`); `enter`
-on one goes to it. That makes no requests of its own: expiry dates come
-with the lists. It says how many vaults it covers; `ctrl+a` in search
-loads the rest.
+on one goes to it. Expiry dates come with the lists. It says how many
+vaults it covers; `ctrl+a` in search loads the rest.
 
 On a vault, the right pane shows its settings: resource group, location,
 SKU, whether access is by Azure roles or access policies, soft delete and

docs/config.md

@@ -1,10 +1,11 @@
 # Config
 
 Optional, at `~/.config/lazysecrets/config.yaml` (or
-`$XDG_CONFIG_HOME/lazysecrets/config.yaml`, or `--config`). Flags override
-it. Unknown keys are an error, so typos don't go unnoticed. `e` on the
-status pane (`0`) opens it in your editor, as in lazygit (making it if
-it isn't there yet); changes apply when lazysecrets starts again.
+`$XDG_CONFIG_HOME/lazysecrets/config.yaml`, or `--config`). Flags (noted
+below) override it. Unknown keys are an error, so typos don't go
+unnoticed. `e` on the status pane (`0`) opens it in your editor, as in
+lazygit (making it if it isn't there yet); changes apply when lazysecrets
+starts again.
 
 ```yaml
 ui:
@@ -17,7 +18,7 @@ ui:
 values:
   revealTimeout: 60s     # hide a revealed value after this long; 0s keeps it shown
   hideOnBlur: true       # hide a revealed value when the terminal loses focus (tmux: focus-events on)
-  clipboardClear: 30s    # clear copied values from the clipboard after this long; 0s disables
+  clipboardClear: 30s    # clear copied values from the clipboard after this long; 0s disables; also --clipboard-clear
 storage:
   cache: true            # keep what was loaded (never values) for the next start
   history: true          # count uses of items for Recent (R)
@@ -28,32 +29,15 @@ updates:
     - https://github.com/karleinarb/lazysecrets
     - https://git.kebcloud.no/keb/lazysecrets
 providers:
-  timeout: 30s                           # per backend request; a provider's own timeout overrides it
-  azure:                                 # applies to every az account
-    enabled: true                        # default
+  timeout: 30s           # per backend request; a provider's own timeout overrides it; also --timeout
+  azure:                 # likewise databricks and repos; azure covers every az account
+    enabled: true        # default
     timeout: 30s
-    hideSubscriptions: [platform-mgmt]   # by name or ID
-    vaults:                              # listed under "Pinned vaults", for vaults
-      - https://kv-foo.vault.azure.net/  # you can read but not discover
-  databricks:
-    enabled: true
-    timeout: 30s
-    hideProfiles: [test]
-  repos:
-    enabled: true
-    timeout: 30s
-    roots: [~/git]
-    paths: [~/work/infra]
-    include: ["secrets/**"]
-    exclude: ["**/testdata/**"]
-sharing:               # sharing env files as encrypted links
-  key: https://kv-team.vault.azure.net/secrets/env-share  # or its lazysecrets:// link; for repos naming none
-  keyRules:            # what a key's value must be
-    minLength: 32      # characters, 16 at least
-    minClasses: 2      # kinds: lowercase, uppercase, digits, symbols
 ```
 
-More, each on its own page: [repos](repos.md) (`providers.repos`),
+More, each on its own page: [Azure](azure.md#vaults-you-cant-discover)
+(`providers.azure`), [Databricks](databricks.md) (`providers.databricks`),
+[repos](repos.md#which-files) (`providers.repos`),
 [sharing env files](sharing.md#sharing-env-files) (`sharing`), the
 [link handler](sharing.md#from-the-browser-and-chat) (`linkHandler`),
 [keybindings](keys.md#rebinding-keys) (`keybinding`) and
@@ -102,9 +86,8 @@ as boxes, turn them off with `ui.icons: false`.
 
 Several config files can be layered, later ones winning (theme roles and
 keybindings merge one by one), with a comma-separated `--config` or
-`LAZYSECRETS_CONFIG_FILE`, like lazygit's `LG_CONFIG_FILE`. An editor
-plugin can so add a generated theme file to your own config, the way
-snacks.nvim themes lazygit from Neovim's highlight groups:
+`LAZYSECRETS_CONFIG_FILE`, like lazygit's `LG_CONFIG_FILE`; e.g. your
+config plus an editor-generated theme:
 
 ```sh
 LAZYSECRETS_CONFIG_FILE=~/.config/lazysecrets/config.yaml,~/.cache/nvim/lazysecrets-theme.yml lazysecrets
@@ -117,11 +100,10 @@ Stars, notes, usage and the layout are kept in
 by you: one record per source, vault or secret, keyed by its
 `lazysecrets://` link, never with values. A star belongs to the account you
 starred the item under (a vault two of your accounts can see can be starred
-for one); a note describes the item, so it shows under every account. It's
-JSON so an editor plugin can read it with a built-in parser; several
-lazysecrets windows can save to it without losing each other's changes.
-One written by a newer lazysecrets is read but not saved to, with a
-warning, until you update.
+for one); a note describes the item, so it shows under every account.
+Several lazysecrets windows can save to it without losing each other's
+changes. One written by a newer lazysecrets is read but not saved to,
+with a warning, until you update.
 
 Revealing, copying, opening in the browser, sharing and jumping to an item
 count as using it: its record keeps when it was last used and how often,
@@ -157,8 +139,9 @@ until then it reuses the answer from the state file. Releases are
 published on GitHub and on git.kebcloud.no, and it asks them in that
 order, the next when one doesn't answer within 5 seconds;
 `updates.sources` lists others, such as a mirror of your own. Offline, or with
-every server down, it says nothing. A newer release shows in the footer, `v0.1.1 ↑ v0.2.0`; `U` (or
-`lazysecrets update --check`) shows what changed since your version, across the last 10 releases.
+every server down, it says nothing. A newer release shows in the status
+pane, `↑ v0.2.0`; `U` (or `lazysecrets update --check`) shows what
+changed since your version, across the last 10 releases.
 
 Updating (`u` there, or `lazysecrets update`) downloads the release for
 your OS and CPU from the first server that has it, checks it against

docs/development.md

@@ -12,7 +12,7 @@ repo, pick `kv-shared-prod / env-share` (the second account's) as the
 key, then paste the link back. The demo repos aren't on disk, so opening
 asks where to save, as for a repo you haven't cloned.
 
-A stripped binary is about 21 MB instead of 30 MB:
+A stripped binary is a third smaller:
 
 ```sh
 go build -trimpath -ldflags "-s -w" -o lazysecrets ./cmd/lazysecrets
@@ -35,10 +35,8 @@ subject, checked by `pr-title.yml`:
 | `fix` | a bug fix | Fixed |
 | `refactor`, `docs`, `test`, `ci`, `chore`, `build`, `style`, `revert` | everything users don't need to hear about | no |
 
-`feat!:` marks a breaking change, `feat(scope):` names a part. Brackets
-and a missing space work too: `[feat] x`, `[feat]: x` and `feat:x` all
-become `feat: x` in the changelog. `[skip changelog]` in the description
-leaves a pull request out.
+`feat!:` marks a breaking change, `feat(scope):` names a part.
+`[skip changelog]` in the description leaves a pull request out.
 
 CI (`ci.yml`) runs gofmt, vet, staticcheck, the tests and a build for each
 platform on pull requests into `main`. `main` is protected: a pull request

docs/integration.md

@@ -34,7 +34,7 @@ tab-separated:
 | name | `platform-prod / kv-app-prod / db-password` |
 | status | why a vault or source couldn't be read, or that it has `expired` or `expires in 12d` (within `ui.expiryWarningDays`), or empty |
 | note | your note on it (`n` in lazysecrets), after a note icon (✎ without icons), or empty |
-| account | what it's listed through: an az account (`Azure:<user>/<tenant>`), `Databricks` or `Repos` |
+| account | what it's listed through: `Azure` (`Azure:<user>/<tenant>` with several az accounts), `Databricks` or `Repos` |
 | link | its `lazysecrets://` link |
 
 What's cached prints at once, then what loads follows as it arrives: read
@@ -47,7 +47,7 @@ so `^prod` finds names starting with prod.
 | Flag | |
 |---|---|
 | `--format json` | an object per line instead, for editor plugins (below) |
-| `--kind secret,vault` | only these kinds: `source`, `vault`, `secret`, `key`, `certificate`; lists only other kinds need aren't loaded |
+| `--kind secret,vault` | only these kinds: `source`, `vault` (also scopes and repo files), `secret`, `key`, `certificate`; lists they don't need aren't loaded |
 | `--cached` | only what's cached, at once: nothing is loaded from Azure or Databricks |
 | `--max-age 2m` | load cached lists older than this again |
 | `--errors=false` | leave out the vaults and sources it couldn't read |
@@ -77,12 +77,11 @@ may be added:
 | `expires` | when a secret, key or certificate expires, if it does (Azure) |
 | `enabled` | `false` for a disabled one; only where the provider says (Azure) |
 
-`lazysecrets open --action go --account <account> <link>` opens one in
-lazysecrets without asking what to do or which account, ending in the
-secrets list, like Go to.
+[`lazysecrets open --action go --account <account> <link>`](sharing.md#opening-a-link)
+opens one in lazysecrets without asking what to do or which account.
 
+### An fzf picker
 
-### Example usage with fzf
 ```sh
 lazysecrets list | fzf --ansi --delimiter='\t' --with-nth='2..-3' --nth='2..' --accept-nth=-1 \
   --header 'enter: link · ctrl-o: open · ctrl-y: copy value · ctrl-x: copy and close' \
@@ -90,5 +89,6 @@ lazysecrets list | fzf --ansi --delimiter='\t' --with-nth='2..-3' --nth='2..' --
   --bind 'ctrl-y:execute-silent(lazysecrets get --account {-2} {-1} | pbcopy)+change-header(Copied the value of {3})' \
   --bind 'ctrl-x:become(lazysecrets get --account {-2} {-1} | pbcopy)'
 ```
+
 ![fzf-example](assets/fzf-example.png)
 

docs/keys.md

@@ -49,7 +49,7 @@ match case exactly.
 | Key | Action |
 |---|---|
 | `space` | reveal / hide the selected value (public material for keys and certificates) |
-| `y` | copy the value without revealing it; cleared from the clipboard after 30s. On an Azure account's row: its object ID; in its pane, the selected field |
+| `y` | copy the value without revealing it. On an Azure account's row: its object ID; in its pane, the selected field |
 | `Y` | copy the reference (`@Microsoft.KeyVault(...)`, key/certificate URL, `{{secrets/scope/key}}`) |
 | `v` | versions of the selected item (Azure); `space`/`y`/`Y` then act on that version; `esc`, `⌫` or `v` to go back |
 | `o` | open the selected item in the browser (over SSH: copy the link) |
@@ -63,10 +63,8 @@ match case exactly.
 A revealed value is shown as it reads best: JSON indented, and PEM
 certificates as their subject, issuer, dates, names and thumbprint, with
 any other PEM block (a private key) named but not shown. `y` still copies
-it exactly as stored.
-
-A revealed value hides again after `values.revealTimeout` (60s) and
-when the terminal loses focus (`values.hideOnBlur`); see [config](config.md).
+it exactly as stored. It hides again after a while, and when the terminal
+loses focus ([config](config.md)).
 
 ## Stars and notes
 
@@ -75,8 +73,7 @@ when the terminal loses focus (`values.hideOnBlur`); see [config](config.md).
 | `f` | star the selected source, vault or secret: it gets a ★ and sorts first in its list |
 | `n` | write a short note on it, shown dimmed on its row and in the detail pane |
 
-A star belongs to the account you starred the item under; a note shows
-under every account. Both are kept in the [state file](config.md#state).
+Both are kept in the [state file](config.md#state).
 
 ## Go to
 
@@ -124,15 +121,16 @@ it's hidden.
 On top, the status pane (`0`) shows the version, a newer release and how
 your accounts are doing; `e` there opens your [config](config.md) in your
 editor, as in lazygit. Focused, the right pane lists more under the
-logo (when there's room): the version and updates (`U`), each account
-(`L` on one that needs it signs in), what's expiring (`enter` goes to
-it), this session's errors, newest first (what a pane showed, or the
-footer flashed before you moved on; not kept after quitting), the config,
-state and cache files (`e` opens one in your editor), and links to the
-docs, source, issues, releases and changelog (`o` opens one; on the
-version or update, its release), then the changelog of every release up
-to yours, built in so it needs no network: `/` filters it (`/fixed`,
-`/search`). `y` copies any row.
+logo; `y` copies any row:
+
+- the version and updates (`U`)
+- each account (`L` on one that needs it signs in)
+- what's expiring (`enter` goes to it)
+- this session's errors, newest first (not kept after quitting)
+- the config, state and cache files (`e` opens one in your editor)
+- links to the docs, source, issues, releases and changelog (`o` opens one)
+- the changelog of every release up to yours, built in: `/` filters it
+  (`/fixed`, `/search`)
 
 | Key | Action |
 |---|---|
@@ -141,9 +139,8 @@ to yours, built in so it needs no network: `/` filters it (`/fixed`,
 | `+` / `_` | zoom the focused pane: normal → half → full screen, and back |
 | `=` | reset the layout (divider, heights, zoom) |
 
-The divider and pane heights are remembered (zoom isn't). macOS uses
-ctrl+arrows for Mission Control and switching desktops by default, hence
-the `<` `>` `{` `}` alternatives.
+The divider and pane heights are remembered (zoom isn't). `<>{}` are for
+macOS, where ctrl+arrows switch desktops.
 
 ## Rebinding keys
 

docs/repos.md

@@ -100,13 +100,5 @@ sops 3.8 or later.
 
 ## Links
 
-`S` → `f` shares env files as an [encrypted link](sharing.md#sharing-env-files).
-
-Links name the repo by its git remote, so they open in a colleague's clone
-wherever it is:
-
-```
-lazysecrets://repo/git.example.com%2Fteam%2Finfra/secrets%2Fapp.yaml/db.password
-```
-
-See [sharing](sharing.md).
+Repo links name the repo by its git remote, so they open in a colleague's
+clone wherever it is ([sharing](sharing.md)).

docs/sharing.md

@@ -7,10 +7,13 @@ permissions: the link names the item, never its value. Env files can
 also be [shared encrypted](#sharing-env-files), in the link itself.
 
 ```
+lazysecrets://azure/subscriptions/<subscription-id>                          subscription
 lazysecrets://azure/kv-app-prod.vault.azure.net                              vault
 lazysecrets://azure/kv-app-prod.vault.azure.net/keys                         vault, Keys tab
 lazysecrets://azure/kv-app-prod.vault.azure.net/secrets/db-password          secret
 lazysecrets://azure/kv-app-prod.vault.azure.net/secrets/db-password/91d3e0   one version
+lazysecrets://databricks/adb-1111111111111111.11.azuredatabricks.net         workspace
+lazysecrets://databricks/adb-1111111111111111.11.azuredatabricks.net/app     scope
 lazysecrets://databricks/adb-1111111111111111.11.azuredatabricks.net/app/storage-key
 lazysecrets://repo/git.example.com%2Fteam%2Finfra/secrets%2Fapp.yaml/db.password
 ```
@@ -102,8 +105,8 @@ it now and then: new links use the newest version.
 ## Opening a link
 
 - Paste it into lazysecrets, or press `ctrl+o`, which reads the clipboard
-  and fills in any reference it finds there. Key Vault URLs,
-  `@Microsoft.KeyVault(...)` and `{{secrets/scope/key}}` work too.
+  and fills in any reference it finds there. Key Vault URLs, Azure portal
+  links, `@Microsoft.KeyVault(...)` and `{{secrets/scope/key}}` work too.
 - `lazysecrets <link>` (or `lazysecrets open <link>`) in a terminal.
 - Click it anywhere, once the [link handler](#from-the-browser-and-chat) is
   set up.