goldenwitch · goldenwitch · Nov 8, 2025 · Nov 8, 2025 · Nov 8, 2025 · Nov 8, 2025
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -83,6 +83,8 @@ Use SemaphoreSlim over lock in async contexts.
 Use System.Threading.Lock for the lock.
 
 ## Misc
+All non‑standard library dependencies must be isolated to integrations. Only integrations may depend on integrations.
+
 One class per file unless describing "dumb" data types like records.
 
 We have enabled implicit usings globally.

diff --git a/INDEX.md b/INDEX.md
@@ -1,35 +1,37 @@
-# Code
+# Index
 
 Project overview: see [README](/README.md).
 
-## Coven Engine (Coven.Core)
-- [Coven.Core](/src/Coven.Core/)
-- [Coven.Core.Tests](/src/Coven.Core.Tests/)
+## Documentation
+- Root: [README](/README.md), [CONTRIBUTING](/CONTRIBUTING.md), [AGENTS](/AGENTS.md)
+- Licensing: [COMMERCIAL-TERMS](/COMMERCIAL-TERMS.md), [LICENSE](/LICENSE), [NOTICE](/NOTICE)
+- Architecture: [README](/architecture/README.md), [Journaling and Scriveners](/architecture/Journaling-and-Scriveners.md), [Abstractions and Branches](/architecture/Abstractions-and-Branches.md), [Windowing and Shattering](/architecture/Windowing-and-Shattering.md), [Licensing](/architecture/Licensing.md)
+- Build/Release: [Release Process](/build/ReleaseProcess.md), [VERSION](/build/VERSION)
 
-## Coven with Agents (Coven.Spellcasting)
-- [Coven.Spellcasting](/src/Coven.Spellcasting/)
+## Projects (src)
+- Solution: [/src/Coven.sln](/src/Coven.sln)
 
-## Coven Infrastructure for Chat
-- [Coven.Chat](/src/Coven.Chat/)
+- Core: [/src/Coven.Core](/src/Coven.Core/) ([README](/src/Coven.Core/README.md))
+- Streaming: [/src/Coven.Core.Streaming](/src/Coven.Core.Streaming/) ([README](/src/Coven.Core.Streaming/README.md))
+- Daemonology: [/src/Coven.Daemonology](/src/Coven.Daemonology/) ([README](/src/Coven.Daemonology/README.md))
+- Transmutation: [/src/Coven.Transmutation](/src/Coven.Transmutation/) ([README](/src/Coven.Transmutation/README.md))
+- Spellcasting: [/src/Coven.Spellcasting](/src/Coven.Spellcasting/) ([README](/src/Coven.Spellcasting/README.md))
 
-# Architecture Guide
+- Chat (branch): [/src/Coven.Chat](/src/Coven.Chat/) ([README](/src/Coven.Chat/README.md))
+- Chat Console (leaf): [/src/Coven.Chat.Console](/src/Coven.Chat.Console/) ([README](/src/Coven.Chat.Console/README.md))
+- Chat Discord (leaf): [/src/Coven.Chat.Discord](/src/Coven.Chat.Discord/) ([README](/src/Coven.Chat.Discord/README.md))
 
-Explore by topic. All paths below are under `/architecture`.
+- Agents (branch): [/src/Coven.Agents](/src/Coven.Agents/) ([README](/src/Coven.Agents/README.md))
+- Agents OpenAI (leaf): [/src/Coven.Agents.OpenAI](/src/Coven.Agents.OpenAI/) ([README](/src/Coven.Agents.OpenAI/README.md))
 
-- [Architecture README](/architecture/README.md)
+- Tests: [/src/Coven.Core.Tests](/src/Coven.Core.Tests/), [/src/Coven.Daemonology.Tests](/src/Coven.Daemonology.Tests/)
 
-## Core Components
-- [Coven.Core](/architecture/Coven.Core.md)
-- [Coven.Chat](/architecture/Coven.Chat.md)
-- [Coven.Daemonology](/architecture/Coven.Daemonology.md)
-- [Coven.Spellcasting](/architecture/Coven.Spellcasting.md)
+## Samples
+- 01.DiscordAgent: [/src/samples/01.DiscordAgent](/src/samples/01.DiscordAgent/) ([README](/src/samples/01.DiscordAgent/README.md))
 
-## Integrations
-- [Coven.Chat.Console](/architecture/Coven.Chat.Console.md)
-- [Coven.Chat.Discord](/architecture/Coven.Chat.Discord.md)
-- [Coven.Codex](/architecture/Coven.Codex.md)
-- [Coven.OpenAI](/architecture/Coven.OpenAI.md)
-- [Coven.Spellcasting.MCP](/architecture/Coven.Spellcasting.MCP.md)
-
-## Meta
-- [Licensing](/architecture/Licensing.md)
+## Toys
+- [/src/toys/Coven.Toys.ConsoleChat](/src/toys/Coven.Toys.ConsoleChat/)
+- [/src/toys/Coven.Toys.ConsoleOpenAI](/src/toys/Coven.Toys.ConsoleOpenAI/)
+- [/src/toys/Coven.Toys.ConsoleOpenAIStreaming](/src/toys/Coven.Toys.ConsoleOpenAIStreaming/)
+- [/src/toys/Coven.Toys.DiscordChat](/src/toys/Coven.Toys.DiscordChat/)
+- [/src/toys/Coven.Toys.DiscordStreaming](/src/toys/Coven.Toys.DiscordStreaming/)
diff --git a/README.md b/README.md
@@ -127,7 +127,7 @@ await foreach ((long _, AgentEntry? entry) in _agents.TailAsync(0, cancellationT
 
 ### Extensibility
 
-Window policies: tune output chunking/summarization. Example (from Sample 01 `Program.cs`):
+Semantic windowing: policies define when streamed messages are ready for decision‑making (not fixed turns). See: `architecture/Windowing-and-Shattering.md`.
 
 ```csharp
 // Paragraph-first + tighter max-length for agent outputs

diff --git a/architecture/Abstractions-and-Branches.md b/architecture/Abstractions-and-Branches.md
@@ -0,0 +1,39 @@
+# Abstractions and Branches:
+
+Single takeaway: Integrate with Chat and Agents; swap leaves (Discord, Console, OpenAI) without changing your application logic.
+
+## Spine, Branches, Leaves
+- Spine: your ritual pipeline (MagikBlocks) orchestrating work.
+- Branches: Chat and Agents abstractions that expose typed journals and services.
+- Leaves: integrations translating abstractions to external systems (e.g., Discord, OpenAI).
+
+Your block logic writes/reads journal entries from Chat/Agents. The specific leaf is free to change (or multiply) behind the branch boundary.
+
+## Directionality
+- Spine: your block/user code lives here.
+- Efferent: spine → leaves (outbound from your code to adapters).
+- Afferent: leaves → spine (inbound to your code from adapters).
+
+## Chat
+- Contract: `IScrivener<ChatEntry>` representing inbound (afferent) and outbound (efferent) chat entries.
+- Examples: Discord and Console leaves both implement chat daemons and journals.
+- Windowing: chat drafts/outputs can be controlled via windowing policies.
+
+## Agents
+- Contract: `IScrivener<AgentEntry>` representing prompts, thoughts, responses, and streaming chunks.
+- Streaming: leaves can stream agent outputs incrementally; window policies decide emission.
+- Templating: use `ITransmuter` to shape request/response items (context, persona, metadata).
+
+## Swap Without Rewrites
+- Replace Discord with Console by changing DI registration; keep Chat code unchanged.
+- Switch AI providers or models by updating the Agents leaf; keep Agent journaling unchanged.
+- Combine multiple leaves (e.g., Discord + Console) and route via the same branch journals.
+
+## DI Patterns
+- Register branches in DI via extension methods; prefer `TryAdd` within libraries.
+- Start leaf daemons in a block and optionally wait for `Status.Running`.
+- Keep application code unaware of leaf‑specific SDKs.
+
+## Related
+- Journaling/Scriveners for boundary decoupling.
+- Windowing/Shattering for streaming behavior.
diff --git a/architecture/Coven.Chat.Console.md b/architecture/Coven.Chat.Console.md
diff --git a/architecture/Coven.Chat.Discord.md b/architecture/Coven.Chat.Discord.md
diff --git a/architecture/Coven.Chat.md b/architecture/Coven.Chat.md
diff --git a/architecture/Coven.Codex.md b/architecture/Coven.Codex.md
diff --git a/architecture/Coven.Core.md b/architecture/Coven.Core.md
diff --git a/architecture/Coven.Daemonology.md b/architecture/Coven.Daemonology.md
diff --git a/architecture/Coven.OpenAI.md b/architecture/Coven.OpenAI.md
diff --git a/architecture/Coven.Spellcasting.MCP.md b/architecture/Coven.Spellcasting.MCP.md
diff --git a/architecture/Coven.Spellcasting.md b/architecture/Coven.Spellcasting.md
diff --git a/architecture/Journaling-and-Scriveners.md b/architecture/Journaling-and-Scriveners.md
@@ -0,0 +1,46 @@
+# Journaling and Scriveners
+
+Scriveners are append‑only journals that record typed entries. They decouple producers from consumers at architectural boundaries, enable replay/time‑travel, and make streaming deterministic.
+
+## Why Journals?
+- Audit and replay: every meaningful event is recorded for debugging and compliance.
+- Decoupling: producers write entries without knowing who consumes them.
+- Testing: deterministic inputs (append entries) yield deterministic outputs (tail reads).
+- Streaming: incremental entries can be windowed/shattered into UX‑friendly outputs.
+
+## Core Behaviors
+- Append‑only: entries are added with a monotonically increasing position.
+- Tail: readers observe `(position, entry)` tuples starting from a position (often `0` or the latest).
+- Typed streams: each journal is strongly typed (e.g., `ChatEntry`, `AgentEntry`).
+
+## Boundary Decoupling
+- Spine ↔ Branch: MagikBlocks read/write `IScrivener<T>`; branches/leaves observe journals and act.
+- Multi‑writer, multi‑reader: independent components coordinate only through entries, not callbacks.
+- Recovery: restartable components can reconstruct state by replaying entries from position `0`.
+
+## Patterns
+- Directionality: efferent entries move away from the spine (outbound to leaves); afferent entries move toward the spine (inbound from leaves).
+- Input/Output symmetry: design afferent vs efferent entries explicitly to clarify direction.
+- Completion markers: write a dedicated “completed” entry to flush buffers and finalize windows.
+- Idempotent consumers: consuming the same entry twice yields the same effect (or is a no‑op).
+- Pure transmutation: map entries to entries with `ITransmuter`/`IBatchTransmuter` without side‑effects.
+
+## Common Entry Families
+- Chat: `ChatAfferent`, `ChatEfferentDraft`/`ChatEfferent`, `ChatChunk`, `ChatStreamCompleted`.
+- Agents: `AgentPrompt`, `AgentThought`, `AgentResponse`, `AgentAfferentChunk`, `AgentAfferentThoughtChunk`.
+- Daemons: `DaemonEvent` for status changes and failures.
+
+## Operational Tips
+- Use a single scrivener per flow in DI; avoid accidental duplicates.
+- Avoid long‑running synchronous work in consumers; prefer daemons that tail asynchronously.
+- Treat journals as the source of truth for cross‑component communication.
+
+## Related
+- Windowing/Shattering: see “Windowing and Shattering”.
+- Daemon lifecycle: see `src/Coven.Daemonology/README.md`.
+
+## Acceptance Criteria
+- Describes the role of scriveners in decoupling boundaries.
+- Explains append/tail and typed streams with concrete families.
+- Provides patterns for completion markers and pure transmutation.
+- Links to related topics and package docs.