ARPAHLS · rosspeili · Aug 30, 2026 · Aug 30, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Ollama integration ([#20](https://github.com/ARPAHLS/aura/issues/20))** — `integrations/ollama/llama_loop.py` stdlib HTTP body loop; README; mocked HTTP test; docs index distinguishes Ollama-only vs Ollama+Skillware paths.
 
+- **Integrations layout ([#19](https://github.com/ARPAHLS/aura/issues/19))** — top-level `integrations/README.md` stack index; Skillware `mock_tools.py` / `live_tools.py` entrypoints; LangGraph stub; doc links from getting-started and provider READMEs.
+
 ### Changed
 
 - **Verified operator identity ([#55](https://github.com/ARPAHLS/aura/issues/55))** — optional identity adapters (manual, mock, OIDC, Auth0); `identity.bound` spine event; `ids.operator` on all event trailers; export redaction; `aura identity show`; profile `types` with `role: identity`.

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -129,10 +129,13 @@ ids:
 
 See [examples/](../examples/README.md) — including [sequencer_pipeline.py](../examples/sequencer_pipeline.py), [07-observer-presets](../examples/07-observer-presets/), and the ToolHost capstone in [reference-tool-host-capstone.md](guides/reference-tool-host-capstone.md). Order: [onboarding.md](onboarding.md#examples-learning-path).
 
+Stack-specific loops live in [integrations/](../integrations/README.md) — start there for Ollama, OpenAI, Anthropic, Gemini, Skillware, and framework wrappers.
+
 ## Next
 
 - [onboarding.md](onboarding.md) — step-by-step first run
 - [using-aura.md](using-aura.md) — membrane, postures, observers
+- [../integrations/README.md](../integrations/README.md) — stack-specific loops
 - [skillware-integration.md](skillware-integration.md) — Skillware host
 - [concepts.md](concepts.md) — agent, session, sequencer
 - [comparison.md](comparison.md) — vs orchestrators and eval harnesses

diff --git a/docs/guides/aura-on-skillware.md b/docs/guides/aura-on-skillware.md
@@ -159,7 +159,8 @@ Recommended loop:
 
 | Provider | Path | Env vars |
 |---|---|---|
-| Ollama (local) | [integrations/skillware/ollama_skill_loop.py](../../integrations/skillware/ollama_skill_loop.py) | `OLLAMA_MODEL`, `OLLAMA_BASE_URL` |
+| Ollama (local body) | [integrations/ollama/](../../integrations/ollama/) | `OLLAMA_MODEL`, `OLLAMA_BASE_URL` |
+| Ollama + Skillware | [integrations/skillware/ollama_skill_loop.py](../../integrations/skillware/ollama_skill_loop.py) | same + `[skillware]` extra |
 | OpenAI | [integrations/openai/](../../integrations/openai/) | `OPENAI_API_KEY`, `OPENAI_MODEL` |
 | Anthropic | [integrations/anthropic/](../../integrations/anthropic/) | `ANTHROPIC_API_KEY`, `ANTHROPIC_MODEL` |
 | Google Gemini | [integrations/google/](../../integrations/google/) | `GOOGLE_API_KEY`, `GEMINI_MODEL` |

diff --git a/docs/guides/reference-tool-host-capstone.md b/docs/guides/reference-tool-host-capstone.md
@@ -52,7 +52,7 @@ Open `.aura/sessions/<id>.jsonl` and confirm:
 | **Live registry** | `$env:SKILLWARE_LIVE=1` + same | Same API, real bundled skills |
 | **Observers** | `python examples/07-observer-presets/main.py` | Analytics only |
 | **Emit-only** | `python examples/08-emit-only-loop/main.py` | Loose — no tool host |
-| **Body + tools** | `python integrations/skillware/ollama_skill_loop.py` | LLM body + egress tools |
+| **Body + tools** | `python integrations/skillware/ollama_skill_loop.py` | LLM body + Skillware egress |
 
 Swap Skillware for your runtime — keep `ToolHost.execute()` through egress.
 

diff --git a/docs/integrations/README.md b/docs/integrations/README.md
@@ -6,15 +6,15 @@ Attach AURA to your stack — models, tool runtimes, frameworks, sandboxes.
 
 | Integration | Path | Notes |
 |---|---|---|
-| **Overview** | this page | Start here to find your stack |
+| **Overview** | [`integrations/README.md`](../../integrations/README.md) | Pick your stack and run command |
 | **Skillware** | [`integrations/skillware/`](../../integrations/skillware/) | Reference ToolHost adapter; `[skillware]` extra |
 | **Operator identity** | [`integrations/identity/`](../../integrations/identity/) | Optional OIDC/Auth0/manual/mock adapters; `[identity]` extra |
 | **Ollama (local)** | [`integrations/ollama/`](../../integrations/ollama/) | Dev default: `llama3.2:1b` via `.env`; stdlib HTTP |
 | **Ollama + Skillware** | [`integrations/skillware/ollama_skill_loop.py`](../../integrations/skillware/ollama_skill_loop.py) | Local model body with Skillware egress |
 | **OpenAI (ChatGPT)** | [`integrations/openai/`](../../integrations/openai/) | Body loop + Skillware egress; `[openai]` extra |
 | **Anthropic (Claude)** | [`integrations/anthropic/`](../../integrations/anthropic/) | Body loop + Skillware egress; `[anthropic]` extra |
 | **Google Gemini** | [`integrations/google/`](../../integrations/google/) | Body loop + Skillware egress; `[google]` extra |
-| **LangGraph / CrewAI** | planned | Framework wrap examples |
+| **LangGraph** | [`integrations/langgraph/`](../../integrations/langgraph/) | Planned framework wrapper |
 
 Copy [`.env.example`](../../.env.example) to `.env` for local Ollama or cloud API keys. Do not commit `.env`.
 
@@ -24,12 +24,12 @@ Use the project **`.venv`** for installs (`pip install -e ".[integrations]"`), n
 
 | Example | Shows |
 |---|---|
-| [05-skillware-skill-types](../examples/05-skillware-skill-types/) | Three skill categories under AURA |
-| [06-skillware-sequencer-chain](../examples/06-skillware-sequencer-chain/) | Sequencer chain with conditional `when` steps |
-| [07-observer-presets](../examples/07-observer-presets/) | Monitor + Break observer presets |
-| [08-emit-only-loop](../examples/08-emit-only-loop/) | Emit-only coat — no tool host |
-| [09-operator-identity](../examples/09-operator-identity/) | Optional verified operator trailer (mock adapter) |
-| [sequencer_pipeline.py](../examples/sequencer_pipeline.py) | Sequencer with mocks |
+| [05-skillware-skill-types](../../examples/05-skillware-skill-types/) | Three skill categories under AURA |
+| [06-skillware-sequencer-chain](../../examples/06-skillware-sequencer-chain/) | Sequencer chain with conditional `when` steps |
+| [07-observer-presets](../../examples/07-observer-presets/) | Monitor + Break observer presets |
+| [08-emit-only-loop](../../examples/08-emit-only-loop/) | Emit-only coat — no tool host |
+| [09-operator-identity](../../examples/09-operator-identity/) | Optional verified operator trailer (mock adapter) |
+| [sequencer_pipeline.py](../../examples/sequencer_pipeline.py) | Sequencer with mocks |
 
 ## Related docs
 

diff --git a/docs/skillware-integration.md b/docs/skillware-integration.md
@@ -140,7 +140,7 @@ host.execute(skill.skill_id, skill.skill_id, {"source_text": untrusted, "sensiti
 
 **Offline starter skills** (no API keys): `optimization/prompt_rewriter`, `security/prompt_injection_firewall`, `monitoring/token_limiter`.
 
-Integration scripts: [`integrations/skillware/`](../integrations/skillware/) — `reference_tool_host.py` (mock or `SKILLWARE_LIVE=1`), `ollama_skill_loop.py` (Ollama + firewall).
+Integration scripts: [`integrations/skillware/`](../integrations/skillware/) — `mock_tools.py`, `live_tools.py`, and `reference_tool_host.py`; Ollama lives under [`integrations/ollama/`](../integrations/ollama/).
 
 ---
 

diff --git a/integrations/README.md b/integrations/README.md
@@ -0,0 +1,30 @@
+# Integrations
+
+Pick your stack, then run the matching AURA loop.
+
+| Stack | Path | Run |
+|---|---|---|
+| Ollama (local body) | [ollama/](ollama/) | `python integrations/ollama/llama_loop.py` |
+| Ollama + Skillware | [skillware/](skillware/) | `python integrations/skillware/ollama_skill_loop.py` |
+| Skillware (tools only) | [skillware/](skillware/) | `python integrations/skillware/mock_tools.py` |
+| Operator identity | [identity/](identity/) | `python examples/09-operator-identity/main.py` |
+| OpenAI (ChatGPT) | [openai/](openai/) | `python integrations/openai/skillware_body_loop.py` |
+| Anthropic (Claude) | [anthropic/](anthropic/) | `python integrations/anthropic/skillware_body_loop.py` |
+| Google Gemini | [google/](google/) | `python integrations/google/skillware_body_loop.py` |
+| LangGraph | [langgraph/](langgraph/) | Planned framework wrapper |
+
+`examples/` stays focused on core AURA patterns: minimal loop, guarded tools,
+task mode, observer presets, and sequencer demos. `integrations/` is for
+stack-specific wiring, optional clients, and provider-specific run notes.
+
+Use the project virtualenv:
+
+```bash
+pip install -e ".[integrations]"
+```
+
+Copy [`.env.example`](../.env.example) to `.env` when a stack needs local model
+or API settings. Do not commit `.env`.
+
+Every integration records the same AURA boundary: session identity, model/body
+events when present, egress tool calls, policy outcomes, and JSONL export paths.
diff --git a/integrations/google/README.md b/integrations/google/README.md
@@ -53,4 +53,4 @@ Uses offline `security/prompt_injection_firewall` — no extra Skillware API key
 
 - [aura-on-skillware.md](../../docs/guides/aura-on-skillware.md)
 - [OpenAI](../openai/README.md) · [Anthropic](../anthropic/README.md)
-- [Ollama local loop](../skillware/ollama_skill_loop.py)
+- [Ollama local loop](../ollama/README.md)
diff --git a/integrations/langgraph/README.md b/integrations/langgraph/README.md
@@ -0,0 +1,7 @@
+# LangGraph + AURA
+
+LangGraph integration is planned. Use this folder as the future home for a
+framework wrapper that shows where AURA records graph node turns, tool egress,
+rules, and session exports.
+
+Current runnable stacks are listed in [../README.md](../README.md).
diff --git a/integrations/openai/README.md b/integrations/openai/README.md
@@ -75,4 +75,4 @@ The script:
 - [Skillware integration guide](../../docs/guides/aura-on-skillware.md)
 - [Anthropic integration](../anthropic/README.md)
 - [Gemini integration](../google/README.md)
-- [Ollama (local), no API key](../skillware/ollama_skill_loop.py)
+- [Ollama (local), no API key](../ollama/README.md)
diff --git a/integrations/skillware/README.md b/integrations/skillware/README.md
@@ -26,8 +26,11 @@ skillware doctor security/prompt_injection_firewall
 
 | Script | Purpose |
 |---|---|
+| [`mock_tools.py`](mock_tools.py) | Mock ToolHost path |
+| [`live_tools.py`](live_tools.py) | Live Skillware registry path |
 | [`reference_tool_host.py`](reference_tool_host.py) | Mock (default) or live Skillware via `SKILLWARE_LIVE=1` |
-| [`ollama_skill_loop.py`](ollama_skill_loop.py) | Ollama `llama3.2:1b` + real `prompt_injection_firewall` through AURA |
+| [`ollama_skill_loop.py`](ollama_skill_loop.py) | Ollama body + Skillware firewall at egress |
+| [`../ollama/llama_loop.py`](../ollama/llama_loop.py) | Ollama body only (stdlib HTTP, no Skillware) |
 
 ## Examples (repo root)
 
@@ -46,7 +49,8 @@ Set `$env:SKILLWARE_LIVE = "1"` for live registry skills in examples 05 and 06.
 | OpenAI (ChatGPT) | [../openai/README.md](../openai/README.md) | `../openai/skillware_body_loop.py` |
 | Anthropic (Claude) | [../anthropic/README.md](../anthropic/README.md) | `../anthropic/skillware_body_loop.py` |
 | Google Gemini | [../google/README.md](../google/README.md) | `../google/skillware_body_loop.py` |
-| Ollama (local) | this folder | `ollama_skill_loop.py` |
+| Ollama (local body) | [../ollama/README.md](../ollama/README.md) | `../ollama/llama_loop.py` |
+| Ollama + Skillware | this folder | `ollama_skill_loop.py` |
 
 All follow the same pattern: **LLM body turn** + **Skillware skills at AURA egress** + **session export**.
 

diff --git a/integrations/skillware/live_tools.py b/integrations/skillware/live_tools.py
@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+"""Run the Skillware reference ToolHost with live registry skills."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+if str(_REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(_REPO_ROOT))
+
+os.environ["SKILLWARE_LIVE"] = "1"
+
+from integrations.skillware.reference_tool_host import main  # noqa: E402
+
+if __name__ == "__main__":
+    main()
diff --git a/integrations/skillware/mock_tools.py b/integrations/skillware/mock_tools.py
@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+"""Run the Skillware reference ToolHost in mock mode."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+if str(_REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(_REPO_ROOT))
+
+os.environ["SKILLWARE_LIVE"] = "0"
+
+from integrations.skillware.reference_tool_host import main  # noqa: E402
+
+if __name__ == "__main__":
+    main()
diff --git a/integrations/skillware/ollama_skill_loop.py b/integrations/skillware/ollama_skill_loop.py
@@ -10,7 +10,7 @@
   pip install ollama
   ollama pull llama3.2:1b
   copy .env.example .env
-  python integrations/skillware/ollama_skill_loop.py
+  python integrations/ollama/llama_loop.py
 
 Requires a running Ollama daemon at OLLAMA_BASE_URL (default http://127.0.0.1:11434).
 """
-Original file line number
+Diff line change
@@ Expand Up @@
     **Offline starter skills** (no API keys): `optimization/prompt_rewriter`, `security/prompt_injection_firewall`, `monitoring/token_limiter`.
-    Integration scripts: [`integrations/skillware/`](../integrations/skillware/) — `reference_tool_host.py` (mock or `SKILLWARE_LIVE=1`), `ollama_skill_loop.py` (Ollama + firewall).
+    Integration scripts: [`integrations/skillware/`](../integrations/skillware/) — `mock_tools.py`, `live_tools.py`, and `reference_tool_host.py`; Ollama lives under [`integrations/ollama/`](../integrations/ollama/).
     ---
@@ Expand Down @@