diff --git a/docs/index.adoc b/docs/index.adoc
index 2564c1371..eba28c9d3 100644
--- a/docs/index.adoc
+++ b/docs/index.adoc
@@ -12409,7 +12409,7 @@ public class CDIFactory implements IFactory {
         if (instance.isResolvable()) {
             return instance.get();
         }
-        return defaultFactory.create(cls);
+        return fallbackFactory.create(cls);
     }
 }
 ----
@@ -12421,9 +12421,13 @@ How to use the above factory depends on the specific container, but in general i
 @Command(name = "cdi-app", mixinStandardHelpOptions = true)
 class MyCDIApp implements Runnable {
 
-    @Option(names = {"-x", "--option"}, description = "example option")
     boolean flag;
 
+    @Option(names = {"-x", "--option"}, description = "example option")
+    public void setFlag(boolean flag) {
+        this.flag = flag;
+    }
+
     @Override
     public void run() {
         // business logic
@@ -12436,6 +12440,14 @@ class MyCDIApp implements Runnable {
 }
 ----
 
+[IMPORTANT]
+====
+Depending on your configuration, CDI may use dynamic proxies for managed instances.
+
+The safest thing to do in CDI applications is to use public <<option-parameters-methods,annotated **setter methods**>> for picocli's `@Option` and `@Parameters`, `@Spec`, and other annotations. 
+Using picocli annotations on fields or on non-public methods may result in picocli-injected values not being available in the proxied instance.
+====
+
 == Java 9 JPMS Modules
 
 The main `picocli-${version}.jar` is a JPMS module named `info.picocli`.
diff --git a/docs/index.html b/docs/index.html
index 04d2cbf0b..62b5f5478 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -1709,81 +1709,81 @@
     });
 });
 </script>
-<style>
-.hidden {
-    display: none;
-}
-
-.switch {
-    border-width: 1px 1px 0 1px;
-    border-style: solid;
-    border-color: #7a2518;
-    display: inline-block;
-}
-
-.switch--item {
-    padding: 10px;
-    background-color: #ffffff;
-    color: #7a2518;
-    display: inline-block;
-    cursor: pointer;
-}
-
-.switch--item.selected {
-    background-color: #7a2519;
-    color: #ffffff;
-}
-
-</style>
-<script src="https://cdnjs.cloudflare.com/ajax/libs/zepto/1.2.0/zepto.min.js"></script>
-<script type="text/javascript">
-function addBlockSwitches() {
-    $('.primary').each(function() {
-        primary = $(this);
-        createSwitchItem(primary, createBlockSwitch(primary)).item.addClass("selected");
-        primary.children('.title').remove();
-    });
-    $('.secondary').each(function(idx, node) {
-        secondary = $(node);
-        primary = findPrimary(secondary);
-        switchItem = createSwitchItem(secondary, primary.children('.switch'));
-        switchItem.content.addClass('hidden');
-        findPrimary(secondary).append(switchItem.content);
-        secondary.remove();
-    });
-}
-
-function createBlockSwitch(primary) {
-    blockSwitch = $('<div class="switch"></div>');
-    primary.prepend(blockSwitch);
-    return blockSwitch;
-}
-
-function findPrimary(secondary) {
-    candidate = secondary.prev();
-    while (!candidate.is('.primary')) {
-        candidate = candidate.prev();
-    }
-    return candidate;
-}
-
-function createSwitchItem(block, blockSwitch) {
-    blockName = block.children('.title').text();
-    content = block.children('.content').first().append(block.next('.colist'));
-    item = $('<div class="switch--item">' + blockName + '</div>');
-    item.on('click', '', content, function(e) {
-        $(this).addClass('selected');
-        $(this).siblings().removeClass('selected');
-        e.data.siblings('.content').addClass('hidden');
-        e.data.removeClass('hidden');
-    });
-    blockSwitch.append(item);
-    return {'item': item, 'content': content};
-}
-
-$(addBlockSwitches);
-
-</script>
+<style>
+.hidden {
+    display: none;
+}
+
+.switch {
+    border-width: 1px 1px 0 1px;
+    border-style: solid;
+    border-color: #7a2518;
+    display: inline-block;
+}
+
+.switch--item {
+    padding: 10px;
+    background-color: #ffffff;
+    color: #7a2518;
+    display: inline-block;
+    cursor: pointer;
+}
+
+.switch--item.selected {
+    background-color: #7a2519;
+    color: #ffffff;
+}
+
+</style>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/zepto/1.2.0/zepto.min.js"></script>
+<script type="text/javascript">
+function addBlockSwitches() {
+    $('.primary').each(function() {
+        primary = $(this);
+        createSwitchItem(primary, createBlockSwitch(primary)).item.addClass("selected");
+        primary.children('.title').remove();
+    });
+    $('.secondary').each(function(idx, node) {
+        secondary = $(node);
+        primary = findPrimary(secondary);
+        switchItem = createSwitchItem(secondary, primary.children('.switch'));
+        switchItem.content.addClass('hidden');
+        findPrimary(secondary).append(switchItem.content);
+        secondary.remove();
+    });
+}
+
+function createBlockSwitch(primary) {
+    blockSwitch = $('<div class="switch"></div>');
+    primary.prepend(blockSwitch);
+    return blockSwitch;
+}
+
+function findPrimary(secondary) {
+    candidate = secondary.prev();
+    while (!candidate.is('.primary')) {
+        candidate = candidate.prev();
+    }
+    return candidate;
+}
+
+function createSwitchItem(block, blockSwitch) {
+    blockName = block.children('.title').text();
+    content = block.children('.content').first().append(block.next('.colist'));
+    item = $('<div class="switch--item">' + blockName + '</div>');
+    item.on('click', '', content, function(e) {
+        $(this).addClass('selected');
+        $(this).siblings().removeClass('selected');
+        e.data.siblings('.content').addClass('hidden');
+        e.data.removeClass('hidden');
+    });
+    blockSwitch.append(item);
+    return {'item': item, 'content': content};
+}
+
+$(addBlockSwitches);
+
+</script>
 
 </head>
 <body class="article toc2 toc-left">
@@ -17486,7 +17486,7 @@ <h3 id="_cdi_2_0_jsr_365"><a class="anchor" href="#_cdi_2_0_jsr_365"></a>22.5. C
         <span class="k">if</span> <span class="o">(</span><span class="n">instance</span><span class="o">.</span><span class="na">isResolvable</span><span class="o">())</span> <span class="o">{</span>
             <span class="k">return</span> <span class="n">instance</span><span class="o">.</span><span class="na">get</span><span class="o">();</span>
         <span class="o">}</span>
-        <span class="k">return</span> <span class="n">defaultFactory</span><span class="o">.</span><span class="na">create</span><span class="o">(</span><span class="n">cls</span><span class="o">);</span>
+        <span class="k">return</span> <span class="n">fallbackFactory</span><span class="o">.</span><span class="na">create</span><span class="o">(</span><span class="n">cls</span><span class="o">);</span>
     <span class="o">}</span>
 <span class="o">}</span></code></pre>
 </div>
@@ -17499,9 +17499,13 @@ <h3 id="_cdi_2_0_jsr_365"><a class="anchor" href="#_cdi_2_0_jsr_365"></a>22.5. C
 <pre class="rouge highlight"><code data-lang="java"><span class="nd">@Command</span><span class="o">(</span><span class="n">name</span> <span class="o">=</span> <span class="s">"cdi-app"</span><span class="o">,</span> <span class="n">mixinStandardHelpOptions</span> <span class="o">=</span> <span class="kc">true</span><span class="o">)</span>
 <span class="kd">class</span> <span class="nc">MyCDIApp</span> <span class="kd">implements</span> <span class="nc">Runnable</span> <span class="o">{</span>
 
-    <span class="nd">@Option</span><span class="o">(</span><span class="n">names</span> <span class="o">=</span> <span class="o">{</span><span class="s">"-x"</span><span class="o">,</span> <span class="s">"--option"</span><span class="o">},</span> <span class="n">description</span> <span class="o">=</span> <span class="s">"example option"</span><span class="o">)</span>
     <span class="kt">boolean</span> <span class="n">flag</span><span class="o">;</span>
 
+    <span class="nd">@Option</span><span class="o">(</span><span class="n">names</span> <span class="o">=</span> <span class="o">{</span><span class="s">"-x"</span><span class="o">,</span> <span class="s">"--option"</span><span class="o">},</span> <span class="n">description</span> <span class="o">=</span> <span class="s">"example option"</span><span class="o">)</span>
+    <span class="kd">public</span> <span class="kt">void</span> <span class="nf">setFlag</span><span class="o">(</span><span class="kt">boolean</span> <span class="n">flag</span><span class="o">)</span> <span class="o">{</span>
+        <span class="k">this</span><span class="o">.</span><span class="na">flag</span> <span class="o">=</span> <span class="n">flag</span><span class="o">;</span>
+    <span class="o">}</span>
+
     <span class="nd">@Override</span>
     <span class="kd">public</span> <span class="kt">void</span> <span class="nf">run</span><span class="o">()</span> <span class="o">{</span>
         <span class="c1">// business logic</span>
@@ -17514,6 +17518,24 @@ <h3 id="_cdi_2_0_jsr_365"><a class="anchor" href="#_cdi_2_0_jsr_365"></a>22.5. C
 <span class="o">}</span></code></pre>
 </div>
 </div>
+<div class="admonitionblock important">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-important" title="Important"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>Depending on your configuration, CDI may use dynamic proxies for managed instances.</p>
+</div>
+<div class="paragraph">
+<p>The safest thing to do in CDI applications is to use public <a href="#option-parameters-methods">annotated <strong>setter methods</strong></a> for picocli&#8217;s <code>@Option</code> and <code>@Parameters</code>, <code>@Spec</code>, and other annotations.
+Using picocli annotations on fields or on non-public methods may result in picocli-injected values not being available in the proxied instance.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
 </div>
 </div>
 </div>
@@ -19140,4 +19162,4 @@ <h3 id="_source"><a class="anchor" href="#_source"></a>37.2. Source</h3>
     handleTocOnResize();
 </script>
 </body>
-</html>
\ No newline at end of file
+</html>