diff --git a/.changeset/prompt-context-feature-undocumented.md b/.changeset/prompt-context-feature-undocumented.md
new file mode 100644
index 0000000..4569d49
--- /dev/null
+++ b/.changeset/prompt-context-feature-undocumented.md
@@ -0,0 +1,5 @@
+---
+"@generata/core": patch
+---
+
+docs: document promptContext feature for injecting file context into agent prompts
diff --git a/packages/core/README.md b/packages/core/README.md
index 01d3191..e4fae04 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -29,6 +29,33 @@ defineWorkflow({
 });
 ```
 
+## Prompt context
+
+Every LLM-backed agent (`worker`, `critic`, `planner`, `dispatcher`) accepts a `promptContext` array on its `defineAgent` options. Each entry names a file to inject into the agent's prompt as an `<context file="...">...</context>` XML block, prepended before the task body. The engine - not the agent author - owns the framing, so templates never need to say "you have X above".
+
+```ts
+defineAgent({
+  type: "worker",
+  description: "...",
+  modelTier: "standard",
+  promptContext: [
+    { filepath: "NOTES.md" },                       // required, full file
+    { filepath: "CHANGELOG.md", head: 40 },         // first 40 lines only
+    { filepath: "logs/run.log", tail: 200 },        // last 200 lines only
+    { filepath: "memory/progress.txt", optional: true }, // skipped if missing
+    { filepath: ({ slug }) => `projects/${slug}/SPEC.md` }, // resolved per-call
+  ],
+  prompt: `...`,
+});
+```
+
+| Field      | Type                                          | Behaviour                                                                 |
+| :--------- | :-------------------------------------------- | :------------------------------------------------------------------------ |
+| `filepath` | `string \| (vars: ContextVars) => string`     | Resolved relative to the run's working directory. Function form receives the same strict variables as `prompt`, so it can interpolate workflow inputs / step outputs. |
+| `head`     | `number` (optional)                           | Keep only the first N lines of the file.                                   |
+| `tail`     | `number` (optional)                           | Keep only the last N lines. Combine with `head` to take a head-then-tail slice. |
+| `optional` | `boolean` (optional)                          | If `true` and the file is missing, the entry is skipped silently - no tag, no warning. If `false` (default) and the file is missing, the engine renders `<context file="..." status="missing" />` and prints a `[context] <agent>: '<path>' not found` warning to stderr. Use `optional: true` for files that are expected to be absent on fresh systems (e.g. `memory/progress.txt`). |
+
 ## Running workflows from code
 
 `@generata/core` exposes `runWorkflow` and `runAgent` so you can drive any workflow or agent from your own TypeScript without going through the CLI. This is the primitive for loops, batch jobs, or wrapping generata in a larger script.
diff --git a/packages/templates/README.md b/packages/templates/README.md
index 29a1723..4417a1d 100644
--- a/packages/templates/README.md
+++ b/packages/templates/README.md
@@ -103,6 +103,24 @@ export default defineAgent<{ slug: string }>(({ slug }) => ({
 
 The filename becomes the agent or workflow name. Every `.ts` under `agents/` is scanned recursively and classified by its default export - `defineAgent` makes it an agent, `defineWorkflow` makes it a workflow. Workflows belong in `agents/workflows/` by convention (used by `standup` and `coding`); the `starter` template uses flat `agents/` placement, which works equally well for projects with a single workflow.
 
+## Injecting file context into prompts
+
+Agents can declare `promptContext` to read files into their prompt without hand-rolling `read` tool calls. The [`coding`](./coding) template uses this to feed `NOTES.md` into the spec creator:
+
+```ts
+defineAgent({
+  type: "worker",
+  // ...
+  promptContext: [
+    { filepath: "NOTES.md" },
+    { filepath: "memory/progress.txt", optional: true },
+  ],
+  prompt: `...`,
+});
+```
+
+Each entry supports `head` / `tail` line caps and an `optional` flag - when `optional: true`, a missing file is silently skipped; otherwise the engine injects `<context file="..." status="missing" />` and warns to stderr. Full field reference in [`@generata/core` README](../core/README.md#prompt-context).
+
 ## The manifest
 
 `generata.template.json` is the only required file. Minimal example: