oracle-samples · fede-kamel · May 23, 2026 · May 22, 2026 · May 23, 2026 · May 23, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -75,12 +75,12 @@ held the same primary keys.
 
 Updated 7 files to match their current notebook number:
 
-- `notebook_16_agent_memory.py` (was `locus_notebook_10_*`)
-- `notebook_35_deepagent.py` (was `locus_notebook_30_medical`)
-- `notebook_44_rag_basics.py` (was `locus_notebook_39_*`)
-- `notebook_45_rag_providers.py` (was `locus_notebook_40_*`)
-- `notebook_46_rag_agents.py` (was `locus_notebook_41_*`)
-- `notebook_54_checkpoint_backends.py` (was `locus_notebook_48`)
+- `notebook_08_agent_memory.py` (was `locus_notebook_10_*`)
+- `notebook_29_deepagent.py` (was `locus_notebook_30_medical`)
+- `notebook_38_rag_basics.py` (was `locus_notebook_39_*`)
+- `notebook_39_rag_providers.py` (was `locus_notebook_40_*`)
+- `notebook_40_rag_agents.py` (was `locus_notebook_41_*`)
+- `notebook_52_checkpoint_backends.py` (was `locus_notebook_48`)
 - `notebook_68_agent_server.py` (was `locus_notebook_62`)
 
 A pre-commit / lint check to prevent future drift is tracked in #241.
@@ -125,8 +125,8 @@ reasoning. Cost: Oracle-only, alpha upstream (`oracleagentmemory`
 - New optional dep `[agentmemory]` in `pyproject.toml`
   (`oracleagentmemory>=26.4.0,<27`). Also rolled into `[checkpoints]`
   so `pip install locus-sdk[checkpoints]` covers everything Oracle.
-- New live notebook `examples/notebook_13_oracle_agent_memory.py` +
-  matching docs page `docs/notebooks/notebook_13_oracle_agent_memory.md`,
+- New live notebook `examples/notebook_09_oracle_agent_memory.py` +
+  matching docs page `docs/notebooks/notebook_09_oracle_agent_memory.md`,
   filed in sequential order in the Oracle 26ai notebook block (slot 13).
 - New workbench pattern `oracle_agent_memory` (PATTERNS + PATTERN_RUNNERS
   in `workbench/backend/runner.py`), filed in sequential order after
@@ -191,26 +191,26 @@ wrapping someone else's bindings rather than Locus driving them.
 Every one of those seven notebooks now puts a Locus `Agent` in the
 driver's seat with Oracle 26ai as the durable substrate:
 
-- **06 — `notebook_06_oracle_26ai_rag.py`**: `create_rag_tool` over
+- **06 — `notebook_41_oracle_26ai_rag.py`**: `create_rag_tool` over
   `OracleVectorStore`; the agent decides when to call `VECTOR_DISTANCE`
   and grounds its answer in the returned passages.
-- **07 — `notebook_07_oracle_26ai_checkpointer.py`**: `Agent(checkpointer=
+- **07 — `notebook_53_oracle_26ai_checkpointer.py`**: `Agent(checkpointer=
   oracle_checkpointer(...))`; a brand-new Agent instance resumes the
   same `thread_id` and recalls turn 1 — no manual save/load.
-- **08 — `notebook_08_oracle_adb_loader.py`**: `@tool fetch_articles_by_topic`
+- **08 — `notebook_42_oracle_adb_loader.py`**: `@tool fetch_articles_by_topic`
   wrapping `OracleADBLoader` with `bind_params`; the agent picks the
   topic and runs the parameter-bound SELECT.
-- **09 — `notebook_09_oracle_indb_chunker.py`**: agent with
+- **09 — `notebook_43_oracle_indb_chunker.py`**: agent with
   `chunk_paragraph` + `chunk_table_rows` tools over `OracleInDBChunker`;
   picks the right primitive per prompt.
-- **10 — `notebook_10_oracle_indb_embeddings.py`**: data-residency RAG
+- **10 — `notebook_44_oracle_indb_embeddings.py`**: data-residency RAG
   agent on `OracleInDBEmbeddings` + `OracleVectorStore` — embedding +
   similarity search both stay inside 26ai.
-- **11 — `notebook_11_oracle_store.py`**: `Agent(memory_manager=
+- **11 — `notebook_10_oracle_store.py`**: `Agent(memory_manager=
   LLMMemoryManager(store=OracleStore))`; thread A teaches a fact,
   brand-new Agent in thread B recalls it without seeing thread A's
   messages.
-- **12 — `notebook_12_oracle_versioned_saver.py`**: three-turn agent
+- **12 — `notebook_54_oracle_versioned_saver.py`**: three-turn agent
   with both `oracle_checkpointer` (live thread) and
   `OracleCheckpointSaver` (versioned lineage); shows
   `list_checkpoints`, `get(checkpoint_id=...)`, and `put_writes`.

diff --git a/README.md b/README.md
@@ -313,7 +313,7 @@ The seven primitives:
 The contracts live in locus, the SQL is generated locally, and the
 only runtime requirement is `python-oracledb` thin mode.
 
-→ [Notebook 06 — Oracle 26ai RAG](https://locusagents.oracle.com/notebooks/notebook_06_oracle_26ai_rag/) · [Notebook 07 — Oracle 26ai checkpointer](https://locusagents.oracle.com/notebooks/notebook_07_oracle_26ai_checkpointer/) · [Notebooks 08-12 — loader, chunker, embeddings, store, versioned saver](https://locusagents.oracle.com/notebooks/)
+→ [Notebook 06 — Oracle 26ai RAG](https://locusagents.oracle.com/notebooks/notebook_41_oracle_26ai_rag/) · [Notebook 07 — Oracle 26ai checkpointer](https://locusagents.oracle.com/notebooks/notebook_53_oracle_26ai_checkpointer/) · [Notebooks 08-12 — loader, chunker, embeddings, store, versioned saver](https://locusagents.oracle.com/notebooks/)
 
 ---
 
@@ -335,10 +335,10 @@ git clone https://github.com/oracle-samples/locus.git
 cd locus && pip install -e .
 
 python examples/notebook_01_oci_transports.py        # start here — three OCI transports
-python examples/notebook_06_oracle_26ai_rag.py       # native VECTOR RAG on Oracle 26ai
-python examples/notebook_07_oracle_26ai_checkpointer.py  # durable agent threads in ADB
-python examples/notebook_14_basic_agent.py           # your first agent
-python examples/notebook_35_deepagent.py             # deep-research factory
+python examples/notebook_41_oracle_26ai_rag.py       # native VECTOR RAG on Oracle 26ai
+python examples/notebook_53_oracle_26ai_checkpointer.py  # durable agent threads in ADB
+python examples/notebook_06_basic_agent.py           # your first agent
+python examples/notebook_29_deepagent.py             # deep-research factory
 python examples/notebook_69_research_workflow.py     # full research pipeline
 ```
 

diff --git a/docs/FEATURES.md b/docs/FEATURES.md
@@ -9,7 +9,7 @@ Everything `locus` ships, what it does, and where to find it.
     - **Idempotent tools** — `@tool(idempotent=True)` dedupes on `(name, args)` inside the loop. No double-charge, double-book, double-page.
     - **Reasoning loop nodes** — Reflexion, Grounding, Causal as first-class
       Think → Execute → **Reflect** → Think nodes, not bolted-on libraries.
-    - **GSAR** — typed-grounding layer from [arXiv:2604.23366](https://arxiv.org/abs/2604.23366) with four-way claim partition + tiered replanning.
+    - **GSAR** — typed-grounding layer from [Federico A. Kamelhar (2026), arXiv:2604.23366](https://arxiv.org/abs/2604.23366) with four-way claim partition + tiered replanning.
     - **Termination algebra** — `MaxIterations(10) | TextMention("DONE") & ConfidenceMet(0.9)` is real Python (`__or__` / `__and__` operator overloads).
     - **Six multi-agent shapes plus A2A** — Composition, Orchestrator, Swarm, Handoff, StateGraph, Functional + A2A for cross-process meshes.
     - **Cognitive router (PRISM)** — NL → typed `GoalFrame` → typed `ProtocolRegistry` → `PolicyGate` → compiled orchestration. LLM fills a schema; 8 built-in protocols; zero topology hand-writing.
@@ -26,7 +26,7 @@ Everything `locus` ships, what it does, and where to find it.
 | **Reflexion** | Self-evaluation node in the ReAct cycle; rewrites the next turn when the last one was wrong | `Agent(reflexion=True)` · [Reasoning](concepts/reasoning.md) |
 | **Grounding** | LLM-as-judge claim verification against tool results; below-threshold triggers replanning | `Agent(grounding=True)` · [Reasoning](concepts/reasoning.md) |
 | **Causal chains** | Cause-effect graph builder with cycle/contradiction detection | `locus.reasoning.causal.CausalChain` · [Reasoning](concepts/reasoning.md) |
-| **GSAR** | Typed-grounding safety layer (arXiv:2604.23366) — four-way claim partition + tiered replanning | `Agent(gsar=GSARConfig(...))` · [GSAR](concepts/gsar.md) |
+| **GSAR** | Typed-grounding safety layer ([Federico A. Kamelhar (2026), arXiv:2604.23366](https://arxiv.org/abs/2604.23366)) — four-way claim partition + tiered replanning | `Agent(gsar=GSARConfig(...))` · [GSAR](concepts/gsar.md) |
 | **Cancel** | Thread-safe abort during a run; emits `TerminateEvent` with reason | `agent.cancel()` · [Agent loop](concepts/agent-loop.md) |
 | **Interrupts (HITL)** | Pause via `InterruptEvent`; resume with `agent.resume(...)` | `locus.core.interrupt` · [Interrupts](concepts/interrupts.md) |
 | **Structured output** | Pass `output_schema=` (Pydantic), final answer is parsed into a typed instance | `locus.agent.config`, `locus.core.structured` · [Structured output](concepts/structured-output.md) |
@@ -90,6 +90,7 @@ Everything `locus` ships, what it does, and where to find it.
 | **CircuitBreaker executor** | Auto-disable a tool after N failures | `locus.tools.executor` · [Executors](concepts/executors.md) |
 | Result-store offload | Move large tool results to object storage; agent sees a pointer | `locus.tools.result_storage` |
 | Path / URL safety | Validate filesystem and network access from tool args | `locus.tools.path_safety`, `locus.tools.url_safety` · [Safety](concepts/safety.md) |
+| **`use_oci` + `describe_oci`** | Open-spec built-ins: drive the whole OCI control plane (~190 services) from one agent — discover with `describe_oci`, execute with `use_oci`; read-only by default | `locus.tools.use_oci`, `locus.tools.describe_oci` · [Tools](concepts/tools.md#open-spec-built-ins-for-the-oracle-estate) |
 | **MCP — client + server** | Talk to / be talked to by Anthropic-spec MCP servers | `locus.integrations.fastmcp` · [MCP](concepts/mcp.md) |
 
 ## Memory — checkpointer backends

diff --git a/docs/capabilities.md b/docs/capabilities.md
@@ -27,9 +27,9 @@ Everything `locus` ships, what it does, and where to find it.
     - **Reasoning loop nodes** — Reflexion, Grounding, Causal as first-class
       Think → Execute → **Reflect** → Think nodes, not bolted-on libraries.
     - **GSAR** — typed-grounding safety layer from
-      [arXiv:2604.23366](https://arxiv.org/abs/2604.23366): four-way claim
-      partition (grounded / ungrounded / contradicted / complementary) + tiered
-      replanning decisions.
+      [Federico A. Kamelhar (2026), arXiv:2604.23366](https://arxiv.org/abs/2604.23366):
+      four-way claim partition (grounded / ungrounded / contradicted /
+      complementary) + tiered replanning decisions.
     - **Termination algebra** — `MaxIterations(10) | TextMention("DONE") & ConfidenceMet(0.9)` is real Python (`__or__` / `__and__` overloads). Greppable, unit-testable, serialisable.
     - **Idempotent tools** — `@tool(idempotent=True)` dedupes on `(name, args)` inside the Execute node. No double-charge, double-book, double-page — even on model retry or checkpoint resume.
     - **OCI, OpenAI, and Anthropic-compatible providers** — OCI Generative AI
@@ -48,7 +48,7 @@ Everything `locus` ships, what it does, and where to find it.
 | **Reflexion** | Self-evaluation node in the ReAct cycle; rewrites the next turn when the last one was wrong | `Agent(reflexion=True)` · [Reasoning](concepts/reasoning.md) |
 | **Grounding** | LLM-as-judge claim verification against tool results; below-threshold triggers replanning | `Agent(grounding=True)` · [Reasoning](concepts/reasoning.md) |
 | **Causal chains** | Cause-effect graph builder with cycle/contradiction detection | `locus.reasoning.causal.CausalChain` · [Reasoning](concepts/reasoning.md) |
-| **GSAR** | Typed-grounding safety layer (arXiv:2604.23366) — four-way claim partition + tiered replanning | `Agent(gsar=GSARConfig(...))` · [GSAR](concepts/gsar.md) |
+| **GSAR** | Typed-grounding safety layer ([Federico A. Kamelhar (2026), arXiv:2604.23366](https://arxiv.org/abs/2604.23366)) — four-way claim partition + tiered replanning | `Agent(gsar=GSARConfig(...))` · [GSAR](concepts/gsar.md) |
 | **Cancel** | Thread-safe abort during a run; emits `TerminateEvent` with reason | `agent.cancel()` · [Agent loop](concepts/agent-loop.md) |
 | **Interrupts (HITL)** | Pause via `InterruptEvent`; resume with `agent.resume(...)` | `locus.core.interrupt` · [Interrupts](concepts/interrupts.md) |
 | **Structured output** | Pass `output_schema=` (Pydantic), final answer is parsed into a typed instance | `locus.agent.config`, `locus.core.structured` · [Structured output](concepts/structured-output.md) |

diff --git a/docs/concepts/checkpointers.md b/docs/concepts/checkpointers.md
@@ -183,7 +183,7 @@ history = await saver.list_checkpoints(thread_id="t1")  # walk lineage
 ```
 
 Notebook walkthrough: [Notebook 07 — Oracle 26ai
-checkpointer](../notebooks/notebook_07_oracle_26ai_checkpointer.md).
+checkpointer](../notebooks/notebook_53_oracle_26ai_checkpointer.md).
 
 ## Two checkpointer shapes — the gotcha to know
 

diff --git a/docs/concepts/deepagent.md b/docs/concepts/deepagent.md
@@ -349,7 +349,7 @@ workflow = create_research_workflow(
 
 ## See also
 
-- [Notebook 42](../notebooks/notebook_35_deepagent.md) — four-part
+- [Notebook 42](../notebooks/notebook_29_deepagent.md) — four-part
   walkthrough: basic factory, filesystem + todos, subagents, observability.
 - [API reference — DeepAgent](../api/deepagent.md) — full class and
   function signatures including `create_research_workflow`.

diff --git a/docs/concepts/gsar.md b/docs/concepts/gsar.md
@@ -9,7 +9,8 @@ scalar over the answer as a whole — often misses this. Each *claim* is
 grounded; the *conclusion* over-reaches.
 
 **GSAR** (Grounding-Stratified Adaptive Replanning, from
-[Kamelhar 2026](https://arxiv.org/abs/2604.23366)) is the upgrade. It
+[Federico A. Kamelhar (2026), arXiv:2604.23366](https://arxiv.org/abs/2604.23366))
+is the upgrade. It
 breaks the synthesis into claims, partitions them four ways, scores
 the partition with per-evidence-type weights, and picks one of three
 responses: `proceed` if the synthesis holds up, `regenerate` if the
@@ -153,6 +154,6 @@ production you'd map your tool taxonomy onto these.
   — outer loop, abstain handling, budget exhaustion.
 - [`tests/integration/test_gsar_live.py`](https://github.com/oracle-samples/locus/blob/main/tests/integration/test_gsar_live.py)
   — live LLM judge driving the full loop.
-- [`examples/notebook_43_gsar_typed_grounding.py`](https://github.com/oracle-samples/locus/blob/main/examples/notebook_43_gsar_typed_grounding.py)
+- [`examples/notebook_37_gsar_typed_grounding.py`](https://github.com/oracle-samples/locus/blob/main/examples/notebook_37_gsar_typed_grounding.py)
   — a runnable walkthrough of the four parts.
-- Paper: [arXiv:2604.23366](https://arxiv.org/abs/2604.23366).
+- Paper: [Federico A. Kamelhar (2026), arXiv:2604.23366](https://arxiv.org/abs/2604.23366).
diff --git a/docs/concepts/hooks.md b/docs/concepts/hooks.md
@@ -220,8 +220,8 @@ any field; this is intentionally tight.
 
 - [`HookProvider` and `HookOrchestrator`](https://github.com/oracle-samples/locus/blob/main/src/locus/hooks/provider.py)
 - [Built-in hooks](https://github.com/oracle-samples/locus/tree/main/src/locus/hooks/builtin)
-- [`notebook_18_agent_hooks.py`](https://github.com/oracle-samples/locus/blob/main/examples/notebook_18_agent_hooks.py) — write your first hook.
-- [`notebook_20_hooks_advanced.py`](https://github.com/oracle-samples/locus/blob/main/examples/notebook_20_hooks_advanced.py) — guardrails + steering, end to end.
+- [`notebook_12_agent_hooks.py`](https://github.com/oracle-samples/locus/blob/main/examples/notebook_12_agent_hooks.py) — write your first hook.
+- [`notebook_14_hooks_advanced.py`](https://github.com/oracle-samples/locus/blob/main/examples/notebook_14_hooks_advanced.py) — guardrails + steering, end to end.
 
 ## See also
 

diff --git a/docs/concepts/idempotency.md b/docs/concepts/idempotency.md
@@ -131,7 +131,7 @@ the side effects still fire exactly once.
 
 - [`@tool` decorator with idempotency hook](https://github.com/oracle-samples/locus/blob/main/src/locus/tools/decorator.py)
 - [`_find_matching_execution`](https://github.com/oracle-samples/locus/blob/main/src/locus/loop/nodes.py#L114) — where the dedup actually happens, in the ReAct loop's Execute node.
-- [`notebook_15_agent_with_tools.py`](https://github.com/oracle-samples/locus/blob/main/examples/notebook_15_agent_with_tools.py) — walks through the `@tool` decorator end-to-end (idempotency covered in the agent-loop walkthrough).
+- [`notebook_07_agent_with_tools.py`](https://github.com/oracle-samples/locus/blob/main/examples/notebook_07_agent_with_tools.py) — walks through the `@tool` decorator end-to-end (idempotency covered in the agent-loop walkthrough).
 
 ## See also
 

diff --git a/docs/concepts/interrupts.md b/docs/concepts/interrupts.md
@@ -136,9 +136,9 @@ debugging, or branch off a new thread from the partial conversation.
 - [Hooks](hooks.md) — write custom hooks that return `Cancel`.
 - [Conversation Management](conversation-management.md) — how
   `thread_id` resumption works.
-- [Notebook 09 — human in the loop](https://github.com/oracle-samples/locus/blob/main/examples/notebook_25_human_in_the_loop.py)
+- [Notebook 09 — human in the loop](https://github.com/oracle-samples/locus/blob/main/examples/notebook_19_human_in_the_loop.py)
   — a full runnable example.
-- [Notebook 46 — multi-agent + HITL](https://github.com/oracle-samples/locus/blob/main/examples/notebook_39_multiagent_human_in_loop.py)
+- [Notebook 46 — multi-agent + HITL](https://github.com/oracle-samples/locus/blob/main/examples/notebook_33_multiagent_human_in_loop.py)
   — three HITL patterns in one file (approval gate, human-as-tool,
   long-pause snapshot/resume).
 - [Notebook 47 — incident response](https://github.com/oracle-samples/locus/blob/main/examples/notebook_63_incident_response.py)

diff --git a/docs/concepts/mcp.md b/docs/concepts/mcp.md
@@ -199,7 +199,7 @@ implementation detail.
 ## Source and notebook
 
 - [`locus.integrations.fastmcp`](https://github.com/oracle-samples/locus/blob/main/src/locus/integrations/fastmcp.py) — built on FastMCP.
-- [`notebook_47_mcp_integration.py`](https://github.com/oracle-samples/locus/blob/main/examples/notebook_47_mcp_integration.py) — consumer + producer end-to-end.
+- [`notebook_45_mcp_integration.py`](https://github.com/oracle-samples/locus/blob/main/examples/notebook_45_mcp_integration.py) — consumer + producer end-to-end.
 
 ## See also
 

diff --git a/docs/concepts/memory-manager.md b/docs/concepts/memory-manager.md
@@ -190,7 +190,7 @@ The upstream is currently alpha (`oracleagentmemory` 26.4.0, Dev
 Status 3). When you need a portable backend or a fully-deterministic
 LLM-free extractor, fall back to the portable path below.
 
-See [notebook 13](../notebooks/notebook_13_oracle_agent_memory.md) for
+See [notebook 13](../notebooks/notebook_09_oracle_agent_memory.md) for
 a runnable end-to-end demo with two sessions on the same `user_id`.
 
 ### Portable path (any BaseStore backend)