diff --git a/README.md b/README.md
index 2f282b3..df282f2 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,7 @@ Once installed, this package gives the agent a native way to ask for clarificati
 
 - 🧭 Familiar ask-style interface: tabbed questions, single/multi select, and preview mode
 - ✍️ Inline free-form `Type your own` answers
+- 📎 Native pi-style `@` file references inside answer and note editors
 - 📝 Question-level and option-level notes
 - 👀 Review tab with `Submit`, `Elaborate`, and `Cancel`
 - 💬 Elaboration flow to capture note-based clarification before final submission
@@ -57,6 +58,11 @@ Capture free-form input inline without leaving the flow.
 
 ![Inline custom answer input for Type your own option](docs/media/feature-custom-answer-input.png)
 
+### Native `@` file references
+Use pi-style `@` file path autocomplete inside free-form answers and note editors.
+
+![Native pi-style @ file references inside the ask flow](docs/media/feature-at-file-mentions.png)
+
 ### Option notes
 Attach clarification notes to a specific option (`n`).
 
@@ -105,7 +111,7 @@ Ask the agent to elaborate on notes before finalizing choices.
 
 After installation, the extension registers the `ask_user` tool.
 
-Agents can auto-discover and call it when they need clarification instead of guessing. In interactive sessions, it opens a terminal UI flow for structured answers and returns normalized answers back to the agent.
+Agents can auto-discover and call it when they need clarification instead of guessing. In interactive sessions, it opens a terminal UI flow for structured answers, supports native pi-style `@` file references while typing answers or notes, and returns normalized answers back to the agent.
 
 This package also bundles the `ask-user` skill profile from `skills/ask-user/SKILL.md`. It reinforces when to use the tool, is enabled by default when installed, and can be disabled via `pi config`. The skill was inspired by https://github.com/edlsh/pi-ask-user.
 
diff --git a/docs/contract.md b/docs/contract.md
index 9de4617..78ae08a 100644
--- a/docs/contract.md
+++ b/docs/contract.md
@@ -191,7 +191,7 @@ This document defines the stable external behavior. It does not explain internal
 - tabbed multi-question flow
 - single-select, multi-select, and preview questions
 - inline free-form answers for all question types
-- pi-style `@` file path autocomplete inside free-form answer and note editors
+- native pi-style `@` file path autocomplete inside free-form answer and note editors
 - question notes via `Shift+N`
 - option notes via `n`
 - number-key quick selection
diff --git a/docs/media/feature-at-file-mentions.png b/docs/media/feature-at-file-mentions.png
new file mode 100644
index 0000000..2060fbc
Binary files /dev/null and b/docs/media/feature-at-file-mentions.png differ