docs: clarify runtime determinism boundaries

docs/concepts/agent.md

@@ -35,19 +35,20 @@ The loop has four parts:
 | Action      | The agent calls a tool or emits output.                       |
 | Observation | Tool results or new messages are added back into context.     |
 
-Veryfront hides most loop plumbing behind the agent runtime. The important
-boundary is still visible: the agent decides what to do next, while tools,
-resources, runs, and app routes own the deterministic work they perform.
+Veryfront hides most loop plumbing behind the agent runtime. The boundary stays
+visible: the agent decides what to do next. Resources own readable context.
+Executable primitives own execution, including tools, tasks, workflows, runs,
+and app routes.
 
 ## Boundary
 
 Use an agent when the system needs judgment, language understanding, tool choice,
 or streamed conversational output. Agents usually pair with tools, memory, and a
 chat UI. AG-UI is the default streaming surface for interactive agent output.
 
-Do not use an agent for deterministic work that a tool, route, task, or workflow
-can own directly. If the next step is always known, the model should not be in
-charge of it.
+Do not use an agent for work that a tool, route, task, or workflow can own
+directly. If the next step is always known, the model should not be in charge of
+it.
 
 ## Wrong fit
 

docs/concepts/eval.md

@@ -8,8 +8,8 @@ An eval defines a repeatable quality check for an agent. It names the target,
 dataset, metrics, thresholds, and report shape that prove whether the agent still
 behaves as expected.
 
-Use evals when model behavior must be measured across examples, not just checked
-with one deterministic unit test.
+Use evals when agent or tool behavior must be measured across examples, not
+checked with one unit test.
 
 ## Characteristics
 
@@ -26,8 +26,8 @@ An eval is the definition. An eval run is one execution of that definition. A
 report is the result of the run. Durable eval runs use run kind `eval` and target
 IDs such as `eval:deep-research`.
 
-Keep evals separate from tests. Tests protect deterministic code behavior. Evals
-measure probabilistic agent behavior, retrieval behavior, tool behavior, and
+Keep evals separate from tests. Tests check code behavior against explicit
+assertions. Evals measure agent behavior, retrieval behavior, tool behavior, and
 operational budgets across datasets.
 
 ## Source files

docs/concepts/framework-primitives.md

@@ -41,7 +41,7 @@ response. A task can run slow background work. An agent can reason about a
 user-facing decision. A skill can give the agent task-specific instructions.
 
 This keeps the project understandable. The app owns entry points. Agents own
-model decisions. Tools own deterministic actions. Tasks own background targets.
+model decisions. Tools own callable actions. Tasks own background targets.
 Evals own quality measurement. Workflows own automation logic. Runs own
 durable execution. Extensions own replaceable runtime infrastructure.
 

docs/concepts/skill.md

@@ -37,7 +37,7 @@ large system prompt.
 
 ## Wrong fit
 
-Do not use a skill for deterministic work that should be a tool, background work
-that should be a task, or multi-step process state that should be a workflow.
+Do not use a skill for callable work that should be a tool, background work that
+should be a task, or multi-step process state that should be a workflow.
 
 For implementation steps, see [Skills](../guides/skills.md).

docs/concepts/tool.md

@@ -6,8 +6,8 @@ order: 22
 
 A tool owns one callable capability. It defines input, output, and execution.
 
-Tools exist because agents and workflows need safe ways to act. The model can
-choose a tool, but the tool owns the deterministic code that runs.
+Tools give agents and workflows defined ways to act. The model can
+choose a tool, but the tool owns the code that runs.
 
 ## Characteristics
 

docs/concepts/webhook.md

@@ -96,7 +96,7 @@ empty string; objects and arrays render as formatted JSON.
 
 Payload text is inserted verbatim. Template rendering is not an input-safety or
 prompt-injection boundary. Agents that act on untrusted event fields should
-apply an explicit input policy and keep authorization in deterministic tools.
+apply an explicit input policy and keep authorization in application code.
 
 Hosted agent webhooks may use `create_new`, `existing`, or `none` conversation
 mode. `existing` requires a conversation UUID. Local runs execute standalone

docs/guides/agents.md

@@ -125,9 +125,10 @@ export default agent({
 });
 ```
 
-`temperature` controls model sampling and defaults to `0` for deterministic
-agent runs. Runtime provider capabilities may omit or normalize the value for
-models that reject generic sampling parameters or require mode-specific values.
+`temperature` controls model sampling and defaults to `0`. It does not guarantee
+repeatable output. Runtime provider capabilities may omit or normalize the value
+for models that reject generic sampling parameters or require mode-specific
+values.
 
 `maxSteps` limits how many tool-call iterations the agent can perform per
 request. See [Tools](./tools.md) for how to define `getWeather`.

docs/guides/choose-a-primitive.md

@@ -28,22 +28,22 @@ clear and prevents overlapping agents, workflows, runs, and integrations.
 
 ## Decision rules
 
-| Primitive   | Use for                                                                       | Do not use for                                                                |
-| ----------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| App route   | A browser, HTTP client, or webhook needs an entry point.                      | The work should outlive the request or be reused outside routing.             |
-| Agent       | The model must decide, explain, call tools, use memory, or stream a response. | The work is deterministic and can be a function, task, or workflow step.      |
-| Tool        | An agent needs a typed operation such as search, lookup, write, or transform. | The operation has multiple long-running states or human approval steps.       |
-| Skill       | An agent needs reusable instructions, references, scripts, and assets.        | The work is deterministic or needs durable process state.                     |
-| Prompt      | An assistant needs reusable instruction text.                                 | The project needs to execute code or read data.                               |
-| Resource    | An assistant needs readable project context.                                  | The operation changes state or starts work.                                   |
-| Eval        | You need repeatable agent quality checks, datasets, metrics, and reports.     | You need deterministic code assertions without model execution.               |
-| Task        | You own a reusable background function in `tasks/`.                           | The user needs conversational reasoning or streaming output.                  |
-| Workflow    | The process has ordered steps, parallel branches, retries, or human review.   | A single agent response or one background function is enough.                 |
-| Run         | You need durable execution, scheduling, batch status, or run history.         | The work can finish inside a request without durability.                      |
-| Integration | You need provider metadata, OAuth, tokens, or remote integration tools.       | A local custom API call is enough and no shared connector behavior is needed. |
-| MCP server  | External assistants or MCP clients need tools, prompts, or resources.         | The capability is only used inside one Veryfront app route.                   |
-| Sandbox     | Code or shell work needs isolation from the app process.                      | The code can run safely in your own trusted runtime.                          |
-| Extension   | A capability should be packaged and reused across projects.                   | The code belongs to one app and can stay local.                               |
+| Primitive   | Use for                                                                                   | Do not use for                                                                     |
+| ----------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| App route   | A browser, HTTP client, or webhook needs an entry point.                                  | The work should outlive the request or be reused outside routing.                  |
+| Agent       | The model must decide, explain, call tools, use memory, or stream a response.             | The work follows fixed control flow and can be a function, task, or workflow step. |
+| Tool        | An agent or workflow needs a typed operation such as search, lookup, write, or transform. | The operation has multiple long-running states or human approval steps.            |
+| Skill       | An agent needs reusable instructions, references, scripts, and assets.                    | The work needs executable behavior or durable process state.                       |
+| Prompt      | An assistant needs reusable instruction text.                                             | The project needs to execute code or read data.                                    |
+| Resource    | An assistant needs readable project context.                                              | The operation changes state or starts work.                                        |
+| Eval        | You need repeatable agent quality checks, datasets, metrics, and reports.                 | You need code assertions without model execution.                                  |
+| Task        | You own a reusable background function in `tasks/`.                                       | The user needs conversational reasoning or streaming output.                       |
+| Workflow    | The process has ordered steps, parallel branches, retries, or human review.               | A single agent response or one background function is enough.                      |
+| Run         | You need durable execution, scheduling, batch status, or run history.                     | The work can finish inside a request without durability.                           |
+| Integration | You need provider metadata, OAuth, tokens, or remote integration tools.                   | A local custom API call is enough and no shared connector behavior is needed.      |
+| MCP server  | External assistants or MCP clients need tools, prompts, or resources.                     | The capability is only used inside one Veryfront app route.                        |
+| Sandbox     | Code or shell work needs isolation from the app process.                                  | The code can run safely in your own trusted runtime.                               |
+| Extension   | A capability should be packaged and reused across projects.                               | The code belongs to one app and can stay local.                                    |
 
 ## Common pairings
 

docs/guides/multi-agent.md

@@ -145,7 +145,8 @@ nested levels.
 
 ## Workflow-based composition
 
-For deterministic multi-agent pipelines, use [workflows](./workflows.md):
+For multi-agent pipelines with explicit execution order, use
+[workflows](./workflows.md):
 
 ```ts
 // workflows/article-pipeline.ts
@@ -173,7 +174,8 @@ Start this workflow from an API route, task, or tool. The [Workflows](./workflow
 | **Agent-as-tool** | The orchestrator decides dynamically which agents to call and in what order |
 | **Workflow**      | The execution order is known in advance: sequential, parallel, or branching |
 
-Agent-as-tool is more flexible but harder to predict. Workflows are deterministic and easier to debug.
+Agent-as-tool is more flexible but harder to predict. Workflows make execution
+order explicit and easier to debug.
 
 ## Agent registry
 

templates/ai-rules/agents.md

@@ -8,7 +8,7 @@ Use these folders as runtime boundaries. Create folders only when the feature ne
 
 - `app/`: pages, layouts, route handlers, and user-facing API routes.
 - `agents/`: model reasoning and tool use.
-- `tools/`: deterministic callable capabilities.
+- `tools/`: callable capabilities for agents and workflows.
 - `workflows/`: multi-step coordination.
 - `skills/`: reusable agent instructions in `skills/<id>/SKILL.md`.
 - `veryfront.config.ts`: project metadata and router configuration.

templates/ai-rules/claude-code.md

@@ -10,7 +10,7 @@ Use these folders as runtime boundaries. Create folders only when the feature ne
 
 - `app/`: pages, layouts, route handlers, and user-facing API routes.
 - `agents/`: model reasoning and tool use.
-- `tools/`: deterministic callable capabilities.
+- `tools/`: callable capabilities for agents and workflows.
 - `workflows/`: multi-step coordination.
 - `skills/`: reusable agent instructions in `skills/<id>/SKILL.md`.
 - `veryfront.config.ts`: project metadata and router configuration.

templates/ai-rules/copilot.md

@@ -10,7 +10,7 @@ Use these folders as runtime boundaries. Create folders only when the feature ne
 
 - `app/`: pages, layouts, route handlers, and user-facing API routes.
 - `agents/`: model reasoning and tool use.
-- `tools/`: deterministic callable capabilities.
+- `tools/`: callable capabilities for agents and workflows.
 - `workflows/`: multi-step coordination.
 - `skills/`: reusable agent instructions in `skills/<id>/SKILL.md`.
 - `veryfront.config.ts`: project metadata and router configuration.

templates/ai-rules/cursor.md

@@ -10,7 +10,7 @@ Use these folders as runtime boundaries. Create folders only when the feature ne
 
 - `app/`: pages, layouts, route handlers, and user-facing API routes.
 - `agents/`: model reasoning and tool use.
-- `tools/`: deterministic callable capabilities.
+- `tools/`: callable capabilities for agents and workflows.
 - `workflows/`: multi-step coordination.
 - `skills/`: reusable agent instructions in `skills/<id>/SKILL.md`.
 - `veryfront.config.ts`: project metadata and router configuration.

templates/ai-rules/skill.md

@@ -18,7 +18,7 @@ Use these folders as runtime boundaries. Create folders only when the feature ne
 
 - `app/`: pages, layouts, route handlers, and user-facing API routes.
 - `agents/`: model reasoning and tool use.
-- `tools/`: deterministic callable capabilities.
+- `tools/`: callable capabilities for agents and workflows.
 - `workflows/`: multi-step coordination.
 - `skills/`: reusable agent instructions in `skills/<id>/SKILL.md`.
 - `veryfront.config.ts`: project metadata and router configuration.

templates/ai-rules/windsurf.md

@@ -10,7 +10,7 @@ Use these folders as runtime boundaries. Create folders only when the feature ne
 
 - `app/`: pages, layouts, route handlers, and user-facing API routes.
 - `agents/`: model reasoning and tool use.
-- `tools/`: deterministic callable capabilities.
+- `tools/`: callable capabilities for agents and workflows.
 - `workflows/`: multi-step coordination.
 - `skills/`: reusable agent instructions in `skills/<id>/SKILL.md`.
 - `veryfront.config.ts`: project metadata and router configuration.