diff --git a/.changeset/global-config-fields-not-documented.md b/.changeset/global-config-fields-not-documented.md
new file mode 100644
index 0000000..e05256c
--- /dev/null
+++ b/.changeset/global-config-fields-not-documented.md
@@ -0,0 +1,5 @@
+---
+"@generata/core": patch
+---
+
+docs: add GlobalConfig field reference table
diff --git a/README.md b/README.md
index 0a28d76..96b6a22 100644
--- a/README.md
+++ b/README.md
@@ -66,6 +66,7 @@ export default defineConfig({
     standard: "claude-sonnet-4-6",
     light: "claude-haiku-4-5-20251001",
   },
+  verboseOutput: true, // stream each agent's raw Claude output to the console
 });
 ```
 
diff --git a/packages/core/README.md b/packages/core/README.md
index 56d5245..7e758c5 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -173,6 +173,26 @@ Looking to expose workflows over HTTP? See [`@generata/serve`](../serve).
 
 Workflow flags: `--worktree` forces git-worktree isolation for the run; `--local` forces it off (mutually exclusive).
 
+## Config reference
+
+Every field accepted by `defineConfig` (i.e. the `GlobalConfig` schema):
+
+| Field                              | Type                       | Default    | Description                                                                          |
+| :--------------------------------- | :------------------------- | :--------- | :----------------------------------------------------------------------------------- |
+| `modelTiers.heavy/standard/light`  | `string`                   | (required) | Model IDs for each cost tier                                                         |
+| `workDir`                          | `string`                   | (required) | Root directory for worktree isolation                                                |
+| `agentsDir`                        | `string`                   | `"agents"` | Directory scanned for agent definition files                                         |
+| `metricsDir`                       | `string`                   | `"metrics"`| Directory where per-run metrics JSON files are written                               |
+| `logsDir`                          | `string`                   | `"logs"`   | Directory where prompt logs are written (when `logPrompts` is true)                  |
+| `logPrompts`                       | `boolean`                  | `true`     | Write full prompt/response logs for every run                                        |
+| `verboseOutput`                    | `boolean`                  | `false`    | Stream each agent's raw Claude output to the console                                 |
+| `showPricing`                      | `boolean`                  | `false`    | Print token cost breakdown after each run                                            |
+| `showWeeklyMetrics`                | `boolean`                  | `true`     | Print a weekly usage summary on CLI startup                                          |
+| `notifications`                    | `boolean`                  | `true`     | Send OS/Telegram notifications on workflow completion                                |
+| `maxCriticRetries`                 | `number`                   | `3`        | How many times a critic agent may loop before the step fails                         |
+| `telegram`                         | `{ botToken, chatId }`     | -          | Telegram bot credentials for completion notifications (requires `notifications: true`) |
+| `serve`                            | `unknown`                  | -          | Passed through to `@generata/serve`; core does not validate the shape                |
+
 ## Template specifiers
 
 `generata init` accepts: