From 2b2a314d656b5e6d0d39beb764a5d4ee5aa5f26f Mon Sep 17 00:00:00 2001
From: Eric Rakestraw <eric@rakestraw.us>
Date: Tue, 19 May 2026 09:12:40 -0500
Subject: [PATCH] Move documentation for external integrations into the
 docs/integrations subfolder

---
 docs/documentation/policy.md                      | 10 ++++++++++
 docs/integrations/README.md                       | 15 +++++++++++++++
 .../audita.md}                                    |  0
 .../scriptorium.md}                               |  0
 .../seriatim.md}                                  |  0
 docs/internal/README.md                           |  6 +++---
 6 files changed, 28 insertions(+), 3 deletions(-)
 create mode 100644 docs/integrations/README.md
 rename docs/{internal/integration-audita.md => integrations/audita.md} (100%)
 rename docs/{internal/integration-scriptorium.md => integrations/scriptorium.md} (100%)
 rename docs/{internal/integration-seriatim.md => integrations/seriatim.md} (100%)

diff --git a/docs/documentation/policy.md b/docs/documentation/policy.md
index f835c00..f4f2105 100644
--- a/docs/documentation/policy.md
+++ b/docs/documentation/policy.md
@@ -283,6 +283,16 @@ Roadmap docs should clearly distinguish:
 
 Roadmap docs should not be confused with current behavior.
 
+### docs/integrations/
+
+**Audience:** developers, LLM coding agents
+
+Required for projects that depend on external CLIs, APIs, services, protocols, or file formats where the integration contract is important to maintain.
+
+This directory contains concise, versioned reference notes for external integration contracts. It should document only the parts of the external system that this project actually uses.
+
+Use one file per integration where useful.
+
 ## Examples Directory
 
 Projects with non-trivial configuration or workflows should include `examples/`.
diff --git a/docs/integrations/README.md b/docs/integrations/README.md
new file mode 100644
index 0000000..3d1d4ab
--- /dev/null
+++ b/docs/integrations/README.md
@@ -0,0 +1,15 @@
+# Integration Documentation Index
+
+## Audience
+Developers and LLM coding agents changing Narratio's external integration contracts.
+
+## Scope
+Implemented-only reference notes for the external systems Narratio currently integrates with.
+
+## Integration Docs
+- `audita.md`: Audita adapter invocation and validation contract.
+- `seriatim.md`: Seriatim normalize/merge/trim adapter contract.
+- `scriptorium.md`: Scriptorium run/render adapter contract.
+
+## Canonical Owner
+`docs/integrations/` is the canonical home for external integration reference notes per `docs/documentation/policy.md`.
diff --git a/docs/internal/integration-audita.md b/docs/integrations/audita.md
similarity index 100%
rename from docs/internal/integration-audita.md
rename to docs/integrations/audita.md
diff --git a/docs/internal/integration-scriptorium.md b/docs/integrations/scriptorium.md
similarity index 100%
rename from docs/internal/integration-scriptorium.md
rename to docs/integrations/scriptorium.md
diff --git a/docs/internal/integration-seriatim.md b/docs/integrations/seriatim.md
similarity index 100%
rename from docs/internal/integration-seriatim.md
rename to docs/integrations/seriatim.md
diff --git a/docs/internal/README.md b/docs/internal/README.md
index 26a7136..46b23fe 100644
--- a/docs/internal/README.md
+++ b/docs/internal/README.md
@@ -20,9 +20,9 @@ Implementation-accurate contracts for workspace/state, stages, and external adap
 - `stage-trim.md`: bounds-driven transcript trimming.
 - `stage-analyze.md`: Scriptorium session recap generation.
 - `stage-archive.md`: archive upload and current-pointer publish contract.
-- `integration-audita.md`: Audita adapter invocation/validation contract.
-- `integration-seriatim.md`: Seriatim merge/normalize/trim adapter contract.
-- `integration-scriptorium.md`: Scriptorium run/render adapter contract.
+
+## External Integration Notes
+- `../integrations/README.md`: canonical location for external integration contracts (`audita.md`, `seriatim.md`, `scriptorium.md`).
 
 ## Canonical Owner
 `docs/internal/` is the canonical home for implemented internals per `docs/documentation/policy.md`.