docs: add declarative manifest-plugins section to secrets management

concepts/secrets-management.mdx

@@ -163,6 +163,63 @@ They never touch disk.
   to add the required packages to your environment.
   </Tab>
 </Tabs>
+
+## Declarative secrets with manifest plugins
+
+<Note>
+  Manifest plugins are **experimental** and under active development.
+  The `[plugins]` section is not yet part of a stable manifest schema
+  version, and Flox versions without the feature reject a manifest
+  containing it with an "unknown field" error.
+  Details described here may change before release.
+</Note>
+
+The hook examples above hand-write the retrieval command for each secret.
+Flox is adding a declarative alternative: install a secrets plugin
+package and declare *which* secrets your environment needs in a
+`[plugins]` section of the manifest.
+The plugin performs the retrieval for you at activation.
+
+The model is the same reference-only JIT pattern: the manifest carries
+each secret's *location* in the store, never its value, so it remains
+safe to commit.
+
+For example, with the 1Password plugin (currently in development):
+
+```toml
+[install]
+1password.pkg-path = "flox/1password"
+
+[plugins.1password]
+GH_TOKEN = "op://Private/GitHub Work Token/credential"
+PGPASSWORD = "op://Private/Postgres/password"
+```
+
+Installing `flox/1password` provides the `op` CLI together with its Flox
+plugin.
+On `flox activate`, the plugin resolves each
+`op://vault/item/field` reference against your active 1Password session
+and exports the value as the named environment variable.
+
+Key behavior:
+
+- Plugin data lives under `[plugins.<pkg-name>]`, keyed by the plugin's
+  package name.
+  Each plugin defines and documents the shape of its own table; for
+  secrets plugins the convention is a flat table of
+  `ENV_VAR = "path/to/secret"`.
+- Retrieval runs during activation **before** the `on-activate` hook,
+  so hooks and `[services]` can use the variables.
+- Plugins run in the `dev` and `build` activation modes, but not in
+  `run` mode (`flox activate --mode run`).
+- Primary auth still belongs to the secret store—for example an active
+  `op` session or biometric unlock—exactly as in phase 1 of the JIT
+  pattern above, and the security properties listed above apply
+  unchanged.
+
+The manual hook pattern keeps working and remains the way to integrate
+a secret store that doesn't have a plugin.
+
 ## Rotating a secret
 
 Because the value lives in the store, not the manifest, rotation requires