Update docs

Author: Aksem

docs/concepts.md

@@ -53,7 +53,7 @@ flowchart LR
 
 **Sequential mode** (default): handlers run one after another. Each handler can read the accumulated result so far via `context.current_result`. Useful when handlers depend on each other's output (e.g. formatter → save-to-disk).
 
-**Concurrent mode** (`run_handlers_concurrently: true`): all handlers run in parallel and results are merged afterward. Accessing `context.current_result` in concurrent mode raises `RuntimeError`. Useful for independent linters.
+**Concurrent mode** (`HANDLER_EXECUTION = HandlerExecution.CONCURRENT`): all handlers run in parallel and results are merged afterward. Accessing `context.current_result` in concurrent mode raises `RuntimeError`. Useful for independent linters.
 
 ## Service
 

docs/configuration.md

@@ -33,7 +33,7 @@ You can declare or extend actions directly in your project:
 source = "finecode_extension_api.actions.lint.LintAction"
 handlers = [
     { name = "ruff", source = "fine_python_ruff.RuffLintFilesHandler", env = "dev_no_runtime", dependencies = ["fine_python_ruff~=0.2.0"] },
-    { name = "mypy", source = "fine_python_mypy.MypyLintHandler", env = "dev_no_runtime", dependencies = ["fine_python_mypy~=0.3.0"] },
+    { name = "mypy", source = "fine_python_mypy.MypyLintFilesHandler", env = "dev_no_runtime", dependencies = ["fine_python_mypy~=0.3.0"] },
 ]
 ```
 
@@ -46,7 +46,7 @@ To completely replace the handlers from presets for an action:
 source = "finecode_extension_api.actions.lint.LintAction"
 handlers_mode = "replace"
 handlers = [
-    { name = "mypy", source = "fine_python_mypy.MypyLintHandler", env = "dev_no_runtime", dependencies = ["fine_python_mypy~=0.3.0"] },
+    { name = "mypy", source = "fine_python_mypy.MypyLintFilesHandler", env = "dev_no_runtime", dependencies = ["fine_python_mypy~=0.3.0"] },
 ]
 ```
 

docs/glossary.md

@@ -8,6 +8,10 @@ A named operation (for example `lint`, `format`, `build_artifact`).
 
 A concrete implementation of an action. Multiple handlers can be registered for a single action, and they run sequentially or concurrently.
 
+## Collection Action
+
+An action whose payload carries multiple items and whose result describes that batch, often with per-item entries. Used when handlers need to iterate over, correlate, or optimize across the full set of items.
+
 ## Execution Environment
 
 A named, isolated context in which handlers and project code execute (e.g. `runtime`, `dev_workspace`, `dev_no_runtime`). Each execution environment has its own dependency set, serving a specific purpose — for example, the project's runtime, dev tooling, or test execution. The concept is inter-language; in Python each execution environment is materialized as a virtual environment. Configuration uses the shorthand `env`.
@@ -16,6 +20,10 @@ A named, isolated context in which handlers and project code execute (e.g. `runt
 
 A process that runs inside a specific execution environment and executes action handler code. The Workspace Manager spawns one ER per (project, execution environment) pair, on demand. ERs communicate with the WM over JSON-RPC. The concept is inter-language — `finecode_extension_runner` is the Python implementation.
 
+## Item Action
+
+An action whose payload carries one item and whose result describes that one item. Used when handlers naturally operate on a single unit of work.
+
 ## Preset
 
 A reusable, distributable bundle of action and handler declarations. Users reference a preset in their project configuration; its declarations merge with the project's own configuration, giving full control to override or disable individual handlers. The concept is inter-language — in Python, presets are distributed as packages installed into the `dev_workspace` execution environment.

docs/reference/actions.md

@@ -62,7 +62,7 @@ Format a source artifact or specific files.
 | `file_paths` | `list[Path]` | `[]` | Files to format (required when `target="files"`) |
 
 !!! note
-    The `save` payload field controls whether changes are written to disk. The built-in `SaveFormatFilesHandler` reads this flag. If you omit the save handler from your preset, files won't be written regardless.
+    The `save` payload field controls whether changes are written to disk. The built-in `SaveFormatFileHandler` reads this flag. If you omit the save handler from your preset, files won't be written regardless.
 
 ---
 
@@ -73,20 +73,54 @@ Format a specific set of files. Internal action dispatched by `format`.
 - **Source:** `finecode_extension_api.actions.FormatFilesAction`
 - **Default handler execution:** sequential
 
-The built-in `FormatFilesDispatchHandler` groups the given files by language and dispatches each language's batch to the matching language subaction — any action declaring `PARENT_ACTION = FormatFilesAction` and the corresponding `LANGUAGE`.
+The built-in `FormatFilesIterateHandler` iterates over all files and delegates each to `format_file`. Language routing is handled by `format_file` via its dispatch handler — `format_files` has no language awareness.
 
 ---
 
-## `format_python_files`
+## `format_file`
 
-Format Python source files. Language-specific subaction of `format_files`.
+Format a single file. Item-level action; handlers run sequentially as a pipeline.
 
-- **Source:** `finecode_extension_api.actions.FormatPythonFilesAction`
+- **Source:** `finecode_extension_api.actions.FormatFileAction`
 - **Default handler execution:** sequential
 
-**Payload fields:** same as `format_files`.
+**Payload fields:**
+
+| Field | Type | Description |
+|---|---|---|
+| `file_path` | `ResourceUri` | The single file to format |
+| `save` | `bool` | Whether to write the result back to disk |
+
+**Run context kwargs** (`FormatFileCallerRunContextKwargs`):
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `file_editor_session` | `IFileEditorSession \| None` | `None` | Shared session from a parent action. If absent, the context opens its own. |
+| `file_info` | `FileInfo \| None` | `None` | Pre-read file content. If absent, the context reads the file itself (with `block=True`). |
+
+When called standalone (e.g. IDE on-save), no kwargs are needed — the context creates its own session and reads the file. When called from `format_files`, the iterate handler passes the parent session. When called from the dispatch handler into a language subaction, both session and file info are passed to avoid redundant reads.
+
+**Result fields:**
+
+| Field | Type | Description |
+|---|---|---|
+| `changed` | `bool` | Whether the file content was modified |
+| `code` | `str` | The formatted content |
+
+Handlers read and update `run_context.file_info` to pass formatted content to the next handler in the pipeline.
+
+---
+
+## `format_python_file`
+
+Format a single Python file. Language-specific item-level subaction of `format_file`.
+
+- **Source:** `finecode_extension_api.actions.FormatPythonFileAction`
+- **Default handler execution:** sequential
+
+**Payload fields:** same as `format_file`.
 
-Register Python formatting tools (ruff, black, …) as handlers for this action.
+Register Python formatting tools (ruff, isort, …) as handlers for this action. Handler order matters — they run sequentially as a pipeline.
 
 ---