Documentation detail pass (#43)

* Rethought Arch structure and added some project specific docs.

* Completed docs

* Updated index

Author: goldenwitch

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.

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/)

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

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.