adjustments: manual v2

docs/developer/en/06_guardrails_judges_and_transaction_evaluation.md

@@ -159,34 +159,15 @@ _, decisions = await pipeline.run_tool(
 
 ### SPI for external guardrails and judges
 
-> Content consolidated from `docs/EXTERNAL_GUARDRAILS_JUDGES.md`.
+Use extensions when a policy or quality criterion belongs to the agent domain. A guardrail implements `evaluate(text, context) -> RailDecision` and can run at `input`, `retrieval`, `tool`, or `output`. A judge implements `evaluate(question, answer, context) -> JudgeResult` and scores rather than rewrites a response.
 
-`agent_framework_oci` supports agent-owned guardrails and judges without importing domain code into the core.
+The [external guardrails and judges guide](../../EXTERNAL_GUARDRAILS_JUDGES_en.md) covers directory layout, imports, copyable implementations, YAML, constructor injection, failure policy, observability, and executable verification.
 
-```yaml
-output:
-  - code: ACME_POLICY
-    type: external
-    class: app.extensions.guardrails:AcmePolicyRail
-```
+Key constraints: `type: external` plus `class: package.module:Class` enables dynamic import; `kwargs` populate the constructor; judges may receive injected `llm` and `settings`; guardrails receive a shared LLM through context only when the pipeline was built with `llm=...`; synchronous implementations run in worker threads; and external judge exceptions should be handled by the implementation.
 
-```yaml
-judges:
-  - name: acme_quality
-    type: external
-    class: app.extensions.judges:AcmeQualityJudge
-    threshold: 0.7
-```
+> **Current limitation:** `agent_template_backend` creates a global pipeline pair at startup. Registry fields `guardrails_config_path` and `judges_config_path` do not automatically select a configuration per request. LLM-backed extensions also require the composition to pass `llm` and `settings` as documented in the full guide.
 
-Native entries remain unchanged. External synchronous `evaluate()` methods execute in worker threads via `asyncio.to_thread`; asynchronous methods execute concurrently on the framework event loop. Judges run concurrently with `asyncio.gather`, preserving YAML result order. Agent plugins should reuse the LLM supplied by the framework rather than instantiate a separate provider.
-
-The core must not reference a concrete agent package, company, product, telecom identifier, or domain-specific policy. Domain-specific variants belong to the agent and should receive distinct public codes/names.
-
-### Compatibility rule
-
-Domain policies must not be replaced by cosmetically generic text inside the core while losing the original policy. The generic core implementation and the agent-specific implementation may coexist; the embedding agent explicitly selects its own code/name in YAML.
-
-Legacy business validators should migrate to the agent domain. A temporary compatibility shim is acceptable for old imports, but new application code must import the agent-owned implementation.
+Verify the published examples with `pytest -q tests/test_external_guardrails_judges_documentation.py`.
 
 ### Mandatory judge execution for transactions
 

docs/developer/en/13_advanced_transactional_workflows.md

@@ -0,0 +1,90 @@
+### Advanced transactional workflows
+
+### Goal
+
+This chapter turns a sensitive tool into a deterministic transaction with parameter collection, pre-validation, confirmation, versioned workflow, pause/resume, idempotency, and recovery. Business rules and actions belong to the agent; the execution engine belongs to the framework.
+
+### Actual flow
+
+1. `routing.yaml` selects the agent and limits candidate tools.
+2. `tools.yaml` describes arguments, prompts, and response behavior.
+3. `mcp_parameter_mapping.yaml` resolves identity, defaults, and extraction.
+4. `tool_policies.yaml` classifies the operation and requires confirmation.
+5. Optional pre-validation checks whether execution may continue without producing an effect.
+6. After unambiguous confirmation, execution is direct or delegated to `WorkflowToolExecutor`.
+7. `WorkflowRuntime` loads the active version, runs actions, persists pauses, and returns `COMPLETED`, `PAUSED`, or `FAILED`.
+8. An idempotency key prevents duplicate external effects.
+
+### Catalog and policy are different contracts
+
+```yaml
+# config/tools.yaml
+tools:
+  request_return:
+    description: Opens an order return.
+    mcp_server: retail
+    enabled: true
+    tool_type: action
+    confirmation_required: true
+    requires: [order_id, reason]
+    args_schema:
+      order_id:
+        type: string
+        label: the order number
+        user_prompt: Provide the order number.
+      reason:
+        type: string
+        label: the return reason
+        user_prompt: What is the return reason?
+```
+
+```yaml
+# config/tool_policies.yaml
+version: 1
+defaults:
+  operation_type: read_only
+  require_confirmation: false
+tool_policies:
+  request_return:
+    operation_type: transactional
+    require_confirmation: true
+    requires: [order_id, reason]
+    pre_validation:
+      enabled: true
+      tool: validate_return
+      fail_open: false
+    execution:
+      mode: workflow
+      workflow: order_return
+      version: active
+```
+
+`tools.yaml` is the public catalog; `tool_policies.yaml` governs effects. Do not rely only on catalog `confirmation_required`: effective policy must declare `operation_type` and `require_confirmation`. A pre-validation tool must be read-only and never perform the transaction early. Prefer `fail_open: false` for sensitive operations.
+
+### Versioned workflow and actions
+
+Store definitions under `workflows/<name>.vN.yaml` and maintain a valid active definition. Node IDs must be unique; `start`, destinations, and `resume_from` must exist; `retry` accepts 0 through 10. Paths under `$.input.*` read workflow input and `$.nodes.<id>.*` read earlier results.
+
+Agent actions use `@workflow_action("name")`, matching `node.action`, and implement `(params: dict, state: dict) -> dict`. Import the action module during startup so decorators register. Return serializable data only—never an HTTP client, connection, exception, or coroutine. Complete executable YAML and Python are available in the matching [Portuguese chapter](../pt/13_workflows_transacionais_avancados.md).
+
+### Idempotent external effects
+
+Create one `create_idempotency_store(...)` instance at startup and inject it into actions. Build the key from stable business identity, operation, resource, and contract version—not merely a timestamp. `IDEMPOTENCY_PROVIDER` takes precedence over checkpoint, session, and cache providers. For production transactions, enable `IDEMPOTENCY_REQUIRE_DURABLE=true` and select an appropriate `oracle`, `redis`, or `sqlite` provider. Memory does not protect across pods or restarts. Persist the outcome only after the external system confirms the effect.
+
+### Pause, expected input, and resume
+
+A node may declare `pause.expected_input` with `key`, `allowed_values`, normalization, `reprompt`, and a semantic classifier. Explicit confirmation remains deterministic; the classifier handles only inconclusive replies and must return an allowed option. `contextual_reentry` releases the workflow and returns the utterance to normal routing without confirming user facts.
+
+Resume with the same `execution_id`; a new execution creates a separate transaction. The checkpoint must contain serializable data sufficient to rebuild the pause. Duplicate replies must check idempotency before repeating an effect.
+
+### Intent shift, recovery, and replay
+
+When a user abandons a transaction, clear pending call, collected arguments, confirmation, and related transaction state. Do not reuse parameters from a closed transaction. A contextual question may be answered and return to the pause; a genuine intent change explicitly closes or suspends the flow according to agent policy.
+
+- `PAUSED`: persist execution ID, prompt, and expected-input contract.
+- `FAILED`: keep technical details in telemetry and return a safe message.
+- timeout after sending: query idempotency or external status before resending.
+- replay after `COMPLETED`: return the persisted result without execution.
+- new version: in-flight runs retain their version; `active` applies to new runs.
+
+Test invalid graphs, valid/invalid paths, retry, pause/resume, unmatched answers, intent shift, duplicates, idempotency-provider failure, and post-finalization replay. Run `pytest -q tests/test_advanced_developer_documentation.py`.

docs/developer/en/14_advanced_routing_parameters_and_state.md

@@ -0,0 +1,31 @@
+### Advanced routing, parameters, and state
+
+### Decision precedence
+
+Routing is not a keyword list. Safe precedence is: explicit block/finalization; pending collection or transaction through `state_policies`; deterministic confirmation; deterministic intent; optional LLM fallback; and finally fallback/handoff. Pending state must win so short replies and isolated parameters do not jump to another agent.
+
+The complete executable YAML is in the matching [Portuguese chapter](../pt/14_routing_parametros_e_estado_avancados.md). In `routing.yaml`, lower `priority` values win ties in the current template. `mcp_tools` limits candidates but does not authorize sensitive effects. `confidence_threshold` gates semantic results, `allow_handoff` permits an explicit agent change, and `domain` supplies scope metadata rather than replacing `agent`.
+
+### Semantic confirmation
+
+Constrain semantic confirmation with `allowed_values`, plus explicit confirm, reject, and continue sets. The prompt must include the allowed values and prohibit execution or invented facts. `include_relevant_context` contributes bounded context related to the pause. If model output does not match an allowed option, keep the transaction pending. Explicit yes/no remains deterministic; the LLM handles inconclusive language only.
+
+### Identity, mapping, and extraction
+
+`identity.yaml` resolves canonical customer, contract, interaction, account, resource, and session keys from the payload, prior `business_context`, or previous context. Validate required identity before MCP execution. A session identifier is not customer identity.
+
+Recommended argument precedence is: already confirmed transaction value, explicit current value, canonical identity mapping, deterministic extraction, LLM/hybrid extraction, and default. A new explicit value may correct an old one; an inferred value must never overwrite a confirmed value.
+
+For `strategy: hybrid`, test both regex and LLM paths. `pattern` and `group` require positive and negative tests. `description` is an operational extraction instruction, not decorative documentation. Type conversion must fail safely when ambiguous.
+
+### Temporal reconciliation
+
+Temporal reconciliation is a fallback only after ordinary collection leaves missing fields. Search relevant messages newest-first and bind values only to fields described by the tool schema/mapping. It must not cross tenant/agent/session, revive a closed transaction, recover a user-invalidated value, replace safe exact matching with dangerous fuzzy matching, or overwrite a confirmed field. Record value origin and correlation without retaining unnecessary sensitive text.
+
+### Dynamic states and multi-agent behavior
+
+Declare new collection and confirmation state fields only when they carry extra data; otherwise reuse generic transaction keys. Every new state needs a matching `state_policies` entry, cleanup on success/cancellation/intent shift, and routing tests. A new state without policy commonly loses route stickiness.
+
+Router mode selects one agent. Supervisor mode coordinates multiple agents and changes cost, latency, state, and telemetry. Do not enable it merely to improve classification. Give subagents minimum context and authorized tools, scoped by `tenant_id:agent_id:session_id`; never share raw memory across agents.
+
+Test keyword overlap, priority ties, below-threshold output, fallback, pending states, short confirmations, ambiguity, parameter correction, regex/LLM extraction, temporal history, and isolation. Run `pytest -q tests/test_advanced_developer_documentation.py`.

docs/developer/en/15_presentation_recovery_and_observability.md

@@ -0,0 +1,25 @@
+### Presentation, recovery, and observability
+
+### Deterministic renderers
+
+Use `response.mode: renderer` for trusted structured tool results whose values must not be changed by an LLM. Register each renderer once at startup. Its keyword-only contract accepts `tool_name`, `result`, `state`, and `agent_label`; return `None` when required fields are absent so the configured fallback can run. Select, format, and mask allowed fields—never interpolate the complete payload. The executable YAML and implementation are in the matching [Portuguese chapter](../pt/15_apresentacao_recuperacao_e_observabilidade.md).
+
+### Output supervision and recovery
+
+The Output Supervisor may allow, sanitize, retry, block, hand over, or observe candidate output. Keep retries bounded, provide objective retry guidance, and revalidate rewritten output. Permanent authorization or dependency failure is not a content retry.
+
+Distinguish validation, transient dependency, permanent dependency, persistence, and programming failures. Before an external send, bounded retry may be safe. After an ambiguous send, query status/idempotency before resending. After external confirmation, persist the outcome before replying. A new user message must not erase evidence of uncertain execution. Checkpoint retry, integrity checks, compaction, and recovery do not make an external action idempotent.
+
+### Voice interruption and replay
+
+On barge-in, preserve confirmed transcript, mark interrupted output, and discard stale audio. An interrupted utterance is not transaction confirmation. Replay uses interaction/message identity and the same scoped session; resume only after revalidating pending state, confirmation, and idempotency.
+
+### Events, mappings, and Pub/Sub
+
+Emit functional behavior as IC, operational dependency/latency as NOC, and guardrail/supervisor decisions as GRL through the observer abstraction. Include tenant, agent, session, transaction/execution, component, and duration where available. Never record credentials, complete prompts, PII, or raw financial payloads.
+
+Map legacy consumer labels through a default registry plus agent overlay. Keep internal events semantic; do not hardcode historical external labels in runtime code.
+
+Pub/Sub publication occurs after the functional decision and must not change its outcome. Ordering requires explicit `sequence`, correlation, and a stable partition key; multiple pods do not provide global ordering. Define retention/TTL, duplicate handling, filters, and failure policy. A Pub/Sub filter does not remove the event from other telemetry destinations.
+
+Validate payload masking, supervisor revalidation, bounded retry, uncertain effects, correlation, mapping, multi-consumer ordering, and voice behavior. Run `pytest -q tests/test_advanced_developer_documentation.py`.

docs/developer/en/16_multi_agent_composition_and_lifecycle.md

@@ -0,0 +1,31 @@
+### Multi-agent composition and lifecycle
+
+### Effective isolation
+
+An `agent_id` is not merely a label. Real isolation includes prompt, routing, tools, MCP servers, guardrails, judges, memory, checkpoints, cache, telemetry, and identity, normally scoped as `tenant_id:agent_id:session_id`. The complete registry and runtime-bundle code are in the matching [Portuguese chapter](../pt/16_multiagente_composicao_e_ciclo_de_vida.md).
+
+Every configured path must exist and be validated at startup. A system prefix guides the model but is not a security boundary; code must enforce tool authorization, persistence namespaces, and pipeline selection.
+
+### Current template limitation
+
+Although `agents.yaml` accepts per-agent paths, the template currently builds one router, one tool/RAG composition, and one global guardrail/judge pair. YAML alone does not provide per-request isolation. Use one global profile per deployment or implement an explicit cached runtime bundle per `agent_id`. Cache immutable/expensive objects rather than constructing LLM clients, routers, or pipelines for every message. Never silently fall back to another agent's bundle.
+
+### Subagents and LLM composition
+
+A subagent is a bounded capability with declared purpose, input/output, authorized tools, timeout/budget, and return conditions. A supervisor consolidates structured results and passes minimum relevant context with correlation and maximum delegation depth. Use routing for one-specialty turns; use supervision only for genuine decomposition. Handoff transfers conversation ownership; subagent delegation leaves final-response ownership with the supervisor.
+
+Reuse framework LLM profiles and clients rather than creating provider SDKs inside domain components. Explicit, observable profile fallback preserves authentication, rate limits, retries, cache, and telemetry; configuration failure must not become an apparently valid answer.
+
+### RAG, memory, and security
+
+`RAG_PROVIDER=kbdb` works only when the execution's `RagService` uses the intended settings. A simple intent should still retrieve knowledge when agent policy requires it. Scope RAG collections, long-term memory, and checkpoints by tenant and agent. Long-term memory stores permitted summarized facts; checkpoints store execution state; neither may mix another agent's identity.
+
+Authentication establishes a principal; authorization controls tenant, agent, route, and tool. Production secrets require hashing/rotation and TLS. Trusted-proxy headers are safe only behind an authenticated edge that removes client-supplied values.
+
+### Startup and delivery lifecycle
+
+At startup validate registry/paths, create providers, register actions/renderers, load workflows, construct bundles, and check mandatory dependencies. `/health` reports process liveness; `/ready` must reject traffic when a required dependency is unusable. Invalid configuration should fail before the first conversation.
+
+Development order: copy the canonical template; create domain agent/configuration; register node and route; implement tools, mappings, policies, actions, and renderers; configure controls/RAG/memory/telemetry; run unit, loader, graph, conversational, and failure tests; run offline evaluation, load, and readiness checks; publish with version, compatibility, and rollback.
+
+The definition of done includes isolation, confirmation, idempotency, recovery, grounding, controls, correlated telemetry, no data leakage, dependency-failure behavior, and PT/EN documentation parity. Run `pytest -q tests/test_advanced_developer_documentation.py`.

docs/developer/en/INDEX_DEVELOPER_GUIDE.md

@@ -125,11 +125,35 @@ If something is not working, use **Search by problem** below.
 
 **Use when:** block messages are generic, `COER` should ask for clarification, or blocked-turn metadata contains stale routing/tool results.
 
+### [13 — Advanced Transactional Workflows](./13_advanced_transactional_workflows.md)
+
+**What it is:** pre-validation, versioned workflow actions, pause/resume, idempotency, replay, and recovery.
+
+**Use when:** a sensitive tool requires a deterministic and recoverable process.
+
+### [14 — Advanced Routing, Parameters, and State](./14_advanced_routing_parameters_and_state.md)
+
+**What it is:** routing precedence, semantic confirmation, hybrid extraction, temporal reconciliation, dynamic states, and subagents.
+
+**Use when:** routing or collection works on the happy path but fails in real conversations.
+
+### [15 — Presentation, Recovery, and Observability](./15_presentation_recovery_and_observability.md)
+
+**What it is:** renderers, Output Supervisor, recovery, voice replay, events, mappings, and ordered Pub/Sub.
+
+**Use when:** output changes evidence, an effect may repeat, or telemetry cannot reconstruct execution.
+
+### [16 — Multi-Agent Composition and Lifecycle](./16_multi_agent_composition_and_lifecycle.md)
+
+**What it is:** actual isolation, per-agent bundles, supervisor/subagents, LLM/RAG/memory, and readiness.
+
+**Use when:** multiple agents share one deployment or a new capability must reach production.
+
 ### Main tutorial
 
 [`README_en.md`](README_en.md) remains the reference for the complete step-by-step flow:
 
-`architecture → configuration → agent creation → registration → state → routing → tools → MCP → identity → execution → tests → gateways → memory → RAG`.
+`architecture → configuration → agent creation → registration → state → routing → tools → MCP → identity → workflows → idempotency → execution → tests → gateways → memory → RAG → operations`.
 
 ### Maintenance
 
@@ -141,4 +165,3 @@ When evolving a feature:
 - update the specialized manual with behavior, configuration, examples, and troubleshooting;
 - update SPECs if the contract changed;
 - keep release notes as history, not as the only current documentation.
-