diff --git a/doc/lessons-learned.md b/doc/lessons-learned.md
index e84f6a2..df48ca9 100644
--- a/doc/lessons-learned.md
+++ b/doc/lessons-learned.md
@@ -22,6 +22,24 @@ pre-optimizer for the model's action space: it narrows the likely useful
 capabilities while leaving final selection, tool loading, argument generation,
 and execution to the normal agent loop.
 
+## Architecture beats prompting alone
+
+The larger lesson is that reliable agent behavior cannot be achieved by prompt
+wording alone. Prompting tells the model what behavior is desired, but it does
+not reliably solve capability discovery for smaller models. The local embedding
+model and injected user-facing guidance work together as runtime architecture:
+
+- embeddings select the relevant capabilities before generation;
+- injected prompts explain how and when to use those capabilities;
+- bounded tool and skill disclosure preserves context for the task;
+- the agent loop and toolsrv enforce the resulting execution path.
+
+This combination moves behavior that would otherwise require repeated model
+reasoning into deterministic runtime preparation. The model still decides and
+acts, but it starts with the right capabilities and explicit operational
+instructions. In practice, this is more effective than adding more prompt text
+or expecting a small model to discover the complete tool surface unaided.
+
 ## Progressive disclosure beats a complete catalog
 
 Injecting every tool and skill into every prompt consumes context and makes