docs: update all documentation for new directory structure after core/ flattening

Author: jddunn

docs/ARCHITECTURE.md

@@ -17,6 +17,80 @@ Current runtime memory note:
 
 ## System Architecture Overview
 
+### Source Directory Layout
+
+After the `core/` flattening refactor, the `src/` tree is organized into domain-specific
+top-level directories. Only the foundational infrastructure modules remain under `core/`.
+
+```
+src/
+├── core/                    # Core infrastructure (7 dirs)
+│   ├── llm/                 # LLM providers, routing, streaming
+│   ├── tools/               # ITool, ToolOrchestrator, permissions
+│   ├── conversation/        # ConversationManager
+│   ├── orchestration/       # IAgentOrchestrator, telemetry
+│   ├── streaming/           # StreamingManager
+│   ├── storage/             # IStorageAdapter, SqlStorageAdapter
+│   └── utils/               # Shared helpers, usage tracking
+│
+├── media/                   # Media generation & processing
+│   ├── audio/               # TTS, music, SFX generation
+│   ├── images/              # Image generation (DALL-E, Stability, etc.)
+│   ├── video/               # Video generation & analysis
+│   └── vision/              # OCR, document AI, CLIP
+│
+├── provenance/              # Content provenance & blockchain anchoring
+│
+├── nlp/                     # NLP: tokenizers, stemmers, sentiment, i18n
+│   ├── language/            # Language detection & translation
+│   └── ai_utilities/        # AI utility helpers
+│
+├── safety/                  # Guardrails & runtime safety
+│   ├── guardrails/          # IGuardrailService, ParallelGuardrailDispatcher
+│   └── runtime/             # Runtime safety checks
+│
+├── agents/                  # Agent definitions & multi-agent collectives
+│   ├── definitions/         # Agent type definitions
+│   └── agency/              # Multi-agent coordination
+│
+├── evaluation/              # Eval framework & observability
+│   └── observability/       # OpenTelemetry tracing & metrics
+│
+├── knowledge/               # Knowledge graph (interface + implementations)
+│
+├── planning/                # Planning engine, HITL, workflows
+│   ├── planner/             # PlanningEngine, ReAct loops
+│   ├── hitl/                # Human-in-the-loop approval
+│   └── workflows/           # Workflow definitions & execution
+│
+├── sandbox/                 # Sandboxed execution & subprocess
+│   ├── executor/            # Sandboxed code execution
+│   └── subprocess/          # CLISubprocessBridge, CLIRegistry
+│
+├── structured/              # Structured output & prompt routing
+│   ├── output/              # StructuredOutputManager, JSON schema
+│   └── prompting/           # Prompt routing & construction
+│
+├── marketplace/             # Agent marketplace & workspace
+│   ├── store/               # Marketplace listings & search
+│   └── workspace/           # Workspace management
+│
+├── rag/                     # Retrieval-augmented generation
+│   └── vector-search/       # HNSW, Pinecone, Qdrant, Postgres
+│
+├── api/                     # Public API surface
+├── memory/                  # Cognitive memory system
+├── channels/                # Messaging channel adapters (37 platforms)
+├── cognitive_substrate/     # GMI (Generalized Mind Instance)
+├── discovery/               # Capability discovery engine
+├── emergent/                # Emergent capabilities
+├── extensions/              # Extension system
+├── orchestration/           # Graph-based workflow DAG engine
+├── query-router/            # Query classification & routing
+├── social-posting/          # Social media post management
+└── ...
+```
+
 ### The Complete AgentOS Ecosystem
 
 ```mermaid
@@ -3988,7 +4062,7 @@ interface PlanStep {
 ### Usage Example
 
 ```typescript
-import { PlanningEngine } from '@framers/agentos/core/planning';
+import { PlanningEngine } from '@framers/agentos/planning/planner';
 
 const planningEngine = new PlanningEngine(
   promptEngine,
@@ -4137,7 +4211,7 @@ interface EscalationContext {
 ### Usage Example
 
 ```typescript
-import { HumanInteractionManager } from '@framers/agentos/core/hitl';
+import { HumanInteractionManager } from '@framers/agentos/planning/hitl';
 
 const hitlManager = new HumanInteractionManager({
   defaultTimeoutMs: 300000, // 5 minutes

docs/CLI_PROVIDERS.md

@@ -16,15 +16,15 @@ ClaudeCodeProvider / GeminiCLIProvider     ← message formatting, tool schema i
 ClaudeCodeCLIBridge / GeminiCLIBridge      ← extends CLISubprocessBridge (flag assembly, error classification)
     │
     ▼
-CLISubprocessBridge (abstract base)        ← core/subprocess/ — spawn, pipe, NDJSON parse, timeout/abort
+CLISubprocessBridge (abstract base)        ← sandbox/subprocess/ — spawn, pipe, NDJSON parse, timeout/abort
     │
     ▼
 execa → local CLI binary                   ← user's authenticated CLI (claude, gemini, codex)
 ```
 
 ### Core Subprocess Module
 
-The generalized subprocess bridge lives at `packages/agentos/src/core/subprocess/`:
+The generalized subprocess bridge lives at `packages/agentos/src/sandbox/subprocess/`:
 
 - **`CLISubprocessBridge`** — abstract base class (template method pattern). Owns process lifecycle: spawn, stdin pipe, NDJSON line splitting, timeout, abort signal. Subclasses implement `buildArgs()`, `classifyError()`, `parseStreamEvent()`.
 - **`CLISubprocessError`** — generic error with open string codes, `guidance` (user-facing fix instructions), and `recoverable` flag. Works for any binary, not just LLM CLIs.

docs/CREATING_GUARDRAILS.md

@@ -1228,7 +1228,7 @@ const mockServiceRegistry: ISharedServiceRegistry = {
 To test how your guardrail behaves within the full two-phase pipeline:
 
 ```typescript
-import { ParallelGuardrailDispatcher } from '@framers/agentos/core/guardrails';
+import { ParallelGuardrailDispatcher } from '@framers/agentos/safety/guardrails';
 
 describe('Integration: ParallelGuardrailDispatcher + MyGuardrail', () => {
   it('should block input through the dispatcher', async () => {
@@ -1250,8 +1250,8 @@ describe('Integration: ParallelGuardrailDispatcher + MyGuardrail', () => {
 
 ### Reference test files
 
-- `packages/agentos/tests/core/guardrails/ParallelGuardrailDispatcher.spec.ts` -- comprehensive dispatcher tests.
-- `packages/agentos/tests/core/guardrails.integration.spec.ts` -- integration tests for the full guardrail pipeline.
+- `packages/agentos/tests/safety/guardrails/ParallelGuardrailDispatcher.spec.ts` -- comprehensive dispatcher tests.
+- `packages/agentos/tests/safety/guardrails.integration.spec.ts` -- integration tests for the full guardrail pipeline.
 
 ---
 

docs/GUARDRAILS_USAGE.md

@@ -47,7 +47,7 @@ import {
   type GuardrailInputPayload,
   type GuardrailOutputPayload,
   type GuardrailEvaluationResult,
-} from '@framers/agentos/core/guardrails';
+} from '@framers/agentos/safety/guardrails';
 
 // Simple content filter
 class ContentFilter implements IGuardrailService {
@@ -245,7 +245,7 @@ import {
   GuardrailAction,
   type CrossAgentOutputPayload,
   type GuardrailEvaluationResult,
-} from '@framers/agentos/core/guardrails';
+} from '@framers/agentos/safety/guardrails';
 
 class SupervisorGuardrail implements ICrossAgentGuardrailService {
   // Observe specific worker agents (empty = all agents)

docs/HUMAN_IN_THE_LOOP.md

@@ -41,7 +41,7 @@ type ActionSeverity = 'low' | 'medium' | 'high' | 'critical';
 ### 1. Initialize the Manager
 
 ```typescript
-import { HumanInteractionManager } from '@framers/agentos/core/hitl';
+import { HumanInteractionManager } from '@framers/agentos/planning/hitl';
 
 const hitlManager = new HumanInteractionManager({
   // Default timeout: 5 minutes

docs/PLANNING_ENGINE.md

@@ -124,7 +124,7 @@ const defaultOptions = {
 ### Basic Plan Generation
 
 ```typescript
-import { PlanningEngine } from '@framers/agentos/core/planning';
+import { PlanningEngine } from '@framers/agentos/planning/planner';
 
 const engine = new PlanningEngine({
   llmProvider: aiModelProviderManager,

docs/STRUCTURED_OUTPUT.md

@@ -18,7 +18,7 @@ The Structured Output Manager ensures LLM outputs conform to predefined JSON Sch
 ### Basic Structured Generation
 
 ```typescript
-import { StructuredOutputManager, JSONSchema } from '@framers/agentos/core/structured';
+import { StructuredOutputManager, JSONSchema } from '@framers/agentos/structured/output';
 
 const manager = new StructuredOutputManager({
   llmProviderManager,
@@ -322,7 +322,7 @@ manager.resetStatistics();
 ## Error Handling
 
 ```typescript
-import { StructuredOutputError } from '@framers/agentos/core/structured';
+import { StructuredOutputError } from '@framers/agentos/structured/output';
 
 try {
   const result = await manager.generate({