diff --git a/examples/QuickStart.hs b/examples/QuickStart.hs
new file mode 100644
--- /dev/null
+++ b/examples/QuickStart.hs
@@ -0,0 +1,22 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+import qualified Data.Map.Strict as Map
+import Data.Function ((&))
+import qualified SecretSpec as S
+
+main :: IO ()
+main = do
+  resolved <-
+    S.load
+      ( S.builder
+          & S.withProvider "keyring://"
+          & S.withProfile "production"
+          & S.withReason "boot web app"
+      )
+
+  print (S.resolvedProvider resolved, S.resolvedProfile resolved)
+  case Map.lookup "DATABASE_URL" (S.resolvedSecrets resolved) of
+    Just db -> print (S.get db) -- the value, or the file path for as_path secrets
+    Nothing -> pure ()
+  S.setAsEnv resolved           -- export everything into the process environment
+  S.close resolved
diff --git a/examples/Report.hs b/examples/Report.hs
new file mode 100644
--- /dev/null
+++ b/examples/Report.hs
@@ -0,0 +1,9 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+import Data.Function ((&))
+import qualified SecretSpec as S
+
+main :: IO ()
+main = do
+  rep <- S.report (S.builder & S.withProfile "production")
+  mapM_ (\s -> print (S.srName s, S.srStatus s, S.srRequired s)) (S.reportSecrets rep)
diff --git a/examples/Scopes.hs b/examples/Scopes.hs
new file mode 100644
--- /dev/null
+++ b/examples/Scopes.hs
@@ -0,0 +1,9 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+import Data.Function ((&))
+import qualified SecretSpec as S
+
+main :: IO ()
+main = do
+  resolved <- S.load (S.builder & S.withScope "api")
+  S.close resolved
diff --git a/secretspec.cabal b/secretspec.cabal
--- a/secretspec.cabal
+++ b/secretspec.cabal
@@ -1,6 +1,6 @@
 cabal-version:      2.4
 name:               secretspec
-version:            0.18.0
+version:            0.19.0
 synopsis:           Haskell SDK for SecretSpec, a declarative secrets manager
 description:
   A thin client over the @secretspec-ffi@ C ABI (linked at build time).
@@ -15,6 +15,13 @@
 category:           Configuration
 build-type:         Simple
 
+flag use-pkg-config
+  description:
+    Locate secretspec_ffi and its link dependencies through pkg-config
+    (secretspec_ffi.pc) instead of command-line library and linker paths.
+  default:            False
+  manual:             True
+
 library
   exposed-modules:    SecretSpec
   hs-source-dirs:     src
@@ -24,13 +31,48 @@
                     , containers <1
                     , directory  <2
                     , text       <3
-  -- The native resolver, statically linked at build time. Point --extra-lib-dirs
-  -- at a directory containing ONLY libsecretspec_ffi.a (so -lsecretspec_ffi
-  -- resolves to the archive, not a co-located .so), and pass the archive's
-  -- transitive native deps via --ghc-options=-optl<lib> (capture them with
+  -- The native resolver is linked at build time. The default path below uses
+  -- the static archive; pkg-config may select a static or shared install.
+  --
+  -- Without the flag: point --extra-lib-dirs at a directory containing ONLY
+  -- libsecretspec_ffi.a (so -lsecretspec_ffi resolves to the archive, not a
+  -- co-located .so), and pass the archive's transitive native deps via
+  -- --ghc-options=-optl<lib> (capture them with
   -- `cargo rustc -p secretspec-ffi --crate-type staticlib -- --print native-static-libs`).
-  -- The Rust code is embedded in the binary, so no LD_LIBRARY_PATH is needed.
-  extra-libraries:    secretspec_ffi
+  if flag(use-pkg-config)
+    pkgconfig-depends: secretspec_ffi
+  else
+    extra-libraries:  secretspec_ffi
+  -- The Darwin frameworks among the archive's native dependencies, declared
+  -- so every final link (executable, test-suite, ghci) receives them through
+  -- the compiler driver.
+  if os(darwin)
+    frameworks:       SystemConfiguration Security CoreFoundation
+  default-language:   Haskell2010
+  ghc-options:        -Wall
+
+executable secretspec-quick-start-example
+  main-is:            QuickStart.hs
+  hs-source-dirs:     examples
+  build-depends:      base
+                    , containers
+                    , secretspec
+  default-language:   Haskell2010
+  ghc-options:        -Wall
+
+executable secretspec-scopes-example
+  main-is:            Scopes.hs
+  hs-source-dirs:     examples
+  build-depends:      base
+                    , secretspec
+  default-language:   Haskell2010
+  ghc-options:        -Wall
+
+executable secretspec-report-example
+  main-is:            Report.hs
+  hs-source-dirs:     examples
+  build-depends:      base
+                    , secretspec
   default-language:   Haskell2010
   ghc-options:        -Wall
 
diff --git a/src/SecretSpec.hs b/src/SecretSpec.hs
--- a/src/SecretSpec.hs
+++ b/src/SecretSpec.hs
@@ -63,9 +63,9 @@
 import           System.Directory (doesFileExist, removeFile)
 import qualified System.Environment.Blank as Env
 
--- The three C ABI functions, statically linked at build time (the archive
--- libsecretspec_ffi.a is embedded; -lsecretspec_ffi resolves to it). They are
--- declared @safe@ because @secretspec_resolve@ may block on provider I/O
+-- The three C ABI functions, linked at build time. The default build embeds the
+-- static archive; pkg-config builds may use a static or shared install. They
+-- are declared @safe@ because @secretspec_resolve@ may block on provider I/O
 -- (1Password, LastPass), and a @safe@ call lets other Haskell threads run.
 foreign import ccall safe "secretspec_resolve"
   c_secretspec_resolve :: CString -> IO CString