diff --git a/CHANGELOG.md b/CHANGELOG.md
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.17.0.0] - 2026-11-16
+
+### Added
+
+* `exampleValue`, to document an example value of a configuration setting.
+* `decodeOnlyConfWith`, `decodeOnlyConfWith'`, `unprefixedDecodeOnlyConfWith`
+  and `unprefixedDecodeOnlyConfWith'`, for a codec that can only parse.
+
+### Changed
+
+* `confWith`, `confWith'`, `unprefixedConfWith` and `unprefixedConfWith'` take
+  a `JSONCodec`, which can also encode.
+  To migrate a codec that can only parse, like `f <$> codec`, make it encode
+  with `dimapCodec` or `bimapCodec`, or use `decodeOnlyConfWith` instead.
+  Such a `dimapCodec` or `bimapCodec` also works with older versions.
+* The Nix option of a setting with a default documents that default whenever
+  its codec can encode it, not only when it shows as JSON.
+* The Nix option of a setting with an `exampleValue` has that `example`.
+* Requires `autodocodec-nix >=0.3.0.0`.
+
 ## [0.16.0.0] - 2026-11-14
 
 ### Added
diff --git a/opt-env-conf.cabal b/opt-env-conf.cabal
--- a/opt-env-conf.cabal
+++ b/opt-env-conf.cabal
@@ -5,7 +5,7 @@
 -- see: https://github.com/sol/hpack
 
 name:           opt-env-conf
-version:        0.16.0.0
+version:        0.17.0.0
 synopsis:       Settings parsing for Haskell: command-line arguments, environment variables, and configuration values.
 homepage:       https://github.com/NorfairKing/opt-env-conf#readme
 bug-reports:    https://github.com/NorfairKing/opt-env-conf/issues
@@ -53,7 +53,7 @@
   build-depends:
       aeson
     , autodocodec >=0.3.0.0
-    , autodocodec-nix >=0.2.0.0
+    , autodocodec-nix >=0.3.0.0
     , autodocodec-schema
     , autodocodec-yaml
     , base <5
diff --git a/src/OptEnvConf.hs b/src/OptEnvConf.hs
--- a/src/OptEnvConf.hs
+++ b/src/OptEnvConf.hs
@@ -29,11 +29,16 @@
     conf,
     confWith,
     confWith',
+    decodeOnlyConfWith,
+    decodeOnlyConfWith',
     unprefixedConf,
     unprefixedConfWith,
     unprefixedConfWith',
+    unprefixedDecodeOnlyConfWith,
+    unprefixedDecodeOnlyConfWith',
     name,
     value,
+    exampleValue,
     hidden,
     metavar,
     completer,
diff --git a/src/OptEnvConf/Nix.hs b/src/OptEnvConf/Nix.hs
--- a/src/OptEnvConf/Nix.hs
+++ b/src/OptEnvConf/Nix.hs
@@ -16,6 +16,7 @@
 import qualified Data.List.NonEmpty as NE
 import Data.Map (Map)
 import qualified Data.Map as M
+import Data.Maybe (listToMaybe)
 import Data.Text (Text)
 import qualified Data.Text as T
 import OptEnvConf.Parser
@@ -78,26 +79,46 @@
                               (optionalFieldWith' p configValSettingCodec)
                               (optionalFieldWith p configValSettingCodec)
                               (T.pack <$> settingHelp s)
-                          -- The codec can only decode, so the default is only
-                          -- documented when what it shows as is a value that
-                          -- the codec accepts, like a number or a string.
-                          -- What else it shows as is Haskell, not Nix.
                           documentedDefault :: Maybe JSON.Value
                           documentedDefault = do
-                            (_, shown) <- settingDefaultValue s
-                            v <- JSON.decodeStrictText (T.pack shown)
-                            _ <- JSON.parseMaybe (parseJSONVia configValSettingCodec) v
-                            pure v
-                       in M.map (\o -> o {optionDocumentedDefault = documentedDefault}) $ objectCodecNixOptions oc
+                            (a, shown) <- settingDefaultValue s
+                            case configValSettingEncoder of
+                              Just encode -> pure (encode a)
+                              -- A codec that can only decode can still
+                              -- document the default when what it shows as is
+                              -- a value that the codec accepts, like a number
+                              -- or a string.
+                              -- What else it shows as is Haskell, not Nix.
+                              Nothing -> do
+                                v <- JSON.decodeStrictText (T.pack shown)
+                                _ <- JSON.parseMaybe (parseJSONVia configValSettingCodec) v
+                                pure v
+                          optionExampleValue :: Maybe JSON.Value
+                          optionExampleValue = do
+                            encode <- configValSettingEncoder
+                            -- A Nix option has only one example.
+                            a <- listToMaybe (settingValueExamples s)
+                            pure (encode a)
+                       in M.map
+                            ( \o ->
+                                o
+                                  { optionDocumentedDefault = documentedDefault,
+                                    optionExample = optionExampleValue
+                                  }
+                            )
+                            $ objectCodecNixOptions oc
                     Just rest ->
                       let m = go' rest
                        in M.singleton p $ emptyOption {optionType = Just (OptionTypeSubmodule m)}
                in go' $ NE.map T.pack configValSettingPath
     combineOption :: Option -> Option -> Option
-    combineOption o1 o2 = case (optionType o1, optionType o2) of
-      (Nothing, _) -> o2
-      (Just ot1, Nothing) -> o2 {optionType = Just ot1}
-      (Just ot1, Just ot2) -> o2 {optionType = Just $ combineOptionType ot1 ot2}
+    combineOption o1 o2 =
+      let o = case (optionType o1, optionType o2) of
+            (Nothing, _) -> o2
+            (Just ot1, Nothing) -> o2 {optionType = Just ot1}
+            (Just ot1, Just ot2) -> o2 {optionType = Just $ combineOptionType ot1 ot2}
+       in -- Any setting's example is a valid example for the key.
+          o {optionExample = optionExample o2 <|> optionExample o1}
 
     combineOptionType :: OptionType -> OptionType -> OptionType
     combineOptionType ot1 ot2 = simplifyOptionType $ case (ot1, ot2) of
diff --git a/src/OptEnvConf/Parser.hs b/src/OptEnvConf/Parser.hs
--- a/src/OptEnvConf/Parser.hs
+++ b/src/OptEnvConf/Parser.hs
@@ -902,6 +902,7 @@
             settingConfigVals = Nothing,
             settingDefaultValue = Nothing,
             settingExamples = [],
+            settingValueExamples = [],
             settingHidden = True,
             settingMetavar = Nothing,
             settingHelp = Nothing,
@@ -921,6 +922,7 @@
             settingConfigVals = Nothing,
             settingDefaultValue = Nothing,
             settingExamples = [],
+            settingValueExamples = [],
             settingHidden = True,
             settingMetavar = Nothing,
             settingHelp = Nothing,
@@ -943,6 +945,7 @@
               settingConfigVals = Nothing,
               settingDefaultValue = Nothing,
               settingExamples = [],
+              settingValueExamples = [],
               settingHidden = False,
               settingMetavar = Just "BOOL",
               settingHelp = settingHelp s,
@@ -964,6 +967,7 @@
               settingConfigVals = Just ne,
               settingDefaultValue = Nothing,
               settingExamples = [],
+              settingValueExamples = settingValueExamples s,
               settingHidden = False,
               settingMetavar = Nothing,
               settingHelp = settingHelp s,
@@ -983,6 +987,7 @@
             settingConfigVals = Nothing,
             settingDefaultValue = Nothing,
             settingExamples = [],
+            settingValueExamples = [],
             settingHidden = False,
             settingMetavar = Nothing,
             settingHelp = settingHelp s,
@@ -1011,6 +1016,8 @@
 
 -- | Load a secret from a text file, with 'readSecretTextFile', or specify it
 -- directly
+--
+-- It ignores any 'exampleValue'.
 secretTextFileOrBareSetting :: (HasCallStack) => [Builder FilePath] -> Parser Text
 secretTextFileOrBareSetting bs =
   withFrozenCallStack $
@@ -1025,7 +1032,13 @@
         ]
   where
     mLoc = snd <$> listToMaybe (getCallStack callStack)
-    b = mconcat $ bs ++ [reader str]
+    -- One example value would document a secret for the bare config setting
+    -- and a path for the file config setting, so it cannot mean either.
+    b = mconcat $ map (mapMaybeBuilder dropValueExample) bs ++ [reader str]
+    dropValueExample :: BuildInstruction FilePath -> Maybe (BuildInstruction FilePath)
+    dropValueExample = \case
+      BuildAddValueExample _ -> Nothing
+      i -> Just i
     bareSetting p f = do
       let s = completeBuilder $ mconcat [mapMaybeBuilder f b, reader str, metavar "SECRET"]
       guard $ p s
diff --git a/src/OptEnvConf/Setting.hs b/src/OptEnvConf/Setting.hs
--- a/src/OptEnvConf/Setting.hs
+++ b/src/OptEnvConf/Setting.hs
@@ -27,14 +27,19 @@
     conf,
     confWith,
     confWith',
+    decodeOnlyConfWith,
+    decodeOnlyConfWith',
     unprefixedConf,
     unprefixedConfWith,
     unprefixedConfWith',
+    unprefixedDecodeOnlyConfWith,
+    unprefixedDecodeOnlyConfWith',
     name,
     value,
     valueWithShown,
     example,
     shownExample,
+    exampleValue,
     hidden,
     completer,
     Builder (..),
@@ -59,6 +64,7 @@
 where
 
 import Autodocodec
+import qualified Data.Aeson as JSON
 import Data.Hashable
 import Data.List.NonEmpty (NonEmpty (..), (<|))
 import qualified Data.List.NonEmpty as NE
@@ -102,6 +108,8 @@
     settingDefaultValue :: !(Maybe (a, String)),
     -- | Example values
     settingExamples :: ![String],
+    -- | Example values, rendered with the 'configValSettingEncoder's
+    settingValueExamples :: ![a],
     -- | Whether to hide docs
     settingHidden :: !Bool,
     -- | Which metavar should be show in documentation
@@ -157,7 +165,10 @@
   ConfigValSetting
   { configValSettingPath :: !(NonEmpty String),
     configValSettingAllowPrefix :: !Bool,
-    configValSettingCodec :: !(ValueCodec void (Maybe a))
+    configValSettingCodec :: !(ValueCodec void (Maybe a)),
+    -- | How to render a value as what 'configValSettingCodec' parses, if
+    -- that codec can encode.
+    configValSettingEncoder :: !(Maybe (a -> JSON.Value))
   }
 
 prefixConfigValSetting :: String -> ConfigValSetting a -> ConfigValSetting a
@@ -188,6 +199,7 @@
       settingMetavar = Nothing,
       settingHelp = Nothing,
       settingExamples = [],
+      settingValueExamples = [],
       settingHidden = False,
       settingDefaultValue = Nothing,
       settingCompleter = Nothing,
@@ -197,7 +209,7 @@
 -- | Show a 'Setting' as much as possible, for debugging
 showSettingABit :: Setting a -> ShowS
 showSettingABit Setting {..} =
-  let Setting _ _ _ _ _ _ _ _ _ _ _ _ _ _ = undefined
+  let Setting _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ = undefined
    in showParen True $
         showString "Setting "
           . showsPrec 11 settingDasheds
@@ -218,6 +230,8 @@
           . showString " "
           . showsPrec 11 settingExamples
           . showString " "
+          . showListWith (\_ -> showString "_") settingValueExamples
+          . showString " "
           . showsPrec 11 settingHidden
           . showString " "
           . showsPrec 11 settingMetavar
@@ -234,6 +248,8 @@
     . showsPrec 11 configValSettingPath
     . showString " "
     . showString (showCodecABit configValSettingCodec)
+    . showString " "
+    . showMaybeWith (\_ -> showString "_") configValSettingEncoder
 
 showMaybeWith :: (a -> ShowS) -> Maybe a -> ShowS
 showMaybeWith _ Nothing = showString "Nothing"
@@ -262,6 +278,7 @@
   | BuildAddConf !(ConfigValSetting a)
   | BuildSetDefault !a !String
   | BuildAddExample !String
+  | BuildAddValueExample !a
   | BuildSetHidden
   | BuildSetCompleter !Completer
   | BuildAddRequiredCapability !Capability
@@ -283,6 +300,7 @@
   BuildAddConf t -> s {settingConfigVals = Just $ maybe (t :| []) (t <|) $ settingConfigVals s}
   BuildSetDefault a shown -> s {settingDefaultValue = Just (a, shown)}
   BuildAddExample e -> s {settingExamples = e : settingExamples s}
+  BuildAddValueExample a -> s {settingValueExamples = a : settingValueExamples s}
   BuildSetHidden -> s {settingHidden = True}
   BuildSetCompleter c -> s {settingCompleter = Just c}
   BuildAddRequiredCapability c -> s {settingRequiredCapabilities = Set.insert c (settingRequiredCapabilities s)}
@@ -385,39 +403,76 @@
 conf k = confWith k codec
 
 -- | Like 'conf' but with a custom 'Codec' for parsing the value.
-confWith :: String -> ValueCodec void a -> Builder a
+--
+-- The codec is also used to render the default value and the
+-- 'exampleValue's in documentation, so it should parse what it renders back
+-- to the same value.
+-- A codec mapped with 'fmap' usually does not, because 'fmap' only changes how
+-- it parses.
+confWith :: String -> JSONCodec a -> Builder a
 confWith k c = confWith' k (maybeCodec c)
 
 -- | Like 'confWith' but allows interpreting 'Null' as a value other than "Not found".
-confWith' :: String -> ValueCodec void (Maybe a) -> Builder a
-confWith' k c =
-  let t =
-        ConfigValSetting
-          { configValSettingPath = k :| [],
-            configValSettingAllowPrefix = True,
-            configValSettingCodec = c
-          }
-   in Builder [BuildAddConf t]
+confWith' :: String -> JSONCodec (Maybe a) -> Builder a
+confWith' = bidirectionalConfigVal True
 
+-- | Like 'confWith' but for a codec that can only parse.
+--
+-- Prefer 'confWith': the default value and the 'exampleValue's of a setting
+-- whose codec cannot encode are not rendered in documentation.
+decodeOnlyConfWith :: String -> ValueCodec void a -> Builder a
+decodeOnlyConfWith k c = decodeOnlyConfWith' k (maybeCodec c)
+
+-- | Like 'confWith'' but for a codec that can only parse.
+--
+-- Prefer 'confWith''; see 'decodeOnlyConfWith'.
+decodeOnlyConfWith' :: String -> ValueCodec void (Maybe a) -> Builder a
+decodeOnlyConfWith' = decodeOnlyConfigVal True
+
 -- | Like 'conf' but ignores any 'subConf', 'subConf_', or 'subAll'.
 unprefixedConf :: (HasCodec a) => String -> Builder a
 unprefixedConf k = unprefixedConfWith k codec
 
 -- | Like 'confWith' but ignores any 'subConf', 'subConf_', or 'subAll'.
-unprefixedConfWith :: String -> ValueCodec void a -> Builder a
+unprefixedConfWith :: String -> JSONCodec a -> Builder a
 unprefixedConfWith k c = unprefixedConfWith' k (maybeCodec c)
 
 -- | Like 'confWith'' but ignores any 'subConf', 'subConf_', or 'subAll'.
-unprefixedConfWith' :: String -> ValueCodec void (Maybe a) -> Builder a
-unprefixedConfWith' k c =
-  let t =
+unprefixedConfWith' :: String -> JSONCodec (Maybe a) -> Builder a
+unprefixedConfWith' = bidirectionalConfigVal False
+
+-- | Like 'decodeOnlyConfWith' but ignores any 'subConf', 'subConf_', or 'subAll'.
+unprefixedDecodeOnlyConfWith :: String -> ValueCodec void a -> Builder a
+unprefixedDecodeOnlyConfWith k c = unprefixedDecodeOnlyConfWith' k (maybeCodec c)
+
+-- | Like 'decodeOnlyConfWith'' but ignores any 'subConf', 'subConf_', or 'subAll'.
+unprefixedDecodeOnlyConfWith' :: String -> ValueCodec void (Maybe a) -> Builder a
+unprefixedDecodeOnlyConfWith' = decodeOnlyConfigVal False
+
+bidirectionalConfigVal :: Bool -> String -> JSONCodec (Maybe a) -> Builder a
+bidirectionalConfigVal allowPrefix k c =
+  Builder
+    [ BuildAddConf
         ConfigValSetting
           { configValSettingPath = k :| [],
-            configValSettingAllowPrefix = False,
-            configValSettingCodec = c
+            configValSettingAllowPrefix = allowPrefix,
+            configValSettingCodec = c,
+            configValSettingEncoder = Just (toJSONVia c . Just)
           }
-   in Builder [BuildAddConf t]
+    ]
 
+decodeOnlyConfigVal :: Bool -> String -> ValueCodec void (Maybe a) -> Builder a
+decodeOnlyConfigVal allowPrefix k c =
+  Builder
+    [ BuildAddConf
+        ConfigValSetting
+          { configValSettingPath = k :| [],
+            configValSettingAllowPrefix = allowPrefix,
+            configValSettingCodec = c,
+            configValSettingEncoder = Nothing
+          }
+    ]
+
 -- | Short-hand function for 'option', 'long', 'env', and 'conf' at the same time.
 --
 -- Multiple 'name's will be tried in order.
@@ -456,6 +511,15 @@
 -- This only makes sense if you use 'reader' 'auto'.
 shownExample :: (Show a) => a -> Builder a
 shownExample = example . show
+
+-- | Provide an example value for the generated Nix option type.
+--
+-- It is rendered with the codec of each 'conf', so it is not rendered for a
+-- 'decodeOnlyConfWith'.
+-- Only the first 'exampleValue' is rendered, because a Nix option has one
+-- example.
+exampleValue :: a -> Builder a
+exampleValue a = Builder [BuildAddValueExample a]
 
 -- | Don't show this setting in documentation
 --
